Canvas

A node editor composed from UI SDK's canvas behaviors: createViewport pans and zooms, createMove drags nodes, createSelection and createLasso choose them, spatialMove sends focus to the nearest node, and createConnect draws wires. People use a pointer or the keyboard; agents use the same actions by the names people see.

Parts

Use

const [canvas] = useState(createCanvasController)
const history = useCanvasHistory({ nodes, edges })
const [selected, setSelected] = useState<string[]>([])

<CanvasToolbar canvas={canvas} kinds={kinds} selectedCount={selected.length}
  onUndo={history.undo} onRedo={history.redo} canUndo={history.canUndo} canRedo={history.canRedo} />
<Canvas
  label="Workflow"
  controller={canvas}
  nodes={history.nodes}
  edges={history.edges}
  onNodesChange={history.onNodesChange}
  onEdgesChange={history.onEdgesChange}
  selected={selected}
  onSelectedChange={setSelected}
  kinds={kinds}
  onAddNode={(kind, at, title) => ({ id: crypto.randomUUID(), kind, title: title ?? "New step", ...at, ...portsFor(kind) })}
  renderNode={(node) => node.data?.summary}
  onUndo={history.undo}
  onRedo={history.redo}
  fitView
/>
<CanvasInspector node={one(selected)} nodes={history.nodes} edges={history.edges} canvas={canvas}
  onRename={rename}>{(node) => <YourFields node={node} />}</CanvasInspector>

• A node is { id, title, x, y, inputs?, outputs?, kind?, color?, width?, data? }; a port is { id, label }. Ids may not contain :.
• An edge is { id, from, to }, with ports keyed "node:out:port" and "node:in:port". Wires run from an output to an input on another node; each input takes one wire, and a new one replaces it. canConnect(from, to) adds your own rules, like matching types.
• Nodes, edges and the selection are controlled or not (defaultNodes, defaultEdges, defaultSelected). Removing nodes removes their wires.
• renderNode draws under a node's ports, as text or pictures: node faces aren't interactive, so the nodes can be a listbox. Its text is part of the node's description. Put fields in the inspector: its children start over for each node shown.
• A node is named by its title, then its kind, as it reads on screen; its description adds the body and its wires.
• CanvasToolbar's label is its own name, "Canvas tools" by default. Keep the canvas's name out of it: agents find components by names that contain what they ask for.
• grid is where dropped nodes snap and how far Alt with an arrow moves them (8).
• locked(node) keeps a node in place. fitView frames every node on first show; controls and minimap turn the corner parts off.
• Ports are drawn from fixed sizes (a 36px header and 28px rows, in canvas units), so wires never wait on measuring. Keep custom styles to those sizes.

Keys

Focus never falls to the page: removing a node (by Delete, the toolbar, an undo or an agent) moves it to the nearest node, the toolbar keeps disabled tools focusable, and Disconnect in the inspector moves to the next wire. A node added from the toolbar takes focus; one an agent adds doesn't take it from the person. Focus rings and the selection edge keep their width on screen at any zoom.

With a pointer: drag empty space to pan, scroll or pinch to zoom, Shift-drag to select a box, drag a node (or the selection) to move it, drag from an output dot to an input to wire them, and press a wire's × to remove it. The minimap pans where you press. Every move, wire and removal is announced, and each node's description says what it's wired to ("Inputs: Prompt from Answer template Prompt.").

For agents

addNode(kind, title?, x?, y?), moveNode(node, x, y), connect(from, to, fromPort?, toPort?), disconnect(from, to), select(...nodes), openNode(node) and fitView(), by titles (or ids, when two share a title). A wire that isn't allowed, an unknown kind or port, or a locked node says why. query({ within: "Workflow" }) lists each node as { value: id, label: "Draft answer (at 600, 130; Inputs: …; Outputs: …)" }. Removing goes through the toolbar's Remove button, marked data-agent-confirm, so a person approves it.

Known limits

Find in page doesn't reveal nodes off screen yet (UI SDK's bindFindable can add it). Very large graphs (thousands of nodes) render every node; virtualizing them is future work.