pmx-canvas 0.1.31 → 0.1.32

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

@@ -6,6 +6,7 @@ import {
   addEdge,
   addNode,
   applyServerCanvasLayout,
+  axSurfaceState,
   bringToFront,
   cancelViewportAnimation,
   canvasTheme,
@@ -24,6 +25,7 @@ import {
   updateNode,
   updateNodeData,
 } from './canvas-store';
+import { fetchAxSurfaceState } from './intent-bridge';
 import { invalidateTokenCache } from '../theme/tokens';
 import { resetAttentionBridge, syncAttentionFromSse } from './attention-bridge';
 
@@ -926,6 +928,19 @@ function handleContextPinsChanged(data: Record<string, unknown>): void {
   syncAttentionFromSse({ event: 'context-pins-changed', data });
 }
 
+// AX state changes arrive as per-primitive deltas; rather than reduce them, treat
+// the event as a "something changed" signal and re-fetch the full compact snapshot
+// (debounced). The snapshot feeds AX-enabled surfaces (HtmlNode/McpAppNode push it
+// into their iframes), so authored boards reflect the live work queue / focus.
+let axRefreshTimer: ReturnType<typeof setTimeout> | null = null;
+function handleAxStateChanged(): void {
+  if (axRefreshTimer) clearTimeout(axRefreshTimer);
+  axRefreshTimer = setTimeout(() => {
+    axRefreshTimer = null;
+    void fetchAxSurfaceState().then((state) => { axSurfaceState.value = state; });
+  }, 150);
+}
+
 // ── SSE connection ────────────────────────────────────────────
 /** @internal — exported for testing */
 export const EVENT_HANDLERS: Record<string, (data: Record<string, unknown>) => void> = {
@@ -959,6 +974,8 @@ export const EVENT_HANDLERS: Record<string, (data: Record<string, unknown>) => v
   'canvas-response-start': handleCanvasResponseStart,
   'canvas-response-delta': handleCanvasResponseDelta,
   'canvas-response-complete': handleCanvasResponseComplete,
+  'ax-state-changed': handleAxStateChanged,
+  'ax-event-created': handleAxStateChanged,
 };
 
 export function connectSSE(): () => void {

package/src/client/theme/global.css

@@ -457,13 +457,15 @@ body,
   font-weight: 600;
 }
 
-/* HUD layer — fixed row: [left-dock] [toolbar] [right-dock] */
+/* HUD layer — [left-dock] [toolbar] [right-dock]. Wraps onto multiple rows in a
+   narrow embedding panel (e.g. the Copilot side panel) instead of clipping. */
 .hud-layer {
   position: fixed;
   top: 12px;
   left: 12px;
   right: 12px;
   display: flex;
+  flex-wrap: wrap;
   align-items: flex-start;
   justify-content: center;
   gap: 8px;
@@ -476,22 +478,24 @@ body,
 .hud-left,
 .hud-right {
   display: flex;
+  flex-wrap: wrap;
   gap: 8px;
 }
 
 /* Toolbar */
 .canvas-toolbar {
   display: flex;
+  flex-wrap: wrap;
   align-items: center;
   gap: 6px;
   padding: 6px 10px;
   min-height: var(--hud-bar-height);
+  max-width: 100%;
   box-sizing: border-box;
   background: var(--c-panel-glass);
   backdrop-filter: blur(12px);
   border: 1px solid var(--c-line);
   border-radius: var(--radius);
-  flex-shrink: 0;
 }
 
 .toolbar-tooltip-anchor {
@@ -666,9 +670,11 @@ body,
 
 .toolbar-group {
   display: flex;
+  flex-wrap: wrap;
   align-items: center;
   gap: 6px;
-  flex-shrink: 0;
+  min-width: 0;
+  max-width: 100%;
 }
 
 .canvas-toolbar button svg {
@@ -692,6 +698,15 @@ body,
   }
 }
 
+/* Narrow embedding panels: drop low-value text from the HUD so the icon controls
+   fit in fewer rows. Buttons keep their aria-labels + tooltips, so nothing is
+   lost for a11y or discovery. */
+@media (max-width: 720px) {
+  .hud-collapsible-text {
+    display: none;
+  }
+}
+
 /* Raw markdown source editor */
 .md-editor-split {
   display: flex;

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

@@ -8,8 +8,9 @@
  */
 
 import type { Spec } from '@json-render/core';
+import { useEffect } from 'react';
 import { createRoot } from 'react-dom/client';
-import { defineRegistry, JSONUIProvider, Renderer } from '@json-render/react';
+import { defineRegistry, JSONUIProvider, Renderer, useStateBinding } from '@json-render/react';
 import { shadcnComponents } from '@json-render/shadcn';
 import { catalog } from '../catalog';
 import { chartComponents } from '../charts/components';
@@ -81,9 +82,30 @@ declare global {
     __PMX_CANVAS_JSON_RENDER_DEVTOOLS__?: boolean;
     __PMX_CANVAS_JSON_RENDER_NODE_ID__?: string;
     __PMX_CANVAS_AX_TOKEN__?: string;
+    __PMX_CANVAS_AX_STATE__?: unknown;
   }
 }
 
+// Read-side AX bridge for json-render: keeps the spec-bound `/ax` state live as
+// the parent canvas pushes nonce-validated `ax-update` messages, so a declarative
+// board ({ "$state": "/ax/workItems" }) reflects the work queue in real time.
+function AxStateSync() {
+  const [, setAx] = useStateBinding<unknown>('ax');
+  useEffect(() => {
+    const token = window.__PMX_CANVAS_AX_TOKEN__;
+    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;
+      window.__PMX_CANVAS_AX_STATE__ = m.state;
+      setAx(m.state);
+    }
+    window.addEventListener('message', onMessage);
+    return () => window.removeEventListener('message', onMessage);
+  }, [setAx]);
+  return null;
+}
+
 // AX interaction types a json-render spec can bind actions to. When an action
 // named like one of these fires, we forward it to the parent canvas (which
 // validates + submits through the capability-gated endpoint). Convention-based
@@ -149,14 +171,21 @@ function App() {
     );
   }
 
+  // Seed AX state under a reserved `/ax` key so specs can bind { "$state": "/ax/workItems" }.
+  const axState = window.__PMX_CANVAS_AX_STATE__;
+  const initialState = axState !== undefined && axState !== null
+    ? { ...(spec.state ?? {}), ax: axState }
+    : spec.state ?? undefined;
+
   return (
     <div style={{ minHeight: '100vh', padding: 16, boxSizing: 'border-box' }}>
       <JSONUIProvider
         registry={registry}
-        initialState={spec.state ?? undefined}
+        initialState={initialState}
         directives={pmxCanvasDirectives}
         handlers={buildAxHandlers()}
       >
+        <AxStateSync />
         <Renderer spec={spec} registry={registry} loading={false} />
         {window.__PMX_CANVAS_JSON_RENDER_DEVTOOLS__ ? (
           <JsonRenderDevtools position="right" />

package/src/json-render/server.ts

@@ -943,6 +943,7 @@ export async function buildJsonRenderViewerHtml(options: {
   devtools?: boolean;
   nodeId?: string;
   axToken?: string;
+  axState?: unknown;
 }): Promise<string> {
   const sanitizeAxValue = (v?: string): string => (typeof v === 'string' ? v.replace(/[^A-Za-z0-9_-]/g, '').slice(0, 80) : '');
   try {
@@ -962,6 +963,8 @@ export async function buildJsonRenderViewerHtml(options: {
       ...(options.nodeId && options.axToken ? [
         `window.__PMX_CANVAS_JSON_RENDER_NODE_ID__ = ${JSON.stringify(sanitizeAxValue(options.nodeId))};`,
         `window.__PMX_CANVAS_AX_TOKEN__ = ${JSON.stringify(sanitizeAxValue(options.axToken))};`,
+        // Read-side AX state: seed for initial render + bound under /ax for specs.
+        `window.__PMX_CANVAS_AX_STATE__ = ${JSON.stringify(options.axState ?? null).replace(/</g, '\\u003c')};`,
       ] : []),
       jsBundle,
     ].join('\n');

package/src/mcp/canvas-access.ts

@@ -685,6 +685,7 @@ class RemoteCanvasAccess implements CanvasAccess {
       slideTitles,
       embeddedNodeIds,
       embeddedUrls,
+      axCapabilities,
       ...rest
     } = input as AddHtmlNodeInput & {
       summary?: string;
@@ -694,6 +695,7 @@ class RemoteCanvasAccess implements CanvasAccess {
       slideTitles?: string[];
       embeddedNodeIds?: string[];
       embeddedUrls?: string[];
+      axCapabilities?: { enabled?: boolean; allowed?: string[] };
     };
     return await this.requestNodeId('POST', '/api/canvas/node', {
       type: 'html',
@@ -706,6 +708,7 @@ class RemoteCanvasAccess implements CanvasAccess {
         ...(Array.isArray(slideTitles) ? { slideTitles } : {}),
         ...(Array.isArray(embeddedNodeIds) ? { embeddedNodeIds } : {}),
         ...(Array.isArray(embeddedUrls) ? { embeddedUrls } : {}),
+        ...(axCapabilities ? { axCapabilities } : {}),
       },
     });
   }

package/src/mcp/server.ts

@@ -447,6 +447,10 @@ export async function startMcpServer(): Promise<void> {
       width: z.number().optional().describe('Width in pixels (default: 720).'),
       height: z.number().optional().describe('Height in pixels (default: 640).'),
       strictSize: z.boolean().optional().describe('Keep explicit width/height fixed; iframe scrolls overflow internally.'),
+      axCapabilities: z.object({
+        enabled: z.boolean().optional(),
+        allowed: z.array(z.string()).optional().describe('AX interaction types this node may emit (e.g. ax.work.create, ax.work.update, ax.steer, ax.focus.set, ax.evidence.add, ax.event.record). Clamped to the html capability ceiling server-side; cannot escalate.'),
+      }).optional().describe('Opt this html node into AX interactions so its sandboxed UI can emit ax.* via window.PMX_AX.emit(type, payload) (and reflect live AX state). html nodes are AX-disabled by default; set { enabled: true, allowed: [...] } to turn the bridge on. Build interactive boards (work queues, review boards, inboxes) this way.'),
       full: z.boolean().optional().describe('Return the full created node payload. Default false returns compact metadata.'),
       verbose: z.boolean().optional().describe('Alias for full:true.'),
     },
@@ -455,6 +459,7 @@ export async function startMcpServer(): Promise<void> {
       const id = await c.addHtmlNode({
         html: input.html,
         ...(typeof input.title === 'string' ? { title: input.title } : {}),
+        ...(input.axCapabilities ? { axCapabilities: input.axCapabilities } : {}),
         ...(typeof input.summary === 'string' ? { summary: input.summary } : {}),
         ...(typeof input.agentSummary === 'string' ? { agentSummary: input.agentSummary } : {}),
         ...(typeof input.description === 'string' ? { description: input.description } : {}),
@@ -1079,11 +1084,15 @@ export async function startMcpServer(): Promise<void> {
       dockPosition: z.enum(['left', 'right']).nullable().optional().describe('Dock the node to the left/right HUD column, or pass null to return it to the canvas'),
       pinned: z.boolean().optional().describe('Pin or unpin the node to exclude it from auto-arrange'),
       arrangeLocked: z.boolean().optional().describe('Prevent auto-arrange from moving this node. Pinned nodes are also skipped.'),
+      axCapabilities: z.object({
+        enabled: z.boolean().optional(),
+        allowed: z.array(z.string()).optional(),
+      }).optional().describe('Enable/disable AX interactions on an existing node (e.g. flip an html node on with { enabled: true, allowed: ["ax.work.create"] }). Merged into the node data; clamped to the node-type ceiling server-side.'),
       full: z.boolean().optional().describe('Return the full updated node payload. Default false returns compact metadata.'),
       verbose: z.boolean().optional().describe('Alias for full:true.'),
     },
     async (input) => {
-      const { id, title, content, x, y, width, height, spec, graphType, data, xKey, yKey, chartHeight, collapsed, dockPosition, pinned, arrangeLocked, toolName, category, status, duration, resultSummary, error } = input;
+      const { id, title, content, x, y, width, height, spec, graphType, data, xKey, yKey, chartHeight, collapsed, dockPosition, pinned, arrangeLocked, axCapabilities, toolName, category, status, duration, resultSummary, error } = input;
       const c = await ensureCanvas();
       const node = await c.getNode(id);
       if (!node) {
@@ -1125,6 +1134,19 @@ export async function startMcpServer(): Promise<void> {
       if (arrangeLocked !== undefined) {
         patch.arrangeLocked = arrangeLocked;
       }
+      if (axCapabilities !== undefined) {
+        // A graph dataset update (`data` array) and an axCapabilities toggle collide
+        // on patch.data (array vs object) — reject rather than silently dropping the
+        // dataset. Otherwise merge into existing node data so enabling AX doesn't
+        // clobber html/spec/etc. The server re-clamps axCapabilities to the ceiling.
+        if (Array.isArray(patch.data)) {
+          return {
+            content: [{ type: 'text', text: 'Update the graph dataset and axCapabilities in separate canvas_update_node calls.' }],
+            isError: true,
+          };
+        }
+        patch.data = { ...(node.data as Record<string, unknown>), axCapabilities };
+      }
       await c.updateNode(id, patch);
       const updated = await c.getNode(id);
       return {

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

@@ -1888,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,25 +107,49 @@ 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;');
@@ -149,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;
 }
 
 /**
@@ -165,7 +194,15 @@ 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);

package/src/server/index.ts

@@ -768,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}` };
   }
 
@@ -776,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}` };
   }
 
@@ -1042,6 +1046,9 @@ export class PmxCanvas extends EventEmitter {
     width?: number;
     height?: number;
     strictSize?: boolean;
+    /** 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',
@@ -1055,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 } : {}),

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,6 +1432,7 @@ 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;
@@ -1441,9 +1442,11 @@ function handleNodeSurface(pathname: string, url: URL): Response {
       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);
   }
@@ -2536,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,
@@ -2543,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: {
@@ -2600,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',
@@ -3827,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'));
@@ -5304,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);
           }