pmx-canvas 0.1.36 → 0.2.1

package/CHANGELOG.md

@@ -5,6 +5,451 @@ All notable changes to `pmx-canvas` are documented here. This project follows
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-06-17
+
+### Fixed
+
+- **Compact AX context surfaces the NEWEST steering first (report #57).** The
+  `delivery.pendingSteering` lead block on `GET /api/canvas/ax/context` /
+  `canvas://ax-context` returned the OLDEST 10 undelivered steers, so on a long-lived
+  board a fresh steer was buried behind old unacked ones and never appeared in the
+  compact block. It now returns the **newest** undelivered steering first (capped at
+  10), so a fresh steer is always visible. The FIFO claim/ack delivery queue
+  (`/api/canvas/ax/delivery/pending`, `canvas_ax_delivery { action: "claim" }`) is
+  unchanged — still oldest-first for ordered processing.
+
+### Added
+
+- **AX context delivery backlog counts (report #57).** `delivery` now includes
+  `totalPending` (undelivered steering for the consumer, loop-safe) and `omittedPending`
+  (`= totalPending − pendingSteering.length`), so an agent can tell the compact block
+  omitted a backlog and drain the full FIFO queue when `omittedPending > 0`. Additive,
+  non-breaking.
+- **Blessed AX HTML Control Surface recipe (report #60).** New
+  `skills/pmx-canvas/references/ax-html-control-surface.md` (linked from `SKILL.md`): a
+  copy-paste-safe template (awaited `emit` + live ack display + `pmx-ax-update`
+  reflection) plus the three footguns that make a hand-rolled AX node look inert — the
+  sandboxed opaque-origin iframe throws on `localStorage`/`sessionStorage`/cookies,
+  `emit` must be awaited, and `ax.steer` is recorded (queued), not delivered.
+
+### Docs
+
+- **Canvas-origin steering does not wake the active agent by itself (report #59).** The
+  host-adapter contract, `SKILL.md`, and the GitHub Copilot adapter reference now state
+  plainly that a browser-origin `ax.steer` (and its `ok:true` emit ack) is *queued*, not
+  pushed into the live session; the wake is host-adapter-owned (drain
+  `canvas_ax_delivery { action: "claim" }` → native send → `mark`), and a steering button
+  must be labeled "queued for the agent's next turn." Adapters should read steering from
+  the compact `delivery.pendingSteering` block, not `timeline.pendingSteering`.
+
+## [0.2.0] - 2026-06-16
+
+### Breaking
+
+Per [`docs/api-stability.md`](docs/api-stability.md), v0.2.0 is the first minor
+allowed to change public-surface behavior, and every such change is collected here.
+All are **cross-surface unifications** — a surface that silently diverged from the
+others is brought into line, never a new restriction invented for this release. The
+detailed per-slice rationale is under **Changed**. MCP tool *names* + input *schemas*,
+HTTP routes + documented success shapes, and CLI flags are all unchanged (frozen by
+`tests/unit/mcp-tool-freeze.test.ts`).
+
+- **SDK `PmxCanvas.removeNode(id)` now throws `Node "<id>" not found.` on an unknown
+  id** instead of silently succeeding — matching the HTTP `DELETE` (already 404) and
+  local MCP `canvas_remove_node`. Idempotent-delete callers must guard or catch.
+- **Local (in-process) MCP error surfacing now matches HTTP for missing targets:**
+  `canvas_remove_node`, `canvas_remove_edge`, `canvas_create_group` (missing child ids),
+  `canvas_focus_node`, and `canvas_ungroup` now return an MCP error result (were silent
+  success / a different message).
+- **MCP `*_resolve` / `*_respond` / `update_work_item` / review `update` /
+  `invoke_command` now return an `isError` result** (not a success-shaped
+  `{ ok:false, <item>:null }`) when the target is missing, already resolved, or an
+  unknown command. Success shapes are unchanged.
+- **AX blocking-gate await over a *remote* MCP transport** surfaces a missing gate as an
+  `isError` rather than `{ <gate>:null }` (the in-process path is unchanged). The HTTP
+  single-gate read keeps its 404 status but its missing-gate body changed to
+  `{ ok:false, <gate>:null, pending:false }`, and it no longer aborts the long-poll on
+  client disconnect (it runs to its ≤120 s timeout).
+- **`canvas_batch` entries now inherit each operation's validation** (they dispatch
+  through the same registry op as the standalone tools): a `node.add` with no `type`
+  fails the batch (was a silent markdown node), an empty-name `snapshot.save` fails the
+  batch (was `ok:true`), and `node.add type:"html-primitive"` now succeeds (was a
+  batch-only rejection). A batched `node.update` now applies the full HTTP superset
+  (webpage `refresh`, top-level `html`, group `children`). The
+  `{ ok, results, refs, failedIndex?, error? }` envelope itself is unchanged.
+
+### Added
+
+- **AX state isolated into `AxStateManager` (plan-007 Slice A).** The canvas-bound
+  AX state, its mutators/readers, and the timeline-direct ops moved out of the
+  2,498-line `CanvasStateManager` into `src/server/ax-state-manager.ts`;
+  `CanvasStateManager` delegates, so the public surface (SDK/HTTP/MCP) is
+  unchanged. The three-partition snapshot-vs-audit contract is now documented
+  authoritatively in `docs/ax-state-contract.md`.
+
+- **Composite MCP tools (plan-006 MCP tool consolidation, wave 1).** Seven
+  action-discriminated tools fold the single-purpose tools behind a clear
+  `action` enum: `canvas_node` (add/get/update/remove), `canvas_render`
+  (describe-schema/validate/add-json-render/stream-json-render/add-graph),
+  `canvas_edge` (add/remove), `canvas_group` (create/add/ungroup),
+  `canvas_history` (undo/redo), `canvas_view` (arrange/focus/fit/clear), and
+  `canvas_query` (search/layout). Each action dispatches to the same registered
+  operation as its standalone tool — reusing that op's input mapping and result
+  formatting — so behavior is byte-identical (proven by
+  `tests/unit/mcp-composites.test.ts`). Additive: the legacy single-purpose
+  tools keep working and are removed in v0.3 per `docs/api-stability.md`. The
+  public MCP surface grows from 69 to 76 tools (deliberate; see
+  `tests/unit/mcp-tool-freeze.test.ts`). Composites/actions whose targets are
+  not yet registry-backed (`canvas_snapshot`, and the `refresh` /
+  `add-primitive` / `remove-annotation` / board-validation actions) land in later
+  waves as the AX / side-channel registry slices complete.
+
+- **AX composite MCP tools (plan-006 MCP tool consolidation, wave 2 / plan-007
+  Slice C).** Five action-discriminated tools fold the 22 legacy AX tools behind
+  clear enums: `canvas_ax_state` (get/set-focus/set-policy/report-capability),
+  `canvas_ax_work` (add/update/annotate), `canvas_ax_timeline`
+  (read/record-event/add-evidence/send-steering), `canvas_ax_delivery`
+  (claim/mark), and `canvas_ax_gate` — which folds **9 gate tools into 1** via two
+  discriminators `{ kind: approval|elicitation|mode, action: request|resolve|await }`
+  so the request/resolve/await lifecycle finally reads as one tool. Each action
+  dispatches to the same registered AX operation as its standalone tool — reusing
+  that op's input mapping and result formatting — so behavior is byte-identical
+  (proven by `tests/unit/mcp-composites.test.ts`). `canvas_ax_interaction`,
+  `canvas_ingest_activity`, and `canvas_invoke_command` deliberately stay
+  standalone (trust-boundary / firehose / execution-intent tools). Additive: the
+  legacy AX tools keep working and are removed in v0.3 per `docs/api-stability.md`.
+  The public MCP surface grows from 76 to 81 tools (deliberate; see
+  `tests/unit/mcp-tool-freeze.test.ts`).
+
+- **`canvas_webview` composite + the 5 webview ops migrated to the operation
+  registry via runner injection (plan-008 Wave 3).** The five browser-automation
+  tools (`canvas_webview_status`, `canvas_webview_start`, `canvas_webview_stop`,
+  `canvas_resize`, `canvas_evaluate`) are now defined once in
+  `src/server/operations/ops/webview.ts` and shared by HTTP, MCP, and the SDK.
+  The Bun.WebView machinery lives in `server.ts` (which `operations/` must not
+  import), so the runner is **injected** — `src/server/operations/webview-runner.ts`
+  declares a `WebviewRunner` interface + `setWebviewRunner`/`getWebviewRunner`,
+  and `server.ts` wires the real automation functions at module load, exactly
+  mirroring the `setOperationEventEmitter` SSE-emitter injection. The new
+  `canvas_webview` composite folds the five tools behind a `status` / `start` /
+  `stop` / `resize` / `evaluate` action enum; each action dispatches to the same
+  op, so behavior is byte-identical (proven by `tests/unit/mcp-composites.test.ts`).
+  Wire shapes, MCP result shapes, and the `canvas_evaluate` arbitrary-eval trust
+  posture are unchanged. `canvas_screenshot` is deliberately **not** folded — it
+  returns a binary image payload the registry JSON wire shape does not model — and
+  stays a standalone hand-written tool (its `POST /api/workbench/webview/screenshot`
+  route also stays hand-written). The public MCP surface grows from 81 to 82 tools
+  (deliberate; see `tests/unit/mcp-tool-freeze.test.ts`).
+
+- **`canvas_app` composite + the 3 external / built-content tools migrated to the
+  operation registry (plan-008 Wave 4).** `canvas_open_mcp_app`,
+  `canvas_add_diagram`, and `canvas_build_web_artifact` are now defined once in
+  `src/server/operations/ops/app.ts` (ops `mcpapp.open`, `diagram.open`,
+  `webartifact.build`) and shared by HTTP, MCP, and the SDK. They were previously
+  deferred as "poor fits" (stateful external session + custom SSE; long-running
+  build), but they migrate cleanly: `executeOperation` is async (the long-running
+  build fits — the "long-running" caveat is about MCP-client timeouts, not registry
+  fit), and their runtimes are server-independent **domain modules**
+  (`mcp-app-runtime.ts`, `diagram-presets.ts`, `web-artifacts.ts`), not `server.ts`
+  — so the op handlers call them directly, no runner injection. To keep
+  `web-artifacts.ts` server-independent its one `emitPrimaryWorkbenchEvent` call
+  was switched to the already-injected `emitCanvasLayoutUpdate` (canvas-operations'
+  `setCanvasLayoutUpdateEmitter`, wired by `server.ts`). The three ops are
+  `mutates:false`: `mcpapp.open` / `diagram.open` emit `ext-app-open` +
+  `ext-app-result` via `ctx.emit` (byte-identical to the legacy events, fired
+  once); `webartifact.build`'s node creation emits its own `canvas-layout-update`
+  from inside `web-artifacts.ts`. The new `canvas_app` composite folds the three
+  behind an `open-mcp-app` / `diagram` / `build-artifact` action enum; each action
+  dispatches to the same op, so behavior is byte-identical (proven by
+  `tests/unit/mcp-composites.test.ts`). Wire shapes and MCP result shapes are
+  unchanged. The public MCP surface grows from 82 to 83 tools (deliberate; see
+  `tests/unit/mcp-tool-freeze.test.ts`).
+
+### Changed
+
+- **Board validation and annotation removal migrated to the operation registry
+  (plan-008 Wave 1).** `canvas_validate` (board validation, a pure read) and
+  `canvas_remove_annotation` (DELETE-by-id) are now defined once in
+  `src/server/operations/ops/validate.ts` and
+  `src/server/operations/ops/annotation.ts`, shared by HTTP, MCP, and the CLI
+  (legacy hand-written handlers + routes + MCP tool blocks + the orphaned
+  `CanvasAccess.validate` / `CanvasAccess.removeAnnotation` methods deleted; the
+  SDK `PmxCanvas.validate()` / `removeAnnotation()` stay public). Tool names,
+  HTTP routes (`GET /api/canvas/validate`, `DELETE /api/canvas/annotation/:id`),
+  the 404 denial body, MCP result shapes, and the `canvas-layout-update` SSE
+  frame are unchanged. Two new composite actions land additively:
+  `canvas_query` gains `validate` (→ `validate.get`) and `canvas_view` gains
+  `remove-annotation` (→ `annotation.remove`).
+
+- **Batch migrated to the `canvas.batch` registry meta-op (plan-008 Wave 2 —
+  the last and highest-risk registry slice).** `canvas_batch` now dispatches
+  each entry through the shared `executeOperation` path (defined once in
+  `src/server/operations/ops/batch.ts`) instead of a hand-written ~290-line
+  switch in `canvas-operations.ts`, which is deleted along with its
+  `resolveBatchRefs` / `serializeCreatedNode` helpers, the
+  `handleCanvasBatch` HTTP handler + route, and the standalone `canvas_batch`
+  MCP tool block. `executeOperation` gained an internal, depth-counted
+  emit-suppression (`runWithSuppressedEmits`) so the meta-op runs every entry
+  with per-entry SSE frames suppressed and then emits exactly ONE final
+  `canvas-layout-update` — preserving the single-final-frame behavior. The
+  `canvas_batch` tool name, the `{ operations:[...] }` and bare-`[...]` body
+  shapes, per-entry result shapes, and the `{ ok, results, refs, failedIndex?,
+  error? }` envelope are unchanged; per-entry ops record their own undo/redo
+  history as before. The SDK `PmxCanvas.runBatch` stays public and delegates to
+  the meta-op.
+
+- **Deleting a node no longer silently re-anchors AX work (plan-007 Slice A).**
+  Node deletion already re-normalized canvas-bound AX state (work items / approval
+  gates / elicitations / mode requests keep the item but lose the dangling node
+  ref; node-anchored review annotations are dropped) — but did so silently. It now
+  records exactly one auditable timeline event (`kind:'note'`, `source:'system'`,
+  `data.systemEvent:'ax-node-orphan'`) naming what was re-anchored/removed, so the
+  human and a resuming agent can see the change. The note is append-only (not
+  rolled back on undo, not duplicated on redo). See `docs/ax-state-contract.md`.
+
+- **AX state ops migrated to the operation registry (plan-007 Slice B, wave 1).**
+  `canvas_get_ax`, `canvas_set_ax_focus`, `canvas_set_ax_policy`, and
+  `canvas_report_host_capability` are now defined once in
+  `src/server/operations/ops/ax-state.ts` and shared by HTTP, MCP, and the SDK
+  (legacy hand-written handlers + tools + CanvasAccess methods deleted). Tool
+  names, MCP result shapes, SSE frames (`ax-state-changed`), and `source`
+  defaulting are unchanged. One deliberate HTTP expansion: `GET /api/canvas/ax`
+  now returns `{ ok, state, host, context }` (previously `{ ok, state }`) — the
+  registry serves one wire body that the remote-MCP invoker also consumes, so the
+  `canvas_get_ax` aggregate is preserved across local and remote MCP. Additive;
+  existing clients that read `state` are unaffected.
+
+- **AX work / review / gate ops migrated to the operation registry (plan-007
+  Slice B, wave 2).** `canvas_add_work_item`, `canvas_update_work_item`,
+  `canvas_add_review_annotation`, `canvas_request_approval`,
+  `canvas_resolve_approval`, `canvas_request_elicitation`,
+  `canvas_respond_elicitation`, `canvas_request_mode`, `canvas_resolve_mode`
+  (plus the HTTP-only review-annotation update) are now defined once in
+  `src/server/operations/ops/ax-work.ts` (legacy handlers + tools + CanvasAccess
+  methods deleted). Tool names, success wire shapes, denial bodies (and their
+  404/400 status codes), SSE frames, and `source` defaulting are unchanged.
+  Cross-surface unification (same class as plan-005 slices 1–4): the
+  `update`/`resolve`/`respond` MCP tools previously returned a success-shaped
+  `{ ok:false, <item>:null }` on a missing/already-resolved target; they now
+  surface the HTTP 404 as an MCP `isError` result with the same message —
+  success shapes are unchanged.
+
+- **AX timeline / delivery / command ops migrated to the operation registry
+  (plan-007 Slice B, wave 3).** `canvas_record_ax_event`, `canvas_add_evidence`,
+  `canvas_send_steering`, `canvas_get_ax_timeline`, `canvas_claim_ax_delivery`,
+  `canvas_mark_ax_delivery`, and `canvas_invoke_command` are now defined once in
+  `src/server/operations/ops/ax-timeline.ts` (legacy handlers + tools +
+  CanvasAccess methods deleted). Tool names, success wire shapes (`{ ok, event }`,
+  `{ ok, evidence }`, `{ ok, steering }`, the timeline aggregate, `{ ok, delivered }`),
+  the timeline SSE frame (`ax-event-created`, distinct from the wave-1/2
+  `ax-state-changed`), the `delivery.mark` `{ steeringDelivered }` frame (emitted
+  only when a message is actually marked), the loop-safe consumer scoping of
+  `canvas_claim_ax_delivery` (steering + `pendingActivity` both filtered), the
+  command allowlist (unknown name → 400 `Unknown command "…"`), and `source`
+  defaulting are unchanged. Two deliberate unifications: (1) `GET
+  /api/canvas/ax/delivery/pending` now returns `{ ok, pending, pendingActivity }`
+  (previously `{ ok, pending }`) so the one wire body matches the
+  `canvas_claim_ax_delivery` aggregate across local and remote MCP — additive,
+  existing clients reading `pending` are unaffected; (2) `canvas_invoke_command`
+  on an unknown name previously returned a success-shaped `{ ok:false, event:null }`
+  over MCP and now surfaces the HTTP 400 as an MCP `isError` (same class as the
+  wave-2 resolve/respond unification). The legacy `GET /api/canvas/ax/command`
+  registry list, `canvas_ingest_activity`, and `canvas_ax_interaction` remain on
+  the standalone surface (deferred to later waves).
+
+- **AX long-poll gate reads migrated to the operation registry (plan-007 Slice
+  B, wave 4).** `canvas_await_approval`, `canvas_await_elicitation`, and
+  `canvas_await_mode` (the report primitive D "gates that actually gate" reads,
+  HTTP `GET /api/canvas/ax/{approval,elicitation,mode}/:id`) are now defined once
+  in `src/server/operations/ops/ax-await.ts` (legacy MCP tools, HTTP single-read
+  handlers, and the orphaned CanvasAccess `await*` methods deleted; the public
+  SDK `PmxCanvas.await*` methods stay). The async handler performs the wait via
+  `waitForAxResolution` (`status !== 'pending'` resolution predicate for all
+  three, matching the legacy HTTP + SDK). `timeoutMs` is normalized to one field
+  the handler reads: HTTP parses `?waitMs` (absent/non-positive ⇒ 0 = immediate
+  read), MCP defaults an omitted `timeoutMs` to 30000; both clamp to
+  [0, 120000]. Tool names, the `{ <gate>, pending }` success shapes, and the
+  HTTP 404 status on a missing gate are unchanged. Two documented behavior
+  changes, both the plan's accepted long-poll tradeoff: (1) the HTTP handler no
+  longer aborts the wait on client disconnect — the registry handler has no
+  access to the `Request`, so the wait runs to its (≤120s, subscription-based,
+  cheap) timeout instead of honoring `req.signal`; resolution detection,
+  timeout, and the `{ value, pending }` result are otherwise identical. (2) The
+  HTTP missing-gate body changed from `{ ok:false, error:"<gate> not found." }`
+  to `{ ok:false, <gate>:null, pending:false }` (status stays 404) so one wire
+  body serves both surfaces; the in-process (Local) MCP path still round-trips
+  the success-shaped `{ <gate>:null }` JSON exactly as before. (Over a remote
+  MCP transport — untested for these reads — an await-on-missing now surfaces as
+  an `isError` rather than the legacy `{ <gate>:null }`, since the generic
+  HTTP invoker throws on 404.)
+
+- **Removing a missing node now errors on every surface (plan-005 slice 1).**
+  Node CRUD + layout reads (`node.add` / `node.get` / `node.update` /
+  `node.remove` / `layout.get`) are defined once in a new operation registry
+  (`src/server/operations/`) shared by HTTP, MCP, CLI, and the SDK. As part of
+  the unification, `canvas_remove_node` over local (in-process) MCP access and
+  `PmxCanvas.removeNode` no longer silently succeed on an unknown node id —
+  they now report the same `Node "<id>" not found.` error the HTTP DELETE
+  already returned (404). The SDK's `updateNode` also gained the HTTP superset
+  patch semantics (webpage `titleSource`/`url`, html top-level `html` /
+  `axCapabilities`, group `children`), erasing long-standing cross-surface
+  drift. Wire shapes and MCP tool names are unchanged.
+
+- **Edges, arrange/focus/fit/clear, and groups migrated to the operation
+  registry (plan-005 slice 2).** Same unification class as slice 1:
+  `canvas_remove_edge` over local MCP access now errors on a missing edge
+  (remote already did); `canvas_create_group` over local access now rejects
+  missing child ids (HTTP already did); `canvas_focus_node` on a missing node
+  now returns a proper MCP error result; `canvas_ungroup` failure text is now
+  the HTTP message `Group not found or empty.`. Group and focus SSE frames now
+  carry the standard sessionId/timestamp envelope like every other mutation.
+  HTTP paths, wire shapes, and MCP tool names are unchanged.
+
+- **Pins, search, history, undo/redo, and snapshots migrated to the operation
+  registry (plan-005 slice 3).** Same unification class as earlier slices:
+  pin updates are now computed server-side authoritatively; undo/redo over
+  local MCP now use the HTTP emit set; restore/delete/diff on a missing
+  snapshot now return the same error on every surface; percent-encoded
+  snapshot ids now work on DELETE. POST `/api/canvas/context-pins` honors an
+  optional `mode` field (`set`/`add`/`remove`, default `set`). Plain-text
+  legacy snapshot error bodies became the standard `{ ok:false, error }`
+  envelope. HTTP paths, wire shapes, and MCP tool names are unchanged.
+
+- **json-render, graph, streaming, schema, and spec-validation migrated to the
+  operation registry (plan-005 slice 4 / migration item 6).** `jsonrender.add`,
+  `jsonrender.stream`, `graph.add`, `schema.describe`, and `spec.validate` are
+  now defined once and shared by HTTP, MCP, CLI, and the SDK. The frame-height
+  alias triangle (`heightPx` from the SDK, `nodeHeight` over HTTP/MCP, `height`
+  for chart content, plus `size.height`) is absorbed into one schema with a
+  legacy-exact resolution order (`nodeHeight ?? heightPx ?? size.height`). The
+  CLI `node add --type json-render`/`--type graph` and `graph add` commands now
+  route through the registry invoker instead of hand-written `fetch` paths, and
+  the SDK's `streamJsonRenderNode` shares the create-or-append core with the op
+  handler. `spec.validate`'s graph branch now honors the full graph payload
+  surface (previously the HTTP handler silently dropped fields the MCP tool and
+  graph-create route honored). The spec-validation error body keeps its exact
+  `{ ok, error, type }` shape. HTTP paths, wire shapes, and MCP tool names are
+  unchanged.
+
+- **Smaller consolidation behavior changes (surfaced by the v0.2.0 release review,
+  documented here for completeness).** Beyond the slice entries above, the unification
+  also changed a few smaller behaviors: (1) `PmxCanvas.addNode({ type:"html" })` and
+  `canvas_add_node { type:"html" }` *without* an explicit size now default to **720×640**
+  (was 360×200 on those two surfaces — their size ladder lacked an html case; this
+  converges to the documented html default and the dedicated `canvas_add_html_node`).
+  (2) The HTTP `POST /api/canvas/mcp-app/open` and `/api/canvas/diagram` success bodies no
+  longer echo `serverName` / `toolName` (both are caller-supplied inputs and remain on the
+  `ext-app-open` / `ext-app-result` SSE frames; the MCP results were never affected).
+  (3) `webview start`'s `dataStoreDir` is now workspace-sandboxed on the HTTP surface too
+  (out-of-workspace → 400), matching the MCP tool. (4) The batch unsupported-operation
+  error text is now `Unsupported canvas_batch operation "<op>".`. None of these change a
+  frozen tool name, input schema, or documented success response shape.
+
+### Deprecated
+
+- **`canvas_validate` and `canvas_remove_annotation` superseded by composite
+  actions (plan-008 Wave 1).** Both tools now carry a `Deprecated: use canvas_x
+  with action "y".` prefix on their tool description (derived automatically from
+  the composite definitions): `canvas_validate` → `canvas_query` action
+  `validate`; `canvas_remove_annotation` → `canvas_view` action
+  `remove-annotation`. They keep working through v0.2 and are removed in v0.3 per
+  `docs/api-stability.md`.
+
+- **The 5 webview MCP tools superseded by the `canvas_webview` composite
+  (plan-008 Wave 3).** `canvas_webview_status`, `canvas_webview_start`,
+  `canvas_webview_stop`, `canvas_resize`, and `canvas_evaluate` now carry a
+  `Deprecated: use canvas_webview with action "y".` prefix on their tool
+  description (derived automatically from the composite definition):
+  `canvas_webview_status` → action `status`; `canvas_webview_start` → `start`;
+  `canvas_webview_stop` → `stop`; `canvas_resize` → `resize`; `canvas_evaluate`
+  → `evaluate`. They keep working through v0.2 (now registry-served) and are
+  removed in v0.3 per `docs/api-stability.md`. `canvas_screenshot` is NOT
+  deprecated — it stays standalone (binary payload).
+
+- **The 3 external / built-content MCP tools superseded by the `canvas_app`
+  composite (plan-008 Wave 4).** `canvas_open_mcp_app`, `canvas_add_diagram`, and
+  `canvas_build_web_artifact` now carry a `Deprecated: use canvas_app with action
+  "y".` prefix on their tool description (derived automatically from the composite
+  definition): `canvas_open_mcp_app` → action `open-mcp-app`; `canvas_add_diagram`
+  → `diagram`; `canvas_build_web_artifact` → `build-artifact`. They keep working
+  through v0.2 (now registry-served) and are removed in v0.3 per
+  `docs/api-stability.md`.
+
+- **The 3 HTML/webpage MCP tools superseded by `canvas_node` (plan-008 Wave 5 — the
+  final fold).** `canvas_add_html_node` → `canvas_node` with `action: "add"` and
+  `type: "html"`; `canvas_add_html_primitive` → `canvas_node` with `action: "add"`,
+  `type: "html"`, `primitive: "<kind>"` (and `data`); `canvas_refresh_webpage_node`
+  → `canvas_node` with `action: "update"` and `refresh: true`. All three now carry a
+  `Deprecated: use canvas_node …` prefix on their tool description. **No new action,
+  composite mechanism, op, or SDK change was needed** — the earlier plan-008 verdict
+  that a fold required a per-action input-injection mechanism was wrong:
+  `node.add` already routes `type:"html"` + `primitive|kind` → `createHtmlPrimitiveNode`
+  and merges the top-level html fields (`summary`/`agentSummary`/`description`/
+  `presentation`/`slideTitles`/`embeddedNodeIds`/`embeddedUrls`) into the node data,
+  and `node.update` already routes `refresh:true` → `refreshCanvasWebpageNode`. Two
+  small correctness fixes made the fold sound: (a) `axCapabilities` is now **advertised**
+  in `node.add`'s schema (it previously only passed through `z.looseObject`, so
+  schema-guided agents migrating off `canvas_add_html_node` would silently drop the
+  AX-bridge config); (b) `node.update`'s `formatResult` now surfaces a FAILED webpage
+  refresh as `isError` + `{ ok:false, error }` (it previously masked it as a false
+  `{ ok:true }` over the MCP-default local invoker — a live bug), matching the HTTP
+  400 and the legacy tool. Parity (incl. the refresh failure path) is proven by
+  `tests/unit/mcp-composites.test.ts`. All three keep working through v0.2 and are
+  removed in v0.3 per `docs/api-stability.md`.
+
+- **Single-purpose MCP tools superseded by wave-1 composites.** The standalone
+  tools folded by the composites above (`canvas_add_node`, `canvas_get_node`,
+  `canvas_update_node`, `canvas_remove_node`, `canvas_add_edge`,
+  `canvas_remove_edge`, `canvas_arrange`, `canvas_focus_node`, `canvas_fit_view`,
+  `canvas_clear`, `canvas_create_group`, `canvas_group_nodes`, `canvas_ungroup`,
+  `canvas_undo`, `canvas_redo`, `canvas_search`, `canvas_get_layout`,
+  `canvas_add_json_render_node`, `canvas_stream_json_render_node`,
+  `canvas_add_graph_node`, `canvas_describe_schema`, `canvas_validate_spec`) now
+  carry a `Deprecated: use canvas_x with action "y".` prefix on their tool
+  description (derived automatically from the composite definitions). They keep
+  working through v0.2 and are removed in v0.3 per `docs/api-stability.md`.
+
+- **Legacy AX MCP tools superseded by the AX composites (wave 2).** The 22
+  standalone AX tools folded by the composites above now carry a `Deprecated: use
+  canvas_x …` prefix on their tool description (derived automatically from the
+  composite definitions): `canvas_get_ax`, `canvas_set_ax_focus`,
+  `canvas_set_ax_policy`, `canvas_report_host_capability` → `canvas_ax_state`;
+  `canvas_add_work_item`, `canvas_update_work_item`, `canvas_add_review_annotation`
+  → `canvas_ax_work`; `canvas_request_approval`, `canvas_resolve_approval`,
+  `canvas_await_approval`, `canvas_request_elicitation`,
+  `canvas_respond_elicitation`, `canvas_await_elicitation`, `canvas_request_mode`,
+  `canvas_resolve_mode`, `canvas_await_mode` → `canvas_ax_gate` (with kind/action);
+  `canvas_get_ax_timeline`, `canvas_record_ax_event`, `canvas_add_evidence`,
+  `canvas_send_steering` → `canvas_ax_timeline`; `canvas_claim_ax_delivery`,
+  `canvas_mark_ax_delivery` → `canvas_ax_delivery`. They keep working through v0.2
+  and are removed in v0.3 per `docs/api-stability.md`.
+
+### Fixed
+
+- **Webview `evaluate` / `resize` runtime failures return the legacy `400` JSON, not a
+  `500` HTML overlay (v0.2.0 release-review fix).** During the registry migration these
+  ops let the automation runner's plain `Error` (e.g. "no active session") escape
+  `dispatchOperationRoute` (which maps only `OperationError`); with no `Bun.serve`
+  request-level boundary, Bun rendered its dev error overlay — HTTP `500 text/html`
+  disclosing the absolute server source path. The handlers now convert runner failures to
+  the legacy `400 { ok:false, error, webview }` contract, the dispatcher returns a clean
+  JSON `500` for any other unexpected throw, and a `Bun.serve` `error()` boundary
+  guarantees no route can ever render the overlay. Covered by a new no-session regression
+  test.
+- **In-place mcp-app / diagram update preserves the node's existing title (v0.2.0
+  release-review fix).** Re-opening an existing `mcp-app` node in place *without* a
+  `title` no longer resets the node title to the external tool's name — the
+  `ext-app-open` title fallback restores the legacy `targetNode.data.title` step.
+
+- **json-render and graph viewer iframes crashed at mount (blank iframes).**
+  Bun 1.3.14 ignores the `NODE_ENV` define for JSX dev/prod selection when a
+  tsconfig is in scope, so the viewer bundle shipped the dev JSX transform
+  (`jsxDEV`) against production React, which exports it as `undefined`. Every
+  json-render/graph iframe failed with `TypeError: t is not a function`.
+  `scripts/build-json-render.sh` now passes `--production` to `bun build`,
+  forcing the production JSX transform. Caught by the restored Playwright e2e
+  gate (8 tests had been failing silently on main).
+
 ## [0.1.36] - 2026-06-09
 
 ### Added
@@ -1826,6 +2271,8 @@ otherwise have to discover by trial and error.
 - Regression coverage for snapshot flat-`id` aliases on both MCP and
   HTTP surfaces, plus async / top-level-`await` WebView script bodies.
 
+[0.2.1]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.2.1
+[0.2.0]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.2.0
 [0.1.36]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.36
 [0.1.35]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.35
 [0.1.34]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.34

package/Readme.md

@@ -105,7 +105,7 @@ the DB so SQLite WAL data is checkpointed into the file.
 
 ### 06 / Any agent
 
-Harness-agnostic. Drive the canvas from [MCP](docs/mcp.md) (69 tools,
+Harness-agnostic. Drive the canvas from [MCP](docs/mcp.md) (83 tools,
 14 resources, change notifications), the [CLI](docs/cli.md), the
 [HTTP API](docs/http-api.md), or the [Bun SDK](docs/sdk.md). Works with
 Claude Code, GitHub Copilot CLI, Codex, Cursor, Windsurf, or any agent
@@ -255,7 +255,7 @@ the agent can read `canvas://skills` and pull in companion skills
   the three-tier visual matrix (json-render → html → web-artifact)
 - **[CLI reference](docs/cli.md)** — full command surface, daemon mode,
   watch streams, WebView automation
-- **[MCP reference](docs/mcp.md)** — 69 tools, 14 resources, change
+- **[MCP reference](docs/mcp.md)** — 83 tools, 14 resources, change
   notifications, node-type routing
 - **[HTTP API](docs/http-api.md)** — REST endpoints, SSE, batch operations
 - **[AX host-adapter contract](docs/ax-host-adapter-contract.md)** — how native