---
name: prototype-canvas
description: Start and operate the local tldraw design canvas that shows HTML artboards. Start the canvas app against a project's board folders, add or switch boards, drive shapes through the bounded window.snapCanvas bridge, and act on annotated screenshots of the canvas. Use when asked to open/launch the canvas, put a mockup on the canvas, annotate or draw on it, fix overlapping frames after a layout.json edit, or respond to a screenshot of the canvas with notes drawn on it.
license: Apache-2.0
compatibility: Requires the sp command from super-prototyping-tools, node or bun to run the canvas, and network access on first start to fetch it. A modern browser to view the canvas.
---

# Prototype canvas

A local tldraw app that discovers every `.html` file under
`mockups/canvases/<slug>/` and renders it as a shape. There is no shape map
to edit and no code change needed to add a board.

The app ships with this plugin and is installed outside your project. Your
boards stay in your project. `sp` joins the two, so upgrading the
plugin replaces the app and never touches a board you wrote.

## Start

```bash
sp start
```

Inside the Super Prototyping app, the canvas is already serving on
127.0.0.1:5173. `sp start` is for a terminal that does not have the app
open, and it refuses a port that already answers rather than reusing it.

From elsewhere, name the project: `sp start <dir>`. Not on PATH, or
`sp --version` prints something lower than the version this skill shipped
with? `sp` installs separately from the plugin, which cannot run an installer
of its own: `uv tool install
"git+https://github.com/ReScienceLab/super-prototyping#subdirectory=tools"`,
adding `--force` to reinstall over a lower version. Leave a higher version
alone, because reinstalling over it would be a downgrade, and the tag may not
even exist.

That is the whole thing. On first run it fetches the canvas app built for
its version into `~/.cache/super-prototyping/<version>/`, then serves it on
127.0.0.1:5173 with node or bun, waits for the port to actually bind, and
prints the address. Started from a terminal it also opens the browser; from
an agent's shell it only prints. A checkout being worked on serves its own
`canvas/dist` instead, rebuilt with bun when a source is newer.

- **Boards** default to `mockups/canvases` under the project: the directory
  named on `sp start <dir>`, else the current one.
  Point somewhere else with `--canvases DIR` or `PROTOTYPING_CANVASES_DIR`.
- **Port** with `--port N`, or `SP_CANVAS_PORT` for a machine that always
  uses another one. A port that already answers is never reused: it may be
  another project's canvas, so `start` refuses rather than showing you the
  wrong boards.
- **Two projects can run two canvases.** Everything is keyed by port — the
  session name, the log, the pidfile — so a second `start` on a free port
  leaves the first one alone. `stop` and `status` take `--port` for the same
  reason, and `stop` only ever kills the canvas it started.
- `sp root` prints which copy of the plugin it found — and with `-v`,
  everywhere it looked. The first thing to run when the canvas is not what
  you expected.
- **It writes two directories and nothing else**: that cache, and
  `~/.local/state/super-prototyping/` for its pidfile and log, the same on
  macOS as on Linux.
  `SUPER_PROTOTYPING_HOME` moves both under one root. `sp paths`
  prints them and every variable in use; `sp clean` removes them.
- Deep-link a page with `?canvas=<slug>`, e.g.
  `http://127.0.0.1:5173/?canvas=notion-ios`, and one board of it with
  `#<file>` after that, e.g. `?canvas=notion-ios#02-search-ask-ai`: it opens
  in the inspector with the camera on it. Give the board link when pointing
  at one screen.
- **Read a board as a web page.** The "Export to Figma" button in the top bar
  opens every board of the page in one scrolling document, each at its own
  size, at `sheet.html?canvas=<slug>`; the button in the bottom right of the
  inspector's preview opens the one board it is showing, at
  `/board/<slug>/<file>.html`. Both are ordinary addresses serving the board's
  own HTML, so they can be linked, reloaded, and read by the browser
  extensions — a Figma importer, say — that refuse to work on a generated
  page. This is where to read type at the size it ships at, rather than at
  whatever the canvas is zoomed to. The sheet opens on what to do with it: the
  html.to.design browser extension, which captures a localhost page that the
  Figma plugin's own servers cannot reach, and the paste or plugin route from
  there into a file.

Keep it on loopback. This is a local design tool, not a service to expose.

A project with no boards yet opens on a notice naming the directory the
canvas resolved, rather than an empty grid: an empty boards folder and a canvas
pointed at the wrong one look identical otherwise.

**A folder created after boot appears on its own.** The server watches the
boards directory and rebuilds its index when a board folder or file is added
or removed. Rewriting a board reloads the page onto the new version, so a
generator can be re-run with the canvas open. If a `?canvas=<slug>` link still
matches no page, the folder has no `.html` file in it yet — an empty folder is
not a board.

The styles panel is hidden by default; toggle it from the toolbar. Always-snap
is on by default. The setting is per browser, so turning it off in tldraw's
preferences menu sticks.

## Boards

One folder under the boards directory = one tldraw page; one `.html` file =
one shape. Switch with the page menu at the top-left; do not build a separate
switcher. `references/layout.md` has the `layout.json` schema, the caption
rules, and the 478 × 980 / sandbox constraints every artboard lives under.

**After editing `layout.json`, right-click the canvas and choose Force
refresh.** Shape creation is idempotent. It fills in what is missing but never
moves a shape that already exists, so inserting or reordering a row entry
leaves the old shape at its old position, overlapping the new one. Force
refresh deletes every `canvas-file` / `canvas-row-heading` /
`canvas-file-label` shape on all pages and rebuilds them from the current
files. Content-only edits to a placed file do **not**
need it: the server reloads the canvas onto the rewritten board.

## Drive the canvas

Prefer the bounded `window.snapCanvas` bridge over mouse-coordinate
automation or exposing tldraw's full `Editor`.

```js
window.snapCanvas.describe()
window.snapCanvas.dispatch({ op: 'get' })
window.snapCanvas.dispatch({ op: 'create', shapes: [{
  type: 'text', x: 80, y: 80,
  props: { richText: { type: 'doc', content: [
    { type: 'paragraph', content: [{ type: 'text', text: 'Note' }] }] } },
}]})
window.snapCanvas.dispatch({ op: 'select', ids: ['shape:example'] })
window.snapCanvas.dispatch({ op: 'zoom',   ids: ['shape:example'] })
window.snapCanvas.dispatch({ op: 'undo' })
```

Call `describe()` before generating commands, and use the ids and bounds that
`get` returns. Never guess screen coordinates. Batch related shape changes
into one dispatch.

Never let bridge commands inject arbitrary JavaScript, never load untrusted
HTML into a board, and never add `allow-same-origin` to the artboard iframe.

## Annotated screenshots

The review loop is a screenshot of the canvas with notes drawn on it, pasted
into chat. Boxes, arrows or numbers all work, from tldraw's own draw/text
tools or any image annotator.

1. Treat each annotation as an exact visual target, and say back what you read
   it as ("box 2: tighten the card gap") before touching anything.
2. Read the surrounding UI and the HTML source before editing.
3. Make the smallest source change that satisfies it.
4. Let the canvas reload, then verify the same region visually.

Do not build an annotation-to-agent protocol. The screenshot is the bridge.

## The chat panel

The canvas has a panel on the left when it runs from `sp start`: a
message to Claude Code or Codex — the mark on the header picks — run in the
project, Claude with its permission prompts off and Codex in its workspace
sandbox, and what it did as it happens. The panel names the canvas that is
open and tells the agent, and points the agent at this skill before it
touches a board folder. A
board it rewrites reloads the canvas as any rewrite does; the panel keeps its
runs across the reload, and its history button lists the runs the server
still holds.

Each message is a fresh `claude -p` or `codex exec` with no memory of the
last, so repeat what matters. A server started by hand needs `PROTOTYPING_PROJECT_DIR` set to the
project, or the panel says it cannot run; `sp start` sets it.

## State and persistence

The document lives in the browser's IndexedDB under `PERSISTENCE_KEY` in the
app's `src/App.tsx`. A board's identity is its path key, so renaming a folder
or a file orphans that board's shapes; Force refresh rebuilds them.
Ordinary layout drift is what refresh is for, not a persistence-key bump.

## Working on the canvas app itself

Only when changing the app, not when using it. `sp root` prints the
checkout to work in.

```bash
cd "$(sp root)/canvas"
bun run lint && bun run test && bun run build
```

Then, in a fresh browser session: each board page loads with its frames,
headings and captions; the frames stay independently selectable; the inspector
opens on the board you click; Force refresh rebuilds a board cleanly.

Everything the canvas needs a server for lives in `canvas/server/`: `sp.ts`
answers `/__sp` and `/board`, the Vite dev server mounts it for working on the
app, and `main.ts` mounts it in front of `dist` as the server `sp start`
runs. Board discovery is `boards.ts`, served as `/__sp/index.json` and fetched
by the page before it loads, not an `import.meta.glob`. Bump
`PERSISTENCE_KEY` **only** when a change would leave existing documents
inconsistent with the code, such as a shape's props changing shape; a bump
discards every persisted hand-drawn annotation.