@oh-my-pi/pi-coding-agent 17.0.9 → 17.1.0

package/src/exec/bash-executor.ts

@@ -10,6 +10,7 @@ import { Settings, type ShellMinimizerSettings } from "../config/settings";
 import { OutputSink } from "../session/streaming-output";
 import { resolveOutputMaxColumns, resolveOutputSinkHeadBytes } from "../tools/output-meta";
 import { getOrCreateSnapshot } from "../utils/shell-snapshot";
+import { loadDirenvEnv } from "./direnv";
 import { buildNonInteractiveEnv } from "./non-interactive-env";
 
 export interface BashExecutorOptions {
@@ -56,6 +57,78 @@ export interface BashResult {
 	workingDir?: string;
 }
 
+/** POSIX-safe variable name — gates which direnv unsets we inject into the
+ *  command line, so a hostile `.envrc` can't smuggle shell syntax through
+ *  `unset`. `.envrc` never produces non-identifier names in practice. */
+const SAFE_ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export interface DirenvPreflightOptions {
+	/** Caller-supplied env overlay; these values win over direnv-provided ones. */
+	callerEnv?: Record<string, string>;
+	signal?: AbortSignal;
+	/** Full direnv-load budget (`bash.direnvLoadTimeoutMs`). A positive
+	 *  `callerTimeoutMs` clamps the effective load below this; `0`/undefined
+	 *  leaves the full budget. */
+	timeoutMs?: number;
+	/** The caller's command deadline (ms). A positive value clamps the direnv
+	 *  load so a cold `.envrc` can't outlast a short-timeout command; `0` or
+	 *  undefined means "no caller clamp" — the load keeps its full `timeoutMs`
+	 *  budget (a disabled command deadline is NOT a 0 ms load). Centralizing the
+	 *  clamp here keeps every backend (executeBash, ACP terminal, PTY) on one
+	 *  contract instead of each re-deriving it. */
+	callerTimeoutMs?: number;
+	/** `bash.direnv` setting — `"off"` skips the load entirely. */
+	direnvSetting: "auto" | "off";
+	/** Shell wrapper prefix (profiler/strace) to place *after* the unset prefix,
+	 *  matching `executeBash`'s ordering. Backends that apply their own shell
+	 *  wrapping (ACP `wrapShellLineForClientTerminal`) omit this. */
+	commandPrefix?: string | undefined;
+}
+
+/**
+ * Load the repo's direnv/devenv env and fold it into a `(command, env)` pair so
+ * every bash backend (one-shot `executeBash`, ACP client terminal, PTY) exposes
+ * the same devenv tools. Encapsulates: load the diff, merge `set` under the
+ * caller's overlay (caller wins), and prepend a regex-gated `unset -v` for
+ * variables the `.envrc` removes (skipping any the caller re-supplied).
+ *
+ * Returns the possibly-prefixed command plus the merged env, or the inputs
+ * unchanged (`env` = `callerEnv`) when direnv is off, absent, or has no `.envrc`.
+ * Pure transform: does NOT layer non-interactive env defaults — that stays the
+ * caller's job (so interactive PTY/ACP paths keep their own env shape).
+ */
+export async function applyDirenvPreflight(
+	command: string,
+	cwd: string,
+	opts: DirenvPreflightOptions,
+): Promise<{ command: string; env: Record<string, string> | undefined }> {
+	const withPrefix = (line: string): string => (opts.commandPrefix ? `${opts.commandPrefix} ${line}` : line);
+	// A positive caller deadline clamps the direnv load below its full budget so
+	// a cold `.envrc` can't outlast a short-timeout command; `0`/undefined means
+	// "no caller clamp" (a disabled command deadline is not a 0 ms load). Every
+	// backend routes through here, so the clamp lives in one place.
+	const loadTimeoutMs =
+		opts.callerTimeoutMs !== undefined && opts.callerTimeoutMs > 0
+			? Math.min(opts.timeoutMs ?? opts.callerTimeoutMs, opts.callerTimeoutMs)
+			: opts.timeoutMs;
+	const direnvDiff =
+		opts.direnvSetting === "off" ? null : await loadDirenvEnv(cwd, { timeoutMs: loadTimeoutMs, signal: opts.signal });
+	if (!direnvDiff) {
+		return { command: withPrefix(command), env: opts.callerEnv };
+	}
+	// The caller's explicit env still wins over direnv-provided values.
+	const mergedEnv = { ...direnvDiff.set, ...opts.callerEnv };
+	// direnv can also *remove* inherited variables (a `.envrc` doing
+	// `unset AWS_PROFILE`). An env overlay can only add/override, so prepend a
+	// real `unset` for those — unless the caller re-supplied the same var
+	// explicitly, in which case the caller wins.
+	const direnvUnsets = direnvDiff.unset.filter(
+		name => !(opts.callerEnv && name in opts.callerEnv) && SAFE_ENV_NAME.test(name),
+	);
+	const unsetPrefix = direnvUnsets.length > 0 ? `unset -v ${direnvUnsets.join(" ")}; ` : "";
+	return { command: `${unsetPrefix}${withPrefix(command)}`, env: mergedEnv };
+}
+
 const shellSessions = new Map<string, Shell>();
 const brokenShellSessions = new Set<string>();
 const shellSessionQuarantines = new Map<string, Promise<unknown>>();
@@ -279,15 +352,25 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 	const minimizer = buildMinimizerOptions(settings.getGroup("shellMinimizer"));
 
 	const commandCwd = resolveShellCwd(options?.cwd);
-	const commandEnv = buildNonInteractiveEnv(options?.env);
-
-	// Apply command prefix if configured
-	const prefixedCommand = prefix ? `${prefix} ${command}` : command;
+	// Fold the repo's direnv/devenv env into the command + env so devenv tools
+	// land on PATH; the caller's explicit `env` still wins. Thread the caller's
+	// signal + timeout so an aborted / short-timeout call can't hang on a cold
+	// `.envrc` load before the abort listener is installed. The helper applies
+	// the configured shell `prefix` after any `unset -v` it prepends.
+	const preflight = await applyDirenvPreflight(command, commandCwd ?? process.cwd(), {
+		callerEnv: options?.env,
+		signal: options?.signal,
+		timeoutMs: settings.get("bash.direnvLoadTimeoutMs"),
+		callerTimeoutMs: options?.timeout,
+		direnvSetting: settings.get("bash.direnv"),
+		commandPrefix: prefix,
+	});
+	const commandEnv = buildNonInteractiveEnv(preflight.env);
 	const runCdInPersistentShell = options?.useUserShell === true && !prefix && isPersistentShellCdCommand(command);
 	const finalCommand =
 		options?.useUserShell === true && !bashShell && !runCdInPersistentShell
-			? buildUserShellCommand(shell, args, prefixedCommand)
-			: prefixedCommand;
+			? buildUserShellCommand(shell, args, preflight.command)
+			: preflight.command;
 
 	// Create output sink for truncation and artifact handling
 	const sink = new OutputSink({

package/src/exec/direnv.ts

@@ -0,0 +1,145 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { $which, logger } from "@oh-my-pi/pi-utils";
+
+/** Default cap on a single `direnv` invocation. The first export for a devenv
+ *  `.envrc` can build a shell; callers may raise this via `bash.direnvLoadTimeoutMs`. */
+export const DEFAULT_DIRENV_TIMEOUT_MS = 30_000;
+
+/** Walk up from `startDir` to the nearest directory containing an `.envrc`. */
+export async function findEnvrc(startDir: string): Promise<string | null> {
+	let dir = path.resolve(startDir);
+	for (;;) {
+		const candidate = path.join(dir, ".envrc");
+		try {
+			if ((await fs.stat(candidate)).isFile()) return candidate;
+		} catch {
+			// no .envrc here — keep walking up
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+export interface DirenvExportDiff {
+	/** Variables direnv sets to a concrete value. */
+	set: Record<string, string>;
+	/** Variables direnv removes (JSON `null`). */
+	unset: string[];
+}
+
+/** Parse `direnv export json` output (`{VAR: value|null}`) into set/unset halves. */
+export function parseDirenvExport(jsonText: string): DirenvExportDiff {
+	const trimmed = jsonText.trim();
+	if (trimmed.length === 0) return { set: {}, unset: [] };
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(trimmed);
+	} catch {
+		return { set: {}, unset: [] };
+	}
+	const set: Record<string, string> = {};
+	const unset: string[] = [];
+	if (parsed && typeof parsed === "object") {
+		for (const [key, value] of Object.entries(parsed as Record<string, unknown>)) {
+			if (value === null) unset.push(key);
+			else if (typeof value === "string") set[key] = value;
+		}
+	}
+	return { set, unset };
+}
+
+let direnvLookup: { bin: string | null } | undefined;
+function direnvBinary(): string | null {
+	if (!direnvLookup) direnvLookup = { bin: $which("direnv") };
+	return direnvLookup.bin;
+}
+
+/** direnv computes its diff relative to the spawning env; strip any inherited
+ *  direnv state so it loads the target `.envrc` from a clean baseline. */
+function cleanSpawnEnv(): Record<string, string> {
+	const out: Record<string, string> = {};
+	for (const [key, value] of Object.entries(Bun.env)) {
+		if (value !== undefined && !key.startsWith("DIRENV_")) out[key] = value;
+	}
+	return out;
+}
+
+async function runDirenv(
+	bin: string,
+	args: string[],
+	cwd: string,
+	timeoutMs: number,
+	env: Record<string, string>,
+	signal?: AbortSignal,
+): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+	// Bail on the caller's cancellation as well as the per-invocation cap so a
+	// cold `.envrc` load can't outlive an aborted / short-timeout bash call.
+	const abortSignal = signal
+		? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)])
+		: AbortSignal.timeout(timeoutMs);
+	const proc = Bun.spawn([bin, ...args], {
+		cwd,
+		env,
+		stdout: "pipe",
+		stderr: "pipe",
+		signal: abortSignal,
+	});
+	// Drain stdout AND stderr concurrently: a cold `use devenv`/Nix load emits
+	// enough diagnostics to fill the stderr pipe and block the child forever if
+	// only stdout is read (it would then wait out `timeoutMs`).
+	const [stdout, stderr] = await Promise.all([
+		new Response(proc.stdout as ReadableStream<Uint8Array>).text(),
+		new Response(proc.stderr as ReadableStream<Uint8Array>).text(),
+	]);
+	const exitCode = await proc.exited;
+	return { exitCode, stdout, stderr };
+}
+
+/**
+ * Resolve the nearest `.envrc` from `cwd` and return its `direnv export` diff
+ * (variables to set, and variables direnv removes). Returns `null` when there
+ * is no `.envrc`, `direnv` is not installed, the `.envrc` is not on direnv's
+ * allow list, or the export fails/times out.
+ *
+ * direnv's own allow list is honored — an `.envrc` the user has not
+ * `direnv allow`ed is NEVER executed or auto-allowed. This keeps OMP's trust
+ * boundary identical to the user's own shell: cloning a repo with a poisoned
+ * `.envrc` grants it nothing until the user explicitly allows it.
+ *
+ * Always re-invokes `direnv export json` rather than serving a cached diff:
+ * direnv is fast once warm, and its own watch/mtime invalidation is the
+ * authoritative freshness signal (a content-hash cache here would go stale when
+ * a `watch_file` target changes without the `.envrc` text changing).
+ */
+export async function loadDirenvEnv(
+	cwd: string,
+	opts?: { timeoutMs?: number; signal?: AbortSignal },
+): Promise<DirenvExportDiff | null> {
+	const envrcPath = await findEnvrc(cwd);
+	if (!envrcPath) return null;
+	const bin = direnvBinary();
+	if (!bin) return null;
+
+	const dir = path.dirname(envrcPath);
+	const timeoutMs = opts?.timeoutMs ?? DEFAULT_DIRENV_TIMEOUT_MS;
+	const env = cleanSpawnEnv();
+	try {
+		const { exitCode, stdout, stderr } = await runDirenv(bin, ["export", "json"], dir, timeoutMs, env, opts?.signal);
+		if (exitCode !== 0) {
+			// A not-yet-allowed .envrc is an expected steady state (the user opted
+			// out by never running `direnv allow`), not an error worth warning on.
+			if (stderr.includes("is blocked")) {
+				logger.debug("direnv .envrc not allowed; skipping", { dir });
+			} else {
+				logger.warn("direnv export failed", { dir, exitCode });
+			}
+			return null;
+		}
+		return parseDirenvExport(stdout);
+	} catch (err) {
+		logger.warn("direnv load failed", { dir, error: err instanceof Error ? err.message : String(err) });
+		return null;
+	}
+}

package/src/export/html/args.ts

@@ -0,0 +1,20 @@
+/**
+ * `/export` argument parsing, split from `./index.ts` so slash-command
+ * registries can parse arguments without eagerly loading the export module's
+ * embedded template/tool-view text.
+ */
+
+/** Dark and light TUI theme names bundled into a dual-theme export. */
+export interface ExportThemeNames {
+	dark: string;
+	light: string;
+}
+
+/** Parse `/export [--themes] [path]`; paths containing spaces were never supported. */
+export function parseExportArgs(args: string): { outputPath?: string; useUserThemes: boolean } {
+	const parts = args.trim().split(/\s+/).filter(Boolean);
+	const useUserThemes = parts.includes("--themes");
+	const paths = parts.filter(part => part !== "--themes");
+	if (paths.length > 1) throw new Error("Usage: /export [--themes] [path]");
+	return { outputPath: paths[0], useUserThemes };
+}

package/src/export/html/index.ts

@@ -6,6 +6,7 @@ import { getResolvedThemeColors, getThemeExportColors } from "../../modes/theme/
 import type { SessionEntry, SessionHeader } from "../../session/session-entries";
 import { loadEntriesFromFile } from "../../session/session-loader";
 import { SessionManager } from "../../session/session-manager";
+import type { ExportThemeNames } from "./args";
 import templateCss from "./template.css" with { type: "text" };
 import templateHtml from "./template.html" with { type: "text" };
 import templateJs from "./template.js" with { type: "text" };
@@ -14,6 +15,8 @@ import templateJs from "./template.js" with { type: "text" };
 import toolViewsJs from "./tool-views.generated.js" with { type: "text" };
 import { webExportThemeVars } from "./web-palette";
 
+export { type ExportThemeNames, parseExportArgs } from "./args";
+
 let cachedTemplate: string | undefined;
 
 /** Compose the standalone export template: minified CSS, tool renderers, and viewer JS inlined. */
@@ -37,20 +40,12 @@ export function getTemplate(): string {
 
 export interface ExportOptions {
 	outputPath?: string;
-	/**
-	 * Which color palette the export ships with.
-	 * - `"web"` (default) — the omp brand identity (collab-web pink/purple),
-	 *   so public HTML exports and the `/s/<id>` share viewer match the live
-	 *   `my.omp.sh` client. See `web-palette.ts`.
-	 * - `"theme"` — derive from `themeName` (or the active TUI theme), preserving
-	 *   the pre-15.12 behavior where an export mirrored the user's terminal.
-	 */
+	/** `"web"` bundles the omp web themes; `"theme"` bundles TUI themes. */
 	palette?: "web" | "theme";
-	/**
-	 * TUI theme to derive colors from when `palette: "theme"`. Ignored for the
-	 * default `"web"` palette. Resolves to the active TUI theme when omitted.
-	 */
+	/** Legacy single TUI theme name. Prefer `themeNames` for dual-theme exports. */
 	themeName?: string;
+	/** Dark and light TUI themes to bundle when `palette` is `"theme"`. */
+	themeNames?: ExportThemeNames;
 	/** Embed subagent session transcripts found next to the session file (default true). */
 	includeSubSessions?: boolean;
 }
@@ -116,50 +111,49 @@ function deriveExportColors(baseColor: string): { pageBg: string; cardBg: string
 }
 
 /**
- * Generate CSS custom properties for the export `:root`.
- *
- * Two call shapes:
- *   • `generateThemeVars("web" | "theme", themeName?)` — explicit palette.
- *     `"web"` (the default for public artifacts) returns the fixed omp brand
- *     palette from `web-palette.ts` — collab-web pink/purple identity, shared
- *     with the live `my.omp.sh` client, so exports and the share viewer render
- *     identically to it. `"theme"` derives from the TUI theme via
- *     `getResolvedThemeColors(themeName)` plus the three
- *     `export.{pageBg,cardBg,infoBg}` surface overrides.
- *   • `generateThemeVars(themeName)` — legacy single-arg form: derive from the
- *     named TUI theme. Kept so existing callers (and the theme-islight test)
- *     keep working; equivalent to `generateThemeVars("theme", themeName)`.
+ * Generate CSS custom properties for one export theme.
  *
- * Exported for the share-viewer build script.
+ * The single-argument theme-name form remains available to callers that need
+ * one TUI palette. Standalone HTML uses `generateThemeStyles()` below.
  */
 export async function generateThemeVars(
 	palette: "web" | "theme" | (string & {}) = "web",
 	themeName?: string,
 ): Promise<string> {
-	// Legacy single-arg form: `generateThemeVars("my-theme")` — the first arg
-	// is a theme name, not a palette. Route it to the themed path.
-	if (palette !== "web" && palette !== "theme") {
-		return generateThemeVars("theme", palette);
-	}
-	if (palette === "web") return webExportThemeVars();
+	if (palette !== "web" && palette !== "theme") return generateThemeVars("theme", palette);
+	if (palette === "web") return webExportThemeVars("dark");
 
 	const colors = await getResolvedThemeColors(themeName);
-	const lines: string[] = [];
-	for (const key in colors) {
-		lines.push(`--${key}: ${colors[key]};`);
-	}
-
+	const lines = Object.entries(colors).map(([key, value]) => `--${key}: ${value};`);
 	const themeExport = await getThemeExportColors(themeName);
-	const userMessageBg = colors.userMessageBg || "#343541";
-	const derived = deriveExportColors(userMessageBg);
+	const derived = deriveExportColors(colors.userMessageBg || "#343541");
 
 	lines.push(`--body-bg: ${themeExport.pageBg ?? derived.pageBg};`);
 	lines.push(`--container-bg: ${themeExport.cardBg ?? derived.cardBg};`);
 	lines.push(`--info-bg: ${themeExport.infoBg ?? derived.infoBg};`);
-
 	return lines.join(" ");
 }
 
+/** Generate dark, light, and auto-following CSS rules for a standalone viewer. */
+export async function generateThemeStyles(
+	palette: "web" | "theme",
+	themeNames?: ExportThemeNames,
+	legacyThemeName?: string,
+): Promise<string> {
+	const [dark, light] =
+		palette === "web"
+			? [webExportThemeVars("dark"), webExportThemeVars("light")]
+			: await Promise.all([
+					generateThemeVars("theme", themeNames?.dark ?? legacyThemeName ?? "dark"),
+					generateThemeVars("theme", themeNames?.light ?? legacyThemeName ?? "light"),
+				]);
+	return [
+		`:root, :root[data-theme="dark"] { color-scheme: dark; ${dark} }`,
+		`:root[data-theme="light"] { color-scheme: light; ${light} }`,
+		`@media (prefers-color-scheme: light) { :root:not([data-theme]) { color-scheme: light; ${light} } }`,
+	].join("\n");
+}
+
 /** Embedded subagent session transcript, keyed by slash-joined agent path in `SessionData.subSessions`. */
 export interface SubSession {
 	/** Bare agent id (session file stem), e.g. "ToolAsk". */
@@ -240,15 +234,19 @@ async function collectSubSessionsFromDir(
 }
 
 /** Generate HTML from bundled template with runtime substitutions. */
-async function generateHtml(sessionData: SessionData, palette: "web" | "theme", themeName?: string): Promise<string> {
-	const themeVars = await generateThemeVars(palette, themeName);
+async function generateHtml(
+	sessionData: SessionData,
+	palette: "web" | "theme",
+	themeNames?: ExportThemeNames,
+	themeName?: string,
+): Promise<string> {
+	const themeStyles = await generateThemeStyles(palette, themeNames, themeName);
 	const sessionDataBase64 = Buffer.from(JSON.stringify(sessionData)).toBase64();
 
 	// Use function replacements so `$'`, `$&`, `$$`, `$n`, etc. in the
-	// substituted CSS/base64 are not interpreted as substitution patterns
-	// (see https://mdn.io/String.replace).
+	// substituted CSS/base64 are not interpreted as substitution patterns.
 	return getTemplate()
-		.replace("<theme-vars/>", () => `<style>:root { ${themeVars} }</style>`)
+		.replace("<theme-vars/>", () => `<style>${themeStyles}</style>`)
 		.replace("{{SESSION_DATA}}", () => sessionDataBase64);
 }
 
@@ -270,7 +268,7 @@ export async function exportSessionToHtml(
 	}
 
 	const palette = opts.palette ?? (opts.themeName ? "theme" : "web");
-	const html = await generateHtml(sessionData, palette, opts.themeName);
+	const html = await generateHtml(sessionData, palette, opts.themeNames, opts.themeName);
 	const outputPath = opts.outputPath || `${APP_NAME}-session-${path.basename(sessionFile, ".jsonl")}.html`;
 
 	await Bun.write(outputPath, html);
@@ -300,7 +298,7 @@ export async function exportFromFile(inputPath: string, options?: ExportOptions
 	}
 
 	const palette = opts.palette ?? (opts.themeName ? "theme" : "web");
-	const html = await generateHtml(sessionData, palette, opts.themeName);
+	const html = await generateHtml(sessionData, palette, opts.themeNames, opts.themeName);
 	const outputPath = opts.outputPath || `${APP_NAME}-session-${path.basename(inputPath, ".jsonl")}.html`;
 
 	await Bun.write(outputPath, html);

package/src/export/html/template.css

@@ -104,11 +104,14 @@
     }
 
     .sidebar-controls {
+      display: flex;
+      gap: 6px;
       padding: 0 0 6px;
     }
 
     .sidebar-search {
-      width: 100%;
+      flex: 1;
+      min-width: 0;
       box-sizing: border-box;
       padding: 5px 9px;
       font-size: 11px;
@@ -138,6 +141,21 @@
       color: var(--muted);
     }
 
+    .theme-select {
+      padding: 5px 8px;
+      font: inherit;
+      font-size: 10px;
+      background: var(--body-bg);
+      color: var(--text);
+      border: 1px solid var(--hairline);
+      border-radius: var(--radius-ctl);
+      cursor: pointer;
+    }
+
+    .theme-select:hover {
+      border-color: var(--hairline-strong);
+    }
+
     .sidebar-filters {
       display: flex;
       gap: 4px;

package/src/export/html/template.html

@@ -8,6 +8,7 @@
   <title>Session Export</title>
   <template-css/>
   <theme-vars/>
+  <script>try{const t=localStorage.getItem("omp-export-theme");if(t==="light"||t==="dark")document.documentElement.dataset.theme=t}catch{}</script>
 </head>
 <body>
   <button id="hamburger" title="Open sidebar" aria-label="Open sidebar"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" aria-hidden="true"><path d="M3 6h18M3 12h18M3 18h18"/></svg></button>
@@ -17,6 +18,11 @@
       <div class="sidebar-header">
         <div class="sidebar-controls">
           <input type="text" class="sidebar-search" id="tree-search" placeholder="Search entries…" autocomplete="off" spellcheck="false">
+          <select class="theme-select" id="theme-select" title="Color theme" aria-label="Color theme">
+            <option value="auto">Auto</option>
+            <option value="light">Light</option>
+            <option value="dark">Dark</option>
+          </select>
         </div>
         <div class="sidebar-filters">
           <button class="filter-btn active" data-filter="default" title="Hide settings entries">Default</button>

package/src/export/html/template.js

@@ -1,6 +1,27 @@
     (function() {
       'use strict';
 
+      const THEME_STORAGE_KEY = 'omp-export-theme';
+      const themeSelect = document.getElementById('theme-select');
+      let themePreference = 'auto';
+      try {
+        const stored = localStorage.getItem(THEME_STORAGE_KEY);
+        if (stored === 'light' || stored === 'dark' || stored === 'auto') themePreference = stored;
+      } catch {}
+
+      function applyThemePreference(next) {
+        themePreference = next;
+        if (next === 'light' || next === 'dark') document.documentElement.dataset.theme = next;
+        else delete document.documentElement.dataset.theme;
+        if (themeSelect) themeSelect.value = next;
+        try {
+          localStorage.setItem(THEME_STORAGE_KEY, next);
+        } catch {}
+      }
+
+      applyThemePreference(themePreference);
+      if (themeSelect) themeSelect.addEventListener('change', () => applyThemePreference(themeSelect.value));
+
       // ============================================================
       // BOOT
       // ============================================================