Primitives

Presence

Who's here, live cursors and typing, typed by your schema.

Presence is who's on a channel right now and a small state for each of them. Join with state, update it with a shallow merge, and leave when the connection closes; anyone who joins later gets a full snapshot. Identity comes from the signed token, so nobody can claim to be someone else.

Type the state

Presence state is typed by the same schema as your events. Keep it small: a name, what someone is doing, where their pointer is.

schema.ts
typescript
import { defineSchema } from "@anishroy/pulse"import { z } from "zod"
export const schema = defineSchema({ events: { /* … */ }, presence: z.object({ name: z.string(), editing: z.string().nullable(), // LiveCursors keeps this one: 0 to 1 across the shared area cursor: z.object({ x: z.number(), y: z.number() }).nullable(), }),})

Join, update, leave

title-field.tsx
tsx
import { usePresence } from "@anishroy/pulse/react"
function TitleField({ doc, me }: { doc: string; me: User }) { // Joins with this state; sends an update whenever it changes const { members, others, update } = usePresence(`doc:${doc}`, { name: me.name, }) const editors = others.filter((m) => m.state?.editing === "title")
return ( <label> Title · {members.length} here <input onFocus={() => update({ editing: "title" })} onBlur={() => update({ editing: null })} /> {editors.map((m) => <Badge key={m.connectionId}>{m.state?.name}</Badge>)} </label> )}
  • members has one entry per connection, so a user with two tabs appears twice. Each has connectionId, user (from the token), state and self.
  • update merges into this tab's state. Pass the whole object or just what changed.
  • Leave the state out to watch who's here without joining:
badge.tsx
tsx
// No state: watch who's here without joiningconst { members } = usePresence(`doc:${doc}`)

Live cursors

LiveCursors shares your pointer over its children and draws everyone else's on top. Positions are 0 to 1 across that area, so different window sizes line up, and they're smoothed between updates so cursors glide instead of jumping. Movement never re-renders React, and drawing stops while nobody moves.

canvas.tsx
tsx
import { LiveCursors } from "@anishroy/pulse/ui"import "@anishroy/pulse/ui/styles.css"
<LiveCursors channel={`doc:${doc}`}> <Canvas /></LiveCursors>

For your own cursor UI, useSmoothCursors runs the same smoothing and calls you with each position to draw. The smoother on its own is CursorSmoother in @anishroy/pulse/cursor, with no framework or DOM.

my-cursors.tsx
tsx
import { useSmoothCursors } from "@anishroy/pulse/react"
const refs = useRef(new Map<string, HTMLElement>())const others = useSmoothCursors(`doc:${doc}`, (connectionId, point) => { const el = refs.current.get(connectionId) if (!el) return el.hidden = !point if (point) { el.style.left = `${point.x * 100}%` el.style.top = `${point.y * 100}%` }})// Render one element per member of `others`, registered in `refs`

Typing

useTyping keeps a typing flag in presence: call notify on input and it clears itself a few seconds after the last keystroke.

composer.tsx
tsx
import { useTyping } from "@anishroy/pulse/react"import { TypingIndicator } from "@anishroy/pulse/ui"
const { notify } = useTyping(`chat:${room}`)
<textarea onChange={(e) => { setText(e.target.value); notify() }} /><TypingIndicator channel={`chat:${room}`} /> {/* "Ada is typing…" */}

Update rate

A connection sends at most 10 presence updates a second, which is already smooth once cursors are interpolated. Faster updates aren't dropped: they're merged, and the newest state always goes out, so a cursor ends exactly where it stopped. To send fewer, lower the rate (1 to 10):

layout.tsx
tsx
<PulseProvider url={PULSE_URL} auth="/api/pulse/token" presenceRate={5}>

A connection that keeps sending far more than the limit is closed and can't rejoin that channel for a minute.

Limits

  • Up to 1,000 members per channel.
  • Up to 10 updates a second per connection.