pmx-canvas 0.4.0 → 0.4.2

package/dist/types/server/canvas-db.d.ts

@@ -5,9 +5,10 @@
  * WAL-mode persistence. Replaces the previous JSON file-based approach.
  */
 import { Database } from 'bun:sqlite';
+import { type CanvasThemeName } from '../shared/themes.js';
 import type { CanvasAnnotation, CanvasEdge, CanvasNodeState, CanvasSnapshot, CanvasSnapshotListOptions, ViewportState } from './canvas-state.js';
 import { type PmxAxState, type PmxAxEvent, type PmxAxEvidence, type PmxAxSteeringMessage, type PmxAxHostCapability, type PmxAxTimelineSummary } from './ax-state.js';
-export type CanvasTheme = 'dark' | 'light' | 'high-contrast';
+export type CanvasTheme = CanvasThemeName;
 export declare function normalizeCanvasTheme(value: unknown, fallback?: CanvasTheme): CanvasTheme;
 export interface PersistedCanvasState {
     version: number;

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/RELEASE.md

@@ -128,12 +128,18 @@ it uses `NPM_TOKEN` directly.
 
 Every release since 0.3.0 has been retested against **stale** skill mirrors:
 consumer workspaces (e.g. `personalclaude`) carry copies of the pmx-canvas
-skill under `.github/`, `.codex/`, `.claude/`, and `.agents/`, and testers
+skills under `.github/`, `.codex/`, `.claude/`, and `.agents/`, and testers
 repeatedly had to sync them mid-cycle before results were trustworthy. After
 publishing, update the installed package in the consumer workspace and re-sync
-its four mirrors from
-`<global npm root>/pmx-canvas/skills/pmx-canvas/` so the first test pass runs
-against the released skill, not the previous version's guidance.
+its four mirrors from `<global npm root>/pmx-canvas/skills/` so the first test
+pass runs against the released skills, not the previous version's guidance.
+
+Sync the **complete tree of every bundled skill** — `pmx-canvas` AND
+`pmx-canvas-testing`, including `references/`, `evals/`, and fixtures — and
+verify by diffing whole directories, not by comparing the `SKILL.md` hash
+alone. The 0.3.4 and 0.4.0 cycles both hit drift where `SKILL.md` matched but
+references/evals were stale, or a newly bundled skill was missing from the
+mirrors entirely.
 
 ## GitHub release
 

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,35 @@ 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).
 
+## Iframe embed probe (nested-iframe hosts)
+
+Some hosts embed the canvas page itself inside an iframe (the Amp orb portal
+does), and Chrome then refuses to load child iframes from `src` URLs — even
+same-origin ones — so iframe-backed nodes would show a broken placeholder.
+When (and only when) the canvas page detects it is embedded, it probes the
+real behavior at boot by loading a hidden iframe against:
+
+```bash
+curl http://localhost:4313/api/canvas/iframe-probe
+```
+
+If that iframe never loads, the client switches every same-origin surface
+(HTML nodes, graph/json-render viewers, frame documents) to `fetch()` +
+`srcdoc` inline rendering. External app URLs stay on `src` — they cannot be
+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).
+
 ## Time travel
 
 ```bash

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

@@ -66,5 +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" (0.3.3 report leaves it open), inline ext-app iframes must render outside the world transform — an architectural change that reopens the parked M3. Only scope on a failing report cycle. |
+| 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 + 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.0",
+  "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.
@@ -223,12 +233,20 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
   time), with a watchdog retry for iframes that never boot and a re-arm when a panel that loaded
   hidden becomes visible. Treat the auto-recovery as best-effort, NOT guaranteed — the 0.3.2
   Copilot-host report shows tiles can still come up black in real WKWebView panels (compositing
-  success is not observable from page JS, so retries are bounded). Keep the cautionary behavior:
+  success is not observable from page JS, so retries are bounded). Since 0.4.1 the canvas also
+  fires a post-boot **repaint nudge** under WebKit (a 1px layout bounce that forces the
+  compositor to re-rasterize the frame — the cheap half of the proven enlarge-close unstick;
+  shows as `repaint-nudge` in the recovery trail). Keep the cautionary behavior anyway:
   recovery is deterministic via **expand-then-close** of the black tile (forces a fresh mount in
   the fullscreen overlay, which always paints), or open the workbench in a normal browser
   (Chrome). Do not diagnose a healthy app session as a broken node. When reporting a black tile,
   fetch `GET /api/canvas/debug/ext-app-recovery` from the daemon and attach the trace — it shows
   what the recovery queue actually did in that panel.
+- Ext-app frame documents live in server memory. Through 0.4.0, killing/restarting the daemon
+  while a panel stays open leaves ext-app tiles on dead frame URLs (`Frame document not found`,
+  0.4.0 report Finding S) until a full workbench reload. Since 0.4.1 the browser revalidates its
+  frame documents on every reconnect and re-mints them against the new process automatically —
+  if a post-restart tile still looks blank on an older install, reload the workbench page.
 - A hosted ext-app (Excalidraw) resized NARROW/TALL (e.g. 360x529) can show its diagram in the
   upper region with the app's own dark fill below it — in every engine (0.3.4 report Finding Q).
   This letterboxing lives inside the hosted app bundle's root container, not in PMX (a body-level
@@ -238,10 +256,20 @@ Prefer `canvas_query { action: "search" }` over parsing the full layout.
 - Behind proxies that buffer streaming responses (e.g. portal hosts), the workbench auto-falls
   back from SSE to a polling transport within ~3s, so the board still boots and stays live.
   Force a mode with `/workbench?transport=poll` (or `transport=sse`) when diagnosing.
+- Nested-iframe embeds (e.g. the Amp orb portal renders the canvas page inside an ampcode.com
+  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). 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 (e.g. the
-  Codex in-app browser) don't deliver live-resize events, so a resized standalone chart can look
-  stale until reload — use a system browser for separate full-page viewing.
+  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
+  graph reflow on a native viewport resize), so if a resized standalone chart looks stale,
+  reload it or use a system browser for separate full-page viewing.
 - Some hosts cannot automate inside sandboxed workbench iframes. Verify those interactions in a
   system browser or through server-side AX state.
 - `pmx-canvas screenshot` requires an active WebView. Start it with

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/skills/pmx-canvas-testing/SKILL.md

@@ -71,6 +71,9 @@ Prefer extending the existing suites before inventing a one-off script.
 - Avoid brittle selectors. Prefer stable text, roles, titles, or deliberate component hooks
 - If a change spans server and client, add at least one server-side assertion and one browser or
   API-level proof
+- MCP harnesses using the official SDK must wind down BOTH halves: call `client.close()` AND
+  `transport.close()` on the `StdioClientTransport`. Closing only the client leaves the spawned
+  stdio server process alive after the test exits (0.4.0 cycle finding)
 
 ## Layout And Embedded Content Checks
 

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

@@ -2,6 +2,11 @@
 import './uuid-polyfill';
 import { render } from 'preact';
 import { App } from './App';
+import { resolveIframeMode } from './state/iframe-mode';
+
+// Start the embed probe before first paint so iframe-backed nodes know whether
+// src-URL iframes work in this context (Amp orb portals block them).
+void resolveIframeMode();
 
 const root = document.getElementById('app');
 if (root) {