pmx-canvas 0.2.6 → 0.3.0

package/CHANGELOG.md

@@ -3,7 +3,160 @@
 All notable changes to `pmx-canvas` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
-## [Unreleased]
+## [0.3.0] - 2026-07-07
+
+### Breaking
+
+- **MCP tool surface shrinks from 84 to 27.** The 57 deprecated legacy
+  single-purpose MCP tools left over from the v0.2 composites migration are
+  removed. Each has a direct composite replacement — same operation, new
+  entry point:
+  - **`canvas_node`**: `canvas_add_node` → `action: "add"`; `canvas_get_node`
+    → `action: "get"`; `canvas_update_node` → `action: "update"`;
+    `canvas_remove_node` → `action: "remove"`; `canvas_add_html_node` →
+    `action: "add"` with `type: "html"`; `canvas_add_html_primitive` →
+    `action: "add"` with `type: "html"` + `primitive: "<kind>"`;
+    `canvas_refresh_webpage_node` → `action: "update"` with `refresh: true`.
+  - **`canvas_render`**: `canvas_describe_schema` → `action:
+    "describe-schema"`; `canvas_validate_spec` → `action: "validate"`;
+    `canvas_add_json_render_node` → `action: "add-json-render"`;
+    `canvas_stream_json_render_node` → `action: "stream-json-render"`;
+    `canvas_add_graph_node` → `action: "add-graph"`.
+  - **`canvas_edge`**: `canvas_add_edge` → `action: "add"`;
+    `canvas_remove_edge` → `action: "remove"`.
+  - **`canvas_group`**: `canvas_create_group` → `action: "create"`;
+    `canvas_group_nodes` → `action: "add"`; `canvas_ungroup` → `action:
+    "ungroup"`.
+  - **`canvas_history`**: `canvas_undo` → `action: "undo"`; `canvas_redo` →
+    `action: "redo"`.
+  - **`canvas_view`**: `canvas_arrange` → `action: "arrange"`;
+    `canvas_focus_node` → `action: "focus"`; `canvas_fit_view` → `action:
+    "fit"`; `canvas_clear` → `action: "clear"`; `canvas_remove_annotation` →
+    `action: "remove-annotation"`.
+  - **`canvas_query`**: `canvas_search` → `action: "search"`;
+    `canvas_get_layout` → `action: "layout"`; `canvas_validate` → `action:
+    "validate"`.
+  - **`canvas_app`**: `canvas_open_mcp_app` → `action: "open-mcp-app"`;
+    `canvas_add_diagram` → `action: "diagram"`; `canvas_build_web_artifact` →
+    `action: "build-artifact"`.
+  - **`canvas_webview`**: `canvas_webview_status` → `action: "status"`;
+    `canvas_webview_start` → `action: "start"`; `canvas_webview_stop` →
+    `action: "stop"`; `canvas_resize` → `action: "resize"`; `canvas_evaluate`
+    → `action: "evaluate"`.
+  - **`canvas_ax_state`**: `canvas_get_ax` → `action: "get"`;
+    `canvas_set_ax_focus` → `action: "set-focus"`; `canvas_set_ax_policy` →
+    `action: "set-policy"`; `canvas_report_host_capability` → `action:
+    "report-capability"`.
+  - **`canvas_ax_work`**: `canvas_add_work_item` → `action: "add"`;
+    `canvas_update_work_item` → `action: "update"`;
+    `canvas_add_review_annotation` → `action: "annotate"`.
+  - **`canvas_ax_gate`**: `canvas_request_approval` → `kind: "approval"`,
+    `action: "request"`; `canvas_resolve_approval` → `kind: "approval"`,
+    `action: "resolve"`; `canvas_await_approval` → `kind: "approval"`,
+    `action: "await"`; `canvas_request_elicitation` → `kind: "elicitation"`,
+    `action: "request"`; `canvas_respond_elicitation` → `kind:
+    "elicitation"`, `action: "resolve"`; `canvas_await_elicitation` → `kind:
+    "elicitation"`, `action: "await"`; `canvas_request_mode` → `kind:
+    "mode"`, `action: "request"`; `canvas_resolve_mode` → `kind: "mode"`,
+    `action: "resolve"`; `canvas_await_mode` → `kind: "mode"`, `action:
+    "await"`.
+  - **`canvas_ax_timeline`**: `canvas_get_ax_timeline` → `action: "read"`;
+    `canvas_record_ax_event` → `action: "record-event"`; `canvas_add_evidence`
+    → `action: "add-evidence"`; `canvas_send_steering` → `action:
+    "send-steering"`.
+  - **`canvas_ax_delivery`**: `canvas_claim_ax_delivery` → `action: "claim"`;
+    `canvas_mark_ax_delivery` → `action: "mark"`.
+
+  The HTTP API, the SDK, and `canvas_batch` are unaffected — these are the
+  same underlying operations, only the standalone MCP tool entry points are
+  removed. `docs/mcp.md` retains the full migration table for reference.
+
+- **Malformed JSON request bodies now return 400.** Every HTTP API route
+  responds `400 { ok: false, error: "Malformed JSON body." }` when a non-empty
+  body fails to parse, instead of silently treating it as an empty request.
+  Empty bodies are still accepted.
+
+### Deprecated
+
+- The 6 snapshot standalone tools (`canvas_snapshot`, `canvas_list_snapshots`,
+  `canvas_restore`, `canvas_delete_snapshot`, `canvas_gc_snapshots`,
+  `canvas_diff`) now carry deprecation notices in their tool descriptions and
+  fold into a `canvas_snapshot` composite (`action: save|list|restore|delete
+  |gc|diff`) in v0.4.
+
+### Removed
+
+- Legacy `ext-app-ext-app-…` double-prefix blob-lookup fallback in
+  `findCanvasExtAppNodeId` (`src/server/ext-app-lookup.ts`), scheduled for
+  removal since v0.1.4. All ext-app node IDs have carried the single-prefix
+  form since then; the primary lookup and the data-scan fallback are
+  unaffected.
+- The orphaned `dist/client` bundle and the generated web-artifact build
+  projects under `.pmx-canvas/artifacts/.web-artifacts/` are no longer
+  committed to the repo.
+
+### Fixed
+
+- HTTP `GET /api/canvas/search` now honors the `limit` query parameter
+  (previously only the MCP tool applied it).
+- The SDK's `setContextPins` emits the same `context-pins-changed` event as
+  the HTTP API and MCP tool, instead of a full layout update.
+- `canvas_ax_interaction` and `canvas_ingest_activity` return a clean tool
+  error instead of an MCP protocol error when they fail.
+- The code graph resolves workspace-relative imports against the configured
+  workspace root instead of the server process working directory.
+- The MCP server now reports the real package version in its handshake
+  (read from `package.json`) instead of a stale hard-coded `0.1.0`.
+
+### Docs
+
+- Operation descriptions and field hints no longer route agents to MCP tools
+  removed in v0.3.0.
+
+## [0.2.7] - 2026-06-25
+
+### Fixed
+
+- **Ghost Cursor of Intent is no longer hidden behind the welcome card on an empty board (report
+  Finding J).** The intent ghost lives inside the zoom/pan world transform (its own stacking
+  context), so its high z-index could not lift it above the `.welcome-card`, which is a sibling
+  outside the transform. The welcome card is now suppressed while a ghost intent is live
+  (`intents.value.size > 0`), so a `canvas_intent` signal on a fresh board is visible immediately;
+  the card returns when the intent clears/settles and the board is still empty. Verified by
+  screenshot in the WebKit backend.
+- **MCP `--mcp` no longer silently splits to (or silently adopts) a wrong workspace — structural
+  fix (report Finding I).** The GitHub Copilot adapter spawns `pmx-canvas --mcp` from an incidental
+  cwd (e.g. `~/.copilot`); the old code then either split to a hidden fallback port (when the
+  preferred port was held) or adopted that incidental cwd as the workspace (when the port was free),
+  so writes landed on a canvas the project panel never renders. Now, in `createCanvasAccess`:
+  - **Port held by a different-workspace daemon →** the MCP server **attaches** to it (inherits its
+    workspace) so writes are visible where the panel renders, instead of splitting.
+  - **Free port + incidental launch cwd (`~/.copilot`-shaped) →** it still binds (the agent always
+    gets a working canvas) but emits a loud, actionable stderr warning instead of silently adopting
+    the cwd; a race-tolerant re-probe first attaches to any daemon that appeared on the port.
+  - **`PMX_CANVAS_WORKSPACE_ROOT=<abs project root>`** (new) pins the workspace for both the lookup
+    and the bound daemon (`startCanvasServer` honors it), overriding the launch cwd — the deterministic
+    host fix. `PMX_CANVAS_ALLOW_WORKSPACE_SPLIT=1` (or a distinct `PMX_CANVAS_PORT`) forces a separate
+    canvas. The incidental detector is **positive-signal only** (home dir / dot-child of home), so the
+    `mkdtemp` temp dirs the test suite runs from are never misflagged — startup behavior is
+    byte-identical for real projects and tests.
+  Verified on the real `--mcp` stdio path: port-held → attach (no fallback); incidental + free →
+  bind-but-warn (no split); `PMX_CANVAS_WORKSPACE_ROOT` → binds the project root (no warning); real
+  project → binds (no warning). Pure `shouldAttachToExistingDaemon` + `looksLikeIncidentalCwd`
+  helpers are unit-tested.
+
+### Docs
+
+- **Clarified the `color` contract: renderer color vs persisted metadata (report Finding H).** A
+  top-level `color` is a renderer parameter only for `group` (frame accent) and `graph` nodes; on
+  `markdown` / `status` / `context` it is dropped, and while an arbitrary `data.color` posted under
+  `data` persists like any `data.*` metadata, it is not read as a render color for basic node types.
+  The reference now states this renderer-vs-storage distinction so docs/schema/runtime agree.
+- **Made the WebView automation timeout error actionable (report Finding G).** The chrome backend is
+  known-flaky on some hosts (Bun.WebView), reproduced in both the Copilot and Codex hosts; the webkit
+  backend (the macOS default) works. The timeout error now points to `start --backend webkit` and the
+  already-configurable `PMX_CANVAS_WEBVIEW_TIMEOUT_MS` instead of a dead-end "may be unavailable".
+  Not a PMX regression — no canvas source touches the WebView/automation path.
 
 ## [0.2.6] - 2026-06-25
 
@@ -2488,6 +2641,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.3.0]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.3.0
+[0.2.7]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.2.7
 [0.2.6]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.2.6
 [0.2.5]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.2.5
 [0.2.4]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.2.4

package/Readme.md

@@ -98,14 +98,14 @@ vendor-specific.
 
 Spatial state auto-saves to `.pmx-canvas/canvas.db` (debounced ~500 ms) —
 git-committable, shareable across machines, and survives both browser
-refresh and server restart. Named [snapshots](docs/mcp.md#tools), full
+refresh and server restart. Named [snapshots](docs/mcp.md#standalone-tools), full
 undo/redo, and an auto-detected code graph (JS/TS, Python, Go, Rust) make
 the canvas durable rather than throwaway. Stop the server before committing
 the DB so SQLite WAL data is checkpointed into the file.
 
 ### 06 / Any agent
 
-Harness-agnostic. Drive the canvas from [MCP](docs/mcp.md) (84 tools,
+Harness-agnostic. Drive the canvas from [MCP](docs/mcp.md) (27 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
@@ -136,9 +136,9 @@ surfaces (the core never imports a host SDK).
   preview).
 - **Codex app** — native through the Codex in-app Browser (opened to
   `/workbench`) plus the PMX MCP server: agents read `canvas://ax-context` /
-  `canvas_get_ax` and label Codex-originated focus with `source: "codex"`. No
-  extension API needed — Codex's two native surfaces (MCP + in-app Browser) are
-  exactly what the canvas requires.
+  `canvas_ax_state { action: "get" }` and label Codex-originated focus with
+  `source: "codex"`. No extension API needed — Codex's two native surfaces
+  (MCP + in-app Browser) are exactly what the canvas requires.
 
 The contract is host-agnostic, so a new host plugs in the same way: map its
 hooks, canvas, and session APIs onto PMX's AX primitives — no core changes.
@@ -219,8 +219,9 @@ Codex needs no extension — its two native surfaces are exactly what the canvas
 requires. Add the PMX MCP server to the Codex workspace config (same snippet as
 [Connect your agent](#connect-your-agent-mcp)), then open the returned
 `/workbench` URL in the **Codex in-app Browser** so you can see mutations live.
-Agents read pinned/focused context from `canvas://ax-context` / `canvas_get_ax`
-and label Codex-originated focus with `source: "codex"`. See
+Agents read pinned/focused context from `canvas://ax-context` /
+`canvas_ax_state { action: "get" }` and label Codex-originated focus with
+`source: "codex"`. See
 [`codex-app-adapter.md`](skills/pmx-canvas/references/codex-app-adapter.md) for
 the full workflow and live-test checklist.
 
@@ -255,7 +256,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)** — 84 tools, 14 resources, change
+- **[MCP reference](docs/mcp.md)** — 27 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
@@ -273,9 +274,10 @@ the agent can read `canvas://skills` and pull in companion skills
 - **What leaves your machine.** The core canvas runs entirely on
   `localhost`. Network egress only happens for explicit, opt-in flows:
   `webpage` nodes fetch the URL you give them; `mcp-app` /
-  `canvas_add_diagram` calls go to whatever MCP server URL you configure
-  (the Excalidraw preset uses `https://mcp.excalidraw.com/mcp`); `bunx`
-  itself reads the npm registry on first install. Nothing else phones home.
+  `canvas_app { action: "diagram" }` calls go to whatever MCP server URL you
+  configure (the Excalidraw preset uses `https://mcp.excalidraw.com/mcp`);
+  `bunx` itself reads the npm registry on first install. Nothing else phones
+  home.
 
 ## Tech stack