pmx-canvas 0.3.4 → 0.4.1

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.1",
+  "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
 
@@ -222,16 +223,41 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
   time), with a watchdog retry for iframes that never boot and a re-arm when a panel that loaded
   hidden becomes visible. Treat the auto-recovery as best-effort, NOT guaranteed — the 0.3.2
   Copilot-host report shows tiles can still come up black in real WKWebView panels (compositing
-  success is not observable from page JS, so retries are bounded). Keep the cautionary behavior:
+  success is not observable from page JS, so retries are bounded). Since 0.4.1 the canvas also
+  fires a post-boot **repaint nudge** under WebKit (a 1px layout bounce that forces the
+  compositor to re-rasterize the frame — the cheap half of the proven enlarge-close unstick;
+  shows as `repaint-nudge` in the recovery trail). Keep the cautionary behavior anyway:
   recovery is deterministic via **expand-then-close** of the black tile (forces a fresh mount in
   the fullscreen overlay, which always paints), or open the workbench in a normal browser
   (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.
+- Ext-app frame documents live in server memory. Through 0.4.0, killing/restarting the daemon
+  while a panel stays open leaves ext-app tiles on dead frame URLs (`Frame document not found`,
+  0.4.0 report Finding S) until a full workbench reload. Since 0.4.1 the browser revalidates its
+  frame documents on every reconnect and re-mints them against the new process automatically —
+  if a post-restart tile still looks blank on an older install, reload the workbench page.
+- 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.
+- Nested-iframe embeds (e.g. the Amp orb portal renders the canvas page inside an ampcode.com
+  iframe) can block child iframes from loading ANY `src` URL, breaking every iframe-backed node
+  with a gray placeholder. The canvas probes this at boot and auto-falls back to fetching
+  same-origin surfaces and rendering them inline via `srcdoc` (HTML, graph, json-render, frame
+  documents). External app URLs cannot be inlined (cross-origin) and may stay blocked in such
+  hosts. Force a mode with `/workbench?iframe-mode=srcdoc` (or `iframe-mode=src`) 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
-  stale until reload — use a system browser for separate full-page viewing.
+  reflow on a live window resize in a normal browser. Some single-tab host browsers historically
+  didn't deliver live-resize events (current Codex builds do — the 0.4.0 retest saw a standalone
+  graph reflow on a native viewport resize), so if a resized standalone chart looks stale,
+  reload it or use a system browser for separate full-page viewing.
 - Some hosts cannot automate inside sandboxed workbench iframes. Verify those interactions in a
   system browser or through server-side AX state.
 - `pmx-canvas screenshot` requires an active WebView. Start it with

package/skills/pmx-canvas/evals/evals.json

@@ -172,7 +172,7 @@
       "id": 7,
       "name": "snapshot-before-changes",
       "prompt": "I want to reorganize the canvas to explore a different approach, but I don't want to lose what's there now. Can you save the current state, clear it, and set up a fresh workspace for the new approach? If it doesn't work out I want to go back.",
-      "expected_output": "Takes a named snapshot of current state, then clears the canvas. Mentions that canvas_restore can bring back the old state. Does NOT just clear without snapshotting.",
+      "expected_output": "Takes a named snapshot of current state, then clears the canvas. Mentions that canvas_snapshot { action: \"restore\" } can bring back the old state. Does NOT just clear without snapshotting.",
       "assertions": [
         {
           "name": "takes-snapshot",
@@ -186,7 +186,7 @@
         },
         {
           "name": "mentions-restore",
-          "description": "Tells the user how to restore (canvas_restore) if they want to go back",
+          "description": "Tells the user how to restore (canvas_snapshot action restore) if they want to go back",
           "type": "output_check"
         }
       ]

package/skills/pmx-canvas/references/full-reference.md

@@ -73,7 +73,7 @@ section below.
 3. **Read before write** — `canvas_query { action: "search", query }` (or `pmx-canvas search`)
    to find existing nodes; avoid duplicates. Use `canvas_query { action: "layout" }` only when
    you need the full board.
-4. **Snapshot before destructive work** — `canvas_snapshot { name }` before clear/major
+4. **Snapshot before destructive work** — `canvas_snapshot { action: "save", name }` before clear/major
    reorg; restore if needed.
 5. **Signal then mutate (default behavior)** — signal with `canvas_intent { action: "signal", … }`
    to telegraph the move before nearly every mutation, then create with the right composite: `canvas_node` (markdown/status/file/webpage/html
@@ -315,6 +315,7 @@ pmx-canvas spatial
 - `group create|add|remove` — manage groups
 - `clear --yes` — destructive clear with explicit confirmation
 - `validate spec` — validate json-render specs and graph payloads without creating nodes
+- `node update` — returns a compact `{ ok, id, nodeId, position, size, updatedFields }` envelope by default; pass `--full` for the complete node payload. Full ext-app/mcp-app payloads embed the bundled app HTML and tool results (hundreds of KB — a no-op ext-app resize once returned ~940 KB), so in agent turns keep the default envelope and read content via `node get --summary`
 - `web-artifact build` — build bundled React/Tailwind HTML artifacts; use `--deps` for extra packages and `--include-logs` only when raw logs are useful. The build pipeline runs bash scripts (POSIX-only) — it is not supported on native Windows; already-built artifacts render everywhere
 - `external-app add --kind excalidraw` — create the hosted Excalidraw preset; response includes `id` and `nodeId` aliases for the same canvas node
 - `serve status|stop` — inspect and stop daemonized servers started with `serve --daemon`
@@ -429,7 +430,7 @@ single-purpose tools behind an `action` (and, for `canvas_ax_gate`, a `kind`) di
 > registered — use the composites instead. The authoritative legacy→composite mapping table lives
 > in [`docs/mcp.md`](../../../docs/mcp.md) — this skill does not re-enumerate the removed names.
 
-### The 15 composites
+### The 16 composites
 
 | Composite | `action` values | What it does |
 |-----------|-----------------|--------------|
@@ -438,6 +439,7 @@ single-purpose tools behind an `action` (and, for `canvas_ax_gate`, a `kind`) di
 | `canvas_edge` | `add` · `remove` | Connect / disconnect nodes |
 | `canvas_group` | `create` · `add` · `ungroup` | Manage spatial group containers |
 | `canvas_history` | `undo` · `redo` | Time travel through the mutation ring buffer |
+| `canvas_snapshot` | `save` · `list` · `restore` · `delete` · `gc` · `diff` | Named snapshots: save/list/restore/delete, garbage-collect old ones, diff current canvas vs a snapshot (`diff` takes `snapshot`, not `id`) |
 | `canvas_view` | `arrange` · `focus` · `fit` · `clear` · `remove-annotation` | Auto-arrange, pan-to-node, fit viewport, clear the board, delete a human-drawn annotation by id |
 | `canvas_query` | `search` · `layout` · `validate` | Find nodes by keyword, read full layout, or **`validate`** the board for node collisions / group-containment / dangling edges |
 | `canvas_app` | `open-mcp-app` · `diagram` · `build-artifact` | Hosted MCP apps, the Excalidraw diagram preset, and bundled web artifacts (folds `canvas_open_mcp_app` / `canvas_add_diagram` / `canvas_build_web_artifact`) |
@@ -505,10 +507,9 @@ investigation board" intent, then run the batch with that linked `intentId` (use
 
 These stay separate by design (trust-boundary, firehose, execution-intent, or not-yet-consolidated
 surfaces): `canvas_batch`, `canvas_pin_nodes`, `canvas_screenshot`, `canvas_ax_interaction`,
-`canvas_ingest_activity`, `canvas_invoke_command`, and the snapshot tools (`canvas_snapshot`,
-`canvas_list_snapshots`, `canvas_restore`, `canvas_delete_snapshot`, `canvas_gc_snapshots`,
-`canvas_diff` — deprecated pending a `canvas_snapshot` composite in v0.4; the name collides with
-the current save-snapshot tool, so the composite cannot land additively).
+`canvas_ingest_activity`, `canvas_invoke_command`. Snapshots moved into the `canvas_snapshot`
+composite in v0.4.0 (actions `save | list | restore | delete | gc | diff`); the 6 legacy snapshot
+standalones were removed after their deprecated 0.3.x window.
 
 `canvas_batch` supports exactly these ops: `node.add`, `node.update`, `node.remove`, `graph.add`,
 `edge.add`, `edge.remove`, `group.create`, `group.add`, `group.remove`, `pin.set`/`pin.add`/
@@ -650,7 +651,7 @@ ID extraction for mixed tool responses:
 
 **`canvas_pin_nodes`** (standalone) — Set, add, or remove pinned context nodes. Use `{ nodeIds: [...] }` — the field is `nodeIds`, not `ids`.
 
-**`canvas_diff`** (standalone) — Compare current canvas state with a saved snapshot. Requires `{ snapshot: "<snapshot-id-or-name>" }`; there is no implicit previous-snapshot default.
+**`canvas_snapshot { action: "diff" }`** — Compare current canvas state with a saved snapshot. Requires `{ snapshot: "<snapshot-id-or-name>" }`; there is no implicit previous-snapshot default.
 
 **`canvas_render { action: "describe-schema" }`** — Inspect the running server's create schemas and
 canonical examples. Use before generating structured payloads when you need the authoritative current
@@ -766,13 +767,14 @@ ranked matches with content snippets. Use instead of parsing the full layout to
 ### History & Snapshots
 
 - **`canvas_history { action: "undo" }`** / **`canvas_history { action: "redo" }`** — step the mutation ring buffer.
-- **`canvas_snapshot`** (standalone) — save a named snapshot; `name` required. Returns `{ ok, id, snapshot }` (flat `id` aliases `snapshot.id`).
-- **`canvas_restore`** (standalone) — restore from a snapshot `id`.
-- **`canvas_diff`** (standalone) — compare current canvas against a saved snapshot (added/removed/modified nodes & edges).
+- **`canvas_snapshot { action: "save", name }`** — save a named snapshot. Returns `{ ok, id, snapshot }` (flat `id` aliases `snapshot.id`).
+- **`canvas_snapshot { action: "list" }`** / **`{ action: "gc", keep }`** / **`{ action: "delete", id }`** — manage saved snapshots.
+- **`canvas_snapshot { action: "restore", id }`** — restore from a snapshot.
+- **`canvas_snapshot { action: "diff", snapshot }`** — compare current canvas against a saved snapshot (added/removed/modified nodes & edges). Note the field is `snapshot` (id or name), not `id`.
 
 ### Canvas Management
 
-**`canvas_view { action: "clear" }`** — Remove all nodes and edges. **Always `canvas_snapshot` first** —
+**`canvas_view { action: "clear" }`** — Remove all nodes and edges. **Always `canvas_snapshot { action: "save" }` first** —
 this is irreversible without a prior snapshot.
 
 ### Browser Automation (WebView)
@@ -1405,19 +1407,19 @@ Monitor ongoing processes:
 
 Show two states side by side for the human to compare:
 
-1. Take a snapshot before changes: `canvas_snapshot` with name "before-X"
+1. Take a snapshot before changes: `canvas_snapshot { action: "save" }` with name "before-X"
 2. Make changes to the canvas
-3. Use `canvas_diff` to show what changed
+3. Use `canvas_snapshot { action: "diff", snapshot }` to show what changed
 4. Or: create two groups ("Before" and "After") with corresponding nodes
 
 ### Save and Start Fresh
 
 When the human wants to explore a different approach without losing current work:
 
-1. **First**, save the current state: `canvas_snapshot` with a descriptive name
+1. **First**, save the current state: `canvas_snapshot { action: "save" }` with a descriptive name
 2. **Then** clear: `canvas_view { action: "clear" }` (never clear without snapshotting first)
 3. Set up the new workspace with initial nodes
-4. Tell the human the snapshot name and that `canvas_restore` can bring everything back
+4. Tell the human the snapshot name and that `canvas_snapshot { action: "restore" }` can bring everything back
 
 ## Best Practices
 

package/skills/pmx-canvas-testing/SKILL.md

@@ -71,6 +71,9 @@ Prefer extending the existing suites before inventing a one-off script.
 - Avoid brittle selectors. Prefer stable text, roles, titles, or deliberate component hooks
 - If a change spans server and client, add at least one server-side assertion and one browser or
   API-level proof
+- MCP harnesses using the official SDK must wind down BOTH halves: call `client.close()` AND
+  `transport.close()` on the `StdioClientTransport`. Closing only the client leaves the spawned
+  stdio server process alive after the test exits (0.4.0 cycle finding)
 
 ## Layout And Embedded Content Checks
 

package/src/cli/commands/history.ts

@@ -193,7 +193,7 @@ cmd('snapshot delete', 'Delete a saved snapshot', ['pmx-canvas snapshot delete <
 });
 
 async function runSnapshotDiff(args: string[]): Promise<void> {
-  const { positional, flags } = parseFlags(args);
+  const { positional } = parseFlags(args);
   const snapshot = positional[0];
   if (!snapshot) die('Missing snapshot ID or name', 'pmx-canvas snapshot diff <snapshot-id-or-name>');
   const result = await invokeOperation('snapshot.diff', { id: snapshot });

package/src/cli/commands/nodes.ts

@@ -830,6 +830,7 @@ cmd(
     'pmx-canvas node update <node-id> --dock-position right',
     'pmx-canvas node update <node-id> --dock-position none   # undock back to the canvas',
     'pmx-canvas node update <node-id> --lock-arrange',
+    'pmx-canvas node update <node-id> --width 840 --full   # full node payload instead of the compact envelope',
   ],
   async (args) => {
     const { positional, flags } = parseFlags(args);
@@ -932,7 +933,36 @@ cmd(
     }
 
     const result = await invokeOperation('node.update', { id, ...body });
-    output(result);
+    if (flags.full || flags.verbose) {
+      output(result);
+      return;
+    }
+    // Finding R (0.3.4 report): the raw update result echoes the FULL node —
+    // ~940 KB for an ext-app (bundled html + tool result) — which can consume a
+    // large share of an agent turn for a simple resize. Default to a compact
+    // envelope; --full restores the complete response.
+    const updatedNode = isRecord(result) && isRecord(result.node) ? result.node : undefined;
+    // Raw geometry flags also land in the body alongside their structured
+    // position/size forms (the graph-patch builder copies them through); report
+    // only the canonical field once.
+    const structuredDupes: Record<string, string> = {
+      width: 'size',
+      height: 'size',
+      nodeHeight: 'size',
+      x: 'position',
+      y: 'position',
+    };
+    const updatedFields = Object.keys(body)
+      .filter((key) => !(structuredDupes[key] && body[structuredDupes[key]] !== undefined))
+      .sort();
+    output({
+      ok: isRecord(result) && result.ok !== undefined ? result.ok : true,
+      id,
+      nodeId: id,
+      ...(updatedNode && isRecord(updatedNode.position) ? { position: updatedNode.position } : {}),
+      ...(updatedNode && isRecord(updatedNode.size) ? { size: updatedNode.size } : {}),
+      updatedFields,
+    });
   },
 );
 

package/src/cli/index.ts

@@ -163,7 +163,10 @@ function runMcpServerProcess(): Promise<void> {
 const serveSubcommand = firstArg === 'serve' ? (args[1] ?? '') : '';
 
 if (firstArg === 'serve' && (serveSubcommand === 'status' || serveSubcommand === 'stop')) {
-  const port = parseInt(readOption('port') ?? process.env.PMX_WEB_CANVAS_PORT ?? '4313');
+  const port = parseInt(
+    readOption('port') ?? process.env.PMX_WEB_CANVAS_PORT ?? process.env.PMX_CANVAS_PORT ?? '4313',
+    10,
+  );
   const daemonLogFile = resolve(readOption('log-file') ?? `.pmx-canvas/daemon-${port}.log`);
   const daemonPidFile = resolve(readOption('pid-file') ?? `.pmx-canvas/daemon-${port}.pid`);
   const daemonWaitMs = readNumberOption('wait-ms') ?? 10_000;
@@ -208,7 +211,10 @@ if (AGENT_COMMANDS.has(routedCommand) && routedCommand !== 'serve') {
   await runMcpServerProcess();
 } else {
   // "serve" is also accessible via flags (backward compat)
-  const port = parseInt(readOption('port') ?? process.env.PMX_WEB_CANVAS_PORT ?? '4313');
+  const port = parseInt(
+    readOption('port') ?? process.env.PMX_WEB_CANVAS_PORT ?? process.env.PMX_CANVAS_PORT ?? '4313',
+    10,
+  );
   const demo = hasFlag('demo');
   const noOpen = hasFlag('no-open');
   const daemon = hasFlag('daemon');

package/src/cli/shared.ts

@@ -147,6 +147,7 @@ function parseFlags(args: string[]): { positional: string[]; flags: Record<strin
     'json',
     'compact',
     'verbose',
+    'full',
     'include-logs',
     'no-pan',
     'schema',

package/src/client/index.tsx

@@ -1,5 +1,12 @@
+// Must run before any module that mints per-mount nonces at import/render time.
+import './uuid-polyfill';
 import { render } from 'preact';
 import { App } from './App';
+import { resolveIframeMode } from './state/iframe-mode';
+
+// Start the embed probe before first paint so iframe-backed nodes know whether
+// src-URL iframes work in this context (Amp orb portals block them).
+void resolveIframeMode();
 
 const root = document.getElementById('app');
 if (root) {

package/src/client/nodes/ExtAppFrame.tsx

@@ -253,6 +253,19 @@ window.parent.postMessage({ source: '${EXT_APP_BOOT_BEACON_SOURCE}', token: ${JS
 </script>`;
 }
 
+/**
+ * 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 function buildExtAppSurfaceBaseStyles(): string {
+  return '<style data-pmx-canvas-ext-app-base>html, body { background: transparent !important; }</style>';
+}
+
 export function injectExtAppAxBridgeScript(html: string, axBridgeScript: string): string {
   if (!axBridgeScript) return html;
   const headMatch = /<head\b[^>]*>/i.exec(html);
@@ -359,7 +372,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   const bootBeaconScript =
     typeof html === 'string' && html.length > 0 ? buildExtAppBootBeaconScript(axToken, nodeId) : '';
   const iframeDocument = useIframeDocument(
-    injectExtAppAxBridgeScript(html ?? '', bootBeaconScript + axBridgeScript),
+    injectExtAppAxBridgeScript(html ?? '', buildExtAppSurfaceBaseStyles() + bootBeaconScript + axBridgeScript),
     iframeSandbox,
   );
 
@@ -566,6 +579,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
     if (!iframe) return;
     let disposed = false;
     let fallbackTimer: ReturnType<typeof setTimeout> | null = null;
+    let repaintNudgeTimer: ReturnType<typeof setTimeout> | null = null;
     let hostContextResizeObserver: ResizeObserver | null = null;
     let hostContextRaf: number | null = null;
     let readyNudgeRaf: number | null = null;
@@ -641,6 +655,32 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
         });
       };
 
+      // Finding N best-effort: WKWebView can keep compositing a stale (black)
+      // texture for the doubly-nested app iframe even after a genuine settled
+      // boot — the user-proven unstick is enlarge+close, i.e. a layout-size
+      // change. Mimic the cheap half of that after the scene draw: bounce the
+      // iframe's height by 1px for two frames so WebKit must re-rasterize the
+      // layer. No reload, no app state loss; a healthy frame repaints
+      // identically. Scheduled past the remount queue's settle pause so it
+      // lands after the app has actually drawn.
+      const scheduleWebkitRepaintNudge = () => {
+        if (!isWebKitOnlyHost(navigator.userAgent)) return;
+        if (repaintNudgeTimer) clearTimeout(repaintNudgeTimer);
+        repaintNudgeTimer = setTimeout(() => {
+          repaintNudgeTimer = null;
+          const frame = iframeRef.current;
+          if (disposed || !frame) return;
+          const previous = frame.style.height;
+          frame.style.height = 'calc(100% - 1px)';
+          requestAnimationFrame(() => {
+            requestAnimationFrame(() => {
+              frame.style.height = previous;
+              extAppRecoveryLog(nodeId, 'repaint-nudge');
+            });
+          });
+        }, WEBKIT_REMOUNT_SETTLE_MS + 200);
+      };
+
       const bridge = new AppBridge(
         null,
         { name: 'PMX Canvas', version: '1.0.0' },
@@ -688,7 +728,9 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
 
       bridge.onsandboxready = async () => {
         await bridge.sendSandboxResourceReady({
-          html,
+          // Same Finding Q base styles for the sandbox-proxy path: the inner
+          // resource document is the one that letterboxes on narrow tiles.
+          html: injectExtAppAxBridgeScript(html, buildExtAppSurfaceBaseStyles()),
           sandbox: DEFAULT_EXT_APP_SANDBOX,
           ...(resourceMeta?.csp ? { csp: resourceMeta.csp } : {}),
           ...(resourceMeta?.permissions ? { permissions: resourceMeta.permissions } : {}),
@@ -790,6 +832,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
             extAppRecoveryLog(nodeId, 'settled');
             for (const waiter of bootWaitersRef.current.splice(0)) waiter();
             nudgeHostContextAfterLayout();
+            scheduleWebkitRepaintNudge();
           })
           .catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
@@ -816,6 +859,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
             setStatus(bootstrapToolResult ? 'done' : 'ready');
             setError(null);
             nudgeHostContextAfterLayout();
+            scheduleWebkitRepaintNudge();
           })
           .catch((err) => {
             const msg = err instanceof Error ? err.message : String(err);
@@ -863,6 +907,10 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
     return () => {
       disposed = true;
       clearFallbackTimer();
+      if (repaintNudgeTimer) {
+        clearTimeout(repaintNudgeTimer);
+        repaintNudgeTimer = null;
+      }
       hostContextResizeObserver?.disconnect();
       hostContextResizeObserver = null;
       if (hostContextRaf !== null) {

package/src/client/nodes/HtmlNode.tsx

@@ -5,6 +5,7 @@ import type { CanvasNodeState } from '../types';
 import { nodeSurfaceUrl, surfaceContentHash } from './surface-url';
 import { useAxSurfaceBridge } from './use-ax-surface-bridge';
 import { useIframeContentHeight } from './use-iframe-content-height';
+import { useSurfaceFrame } from './use-surface-frame';
 
 export function shouldShowPresentationControls(node: CanvasNodeState): boolean {
   return node.type === 'html' && node.data.presentation === true;
@@ -60,6 +61,9 @@ export function HtmlNode({
     [html, presentation, presentationExitToken, themeToken, v, node.id, axToken, frameToken],
   );
 
+  // src vs fetch()+srcdoc, decided by the boot-wide embed probe (Amp portals).
+  const surfaceFrame = useSurfaceFrame(surfaceSrc);
+
   // Grow the node to fit the surface's reported content height (grow-only, gated).
   // Never in the expanded overlay — there the surface fills the large overlay frame.
   useIframeContentHeight(node, iframeRef, expanded ? '' : frameToken);
@@ -149,7 +153,7 @@ export function HtmlNode({
       class={presentation ? 'html-node-frame html-node-frame-presentation' : 'html-node-frame'}
       title={typeof node.data.title === 'string' ? node.data.title : 'HTML node'}
       sandbox="allow-scripts"
-      src={surfaceSrc}
+      {...surfaceFrame}
       tabIndex={autoFocus ? 0 : undefined}
       onLoad={handleFrameLoad}
       style={{

package/src/client/nodes/McpAppNode.tsx

@@ -6,6 +6,7 @@ import { shouldContentFitIframeNode } from '../canvas/auto-fit';
 import { ExtAppFrame } from './ExtAppFrame';
 import { useAxSurfaceBridge } from './use-ax-surface-bridge';
 import { useIframeContentHeight } from './use-iframe-content-height';
+import { useSurfaceFrame } from './use-surface-frame';
 
 function withViewerParams(
   url: string,
@@ -117,6 +118,9 @@ function McpAppViewer({ node, expanded }: { node: CanvasNodeState; expanded: boo
     frameToken || undefined,
     contentFit,
   );
+  // src vs fetch()+srcdoc, decided by the boot-wide embed probe (Amp portals).
+  // External viewer URLs always stay src — the hook passes them through.
+  const surfaceFrame = useSurfaceFrame(url);
   const sourceServer = (node.data.sourceServer as string) || '';
   const hostMode = (node.data.hostMode as string) || 'hosted';
   const fallbackReason = node.data.fallbackReason as string | undefined;
@@ -174,7 +178,7 @@ function McpAppViewer({ node, expanded }: { node: CanvasNodeState; expanded: boo
           app/host RPC and broader capabilities. */}
       <iframe
         ref={iframeRef}
-        src={url}
+        {...surfaceFrame}
         class="mcp-app-frame"
         sandbox="allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox"
         allow="clipboard-read; clipboard-write"