pmx-canvas 0.1.17 → 0.1.19

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.1.19] - 2026-05-05
+
+Snapshot ergonomics and reference-doc distribution. Adds `before` /
+`after` ISO timestamp filters on snapshot listing across CLI, HTTP,
+and MCP, ships the `docs/` reference tree inside the npm tarball so
+consumers see the same surface docs as the repo, and surfaces the
+existing trace-field flags in `node update --help`. Also lands the
+deflake of the MCP-app fullscreen reopen e2e (originally
+`LRN-20260505-001`) — 9/20 → 50+/50 stability via a retry-on-stuck-
+iframe helper.
+
+### Added
+
+- **`pmx-canvas snapshot list --before / --after`.** Both flags
+  accept ISO 8601 timestamps and filter against `snapshot.createdAt`.
+  Same surface lands on `GET /api/canvas/snapshots?before=&after=`,
+  `RemoteCanvasAccess.listSnapshots()`, and the `canvas_list_snapshots`
+  MCP tool schema. The CLI help (`pmx-canvas snapshot list --help`)
+  now lists the new flags alongside `--limit`, `--query`, and
+  `--all`.
+- **`docs/` shipped in the npm tarball.** The package `files`
+  allowlist now includes `docs/`, so consumers installing
+  `pmx-canvas` see the same `docs/cli.md`, `docs/http-api.md`,
+  `docs/mcp.md`, `docs/node-types.md`, and `docs/sdk.md` reference
+  files that ship in the repo.
+- **`node update --help` advertises trace flags.** The CLI help now
+  documents `--tool-name` / `--toolName`, `--category`, `--status`,
+  `--duration`, `--result-summary` / `--resultSummary`, and `--error`
+  so agents discover trace-field updates without reading the source
+  or schema.
+
+### Fixed
+
+- **MCP-app fullscreen reopen e2e is no longer flaky.** The
+  visibility check for the fixture editor used to race the ext-app
+  bridge handshake — if the iframe started parsing before the
+  parent registered its postMessage listener, the iframe's
+  `ui/initialize` request was lost and `app.connect()` hung. The
+  test now wraps the assertion in a retry-on-stuck-iframe helper
+  that closes and reopens the fullscreen overlay (each remount is
+  independent of the prior failed handshake), with three 5s
+  attempts to match the original 15s budget. Pass rate moved from
+  9/20 to 50+/50 consecutive runs.
+
+### Internal
+
+- Regression coverage for: snapshot list before/after filtering at
+  the canvas-state layer and through the CLI, snapshot list help
+  advertising the new flags, `node update --help` advertising
+  trace flags, the `docs/` allowlist entry surviving in
+  `package.json` for npm consumers, and the existing arrange
+  operation recording as a single undoable history entry.
+
+## [0.1.18] - 2026-05-05
+
+Token-budget polish on top of 0.1.17. Full-mode MCP responses for
+hosted external-MCP-app nodes now elide the rendered shell HTML in
+favor of a compact `{ omitted, resourceUri, bytes, sha256 }` summary,
+so an agent that asks for `full: true` no longer re-receives the same
+ext-app shell HTML on every read. Adds a dedicated
+`excalidraw-diagram-authoring.md` skill reference and folds the
+freehand annotation feature into the README's main feature list.
+
+### Added
+
+- **`serializeCanvasNodeForAgent` / `serializeCanvasLayoutForAgent`.**
+  New agent-facing serializers wrap the existing
+  `serializeCanvasNode` / `serializeCanvasLayout` helpers and replace
+  hosted ext-app shell HTML (`mcp-app` nodes in `ext-app` mode that
+  carry a `resourceUri`) with a `{ omitted: 'external-mcp-app-html',
+  resourceUri, bytes, sha256 }` descriptor. The MCP server uses
+  these wrappers for `canvas_get_node` (full), `canvas_get_layout`
+  (full), and the full-payload branch of every add-style response.
+  Non-external-app HTML — `html` nodes, bundled web-artifact
+  output — is preserved exactly as before.
+- **`skills/pmx-canvas/references/excalidraw-diagram-authoring.md`.**
+  A 145-line authoring guide for `canvas_add_diagram` covering shape-
+  level `label` format, sizing and camera rules, the pastel palette,
+  and common pitfalls. The SKILL points to it from the diagram
+  guidance section.
+
+### Changed
+
+- **README adds an `03 / Annotate` section.** The annotation feature
+  shipped in 0.1.17 is now part of the main README feature list
+  alongside Curate / Mix / Control / Save / Any agent. Subsequent
+  sections were renumbered (Control your context → 04, Save → 05,
+  Any agent → 06).
+
+### Internal
+
+- Regression coverage for: agent-mode node serialization eliding
+  hosted ext-app shell HTML, agent-mode layout serialization not
+  repeating the ext-app shell across multiple nodes, non-external-
+  app HTML payloads being preserved unchanged, and `canvas_get_node`
+  / `canvas_get_layout` full-mode elision through the MCP server.
+
 ## [0.1.17] - 2026-05-04
 
 Adds a freehand annotation layer so humans can draw directly on the
@@ -727,6 +824,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.1.19]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.19
+[0.1.18]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.18
 [0.1.17]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.17
 [0.1.16]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.16
 [0.1.15]: https://github.com/pskoett/pmx-canvas/releases/tag/v0.1.15

package/Readme.md

@@ -1,8 +1,8 @@
 # pmx-canvas
 
 **A moldable canvas for agent-assisted thinking.** An infinite 2D surface
-where files, plans, status, charts, fetched web pages, and hand-drawn
-diagrams live side by side. Every node carries its own renderer; agents
+where files, plans, status, charts, fetched web pages, annotations, and
+hand-drawn diagrams live side by side. Every node carries its own renderer; agents
 (and you) build new views in the middle of a session, not as a separate
 tooling project. Pin what matters and the agent reads your spatial
 curation as structured context.
@@ -41,14 +41,21 @@ surface. The reach of the canvas is the union of its
 already has access to** — MCP servers, CLIs, file reads, web fetch, anything
 on its toolbelt.
 
-### 03 / Control your context
+### 03 / Annotate
+
+Draw freehand marks directly on the canvas to circle, underline, connect, or
+call out what matters without turning the markup into another node. Annotations
+persist with state and snapshots, can be erased in the browser, and appear to
+agents as compact spatial context: target, bounds, and nearby canvas content.
+
+### 04 / Control your context
 
 Pinning is an explicit, low-noise control over what the agent sees next. No
 prompt engineering, no copy-paste — pin a node in the browser and the MCP
 server fires a `notifications/resources/updated` event the agent's harness
 picks up immediately.
 
-### 04 / Save
+### 05 / Save
 
 Spatial state auto-saves to `.pmx-canvas/state.json` (debounced ~500 ms) —
 git-committable, shareable across machines, and survives both browser
@@ -56,7 +63,7 @@ refresh and server restart. Named [snapshots](docs/mcp.md#tools), full
 undo/redo, and an auto-detected code graph (JS/TS, Python, Go, Rust) make
 the canvas durable rather than throwaway.
 
-### 05 / Any agent
+### 06 / Any agent
 
 Harness-agnostic. Drive the canvas from [MCP](docs/mcp.md) (41 tools,
 8 resources, change notifications), the [CLI](docs/cli.md), the

package/dist/types/server/canvas-serialization.d.ts

@@ -33,8 +33,10 @@ export declare function getCanvasNodeKind(node: CanvasNodeState, data: Record<st
 export declare function getCanvasNodeTitle(node: CanvasNodeState): string | null;
 export declare function getCanvasNodeContent(node: CanvasNodeState): string | null;
 export declare function serializeCanvasNode(node: CanvasNodeState): SerializedCanvasNode;
+export declare function serializeCanvasNodeForAgent(node: CanvasNodeState): SerializedCanvasNode;
 export declare function serializeCanvasNodeWithBlobSummaries(node: CanvasNodeState): SerializedCanvasNode;
 export declare function serializeCanvasLayout(layout: CanvasLayout): SerializedCanvasLayout;
+export declare function serializeCanvasLayoutForAgent(layout: CanvasLayout): SerializedCanvasLayout;
 export declare function serializeCanvasLayoutWithBlobSummaries(layout: CanvasLayout): SerializedCanvasLayout;
 export declare function summarizeCanvasAnnotation(annotation: CanvasAnnotation): CanvasAnnotationSummary;
 export declare function summarizeCanvasAnnotationForContext(annotation: CanvasAnnotation, nodes: CanvasNodeState[]): CanvasAnnotationContextSummary;

package/dist/types/server/canvas-state.d.ts

@@ -39,6 +39,8 @@ export interface CanvasSnapshot {
 export interface CanvasSnapshotListOptions {
     limit?: number;
     query?: string;
+    before?: string;
+    after?: string;
     all?: boolean;
 }
 export interface CanvasSnapshotGcOptions {

package/docs/RELEASE.md

@@ -0,0 +1,153 @@
+# Release process
+
+Internal recipe for cutting a new `pmx-canvas` release. Lives in `docs/`
+rather than the README so end-user agents and humans driving the canvas
+aren't distracted by maintainer-only flow. Agents working **on** this
+repo (improving the canvas itself) should treat this file as the
+single source of truth for the release dance — see also
+[`AGENTS.md`](../AGENTS.md) and [`CLAUDE.md`](../CLAUDE.md).
+
+## TL;DR
+
+1. Land all the changes you want in the release on `main` with green CI.
+2. Bump `package.json` `version`.
+3. Add a `## [X.Y.Z]` block to `CHANGELOG.md`.
+4. Commit, push, wait for `test.yml` green.
+5. `git tag -a vX.Y.Z -m "..." && git push origin vX.Y.Z` →
+   `publish.yml` runs `npm publish --access public --provenance`.
+6. `gh release create vX.Y.Z --notes-file <notes.md>`.
+7. Smoke-test the published tarball: `bunx pmx-canvas@X.Y.Z --no-open`.
+
+## Pre-flight gates
+
+Run these locally before tagging. They mirror what `publish.yml`
+re-runs in CI; a failure here means the publish workflow will also fail.
+
+```bash
+bun install --frozen-lockfile
+bun run typecheck
+bun run build
+bun test tests/unit         # 200+ tests, all green
+bun run test:web-canvas     # Playwright E2E, all green
+bun run test:e2e-cli        # fresh-workspace CLI eval
+bun run release:check       # bundles + lints
+bun run release:smoke       # packs + boots from a clean dir
+bun run pack:dry-run        # confirms the tarball shape
+```
+
+`bun run test:e2e-cli` starts a local server in a fresh temp workspace
+and exercises the CLI flows from
+[`docs/evals/e2e-cli-coverage.md`](evals/e2e-cli-coverage.md).
+
+## 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).
+- Major (`0.x → 1.0`): production-stability commitment.
+
+CLAUDE.md rule #5 (CanvasStateManager / PmxCanvas SDK / HTTP / MCP
+four-layer parity) is the strongest hard rule for what counts as
+non-breaking — a CLI/HTTP-only addition without MCP parity has
+historically required a follow-up patch release to restore parity.
+
+## CHANGELOG
+
+`CHANGELOG.md` follows [Keep a Changelog](https://keepachangelog.com/).
+Each release section uses these subheadings:
+
+- **Added** — new public surface (HTTP endpoint, MCP tool/resource, CLI
+  command/flag, SDK export, JSON shape).
+- **Changed** — behavior changes that aren't strictly bug fixes
+  (response shape additions, schema cleanups, stricter validation).
+- **Fixed** — bug fixes.
+- **Internal** — refactors, test additions, docs that don't affect
+  the public surface.
+
+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.
+
+## Tag → publish
+
+The publish workflow ([`/.github/workflows/publish.yml`](../.github/workflows/publish.yml))
+triggers on tags matching `v*`:
+
+```bash
+git tag -a v0.1.6 -m "v0.1.6 — short summary"
+git push origin v0.1.6
+```
+
+It will:
+
+1. Verify the tag matches `package.json` version.
+2. Re-run typecheck / build / unit / E2E / pack.
+3. `npm publish --access public --provenance` using the `NPM_TOKEN`
+   secret. Provenance attestations are signed via sigstore and visible
+   on the npm package page.
+
+Watch it complete:
+
+```bash
+gh run watch
+```
+
+If publish fails after npm has accepted the tarball, you cannot reuse
+the same version number. Bump the patch and re-tag.
+
+If this is the first release from your machine, run `bunx npm login`
+once so Bun can reuse your npm credentials. CI does not need this —
+it uses `NPM_TOKEN` directly.
+
+## GitHub release
+
+After `npm publish` succeeds:
+
+```bash
+gh release create v0.1.6 \
+  --title "pmx-canvas 0.1.6 — short theme" \
+  --notes-file /tmp/pmx-canvas-v0.1.6-release-notes.md \
+  --verify-tag
+```
+
+`--verify-tag` makes the command fail if the local tag drifted from
+the remote — a small but useful guard.
+
+## Smoke test from npm
+
+```bash
+cd /tmp && rm -rf smoke && mkdir smoke && cd smoke
+bunx --bun pmx-canvas@<version> --no-open --port=4926 > smoke.log &
+SP=$!
+for i in 1 2 3 4 5 6 7 8 9 10; do
+  curl -sf http://localhost:4926/health >/dev/null 2>&1 && break
+  sleep 1
+done
+curl -s http://localhost:4926/health      # → {"ok":true,"workspace":"…"}
+bunx pmx-canvas@<version> --version       # → <version>
+kill $SP
+```
+
+If `bunx pmx-canvas@<version>` resolves and the health endpoint replies
+with `ok: true`, the published tarball is intact end-to-end.
+
+## Common gotchas
+
+- **`/.pmx-canvas/artifacts/.web-artifacts/sdlc-control-room/.parcel-cache/`**
+  files always show as modified after running an artifact build. They
+  are workspace-local cache and must not be committed; they're gitignored
+  but still appear in `git status`. Use `git restore --staged` if they
+  sneak into a `git add -A`.
+- **`docs/screenshot.png`** updates whenever the showcase E2E runs.
+  Don't bake those updates into a release commit unless the screenshot
+  in `Readme.md` actually needs the refresh.
+- **CHANGELOG dates**: use the actual publish date in the
+  `## [version] - YYYY-MM-DD` header, not the day you wrote the entry.
+- **Node 24 deprecation timeline**: GitHub Actions is migrating
+  `actions/checkout`, `setup-node`, `upload-artifact` to Node 24 by
+  June 2, 2026. The publish workflow already pins `@v5` of all three.

package/docs/bun-webview-integration.md

@@ -0,0 +1,296 @@
+# Bun.WebView Integration
+
+PMX Canvas now uses Bun's built-in `Bun.WebView` API for **headless canvas automation**, while keeping the current external browser launcher for the normal interactive canvas window.
+
+This document tracks:
+
+- what is implemented today
+- what was validated on stable Bun `v1.3.12`
+- what still remains future work
+
+## Current Status
+
+**Implemented** for Phase 1.
+
+The repo now targets Bun `>=1.3.12`, and PMX Canvas ships an opt-in, server-owned WebView automation session that can:
+
+- start a headless browser session for `/workbench`
+- report WebView runtime status
+- evaluate JavaScript in the page
+- resize the automation viewport
+- capture screenshots
+- stop and clean up the automation session explicitly
+
+What is **not** implemented:
+
+- replacing `openUrlInExternalBrowser()` for the visible user-facing canvas window
+- headed Bun.WebView window support
+- Chrome-only CDP tooling
+
+## Why This Exists
+
+The existing browser-launch path in [`src/server/server.ts`](../src/server/server.ts) still opens the interactive canvas with platform-specific shell behavior:
+
+- macOS: AppleScript / `osascript`
+- Windows: `cmd /c start` or a resolved browser executable
+- Linux: `xdg-open`
+
+That path is still appropriate for humans, but it provides no programmatic control once the browser is open.
+
+`Bun.WebView` gives PMX Canvas a controlled browser session that the server can own directly. That unlocks:
+
+- agent-visible screenshots
+- browser-backed evaluation of rendered canvas state
+- controlled viewport sizing
+- future browser automation tools without depending on Playwright for the basic runtime
+
+## Implemented Surface
+
+### Server layer
+
+Implemented in [`src/server/server.ts`](../src/server/server.ts):
+
+- `getCanvasAutomationWebViewStatus()`
+- `startCanvasAutomationWebView(url, options)`
+- `stopCanvasAutomationWebView()`
+- `evaluateCanvasAutomationWebView(expression)`
+- `resizeCanvasAutomationWebView(width, height)`
+- `screenshotCanvasAutomationWebView(options)`
+
+Important behavior:
+
+- runtime-gated: if `Bun.WebView` is unavailable, PMX Canvas returns a clear error
+- headless-only: PMX Canvas does not rely on `headless: false`
+- explicit lifecycle: start and stop are owned by the server
+- screenshot normalization handles Bun return types correctly, including `Blob`
+
+### HTTP API
+
+Implemented in [`src/server/server.ts`](../src/server/server.ts):
+
+- `GET /api/workbench/webview`
+- `POST /api/workbench/webview/start`
+- `POST /api/workbench/webview/evaluate`
+- `POST /api/workbench/webview/resize`
+- `POST /api/workbench/webview/screenshot`
+- `DELETE /api/workbench/webview`
+
+Current HTTP behavior:
+
+- `GET` returns runtime support plus active-session status
+- `POST` starts a new headless automation session for the current `/workbench`
+- `POST /evaluate` runs JavaScript in the active automation session and returns JSON
+- `POST /resize` updates the active automation viewport and returns JSON status
+- `POST /screenshot` returns image bytes for the active automation session
+- `DELETE` stops the current automation session
+
+Current options accepted by `POST /api/workbench/webview/start`:
+
+- `backend`: `"chrome"` or `"webkit"`
+- `width`
+- `height`
+- `chromePath`
+- `chromeArgv`
+- `dataStoreDir`
+
+### SDK
+
+Implemented in [`src/server/index.ts`](../src/server/index.ts):
+
+- `canvas.start({ automationWebView: ... })`
+- `canvas.startAutomationWebView(options)`
+- `canvas.stopAutomationWebView()`
+- `canvas.getAutomationWebViewStatus()`
+- `canvas.evaluateAutomationWebView(expression)`
+- `canvas.resizeAutomationWebView(width, height)`
+- `canvas.screenshotAutomationWebView(options)`
+
+### CLI
+
+Implemented in [`src/cli/index.ts`](../src/cli/index.ts):
+
+- `--webview-automation`
+- `--webview-backend`
+- `--webview-width`
+- `--webview-height`
+- `--webview-chrome-path`
+- `--webview-chrome-argv`
+- `--webview-data-dir`
+
+Implemented in [`src/cli/agent.ts`](../src/cli/agent.ts):
+
+- `pmx-canvas webview status`
+- `pmx-canvas webview start`
+- `pmx-canvas webview evaluate`
+- `pmx-canvas webview resize`
+- `pmx-canvas webview screenshot`
+- `pmx-canvas webview stop`
+
+Example:
+
+```bash
+pmx-canvas --no-open --webview-automation
+pmx-canvas --webview-automation --webview-backend=chrome
+pmx-canvas webview start --backend chrome --width 1440 --height 900
+pmx-canvas webview evaluate --expression "document.title"
+pmx-canvas webview resize --width 1280 --height 800
+pmx-canvas webview screenshot --output ./canvas.png
+pmx-canvas webview stop
+```
+
+These flags are intentionally automation-only. They do **not** imply a visible Bun-managed window.
+
+### MCP
+
+Implemented in [`src/mcp/server.ts`](../src/mcp/server.ts):
+
+- `canvas_webview_status`
+- `canvas_webview_start`
+- `canvas_webview_stop`
+- `canvas_evaluate`
+- `canvas_resize`
+- `canvas_screenshot`
+
+Current MCP behavior:
+
+- automation lifecycle is explicit rather than implicit
+- screenshot returns an MCP image payload plus JSON metadata
+- evaluate/resize/screenshot require an active automation session
+- start accepts the same backend/viewport/data-store options as the server layer
+
+## Backend Strategy
+
+PMX Canvas follows Bun's current stable backend reality.
+
+### WebKit backend
+
+- macOS only
+- good default on macOS when CDP is not required
+- zero external Chrome dependency
+
+### Chrome backend
+
+- required on Linux and Windows
+- also supported on macOS
+- preferred when backend consistency or future CDP-based tooling matters
+
+### Current default behavior
+
+PMX Canvas defaults to:
+
+- `webkit` on macOS
+- `chrome` elsewhere
+
+If `chromePath` or `chromeArgv` is provided, PMX Canvas forces a Chrome-backed session.
+
+## Bun Runtime Requirements
+
+The repo now requires:
+
+- Bun `>=1.3.12`
+
+That change is reflected in:
+
+- [`package.json`](../package.json)
+- [`.github/workflows/test.yml`](../.github/workflows/test.yml)
+
+PMX Canvas still keeps a runtime guard because older local Bun versions can exist in user environments. If `Bun.WebView` is missing, startup fails cleanly for the automation path instead of partially starting.
+
+## Validation Results
+
+Validated on Bun `v1.3.12`.
+
+### Unit coverage
+
+Verified by tests in:
+
+- [`tests/unit/server-api.test.ts`](../tests/unit/server-api.test.ts)
+- [`tests/unit/cli-webview.test.ts`](../tests/unit/cli-webview.test.ts)
+- [`tests/unit/webview-automation.test.ts`](../tests/unit/webview-automation.test.ts)
+
+Covered behavior:
+
+- WebView status over HTTP
+- start/stop lifecycle over HTTP
+- evaluate/resize/screenshot over HTTP
+- CLI status/start/evaluate/resize/screenshot/stop commands
+- graceful unsupported-runtime handling
+- SDK start/evaluate/resize/screenshot flow
+
+### Live runtime smoke
+
+Validated manually after upgrading the local runtime to Bun `1.3.12`:
+
+- `pmx-canvas --port=4529 --no-open --webview-automation --webview-backend=chrome`
+- `GET /api/workbench/webview`
+- `DELETE /api/workbench/webview`
+- SDK smoke with:
+  - `startAutomationWebView`
+  - `evaluateAutomationWebView('document.title')`
+  - `resizeAutomationWebView(...)`
+  - `screenshotAutomationWebView(...)`
+
+Observed results:
+
+- automation session started successfully
+- status endpoint reported `active: true`
+- JS evaluation returned `"PMX Canvas"`
+- viewport resize updated status correctly
+- screenshots returned non-zero image bytes on both WebKit and Chrome backends during smoke testing
+
+## Implementation Notes
+
+### Screenshot normalization bug
+
+During real runtime validation, a bug was found in the first implementation:
+
+- PMX Canvas assumed `view.screenshot()` returned only `Uint8Array` or `ArrayBuffer`
+- on this machine, Bun could also return a `Blob`
+- that caused zero-byte screenshots in the wrapper even though Bun was returning valid image data
+
+This was fixed in [`src/server/server.ts`](../src/server/server.ts) by normalizing:
+
+- `Uint8Array`
+- `ArrayBuffer`
+- `Blob`
+
+The regression is now covered by [`tests/unit/webview-automation.test.ts`](../tests/unit/webview-automation.test.ts).
+
+### Why the interactive browser path still exists
+
+Even with Bun `v1.3.12`, PMX Canvas should still keep `openUrlInExternalBrowser()` for the normal canvas window because Bun's current documented WebView surface is still effectively headless automation. There is no reason yet to promise a headed replacement window to users.
+
+## Known Limits
+
+These are current, accepted constraints:
+
+- no visible Bun-managed canvas window
+- no persistent automation-session orchestration beyond the single owned server session
+- no Chrome-only CDP tool surface yet
+
+## Future Work
+
+### Near-term
+
+The most obvious next steps are:
+
+1. Add an optional `canvas_cdp` MCP tool for Chrome-backed sessions only
+2. Decide whether the default macOS backend should stay `webkit` or move to `chrome` for stricter cross-platform parity
+3. Add more backend-specific test coverage if Bun behavior diverges between WebKit and Chrome
+
+### Later
+
+Defer these until Bun's API justifies them:
+
+1. Replace `openUrlInExternalBrowser()` with Bun.WebView for the normal interactive canvas window
+2. Add headed window management semantics
+3. Build user-facing browser controls around Bun.WebView if Bun documents those behaviors as stable
+
+## Decision Summary
+
+The project should continue with this split:
+
+- **Interactive canvas for humans**: external browser
+- **Programmatic canvas automation for agents/server workflows**: Bun.WebView
+
+That keeps the current user-facing behavior stable while giving PMX Canvas a real browser automation surface that is built into the runtime.