pmx-canvas 0.1.29 → 0.1.31

package/docs/sdk.md

@@ -15,7 +15,9 @@ import { createCanvas } from 'pmx-canvas';
 const canvas = createCanvas({ port: 4313 });
 await canvas.start({ open: true });
 
-// Add nodes — addNode returns the created node (with `.id`, geometry, and data)
+// Add nodes — addNode/getNode/addHtmlNode return the created node: `.id`
+// (plus a `.nodeId` alias), geometry, `.data`, and `.surfaceUrl` for
+// surface-eligible types (html, json-render, graph, …).
 const n1 = canvas.addNode({ type: 'markdown', title: 'Plan', content: '# Step 1\nDo the thing.' });
 const n2 = canvas.addNode({ type: 'status', title: 'Build', content: 'passing' });
 const n3 = canvas.addNode({ type: 'file', content: 'src/index.ts' });
@@ -106,6 +108,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.29",
+  "version": "0.1.31",
   "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

@@ -1099,6 +1099,11 @@ const RESOURCE_SUBCOMMAND_HINTS: Record<string, Record<string, string>> = {
     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',
   },
 };
 
@@ -1879,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/cli/index.ts

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { runAgentCli } from './agent.js';
 import { createCanvas } from '../server/index.js';
 import { seedDemoCanvas } from '../server/demo.js';
+import { ensureDefaultDockedNodes } from '../server/server.js';
 
 const args = process.argv.slice(2);
 
@@ -599,7 +600,13 @@ Examples:
     process.exit(1);
   }
 
-  if (demo && canvas.getLayout().nodes.length === 0) seedDemoCanvas();
+  if (demo && canvas.getLayout().nodes.length === 0) {
+    seedDemoCanvas();
+  } else if (!demo) {
+    // First-run only: dock a status (left) + context (right) widget by default so
+    // a fresh canvas isn't empty. No-op once the workspace has saved state.
+    ensureDefaultDockedNodes();
+  }
 
   console.log(`\n  PMX Canvas running at http://localhost:${canvas.port}`);
   console.log(`  Health: http://localhost:${canvas.port}/health\n`);

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/DockedNode.tsx

@@ -2,7 +2,7 @@ import { ContextNode } from '../nodes/ContextNode';
 import { LedgerNode } from '../nodes/LedgerNode';
 import { StatusNode } from '../nodes/StatusNode';
 import { StatusSummary } from '../nodes/StatusSummary';
-import { attentionHistoryOpen, closeAttentionHistory } from '../state/attention-store';
+import { closeAttentionHistory } from '../state/attention-store';
 import { getContextPinnedNodes, toggleCollapsed, undockNode } from '../state/canvas-store';
 import { TYPE_LABELS } from '../types';
 import type { CanvasNodeState } from '../types';
@@ -40,44 +40,44 @@ function ContextDockedNode({ node }: { node: CanvasNodeState }) {
     toggleCollapsed(node.id);
   };
 
-  // Hide the collapsed Context pill while the Updates side panel is open.
-  // Mutual exclusion guarantees both panels can't be expanded simultaneously,
-  // but the pill itself would otherwise sit beneath/beside the Updates panel
-  // at the same right edge — better to hide until Updates is closed.
-  if (collapsed && attentionHistoryOpen.value) return null;
-
   if (collapsed) {
+    // Collapsed = a menu-height pill in the right of the top HUD row, mirroring
+    // the docked status widget on the left so the bar reads as one continuous menu.
     return (
-      <button
-        type="button"
-        class="context-dock-tab"
-        data-docked-node="true"
-        onClick={expand}
-        aria-label={hasItems ? `Context — ${count} item${count === 1 ? '' : 's'}` : 'Context'}
-        title={hasItems ? `${count} item${count === 1 ? '' : 's'} in agent context` : 'Agent context'}
-      >
-        <svg
-          width="14"
-          height="14"
-          viewBox="0 0 16 16"
-          fill="none"
-          stroke="currentColor"
-          stroke-width="1.5"
-          stroke-linecap="round"
-          stroke-linejoin="round"
-          aria-hidden="true"
-        >
-          <rect x="1.5" y="2.5" width="13" height="11" rx="1.5" />
-          <line x1="1.5" y1="6" x2="14.5" y2="6" />
-          <circle cx="4" cy="4.25" r="0.6" fill="currentColor" stroke="none" />
-        </svg>
-        <span class="context-dock-tab-label">Context</span>
-        {hasItems && (
-          <span class="context-dock-tab-badge" aria-hidden="true">
-            {count > 99 ? '99+' : count}
-          </span>
-        )}
-      </button>
+      <div class="docked-node docked-node--collapsed" data-docked-node="true">
+        <div class="docked-node-header">
+          <span class="node-type-badge">Context</span>
+          {hasItems && (
+            <span class="docked-node-count" aria-hidden="true">
+              {count > 99 ? '99+' : count}
+            </span>
+          )}
+          <div class="docked-node-controls">
+            <button
+              type="button"
+              onClick={(e) => {
+                e.stopPropagation();
+                expand();
+              }}
+              title={hasItems ? `${count} item${count === 1 ? '' : 's'} in agent context — expand` : 'Expand agent context'}
+              aria-label={hasItems ? `Context — ${count} item${count === 1 ? '' : 's'}` : 'Expand agent context'}
+            >
+              {'▸'}
+            </button>
+            <button
+              type="button"
+              onClick={(e) => {
+                e.stopPropagation();
+                undockNode(node.id);
+              }}
+              title="Undock to canvas"
+              aria-label="Undock to canvas"
+            >
+              {'⊙'}
+            </button>
+          </div>
+        </div>
+      </div>
     );
   }
 
@@ -130,7 +130,7 @@ export function DockedNode({ node }: { node: CanvasNodeState }) {
   }
 
   return (
-    <div class="docked-node" data-docked-node="true">
+    <div class={`docked-node${node.collapsed ? ' docked-node--collapsed' : ''}`} data-docked-node="true">
       <div class="docked-node-header">
         <span class="node-type-badge">{TYPE_LABELS[node.type] ?? node.type}</span>
         {node.type === 'status' && node.collapsed && <StatusSummary node={node} />}

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