pmx-canvas 0.3.2 → 0.3.4

package/src/client/canvas/ExpandedNodeOverlay.tsx

@@ -1,3 +1,4 @@
+import { HTML_SURFACE_PUSH_SOURCE } from '../../shared/ax-surface-protocol.js';
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'preact/hooks';
 import { ContextNode } from '../nodes/ContextNode';
 import { FileNode } from '../nodes/FileNode';
@@ -86,7 +87,7 @@ function isPresentationExitMessage(value: unknown, token: string): boolean {
   return (
     value !== null &&
     typeof value === 'object' &&
-    (value as { source?: unknown }).source === 'pmx-canvas-html-node' &&
+    (value as { source?: unknown }).source === HTML_SURFACE_PUSH_SOURCE &&
     (value as { type?: unknown }).type === 'presentation-exit' &&
     (value as { token?: unknown }).token === token
   );
@@ -134,7 +135,7 @@ export function ExpandedNodeOverlay() {
       );
       frame?.contentWindow?.postMessage(
         {
-          source: 'pmx-canvas-html-node',
+          source: HTML_SURFACE_PUSH_SOURCE,
           token: presentationExitToken,
           ...message,
         },

package/src/client/nodes/ExtAppFrame.tsx

@@ -2,10 +2,13 @@ import type { CallToolResult, ListToolsResult, RequestId, Tool } from '@modelcon
 import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { AppBridge, PostMessageTransport, buildAllowAttribute } from '@modelcontextprotocol/ext-apps/app-bridge';
 import { useEffect, useMemo, useRef, useState } from 'preact/hooks';
+import {
+  AX_SURFACE_ACK_SOURCE,
+  AX_SURFACE_EMIT_SOURCE,
+  EXT_APP_BOOT_BEACON_SOURCE,
+} from '../../shared/ax-surface-protocol.js';
 import { extAppToolResultsMatch } from '../../shared/ext-app-tool-result.js';
 import { DEFAULT_EXT_APP_SANDBOX } from '../../shared/surface.js';
-import { submitAxInteractionFromClient } from '../state/intent-bridge';
-import { showToast } from '../state/attention-bridge';
 import {
   canvasTheme,
   collapseExpandedNode,
@@ -18,6 +21,7 @@ import {
 import type { CanvasNodeState } from '../types';
 import { AUTO_FIT_TITLEBAR_HEIGHT } from '../canvas/auto-fit';
 import { useIframeDocument } from './iframe-document-url';
+import { useAxSurfaceBridge } from './use-ax-surface-bridge';
 
 type McpUiTheme = 'light' | 'dark';
 
@@ -92,6 +96,33 @@ export function extAppRecoveryLog(nodeId: string, event: string): void {
   const host = window as unknown as { __PMX_EXTAPP_LOG?: Array<{ t: number; nodeId: string; event: string }> };
   host.__PMX_EXTAPP_LOG ??= [];
   if (host.__PMX_EXTAPP_LOG.length < 500) host.__PMX_EXTAPP_LOG.push({ t: Date.now(), nodeId, event });
+  queueExtAppRecoveryReport({ t: Date.now(), nodeId, event });
+}
+
+// Mirror the recovery trail to the daemon (batched, fire-and-forget) so a host
+// panel without devtools access — the Copilot WKWebView, exactly where the
+// black tiles happen — still yields an actionable trace: agents read it back
+// via GET /api/canvas/debug/ext-app-recovery (0.3.2 report Finding N).
+let extAppReportQueue: Array<{ t: number; nodeId: string; event: string; visibility?: string }> = [];
+let extAppReportTimer: ReturnType<typeof setTimeout> | null = null;
+function queueExtAppRecoveryReport(entry: { t: number; nodeId: string; event: string }): void {
+  extAppReportQueue.push({
+    ...entry,
+    ...(typeof document !== 'undefined' ? { visibility: document.visibilityState } : {}),
+  });
+  if (extAppReportTimer) return;
+  extAppReportTimer = setTimeout(() => {
+    extAppReportTimer = null;
+    const entries = extAppReportQueue.splice(0);
+    if (entries.length === 0) return;
+    void fetch('/api/canvas/debug/ext-app-recovery', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ entries }),
+    }).catch(() => {
+      // Diagnostics only — never let reporting failures affect recovery.
+    });
+  }, 1500);
 }
 
 let webkitRemountChain: Promise<void> = Promise.resolve();
@@ -178,7 +209,7 @@ export function buildExtAppAxBridgeScript(axToken: string, nodeId: string): stri
       }, 10000);
       pending.set(correlationId, function (result) { clearTimeout(timer); resolve(result); });
       window.parent.postMessage({
-        source: 'pmx-canvas-ax',
+        source: '${AX_SURFACE_EMIT_SOURCE}',
         token: PMX_AX_TOKEN,
         nodeId: PMX_AX_NODE_ID,
         correlationId: correlationId,
@@ -191,7 +222,7 @@ export function buildExtAppAxBridgeScript(axToken: string, nodeId: string): stri
   };
   window.addEventListener('message', function (event) {
     const m = event.data;
-    if (!m || m.source !== 'pmx-canvas-ax-ack' || m.token !== PMX_AX_TOKEN) return;
+    if (!m || m.source !== '${AX_SURFACE_ACK_SOURCE}' || m.token !== PMX_AX_TOKEN) return;
     const result = m.result || { ok: false };
     const resolver = m.correlationId ? pending.get(m.correlationId) : undefined;
     if (resolver) { pending.delete(m.correlationId); resolver(result); }
@@ -204,6 +235,24 @@ export function buildExtAppAxBridgeScript(axToken: string, nodeId: string): stri
 </script>`;
 }
 
+/**
+ * Boot beacon injected into EVERY ext-app document (not gated on AX): posts one
+ * parent message the moment the iframe's scripts execute. This is the liveness
+ * signal the WebKit never-booted watchdog keys on — it distinguishes an app
+ * that is alive but boots via the 1200ms bootstrap fallback (e.g. a non-SDK
+ * widget that never sends ui/notifications/initialized) from a dead window
+ * whose scripts never ran. Without it, the watchdog treated every
+ * fallback-booted app as never-booted and remounted it up to the attempt cap —
+ * a reboot/flicker loop for exactly the apps the fallback exists to support
+ * (0.3.2 pre-release review). The token scopes the message to this component;
+ * the host also checks event.source against the live iframe.
+ */
+export function buildExtAppBootBeaconScript(frameToken: string, nodeId: string): string {
+  return `<script data-pmx-canvas-boot-beacon>
+window.parent.postMessage({ source: '${EXT_APP_BOOT_BEACON_SOURCE}', token: ${JSON.stringify(frameToken)}, nodeId: ${JSON.stringify(nodeId)} }, '*');
+</script>`;
+}
+
 export function injectExtAppAxBridgeScript(html: string, axBridgeScript: string): string {
   if (!axBridgeScript) return html;
   const headMatch = /<head\b[^>]*>/i.exec(html);
@@ -262,8 +311,15 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   // handshake (bridge.oninitialized) — NOT by the 1200ms bootstrap fallback,
   // which flips status via notifications that resolve even into a dead iframe.
   const appInitializedRef = useRef(false);
+  // Liveness signal from the injected boot beacon: the CURRENT frame's scripts
+  // executed. Proves "alive" for apps that boot via the fallback path without
+  // ever sending initialized; a dead window never beacons.
+  const appScriptsRanRef = useRef(false);
   const bootWaitersRef = useRef<Array<() => void>>([]);
   const remountQueuedRef = useRef(false);
+  // Recovery ran while the document was hidden (compositing suppressed) — re-arm
+  // one fresh remount round when the panel becomes visible (Finding N).
+  const bootedWhileHiddenRef = useRef(false);
   const unmountedRef = useRef(false);
   const [status, setStatus] = useState<ExtAppFrameStatus>('loading');
   const [error, setError] = useState<string | null>(null);
@@ -298,48 +354,29 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   const axEnabled = axCaps?.enabled === true && typeof html === 'string' && html.length > 0;
   const axToken = useMemo(() => `ax-${crypto.randomUUID()}`, []);
   const axBridgeScript = axEnabled ? buildExtAppAxBridgeScript(axToken, nodeId) : '';
-  const iframeDocument = useIframeDocument(injectExtAppAxBridgeScript(html ?? '', axBridgeScript), iframeSandbox);
+  // The boot beacon precedes the AX bridge so it runs first at parse time; it
+  // shares the per-component token (used purely to authenticate the message).
+  const bootBeaconScript =
+    typeof html === 'string' && html.length > 0 ? buildExtAppBootBeaconScript(axToken, nodeId) : '';
+  const iframeDocument = useIframeDocument(
+    injectExtAppAxBridgeScript(html ?? '', bootBeaconScript + axBridgeScript),
+    iframeSandbox,
+  );
 
   useEffect(() => {
-    if (!axEnabled) return;
-    function onAxMessage(event: MessageEvent) {
+    function onBootBeacon(event: MessageEvent) {
       if (event.source !== iframeRef.current?.contentWindow) return;
-      const data = event.data as {
-        source?: string;
-        token?: string;
-        nodeId?: string;
-        correlationId?: string;
-        interaction?: { type?: unknown; payload?: unknown };
-      } | null;
-      if (!data || data.source !== 'pmx-canvas-ax' || data.token !== axToken || data.nodeId !== nodeId) return;
-      const interaction = data.interaction;
-      if (!interaction || typeof interaction.type !== 'string') return;
-      const interactionType = interaction.type;
-      void submitAxInteractionFromClient({
-        type: interactionType,
-        sourceNodeId: nodeId,
-        sourceSurface: 'mcp-app',
-        ...(interaction.payload && typeof interaction.payload === 'object'
-          ? { payload: interaction.payload as Record<string, unknown> }
-          : {}),
-      }).then((res) => {
-        if (res.ok) showToast('context', 'AX interaction', interactionType, [nodeId]);
-        else showToast('remove', 'AX interaction rejected', res.error ?? res.code ?? '', [nodeId]);
-        iframeRef.current?.contentWindow?.postMessage(
-          {
-            source: 'pmx-canvas-ax-ack',
-            token: axToken,
-            ...(data.correlationId ? { correlationId: data.correlationId } : {}),
-            interaction: { type: interactionType },
-            result: res,
-          },
-          '*',
-        );
-      });
+      const data = event.data as { source?: string; token?: string; nodeId?: string } | null;
+      if (!data || data.source !== EXT_APP_BOOT_BEACON_SOURCE || data.token !== axToken || data.nodeId !== nodeId)
+        return;
+      appScriptsRanRef.current = true;
     }
-    window.addEventListener('message', onAxMessage);
-    return () => window.removeEventListener('message', onAxMessage);
-  }, [axEnabled, axToken, nodeId]);
+    window.addEventListener('message', onBootBeacon);
+    return () => window.removeEventListener('message', onBootBeacon);
+  }, [axToken, nodeId]);
+
+  // Ext-app AX emits — the shared sandboxed-surface trust boundary (M2).
+  useAxSurfaceBridge({ enabled: axEnabled, token: axToken, nodeId, sourceSurface: 'mcp-app', iframeRef });
 
   // Enqueue one serialized remount attempt for this node (Finding F recovery).
   // Attempts are capped so a persistently-failing app degrades to the manual
@@ -361,7 +398,18 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
           extAppRecoveryLog(nodeId, 'remount-skipped');
           return false;
         }
+        // Stamp visibility at RUN time, not schedule time: the serialized queue
+        // can hold this slot for many seconds, and what decides whether the
+        // repaint can composite is the document's visibility when the remount
+        // actually executes (the Finding N re-arm keys on this flag). Covers
+        // every scheduling path (post-boot repaint, boot watchdog, re-arm).
+        bootedWhileHiddenRef.current = typeof document !== 'undefined' && document.visibilityState === 'hidden';
         extAppRecoveryLog(nodeId, `remount-run #${webkitRemountAttemptsRef.current}`);
+        // Back to 'loading' so the connecting overlay covers this recovery
+        // remount's boot window too (the fallback boot flipped status to
+        // ready/done even when the previous frame was dead — without this the
+        // overlay only ever covered the INITIAL boot, not recovery).
+        setStatus('loading');
         setRetryKey((k) => k + 1);
         return true;
       },
@@ -401,11 +449,42 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [status, hasReplayToolResult]);
 
-  // Never-booted watchdog (0.3.1): an iframe whose scripts never ran in the burst
+  // Finding N (0.3.2 report): the Copilot panel can load the canvas while the
+  // WKWebView document is HIDDEN (panel backgrounded/occluded). WebKit suppresses
+  // compositing for hidden documents, so the whole serialized recovery above can
+  // run to completion without ever producing a visible paint — and nothing
+  // retried once the panel was shown, which is why tiles stayed black until a
+  // manual expand+close (necessarily performed while visible). When the document
+  // becomes visible again, re-arm ONE fresh serialized remount round for frames
+  // whose recovery ran while hidden.
+  useEffect(() => {
+    if (expanded) return;
+    if (typeof document === 'undefined' || typeof navigator === 'undefined' || typeof window === 'undefined') return;
+    if (!isWebKitOnlyHost(navigator.userAgent)) return;
+    function onVisibilityChange() {
+      if (document.visibilityState !== 'visible') return;
+      if (!bootedWhileHiddenRef.current || unmountedRef.current) return;
+      bootedWhileHiddenRef.current = false;
+      // Fresh visibility = fresh recovery budget: the hidden-run attempts were
+      // spent without a chance of compositing.
+      webkitRemountAttemptsRef.current = 0;
+      extAppRecoveryLog(nodeId, 'visible-again-rearm');
+      scheduleWebkitRemount('visible-after-hidden-boot');
+    }
+    document.addEventListener('visibilitychange', onVisibilityChange);
+    return () => document.removeEventListener('visibilitychange', onVisibilityChange);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [expanded, nodeId]);
+
+  // Never-booted watchdog (0.3.2): an iframe whose scripts never ran in the burst
   // shows no error — the bootstrap fallback flips status via notifications that
-  // resolve into a dead window, so the tile just stays black. If the CURRENT frame
-  // has not completed the genuine initialize handshake within the watchdog window,
-  // retry it through the same serialized queue (bounded by the shared attempt cap).
+  // resolve into a dead window, so the tile just stays black. "Alive" is either
+  // boot signal from the CURRENT frame: the genuine initialize handshake, or the
+  // injected boot beacon (which covers apps that boot via the fallback without
+  // ever sending initialized — remounting those was a flicker loop, and checking
+  // bridgeReadyRef instead would be wrong: the fallback sets it blindly, dead
+  // window or not). Only a frame with NEITHER signal is retried through the
+  // serialized queue (bounded by the shared attempt cap).
   const WEBKIT_BOOT_WATCHDOG_MS = 6000;
   useEffect(() => {
     if (expanded) return;
@@ -413,7 +492,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
     if (!isWebKitOnlyHost(navigator.userAgent)) return;
     if (!iframeDocument.ready) return;
     const timer = window.setTimeout(() => {
-      if (appInitializedRef.current || unmountedRef.current) return;
+      if (appInitializedRef.current || appScriptsRanRef.current || unmountedRef.current) return;
       scheduleWebkitRemount('boot-watchdog');
     }, WEBKIT_BOOT_WATCHDOG_MS);
     return () => window.clearTimeout(timer);
@@ -494,9 +573,11 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
     lastSentToolResultRef.current = undefined;
     toolResultSendingRef.current = null;
     bridgeReadyRef.current = false;
-    // New frame = new boot attempt: the genuine-initialized signal belongs to the
-    // CURRENT iframe. The queue's awaitBoot waits on this frame's handshake.
+    // New frame = new boot attempt: both boot signals belong to the CURRENT
+    // iframe (the beacon listener also pins event.source to the live element).
+    // The queue's awaitBoot waits on this frame's handshake.
     appInitializedRef.current = false;
+    appScriptsRanRef.current = false;
 
     const clearFallbackTimer = (): void => {
       if (!fallbackTimer) return;
@@ -967,9 +1048,6 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
           </button>
         </div>
       )}
-      {status === 'loading' && (
-        <div style={{ padding: '8px', fontSize: '11px', color: 'var(--c-muted)' }}>Connecting to ext-app viewer...</div>
-      )}
       {/* Iframe stack: the widget renders a preview; when not expanded, a
           transparent click-catcher sits on top so the first click always
           expands the node. Without this, widgets like Excalidraw show their
@@ -999,6 +1077,42 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
           }}
           title={`Ext App: ${toolName}`}
         />
+        {/* Connecting overlay: an opaque sibling ABOVE the iframe while this
+            frame boots. During WebKit recovery remounts the iframe's own layer
+            can composite black (Finding N), but sibling DOM always paints — so
+            the multi-second recovery window reads as an intentional loading
+            state instead of a broken black tile. pointer-events pass through
+            so the expand click-catcher keeps working. */}
+        {status === 'loading' && !error && (
+          <div
+            style={{
+              position: 'absolute',
+              inset: 0,
+              display: 'flex',
+              flexDirection: 'column',
+              alignItems: 'center',
+              justifyContent: 'center',
+              gap: '10px',
+              background: 'var(--c-panel)',
+              color: 'var(--c-muted)',
+              fontSize: '12px',
+              pointerEvents: 'none',
+            }}
+          >
+            <div
+              style={{
+                width: '22px',
+                height: '22px',
+                border: '2px solid var(--c-line)',
+                borderTopColor: 'var(--c-muted)',
+                borderRadius: '50%',
+                animation: 'spin 1s linear infinite',
+              }}
+            />
+            <div>Connecting to {toolName}...</div>
+            <style>{'@keyframes spin { to { transform: rotate(360deg); } }'}</style>
+          </div>
+        )}
         {!isExpanded && (
           <button
             type="button"

package/src/client/nodes/HtmlNode.tsx

@@ -1,9 +1,9 @@
 import { useEffect, useMemo, useRef } from 'preact/hooks';
+import { HTML_SURFACE_PUSH_SOURCE } from '../../shared/ax-surface-protocol.js';
 import { axSurfaceState, canvasTheme } from '../state/canvas-store';
-import { submitAxInteractionFromClient } from '../state/intent-bridge';
-import { showToast } from '../state/attention-bridge';
 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';
 
 export function shouldShowPresentationControls(node: CanvasNodeState): boolean {
@@ -64,56 +64,13 @@ export function HtmlNode({
   // Never in the expanded overlay — there the surface fills the large overlay frame.
   useIframeContentHeight(node, iframeRef, expanded ? '' : frameToken);
 
-  // Phase 3 HTML bridge: receive window.PMX_AX.emit(...) messages from the
-  // sandboxed iframe, validate the nonce + node id, and submit the interaction
-  // through the capability-gated endpoint (the server re-validates capabilities).
-  useEffect(() => {
-    function onAxMessage(event: MessageEvent) {
-      // Bind to THIS node's own iframe (matches the ext-app bridge); the nonce +
-      // nodeId are a second gate, not the only one.
-      if (event.source !== iframeRef.current?.contentWindow) return;
-      const data = event.data as {
-        source?: string;
-        token?: string;
-        nodeId?: string;
-        correlationId?: string;
-        interaction?: { type?: unknown; payload?: unknown };
-      } | null;
-      if (!data || data.source !== 'pmx-canvas-ax' || data.token !== axToken || data.nodeId !== node.id) return;
-      const interaction = data.interaction;
-      if (!interaction || typeof interaction.type !== 'string') return;
-      const interactionType = interaction.type;
-      void submitAxInteractionFromClient({
-        type: interactionType,
-        sourceNodeId: node.id,
-        sourceSurface: 'html-node',
-        ...(interaction.payload && typeof interaction.payload === 'object'
-          ? { payload: interaction.payload as Record<string, unknown> }
-          : {}),
-      }).then((res) => {
-        if (res.ok) showToast('context', 'AX interaction', interactionType, [node.id]);
-        else showToast('remove', 'AX interaction rejected', res.error ?? res.code ?? '', [node.id]);
-        // Report #55: ack back to the surface so it can self-confirm (e.g. "queued ✓").
-        iframeRef.current?.contentWindow?.postMessage(
-          {
-            source: 'pmx-canvas-ax-ack',
-            token: axToken,
-            ...(data.correlationId ? { correlationId: data.correlationId } : {}),
-            interaction: { type: interactionType },
-            result: res,
-          },
-          '*',
-        );
-      });
-    }
-    window.addEventListener('message', onAxMessage);
-    return () => window.removeEventListener('message', onAxMessage);
-  }, [axToken, node.id]);
+  // Phase 3 HTML bridge — the shared sandboxed-surface trust boundary (M2).
+  useAxSurfaceBridge({ enabled: true, token: axToken, nodeId: node.id, sourceSurface: 'html-node', iframeRef });
 
   useEffect(() => {
     iframeRef.current?.contentWindow?.postMessage(
       {
-        source: 'pmx-canvas-html-node',
+        source: HTML_SURFACE_PUSH_SOURCE,
         type: 'theme-update',
         token: themeToken,
         theme,
@@ -134,7 +91,7 @@ export function HtmlNode({
     if (!axEnabled || axStateValue == null) return;
     iframeRef.current?.contentWindow?.postMessage(
       {
-        source: 'pmx-canvas-html-node',
+        source: HTML_SURFACE_PUSH_SOURCE,
         type: 'ax-update',
         token: axToken,
         state: axStateValue,
@@ -152,7 +109,7 @@ export function HtmlNode({
   const handleFrameLoad = () => {
     iframeRef.current?.contentWindow?.postMessage(
       {
-        source: 'pmx-canvas-html-node',
+        source: HTML_SURFACE_PUSH_SOURCE,
         type: 'theme-update',
         token: themeToken,
         theme,
@@ -162,7 +119,7 @@ export function HtmlNode({
     if (axEnabled && axSurfaceState.value != null) {
       iframeRef.current?.contentWindow?.postMessage(
         {
-          source: 'pmx-canvas-html-node',
+          source: HTML_SURFACE_PUSH_SOURCE,
           type: 'ax-update',
           token: axToken,
           state: axSurfaceState.value,

package/src/client/nodes/McpAppNode.tsx

@@ -1,10 +1,10 @@
 import { useEffect, useMemo, useRef } from 'preact/hooks';
+import { HTML_SURFACE_PUSH_SOURCE } from '../../shared/ax-surface-protocol.js';
 import type { CanvasNodeState } from '../types';
 import { axSurfaceState, canvasTheme } from '../state/canvas-store';
 import { shouldContentFitIframeNode } from '../canvas/auto-fit';
-import { submitAxInteractionFromClient } from '../state/intent-bridge';
-import { showToast } from '../state/attention-bridge';
 import { ExtAppFrame } from './ExtAppFrame';
+import { useAxSurfaceBridge } from './use-ax-surface-bridge';
 import { useIframeContentHeight } from './use-iframe-content-height';
 
 function withViewerParams(
@@ -80,50 +80,15 @@ function McpAppViewer({ node, expanded }: { node: CanvasNodeState; expanded: boo
   const frameToken = useMemo(() => (contentFit ? `frame-${crypto.randomUUID()}` : ''), [contentFit]);
   useIframeContentHeight(node, iframeRef, frameToken);
 
-  // Receive AX emits forwarded by the json-render viewer; validate (bound to this
-  // node's iframe + nonce + node id) and submit through the capability-gated
-  // endpoint, which re-validates server-side.
-  useEffect(() => {
-    if (!isAxViewer || !axToken) return;
-    function onAxMessage(event: MessageEvent) {
-      if (event.source !== iframeRef.current?.contentWindow) return;
-      const data = event.data as {
-        source?: string;
-        token?: string;
-        nodeId?: string;
-        correlationId?: string;
-        interaction?: { type?: unknown; payload?: unknown };
-      } | null;
-      if (!data || data.source !== 'pmx-canvas-ax' || data.token !== axToken || data.nodeId !== node.id) return;
-      const interaction = data.interaction;
-      if (!interaction || typeof interaction.type !== 'string') return;
-      const interactionType = interaction.type;
-      void submitAxInteractionFromClient({
-        type: interactionType,
-        sourceNodeId: node.id,
-        sourceSurface: axSurface,
-        ...(interaction.payload && typeof interaction.payload === 'object'
-          ? { payload: interaction.payload as Record<string, unknown> }
-          : {}),
-      }).then((res) => {
-        if (res.ok) showToast('context', 'AX interaction', interactionType, [node.id]);
-        else showToast('remove', 'AX interaction rejected', res.error ?? res.code ?? '', [node.id]);
-        // Report #55: ack back to the viewer so the surface can self-confirm.
-        iframeRef.current?.contentWindow?.postMessage(
-          {
-            source: 'pmx-canvas-ax-ack',
-            token: axToken,
-            ...(data.correlationId ? { correlationId: data.correlationId } : {}),
-            interaction: { type: interactionType },
-            result: res,
-          },
-          '*',
-        );
-      });
-    }
-    window.addEventListener('message', onAxMessage);
-    return () => window.removeEventListener('message', onAxMessage);
-  }, [isAxViewer, axToken, node.id]);
+  // AX emits forwarded by the json-render viewer — the shared sandboxed-surface
+  // trust boundary (M2).
+  useAxSurfaceBridge({
+    enabled: isAxViewer && Boolean(axToken),
+    token: axToken,
+    nodeId: node.id,
+    sourceSurface: axSurface,
+    iframeRef,
+  });
 
   // Read-side: push live AX state into the json-render viewer so a spec bound to
   // /ax reflects the work queue. Validated by the viewer against axToken.
@@ -132,7 +97,7 @@ function McpAppViewer({ node, expanded }: { node: CanvasNodeState; expanded: boo
     if (!isAxViewer || !axToken || axStateValue == null) return;
     iframeRef.current?.contentWindow?.postMessage(
       {
-        source: 'pmx-canvas-html-node',
+        source: HTML_SURFACE_PUSH_SOURCE,
         type: 'ax-update',
         token: axToken,
         state: axStateValue,

package/src/client/nodes/use-ax-surface-bridge.ts

@@ -0,0 +1,71 @@
+import type { RefObject } from 'preact';
+import { useEffect } from 'preact/hooks';
+import { AX_SURFACE_ACK_SOURCE, AX_SURFACE_EMIT_SOURCE } from '../../shared/ax-surface-protocol.js';
+import { showToast } from '../state/attention-bridge';
+import { submitAxInteractionFromClient } from '../state/intent-bridge';
+
+/** Sandboxed surfaces that emit through this bridge (clamped to their own node server-side). */
+export type AxSurfaceBridgeSurface = 'json-render' | 'html-node' | 'mcp-app';
+
+/**
+ * The sandboxed-surface AX trust boundary, single-sited (plan-009 M2; the
+ * listener was copy-pasted across HtmlNode, McpAppNode, and ExtAppFrame — a
+ * prior near-miss lived exactly in that duplication). Receives a
+ * `window.PMX_AX.emit(...)` message from THIS node's iframe, validates the
+ * event source against the live contentWindow plus the per-mount nonce token
+ * and node id, submits the interaction through the capability-gated endpoint
+ * (the server re-validates capabilities and clamps sandboxed surfaces to their
+ * own node), and acks the result back so the surface can self-confirm (#55).
+ */
+export function useAxSurfaceBridge(options: {
+  enabled: boolean;
+  token: string;
+  nodeId: string;
+  sourceSurface: AxSurfaceBridgeSurface;
+  iframeRef: RefObject<HTMLIFrameElement>;
+}): void {
+  const { enabled, token, nodeId, sourceSurface, iframeRef } = options;
+  useEffect(() => {
+    if (!enabled || !token) return;
+    function onAxMessage(event: MessageEvent) {
+      // Bind to THIS node's own iframe; the nonce + nodeId are a second gate,
+      // not the only one.
+      if (event.source !== iframeRef.current?.contentWindow) return;
+      const data = event.data as {
+        source?: string;
+        token?: string;
+        nodeId?: string;
+        correlationId?: string;
+        interaction?: { type?: unknown; payload?: unknown };
+      } | null;
+      if (!data || data.source !== AX_SURFACE_EMIT_SOURCE || data.token !== token || data.nodeId !== nodeId) return;
+      const interaction = data.interaction;
+      if (!interaction || typeof interaction.type !== 'string') return;
+      const interactionType = interaction.type;
+      void submitAxInteractionFromClient({
+        type: interactionType,
+        sourceNodeId: nodeId,
+        sourceSurface,
+        ...(interaction.payload && typeof interaction.payload === 'object'
+          ? { payload: interaction.payload as Record<string, unknown> }
+          : {}),
+      }).then((res) => {
+        if (res.ok) showToast('context', 'AX interaction', interactionType, [nodeId]);
+        else showToast('remove', 'AX interaction rejected', res.error ?? res.code ?? '', [nodeId]);
+        iframeRef.current?.contentWindow?.postMessage(
+          {
+            source: AX_SURFACE_ACK_SOURCE,
+            token,
+            ...(data.correlationId ? { correlationId: data.correlationId } : {}),
+            interaction: { type: interactionType },
+            result: res,
+          },
+          '*',
+        );
+      });
+    }
+    window.addEventListener('message', onAxMessage);
+    return () => window.removeEventListener('message', onAxMessage);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled, token, nodeId, sourceSurface]);
+}

package/src/json-render/renderer/index.tsx

@@ -8,6 +8,7 @@
  */
 
 import type { Spec } from '@json-render/core';
+import { AX_SURFACE_EMIT_SOURCE, HTML_SURFACE_PUSH_SOURCE } from '../../shared/ax-surface-protocol.js';
 import { useEffect } from 'react';
 import { createRoot } from 'react-dom/client';
 import { defineRegistry, JSONUIProvider, Renderer, useStateBinding } from '@json-render/react';
@@ -101,7 +102,7 @@ function AxStateSync() {
     if (!token) return undefined;
     function onMessage(event: MessageEvent) {
       const m = event.data as { source?: string; type?: string; token?: string; state?: unknown } | null;
-      if (!m || m.source !== 'pmx-canvas-html-node' || m.type !== 'ax-update' || m.token !== token) return;
+      if (!m || m.source !== HTML_SURFACE_PUSH_SOURCE || m.type !== 'ax-update' || m.token !== token) return;
       window.__PMX_CANVAS_AX_STATE__ = m.state;
       setAx(m.state);
     }
@@ -141,7 +142,7 @@ function buildAxHandlers(): Record<string, (params: Record<string, unknown>) =>
     handlers[type] = (params: Record<string, unknown>) => {
       window.parent.postMessage(
         {
-          source: 'pmx-canvas-ax',
+          source: AX_SURFACE_EMIT_SOURCE,
           token,
           nodeId,
           interaction: { type, payload: params && typeof params === 'object' ? params : {} },