SDK reference

The dictionary. One entry per element, alphabetized within groups: what it is, why it exists, every property it takes, one minimal example. For the narrative version of any of these — the path through, rather than the lookup — each entry's See also line points at the guide or build-along that introduced it.

Everything on this page is imported from @vvd/sdk unless the example shows a subpath (the one exception: defineDocumentCodec prefers the server-safe @vvd/sdk/document/codec entry).

Defining a creation

The identity functions. Each takes one options object, returns it typed, and is the single authoring entry point for its kind of thing: an app provides a host, a tool consumes one, a block is the embeddable face of a tool, and a codec is the one module where Yjs may appear.

AssetManifest

The declared asset surface of a tool or app — the assets property on defineTool / defineApp. A plain record mapping each version-stable slot key ("weather.rain") to an AssetSpec:

Code references a slot by key, never by path, and resolves it with useAsset — which is what lets a user replace the file without your code changing.

See also: useAsset · useAssetUrl · the appAssets row of HostServices.

buildSeed

Builds a document seed — a Yjs update binary — by running your build callback against a fresh in-memory doc. It exists so sample content can be authored without a server: the result is what a codec's seed property holds and what a fixture hands a mock host, applied by the no-socket local runtime (previews, Storybook, tests) before the document goes ready. Never applied to a live doc.

buildSeed(build: (doc: Y.Doc) => void): Uint8Array

The callback receives a raw Y.Doc — write through the same roots your codec reads. That makes a seed-building module a codec-adjacent module: keep it next to the codec, not in a view.

import { buildSeed } from "@vvd/sdk"

export const sampleTraySeed = buildSeed((doc) => {
  doc.getArray<number>("rolls").push([12, 7, 19])
})

See also: defineDocumentCodec (the seed row) — defineStateCodec derives its seed from your field defaults, so you only build one by hand for a hand-rolled codec or a fixture.

defineApp

Declares an app — a lens that provides a useHost() and owns a space (a tab, a route, a project kind). Reach for it when you're building the thing that hosts tools, not the thing that edits one document; unlike defineTool it validates its derived manifest at the moment your module is imported, so a bad route or version throws before anything mounts.

The two publish presets are platform-executed projections — pure data on the manifest, so an app becomes publishable with no publish code of its own. { preset: "world-site" } publishes the wiki-shaped projection of the world's shippable content (index, refs, routes, types, media, documents), served through the site-family surface — "publish my world". { preset: "project-docs" } publishes only the instance's own project documents as a reading surface (the quill-style story reader) — nothing of the world's canon ships. Full hooks are the code path for apps whose published surface neither preset fits.

import { ToolRegistry, defineApp, deriveCapabilities } from "@vvd/sdk"

import { LobbyHost } from "./host"
import { LobbySurface } from "./surface"
import lobbyTool from "./tool"

const tools = new ToolRegistry().register(lobbyTool)

export default defineApp({
  id: "lobby",
  name: "Lobby",
  route: "lobby",
  version: "1.0.0",
  capabilities: deriveCapabilities(tools, ["world"]),
  Host: LobbyHost,
  Surface: LobbySurface,
  tools,
})

See also: defineTool · useHost — long form: Apps reference → defineApp, in full and the Apps build-along.

defineBlock

Declares a block — a renderer insertable into another surface (a card body, a page), carrying its own bag of data inside the host document. Reach for it when your tool ships UI for someone else's document, or when you're building a document-less, world-reading widget (scope: "world") mountable anywhere via <BlockSlot>.

Its render receives BlockRenderProps<TData>:

import { type BlockRenderProps, defineBlock } from "@vvd/sdk"

interface RollData {
  label: string
  result: number
}

function RollBlock({ block, canEdit, onUpdate }: BlockRenderProps<RollData>) {
  return (
    <aside>
      <strong>{block.data.label}</strong>: {block.data.result}
      {canEdit ? (
        <button onClick={() => onUpdate?.({ result: 1 + Math.floor(Math.random() * 20) })}>
          Reroll
        </button>
      ) : null}
    </aside>
  )
}

export const rollBlock = defineBlock<RollData>({
  type: "dice-roll",
  name: "Die roll",
  render: RollBlock,
})

See also: defineTool — long form: Tools reference → Blocks and World blocks.

defineDocumentCodec

Declares a hand-rolled document codec — the per-document-type adapter that maps a raw Yjs doc to a typed snapshot plus typed actions, and the only module where Yjs may appear. Reach for it when defineStateCodec can't express your data (a canvas, a tree, custom CRDT structure); everything a state codec produces for free you now declare by hand.

import { defineDocumentCodec } from "@vvd/sdk/document/codec"

interface Tray {
  rolls: number[]
}
interface TrayActions {
  roll(sides: number): void
}

export const trayCodec = defineDocumentCodec<Tray, TrayActions>({
  read: (doc) => ({ rolls: doc.getArray<number>("rolls").toArray() }),
  observe: (doc, onChange) => {
    const rolls = doc.getArray<number>("rolls")
    rolls.observe(onChange)
    return () => rolls.unobserve(onChange)
  },
  actions: (doc) => ({
    roll: (sides) =>
      doc.transact(() =>
        doc.getArray<number>("rolls").push([1 + Math.floor(Math.random() * sides)]),
      ),
  }),
  undoScope: (doc) => [doc.getArray("rolls")],
  agentSummary: "A dice tray: the log of rolls made at this table.",
})

See also: defineStateCodec · useDocument — long form: Tools reference → Making it agentable.

defineStateCodec

Declares a typed field shape and returns a complete, collaborative DocumentCodec — read, observe, typed actions, seed, undo scope, history captions, and an auto-derived agent surface, with zero Yjs written by you. Reach for it first, always; eject to defineDocumentCodec only when a declared shape can't express your data.

defineStateCodec(shape, options?) — shape is a Record<string, StateField> built from field.*; options is:

The returned codec's actions (what useDocument(...).actions gives you):

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

export const sheetCodec = defineStateCodec(
  {
    title: field.value("Untitled sheet"),
    rows: field.list<{ label: string; done: boolean }>(),
    votes: field.map<number>(),
    notes: field.prose(),
  },
  { agentSummary: "A shared sheet: a title, rows of items, votes, and notes." },
)

See also: field.* · useDocument · defineDocumentCodec — introduced in Build a shared sheet; storage semantics in the Storing data guide.

defineTool

Declares a tool — a document editor for one or more document types, consuming its host through useHost(). This is the root of every tool project: the host resolves your tool by the document's type and mounts your one render in whichever view fits.

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

import { sheetCodec } from "./codec"

function SheetView({ document, context }: ToolRenderProps) {
  const { data, status, actions, retry } = useDocument(
    { worldId: document.worldId, documentId: document.id, scope: context.scope },
    sheetCodec,
  )
  return (
    <DocumentGate status={status} onRetry={retry}>
      <input
        value={data?.title ?? ""}
        readOnly={!context.canEdit}
        onChange={(e) => actions?.set("title", e.target.value)}
      />
    </DocumentGate>
  )
}

export default defineTool({
  id: "sheet",
  name: "Sheet",
  documentTypes: ["sheet"],
  render: SheetView,
})

See also: ToolRenderProps · useDocument · defineBlock — long form: Tools reference → defineTool, in full; first met in Build a shared sheet.

field.*

The four field constructors — the whole authoring surface of a defineStateCodec shape, each carrying its own CRDT merge behavior. They exist so you choose merge semantics per field once, declaratively, instead of writing Yjs: pick by what should happen when two people edit at the same time.

The optional schema on the first three is a runtime schema (zod works — it implements Standard Schema) that makes the field's auto-generated agent operations and import target precise. Adding a field never needs a migration: a missing field reads as its default.

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

export const questCodec = defineStateCodec({
  title: field.value("Untitled quest"), // LWW scalar
  objectives: field.list<{ text: string; done: boolean }>(), // both inserts land
  rewards: field.map<number>(), // per-key LWW
  briefing: field.prose(), // per-character merge
})

See also: defineStateCodec · CollaborativeText — merge semantics in depth in the Storing data guide.

Reading & writing documents

The document runtime, as a tool sees it: open a document as typed data, gate on its connection status, and render collaborative prose — with the whole connection/sync/Yjs stack hidden behind the codec.

CollaborativeText

A collaborative rich-text surface for one field.prose() field of a document — TipTap, Yjs and the shared doc are all hidden inside. Reach for it whenever people type paragraphs two of them might edit at once; a field.value string would be last-write-wins and eat one person's edit.

import {
  CollaborativeText,
  DocumentGate,
  type DocumentCoords,
  useDocument,
} from "@vvd/sdk"

import { sheetCodec } from "./codec"

export function Notes({ coords, canEdit }: { coords: DocumentCoords; canEdit: boolean }) {
  const { data, handle, status, retry } = useDocument(coords, sheetCodec)
  return (
    <DocumentGate status={status} onRetry={retry}>
      {data ? (
        <CollaborativeText
          handle={handle}
          field={data.notes}
          editable={canEdit}
          placeholder="Start typing…"
        />
      ) : null}
    </DocumentGate>
  )
}

See also: field.* · useDocument — long form: Tools reference → Collaborative text.

DocumentGate

The shared status gate every tool wraps its body with: error states render the SDK's retry card, connecting renders a skeleton, ready renders your children. It exists so status/error/skeleton handling is inherited with zero per-tool connection UI — the tool owns useDocument, so the tool surfaces status and retry here.

import { DocumentGate, type DocumentCoords, useDocument } from "@vvd/sdk"

import { sheetCodec } from "./codec"
import { SheetSkeleton } from "./skeleton"

export function SheetBody({ coords }: { coords: DocumentCoords }) {
  const { data, status, retry } = useDocument(coords, sheetCodec)
  return (
    <DocumentGate status={status} onRetry={retry} skeleton={SheetSkeleton}>
      <h1>{data?.title}</h1>
    </DocumentGate>
  )
}

See also: useDocument · defineTool (Skeleton) — the related exports DocumentError and DefaultDocumentSkeleton are the pieces it composes.

encodeDocumentSnapshot

Encodes the current state of an open document as a portable update binary — the one supported way a tool captures a document for publishing. It exists so publishing never requires the tool to touch Yjs: take the bytes from the handle, hand them to host.publish.publish(...).

Returns Uint8Array — the snapshot the published surface re-seeds an in-memory doc with; the same codec reads it back identically.

import {
  type DocumentHandle,
  type VvdDocument,
  encodeDocumentSnapshot,
  useHost,
} from "@vvd/sdk"

export function PublishButton({
  document,
  handle,
}: {
  document: VvdDocument
  handle: DocumentHandle | null
}) {
  const host = useHost()
  if (!host.publish || !handle) return null
  return (
    <button
      onClick={async () => {
        const { url } = await host.publish!.publish({
          documentId: document.id,
          documentType: document.type,
          title: document.title,
          snapshot: encodeDocumentSnapshot(handle),
        })
        await navigator.clipboard.writeText(url)
      }}
    >
      Publish a snapshot
    </button>
  )
}

See also: useDocument (handle) · the publish row of HostServices.

ToolRenderProps

The props a tool's render receives — exactly two: the document's identity and the mount's context. It exists as the whole input contract of a tool view: everything else (live data, capabilities) is reached through hooks, so the same render runs under every host.

document (VvdDocument):

context (ToolContext):

import { type ToolRenderProps } from "@vvd/sdk"

export function SheetView({ document, context }: ToolRenderProps) {
  if (context.view === "embed") {
    return <CompactSheet documentId={document.id} />
  }
  return <FullSheet documentId={document.id} canEdit={context.canEdit} />
}

See also: defineTool · useDocument — long form: Tools reference → defineTool, in full.

useDocument

Opens a document and returns it as typed, reactive data with typed mutators — the whole connection/sync/Yjs stack hidden behind the runtime and your codec. This is the one hook every tool's render calls; it re-renders only when the snapshot actually changes, never on unrelated edits.

useDocument(coords, codec):

Returns UseDocumentResult<TData, TActions>:

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

import { sheetCodec } from "./codec"

export function SheetView({ document, context }: ToolRenderProps) {
  const { data, status, actions, retry } = useDocument(
    { worldId: document.worldId, documentId: document.id, scope: context.scope },
    sheetCodec,
  )
  return (
    <DocumentGate status={status} onRetry={retry}>
      <button
        disabled={!context.canEdit}
        onClick={() => actions?.list("rows").push({ label: "New row", done: false })}
      >
        Add row ({data?.rows.length ?? 0})
      </button>
    </DocumentGate>
  )
}

See also: defineStateCodec · DocumentGate · useDocumentPresence — the loop is walked through in Build a shared sheet; data-plane rules in the Retrieving data guide.

Presence

Who else is here. Presence derives from Yjs awareness — a separate protocol from document data — so reading it never touches your codec and never writes the doc.

PresencePeer

One remote (or local) collaborator on an open document, deduped by user. It exists as the one shape every presence hook returns, so a presence strip renders the same peers whether it sits inside the tool or beside it.

import { type PresencePeer } from "@vvd/sdk"

export function Avatar({ peer }: { peer: PresencePeer }) {
  return (
    <span
      title={peer.isSelf ? `${peer.name} (you)` : peer.name}
      style={{ borderColor: peer.color }}
    >
      {peer.name.slice(0, 1).toUpperCase()}
    </span>
  )
}

See also: useDocumentPresence · useDocumentPresenceById — the Presence guide.

useCollabPresence

Ephemeral per-peer state (cursor, selection, "what I'm looking at") over a shared state room's awareness — set your own small JSON, read everyone's. Reach for it when peers need to see each other doing, not just being there: it's lost on disconnect by design, and identity fields are host-stamped, never author-writable.

useCollabPresence<T>(handle) takes the DocumentHandle of the shared state (usually from useCollabState) and returns:

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

export function Cursors() {
  const { handle } = useCollabState({ title: field.value("") })
  const { peers, setLocal } = useCollabPresence<{ x: number; y: number }>(handle)
  return (
    <div onPointerMove={(e) => setLocal({ x: e.clientX, y: e.clientY })}>
      {peers
        .filter((p) => !p.isSelf && p.state)
        .map((p) => (
          <span
            key={p.userId}
            style={{ left: p.state!.x, top: p.state!.y, color: p.color }}
          >
            {p.name}
          </span>
        ))}
    </div>
  )
}

See also: useCollabState · PresencePeer — the Presence guide.

useCollabState

Typed, live, convergent shared state for this mount — a tool's document, or an app surface's durable per-instance state doc — declared as a field.* shape, with peers included. Reach for it in an app (which has no document of its own) or any surface that wants shared state without managing coordinates: the host's collab capability says where the state lives.

useCollabState(shape, options?) takes the same arguments as defineStateCodec and returns everything useDocument returns, plus:

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

export function LobbyBanner() {
  const { data, actions, peers, status } = useCollabState({
    motto: field.value("Welcome, travelers"),
  })
  if (status !== "ready" || !data) return null
  return (
    <header>
      <input value={data.motto} onChange={(e) => actions?.set("motto", e.target.value)} />
      <span>{peers.length} here now</span>
    </header>
  )
}

See also: useDocument · useCollabPresence — app state in Apps reference → State, routes and tabs.

useDocumentAwareness

The live Yjs Awareness for the document a handle wraps — the raw channel every presence hook on this page derives from. Reach for it when the typed hooks aren't enough: to hand awareness through to an SDK collaborative component that draws cursors, or to broadcast a small ephemeral payload of your own with setLocalStateField.

Returns Awareness | null (the y-protocols/awareness type) — null until the document opens.

Whatever you broadcast over it is ephemeral by contract: it lives only while you're connected, is never written to the document, and identity fields stay host-stamped. For the common typed case — publish one small state, read every peer's — useCollabPresence is the friendlier door; the raw object is for when you need the protocol itself (the Blocks starter kit broadcasts each peer's hand position this way).

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

export function Board() {
  const { handle } = useCollabState({ title: field.value("") })
  const awareness = useDocumentAwareness(handle)
  return (
    <div
      onPointerMove={(e) => awareness?.setLocalStateField("cursor", { x: e.clientX, y: e.clientY })}
      onPointerLeave={() => awareness?.setLocalStateField("cursor", null)}
    />
  )
}

See also: useCollabPresence · useDocumentPresence — the Presence guide.

useDocumentPresence

The deduped peer list on the document a handle wraps — re-renders only on an awareness change. Reach for it inside the tool that holds the document open: a presence strip, a "who's editing" row.

Returns PresencePeer[] — deduped by userId, the local user marked isSelf.

import { type DocumentHandle, useDocumentPresence } from "@vvd/sdk"

export function PresenceStrip({ handle }: { handle: DocumentHandle | null }) {
  const peers = useDocumentPresence(handle)
  const others = peers.filter((p) => !p.isSelf)
  if (others.length === 0) return null
  return (
    <div>
      {others.map((p) => (
        <span key={p.userId} style={{ background: p.color }}>
          {p.name}
        </span>
      ))}
    </div>
  )
}

See also: PresencePeer · useDocumentPresenceById — the Presence guide.

useDocumentPresenceById

Presence for chrome that sits next to a mounted tool — a panel header's avatar row — which knows a documentId but holds no DocumentHandle (the handle lives inside the tool). It observes the doc the tool itself has open — no second connection — and returns [] until the tool has opened it.

Returns PresencePeer[], refreshing on joins, leaves, and identity re-stamps.

import { useDocumentPresenceById } from "@vvd/sdk"

export function PanelHeader({ documentId, title }: { documentId: string; title: string }) {
  const peers = useDocumentPresenceById(documentId)
  return (
    <header>
      <h2>{title}</h2>
      <span>{peers.filter((p) => !p.isSelf).length} others</span>
    </header>
  )
}

See also: useDocumentPresence (when you do have the handle) · PresencePeer.

The host

The single capability seam a tool or block reaches its environment through. The app implements HostServices once and provides it via <HostProvider>; the same tool runs against the editor, a wiki, and a published page because only the host object changes.

HostServices

The full capability interface behind useHost() — a lightly namespaced object where each key is one capability a host may (or must) provide. It exists so a consumer declares exactly what it needs, a host can honestly omit what it doesn't have, and a missing namespace fails loud at the boundary instead of as an undefined deref three frames deep.

Every capability, what it gives you, and how a tool consumes it:

Three kinds, three habits: always-present capabilities you just read; grant-gated ones you list in needs and consume via useHostCapability (fails loud, by name); inherited ones you never declare — their hooks degrade quietly under a host that omits them (icons fall back to a glyph, sound goes silent, a right-click hands the event back to the browser).

import { useHost } from "@vvd/sdk"

export function RollButton({ onRoll }: { onRoll: () => number }) {
  const host = useHost()
  return (
    <button
      onClick={() => {
        const value = onRoll()
        host.analytics?.track("rolled", { value }) // inherited: optional-chain, never in needs
      }}
    >
      Roll
    </button>
  )
}

See also: useHost · useHostCapability — the full kind-by-kind treatment in Tools reference → Host capabilities and the Host guide.

loadThree

The platform's shared three.js, loaded lazily. Three.js is around a megabyte, so no creation bundles its own copy: the platform ships one, code-split, and a creation that wants 3D just awaits this. A plain export rather than a capability — call it anywhere, not through the host — and nothing is fetched until the first call, so a creation that never shows a model pays nothing.

loadThree(): Promise<ThreeKit> — no parameters. Resolves to ThreeKit: three's module namespace merged with the bundled example loaders (OBJLoader, GLTFLoader, STLLoader, PLYLoader, FBXLoader), so T.Scene and new T.OBJLoader() both resolve off the one object. The promise is cached: repeat and concurrent callers share a single in-flight import, and every creation in the session shares the one three instance — which is what keeps loader output and instanceof checks agreeing across creations. (ThreeKit is typed loosely — three ships no SDK types.)

import { loadThree } from "@vvd/sdk"

export async function loadModel(url: string) {
  const T = await loadThree()
  const model = await new T.OBJLoader().loadAsync(url)
  return model
}

See also: the 3D Model starter kit — a whole viewer built on it.

useHost

Returns the full HostServices for this mount — the whole seam in one read. Reach for it in code touching several namespaces at once (a tool's main edit view); it throws outside a <HostProvider>, which in practice means "you rendered a tool outside a host — wrap tests in createFakeHost".

No parameters. Returns HostServices.

import { peekOrOpenDocument, useHost } from "@vvd/sdk"

export function LinkedCard({
  worldId,
  id,
  name,
}: {
  worldId: string
  id: string
  name: string
}) {
  const { nav, refs } = useHost()
  return (
    <button
      onClick={() =>
        peekOrOpenDocument(nav, refs.coordsFor(id) ?? { worldId, documentId: id })
      }
    >
      {name}
    </button>
  )
}

See also: useHostCapability · HostServices · createFakeHost — the Host guide.

useHostCapability

Returns exactly one named capability, throwing a named error when the host doesn't provide it. Reach for it for every grant-gated capability (world, projects, search, documents, install, …): the failure surfaces at the boundary, with the capability's name, instead of as an undefined deref deep in a leaf.

Returns the non-null capability. Throws Host capability "<name>" is not provided by this host … when absent — the message you'll see when a grant is missing from vvd.json.

import { useHostCapability } from "@vvd/sdk"

export function NewSpaceButton() {
  const projects = useHostCapability("projects") // needs the writesWorld grant
  return (
    <button onClick={() => projects.create("lobby", "A new space")}>New space</button>
  )
}

See also: useHost · HostServices — grant mapping in Apps reference → Owning a space.

Capability hooks

The per-capability hooks the HostServices table's "Consume via" column names — each wraps one namespace with the right consumption habit built in (defensive for inherited capabilities, fail-loud for grant-gated ones). Short entries: what it is, its signature, the capability it rides.

useAsset

Resolves a tool/app asset slot to a URL through the override cascade — doc override ?? install override ?? the shipped default from the AssetManifest. Rides appAssets (host-owned) + media.

useAsset(app: string, slotKey: string, overrides?: AssetOverrideLayers): string | null

null until resolved, or when the slot is neither overridden nor declared. "Revert to default" is just dropping the slot from overrides.

useAssetUrl

Resolves any AssetRef (a bare world_media id string, { kind: "media", id }, or { kind: "app", app, key, version? }) to a URL in two phases: the sync placeholder paints first, then the async truth settles. Rides appAssets + media.

useAssetUrl(ref: AssetRef | null | undefined): string | null

The consumer can't tell whether the bytes came from the app bundle or the world media pool — which is the point.

useDndState

Live discrete drag state — dragging / payload / hovered zone — re-rendering on coarse changes only, never at pointer rate. Rides dnd (inherited).

useDndState(): DndSnapshot

Under a dnd-less host it returns the inert snapshot, so if (state.dragging) affordances simply never light up.

useDocDragSource

Makes an element a cross-surface document drag source: spread the result ({ draggable, onDragStart, onDragEnd }) on the row or handle. Rides dnd (inherited).

useDocDragSource(payload: DocDragPayload | null): DocDragSourceProps

Writes the payload to dataTransfer at dragstart and mirrors it into the host's engine so targets can validate during dragover and the platform ghost can morph; under a dnd-less host it degrades to a plain native drag. null payload renders the element non-draggable.

useDocDropTarget

Makes an element a document drop target on both input channels: spread the returned props (native HTML5 drag events) and attach the returned ref (pointer/touch drags) to the same element. Rides dnd (inherited).

useDocDropTarget(opts: { zone: string; preview?: DropPreviewKind; accepts?: (payload) => boolean; onDrop: (payload, point) => void }): { props; ref; isOver; canDrop }

accepts filters during dragover and is re-checked on drop; onDrop gets the payload plus the drop point in client coordinates. Works unchanged under a dnd-less host — native drops still land, nothing morphs.

useEmbeddedDocument

The projected-embed read for a referenced document (map tiles, timeline spans): prefers the host's live subscribe, falls back to fetch on published/baked surfaces — the tool never branches on host. Rides embeds (always present).

useEmbeddedDocument<T>(coords: DocumentCoords | null): { data: T | null; loading: boolean }

null coords (an unresolvable ref) answers { data: null, loading: false } — settled and empty, never an eternal spinner. For a raw-Yjs embed of another document, use useDocument with refs.coordsFor(id) instead.

useFeedback

Submit user feedback about this creation through the host's one feedback layer — the host stamps which tool it came from (un-spoofable) and routes it. Rides feedback (inherited).

useFeedback(): { submit(feedback: FeedbackSubmission): Promise<boolean>; shouldPrompt(trigger: string): boolean }

submit resolves false — touching nothing — under a feedback-less host or on empty text; shouldPrompt is the host-owned cooldown gate for proactive prompts.

useFocusMode

The shell's chrome-hidden view as a switch your UI can read and drive. Rides focusMode (inherited).

useFocusMode(): { available: boolean; active: boolean; set(active: boolean): void; toggle(): void }

available is false under hosts with no chrome to hide (published/anon/test) — hide your toggle button on it; the mutators no-op there.

useHostLocale

The reader's language plus the locale catalogs your creation shipped, re-rendering live when the reader switches language. Rides locale (inherited).

useHostLocale(): HostLocaleSnapshot — { locale, supported, defaultLocale, messages, defaultMessages }

Read it for the language list a picker offers (supported is the creation's locales, not the platform's) or the active code; for words, use useT. Under a locale-less host it returns the frozen en fallback.

useOpenWorldDocumentFields

Live typed field values from documents currently open in this client — the host performs the codec read, so a tool receives only fields, never another tool's Y.Doc or codec (the zero-copy bridge projections like Table use). Rides world (grant-gated, readsWorld).

useOpenWorldDocumentFields(input: { documentType: string; entityTypeId?: string; fields: { id: string; field: WorldDocumentField }[] }): readonly WorldDocumentFieldRow[]

Closed documents are intentionally absent — the durable world index remains their source.

useReactions

A subject's like/comment/report feed with optimistic mutations — one fetch seeds it, every gesture patches it, the service confirms or rolls back. Rides reactions (inherited).

useReactions(subject: { type, id } | null | undefined, opts?): ReactionsState

Returns the feed plus isLoading, unavailable (no capability, or the viewer can't see the subject — render nothing), signedOut, can(type), and toggleLike / toggleDislike / postComment / deleteComment / report. Reports are deliberately not optimistic — filing one waits for the server.

useScope

The mount's Scope — the same value as useHost().scope, readable without pulling the whole host object. Rides scope (always present).

useScope(): Scope — { type: "world", worldId } or { type: "project", worldId, projectId }

Throws outside a <ScopeProvider>; the host's dispatch (ToolHost) wraps every tool mount in one.

useT

Your creation's own strings in the reader's language — the translator over useHostLocale. Rides locale (inherited).

useT(): Translator — t(key, params?), plus t.plural(key, count), t.date(when), t.number(n), t.locale

Never throws and never renders an empty box: a missing catalog falls to the base language, then the creation's default, then the key's own text — so writing default-language strings as the keys is a fine way to adopt it one string at a time.

useUndoableCommand

Push an invertible structural command onto the host's undo engine — the data-plane half of undo. Mutate first (optimistically, through your normal write path), then record the inverse. Rides undo (inherited).

useUndoableCommand(): (command: UndoableCommand) => boolean

A command is { labels, undo(): Promise<boolean>, redo(): Promise<boolean>, isStale?, batchKey? } — consecutive pushes sharing a batchKey coalesce into one Cmd+Z. Returns false (recording nothing) under an undo-less host; the mutation itself already happened.

useUndoScope

Register a live undo provider (a library's own stack — tldraw, a custom model) with the host's engine, anchored in the focus tree so Cmd+Z routes to the surface the user is looking at. Rides undo (inherited).

useUndoScope(handle: UndoScopeHandle | null): void

The handle is { canUndo(), canRedo(), undo(), redo(), label? }; pass null to stand down (read-only views). useDocument-backed tools never call this — the document surface registers for them. No-op under an undo-less host.

World data

Live, read-only reads over the world's catalog — the same collections the platform renders from, projected through the contract. All of it rides the world capability (the readsWorld grant); content stays behind the document seam — a row gives you ids and names to feed useDocument or an embed.

useUseCase

What the world you're mounted in is for — its declared use cases, first one primary. Reach for it to match the platform's voice ("roll for it" in a campaign world, "try it" elsewhere) without owning a variant schema; it's a hint, so match the values you know and fall through to neutral wording.

No parameters. Returns:

import { useUseCase } from "@vvd/sdk"

export function EmptyState() {
  const { primary } = useUseCase()
  return <p>{primary === "campaign" ? "Roll for it." : "Try it."}</p>
}

See also: useWorldMeta (the row it reads from) — the World data guide.

useWorldMeta

The world's own header — identity, presentation, theme — live. Reach for it to render the world's name and wear its look; returns null when the host doesn't provide it, and fails loud only on the missing world capability itself.

No parameters. Returns WorldMetaRow | null:

import { useWorldMeta } from "@vvd/sdk"

export function WorldHeader() {
  const meta = useWorldMeta()
  if (!meta) return null
  return <h1 style={{ color: meta.theme["--primary"] }}>{meta.name}</h1>
}

See also: useWorldQuery · the theme row of HostServices — the World data guide.

useWorldQuery

Live React reads over the world's catalog — the component re-renders as the world changes on any client. This is the standard read for "list the world's X": no fetch, no cache of your own, no snapshot that silently goes stale.

useWorldQuery(kind, filter?):

Fails loud (naming the capability) when the install didn't grant readsWorld. Three siblings cover the edges: useWorldDocumentsOptional / useWorldMediaOptional return [] instead of throwing on a world-less host (for UI that merely enriches), and useOpenWorldDocumentFields streams typed fields from documents currently open in this client (the zero-copy bridge projections like Table use).

import { useWorldQuery } from "@vvd/sdk"

export function Roster() {
  const cards = useWorldQuery("documents", { type: "card" })
  return (
    <ul>
      {cards.map((c) => (
        <li key={c.id}>{c.name}</li>
      ))}
    </ul>
  )
}

See also: useWorldMeta · useHostCapability — the World data guide; the index grammar in Tools reference → Search and the index.

Testing

The dependency-free harness: a complete host of fakes, so a tool renders and unit-tests headless against the same useHost() contract it ships against.

createFakeHost

Builds a complete HostServices of inert fakes — no network, no Yjs server, permissive identity — for rendering a tool under <HostProvider> in tests, Storybook, and previews. Reach for it in every tool test; swap in a recording fake for any capability you want to assert the tool actually called.

Returns a full HostServices. The recording twins, each returning the capability plus an array you assert on:

import { render, screen } from "@testing-library/react"
import { HostProvider, createFakeHost, createRecordingAnalytics } from "@vvd/sdk"

import sheetTool from "./tool"

it("renders and tracks under a fake host", () => {
  const { analytics, events } = createRecordingAnalytics()
  const host = createFakeHost({ analytics })
  const Tool = sheetTool.render
  render(
    <HostProvider services={host}>
      <Tool
        document={{
          id: "d1",
          worldId: host.scope.worldId,
          type: "sheet",
          title: "Sheet",
          scope: host.scope,
          visibility: "shown",
        }}
        context={{ scope: host.scope, canEdit: true, view: "editor" }}
      />
    </HostProvider>,
  )
  screen.getByRole("button", { name: /add row/i }).click()
  expect(events.map((e) => e.name)).toContain("row_added")
})

See also: useHost · HostServices — the Testing guide; server-side twins (createFakeServerContext) in Tools reference → Server endpoints.