Step 6: See their cursors, live

A facepile with useDocumentPresence, and a real remote pointer moving over your own canvas.

Data converging is most of the way there. The last thing a spatial tool wants is to see who's there — a facepile in the header, exactly like Getting Started's text board got, using the same hook:

function PresenceStrip({ handle }) {
  const others = useDocumentPresence(handle).filter((p) => !p.isSelf)
  if (others.length === 0) return null
  return (
    <span style={{ display: "flex" }}>
      {others.map((p) => (
        <span key={p.userId} style={{ background: p.color /* … */ }}>
          {p.name.slice(0, 1).toUpperCase()}
        </span>
      ))}
    </span>
  )
}

Pull handle out of useDocument and thread it into Board, next to the pin count.

Add a facepile

src/tool.tsx

import { useMemo, useRef } from "react"

import type { MouseEvent as ReactMouseEvent, PointerEvent as ReactPointerEvent } from "react"

import {

DocumentGate,

type ToolRenderProps,

defineStateCodec,

defineTool,

field,

useDocument,

} from "@vvd/sdk"

/** One pin. x/y are pixels in the BOARD's own space — never a scaled ancestor's. */

export type Pin = {

x: number

y: number

label: string

}

export const codec = defineStateCodec({

// A per-KEY map: two people dropping different pins at once BOTH land.

pins: field.map<Pin>(),

})

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

function Board({

data,

actions,

canEdit,

}: {

data: { pins: Readonly<Record<string, Pin>> }

actions: {

map(name: "pins"): { set(key: string, value: Pin): void; delete(key: string): void }

}

canEdit: boolean

}) {

const boardRef = useRef<HTMLDivElement | null>(null)

const dragRef = useRef<{ id: string; dx: number; dy: number } | null>(null)

const pins = Object.entries(data.pins)

const onBoardClick = (e: ReactMouseEvent<HTMLDivElement>) => {

if (!canEdit || e.target !== boardRef.current) return

const rect = boardRef.current.getBoundingClientRect()

actions.map("pins").set(newId(), {

x: e.clientX - rect.left,

y: e.clientY - rect.top,

label: "Pin",

})

}

const beginDrag = (id: string, pin: Pin) => (e: ReactPointerEvent<HTMLDivElement>) => {

if (!canEdit) return

e.stopPropagation()

const rect = boardRef.current?.getBoundingClientRect()

if (!rect) return

dragRef.current = { id, dx: e.clientX - rect.left - pin.x, dy: e.clientY - rect.top - pin.y }

e.currentTarget.setPointerCapture(e.pointerId)

}

const onDrag = (e: ReactPointerEvent<HTMLDivElement>) => {

const d = dragRef.current

const pin = d && data.pins[d.id]

if (!d || !pin) return

const rect = boardRef.current?.getBoundingClientRect()

if (!rect) return

actions.map("pins").set(d.id, {

...pin,

x: e.clientX - rect.left - d.dx,

y: e.clientY - rect.top - d.dy,

})

}

const endDrag = () => {

dragRef.current = null

}

return (

<strong style={{ fontSize: 14 }}>pin board</strong>

<span style={{ fontSize: 12, opacity: 0.6 }}>{pins.length} pins</span>

</div>

<div

ref={boardRef}

onClick={onBoardClick}

style={{

position: "relative",

overflow: "hidden",

background:

"radial-gradient(rgba(127,127,127,0.25) 1px, transparent 1px) 0 0 / 20px 20px",

cursor: canEdit ? "crosshair" : "default",

}}

{pins.map(([id, pin]) => (

<div

key={id}

onPointerDown={beginDrag(id, pin)}

onPointerMove={onDrag}

onPointerUp={endDrag}

style={{

position: "absolute",

left: pin.x,

top: pin.y,

transform: "translate(-50%, -100%)",

touchAction: "none",

cursor: canEdit ? "grab" : "default",

fontSize: 22,

lineHeight: 1,

userSelect: "none",

}}

📍

</div>

))}

{pins.length === 0 && (

style={{

position: "absolute",

inset: 0,

display: "grid",

placeItems: "center",

margin: 0,

opacity: 0.5,

fontSize: 13,

pointerEvents: "none",

}}

Click anywhere to drop a pin

</p>

)}

</div>

)

}

function PinBoard({ document, context }: 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 ? (

) : null}

</DocumentGate>

)

}

export default defineTool({

id: "pin-board",

name: "Pin board",

documentTypes: ["pin-board"],

embed: "interactive",

render: PinBoard,

})

import { useMemo, useRef } from "react"
import type { MouseEvent as ReactMouseEvent, PointerEvent as ReactPointerEvent } from "react"

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

/** One pin. x/y are pixels in the BOARD's own space — never a scaled ancestor's. */
export type Pin = {
x: number
y: number
label: string
}

export const codec = defineStateCodec({
// A per-KEY map: two people dropping different pins at once BOTH land.
pins: field.map<Pin>(),
})

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

const onBoardClick = (e: ReactMouseEvent<HTMLDivElement>) => {
  if (!canEdit || e.target !== boardRef.current) return
  const rect = boardRef.current.getBoundingClientRect()
  actions.map("pins").set(newId(), {
    x: e.clientX - rect.left,
    y: e.clientY - rect.top,
    label: "Pin",
  })
}

const beginDrag = (id: string, pin: Pin) => (e: ReactPointerEvent<HTMLDivElement>) => {
  if (!canEdit) return
  e.stopPropagation()
  const rect = boardRef.current?.getBoundingClientRect()
  if (!rect) return
  dragRef.current = { id, dx: e.clientX - rect.left - pin.x, dy: e.clientY - rect.top - pin.y }
  e.currentTarget.setPointerCapture(e.pointerId)
}
const onDrag = (e: ReactPointerEvent<HTMLDivElement>) => {
  const d = dragRef.current
  const pin = d && data.pins[d.id]
  if (!d || !pin) return
  const rect = boardRef.current?.getBoundingClientRect()
  if (!rect) return
  actions.map("pins").set(d.id, {
    ...pin,
    x: e.clientX - rect.left - d.dx,
    y: e.clientY - rect.top - d.dy,
  })
}
const endDrag = () => {
  dragRef.current = null
}

return (
  <div style={{ display: "grid", gridTemplateRows: "auto 1fr", height: "100%", font: "inherit" }}>
    <div style={{ display: "flex", alignItems: "center", gap: 10, padding: "10px 14px" }}>
      <strong style={{ fontSize: 14 }}>pin board</strong>
      <span style={{ fontSize: 12, opacity: 0.6 }}>{pins.length} pins</span>
    </div>
    <div
      ref={boardRef}
      onClick={onBoardClick}
      style={{
        position: "relative",
        overflow: "hidden",
        background:
          "radial-gradient(rgba(127,127,127,0.25) 1px, transparent 1px) 0 0 / 20px 20px",
        cursor: canEdit ? "crosshair" : "default",
      }}
    >
      {pins.map(([id, pin]) => (
        <div
          key={id}
          onPointerDown={beginDrag(id, pin)}
          onPointerMove={onDrag}
          onPointerUp={endDrag}
          style={{
            position: "absolute",
            left: pin.x,
            top: pin.y,
            transform: "translate(-50%, -100%)",
            touchAction: "none",
            cursor: canEdit ? "grab" : "default",
            fontSize: 22,
            lineHeight: 1,
            userSelect: "none",
          }}
        >
          📍
        </div>
      ))}
      {pins.length === 0 && (
        <p
          style={{
            position: "absolute",
            inset: 0,
            display: "grid",
            placeItems: "center",
            margin: 0,
            opacity: 0.5,
            fontSize: 13,
            pointerEvents: "none",
          }}
        >
          Click anywhere to drop a pin
        </p>
      )}
    </div>
  </div>
)
}

function PinBoard({ document, context }: 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} canEdit={context.canEdit} />
    ) : null}
  </DocumentGate>
)
}

export default defineTool({
id: "pin-board",
name: "Pin board",
documentTypes: ["pin-board"],
embed: "interactive",
render: PinBoard,
})

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. Presence lives in the awareness channel, never your document, so it has nothing to show until someone else shows up.

Here's someone else showing up — two real identities, each with their own cursor, both looking at the same board:

Two people, one board

Move your pointer inside a pane

Starting the example…

Move your pointer inside a pane — the other one draws it, right over the board, not just somewhere on the page. Drop a pin and the coloured chip appears in both headers, because both panes are running your PresenceStrip, reading the same useDocumentPresence(handle).

That's the whole reason a spatial tool's presence reads differently from a text tool's: the cursor isn't decorating a line of prose, it's a second person's hand on the same board as yours.

Recap

useDocumentPresence(handle) lists everyone in the document right now — build a facepile from it with no channel of your own to manage.
Presence is ephemeral — it lives in the awareness channel, never your document — so a lone pane shows nothing until someone else arrives.
The remote cursor you just watched move is real: a genuine second Awareness, relayed live, never simulated.

What you built

A document-backed pin board: drop a pin at the exact pixel you clicked, drag one without drift, mount the same component full-size or card-sized via context.view, and watch two people work it at once — data and cursors both, live. Six steps, no sync code written by hand.

Next steps

ReferenceThe full host-capability table, defineBlock's every field, and more on scope: 'world'.Build a tool that calls an external APIThe third build-along — api/, config.secrets, and the trust boundary.Starter Kit: canvasvvd create --template canvas is this same shape, with pan/zoom and world links built in.