pmx-canvas 0.4.1 → 0.4.3

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

@@ -14,7 +14,8 @@
  * toggling the attribute (the theme bridge below) — no CSS payload over
  * postMessage required.
  */
-export type SurfaceTheme = 'dark' | 'light' | 'high-contrast';
+import { type CanvasThemeName } from '../shared/themes.js';
+export type SurfaceTheme = CanvasThemeName;
 /** Path the surface document links for its theme tokens (served from dist/canvas). */
 export declare const SURFACE_THEME_STYLESHEET = "/canvas/surface-theme.css";
 /** CSP sandbox tokens for an `html`/`html-primitive` surface — scripts only, opaque origin. */
@@ -77,6 +78,12 @@ export interface HtmlSurfaceOptions {
     axState?: unknown;
     /** Nonce for the content-height reporter (lets the node grow to fit content). */
     contentHeightToken?: string;
+    /**
+     * Contents of surface-theme.css to inline as a <style> instead of the
+     * same-origin <link> — required for srcdoc-rendered surfaces (nested-iframe
+     * hosts) where the stylesheet subresource may not load.
+     */
+    inlineThemeCss?: string;
 }
 /**
  * Wrap author HTML into a complete, themed standalone document. Accepts either a

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

@@ -345,6 +345,14 @@ produces no event within 3 seconds of connecting, it switches to polling.
 Force a transport with `/workbench?transport=poll` (or `transport=sse` to
 disable the fallback).
 
+## Session theme override (host-default theming)
+
+`/workbench?theme=<name>` gives that browser session its own theme without
+touching the server-global theme other clients see — embedding hosts use it to
+match their chrome (the bundled Copilot extension opens `?theme=light`).
+`?theme=auto` follows the host's `prefers-color-scheme` live. Picking a theme
+from the toolbar ends the override and saves globally as usual.
+
 ## Iframe embed probe (nested-iframe hosts)
 
 Some hosts embed the canvas page itself inside an iframe (the Amp orb portal
@@ -363,6 +371,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,15 @@ 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. |
+| 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; 0.4.2 cycle saw the legacy tools gone from the host list after refresh. |
+| Finding T — theme/More menu mis-anchored | **Done (2026-08-05):** menus moved inside `.toolbar-menu-anchor` wrappers around their triggers (the group-level `position:relative` + `right:0` anchored them ~212px right of the button, both hosts). Anchor-geometry e2e regression tests added. |
+| Finding U — sticky `-32001` session-error banner over rendering content | **Mitigated (2026-08-05), root cause open:** when an ext-app session errors but the cached document still renders, the banner is now a soft degraded-interactivity notice instead of a red alarm. The underlying stressed-reconnect MCP timeout (long-lived tiles through theme churn + daemon respawn) is not clean-reproducible — investigate session re-establishment retry/backoff if the next cycle still hits it. |
 | 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.3",
   "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",
@@ -43,9 +43,9 @@
     "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
-    "test": "PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit",
+    "test": "if [ -d tests/unit ]; then PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit; else echo 'tests/ is not shipped in the npm package — clone the repo to run the suite'; fi",
     "test:unit": "PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun test tests/unit",
-    "test:client": "bun test --preload ./tests/client/setup.ts tests/client",
+    "test:client": "if [ -d tests/client ]; then bun test --preload ./tests/client/setup.ts tests/client; else echo 'tests/ is not shipped in the npm package — clone the repo to run the suite'; fi",
     "test:coverage": "PMX_MCP_APP_HOST_STATE_FILE=/tmp/pmx-canvas-test-app-host-state.json bun test tests/unit --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir coverage && bun scripts/check-coverage.ts",
     "test:web-canvas": "PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bun run build && PMX_CANVAS_DISABLE_BROWSER_OPEN=1 bash scripts/run-playwright.sh",
     "test:e2e": "bun run test:web-canvas",

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,16 @@ 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.
+- Embedding hosts can open `/workbench?theme=<name>` (or `?theme=auto` to follow the host's
+  light/dark appearance) for a session-local default theme that never changes the server-global
+  theme other clients see; an explicit pick from the theme menu ends the override. The bundled
+  Copilot extension opens its panel with `?theme=light`.
 
 After changing files under `src/client/`, rebuild with `bun run build` before manual browser
 verification.
@@ -250,9 +264,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

@@ -59,8 +59,16 @@ import {
   IconZoomIn,
   IconZoomOut,
 } from './icons';
+import { clearThemeOverride } from './state/theme-override';
 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 +161,69 @@ 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) => {
+    // An explicit pick ends any ?theme= session override (host default) and
+    // returns this client to the shared server-global theme it just saved.
+    clearThemeOverride();
+    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 +282,149 @@ 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>
+          {/* Anchor wrapper: the theme menu must open under THIS control, not at
+              the toolbar-group's right edge (0.4.2 report Finding T). */}
+          <span class="toolbar-menu-anchor">
+            <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>
+            {openMenu === 'theme' && (
+              <div class="toolbar-menu" role="menu" aria-label="Theme">
+                {themeMenuItems}
+              </div>
+            )}
+          </span>
+          <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 toolbar-menu-anchor">
+          <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>
+          {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>
+          )}
+        </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'}

package/src/client/canvas/CommandPalette.tsx

@@ -11,6 +11,7 @@ import {
 import { createNodeFromClient, saveCanvasTheme } from '../state/intent-bridge';
 import { TYPE_LABELS, type CanvasNodeState } from '../types';
 import { invalidateTokenCache } from '../theme/tokens';
+import { clearThemeOverride } from '../state/theme-override';
 
 import { MOD_KEY } from '../utils/platform';
 
@@ -174,6 +175,9 @@ export function CommandPalette({ onClose, onToggleMinimap }: { onClose: () => vo
         badge: 'THEME',
         action: () => {
           const next = canvasTheme.value === 'dark' ? 'light' : 'dark';
+          // An explicit pick ends any ?theme= session override, same as the
+          // toolbar picker — otherwise the session stays sticky-overridden.
+          clearThemeOverride();
           document.documentElement.setAttribute('data-theme', next);
           invalidateTokenCache();
           canvasTheme.value = next;

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,15 +521,24 @@ 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;
   latestToolResultRef.current = toolResult;
 
+  // Finding U (0.4.2 report): a stressed reconnect can leave sessionStatus
+  // 'error' (e.g. "MCP error -32001: Request timed out") while the cached app
+  // document still renders fine below. When content IS available, present the
+  // error as a degraded-interactivity notice, not a full-alarm banner over a
+  // working diagram.
+  const sessionErrorWithContent = sessionStatus === 'error' && typeof html === 'string' && html.length > 0;
   const sessionUnavailableMessage =
     sessionStatus === 'error'
-      ? (sessionError ?? 'Saved app session is unavailable. Reopen the app to restore interactivity.')
+      ? sessionErrorWithContent
+        ? `Live session unavailable — showing saved content. Reopen the app to restore interactivity.${sessionError ? ` (${sessionError})` : ''}`
+        : (sessionError ?? 'Saved app session is unavailable. Reopen the app to restore interactivity.')
       : 'Reconnecting saved app session...';
 
   const flushToolResult = (bridge: AppBridge | null): Promise<void> | null => {
@@ -1038,9 +1048,12 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
           style={{
             padding: '6px 10px',
             fontSize: '11px',
-            background: sessionStatus === 'error' ? 'var(--c-danger-12)' : 'var(--c-warn-10)',
-            color: sessionStatus === 'error' ? 'var(--c-danger)' : 'var(--c-warn)',
-            borderBottom: `1px solid ${sessionStatus === 'error' ? 'var(--c-danger-12)' : 'var(--c-warn-15)'}`,
+            background:
+              sessionStatus === 'error' && !sessionErrorWithContent ? 'var(--c-danger-12)' : 'var(--c-warn-10)',
+            color: sessionStatus === 'error' && !sessionErrorWithContent ? 'var(--c-danger)' : 'var(--c-warn)',
+            borderBottom: `1px solid ${
+              sessionStatus === 'error' && !sessionErrorWithContent ? 'var(--c-danger-12)' : 'var(--c-warn-15)'
+            }`,
           }}
         >
           {sessionUnavailableMessage}

package/src/client/nodes/McpAppNode.tsx

@@ -1,7 +1,9 @@
 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 { iframeMode } from '../state/iframe-mode';
 import { shouldContentFitIframeNode } from '../canvas/auto-fit';
 import { ExtAppFrame } from './ExtAppFrame';
 import { useAxSurfaceBridge } from './use-ax-surface-bridge';
@@ -20,7 +22,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.
@@ -182,7 +186,11 @@ function McpAppViewer({ node, expanded }: { node: CanvasNodeState; expanded: boo
         class="mcp-app-frame"
         sandbox="allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox"
         allow="clipboard-read; clipboard-write"
-        loading="lazy"
+        // Lazy loading only helps src mode (defers the HTTP request for
+        // off-screen nodes). In srcdoc mode the content is already inline —
+        // lazy would just delay PAINTING until the node scrolls near the
+        // viewport, which reads as "blank until opened" (Amp portal report).
+        loading={iframeMode.value === 'srcdoc' ? undefined : 'lazy'}
         onLoad={pushAxState}
         style={{ flex: 1, minHeight: 0, width: '100%' }}
         title={`MCP App: ${sourceServer}`}