create-canvas-app

Create Canvas App

A batteries-included way to build Copilot App canvas extensions. It exists because hand-rolled canvases keep hitting the same walls: an innerHTML repaint loop that eats keystrokes, state that lives only in one panel, ad-hoc styling that ignores the host theme, and inconsistent icons. The kit fixes all four.

What a canvas is (and when to build one)

A canvas is an interactive surface the agent opens in a side panel via open_canvas. Both the agent and the user act on the same state through the same action handlers. Reach for a canvas when chat text or a diff isn't enough: live dashboards, editors, spreadsheets, trackers, kanban/board views, document previews, tool-specific workflows.

If the user just needs a non-visual agent tool, build a normal extension tool instead — not a canvas.

Rendering tier — decide first

Tier	Use when	How
Static HTML string	Read-only or near-static content; no inputs to protect	The runtime's vanilla scaffold (extensions_manage scaffold kind:canvas).
Preact + htm + this kit	Anything interactive: inputs, live updates, lists, forms, shared state	This kit. Default choice for real canvases.

The single most important reason to use the kit: Preact diffs the DOM, so a live state push from the agent does not clobber focus, caret position, or half-typed text in an input. The innerHTML = ... pattern most early canvases use repaints the whole tree and loses keystrokes on every push. Don't do that.

The model (read this before coding)

extension.mjs   ── the ONLY file that imports the Copilot SDK (thin adapter; also wires host AI)
canvas.mjs      ── your canvas: id, schema, state load/save, action handlers (SDK-free)
canvas-kit/     ── the kit (copied in verbatim; do not edit)
web/index.html  ── shell: loads /kit/theme.css and ./app.mjs
web/app.mjs     ── your Preact view

• State is shared and durable. It's keyed by a domain id resolved from the open input (resolveDomainId), not by instanceId — open the same domain in two panels and they show the same data. Persistence goes through userStore(extName, file) → $COPILOT_HOME/extensions/<name>/artifacts/<domain>.json. Two more tiers exist in kit/storage.mjs for non-durable/scoped state: sessionStore(sessionId, extName, file) (per-session scratch, discarded with the session) and workspaceStore(workspacePath, file) (rooted at the session workspace). All three write atomically (temp + rename) and serialize concurrent saves to the same file, so a racing agent + UI save can't corrupt or EPERM the durable file.
• Shared, multiplayer state (optional). For a board multiple people edit, swap the local tier for githubStore({ owner, repo, path }) from kit/github-store.mjs: it persists the same JSON to a file in a (private) repo via the GitHub Contents API, so every collaborator with push access edits ONE document — GitHub is both the store and the access control. Wire it as loadState/saveState, and add syncState: () => store.poll() + syncIntervalMs so the runtime polls for other people's edits (cheap ETag 304 when unchanged) and adopts them live — but only while a panel is being viewed. Writes are optimistic-locked by blob SHA (a conflicting commit re-reads + retries; last-writer-wins by default, or pass a merge(remote, mine)). Token comes from GH_TOKEN/GITHUB_TOKEN or gh auth token and is only ever sent as an Authorization header.
• Agent and UI share handlers. An action invoked by the agent and the same action invoked from a button run the identical handler and produce the identical state mutation. Write the logic once, in canvas.mjs.
• Live updates are automatic. The kit serves GET /state, GET /events (SSE), and POST /action. mountCanvas wires them up; every state change fans out to all open panels.
• server.mjs is SDK-free so the whole runtime is testable with plain Node HTTP (see test/http.test.mjs). Keep SDK calls in extension.mjs only.