pmx-canvas 0.1.30 → 0.1.32

package/src/server/ax-context.ts

@@ -1,7 +1,55 @@
 import { buildAgentContextPreamble, serializeNodeForAgentContext } from './agent-context.js';
-import { buildAxContext, type PmxAxContext, type PmxAxPinnedContext } from './ax-state.js';
+import {
+  buildAxContext,
+  type PmxAxContext,
+  type PmxAxPinnedContext,
+  type PmxAxWorkItem,
+  type PmxAxApprovalGate,
+  type PmxAxReviewAnnotation,
+  type PmxAxElicitation,
+  type PmxAxModeRequest,
+  type PmxAxPolicy,
+} from './ax-state.js';
 import { canvasState, type CanvasNodeState } from './canvas-state.js';
 
+/**
+ * Compact, surface-safe view of the canvas-bound AX state, injected into (and
+ * pushed to) AX-enabled surfaces so authored boards can RENDER the work queue /
+ * focus, not just emit interactions. Deliberately excludes the timeline, pinned
+ * preamble, and serialized node bodies to keep the payload small.
+ */
+export interface PmxAxSurfaceSnapshot {
+  focus: string[];
+  workItems: PmxAxWorkItem[];
+  approvalGates: PmxAxApprovalGate[];
+  // Free-text human fields (`body`, `author`) are redacted — a surface gets review
+  // status/severity/anchor for a review board, but not raw human comment text.
+  reviewAnnotations: Array<Omit<PmxAxReviewAnnotation, 'body' | 'author'>>;
+  elicitations: PmxAxElicitation[];
+  modeRequests: PmxAxModeRequest[];
+  policy: PmxAxPolicy;
+}
+
+/**
+ * NOTE: this is whole-canvas AX state (every work item, etc.), exposed to ANY
+ * AX-enabled surface — reads are board-wide while emits are node-scoped. Acceptable
+ * under the single-workspace local-trust model, but author surfaces accordingly
+ * (don't embed untrusted third-party scripts in an AX-enabled surface). Sensitive
+ * human review text is redacted below.
+ */
+export function buildCanvasAxSurfaceSnapshot(): PmxAxSurfaceSnapshot {
+  const ax = canvasState.getAxState();
+  return {
+    focus: ax.focus.nodeIds,
+    workItems: ax.workItems,
+    approvalGates: ax.approvalGates,
+    reviewAnnotations: ax.reviewAnnotations.map(({ body: _body, author: _author, ...rest }) => rest),
+    elicitations: ax.elicitations,
+    modeRequests: ax.modeRequests,
+    policy: ax.policy,
+  };
+}
+
 function serializeNodes(nodes: CanvasNodeState[]) {
   return nodes.map((node) => serializeNodeForAgentContext(node, {
     defaultTextLength: 700,

package/src/server/ax-interaction.ts

@@ -500,6 +500,9 @@ export function applyAxInteraction(
       const p = payloadParsed.data as { body: string; kind?: PmxAxReviewKind; severity?: PmxAxReviewSeverity; anchorType?: PmxAxReviewAnchorType; nodeId?: string; file?: string; author?: string };
       // Sandboxed surfaces may only review their own node; trusted surfaces may
       // anchor to a file/region or another node.
+      // A node-interaction review carries a sourceNodeId, so it defaults to a node
+      // anchor on that source (see nodeId resolution below). Body-only/unanchored
+      // is the adapter/HTTP/MCP path (addReviewAnnotation's context-aware default).
       const anchorType: PmxAxReviewAnchorType = scoped ? 'node' : (p.anchorType ?? 'node');
       const reviewAnnotation = manager.addReviewAnnotation(
         {

package/src/server/ax-state.ts

@@ -636,7 +636,9 @@ export function createAxReviewAnnotation(
   source: PmxAxSource | null,
 ): PmxAxReviewAnnotation {
   const now = nowIso();
-  const anchorType = input.anchorType ?? 'node';
+  // Mirror addReviewAnnotation's context-aware default so a body-only annotation
+  // (no anchorType, no nodeId) becomes an unanchored note instead of a node anchor.
+  const anchorType = input.anchorType ?? (typeof input.nodeId === 'string' && input.nodeId ? 'node' : 'file');
   return {
     id: axId('rev'),
     kind: input.kind ?? 'comment',

package/src/server/canvas-state.ts

@@ -442,18 +442,14 @@ class CanvasStateManager {
   }
 
   private normalizeNode(node: CanvasNodeState): CanvasNodeState {
-    const normalized: CanvasNodeState = {
+    // Context nodes default to a right-docked, collapsed pill (see DockedNode.tsx),
+    // but that default is applied at CREATE time only — it must not be re-forced on
+    // every write, or the node could never be undocked. Undocking (dockPosition →
+    // null) is a deliberate user action and is respected here.
+    return {
       ...node,
       data: normalizeCanvasNodeData(node.type, node.data),
     };
-    // Context nodes are always docked to the right side as a pill/panel widget
-    // (see DockedNode.tsx). They start collapsed so the user sees the slim
-    // pill first; expanding reveals the full context overview panel.
-    if (normalized.type === 'context' && normalized.dockPosition !== 'right') {
-      normalized.dockPosition = 'right';
-      normalized.collapsed = true;
-    }
-    return normalized;
   }
 
   private nodeForRead(node: CanvasNodeState): CanvasNodeState {
@@ -930,6 +926,16 @@ class CanvasStateManager {
     return false;
   }
 
+  /**
+   * Whether this workspace's canvas DB already holds saved state. Used to gate
+   * brand-new-workspace seeding (e.g. the default docked status/context widgets)
+   * so we never add nodes to a canvas that already has content. Reflects the
+   * pre-run persisted flag until the next save.
+   */
+  hasPersistedState(): boolean {
+    return this._db ? isDbPopulated(this._db) : false;
+  }
+
   /** Debounced save — coalesces rapid mutations into a single write. */
   private scheduleSave(): void {
     if (!this._db) return;
@@ -1343,7 +1349,15 @@ class CanvasStateManager {
   }
 
   addNode(node: CanvasNodeState): void {
-    const cloned = structuredClone(this.normalizeNode(node));
+    // Context nodes default to a right-docked, collapsed pill when created without
+    // an explicit dock position. CREATE-time default only — once placed, updates
+    // (including undock → dockPosition null) are respected (see normalizeNode).
+    // Skip during suppressed replay (undo/redo re-add) so a deliberately-undocked
+    // context node is restored verbatim instead of being snapped back to the dock.
+    const seeded = node.type === 'context' && node.dockPosition == null && this._suppressRecordingDepth === 0
+      ? { ...node, dockPosition: 'right' as const, collapsed: true }
+      : node;
+    const cloned = structuredClone(this.normalizeNode(seeded));
     this.nodes.set(node.id, cloned);
     this.scheduleSave();
     this.notifyChange('nodes');
@@ -1874,7 +1888,12 @@ class CanvasStateManager {
     // normalizeAxForCurrentNodes after apply, yet still returned as a phantom
     // success object — false success / silent data loss. Reject instead so the
     // HTTP/MCP layers surface ok:false / 4xx.
-    const anchorType = input.anchorType ?? 'node';
+    // Context-aware default: only fall back to a node anchor when a usable nodeId
+    // is present; otherwise treat it as an unanchored (body-only) note so a
+    // `{ body }`-only annotation succeeds (anchorType is documented optional).
+    const anchorType = input.anchorType ?? (typeof input.nodeId === 'string' && input.nodeId ? 'node' : 'file');
+    // An EXPLICIT node anchor still requires a real nodeId — reject a phantom
+    // node-anchored review rather than silently dropping it post-apply.
     if (anchorType === 'node' && (typeof input.nodeId !== 'string' || !this.currentNodeIdSet().has(input.nodeId))) {
       return null;
     }

package/src/server/html-surface.ts

@@ -107,27 +107,62 @@ function injectIntoHead(html: string, content: string): string {
  * the server re-validates every interaction — so this is a convenience surface,
  * not a trust boundary.
  */
-function buildAxBridge(axToken: string, nodeId: string): string {
+export function buildAxBridge(axToken: string, nodeId: string): string {
   const token = JSON.stringify(axToken);
   const node = JSON.stringify(nodeId);
   return `<script data-pmx-canvas-ax-bridge>
 const PMX_AX_TOKEN = ${token};
 const PMX_AX_NODE_ID = ${node};
-window.PMX_AX = {
-  emit(type, payload) {
-    window.parent.postMessage({
-      source: 'pmx-canvas-ax',
-      token: PMX_AX_TOKEN,
-      nodeId: PMX_AX_NODE_ID,
-      interaction: { type: String(type), payload: payload && typeof payload === 'object' ? payload : {} },
-    }, '*');
-  },
+window.PMX_AX = window.PMX_AX || {};
+window.PMX_AX.emit = function (type, payload) {
+  window.parent.postMessage({
+    source: 'pmx-canvas-ax',
+    token: PMX_AX_TOKEN,
+    nodeId: PMX_AX_NODE_ID,
+    interaction: { type: String(type), payload: payload && typeof payload === 'object' ? payload : {} },
+  }, '*');
 };
 </script>`;
 }
 
+/**
+ * Read-side bridge: seeds `window.PMX_AX.state` with a snapshot of the canvas AX
+ * state and keeps it live via nonce-validated `ax-update` messages from the parent
+ * canvas. Author HTML can read `window.PMX_AX.state` and subscribe to the
+ * `pmx-ax-update` CustomEvent to render a live work queue / focus. Injected only
+ * alongside the emit bridge (AX-enabled nodes). Read-only — no capability beyond
+ * the existing AX-enabled gate.
+ */
+export function buildAxStateBridge(axToken: string, snapshotJson: string): string {
+  const token = JSON.stringify(axToken);
+  return `<script data-pmx-canvas-ax-state-bridge>
+(function () {
+  const PMX_AX_STATE_TOKEN = ${token};
+  window.PMX_AX = window.PMX_AX || {};
+  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;
+    window.PMX_AX.state = m.state;
+    try { window.dispatchEvent(new CustomEvent('pmx-ax-update', { detail: m.state })); } catch (e) {}
+  });
+})();
+</script>`;
+}
+
+/** Escape a string for safe interpolation into element text (e.g. `<title>`). */
+function escapeSurfaceHtml(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
 export interface HtmlSurfaceOptions {
   theme: SurfaceTheme;
+  /**
+   * Tab/document title. Injected as `<title>` only when the author HTML does not
+   * already declare one, so a standalone "Open as site" tab shows the node title
+   * instead of falling back to the raw URL.
+   */
+  title?: string;
   /** Client nonce that authorizes parent → iframe theme-update messages. */
   themeToken?: string;
   presentation?: boolean;
@@ -138,6 +173,11 @@ export interface HtmlSurfaceOptions {
   axToken?: string;
   /** Node id stamped on emitted interactions. */
   nodeId?: string;
+  /**
+   * Initial AX state snapshot to seed `window.PMX_AX.state` (only used when
+   * axBridge is enabled). Kept live via parent → iframe `ax-update` messages.
+   */
+  axState?: unknown;
 }
 
 /**
@@ -154,17 +194,34 @@ export function buildHtmlSurfaceDocument(userHtml: string, options: HtmlSurfaceO
   const axBridge = options.axBridge
     ? buildAxBridge(sanitizeToken(options.axToken), sanitizeToken(options.nodeId))
     : '';
-  const injectedHeadContent = `${link}${themeBridge}${presentationBridge}${axBridge}`;
+  // Read-side AX state bridge (seed + live push). `</` is escaped so a work-item
+  // title containing "</script>" can't break out of the inline script.
+  const axStateBridge = options.axBridge
+    ? buildAxStateBridge(
+        sanitizeToken(options.axToken),
+        options.axState !== undefined ? JSON.stringify(options.axState).replace(/</g, '\\u003c') : 'null',
+      )
+    : '';
+  const injectedHeadContent = `${link}${themeBridge}${presentationBridge}${axBridge}${axStateBridge}`;
   const presentationAttr = options.presentation ? ' data-pmx-presentation-mode="present"' : '';
   const trimmed = userHtml.trim();
   const isFullDoc = /<html[\s>]/i.test(trimmed);
+  // Only supply a fallback <title> when the author HTML does not already set a
+  // DOCUMENT title. Strip inline <svg>/<math> first so a nested accessibility
+  // <title> (e.g. <svg><title>…</title></svg>) doesn't suppress the fallback.
+  const withoutNestedTitles = trimmed
+    .replace(/<svg[\s\S]*?<\/svg>/gi, '')
+    .replace(/<math[\s\S]*?<\/math>/gi, '');
+  const titleTag = options.title && !/<title[\s>]/i.test(withoutNestedTitles)
+    ? `<title>${escapeSurfaceHtml(options.title)}</title>`
+    : '';
   if (isFullDoc) {
     const withTheme = trimmed.replace(
       /<html([^>]*)>/i,
       `<html$1 data-pmx-canvas-theme="${options.theme}" data-theme="${options.theme}"${presentationAttr}>`,
     );
-    return injectIntoHead(withTheme, injectedHeadContent);
+    return injectIntoHead(withTheme, `${titleTag}${injectedHeadContent}`);
   }
   // Fragment — wrap in a full document.
-  return `<!doctype html><html data-pmx-canvas-theme="${options.theme}" data-theme="${options.theme}"${presentationAttr}><head><meta charset="utf-8">${injectedHeadContent}</head><body>${userHtml}</body></html>`;
+  return `<!doctype html><html data-pmx-canvas-theme="${options.theme}" data-theme="${options.theme}"${presentationAttr}><head><meta charset="utf-8">${titleTag}${injectedHeadContent}</head><body>${userHtml}</body></html>`;
 }

package/src/server/index.ts

@@ -74,6 +74,7 @@ import {
 } from './canvas-operations.js';
 import { validateCanvasLayout } from './canvas-validation.js';
 import { describeCanvasSchema, validateStructuredCanvasPayload } from './canvas-schema.js';
+import { serializeCanvasNode, type SerializedCanvasNode } from './canvas-serialization.js';
 import { buildHtmlPrimitive, getHtmlPrimitiveSemanticMetadata, isHtmlPrimitiveKind, listHtmlPrimitiveDescriptors } from './html-primitives.js';
 import type { HtmlPrimitiveKind } from './html-primitives.js';
 import {
@@ -124,6 +125,19 @@ import type {
   PrimaryWorkbenchIntent,
 } from './server.js';
 
+/**
+ * Node object returned by the SDK's create/get methods. It is the fully
+ * serialized node (adds `surfaceUrl`, `kind`, `title`, `content`, …) plus a
+ * `nodeId` alias for `id`, so the SDK return shape matches the HTTP/CLI
+ * `node`-create responses field-for-field.
+ */
+export type SdkCanvasNode = SerializedCanvasNode & { nodeId: string };
+
+/** Enrich a raw canvas node into the SDK return shape (surfaceUrl + nodeId). */
+function toSdkNode(node: CanvasNodeState): SdkCanvasNode {
+  return { ...serializeCanvasNode(node), nodeId: node.id };
+}
+
 export class PmxCanvas extends EventEmitter {
   private _port: number;
   private _server: string | null = null;
@@ -224,7 +238,7 @@ export class PmxCanvas extends EventEmitter {
     width?: number;
     height?: number;
     strictSize?: boolean;
-  }): CanvasNodeState {
+  }): SdkCanvasNode {
     if (input.type === 'webpage') {
       throw new Error('Use addWebpageNode for webpage nodes so page content is fetched and cached on the server.');
     }
@@ -241,7 +255,7 @@ export class PmxCanvas extends EventEmitter {
       });
       const groupNode = canvasState.getNode(groupId);
       if (!groupNode) throw new Error(`Group node "${groupId}" was not created.`);
-      return groupNode;
+      return toSdkNode(groupNode);
     }
     const { id, needsCodeGraphRecompute } = addCanvasNode({
       ...input,
@@ -277,7 +291,7 @@ export class PmxCanvas extends EventEmitter {
 
     const node = canvasState.getNode(id);
     if (!node) throw new Error(`Node "${id}" was not created.`);
-    return node;
+    return toSdkNode(node);
   }
 
   async addWebpageNode(input: {
@@ -735,8 +749,9 @@ export class PmxCanvas extends EventEmitter {
     return canvasState.getLayout();
   }
 
-  getNode(id: string): CanvasNodeState | undefined {
-    return canvasState.getNode(id);
+  getNode(id: string): SdkCanvasNode | undefined {
+    const node = canvasState.getNode(id);
+    return node ? toSdkNode(node) : undefined;
   }
 
   search(query: string): ReturnType<typeof searchNodes> {
@@ -753,6 +768,9 @@ export class PmxCanvas extends EventEmitter {
     if (!entry) return { ok: false, description: 'Nothing to undo' };
     await syncCanvasRuntimeBackends();
     emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+    // Undo can reverse an AX mutation (work item, focus, …); nudge AX surfaces to
+    // re-fetch so a live board reflects the reversal (debounced client-side).
+    emitPrimaryWorkbenchEvent('ax-state-changed', {});
     return { ok: true, description: `Undid: ${entry.description}` };
   }
 
@@ -761,6 +779,7 @@ export class PmxCanvas extends EventEmitter {
     if (!entry) return { ok: false, description: 'Nothing to redo' };
     await syncCanvasRuntimeBackends();
     emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+    emitPrimaryWorkbenchEvent('ax-state-changed', {});
     return { ok: true, description: `Redid: ${entry.description}` };
   }
 
@@ -1027,7 +1046,10 @@ export class PmxCanvas extends EventEmitter {
     width?: number;
     height?: number;
     strictSize?: boolean;
-  }): string {
+    /** Opt this html node into AX interactions (window.PMX_AX.emit). Clamped to
+     *  the html capability ceiling server-side; cannot escalate. */
+    axCapabilities?: { enabled?: boolean; allowed?: string[] };
+  }): SdkCanvasNode {
     const { id } = addCanvasNode({
       type: 'html',
       ...(typeof input.title === 'string' ? { title: input.title } : {}),
@@ -1040,6 +1062,7 @@ export class PmxCanvas extends EventEmitter {
         ...(Array.isArray(input.slideTitles) ? { slideTitles: input.slideTitles } : {}),
         ...(Array.isArray(input.embeddedNodeIds) ? { embeddedNodeIds: input.embeddedNodeIds } : {}),
         ...(Array.isArray(input.embeddedUrls) ? { embeddedUrls: input.embeddedUrls } : {}),
+        ...(input.axCapabilities ? { axCapabilities: input.axCapabilities } : {}),
       },
       ...(typeof input.x === 'number' ? { x: input.x } : {}),
       ...(typeof input.y === 'number' ? { y: input.y } : {}),
@@ -1050,7 +1073,9 @@ export class PmxCanvas extends EventEmitter {
       defaultHeight: 640,
     });
     emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
-    return id;
+    const node = canvasState.getNode(id);
+    if (!node) throw new Error(`HTML node "${id}" was not created.`);
+    return toSdkNode(node);
   }
 
   addHtmlPrimitive(input: {

package/src/server/server.ts

@@ -48,7 +48,7 @@ import type {
   ListToolsResult,
 } from '@modelcontextprotocol/sdk/types.js';
 import { type CanvasAnnotation, type CanvasEdge, type CanvasLayout, type CanvasNodeState, IMAGE_MIME_MAP, canvasState } from './canvas-state.js';
-import { buildHtmlSurfaceDocument, HTML_SURFACE_SANDBOX, normalizeSurfaceTheme } from './html-surface.js';
+import { buildAxBridge, buildAxStateBridge, buildHtmlSurfaceDocument, HTML_SURFACE_SANDBOX, normalizeSurfaceTheme } from './html-surface.js';
 import { findCanvasExtAppNodeId as findCanvasExtAppNodeIdShared } from './ext-app-lookup.js';
 import { normalizeExtAppToolResult } from './ext-app-tool-result.js';
 import { getMcpAppHostSnapshot } from './mcp-app-host.js';
@@ -77,7 +77,7 @@ import {
 } from './canvas-serialization.js';
 import { buildCodeGraphSummary, formatCodeGraph } from './code-graph.js';
 import { buildAgentContextPreamble, serializeNodeForAgentContext } from './agent-context.js';
-import { buildCanvasAxContext } from './ax-context.js';
+import { buildCanvasAxContext, buildCanvasAxSurfaceSnapshot } from './ax-context.js';
 import { applyAxInteraction, resolveNodeAxCapabilities } from './ax-interaction.js';
 import { isAxEventKind, isAxEvidenceKind } from './ax-state.js';
 import type {
@@ -1432,14 +1432,21 @@ function handleNodeSurface(pathname: string, url: URL): Response {
     if (!html) return responseText('HTML node has no content', 404);
     const present = url.searchParams.get('present') === '1';
     const axCaps = resolveNodeAxCapabilities(node);
+    const axEnabled = axCaps.enabled && axCaps.allowed.length > 0;
+    const surfaceTitle = typeof node.data.title === 'string' && node.data.title.trim()
+      ? node.data.title
+      : node.id;
     const doc = buildHtmlSurfaceDocument(html, {
       theme,
+      title: surfaceTitle,
       themeToken: url.searchParams.get('themeToken') ?? undefined,
       presentation: present,
       presentationExitToken: url.searchParams.get('presentToken') ?? undefined,
-      axBridge: axCaps.enabled && axCaps.allowed.length > 0,
+      axBridge: axEnabled,
       axToken: url.searchParams.get('axToken') ?? undefined,
       nodeId: node.id,
+      // Seed the read-side bridge with the current AX state (only for AX surfaces).
+      ...(axEnabled ? { axState: buildCanvasAxSurfaceSnapshot() } : {}),
     });
     return surfaceHtmlResponse(doc, HTML_SURFACE_SANDBOX);
   }
@@ -2532,6 +2539,7 @@ async function handleJsonRenderView(url: URL): Promise<Response> {
     process.env.PMX_CANVAS_JSON_RENDER_DEVTOOLS === '1' &&
     url.searchParams.get('devtools') === '1';
   const axToken = url.searchParams.get('axToken');
+  const axEnabled = resolveNodeAxCapabilities(node).enabled;
   const html = await buildJsonRenderViewerHtml({
     title,
     spec,
@@ -2539,6 +2547,8 @@ async function handleJsonRenderView(url: URL): Promise<Response> {
     ...(url.searchParams.get('display') === 'expanded' ? { display: 'expanded' as const } : {}),
     ...(devtoolsEnabled ? { devtools: true } : {}),
     ...(axToken ? { nodeId, axToken } : {}),
+    // Seed the read-side AX state (only for AX-enabled nodes) so specs can bind /ax.
+    ...(axToken && axEnabled ? { axState: buildCanvasAxSurfaceSnapshot() } : {}),
   });
   return new Response(html, {
     headers: {
@@ -2596,7 +2606,27 @@ function handleArtifactView(url: URL): Response {
   }
 
   if (ext === '.html' || ext === '.htm') {
-    const content = readFileSync(safePath, 'utf-8');
+    let content = readFileSync(safePath, 'utf-8');
+    // AX bridge for web-artifacts (same opaque-origin postMessage bridge as html
+    // surfaces — a sandboxed artifact can't fetch the API directly). The viewer
+    // appends axToken + axNodeId only for AX-enabled artifacts; the server still
+    // re-validates every interaction.
+    const axToken = url.searchParams.get('axToken');
+    const axNodeId = url.searchParams.get('axNodeId');
+    if (axToken && axNodeId) {
+      const node = canvasState.getNode(axNodeId);
+      if (node && resolveNodeAxCapabilities(node).enabled) {
+        const safeToken = axToken.replace(/[^A-Za-z0-9_-]/g, '').slice(0, 80);
+        // Use the canonical node.id (server-generated [a-z0-9-]) rather than the raw
+        // query param so nothing untrusted reaches the inline bridge script.
+        const safeNodeId = node.id.replace(/[^A-Za-z0-9_-]/g, '').slice(0, 80);
+        const stateJson = JSON.stringify(buildCanvasAxSurfaceSnapshot()).replace(/</g, '\\u003c');
+        const bridge = `${buildAxBridge(safeToken, safeNodeId)}${buildAxStateBridge(safeToken, stateJson)}`;
+        content = content.includes('</head>')
+          ? content.replace('</head>', `${bridge}</head>`)
+          : `${bridge}${content}`;
+      }
+    }
     return new Response(content, {
       headers: {
         'Content-Type': 'text/html; charset=utf-8',
@@ -3823,6 +3853,30 @@ function handleGetAxContext(): Response {
   return responseJson(buildCanvasAxContext());
 }
 
+// Compact AX state for surfaces (the same shape seeded into AX-enabled iframes).
+// The client fetches this and pushes it to surfaces over the ax-update channel.
+function handleGetAxSurfaceSnapshot(): Response {
+  return responseJson(buildCanvasAxSurfaceSnapshot());
+}
+
+// Open a node's surface in the user's real system browser (for hosts whose
+// embedded browser makes window.open('_blank') feel in-place, e.g. Codex).
+// Accepts ONLY { nodeId } and opens this server's own surface URL — never an
+// arbitrary URL — so it can't be used to launch external sites (no SSRF). Honors
+// the PMX_CANVAS_DISABLE_BROWSER_OPEN kill switch via openUrlInExternalBrowser.
+async function handleOpenExternalSurface(req: Request): Promise<Response> {
+  const body = await readJson(req);
+  const nodeId = typeof body.nodeId === 'string' ? body.nodeId : '';
+  if (!nodeId) return responseJson({ ok: false, error: 'nodeId is required.' }, 400);
+  const node = canvasState.getNode(nodeId);
+  if (!node) return responseJson({ ok: false, error: `Node "${nodeId}" not found.` }, 404);
+  const port = getCanvasServerPort();
+  if (!port) return responseJson({ ok: false, opened: false, error: 'Server port unavailable.' }, 503);
+  const surfacePath = `/api/canvas/surface/${encodeURIComponent(nodeId)}`;
+  const opened = openUrlInExternalBrowser(`http://localhost:${port}${surfacePath}`);
+  return responseJson({ ok: true, opened, url: surfacePath });
+}
+
 async function handleAxInteraction(req: Request): Promise<Response> {
   const body = await readJson(req);
   const { result, events } = applyAxInteraction(canvasState, body, normalizeAxSource(body.source, 'api'));
@@ -4482,6 +4536,57 @@ function syncContextNodeToCanvasState(
   canvasState.updateNode(id, { data: mergedData });
 }
 
+/**
+ * Seed the docked status (left) + context (right) widgets so a freshly opened
+ * canvas shows them by default — the same nodes the agent-event path creates on
+ * demand (`status-main`, `context-main`), just present from the start.
+ *
+ * First-run only: we bail if the workspace canvas already has persisted state,
+ * so we never add them to a board with content, and — because first-run state is
+ * persisted on save — deleting or undocking them later is respected (they are
+ * not re-seeded). Create-if-missing keeps it idempotent if the agent path
+ * already made one. Returns true if anything was seeded.
+ */
+export function ensureDefaultDockedNodes(): boolean {
+  if (canvasState.hasPersistedState()) return false;
+  let seeded = false;
+  // NOTE: these node specs mirror the agent-event create paths below
+  // (`canvas-status` for status-main, `syncContextNodeToCanvasState` for
+  // context-main) — keep geometry/dock defaults in sync if you change them.
+  if (!canvasState.getNode('status-main')) {
+    canvasState.addNode({
+      id: 'status-main',
+      type: 'status',
+      position: { x: 40, y: 80 },
+      size: { width: 300, height: 120 },
+      zIndex: 0,
+      collapsed: true,
+      pinned: false,
+      dockPosition: 'left',
+      data: { phase: 'idle', message: '', elapsed: 0 },
+    });
+    seeded = true;
+  }
+  if (!canvasState.getNode('context-main')) {
+    canvasState.addNode({
+      id: 'context-main',
+      type: 'context',
+      position: { x: 1130, y: 80 },
+      size: { width: 320, height: 400 },
+      zIndex: 1,
+      collapsed: true,
+      pinned: false,
+      dockPosition: 'right',
+      data: { cards: [], auxTabs: [] },
+    });
+    seeded = true;
+  }
+  if (seeded) {
+    emitPrimaryWorkbenchEvent('canvas-layout-update', { layout: canvasState.getLayout() });
+  }
+  return seeded;
+}
+
 // Maps responseNodeId -> thread prompt node ID for O(1) routing of response events
 const serverResponseToThreadMap = new Map<string, string>();
 
@@ -5249,6 +5354,14 @@ export function startCanvasServer(options: CanvasServerOptions = {}): string | n
             return handleGetAxContext();
           }
 
+          if (url.pathname === '/api/canvas/ax/surface-snapshot' && req.method === 'GET') {
+            return handleGetAxSurfaceSnapshot();
+          }
+
+          if (url.pathname === '/api/canvas/open-external' && req.method === 'POST') {
+            return handleOpenExternalSurface(req);
+          }
+
           if (url.pathname === '/api/canvas/ax/focus' && req.method === 'POST') {
             return handleAxFocusUpdate(req);
           }