pmx-canvas 0.1.31 → 0.1.32

package/dist/types/client/nodes/surface-url.d.ts

@@ -20,3 +20,10 @@ export declare function nodeSurfaceUrl(nodeId: string, opts?: SurfaceUrlOptions)
 export declare function canOpenAsSite(node: CanvasNodeState): boolean;
 /** Open the node's surface in a new browser tab. */
 export declare function openNodeAsSite(node: CanvasNodeState): void;
+/**
+ * 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 declare function openNodeInSystemBrowser(node: CanvasNodeState): Promise<void>;

package/dist/types/client/state/canvas-store.d.ts

@@ -9,6 +9,7 @@ export declare const sessionId: import("@preact/signals-core").Signal<string>;
 export declare const traceEnabled: import("@preact/signals-core").Signal<boolean>;
 export declare const canvasTheme: import("@preact/signals-core").Signal<string>;
 export declare const hasInitialServerLayout: import("@preact/signals-core").Signal<boolean>;
+export declare const axSurfaceState: import("@preact/signals-core").Signal<unknown>;
 export declare const expandedNodeId: import("@preact/signals-core").Signal<string | null>;
 export declare const pendingExpandedNodeCloseId: import("@preact/signals-core").Signal<string | null>;
 export declare const pendingConnection: import("@preact/signals-core").Signal<{

package/dist/types/client/state/intent-bridge.d.ts

@@ -126,6 +126,13 @@ export interface AxInteractionResponse {
     code?: string;
     error?: string;
 }
+/** Fetch the compact AX state snapshot pushed into AX-enabled surfaces. */
+export declare function fetchAxSurfaceState(): Promise<unknown>;
+/** Ask the server to open a node's surface in the system browser. */
+export declare function openNodeInSystemBrowserRequest(nodeId: string): Promise<{
+    ok: boolean;
+    opened: boolean;
+}>;
 /** Submit a capability-gated AX interaction from a native node control. */
 export declare function submitAxInteractionFromClient(input: AxInteractionRequest): Promise<AxInteractionResponse>;
 /** Commit the current viewport to the authoritative server state. */

package/dist/types/json-render/renderer/index.d.ts

@@ -16,5 +16,6 @@ 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;
     }
 }

package/dist/types/json-render/server.d.ts

@@ -92,4 +92,5 @@ export declare function buildJsonRenderViewerHtml(options: {
     devtools?: boolean;
     nodeId?: string;
     axToken?: string;
+    axState?: unknown;
 }): Promise<string>;

package/dist/types/server/ax-context.d.ts

@@ -1,3 +1,26 @@
-import { type PmxAxContext, type PmxAxPinnedContext } from './ax-state.js';
+import { type PmxAxContext, type PmxAxPinnedContext, type PmxAxWorkItem, type PmxAxApprovalGate, type PmxAxReviewAnnotation, type PmxAxElicitation, type PmxAxModeRequest, type PmxAxPolicy } from './ax-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[];
+    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 declare function buildCanvasAxSurfaceSnapshot(): PmxAxSurfaceSnapshot;
 export declare function buildCanvasAxPinnedContext(): PmxAxPinnedContext;
 export declare function buildCanvasAxContext(): PmxAxContext;

package/dist/types/server/html-surface.d.ts

@@ -20,6 +20,24 @@ export declare const SURFACE_THEME_STYLESHEET = "/canvas/surface-theme.css";
 /** CSP sandbox tokens for an `html`/`html-primitive` surface — scripts only, opaque origin. */
 export declare const HTML_SURFACE_SANDBOX = "allow-scripts";
 export declare function normalizeSurfaceTheme(value: string | null | undefined): SurfaceTheme;
+/**
+ * Bridge that exposes `window.PMX_AX.emit(type, payload)` to author HTML. Calls
+ * post a nonce-tagged message to the parent canvas, which validates the nonce +
+ * node id and submits the interaction through the capability-gated endpoint. Only
+ * injected when the node's AX capabilities are enabled (opt-in for `html`), and
+ * the server re-validates every interaction — so this is a convenience surface,
+ * not a trust boundary.
+ */
+export declare function buildAxBridge(axToken: string, nodeId: string): string;
+/**
+ * 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 declare function buildAxStateBridge(axToken: string, snapshotJson: string): string;
 export interface HtmlSurfaceOptions {
     theme: SurfaceTheme;
     /**
@@ -38,6 +56,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;
 }
 /**
  * Wrap author HTML into a complete, themed standalone document. Accepts either a

package/dist/types/server/index.d.ts

@@ -445,6 +445,12 @@ export declare 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;
     addHtmlPrimitive(input: {
         kind: HtmlPrimitiveKind;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.31",
+  "version": "0.1.32",
   "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",

package/skills/pmx-canvas/SKILL.md

@@ -770,7 +770,11 @@ server's `ui://` resource as an iframe node on the canvas
 
 Any renderable surface node can be opened full-page in its own browser tab — the same
 document it shows in the canvas, just without the node chrome. In the workbench, use the
-↗ **Open as site** button in the node title bar (or the expanded overlay).
+↗ **Open as site** button (new tab) or the ⤤ **Open in system browser** button in the
+node title bar (or the expanded overlay). "Open in system browser" launches the real OS
+browser via `POST /api/canvas/open-external` `{ nodeId }` (it opens only this server's own
+surface URL; falls back to a normal new tab when the server can't launch) — use it when
+the host's embedded browser (e.g. Codex) opens `_blank` tabs in-place.
 
 - Works for `html` / `html-primitive`, bundled `web-artifact`, `json-render` / `graph`,
   `webpage`, and hosted ext-app `mcp-app` nodes.
@@ -879,6 +883,97 @@ elicitation, or mode request. One envelope, many transports:
 Interactions request PMX-AX primitives only — never arbitrary shell, tool, MCP,
 or host execution.
 
+#### Where AX can be used — node capability matrix
+
+AX interactions are gated per node type. The lists below are each type's **ceiling**
+— `data.axCapabilities.allowed` can NARROW it, never escalate beyond it.
+
+**Enabled by default** (no opt-in needed — an agent/native control can emit straight away):
+
+| Node type | Allowed AX interaction types |
+|-----------|------------------------------|
+| `markdown` | `ax.steer`, `ax.work.create`, `ax.evidence.add`, `ax.command.invoke`, `ax.event.record` |
+| `context` | `ax.focus.set`, `ax.steer`, `ax.evidence.add`, `ax.command.invoke`, `ax.event.record` |
+| `status` | `ax.work.create`, `ax.work.update`, `ax.approval.request`, `ax.mode.request`, `ax.event.record` |
+| `file` | `ax.evidence.add`, `ax.review.add`, `ax.focus.set`, `ax.event.record` |
+| `json-render` | `ax.work.create`, `ax.work.update`, `ax.evidence.add`, `ax.elicitation.request`, `ax.event.record` |
+| `graph` | `ax.evidence.add`, `ax.focus.set`, `ax.event.record` |
+| `ledger` | `ax.evidence.add`, `ax.event.record` |
+| `trace` | `ax.evidence.add`, `ax.event.record` |
+| `image` | `ax.evidence.add`, `ax.review.add` |
+| `webpage` | `ax.evidence.add`, `ax.review.add`, `ax.focus.set`, `ax.event.record` |
+| `group` | `ax.focus.set`, `ax.work.create`, `ax.command.invoke`, `ax.event.record` |
+
+**Opt-in** — set `data.axCapabilities.enabled = true` (MCP: pass `axCapabilities` to
+`canvas_add_html_node` or `canvas_update_node`; HTTP: nest under `data`):
+
+| Node type | Allowed AX interaction types |
+|-----------|------------------------------|
+| `html` / `html-primitive` | the full set: `ax.work.create`, `ax.work.update`, `ax.steer`, `ax.approval.request`, `ax.review.add`, `ax.evidence.add`, `ax.focus.set`, `ax.elicitation.request`, `ax.mode.request`, `ax.command.invoke`, `ax.event.record` |
+| `mcp-app` (incl. **web-artifact**) | `ax.event.record`, `ax.evidence.add`, `ax.work.create`, `ax.work.update`, `ax.focus.set`, `ax.elicitation.request` |
+
+**Never (anchor-only):** internal `prompt` / `response` thread nodes — `ax.event.record`
+only, no human-facing emit.
+
+The 11 interaction types and what they create: `ax.work.create` / `ax.work.update`
+(work-queue items, status todo→in-progress→blocked→done→cancelled), `ax.evidence.add`
+(timeline evidence), `ax.review.add` (review annotation), `ax.focus.set` (agent focus
+pointer), `ax.steer` (a steering message delivered to the agent), `ax.approval.request`
+(approval gate), `ax.elicitation.request` (structured human input), `ax.mode.request`
+(plan/execute/autonomous transition), `ax.command.invoke` (registry command), and
+`ax.event.record` (diagnostic agent-event).
+
+#### Building an AX surface in the canvas (emit + reflect)
+
+AX surfaces are **composable** — you can build a live work board, review board, or
+inbox as a canvas node that BOTH emits AX interactions AND renders the current AX
+state. The read side mirrors the write side:
+
+- **Opt in** (html/mcp-app are off by default): create with
+  `canvas_add_html_node({ html, axCapabilities: { enabled: true, allowed: ["ax.work.create","ax.work.update"] } })`,
+  or flip an existing node on with
+  `canvas_update_node({ id, axCapabilities: { enabled: true, allowed: [...] } })`.
+  json-render / graph nodes are enabled by default.
+- **Emit (write):** in `html`, call `window.PMX_AX.emit("ax.work.create", { title })`;
+  in `json-render`, bind a control action named after the AX type
+  (`on: { press: { action: "ax.work.create", params: { title } } }`).
+- **Reflect (read):** the canvas seeds the surface with a compact AX snapshot at
+  load (the same shape as `GET /api/canvas/ax/surface-snapshot`) and live-updates it
+  as AX state changes. Works on all three authored surface types:
+  - `html` / `html-primitive`: read `window.PMX_AX.state` (`{ focus, workItems,
+    approvalGates, reviewAnnotations, elicitations, modeRequests, policy }`) and
+    subscribe to the `pmx-ax-update` event:
+    `window.addEventListener("pmx-ax-update", e => render(e.detail))`.
+  - `json-render` / `graph`: the snapshot is bound under `/ax`, so a spec reads
+    `{ "$state": "/ax/workItems" }` and it stays live as work items change.
+  - `web-artifact` (mcp-app): the same `window.PMX_AX.state` + `pmx-ax-update` bridge
+    is injected at the `/artifact` route once the node opts in — author the React app
+    against `window.PMX_AX`, not direct `fetch()` (the artifact iframe is sandboxed
+    opaque-origin, so it can't call the API directly).
+
+Minimal html work board (drop-in via `canvas_add_html_node`, `axCapabilities.enabled: true`):
+
+```html
+<button onclick="window.PMX_AX.emit('ax.work.create',{title:'New task'})">+ Task</button>
+<ul id="q"></ul>
+<script>
+  function render(s){ document.getElementById('q').innerHTML =
+    ((s&&s.workItems)||[]).map(w => '<li>['+w.status+'] '+w.title+'</li>').join(''); }
+  render(window.PMX_AX && window.PMX_AX.state);
+  window.addEventListener('pmx-ax-update', e => render(e.detail));
+</script>
+```
+
+This is the right home for a deliberate, interactive AX experience — not the
+native node buttons. Any agent (via MCP/SDK) can also create/update the same work
+items, and the board reflects them live.
+
+> Security note: an AX-enabled surface can READ the whole canvas AX board (all
+> work items, focus, approval gates, etc. — human review comment text is redacted),
+> while its EMITS are clamped to its own node. Under the single-workspace
+> local-trust model this is fine, but don't embed untrusted third-party scripts in
+> an AX-enabled surface.
+
 ### Reading Spatial Intent
 
 The `canvas://spatial-context` resource reveals how the human has organized information:

package/src/cli/agent.ts

@@ -1448,6 +1448,8 @@ cmd('node update', 'Update a node by ID', [
   'pmx-canvas node update <node-id> --spec-file ./dashboard.json',
   'pmx-canvas node update <graph-id> --data-file ./metrics.json --chart-height 420',
   'pmx-canvas node update <node-id> --pinned true',
+  'pmx-canvas node update <node-id> --dock-position right',
+  'pmx-canvas node update <node-id> --dock-position none   # undock back to the canvas',
   'pmx-canvas node update <node-id> --lock-arrange',
 ], async (args) => {
   const { positional, flags } = parseFlags(args);
@@ -1521,10 +1523,25 @@ cmd('node update', 'Update a node by ID', [
 
   if (pinned !== undefined) body.pinned = pinned;
 
+  // --dock-position left|right|none : dock a node into the top HUD or undock it.
+  // `none`/`null`/empty map to JS null (undock). Assigned with a !== undefined
+  // guard so the null survives JSON.stringify to the server (which accepts a
+  // top-level dockPosition: null). HTTP PATCH already supports this; this is the
+  // CLI path the report (#40) found missing.
+  const dockRaw = getStringFlag(flags, 'dock-position', 'dockPosition');
+  let dockPosition: 'left' | 'right' | null | undefined;
+  if (dockRaw !== undefined) {
+    const v = dockRaw.trim().toLowerCase();
+    if (v === 'left' || v === 'right') dockPosition = v;
+    else if (v === 'none' || v === 'null' || v === '') dockPosition = null;
+    else die(`Invalid --dock-position "${dockRaw}".`, 'Use left, right, or none (to undock).');
+  }
+  if (dockPosition !== undefined) body.dockPosition = dockPosition;
+
   if (Object.keys(body).length === 0) {
     die(
       'No updates specified',
-      'Use --title, --content, --x, --y, --width, --height, --strict-size, --pinned, trace fields, --lock-arrange, --unlock-arrange, or --stdin',
+      'Use --title, --content, --x, --y, --width, --height, --strict-size, --pinned, --dock-position, trace fields, --lock-arrange, --unlock-arrange, or --stdin',
     );
   }
 

package/src/client/App.tsx

@@ -167,7 +167,7 @@ function Toolbar({
         <ToolbarHint label="Canvas status" detail={hasSynced ? statusLabel : 'Syncing canvas from server'} align="start">
           <span class={`connection-dot ${status}`} aria-label={`Canvas status: ${statusTitle}`} />
         </ToolbarHint>
-        <span style={{ fontSize: '11px', color: 'var(--c-muted)' }}>
+        <span class="hud-collapsible-text" style={{ fontSize: '11px', color: 'var(--c-muted)' }}>
           {sessionId.value ? sessionId.value.slice(0, 12) : '…'}
         </span>
 
@@ -209,7 +209,7 @@ function Toolbar({
             <IconZoomOut />
           </button>
         </ToolbarHint>
-        <span style={{ fontSize: '10px', color: 'var(--c-dim)', minWidth: '36px', textAlign: 'center' }}>
+        <span class="hud-collapsible-text" style={{ fontSize: '10px', color: 'var(--c-dim)', minWidth: '36px', textAlign: 'center' }}>
           {Math.round(v.scale * 100)}%
         </span>
 
@@ -357,7 +357,7 @@ function Toolbar({
           </button>
         </ToolbarHint>
 
-        <span style={{ fontSize: '10px', color: 'var(--c-dim)' }}>{countsLabel}</span>
+        <span class="hud-collapsible-text" style={{ fontSize: '10px', color: 'var(--c-dim)' }}>{countsLabel}</span>
       </div>
     </div>
   );

package/src/client/canvas/CanvasNode.tsx

@@ -25,7 +25,7 @@ import {
   viewport,
 } from '../state/canvas-store';
 import { removeNodeFromClient, updateNodeFromClient } from '../state/intent-bridge';
-import { canOpenAsSite, openNodeAsSite } from '../nodes/surface-url';
+import { canOpenAsSite, openNodeAsSite, openNodeInSystemBrowser } from '../nodes/surface-url';
 import { getNodeIcon } from '../icons';
 import { EXPANDABLE_TYPES, TYPE_LABELS } from '../types';
 import type { CanvasNodeState } from '../types';
@@ -292,6 +292,21 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
               ↗
             </button>
           )}
+          {/* Open in the real system browser (for hosts whose embedded browser
+              makes a normal new tab feel in-place, e.g. Codex). Falls back to a
+              new tab when the server can't launch the OS browser. */}
+          {canOpenAsSite(node) && (
+            <button
+              type="button"
+              onClick={(e) => {
+                e.stopPropagation();
+                void openNodeInSystemBrowser(node);
+              }}
+              title="Open in system browser"
+            >
+              ⤤
+            </button>
+          )}
           {/* Expand — opens node as full-viewport overlay for focused work */}
           {EXPANDABLE_TYPES.has(node.type) && (
             <button

package/src/client/canvas/ExpandedNodeOverlay.tsx

@@ -8,7 +8,7 @@ import { StatusNode } from '../nodes/StatusNode';
 import { ImageNode } from '../nodes/ImageNode';
 import { WebpageNode } from '../nodes/WebpageNode';
 import { HtmlNode, shouldShowPresentationControls } from '../nodes/HtmlNode';
-import { canOpenAsSite, openNodeAsSite } from '../nodes/surface-url';
+import { canOpenAsSite, openNodeAsSite, openNodeInSystemBrowser } from '../nodes/surface-url';
 import { PromptNode } from '../nodes/PromptNode';
 import { ResponseNode } from '../nodes/ResponseNode';
 import { TraceNode } from '../nodes/TraceNode';
@@ -315,6 +315,17 @@ export function ExpandedNodeOverlay() {
               </button>
             )}
 
+            {canOpenAsSite(node) && (
+              <button
+                type="button"
+                class="expanded-action-btn"
+                onClick={() => void openNodeInSystemBrowser(node)}
+                title="Open in the system browser (e.g. Chrome) — useful when the host browser opens tabs in-place"
+              >
+                Open in system browser
+              </button>
+            )}
+
             {canPresent && (
               <button
                 type="button"

package/src/client/nodes/ContextNode.tsx

@@ -178,7 +178,7 @@ export function ContextNode({
         <button
           type="button"
           class="ax-node-action"
-          title="Set AX focus to this node"
+          title="Point the agent at this node — sets it as the agent's current AX focus so the agent pulls it into context to work on next (a one-click alternative to manually pinning)."
           style={axNodeActionButtonStyle}
           onClick={(e) => {
             e.stopPropagation();

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>(