pmx-canvas 0.6.4 → 0.6.5

package/docs/http-api.md

@@ -9,6 +9,40 @@ bodies are treated as an empty request. As of 0.4.0 every error response is a
 JSON envelope of that same shape (`{ ok: false, error }`, status unchanged) —
 no plain-text errors remain.
 
+Node-create responses include `sizeAdjustment` when a frame dimension was
+defaulted or raised to its node type's readability floor. It contains the
+`requested` dimensions (`null` when omitted), the final `applied` dimensions,
+and a `reason` (`defaulted`, `clamped-to-minimum`, or
+`defaulted-and-clamped-to-minimum`; groups also use `fit-to-children`). `strictSize: true`
+still bypasses the readability clamp, but omitted dimensions are reported as
+defaulted. MCP create actions return the same size report.
+Updates preserve explicit dimensions without applying creation floors; their
+returned node `size` is the applied size. Omitted update dimensions retain the
+existing size and are not reported as defaulted adjustments.
+
+Both group-create routes report defaults or final child-derived dimensions, including
+when children override supplied width/height because x/y were omitted. Explicit manual
+frames retain their existing semantics. Group child replacement reports `fit-to-children`
+when it changes the frame; `group.add` reports the previous frame as `requested` and
+the final frame as `applied`. Reports survive compact/full MCP and batch responses.
+External MCP app creation and web-artifact builds that open a node report their default
+frames too; reusing an existing app node or building without opening does not report a
+creation default. These reports describe the synchronous operation, not later browser
+content auto-height or indirect parent-group reflow after editing a child.
+
+## Board tours
+
+- `GET /api/canvas/tour` → `{ tour: { stops: [...] }, derived: boolean }`.
+- `POST /api/canvas/tour` with `{ "tour": { "stops": [...] } }` persists the tour;
+  `{ "tour": null }` resets to derived group reading order. Returns `{ "ok": true }`.
+- `GET /api/canvas/state` includes optional `tour`. Tour writes broadcast a layout
+  update and are included in snapshots/undo. They are board-wide writes under a scope fence.
+
+The [tour model and recording walkthrough](cli.md#tour-and-presentation) describes
+targets, duration, easing, padding, and pullback. Open `/workbench?present=1` to hide
+chrome; camera movement is local to that viewer. Recording writes local files via
+the CLI, not an HTTP job endpoint.
+
 ## Canvas state
 
 ```bash
@@ -35,6 +69,10 @@ curl -X POST http://localhost:4313/api/canvas/json-render \
   -H "Content-Type: application/json" \
   -d '{"title":"Panel","nodeHeight":280,"spec":{"root":"card","elements":{"card":{"type":"Card","props":{"title":"Live"},"children":[]}}}}'
 
+# For graph nodes, `height` is the chart's plot height, not the node frame.
+# Set the frame with `nodeHeight` (`heightPx` in the SDK). A graph request that
+# supplies only `height` gets the default frame height and a response warning.
+
 # Validate an HTML primitive without creating a node
 curl -X POST http://localhost:4313/api/canvas/schema/validate \
   -H "Content-Type: application/json" \
@@ -70,6 +108,11 @@ A node creation request must resolve a `type` — pass it in the body (`{ "type"
 ... }`) or as a `?type=` query param. An empty / type-less body returns `400`
 rather than silently creating a markdown node.
 
+Mermaid nodes accept `data: { "fit": "contain" | "none" }` on both
+`POST /api/canvas/node` and `PATCH /api/canvas/node/:id`. The default, `contain`,
+shrinks overflowing diagrams without changing aspect ratio; `none` keeps 100%
+with scrolling. [Mermaid sizing and readability](node-types.md#mermaid-nodes).
+
 ### File node content and bytes
 
 A `file` node reads its file server-side. Text is stored on the node as
@@ -145,6 +188,31 @@ curl -X DELETE http://localhost:4313/api/canvas/annotation/ann-123
 Agent-readable context reports annotation IDs, targets, and bounds. Use WebView
 inspection or screenshots when the drawn shape matters.
 
+## Viewport
+
+```bash
+# Set the camera transform (screen = world * scale + {x,y})
+curl -X POST http://localhost:4313/api/canvas/viewport \
+  -H "Content-Type: application/json" \
+  -d '{"x":64,"y":96,"scale":0.8}'
+
+# Fit selected nodes (omit nodeIds to fit the whole canvas)
+curl -X POST http://localhost:4313/api/canvas/fit \
+  -H "Content-Type: application/json" \
+  -d '{"nodeIds":["node-1"],"width":1200,"height":700}'
+
+# Focus without moving the camera
+curl -X POST http://localhost:4313/api/canvas/focus \
+  -H "Content-Type: application/json" \
+  -d '{"id":"node-1","noPan":true}'
+```
+
+Viewport `x`/`y`, fit `width`/`height`, and fit padding are interpreted against
+the **canvas area**, excluding the tool rail, top bar, and other surrounding
+page chrome—not the full browser window. Camera, fit, and focus-only requests
+do not create or refresh agent writer presence. Use the explicit presence API
+when an agent should publish a cursor or `focusNodeId`.
+
 ## Pins
 
 ```bash
@@ -341,13 +409,20 @@ When that session ends (`attached: false`, `session-end`, or the idle expiry)
 the stream carries one `agent-session-ended` frame:
 
 ```json
-{ "label": "Copilot", "endedAt": "…", "counts": { "items": 4, "done": 3, "vetoed": 1 },
+{ "label": "Copilot", "parentAgentId": null, "endedAt": "…", "endedBy": "agent",
+  "unchanged": false, "counts": { "items": 4, "done": 3, "cancelled": 1, "rejected": 0, "held": 0 },
   "snapshot": { "id": "…", "name": "Before session · Copilot · 14:00" } }
 ```
 
-`items`/`done` count the work items on the board; `vetoed` counts cancelled
-items plus rejected or held gates. `snapshot` is null when the board was
-empty at attach. The browser renders this as the session receipt; its *View
+`items`/`done` count the work items on the board; cancelled items, rejected
+gates, and held gates have separate counts. `snapshot` is null when the board was
+empty at attach or unchanged at end (the redundant snapshot is removed).
+The browser shows a receipt only for a changed top-level session: `unchanged: true`
+and worker endings (`parentAgentId` set) never open or replace a popup. An empty
+board that stays empty is unchanged too. This only filters the popup: session-end
+events, timeline records, and changed-session snapshots remain available.
+There is at most one receipt, replaced by the next qualifying ending and kept until
+dismissed so restore/diff actions do not disappear on a timer. Its *View
 diff* is `GET /api/canvas/snapshots/<id>/diff` against that snapshot, and
 restoring the snapshot undoes the session. Adapters should end their session
 explicitly so the human gets the receipt promptly rather than after the idle

package/docs/mcp.md

@@ -13,6 +13,15 @@ nodes in the browser, agents are notified immediately.
 > snapshot standalones — each step per [`api-stability.md`](api-stability.md)'s
 > deprecate-one-minor-before-removal rule. **Prefer the composites.**
 
+## Board tours
+
+`canvas_view { action: "get-tour" }` returns `{ tour, derived }`, using group
+reading order when there is no saved tour. `canvas_view { action: "set-tour",
+tour: { stops: [...] } }` persists an ordered tour; `tour: null` resets it.
+See the [tour model and CLI walkthrough](cli.md#tour-and-presentation) for stop
+fields. Recording is a local CLI operation; no remote recording/file-writing
+tool is added.
+
 ## Connect
 
 Add to your agent's MCP config:
@@ -42,7 +51,7 @@ its `action` to the same operation the legacy tool used, so results are identica
 | `canvas_edge` | `add` · `update` · `remove` | `canvas_add_edge`, `canvas_update_edge`, `canvas_remove_edge` |
 | `canvas_group` | `create` · `add` · `ungroup` | `canvas_create_group`, `canvas_group_nodes`, `canvas_ungroup` |
 | `canvas_history` | `undo` · `redo` | `canvas_undo`, `canvas_redo` |
-| `canvas_view` | `arrange` · `focus` · `fit` · `clear` · `remove-annotation` | `canvas_arrange`, `canvas_focus_node`, `canvas_fit_view`, `canvas_clear`, `canvas_remove_annotation` |
+| `canvas_view` | `arrange` · `focus` · `fit` · `clear` · `remove-annotation` · `get-tour` · `set-tour` | `canvas_arrange`, `canvas_focus_node`, `canvas_fit_view`, `canvas_clear`, `canvas_remove_annotation` |
 | `canvas_query` | `search` · `layout` · `validate` | `canvas_search`, `canvas_get_layout`, `canvas_validate` |
 | `canvas_webview` | `status` · `start` · `stop` · `resize` · `evaluate` | `canvas_webview_status`, `canvas_webview_start`, `canvas_webview_stop`, `canvas_resize`, `canvas_evaluate` |
 | `canvas_app` | `open-mcp-app` · `diagram` · `build-artifact` | `canvas_open_mcp_app`, `canvas_add_diagram`, `canvas_build_web_artifact` |
@@ -54,6 +63,11 @@ its `action` to the same operation the legacy tool used, so results are identica
 | `canvas_intent` | `signal` · `update` · `clear` | _(new — Ghost Cursor of Intent; no legacy standalone tool)_ |
 | `canvas_snapshot` | `save` · `list` · `restore` · `delete` · `gc` · `diff` | `canvas_snapshot` (legacy save tool), `canvas_list_snapshots`, `canvas_restore`, `canvas_delete_snapshot`, `canvas_gc_snapshots`, `canvas_diff` — removed in v0.4.0 after one deprecated minor |
 
+For Mermaid nodes, `canvas_node` actions `add` and `update` accept
+`data: { fit: "contain" | "none" }`. Contain is the default, shrinking overflow
+uniformly; none keeps 100% with scrolling. Use Open as site for 100% without
+changing the node setting. [Sizing and readability](node-types.md#mermaid-nodes).
+
 ### `canvas_intent` — Ghost Cursor of Intent
 
 Announce the spatial move you are **about** to make so the canvas paints a faint
@@ -92,6 +106,16 @@ fixing `node.update`'s `formatResult` to surface a FAILED refresh as `isError` +
 fold completed in v0.4.0: `canvas_snapshot { action: "save" | "list" | "restore" |
 "delete" | "gc" | "diff" }` replaced the 6 deprecated snapshot standalones.
 
+### Viewport coordinates
+
+`canvas_view { action: "focus" | "fit" }` controls the camera without counting
+as a writer operation or refreshing agent presence. Viewport translation uses
+screen-space canvas-area coordinates (`screen = world * scale + viewport`). Fit
+dimensions and padding likewise refer to the canvas area after excluding the
+tool rail, top bar, and surrounding page chrome—not the full browser window.
+Use `canvas_ax_state { action: "set-presence", cursor, focusNodeId }` when the
+agent intends to publish its own cursor or attention target.
+
 ## Standalone tools
 
 6 tools that intentionally stay outside the composites — folding them would

package/docs/node-types.md

@@ -26,6 +26,17 @@ see [MCP tools](mcp.md), [HTTP API](http-api.md), and [SDK](sdk.md).
 | `web-artifact` | Bundled React/Tailwind artifact (full single-file app) |
 | `group` | Spatial container/frame around other nodes |
 
+Creation applies per-type frame defaults and readability minimums. When a
+dimension is defaulted or clamped, HTTP and MCP create responses include a
+`sizeAdjustment` with requested and applied dimensions plus the reason.
+`strictSize: true` bypasses minimum-size clamping; it does not change defaults
+for omitted dimensions.
+
+For `graph` nodes, `height` controls the chart plot inside the viewer.
+`nodeHeight` controls the canvas node frame (`heightPx` is the SDK alias). If
+only `height` is supplied, the frame keeps its default height and the create
+response warns about the distinction.
+
 Thread node types `prompt` and `response` exist internally for agent
 conversation rendering and are not created through public APIs.
 
@@ -64,6 +75,34 @@ different type by extension:
 - **Text files over 2 MB** render truncated with a banner saying so, so a huge
   log can never exhaust memory.
 
+## Mermaid nodes
+
+Mermaid diagrams default to `data.fit: "contain"`: when the diagram overflows
+the available body, it shrinks uniformly until the entire diagram fits. Small
+diagrams stay at 100%; aspect ratio, labels, and edges are preserved, in both
+dark and light themes. Resizing a card or expanding it recalculates the fit.
+`strictSize` keeps the requested node geometry while the diagram fits inside it;
+ordinary cards retain their grow-only automatic sizing.
+
+Fitting a large diagram makes its text smaller. Use **Expand** for more space,
+or **Open as site** for a 100% natural-size diagram with scrolling. Set
+`data.fit: "none"` to use that natural-size, scrollable view inside the card too.
+This setting is independent of the canvas camera's **Fit view** action.
+
+```ts
+canvas_node({ action: 'add', type: 'mermaid', content: 'flowchart TD; A-->B-->C-->D',
+  width: 920, height: 870, strictSize: true, data: { fit: 'contain' } })
+canvas_node({ action: 'update', id: 'node-id', data: { fit: 'none' } })
+```
+
+HTTP uses the same `data` object in `POST /api/canvas/node` and
+`PATCH /api/canvas/node/:id`. CLI creation and updates expose `--fit`:
+
+```bash
+pmx-canvas node add --type mermaid --content 'flowchart TD; A-->B-->C-->D' --fit contain --width 920 --height 870 --strict-size
+pmx-canvas node update node-id --fit none
+```
+
 ## Image nodes
 
 Image nodes display local paths, remote URLs, and data URIs. File-backed and
@@ -163,6 +202,40 @@ Specs preserve top-level `state` and element-level `repeat`, `watch`, and
 `$state` only reads a value. Nested repeats can use `statePath: { "$item": "tasks" }`
 to iterate the current item's tasks. Watchers run after changes, not on mount.
 
+**Seed form values through bindings, not literal `value` props.** In shadcn
+0.21, `Input`, `Textarea`, `Select`, `Radio`, `Slider`, `ToggleGroup`, and
+`Tabs` ignore an unbound `value`; `ButtonGroup` ignores unbound `selected`.
+This includes read-only `$state` expressions. PMX returns a `warnings` array
+from `POST /api/canvas/json-render`, `POST /api/canvas/schema/validate`, and
+`canvas_render` actions `add-json-render` and `validate`. Warnings name the
+element/property; they do not reject or rewrite the spec. PMX does not invent
+state paths because repeated controls and existing actions may need distinct
+or deliberately shared state.
+
+```json
+{
+  "root": "postcode",
+  "state": { "form": { "postcode": "nw1 6xe" } },
+  "elements": {
+    "postcode": {
+      "type": "Input",
+      "props": {
+        "label": "Postcode",
+        "name": "postcode",
+        "value": { "$bindState": "/form/postcode" }
+      }
+    }
+  }
+}
+```
+
+Inside repeats, use `$bindItem` with seeded item data. `Checkbox`/`Switch`
+honor literal `checked`, `Toggle` honors literal `pressed`, and `Tabs` honors
+`defaultValue` for an uncontrolled initial tab. `Pagination` reads `page`
+directly; `DropdownMenu.value` is an output binding for selection, not a
+displayed selection. These do not require the same ignored-value warning.
+Use two-way bindings whenever edits or form checks must participate in state.
+
 Cards keep their body in `children` and accept
 `slots: { header: ['headingId'], footer: ['actionsId'] }`. Slot IDs reference
 entries in `elements`; a custom header replaces the title and description props.
@@ -277,6 +350,13 @@ component gallery, interaction prototype, flowchart, SVG illustration set,
 presentation, explainer, status report, incident report, triage board, config
 editor, or prompt tuner.
 
+Omitted fields may use the template's examples. Explicit empty arrays, empty
+strings, or `null` mean “show nothing”: the field's section, heading, and
+dependent controls are omitted rather than replaced with sample content.
+Other populated or omitted fields keep their normal behavior. Empty `slides`
+or flow `steps` also omit navigation/run controls; an AX board's live task
+controls remain available when only its optional note is empty.
+
 Two kinds are **live AX control surfaces** rather than static documents, and are
 the only primitives created with AX enabled:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",

package/skills/pmx-canvas/SKILL.md

@@ -16,9 +16,17 @@ PMX Canvas is a server-authoritative spatial workbench controlled through MCP, H
 Humans curate agent context by pinning nodes; agents read that curation through
 `canvas://pinned-context`. State survives browser refresh.
 
+For presentations, `canvas_view { action: "set-tour", tour: { stops: [...] } }`
+persists ordered camera stops; `get-tour` reads them (or derived group order).
+Each stop targets `{ nodeId }` (including groups) or `{ viewport: { x, y, scale } }`,
+with optional `duration` seconds, `easing`, screen-pixel `padding`, and `pullback`.
+Open `/workbench?present=1` for chrome-free viewing. Optionally capture that same
+tour with `pmx-canvas record --mode deterministic --present --output tour.mp4`.
+There is no separate recording model. See `docs/cli.md` for the full tour model.
+
 ## Runtime prerequisites
 
-PMX Canvas 0.6.4 requires **Bun >=1.4.2**, including when installed through npm.
+PMX Canvas 0.6.5 requires **Bun >=1.4.2**, including when installed through npm.
 Check `bun --version` and ensure Bun is on the MCP host's PATH, not just your shell's;
 use an absolute executable path if needed. Install/configure only when requested.
 For pinned installation, MCP configuration, managed services, and disposable verification,
@@ -178,7 +186,7 @@ always authoritative, independent of the installed release version.
 | `canvas_edge` | `add`, `update`, `remove` |
 | `canvas_group` | `create`, `add`, `ungroup` |
 | `canvas_history` | `undo`, `redo` |
-| `canvas_view` | `arrange`, `focus`, `fit`, `clear`, `remove-annotation` |
+| `canvas_view` | `arrange`, `focus`, `fit`, `clear`, `remove-annotation`, `get-tour`, `set-tour` |
 | `canvas_query` | `search`, `layout`, `validate` |
 | `canvas_webview` | `status`, `start`, `stop`, `resize`, `evaluate` |
 | `canvas_app` | `open-mcp-app`, `diagram`, `build-artifact` |

package/skills/pmx-canvas/references/full-reference.md

@@ -441,7 +441,7 @@ single-purpose tools behind an `action` (and, for `canvas_ax_gate`, a `kind`) di
 | `canvas_group` | `create` · `add` · `ungroup` | Manage spatial group containers |
 | `canvas_history` | `undo` · `redo` | Time travel through the mutation ring buffer |
 | `canvas_snapshot` | `save` · `list` · `restore` · `delete` · `gc` · `diff` | Named snapshots: save/list/restore/delete, garbage-collect old ones, diff current canvas vs a snapshot (`diff` takes `snapshot`, not `id`) |
-| `canvas_view` | `arrange` · `focus` · `fit` · `clear` · `remove-annotation` | Auto-arrange, pan-to-node, fit viewport, clear the board, delete a human-drawn annotation by id |
+| `canvas_view` | `arrange` · `focus` · `fit` · `clear` · `remove-annotation` · `get-tour` · `set-tour` | Auto-arrange, pan-to-node, fit viewport, clear the board, delete annotations, read/persist ordered presentation stops (`tour: null` derives group order) |
 | `canvas_query` | `search` · `layout` · `validate` | Find nodes by keyword, read full layout, or **`validate`** the board for node collisions / group-containment / dangling edges |
 | `canvas_app` | `open-mcp-app` · `diagram` · `build-artifact` | Hosted MCP apps, the Excalidraw diagram preset, and bundled web artifacts (folds `canvas_open_mcp_app` / `canvas_add_diagram` / `canvas_build_web_artifact`) |
 | `canvas_webview` | `status` · `start` · `stop` · `resize` · `evaluate` | Headless Bun.WebView automation for the workbench (folds the `canvas_webview_*` / `canvas_resize` / `canvas_evaluate` tools) |

package/skills/pmx-canvas/references/installing-pmx-canvas.md

@@ -4,7 +4,7 @@ Use this reference when the `pmx-canvas` skill is installed but the `pmx-canvas`
 
 ## Prerequisites and version
 
-The examples pin **PMX Canvas 0.6.4**, which requires **Bun >=1.4.2** even when
+The examples pin **PMX Canvas 0.6.5**, which requires **Bun >=1.4.2** even when
 installed through npm: the CLI runs through Bun, not Node. Check `bun --version`
 first. If missing or older, follow the [Bun installation instructions](https://bun.sh/docs/installation)
 with the user's authorization. Ensure Bun is on the MCP host's PATH as well as the
@@ -17,11 +17,11 @@ in `SKILL.md`. Do not pair newer checkout guidance with an older runtime unknowi
 ## Install from npm
 
 ```bash
-npm install -g pmx-canvas@0.6.4
+npm install -g pmx-canvas@0.6.5
 pmx-canvas --version
 ```
 
-Without a global install, use `bunx pmx-canvas@0.6.4` in place of `pmx-canvas` in
+Without a global install, use `bunx pmx-canvas@0.6.5` in place of `pmx-canvas` in
 the commands below. Do not use unpinned `bunx pmx-canvas` for a version-specific check.
 
 ## Choose the workspace and target
@@ -91,7 +91,7 @@ discards empty env values, remove `PMX_CANVAS_URL` from its launch environment i
   "mcpServers": {
     "canvas": {
       "command": "bunx",
-      "args": ["pmx-canvas@0.6.4", "--mcp"],
+      "args": ["pmx-canvas@0.6.5", "--mcp"],
       "env": {
         "PMX_CANVAS_WORKSPACE_ROOT": "/absolute/path/to/project",
         "PMX_CANVAS_PORT": "14313",

package/src/cli/agent.ts

@@ -30,6 +30,7 @@ import './commands/history.js';
 import './commands/ax.js';
 import './commands/pump.js';
 import './commands/webview.js';
+import './commands/record.js';
 import './commands/apps.js';
 import './commands/copilot.js';
 import './commands/skills.js';
@@ -46,6 +47,10 @@ Usage:
   pmx-canvas <command> [options]
   pmx-canvas [server-options]
 
+Presentation and capture:
+  pmx-canvas tour get|set             Read or persist ordered camera stops
+  pmx-canvas record --help            Optionally capture the same board tour or live presentation
+
 Server:
   pmx-canvas                          Start server + open browser
   pmx-canvas --no-open --demo         Start server headless with sample data

package/src/cli/commands/nodes.ts

@@ -27,6 +27,12 @@ import {
 
 const TRACE_NODE_FIELDS = ['toolName', 'category', 'status', 'duration', 'resultSummary', 'error'] as const;
 
+function applyMermaidFitFlag(body: Record<string, unknown>, flags: Record<string, string | boolean>): void {
+  if (flags.fit === undefined) return;
+  if (flags.fit !== 'contain' && flags.fit !== 'none') die('Use --fit contain or --fit none (Mermaid nodes).');
+  body.data = { ...(isRecord(body.data) ? body.data : {}), fit: flags.fit };
+}
+
 interface CanvasSchemaField {
   name: string;
   type: string;
@@ -483,6 +489,7 @@ cmd(
     'pmx-canvas node add --type html --title "Showcase" --content ./report.html   (a .html path is read from disk; otherwise --content is raw HTML)',
     'pmx-canvas node add --type html --primitive choice-grid --data-file ./options.json --title "Options"',
     'pmx-canvas node add --type markdown --title "Note" --x 100 --y 200',
+    'pmx-canvas node add --type mermaid --content "graph TD; A-->B" --fit contain',
     'pmx-canvas node add --type json-render --title "Ops Dashboard" --spec-file ./dashboard.json',
     'pmx-canvas node add --type graph --graph-type bar --data-file ./metrics.json --x-key label --y-key value',
     'pmx-canvas node add --type web-artifact --title "Dashboard" --app-file ./App.tsx',
@@ -530,6 +537,7 @@ cmd(
     }
 
     const body: Record<string, unknown> = { type };
+    applyMermaidFitFlag(body, flags);
     if (flags.title) body.title = flags.title;
     const webpageUrl = getStringFlag(flags, 'url');
     const imagePath = getStringFlag(flags, 'path');
@@ -821,6 +829,7 @@ cmd(
   [
     'pmx-canvas node update <node-id> --title "New Title"',
     'pmx-canvas node update <node-id> --content "Updated content"',
+    'pmx-canvas node update <mermaid-id> --fit none',
     'pmx-canvas node update <node-id> --title "Moved" --x 500 --y 300',
     'pmx-canvas node update <node-id> --width 840 --height 620',
     'pmx-canvas node update <node-id> --spec-file ./dashboard.json',
@@ -838,6 +847,7 @@ cmd(
 
     const body: Record<string, unknown> = {};
     await applyStructuredNodeUpdateFlags(body, flags);
+    applyMermaidFitFlag(body, flags);
     if (flags.title && flags.title !== true) body.title = flags.title;
     if (flags.content && flags.content !== true) body.content = flags.content;
     if (flags.stdin) body.content = await readStdin();

package/src/cli/commands/record.ts

@@ -0,0 +1,218 @@
+import { mkdirSync, existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { z } from 'zod';
+import { isCanvasTheme } from '../../shared/themes.js';
+import { derivedTour, tourSchema, tourFrames, type Camera, type TourNode } from '../../shared/tour.js';
+import {
+  startCanvasAutomationWebView,
+  evaluateCanvasAutomationWebView,
+  screenshotCanvasAutomationWebView,
+  resizeCanvasAutomationWebView,
+  stopCanvasAutomationWebView,
+} from '../../server/server.js';
+import { cmd, getBaseUrl, invokeOperation, output, parseFlags, showCommandHelp } from '../shared.js';
+
+export function parseRecordOptions(flags: Record<string, string | boolean>) {
+  const number = (key: string, fallback: number) => {
+    if (flags[key] === true || flags[key] === false) throw new Error(`--${key} needs a number`);
+    return flags[key] === undefined ? fallback : Number(flags[key]);
+  };
+  for (const key of ['tour-file', 'chrome-path']) {
+    if (flags[key] !== undefined && typeof flags[key] !== 'string') throw new Error(`--${key} needs a path`);
+  }
+  const resolution = String(flags.resolution ?? '1280x720').match(/^(\d+)x(\d+)$/);
+  if (!resolution) throw new Error('Use --resolution WIDTHxHEIGHT');
+  const options = z
+    .object({
+      width: z.number().int().min(64).max(7680),
+      height: z.number().int().min(64).max(4320),
+      fps: z.number().int().min(1).max(120),
+      duration: z.number().positive().max(86400).optional(),
+      mode: z.enum(['realtime', 'deterministic']),
+      output: z.string().min(1),
+    })
+    .parse({
+      width: Number(resolution[1]),
+      height: Number(resolution[2]),
+      fps: number('fps', 30),
+      duration: flags.duration === undefined ? undefined : number('duration', 10),
+      mode: flags.mode ?? 'realtime',
+      output: typeof flags.output === 'string' ? flags.output : '',
+    });
+  if (flags.theme !== undefined && !isCanvasTheme(flags.theme)) throw new Error('Unknown --theme');
+  if (options.mode === 'realtime' && !options.duration && flags['stop-on-signal'] !== true) {
+    throw new Error('Realtime recording needs --duration SECONDS or --stop-on-signal');
+  }
+  if (options.mode === 'deterministic' && (flags.duration !== undefined || flags['stop-on-signal'])) {
+    throw new Error('Deterministic duration comes from tour stops; omit --duration and --stop-on-signal');
+  }
+  if (flags['tour-file'] && options.mode !== 'deterministic')
+    throw new Error('--tour-file requires --mode deterministic');
+  return {
+    ...options,
+    theme: typeof flags.theme === 'string' ? flags.theme : undefined,
+    present: flags.present === true,
+    tourFile: typeof flags['tour-file'] === 'string' ? flags['tour-file'] : undefined,
+    chromePath: typeof flags['chrome-path'] === 'string' ? flags['chrome-path'] : undefined,
+  };
+}
+
+cmd('tour get', 'Read the persisted tour or derived group order', ['pmx-canvas tour get'], async () => {
+  output(await invokeOperation('tour.get', {}));
+});
+cmd(
+  'tour set',
+  'Persist camera stops from JSON (null resets to group order)',
+  ['pmx-canvas tour set --file tour.json'],
+  async (args) => {
+    const { flags } = parseFlags(args);
+    if (flags.help) return showCommandHelp('tour set');
+    if (typeof flags.file !== 'string') throw new Error('Missing --file');
+    const tour = tourSchema.nullable().parse(await Bun.file(flags.file).json());
+    output(await invokeOperation('tour.set', { tour }));
+  },
+);
+
+cmd(
+  'record',
+  'Optionally capture the board tour or live presentation using Bun.WebView Chrome',
+  [
+    'pmx-canvas record --duration 10 --present --output demo.mp4',
+    'pmx-canvas record --mode deterministic --tour-file tour.json --present --fps 30 --output frames',
+    'pmx-canvas record --stop-on-signal --resolution 1920x1080 --output live.mp4',
+  ],
+  async (args) => {
+    const { flags } = parseFlags(args, { boolFlags: ['present', 'stop-on-signal'] });
+    if (flags.help || flags.h) return showCommandHelp('record');
+    const options = parseRecordOptions(flags);
+    const outputPath = resolve(options.output);
+    const video = /\.mp4$/i.test(outputPath);
+    const framesPath = video ? `${outputPath}.frames` : outputPath;
+    if (existsSync(outputPath) || existsSync(framesPath)) throw new Error('Output already exists; choose a new path');
+    const response = await fetch(`${getBaseUrl()}/api/canvas/state`);
+    if (!response.ok) throw new Error(`Cannot read board: HTTP ${response.status}`);
+    const board = (await response.json()) as { nodes: TourNode[]; viewport: Camera; tour?: unknown };
+    const tour =
+      options.mode === 'deterministic'
+        ? tourSchema.parse(
+            options.tourFile ? await Bun.file(options.tourFile).json() : (board.tour ?? derivedTour(board.nodes)),
+          )
+        : undefined;
+    if (tour && !tour.stops.length) throw new Error('No tour stops: supply --tour-file or create groups/a tour');
+    const url = new URL('/workbench', getBaseUrl());
+    if (options.present) url.searchParams.set('present', '1');
+    if (tour) url.searchParams.set('capture', '1');
+    if (options.theme) url.searchParams.set('theme', options.theme);
+    let stopping = false;
+    const stop = () => {
+      stopping = true;
+    };
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+    let count = 0;
+    let duplicated = 0;
+    try {
+      await startCanvasAutomationWebView(url.href, {
+        backend: 'chrome',
+        width: options.width,
+        height: options.height,
+        chromePath: options.chromePath,
+      });
+      const deadline = Date.now() + 30_000;
+      while (!(await evaluateCanvasAutomationWebView('!!window.pmxCapture?.ready()'))) {
+        if (Date.now() > deadline) throw new Error('Workbench did not become capture-ready in 30 seconds');
+        await Bun.sleep(50);
+      }
+      // Chrome launch dimensions describe the outer window. WebView.resize
+      // applies viewport emulation, giving screenshots the requested pixels.
+      await resizeCanvasAutomationWebView(options.width, options.height);
+      await evaluateCanvasAutomationWebView(
+        'new Promise(r => requestAnimationFrame(() => requestAnimationFrame(() => r(true))))',
+      );
+      await evaluateCanvasAutomationWebView('document.fonts.ready.then(() => true)');
+      const area = (await evaluateCanvasAutomationWebView('window.pmxCapture.area()')) as {
+        width: number;
+        height: number;
+      };
+      const initial = (await evaluateCanvasAutomationWebView('window.pmxCapture.camera()')) as Camera;
+      mkdirSync(framesPath, { recursive: true });
+      const write = async (bytes: Uint8Array) => {
+        await Bun.write(join(framesPath, `frame-${String(count++).padStart(6, '0')}.png`), bytes);
+      };
+      const started = performance.now();
+      if (tour) {
+        for (const camera of tourFrames(tour, initial, board.nodes, area.width, area.height, options.fps)) {
+          if (stopping) break;
+          const applied = (await evaluateCanvasAutomationWebView(
+            `window.pmxCapture.frame(${JSON.stringify(camera)})`,
+          )) as Camera;
+          if (applied.x !== camera.x || applied.y !== camera.y || applied.scale !== camera.scale) {
+            throw new Error('Capture camera was changed before paint');
+          }
+          await write(await screenshotCanvasAutomationWebView({ format: 'png' }));
+        }
+      } else {
+        const limit = options.duration ? Math.ceil(options.duration * options.fps) : Infinity;
+        while (!stopping && count < limit) {
+          await Bun.sleep(Math.max(0, started + (count / options.fps) * 1000 - performance.now()));
+          const bytes = await screenshotCanvasAutomationWebView({ format: 'png' });
+          await write(bytes);
+          // Preserve wall-clock speed if capture is slower than requested fps.
+          const elapsedFrames = Math.min(limit, Math.floor(((performance.now() - started) / 1000) * options.fps));
+          while (count < elapsedFrames) {
+            await write(bytes);
+            duplicated++;
+          }
+        }
+      }
+      await Bun.write(
+        join(framesPath, 'recording.json'),
+        JSON.stringify(
+          {
+            mode: options.mode,
+            fps: options.fps,
+            width: options.width,
+            height: options.height,
+            frames: count,
+            duplicated,
+            seconds: count / options.fps,
+          },
+          null,
+          2,
+        ),
+      );
+    } finally {
+      process.off('SIGINT', stop);
+      process.off('SIGTERM', stop);
+      await stopCanvasAutomationWebView();
+    }
+    let encoded = false;
+    if (video && count > 0) {
+      const ffmpeg = Bun.which('ffmpeg');
+      if (!ffmpeg) console.error(`ffmpeg not found; PNG sequence retained at ${framesPath}`);
+      else {
+        const process = Bun.spawn(
+          [
+            ffmpeg,
+            '-n',
+            '-framerate',
+            String(options.fps),
+            '-i',
+            join(framesPath, 'frame-%06d.png'),
+            '-c:v',
+            'libx264',
+            '-pix_fmt',
+            'yuv420p',
+            '-vf',
+            'pad=ceil(iw/2)*2:ceil(ih/2)*2',
+            outputPath,
+          ],
+          { stdout: 'ignore', stderr: 'inherit' },
+        );
+        encoded = (await process.exited) === 0;
+        if (!encoded) throw new Error(`ffmpeg failed; PNG sequence retained at ${framesPath}`);
+      }
+    }
+    output({ ok: true, output: encoded ? outputPath : framesPath, frames: count, fps: options.fps, duplicated });
+  },
+);

package/src/cli/index.ts

@@ -32,6 +32,8 @@ if (args.includes('--version') || args.includes('-v')) {
 // ── Agent CLI subcommands ────────────────────────────────────
 // If first arg is a known subcommand (not a --flag), route to the agent CLI.
 const AGENT_COMMANDS = new Set([
+  'tour',
+  'record',
   'node',
   'edge',
   'json-render',