pmx-canvas 0.1.28 → 0.1.30

package/docs/sdk.md

@@ -106,6 +106,26 @@ canvas.addReviewAnnotation({ body: 'off-by-one', kind: 'finding', severity: 'err
 // Host/session capability (own table, survives clear)
 canvas.reportHostCapability({ host: 'copilot', canvas: true, sessionMessaging: true }, { source: 'sdk' });
 console.log(canvas.getHostCapability());
+
+// Node interactions — one capability-gated envelope; the server re-validates and
+// clamps sandboxed surfaces (html-node/mcp-app/json-render) to their own node.
+canvas.submitAxInteraction({ type: 'ax.work.create', sourceNodeId: n1, payload: { title: 'Wire auth' } });
+
+// Delivery — claim pending steering for a consumer (loop-safe), then acknowledge
+const pending = canvas.getPendingSteering({ consumer: 'copilot', limit: 20 });
+if (pending[0]) canvas.markSteeringDelivered(pending[0].id, { consumer: 'copilot' });
+
+// Elicitation + mode requests (canvas-bound, snapshotted)
+const elic = canvas.requestElicitation({ prompt: 'Who owns this?', fields: ['owner'] }, { source: 'sdk' });
+canvas.respondElicitation(elic.id, { owner: 'alice' });
+const mode = canvas.requestMode({ mode: 'execute', reason: 'plan approved' }, { source: 'sdk' });
+canvas.resolveModeRequest(mode.id, 'approved');
+
+// Command registry + tool/prompt policy
+console.log(canvas.getCommandRegistry());
+canvas.invokeCommand('pmx.plan', { note: 'draft a plan' }, { source: 'sdk' });
+canvas.setPolicy({ tools: { excluded: ['shell'] }, prompt: { mode: 'concise' } }, { source: 'sdk' });
+console.log(canvas.getPolicy());
 ```
 
 ## WebView automation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "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",
@@ -32,7 +32,7 @@
     "dev:demo": "bun run src/cli/index.ts --demo",
     "dev:portless": "portless run --name pmx --app-port 4313 bun run src/cli/index.ts --no-open --port=4313",
     "dev:portless:demo": "portless run --name pmx --app-port 4313 bun run src/cli/index.ts --no-open --port=4313 --demo",
-    "build:client": "bun build src/client/index.tsx --outdir dist/canvas --minify && cp src/client/theme/global.css dist/canvas/global.css",
+    "build:client": "bun build src/client/index.tsx --outdir dist/canvas --minify && cp src/client/theme/global.css dist/canvas/global.css && cp src/client/theme/surface-theme.css dist/canvas/surface-theme.css",
     "build:json-render": "bash scripts/build-json-render.sh",
     "build:types": "tsc -p tsconfig.types.json",
     "build": "bun run build:client && bun run build:json-render && bun run build:types",

package/skills/pmx-canvas/SKILL.md

@@ -75,14 +75,19 @@ reference before using adapter-native features:
 - `references/codex-app-adapter.md` — Codex app native Browser + MCP adapter, AX context reading,
   focus labeling, and live-test checklist.
 
-Host-aware visibility rule:
-- If a native PMX Canvas adapter/panel is available and already represents the workbench (for example
-  the GitHub Copilot app `pmx-canvas` canvas extension, or Codex's in-app Browser opened to
-  `/workbench`), use that panel. Do **not** also open a separate browser panel to the same workbench;
-  it wastes space and confuses which surface is authoritative.
-- If no native adapter/panel is available (generic MCP client, shell-only agent, raw CLI harness,
-  or another agent harness without canvas support), open the normal PMX Canvas browser workbench first
-  so the human can see mutations as they happen. Use the server URL's `/workbench` route.
+Open the canvas first — always:
+The canvas is the shared human↔agent surface. **Before you create or mutate any nodes, make the
+workbench visible.** Do **not** assume the host opened it for you — some hosts (e.g. the Codex app)
+do not open it on their own. Take the action to open it yourself, whatever the host:
+- **Native adapter/panel available** (the GitHub Copilot app `pmx-canvas` canvas extension, or the
+  Codex in-app Browser): open/focus that panel to the server's `/workbench` route.
+- **Any other browser** (Chrome, Safari, Arc, Edge, …) **or a generic/CLI agent** with no native
+  panel: open the server's `/workbench` URL in a browser.
+
+Then reuse that **single** surface for the rest of the session — do **not** open a second panel to
+the same workbench (it wastes space and confuses which surface is authoritative). If you genuinely
+cannot open any browser (headless/CI), say so and proceed, but still print the `/workbench` URL so a
+human can open it.
 - External URLs in `mcp-app` nodes show the "Unverified domain" interstitial by design. Only
   same-origin `/api/canvas/frame-documents/<id>` URLs are auto-trusted. For external tools, use a
   bundled `web-artifact`, same-origin frame document, or set `data.trustedDomain: true` only when the
@@ -213,6 +218,9 @@ pmx-canvas spatial
   `ax review add|list` — canvas-bound AX state (work items, approval gates,
   review annotations) that rides snapshots and restore and is cleared by `clear`.
 - `ax host report|status` — report/read the host/session capability (own partition).
+- `ax command list|invoke`, `ax policy get|set` — list/invoke registry commands
+  (`pmx.plan`, `pmx.execute`, `pmx.promote-context`, `pmx.summarize`, `pmx.review`)
+  and read/patch the canvas-bound tool/prompt policy.
 - `copilot install-extension [--dry-run] [--yes]` — install the bundled GitHub
   Copilot adapter into a repo; the core stays host-agnostic.
 - `fit [id ...]` — set the server viewport to fit the whole canvas or selected nodes before screenshots or whole-board review
@@ -290,6 +298,24 @@ points from `from` to `to`, indicating sequence or data flow direction.
 pending dependencies, and `dotted` for weak/optional relationships. Use `animated: true` to
 draw visual attention to critical paths.
 
+### Layout: spacing and groups
+
+Agents tend to pack boards too tightly. Give nodes room to breathe — readability beats density.
+
+- **Default spacing:** leave a clear gap between neighbors — roughly half a node's width
+  horizontally and half its height vertically. A 280×180 node reads well with ~360px between
+  column origins and ~260px between row origins.
+- **When nodes are connected by edges, space them further apart** so the edge line, its arrowhead,
+  and its label are clearly visible in the gap between nodes. Crowded nodes hide the flow — this is
+  the most common cause of an unreadable board.
+- **Inside a group, keep the same breathing room** (groups no longer auto-pack children, so the
+  spacing you set is what the human sees). Edges between grouped children especially need the gap.
+- **Size a group frame larger than its children's bounding box** so the group header — including the
+  node-count badge — stays visible and isn't hidden under the top-left child. For an explicit
+  (manual) group frame, add margin on every side (≈56px) plus room at the top for the header rather
+  than hugging the children. Auto-fit groups (created without an explicit width/height) already
+  reserve this margin.
+
 ### Colors (Semantic)
 
 Use color consistently to convey meaning:
@@ -740,6 +766,28 @@ server's `ui://` resource as an iframe node on the canvas
 - Read `htmlPrimitives` from `canvas_describe_schema` for the data shape and examples before constructing a payload
 - For payload patterns, export loops, and the primitive catalog, read `references/html-primitives.md` before creating dense or editable artifacts
 
+### Open as Site (standalone surfaces)
+
+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).
+
+- Works for `html` / `html-primitive`, bundled `web-artifact`, `json-render` / `graph`,
+  `webpage`, and hosted ext-app `mcp-app` nodes.
+- The tab loads the node's stable surface URL, `/api/canvas/surface/<nodeId>`. The
+  in-canvas iframe loads the **exact same URL**, so there is one render path and no
+  separate "preview" version — what you see in the canvas is what opens. The URL reflects
+  current node state and survives a refresh.
+- Agents can read this URL from any node payload (`canvas_get_node` / `canvas_get_layout`)
+  as `surfaceUrl` — a reliable way to tell a human "open the artifact" without disturbing
+  the canvas.
+- Served HTML stays sandboxed (opaque origin via a `Content-Security-Policy: sandbox`
+  response header), so opening author code top-level cannot reach the canvas origin.
+- ext-app `mcp-app` nodes open their UI, but interactive tool-calls only work inside the
+  canvas (the host bridge has no peer in a bare tab). `webpage` and URL-backed `mcp-app`
+  nodes redirect to their external site.
+- This is additive — opening a site never evicts or replaces canvas nodes.
+
 ### Choosing the Right Visual Tier
 
 When the output is more than markdown, pick the lightest tier that fits:
@@ -761,6 +809,8 @@ Use native `json-render` and `graph` nodes when the output should stay fully ins
 3. Use the repo-local `json-render-*` skills when you need help authoring or refining the spec itself
 4. Use `canvas_build_web_artifact` instead when the result needs a full custom React app rather than a schema-driven UI
 
+Spec elements support an `on` map (`on.press`, `on.change`, …) binding events to actions (`{ action, params }`) — built-in actions (`setState`, `pushState`, …) or, when named after an AX interaction type, a capability-gated AX emit. e.g. a Button with `on: { press: { action: 'ax.work.create', params: { title: '…' } } }` lets a human turn a panel control into a tracked work item; the viewer forwards it to the canvas, which validates and submits it server-side (clamped to the node's own id). See **Node AX Interactions** above.
+
 ## MCP Resources
 
 These resources give you read access to canvas intelligence. Read them to understand
@@ -777,10 +827,58 @@ what the human has set up and what they're focusing on.
 | `canvas://code-graph` | Auto-detected file import dependencies (JS/TS, Python, Go, Rust) |
 | `canvas://ax` | Host-agnostic AX state: focus, work items, approval gates, review annotations, host capability |
 | `canvas://ax-context` | Agent-ready AX context: pinned context + current focus |
-| `canvas://ax-work` | Canvas-bound AX work: work items, approval gates, review annotations |
+| `canvas://ax-work` | Canvas-bound AX work: work items, approval gates, review annotations, elicitations, mode requests, and tool/prompt policy |
 | `canvas://ax-timeline` | Bounded AX timeline: recent agent events, evidence, and steering messages |
+| `canvas://ax-pending-steering` | Undelivered steering an MCP client can claim, act on, and mark delivered (adapterless delivery) |
+| `canvas://ax-delivery` | Steering delivery state (delivered flag) for diagnostics |
 | `canvas://skills` | Index of bundled agent skills shipped with the install. Each skill is also addressable as `canvas://skills/<name>` (e.g. `canvas://skills/web-artifacts-builder`) and returns the full SKILL.md. Read this resource first to discover companion workflows the canvas is built to support. |
 
+### Node AX Interactions (capability-gated)
+
+Eligible nodes can emit one normalized, validated AX interaction that maps onto an
+AX operation — work item, evidence, approval, review, focus, steering, event,
+elicitation, or mode request. One envelope, many transports:
+
+- **Endpoint:** `POST /api/canvas/ax/interaction` with
+  `{ type, sourceNodeId, payload }` (MCP: `canvas_ax_interaction`; CLI:
+  `pmx-canvas ax interaction`). Returns `{ ok, primitive }` or
+  `{ ok: false, code }` if the node type/metadata disallows the type.
+- **Capabilities:** each node type has a default capability set (a ceiling). A
+  node may opt in or narrow via `data.axCapabilities` (`{ enabled, allowed }`),
+  clamped to the ceiling — a node can never escalate beyond its type's ceiling.
+  `html` / `html-primitive`, `mcp-app`, and internal `prompt` / `response` nodes
+  are **disabled by default** (opt-in).
+- **Transports:** native node controls call the endpoint directly. Sandboxed
+  surfaces emit via a nonce-tagged `postMessage` the parent canvas validates
+  before submitting: `html` / `html-primitive` nodes (when opted in) call
+  `window.PMX_AX.emit(type, payload)`; **json-render / graph** viewers forward a
+  spec action named after an AX type (e.g. `on.press → { action:
+  "ax.work.create", params }`, `sourceSurface: 'json-render'`); opted-in ext-app
+  **`mcp-app`** nodes get the same `window.PMX_AX.emit` injected
+  (`sourceSurface: 'mcp-app'`). The server re-validates capabilities regardless
+  of transport — bridges are convenience, not a trust boundary.
+- **Delivery:** steering can be claimed by adapterless MCP clients via
+  `canvas://ax-pending-steering` / `canvas_claim_ax_delivery` and acknowledged
+  with `canvas_mark_ax_delivery` (loop-safe — a consumer never receives steering
+  it originated).
+- **Elicitation / mode:** request structured human input
+  (`canvas_request_elicitation` → `canvas_respond_elicitation`) or a workflow
+  mode transition (`canvas_request_mode` → `canvas_resolve_mode`); both are
+  canvas-bound and snapshotted.
+- **Commands:** invoke a registry command — `pmx.plan`, `pmx.execute`,
+  `pmx.promote-context`, `pmx.summarize`, `pmx.review` — via
+  `canvas_invoke_command` (HTTP `POST /api/canvas/ax/command`; CLI
+  `pmx-canvas ax command invoke`; envelope `ax.command.invoke`). Unknown names
+  are rejected; an invocation records an `agent-event` of kind `command`.
+- **Policy:** a canvas-bound, snapshotted tool/prompt policy
+  (`tools.allowed|excluded|approvalRequired`, `prompt.systemAppend|mode`) read
+  into `canvas://ax-context`. Patch it with `canvas_set_ax_policy` (HTTP
+  `GET|POST /api/canvas/ax/policy`; CLI `pmx-canvas ax policy get|set`); patches
+  merge and are normalized server-side.
+
+Interactions request PMX-AX primitives only — never arbitrary shell, tool, MCP,
+or host execution.
+
 ### Reading Spatial Intent
 
 The `canvas://spatial-context` resource reveals how the human has organized information:

package/src/cli/agent.ts

@@ -1082,11 +1082,29 @@ const RESOURCE_COMMAND_ALIASES: Record<string, Record<string, string>> = {
     delete: 'remove',
     rm: 'remove',
   },
+  ax: {
+    // Single-subcommand AX groups: the bare verb maps to its only action so
+    // `ax event` / `ax evidence` suggest the full command instead of erroring.
+    event: 'event add',
+    evidence: 'evidence add',
+  },
 };
 const RESOURCE_SUBCOMMAND_HINTS: Record<string, Record<string, string>> = {
   node: {
     pin: 'Use the top-level pin command instead: pmx-canvas pin <node-id>',
   },
+  ax: {
+    // Multi-subcommand AX groups: point at the available actions.
+    host: 'Pick an action: pmx-canvas ax host report | pmx-canvas ax host status',
+    work: 'Pick an action: pmx-canvas ax work add | update | list',
+    approval: 'Pick an action: pmx-canvas ax approval request | resolve | list',
+    review: 'Pick an action: pmx-canvas ax review add | list',
+    delivery: 'Pick an action: pmx-canvas ax delivery list | mark',
+    elicitation: 'Pick an action: pmx-canvas ax elicitation request | respond | list',
+    mode: 'Pick an action: pmx-canvas ax mode request | resolve | list',
+    command: 'Pick an action: pmx-canvas ax command list | invoke',
+    policy: 'Pick an action: pmx-canvas ax policy get | set',
+  },
 };
 
 function cmd(
@@ -1866,6 +1884,178 @@ cmd('ax steer', 'Send a steering message to the active agent session', [
   output(await api('POST', '/api/canvas/ax/steer', { message, source: 'cli' }));
 });
 
+cmd('ax interaction', 'Submit a node-originated AX interaction (capability-gated)', [
+  'pmx-canvas ax interaction --type ax.work.create --node node-1 --payload \'{"title":"Wire auth"}\'',
+  'pmx-canvas ax interaction --type ax.focus.set --node node-2',
+], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax interaction');
+
+  const type = getStringFlag(flags, 'type');
+  if (!type) die('Missing --type', 'pmx-canvas ax interaction --type <ax.*> --node <id> [--payload <json>]');
+  const sourceNodeId = getStringFlag(flags, 'node');
+  if (!sourceNodeId) die('Missing --node', 'pmx-canvas ax interaction --type <ax.*> --node <id>');
+
+  let payload: unknown;
+  const payloadRaw = getStringFlag(flags, 'payload');
+  if (payloadRaw) {
+    try {
+      payload = JSON.parse(payloadRaw);
+    } catch {
+      die('Invalid --payload JSON', 'pmx-canvas ax interaction --payload \'{"title":"..."}\'');
+    }
+  }
+
+  output(await api('POST', '/api/canvas/ax/interaction', {
+    type,
+    sourceNodeId,
+    ...(payload !== undefined ? { payload } : {}),
+    source: 'cli',
+  }));
+});
+
+cmd('ax delivery list', 'List pending AX steering for a consumer (loop-safe)', [
+  'pmx-canvas ax delivery list',
+  'pmx-canvas ax delivery list --consumer copilot --limit 20',
+], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax delivery list');
+  const consumer = getStringFlag(flags, 'consumer');
+  const limit = optionalNumberFlag(flags, 'limit', 'pmx-canvas ax delivery list --limit <n>');
+  const params = new URLSearchParams();
+  if (consumer) params.set('consumer', consumer);
+  if (limit) params.set('limit', String(limit));
+  const qs = params.toString();
+  output(await api('GET', `/api/canvas/ax/delivery/pending${qs ? `?${qs}` : ''}`));
+});
+
+cmd('ax delivery mark', 'Mark an AX steering message as delivered', [
+  'pmx-canvas ax delivery mark <steering-id>',
+], async (args) => {
+  const { positional, flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax delivery mark');
+  const id = getStringFlag(flags, 'id') ?? positional[0];
+  if (!id) die('Missing steering id', 'pmx-canvas ax delivery mark <steering-id>');
+  output(await api('POST', `/api/canvas/ax/delivery/${encodeURIComponent(id)}/mark`, {}));
+});
+
+cmd('ax elicitation request', 'Request structured human input', [
+  'pmx-canvas ax elicitation request --prompt "Who owns this migration?"',
+  'pmx-canvas ax elicitation request --prompt "Pick a region" --fields region,owner',
+], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax elicitation request');
+  const prompt = requireFlag(flags, 'prompt', 'pmx-canvas ax elicitation request --prompt <text>');
+  const fields = getStringFlag(flags, 'fields');
+  output(await api('POST', '/api/canvas/ax/elicitation', {
+    prompt,
+    ...(fields ? { fields: fields.split(',').map((f) => f.trim()).filter(Boolean) } : {}),
+    source: 'cli',
+  }));
+});
+
+cmd('ax elicitation respond', 'Answer a pending elicitation', [
+  'pmx-canvas ax elicitation respond <id> --response \'{"owner":"alice"}\'',
+], async (args) => {
+  const { positional, flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax elicitation respond');
+  const id = getStringFlag(flags, 'id') ?? positional[0];
+  if (!id) die('Missing elicitation id', 'pmx-canvas ax elicitation respond <id> --response <json>');
+  let response: unknown = {};
+  const raw = getStringFlag(flags, 'response');
+  if (raw) {
+    try { response = JSON.parse(raw); } catch { die('Invalid --response JSON', '--response \'{"k":"v"}\''); }
+  }
+  output(await api('POST', `/api/canvas/ax/elicitation/${encodeURIComponent(id)}/respond`, { response, source: 'cli' }));
+});
+
+cmd('ax elicitation list', 'List elicitations', ['pmx-canvas ax elicitation list'], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax elicitation list');
+  output(await api('GET', '/api/canvas/ax/elicitation'));
+});
+
+cmd('ax mode request', 'Request a workflow mode transition (plan/execute/autonomous)', [
+  'pmx-canvas ax mode request --mode execute --reason "plan approved"',
+], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax mode request');
+  const mode = requireFlag(flags, 'mode', 'pmx-canvas ax mode request --mode plan|execute|autonomous');
+  const reason = getStringFlag(flags, 'reason');
+  output(await api('POST', '/api/canvas/ax/mode', { mode, ...(reason ? { reason } : {}), source: 'cli' }));
+});
+
+cmd('ax mode resolve', 'Resolve a pending mode request', [
+  'pmx-canvas ax mode resolve <id> --decision approved',
+], async (args) => {
+  const { positional, flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax mode resolve');
+  const id = getStringFlag(flags, 'id') ?? positional[0];
+  if (!id) die('Missing mode request id', 'pmx-canvas ax mode resolve <id> --decision approved|rejected');
+  const decision = getStringFlag(flags, 'decision');
+  if (decision !== 'approved' && decision !== 'rejected') die('Invalid --decision', '--decision approved|rejected');
+  const resolution = getStringFlag(flags, 'resolution');
+  output(await api('POST', `/api/canvas/ax/mode/${encodeURIComponent(id)}/resolve`, {
+    decision,
+    ...(resolution ? { resolution } : {}),
+    source: 'cli',
+  }));
+});
+
+cmd('ax mode list', 'List mode requests', ['pmx-canvas ax mode list'], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax mode list');
+  output(await api('GET', '/api/canvas/ax/mode'));
+});
+
+cmd('ax command list', 'List the PMX command registry', ['pmx-canvas ax command list'], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax command list');
+  output(await api('GET', '/api/canvas/ax/command'));
+});
+
+cmd('ax command invoke', 'Invoke a registry-gated PMX command intent', [
+  'pmx-canvas ax command invoke pmx.plan',
+  'pmx-canvas ax command invoke pmx.promote-context --args \'{"nodeIds":["n1"]}\'',
+], async (args) => {
+  const { positional, flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax command invoke');
+  const name = getStringFlag(flags, 'name') ?? positional[0];
+  if (!name) die('Missing command name', 'pmx-canvas ax command invoke <name>');
+  let cmdArgs: unknown;
+  const raw = getStringFlag(flags, 'args');
+  if (raw) {
+    try { cmdArgs = JSON.parse(raw); } catch { die('Invalid --args JSON', '--args \'{"k":"v"}\''); }
+  }
+  output(await api('POST', '/api/canvas/ax/command', { name, ...(cmdArgs !== undefined ? { args: cmdArgs } : {}), source: 'cli' }));
+});
+
+cmd('ax policy get', 'Show the current declarative AX policy', ['pmx-canvas ax policy get'], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax policy get');
+  output(await api('GET', '/api/canvas/ax/policy'));
+});
+
+cmd('ax policy set', 'Set the declarative AX policy (stored by PMX, enforced by adapters)', [
+  'pmx-canvas ax policy set --excluded-tools shell,write --mode concise',
+], async (args) => {
+  const { flags } = parseFlags(args);
+  if (flags.help || flags.h) return showCommandHelp('ax policy set');
+  const csv = (v?: string) => (v ? v.split(',').map((s) => s.trim()).filter(Boolean) : undefined);
+  const allowed = csv(getStringFlag(flags, 'allowed-tools'));
+  const excluded = csv(getStringFlag(flags, 'excluded-tools'));
+  const approvalRequired = csv(getStringFlag(flags, 'approval-tools'));
+  const mode = getStringFlag(flags, 'mode');
+  const systemAppend = getStringFlag(flags, 'system-append');
+  const tools = (allowed || excluded || approvalRequired)
+    ? { ...(allowed ? { allowed } : {}), ...(excluded ? { excluded } : {}), ...(approvalRequired ? { approvalRequired } : {}) }
+    : undefined;
+  const prompt = (mode || systemAppend)
+    ? { ...(mode ? { mode } : {}), ...(systemAppend ? { systemAppend } : {}) }
+    : undefined;
+  output(await api('POST', '/api/canvas/ax/policy', { ...(tools ? { tools } : {}), ...(prompt ? { prompt } : {}), source: 'cli' }));
+});
+
 cmd('ax timeline', 'Read the bounded AX timeline (events, evidence, steering)', [
   'pmx-canvas ax timeline',
   'pmx-canvas ax timeline --limit 100',

package/src/client/canvas/CanvasNode.tsx

@@ -25,6 +25,7 @@ import {
   viewport,
 } from '../state/canvas-store';
 import { removeNodeFromClient, updateNodeFromClient } from '../state/intent-bridge';
+import { canOpenAsSite, openNodeAsSite } from '../nodes/surface-url';
 import { getNodeIcon } from '../icons';
 import { EXPANDABLE_TYPES, TYPE_LABELS } from '../types';
 import type { CanvasNodeState } from '../types';
@@ -275,15 +276,18 @@ export function CanvasNode({ node, children, onContextMenu }: CanvasNodeProps) {
           >
             {'\u2726'}
           </button>
-          {/* Open externally — only for URL-based MCP app nodes (not ext-apps which need a host bridge) */}
-          {(node.type === 'mcp-app' || node.type === 'webpage') && node.data.url && !node.data.mode && (
+          {/* Open as site — full-page standalone view of this node's surface,
+              served from /api/canvas/surface/:id (same document as the canvas
+              iframe). Covers html, web-artifact/ext-app/url mcp-apps,
+              json-render/graph, and webpage nodes. */}
+          {canOpenAsSite(node) && (
             <button
               type="button"
               onClick={(e) => {
                 e.stopPropagation();
-                window.open(node.data.url as string, '_blank', 'noopener');
+                openNodeAsSite(node);
               }}
-              title="Open in new tab"
+              title="Open as site (new tab)"
             >
               ↗
             </button>

package/src/client/canvas/ExpandedNodeOverlay.tsx

@@ -8,6 +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 { PromptNode } from '../nodes/PromptNode';
 import { ResponseNode } from '../nodes/ResponseNode';
 import { TraceNode } from '../nodes/TraceNode';
@@ -303,6 +304,17 @@ export function ExpandedNodeOverlay() {
               </button>
             )}
 
+            {canOpenAsSite(node) && (
+              <button
+                type="button"
+                class="expanded-action-btn"
+                onClick={() => openNodeAsSite(node)}
+                title="Open as a full-page site in a new tab"
+              >
+                Open as site
+              </button>
+            )}
+
             {canPresent && (
               <button
                 type="button"

package/src/client/nodes/ContextNode.tsx

@@ -1,5 +1,6 @@
 import { openWorkbenchFile } from '../state/intent-bridge';
 import { TYPE_LABELS, type CanvasNodeState } from '../types';
+import { axNodeActionButtonStyle, runNodeAxInteraction } from './ax-node-actions';
 
 interface ContextCard {
   key?: string;
@@ -172,6 +173,22 @@ export function ContextNode({
         padding: expanded ? '8px 0' : undefined,
       }}
     >
+      {/* AX: focus the agent on this context node */}
+      <div style={{ display: 'flex', justifyContent: 'flex-end' }}>
+        <button
+          type="button"
+          class="ax-node-action"
+          title="Set AX focus to this node"
+          style={axNodeActionButtonStyle}
+          onClick={(e) => {
+            e.stopPropagation();
+            void runNodeAxInteraction(node, 'ax.focus.set', undefined, 'Focus set');
+          }}
+        >
+          Set focus
+        </button>
+      </div>
+
       {tokenLimit !== null && tokenLimit > 0 && (
         <div style={{ marginBottom: '8px' }}>
           <div

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}