pmx-canvas 0.1.30 → 0.1.32

package/src/client/nodes/HtmlNode.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useMemo, useRef } from 'preact/hooks';
-import { canvasTheme } from '../state/canvas-store';
+import { axSurfaceState, canvasTheme } from '../state/canvas-store';
 import { submitAxInteractionFromClient } from '../state/intent-bridge';
 import { showToast } from '../state/attention-bridge';
 import type { CanvasNodeState } from '../types';
@@ -82,6 +82,23 @@ export function HtmlNode({
     if (autoFocus) iframeRef.current?.focus();
   }, [theme, themeToken]);
 
+  // Read-side AX bridge: push live AX state into the surface so an AX-enabled
+  // board reflects the work queue / focus. Validated by the surface against axToken.
+  // Gate matches the server's bridge-injection gate (enabled && allowed not empty)
+  // so we never push state to a surface the server left without the bridge.
+  const axCaps = node.data.axCapabilities as { enabled?: boolean; allowed?: unknown } | undefined;
+  const axEnabled = axCaps?.enabled === true && (!Array.isArray(axCaps.allowed) || axCaps.allowed.length > 0);
+  const axStateValue = axSurfaceState.value;
+  useEffect(() => {
+    if (!axEnabled || axStateValue == null) return;
+    iframeRef.current?.contentWindow?.postMessage({
+      source: 'pmx-canvas-html-node',
+      type: 'ax-update',
+      token: axToken,
+      state: axStateValue,
+    }, '*');
+  }, [axEnabled, axStateValue, axToken]);
+
   useEffect(() => {
     if (!autoFocus) return;
     const id = window.setTimeout(() => iframeRef.current?.focus(), 0);
@@ -95,6 +112,14 @@ export function HtmlNode({
       token: themeToken,
       theme,
     }, '*');
+    if (axEnabled && axSurfaceState.value != null) {
+      iframeRef.current?.contentWindow?.postMessage({
+        source: 'pmx-canvas-html-node',
+        type: 'ax-update',
+        token: axToken,
+        state: axSurfaceState.value,
+      }, '*');
+    }
     if (autoFocus) iframeRef.current?.focus();
   };
 

package/src/client/nodes/McpAppNode.tsx

@@ -1,11 +1,11 @@
 import { useEffect, useMemo, useRef } from 'preact/hooks';
 import type { CanvasNodeState } from '../types';
-import { canvasTheme } from '../state/canvas-store';
+import { axSurfaceState, canvasTheme } from '../state/canvas-store';
 import { submitAxInteractionFromClient } from '../state/intent-bridge';
 import { showToast } from '../state/attention-bridge';
 import { ExtAppFrame } from './ExtAppFrame';
 
-function withViewerParams(url: string, expanded: boolean, specVersion?: number, axToken?: string): string {
+function withViewerParams(url: string, expanded: boolean, specVersion?: number, axToken?: string, axNodeId?: string): string {
   if (!url) return url;
   try {
     const resolved = new URL(url, window.location.origin);
@@ -14,8 +14,11 @@ function withViewerParams(url: string, expanded: boolean, specVersion?: number,
     // Streaming json-render nodes bump specVersion as patches accumulate; including
     // it in the src reloads the iframe so it re-reads the latest accumulated spec.
     if (typeof specVersion === 'number') resolved.searchParams.set('v', String(specVersion));
-    // AX bridge nonce for json-render/graph viewer nodes (Phase 6 follow-up).
+    // AX bridge nonce for json-render/graph + web-artifact viewer nodes.
     if (axToken) resolved.searchParams.set('axToken', axToken);
+    // The /artifact route needs the node id to inject the AX bridge (the json-render
+    // view route already gets nodeId from its own query param).
+    if (axNodeId) resolved.searchParams.set('axNodeId', axNodeId);
     return resolved.toString();
   } catch {
     return url;
@@ -43,9 +46,18 @@ export function McpAppNode({ node, expanded = false }: { node: CanvasNodeState;
 
 function McpAppViewer({ node, expanded }: { node: CanvasNodeState; expanded: boolean }) {
   const iframeRef = useRef<HTMLIFrameElement>(null);
-  // json-render / graph viewers run the json-render bundle, which can forward
-  // spec actions named ax.* to us. Other viewers (web-artifact, hosted URLs) do not.
-  const isAxViewer = node.type === 'json-render' || node.type === 'graph';
+  // json-render / graph viewers run the json-render bundle, which forwards spec
+  // actions named ax.* to us. AX-enabled web-artifacts get the same emit+read
+  // bridge injected at the /artifact route. Hosted URL viewers do not.
+  const isWebArtifact = node.type === 'mcp-app' && node.data.viewerType === 'web-artifact';
+  const isJsonViewer = node.type === 'json-render' || node.type === 'graph';
+  const axFlag = (node.data.axCapabilities as { enabled?: boolean } | undefined)?.enabled;
+  // json-render/graph are AX-enabled by default (opt OUT with enabled:false, matching
+  // the server seed gate); web-artifacts opt IN. So an opted-out viewer is not treated
+  // as an AX viewer — no token, no emit, no read-state push.
+  const axOn = isWebArtifact ? axFlag === true : axFlag !== false;
+  const isAxViewer = (isJsonViewer || isWebArtifact) && axOn;
+  const axSurface: 'json-render' | 'mcp-app' = isWebArtifact ? 'mcp-app' : 'json-render';
   const axToken = useMemo(() => (isAxViewer ? `ax-${crypto.randomUUID()}` : ''), [isAxViewer]);
 
   // Receive AX emits forwarded by the json-render viewer; validate (bound to this
@@ -65,7 +77,7 @@ function McpAppViewer({ node, expanded }: { node: CanvasNodeState; expanded: boo
       void submitAxInteractionFromClient({
         type: interaction.type,
         sourceNodeId: node.id,
-        sourceSurface: 'json-render',
+        sourceSurface: axSurface,
         ...(interaction.payload && typeof interaction.payload === 'object'
           ? { payload: interaction.payload as Record<string, unknown> }
           : {}),
@@ -78,8 +90,22 @@ function McpAppViewer({ node, expanded }: { node: CanvasNodeState; expanded: boo
     return () => window.removeEventListener('message', onAxMessage);
   }, [isAxViewer, axToken, node.id]);
 
+  // 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.
+  const axStateValue = axSurfaceState.value;
+  const pushAxState = () => {
+    if (!isAxViewer || !axToken || axStateValue == null) return;
+    iframeRef.current?.contentWindow?.postMessage({
+      source: 'pmx-canvas-html-node',
+      type: 'ax-update',
+      token: axToken,
+      state: axStateValue,
+    }, '*');
+  };
+  useEffect(pushAxState, [isAxViewer, axToken, axStateValue]);
+
   const specVersion = typeof node.data.specVersion === 'number' ? node.data.specVersion : undefined;
-  const url = withViewerParams((node.data.url as string) || '', expanded, specVersion, axToken || undefined);
+  const url = withViewerParams((node.data.url as string) || '', expanded, specVersion, axToken || undefined, isAxViewer ? node.id : undefined);
   const sourceServer = (node.data.sourceServer as string) || '';
   const hostMode = (node.data.hostMode as string) || 'hosted';
   const fallbackReason = node.data.fallbackReason as string | undefined;
@@ -146,6 +172,7 @@ function McpAppViewer({ node, expanded }: { node: CanvasNodeState; expanded: boo
         sandbox="allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox"
         allow="clipboard-read; clipboard-write"
         loading="lazy"
+        onLoad={pushAxState}
         style={{ flex: 1, minHeight: 0, width: '100%' }}
         title={`MCP App: ${sourceServer}`}
       />

package/src/client/nodes/StatusNode.tsx

@@ -1,6 +1,5 @@
 import { PHASE_COLORS } from '../theme/tokens';
 import type { CanvasNodeState } from '../types';
-import { axNodeActionButtonStyle, runNodeAxInteraction } from './ax-node-actions';
 
 export function getStatusDisplayPhase(node: CanvasNodeState): string {
   const phase = typeof node.data.phase === 'string' && node.data.phase.trim().length > 0
@@ -95,25 +94,6 @@ export function StatusNode({ node }: { node: CanvasNodeState }) {
           {message}
         </div>
       )}
-
-      {/* AX: turn this status into a tracked work item */}
-      <button
-        type="button"
-        class="ax-node-action"
-        title="Create an AX work item tied to this node"
-        style={axNodeActionButtonStyle}
-        onClick={(e) => {
-          e.stopPropagation();
-          void runNodeAxInteraction(
-            node,
-            'ax.work.create',
-            { title: (node.data.title as string) || message || phase || 'Status update' },
-            'Tracked as work',
-          );
-        }}
-      >
-        Track as work
-      </button>
     </div>
   );
 }

package/src/client/nodes/surface-url.ts

@@ -1,4 +1,5 @@
 import { canvasTheme } from '../state/canvas-store';
+import { openNodeInSystemBrowserRequest } from '../state/intent-bridge';
 import { canOpenNodeAsSurface } from '../../shared/surface.js';
 import type { CanvasNodeState } from '../types';
 
@@ -46,3 +47,14 @@ export function canOpenAsSite(node: CanvasNodeState): boolean {
 export function openNodeAsSite(node: CanvasNodeState): void {
   window.open(nodeSurfaceUrl(node.id), '_blank', 'noopener');
 }
+
+/**
+ * Open the node's surface in the user's real SYSTEM browser via the server's OS
+ * launcher — for hosts (e.g. Codex) whose embedded browser makes a normal
+ * `_blank` tab feel in-place. Falls back to a normal new-tab open when the server
+ * can't launch (headless / PMX_CANVAS_DISABLE_BROWSER_OPEN).
+ */
+export async function openNodeInSystemBrowser(node: CanvasNodeState): Promise<void> {
+  const res = await openNodeInSystemBrowserRequest(node.id);
+  if (!res.opened) openNodeAsSite(node);
+}

package/src/client/state/canvas-store.ts

@@ -18,6 +18,10 @@ export const sessionId = signal<string>('');
 export const traceEnabled = signal<boolean>(false);
 export const canvasTheme = signal<string>('dark');
 export const hasInitialServerLayout = signal<boolean>(false);
+// Compact AX state snapshot (work items, focus, …) mirrored from the server and
+// pushed into AX-enabled surfaces so authored boards can render the live queue.
+// Refreshed by the SSE bridge on ax-state-changed / ax-event-created.
+export const axSurfaceState = signal<unknown>(null);
 
 // ── Expanded (focus) node ─────────────────────────────────────
 // Only one node at a time can be in expanded/focus mode. When expanded, the

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

@@ -255,6 +255,25 @@ export interface AxInteractionResponse {
   error?: string;
 }
 
+/** Fetch the compact AX state snapshot pushed into AX-enabled surfaces. */
+export async function fetchAxSurfaceState(): Promise<unknown> {
+  return requestJson<unknown>('fetchAxSurfaceState', '/api/canvas/ax/surface-snapshot', null);
+}
+
+/** Ask the server to open a node's surface in the system browser. */
+export async function openNodeInSystemBrowserRequest(nodeId: string): Promise<{ ok: boolean; opened: boolean }> {
+  return requestJson<{ ok: boolean; opened: boolean }>(
+    'openNodeInSystemBrowserRequest',
+    '/api/canvas/open-external',
+    { ok: false, opened: false },
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ nodeId }),
+    },
+  );
+}
+
 /** Submit a capability-gated AX interaction from a native node control. */
 export async function submitAxInteractionFromClient(input: AxInteractionRequest): Promise<AxInteractionResponse> {
   return requestJson<AxInteractionResponse>(

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

@@ -56,6 +56,10 @@
   --mono: "IBM Plex Mono", "SF Mono", "Fira Code", monospace;
   --radius: 10px;
   --radius-sm: 6px;
+  /* Shared height for the top HUD row so the toolbar and the collapsed docked
+     status/context widgets that flank it line up to the same height. Matches the
+     toolbar's natural content height (icon buttons at 6px padding). */
+  --hud-bar-height: 44px;
 }
 
 :root[data-theme="light"] {
@@ -453,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;
@@ -472,20 +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 {
@@ -660,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 {
@@ -686,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;
@@ -1409,6 +1430,38 @@ html.is-node-resizing .ext-app-preview-catcher {
   max-width: 320px;
 }
 
+/* Collapsed docked widget = a single menu-height pill that flanks the toolbar.
+   Pinned to the same height as .canvas-toolbar so the top HUD row reads as one
+   continuous bar (status on the left, context on the right). */
+.docked-node--collapsed {
+  height: var(--hud-bar-height);
+  box-sizing: border-box;
+  justify-content: center;
+  width: auto;
+  /* Reset the base .docked-node min-width so the collapsed pill hugs its content
+     (badge + count + controls) instead of stretching to a 200px bar. */
+  min-width: 0;
+}
+.docked-node--collapsed .docked-node-header {
+  height: 100%;
+  padding: 0 10px;
+  border-bottom: none;
+}
+.docked-node-count {
+  min-width: 18px;
+  height: 18px;
+  padding: 0 5px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 9px;
+  background: var(--c-accent);
+  color: var(--c-contrast-fg);
+  font-size: 10px;
+  font-weight: 700;
+  flex-shrink: 0;
+}
+
 .docked-node-header {
   display: flex;
   align-items: center;
@@ -1948,62 +2001,6 @@ html.is-node-resizing .ext-app-preview-catcher {
   max-width: 200px;
 }
 
-/* Context dock — collapsed pill mirrors Updates pill, sits above it */
-.context-dock-tab {
-  position: fixed;
-  top: 92px;
-  right: 0;
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  padding: 8px 12px 8px 14px;
-  background: color-mix(in srgb, var(--c-panel-glass) 96%, transparent);
-  backdrop-filter: blur(16px);
-  border: 1px solid color-mix(in srgb, var(--c-line) 82%, var(--c-accent) 18%);
-  border-right: 0;
-  border-radius: 14px 0 0 14px;
-  box-shadow: 0 12px 36px var(--c-shadow);
-  color: var(--c-text);
-  cursor: pointer;
-  font: inherit;
-  font-size: 11px;
-  font-weight: 600;
-  letter-spacing: 0.08em;
-  text-transform: uppercase;
-  z-index: 60;
-}
-
-.context-dock-tab:hover {
-  border-color: color-mix(in srgb, var(--c-accent) 40%, var(--c-line) 60%);
-  color: var(--c-accent);
-}
-
-.context-dock-tab svg {
-  display: block;
-  color: var(--c-accent);
-  flex-shrink: 0;
-}
-
-.context-dock-tab-label {
-  white-space: nowrap;
-}
-
-.context-dock-tab-badge {
-  min-width: 18px;
-  height: 18px;
-  padding: 0 5px;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  border-radius: 9px;
-  background: var(--c-accent);
-  color: var(--c-contrast-fg);
-  font-size: 10px;
-  font-weight: 700;
-  letter-spacing: 0;
-  text-transform: none;
-}
-
 /* Context dock — expanded panel anchored top-right edge.
    Mutually exclusive with the Updates panel (see DockedNode.tsx and
    AttentionHistory.tsx) — opening one collapses the other, so they can both

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

@@ -271,7 +271,9 @@ class LocalCanvasAccess implements CanvasAccess {
   }
 
   async addHtmlNode(input: AddHtmlNodeInput): Promise<string> {
-    return this.canvas.addHtmlNode(input);
+    // PmxCanvas.addHtmlNode returns the created node; the CanvasAccess contract
+    // is a bare id string, so extract it (mirrors addNode above).
+    return this.canvas.addHtmlNode(input).id;
   }
 
   async addHtmlPrimitive(input: AddHtmlPrimitiveInput): Promise<AddHtmlPrimitiveResult> {
@@ -683,6 +685,7 @@ class RemoteCanvasAccess implements CanvasAccess {
       slideTitles,
       embeddedNodeIds,
       embeddedUrls,
+      axCapabilities,
       ...rest
     } = input as AddHtmlNodeInput & {
       summary?: string;
@@ -692,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',
@@ -704,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 {