Step 3: A shared headline

One line of state, shared by the whole app instance — not a document, a room.

The lobby needs something to say. Not a document someone opens — a line of text every member of the world sees, edited by anyone, converging live. That's useCollabState:

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

Same field shapes a document codec uses, but there's no codec to declare and no coords to pass. The host already knows where your app's shared state lives — one room per app instance in this world — so you just describe the shape and get back data/actions, exactly like useDocument.

Add the hook, and an input that writes to it. Edit the code below:

A shared headline

src/app.tsx

import {

type AppHostProps,

type AppSurfaceProps,

type ToolRenderProps,

AppHost,

ToolRegistry,

defineApp,

defineTool,

} from "@vvd/sdk"

function LobbyScreen({ context }: ToolRenderProps) {

const canEdit = context.canEdit

return (

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

</div>

)

}

const lobbyScreen = defineTool({

id: "lobby-screen",

documentTypes: ["lobby-screen"],

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,
} from "@vvd/sdk"

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

return (
  <div style={{ padding: 24, font: "inherit", color: "inherit" }}>
    <h1 style={{ margin: 0, fontSize: 22 }}>Lobby</h1>
  </div>
)
}

const lobbyScreen = defineTool({
id: "lobby-screen",
name: "Lobby",
documentTypes: ["lobby-screen"],
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: an italic line appears under "Lobby", already reading "Welcome — make this place yours." — that default came from field.value's argument, not from you typing anything. Change it. Reload the page and it's gone (this is one browser tab, not a real world) — but point two real people at the same running app and both see the same line, live, the moment either edits it.

Not the document you're looking at

Notice LobbyScreen never called useDocument. The headline isn't stored on any document — it lives in a room the HOST owns, one per app instance in this world. That's what makes it app state rather than document state: every screen this instance renders shares the same headline, the same way every tab of one browser shares localStorage.

Next steps

Step 4 — Pin the worldStar Aria of the North from the world onto the lobby's pinboard.