feat(tui): add automatic light theme selection

Author: TheGreatAxios

src/config/settings.ts

@@ -186,6 +186,9 @@ export interface Settings {
   // results on the outgoing prompt only. Default off: sessions do not depend
   // on that shrink.
   anthropicCachePrompt?: boolean;
+  // Terminal palette selection (CL-8993). "auto" (default when unset) follows
+  // the terminal/OS detection chain; "light"/"dark" pin the palette.
+  theme?: "auto" | "light" | "dark";
 }
 
 function modelRefKey(ref: ModelRef): string {
@@ -599,6 +602,7 @@ const SettingsSchema = type({
   "showPromptCost?": "boolean",
   "dangerouslySkipPermissions?": "boolean",
   "anthropicCachePrompt?": "boolean",
+  "theme?": "'auto' | 'light' | 'dark'",
 });
 
 // Per-entry MCP shape without the name key. The "exactly one transport" rule is
@@ -803,6 +807,7 @@ export const GLOBAL_SETTINGS_OPTIONAL_KEYS = [
   "favoriteModels",
   "dangerouslySkipPermissions",
   "anthropicCachePrompt",
+  "theme",
 ] as const satisfies readonly (keyof OptionalSettingsFields)[];
 
 /** Optional local settings keys the load path is required to consider. */
@@ -974,6 +979,10 @@ function normalizeParsedSettings(path: string, parsed: unknown): Settings {
       s.anthropicCachePrompt !== undefined
         ? Boolean(s.anthropicCachePrompt)
         : undefined,
+    theme:
+      s.theme === "light" || s.theme === "dark" || s.theme === "auto"
+        ? s.theme
+        : undefined,
   };
   return {
     providers: s.providers as Settings["providers"],

src/tui/runner/index.ts

@@ -37,6 +37,12 @@ import { wireMcp } from "./mcp.js";
 import { wirePostStartup } from "./wiring.js";
 import { createRunnerState, liveAgent } from "./state.js";
 import { applyCredentialRecoverySelection } from "./credential-recovery.js";
+import { setTheme } from "../theme.js";
+import {
+  resolveDetectedTheme,
+  resolveThemeSetting,
+  syncEnvFromRecord,
+} from "../theme-detect.js";
 import { getLogger } from "@intx/log";
 import { LOG_NAMESPACE_ROOT } from "../../branding.js";
 
@@ -52,6 +58,19 @@ export async function runTUI(initialConfig: Config): Promise<number> {
   if (start === null) return 0;
   const state = createRunnerState(start);
 
+  // Sync theme answer (CL-8993): the explicit setting wins, else the
+  // COLORFGBG/TERM_PROGRAM sniff, else dark. Paints correctly on first frame;
+  // the async OS-appearance upgrade in wirePostStartup repaints if it lands
+  // lighter. Unknown terminals stay dark.
+  setTheme(
+    resolveDetectedTheme({
+      setting: resolveThemeSetting(state.config.settings?.theme),
+      syncEnv: syncEnvFromRecord(process.env),
+      osc: null,
+      os: null,
+    }),
+  );
+
   const { pluginModules } = start.trust;
   // /plugins UI backend state: discovered modules plus live, persisted config
   // (enabled flag, credentials, web override, extra paths). Trust grants swap

src/tui/runner/wiring.ts

@@ -7,6 +7,7 @@
  */
 
 import { getLogger } from "@intx/log";
+import { spawnSync } from "node:child_process";
 import {
   loadSettings,
   listFavoriteModels,
@@ -47,7 +48,19 @@ import {
   RESUME_TRANSCRIPT_BLOCK_LIMIT,
   turnsToContentBlocks,
 } from "../turns-to-blocks.js";
-import { setPluginNeedsAttention, setStatusFlash } from "../shell/chrome.js";
+import {
+  setPluginNeedsAttention,
+  setStatusFlash,
+  repaintTranscriptWindow,
+} from "../shell/chrome.js";
+import { UI, setTheme } from "../theme.js";
+import {
+  detectOsAppearance,
+  resolveDetectedTheme,
+  resolveThemeSetting,
+  sniffSyncTheme,
+  syncEnvFromRecord,
+} from "../theme-detect.js";
 import {
   setEffortCycleHandler,
   setMentionSuggestionSource,
@@ -490,6 +503,39 @@ export function wirePostStartup(
       });
     });
 
+  // Async theme upgrade (CL-8993): the sync answer already painted, so a
+  // slower OS-appearance read that disagrees swaps the live binding and
+  // repaints once. Fire-and-forget and spawn-capped — a missing `defaults`
+  // binary abstains to dark rather than stalling startup.
+  void (async () => {
+    const setting = resolveThemeSetting(state.config.settings?.theme);
+    if (setting !== "auto") return;
+    const syncEnv = syncEnvFromRecord(process.env);
+    if (sniffSyncTheme(syncEnv) !== null) return;
+    const os = detectOsAppearance(process.platform, (command, args) => {
+      try {
+        const out = spawnSync(command, [...args], {
+          encoding: "utf8",
+          timeout: 500,
+        });
+        if (out.error !== undefined) return undefined;
+        if (out.status !== 0) return null;
+        return typeof out.stdout === "string" ? out.stdout : undefined;
+      } catch {
+        return undefined;
+      }
+    });
+    const next = resolveDetectedTheme({ setting, syncEnv, osc: null, os });
+    if (next === UI.name) return;
+    setTheme(next);
+    const host = services.hostHolder.instance;
+    if (host !== undefined) repaintTranscriptWindow(host.shell);
+  })().catch((err: unknown) => {
+    tuiLogger.debug("async theme detect failed: {error}", {
+      error: err instanceof Error ? err.message : String(err),
+    });
+  });
+
   if (!state.resumeSkipInitialTask && state.config.task.trim().length > 0) {
     // The operator's initial task, typed as a CLI argument before launch —
     // same provenance as a prompt submit.

src/tui/theme-detect.test.ts

@@ -0,0 +1,233 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  detectOsAppearance,
+  parseOsc11Reply,
+  queryTerminalBackground,
+  resolveDetectedTheme,
+  resolveThemeSetting,
+  settingTheme,
+  sniffSyncTheme,
+  syncEnvFromRecord,
+  type ThemeResolution,
+} from "./theme-detect";
+
+const SYNC_UNKNOWN = { syncEnv: {}, osc: null, os: null } as const;
+
+function resolution(over: Partial<ThemeResolution>): ThemeResolution {
+  return {
+    setting: "auto",
+    syncEnv: {},
+    osc: null,
+    os: null,
+    ...over,
+  };
+}
+
+describe("resolveThemeSetting", () => {
+  test("accepts auto, light, and dark", () => {
+    expect(resolveThemeSetting("auto")).toBe("auto");
+    expect(resolveThemeSetting("light")).toBe("light");
+    expect(resolveThemeSetting("dark")).toBe("dark");
+  });
+
+  test("unknown values fall back to auto", () => {
+    for (const raw of [undefined, null, "", "blue", 1, {}, []]) {
+      expect(resolveThemeSetting(raw)).toBe("auto");
+    }
+  });
+});
+
+describe("sniffSyncTheme", () => {
+  test("dark COLORFGBG backgrounds resolve dark", () => {
+    expect(sniffSyncTheme({ COLORFGBG: "15;0" })).toBe("corbits-dark");
+    expect(sniffSyncTheme({ COLORFGBG: "0;default;15" })).toBeNull();
+    expect(sniffSyncTheme({ COLORFGBG: "7;8" })).toBe("corbits-dark");
+  });
+
+  test("light COLORFGBG backgrounds resolve light", () => {
+    expect(sniffSyncTheme({ COLORFGBG: "0;15" })).toBe("corbits-light");
+    expect(sniffSyncTheme({ COLORFGBG: "0;7" })).toBe("corbits-light");
+  });
+
+  test("default and missing backgrounds abstain", () => {
+    expect(sniffSyncTheme({})).toBeNull();
+    expect(sniffSyncTheme({ COLORFGBG: "" })).toBeNull();
+    expect(sniffSyncTheme({ COLORFGBG: "0;default;15" })).toBeNull();
+    expect(sniffSyncTheme({ COLORFGBG: "bogus" })).toBeNull();
+  });
+
+  test("TERM_PROGRAM alone never decides", () => {
+    expect(sniffSyncTheme({ TERM_PROGRAM: "iTerm.app" })).toBeNull();
+    expect(sniffSyncTheme({ TERM_PROGRAM: "Apple_Terminal" })).toBeNull();
+  });
+});
+
+describe("parseOsc11Reply", () => {
+  test("dark replies resolve dark, light replies resolve light", () => {
+    expect(parseOsc11Reply("\u001b]11;rgb:1919/1616/1414\u001b\\")).toBe(
+      "corbits-dark",
+    );
+    expect(parseOsc11Reply("\u001b]11;rgb:f7f7/eaea/d5d5\u001b\\")).toBe(
+      "corbits-light",
+    );
+  });
+
+  test("garbage abstains dark-first", () => {
+    expect(parseOsc11Reply("")).toBeNull();
+    expect(parseOsc11Reply("not-a-reply")).toBeNull();
+    expect(parseOsc11Reply("\u001b]11;rgb:zz/zz/zz\u001b\\")).toBeNull();
+  });
+});
+
+describe("queryTerminalBackground", () => {
+  test("resolves the queried theme", async () => {
+    await expect(
+      queryTerminalBackground(async () => "rgb:f7f7/eaea/d5d5", 50),
+    ).resolves.toBe("corbits-light");
+  });
+
+  test("a silent terminal times out instead of hanging", async () => {
+    const start = Date.now();
+    await expect(
+      queryTerminalBackground(
+        () =>
+          new Promise<null>((resolve) => {
+            void resolve;
+          }),
+        20,
+      ),
+    ).resolves.toBeNull();
+    expect(Date.now() - start).toBeLessThan(1000);
+  });
+
+  test("a throwing transport resolves null", async () => {
+    await expect(
+      queryTerminalBackground(async () => {
+        throw new Error("no tty");
+      }, 50),
+    ).resolves.toBeNull();
+  });
+});
+
+describe("detectOsAppearance", () => {
+  test("macOS Dark reads dark", () => {
+    expect(detectOsAppearance("darwin", () => "Dark\n")).toBe("corbits-dark");
+  });
+
+  test("macOS without the key means the Light default", () => {
+    expect(detectOsAppearance("darwin", () => null)).toBe("corbits-light");
+  });
+
+  test("detector failures abstain", () => {
+    expect(detectOsAppearance("darwin", () => undefined)).toBeNull();
+    expect(
+      detectOsAppearance("darwin", () => {
+        throw new Error("defaults unavailable");
+      }),
+    ).toBeNull();
+  });
+
+  test("other platforms abstain", () => {
+    const fail = (): string | null => {
+      throw new Error("must not run");
+    };
+    expect(detectOsAppearance("linux", fail)).toBeNull();
+    expect(detectOsAppearance("win32", fail)).toBeNull();
+  });
+});
+
+describe("resolveDetectedTheme precedence", () => {
+  test("unknown everything stays dark", () => {
+    expect(resolveDetectedTheme(resolution({}))).toBe("corbits-dark");
+  });
+
+  test("explicit setting beats every signal", () => {
+    expect(
+      resolveDetectedTheme(
+        resolution({
+          setting: "light",
+          syncEnv: { COLORFGBG: "15;0" },
+          osc: "corbits-dark",
+          os: "corbits-dark",
+        }),
+      ),
+    ).toBe("corbits-light");
+    expect(
+      resolveDetectedTheme(
+        resolution({
+          setting: "dark",
+          syncEnv: { COLORFGBG: "0;15" },
+          osc: "corbits-light",
+          os: "corbits-light",
+        }),
+      ),
+    ).toBe("corbits-dark");
+  });
+
+  test("sync sniff beats async signals", () => {
+    expect(
+      resolveDetectedTheme(
+        resolution({
+          syncEnv: { COLORFGBG: "0;15" },
+          osc: "corbits-dark",
+          os: "corbits-dark",
+        }),
+      ),
+    ).toBe("corbits-light");
+    expect(
+      resolveDetectedTheme(
+        resolution({
+          syncEnv: { COLORFGBG: "15;0" },
+          osc: "corbits-light",
+          os: "corbits-light",
+        }),
+      ),
+    ).toBe("corbits-dark");
+  });
+
+  test("OSC beats OS appearance", () => {
+    expect(
+      resolveDetectedTheme(
+        resolution({ osc: "corbits-light", os: "corbits-dark" }),
+      ),
+    ).toBe("corbits-light");
+    expect(
+      resolveDetectedTheme(
+        resolution({ osc: "corbits-dark", os: "corbits-light" }),
+      ),
+    ).toBe("corbits-dark");
+  });
+
+  test("OS appearance beats the dark default", () => {
+    expect(resolveDetectedTheme(resolution({ os: "corbits-light" }))).toBe(
+      "corbits-light",
+    );
+  });
+
+  test("setting helper defers on auto", () => {
+    expect(settingTheme("auto")).toBeNull();
+    expect(settingTheme("light")).toBe("corbits-light");
+    expect(settingTheme("dark")).toBe("corbits-dark");
+  });
+
+  test("syncEnvFromRecord picks only the two sniffed vars", () => {
+    expect(
+      syncEnvFromRecord({
+        COLORFGBG: "15;0",
+        TERM_PROGRAM: "iTerm.app",
+        PATH: "/bin",
+      }),
+    ).toEqual({ COLORFGBG: "15;0", TERM_PROGRAM: "iTerm.app" });
+    expect(syncEnvFromRecord({})).toEqual({});
+  });
+
+  test("contrast direction: light ground reads light, dark reads dark", () => {
+    expect({ ...SYNC_UNKNOWN }).toBeDefined();
+    expect(
+      resolveDetectedTheme(resolution({ syncEnv: { COLORFGBG: "0;15" } })),
+    ).not.toBe(
+      resolveDetectedTheme(resolution({ syncEnv: { COLORFGBG: "15;0" } })),
+    );
+  });
+});