Step 4: Pin the world

A pinboard is a list of ids in your own state, pointing at documents you don't own.

A pinboard doesn't need new documents — it needs a list of ids pointing at documents that already exist, plus a way to open one. Add a second field to the same shared state, and read the world alongside it:

const { data, actions } = useCollabState({
  headline: field.value<string>("Welcome — make this place yours."),
  pinnedIds: field.list<string>(),
})
const docs = useWorldQuery("documents")

useWorldQuery("documents") is live — it re-renders as the world's catalog changes on any client, the same way useCollabState is live for the headline. Reading it takes one declaration: needs: ["world"] on the tool, because needs is your consent surface — refs and nav are always present, but reading the world must be asked for.

Pin "Aria of the North" with actions.list("pinnedIds").push(id); open it by resolving its id through the refs capability and handing the result to nav:

A pinboard

src/app.tsx

import {

type AppHostProps,

type AppSurfaceProps,

type ToolRenderProps,

AppHost,

ToolRegistry,

defineApp,

defineTool,

field,

useCollabState,

} from "@vvd/sdk"

function LobbyScreen({ context }: ToolRenderProps) {

const canEdit = context.canEdit

const { data, actions } = useCollabState({

headline: field.value<string>("Welcome — make this place yours."),

})

return (

<h1 style={{ margin: 0, fontSize: 22 }}>Lobby</h1>

{canEdit ? (

<input

value={data?.headline ?? ""}

onChange={(e) => actions?.set("headline", e.target.value)}

style={{ marginTop: 10, width: "100%", border: "none", outline: "none", background: "transparent", color: "inherit", font: "inherit", fontSize: 15, fontStyle: "italic", opacity: 0.85 }}

) : (

<p style={{ margin: "10px 0 0", fontSize: 15, fontStyle: "italic", opacity: 0.85 }}>{data?.headline}</p>

)}

</div>

)

}

const lobbyScreen = defineTool({

id: "lobby-screen",

documentTypes: ["lobby-screen"],

needs: ["world"],

surface: "plain",

render: LobbyScreen,

})

const lobbyApp = defineApp({

id: "lobby",

route: "lobby",

Host: function LobbyHost({ children }: AppHostProps) {

return <>{children}</>

Surface: function LobbySurface({ children }: AppSurfaceProps) {

return <div style={{ height: "100%" }}>{children}</div>

tools: new ToolRegistry().register(lobbyScreen),

})

export default defineTool({

id: "app-demo",

documentTypes: ["app-demo"],

surface: "plain",

render: function AppDemo({ document, context }: ToolRenderProps) {

return <AppHost app={lobbyApp} document={{ ...document, type: "lobby-screen" }} context={context} />

})

import {
type AppHostProps,
type AppSurfaceProps,
type ToolRenderProps,
AppHost,
ToolRegistry,
defineApp,
defineTool,
field,
useCollabState,
} from "@vvd/sdk"

function LobbyScreen({ context }: ToolRenderProps) {
const canEdit = context.canEdit

const { data, actions } = useCollabState({
  headline: field.value<string>("Welcome — make this place yours."),
})

return (
  <div style={{ padding: 24, font: "inherit", color: "inherit" }}>
    <h1 style={{ margin: 0, fontSize: 22 }}>Lobby</h1>
    {canEdit ? (
      <input
        value={data?.headline ?? ""}
        onChange={(e) => actions?.set("headline", e.target.value)}
        style={{ marginTop: 10, width: "100%", border: "none", outline: "none", background: "transparent", color: "inherit", font: "inherit", fontSize: 15, fontStyle: "italic", opacity: 0.85 }}
      />
    ) : (
      <p style={{ margin: "10px 0 0", fontSize: 15, fontStyle: "italic", opacity: 0.85 }}>{data?.headline}</p>
    )}
  </div>
)
}

const lobbyScreen = defineTool({
id: "lobby-screen",
name: "Lobby",
documentTypes: ["lobby-screen"],
needs: ["world"],
surface: "plain",
render: LobbyScreen,
})

const lobbyApp = defineApp({
id: "lobby",
name: "Lobby",
route: "lobby",
Host: function LobbyHost({ children }: AppHostProps) {
  return <>{children}</>
},
Surface: function LobbySurface({ children }: AppSurfaceProps) {
  return <div style={{ height: "100%" }}>{children}</div>
},
tools: new ToolRegistry().register(lobbyScreen),
})

export default defineTool({
id: "app-demo",
name: "App demo",
documentTypes: ["app-demo"],
surface: "plain",
render: function AppDemo({ document, context }: ToolRenderProps) {
  return <AppHost app={lobbyApp} document={{ ...document, type: "lobby-screen" }} context={context} />
},
})

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

Running · your edits, live

Starting the example…

You should see: every document in the world listed under the headline, each with a star. Click "Aria of the North" — it fills in and stays filled after you click elsewhere. Click it again to unpin.

A reference, never a copy

pinnedIds holds ids, not documents. Pin "Aria of the North" and you've written one string into your app's own state — the card itself still lives where it always did, still owned by whoever owns it, still visible to whoever could see it before. Rename the card in the editor and the pinned chip's label follows, because it's reading the same row useWorldQuery already gave you.

Next steps

Step 5 — A live directoryGroup everything the world holds, without a pin.