Step 7: See each other

useDocumentPresence lists who's in the document right now — no channel to open, no state of your own.

The platform already drew a cursor for you in the last step — that came free, from the surface around the tool. Now make your own UI say who's here, with one hook.

Why does presence come off handle, the thing useDocument returned? Because presence is a per-document question — "who's in this document", not "who's online" — so it rides the same live connection the document already opened. That's the whole design: no channel of your own to open or tear down, and nothing written into the document itself. Presence is ephemeral on purpose — when someone closes the tab, they're simply gone, with no stale row to clean up.

Add this component to src/tool.tsx, above Board. DocumentHandle is the SDK's name for the thing useDocument returns as handle — the prop is typed because the scaffold's tsconfig is strict, and an untyped { handle } destructuring is an implicit-any error:

src/tool.tsx

function PresenceStrip({ handle }: { handle: DocumentHandle | null }) {
  const others = useDocumentPresence(handle).filter((p) => !p.isSelf)
  if (others.length === 0) return null
  return (
    <span style={{ display: "flex", alignItems: "center" }}>
      {others.map((p) => (
        <span
          key={p.userId}
          style={{
            width: 22,
            height: 22,
            borderRadius: "50%",
            marginLeft: -6,
            display: "inline-flex",
            alignItems: "center",
            justifyContent: "center",
            background: p.color,
            color: "#fff",
            fontSize: 11,
            fontWeight: 700,
          }}
        >
          {p.name ? p.name.slice(0, 1).toUpperCase() : ""}
        </span>
      ))}
    </span>
  )
}

Then wire it up — three small edits, all in src/tool.tsx (the codec half at the top of the pane is untouched this step): add handle to what BestiaryView pulls out of useDocument, thread it into Board as a prop, and render <PresenceStrip handle={handle} /> next to the Add button. Don't forget useDocumentPresence — and type DocumentHandle — in the @vvd/sdk import. (Splitting rule for that merged import block, as ever: defineStateCodec and field belong to src/codec.ts; everything else — PresenceStrip and newId included — is src/tool.tsx.)

Add presence

src/tool.tsx

import { useMemo } from "react"

import {

DocumentGate,

type ToolRenderProps,

defineStateCodec,

defineTool,

field,

useDocument,

} from "@vvd/sdk"

// src/codec.ts

/** One note on the board. */

export type Note = {

text: string

/** Creation time — a stable sort key every peer agrees on. */

at: number

}

export const codec = defineStateCodec({

// A per-KEY map: two people adding or editing different notes at once BOTH land.

notes: field.map<Note>(),

})

// src/tool.tsx

const newId = () => crypto.randomUUID()

function Board({

data,

actions,

}: {

data: { notes: Readonly<Record<string, Note>> }

actions: {

map(name: "notes"): {

set(key: string, value: Note): void

delete(key: string): void

}

}) {

const notes = useMemo(

() => Object.entries(data.notes).sort((a, b) => a[1].at - b[1].at),

[data.notes],

)

const addNote = () =>

actions.map("notes").set(newId(), { text: "", at: Date.now() })

return (

<h1 style={{ margin: 0, fontSize: 20 }}>bestiary</h1>

Add a note

</button>

</div>

{notes.map(([id, note]) => (

<textarea

value={note.text}

placeholder="Write something…"

onChange={(e) =>

actions

.map("notes")

.set(id, { ...note, text: e.target.value })

}

style={{ flex: 1, minHeight: 64, padding: 10 }}

<button

type="button"

onClick={() => actions.map("notes").delete(id)}

Delete

</button>

</div>

))}

{notes.length === 0 && <p style={{ opacity: 0.6 }}>No notes yet.</p>}

</div>

)

}

export function BestiaryView({ document }: ToolRenderProps) {

const coords = useMemo(

() => ({ worldId: document.worldId, documentId: document.id }),

[document.worldId, document.id],

)

const { data, status, actions, retry } = useDocument(coords, codec)

return (

{data && actions && <Board data={data} actions={actions} />}

</DocumentGate>

)

}

export default defineTool({

id: "bestiary",

name: "bestiary",

documentTypes: ["bestiary"],

needs: [],

render: BestiaryView,

})

import { useMemo } from "react"

import {
DocumentGate,
type ToolRenderProps,
defineStateCodec,
defineTool,
field,
useDocument,
} from "@vvd/sdk"

// src/codec.ts
/** One note on the board. */
export type Note = {
text: string
/** Creation time — a stable sort key every peer agrees on. */
at: number
}

export const codec = defineStateCodec({
// A per-KEY map: two people adding or editing different notes at once BOTH land.
notes: field.map<Note>(),
})

// src/tool.tsx
const newId = () => crypto.randomUUID()

function Board({
data,
actions,
}: {
data: { notes: Readonly<Record<string, Note>> }
actions: {
  map(name: "notes"): {
    set(key: string, value: Note): void
    delete(key: string): void
  }
}
}) {
const notes = useMemo(
  () => Object.entries(data.notes).sort((a, b) => a[1].at - b[1].at),
  [data.notes],
)
const addNote = () =>
  actions.map("notes").set(newId(), { text: "", at: Date.now() })
return (
  <div style={{ maxWidth: 640, margin: "0 auto", padding: 24 }}>
    <div style={{ display: "flex", alignItems: "center", gap: 12 }}>
      <h1 style={{ margin: 0, fontSize: 20 }}>bestiary</h1>
      <button type="button" onClick={addNote} style={{ marginLeft: "auto" }}>
        Add a note
      </button>
    </div>
    <div style={{ marginTop: 16, display: "grid", gap: 12 }}>
      {notes.map(([id, note]) => (
        <div key={id} style={{ display: "flex", gap: 8 }}>
          <textarea
            value={note.text}
            placeholder="Write something…"
            onChange={(e) =>
              actions
                .map("notes")
                .set(id, { ...note, text: e.target.value })
            }
            style={{ flex: 1, minHeight: 64, padding: 10 }}
          />
          <button
            type="button"
            onClick={() => actions.map("notes").delete(id)}
          >
            Delete
          </button>
        </div>
      ))}
      {notes.length === 0 && <p style={{ opacity: 0.6 }}>No notes yet.</p>}
    </div>
  </div>
)
}

export function BestiaryView({ document }: ToolRenderProps) {
const coords = useMemo(
  () => ({ worldId: document.worldId, documentId: document.id }),
  [document.worldId, document.id],
)
const { data, status, actions, retry } = useDocument(coords, codec)
return (
  <DocumentGate status={status} onRetry={retry}>
    {data && actions && <Board data={data} actions={actions} />}
  </DocumentGate>
)
}

export default defineTool({
id: "bestiary",
name: "bestiary",
documentTypes: ["bestiary"],
needs: [],
render: BestiaryView,
})

Edit and the example re-runs. Tab indents; press Escape to leave the editor.

Running · your edits, live

Starting the example…

You should see: nothing changes yet — there's only one of you in this pane. The next demo proves it works, with a second identity for real.

Two people, one document

Move your pointer inside a pane

Starting the example…

Move your pointer inside a pane. The other one draws it. Add a note in one — the coloured chip appears in both headers, because both panes are running your PresenceStrip, reading the same useDocumentPresence(handle).

Recap

useDocumentPresence(handle) lists everyone in the document right now — userId, name, color, isSelf.
It's ephemeral: presence lives in the awareness channel, never in your document.
Cursors are drawn by the surface around your tool; the facepile is yours to build.

Next steps

Step 8 — Reach into the worldPoint a note at a real document, without copying it.