SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsprototype-canvas

prototype-canvas

Frontend & websites

View repository

Updated 10-16 07:58

About this skill

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

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.

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.

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.