pmx-canvas 0.4.2 → 0.4.3

package/dist/canvas/surface-theme.css

@@ -218,32 +218,32 @@
 }
 
 :root[data-theme="ember"] {
-  /* ── Core palette (ember · charcoal + vivid warm orange) ─── */
-  --c-bg: #0E0E11;
-  --c-panel: #17181D;
-  --c-panel-soft: #121317;
-  --c-line: #2A2C34;
-  --c-text: #ECEDF0;
-  --c-text-soft: #C9CCD4;
-  --c-muted: #8E939F;
-  --c-dim: #5F646E;
-  --c-accent: #FF5C2E;
+  /* ── Core palette (ember · neutral charcoal + vivid orange-red) ─── */
+  --c-bg: #0B0B0C;
+  --c-panel: #161618;
+  --c-panel-soft: #101012;
+  --c-line: #29292C;
+  --c-text: #EDEBE6;
+  --c-text-soft: #CBC9C2;
+  --c-muted: #96948D;
+  --c-dim: #66655F;
+  --c-accent: #F34E1C;
   --c-ok: #4CC38A;
   --c-warn: #F5B944;
   --c-warn-alt: #FFB300;
   --c-danger: #F0566A;
   --c-purple: #A78BFA;
 
-  --color-bg: #0E0E11;
-  --color-panel: #17181D;
-  --color-surface: #121317;
-  --color-border: #2A2C34;
-  --color-text: #ECEDF0;
-  --color-text-primary: #ECEDF0;
-  --color-text-secondary: #C9CCD4;
-  --color-text-muted: #8E939F;
-  --color-text-dim: #5F646E;
-  --color-accent: #FF5C2E;
+  --color-bg: #0B0B0C;
+  --color-panel: #161618;
+  --color-surface: #101012;
+  --color-border: #29292C;
+  --color-text: #EDEBE6;
+  --color-text-primary: #EDEBE6;
+  --color-text-secondary: #CBC9C2;
+  --color-text-muted: #96948D;
+  --color-text-dim: #66655F;
+  --color-accent: #F34E1C;
   --color-success: #4CC38A;
   --color-warning: #F5B944;
   --color-danger: #F0566A;

package/dist/types/client/state/theme-override.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Per-session theme override — host-default theming.
+ *
+ * Hosts that embed the workbench (the GitHub Copilot panel, the Claude Code
+ * desktop browser pane, ChatGPT-style app browsers, …) can open it with
+ * `?theme=<name>` or `?theme=auto` to give THEIR panel a fitting default
+ * without touching the server-global theme every other client sees. The
+ * override is client-local: server theme frames are ignored while it is
+ * active, and it ends the moment the user explicitly picks a theme from the
+ * picker (which then applies + saves globally as usual).
+ *
+ * `theme=auto` follows the host's prefers-color-scheme live, mapping to the
+ * built-in light/dark themes — so a light-mode host panel gets a light canvas
+ * by default and flips with the host appearance.
+ */
+import { type CanvasThemeName } from '../../shared/themes.js';
+export declare function themeOverrideActive(): boolean;
+/** Test-only: reset the module state, including the page-lifetime latch. */
+export declare function resetThemeOverrideForTests(): void;
+/** The user picked a theme explicitly — the session override ends for good. */
+export declare function clearThemeOverride(): void;
+export declare function sessionThemeParam(): CanvasThemeName | 'auto' | null;
+/**
+ * Activate the override from the URL (no-op without a valid `?theme=`).
+ * `apply` is the canvas theme applier (client-side only — never saved).
+ */
+export declare function initSessionThemeOverride(apply: (theme: CanvasThemeName) => void): void;

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

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

@@ -74,5 +74,7 @@ The remaining items were re-analyzed with pros/cons and tiered; the maintainer a
 |---|---|
 | 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.2",
+  "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

@@ -181,6 +181,10 @@ Use the visible workbench when the human is actively curating layout:
   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.

package/src/client/App.tsx

@@ -59,6 +59,7 @@ import {
   IconZoomIn,
   IconZoomOut,
 } from './icons';
+import { clearThemeOverride } from './state/theme-override';
 import { invalidateTokenCache } from './theme/tokens';
 import { MOD_KEY } from './utils/platform';
 import {
@@ -184,6 +185,9 @@ function Toolbar({
   }, [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;
@@ -307,18 +311,27 @@ function Toolbar({
               <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>
+          {/* 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}
@@ -333,7 +346,7 @@ function Toolbar({
         </span>
 
         {/* Narrow screens: everything collapsed lives in this single menu. */}
-        <span class="toolbar-more">
+        <span class="toolbar-more toolbar-menu-anchor">
           <ToolbarHint label="More" detail="All canvas actions" align="end">
             <button
               type="button"
@@ -348,6 +361,65 @@ function Toolbar({
               </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>
 
@@ -443,71 +515,6 @@ 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/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

@@ -528,9 +528,17 @@ export function ExtAppFrame({ node, expanded = false }: { node: CanvasNodeState;
   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 => {
@@ -1040,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

@@ -3,6 +3,7 @@ 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';
@@ -185,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}`}

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

@@ -26,6 +26,7 @@ import {
   workbenchConnectionEpoch,
 } from './canvas-store';
 import { fetchAxSurfaceState } from './intent-bridge';
+import { initSessionThemeOverride, themeOverrideActive } from './theme-override';
 import { DEFAULT_POSITIONS, makeNodeState } from './node-factory';
 import { invalidateTokenCache } from '../theme/tokens';
 import { resetAttentionBridge, syncAttentionFromSse } from './attention-bridge';
@@ -399,7 +400,9 @@ function handleConnected(data: Record<string, unknown>): void {
   connectionStatus.value = 'connected';
   // Reconnect marker for holders of server-minted URLs (Finding S).
   workbenchConnectionEpoch.value += 1;
-  if (typeof data.theme === 'string') {
+  // A ?theme= session override (host-default theming) wins over the
+  // server-global theme for THIS client only.
+  if (typeof data.theme === 'string' && !themeOverrideActive()) {
     applyCanvasTheme(data.theme);
   }
   if (data.ledgerSummary) {
@@ -890,7 +893,7 @@ function handleTraceState(data: Record<string, unknown>): void {
 }
 
 function handleThemeChanged(data: Record<string, unknown>): void {
-  if (typeof data.theme === 'string') {
+  if (typeof data.theme === 'string' && !themeOverrideActive()) {
     applyCanvasTheme(data.theme);
   }
 }
@@ -1082,6 +1085,9 @@ function startPollingTransport(): () => void {
 }
 
 export function connectSSE(): () => void {
+  // Host-default theming: a ?theme= param applies before the first server
+  // frame so an embedding host panel never flashes the server-global theme.
+  initSessionThemeOverride(applyCanvasTheme);
   savedLayout = restoreLayout();
   ensureStatusNode();
   hasInitialServerLayout.value = false;

package/src/client/state/theme-override.ts

@@ -0,0 +1,83 @@
+/**
+ * Per-session theme override — host-default theming.
+ *
+ * Hosts that embed the workbench (the GitHub Copilot panel, the Claude Code
+ * desktop browser pane, ChatGPT-style app browsers, …) can open it with
+ * `?theme=<name>` or `?theme=auto` to give THEIR panel a fitting default
+ * without touching the server-global theme every other client sees. The
+ * override is client-local: server theme frames are ignored while it is
+ * active, and it ends the moment the user explicitly picks a theme from the
+ * picker (which then applies + saves globally as usual).
+ *
+ * `theme=auto` follows the host's prefers-color-scheme live, mapping to the
+ * built-in light/dark themes — so a light-mode host panel gets a light canvas
+ * by default and flips with the host appearance.
+ */
+import { type CanvasThemeName, isCanvasTheme } from '../../shared/themes.js';
+
+let active = false;
+// Latched when the user explicitly ends the override: the URL param survives
+// reconnects (connectSSE re-inits on every transport drop), but the user's
+// choice must stick for the page lifetime — only a reload re-activates.
+let userEnded = false;
+let schemeQuery: MediaQueryList | null = null;
+let schemeListener: (() => void) | null = null;
+
+export function themeOverrideActive(): boolean {
+  return active;
+}
+
+/** Test-only: reset the module state, including the page-lifetime latch. */
+export function resetThemeOverrideForTests(): void {
+  active = false;
+  userEnded = false;
+  detachSchemeListener();
+}
+
+/** The user picked a theme explicitly — the session override ends for good. */
+export function clearThemeOverride(): void {
+  active = false;
+  userEnded = true;
+  detachSchemeListener();
+}
+
+function detachSchemeListener(): void {
+  if (schemeQuery && schemeListener) {
+    schemeQuery.removeEventListener('change', schemeListener);
+  }
+  schemeQuery = null;
+  schemeListener = null;
+}
+
+export function sessionThemeParam(): CanvasThemeName | 'auto' | null {
+  // DOM-less callers (server-side rendering of the module graph, unit tests
+  // that import the sse-bridge without a DOM) have no override.
+  if (typeof window === 'undefined' || !window.location) return null;
+  const value = new URLSearchParams(window.location.search).get('theme');
+  if (value === 'auto') return 'auto';
+  return isCanvasTheme(value) ? value : null;
+}
+
+/**
+ * Activate the override from the URL (no-op without a valid `?theme=`).
+ * `apply` is the canvas theme applier (client-side only — never saved).
+ */
+export function initSessionThemeOverride(apply: (theme: CanvasThemeName) => void): void {
+  if (userEnded) return;
+  const param = sessionThemeParam();
+  if (!param) return;
+  // Re-init happens on every reconnect — replace any prior listener instead
+  // of accumulating one per reconnect cycle.
+  detachSchemeListener();
+  active = true;
+  if (param !== 'auto') {
+    apply(param);
+    return;
+  }
+  schemeQuery = window.matchMedia('(prefers-color-scheme: light)');
+  schemeListener = () => {
+    if (active && schemeQuery) apply(schemeQuery.matches ? 'light' : 'dark');
+  };
+  schemeListener();
+  schemeQuery.addEventListener('change', schemeListener);
+}