pmx-canvas 0.3.4 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,58 @@
 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
@@ -2779,6 +2831,7 @@ 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

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#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) — all
 [environment variables documented here](docs/environment.md). Works with
@@ -140,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.
@@ -257,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