pmx-canvas 0.3.4 → 0.4.1

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/nodes/iframe-document-url.d.ts

@@ -2,6 +2,7 @@ export declare function createIframeDocumentUrl(html: string, sandbox: string):
 export declare function useIframeDocument(html: string, sandbox: string): {
     attributes: {
         src?: string;
+        srcdoc?: string;
     };
     ready: boolean;
     key: string;

package/dist/types/client/nodes/use-surface-frame.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Attributes for a surface iframe, honoring the boot-wide iframe mode
+ * (state/iframe-mode.ts): `src` by default, fetch() + `srcdoc` when src-URL
+ * iframes are blocked by the embedding context (nested-iframe hosts like Amp
+ * orb portals). Cross-origin URLs always stay `src` — they cannot be fetched
+ * from here. While the probe is pending, same-origin frames stay empty rather
+ * than loading a src that may show the broken placeholder; a failed srcdoc
+ * fetch falls back to `src` (no worse than before).
+ */
+export declare function useSurfaceFrame(url: string): {
+    src?: string;
+    srcdoc?: string;
+};

package/dist/types/client/state/canvas-store.d.ts

@@ -5,6 +5,7 @@ export declare const edges: import("@preact/signals-core").Signal<Map<string, Ca
 export declare const annotations: import("@preact/signals-core").Signal<Map<string, CanvasAnnotation>>;
 export declare const activeNodeId: import("@preact/signals-core").Signal<string | null>;
 export declare const connectionStatus: import("@preact/signals-core").Signal<ConnectionStatus>;
+export declare const workbenchConnectionEpoch: import("@preact/signals-core").Signal<number>;
 export declare const sessionId: import("@preact/signals-core").Signal<string>;
 export declare const traceEnabled: import("@preact/signals-core").Signal<boolean>;
 export declare const canvasTheme: import("@preact/signals-core").Signal<string>;

package/dist/types/client/state/iframe-mode.d.ts

@@ -0,0 +1,25 @@
+export type IframeMode = 'src' | 'srcdoc';
+export declare const IFRAME_PROBE_PATH = "/api/canvas/iframe-probe";
+/** Boot-wide iframe transport mode; null until the probe (or override) resolves. */
+export declare const iframeMode: import("@preact/signals-core").Signal<IframeMode | null>;
+export declare function forcedIframeMode(): IframeMode | null;
+/**
+ * Probe whether `src`-URL iframes load in this embedding context. Resolves true
+ * when the hidden probe iframe fires `load`; false on error or timeout. The
+ * blocked-portal case shows its placeholder without reliably firing either
+ * event, so the timeout is the real signal there — and a false negative is
+ * safe, because srcdoc rendering works in normal hosts too.
+ */
+export declare function probeSrcIframes(timeoutMs?: number): Promise<boolean>;
+/**
+ * Resolve the boot-wide iframe mode once; all surface hooks share the result.
+ * The blocked-src condition only exists when the canvas page itself runs
+ * inside an iframe, so top-level documents resolve `src` synchronously — the
+ * normal path pays zero probe latency before surfaces mount. Only embedded
+ * documents run the probe (`embedded` is overridable for tests).
+ */
+export declare function resolveIframeMode(opts?: {
+    embedded?: boolean;
+}): Promise<IframeMode>;
+/** Test hook: clear the memoized probe so each test starts unresolved. */
+export declare function resetIframeModeForTests(): void;

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/RELEASE.md

@@ -128,12 +128,18 @@ it uses `NPM_TOKEN` directly.
 
 Every release since 0.3.0 has been retested against **stale** skill mirrors:
 consumer workspaces (e.g. `personalclaude`) carry copies of the pmx-canvas
-skill under `.github/`, `.codex/`, `.claude/`, and `.agents/`, and testers
+skills under `.github/`, `.codex/`, `.claude/`, and `.agents/`, and testers
 repeatedly had to sync them mid-cycle before results were trustworthy. After
 publishing, update the installed package in the consumer workspace and re-sync
-its four mirrors from
-`<global npm root>/pmx-canvas/skills/pmx-canvas/` so the first test pass runs
-against the released skill, not the previous version's guidance.
+its four mirrors from `<global npm root>/pmx-canvas/skills/` so the first test
+pass runs against the released skills, not the previous version's guidance.
+
+Sync the **complete tree of every bundled skill** — `pmx-canvas` AND
+`pmx-canvas-testing`, including `references/`, `evals/`, and fixtures — and
+verify by diffing whole directories, not by comparing the `SKILL.md` hash
+alone. The 0.3.4 and 0.4.0 cycles both hit drift where `SKILL.md` matched but
+references/evals were stale, or a newly bundled skill was missing from the
+mirrors entirely.
 
 ## GitHub release
 

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,50 @@ 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).
+
+## Iframe embed probe (nested-iframe hosts)
+
+Some hosts embed the canvas page itself inside an iframe (the Amp orb portal
+does), and Chrome then refuses to load child iframes from `src` URLs — even
+same-origin ones — so iframe-backed nodes would show a broken placeholder.
+When (and only when) the canvas page detects it is embedded, it probes the
+real behavior at boot by loading a hidden iframe against:
+
+```bash
+curl http://localhost:4313/api/canvas/iframe-probe
+```
+
+If that iframe never loads, the client switches every same-origin surface
+(HTML nodes, graph/json-render viewers, frame documents) to `fetch()` +
+`srcdoc` inline rendering. External app URLs stay on `src` — they cannot be
+fetched cross-origin. Force a mode with `/workbench?iframe-mode=srcdoc` (or
+`iframe-mode=src`).
+
+`/api/canvas/frame-documents/:id` also answers `HEAD`, which the browser uses
+after every reconnect to detect frame documents lost to a server restart and
+re-mint them automatically (Finding S).
+
 ## 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)
 
@@ -65,5 +66,13 @@ The remaining items were re-analyzed with pros/cons and tiered; the maintainer a
 |---|---|
 | Windows web-artifacts | The artifact build pipeline is bash-script-backed (POSIX-only); `tests/unit/web-artifacts.test.ts` self-skips on win32 and docs now state the boundary. Decide: port the build scripts to a cross-platform runner, or keep the documented "build on POSIX, render anywhere" stance. |
 | Composite parity no longer machine-checked | Since v0.3.0 removed the legacy standalones, the byte-identical composite-vs-legacy guarantee has no head-to-head test — regressions in `buildInput`/`formatResult` reuse surface only via output-shape assertions. Accepted at review; revisit if a composite drifts. |
-| Portal-layer ext-app mount (contingency) | If the maintainer sets the WebKit UX bar at "never any visible gap" (0.3.3 report leaves it open), inline ext-app iframes must render outside the world transform — an architectural change that reopens the parked M3. Only scope on a failing report cycle. |
+| Portal-layer ext-app mount (contingency) | If the maintainer sets the WebKit UX bar at "never any visible gap", inline ext-app iframes must render outside the world transform — an architectural change that reopens the parked M3. The 0.4.0 Copilot report keeps Finding N open (residual black after settled recovery; enlarge/close still the reliable unstick) — 0.4.1 ships a cheaper mimic first (post-settle WebKit repaint nudge, `repaint-nudge` trail event). If the next Copilot cycle still fails with the nudge in place, THIS contingency is the next step. |
+
+## Added post-0.4.0 (2026-08-04 report cycle)
+
+| Item | What's open |
+|---|---|
+| Finding S — frame documents vs server restart | **Done (2026-08-04):** the browser revalidates minted frame-document URLs on every reconnect epoch (`workbenchConnectionEpoch`, HEAD probe) and re-mints against the new process when the store is gone; `/api/canvas/frame-documents/:id` answers HEAD. Confirmed-fix pending the next Copilot/Codex kill-respawn cycle. Server-side persistence of frame docs deliberately NOT done — they are client-derived and re-mintable. |
+| Amp portal nested-iframe embedding | **Done (2026-08-04):** boot-time embed probe (`/api/canvas/iframe-probe`) + fetch()+srcdoc fallback for all same-origin surfaces (`useSurfaceFrame`, `useIframeDocument` srcdoc short-circuit), `?iframe-mode` override, e2e-forced-mode coverage. External (cross-origin) app URLs cannot be inlined — documented limitation. |
+| Copilot adapter `canvas_snapshot list` descriptor lag | Host-side cached tool schema still requires `name`; fresh `--mcp` is correct. Adapter/packaging issue, not a daemon defect — nothing to change in core; re-verify next cycle. |
 | Registry-migration dead-code sweep | **Done (2026-08-03):** removed the orphaned `describeOp`/`describeGateOp` (composites.ts, dead since the v0.3.0 registration filter) and the `compactNodePayload`/`compactLayoutPayload`/`wantsFullPayload` duplicates in `mcp/server.ts` (live copies are in `ops/nodes.ts`). |