pmx-canvas 0.10.0 → 0.12.0

package/skills/pmx-canvas/evals/evals.json

@@ -536,8 +536,8 @@
     {
       "id": 22,
       "name": "tour-authoring-and-capture",
-      "prompt": "Turn the Overview group and the Results card into a presentation tour, then tell me how to capture it deterministically at 1920x1080. I want a one-second overview move, a zero-duration jump to Results, and no changes to another viewer's camera.",
-      "expected_output": "Targets the intended board, resolves the real group/card IDs, persists one tour with canvas_view set-tour, and uses valid node targets with durations 1 and 0. Explains that presentation is viewer-local and does not auto-advance. Gives deterministic record guidance using the same saved tour, --resolution 1920x1080, --present, and a new output path after verifying the matching daemon/workspace and Chrome/Bun WebView prerequisites. Does not invent a separate recording timeline or use realtime --duration.",
+      "prompt": "On the current board, turn the Overview group and the Results card into a presentation tour, then tell me how to capture it deterministically at 1920x1080. I want a one-second overview move, a zero-duration jump to Results, and no changes to another viewer's camera. That viewer is already presenting.",
+      "expected_output": "Verifies the current board, resolves the real group/card IDs, persists one tour with canvas_view set-tour, and uses valid node targets with durations 1 and 0. Distinguishes viewer-local rendering/free pan and isolated recording from shared tour navigation and exit. Does not call tour-go, tour-exit or move, switch boards, or use human Next/Back controls. Explains that present:false still advances viewers already presenting. Gives deterministic record guidance using the same saved tour, --resolution 1920x1080, --present, and a new output path after verifying the matching daemon/workspace and Chrome/Bun WebView prerequisites. Does not invent a separate recording timeline or use realtime --duration.",
       "assertions": [
         {
           "name": "persists-valid-shared-tour-model",
@@ -556,7 +556,30 @@
         },
         {
           "name": "preserves-viewer-camera",
-          "description": "States that the presentation/capture camera is local and stops advance manually, rather than moving another viewer's camera",
+          "description": "Keeps the already-presenting viewer unchanged by avoiding shared tour-go/tour-exit/move, board switching and human navigation; distinguishes isolated capture from the shared cursor and does not treat present:false as isolation",
+          "type": "output_check"
+        }
+      ]
+    },
+    {
+      "id": 44,
+      "name": "presenter-superseded-is-not-applied-navigation",
+      "prompt": "In a disposable board, verify optional presenter ordering. Send a valid go with intent 2, then an exit with intent 1 for the same document and activation. Repeat with a stale activation. Include an independent-document control and an ordinary unfenced call. Can ok:true or the SDK exit return prove the stale command ran?",
+      "expected_output": "Reads the actual activation stamps and uses positive safe-integer intents with independent document IDs. Checks applied delivery stamps and cursor/event behavior. Older intent and stale activation return ok:true,superseded:true without a navigation event or cursor change. Independent and unfenced controls still apply. Explains that the fence orders requests, does not grant authority or isolate viewers, and that SDK exit returns void while fenced go may return superseded:true. Does not count eval definitions as executed evidence.",
+      "assertions": [
+        {
+          "name": "checks-superseded-side-effects",
+          "description": "Observes no navigation event or cursor change for stale intent and activation, rather than treating ok:true as applied navigation",
+          "type": "output_check"
+        },
+        {
+          "name": "positive-controls-and-stamps",
+          "description": "Verifies applied epoch/generation/sequence for the newer request and exercises independent-document and unfenced calls without inventing mandatory presenter credentials",
+          "type": "output_check"
+        },
+        {
+          "name": "sdk-return-boundary",
+          "description": "Distinguishes fenced go's superseded result from exit's void return and avoids claiming viewer isolation or authority from the fence",
           "type": "output_check"
         }
       ]

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

@@ -349,7 +349,7 @@ The CLI targets `http://localhost:4313` by default. Override with `PMX_CANVAS_UR
 | Type | Purpose | When to use |
 |------|---------|-------------|
 | `markdown` | Rich formatted content | Explanations, documentation, notes, findings |
-| `status` | Compact color-coded indicator | Progress tracking, build/test results, task state |
+| `status` | Compact status or deliberately authored work card | Work plans with `data.workState`; phase/tool status without it |
 | `file` | Live file viewer (auto-watches) | Show source code with live updates on file change |
 | `image` | Image display | Screenshots, diagrams, charts |
 | `context` | Context card | Key context the human should see |
@@ -419,6 +419,9 @@ contract). Their meaning comes from the node **type** and value instead: a `stat
 `waiting` — e.g. `review` → green, `running` → accent; an unrecognized phase renders gray), and a
 `trace` node from its `status` field (`success` → green, `failed` → red, `running` → accent). To
 color an arbitrary region, group the nodes and set the group's `color`.
+Authored status cards with `data.workState` instead use the work-state glyph and label:
+blocked uses the warning token, done the success token, and cancelled the muted token.
+Do not set arbitrary colors to encode work state.
 
 When you do set a color (group/graph), use this palette consistently to convey meaning:
 - **Green** (`#22c55e`) — success, done, healthy
@@ -455,9 +458,9 @@ enforce conditional requirements. Non-registry tools use `tools/list` instead.
 | `canvas_edge` | `add` · `update` · `remove` | Connect / edit / disconnect nodes |
 | `canvas_group` | `create` · `add` · `ungroup` | Manage spatial group containers |
 | `canvas_history` | `undo` · `redo` | Time travel through the mutation ring buffer |
-| `canvas_board` | `list` · `get` · `create` · `create-from` · `open` · `update` · `pin` · `unpin` · `knowledge-list` · `category-set` · `category-remove` · `folder-set` · `relation-preset-set` · `relation-preset-remove` | Boards and workspace categories/folder properties/shared relation templates; knowledge writes never open a board. Template edits/deletion never rewrite boards or connections. `category-remove` takes `id` and refuses explicit folder assignments, including empty folders; reassign or clear them first. |
+| `canvas_board` | `list` · `get` · `create` · `create-from` · `move-selection` · `open` · `update` · `pin` · `unpin` · `knowledge-list` · `category-set` · `category-remove` · `folder-set` · `relation-preset-set` · `relation-preset-remove` | Boards and workspace categories/folder properties/shared relation templates; knowledge writes never open a board. Template edits/deletion never rewrite boards or connections. `category-remove` takes `id` and refuses explicit folder assignments, including empty folders; reassign or clear them first. |
 | `canvas_snapshot` | `save` · `list` · `restore` · `restore-node` · `delete` · `gc` · `diff` | Named snapshots: save/list/restore/delete, garbage-collect old ones, diff current canvas vs a snapshot (`diff` takes `snapshot`, not `id`); `restore-node` puts one card (`nodeId`) back to its content in snapshot `id` |
-| `canvas_view` | `arrange` · `focus` · `fit` · `clear` · `remove-annotation` · `get-tour` · `set-tour` · `tour-go` · `tour-exit` · `move` | Auto-arrange, pan-to-node, fit viewport, clear the board, delete annotations, read/persist ordered presentation stops (`tour: null` derives group order), present a stop / exit, ease the camera to a node, rect or viewport (never an undo step) |
+| `canvas_view` | `arrange` · `focus` · `fit` · `clear` · `add-annotation` · `remove-annotation` · `get-tour` · `set-tour` · `tour-go` · `tour-exit` · `move` | Auto-arrange, pan-to-node, fit viewport, clear the board, draw/write/erase annotations, read/persist ordered presentation stops (`tour: null` derives group order), present a stop / exit, ease the camera to a node, rect or viewport (never an undo step) |
 | `canvas_query` | `context` · `graph` · `search` · `layout` · `validate` | Read the budgeted brief or summary-only connected memory graph, find nodes, read full layout, or **`validate`** collisions / 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) |
@@ -498,6 +501,18 @@ group structure are optional; fresh IDs are allocated; pins, AX state, and
 history are not copied; the source remains unchanged and the new board inactive.
 The new board records `previousBoardId` pointing to its source.
 
+For an identity-preserving move, use `canvas_board` action `move-selection`, not
+copy/delete. Read the active source board's `contentRevision` with `get`. Preview
+with `sourceBoardId`, `nodeIds`, `name`, `expectedRevision: contentRevision`,
+`requestId` and `preview: true`; inspect blockers and notices before committing
+with the same inputs without `preview`. Retry an uncertain response with the same
+request ID and inputs. Group descendants move together; unsafe bindings refuse
+the entire move. Cards retain identities, pins, relations and review history,
+without new validation or read evidence. The source stays open with a portal to
+the new board. Pre-move Undo/Redo is cleared on affected boards; older snapshots
+remain inspectable but cannot be restored across the move. Open the returned
+`destinationBoardId` only when navigation is wanted.
+
 ### Connected memory (wave 2)
 
 Home Folders, Map and Graph, wiki links/backlinks, and brief discovery share one
@@ -555,10 +570,15 @@ Once the board list has loaded, all workbench context-pin writes send the captur
 `expectedBoardId`; a server-side board switch returns 409 instead of changing
 another board's pins. Receipt pin actions require reopening the owning board.
 
-Embedded JSON/graph runtime readiness waits up to 10 seconds after document load
-and retries a failed handoff once while retaining the last painted document.
-After another failure, the error toast/history say **Reload to retry**; a later
-healthy authored update can recover. This is not an overall network-load timeout.
+Embedded previews mount automatically near the viewport at every zoom and remain
+mounted to preserve arbitrary app state. There is no lifetime preview cap. Mermaid renders
+inline, without an iframe. JSON/graph viewers inherit all nine named canvas themes
+and keep form drafts when the theme changes. During replacement, the pending
+document temporarily coexists with its painted predecessor.
+
+A network load or missing JSON runtime times out after 10 seconds and offers a
+visible **Retry**, retaining the last painted document during replacement.
+An already mounted offscreen runtime may wait for paint without being timed out.
 
 Native edge add accepts optional `toBoardId`: `from` is on the open source board,
 `to` is a card on the target board. CLI: `pmx-canvas edge add --from <source> --to <target>
@@ -697,8 +717,33 @@ delete+recreate; preserves edges, pins, position)
 
 **`canvas_node { action: "get", id }`** — Get a single node's full data by `id`.
 
-**`canvas_view { action: "remove-annotation", id }`** — Remove a human-drawn annotation by `id`. Use when
-context gives you the annotation ID; use WebView first if you need to identify a mark by shape or location.
+**`canvas_view { action: "add-annotation", points, … }`** — Draw freehand ink with at least two
+world-coordinate points, or set `type: "text"`, `text` and one point to write a note.
+`width` is stroke width (default 4, clamped to 1–24) or font size (default 24,
+clamped to 1–96). `color` defaults to `currentColor`, the theme's annotation ink;
+explicit colors must be `#rrggbb`. Text is trimmed to 240 characters, labels to 160.
+Bounds and creation time are server-derived.
+
+Freehand points render as straight segments with round caps/joins, without automatic
+smoothing. Sample curves densely for smooth-looking outlines and loops. Cursor updates
+through `canvas_ax_state { action: "set-presence", cursor: { x, y } }` are separate,
+ephemeral presence, not drawing gestures; reuse your writer identity without attaching
+a session. An annotation appears complete on creation, not as a streaming stroke.
+See [Shared ink and questions](workbench-workflows.md#shared-ink-and-questions).
+
+Use an explicit `id` for retries: equal normalized content returns the existing mark
+without another Undo entry, while different content conflicts. After erasing or Undo,
+adding the ID creates a mark again; this is not a durable creation receipt.
+
+**`canvas_view { action: "remove-annotation", id }`** — Erase a whole human or agent mark,
+not the underlying card. An absent mark returns not-found. Context gives you IDs;
+inspect the canvas first when identifying a mark by shape or location.
+CLI and MCP batches accept `annotation.add` / `annotation.remove` with the same arguments.
+
+Humans and agents share this layer. Use marks when helpful, not for every task.
+The human may answer in the external agent host's composer; no PMX session,
+PMX composer or reply card is required. Marks are not approval gates, and drawing
+or erasing does not answer a question or execute a loop. Existing scope fences apply.
 
 **`canvas_node { action: "update", id, refresh: true }`** — Re-fetch the URL stored on a `webpage` node
 - `id` (required): webpage node to refresh
@@ -957,17 +1002,17 @@ below operates on the live canvas state through the `canvas_webview` composite.
 Useful workbench selectors:
 - Nodes: `.canvas-node`, `.canvas-node.active`, `.canvas-node.context-pinned`, `.canvas-node.group-node`
 - Node internals: `.node-title`, `.node-titlebar`, `.node-body`, `.node-type-badge`, `.node-controls`
-- Annotations: `.annotation-layer path` renders human-drawn freehand ink. Use WebView
-  to inspect or screenshot annotation shapes; MCP/context resources only expose compact
-  annotation target summaries, not the raw visual shape. Humans can remove marks with
-  the eraser in the rail's Annotate popover; agents can remove a known annotation ID with
-  `canvas_view { action: "remove-annotation" }`.
+- Annotations: `.annotation-layer path` renders shared freehand ink; `.annotation-layer text`
+  renders text notes. Use WebView to inspect or screenshot shapes; MCP/context resources
+  expose IDs, text, labels, targets and bounds, not raw stroke geometry. Humans use the
+  rail's Draw / Text note / Eraser tools; agents use `canvas_view` actions
+  `add-annotation` / `remove-annotation` on the same layer.
 - Canvas chrome (rail-chrome-v2): `.tool-rail`, `.top-bar` (`.connection-dot`, `.agent-chip`,
   `.gate-badge`, `.context-chip`, `.external-indicator`, `.start-session-btn`),
   `.connection-banner`, `.canvas-region`, `.session-panel`, `.command-bar`, `.selection-bar`,
   `.activity-feed`, `.writers-sheet`, `.session-receipt`, `.snapshot-panel` (the History
   drawer), `.minimap`, `.empty-state`, `.command-palette`, `.expanded-overlay-panel`.
-- Presence: `.agent-cursor` (attached agent), `.human-cursor` (other tabs), `.scope-fence`,
+- Presence: `.agent-cursor` (attached or external agent), `.human-cursor` (other tabs), `.scope-fence`,
   `.canvas-node.agent-mutating` (shimmer), `.node-yield-pill`.
 - Groups: `.canvas-node.group-node` with `.group-name-pill`, `.group-actions`, `.group-chip`
   (collapsed); `.drop-pill` while a dragged node would join/leave a group; `.edge-hint-pill`
@@ -1444,7 +1489,7 @@ The `canvas://spatial-context` resource reveals how the human has organized info
   This implies sequence or priority.
 - **Pinned neighborhoods** — For each pinned node, nearby unpinned nodes are listed. These
   are the human's implicit context — things they consider related to what they pinned.
-- **Annotations** — Human-drawn markup is summarized by target/bounds only, e.g. an
+- **Annotations** — Shared markup is summarized by ID, label, text, target and bounds, e.g. an
   annotation over a node or empty canvas region. Use WebView (`canvas_webview { action: "start" }` +
   `canvas_webview { action: "evaluate" }`/`canvas_screenshot`) when you need to see whether the mark is an
   arrow, line, circle, or other drawn shape. Remove known annotations with
@@ -1570,15 +1615,35 @@ Show system components and how they interact:
 
 ### Task Plan with Dependencies
 
-Track work items and their relationships:
+Show useful work deliberately, not a card per task or event. Ordinary work cards are authored
+node data, not AX work items. They require no session and create no approval or execution.
+
+1. Create a `status` node with `data.workState`: `todo`, `in-progress`, `blocked`, `done` or
+   `cancelled`. Use string `data.detail` for context and optional `data.progress` from 0 to 100.
+   Progress is independent of state: Done does not imply 100%; `null` clears progress.
+2. Update the same card through `canvas_node { action: "update", id, data: { ... } }`.
+   Include `expectedBoardId` and `expectedContentRevision` when an edit depends on a prior read.
+3. Connect steps, dependencies, alternatives and intentional loops with existing relations.
+   A drawn loop does not execute. Group distinct phases when useful, then inspect readability.
+4. Humans use **New work card** from the background menu and **Edit/Save/Cancel** inside the card.
+   Drafts and pending/refused saves survive focus-mode open/close, but not a page reload.
+   The editor's temporary growth does not resize the saved card.
+
+MCP creation:
+
+```json
+{"action":"add","type":"status","title":"Verify","data":{"workState":"todo","detail":"Run browser checks"}}
+```
+
+CLI creation uses structured batch data, not `node add --data` (that flag is for graph series):
+
+```bash
+pmx-canvas batch --json '[{"op":"node.add","args":{"type":"status","title":"Verify","data":{"workState":"todo","detail":"Run browser checks"}}}]'
+```
 
-1. Create `status` nodes for each task
-2. Color-code: green=done, yellow=in-progress, red=blocked, gray=queued, blue=ready/available
-3. Connect with `depends-on` edges — use `dashed` style for blocked dependencies, `solid` for
-   satisfied ones
-4. Update status nodes as work progresses using `canvas_node { action: "update" }`
-5. Arrange with `flow` layout to show the dependency chain left-to-right
-6. Group related tasks if the plan has distinct phases
+Without `data.workState`, status cards retain their phase/tool display. Session-task linking
+is not provided by these authored cards. Questions can be drawn or written beside the plan;
+the human can answer in the external agent host's composer, without a PMX reply card.
 
 ### Code Exploration
 

package/skills/pmx-canvas/references/html-primitives.md

@@ -110,6 +110,13 @@ agent.
 - `interaction-prototype` exposes live controls and copyable config for implementation tuning.
 - Tell the human which copy/export button to use, then ask them to paste the result back if you need to act on edits.
 
+The card menu also offers **Copy JSON** for non-presentation HTML primitives. Open the viewer
+first: this reads its current interactive state, preferring the expanded frame when present,
+not a stale export of saved node data. The reply is bound to the frame source, document token
+and request ID; the parent workbench requests clipboard access from the human's click.
+Clipboard permission or host limitations can still refuse the copy and show an error.
+This does not persist edits, support arbitrary raw HTML, or replace the per-format buttons above.
+
 ## Sandbox And Persistence
 
 - Primitive output runs inside the existing HTML iframe sandbox with scripts allowed but no same-origin access.

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.10.0**, which requires **Bun >=1.4.4** even when
+The examples pin **PMX Canvas 0.12.0**, which requires **Bun >=1.4.4** 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
@@ -22,11 +22,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.10.0
+npm install -g pmx-canvas@0.12.0
 pmx-canvas --version
 ```
 
-Without a global install, use `bunx pmx-canvas@0.10.0` in place of `pmx-canvas` in
+Without a global install, use `bunx pmx-canvas@0.12.0` 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
@@ -96,7 +96,7 @@ discards empty env values, remove `PMX_CANVAS_URL` from its launch environment i
   "mcpServers": {
     "canvas": {
       "command": "bunx",
-      "args": ["pmx-canvas@0.10.0", "--mcp"],
+      "args": ["pmx-canvas@0.12.0", "--mcp"],
       "env": {
         "PMX_CANVAS_WORKSPACE_ROOT": "/absolute/path/to/project",
         "PMX_CANVAS_PORT": "14313",
@@ -140,7 +140,7 @@ Amp executes, not only on the user's laptop. Merge this into that workspace's
   "amp.mcpServers": {
     "canvas": {
       "command": "bunx",
-      "args": ["pmx-canvas@0.10.0", "--mcp"],
+      "args": ["pmx-canvas@0.12.0", "--mcp"],
       "includeTools": ["canvas_*"],
       "env": {
         "PMX_CANVAS_WORKSPACE_ROOT": "/absolute/path/to/project",
@@ -174,7 +174,7 @@ The agent must not run this approval itself or move the command to global settin
 `--mcp-config` to bypass workspace trust. Approval authorizes execution of this MCP
 command; it is not a new Canvas import consent or permission to mutate arbitrary boards.
 After approval, reload MCP connections (`reload_mcp` in Amp) and require `connected`.
-Discover `canvas` tools with `tool_search`; the full unfiltered 0.10.0 server has 25 tools,
+Discover `canvas` tools with `tool_search`; the full unfiltered 0.12.0 server has 25 tools,
 including `canvas_help`. If still absent, inspect the server status, command/PATH and target instead
 of reinstalling blindly. See [Amp MCP documentation](https://ampcode.com/docs/customize/mcp).
 

package/skills/pmx-canvas/references/tours-and-recording.md

@@ -31,8 +31,10 @@ Persist a tour with `canvas_view { action: "set-tour", tour: { stops: [...] } }`
 Open `/workbench?present=1` for chrome-free viewing. Right, Down, or Space advances; Left or Up
 goes back; Escape or **Exit presentation** exits. Right-drag pans and interrupts an ongoing
 transition without editing cards. Stops do not auto-advance. A missing node target reports an
-error and may be skipped. The presentation camera is local to that viewer while board content
-continues to update. Recording hides the exit control.
+error and may be skipped. Camera rendering and free pan are viewer-local, but human Back/Next
+and arrow keys advance the shared cursor for all presenting viewers; Exit leaves presentation
+everywhere. `present: false` does not isolate navigation from another presenting viewer.
+Deterministic capture uses its own viewer and ignores live navigation. Recording hides the exit control.
 
 Tours are board-scoped, persist with that board and its snapshots, participate in undo, and clear
 with the board. Setting `tour: null` resets to a derived tour: groups ordered by y, then x, then
@@ -54,6 +56,31 @@ viewport. Tour steps and moves never enter undo history, never count as agent wr
 allowed under a scope fence. Viewers with reduced motion jump instead of animating; a
 deterministic capture ignores both.
 
+If another viewer's camera must stay unchanged, do not send `tour-go`, `tour-exit` or `move`,
+or use the human shared navigation controls. Author stops and capture them in the separate
+recording viewer instead. Verify isolation with another viewer already presenting, not only
+an ordinary canvas tab.
+
+### Optional presenter ordering fence
+
+`tour-go` and `tour-exit` accept `presenter: { clientId, intent, catalogEpoch, boardGeneration }`.
+Use a distinct `clientId` per document, an increasing positive safe-integer `intent` per gesture,
+and the actual server activation's epoch and nonnegative safe-integer generation. Ordinary
+agent calls may omit this object. It orders requests; it is not authorization or viewer isolation.
+
+A stale activation or duplicate/older intent returns `{ ok: true, superseded: true }` with no
+navigation event or cursor change. Do not claim navigation from `ok: true` alone. Applied results
+and events carry `catalogEpoch`, `boardGeneration` and `sequence`; presenter-aware clients use
+these to reject stale acknowledgements and events. A structurally valid newer intent is claimed
+before resolving the stop, so even a missing newer stop supersedes older requests.
+
+This is latest-intent-wins, not FIFO: reversed relative Next requests can coalesce. Separate
+documents remain independent, and reload does not cancel an old document's pending request.
+An activation retains at most 4096 document IDs; a new ID beyond that returns 409 rather than
+evicting an ordering record. Switching boards resets the capacity but old activation stamps stay stale.
+The SDK accepts `goToTourStop(step, { presenter })` and `exitTour(presenter)`; fenced go can return
+`{ superseded: true }`, while exit returns void. Do not infer applied exit from that void return.
+
 ## Capture prerequisites and behavior
 
 Start and verify the matching PMX daemon first: its `/health` workspace and version must match the