You are reading Nightly documentation for 0.12.4.dev0+g50bde75.

This documentation may describe behavior that differs from Stable.

Open Stable documentation

Documentation version

0.12.4.dev0+g50bde75 · Nightly
Stable Beta Nightly

Canvas

Canvas

A canvas is a live visual surface the agent renders beside your chat — a dashboard, a comparison table, a status board — that updates in place as the conversation moves, instead of scrolling past as more chat bubbles.

Ask for one in plain language: "make me a status dashboard for the release", "put the pros and cons side by side on a canvas", "track the sprint on a board and keep it updated". The agent creates the canvas with its update_canvas tool and revises it as things change; every revision replaces the whole surface, so what you see is always the current state.

Where canvases appear

  • The canvas panel. The first canvas in a chat opens a panel beside the conversation. When a chat has several canvases, the panel shows them as tabs. The panel announces updates politely to screen readers ("Canvas 'Sprint board' updated") and never steals focus.
  • The header toggle. A panel button appears in the header whenever the chat has canvases — use it to hide or show the panel. Your choice sticks across sessions; a fresh update re-shows the panel without changing the saved preference.
  • The sidebar. Every canvas in the chat is listed under Canvases in the sidebar (next to Artifacts); choosing one opens the panel on that canvas.
  • Its own page. Each canvas has a durable URL (/canvas/<id>, or the Full page link in the panel) that renders it full-width, updates live, and survives across sessions — handy for keeping a dashboard open on a second monitor.
  • Everywhere else. Canvases are part of the canonical event stream, so non-visual surfaces stay informed: the terminal prints a one-line summary (canvas updated: 'Sprint board' revision 3 …) and points at the web UI.

Canvases are saved with their chat. Reopening a chat restores its canvases at their latest revision, and deleting a chat deletes them.

Interacting with a canvas

Canvases can carry buttons and small forms (text fields, dropdowns, checkboxes). Pressing a button or submitting a form sends the interaction back to the agent as a clearly framed message in the conversation — [canvas "Release console"] button "Refresh" pressed — so you always see in the transcript exactly what the canvas told the agent, and the agent responds (usually by updating the canvas).

Two properties keep this safe and predictable:

  • Only you can press the controls — canvas input arrives with the same trust as text you type, nothing more.
  • An interaction is validated against the canvas's current revision. If the agent has since replaced a button, a press from the stale view is refused instead of misfiring, and every interaction is recorded as a canvas_input event in the audit stream.

What a canvas can contain

The agent composes canvases from a fixed catalog of building blocks — headings, text, images it has generated, professional-artifact cards pinned to an exact version, badges, big-number stats, progress meters, lists, data tables, cards, sections, columns, and the buttons and forms described above. An artifact card can show one validated preview and an exact-version download without embedding the document binary in the canvas. See Professional artifacts. By default the agent does not write raw HTML or scripts: each block is rendered by the app's own accessible components, so every canvas follows your theme (light/dark), works with screen readers, and can't run code.

That catalog design is deliberate. Labels, image alt text, and table captions are required by validation — a canvas that would be meaningless to a screen-reader user is rejected before it renders, and the agent gets an error telling it exactly what to fix.

The HTML escape hatch

For visuals the catalog genuinely can't express — a custom diagram, an animation — the agent can embed a small HTML island. Islands are deliberately confined:

  • Each island renders in a sandboxed frame with no access to the app: it can't touch the page, your storage, or your session, and a strict policy removes the network entirely, so an island is a self-contained visual with no way to send data anywhere.
  • Islands are display-only — buttons and forms stay in the accessible catalog, so everything interactive remains screen-reader-native.
  • Every island requires a real written summary (validated for substance, not just presence). Screen readers announce the summary as the island's name, so the visual is never a black hole non-visually.
  • Islands are rationed (a few per canvas, with a size cap), and the agent is explicitly instructed to treat them as a last resort — if a catalog block can carry the content, the catalog wins.

Accessibility

The canvas panel is a labeled region with a coherent heading structure, updates are announced through a polite live region, tables carry captions and proper headers, progress meters expose their values to assistive tech, and the tab strip is fully keyboard-navigable. If you use a screen reader, a canvas reads as a well-structured document, not a picture of one.

Current limits

  • Canvases exist in web chats (and the desktop app); terminal sessions summarize canvas updates but don't render them.
  • There is no chart block yet — for now the agent expresses numbers with stats, progress meters, and tables.
← Previous Browser agent Next → Holaryn Agent capability matrix