Step 3: Give it shared state

One hook, no coordinates — the host already knows where this mount's document lives.

A tool you built in Getting Started opens its state with useDocument(coords, codec) — you hand it a document id, it hands back data. An app's own state skips the coordinates entirely, because the host already knows the answer: one document per world, per app, per project.

Edit the board below. Replace the empty function Board() with one that reads data.blocks through useCollabState:

import { field, useCollabState } from "@vvd/sdk"

function Board() {
  const { data, actions } = useCollabState({ blocks: field.map<Block>() })
  if (!data || !actions) return null
  // … same rendering as before, reading data.blocks instead of nothing
}

Add the blocks field

src/app.tsx

import { defineTool } from "@vvd/sdk"

type Block = { x: number; y: number }

const WORD = "TOY"

const SIZE = 64

const COLORS = ["#c0392b", "#2e86c1", "#d68910"]

function defaultBlock(i: number, n: number): Block {

const gap = Math.min(0.24, 0.6 / Math.max(1, n - 1))

return { x: 0.5 + (i - (n - 1) / 2) * gap, y: 0.5 }

}

function Board() {

const letters = WORD.split("")

return (

{letters.map((ch, i) => {

const b = defaultBlock(i, letters.length)

return (

<div

key={i}

style={{

position: "absolute",

left: b.x * 100 + "%",

top: b.y * 100 + "%",

width: SIZE,

height: SIZE,

marginLeft: -SIZE / 2,

marginTop: -SIZE / 2,

display: "grid",

placeItems: "center",

borderRadius: 12,

background: COLORS[i % COLORS.length],

color: "#fff",

fontFamily: "Georgia, serif",

fontSize: 26,

fontWeight: 700,

}}

{ch}

</div>

)

})}

</div>

)

}

export default defineTool({

id: "toy",

name: "Toy",

documentTypes: ["toy"],

surface: "plain",

render: Board,

})

import { defineTool } from "@vvd/sdk"

type Block = { x: number; y: number }

const WORD = "TOY"
const SIZE = 64
const COLORS = ["#c0392b", "#2e86c1", "#d68910"]

function defaultBlock(i: number, n: number): Block {
const gap = Math.min(0.24, 0.6 / Math.max(1, n - 1))
return { x: 0.5 + (i - (n - 1) / 2) * gap, y: 0.5 }
}

function Board() {
const letters = WORD.split("")
return (
  <div style={{ position: "relative", height: "100%" }}>
    {letters.map((ch, i) => {
      const b = defaultBlock(i, letters.length)
      return (
        <div
          key={i}
          style={{
            position: "absolute",
            left: b.x * 100 + "%",
            top: b.y * 100 + "%",
            width: SIZE,
            height: SIZE,
            marginLeft: -SIZE / 2,
            marginTop: -SIZE / 2,
            display: "grid",
            placeItems: "center",
            borderRadius: 12,
            background: COLORS[i % COLORS.length],
            color: "#fff",
            fontFamily: "Georgia, serif",
            fontSize: 26,
            fontWeight: 700,
          }}
        >
          {ch}
        </div>
      )
    })}
  </div>
)
}

export default defineTool({
id: "toy",
name: "Toy",
documentTypes: ["toy"],
surface: "plain",
render: Board,
})

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 — the map is empty, so every block still falls back to its default spot. That's expected. What changed is underneath: data.blocks is now a real collaborative field, not a constant, and the moment something writes to it, this view is already reading the right place.

No coordinates, and that's the whole point

Compare this to useDocument(coords, codec) from Getting Started — that hook needed a document id because a tool's document could be any document. An app's own state only ever means one thing: this mount's state. The host resolves "which document" for you, keyed by world, app, and — you'll feel the reason for that third key in Step 5 — project. State, routes and tabs has the full picture.

Next steps

Step 4 — Drag a blockWrite to the field you just read, and watch it stick.