pmx-canvas 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,103 @@
 All notable changes to `pmx-canvas` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [0.4.0] - 2026-08-04
+
+### Breaking
+
+- **The `canvas_snapshot` MCP tool is now a composite** with actions `save`,
+  `list`, `restore`, `delete`, `gc`, and `diff`, and the 6 deprecated snapshot
+  standalones (`canvas_snapshot` save tool, `canvas_list_snapshots`,
+  `canvas_restore`, `canvas_delete_snapshot`, `canvas_gc_snapshots`,
+  `canvas_diff`) are removed after their deprecated 0.3.x window. The MCP
+  surface is now 22 tools: 16 composites + 6 standalones. Arguments are
+  unchanged apart from adding the `action` field; the CLI and HTTP snapshot
+  surfaces are unaffected.
+- Pre-0.2 legacy layouts (`.pmx-canvas/state.json`, `.pmx-canvas.json`, legacy
+  snapshot dirs and blob files) are no longer imported on boot. Upgrade
+  through a 0.3.x install first if you still have one. `PMX_CANVAS_STATE_FILE`
+  remains only as a `.db`-path alias; other values are ignored with a warning.
+- HTTP error responses are now JSON envelopes (`{ ok: false, error }`) with
+  unchanged status codes, instead of plain text — one error shape across every
+  endpoint.
+
+### Added
+
+- The canvas now works behind proxies that buffer streaming responses (e.g.
+  Amp orb portals): if the live event stream delivers nothing shortly after
+  connecting, the browser switches to a polling transport
+  (`GET /api/workbench/poll`) that carries the same events as ordinary JSON
+  responses. Force a mode with `/workbench?transport=poll` or `?transport=sse`.
+- `crypto.randomUUID` is polyfilled in the browser client, so the canvas also
+  boots in embedded pages served outside a secure context.
+- `/health` reports persistence health: `persistence.ok` turns false after a
+  failed state save (the canvas keeps serving from memory) and true again
+  after the next successful save.
+
+### Changed
+
+- The server now falls back to `PMX_CANVAS_PORT` when `--port` and
+  `PMX_WEB_CANVAS_PORT` are unset, so one variable can point the client and
+  server at the same port.
+
+- `pmx-canvas node update` returns a compact `{ ok, id, position, size,
+  updatedFields }` envelope by default; pass `--full` for the complete node
+  payload (a no-op ext-app resize previously echoed ~940 KB — 0.3.4 report
+  Finding R).
+
+### Fixed
+
+- App documents are made background-transparent so tiles that letterbox at the
+  document level show the theme background instead of black. Narrow or tall
+  Excalidraw tiles can still show the app's own dark fill below the diagram —
+  that part lives inside the hosted app bundle (0.3.4 report Finding Q,
+  documented with a sizing workaround in the skill).
+
+## [0.3.4] - 2026-08-03
+
+### Added
+
+- A client component test harness (happy-dom + Testing Library) with the
+  first 20 render tests, plus dedicated suites for the semantic watch
+  reducer and the canvas schema (46 new tests). Test files are now
+  typechecked, and CI fails when total coverage drops below the recorded
+  floor.
+
+### Fixed
+
+- App tiles now show a spinner and a "Connecting to <app>..." overlay while an
+  app frame boots or recovers, instead of a dark tile body (0.3.3 report: the
+  transient black window during automatic recovery).
+- Composite tools now name the missing field when a required argument for the
+  chosen action is absent, instead of failing deep in the handler or silently
+  doing nothing.
+- A pending code-graph recompute timer no longer outlives its server across
+  start/stop cycles.
+
+### Changed
+
+- The sandboxed-surface AX bridge (the listener that validates and submits
+  iframe interactions) is now one shared implementation across html, app, and
+  viewer nodes, with the protocol tags defined in a single module. No behavior
+  change — this hardens a security boundary that was previously copy-pasted.
+- The CLI dispatches every canvas command through the operation registry's
+  HTTP invoker instead of hand-written request paths; success output is
+  unchanged. One failure-path improvement: a failed `pmx-canvas batch` now
+  prints the full result envelope (`ok:false`, `failedIndex`, partial
+  `results`, `refs`) on stdout and exits 1, instead of a bare stderr error.
+
+### Docs
+
+- WebView backend preflight: prefer webkit on macOS; the chrome backend can
+  show an "Allow remote debugging?" dialog that must be approved promptly, and
+  `PMX_CANVAS_WEBVIEW_TIMEOUT_MS` can be raised for slow starts.
+- Skill evals: the two file-node eval prompts now reference the bundled
+  fixture paths, so a literal eval run works in any workspace.
+- Web-artifact builds are documented as POSIX-only (the build pipeline runs
+  bash scripts); already-built artifacts render on every platform.
+- All `PMX_*` environment variables are documented in
+  [`docs/environment.md`](docs/environment.md).
+
 ## [0.3.3] - 2026-07-08
 
 ### Fixed
@@ -2734,6 +2831,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.4.0]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.4.0
+[0.3.4]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.3.4
 [0.3.3]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.3.3
 [0.3.2]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.3.2
 [0.3.1]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.3.1

package/Readme.md

@@ -98,16 +98,17 @@ 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#standalone-tools), full
+refresh and server restart. Named [snapshots](docs/mcp.md), 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) (27 tools,
+Harness-agnostic. Drive the canvas from [MCP](docs/mcp.md) (22 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
+[HTTP API](docs/http-api.md), or the [Bun SDK](docs/sdk.md) — all
+[environment variables documented here](docs/environment.md). Works with
 Claude Code, GitHub Copilot CLI, Codex, Cursor, Windsurf, or any agent
 that can spawn an MCP stdio server, call a CLI, or hit an HTTP endpoint.
 
@@ -139,6 +140,14 @@ surfaces (the core never imports a host SDK).
   `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.
+- **Claude Code desktop app** — the workbench runs in the desktop app's
+  built-in browser pane alongside the PMX MCP server, same zero-adapter recipe
+  as Codex: open `http://localhost:4313/workbench` in the app's browser and the
+  live board, pins, and Ghost Cursor all work in-panel.
+- **Amp orb portals** (and other buffering proxies) — the canvas detects when
+  the live event stream is being buffered by the proxy and automatically
+  switches to a polling transport, so the board boots and stays live through
+  the portal with no proxy shims (`/workbench?transport=poll` forces it).
 
 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.
@@ -256,7 +265,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)** — 27 tools, 14 resources, change
+- **[MCP reference](docs/mcp.md)** — 22 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