pmx-canvas 0.2.7 → 0.3.0

package/dist/types/server/operations/http.d.ts

@@ -1,7 +1,8 @@
 /**
  * Shared body reader: preserves the parsed JSON value as-is (object, array,
  * or primitive) — per-op `readInput` decides what to do with non-object
- * bodies; the shared reader never coerces.
+ * bodies; the shared reader never coerces. A non-empty body that fails to
+ * parse is a 400 (OperationError), never a silent empty input.
  */
 export declare function readJsonValue(req: Request): Promise<unknown>;
 export declare function dispatchOperationRoute(req: Request, url: URL): Promise<Response | null>;

package/dist/types/shared/ax-intent.d.ts

@@ -5,7 +5,7 @@
  * agent is ABOUT to make (create / move / connect / remove / edit) so the canvas
  * can paint a faint placeholder before the real mutation lands. Like a
  * multiplayer cursor, it auto-expires, is count-capped, and never enters
- * `canvas_get_layout`, `state.json`, or snapshots.
+ * `canvas_query` (`layout` action), `state.json`, or snapshots.
  *
  * This module is import-shared by the server (IntentRegistry + the intent ops)
  * and the client (intent-store + IntentLayer); it must stay free of any

package/docs/RELEASE.md

@@ -46,14 +46,18 @@ and exercises the CLI flows from
 
 ## Versioning
 
-Semantic versioning. While we are still in `0.1.x`:
-
-- Patch (`0.1.x → 0.1.x+1`): bug fixes, hardening, internal cleanups,
-  additive CLI flags / MCP fields with backwards-compat fallbacks.
-- Minor (`0.1.x → 0.2.0`): documented breaking changes (e.g. dropping
-  the `hostMode + path` fallback in `getCanvasNodeKind`, removing legacy
-  `ext-app-ext-app-…` ID handling, JSON-shape changes that aren't
-  additive).
+Semantic versioning, in 0.x semver honestly (see `docs/api-stability.md`).
+We are pre-1.0, so minor versions — not just major — are the breaking-change
+boundary:
+
+- Patch (`0.x.y → 0.x.y+1`): bug fixes, hardening, internal cleanups,
+  additive CLI flags / MCP fields with backwards-compat fallbacks. Never
+  breaks a public surface.
+- Minor (`0.x → 0.x+1`): documented breaking changes are allowed only here
+  (e.g. the 0.2 → 0.3 removal of the 57 deprecated legacy single-purpose MCP
+  tools in favor of their composite replacements). Every breaking change in
+  a minor needs a `### Breaking` CHANGELOG entry naming the replacement —
+  see the release-blocker gate below.
 - Major (`0.x → 1.0`): production-stability commitment.
 
 CLAUDE.md rule #5 (CanvasStateManager / PmxCanvas SDK / HTTP / MCP
@@ -70,6 +74,11 @@ Each release section uses these subheadings:
   command/flag, SDK export, JSON shape).
 - **Changed** — behavior changes that aren't strictly bug fixes
   (response shape additions, schema cleanups, stricter validation).
+- **Breaking** — removed or incompatibly changed public surface (see
+  `docs/api-stability.md`). Required at minor version boundaries whenever a
+  public surface breaks; must name the replacement.
+- **Deprecated** — public surface marked for removal in a future minor,
+  per the `docs/api-stability.md` deprecation policy.
 - **Fixed** — bug fixes.
 - **Internal** — refactors, test additions, docs that don't affect
   the public surface.
@@ -78,6 +87,12 @@ Don't ship a release without a CHANGELOG entry. The GitHub release
 notes file (`/tmp/pmx-canvas-vX.Y.Z-release-notes.md` by convention)
 expands on the CHANGELOG with examples and migration notes.
 
+**Release-blocker gate:** a breaking change without a `### Breaking`
+CHANGELOG entry blocks the release (`docs/api-stability.md`). Check the
+diff against the previous tag for removed/renamed public surface — MCP
+tool names, HTTP routes, SDK exports, CLI flags — before tagging; if
+anything broke and isn't named under `### Breaking`, add the entry first.
+
 ## Tag → publish
 
 The publish workflow ([`/.github/workflows/publish.yml`](../.github/workflows/publish.yml))

package/docs/ax-host-adapter-contract.md

@@ -20,9 +20,9 @@ surface each one binds to.
 | Adapter method | PMX surface (owned) | Harness-owned part |
 | --- | --- | --- |
 | `pullContext()` | `GET /api/canvas/ax/context?consumer=<id>` · `canvas://ax-context` — full board **plus** a compact `delivery` lead block | When/where to inject it into the model's turn |
-| `deliverSteer()` | `GET /api/canvas/ax/delivery/pending?consumer=<id>` · `canvas_claim_ax_delivery` → act → `POST …/delivery/<id>/mark` · `canvas_mark_ax_delivery` | Calling the host's native send/wake |
+| `deliverSteer()` | `GET /api/canvas/ax/delivery/pending?consumer=<id>` · `canvas_ax_delivery { action: "claim" }` → act → `POST …/delivery/<id>/mark` · `canvas_ax_delivery { action: "mark" }` | Calling the host's native send/wake |
 | `ingestActivity(event)` | `POST /api/canvas/ax/activity` · `canvas_ingest_activity` — board auto-reacts | Forwarding the host's tool/session hooks |
-| `awaitGate(id)` | `GET /api/canvas/ax/{approval\|elicitation\|mode}/<id>?waitMs=` · `canvas_await_*` | Optionally surfacing a native modal; the agent must await PMX |
+| `awaitGate(id)` | `GET /api/canvas/ax/{approval\|elicitation\|mode}/<id>?waitMs=` · `canvas_ax_gate { kind: "approval"\|"elicitation"\|"mode", action: "await" }` | Optionally surfacing a native modal; the agent must await PMX |
 | `mirrorLog(event)` *(optional)* | `GET /api/canvas/ax/timeline` · `canvas://ax-timeline` | Writing AX events into the host's own chat/session log |
 
 ## Steering is gated, not pushed (#54)
@@ -37,8 +37,8 @@ message; it does **not** wake the agent. It reaches the next turn only when:
 2. **A human message fires the turn.** A sandbox button click cannot itself create a
    new agent turn (an app-platform constraint). Any human prompt triggers the injection.
 3. **The agent acts, then acks.** Injected `pendingSteering` / `pendingActivity` is
-   *to-do*, not narration: act on it, then `canvas_mark_ax_delivery` the steering
-   (or resolve the work item / gate). Until acked, steering re-injects every gated turn.
+   *to-do*, not narration: act on it, then `canvas_ax_delivery { action: "mark" }`
+   the steering (or resolve the work item / gate). Until acked, steering re-injects every gated turn.
 
 The `delivery` lead block (`GET /api/canvas/ax/context?consumer=<id>`) is the
 robustness hedge: it's compact and sits above the full dump, so an adapter can inject
@@ -69,9 +69,9 @@ turn"), never imply it interrupts the agent now.
   tool becomes a blocked work item + a review finding + evidence without the agent
   remembering to push it. Reactions are kind-driven and overridable per call.
 - **Blocking gates (gates that actually gate).** Before, an approval gate was inert
-  data the agent had to poll. With `canvas_await_approval` (and the `?waitMs` HTTP
-  long-poll), the agent requests a gate then *blocks* until the human resolves it in
-  the browser — real human-in-the-loop control on any harness.
+  data the agent had to poll. With `canvas_ax_gate { kind: "approval", action: "await" }`
+  (and the `?waitMs` HTTP long-poll), the agent requests a gate then *blocks* until the
+  human resolves it in the browser — real human-in-the-loop control on any harness.
 
 ## What stays harness-owned
 

package/docs/ax-state-contract.md

@@ -6,7 +6,7 @@ snapshot-vs-audit boundary; it is the documented module boundary for
 `AxStateManager` (`src/server/ax-state-manager.ts`), which `CanvasStateManager`
 holds and delegates to.
 
-| Partition | Members | Storage | Snapshotted | Cleared by `canvas_clear` | Cleared by `restore` |
+| Partition | Members | Storage | Snapshotted | Cleared by `canvas_view { action: "clear" }` | Cleared by `restore` |
 |-----------|---------|---------|:-----------:|:-------------------------:|:--------------------:|
 | **Canvas-bound** | `focus`, `workItems`, `approvalGates`, `reviewAnnotations`, `elicitations`, `modeRequests`, `policy` | in-memory `_axState` + one JSON blob in the `ax_state` table | ✅ | ✅ | ✅ (replaced by the snapshot's AX) |
 | **Timeline (audit-only)** | `agent-event`, `evidence-item`, `steering-message` | `ax_events` / `ax_evidence` / `ax_steering` tables, 500-row retention, sequential ids | ❌ | ❌ | ❌ |
@@ -15,14 +15,15 @@ holds and delegates to.
 **Rules.** Canvas-bound state travels with the canvas (snapshot / restore / clear);
 timeline and host data are diagnostic and survive all three. Timeline rows are
 append-only, retention-bounded (`AX_TIMELINE_RETENTION = 500` per table), and
-read via `canvas_get_ax_timeline` / `canvas://ax-timeline`. The host-capability
-row is reported by adapters and read via `canvas_get_ax`.
+read via `canvas_ax_timeline { action: "read" }` / `canvas://ax-timeline`. The
+host-capability row is reported by adapters and read via `canvas_ax_state {
+action: "get" }`.
 
 ## Read surfaces
 
-- **Canvas-bound:** `canvas_get_ax`, `canvas://ax`, `canvas://ax-context`, `canvas://ax-work`
-- **Timeline:** `canvas_get_ax_timeline`, `canvas://ax-timeline`, `canvas://ax-pending-steering`, `canvas://ax-delivery`
-- **Host:** `canvas_get_ax`
+- **Canvas-bound:** `canvas_ax_state { action: "get" }`, `canvas://ax`, `canvas://ax-context`, `canvas://ax-work`
+- **Timeline:** `canvas_ax_timeline { action: "read" }`, `canvas://ax-timeline`, `canvas://ax-pending-steering`, `canvas://ax-delivery`
+- **Host:** `canvas_ax_state { action: "get" }`
 
 ## Node-deletion semantics (soft-orphan + audit)
 

package/docs/bun-webview-integration.md

@@ -144,11 +144,11 @@ These flags are intentionally automation-only. They do **not** imply a visible B
 
 Implemented in [`src/mcp/server.ts`](../src/mcp/server.ts):
 
-- `canvas_webview_status`
-- `canvas_webview_start`
-- `canvas_webview_stop`
-- `canvas_evaluate`
-- `canvas_resize`
+- `canvas_webview { action: "status" }`
+- `canvas_webview { action: "start" }`
+- `canvas_webview { action: "stop" }`
+- `canvas_webview { action: "evaluate" }`
+- `canvas_webview { action: "resize" }`
 - `canvas_screenshot`
 
 Current MCP behavior:

package/docs/cli.md

@@ -217,7 +217,7 @@ take a screenshot when the drawn form matters.
 
 Humans draw with the pen toolbar button and remove marks with the eraser button.
 If an agent already knows the annotation ID from context, it can remove it through
-MCP with `canvas_remove_annotation`.
+MCP with `canvas_view { action: "remove-annotation", id }`.
 
 ## When to reach for the CLI
 

package/docs/http-api.md

@@ -3,14 +3,18 @@
 REST endpoints for all canvas operations + an SSE event stream. Works from
 any language. Default base URL: `http://localhost:4313`.
 
+A non-empty request body that is not valid JSON returns
+`400 { "ok": false, "error": "Malformed JSON body." }` on every route; empty
+bodies are treated as an empty request.
+
 ## Canvas state
 
 ```bash
 # Get canvas state
 curl http://localhost:4313/api/canvas/state
 
-# Search nodes
-curl "http://localhost:4313/api/canvas/search?q=auth"
+# Search nodes (optional limit= caps the result count)
+curl "http://localhost:4313/api/canvas/search?q=auth&limit=10"
 
 # Validate the current layout
 curl http://localhost:4313/api/canvas/validate
@@ -133,7 +137,7 @@ Host-agnostic agent-experience primitives across three state partitions.
 Canvas-bound state (work items, approval gates, review annotations) rides
 canvas snapshots; timeline state (events, evidence, steering) persists for
 diagnostics but is retention-bounded and not restored by snapshots; the host
-capability is reported by adapters and survives `canvas_clear`.
+capability is reported by adapters and survives `canvas_view { action: "clear" }`.
 
 ```bash
 # Timeline — record a normalized agent-event

package/docs/mcp.md

@@ -1,17 +1,19 @@
 # MCP reference
 
-PMX Canvas ships an MCP stdio server with **84 tools** + **14 core resources**,
+PMX Canvas ships an MCP stdio server with **27 tools** + **14 core resources**,
 plus per-skill resources at `canvas://skills/<name>`. The server emits
 `notifications/resources/updated` when canvas state changes — humans pin
 nodes in the browser, agents are notified immediately.
 
-> **Consolidation in progress (plan-006/008).** The 84 tools are 15 action-discriminated
-> **composites** (recommended — see below) plus 69 legacy single-purpose tools.
-> The composites fold the legacy tools behind an `action` (and, for `canvas_ax_gate`,
-> a `kind`) enum; each action dispatches to the same operation, so behavior is
-> identical. Folded legacy tools are marked `Deprecated:` in their descriptions and
-> are removed in v0.3 per [`api-stability.md`](api-stability.md). **Prefer the
-> composites.**
+> **Consolidation completed in v0.3.0 (plan-006/008).** The MCP surface shrank
+> from 84 tools to 27: 15 action-discriminated **composites** (recommended —
+> see below) plus 12 standalone tools. The 57 legacy single-purpose tools that
+> the composites replaced were removed in v0.3.0 per
+> [`api-stability.md`](api-stability.md); their descriptions carried
+> `Deprecated:` prefixes for one minor before removal. The 6 snapshot tools
+> remain registered as deprecated standalones — they fold into a
+> `canvas_snapshot` composite in v0.4 (see [Standalone tools](#standalone-tools)
+> below). **Prefer the composites.**
 
 ## Connect
 
@@ -35,15 +37,15 @@ The canvas auto-starts on first tool call.
 Action-discriminated tools that consolidate the single-purpose tools. Each maps
 its `action` to the same operation the legacy tool used, so results are identical.
 
-| Composite | `action` values | Replaces |
+| Composite | `action` values | Replaced (removed in v0.3.0) |
 |-----------|-----------------|----------|
 | `canvas_node` | `add` · `get` · `update` · `remove` | `canvas_add_node`, `canvas_get_node`, `canvas_update_node`, `canvas_remove_node`, `canvas_add_html_node` (`add` + `type:"html"`), `canvas_add_html_primitive` (`add` + `type:"html"`, `primitive:"<kind>"`), `canvas_refresh_webpage_node` (`update` + `refresh:true`) |
 | `canvas_render` | `describe-schema` · `validate` · `add-json-render` · `stream-json-render` · `add-graph` | `canvas_describe_schema`, `canvas_validate_spec`, `canvas_add_json_render_node`, `canvas_stream_json_render_node`, `canvas_add_graph_node` |
 | `canvas_edge` | `add` · `remove` | `canvas_add_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` | `canvas_arrange`, `canvas_focus_node`, `canvas_fit_view`, `canvas_clear` |
-| `canvas_query` | `search` · `layout` | `canvas_search`, `canvas_get_layout` |
+| `canvas_view` | `arrange` · `focus` · `fit` · `clear` · `remove-annotation` | `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` |
 | `canvas_ax_state` | `get` · `set-focus` · `set-policy` · `report-capability` | `canvas_get_ax`, `canvas_set_ax_focus`, `canvas_set_ax_policy`, `canvas_report_host_capability` |
@@ -64,7 +66,7 @@ veto it — before the mutation lands.
 - `clear` — abandon/dissolve it explicitly. Normal linked mutations settle automatically.
 
 Intents are **ephemeral presence**: never persisted, never snapshotted, never in
-`canvas_get_layout`, and auto-expiring. They ride their own SSE channel
+`canvas_query { action: "layout" }`, and auto-expiring. They ride their own SSE channel
 (`ax-intent` / `ax-intent-clear`) and replay to reconnecting browsers while still
 live. Best practice — narrate your next move: `signal` → mutate with the returned
 `intent.id` as `intentId`. A vetoed or expired linked mutation is rejected, and a
@@ -87,86 +89,105 @@ tools). `canvas_screenshot` also stays standalone — it returns a binary image
 the composite/registry JSON wire shape does not model. (Wave 5 folded
 `canvas_refresh_webpage_node` → `canvas_node { action: "update", refresh: true }` after
 fixing `node.update`'s `formatResult` to surface a FAILED refresh as `isError` +
-`{ ok:false, error }` instead of masking it as a false `{ ok:true }`.) Snapshots
-fold as their registry slice lands.
+`{ ok:false, error }` instead of masking it as a false `{ ok:true }`.) The 6
+snapshot tools are the one deferred fold: a `canvas_snapshot` composite is
+planned for v0.4 (the name collides with the legacy `canvas_snapshot` save
+tool, and [`api-stability.md`](api-stability.md) requires deprecating a tool
+for one minor before removing it) — they stay registered as deprecated
+standalones until then.
 
-## Tools (legacy single-purpose)
+## Standalone tools
+
+12 tools that intentionally stay outside the composites — either because
+folding them would hurt (distinct callers, binary payloads, trust-boundary or
+execution-intent semantics), or because they're mid-deprecation pending a
+v0.4 composite. See [Migration reference](#migration-reference) below for the
+57 tools these composites replaced.
 
 | Tool | Description |
 |------|-------------|
-| `canvas_add_node` | Add a node (markdown, status, context, file, webpage, html, etc.) |
-| `canvas_add_html_node` | **Deprecated** → `canvas_node { action: "add", type: "html" }`. Create an `html` node from a self-contained HTML/JS document (sandboxed iframe) |
-| `canvas_add_html_primitive` | **Deprecated** → `canvas_node { action: "add", type: "html", primitive: "<kind>" }`. Create a reusable generated HTML communication primitive as a sandboxed `html` node |
-| `canvas_add_diagram` | Hand-drawn diagram via the hosted Excalidraw MCP App (preset alias for `canvas_open_mcp_app`) |
-| `canvas_open_mcp_app` | Open any [MCP Apps](https://modelcontextprotocol.io/docs/extensions/apps) server's `ui://` resource as an iframe node |
-| `canvas_describe_schema` | Describe the running server's create schemas, examples, json-render catalog, and HTML primitive catalog |
-| `canvas_validate_spec` | Validate a json-render spec, graph payload, or HTML primitive payload without creating a node |
-| `canvas_refresh_webpage_node` | **Deprecated** → `canvas_node { action: "update", refresh: true }`. Re-fetch and update a webpage node from its stored URL |
-| `canvas_add_json_render_node` | Create a native json-render node from a validated spec |
-| `canvas_stream_json_render_node` | Progressively build a json-render node from SpecStream JSON-Patch ops (live/streaming panels) |
-| `canvas_add_graph_node` | Create a native graph node (line, bar, pie, area, scatter, radar, stacked-bar, composed, sparkline, dot-plot, bullet, slopegraph) |
-| `canvas_build_web_artifact` | Build a bundled HTML artifact and open it on the canvas |
-
-`canvas_add_html_node` accepts optional `summary`, `agentSummary`, `embeddedNodeIds`, and
-`embeddedUrls`. PMX also derives a bounded text summary from visible HTML, so rich HTML nodes stay
-searchable and readable in pinned/spatial context.
-| `canvas_update_node` | Update content, position, size, collapsed state |
-| `canvas_remove_node` | Remove a node and its edges |
-| `canvas_get_layout` | Get full canvas state |
-| `canvas_get_node` | Get a single node by ID |
-| `canvas_remove_annotation` | Remove a human-drawn annotation by ID |
-| `canvas_add_edge` | Connect two nodes |
-| `canvas_remove_edge` | Remove a connection |
-| `canvas_arrange` | Auto-arrange (grid/column/flow) |
-| `canvas_validate` | Validate collisions, containment, and missing edge endpoints |
-| `canvas_focus_node` | Pan viewport to a node; use CLI `focus --no-pan` when you only need to select/raise |
-| `canvas_fit_view` | Fit the canvas viewport to all nodes or a selected subset |
-| `canvas_get_ax` | Read the PMX AX state (focus, work items, approvals, review annotations, host capability) plus pinned/focused context |
-| `canvas_set_ax_focus` | Set the host-agnostic AX focus node set; adapters can pass a source such as `codex` |
-| `canvas_record_ax_event` | Record a normalized timeline `agent-event` (prompt/assistant-message/tool-start/tool-result/failure/approval/steering) |
-| `canvas_send_steering` | Record a `steering-message`: a user instruction from the surface to the active agent session |
-| `canvas_get_ax_timeline` | Read the bounded AX timeline (events, evidence, steering) plus counts |
-| `canvas_add_work_item` | Add a canvas-bound `work-item` (visible task/plan/status tied to nodes) |
-| `canvas_update_work_item` | Update a work item's title/status/detail/nodeIds by ID |
-| `canvas_request_approval` | Request human approval via an `approval-gate` (pending) before a high-impact action |
-| `canvas_resolve_approval` | Resolve a pending approval gate (`approved`/`rejected`) |
-| `canvas_add_evidence` | Record an `evidence-item` on the timeline (logs/tool-result/screenshot/file/diff/test-output) |
-| `canvas_add_review_annotation` | Add a canvas-bound `review-annotation` (comment/finding) anchored to a node, file, or region |
-| `canvas_report_host_capability` | Report a host/session `host-capability` for diagnostics |
+| `canvas_batch` | Run a batch of canvas operations with `$ref` support |
+| `canvas_pin_nodes` | Pin nodes to include in agent context |
+| `canvas_invoke_command` | Invoke a registry command (`pmx.plan`, `pmx.execute`, `pmx.promote-context`, `pmx.summarize`, `pmx.review`); records a `command` agent-event, unknown names rejected |
 | `canvas_ax_interaction` | Submit one capability-gated AX interaction envelope (`{ type, sourceNodeId, payload }`) that maps onto an AX operation; the server re-validates and clamps sandboxed surfaces to their own node |
-| `canvas_claim_ax_delivery` | Claim undelivered steering messages for an adapterless consumer (loop-safe — never returns steering the consumer originated) |
-| `canvas_mark_ax_delivery` | Mark a steering message delivered for a consumer |
-| `canvas_request_elicitation` | Request structured human input via a canvas-bound `elicitation` (pending) |
-| `canvas_respond_elicitation` | Respond to / resolve a pending elicitation |
-| `canvas_request_mode` | Request a workflow `mode-request` transition (plan/execute/autonomous) |
-| `canvas_resolve_mode` | Resolve a pending mode request |
 | `canvas_ingest_activity` | Ingest a harness-forwarded agent activity (tool/session event); the board auto-reacts with kind-driven, overridable defaults (failure → work item + review + evidence; `tool-result`+success → evidence). Makes AX bidirectional |
-| `canvas_await_approval` | Block until an approval gate resolves (human approves/rejects in the browser) or the timeout elapses (`timeoutMs` 0 = immediate read). Gates that actually gate |
-| `canvas_await_elicitation` | Block until an elicitation is answered or the timeout elapses |
-| `canvas_await_mode` | Block until a mode request resolves or the timeout elapses |
-| `canvas_invoke_command` | Invoke a registry command (`pmx.plan`, `pmx.execute`, `pmx.promote-context`, `pmx.summarize`, `pmx.review`); records a `command` agent-event, unknown names rejected |
-| `canvas_set_ax_policy` | Patch the canvas-bound tool/prompt policy (`tools.allowed\|excluded\|approvalRequired`, `prompt.systemAppend\|mode`); patches merge and are normalized |
-| `canvas_pin_nodes` | Pin nodes to include in agent context |
-| `canvas_clear` | Clear all nodes and edges |
-| `canvas_snapshot` | Save current canvas as a named snapshot |
-| `canvas_list_snapshots` | List saved snapshots, bounded to the newest 20 by default |
-| `canvas_gc_snapshots` | Delete old snapshots while keeping the newest N |
-| `canvas_restore` | Restore canvas from a saved snapshot |
-| `canvas_delete_snapshot` | Delete a saved snapshot |
-| `canvas_search` | Find nodes by title/content keywords |
-| `canvas_undo` | Undo the last canvas mutation |
-| `canvas_redo` | Redo the last undone mutation |
-| `canvas_diff` | Compare current canvas vs a saved snapshot |
-| `canvas_create_group` | Create a group containing specified nodes |
-| `canvas_group_nodes` | Add nodes to an existing group |
-| `canvas_ungroup` | Release all children from a group |
-| `canvas_batch` | Run a batch of canvas operations with `$ref` support |
-| `canvas_webview_status` | Get Bun.WebView automation status for the workbench |
-| `canvas_webview_start` | Start or replace the Bun.WebView automation session |
-| `canvas_webview_stop` | Stop the active Bun.WebView automation session |
-| `canvas_evaluate` | Evaluate JavaScript in the active workbench automation session |
-| `canvas_resize` | Resize the active workbench automation viewport |
 | `canvas_screenshot` | Capture a screenshot from the active workbench automation session |
+| `canvas_snapshot` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). Save current canvas as a named snapshot |
+| `canvas_list_snapshots` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). List saved snapshots, bounded to the newest 20 by default |
+| `canvas_restore` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). Restore canvas from a saved snapshot |
+| `canvas_delete_snapshot` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). Delete a saved snapshot |
+| `canvas_gc_snapshots` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). Delete old snapshots while keeping the newest N |
+| `canvas_diff` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). Compare current canvas vs a saved snapshot |
+
+`canvas_node { action: "add", type: "html" }` accepts optional `summary`, `agentSummary`,
+`embeddedNodeIds`, and `embeddedUrls`. PMX also derives a bounded text summary from visible
+HTML, so rich HTML nodes stay searchable and readable in pinned/spatial context.
+
+## Migration reference
+
+The 57 legacy single-purpose tools below were removed in v0.3.0. Each row is
+the composite call that replaces it — kept as a lookup table for anyone
+migrating an older integration.
+
+| Removed tool | Composite replacement |
+|------|-------------|
+| `canvas_add_node` | `canvas_node { action: "add" }` |
+| `canvas_get_node` | `canvas_node { action: "get" }` |
+| `canvas_update_node` | `canvas_node { action: "update" }` |
+| `canvas_remove_node` | `canvas_node { action: "remove" }` |
+| `canvas_add_html_node` | `canvas_node { action: "add", type: "html" }` |
+| `canvas_add_html_primitive` | `canvas_node { action: "add", type: "html", primitive: "<kind>" }` |
+| `canvas_refresh_webpage_node` | `canvas_node { action: "update", refresh: true }` |
+| `canvas_describe_schema` | `canvas_render { action: "describe-schema" }` |
+| `canvas_validate_spec` | `canvas_render { action: "validate" }` |
+| `canvas_add_json_render_node` | `canvas_render { action: "add-json-render" }` |
+| `canvas_stream_json_render_node` | `canvas_render { action: "stream-json-render" }` |
+| `canvas_add_graph_node` | `canvas_render { action: "add-graph" }` |
+| `canvas_add_edge` | `canvas_edge { action: "add" }` |
+| `canvas_remove_edge` | `canvas_edge { action: "remove" }` |
+| `canvas_create_group` | `canvas_group { action: "create" }` |
+| `canvas_group_nodes` | `canvas_group { action: "add" }` |
+| `canvas_ungroup` | `canvas_group { action: "ungroup" }` |
+| `canvas_undo` | `canvas_history { action: "undo" }` |
+| `canvas_redo` | `canvas_history { action: "redo" }` |
+| `canvas_arrange` | `canvas_view { action: "arrange" }` |
+| `canvas_focus_node` | `canvas_view { action: "focus" }` |
+| `canvas_fit_view` | `canvas_view { action: "fit" }` |
+| `canvas_clear` | `canvas_view { action: "clear" }` |
+| `canvas_remove_annotation` | `canvas_view { action: "remove-annotation" }` |
+| `canvas_search` | `canvas_query { action: "search" }` |
+| `canvas_get_layout` | `canvas_query { action: "layout" }` |
+| `canvas_validate` | `canvas_query { action: "validate" }` |
+| `canvas_open_mcp_app` | `canvas_app { action: "open-mcp-app" }` |
+| `canvas_add_diagram` | `canvas_app { action: "diagram" }` |
+| `canvas_build_web_artifact` | `canvas_app { action: "build-artifact" }` |
+| `canvas_webview_status` | `canvas_webview { action: "status" }` |
+| `canvas_webview_start` | `canvas_webview { action: "start" }` |
+| `canvas_webview_stop` | `canvas_webview { action: "stop" }` |
+| `canvas_resize` | `canvas_webview { action: "resize" }` |
+| `canvas_evaluate` | `canvas_webview { action: "evaluate" }` |
+| `canvas_get_ax` | `canvas_ax_state { action: "get" }` |
+| `canvas_set_ax_focus` | `canvas_ax_state { action: "set-focus" }` |
+| `canvas_set_ax_policy` | `canvas_ax_state { action: "set-policy" }` |
+| `canvas_report_host_capability` | `canvas_ax_state { action: "report-capability" }` |
+| `canvas_add_work_item` | `canvas_ax_work { action: "add" }` |
+| `canvas_update_work_item` | `canvas_ax_work { action: "update" }` |
+| `canvas_add_review_annotation` | `canvas_ax_work { action: "annotate" }` |
+| `canvas_request_approval` | `canvas_ax_gate { kind: "approval", action: "request" }` |
+| `canvas_resolve_approval` | `canvas_ax_gate { kind: "approval", action: "resolve" }` |
+| `canvas_await_approval` | `canvas_ax_gate { kind: "approval", action: "await" }` |
+| `canvas_request_elicitation` | `canvas_ax_gate { kind: "elicitation", action: "request" }` |
+| `canvas_respond_elicitation` | `canvas_ax_gate { kind: "elicitation", action: "resolve" }` |
+| `canvas_await_elicitation` | `canvas_ax_gate { kind: "elicitation", action: "await" }` |
+| `canvas_request_mode` | `canvas_ax_gate { kind: "mode", action: "request" }` |
+| `canvas_resolve_mode` | `canvas_ax_gate { kind: "mode", action: "resolve" }` |
+| `canvas_await_mode` | `canvas_ax_gate { kind: "mode", action: "await" }` |
+| `canvas_get_ax_timeline` | `canvas_ax_timeline { action: "read" }` |
+| `canvas_record_ax_event` | `canvas_ax_timeline { action: "record-event" }` |
+| `canvas_add_evidence` | `canvas_ax_timeline { action: "add-evidence" }` |
+| `canvas_send_steering` | `canvas_ax_timeline { action: "send-steering" }` |
+| `canvas_claim_ax_delivery` | `canvas_ax_delivery { action: "claim" }` |
+| `canvas_mark_ax_delivery` | `canvas_ax_delivery { action: "mark" }` |
 
 ## Resources
 
@@ -255,27 +276,27 @@ raw stroke geometry or visual shape.
 
 Annotations are a browser-visible markup layer. Use the pen toolbar button to
 draw and the eraser toolbar button to remove an annotation again; agents can also
-remove a known annotation ID with `canvas_remove_annotation`.
+remove a known annotation ID with `canvas_view { action: "remove-annotation", id }`.
 
 Use WebView automation when an agent needs to actually see annotations as drawn.
-For example, inspect `.annotation-layer path` with `canvas_evaluate` or capture a
-`canvas_screenshot` to distinguish an arrow from a line, circle, or highlight.
+For example, inspect `.annotation-layer path` with `canvas_webview { action: "evaluate" }`
+or capture a `canvas_screenshot` to distinguish an arrow from a line, circle, or highlight.
 
 ## Node-type routing
 
-MCP node creation uses dedicated tools for structured node families. Read
-`mcp.nodeTypeRouting` from `canvas_describe_schema` / `canvas://schema` when
-in doubt:
-
-- `json-render` → `canvas_add_json_render_node`
-- `graph` → `canvas_add_graph_node`
-- `html-primitive` → `canvas_node { action: "add", type: "html", primitive: "<kind>" }` (or the deprecated `canvas_add_html_primitive`)
-- `html` → `canvas_node { action: "add", type: "html" }` (or the deprecated `canvas_add_html_node`)
-- `web-artifact` → `canvas_build_web_artifact`
-- `mcp-app` → `canvas_open_mcp_app`
-- `group` → `canvas_create_group`
+MCP node creation uses dedicated composite actions for structured node
+families. Read `mcp.nodeTypeRouting` from `canvas_render { action:
+"describe-schema" }` / `canvas://schema` when in doubt:
+
+- `json-render` → `canvas_render { action: "add-json-render" }`
+- `graph` → `canvas_render { action: "add-graph" }`
+- `html-primitive` → `canvas_node { action: "add", type: "html", primitive: "<kind>" }`
+- `html` → `canvas_node { action: "add", type: "html" }`
+- `web-artifact` → `canvas_app { action: "build-artifact" }`
+- `mcp-app` → `canvas_app { action: "open-mcp-app" }`
+- `group` → `canvas_group { action: "create" }`
 - Basic nodes (`markdown`, `status`, `file`, `image`, `webpage`) →
-  `canvas_add_node`
+  `canvas_node { action: "add" }`
 
 ## CLI/MCP alignment