pmx-canvas 0.1.29 → 0.1.31

package/src/client/nodes/ExtAppFrame.tsx

@@ -1,8 +1,11 @@
 import type { CallToolResult, ListToolsResult, RequestId, Tool } from '@modelcontextprotocol/sdk/types.js';
 import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { AppBridge, PostMessageTransport, buildAllowAttribute } from '@modelcontextprotocol/ext-apps/app-bridge';
-import { useEffect, useRef, useState } from 'preact/hooks';
+import { useEffect, useMemo, useRef, useState } from 'preact/hooks';
 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,
@@ -20,7 +23,6 @@ type McpUiTheme = 'light' | 'dark';
 
 type ExtAppBridgeNotifications = Pick<AppBridge, 'sendToolInput' | 'sendToolResult'>;
 type DisplayMode = 'inline' | 'fullscreen' | 'pip';
-const DEFAULT_EXT_APP_SANDBOX = 'allow-scripts allow-popups allow-popups-to-escape-sandbox';
 
 interface ExtAppHostDimensionsTarget {
   clientWidth?: number;
@@ -156,7 +158,42 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   const nodeId = node.id;
   const frameKey = getExtAppBridgeInitKey(node, retryKey);
   const iframeSandbox = resolveExtAppSandbox(null);
-  const iframeDocument = useIframeDocument(html ?? '', iframeSandbox);
+  // Phase 6 — opt-in ext-app AX bridge. When the node sets data.axCapabilities.enabled,
+  // inject window.PMX_AX into the app HTML and accept emits below (server re-validates).
+  const axCaps = node.data.axCapabilities as { enabled?: boolean } | undefined;
+  const axEnabled = axCaps?.enabled === true && typeof html === 'string' && html.length > 0;
+  const axToken = useMemo(() => `ax-${crypto.randomUUID()}`, []);
+  const axBridgeScript = axEnabled
+    ? `<script data-pmx-canvas-ax-bridge>window.PMX_AX={emit:function(t,p){window.parent.postMessage({source:'pmx-canvas-ax',token:${JSON.stringify(axToken)},nodeId:${JSON.stringify(nodeId)},interaction:{type:String(t),payload:p&&typeof p==='object'?p:{}}},'*');}};</script>`
+    : '';
+  const iframeDocument = useIframeDocument((html ?? '') + axBridgeScript, iframeSandbox);
+
+  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;
+        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;
+      void submitAxInteractionFromClient({
+        type: interaction.type,
+        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', interaction.type as string, [nodeId]);
+        else showToast('remove', 'AX interaction rejected', res.error ?? res.code ?? '', [nodeId]);
+      });
+    }
+    window.addEventListener('message', onAxMessage);
+    return () => window.removeEventListener('message', onAxMessage);
+  }, [axEnabled, axToken, nodeId]);
   const toMcpTheme = (theme: string): McpUiTheme => (theme === 'light' ? 'light' : 'dark');
   const isExpanded = expanded || expandedNodeId.value === nodeId;
 

package/src/client/nodes/FileNode.tsx

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useState } from 'preact/hooks';
 import { updateNodeData } from '../state/canvas-store';
 import { fetchFile, updateNodeFromClient } from '../state/intent-bridge';
 import type { CanvasNodeState } from '../types';
+import { runNodeAxInteraction } from './ax-node-actions';
 
 /** Guess a language label from a file extension for display. */
 function langFromPath(path: string): string {
@@ -170,6 +171,31 @@ export function FileNode({
             {new Date(updatedAt).toLocaleTimeString()}
           </span>
         )}
+        <button
+          type="button"
+          class="ax-node-action"
+          title="Mark this file as AX evidence"
+          onClick={(e) => {
+            e.stopPropagation();
+            void runNodeAxInteraction(
+              node,
+              'ax.evidence.add',
+              { kind: 'file', title: filePath.split('/').pop() || filePath, ref: filePath },
+              'Marked as evidence',
+            );
+          }}
+          style={{
+            background: 'none',
+            border: 'none',
+            color: 'var(--c-muted)',
+            cursor: 'pointer',
+            padding: '2px 4px',
+            fontSize: '12px',
+            flexShrink: 0,
+          }}
+        >
+          ⊕
+        </button>
         <button
           type="button"
           onClick={handleReload}

package/src/client/nodes/HtmlNode.tsx

@@ -1,181 +1,9 @@
 import { useEffect, useMemo, useRef } from 'preact/hooks';
 import { canvasTheme } from '../state/canvas-store';
-import { getCanvasTokens } from '../theme/tokens';
+import { submitAxInteractionFromClient } from '../state/intent-bridge';
+import { showToast } from '../state/attention-bridge';
 import type { CanvasNodeState } from '../types';
-import { useIframeDocument } from './iframe-document-url';
-
-/**
- * Strip characters that could break out of a CSS custom-property value context
- * before interpolating into a `<style>` block. The expected token shape is a
- * CSS color (`#abc`, `rgb(...)`) or font-family list, neither of which needs
- * `<`, `>`, `{`, `}`, `;`, or backticks. Defense-in-depth against a future
- * scenario where theme tokens become runtime-editable.
- */
-function sanitizeCssTokenValue(value: string): string {
-  return value.replace(/[<>{};`\\]/g, '').trim();
-}
-
-/**
- * Build a `<style>` block that exposes canvas theme tokens to the iframe under
- * both the canonical `--c-*` names and common `--color-*` aliases. Also sets
- * sensible body defaults (font, bg, color) so authored HTML inherits the look.
- */
-function buildThemeStyleBlock(): string {
-  const raw = getCanvasTokens();
-  const t = {
-    bg: sanitizeCssTokenValue(raw.bg),
-    panel: sanitizeCssTokenValue(raw.panel),
-    panelSoft: sanitizeCssTokenValue(raw.panelSoft),
-    line: sanitizeCssTokenValue(raw.line),
-    text: sanitizeCssTokenValue(raw.text),
-    textSoft: sanitizeCssTokenValue(raw.textSoft),
-    muted: sanitizeCssTokenValue(raw.muted),
-    dim: sanitizeCssTokenValue(raw.dim),
-    accent: sanitizeCssTokenValue(raw.accent),
-    ok: sanitizeCssTokenValue(raw.ok),
-    warn: sanitizeCssTokenValue(raw.warn),
-    warnAlt: sanitizeCssTokenValue(raw.warnAlt),
-    danger: sanitizeCssTokenValue(raw.danger),
-    purple: sanitizeCssTokenValue(raw.purple),
-    font: sanitizeCssTokenValue(raw.font),
-    mono: sanitizeCssTokenValue(raw.mono),
-  };
-  return `
-    :root {
-      --c-bg: ${t.bg};
-      --c-panel: ${t.panel};
-      --c-panel-soft: ${t.panelSoft};
-      --c-line: ${t.line};
-      --c-text: ${t.text};
-      --c-text-soft: ${t.textSoft};
-      --c-muted: ${t.muted};
-      --c-dim: ${t.dim};
-      --c-accent: ${t.accent};
-      --c-ok: ${t.ok};
-      --c-warn: ${t.warn};
-      --c-warn-alt: ${t.warnAlt};
-      --c-danger: ${t.danger};
-      --c-purple: ${t.purple};
-
-      /* Common aliases authored HTML might use. */
-      --color-bg: ${t.bg};
-      --color-panel: ${t.panel};
-      --color-surface: ${t.panelSoft};
-      --color-border: ${t.line};
-      --color-text: ${t.text};
-      --color-text-primary: ${t.text};
-      --color-text-secondary: ${t.textSoft};
-      --color-text-muted: ${t.muted};
-      --color-text-dim: ${t.dim};
-      --color-accent: ${t.accent};
-      --color-success: ${t.ok};
-      --color-warning: ${t.warn};
-      --color-danger: ${t.danger};
-
-      --font: ${t.font};
-      --font-sans: ${t.font};
-      --font-mono: ${t.mono};
-
-      color-scheme: dark light;
-    }
-    html, body {
-      margin: 0;
-      padding: 0;
-      background: ${t.bg};
-      color: ${t.text};
-      font-family: ${t.font || 'system-ui, sans-serif'};
-      font-size: 14px;
-      line-height: 1.5;
-    }
-    body { padding: 16px; box-sizing: border-box; }
-    a { color: ${t.accent}; }
-  `;
-}
-
-/**
- * Inject the theme style block into the user-supplied HTML. If the document has
- * a `<head>`, inject at the top of head; otherwise wrap the content in a full
- * document. Returns a complete HTML string suitable for `srcdoc`.
- */
-function buildPresentationEscapeBridge(exitToken?: string): string {
-  const token = JSON.stringify(exitToken ?? '');
-  return `<script data-pmx-canvas-presentation-bridge>
-const PMX_CANVAS_PRESENTATION_EXIT_TOKEN = ${token};
-document.addEventListener('keydown', (event) => {
-  if (event.key === 'Escape') {
-    window.parent.postMessage({ source: 'pmx-canvas-html-node', type: 'presentation-exit', token: PMX_CANVAS_PRESENTATION_EXIT_TOKEN }, '*');
-  }
-}, true);
-window.addEventListener('message', (event) => {
-  const message = event.data;
-  if (!message || message.source !== 'pmx-canvas-html-node' || message.type !== 'presentation-key' || message.token !== PMX_CANVAS_PRESENTATION_EXIT_TOKEN) return;
-  if (typeof message.key !== 'string') return;
-  if (typeof window.PMX_CANVAS_PRESENTATION_HANDLE_KEY === 'function') {
-    window.PMX_CANVAS_PRESENTATION_HANDLE_KEY(message.key);
-    return;
-  }
-  document.dispatchEvent(new CustomEvent('pmx-presentation-key', { detail: { key: message.key }, bubbles: true, cancelable: true }));
-  document.dispatchEvent(new KeyboardEvent('keydown', { key: message.key, bubbles: true, cancelable: true }));
-});
-</script>`;
-}
-
-function buildThemeBridge(themeToken: string): string {
-  const token = JSON.stringify(themeToken);
-  return `<script data-pmx-canvas-theme-bridge>
-const PMX_CANVAS_THEME_TOKEN = ${token};
-window.addEventListener('message', (event) => {
-  const message = event.data;
-  if (!message || message.source !== 'pmx-canvas-html-node' || message.type !== 'theme-update' || message.token !== PMX_CANVAS_THEME_TOKEN) return;
-  if (typeof message.css !== 'string' || typeof message.theme !== 'string') return;
-  let style = document.querySelector('style[data-pmx-canvas-theme]');
-  if (!style) {
-    style = document.createElement('style');
-    style.setAttribute('data-pmx-canvas-theme', '');
-    document.head.prepend(style);
-  }
-  style.textContent = message.css;
-  document.documentElement.setAttribute('data-pmx-canvas-theme', message.theme);
-  document.documentElement.setAttribute('data-theme', message.theme);
-});
-</script>`;
-}
-
-function injectIntoHead(html: string, content: string): string {
-  if (/<head[\s>]/i.test(html)) {
-    return html.replace(/<head([^>]*)>/i, `<head$1>${content}`);
-  }
-  if (/<html[\s>]/i.test(html)) {
-    return html.replace(/<html([^>]*)>/i, `<html$1><head>${content}</head>`);
-  }
-  return html;
-}
-
-function buildSrcDoc(userHtml: string, options: { presentation?: boolean; presentationExitToken?: string; themeToken: string; themeCss: string; theme: string }): string {
-  const styleBlock = `<style data-pmx-canvas-theme>${options.themeCss}</style>`;
-  const themeBridge = buildThemeBridge(options.themeToken);
-  const presentationBridge = options.presentation ? buildPresentationEscapeBridge(options.presentationExitToken) : '';
-  const injectedHeadContent = `${styleBlock}${themeBridge}${presentationBridge}`;
-  const presentationAttr = options.presentation ? ' data-pmx-presentation-mode="present"' : '';
-  const trimmed = userHtml.trim();
-  const isFullDoc = /<html[\s>]/i.test(trimmed);
-  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);
-  }
-  // Fragment — wrap in 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>`;
-}
-
-export function createHtmlNodeSrcDocForTest(userHtml: string, options: { theme: string; themeCss: string; themeToken?: string; presentation?: boolean; presentationExitToken?: string }): string {
-  return buildSrcDoc(userHtml, {
-    themeToken: options.themeToken ?? 'test-theme-token',
-    theme: options.theme,
-    themeCss: options.themeCss,
-    presentation: options.presentation,
-    presentationExitToken: options.presentationExitToken,
-  });
-}
+import { nodeSurfaceUrl, surfaceContentHash } from './surface-url';
 
 export function shouldShowPresentationControls(node: CanvasNodeState): boolean {
   return node.type === 'html' && node.data.presentation === true;
@@ -190,16 +18,59 @@ export function HtmlNode({
 }: { node: CanvasNodeState; expanded?: boolean; presentation?: boolean; presentationExitToken?: string; autoFocus?: boolean }) {
   const iframeRef = useRef<HTMLIFrameElement>(null);
   const theme = canvasTheme.value;
-  const themeToken = useMemo(() => `theme-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`, []);
-  const themeCss = useMemo(() => buildThemeStyleBlock(), [theme]);
+  // Stable per-mount nonce that authorizes parent → iframe theme-update messages.
+  const themeToken = useMemo(() => `theme-${crypto.randomUUID()}`, []);
+  // Per-mount nonce authorizing iframe → parent AX emits (Phase 3 HTML bridge).
+  const axToken = useMemo(() => `ax-${crypto.randomUUID()}`, []);
   const html = typeof node.data.html === 'string'
     ? node.data.html
     : typeof node.data.content === 'string'
       ? node.data.content
       : '';
-  const srcDoc = useMemo(() => (html ? buildSrcDoc(html, { presentation, presentationExitToken, themeToken, themeCss, theme }) : ''), [html, presentation, presentationExitToken, themeToken]);
-  const iframeSandbox = 'allow-scripts';
-  const iframeDocument = useIframeDocument(srcDoc, iframeSandbox);
+  const v = useMemo(() => surfaceContentHash(html), [html]);
+
+  // The in-canvas iframe and the "Open as site" tab load the SAME server-rendered
+  // surface URL (/api/canvas/surface/:id) — one render path, no content fork.
+  // `theme` is intentionally excluded from the deps: live theme changes are pushed
+  // via postMessage below (no reload), while `v` reloads the frame when the HTML
+  // itself changes.
+  const surfaceSrc = useMemo(
+    () => (html
+      ? nodeSurfaceUrl(node.id, { theme, themeToken, present: presentation, presentToken: presentationExitToken, v, axToken })
+      : ''),
+    [html, presentation, presentationExitToken, themeToken, v, node.id, axToken],
+  );
+
+  // 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;
+        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;
+      void submitAxInteractionFromClient({
+        type: interaction.type,
+        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', interaction.type as string, [node.id]);
+        else showToast('remove', 'AX interaction rejected', res.error ?? res.code ?? '', [node.id]);
+      });
+    }
+    window.addEventListener('message', onAxMessage);
+    return () => window.removeEventListener('message', onAxMessage);
+  }, [axToken, node.id]);
 
   useEffect(() => {
     iframeRef.current?.contentWindow?.postMessage({
@@ -207,16 +78,15 @@ export function HtmlNode({
       type: 'theme-update',
       token: themeToken,
       theme,
-      css: themeCss,
     }, '*');
     if (autoFocus) iframeRef.current?.focus();
-  }, [theme, themeCss, themeToken]);
+  }, [theme, themeToken]);
 
   useEffect(() => {
     if (!autoFocus) return;
     const id = window.setTimeout(() => iframeRef.current?.focus(), 0);
     return () => window.clearTimeout(id);
-  }, [autoFocus, srcDoc]);
+  }, [autoFocus, surfaceSrc]);
 
   const handleFrameLoad = () => {
     iframeRef.current?.contentWindow?.postMessage({
@@ -224,7 +94,6 @@ export function HtmlNode({
       type: 'theme-update',
       token: themeToken,
       theme,
-      css: themeCss,
     }, '*');
     if (autoFocus) iframeRef.current?.focus();
   };
@@ -241,15 +110,18 @@ export function HtmlNode({
   // `allow-same-origin` (would grant the iframe access to parent localStorage
   // and credentialed requests to the canvas origin), `allow-top-navigation`
   // (would let scripts redirect the parent window), or `allow-forms` (would
-  // let the iframe POST back to the host). The whole html-node tier assumes
-  // arbitrary author code runs inside this exact sandbox.
+  // let the iframe POST back to the host). The surface route reinforces this
+  // with a matching `Content-Security-Policy: sandbox allow-scripts` response
+  // header, so the document stays on an opaque origin even when opened as a
+  // standalone tab. The whole html-node tier assumes arbitrary author code runs
+  // inside this exact sandbox.
   return (
     <iframe
       ref={iframeRef}
       class={presentation ? 'html-node-frame html-node-frame-presentation' : 'html-node-frame'}
       title={typeof node.data.title === 'string' ? node.data.title : 'HTML node'}
-      sandbox={iframeSandbox}
-      {...iframeDocument.attributes}
+      sandbox="allow-scripts"
+      src={surfaceSrc}
       tabIndex={autoFocus ? 0 : undefined}
       onLoad={handleFrameLoad}
       style={{

package/src/client/nodes/McpAppNode.tsx

@@ -1,8 +1,11 @@
+import { useEffect, useMemo, useRef } from 'preact/hooks';
 import type { CanvasNodeState } from '../types';
 import { 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): string {
+function withViewerParams(url: string, expanded: boolean, specVersion?: number, axToken?: string): string {
   if (!url) return url;
   try {
     const resolved = new URL(url, window.location.origin);
@@ -11,6 +14,8 @@ 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).
+    if (axToken) resolved.searchParams.set('axToken', axToken);
     return resolved.toString();
   } catch {
     return url;
@@ -33,9 +38,48 @@ export function McpAppNode({ node, expanded = false }: { node: CanvasNodeState;
   if (node.data.mode === 'ext-app') {
     return <ExtAppFrame node={node} expanded={expanded} />;
   }
+  return <McpAppViewer node={node} expanded={expanded} />;
+}
+
+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';
+  const axToken = useMemo(() => (isAxViewer ? `ax-${crypto.randomUUID()}` : ''), [isAxViewer]);
+
+  // 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;
+        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;
+      void submitAxInteractionFromClient({
+        type: interaction.type,
+        sourceNodeId: node.id,
+        sourceSurface: 'json-render',
+        ...(interaction.payload && typeof interaction.payload === 'object'
+          ? { payload: interaction.payload as Record<string, unknown> }
+          : {}),
+      }).then((res) => {
+        if (res.ok) showToast('context', 'AX interaction', interaction.type as string, [node.id]);
+        else showToast('remove', 'AX interaction rejected', res.error ?? res.code ?? '', [node.id]);
+      });
+    }
+    window.addEventListener('message', onAxMessage);
+    return () => window.removeEventListener('message', onAxMessage);
+  }, [isAxViewer, axToken, node.id]);
 
   const specVersion = typeof node.data.specVersion === 'number' ? node.data.specVersion : undefined;
-  const url = withViewerParams((node.data.url as string) || '', expanded, specVersion);
+  const url = withViewerParams((node.data.url as string) || '', expanded, specVersion, axToken || undefined);
   const sourceServer = (node.data.sourceServer as string) || '';
   const hostMode = (node.data.hostMode as string) || 'hosted';
   const fallbackReason = node.data.fallbackReason as string | undefined;
@@ -96,6 +140,7 @@ export function McpAppNode({ node, expanded = false }: { node: CanvasNodeState;
           the explicit postMessage bridge instead, which is the only path that needs
           app/host RPC and broader capabilities. */}
       <iframe
+        ref={iframeRef}
         src={url}
         class="mcp-app-frame"
         sandbox="allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox"

package/src/client/nodes/StatusNode.tsx

@@ -1,5 +1,6 @@
 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
@@ -94,6 +95,25 @@ 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/ax-node-actions.ts

@@ -0,0 +1,39 @@
+import { submitAxInteractionFromClient } from '../state/intent-bridge';
+import { showToast } from '../state/attention-bridge';
+import type { CanvasNodeState } from '../types';
+
+/**
+ * Submit a native-node AX interaction (plan-004 Phase 2) and surface the outcome
+ * as a transient toast. Inline node controls call this; the server enforces the
+ * node's capabilities, so a denied interaction simply shows an error toast.
+ */
+export async function runNodeAxInteraction(
+  node: CanvasNodeState,
+  type: string,
+  payload: Record<string, unknown> | undefined,
+  successTitle: string,
+): Promise<void> {
+  const res = await submitAxInteractionFromClient({
+    type,
+    sourceNodeId: node.id,
+    sourceSurface: 'native-node',
+    ...(payload ? { payload } : {}),
+  });
+  if (res.ok) {
+    showToast('context', successTitle, '', [node.id]);
+  } else {
+    showToast('remove', 'AX action failed', res.error ?? res.code ?? 'Unknown error', [node.id]);
+  }
+}
+
+/** Shared style for the small inline AX action button on native nodes. */
+export const axNodeActionButtonStyle = {
+  padding: '3px 8px',
+  fontSize: '10px',
+  background: 'var(--c-accent-12)',
+  border: '1px solid var(--c-accent-25)',
+  borderRadius: '4px',
+  color: 'var(--c-text-soft)',
+  cursor: 'pointer',
+  flexShrink: 0,
+} as const;

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

@@ -0,0 +1,48 @@
+import { canvasTheme } from '../state/canvas-store';
+import { canOpenNodeAsSurface } from '../../shared/surface.js';
+import type { CanvasNodeState } from '../types';
+
+/**
+ * Stable content hash (djb2) used to cache-bust the surface iframe `src` when a
+ * node's HTML changes. The server always serves current state, but a same `src`
+ * string won't reload the iframe on its own — bumping `?v=` does.
+ */
+export function surfaceContentHash(input: string): string {
+  let h = 5381;
+  for (let i = 0; i < input.length; i += 1) {
+    h = ((h << 5) + h + input.charCodeAt(i)) | 0;
+  }
+  return (h >>> 0).toString(36);
+}
+
+export interface SurfaceUrlOptions {
+  theme?: string;
+  themeToken?: string;
+  present?: boolean;
+  presentToken?: string;
+  v?: string;
+  /** Nonce authorizing iframe → parent AX emits (html bridge). */
+  axToken?: string;
+}
+
+/** Build the stable per-node surface URL (/api/canvas/surface/:id) the iframe and "Open as site" both use. */
+export function nodeSurfaceUrl(nodeId: string, opts: SurfaceUrlOptions = {}): string {
+  const params = new URLSearchParams();
+  params.set('theme', opts.theme ?? canvasTheme.value);
+  if (opts.themeToken) params.set('themeToken', opts.themeToken);
+  if (opts.present) params.set('present', '1');
+  if (opts.presentToken) params.set('presentToken', opts.presentToken);
+  if (opts.v) params.set('v', opts.v);
+  if (opts.axToken) params.set('axToken', opts.axToken);
+  return `/api/canvas/surface/${encodeURIComponent(nodeId)}?${params.toString()}`;
+}
+
+/** Whether a node can be opened as a standalone site (shared with the server). */
+export function canOpenAsSite(node: CanvasNodeState): boolean {
+  return canOpenNodeAsSurface(node.type, node.data as Record<string, unknown>);
+}
+
+/** Open the node's surface in a new browser tab. */
+export function openNodeAsSite(node: CanvasNodeState): void {
+  window.open(nodeSurfaceUrl(node.id), '_blank', 'noopener');
+}

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

@@ -275,6 +275,11 @@ function enqueueToast(entry: AttentionEntry): void {
   flushToastQueue();
 }
 
+/** Show a transient toast from arbitrary client code (e.g. AX action feedback). */
+export function showToast(tone: AttentionTone, title: string, detail = '', nodeIds: string[] = []): void {
+  enqueueToast(makeEntry(tone, title, detail, nodeIds));
+}
+
 function pulseNodes(nodeIds: string[]): void {
   cancelTimer(pulseTimer);
   pulseTimer = null;

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

@@ -236,6 +236,39 @@ export async function removeNodeFromClient(id: string): Promise<{ ok: boolean; r
   });
 }
 
+// ── PMX-AX node interactions ──────────────────────────────────
+
+export interface AxInteractionRequest {
+  type: string;
+  sourceNodeId: string;
+  payload?: Record<string, unknown>;
+  sourceSurface?: 'native-node' | 'json-render' | 'html-node' | 'mcp-app' | 'adapter';
+}
+
+export interface AxInteractionResponse {
+  ok: boolean;
+  type?: string;
+  sourceNodeId?: string;
+  primitive?: unknown;
+  status?: number;
+  code?: string;
+  error?: string;
+}
+
+/** Submit a capability-gated AX interaction from a native node control. */
+export async function submitAxInteractionFromClient(input: AxInteractionRequest): Promise<AxInteractionResponse> {
+  return requestJson<AxInteractionResponse>(
+    'submitAxInteractionFromClient',
+    '/api/canvas/ax/interaction',
+    { ok: false, code: 'request-failed', error: 'Request failed' },
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ sourceSurface: 'native-node', ...input, source: 'browser' }),
+    },
+  );
+}
+
 /** Commit the current viewport to the authoritative server state. */
 export async function updateViewportFromClient(
   viewport: { x: number; y: number; scale: number },