pmx-canvas 0.4.1 → 0.4.2

package/dist/types/shared/themes.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Canonical canvas theme registry — single source of truth for every layer
+ * that validates, stores, or renders a theme name (client shell, HTML
+ * surfaces, json-render viewer, CLI/env plumbing, persistence).
+ *
+ * Adding a theme: add the name here, author its variable blocks in
+ * src/client/theme/global.css AND src/client/theme/surface-theme.css (guarded
+ * by tests/unit/surface-theme-tokens.test.ts), and give it meta below. The
+ * theme picker, server validation, and surface documents pick it up from this
+ * list.
+ */
+export declare const CANVAS_THEMES: readonly ["dark", "light", "high-contrast", "midnight", "sepia", "arctic", "ember", "forest"];
+export type CanvasThemeName = (typeof CANVAS_THEMES)[number];
+export declare function isCanvasTheme(value: unknown): value is CanvasThemeName;
+export declare function normalizeCanvasThemeName(value: unknown, fallback?: CanvasThemeName): CanvasThemeName;
+export interface CanvasThemeMeta {
+    /** Human label shown in the theme picker. */
+    label: string;
+    /** Whether embedded viewers that only know dark/light should treat it as light. */
+    scheme: 'dark' | 'light';
+    /** Picker swatch colors — MUST match --c-bg / --c-accent in global.css. */
+    swatchBg: string;
+    swatchAccent: string;
+}
+export declare const CANVAS_THEME_META: Record<CanvasThemeName, CanvasThemeMeta>;
+/** Collapse a theme to the dark/light scheme embedded dark|light-only viewers understand. */
+export declare function canvasThemeScheme(value: unknown): 'dark' | 'light';

package/docs/cli.md

@@ -20,7 +20,7 @@ pmx-canvas                            # Start canvas, open browser
 pmx-canvas --demo                     # Start with the saved dashboard demo board
 pmx-canvas --port=8080                # Custom port
 pmx-canvas --no-open                  # Headless (for agents/CI)
-pmx-canvas --theme=light              # dark | light | high-contrast
+pmx-canvas --theme=light              # dark | light | high-contrast | midnight | sepia | arctic | ember | forest
 pmx-canvas --mcp                      # Run as MCP server (stdio)
 pmx-canvas --webview-automation       # Start headless Bun.WebView session
 pmx-canvas open                       # Open the current workbench in a browser

package/docs/environment.md

@@ -25,7 +25,8 @@ optional; defaults are listed.
 
 | Variable | Read by | Effect |
 |---|---|---|
-| `PMX_CANVAS_THEME` | server | Startup theme: `dark` (default), `light`, `high-contrast`. |
+| `PMX_CANVAS_THEME` | server | Startup theme: `dark` (default), `light`, `high-contrast`, `midnight`, `sepia`, `arctic`, `ember`, `forest`. |
+| `AMP_ORB` | server | Set by Amp orb services. When present, the served canvas page tells the browser it is running in an orb, which skips the iframe embed probe and forces `srcdoc` surface rendering when embedded (the orb portal blocks `src`-URL child iframes and the probe is unreliable there). |
 | `PMX_CANVAS_DISABLE_BROWSER_OPEN` | server | `1` suppresses auto-opening the browser (used by tests/CI). |
 | `PMX_CANVAS_DIST` | server | Explicit client bundle directory to serve instead of the packaged `dist/canvas`. |
 | `PMX_CANVAS_WEBVIEW_TIMEOUT_MS` | server | Startup timeout for the Bun.WebView automation session. |

package/docs/http-api.md

@@ -363,6 +363,13 @@ If that iframe never loads, the client switches every same-origin surface
 fetched cross-origin. Force a mode with `/workbench?iframe-mode=srcdoc` (or
 `iframe-mode=src`).
 
+In Amp orbs the probe itself is unreliable (a tiny probe iframe can load even
+though node-sized ones will not), so when the server runs with `AMP_ORB` set
+(orb services always do) it stamps `window.__PMX_AMP_ORB` into the page and
+the embedded client forces `srcdoc` without probing. HTML surface documents
+also inline their theme stylesheet, so srcdoc-rendered surfaces stay styled
+without any subresource load.
+
 `/api/canvas/frame-documents/:id` also answers `HEAD`, which the browser uses
 after every reconnect to detect frame documents lost to a server restart and
 re-mint them automatically (Finding S).

package/docs/plans/plan-009-tech-debt-backlog.md

@@ -66,13 +66,13 @@ The remaining items were re-analyzed with pros/cons and tiered; the maintainer a
 |---|---|
 | Windows web-artifacts | The artifact build pipeline is bash-script-backed (POSIX-only); `tests/unit/web-artifacts.test.ts` self-skips on win32 and docs now state the boundary. Decide: port the build scripts to a cross-platform runner, or keep the documented "build on POSIX, render anywhere" stance. |
 | Composite parity no longer machine-checked | Since v0.3.0 removed the legacy standalones, the byte-identical composite-vs-legacy guarantee has no head-to-head test — regressions in `buildInput`/`formatResult` reuse surface only via output-shape assertions. Accepted at review; revisit if a composite drifts. |
-| Portal-layer ext-app mount (contingency) | If the maintainer sets the WebKit UX bar at "never any visible gap", inline ext-app iframes must render outside the world transform — an architectural change that reopens the parked M3. The 0.4.0 Copilot report keeps Finding N open (residual black after settled recovery; enlarge/close still the reliable unstick) — 0.4.1 ships a cheaper mimic first (post-settle WebKit repaint nudge, `repaint-nudge` trail event). If the next Copilot cycle still fails with the nudge in place, THIS contingency is the next step. |
+| Portal-layer ext-app mount (contingency) | If the maintainer sets the WebKit UX bar at "never any visible gap", inline ext-app iframes must render outside the world transform — an architectural change that reopens the parked M3. 0.4.1 shipped the cheaper mimic (post-settle WebKit repaint nudge, `repaint-nudge` trail event) and the 0.4.1 Copilot report confirms the nudge RUNS but residual black tiles still appear (Diamond on first-load settle, Ellipse after restart settle) — the contingency's trigger condition is now met. This portal-layer mount is the designated next Finding N step; scope it as its own project (drag/zoom sync, z-order, clipping, minimap interplay), not a patch-release bolt-on. |
 
 ## Added post-0.4.0 (2026-08-04 report cycle)
 
 | Item | What's open |
 |---|---|
-| Finding S — frame documents vs server restart | **Done (2026-08-04):** the browser revalidates minted frame-document URLs on every reconnect epoch (`workbenchConnectionEpoch`, HEAD probe) and re-mints against the new process when the store is gone; `/api/canvas/frame-documents/:id` answers HEAD. Confirmed-fix pending the next Copilot/Codex kill-respawn cycle. Server-side persistence of frame docs deliberately NOT done — they are client-derived and re-mintable. |
+| Finding S — frame documents vs server restart | **Done + field-confirmed (0.4.1 reports, both hosts):** the browser revalidates minted frame-document URLs on every reconnect epoch (`workbenchConnectionEpoch`, HEAD probe) and re-mints against the new process when the store is gone; `/api/canvas/frame-documents/:id` answers HEAD. Copilot: IDs fully rotated, all post-restart 200, no frame-not-found tiles. Codex: re-mint without workbench reload. Server-side persistence deliberately NOT done — frames are client-derived and re-mintable. |
 | Amp portal nested-iframe embedding | **Done (2026-08-04):** boot-time embed probe (`/api/canvas/iframe-probe`) + fetch()+srcdoc fallback for all same-origin surfaces (`useSurfaceFrame`, `useIframeDocument` srcdoc short-circuit), `?iframe-mode` override, e2e-forced-mode coverage. External (cross-origin) app URLs cannot be inlined — documented limitation. |
 | Copilot adapter `canvas_snapshot list` descriptor lag | Host-side cached tool schema still requires `name`; fresh `--mcp` is correct. Adapter/packaging issue, not a daemon defect — nothing to change in core; re-verify next cycle. |
 | Registry-migration dead-code sweep | **Done (2026-08-03):** removed the orphaned `describeOp`/`describeGateOp` (composites.ts, dead since the v0.3.0 registration filter) and the `compactNodePayload`/`compactLayoutPayload`/`wantsFullPayload` duplicates in `mcp/server.ts` (live copies are in `ops/nodes.ts`). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Spatial canvas workbench for coding agents \u2014 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

@@ -99,6 +99,10 @@ json-render, a graph, or an HTML primitive is sufficient.
 
 ## Current MCP Composites
 
+The live MCP surface is **22 tools**: the 16 composites below plus 6 standalones (v0.4.x —
+this table is kept in sync with the server's composite registry; `tools/list` on a fresh
+`pmx-canvas --mcp` is always authoritative).
+
 | Composite | Actions |
 |-----------|---------|
 | `canvas_node` | `add`, `get`, `update`, `remove` |
@@ -171,6 +175,12 @@ Use the visible workbench when the human is actively curating layout:
 - Drop files or URLs to create matching nodes.
 - Double-click markdown to edit inline.
 - Use toolbar snapshots before experiments and restore only after confirmation.
+- The toolbar carries view controls (fit, reset, zoom), arrange, minimap, a theme picker (eight
+  themes: dark, light, high-contrast, midnight, sepia, arctic, ember, forest), snapshots, trace,
+  the annotation tools, search (Cmd+K), and shortcuts. On narrow viewports (≤900px — most
+  embedded host panes and mobile) the secondary controls collapse into a single "⋯" More menu at
+  the end of the bar; every action is still there as a labeled row, including the theme list. If
+  an automation script can't find a toolbar button at panel width, open the More menu first.
 
 After changing files under `src/client/`, rebuild with `bun run build` before manual browser
 verification.
@@ -250,9 +260,11 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
   iframe) can block child iframes from loading ANY `src` URL, breaking every iframe-backed node
   with a gray placeholder. The canvas probes this at boot and auto-falls back to fetching
   same-origin surfaces and rendering them inline via `srcdoc` (HTML, graph, json-render, frame
-  documents). External app URLs cannot be inlined (cross-origin) and may stay blocked in such
-  hosts. Force a mode with `/workbench?iframe-mode=srcdoc` (or `iframe-mode=src`) when
-  diagnosing.
+  documents). In Amp orbs specifically, the server sees `AMP_ORB` in its environment and stamps
+  the page so the embedded client skips the (there-unreliable) probe and goes straight to
+  `srcdoc`; HTML surfaces also inline their theme stylesheet so they render styled. External app
+  URLs cannot be inlined (cross-origin) and may stay blocked in such hosts. Force a mode with
+  `/workbench?iframe-mode=srcdoc` (or `iframe-mode=src`) when diagnosing.
 - Graph and json-render standalone surfaces use `display=site` and fill the browser viewport, and
   reflow on a live window resize in a normal browser. Some single-tab host browsers historically
   didn't deliver live-resize events (current Codex builds do — the 0.4.0 retest saw a standalone

package/skills/pmx-canvas/references/full-reference.md

@@ -132,7 +132,7 @@ pmx-canvas --theme=light       # Light theme
 pmx-canvas --version           # Print installed version and exit
 ```
 
-`--theme` accepts `dark` (default), `light`, or `high-contrast`. Same value can be set via
+`--theme` accepts `dark` (default), `light`, `high-contrast`, `midnight`, `sepia`, `arctic`, `ember`, or `forest` (0.4.x; the browser toolbar has a matching theme picker). Same value can be set via
 the `PMX_CANVAS_THEME` environment variable, or toggled live in the browser toolbar.
 
 Start the canvas once per session, then reuse it. Use `--no-open` when running as an agent — the
@@ -420,8 +420,8 @@ When you do set a color (group/graph), use this palette consistently to convey m
 
 ## MCP Tools Reference
 
-PMX Canvas exposes **15 action-discriminated composites** (the whole recommended surface) plus a
-set of first-class standalones. The composites fold the older
+PMX Canvas exposes **16 action-discriminated composites** (the whole recommended surface) plus
+**6 first-class standalones** — 22 tools total (v0.4.x). The composites fold the older
 single-purpose tools behind an `action` (and, for `canvas_ax_gate`, a `kind`) discriminator —
 **field names are unchanged**; only the tool name + the `action`/`kind` selector differ.
 

package/src/cli/index.ts

@@ -5,6 +5,7 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { showServeStatus, startDaemonMode, stopServeDaemon } from './daemon.js';
 import { runAgentCli } from './agent.js';
+import { isCanvasTheme } from '../shared/themes.js';
 import { createCanvas } from '../server/index.js';
 import { seedDemoCanvas } from '../server/demo.js';
 import { ensureDefaultDockedNodes } from '../server/server.js';
@@ -231,7 +232,7 @@ if (AGENT_COMMANDS.has(routedCommand) && routedCommand !== 'serve') {
   const daemonWaitMs = readNumberOption('wait-ms') ?? 10_000;
   const webviewBackendOption: 'chrome' | 'webkit' | undefined =
     webviewBackend === 'chrome' || webviewBackend === 'webkit' ? webviewBackend : undefined;
-  if (themeArg && ['dark', 'light', 'high-contrast'].includes(themeArg)) {
+  if (themeArg && isCanvasTheme(themeArg)) {
     process.env.PMX_CANVAS_THEME = themeArg;
   }
   const help = hasFlag('help') || args.includes('-h');
@@ -252,7 +253,7 @@ Server options:
   --log-file=PATH  Daemon log file (default: ./.pmx-canvas/daemon-${port}.log)
   --pid-file=PATH  Optional daemon PID file (default: ./.pmx-canvas/daemon-${port}.pid)
   --wait-ms=MS   Health-check wait budget for daemon mode (default: 10000)
-  --theme=THEME  Theme: dark (default), light, high-contrast
+  --theme=THEME  Theme: dark (default), light, high-contrast, midnight, sepia, arctic, ember, forest
   --webview-automation        Start a headless Bun.WebView automation session for /workbench
   --webview-backend=BACKEND   Bun.WebView backend: chrome or webkit
   --webview-width=PX          Automation WebView width (default: 1280)

package/src/client/App.tsx

@@ -61,6 +61,13 @@ import {
 } from './icons';
 import { invalidateTokenCache } from './theme/tokens';
 import { MOD_KEY } from './utils/platform';
+import {
+  CANVAS_THEMES,
+  CANVAS_THEME_META,
+  type CanvasThemeName,
+  canvasThemeScheme,
+  normalizeCanvasThemeName,
+} from '../shared/themes.js';
 
 function logAppError(action: string, error: unknown): void {
   console.error(`[app] ${action} failed`, error);
@@ -153,8 +160,66 @@ function Toolbar({
       ].join(' · ')
     : 'Syncing canvas…';
 
+  // Popover state: the theme picker (desktop toolbar) and the mobile "More"
+  // menu share one open-slot so at most one popover shows at a time.
+  const [openMenu, setOpenMenu] = useState<null | 'theme' | 'more'>(null);
+  const groupRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!openMenu) return;
+    const onPointerDown = (e: PointerEvent) => {
+      if (groupRef.current && e.target instanceof Node && !groupRef.current.contains(e.target)) {
+        setOpenMenu(null);
+      }
+    };
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') setOpenMenu(null);
+    };
+    document.addEventListener('pointerdown', onPointerDown);
+    document.addEventListener('keydown', onKeyDown);
+    return () => {
+      document.removeEventListener('pointerdown', onPointerDown);
+      document.removeEventListener('keydown', onKeyDown);
+    };
+  }, [openMenu]);
+
+  const applyTheme = (next: CanvasThemeName) => {
+    document.documentElement.setAttribute('data-theme', next);
+    invalidateTokenCache();
+    canvasTheme.value = next;
+    void saveCanvasTheme(next);
+    setOpenMenu(null);
+  };
+
+  const menuAction = (fn: () => void) => () => {
+    fn();
+    setOpenMenu(null);
+  };
+
+  const activeTheme = normalizeCanvasThemeName(canvasTheme.value);
+  const themeMenuItems = CANVAS_THEMES.map((name) => (
+    <button
+      key={name}
+      type="button"
+      role="menuitemradio"
+      aria-checked={activeTheme === name}
+      class={`toolbar-menu-item${activeTheme === name ? ' active' : ''}`}
+      onClick={() => applyTheme(name)}
+    >
+      <span class="theme-swatch" style={{ background: CANVAS_THEME_META[name].swatchBg }}>
+        <span class="theme-swatch-dot" style={{ background: CANVAS_THEME_META[name].swatchAccent }} />
+      </span>
+      <span>{CANVAS_THEME_META[name].label}</span>
+      {activeTheme === name && (
+        <span class="toolbar-menu-check" aria-hidden="true">
+          ✓
+        </span>
+      )}
+    </button>
+  ));
+
   return (
-    <div class="toolbar-group">
+    <div class="toolbar-group" ref={groupRef}>
       {/* ── Navigation Bar ──────────────────────────────────── */}
       <div class="canvas-toolbar">
         <ToolbarHint label="PMX Canvas" detail="Focus Field · spatial workbench for coding agents" align="start">
@@ -213,63 +278,81 @@ function Toolbar({
           {Math.round(v.scale * 100)}%
         </span>
 
-        <div class="separator" />
+        {/* Secondary controls collapse into the More menu on narrow screens. */}
+        <span class="toolbar-collapsible">
+          <div class="separator" />
 
-        <ToolbarHint
-          label="Arrange layout"
-          detail={edgeCount > 0 ? 'Graph-aware layout for connected nodes' : 'Grid layout for loose nodes'}
-        >
-          <button
-            type="button"
-            onClick={() => (edgeCount > 0 ? forceDirectedArrange() : autoArrange())}
-            aria-label="Arrange layout"
-          >
-            <IconArrange />
-          </button>
-        </ToolbarHint>
-        <ToolbarHint label={minimapVisible ? 'Hide minimap' : 'Show minimap'} detail="Quickly navigate large canvases">
-          <button
-            type="button"
-            onClick={onToggleMinimap}
-            aria-label={minimapVisible ? 'Hide minimap' : 'Show minimap'}
-            style={{ color: minimapVisible ? 'var(--c-accent)' : undefined }}
-          >
-            <IconMinimap />
-          </button>
-        </ToolbarHint>
-        <ToolbarHint
-          label={`Switch to ${canvasTheme.value === 'dark' ? 'light' : 'dark'} theme`}
-          detail={`Current theme: ${canvasTheme.value}`}
-        >
-          <button
-            type="button"
-            onClick={() => {
-              const next = canvasTheme.value === 'dark' ? 'light' : 'dark';
-              document.documentElement.setAttribute('data-theme', next);
-              invalidateTokenCache();
-              canvasTheme.value = next;
-              void saveCanvasTheme(next);
-            }}
-            aria-label={`Switch to ${canvasTheme.value === 'dark' ? 'light' : 'dark'} theme`}
+          <ToolbarHint
+            label="Arrange layout"
+            detail={edgeCount > 0 ? 'Graph-aware layout for connected nodes' : 'Grid layout for loose nodes'}
           >
-            {canvasTheme.value === 'dark' ? <IconSun /> : <IconMoon />}
-          </button>
-        </ToolbarHint>
-        <ToolbarHint label="Snapshots" detail="Capture and restore canvas states" align="end">
-          <button
-            ref={snapshotBtnRef}
-            type="button"
-            onClick={onToggleSnapshot}
-            aria-label="Snapshots"
-            style={{ color: snapshotOpen ? 'var(--c-accent)' : undefined }}
+            <button
+              type="button"
+              onClick={() => (edgeCount > 0 ? forceDirectedArrange() : autoArrange())}
+              aria-label="Arrange layout"
+            >
+              <IconArrange />
+            </button>
+          </ToolbarHint>
+          <ToolbarHint
+            label={minimapVisible ? 'Hide minimap' : 'Show minimap'}
+            detail="Quickly navigate large canvases"
           >
-            <IconSnapshot />
-          </button>
-        </ToolbarHint>
+            <button
+              type="button"
+              onClick={onToggleMinimap}
+              aria-label={minimapVisible ? 'Hide minimap' : 'Show minimap'}
+              style={{ color: minimapVisible ? 'var(--c-accent)' : undefined }}
+            >
+              <IconMinimap />
+            </button>
+          </ToolbarHint>
+          <ToolbarHint label="Theme" detail={`Current theme: ${CANVAS_THEME_META[activeTheme].label}`}>
+            <button
+              type="button"
+              onClick={() => setOpenMenu(openMenu === 'theme' ? null : 'theme')}
+              aria-label="Choose theme"
+              aria-haspopup="menu"
+              aria-expanded={openMenu === 'theme'}
+              style={{ color: openMenu === 'theme' ? 'var(--c-accent)' : undefined }}
+            >
+              {canvasThemeScheme(activeTheme) === 'dark' ? <IconSun /> : <IconMoon />}
+            </button>
+          </ToolbarHint>
+          <ToolbarHint label="Snapshots" detail="Capture and restore canvas states" align="end">
+            <button
+              ref={snapshotBtnRef}
+              type="button"
+              onClick={onToggleSnapshot}
+              aria-label="Snapshots"
+              style={{ color: snapshotOpen ? 'var(--c-accent)' : undefined }}
+            >
+              <IconSnapshot />
+            </button>
+          </ToolbarHint>
+        </span>
+
+        {/* Narrow screens: everything collapsed lives in this single menu. */}
+        <span class="toolbar-more">
+          <ToolbarHint label="More" detail="All canvas actions" align="end">
+            <button
+              type="button"
+              onClick={() => setOpenMenu(openMenu === 'more' ? null : 'more')}
+              aria-label="More actions"
+              aria-haspopup="menu"
+              aria-expanded={openMenu === 'more'}
+              style={{ color: openMenu === 'more' ? 'var(--c-accent)' : undefined }}
+            >
+              <span class="toolbar-more-glyph" aria-hidden="true">
+                ⋯
+              </span>
+            </button>
+          </ToolbarHint>
+        </span>
       </div>
 
-      {/* ── Action Bar ──────────────────────────────────────── */}
-      <div class="canvas-toolbar">
+      {/* ── Action Bar (hidden on narrow screens — lives in the More menu) ── */}
+      <div class="canvas-toolbar toolbar-actions-bar">
         <ToolbarHint
           label={isTraceOn ? 'Disable trace' : 'Enable trace'}
           detail={isTraceOn ? 'Stop collecting new trace nodes' : 'Capture agent execution on the canvas'}
@@ -360,6 +443,71 @@ function Toolbar({
           {countsLabel}
         </span>
       </div>
+
+      {openMenu === 'theme' && (
+        <div class="toolbar-menu" role="menu" aria-label="Theme">
+          {themeMenuItems}
+        </div>
+      )}
+      {openMenu === 'more' && (
+        <div class="toolbar-menu" role="menu" aria-label="Canvas actions">
+          <button
+            type="button"
+            class="toolbar-menu-item"
+            onClick={menuAction(() => (edgeCount > 0 ? forceDirectedArrange() : autoArrange()))}
+          >
+            <IconArrange />
+            <span>Arrange layout</span>
+          </button>
+          <button type="button" class="toolbar-menu-item" onClick={menuAction(onToggleMinimap)}>
+            <IconMinimap />
+            <span>{minimapVisible ? 'Hide minimap' : 'Show minimap'}</span>
+          </button>
+          <button type="button" class="toolbar-menu-item" onClick={menuAction(onToggleSnapshot)}>
+            <IconSnapshot />
+            <span>Snapshots</span>
+          </button>
+          <div class="toolbar-menu-separator" />
+          <button
+            type="button"
+            class="toolbar-menu-item"
+            onClick={menuAction(() => sendIntent('trace-toggle', { enabled: !isTraceOn }))}
+          >
+            <IconTrace />
+            <span>{isTraceOn ? 'Disable trace' : 'Enable trace'}</span>
+          </button>
+          {(isTraceOn || traceNodeCount > 0) && (
+            <button type="button" class="toolbar-menu-item" onClick={menuAction(() => sendIntent('trace-clear'))}>
+              <IconClearTrace />
+              <span>Clear trace</span>
+            </button>
+          )}
+          <button type="button" class="toolbar-menu-item" onClick={menuAction(onToggleAnnotationMode)}>
+            <IconPen />
+            <span>{annotationTool === 'pen' ? 'Stop annotating' : 'Annotate canvas'}</span>
+          </button>
+          <button type="button" class="toolbar-menu-item" onClick={menuAction(onToggleAnnotationEraser)}>
+            <IconEraser />
+            <span>{annotationTool === 'eraser' ? 'Stop erasing' : 'Erase annotations'}</span>
+          </button>
+          <button type="button" class="toolbar-menu-item" onClick={menuAction(onToggleTextAnnotation)}>
+            <IconTextAnnotation />
+            <span>{annotationTool === 'text' ? 'Stop text annotations' : 'Text annotations'}</span>
+          </button>
+          <div class="toolbar-menu-separator" />
+          <button type="button" class="toolbar-menu-item" onClick={menuAction(onOpenPalette)}>
+            <IconSearch />
+            <span>Search nodes and actions</span>
+          </button>
+          <button type="button" class="toolbar-menu-item" onClick={menuAction(onOpenShortcuts)}>
+            <IconShortcuts />
+            <span>Keyboard shortcuts</span>
+          </button>
+          <div class="toolbar-menu-separator" />
+          <div class="toolbar-menu-heading">Theme</div>
+          {themeMenuItems}
+        </div>
+      )}
     </div>
   );
 }

package/src/client/nodes/ExtAppFrame.tsx

@@ -9,6 +9,7 @@ import {
 } from '../../shared/ax-surface-protocol.js';
 import { extAppToolResultsMatch } from '../../shared/ext-app-tool-result.js';
 import { DEFAULT_EXT_APP_SANDBOX } from '../../shared/surface.js';
+import { canvasThemeScheme } from '../../shared/themes.js';
 import {
   canvasTheme,
   collapseExpandedNode,
@@ -520,7 +521,8 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
     [],
   );
 
-  const toMcpTheme = (theme: string): McpUiTheme => (theme === 'light' ? 'light' : 'dark');
+  // MCP apps only understand dark/light — collapse named themes to their scheme.
+  const toMcpTheme = (theme: string): McpUiTheme => canvasThemeScheme(theme);
   const isExpanded = expanded || expandedNodeId.value === nodeId;
 
   latestToolInputRef.current = toolInput;

package/src/client/nodes/McpAppNode.tsx

@@ -1,5 +1,6 @@
 import { useEffect, useMemo, useRef } from 'preact/hooks';
 import { HTML_SURFACE_PUSH_SOURCE } from '../../shared/ax-surface-protocol.js';
+import { canvasThemeScheme } from '../../shared/themes.js';
 import type { CanvasNodeState } from '../types';
 import { axSurfaceState, canvasTheme } from '../state/canvas-store';
 import { shouldContentFitIframeNode } from '../canvas/auto-fit';
@@ -20,7 +21,9 @@ function withViewerParams(
   if (!url) return url;
   try {
     const resolved = new URL(url, window.location.origin);
-    resolved.searchParams.set('theme', canvasTheme.value === 'light' ? 'light' : 'dark');
+    // The json-render viewer + artifacts understand dark/light — collapse named
+    // themes (sepia → light, midnight/arctic/ember/forest → dark) to a scheme.
+    resolved.searchParams.set('theme', canvasThemeScheme(canvasTheme.value));
     if (expanded) resolved.searchParams.set('display', 'expanded');
     // Streaming json-render nodes bump specVersion as patches accumulate; including
     // it in the src reloads the iframe so it re-reads the latest accumulated spec.

package/src/client/state/iframe-mode.ts

@@ -69,6 +69,17 @@ function isEmbeddedDocument(): boolean {
   }
 }
 
+/**
+ * Amp orb services run with AMP_ORB=1 and the server stamps that into the page
+ * as window.__PMX_AMP_ORB (see canvasSpaHtml). The orb portal's nested-iframe
+ * embed blocks src-URL child iframes, but the probe is unreliable there — a
+ * tiny probe iframe sometimes loads even though node-sized ones will not — so
+ * a known orb host must skip the probe and go straight to srcdoc.
+ */
+function isAmpOrbHost(): boolean {
+  return (window as Window & { __PMX_AMP_ORB?: unknown }).__PMX_AMP_ORB === true;
+}
+
 /**
  * Resolve the boot-wide iframe mode once; all surface hooks share the result.
  * The blocked-src condition only exists when the canvas page itself runs
@@ -76,7 +87,7 @@ function isEmbeddedDocument(): boolean {
  * normal path pays zero probe latency before surfaces mount. Only embedded
  * documents run the probe (`embedded` is overridable for tests).
  */
-export function resolveIframeMode(opts: { embedded?: boolean } = {}): Promise<IframeMode> {
+export function resolveIframeMode(opts: { embedded?: boolean; ampOrb?: boolean } = {}): Promise<IframeMode> {
   if (iframeMode.value) return Promise.resolve(iframeMode.value);
   if (pending) return pending;
   const forced = forcedIframeMode();
@@ -88,6 +99,10 @@ export function resolveIframeMode(opts: { embedded?: boolean } = {}): Promise<If
     iframeMode.value = 'src';
     return Promise.resolve('src');
   }
+  if (opts.ampOrb ?? isAmpOrbHost()) {
+    iframeMode.value = 'srcdoc';
+    return Promise.resolve('srcdoc');
+  }
   pending = probeSrcIframes().then((srcWorks) => {
     const mode: IframeMode = srcWorks ? 'src' : 'srcdoc';
     iframeMode.value = mode;

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

@@ -31,6 +31,7 @@ import { invalidateTokenCache } from '../theme/tokens';
 import { resetAttentionBridge, syncAttentionFromSse } from './attention-bridge';
 import { dissolveIntent, resetIntents, settleIntent, upsertIntent } from './intent-store';
 import type { PmxAxIntent } from '../../shared/ax-intent.js';
+import { isCanvasTheme } from '../../shared/themes.js';
 
 let eventSource: EventSource | null = null;
 let savedLayout: Map<string, Partial<CanvasNodeState>> | null = null;
@@ -275,8 +276,10 @@ function ensureLedgerNode(summary: Record<string, unknown>): void {
 }
 
 function applyCanvasTheme(theme: string): void {
-  const valid = theme === 'dark' || theme === 'light' || theme === 'high-contrast';
-  if (!valid) return;
+  // Registry-driven: this is the ONLY path a server-side theme reaches the
+  // browser (connected snapshot + theme-changed events) — a hardcoded subset
+  // here silently drops themes on reload and breaks cross-tab sync.
+  if (!isCanvasTheme(theme)) return;
   document.documentElement.setAttribute('data-theme', theme);
   invalidateTokenCache();
   if (canvasTheme.value !== theme) canvasTheme.value = theme;