pmx-canvas 0.3.3 → 0.4.0

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/index.tsx

@@ -1,3 +1,5 @@
+// Must run before any module that mints per-mount nonces at import/render time.
+import './uuid-polyfill';
 import { render } from 'preact';
 import { App } from './App';
 

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,10 +249,23 @@ 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>`;
 }
 
+/**
+ * Base styles injected into every ext-app document (Finding Q, 0.3.4 report):
+ * apps aspect-fit their drawn surface to the frame width, and on narrow/tall
+ * tiles the leftover region shows the app document's own body background —
+ * pure black for the hosted Excalidraw bundle, in every engine. Making the
+ * app document transparent lets the host iframe's theme background
+ * (var(--c-panel)) show through the letterbox instead. Background only — app
+ * content, its drawn scene, and its own foreground styling are untouched.
+ */
+export function buildExtAppSurfaceBaseStyles(): string {
+  return '<style data-pmx-canvas-ext-app-base>html, body { background: transparent !important; }</style>';
+}
+
 export function injectExtAppAxBridgeScript(html: string, axBridgeScript: string): string {
   if (!axBridgeScript) return html;
   const headMatch = /<head\b[^>]*>/i.exec(html);
@@ -355,7 +372,7 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   const bootBeaconScript =
     typeof html === 'string' && html.length > 0 ? buildExtAppBootBeaconScript(axToken, nodeId) : '';
   const iframeDocument = useIframeDocument(
-    injectExtAppAxBridgeScript(html ?? '', bootBeaconScript + axBridgeScript),
+    injectExtAppAxBridgeScript(html ?? '', buildExtAppSurfaceBaseStyles() + bootBeaconScript + axBridgeScript),
     iframeSandbox,
   );
 
@@ -363,7 +380,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 +388,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 +418,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;
       },
@@ -717,7 +701,9 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
 
       bridge.onsandboxready = async () => {
         await bridge.sendSandboxResourceReady({
-          html,
+          // Same Finding Q base styles for the sandbox-proxy path: the inner
+          // resource document is the one that letterboxes on narrow tiles.
+          html: injectExtAppAxBridgeScript(html, buildExtAppSurfaceBaseStyles()),
           sandbox: DEFAULT_EXT_APP_SANDBOX,
           ...(resourceMeta?.csp ? { csp: resourceMeta.csp } : {}),
           ...(resourceMeta?.permissions ? { permissions: resourceMeta.permissions } : {}),
@@ -1077,9 +1063,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 +1092,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/client/state/node-factory.ts

@@ -0,0 +1,72 @@
+import type { CanvasNodeState } from '../types';
+
+// ── Client node-creation defaults (plan-009 H5, client half) ──
+// Single source of truth for the frame (position/size/zIndex/flags) a NEW
+// client-created node gets when its creating event carries no explicit
+// geometry. Extracted from sse-bridge, which kept one `makeNode` helper plus
+// three inline node literals (ext-app open, prompt, response) duplicating
+// these defaults.
+//
+// Divergences found during extraction — documented, NOT silently unified:
+// - `canvas-store.ts` holds no node-creation defaults today. Human-created
+//   nodes go through `createNodeFromClient` (intent-bridge → POST
+//   /api/canvas/node) and get the SERVER's `defaultNodeSize`
+//   (src/server/operations/ops/nodes.ts), which differs from this table for
+//   most types (e.g. its fallback is 360x200). The server half of H5
+//   (`syncEventToCanvasState`, `ensureDefaultDockedNodes`) is deliberately
+//   deferred — do not "fix" that mismatch from this file.
+// - The server seeds `status-main`/`context-main` docked AND collapsed
+//   (`ensureDefaultDockedNodes` in src/server/server.ts); the SSE bridge
+//   creates the same ids expanded, with `context-main` undocked. Client
+//   behavior is preserved as-is.
+// - sse-bridge's prompt literal hardcoded `height: 400` beside a table entry
+//   of the same value; both now read the table (no rendering change).
+
+export const DEFAULT_POSITIONS: Record<CanvasNodeState['type'], { x: number; y: number; w: number; h: number }> &
+  Record<'prompt' | 'response', { x: number; y: number; w: number; h: number }> = {
+  status: { x: 40, y: 80, w: 300, h: 120 },
+  markdown: { x: 380, y: 80, w: 720, h: 600 },
+  context: { x: 1130, y: 80, w: 320, h: 400 },
+  'mcp-app': { x: 380, y: 720, w: 960, h: 600 },
+  webpage: { x: 380, y: 80, w: 520, h: 420 },
+  'json-render': { x: 380, y: 720, w: 840, h: 620 },
+  graph: { x: 380, y: 720, w: 760, h: 520 },
+  ledger: { x: 1130, y: 520, w: 320, h: 280 },
+  trace: { x: 40, y: 900, w: 200, h: 56 },
+  file: { x: 380, y: 80, w: 720, h: 600 },
+  image: { x: 380, y: 80, w: 720, h: 520 },
+  html: { x: 380, y: 80, w: 720, h: 640 },
+  group: { x: 220, y: 60, w: 840, h: 560 },
+  prompt: { x: 380, y: 1260, w: 520, h: 400 },
+  response: { x: 380, y: 1480, w: 720, h: 400 },
+};
+
+/**
+ * Build a canvas node with the shared client defaults. `position`/`size`
+ * default to the type's DEFAULT_POSITIONS entry; callers that compute
+ * placement (auto-placement, event-supplied geometry) pass explicit values.
+ * Status nodes sit at zIndex 0 (background chrome), everything else at 1.
+ */
+export function makeNodeState(
+  id: string,
+  type: CanvasNodeState['type'],
+  data: Record<string, unknown>,
+  options: {
+    position?: { x: number; y: number };
+    size?: { width: number; height: number };
+    dockPosition?: 'left' | 'right' | null;
+  } = {},
+): CanvasNodeState {
+  const defaults = DEFAULT_POSITIONS[type];
+  return {
+    id,
+    type,
+    position: options.position ?? { x: defaults.x, y: defaults.y },
+    size: options.size ?? { width: defaults.w, height: defaults.h },
+    zIndex: type === 'status' ? 0 : 1,
+    collapsed: false,
+    pinned: false,
+    dockPosition: options.dockPosition ?? null,
+    data,
+  };
+}