pmx-canvas 0.1.18 → 0.1.19

package/CHANGELOG.md

@@ -3,6 +3,59 @@
 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
@@ -771,6 +824,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.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

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.

package/docs/cli.md

@@ -0,0 +1,140 @@
+# CLI reference
+
+The CLI is the shell-native way to run and control PMX Canvas. It targets
+`http://localhost:4313` by default — override with `PMX_CANVAS_URL` or
+`PMX_CANVAS_PORT` when the server runs elsewhere.
+
+## Server lifecycle
+
+```bash
+pmx-canvas                            # Start canvas, open browser
+pmx-canvas --demo                     # Start with the project-tour demo board
+pmx-canvas --port=8080                # Custom port
+pmx-canvas --no-open                  # Headless (for agents/CI)
+pmx-canvas --theme=light              # dark | light | high-contrast
+pmx-canvas --mcp                      # Run as MCP server (stdio)
+pmx-canvas --webview-automation       # Start headless Bun.WebView session
+pmx-canvas open                       # Open the current workbench in a browser
+```
+
+### Daemon mode
+
+Run detached with pid/log tracking instead of holding a terminal:
+
+```bash
+pmx-canvas serve --daemon --no-open --wait-ms=20000   # Start detached, wait for health
+pmx-canvas serve status                               # Inspect daemon health + pid
+pmx-canvas serve stop                                 # Stop the daemon for this port
+```
+
+## Nodes and edges
+
+```bash
+pmx-canvas node add --type webpage --url https://example.com/docs
+pmx-canvas node add --type web-artifact --title "Dashboard" --app-file ./App.tsx
+pmx-canvas node add --type graph --graph-type bar --data-file ./metrics.json --x-key label --y-key value
+pmx-canvas node add --type graph --graph-type bar --data '[{"x":"a","y":1}]' --x-key x --y-key y
+pmx-canvas graph add --graph-type bar --data '[{"x":"a","y":1}]' --x-key x --y-key y   # Alias
+pmx-canvas node add --help --type webpage --json                                        # Schema for one type
+
+pmx-canvas external-app add --kind excalidraw --title "Diagram"
+
+pmx-canvas edge add --from-search "DVT O3 — GitOps" --to-search "deep work trend" --type relation
+```
+
+`--from-search` / `--to-search` must each resolve to exactly one node — broad
+queries fail rather than guess. Use the full visible title.
+
+CLI create commands return the created node shape with normalized title,
+content, and geometry, which makes scripting stacked layouts and batch
+follow-ups easier.
+
+### Graph height flags
+
+Graph height flags split by target:
+
+- `--node-height` / `--nodeHeight` — the canvas node frame
+- `--chart-height` — the chart content inside the node
+- `--height` — accepted as a frame-height compatibility alias
+
+For MCP/HTTP payloads, use `nodeHeight` for the frame and `height` for chart
+content.
+
+## Discovery and validation
+
+```bash
+pmx-canvas node schema --type json-render --component Table --summary
+pmx-canvas validate                                                      # Layout validation
+pmx-canvas validate spec --type json-render --spec-file ./dashboard.json --summary
+```
+
+The schema commands surface the running server's data, which is strictly
+better than guessing flags or payloads.
+
+## Batch and arrange
+
+```bash
+pmx-canvas batch --file ./canvas-ops.json
+```
+
+See [HTTP API → batch](http-api.md#batch-operations) for the operation
+schema; the same JSON works for the CLI batch file.
+
+## Web artifacts
+
+```bash
+pmx-canvas web-artifact build --title "Dashboard" --app-file ./App.tsx --deps recharts --include-logs
+```
+
+Failed or empty CLI bundles print `ok: false`, exit non-zero, and do not
+create a canvas node.
+
+## Watch (semantic deltas)
+
+`pmx-canvas watch` consumes the SSE stream and emits compact semantic deltas
+for agents that need low-token updates instead of full layout snapshots. It
+filters noise from harmless moves and reports meaningful events such as pins,
+node additions/removals, group changes, edge connections, and moves that
+change spatial clustering.
+
+```bash
+pmx-canvas watch --events context-pin,move-end
+pmx-canvas watch --json --events context-pin --max-events 1
+```
+
+## Focus
+
+```bash
+pmx-canvas focus <node-id>            # Pan viewport to a node
+pmx-canvas focus <node-id> --no-pan   # Select/raise without panning
+```
+
+## WebView automation
+
+Drive a headless Bun.WebView (Chromium or WebKit) pointed at the workbench:
+
+```bash
+pmx-canvas webview status
+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
+```
+
+Use WebView for visual annotation inspection. Agent-readable canvas context only
+reports annotation targets and bounds; it does not describe whether the human
+drew an arrow, line, circle, or other shape. Inspect `.annotation-layer path` or
+take a screenshot when the drawn form matters.
+
+Humans draw with the pen toolbar button and remove marks with the eraser button.
+If an agent already knows the annotation ID from context, it can remove it through
+MCP with `canvas_remove_annotation`.
+
+## When to reach for the CLI
+
+- Direct terminal control without MCP wiring
+- Shell scripts and CI-friendly automation
+- Schema-driven discovery from the running server
+- Local debugging of canvas, webview, and screenshot flows
+- A control surface that covers normal canvas work without MCP wiring