Step 4: Design the embed

The same component renders full-size and card-sized — context.view is how it knows which.

Whoever drops your pin board into a card meets it small, next to a paragraph of prose, long before anyone opens it on its own. That inline mount is a block — the embeddable face of your tool — and you don't write a second component for it. You write one that knows which face it's wearing.

The host mounts your render in one of three views and tells you which via context.view: "embed" (block-sized, inline), "editor" (the side panel — the default), or "fullscreen". A pin board only really has two layouts — branch on "embed" and treat everything else the same:

const compact = context.view === "embed"

One board, two faces

src/tool.tsx

import { useMemo, useRef } from "react"

import type { MouseEvent as ReactMouseEvent, PointerEvent as ReactPointerEvent } from "react"

import {

DocumentGate,

type ToolRenderProps,

defineStateCodec,

defineTool,

field,

useDocument,

} from "@vvd/sdk"

/** One pin. x/y are pixels in the BOARD's own space — never a scaled ancestor's. */

export type Pin = {

x: number

y: number

label: string

}

export const codec = defineStateCodec({

// A per-KEY map: two people dropping different pins at once BOTH land.

pins: field.map<Pin>(),

})

const newId = () => crypto.randomUUID()

function Board({

data,

actions,

canEdit,

}: {

data: { pins: Readonly<Record<string, Pin>> }

actions: {

map(name: "pins"): { set(key: string, value: Pin): void; delete(key: string): void }

}

canEdit: boolean

}) {

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

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

const pins = Object.entries(data.pins)

const onBoardClick = (e: ReactMouseEvent<HTMLDivElement>) => {

if (!canEdit || e.target !== boardRef.current) return

const rect = boardRef.current.getBoundingClientRect()

actions.map("pins").set(newId(), {

x: e.clientX - rect.left,

y: e.clientY - rect.top,

label: "Pin",

})

}

const beginDrag = (id: string, pin: Pin) => (e: ReactPointerEvent<HTMLDivElement>) => {

if (!canEdit) return

e.stopPropagation()

const rect = boardRef.current?.getBoundingClientRect()

if (!rect) return

dragRef.current = { id, dx: e.clientX - rect.left - pin.x, dy: e.clientY - rect.top - pin.y }

e.currentTarget.setPointerCapture(e.pointerId)

}

const onDrag = (e: ReactPointerEvent<HTMLDivElement>) => {

const d = dragRef.current

const pin = d && data.pins[d.id]

if (!d || !pin) return

const rect = boardRef.current?.getBoundingClientRect()

if (!rect) return

actions.map("pins").set(d.id, {

...pin,

x: e.clientX - rect.left - d.dx,

y: e.clientY - rect.top - d.dy,

})

}

const endDrag = () => {

dragRef.current = null

}

return (

<div

ref={boardRef}

onClick={onBoardClick}

style={{

position: "relative",

height: "100%",

background:

"radial-gradient(rgba(127,127,127,0.25) 1px, transparent 1px) 0 0 / 20px 20px",

cursor: canEdit ? "crosshair" : "default",

}}

{pins.map(([id, pin]) => (

<div

key={id}

onPointerDown={beginDrag(id, pin)}

onPointerMove={onDrag}

onPointerUp={endDrag}

style={{

position: "absolute",

left: pin.x,

top: pin.y,

transform: "translate(-50%, -100%)",

touchAction: "none",

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

fontSize: 22,

lineHeight: 1,

userSelect: "none",

}}

📍

</div>

))}

{pins.length === 0 && (

style={{

position: "absolute",

inset: 0,

display: "grid",

placeItems: "center",

margin: 0,

opacity: 0.5,

fontSize: 13,

pointerEvents: "none",

}}

Click anywhere to drop a pin

</p>

)}

</div>

)

}

function PinBoard({ document, context }: ToolRenderProps) {

const coords = useMemo(

() => ({ worldId: document.worldId, documentId: document.id }),

[document.worldId, document.id],

)

const { data, status, actions, retry } = useDocument(coords, codec)

return (

{data && actions ? (

) : null}

</DocumentGate>

)

}

export default defineTool({

id: "pin-board",

name: "Pin board",

documentTypes: ["pin-board"],

render: PinBoard,

})

import { useMemo, useRef } from "react"
import type { MouseEvent as ReactMouseEvent, PointerEvent as ReactPointerEvent } from "react"

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

/** One pin. x/y are pixels in the BOARD's own space — never a scaled ancestor's. */
export type Pin = {
x: number
y: number
label: string
}

export const codec = defineStateCodec({
// A per-KEY map: two people dropping different pins at once BOTH land.
pins: field.map<Pin>(),
})

const newId = () => crypto.randomUUID()

const onBoardClick = (e: ReactMouseEvent<HTMLDivElement>) => {
  if (!canEdit || e.target !== boardRef.current) return
  const rect = boardRef.current.getBoundingClientRect()
  actions.map("pins").set(newId(), {
    x: e.clientX - rect.left,
    y: e.clientY - rect.top,
    label: "Pin",
  })
}

const beginDrag = (id: string, pin: Pin) => (e: ReactPointerEvent<HTMLDivElement>) => {
  if (!canEdit) return
  e.stopPropagation()
  const rect = boardRef.current?.getBoundingClientRect()
  if (!rect) return
  dragRef.current = { id, dx: e.clientX - rect.left - pin.x, dy: e.clientY - rect.top - pin.y }
  e.currentTarget.setPointerCapture(e.pointerId)
}
const onDrag = (e: ReactPointerEvent<HTMLDivElement>) => {
  const d = dragRef.current
  const pin = d && data.pins[d.id]
  if (!d || !pin) return
  const rect = boardRef.current?.getBoundingClientRect()
  if (!rect) return
  actions.map("pins").set(d.id, {
    ...pin,
    x: e.clientX - rect.left - d.dx,
    y: e.clientY - rect.top - d.dy,
  })
}
const endDrag = () => {
  dragRef.current = null
}

return (
  <div
    ref={boardRef}
    onClick={onBoardClick}
    style={{
      position: "relative",
      height: "100%",
      background:
        "radial-gradient(rgba(127,127,127,0.25) 1px, transparent 1px) 0 0 / 20px 20px",
      cursor: canEdit ? "crosshair" : "default",
    }}
  >
    {pins.map(([id, pin]) => (
      <div
        key={id}
        onPointerDown={beginDrag(id, pin)}
        onPointerMove={onDrag}
        onPointerUp={endDrag}
        style={{
          position: "absolute",
          left: pin.x,
          top: pin.y,
          transform: "translate(-50%, -100%)",
          touchAction: "none",
          cursor: canEdit ? "grab" : "default",
          fontSize: 22,
          lineHeight: 1,
          userSelect: "none",
        }}
      >
        📍
      </div>
    ))}
    {pins.length === 0 && (
      <p
        style={{
          position: "absolute",
          inset: 0,
          display: "grid",
          placeItems: "center",
          margin: 0,
          opacity: 0.5,
          fontSize: 13,
          pointerEvents: "none",
        }}
      >
        Click anywhere to drop a pin
      </p>
    )}
  </div>
)
}

function PinBoard({ document, context }: ToolRenderProps) {
const coords = useMemo(
  () => ({ worldId: document.worldId, documentId: document.id }),
  [document.worldId, document.id],
)
const { data, status, actions, retry } = useDocument(coords, codec)
return (
  <DocumentGate status={status} onRetry={retry}>
    {data && actions ? (
      <Board data={data} actions={actions} canEdit={context.canEdit} />
    ) : null}
  </DocumentGate>
)
}

export default defineTool({
id: "pin-board",
name: "Pin board",
documentTypes: ["pin-board"],
render: PinBoard,
})

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

Running · your edits, live

Starting the example…

Flip the "pretend view" chip to embed. You should see: the header disappears, pins and empty-state text shrink, and the board still takes clicks and drags — because you also set embed: "interactive" on the definition.

Why interactive, not preview

The default (embed: "preview") mounts your embed read-only and pointer-inert, behind a click-to-open affordance — right for a document whose embed is a preview of it, like a mini- map that would otherwise swallow a card's scroll wheel. A pin board is the opposite kind of thing: dropping and dragging pins is the tool, so an inert picture would be a smaller, broken version of it, not a smaller correct one. embed: "interactive" mounts it live, with the viewer's real edit rights, plus one small corner control to open the full view.

What if I want a summary of the board somewhere else entirely?Deep dive

context.view === "embed" is for this document's own inline face — someone drops this exact board into a card. That's different from wanting, say, "boards near this one" shown in world chrome, with no document to point at.

For that you'd ship a second, small defineBlock with scope: "world": it reads the world instead of block.data, and it mounts anywhere with one line, no BlockInstance to supply — <BlockSlot type="pin-board-roster" />. It's a different shape from what this page builds; see World blocks for the whole pattern.

Recap

The host mounts one render in three views; context.view === "embed" is the block-sized one.
embed: "interactive" mounts a control surface live with real edit rights; the default, "preview", mounts a read-only picture behind a click-to-open.
A scope: "world" block, mounted via <BlockSlot>, is the different shape you'd reach for to summarize the board somewhere with no document of its own.

Next steps

Step 5 — Two people at onceThe same board, mounted twice — pins from both sides both land.