From d3040e726ace5efb5cd5fe48f14409c4c9241972 Mon Sep 17 00:00:00 2001
From: Factory Agent <agent@factory.dev>
Date: Fri, 23 Oct 2026 16:55:47 +0700
Subject: [PATCH 1/3] Follow the Windows app theme in Settings under auto

---
 apps/desktop-tauri/scripts/proof-check.mjs    |   9 +-
 .../scripts/proof-scenarios.json              |  22 ++++
 .../src-tauri/src/commands/system.rs          |  49 +++++++
 apps/desktop-tauri/src-tauri/src/main.rs      |   1 +
 apps/desktop-tauri/src/App.tsx                |   6 +-
 apps/desktop-tauri/src/hooks/useTheme.test.ts | 123 +++++++++++++++++-
 apps/desktop-tauri/src/hooks/useTheme.ts      |  75 ++++++++++-
 apps/desktop-tauri/src/lib/tauri.ts           |   5 +
 apps/desktop-tauri/src/proof/install.ts       |   7 +-
 apps/desktop-tauri/src/proof/params.ts        |  11 ++
 apps/desktop-tauri/src/proof/router.test.ts   |  27 +++-
 apps/desktop-tauri/src/proof/router.ts        |   3 +
 docs/WINDOWS_PROOF.md                         |   1 +
 13 files changed, 321 insertions(+), 18 deletions(-)

diff --git a/apps/desktop-tauri/scripts/proof-check.mjs b/apps/desktop-tauri/scripts/proof-check.mjs
index d54851a31ea..a7a62a9abce 100644
--- a/apps/desktop-tauri/scripts/proof-check.mjs
+++ b/apps/desktop-tauri/scripts/proof-check.mjs
@@ -15,7 +15,7 @@
 // Scenario steps (scripts/proof-scenarios.json), run in order:
 //   expectText / expectNoText   page text includes / excludes each string
 //   expectSelector              a DOM selector matches
-//   expectTheme                 documentElement dataset.theme
+//   expectTheme                 documentElement dataset.theme (waits for the value)
 //   expectField                 a native <select> by label: value, options, enabled
 //   expectCall                  a backend command was invoked (optional args match)
 //   expectNoCall                a backend command was not invoked (waits 300 ms first)
@@ -384,8 +384,11 @@ async function runStep(page, step, ctx) {
       .map((el) => el.textContent)`);
     if (clipped.length > 0) throw new Error(`text clipped in ${step.expectNoOverflow}: ${js(clipped)}`);
   } else if (step.expectTheme !== undefined) {
-    const theme = await page.eval("document.documentElement.dataset.theme");
-    if (theme !== step.expectTheme) throw new Error(`theme is ${js(theme)}, expected ${js(step.expectTheme)}`);
+    // Polled: under `auto` the theme arrives after an async shell read.
+    const theme = "document.documentElement.dataset.theme";
+    if (!(await page.poll(`${theme} === ${js(step.expectTheme)}`))) {
+      throw new Error(`theme is ${js(await page.eval(theme))}, expected ${js(step.expectTheme)}`);
+    }
   } else if (step.click !== undefined) {
     // `near` picks, among same-label matches, the one whose closest ancestor
     // containing that text is nearest (e.g. the Switch button of one account row).
diff --git a/apps/desktop-tauri/scripts/proof-scenarios.json b/apps/desktop-tauri/scripts/proof-scenarios.json
index ad5dfad7617..c754acd7acc 100644
--- a/apps/desktop-tauri/scripts/proof-scenarios.json
+++ b/apps/desktop-tauri/scripts/proof-scenarios.json
@@ -218,6 +218,28 @@
         { "screenshot": "settings-general-light" }
       ]
     },
+    {
+      "name": "settings-auto-follows-windows-light",
+      "query": "window=settings&tab=general&theme=auto&system=light",
+      "size": [880, 620],
+      "steps": [
+        { "expectCall": { "cmd": "get_system_theme" } },
+        { "expectTheme": "light" },
+        { "expectText": "Refresh interval" },
+        { "screenshot": "settings-auto-follows-windows-light" }
+      ]
+    },
+    {
+      "name": "settings-auto-follows-windows-dark",
+      "query": "window=settings&tab=general&theme=auto&system=dark",
+      "size": [880, 620],
+      "steps": [
+        { "expectCall": { "cmd": "get_system_theme" } },
+        { "expectTheme": "dark" },
+        { "expectText": "Refresh interval" },
+        { "screenshot": "settings-auto-follows-windows-dark" }
+      ]
+    },
     {
       "name": "settings-providers",
       "query": "window=settings&tab=providers&theme=dark",
diff --git a/apps/desktop-tauri/src-tauri/src/commands/system.rs b/apps/desktop-tauri/src-tauri/src/commands/system.rs
index 146561cd447..12e820969cc 100644
--- a/apps/desktop-tauri/src-tauri/src/commands/system.rs
+++ b/apps/desktop-tauri/src-tauri/src/commands/system.rs
@@ -204,6 +204,44 @@ fn abgr_to_hex(value: u32) -> String {
     format!("#{r:02x}{g:02x}{b:02x}")
 }
 
+/// The Windows app-theme setting (`"light"` or `"dark"`) for the Settings
+/// window under the `auto` theme.
+///
+/// Every native window is pinned to Dark (see `shell/settings_window.rs`), so
+/// `prefers-color-scheme` inside the webview always reports dark. This reads
+/// the OS setting directly instead.
+#[tauri::command]
+pub fn get_system_theme() -> String {
+    theme_from_apps_use_light(apps_use_light_theme_value()).to_string()
+}
+
+/// Maps `HKCU\...\Themes\Personalize\AppsUseLightTheme` to a theme name.
+/// Only a non-zero value means light. A zero, a missing value or a read error
+/// resolves to dark, the theme these windows used before the OS was read.
+fn theme_from_apps_use_light(value: Option<u32>) -> &'static str {
+    match value {
+        Some(0) | None => "dark",
+        Some(_) => "light",
+    }
+}
+
+#[cfg(windows)]
+fn apps_use_light_theme_value() -> Option<u32> {
+    use winreg::RegKey;
+    use winreg::enums::HKEY_CURRENT_USER;
+
+    RegKey::predef(HKEY_CURRENT_USER)
+        .open_subkey(r"Software\Microsoft\Windows\CurrentVersion\Themes\Personalize")
+        .ok()?
+        .get_value::<u32, _>("AppsUseLightTheme")
+        .ok()
+}
+
+#[cfg(not(windows))]
+fn apps_use_light_theme_value() -> Option<u32> {
+    None
+}
+
 #[tauri::command]
 pub fn play_notification_sound(
     event: codexbar::sound::NotificationSoundEvent,
@@ -500,4 +538,15 @@ mod tests {
         assert_eq!(find_copilot_account_by_identity(&accounts, 123), Some(1));
         assert!(copilot_label_matches_login(&legacy, Some("octocat")));
     }
+
+    #[test]
+    fn apps_use_light_theme_nonzero_reads_as_light() {
+        assert_eq!(theme_from_apps_use_light(Some(1)), "light");
+    }
+
+    #[test]
+    fn apps_use_light_theme_zero_or_unreadable_reads_as_dark() {
+        assert_eq!(theme_from_apps_use_light(Some(0)), "dark");
+        assert_eq!(theme_from_apps_use_light(None), "dark");
+    }
 }
diff --git a/apps/desktop-tauri/src-tauri/src/main.rs b/apps/desktop-tauri/src-tauri/src/main.rs
index 632a84e8fce..dc1f9a5b8e1 100644
--- a/apps/desktop-tauri/src-tauri/src/main.rs
+++ b/apps/desktop-tauri/src-tauri/src/main.rs
@@ -339,6 +339,7 @@ fn main() {
             commands::unregister_global_shortcut,
             commands::get_work_area_rect,
             commands::get_system_accent_color,
+            commands::get_system_theme,
             commands::play_notification_sound,
             commands::open_external_url,
             commands::reanchor_tray_panel,
diff --git a/apps/desktop-tauri/src/App.tsx b/apps/desktop-tauri/src/App.tsx
index fc9c8c3e99e..019e0b54e74 100644
--- a/apps/desktop-tauri/src/App.tsx
+++ b/apps/desktop-tauri/src/App.tsx
@@ -63,7 +63,11 @@ function AppInner() {
   const [error, setError] = useState<string | null>(null);
   const [themePreference, setThemePreference] = useState<ThemePreference>("dark");
 
-  useTheme(themePreference);
+  // Settings follows the Windows app theme under `auto`; the other surfaces
+  // keep the pinned-Dark media query.
+  useTheme(themePreference, {
+    followSystem: isSettingsWindow() || surface.mode === "settings",
+  });
   useDeepSeekPricingStatus();
 
   const reloadBootstrapState = useCallback(
diff --git a/apps/desktop-tauri/src/hooks/useTheme.test.ts b/apps/desktop-tauri/src/hooks/useTheme.test.ts
index 546bc5024bc..8ce09b1eb19 100644
--- a/apps/desktop-tauri/src/hooks/useTheme.test.ts
+++ b/apps/desktop-tauri/src/hooks/useTheme.test.ts
@@ -1,5 +1,43 @@
-import { describe, expect, it, vi } from "vitest";
-import { resolveTheme } from "./useTheme";
+import { act, cleanup, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { getSystemTheme } from "../lib/tauri";
+import { resolveTheme, useTheme } from "./useTheme";
+
+vi.mock("../lib/tauri", () => ({ getSystemTheme: vi.fn() }));
+
+const mockedGetSystemTheme = vi.mocked(getSystemTheme);
+
+/** The webview's own media query, which every pinned window reports as dark. */
+function stubMediaQuery(lightPreferred: boolean) {
+  vi.stubGlobal("matchMedia", (query: string) => ({
+    matches: query === "(prefers-color-scheme: light)" && lightPreferred,
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+  }));
+}
+
+function setTauriBridge(present: boolean) {
+  if (present) {
+    Object.defineProperty(window, "__TAURI_INTERNALS__", {
+      value: {},
+      configurable: true,
+      writable: true,
+    });
+  } else {
+    delete (window as unknown as Record<string, unknown>).__TAURI_INTERNALS__;
+  }
+}
+
+beforeEach(() => {
+  mockedGetSystemTheme.mockReset();
+  document.documentElement.removeAttribute("data-theme");
+});
+
+afterEach(() => {
+  cleanup();
+  setTauriBridge(false);
+  vi.unstubAllGlobals();
+});
 
 describe("resolveTheme", () => {
   it("uses the OS light preference in auto mode", () => {
@@ -19,4 +57,85 @@ describe("resolveTheme", () => {
 
     vi.unstubAllGlobals();
   });
+
+  it("takes the system signal from the caller when one is given", () => {
+    expect(resolveTheme("auto", true)).toBe("light");
+    expect(resolveTheme("auto", false)).toBe("dark");
+    expect(resolveTheme("light", false)).toBe("light");
+    expect(resolveTheme("dark", true)).toBe("dark");
+  });
+});
+
+describe("useTheme", () => {
+  it("applies the Windows app theme under Tauri when following the system", async () => {
+    setTauriBridge(true);
+    stubMediaQuery(false);
+    mockedGetSystemTheme.mockResolvedValue("light");
+
+    renderHook(() => useTheme("auto", { followSystem: true }));
+
+    await waitFor(() => expect(document.documentElement.dataset.theme).toBe("light"));
+    expect(document.documentElement.style.colorScheme).toBe("light");
+    expect(mockedGetSystemTheme).toHaveBeenCalled();
+  });
+
+  it("keeps the media query for windows that do not follow the system", async () => {
+    setTauriBridge(true);
+    stubMediaQuery(false);
+    mockedGetSystemTheme.mockResolvedValue("light");
+
+    renderHook(() => useTheme("auto"));
+
+    expect(document.documentElement.dataset.theme).toBe("dark");
+    expect(mockedGetSystemTheme).not.toHaveBeenCalled();
+  });
+
+  it("uses the media query when following the system outside Tauri", () => {
+    setTauriBridge(false);
+    stubMediaQuery(true);
+
+    renderHook(() => useTheme("auto", { followSystem: true }));
+
+    expect(document.documentElement.dataset.theme).toBe("light");
+    expect(mockedGetSystemTheme).not.toHaveBeenCalled();
+  });
+
+  it("ignores the system theme for explicit overrides", () => {
+    setTauriBridge(true);
+    mockedGetSystemTheme.mockResolvedValue("light");
+
+    renderHook(() => useTheme("dark", { followSystem: true }));
+
+    expect(document.documentElement.dataset.theme).toBe("dark");
+    expect(mockedGetSystemTheme).not.toHaveBeenCalled();
+  });
+
+  it("re-reads the Windows theme when settings change", async () => {
+    setTauriBridge(true);
+    mockedGetSystemTheme.mockResolvedValueOnce("dark").mockResolvedValueOnce("light");
+
+    renderHook(() => useTheme("auto", { followSystem: true }));
+    await waitFor(() => expect(document.documentElement.dataset.theme).toBe("dark"));
+
+    act(() => {
+      window.dispatchEvent(new Event("codexbar:settings-updated"));
+    });
+
+    await waitFor(() => expect(document.documentElement.dataset.theme).toBe("light"));
+    expect(mockedGetSystemTheme).toHaveBeenCalledTimes(2);
+  });
+
+  it("re-reads the Windows theme when the window regains focus", async () => {
+    setTauriBridge(true);
+    mockedGetSystemTheme.mockResolvedValueOnce("dark").mockResolvedValueOnce("light");
+
+    renderHook(() => useTheme("auto", { followSystem: true }));
+    await waitFor(() => expect(document.documentElement.dataset.theme).toBe("dark"));
+
+    act(() => {
+      window.dispatchEvent(new Event("focus"));
+    });
+
+    await waitFor(() => expect(document.documentElement.dataset.theme).toBe("light"));
+  });
 });
diff --git a/apps/desktop-tauri/src/hooks/useTheme.ts b/apps/desktop-tauri/src/hooks/useTheme.ts
index 3894dc6bc10..ec33eac7e61 100644
--- a/apps/desktop-tauri/src/hooks/useTheme.ts
+++ b/apps/desktop-tauri/src/hooks/useTheme.ts
@@ -1,9 +1,12 @@
 import { useEffect } from "react";
+import { getSystemTheme } from "../lib/tauri";
 import type { ThemePreference } from "../types/bridge";
 
 export type ResolvedTheme = "light" | "dark";
 
 const MEDIA_QUERY = "(prefers-color-scheme: light)";
+/** How often a visible Settings window re-reads the Windows theme. */
+const SYSTEM_THEME_POLL_MS = 30_000;
 
 function prefersLight(): boolean {
   if (typeof window === "undefined" || !window.matchMedia) {
@@ -12,10 +15,18 @@ function prefersLight(): boolean {
   return window.matchMedia(MEDIA_QUERY).matches;
 }
 
-export function resolveTheme(preference: ThemePreference): ResolvedTheme {
+/** True inside the Tauri shell. The browser proof's `mockIPC` sets the same global. */
+function hasTauriBridge(): boolean {
+  return typeof window !== "undefined" && "__TAURI_INTERNALS__" in window;
+}
+
+export function resolveTheme(
+  preference: ThemePreference,
+  systemLight: boolean = prefersLight(),
+): ResolvedTheme {
   if (preference === "light") return "light";
   if (preference === "dark") return "dark";
-  return prefersLight() ? "light" : "dark";
+  return systemLight ? "light" : "dark";
 }
 
 function apply(theme: ResolvedTheme) {
@@ -24,15 +35,65 @@ function apply(theme: ResolvedTheme) {
   document.documentElement.style.colorScheme = theme;
 }
 
+/**
+ * Applies the Windows app theme read through the shell. Every native window is
+ * pinned Dark, so the webview's media query can't report the OS setting. The
+ * shell is re-asked on focus, on settings changes, and every
+ * SYSTEM_THEME_POLL_MS while the window is visible. No theme-change event is
+ * used: the pinned theme may suppress one.
+ */
+function followWindowsTheme(): () => void {
+  let cancelled = false;
+  const sync = () => {
+    getSystemTheme()
+      .then((theme) => {
+        if (!cancelled) apply(theme);
+      })
+      .catch(() => {});
+  };
+  sync();
+
+  const timer = window.setInterval(() => {
+    if (document.visibilityState === "visible") sync();
+  }, SYSTEM_THEME_POLL_MS);
+  window.addEventListener("focus", sync);
+  document.addEventListener("visibilitychange", sync);
+  window.addEventListener("codexbar:settings-updated", sync);
+
+  return () => {
+    cancelled = true;
+    window.clearInterval(timer);
+    window.removeEventListener("focus", sync);
+    document.removeEventListener("visibilitychange", sync);
+    window.removeEventListener("codexbar:settings-updated", sync);
+  };
+}
+
+export interface UseThemeOptions {
+  /**
+   * Follow the Windows app theme when the preference is `auto`. Only the
+   * Settings surface sets this; other windows keep the media query, which
+   * reads dark on every pinned window.
+   */
+  followSystem?: boolean;
+}
+
 /**
  * Applies the user's theme preference at runtime.
  *
- * When `preference === "auto"`, subscribes to `prefers-color-scheme` so the
- * UI flips along with the OS. Explicit "light"/"dark" overrides detach from
- * the media query.
+ * When `preference === "auto"`, the UI follows the OS: the Windows app-theme
+ * setting when `followSystem` is set under Tauri, otherwise the
+ * `prefers-color-scheme` media query. Explicit "light"/"dark" overrides detach
+ * from both.
  */
-export function useTheme(preference: ThemePreference): void {
+export function useTheme(preference: ThemePreference, options: UseThemeOptions = {}): void {
+  const followSystem = options.followSystem === true;
+
   useEffect(() => {
+    if (preference === "auto" && followSystem && hasTauriBridge()) {
+      return followWindowsTheme();
+    }
+
     apply(resolveTheme(preference));
 
     if (preference !== "auto" || typeof window === "undefined" || !window.matchMedia) {
@@ -49,5 +110,5 @@ export function useTheme(preference: ThemePreference): void {
     // Safari < 14 fallback.
     mq.addListener(handle);
     return () => mq.removeListener(handle);
-  }, [preference]);
+  }, [preference, followSystem]);
 }
diff --git a/apps/desktop-tauri/src/lib/tauri.ts b/apps/desktop-tauri/src/lib/tauri.ts
index 1d1b6dcdbd9..e69a5a7e17e 100644
--- a/apps/desktop-tauri/src/lib/tauri.ts
+++ b/apps/desktop-tauri/src/lib/tauri.ts
@@ -661,6 +661,11 @@ export function getSystemAccentColor(): Promise<string | null> {
   return invoke<string | null>("get_system_accent_color");
 }
 
+/** The Windows app-theme setting; the native windows are pinned Dark, so the webview cannot read it. */
+export function getSystemTheme(): Promise<"light" | "dark"> {
+  return invoke<"light" | "dark">("get_system_theme");
+}
+
 export function quitApp(): Promise<void> {
   return invoke<void>("quit_app");
 }
diff --git a/apps/desktop-tauri/src/proof/install.ts b/apps/desktop-tauri/src/proof/install.ts
index 94e6c9a7bb4..f2950c20f3e 100644
--- a/apps/desktop-tauri/src/proof/install.ts
+++ b/apps/desktop-tauri/src/proof/install.ts
@@ -24,7 +24,12 @@ export function installProofMocks(params: ProofParams, now: Date = new Date()):
   if (params.theme) {
     scenario.settings = { ...scenario.settings, theme: params.theme };
   }
-  const router = createProofRouter(scenario, { window: params.window, tab: params.tab, now });
+  const router = createProofRouter(scenario, {
+    window: params.window,
+    tab: params.tab,
+    now,
+    systemTheme: params.systemTheme,
+  });
   const current = windowLabel(params.window);
   const others = PROOF_WINDOWS.map(windowLabel).filter((label) => label !== current);
   mockWindows(current, ...others);
diff --git a/apps/desktop-tauri/src/proof/params.ts b/apps/desktop-tauri/src/proof/params.ts
index 6fccea0dcbe..0cb4e873ab2 100644
--- a/apps/desktop-tauri/src/proof/params.ts
+++ b/apps/desktop-tauri/src/proof/params.ts
@@ -5,6 +5,9 @@ import { isProofScenarioName, type ProofScenarioName } from "./fixtures/scenario
 export const PROOF_WINDOWS = ["main", "settings", "flyout", "floatbar"] as const;
 export type ProofWindow = (typeof PROOF_WINDOWS)[number];
 
+/** The Windows app theme that the `get_system_theme` fixture reports. */
+export type ProofSystemTheme = "light" | "dark";
+
 export interface ProofParams {
   window: ProofWindow;
   /** Raw settings tab request (`general`, `providers:codex`, ...); App parses it. */
@@ -12,6 +15,8 @@ export interface ProofParams {
   fixture: ProofScenarioName;
   /** Overrides the fixture's saved theme when present. */
   theme: ThemePreference | null;
+  /** The Windows app theme (`system=light|dark`); dark when absent. */
+  systemTheme: ProofSystemTheme;
 }
 
 function isProofWindow(value: string): value is ProofWindow {
@@ -22,16 +27,22 @@ function isThemePreference(value: string): value is ThemePreference {
   return value === "dark" || value === "light" || value === "auto";
 }
 
+function isSystemTheme(value: string): value is ProofSystemTheme {
+  return value === "dark" || value === "light";
+}
+
 export function parseProofParams(search: string): ProofParams {
   const params = new URLSearchParams(search);
   const windowParam = params.get("window") ?? "";
   const fixture = params.get("fixture") ?? "";
   const theme = params.get("theme") ?? "";
+  const system = params.get("system") ?? "";
   return {
     window: isProofWindow(windowParam) ? windowParam : "main",
     tab: params.get("tab") || "general",
     fixture: isProofScenarioName(fixture) ? fixture : "default",
     theme: isThemePreference(theme) ? theme : null,
+    systemTheme: isSystemTheme(system) ? system : "dark",
   };
 }
 
diff --git a/apps/desktop-tauri/src/proof/router.test.ts b/apps/desktop-tauri/src/proof/router.test.ts
index 1b8df9fcce1..67f5a254c45 100644
--- a/apps/desktop-tauri/src/proof/router.test.ts
+++ b/apps/desktop-tauri/src/proof/router.test.ts
@@ -163,22 +163,41 @@ describe("proof router", () => {
   });
 });
 
+describe("proof system theme", () => {
+  it("reports the Windows app theme the scenario asks for, dark by default", () => {
+    const light = createProofRouter(buildProofScenario("default", NOW), {
+      window: "settings",
+      tab: "general",
+      now: NOW,
+      systemTheme: "light",
+    });
+    expect(light.handle("get_system_theme")).toBe("light");
+
+    const fallback = routerFor("default", "settings");
+    expect(fallback.handle("get_system_theme")).toBe("dark");
+  });
+});
+
 describe("proof URL params", () => {
   it("falls back to safe defaults", () => {
-    expect(parseProofParams("?window=nope&fixture=nope&theme=nope")).toEqual({
+    expect(parseProofParams("?window=nope&fixture=nope&theme=nope&system=nope")).toEqual({
       window: "main",
       tab: "general",
       fixture: "default",
       theme: null,
+      systemTheme: "dark",
     });
   });
 
-  it("reads window, tab, fixture and theme", () => {
-    expect(parseProofParams("?window=settings&tab=menu&fixture=errors&theme=light")).toEqual({
+  it("reads window, tab, fixture, theme and the system theme", () => {
+    expect(
+      parseProofParams("?window=settings&tab=menu&fixture=errors&theme=auto&system=light"),
+    ).toEqual({
       window: "settings",
       tab: "menu",
       fixture: "errors",
-      theme: "light",
+      theme: "auto",
+      systemTheme: "light",
     });
   });
 });
diff --git a/apps/desktop-tauri/src/proof/router.ts b/apps/desktop-tauri/src/proof/router.ts
index 910a75b9963..10a944747d7 100644
--- a/apps/desktop-tauri/src/proof/router.ts
+++ b/apps/desktop-tauri/src/proof/router.ts
@@ -108,6 +108,8 @@ export interface ProofRouterOptions {
   window: ProofWindow;
   tab: string;
   now?: Date;
+  /** What `get_system_theme` reports (the Windows app theme). Dark when omitted. */
+  systemTheme?: "light" | "dark";
 }
 
 export interface ProofRouter {
@@ -277,6 +279,7 @@ export function createProofRouter(
     apply_http_server_config: (args) =>
       applyHttpServer(argsRecord(args.config) as unknown as HttpServerConfig),
     get_system_accent_color: () => "#4c8bf5",
+    get_system_theme: () => options.systemTheme ?? "dark",
     // A fixed 1080p desktop minus the taskbar: headless browsers report a
     // small `screen`, which would cap the tray panel's auto-fit height.
     get_work_area_rect: () => ({ x: 0, y: 0, width: 1920, height: 1032 }),
diff --git a/docs/WINDOWS_PROOF.md b/docs/WINDOWS_PROOF.md
index 1ad0e2c9eaf..5eaa7a53dc5 100644
--- a/docs/WINDOWS_PROOF.md
+++ b/docs/WINDOWS_PROOF.md
@@ -219,6 +219,7 @@ URL parameters:
 | `tab` | any settings tab id, or `providers:<id>` | `general` |
 | `fixture` | `default`, `two-codex-accounts`, `errors`, `empty`, `claude-plan-hidden`, `kpi-long-titles`, `codex-conversations`, `codex-conversations-private` | `default` |
 | `theme` | `dark`, `light`, `auto` (overrides the fixture) | fixture value |
+| `system` | `dark`, `light`: the Windows app theme that `get_system_theme` reports, which Settings follows under `auto` | `dark` |
 
 Example: `proof.html?window=settings&tab=providers:codex&fixture=two-codex-accounts`.
 

From 9b44e8025081fe3cf3cf366540f5dc01114bd108 Mon Sep 17 00:00:00 2001
From: Factory Agent <agent@factory.dev>
Date: Fri, 23 Oct 2026 17:19:07 +0700
Subject: [PATCH 2/3] Add CODEXBAR_PROOF_SYSTEM_THEME override for proof runs

---
 .../src-tauri/src/commands/system.rs          |  6 +-
 apps/desktop-tauri/src-tauri/src/main.rs      |  1 +
 .../src-tauri/src/proof_harness.rs            | 65 +++++++++++++++++++
 docs/WINDOWS_PROOF.md                         | 10 +++
 4 files changed, 81 insertions(+), 1 deletion(-)

diff --git a/apps/desktop-tauri/src-tauri/src/commands/system.rs b/apps/desktop-tauri/src-tauri/src/commands/system.rs
index 12e820969cc..ec3253c4495 100644
--- a/apps/desktop-tauri/src-tauri/src/commands/system.rs
+++ b/apps/desktop-tauri/src-tauri/src/commands/system.rs
@@ -209,9 +209,13 @@ fn abgr_to_hex(value: u32) -> String {
 ///
 /// Every native window is pinned to Dark (see `shell/settings_window.rs`), so
 /// `prefers-color-scheme` inside the webview always reports dark. This reads
-/// the OS setting directly instead.
+/// the OS setting directly instead. In proof mode, `CODEXBAR_PROOF_SYSTEM_THEME`
+/// replaces the OS read so the `auto` theme can be proven in both directions.
 #[tauri::command]
 pub fn get_system_theme() -> String {
+    if let Some(theme) = crate::proof_harness::system_theme_override() {
+        return theme.to_string();
+    }
     theme_from_apps_use_light(apps_use_light_theme_value()).to_string()
 }
 
diff --git a/apps/desktop-tauri/src-tauri/src/main.rs b/apps/desktop-tauri/src-tauri/src/main.rs
index dc1f9a5b8e1..bb3b7b83b4a 100644
--- a/apps/desktop-tauri/src-tauri/src/main.rs
+++ b/apps/desktop-tauri/src-tauri/src/main.rs
@@ -145,6 +145,7 @@ fn main() {
     let proof_config = proof_harness::ProofConfig::from_env();
     let is_proof_mode = proof_config.is_some();
     proof_harness::install_window_origin_from_env(is_proof_mode);
+    proof_harness::install_system_theme_from_env(is_proof_mode);
     let force_start_visible = std::env::var_os("CODEXBAR_START_VISIBLE").is_some();
     let mut settings = codexbar::settings::Settings::load();
     settings.apply_display_mode_fold_migration();
diff --git a/apps/desktop-tauri/src-tauri/src/proof_harness.rs b/apps/desktop-tauri/src-tauri/src/proof_harness.rs
index 03d508ac218..bfaf2b6e34d 100644
--- a/apps/desktop-tauri/src-tauri/src/proof_harness.rs
+++ b/apps/desktop-tauri/src-tauri/src/proof_harness.rs
@@ -32,6 +32,11 @@
 //! opens the flyout, Settings and float bar windows at that point instead of
 //! their normal placement, so proof runs can keep every window on one chosen
 //! monitor.
+//!
+//! `CODEXBAR_PROOF_SYSTEM_THEME=light|dark` (proof mode only) makes
+//! `get_system_theme` report that Windows app theme, so the `auto` theme can be
+//! proven in both directions without changing the real OS setting. Any other
+//! value is ignored.
 
 use std::collections::HashSet;
 use std::sync::{Mutex, OnceLock};
@@ -315,6 +320,48 @@ pub fn is_proof_mode(app: &AppHandle) -> bool {
 
 // ── Window origin (CODEXBAR_PROOF_WINDOW_ORIGIN) ─────────────────────
 
+// ── System theme (CODEXBAR_PROOF_SYSTEM_THEME) ───────────────────────
+
+/// Environment variable naming the app theme (`light` or `dark`) that
+/// `get_system_theme` reports. Honored only in proof mode.
+pub const SYSTEM_THEME_ENV_VAR: &str = "CODEXBAR_PROOF_SYSTEM_THEME";
+
+static SYSTEM_THEME: OnceLock<&'static str> = OnceLock::new();
+
+/// Read `CODEXBAR_PROOF_SYSTEM_THEME` once at startup. Outside proof mode,
+/// or when the value is unset or invalid, nothing is installed and
+/// `get_system_theme` reads the OS setting.
+pub fn install_system_theme_from_env(proof_mode: bool) {
+    let raw = std::env::var(SYSTEM_THEME_ENV_VAR).ok();
+    if let Some(theme) = proof_system_theme(proof_mode, raw.as_deref()) {
+        tracing::info!("proof-harness: system theme {theme}");
+        let _ = SYSTEM_THEME.set(theme);
+    }
+}
+
+/// The proof theme override, when one was installed at startup.
+pub fn system_theme_override() -> Option<&'static str> {
+    SYSTEM_THEME.get().copied()
+}
+
+/// Gate for `CODEXBAR_PROOF_SYSTEM_THEME`. Returns `None` outside proof mode,
+/// when the value is unset or blank, and when it is not `light` or `dark`.
+fn proof_system_theme(proof_mode: bool, raw: Option<&str>) -> Option<&'static str> {
+    let raw = raw.map(str::trim).filter(|raw| !raw.is_empty())?;
+    if !proof_mode {
+        tracing::warn!("{SYSTEM_THEME_ENV_VAR} is ignored outside proof mode");
+        return None;
+    }
+    match raw.to_ascii_lowercase().as_str() {
+        "light" => Some("light"),
+        "dark" => Some("dark"),
+        _ => {
+            tracing::warn!("{SYSTEM_THEME_ENV_VAR}: expected 'light' or 'dark', ignoring");
+            None
+        }
+    }
+}
+
 /// Environment variable with a `<x>,<y>` physical-pixel origin for proof
 /// windows. Honored only in proof mode.
 pub const WINDOW_ORIGIN_ENV_VAR: &str = "CODEXBAR_PROOF_WINDOW_ORIGIN";
@@ -1086,6 +1133,24 @@ mod tests {
         }
     }
 
+    #[test]
+    fn system_theme_is_honored_only_in_proof_mode() {
+        assert_eq!(proof_system_theme(true, Some("light")), Some("light"));
+        assert_eq!(proof_system_theme(true, Some(" Dark ")), Some("dark"));
+        assert_eq!(proof_system_theme(false, Some("light")), None);
+        assert_eq!(proof_system_theme(false, Some("dark")), None);
+    }
+
+    #[test]
+    fn system_theme_ignores_unset_blank_and_invalid_values() {
+        assert_eq!(proof_system_theme(true, None), None);
+        assert_eq!(proof_system_theme(true, Some("")), None);
+        assert_eq!(proof_system_theme(true, Some("   ")), None);
+        for raw in ["auto", "system", "lightish", "1"] {
+            assert_eq!(proof_system_theme(true, Some(raw)), None, "{raw}");
+        }
+    }
+
     #[test]
     fn window_origin_env_is_honored_only_in_proof_mode() {
         with_window_origin_env(Some("-3600,-1188"), || {
diff --git a/docs/WINDOWS_PROOF.md b/docs/WINDOWS_PROOF.md
index 5eaa7a53dc5..8e7ffdf194c 100644
--- a/docs/WINDOWS_PROOF.md
+++ b/docs/WINDOWS_PROOF.md
@@ -86,6 +86,16 @@ When it is set in proof mode:
 
 The app ignores the variable outside proof mode. It logs a warning and uses normal placement when the value isn't two whole numbers separated by a comma, or when no monitor contains the point.
 
+### Report a fixed system theme
+
+`CODEXBAR_PROOF_SYSTEM_THEME` makes the app report a fixed Windows app theme to `get_system_theme`. The `auto` theme in Settings then follows that value, so both directions can be proven without changing the real OS setting.
+
+```powershell
+$env:CODEXBAR_PROOF_SYSTEM_THEME = 'light'   # or 'dark'
+```
+
+It takes effect only in proof mode and accepts `light` or `dark`, case-insensitive. Outside proof mode the app logs a warning and reads the OS setting. An unset or blank value, or any other value, is ignored, and the app reads the OS setting. The override changes only what the app reports. It does not change the Windows setting, so the DWM caption, scrollbars and `<select>` popups keep their pinned dark theme.
+
 ## Drive the app
 
 Drive the app without taking the user's focus or keyboard. Don't use cua-driver's `bring_to_front`, foreground mode, `hotkey` or `type_text`.

From 5616e5c9f27eb2be4d44f0505e2912c46da10fc9 Mon Sep 17 00:00:00 2001
From: Factory Agent <agent@factory.dev>
Date: Sat, 24 Oct 2026 06:44:38 +0700
Subject: [PATCH 3/3] Apply only the latest Windows theme read in Settings

---
 apps/desktop-tauri/src/hooks/useTheme.test.ts | 26 +++++++++++++++++++
 apps/desktop-tauri/src/hooks/useTheme.ts      |  5 +++-
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/apps/desktop-tauri/src/hooks/useTheme.test.ts b/apps/desktop-tauri/src/hooks/useTheme.test.ts
index 8ce09b1eb19..0e1cee2d008 100644
--- a/apps/desktop-tauri/src/hooks/useTheme.test.ts
+++ b/apps/desktop-tauri/src/hooks/useTheme.test.ts
@@ -138,4 +138,30 @@ describe("useTheme", () => {
 
     await waitFor(() => expect(document.documentElement.dataset.theme).toBe("light"));
   });
+
+  it("does not let an older read that finishes last replace a newer one", async () => {
+    setTauriBridge(true);
+    let resolveFirst: (theme: "light" | "dark") => void = () => {};
+    mockedGetSystemTheme
+      .mockImplementationOnce(
+        () =>
+          new Promise((resolve) => {
+            resolveFirst = resolve;
+          }),
+      )
+      .mockResolvedValueOnce("light");
+
+    renderHook(() => useTheme("auto", { followSystem: true }));
+    act(() => {
+      window.dispatchEvent(new Event("focus"));
+    });
+    await waitFor(() => expect(document.documentElement.dataset.theme).toBe("light"));
+
+    await act(async () => {
+      resolveFirst("dark");
+      await Promise.resolve();
+    });
+
+    expect(document.documentElement.dataset.theme).toBe("light");
+  });
 });
diff --git a/apps/desktop-tauri/src/hooks/useTheme.ts b/apps/desktop-tauri/src/hooks/useTheme.ts
index ec33eac7e61..b957db9c90d 100644
--- a/apps/desktop-tauri/src/hooks/useTheme.ts
+++ b/apps/desktop-tauri/src/hooks/useTheme.ts
@@ -44,10 +44,13 @@ function apply(theme: ResolvedTheme) {
  */
 function followWindowsTheme(): () => void {
   let cancelled = false;
+  // Reads can overlap (focus during a poll); only the latest one may apply.
+  let latestRequest = 0;
   const sync = () => {
+    const request = ++latestRequest;
     getSystemTheme()
       .then((theme) => {
-        if (!cancelled) apply(theme);
+        if (!cancelled && request === latestRequest) apply(theme);
       })
       .catch(() => {});
   };