Step 6: Let people make their own board

The same picker vvd run shows in the terminal, built from inside the app itself.

Step 5 proved two boards can be independent. It didn't show you how anyone gets a second one. Right now that's a terminal question — vvd run asks "open which project?" before it ever shows you a browser. Here's that exact prompt, for real, in a real project:

$ vvd run
? Open Toy in which project? › (Use arrow keys)
❯ The Salt Road
  Winterhold
  + New — a fresh Toy

Pick one (or make one) and the dev tab opens already scoped to it — that's the mechanism behind Step 5's independence, driven from a terminal instead of two browser panes.

Your app can offer the same choice inside its own UI, with the capability that prompt is built on:

const projects = useHostCapability("projects")

const boards = await projects.list("toy") // every board this world has
const fresh = await projects.create("toy", "A new board")

Add a small header above the canvas that lists existing boards and makes new ones:

A picker of your own

src/app.tsx

import { type PointerEvent, useRef } from "react"

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

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

const WORD = "TOY"

const SIZE = 64

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

const clamp01 = (v: number) => (v < 0 ? 0 : v > 1 ? 1 : v)

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({ context }: ToolRenderProps) {

const { data, actions } = useCollabState({ blocks: field.map<Block>() })

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

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

if (!data || !actions) return null

const letters = WORD.split("")

const at = (i: number): Block => data.blocks[String(i)] || defaultBlock(i, letters.length)

const begin = (i: number, e: PointerEvent) => {

if (!context.canEdit) return

const rect = areaRef.current?.getBoundingClientRect()

const b = at(i)

dragRef.current = {

dx: rect ? e.clientX - (rect.left + b.x * rect.width) : 0,

dy: rect ? e.clientY - (rect.top + b.y * rect.height) : 0,

}

areaRef.current?.setPointerCapture?.(e.pointerId)

}

const onMove = (e: PointerEvent) => {

const d = dragRef.current

const rect = areaRef.current?.getBoundingClientRect()

if (!d || !rect) return

actions.map("blocks").set(String(d.i), {

x: clamp01((e.clientX - d.dx - rect.left) / rect.width),

y: clamp01((e.clientY - d.dy - rect.top) / rect.height),

})

}

return (

<div

ref={areaRef}

onPointerMove={onMove}

onPointerUp={() => { dragRef.current = null }}

style={{ position: "relative", height: "100%", touchAction: "none" }}

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

const b = at(i)

return (

<div

key={i}

onPointerDown={(e) => begin(i, e)}

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,

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

touchAction: "none",

userSelect: "none",

}}

{ch}

</div>

)

})}

</div>

)

}

export default defineTool({

id: "toy",

name: "Toy",

documentTypes: ["toy"],

surface: "plain",

render: Board,

})

import { type PointerEvent, useRef } from "react"

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

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

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

const clamp01 = (v: number) => (v < 0 ? 0 : v > 1 ? 1 : v)

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({ context }: ToolRenderProps) {
const { data, actions } = useCollabState({ blocks: field.map<Block>() })
const areaRef = useRef<HTMLDivElement | null>(null)
const dragRef = useRef<{ i: number; dx: number; dy: number } | null>(null)
if (!data || !actions) return null

const letters = WORD.split("")
const at = (i: number): Block => data.blocks[String(i)] || defaultBlock(i, letters.length)

const begin = (i: number, e: PointerEvent) => {
  if (!context.canEdit) return
  const rect = areaRef.current?.getBoundingClientRect()
  const b = at(i)
  dragRef.current = {
    i,
    dx: rect ? e.clientX - (rect.left + b.x * rect.width) : 0,
    dy: rect ? e.clientY - (rect.top + b.y * rect.height) : 0,
  }
  areaRef.current?.setPointerCapture?.(e.pointerId)
}
const onMove = (e: PointerEvent) => {
  const d = dragRef.current
  const rect = areaRef.current?.getBoundingClientRect()
  if (!d || !rect) return
  actions.map("blocks").set(String(d.i), {
    x: clamp01((e.clientX - d.dx - rect.left) / rect.width),
    y: clamp01((e.clientY - d.dy - rect.top) / rect.height),
  })
}

return (
  <div
    ref={areaRef}
    onPointerMove={onMove}
    onPointerUp={() => { dragRef.current = null }}
    style={{ position: "relative", height: "100%", touchAction: "none" }}
  >
    {letters.map((ch, i) => {
      const b = at(i)
      return (
        <div
          key={i}
          onPointerDown={(e) => begin(i, e)}
          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,
            cursor: context.canEdit ? "grab" : "default",
            touchAction: "none",
            userSelect: "none",
          }}
        >
          {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: a thin bar above the board, naming your scope ("world canon" — a docs page mounts no project) and a + New board button. Click it a few times; the pill row fills up. Nothing is wired to actually switch boards here — that's the tab's job, covered next — but the list and the creation are real calls against the fake host, the same shape vvd run's prompt makes against the real one.

needs: ['projects'] — new here

Every capability your tool touches gets declared. useCollabState didn't need one (collaboration is granted by default); projects does — it's how the install screen tells a user "this app can create instances of itself" before they say yes.

Switching, for real

Inside a real world, your app is mounted as a tab, and the tab knows which board it's bound to:

const tab = useHost().tab

tab?.setProject(chosen) // re-bind THIS tab — the host persists it and re-scopes you
tab?.setProject(null) // back to world canon

Read tab off the host rather than through useHostCapability — it only exists where there are tabs, and a docs page, an embed, and a published link all honestly have none. Projects covers tab and the projects capability end to end.

Next steps

Step 7 — Wear the world's look, then ship ituseHostTheme, and the commands that put this in a real world, shared.