pmx-canvas 0.3.4 → 0.4.0

package/dist/types/client/index.d.ts

@@ -1 +1 @@
-export {};
+import './uuid-polyfill';

package/dist/types/client/nodes/ExtAppFrame.d.ts

@@ -51,6 +51,16 @@ export declare function buildExtAppAxBridgeScript(axToken: string, nodeId: strin
  * the host also checks event.source against the live iframe.
  */
 export declare function buildExtAppBootBeaconScript(frameToken: string, nodeId: string): string;
+/**
+ * Base styles injected into every ext-app document (Finding Q, 0.3.4 report):
+ * apps aspect-fit their drawn surface to the frame width, and on narrow/tall
+ * tiles the leftover region shows the app document's own body background —
+ * pure black for the hosted Excalidraw bundle, in every engine. Making the
+ * app document transparent lets the host iframe's theme background
+ * (var(--c-panel)) show through the letterbox instead. Background only — app
+ * content, its drawn scene, and its own foreground styling are untouched.
+ */
+export declare function buildExtAppSurfaceBaseStyles(): string;
 export declare function injectExtAppAxBridgeScript(html: string, axBridgeScript: string): string;
 export declare function resolveExtAppContainerDimensions(target: ExtAppHostDimensionsTarget | null | undefined, fallback: {
     width: number;

package/dist/types/client/state/node-factory.d.ts

@@ -0,0 +1,29 @@
+import type { CanvasNodeState } from '../types';
+export declare const DEFAULT_POSITIONS: Record<CanvasNodeState['type'], {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}> & Record<'prompt' | 'response', {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}>;
+/**
+ * Build a canvas node with the shared client defaults. `position`/`size`
+ * default to the type's DEFAULT_POSITIONS entry; callers that compute
+ * placement (auto-placement, event-supplied geometry) pass explicit values.
+ * Status nodes sit at zIndex 0 (background chrome), everything else at 1.
+ */
+export declare function makeNodeState(id: string, type: CanvasNodeState['type'], data: Record<string, unknown>, options?: {
+    position?: {
+        x: number;
+        y: number;
+    };
+    size?: {
+        width: number;
+        height: number;
+    };
+    dockPosition?: 'left' | 'right' | null;
+}): CanvasNodeState;

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

@@ -35,7 +35,6 @@ export declare function listSnapshotsFromDB(db: Database, options?: CanvasSnapsh
 export declare function deleteSnapshotFromDB(db: Database, id: string): boolean;
 export declare function writeBlobToDB(db: Database, sha256: string, jsonValue: string): number;
 export declare function readBlobFromDB(db: Database, sha256: string): string | null;
-export declare function hasBlobInDB(db: Database, sha256: string): boolean;
 export interface AxTimelineQuery {
     limit?: number;
     sessionId?: string;

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

@@ -7,7 +7,9 @@
  *
  * Persistence: canvas state auto-saves to `.pmx-canvas/canvas.db` (SQLite WAL mode)
  * in the workspace root on every mutation (debounced). Auto-loads on `loadFromDisk()`.
- * Legacy `.pmx-canvas/state.json` is auto-migrated on first boot.
+ * Legacy pre-0.2 formats (`.pmx-canvas/state.json`, `.pmx-canvas.json`,
+ * `.pmx-canvas-snapshots/`, loose blob files) are no longer imported as of 0.4.0 —
+ * the one-shot boot migration into SQLite was retired.
  */
 import { type PersistedCanvasState, type CanvasTheme, type AxTimelineQuery } from './canvas-db.js';
 import { type PmxAxActivityKind, type PmxAxElicitation, type PmxAxModeRequest, type PmxAxMode, type PmxAxCommandDescriptor, type PmxAxPolicy, type PmxAxFocusState, type PmxAxSource, type PmxAxState, type PmxAxWorkItem, type PmxAxWorkItemStatus, type PmxAxApprovalGate, type PmxAxReviewAnnotation, type PmxAxReviewKind, type PmxAxReviewSeverity, type PmxAxReviewStatus, type PmxAxReviewAnchorType, type PmxAxReviewRegion, type PmxAxEvent, type PmxAxEventKind, type PmxAxEvidence, type PmxAxEvidenceKind, type PmxAxSteeringMessage, type PmxAxHostCapability, type PmxAxTimelineSummary } from './ax-state.js';
@@ -155,7 +157,7 @@ declare class CanvasStateManager {
     private notifyChange;
     private _mutationRecorder;
     private _suppressRecordingDepth;
-    /** Register a mutation recorder. Used by mutation-history to capture undo/redo closures. */
+    /** Register THE mutation recorder (single slot, last-write-wins — see note above). */
     onMutation(cb: (info: MutationRecordInfo) => void): void;
     /** Run a function with mutation recording suppressed (for undo/redo replay and computed edges). */
     withSuppressedRecording(fn: () => void): void;
@@ -171,7 +173,6 @@ declare class CanvasStateManager {
     private translateGroupChildren;
     private recomputeParentGroupBounds;
     private compactGroupChildren;
-    private _stateFilePath;
     private _db;
     private _saveTimer;
     /** Workspace root backing persistence and workspace-relative path resolution. */
@@ -188,20 +189,9 @@ declare class CanvasStateManager {
     isBlobReference(value: unknown): value is PersistedBlobRef;
     resolveBlobReference(value: unknown): unknown;
     private externalizePersistedStateBlobs;
-    /**
-     * One-time migration: rename files from the pre-consolidation layout
-     * (`.pmx-canvas.json` + `.pmx-canvas-snapshots/`) into `.pmx-canvas/`.
-     * No-op when the new layout already exists.
-     */
-    private migrateLegacyLayout;
-    /**
-     * One-time migration: import state.json + snapshot JSON files + blob files
-     * into the SQLite database. Renames originals to `.bak`.
-     */
-    private migrateJsonToSqlite;
     getWorkspaceRoot(): string;
     private emptyPersistedState;
-    /** Load canvas state from SQLite (or legacy JSON fallback). Call once on server startup. */
+    /** Load canvas state from SQLite. Call once on server startup. */
     loadFromDisk(options?: LoadFromDiskOptions): boolean;
     /**
      * Whether this workspace's canvas DB already holds saved state. Used to gate
@@ -215,6 +205,15 @@ declare class CanvasStateManager {
     flushToDisk(): void;
     /** Write current state to SQLite immediately. */
     private saveToDisk;
+    private _lastPersistenceError;
+    /** Health view of state persistence: ok until a save fails, ok again after the next success. */
+    get persistenceHealth(): {
+        ok: boolean;
+        lastError: {
+            message: string;
+            at: string;
+        } | null;
+    };
     /** Close the SQLite database cleanly. Call on server shutdown. */
     close(): void;
     private get snapshotsDir();

package/dist/types/server/operations/composites.d.ts

@@ -16,27 +16,12 @@
  * operation (plan-005 slices 1–7 + plan-008 Wave 1) that is now reachable ONLY
  * through its composite (or `canvas_batch`).
  *
- * Deferred to v0.4: the `canvas_snapshot` composite (still a name collision —
- * see below). Its 6 legacy snapshot standalones (`canvas_snapshot`,
- * `canvas_list_snapshots`, `canvas_restore`, `canvas_delete_snapshot`,
- * `canvas_gc_snapshots`, `canvas_diff`) stay registered in v0.3.0 but are marked
- * deprecated (description-prefixed) per docs/api-stability.md's
- * deprecate-one-minor-before-removal rule. (`canvas_webview` shipped in plan-008
- * Wave 3 via runner injection; `canvas_app` shipped in Wave 4 — open-mcp-app /
- * diagram / build-artifact. Wave 5 folded the last three legacy tools
- * deprecate-only — NO per-action input-injection mechanism was needed:
- * `canvas_add_html_node` / `canvas_add_html_primitive` → `canvas_node` action
- * "add" (type:"html" [+ primitive]); `canvas_refresh_webpage_node` → `canvas_node`
- * action "update" (refresh:true). `canvas_screenshot` stays standalone — it
- * returns a binary image payload the composite/registry JSON wire shape does not
- * model.)
- *
- * Not shipped here: the `canvas_snapshot` composite (plan-006 #7). Its target
- * name is ALREADY a legacy standalone tool (the save-snapshot tool, op
- * `snapshot.save`), so it cannot be added additively without a name clash, and
- * repurposing `canvas_snapshot` to be action-discriminated now would break
- * existing callers. It lands in v0.4, in the same change that removes the 6
- * kept-but-deprecated legacy snapshot tools and frees the name.
+ * v0.4.0 completed the fold: the `canvas_snapshot` composite shipped (its name
+ * was held by the legacy save-snapshot standalone through v0.3.x, which — with
+ * the other 5 snapshot standalones — was deprecated in 0.3.0 and removed here
+ * per docs/api-stability.md's deprecate-one-minor-before-removal rule).
+ * `canvas_screenshot` stays standalone — it returns a binary image payload the
+ * composite/registry JSON wire shape does not model.
  *
  * This module must never import server.ts or index.ts.
  */

package/dist/types/server/server.d.ts

@@ -24,6 +24,7 @@
  * - GET  /api/canvas/json-render/view?nodeId=... -> local json-render viewer
  * - POST /api/canvas/web-artifact -> build bundled HTML artifact + optional canvas node
  * - GET  /api/workbench/events   -> SSE event stream
+ * - GET  /api/workbench/poll     -> proxy-safe polling transport (same events, JSON)
  * - GET  /api/workbench/state    -> workbench state snapshot
  * - POST /api/workbench/intent   -> workbench intents
  * - GET  /api/workbench/webview  -> Bun.WebView automation status

package/docs/cli.md

@@ -51,6 +51,11 @@ pmx-canvas node add --help --type webpage --json
 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
+
+# Updates return a compact { ok, id, position, size, updatedFields } envelope;
+# pass --full for the complete node payload (ext-app payloads can be huge).
+pmx-canvas node update <node-id> --width 840 --height 620
+pmx-canvas node update <node-id> --title "Renamed" --full
 ```
 
 `--from-search` / `--to-search` must each resolve to exactly one node — broad

package/docs/environment.md

@@ -8,7 +8,7 @@ optional; defaults are listed.
 | Variable | Read by | Effect |
 |---|---|---|
 | `PMX_WEB_CANVAS_PORT` | server, CLI `serve` | Preferred server port (default `4313`). CLI `--port` wins over it. |
-| `PMX_CANVAS_PORT` | agent CLI, MCP transport | Client-side default target port for CLI commands and the `--mcp` same-workspace lookup. Does not change what the server binds. |
+| `PMX_CANVAS_PORT` | all entry points | Client-side target port for CLI commands and the `--mcp` lookup; as of 0.4.0 the server also falls back to it when `--port`/`PMX_WEB_CANVAS_PORT` are unset, so one var can drive the whole stack. |
 | `PMX_CANVAS_URL` | agent CLI, MCP transport | Full base URL target (wins over `PMX_CANVAS_PORT`). |
 | `PMX_CANVAS_WORKSPACE_ROOT` | server, MCP transport | Pins the workspace root for daemon binds and the MCP same-workspace lookup, overriding the launch cwd. Set it when a host spawns `--mcp` from an incidental dir. |
 | `PMX_CANVAS_ALLOW_WORKSPACE_SPLIT` | MCP transport | `1` forces a separate canvas instead of attaching to a different-workspace daemon on the preferred port. |
@@ -18,7 +18,7 @@ optional; defaults are listed.
 | Variable | Read by | Effect |
 |---|---|---|
 | `PMX_CANVAS_DB_PATH` | server | Overrides the SQLite path (default `.pmx-canvas/canvas.db`). |
-| `PMX_CANVAS_STATE_FILE` | server | Legacy JSON state path (back-compat; a `.db` value is treated as the DB path). |
+| `PMX_CANVAS_STATE_FILE` | server | `.db`-path alias only as of 0.4.0 (non-`.db` values are ignored with a boot warning; the pre-0.2 JSON import was removed). |
 | `PMX_CANVAS_BLOB_THRESHOLD_BYTES` | server | Node payloads above this many JSON bytes are stored as blobs (default `2048`). |
 
 ## Server behavior

package/docs/http-api.md

@@ -5,7 +5,9 @@ any language. Default base URL: `http://localhost:4313`.
 
 A non-empty request body that is not valid JSON returns
 `400 { "ok": false, "error": "Malformed JSON body." }` on every route; empty
-bodies are treated as an empty request.
+bodies are treated as an empty request. As of 0.4.0 every error response is a
+JSON envelope of that same shape (`{ ok: false, error }`, status unchanged) —
+no plain-text errors remain.
 
 ## Canvas state
 
@@ -321,6 +323,28 @@ curl -N http://localhost:4313/api/workbench/events
 The browser, the CLI `watch` command, and the MCP resource notifications
 all consume this stream. Auto-reconnect with exponential backoff.
 
+## Polling transport (proxy-safe)
+
+Some proxies (e.g. the Amp orb portal) buffer streaming responses and only
+flush them on close, so the SSE stream above delivers nothing. The polling
+transport returns the same events as short-lived JSON responses that pass
+through any proxy:
+
+```bash
+# No `since`: a full connect snapshot (same events an SSE connect sends) + the
+# current cursor. With `since=<seq>`: only events after that cursor.
+curl "http://localhost:4313/api/workbench/poll"
+curl "http://localhost:4313/api/workbench/poll?since=42"
+```
+
+Responses are `{ ok, transport: "poll", snapshot, seq, events }` — poll again
+with `since=<seq>` every couple of seconds. A `since` from a previous server
+run or one that fell off the bounded event ring recovers with a fresh
+snapshot. The browser client uses this automatically: if the SSE stream
+produces no event within 3 seconds of connecting, it switches to polling.
+Force a transport with `/workbench?transport=poll` (or `transport=sse` to
+disable the fallback).
+
 ## Time travel
 
 ```bash

package/docs/mcp.md

@@ -1,19 +1,17 @@
 # MCP reference
 
-PMX Canvas ships an MCP stdio server with **27 tools** + **14 core resources**,
+PMX Canvas ships an MCP stdio server with **22 tools** + **14 core resources**,
 plus per-skill resources at `canvas://skills/<name>`. The server emits
 `notifications/resources/updated` when canvas state changes — humans pin
 nodes in the browser, agents are notified immediately.
 
-> **Consolidation completed in v0.3.0 (plan-006/008).** The MCP surface shrank
-> from 84 tools to 27: 15 action-discriminated **composites** (recommended —
-> see below) plus 12 standalone tools. The 57 legacy single-purpose tools that
-> the composites replaced were removed in v0.3.0 per
-> [`api-stability.md`](api-stability.md); their descriptions carried
-> `Deprecated:` prefixes for one minor before removal. The 6 snapshot tools
-> remain registered as deprecated standalones — they fold into a
-> `canvas_snapshot` composite in v0.4 (see [Standalone tools](#standalone-tools)
-> below). **Prefer the composites.**
+> **Consolidation complete (plan-006/008).** The MCP surface shrank from 84
+> tools to 22: 16 action-discriminated **composites** (recommended — see
+> below) plus 6 standalone tools. The 57 legacy single-purpose tools the
+> composites replaced were removed in v0.3.0, and v0.4.0 finished the fold by
+> shipping the `canvas_snapshot` composite and removing the 6 deprecated
+> snapshot standalones — each step per [`api-stability.md`](api-stability.md)'s
+> deprecate-one-minor-before-removal rule. **Prefer the composites.**
 
 ## Connect
 
@@ -54,6 +52,7 @@ its `action` to the same operation the legacy tool used, so results are identica
 | `canvas_ax_timeline` | `read` · `record-event` · `add-evidence` · `send-steering` | `canvas_get_ax_timeline`, `canvas_record_ax_event`, `canvas_add_evidence`, `canvas_send_steering` |
 | `canvas_ax_delivery` | `claim` · `mark` | `canvas_claim_ax_delivery`, `canvas_mark_ax_delivery` |
 | `canvas_intent` | `signal` · `update` · `clear` | _(new — Ghost Cursor of Intent; no legacy standalone tool)_ |
+| `canvas_snapshot` | `save` · `list` · `restore` · `delete` · `gc` · `diff` | `canvas_snapshot` (legacy save tool), `canvas_list_snapshots`, `canvas_restore`, `canvas_delete_snapshot`, `canvas_gc_snapshots`, `canvas_diff` — removed in v0.4.0 after one deprecated minor |
 
 ### `canvas_intent` — Ghost Cursor of Intent
 
@@ -89,20 +88,16 @@ tools). `canvas_screenshot` also stays standalone — it returns a binary image
 the composite/registry JSON wire shape does not model. (Wave 5 folded
 `canvas_refresh_webpage_node` → `canvas_node { action: "update", refresh: true }` after
 fixing `node.update`'s `formatResult` to surface a FAILED refresh as `isError` +
-`{ ok:false, error }` instead of masking it as a false `{ ok:true }`.) The 6
-snapshot tools are the one deferred fold: a `canvas_snapshot` composite is
-planned for v0.4 (the name collides with the legacy `canvas_snapshot` save
-tool, and [`api-stability.md`](api-stability.md) requires deprecating a tool
-for one minor before removing it) — they stay registered as deprecated
-standalones until then.
+`{ ok:false, error }` instead of masking it as a false `{ ok:true }`.) The snapshot
+fold completed in v0.4.0: `canvas_snapshot { action: "save" | "list" | "restore" |
+"delete" | "gc" | "diff" }` replaced the 6 deprecated snapshot standalones.
 
 ## Standalone tools
 
-12 tools that intentionally stay outside the composites — either because
-folding them would hurt (distinct callers, binary payloads, trust-boundary or
-execution-intent semantics), or because they're mid-deprecation pending a
-v0.4 composite. See [Migration reference](#migration-reference) below for the
-57 tools these composites replaced.
+6 tools that intentionally stay outside the composites — folding them would
+hurt (distinct callers, binary payloads, trust-boundary or execution-intent
+semantics). See [Migration reference](#migration-reference) below for the
+legacy tools the composites replaced.
 
 | Tool | Description |
 |------|-------------|
@@ -112,12 +107,6 @@ v0.4 composite. See [Migration reference](#migration-reference) below for the
 | `canvas_ax_interaction` | Submit one capability-gated AX interaction envelope (`{ type, sourceNodeId, payload }`) that maps onto an AX operation; the server re-validates and clamps sandboxed surfaces to their own node |
 | `canvas_ingest_activity` | Ingest a harness-forwarded agent activity (tool/session event); the board auto-reacts with kind-driven, overridable defaults (failure → work item + review + evidence; `tool-result`+success → evidence). Makes AX bidirectional |
 | `canvas_screenshot` | Capture a screenshot from the active workbench automation session |
-| `canvas_snapshot` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). Save current canvas as a named snapshot |
-| `canvas_list_snapshots` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). List saved snapshots, bounded to the newest 20 by default |
-| `canvas_restore` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). Restore canvas from a saved snapshot |
-| `canvas_delete_snapshot` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). Delete a saved snapshot |
-| `canvas_gc_snapshots` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). Delete old snapshots while keeping the newest N |
-| `canvas_diff` | **Deprecated** → folds into the `canvas_snapshot` composite in v0.4 (actions `save\|list\|restore\|delete\|gc\|diff`). Compare current canvas vs a saved snapshot |
 
 `canvas_node { action: "add", type: "html" }` accepts optional `summary`, `agentSummary`,
 `embeddedNodeIds`, and `embeddedUrls`. PMX also derives a bounded text summary from visible
@@ -125,7 +114,9 @@ HTML, so rich HTML nodes stay searchable and readable in pinned/spatial context.
 
 ## Migration reference
 
-The 57 legacy single-purpose tools below were removed in v0.3.0. Each row is
+The 57 legacy single-purpose tools below were removed in v0.3.0, and v0.4.0
+additionally removed the 6 deprecated snapshot standalones (see the
+`canvas_snapshot` composite row above for their replacements). Each row is
 the composite call that replaces it — kept as a lookup table for anyone
 migrating an older integration.
 
@@ -304,5 +295,5 @@ CLI and MCP are kept aligned for the main canvas operations: node and edge
 creation, graph/json-render/html/html-primitive nodes, web artifacts, external apps, groups,
 batch builds, layout validation, snapshots, search, focus, pins, undo/redo,
 semantic watch streams, WebView automation, and daemon/server control where
-it applies. A few agent-native capabilities — resource subscriptions and
-`canvas_diff` — remain MCP-only.
+it applies. A few agent-native capabilities — such as resource
+subscriptions — remain MCP-only.

package/docs/plans/plan-009-tech-debt-backlog.md

@@ -11,7 +11,8 @@ Each item is tagged by shape: **project** (multi-day, own plan/PR), **decision**
 The remaining items were re-analyzed with pros/cons and tiered; the maintainer approved this ordering:
 
 - **Tier 1 (do):** CLI raw fetches → operation invoker **together with** the H3 parser/module split (same file, one project); H7 test coverage **as a prerequisite** for any client refactor; M2 AX-bridge dedup (first client task after H7); the M8 flake subset (mock the Excalidraw network tests, share `getAvailablePort`, Playwright `retries`/`forbidOnly`, `e2e-cli` into CI). *C1b done (2026-07-08):* all 60 raw `api()` calls migrated onto the invoker (9-agent verified mapping; `webartifact.build` gained `errorBodyAsResult`; batch failure prints the envelope + exits 1; the `api()` helper is deleted; two deliberate raw `fetch` sites remain — binary screenshot, SSE watch). *H3 module split done (2026-07-09):* `agent.ts` is a 227-line entry over `src/cli/shared.ts` (cycle-free core: registry, parser, transport) + 11 `src/cli/commands/*` domain modules, moved byte-identically; ax-parity reads the whole cli tree. **Parser sub-item reshaped:** `parseFlags`/`BOOL_FLAGS` is now single-sited in shared.ts; `index.ts` keeps its intentionally tiny fixed-flag launcher reader (different domain — server launch, not agent commands). The spec-driven per-command flag parser (`defineCommand`) remains the ideal but is a redesign of all 83 command surfaces — deferred to a future CLI UX change, not worth manufactured churn now.
-- **Tier 2 (reshaped):** the PmxCanvas→executeOperation collapse is **not** mechanical — `executeOperation` is async while 57/76 SDK methods are sync with typed returns, so a full collapse is a breaking SDK change. Verdict: migrate only the already-async/void methods now; decide the full async-SDK question as a **v0.4 breaking item** with the `canvas_snapshot` composite. Post-registry the sync methods are thin presentation over the shared cores (single logic site) — not logic duplication. H5 (sse-bridge factory) proceeds **after H7**. M6 gets the middle path: runtime per-action required-field errors, no `oneOf` schema break (many MCP hosts handle `oneOf` poorly). M1 gets the minimum four (minify, devtools→devDeps, lazy-load, replace the python mtime gate); the React-stack decision stays open.
+- **Tier 2 — async-SDK question DECIDED NO (2026-08-03, v0.4.0):** the sync `PmxCanvas` facade is the contract. Post-registry the 57 sync methods are thin presentation over the shared operation cores (single logic site — the tier's own analysis), so forcing them async would break every SDK consumer to remove zero duplication. The already-async/void methods dispatch through `executeOperation`; the rest stay sync by design. No further collapse is planned.
+- **Tier 2 (original analysis):** the PmxCanvas→executeOperation collapse is **not** mechanical — `executeOperation` is async while 57/76 SDK methods are sync with typed returns, so a full collapse is a breaking SDK change. Verdict: migrate only the already-async/void methods now; decide the full async-SDK question as a **v0.4 breaking item** with the `canvas_snapshot` composite. Post-registry the sync methods are thin presentation over the shared cores (single logic site) — not logic duplication. H5 (sse-bridge factory) proceeds **after H7**. M6 gets the middle path: runtime per-action required-field errors, no `oneOf` schema break (many MCP hosts handle `oneOf` poorly). M1 gets the minimum four (minify, devtools→devDeps, lazy-load, replace the python mtime gate); the React-stack decision stays open.
 - **Tier 3 (cheap batch):** CI check that CLAUDE.md/AGENTS.md stay identical (instead of doc generation); document `PMX_DATA` + the `PMX_CANVAS_JSON_RENDER_*`/`PMX_MCP_APP_HOST_*` env families; publish.yml verifies the tag SHA passed test.yml; `@types/turndown` → devDependencies; L1 dead `ContextPinHud`; L4 one-shot migration marker; L6 timer-leak fixes.
 - **Tier 4 (closed as by-design / parked):** the six server-coupled routes (nothing to dedup — injection machinery for single-copy handlers isn't worth it); M3 ExtAppFrame refactor (the timing hacks are load-bearing WebKit fixes — document invariants, enter only when a feature forces it); M7 notification fan-out, L2, L3, `noUncheckedIndexedAccess` (parked); M10 packaging closed after the `@types` one-liner (`bin`→`src` under Bun and shipped `dist/` are both load-bearing by design).
 
@@ -19,10 +20,10 @@ The remaining items were re-analyzed with pros/cons and tiered; the maintainer a
 
 | Item | Source | What's open | Shape |
 |---|---|---|---|
-| Complete the registry migration | C1 | Fold the remaining hand-written routes in `server.ts` into operations; collapse the 76-method `PmxCanvas` onto `executeOperation`; migrate the CLI's 60 raw `fetch` calls onto the operation invoker. **Slice 1 done post-0.3.0:** the 7 `/api/ext-app/*` routes moved to `ops/ext-app.ts` (~290 lines out of `server.ts`, the 5 clone handlers — old M5 — collapsed to one parametrized definition; wire envelopes byte-identical, no new MCP tools). **Slice 2 done:** the 15 ax wire routes (8 GET lists + `ax/context` + `ax/surface-snapshot` + `pinned-context` + `code-graph` + `ax/activity` + `ax/interaction` + legacy `PATCH /api/canvas/ax`) moved to `ops/ax-read.ts` (~370 more lines out of `server.ts`); `open-external` stays hand-written (coupled to the live server port + system browser opener). **Slice 3 done:** theme GET/POST, canvas update, viewport, annotation POST, and node `:id/refresh` moved to the registry (`ops/canvas-wire.ts`, plus additions to `ops/viewport.ts`, `ops/annotation.ts`, `ops/nodes.ts`); the two dispatch gates unified into one `/api/` gate; `server.ts` is at ~2,980 lines (from 3,873 at the audit). **Remaining routes (~20)** are the deliberate poor fits (SSE, binary, HTML/static, file bodies) plus four server-coupled handlers: `prompt` + workbench `state`/`open`/`intent` (module-local `primaryWorkbench*` session state), `render` (Excalidraw URL-normalizer chain), `open-external` (live port + system browser). Those need state injection like the webview runner — a deliberate follow-up, not mechanical. After routes, the bigger halves remain: `PmxCanvas` (76 methods) onto `executeOperation`, and the CLI's raw fetches onto the invoker. | project (in progress) |
-| One HTTP envelope | M4 residual | Registry ops return bare bodies, legacy ext-app handlers `{ok:true,result}`, 404s plaintext. **Reclassified v0.4-breaking (2026-08-03):** unifying changes response shapes that the Copilot adapter and the external test harnesses parse — it cannot ship in a patch. Bundle with the other v0.4 breaking items (`canvas_snapshot` composite, async-SDK decision). The `/health` degraded flag for the 63 catch→warn→continue persistence sites is additive and can ship earlier. | project (v0.4) |
+| Complete the registry migration | C1 | Fold the remaining hand-written routes in `server.ts` into operations; collapse the 76-method `PmxCanvas` onto `executeOperation`; migrate the CLI's 60 raw `fetch` calls onto the operation invoker. **Slice 1 done post-0.3.0:** the 7 `/api/ext-app/*` routes moved to `ops/ext-app.ts` (~290 lines out of `server.ts`, the 5 clone handlers — old M5 — collapsed to one parametrized definition; wire envelopes byte-identical, no new MCP tools). **Slice 2 done:** the 15 ax wire routes (8 GET lists + `ax/context` + `ax/surface-snapshot` + `pinned-context` + `code-graph` + `ax/activity` + `ax/interaction` + legacy `PATCH /api/canvas/ax`) moved to `ops/ax-read.ts` (~370 more lines out of `server.ts`); `open-external` stays hand-written (coupled to the live server port + system browser opener). **Slice 3 done:** theme GET/POST, canvas update, viewport, annotation POST, and node `:id/refresh` moved to the registry (`ops/canvas-wire.ts`, plus additions to `ops/viewport.ts`, `ops/annotation.ts`, `ops/nodes.ts`); the two dispatch gates unified into one `/api/` gate; `server.ts` is at ~2,980 lines (from 3,873 at the audit). **Remaining routes (~20)** are the deliberate poor fits (SSE, binary, HTML/static, file bodies) plus four server-coupled handlers: `prompt` + workbench `state`/`open`/`intent` (module-local `primaryWorkbench*` session state), `render` (Excalidraw URL-normalizer chain), `open-external` (live port + system browser). Those need state injection like the webview runner — a deliberate follow-up, not mechanical. **Status (2026-08-03):** the CLI fetches are done (C1b) and the `PmxCanvas` collapse is closed by the async-SDK decision (sync facade stays). The 4 server-coupled routes (`prompt`, workbench `state`/`open`/`intent`, `render`, `open-external`) remain the only open C1 work — internal state-injection refactor, zero wire impact, deliberately post-0.4. | tail open (post-0.4) |
+| One HTTP envelope | M4 residual | **Done (2026-08-03, v0.4.0):** every hand-written error response is now a JSON `{ ok:false, error }` envelope with unchanged status codes (matching the registry dispatcher); `/health` gained a `persistence` block that reports degraded durability after a failed save (ok again on the next success). The ext-app `{ok:true,result}` wrapper is KEPT deliberately — it is the app-bridge proxy contract our own panel parses; changing it bought no consumer value. | done |
 | `dist/` commit policy | C3 residual | **Decided + done post-0.3.0:** `dist/` stays committed; `test.yml` now has a `dist/types` staleness gate (rebuild + fail on drift). The `dist/canvas`/`dist/json-render` bundles are deliberately not byte-checked — bundler output varies across bun versions; their staleness story folds into M1. | done |
-| Skill-mirror validator | C2 residual | `validate:agent-skills` exits 0 when the (local-only, gitignored) trees are absent. Docs are honest about this now; decide whether to repoint, gate, or delete the check. | decision |
+| Skill-mirror validator | C2 residual | **Decided + done (2026-08-03):** the script prints a labeled SKIPPED notice when trees are absent (local behavior unchanged), and the permanently-no-op CI step was removed with a comment. | done |
 | Generate CLAUDE.md/AGENTS.md from one source | M9 residual | **Done (tier-3 batch):** CI fails on any CLAUDE.md/AGENTS.md byte drift (`test.yml` identity gate) — the cheap alternative to generation the decision analysis chose. Generation/symlinking stays unnecessary while the gate holds. | done |
 
 ## Phase 2 — make the safety net real
@@ -30,19 +31,19 @@ The remaining items were re-analyzed with pros/cons and tiered; the maintainer a
 | Item | Source | What's open | Shape |
 |---|---|---|---|
 | Lint/format tooling | H6 | **Done post-0.3.0:** Biome 2.5 adopted — `bun run lint` / `lint:fix`, wired into `release:check` (making RELEASE.md's "lints" claim true) and CI. First-run format sweep landed as its own mechanical commit; 7 lint errors hand-fixed (incl. a real conditional-hooks bug in `SelectionBar.tsx`). Deliberately disabled rules to revisit: a11y group, `useExhaustiveDependencies` (misfires on Preact signals), `noNonNullAssertion` (143 deliberate uses), `noArrayIndexKey` (13 sites). ~77 warnings (unused imports/vars, optional-chain) left as a burn-down list — warnings don't fail the gate. | done |
-| Client + server unit coverage | H7 | **Done post-0.3.3 (first tranche):** happy-dom + @testing-library/preact harness under `tests/client/` (own preload so DOM globals never leak into server suites); 20 client render tests incl. the SelectionBar conditional-hooks regression; `semantic-attention` (25 tests) and `canvas-schema` (21 tests incl. an M12 stale-tool-drift invariant) covered; tests are TYPECHECKED (`tsconfig.tests.json`, 270 latent errors fixed, wired into `typecheck` + CI); coverage now GATES via `scripts/check-coverage.ts` total floors (bun's bunfig threshold is per-file and its table form is silently ignored — documented). **Remaining (opportunistic):** dedicated tests for `ax-state-manager.ts` and `mcp-app-host.ts`, and growing the client suite alongside H5/M2 work. | first tranche done |
+| Client + server unit coverage | H7 | **Done post-0.3.3 (first tranche):** happy-dom + @testing-library/preact harness under `tests/client/` (own preload so DOM globals never leak into server suites); 20 client render tests incl. the SelectionBar conditional-hooks regression; `semantic-attention` (25 tests) and `canvas-schema` (21 tests incl. an M12 stale-tool-drift invariant) covered; tests are TYPECHECKED (`tsconfig.tests.json`, 270 latent errors fixed, wired into `typecheck` + CI); coverage now GATES via `scripts/check-coverage.ts` total floors (bun's bunfig threshold is per-file and its table form is silently ignored — documented). **Done (2026-08-03):** dedicated suites for `ax-state-manager.ts` (39 tests, injected-deps harness + in-memory SQLite) and `mcp-app-host.ts` (15 tests; stateful paths in hermetic subprocesses). Unit-test scripts now pin `PMX_MCP_APP_HOST_STATE_FILE` to a scratch path so suites never touch the real home-dir state. Client suite grows alongside H5. | done |
 | Daemon port/lock lifecycle | H4 | **Fixed post-0.3.0** (`src/cli/daemon.ts` + `tests/unit/cli-daemon.test.ts`). Note the original finding was partly wrong: the daemon child was already strict-port (`PmxCanvas.start` pins `allowPortFallback: false`), so fallback-blind polling could not occur. The real defects — fixed — were: the pre-check accepted any responsive `/health` as "already running" (even a foreign workspace's daemon), a TOCTOU double-spawn window, the pid recorded only after health passed (slow start → unkillable orphan), and no PID-recycling guard. The flaky `pmx-canvas-sdk.test.ts` port collision is NOT this — it's M8's copy-pasted `getAvailablePort()` racing. | done |
-| Test-suite structure | M8 | Integration monoliths under `tests/unit/` (`server-api` 5,213 lines, `cli-node` 2,903); `getAvailablePort()` copy-pasted in 5 files; `waitForPersistence(650ms)` fixed sleeps in 9 files + ~19 magic `Bun.sleep`s; Playwright lacks `retries`/`forbidOnly`; `test:e2e-cli` (517-line script) runs in no CI workflow. *Post-0.3.0:* `operation-parity` now binds port 0 and derives the port from the base URL (removes one reserve-then-rebind race); the shared-helper dedup and the rest remain. Also noted: `ax-parity.test.ts` is a string-matching source-analysis test whose needles broke when Biome re-wrapped `cmd(` calls — its CLI needles are now layout-independent, but any future needle should avoid depending on line layout. **Also noted (2026-07-07):** the `server-api` Excalidraw diagram tests do real network round-trips to the hosted `mcp.excalidraw.com` MCP server and intermittently time out (30s) under full parallel runs. **M8 subset done (2026-07-08):** those tests now run against the local stdio fixture via `PMX_CANVAS_EXCALIDRAW_MCP_COMMAND`; `getAvailablePort` is one shared helper; Playwright has `retries`/`forbidOnly` on CI; `e2e-cli` is a CI job. **Remaining (parked):** the `tests/unit/` monolith split and the `waitForPersistence` fixed-sleep sweep. | subset done |
+| Test-suite structure | M8 | Integration monoliths under `tests/unit/` (`server-api` 5,213 lines, `cli-node` 2,903); `getAvailablePort()` copy-pasted in 5 files; `waitForPersistence(650ms)` fixed sleeps in 9 files + ~19 magic `Bun.sleep`s; Playwright lacks `retries`/`forbidOnly`; `test:e2e-cli` (517-line script) runs in no CI workflow. *Post-0.3.0:* `operation-parity` now binds port 0 and derives the port from the base URL (removes one reserve-then-rebind race); the shared-helper dedup and the rest remain. Also noted: `ax-parity.test.ts` is a string-matching source-analysis test whose needles broke when Biome re-wrapped `cmd(` calls — its CLI needles are now layout-independent, but any future needle should avoid depending on line layout. **Also noted (2026-07-07):** the `server-api` Excalidraw diagram tests do real network round-trips to the hosted `mcp.excalidraw.com` MCP server and intermittently time out (30s) under full parallel runs. **M8 subset done (2026-07-08):** those tests now run against the local stdio fixture via `PMX_CANVAS_EXCALIDRAW_MCP_COMMAND`; `getAvailablePort` is one shared helper; Playwright has `retries`/`forbidOnly` on CI; `e2e-cli` is a CI job. **Sleep sweep done (2026-08-03):** fixed persistence sleeps replaced by condition polling via a shared helper. **Remaining (post-0.4, test organization only):** the `tests/unit/` monolith split. | sleep sweep done |
 | `noUncheckedIndexedAccess` | L7 residual | Enable in tsconfig; will surface many index-access errors — treat as its own sweep. | small (noisy) |
 
 ## Phase 3 — client consolidation
 
 | Item | Source | What's open | Shape |
 |---|---|---|---|
-| One node factory | H5 | `sse-bridge.ts` (1,066 lines) keeps its own `DEFAULT_POSITIONS`/`makeNode` divergent from `canvas-store`; `responseToThreadMap` is not cleaned on SSE reconnect; server-side `syncEventToCanvasState` (~330 lines) mirrors it as an if/else chain with geometry defaults duplicated against `ensureDefaultDockedNodes`. Share one factory; treat `canvas-layout-update` as the single source of truth; table-drive the event sync. | project |
+| One node factory | H5 | **Client half done (2026-08-03):** the `responseToThreadMap` reconnect leak is fixed (cleared in the shared per-connection reset path; mutation-verified test) and all four sse-bridge construction sites route through a shared `node-factory.ts`. **Premise correction:** `canvas-store` holds no node-creation defaults — the real divergences are client-vs-SERVER (server `defaultNodeSize` vs the client table; `ensureDefaultDockedNodes` seeding collapsed/docked vs the bridge's expanded/undocked; a same-class `serverResponseToThreadMap` leak at server.ts:2469) — all catalogued in the factory for the deferred server half (table-drive `syncEventToCanvasState`, single source of truth). | client half done |
 | Shared AX iframe bridge | M2 | **Done (2026-08-03):** `useAxSurfaceBridge` (`src/client/nodes/use-ax-surface-bridge.ts`) single-sites the sandboxed-surface trust boundary previously copy-pasted in `HtmlNode.tsx`, `McpAppNode.tsx`, `ExtAppFrame.tsx`; `src/shared/ax-surface-protocol.ts` owns the wire tags (`pmx-canvas-ax`, `-ack`, `pmx-canvas-html-node`, the ext-app boot beacon) — client parsers import them, generated surface scripts (html-surface.ts, ext-app builders, json-render viewer) interpolate them byte-identically. Client render tests pin the validation gates + submit→ack round-trip (`tests/client/use-ax-surface-bridge.test.tsx`). | done |
 | `ExtAppFrame.tsx` timing hacks | M3 | 915 lines, 12 refs, 7 `setTimeout`s, 5 rAFs, WebKit remount slot counter, 1200 ms fallback bootstrap, two near-duplicate `buildHostContext` blocks. Extract `useExtAppBridge`; single `buildHostContext`. | project |
-| json-render stack decision | M1 | Preact + React 19 + recharts all runtime deps; 7 exact-pinned `@json-render/*` incl. 3 devtools packages shipped; `dist/json-render/index.js` 1.37 MB and `dist/canvas/index.js` 599 KB both unminified; build script shells to python3 with a stale-bundle fallback. Minimum: minify, move devtools to devDependencies, lazy-load the viewer, replace the python mtime gate. Bigger call: separate optional package if the React stack stays. | decision + project |
+| json-render stack decision | M1 | **Minimum-four done (2026-08-03):** both bundles verified minified (the audit's "unminified" was stale — React+recharts dominate the 1.31 MiB minified size); the 2 `@json-render/devtools*` packages moved to devDependencies; the viewer is already a separate page bundle (nothing to lazy-load — verified, no churn manufactured); the python mtime gate is now Bun with parity-tested exit codes. **Still open (decision):** the React-stack question — a separate optional package remains the only real size lever. | decision |
 | Client dead code / duplication | L1, L2, L3 | `ContextPinHud.tsx` unreferenced; three pure re-export shims; two parallel markdown-format stacks; `global.css` 3,746 lines with 11 `!important` vs 227 inline styles and unscaled z-indexes. | small (batchable) |
 
 ## Smaller items (no phase, pick up opportunistically)
@@ -51,13 +52,13 @@ The remaining items were re-analyzed with pros/cons and tiered; the maintainer a
 |---|---|---|
 | Per-action composite schemas | M6 | **Done (2026-08-03, middle path per the decision analysis):** composite dispatch re-enforces each member op's required MCP fields at runtime and names the missing field (`requiredMcpFields` in `operations/mcp.ts`) — no `oneOf` schema break (many MCP hosts handle `oneOf` poorly). Advertised schemas stay all-optional by design. |
 | Packaging | M10 | `files` ships both `src/` and `dist/` (~double tarball, two import paths); `bin` points at raw `.ts` (undocumented Bun-only constraint); `@types/turndown` in runtime deps. |
-| Env var hygiene | M11 residual | Docs side **done (tier-3 batch)**: `docs/environment.md` covers `PMX_DATA` + the `PMX_CANVAS_JSON_RENDER_*`/`PMX_MCP_APP_HOST_*` families. Still open: `PMX_CANVAS_PORT` vs `PMX_WEB_CANVAS_PORT` applied inconsistently across entry points (partly mitigated by the global `--port`/`--server-url` CLI flags). |
+| Env var hygiene | M11 residual | **Done (2026-08-03):** server startup now falls back `--port` → `PMX_WEB_CANVAS_PORT` → `PMX_CANVAS_PORT` → 4313, so setting only the client var no longer splits client and server ports; documented in `docs/environment.md`. |
 | `publish.yml` e2e gap | M11 residual | **Done (tier-3 batch):** publish.yml verifies the tagged SHA has a successful `test.yml` run before publishing. |
 | MCP notification fan-out | M7 residual | Five `canvas://` resource URIs notify on every mutation regardless of type (`mcp/server.ts:95-99`). |
-| Legacy migration code on every boot | L4 | **Parked deliberately (2026-07-08):** the "unconditional" run is a couple of `existsSync` stats per boot — a one-shot marker adds state machinery to save nothing measurable and risks breaking upgrades from old layouts. Retire the migration code wholesale in a future major instead. |
-| Suppression/mutation plumbing | L5 | Two parallel suppression depth-counters; `onMutation` is a single-slot setter wired twice (last-write-wins). |
+| Legacy migration code on every boot | L4 | **Done (2026-08-03, v0.4.0 breaking window):** the pre-0.2 import path is deleted (~150 lines); fresh-boot bootstrapping untouched; `PMX_CANVAS_STATE_FILE` survives only as a `.db`-path alias with a boot warning otherwise. Verified with a legacy-artifacts smoke (files untouched, no `.bak`). |
+| Suppression/mutation plumbing | L5 | **Done (2026-08-03):** the "two counters" are semantically distinct by design (emit-suppression for batch vs recording-suppression for undo/redo — merging breaks one or the other; documented at both declarations). The redundant second `onMutation` wire in `PmxCanvas.start` was deleted; the slot contract is documented. |
 | Module-global lifecycle leaks | L6 | ~20 module-level `let`s in `server.ts`; code-graph debounce timer survives `stopCanvasServer`; remote SSE watcher loop has no cancellation. |
-| June doc citations | L7 residual | `tech-debt-assessment-2026-06.md` cites gitignored `.learnings/` entries future maintainers can't read. |
+| June doc citations | L7 residual | **Done (2026-08-03):** each cited entry's substance is inlined so the doc stands alone; one miscitation corrected. |
 
 ## Added post-0.3.3 (2026-08-03 sweep)
 

package/docs/tech-debt-assessment-2026-06.md

@@ -14,11 +14,11 @@ Code quality is better than the release velocity would suggest: zero `as any` ac
 
 Every operation is hand-written four times — `CanvasStateManager` → `PmxCanvas` → HTTP handler in `server.ts` → MCP tool in `src/mcp/server.ts` — each with its own validation and error shapes. The CLI (`src/cli/agent.ts`, 3,300 lines) duplicates it a fifth time with raw fetch calls instead of using the SDK.
 
-Evidence from `.learnings/` that this is actively producing bugs:
+Evidence from `.learnings/` that this is actively producing bugs (the `.learnings/` tree is gitignored, so the substance of each cited entry is inlined here):
 
-- [LRN-20260606-006] Fix #32 applied to only one of two duplicated mutation paths (`updateNode()` vs `applyUpdates()`).
-- [LRN-20260607-005] New `json-render` sourceSurface enum member silently took the permissive default because the `scoped` guard in `applyAxInteraction` was not updated. Security near-miss.
-- [LRN-20260608-002] `readJson` hardening silently killed the documented bare-array shape of `POST /api/canvas/batch` (#49).
+- [LRN-20260606-006] Fix #32 applied to only one of two duplicated mutation paths (`updateNode()` vs `applyUpdates()`). Both paths carried an identical copy of the group repack-on-resize logic, so fixing only the batch path left single-node `PATCH` updates still repacking siblings. The same entry records the parallel serializer pair drifting: the `nodeId` response alias was added to the MCP `createdNodePayload` but not the HTTP `buildNodeResponse`, so CLI/HTTP `node add --json` lacked it (#31).
+- [LRN-20260607-005] New `json-render` sourceSurface enum member silently took the permissive default because the `scoped` guard in `applyAxInteraction` was not updated. Security near-miss: the sandboxed viewer forwards author-controlled spec action params verbatim, so a prompt-injected spec could have anchored AX state onto arbitrary nodes via caller-supplied `nodeIds` (`on.press → { action: 'ax.work.create', params: { nodeIds: ['victim'] } }`). The fix added `json-render` to the clamp; the durable rule is that any guard switching on an enum-like string is a mandatory co-change site for every new member, or the new member takes the permissive default.
+- [LRN-20260608-002] `readJson` hardening silently killed the documented bare-array shape of `POST /api/canvas/batch` (#49). The #47 hardening normalized every non-object body — including top-level arrays — to `{}`, which turned the handler's `Array.isArray(body)` branch into dead code: bare-array batches returned `{ ok: true, results: [] }` and created nothing. Fixed with an array-preserving reader (`readJsonObjectOrArray`) used only by the batch endpoint.
 
 These are not three bugs. They are one architecture failing three times.
 
@@ -36,7 +36,7 @@ A project whose thesis is agent experience ships a tool surface that consumes a
 
 ### 4. E2E is not a CI gate (high)
 
-The Playwright/Bun ESM loader blocker ([ERR-20260508-001]) has been open for weeks. E2E was removed from the publish workflow after the apt-mirror hang ([LRN-20260603-002]) and does not gate PRs. The bugs that matter (iframe blank flicker, literal `\n` in ledger, SVG calc()) were all caught only by browser tests. Green CI can currently ship a broken canvas.
+The Playwright/Bun ESM loader blocker ([ERR-20260508-001]: `bun x playwright test` dies before test discovery because Playwright's transform layer tries to import a nonexistent `playwright.config.ts.esm.preflight` module under Bun; browser tests only run when Playwright is launched through Node with Bun on `PATH`) has been open for weeks. E2E was removed from the publish workflow after the apt-mirror hang ([LRN-20260603-001]: the `playwright install --with-deps chromium` step began reliably hanging ~15 minutes on GitHub runners with zero code change — a runner-image/apt regression — so publish dropped its redundant browser steps and kept build + typecheck + unit + smoke) and does not gate PRs. The bugs that matter (iframe blank flicker, literal `\n` in ledger, SVG calc()) were all caught only by browser tests. Green CI can currently ship a broken canvas.
 
 **Fix:** run Playwright via Node's runner in CI permanently, and make headless e2e a hard PR gate.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pmx-canvas",
-  "version": "0.3.4",
-  "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
+  "version": "0.4.0",
+  "description": "Spatial canvas workbench for coding agents \u2014 infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",
   "module": "./src/server/index.ts",
@@ -43,10 +43,10 @@
     "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
-    "test": "PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit",
-    "test:unit": "PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit",
+    "test": "PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit",
+    "test:unit": "PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit",
     "test:client": "bun test --preload ./tests/client/setup.ts tests/client",
-    "test:coverage": "bun test tests/unit --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir coverage && bun scripts/check-coverage.ts",
+    "test:coverage": "PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json bun test tests/unit --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir coverage && bun scripts/check-coverage.ts",
     "test:web-canvas": "PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun run build && PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bash scripts/run-playwright.sh",
     "test:e2e": "bun run test:web-canvas",
     "test:e2e-cli": "bash scripts/e2e-cli-coverage.sh",
@@ -60,8 +60,6 @@
   "dependencies": {
     "@joplin/turndown-plugin-gfm": "^1.0.64",
     "@json-render/core": "0.19.0",
-    "@json-render/devtools": "0.19.0",
-    "@json-render/devtools-react": "0.19.0",
     "@json-render/directives": "0.19.0",
     "@json-render/mcp": "0.19.0",
     "@json-render/react": "0.19.0",
@@ -80,6 +78,8 @@
   "devDependencies": {
     "@biomejs/biome": "^2.5.2",
     "@happy-dom/global-registrator": "^20.10.6",
+    "@json-render/devtools": "0.19.0",
+    "@json-render/devtools-react": "0.19.0",
     "@playwright/test": "^1.58.2",
     "@tailwindcss/cli": "^4.1.18",
     "@testing-library/preact": "^3.2.4",

package/skills/pmx-canvas/SKILL.md

@@ -26,8 +26,8 @@ Humans curate agent context by pinning nodes; agents read that curation through
 3. **Read before write.** Search with `canvas_query { action: "search", query }` before creating
    nodes. Read the full layout only when necessary. The MCP parameter is `query` — passing the
    HTTP API's `q` is silently ignored and returns zero results.
-4. **Snapshot before destructive changes.** Use `canvas_snapshot` (deprecated standalone; folds into
-   the `canvas_snapshot` composite's `save` action in v0.4) before clear, restore, or a major
+4. **Snapshot before destructive changes.** Use `canvas_snapshot { action: "save", name }` before
+   clear, restore, or a major
    reorganization.
 5. **Show intent with the Ghost Cursor — by default.** Signal with
    `canvas_intent { action: "signal", ... }` before every meaningful create, move, connect, remove,
@@ -36,7 +36,7 @@ Humans curate agent context by pinning nodes; agents read that curation through
    human watches intent form and can veto mid-thought. Skip it only for trivial in-place tweaks or
    high-frequency batch churn. The default TTL (~8s) expires between agent turns: signal with
    `ttlMs: 30000` and settle by passing `intentId` on the mutation in the same or next call.
-6. **Mutate through current composites.** Prefer the 15 composite MCP tools below.
+6. **Mutate through current composites.** Prefer the 16 composite MCP tools below.
 7. **Arrange and validate.** After batch changes, use `canvas_view { action: "arrange" }` when
    appropriate and always finish with `canvas_query { action: "validate" }`.
 8. **Verify context pins.** Pin with `canvas_pin_nodes` or the browser's **Pin as context**, then
@@ -115,6 +115,7 @@ json-render, a graph, or an HTML primitive is sufficient.
 | `canvas_ax_gate` | `request`, `resolve`, `await` with `approval`, `elicitation`, or `mode` |
 | `canvas_ax_timeline` | `read`, `record-event`, `add-evidence`, `send-steering` |
 | `canvas_ax_delivery` | `claim`, `mark` |
+| `canvas_snapshot` | `save`, `list`, `restore`, `delete`, `gc`, `diff` |
 | `canvas_intent` | `signal`, `update`, `clear` |
 
 Important routing:
@@ -131,9 +132,9 @@ Important routing:
 As of v0.3.0, the 57 legacy single-purpose tools from the v0.2 compatibility window are removed.
 The composites above plus the retained standalones are now the whole MCP surface: `canvas_batch`,
 `canvas_pin_nodes`, `canvas_screenshot`, `canvas_ax_interaction`, `canvas_ingest_activity`, and
-`canvas_invoke_command`. The 6 snapshot tools (`canvas_snapshot`, `canvas_list_snapshots`,
-`canvas_restore`, `canvas_delete_snapshot`, `canvas_gc_snapshots`, `canvas_diff`) are also retained
-but deprecated, pending a `canvas_snapshot` composite in v0.4.
+`canvas_invoke_command`. Snapshots are the `canvas_snapshot` composite (actions
+`save | list | restore | delete | gc | diff`); the 6 legacy snapshot standalones were removed in
+v0.4.0 after their deprecated 0.3.x window.
 
 ## Spatial Rules
 
@@ -228,6 +229,15 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
   (Chrome). Do not diagnose a healthy app session as a broken node. When reporting a black tile,
   fetch `GET /api/canvas/debug/ext-app-recovery` from the daemon and attach the trace — it shows
   what the recovery queue actually did in that panel.
+- A hosted ext-app (Excalidraw) resized NARROW/TALL (e.g. 360x529) can show its diagram in the
+  upper region with the app's own dark fill below it — in every engine (0.3.4 report Finding Q).
+  This letterboxing lives inside the hosted app bundle's root container, not in PMX (a body-level
+  background override ships but cannot reach the app's inner root). Keep ext-app tiles near the
+  app's aspect (the 960x738 default, or the same ratio), or expand the node — the fullscreen
+  overlay renders full-bleed. The durable fix is upstream in the excalidraw-mcp app.
+- Behind proxies that buffer streaming responses (e.g. portal hosts), the workbench auto-falls
+  back from SSE to a polling transport within ~3s, so the board still boots and stays live.
+  Force a mode with `/workbench?transport=poll` (or `transport=sse`) when diagnosing.
 - Graph and json-render standalone surfaces use `display=site` and fill the browser viewport, and
   reflow on a live window resize in a normal browser. Some single-tab host browsers (e.g. the
   Codex in-app browser) don't deliver live-resize events, so a resized standalone chart can look