---
name: html-visuals
description: How to build a self-contained HTML visual for the session canvas or the portal viewer — the sandbox contract, responsive rules, and the chart/dashboard idioms that survive it.
---
# HTML Visuals
When the user wants to *see* something — a chart, a dashboard, a graph, a
comparison, a timeline, "show me", "visualize this" — build a single
self-contained HTML page. This skill is about the PAGE; where it goes is
decided once, per visual:
- **Root session → the canvas.** `draw_canvas(html, note)` puts it on the
user's screen live. No artifact, no `show_artifact`, no links — the canvas
updating IS the delivery, and iterating means redrawing it.
- **A keepable file, or no canvas (sub-agents)** → write it as an artifact and
open the reader:
write_artifact(filename="outage-graph.html", content="…")
show_artifact(filename="outage-graph.html")
Include the returned `artifact://` link in your reply in this case only —
the live push lands if someone is watching; the link works forever.
Never send the same visual to both surfaces; one request, one destination.
## Forms: batch the input
Use this whenever you draw a canvas whose job is to COLLECT input: a release
sign-off, a settings sheet, a triage checklist, a survey. The cardinal rule:
**The page is the scratchpad; you are the database. One user intent = one
action.** A 23-item checklist is NOT 23 canvas actions — the user checks,
unchecks, writes comments, changes their mind, and everything stays in page
state. You hear about it exactly once, when they hit Submit.
## The contract shape
Declare one submit action carrying a single `json` field (the whole form
state), plus at most a couple of coarse verbs:
draw_canvas(html=..., note="release sign-off",
responseContract={"actions": {
"submit": {"decision": "string", "form": "json"},
}})
`json` fields carry one structured object (bounded at 8 KB serialized — a
checklist of dozens of items with comments fits comfortably; do not ship
essays through it).
## The page pattern
- Keep ALL form state in a plain JS object; every checkbox/input writes to it
locally. Nothing posts until submit.
- Submit gathers and posts once:
function submit(decision) {
parent.postMessage({ type: "canvas-action", action: "submit",
data: { decision, form: { rev: FORM_REV, items: state.items } } }, "*");
lockForm("Submitted — waiting for confirmation…");
}
- **Bake a form revision in.** Set `FORM_REV` to the canvas rev you drew (you
know it from the draw result) and include it in the payload — if you have
redrawn since, a submit carrying an older rev tells you the user answered a
stale form; say so and redraw the current one.
- **Lock on submit** (disable inputs, show a submitted banner). Your
confirmation is the next redraw; the lock is what stops double-submits and
makes the seconds of latency legible.
- GO/NO-GO style decisions are two buttons calling the same submit with a
different `decision` — not two actions.
- On receipt, REDRAW showing what you recorded (received N items, decision,
the follow-ups you are taking). The redraw is the acknowledgement.
## What NOT to do
- No per-keystroke, per-checkbox, or per-row actions. If you feel the urge to
know intermediate state, you have designed the form wrong.
- No timers or auto-submit — a form posts on an explicit user gesture only.
- Do not redraw while the form is live except in response to a submit; a
redraw replaces the document and wipes everything typed so far.
- Do not block the session on the form: keep working where possible, and note
in chat that the canvas is waiting whenever the user may not be looking.
Hard approval gates stay on `ask_user`.
## Sharing caveat
Only a viewer with session WRITE access (the creator, and anyone the session is write-shared with) can post canvas actions — read-only viewers see the
form, but their clicks are refused by the platform (their view of a mutating
canvas may be stale). If the session is shared, say in the page footer who
the form is addressed to, and let others respond in chat.
## Live data updates (update_canvas)
When the canvas's CONTENT changes but its layout does not — dashboards,
tickers, watchers — draw the shell ONCE, then tick with
`update_canvas(data={...})`. The tick reaches the page as a message; the
platform replays the latest tick into any freshly loaded page, so one
idempotent renderer covers live updates and cold loads alike:
addEventListener("message", (e) => {
if (e.data?.type === "canvas-data") applyData(e.data.data);
});
function applyData(d) { /* render the WHOLE state from d */ }
- Declare `data: { example: {...} }` in the draw contract; after a memory
gap, re-read it before ticking so your payload shape never drifts.
- Ticks never flip the view and write no chat line; they light the unseen
badge until the user looks. Cap: 32 KB for the MERGED state.
- Layout change → `draw_canvas`. Content change → `update_canvas`. Never
redraw to refresh numbers.
### Patch, don't re-send (update_canvas patch)
`data` REPLACES the whole state — use it for the first tick after a draw
and for wholesale refreshes. For every incremental change, send a PATCH:
update_canvas(patch={ gauges: { cpu: 91 } }) // a few tokens
update_canvas(data={ ...entire dashboard... }) // thousands — avoid
Patch rules (RFC 7386 merge patch, applied server-side):
- Send ONLY the subtree you are changing. Objects deep-merge into the
current state; arrays and scalars replace wholesale.
- `null` DELETES a key. Omit keys you are not touching — null is deletion,
not "no change".
- Your page keeps working unchanged: `canvas-data` messages always carry
the complete merged state. A page that wants the delta too (targeted DOM
updates, transitions) may ALSO listen for `canvas-patch` messages
(`{type:'canvas-patch', patch, dataRev}`) — the whole-state message
still arrives alongside, so the fancy path can never strand the page.
- Lost track of the current state (restart, another writer)? Resync with
`read_canvas(include_data=true)` and go back to patching.
### Shared dashboards (sub-agents writing the parent's canvas)
Every canvas tool takes `session_id` targeting an ANCESTOR session —
parent, grandparent, root; never siblings or strangers. The pattern for a
parent with N children keeping one dashboard live:
1. Parent draws the shell once with a `tiles` region per child.
2. Each child patches ITS OWN subtree of the parent's canvas:
`update_canvas(session_id=, patch={ tiles: { worker3: {...} } })`.
Disjoint subtrees compose automatically — children cannot clobber each
other. Same-path writes are last-writer-wins, attributed.
3. A child's write never flips the parent's view; the unseen badge and the
activity feed carry who wrote what.
## Interactive canvases
A canvas can accept structured responses while a user views it live. Declare
the contract on the draw, then wire controls to `parent.postMessage`:
draw_canvas(html=..., note="order form",
responseContract={"actions": {"submit": {"qty": "number", "note": "string?"}}})
Rules that make this work:
- The browser enforces YOUR contract: undeclared actions, wrong types, and
extra fields are dropped before they reach you. No contract on the current
revision means nothing is accepted — a display-only canvas stays inert.
- Responses arrive as `[canvas-action] {"action":...,"data":...}` user
messages, hidden from the portal chat. Answer by REDRAWING with the result
baked in — the canvas is both the form and the reply.
- Echo input optimistically in the page (append the row, disable the button);
your redraw arrives seconds later and replaces the document.
- The sandbox has no `allow-forms`: wire click/keydown handlers, never rely on
real form submission. Enter-to-submit = a keydown listener on the input.
- **Text inputs: `font-size: 16px` minimum.** iOS Safari zooms the whole
viewport when a smaller input is focused and never zooms back — the page
comes out cropped and panned after every comment box.
- A page taller than the viewport scrolls in the browser's own scroller —
set nothing that traps it (`overflow: hidden` on body kills mobile scroll;
`touch-action` overrides eat pans). Let the default body scroll work.
- Do not redraw a canvas that carries input fields except in response to an
action — a spontaneous redraw wipes drafts mid-typing.
- Controls only function while someone is watching the portal. Never block on
a canvas click; chat is the fallback and approval gates stay on ask_user.
Prefer this over pasting a Markdown table when the answer is *shape* —
proportion, trend, flow, overlap, ranking across many rows. Prefer a Markdown
table when the answer is a handful of exact values. A table of 8 numbers does
not need a chart; 200 rows of "who is waiting on what" does.
## The sandbox contract
The page runs in an iframe with `allow-scripts` and **no** `allow-same-origin`.
Your script runs; it just has no world outside the document. Violating any of
these produces a blank or broken page, not an error message:
1. **Self-contained. No network of any kind.** No CDN `