pmx-canvas 0.1.30 → 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/canvas-state.d.ts

@@ -199,6 +199,13 @@ declare class CanvasStateManager {
     private emptyPersistedState;
     /** Load canvas state from SQLite (or legacy JSON fallback). Call once on server startup. */
     loadFromDisk(options?: LoadFromDiskOptions): boolean;
+    /**
+     * Whether this workspace's canvas DB already holds saved state. Used to gate
+     * brand-new-workspace seeding (e.g. the default docked status/context widgets)
+     * so we never add nodes to a canvas that already has content. Reflects the
+     * pre-run persisted flag until the next save.
+     */
+    hasPersistedState(): boolean;
     /** Debounced save — coalesces rapid mutations into a single write. */
     private scheduleSave;
     flushToDisk(): void;

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

@@ -20,8 +20,32 @@ 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;
+    /**
+     * Tab/document title. Injected as `<title>` only when the author HTML does not
+     * already declare one, so a standalone "Open as site" tab shows the node title
+     * instead of falling back to the raw URL.
+     */
+    title?: string;
     /** Client nonce that authorizes parent → iframe theme-update messages. */
     themeToken?: string;
     presentation?: boolean;
@@ -32,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

@@ -7,12 +7,22 @@ import type { AxTimelineQuery } from './canvas-db.js';
 import { searchNodes } from './spatial-analysis.js';
 import { diffLayouts } from './mutation-history.js';
 import { fitCanvasView, gcCanvasSnapshots, listCanvasSnapshots } from './canvas-operations.js';
+import { type SerializedCanvasNode } from './canvas-serialization.js';
 import type { HtmlPrimitiveKind } from './html-primitives.js';
 import { type WebArtifactBuildInput, type WebArtifactCanvasBuildResult } from './web-artifacts.js';
 import { type ExternalMcpTransportConfig } from './mcp-app-runtime.js';
 import { type DiagramPresetOpenInput } from './diagram-presets.js';
 import { type GraphNodeInput, type JsonRenderNodeInput, type JsonRenderSpec } from '../json-render/server.js';
 import type { CanvasAutomationWebViewOptions, CanvasAutomationWebViewStatus } from './server.js';
+/**
+ * Node object returned by the SDK's create/get methods. It is the fully
+ * serialized node (adds `surfaceUrl`, `kind`, `title`, `content`, …) plus a
+ * `nodeId` alias for `id`, so the SDK return shape matches the HTTP/CLI
+ * `node`-create responses field-for-field.
+ */
+export type SdkCanvasNode = SerializedCanvasNode & {
+    nodeId: string;
+};
 export declare class PmxCanvas extends EventEmitter {
     private _port;
     private _server;
@@ -54,7 +64,7 @@ export declare class PmxCanvas extends EventEmitter {
         width?: number;
         height?: number;
         strictSize?: boolean;
-    }): CanvasNodeState;
+    }): SdkCanvasNode;
     addWebpageNode(input: {
         title?: string;
         url: string;
@@ -262,7 +272,7 @@ export declare class PmxCanvas extends EventEmitter {
         nodeIds?: string[];
     }): ReturnType<typeof fitCanvasView>;
     getLayout(): CanvasLayout;
-    getNode(id: string): CanvasNodeState | undefined;
+    getNode(id: string): SdkCanvasNode | undefined;
     search(query: string): ReturnType<typeof searchNodes>;
     getSpatialContext(): import("./spatial-analysis.js").SpatialContext;
     undo(): Promise<{
@@ -435,7 +445,13 @@ export declare class PmxCanvas extends EventEmitter {
         width?: number;
         height?: number;
         strictSize?: boolean;
-    }): string;
+        /** 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;
         title?: string;

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

@@ -83,6 +83,18 @@ export declare function hasWorkbenchSubscribers(): boolean;
 export declare function setPrimaryWorkbenchCanvasPromptHandler(handler: PrimaryWorkbenchCanvasPromptHandler | null): void;
 export declare function buildMacBrowserOpenScript(appName: string, url: string): string;
 export declare function openUrlInExternalBrowser(url: string): boolean;
+/**
+ * Seed the docked status (left) + context (right) widgets so a freshly opened
+ * canvas shows them by default — the same nodes the agent-event path creates on
+ * demand (`status-main`, `context-main`), just present from the start.
+ *
+ * First-run only: we bail if the workspace canvas already has persisted state,
+ * so we never add them to a board with content, and — because first-run state is
+ * persisted on save — deleting or undocking them later is respected (they are
+ * not re-seeded). Create-if-missing keeps it idempotent if the agent path
+ * already made one. Returns true if anything was seeded.
+ */
+export declare function ensureDefaultDockedNodes(): boolean;
 export declare function emitPrimaryWorkbenchEvent(event: string, payload?: PrimaryWorkbenchEventPayload): void;
 export declare function consumePrimaryWorkbenchIntents(limit?: number): PrimaryWorkbenchIntent[];
 export declare function getPrimaryWorkbenchUrl(workspaceRoot?: string): string | null;

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' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.30",
+  "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/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/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/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,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();