pmx-canvas 0.4.0 → 0.4.1

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/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/http-api.md

@@ -345,6 +345,28 @@ 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/plans/plan-009-tech-debt-backlog.md

@@ -66,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`). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.4.0",
+  "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",

package/skills/pmx-canvas/SKILL.md

@@ -223,12 +223,20 @@ 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
@@ -238,10 +246,18 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
 - 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-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/client/index.tsx

@@ -2,6 +2,11 @@
 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

@@ -579,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;
@@ -654,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' },
@@ -805,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);
@@ -831,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);
@@ -878,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"

package/src/client/nodes/iframe-document-url.ts

@@ -1,4 +1,7 @@
-import { useEffect, useMemo, useState } from 'preact/hooks';
+import { useEffect, useMemo, useRef, useState } from 'preact/hooks';
+import { workbenchConnectionEpoch } from '../state/canvas-store';
+import { iframeMode } from '../state/iframe-mode';
+import { surfaceContentHash } from './surface-url';
 
 interface FrameDocumentCreateResponse {
   ok: boolean;
@@ -37,13 +40,20 @@ export async function createIframeDocumentUrl(html: string, sandbox: string): Pr
 export function useIframeDocument(
   html: string,
   sandbox: string,
-): { attributes: { src?: string }; ready: boolean; key: string } {
+): { attributes: { src?: string; srcdoc?: string }; ready: boolean; key: string } {
+  // Boot-wide embed probe (state/iframe-mode.ts): srcdoc mode means src-URL
+  // iframes are blocked here (nested-iframe hosts like Amp orb portals), so the
+  // frame-documents round-trip would produce a URL the browser refuses to load.
+  const mode = iframeMode.value;
   const [src, setSrc] = useState<string | null>(null);
+  const [remintNonce, setRemintNonce] = useState(0);
+  const mintEpochRef = useRef(0);
 
   useEffect(() => {
     setSrc(null);
-    if (!html) return;
+    if (!html || mode !== 'src') return;
     let cancelled = false;
+    mintEpochRef.current = workbenchConnectionEpoch.value;
     void createIframeDocumentUrl(html, sandbox)
       .then((url) => {
         if (!cancelled) setSrc(url);
@@ -54,14 +64,57 @@ export function useIframeDocument(
     return () => {
       cancelled = true;
     };
-  }, [html, sandbox]);
+  }, [html, sandbox, mode, remintNonce]);
 
-  return useMemo(
-    () => ({
+  // Finding S: frame documents live in server memory, so a daemon restart turns
+  // this mount's URL into a 404 while the panel keeps showing the dead frame.
+  // Every reconnect frame (SSE reconnect or poll snapshot reset) revalidates the
+  // minted URL and re-mints a fresh document when the server no longer has it —
+  // no full workbench reload required.
+  const epoch = workbenchConnectionEpoch.value;
+  useEffect(() => {
+    if (mode !== 'src' || epoch === mintEpochRef.current) return;
+    if (!src) {
+      // A previous mint failed outright (e.g. the daemon flapped down between
+      // the HEAD 404 and the re-mint POST). A fresh connection epoch means the
+      // server is reachable again — retry the mint instead of stranding the
+      // tile until a manual reload.
+      setRemintNonce((n) => n + 1);
+      return;
+    }
+    let cancelled = false;
+    void fetch(src, { method: 'HEAD' })
+      .then((res) => {
+        if (cancelled) return;
+        if (res.ok) {
+          mintEpochRef.current = epoch;
+          return;
+        }
+        setRemintNonce((n) => n + 1);
+      })
+      .catch(() => {
+        // Transient network failure — the next reconnect epoch retries.
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [epoch, src, mode]);
+
+  return useMemo(() => {
+    if (mode === 'srcdoc' && html) {
+      // The document already lives client-side, so serve it inline. Consumers
+      // always render the iframe `sandbox` attribute, which supplies the
+      // sandboxing the frame-document CSP header would have.
+      return {
+        attributes: { srcdoc: html },
+        ready: true,
+        key: `srcdoc-${surfaceContentHash(html)}`,
+      };
+    }
+    return {
       attributes: src ? { src } : {},
       ready: Boolean(src),
       key: src ?? '',
-    }),
-    [src],
-  );
+    };
+  }, [src, mode, html]);
 }

package/src/client/nodes/use-surface-frame.ts

@@ -0,0 +1,53 @@
+import { useEffect, useState } from 'preact/hooks';
+import { iframeMode } from '../state/iframe-mode';
+
+function isSameOriginUrl(url: string): boolean {
+  try {
+    return new URL(url, window.location.origin).origin === window.location.origin;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 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 function useSurfaceFrame(url: string): { src?: string; srcdoc?: string } {
+  const mode = iframeMode.value;
+  const [doc, setDoc] = useState<{ url: string; html: string } | null>(null);
+  const sameOrigin = Boolean(url) && isSameOriginUrl(url);
+  const wantsSrcdoc = mode === 'srcdoc' && sameOrigin;
+
+  useEffect(() => {
+    if (!wantsSrcdoc) return;
+    let cancelled = false;
+    void fetch(url, { credentials: 'same-origin' })
+      .then((res) => (res.ok ? res.text() : Promise.reject(new Error(`HTTP ${res.status}`))))
+      .then((html) => {
+        if (!cancelled) setDoc({ url, html });
+      })
+      .catch((error) => {
+        console.error('[surface-frame] srcdoc fetch failed, falling back to src:', url, error);
+        // Empty html marks the src fallback below.
+        if (!cancelled) setDoc({ url, html: '' });
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [wantsSrcdoc, url]);
+
+  if (!url) return {};
+  if (!wantsSrcdoc) {
+    return mode === null && sameOrigin ? {} : { src: url };
+  }
+  // Keep the previous document visible while a newer URL is being fetched —
+  // same UX as src mode, where the old document stays until the new one loads.
+  if (doc) return doc.html ? { srcdoc: doc.html } : { src: doc.url };
+  return {};
+}

package/src/client/state/canvas-store.ts

@@ -22,6 +22,11 @@ export const edges = signal<Map<string, CanvasEdge>>(new Map());
 export const annotations = signal<Map<string, CanvasAnnotation>>(new Map());
 export const activeNodeId = signal<string | null>(null);
 export const connectionStatus = signal<ConnectionStatus>('connecting');
+// Bumped on every processed `connected` frame (SSE reconnects and poll snapshot
+// resets alike). Consumers holding server-minted URLs revalidate on change —
+// a server restart invalidates in-memory resources like frame documents
+// (Finding S) while the browser keeps the stale URLs alive.
+export const workbenchConnectionEpoch = signal<number>(0);
 export const sessionId = signal<string>('');
 export const traceEnabled = signal<boolean>(false);
 export const canvasTheme = signal<string>('dark');

package/src/client/state/iframe-mode.ts

@@ -0,0 +1,103 @@
+/**
+ * Nested-iframe embedding detection (Amp orb portals).
+ *
+ * When the canvas page itself runs inside an iframe (ampcode.com embeds the
+ * portal URL on *.onamp.dev), Chrome refuses to load child iframes from `src`
+ * URLs — even same-origin relative ones — leaving every iframe-backed node a
+ * gray "refused to connect" placeholder. Inline documents (`srcdoc`) still
+ * render. This module probes the real behavior once per boot: a hidden 1px
+ * iframe navigates to the tiny /api/canvas/iframe-probe document; if `load`
+ * fires the host is normal (`src` mode), otherwise same-origin surfaces fall
+ * back to fetch() + `srcdoc` (see nodes/use-surface-frame.ts and
+ * nodes/iframe-document-url.ts).
+ *
+ * `src` stays the default everywhere it works: URL-loaded surfaces keep real
+ * document URLs, and the frame-document transport exists precisely because
+ * attribute-sized srcdoc documents were the worse default (v0.1.24). srcdoc is
+ * the blocked-embed fallback, not the new normal.
+ *
+ * Force a mode with `?iframe-mode=srcdoc` (or `=src`) for debugging.
+ */
+import { signal } from '@preact/signals';
+
+export type IframeMode = 'src' | 'srcdoc';
+
+export const IFRAME_PROBE_PATH = '/api/canvas/iframe-probe';
+const PROBE_TIMEOUT_MS = 3000;
+
+/** Boot-wide iframe transport mode; null until the probe (or override) resolves. */
+export const iframeMode = signal<IframeMode | null>(null);
+
+export function forcedIframeMode(): IframeMode | null {
+  const value = new URLSearchParams(window.location.search).get('iframe-mode');
+  return value === 'srcdoc' || value === 'src' ? value : 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 function probeSrcIframes(timeoutMs = PROBE_TIMEOUT_MS): Promise<boolean> {
+  return new Promise((resolve) => {
+    const test = document.createElement('iframe');
+    test.setAttribute('data-pmx-iframe-probe', '');
+    test.style.cssText = 'position:fixed;width:1px;height:1px;left:-9999px;border:none';
+    test.setAttribute('sandbox', 'allow-scripts');
+    const done = (ok: boolean) => {
+      window.clearTimeout(timer);
+      test.remove();
+      resolve(ok);
+    };
+    const timer = window.setTimeout(() => done(false), timeoutMs);
+    test.addEventListener('load', () => done(true));
+    test.addEventListener('error', () => done(false));
+    test.src = IFRAME_PROBE_PATH;
+    (document.body ?? document.documentElement).appendChild(test);
+  });
+}
+
+let pending: Promise<IframeMode> | null = null;
+
+function isEmbeddedDocument(): boolean {
+  try {
+    return window.self !== window.top;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * 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 function resolveIframeMode(opts: { embedded?: boolean } = {}): Promise<IframeMode> {
+  if (iframeMode.value) return Promise.resolve(iframeMode.value);
+  if (pending) return pending;
+  const forced = forcedIframeMode();
+  if (forced) {
+    iframeMode.value = forced;
+    return Promise.resolve(forced);
+  }
+  if (!(opts.embedded ?? isEmbeddedDocument())) {
+    iframeMode.value = 'src';
+    return Promise.resolve('src');
+  }
+  pending = probeSrcIframes().then((srcWorks) => {
+    const mode: IframeMode = srcWorks ? 'src' : 'srcdoc';
+    iframeMode.value = mode;
+    return mode;
+  });
+  return pending;
+}
+
+/** Test hook: clear the memoized probe so each test starts unresolved. */
+export function resetIframeModeForTests(): void {
+  iframeMode.value = null;
+  pending = null;
+}

package/src/client/state/sse-bridge.ts

@@ -23,6 +23,7 @@ import {
   sessionId,
   traceEnabled,
   updateNodeData,
+  workbenchConnectionEpoch,
 } from './canvas-store';
 import { fetchAxSurfaceState } from './intent-bridge';
 import { DEFAULT_POSITIONS, makeNodeState } from './node-factory';
@@ -393,6 +394,8 @@ function parseCanvasAnnotation(raw: Record<string, unknown>): CanvasAnnotation |
 function handleConnected(data: Record<string, unknown>): void {
   sessionId.value = (data.sessionId as string) || '';
   connectionStatus.value = 'connected';
+  // Reconnect marker for holders of server-minted URLs (Finding S).
+  workbenchConnectionEpoch.value += 1;
   if (typeof data.theme === 'string') {
     applyCanvasTheme(data.theme);
   }