pmx-canvas 0.3.3 → 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';
 
@@ -205,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,
@@ -218,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); }
@@ -245,7 +249,7 @@ export function buildExtAppAxBridgeScript(axToken: string, nodeId: string): stri
  */
 export function buildExtAppBootBeaconScript(frameToken: string, nodeId: string): string {
   return `<script data-pmx-canvas-boot-beacon>
-window.parent.postMessage({ source: 'pmx-canvas-ext-app-alive', token: ${JSON.stringify(frameToken)}, nodeId: ${JSON.stringify(nodeId)} }, '*');
+window.parent.postMessage({ source: '${EXT_APP_BOOT_BEACON_SOURCE}', token: ${JSON.stringify(frameToken)}, nodeId: ${JSON.stringify(nodeId)} }, '*');
 </script>`;
 }
 
@@ -363,7 +367,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
     function onBootBeacon(event: MessageEvent) {
       if (event.source !== iframeRef.current?.contentWindow) return;
       const data = event.data as { source?: string; token?: string; nodeId?: string } | null;
-      if (!data || data.source !== 'pmx-canvas-ext-app-alive' || data.token !== axToken || data.nodeId !== nodeId)
+      if (!data || data.source !== EXT_APP_BOOT_BEACON_SOURCE || data.token !== axToken || data.nodeId !== nodeId)
         return;
       appScriptsRanRef.current = true;
     }
@@ -371,46 +375,8 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
     return () => window.removeEventListener('message', onBootBeacon);
   }, [axToken, nodeId]);
 
-  useEffect(() => {
-    if (!axEnabled) 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 !== 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,
-          },
-          '*',
-        );
-      });
-    }
-    window.addEventListener('message', onAxMessage);
-    return () => window.removeEventListener('message', onAxMessage);
-  }, [axEnabled, 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
@@ -439,6 +405,11 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
         // 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;
       },
@@ -1077,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
@@ -1109,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 : {} },

package/src/mcp/server.ts

@@ -175,53 +175,6 @@ function encodeBase64(bytes: Uint8Array): string {
   return Buffer.from(bytes).toString('base64');
 }
 
-function wantsFullPayload(input: { full?: boolean; verbose?: boolean; includeData?: boolean } = {}): boolean {
-  return input.full === true || input.verbose === true || input.includeData === true;
-}
-
-function compactNodePayload(node: Awaited<ReturnType<CanvasAccess['getNode']>>): Record<string, unknown> | null {
-  if (!node) return null;
-  const serialized = serializeCanvasNode(node);
-  return {
-    id: serialized.id,
-    type: serialized.type,
-    kind: serialized.kind,
-    title: serialized.title,
-    content: serialized.content,
-    position: serialized.position,
-    size: serialized.size,
-    pinned: serialized.pinned,
-    collapsed: serialized.collapsed,
-    dockPosition: serialized.dockPosition,
-    provenance: serialized.provenance,
-  };
-}
-
-function compactLayoutPayload(
-  layout: Awaited<ReturnType<CanvasAccess['getLayout']>>,
-  pinnedIds: string[],
-): Record<string, unknown> {
-  return {
-    summary: buildSummaryFromLayout(layout, pinnedIds),
-    viewport: layout.viewport,
-    annotations: (layout.annotations ?? []).map((annotation) =>
-      summarizeCanvasAnnotationForContext(annotation, layout.nodes),
-    ),
-    nodes: layout.nodes
-      .map((node) => compactNodePayload(node))
-      .filter((node): node is Record<string, unknown> => node !== null),
-    edges: layout.edges.map((edge) => ({
-      id: edge.id,
-      from: edge.from,
-      to: edge.to,
-      type: edge.type,
-      ...(edge.label ? { label: edge.label } : {}),
-      ...(edge.style ? { style: edge.style } : {}),
-      ...(edge.animated !== undefined ? { animated: edge.animated } : {}),
-    })),
-  };
-}
-
 function agentSafeFullLayoutPayload(layout: Awaited<ReturnType<CanvasAccess['getLayout']>>): Record<string, unknown> {
   return {
     ...serializeCanvasLayoutForAgent(layout),

package/src/server/canvas-operations.ts

@@ -856,6 +856,14 @@ export function scheduleCodeGraphRecompute(onComplete?: () => void): void {
   }, 300);
 }
 
+/** Clear a pending recompute so the timer cannot outlive its server (start/stop cycles, tests). */
+export function cancelCodeGraphRecompute(): void {
+  if (codeGraphTimer) {
+    clearTimeout(codeGraphTimer);
+    codeGraphTimer = null;
+  }
+}
+
 /**
  * Resolve an html-node `html` field that may be a path to a local .html/.htm file.
  *

package/src/server/diagram-presets.ts

@@ -41,6 +41,20 @@ export const EXCALIDRAW_MCP_TRANSPORT: ExternalMcpTransportConfig = {
   url: EXCALIDRAW_MCP_URL,
 };
 
+/**
+ * The diagram preset targets the hosted Excalidraw MCP server. Tests set
+ * PMX_CANVAS_EXCALIDRAW_MCP_COMMAND (a stdio command line, e.g.
+ * "bun run tests/fixtures/mcp-app-fixture.ts") so the unit suite never does a
+ * real network round-trip — the hosted dependency made diagram tests time out
+ * under parallel load (plan-009 M8).
+ */
+export function resolveExcalidrawTransport(): ExternalMcpTransportConfig {
+  const override = process.env.PMX_CANVAS_EXCALIDRAW_MCP_COMMAND?.trim();
+  if (!override) return EXCALIDRAW_MCP_TRANSPORT;
+  const [command = override, ...args] = override.split(/\s+/);
+  return { type: 'stdio', command, args };
+}
+
 export interface DiagramPresetOpenInput {
   elements: unknown;
   nodeId?: string;
@@ -379,7 +393,7 @@ export function ensureExcalidrawCheckpointId(
 export function buildExcalidrawOpenMcpAppInput(input: DiagramPresetOpenInput): ExcalidrawOpenMcpAppInput {
   const elements = normalizeExcalidrawElementsForToolInput(input.elements);
   const out: ExcalidrawOpenMcpAppInput = {
-    transport: EXCALIDRAW_MCP_TRANSPORT,
+    transport: resolveExcalidrawTransport(),
     toolName: EXCALIDRAW_CREATE_VIEW_TOOL,
     serverName: EXCALIDRAW_SERVER_NAME,
     toolArguments: { elements },

package/src/server/html-surface.ts

@@ -15,6 +15,11 @@
  * postMessage required.
  */
 
+import {
+  AX_SURFACE_ACK_SOURCE,
+  AX_SURFACE_EMIT_SOURCE,
+  HTML_SURFACE_PUSH_SOURCE,
+} from '../shared/ax-surface-protocol.js';
 import { contentHeightReporterTag } from '../shared/content-height-reporter.js';
 
 export type SurfaceTheme = 'dark' | 'light' | 'high-contrast';
@@ -54,7 +59,7 @@ function buildThemeBridge(themeToken: string): string {
 const PMX_CANVAS_THEME_TOKEN = ${token};
 window.addEventListener('message', (event) => {
   const message = event.data;
-  if (!message || message.source !== 'pmx-canvas-html-node' || message.type !== 'theme-update' || message.token !== PMX_CANVAS_THEME_TOKEN) return;
+  if (!message || message.source !== '${HTML_SURFACE_PUSH_SOURCE}' || message.type !== 'theme-update' || message.token !== PMX_CANVAS_THEME_TOKEN) return;
   if (typeof message.theme !== 'string') return;
   document.documentElement.setAttribute('data-pmx-canvas-theme', message.theme);
   document.documentElement.setAttribute('data-theme', message.theme);
@@ -74,12 +79,12 @@ function buildPresentationEscapeBridge(exitToken: string): string {
 const PMX_CANVAS_PRESENTATION_EXIT_TOKEN = ${token};
 document.addEventListener('keydown', (event) => {
   if (event.key === 'Escape') {
-    window.parent.postMessage({ source: 'pmx-canvas-html-node', type: 'presentation-exit', token: PMX_CANVAS_PRESENTATION_EXIT_TOKEN }, '*');
+    window.parent.postMessage({ source: '${HTML_SURFACE_PUSH_SOURCE}', type: 'presentation-exit', token: PMX_CANVAS_PRESENTATION_EXIT_TOKEN }, '*');
   }
 }, true);
 window.addEventListener('message', (event) => {
   const message = event.data;
-  if (!message || message.source !== 'pmx-canvas-html-node' || message.type !== 'presentation-key' || message.token !== PMX_CANVAS_PRESENTATION_EXIT_TOKEN) return;
+  if (!message || message.source !== '${HTML_SURFACE_PUSH_SOURCE}' || message.type !== 'presentation-key' || message.token !== PMX_CANVAS_PRESENTATION_EXIT_TOKEN) return;
   if (typeof message.key !== 'string') return;
   if (typeof window.PMX_CANVAS_PRESENTATION_HANDLE_KEY === 'function') {
     window.PMX_CANVAS_PRESENTATION_HANDLE_KEY(message.key);
@@ -131,7 +136,7 @@ export function buildAxBridge(axToken: string, nodeId: string): string {
     seq += 1;
     const correlationId = PMX_AX_NODE_ID + '-' + seq + '-' + (Date.now ? Date.now() : 0);
     window.parent.postMessage({
-      source: 'pmx-canvas-ax',
+      source: '${AX_SURFACE_EMIT_SOURCE}',
       token: PMX_AX_TOKEN,
       nodeId: PMX_AX_NODE_ID,
       correlationId: correlationId,
@@ -152,7 +157,7 @@ export function buildAxBridge(axToken: string, nodeId: string): string {
   };
   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); }
@@ -182,7 +187,7 @@ export function buildAxStateBridge(axToken: string, snapshotJson: string): strin
   window.PMX_AX.state = ${snapshotJson};
   window.addEventListener('message', function (event) {
     const m = event.data;
-    if (!m || m.source !== 'pmx-canvas-html-node' || m.type !== 'ax-update' || m.token !== PMX_AX_STATE_TOKEN) return;
+    if (!m || m.source !== '${HTML_SURFACE_PUSH_SOURCE}' || m.type !== 'ax-update' || m.token !== PMX_AX_STATE_TOKEN) return;
     window.PMX_AX.state = m.state;
     try { window.dispatchEvent(new CustomEvent('pmx-ax-update', { detail: m.state })); } catch (e) {}
   });