From beebc32930e1e965f3ba6a2048c00a360bcd9e6d Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden@coder.com>
Date: Tue, 17 Feb 2026 16:41:56 +0000
Subject: [PATCH 1/4] =?UTF-8?q?=F0=9F=A4=96=20feat:=20add=20renderer-first?=
 =?UTF-8?q?=20auto=20theme=20preference?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Persist theme preference separately from resolved concrete theme so existing consumers keep receiving concrete values.
- Add auto follow behavior in the renderer via prefers-color-scheme change listeners.
- Expose Auto in settings, compact selector, command palette, and pre-hydration theme bootstrap; keep cycle/toggle manual-only.
- Expand ThemeContext and command source tests for auto preference behavior.
---
 index.html                                    |  33 +--
 src/browser/App.tsx                           |   8 +-
 .../Settings/sections/GeneralSection.tsx      |   9 +-
 src/browser/components/ThemeSelector.tsx      |  13 +-
 src/browser/contexts/ThemeContext.test.tsx    | 196 +++++++++++++-----
 src/browser/contexts/ThemeContext.tsx         | 109 +++++++---
 src/browser/utils/commands/sources.test.ts    |  24 ++-
 src/browser/utils/commands/sources.ts         |   8 +-
 8 files changed, 297 insertions(+), 103 deletions(-)

diff --git a/index.html b/index.html
index 51e75f1b85..1a13cf7051 100644
--- a/index.html
+++ b/index.html
@@ -106,7 +106,13 @@
     <script>
       (function () {
         const THEME_KEY = "uiTheme";
-        const VALID_THEMES = new Set(["light", "dark", "flexoki-light", "flexoki-dark"]);
+        const VALID_THEME_PREFERENCES = new Set([
+          "auto",
+          "light",
+          "dark",
+          "flexoki-light",
+          "flexoki-dark",
+        ]);
 
         const THEME_COLORS = {
           dark: "#1e1e1e",
@@ -115,6 +121,14 @@
           "flexoki-dark": "#100f0f",
         };
 
+        function resolveSystemTheme() {
+          if (!window.matchMedia) {
+            return "dark";
+          }
+
+          return window.matchMedia("(prefers-color-scheme: light)").matches ? "light" : "dark";
+        }
+
         function getColorScheme(theme) {
           return theme === "light" || theme.endsWith("-light") ? "light" : "dark";
         }
@@ -132,23 +146,18 @@
             }
           }
 
-          const prefersLight = window.matchMedia
-            ? window.matchMedia("(prefers-color-scheme: light)").matches
-            : false;
-
-          const fallbackTheme = prefersLight ? "light" : "dark";
-          let theme = fallbackTheme;
-
+          let themePreference = "auto";
           if (typeof parsed === "string") {
-            if (VALID_THEMES.has(parsed)) {
-              theme = parsed;
+            if (VALID_THEME_PREFERENCES.has(parsed)) {
+              themePreference = parsed;
             } else if (parsed.endsWith("-light")) {
-              theme = "light";
+              themePreference = "light";
             } else if (parsed.endsWith("-dark")) {
-              theme = "dark";
+              themePreference = "dark";
             }
           }
 
+          const theme = themePreference === "auto" ? resolveSystemTheme() : themePreference;
           const colorScheme = getColorScheme(theme);
 
           document.documentElement.dataset.theme = theme;
diff --git a/src/browser/App.tsx b/src/browser/App.tsx
index 01de978216..3a317dc72c 100644
--- a/src/browser/App.tsx
+++ b/src/browser/App.tsx
@@ -29,7 +29,7 @@ import { useStableReference, compareMaps } from "./hooks/useStableReference";
 import { CommandRegistryProvider, useCommandRegistry } from "./contexts/CommandRegistryContext";
 import { useOpenTerminal } from "./hooks/useOpenTerminal";
 import type { CommandAction } from "./contexts/CommandRegistryContext";
-import { useTheme, type ThemeMode } from "./contexts/ThemeContext";
+import { useTheme, type ThemePreference } from "./contexts/ThemeContext";
 import { CommandPalette } from "./components/CommandPalette";
 import { buildCoreSources, type BuildSourcesParams } from "./utils/commands/sources";
 
@@ -101,10 +101,10 @@ function AppInner() {
     beginWorkspaceCreation,
   } = useWorkspaceContext();
   const { currentWorkspaceId, currentSettingsSection } = useRouter();
-  const { theme, setTheme, toggleTheme } = useTheme();
+  const { themePreference, setTheme, toggleTheme } = useTheme();
   const { open: openSettings, isOpen: isSettingsOpen } = useSettings();
   const setThemePreference = useCallback(
-    (nextTheme: ThemeMode) => {
+    (nextTheme: ThemePreference) => {
       setTheme(nextTheme);
     },
     [setTheme]
@@ -591,7 +591,7 @@ function AppInner() {
     projects,
     workspaceMetadata,
     selectedWorkspace,
-    theme,
+    themePreference,
     getThinkingLevel: getThinkingLevelForWorkspace,
     onSetThinkingLevel: setThinkingLevelFromPalette,
     onStartWorkspaceCreation: openNewWorkspaceFromPalette,
diff --git a/src/browser/components/Settings/sections/GeneralSection.tsx b/src/browser/components/Settings/sections/GeneralSection.tsx
index f0c2ffb55e..66c5a76826 100644
--- a/src/browser/components/Settings/sections/GeneralSection.tsx
+++ b/src/browser/components/Settings/sections/GeneralSection.tsx
@@ -1,5 +1,5 @@
 import React, { useEffect, useState, useCallback, useRef } from "react";
-import { useTheme, THEME_OPTIONS, type ThemeMode } from "@/browser/contexts/ThemeContext";
+import { useTheme, THEME_OPTIONS, type ThemePreference } from "@/browser/contexts/ThemeContext";
 import {
   Select,
   SelectContent,
@@ -127,7 +127,7 @@ const EDITOR_OPTIONS: Array<{ value: EditorType; label: string }> = [
 const isBrowserMode = typeof window !== "undefined" && !window.api;
 
 export function GeneralSection() {
-  const { theme, setTheme } = useTheme();
+  const { themePreference, setTheme } = useTheme();
   const { api } = useAPI();
   const [rawTerminalFontConfig, setTerminalFontConfig] = usePersistedState<TerminalFontConfig>(
     TERMINAL_FONT_CONFIG_KEY,
@@ -334,7 +334,10 @@ export function GeneralSection() {
               <div className="text-foreground text-sm">Theme</div>
               <div className="text-muted text-xs">Choose your preferred theme</div>
             </div>
-            <Select value={theme} onValueChange={(value) => setTheme(value as ThemeMode)}>
+            <Select
+              value={themePreference}
+              onValueChange={(value) => setTheme(value as ThemePreference)}
+            >
               <SelectTrigger className="border-border-medium bg-background-secondary hover:bg-hover h-9 w-auto cursor-pointer rounded-md border px-3 text-sm transition-colors">
                 <SelectValue />
               </SelectTrigger>
diff --git a/src/browser/components/ThemeSelector.tsx b/src/browser/components/ThemeSelector.tsx
index 161e62a9ac..506c8b0611 100644
--- a/src/browser/components/ThemeSelector.tsx
+++ b/src/browser/components/ThemeSelector.tsx
@@ -1,4 +1,4 @@
-import { useTheme, THEME_OPTIONS, type ThemeMode } from "@/browser/contexts/ThemeContext";
+import { useTheme, THEME_OPTIONS, type ThemePreference } from "@/browser/contexts/ThemeContext";
 import { Tooltip, TooltipTrigger, TooltipContent } from "./ui/tooltip";
 import {
   Select,
@@ -9,13 +9,16 @@ import {
 } from "@/browser/components/ui/select";
 
 export function ThemeSelector() {
-  const { theme, setTheme } = useTheme();
-  const currentLabel = THEME_OPTIONS.find((t) => t.value === theme)?.label ?? theme;
+  const { themePreference, setTheme } = useTheme();
+  const currentLabel = THEME_OPTIONS.find((theme) => theme.value === themePreference)?.label;
 
   return (
     <Tooltip>
       <TooltipTrigger asChild>
-        <Select value={theme} onValueChange={(value) => setTheme(value as ThemeMode)}>
+        <Select
+          value={themePreference}
+          onValueChange={(value) => setTheme(value as ThemePreference)}
+        >
           <SelectTrigger
             className="border-border-light text-muted-foreground hover:border-border-medium/80 hover:bg-toggle-bg/70 h-5 w-auto cursor-pointer border bg-transparent px-1.5 text-[11px] transition-colors duration-150"
             aria-label="Select theme"
@@ -32,7 +35,7 @@ export function ThemeSelector() {
           </SelectContent>
         </Select>
       </TooltipTrigger>
-      <TooltipContent align="end">Theme: {currentLabel}</TooltipContent>
+      <TooltipContent align="end">Theme: {currentLabel ?? themePreference}</TooltipContent>
     </Tooltip>
   );
 }
diff --git a/src/browser/contexts/ThemeContext.test.tsx b/src/browser/contexts/ThemeContext.test.tsx
index 4e216b6d9a..757d44fe45 100644
--- a/src/browser/contexts/ThemeContext.test.tsx
+++ b/src/browser/contexts/ThemeContext.test.tsx
@@ -6,103 +6,205 @@ const dom = new GlobalWindow();
 (global as any).window = dom.window;
 (global as any).document = dom.window.document;
 (global as any).location = new URL("https://example.com/");
-// Polyfill console since happy-dom might interfere or we just want standard console
 (global as any).console = console;
 /* eslint-enable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access */
 
-import { afterEach, describe, expect, mock, test, beforeEach } from "bun:test";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import { act, cleanup, fireEvent, render } from "@testing-library/react";
 
-import { render, cleanup } from "@testing-library/react";
 import { ThemeProvider, useTheme } from "./ThemeContext";
 import { UI_THEME_KEY } from "@/common/constants/storage";
 
-// Helper to access internals
+let prefersLight = false;
+const mediaQueryListeners = new Set<(event: MediaQueryListEvent) => void>();
+
+const mediaQueryList = {
+  get matches() {
+    return prefersLight;
+  },
+  media: "(prefers-color-scheme: light)",
+  onchange: null as ((this: MediaQueryList, event: MediaQueryListEvent) => void) | null,
+  addListener: (listener: (event: MediaQueryListEvent) => void) => {
+    mediaQueryListeners.add(listener);
+  },
+  removeListener: (listener: (event: MediaQueryListEvent) => void) => {
+    mediaQueryListeners.delete(listener);
+  },
+  addEventListener: (
+    type: string,
+    listener: EventListenerOrEventListenerObject | null,
+    _options?: boolean | AddEventListenerOptions
+  ) => {
+    if (type !== "change") {
+      return;
+    }
+
+    if (typeof listener === "function") {
+      mediaQueryListeners.add(listener as (event: MediaQueryListEvent) => void);
+    }
+  },
+  removeEventListener: (
+    type: string,
+    listener: EventListenerOrEventListenerObject | null,
+    _options?: boolean | EventListenerOptions
+  ) => {
+    if (type !== "change") {
+      return;
+    }
+
+    if (typeof listener === "function") {
+      mediaQueryListeners.delete(listener as (event: MediaQueryListEvent) => void);
+    }
+  },
+  dispatchEvent: () => true,
+} as MediaQueryList;
+
+function setSystemTheme(theme: "light" | "dark") {
+  prefersLight = theme === "light";
+
+  const event = {
+    matches: prefersLight,
+    media: mediaQueryList.media,
+  } as MediaQueryListEvent;
+
+  for (const listener of mediaQueryListeners) {
+    listener(event);
+  }
+
+  mediaQueryList.onchange?.call(mediaQueryList, event);
+}
+
+const mockMatchMedia = mock(() => mediaQueryList);
+
 const TestComponent = () => {
-  const { theme, toggleTheme } = useTheme();
+  const { theme, themePreference, toggleTheme, setTheme } = useTheme();
+
   return (
     <div>
       <span data-testid="theme-value">{theme}</span>
+      <span data-testid="theme-preference">{themePreference}</span>
       <button onClick={toggleTheme} data-testid="toggle-btn">
         Toggle
       </button>
+      <button onClick={() => setTheme("auto")} data-testid="set-auto-btn">
+        Auto
+      </button>
+      <button onClick={() => setTheme("flexoki-dark")} data-testid="set-flexoki-dark-btn">
+        Flexoki Dark
+      </button>
     </div>
   );
 };
 
 describe("ThemeContext", () => {
-  // Mock matchMedia
-  const mockMatchMedia = mock(() => ({
-    matches: false,
-    media: "",
-    onchange: null,
-    addListener: () => {
-      // no-op
-    },
-    removeListener: () => {
-      // no-op
-    },
-    addEventListener: () => {
-      // no-op
-    },
-    removeEventListener: () => {
-      // no-op
-    },
-    dispatchEvent: () => true,
-  }));
-
   beforeEach(() => {
-    // Ensure window exists (Bun test with happy-dom should provide it)
-    if (typeof window !== "undefined") {
-      window.matchMedia = mockMatchMedia;
-      window.localStorage.clear();
-    }
+    prefersLight = false;
+    mediaQueryListeners.clear();
+    mockMatchMedia.mockClear();
+
+    window.matchMedia = mockMatchMedia;
+    window.localStorage.clear();
   });
 
   afterEach(() => {
     cleanup();
-    if (typeof window !== "undefined") {
-      window.localStorage.clear();
-    }
+    window.localStorage.clear();
   });
 
-  test("uses persisted state by default", () => {
+  test("defaults to auto preference and resolves theme from system", () => {
     const { getByTestId } = render(
       <ThemeProvider>
         <TestComponent />
       </ThemeProvider>
     );
-    // If matchMedia matches is false (default mock), resolveSystemTheme returns 'dark' (since it checks prefers-color-scheme: light)
-    // resolveSystemTheme logic: window.matchMedia("(prefers-color-scheme: light)").matches ? "light" : "dark"
+
+    expect(getByTestId("theme-preference").textContent).toBe("auto");
     expect(getByTestId("theme-value").textContent).toBe("dark");
   });
 
-  test("respects forcedTheme prop", () => {
-    const { getByTestId, rerender } = render(
-      <ThemeProvider forcedTheme="light">
+  test("normalizes invalid stored preferences to auto", () => {
+    window.localStorage.setItem(UI_THEME_KEY, JSON.stringify("totally-invalid"));
+
+    const { getByTestId } = render(
+      <ThemeProvider>
         <TestComponent />
       </ThemeProvider>
     );
-    expect(getByTestId("theme-value").textContent).toBe("light");
 
-    rerender(
-      <ThemeProvider forcedTheme="dark">
+    expect(getByTestId("theme-preference").textContent).toBe("auto");
+    expect(JSON.parse(window.localStorage.getItem(UI_THEME_KEY)!)).toBe("auto");
+  });
+
+  test("follows OS theme changes while preference is auto", () => {
+    const { getByTestId } = render(
+      <ThemeProvider>
         <TestComponent />
       </ThemeProvider>
     );
+
+    expect(getByTestId("theme-preference").textContent).toBe("auto");
+    expect(getByTestId("theme-value").textContent).toBe("dark");
+
+    act(() => {
+      setSystemTheme("light");
+    });
+
+    expect(getByTestId("theme-value").textContent).toBe("light");
+
+    act(() => {
+      setSystemTheme("dark");
+    });
+
     expect(getByTestId("theme-value").textContent).toBe("dark");
   });
 
-  test("forcedTheme overrides persisted state", () => {
-    window.localStorage.setItem(UI_THEME_KEY, JSON.stringify("light"));
+  test("stops following OS changes when a manual theme is selected", () => {
+    const { getByTestId } = render(
+      <ThemeProvider>
+        <TestComponent />
+      </ThemeProvider>
+    );
+
+    fireEvent.click(getByTestId("set-flexoki-dark-btn"));
+    expect(getByTestId("theme-preference").textContent).toBe("flexoki-dark");
+    expect(getByTestId("theme-value").textContent).toBe("flexoki-dark");
+
+    act(() => {
+      setSystemTheme("light");
+    });
 
+    expect(getByTestId("theme-value").textContent).toBe("flexoki-dark");
+  });
+
+  test("cycle toggle uses manual themes only", () => {
     const { getByTestId } = render(
+      <ThemeProvider>
+        <TestComponent />
+      </ThemeProvider>
+    );
+
+    expect(getByTestId("theme-preference").textContent).toBe("auto");
+
+    fireEvent.click(getByTestId("toggle-btn"));
+
+    // Auto resolves to dark by default in this test, so the next manual theme is flexoki-light.
+    expect(getByTestId("theme-preference").textContent).toBe("flexoki-light");
+    expect(getByTestId("theme-value").textContent).toBe("flexoki-light");
+  });
+
+  test("respects forcedTheme prop", () => {
+    const { getByTestId, rerender } = render(
+      <ThemeProvider forcedTheme="light">
+        <TestComponent />
+      </ThemeProvider>
+    );
+    expect(getByTestId("theme-value").textContent).toBe("light");
+
+    rerender(
       <ThemeProvider forcedTheme="dark">
         <TestComponent />
       </ThemeProvider>
     );
     expect(getByTestId("theme-value").textContent).toBe("dark");
-
-    // Check that localStorage is still light (since forcedTheme doesn't write to storage by itself)
-    expect(JSON.parse(window.localStorage.getItem(UI_THEME_KEY)!)).toBe("light");
   });
 });
diff --git a/src/browser/contexts/ThemeContext.tsx b/src/browser/contexts/ThemeContext.tsx
index 7900a9f7da..c91a66b845 100644
--- a/src/browser/contexts/ThemeContext.tsx
+++ b/src/browser/contexts/ThemeContext.tsx
@@ -2,31 +2,36 @@ import React, {
   createContext,
   useCallback,
   useContext,
+  useEffect,
   useLayoutEffect,
   useMemo,
+  useState,
   type ReactNode,
 } from "react";
-import { usePersistedState } from "@/browser/hooks/usePersistedState";
+import { readPersistedString, usePersistedState } from "@/browser/hooks/usePersistedState";
 import { UI_THEME_KEY } from "@/common/constants/storage";
 
 export type ThemeMode = "light" | "dark" | "flexoki-light" | "flexoki-dark";
+export type ThemePreference = ThemeMode | "auto";
 
-export const THEME_OPTIONS: Array<{ value: ThemeMode; label: string }> = [
+export const THEME_OPTIONS: Array<{ value: ThemePreference; label: string }> = [
+  { value: "auto", label: "Auto" },
   { value: "light", label: "Light" },
   { value: "dark", label: "Dark" },
   { value: "flexoki-light", label: "Flexoki Light" },
   { value: "flexoki-dark", label: "Flexoki Dark" },
 ];
 
-const THEME_VALUES = THEME_OPTIONS.map((t) => t.value);
+const MANUAL_THEME_VALUES: ThemeMode[] = ["light", "dark", "flexoki-light", "flexoki-dark"];
+const THEME_PREFERENCE_VALUES = THEME_OPTIONS.map((theme) => theme.value);
 
-function normalizeThemeMode(value: unknown): ThemeMode | undefined {
+function normalizeThemePreference(value: unknown): ThemePreference | undefined {
   if (typeof value !== "string") {
     return undefined;
   }
 
-  if (THEME_VALUES.includes(value as ThemeMode)) {
-    return value as ThemeMode;
+  if (THEME_PREFERENCE_VALUES.includes(value as ThemePreference)) {
+    return value as ThemePreference;
   }
 
   // Preserve intent for removed themes (e.g. legacy solarized-light/dark).
@@ -42,8 +47,11 @@ function normalizeThemeMode(value: unknown): ThemeMode | undefined {
 }
 
 interface ThemeContextValue {
+  /** Concrete theme consumed by existing components (`auto` resolves to light/dark). */
   theme: ThemeMode;
-  setTheme: React.Dispatch<React.SetStateAction<ThemeMode>>;
+  /** Persisted user preference shown in settings/selector (includes explicit `auto`). */
+  themePreference: ThemePreference;
+  setTheme: React.Dispatch<React.SetStateAction<ThemePreference>>;
   toggleTheme: () => void;
   /** True if this provider has a forcedTheme - nested providers should not override */
   isForced: boolean;
@@ -85,7 +93,7 @@ function applyThemeFavicon(theme: ThemeMode) {
   }
 }
 
-function resolveSystemTheme(): ThemeMode {
+function resolveSystemTheme(): "light" | "dark" {
   if (typeof window === "undefined" || !window.matchMedia) {
     return "dark";
   }
@@ -127,23 +135,67 @@ export function ThemeProvider({
   const parentContext = useContext(ThemeContext);
   const isNestedUnderForcedProvider = parentContext?.isForced ?? false;
 
-  const [persistedTheme, setTheme] = usePersistedState<ThemeMode>(
+  const [persistedThemePreference, setTheme] = usePersistedState<ThemePreference>(
     UI_THEME_KEY,
-    resolveSystemTheme(),
+    "auto",
     {
       listener: true,
     }
   );
 
-  const parsedPersistedTheme = normalizeThemeMode(persistedTheme);
-  const normalizedPersistedTheme = parsedPersistedTheme ?? resolveSystemTheme();
+  // Keep the explicit user preference (`auto`/manual) separate from the concrete theme we apply.
+  // This lets existing UI consumers keep using a resolved theme while settings can still show `auto`.
+  const storedThemePreference = readPersistedString(UI_THEME_KEY) ?? persistedThemePreference;
+  const parsedPersistedThemePreference = normalizeThemePreference(storedThemePreference);
+  const normalizedThemePreference = parsedPersistedThemePreference ?? "auto";
+
+  const [systemTheme, setSystemTheme] = useState<"light" | "dark">(() => resolveSystemTheme());
+
+  useEffect(() => {
+    if (
+      typeof window === "undefined" ||
+      !window.matchMedia ||
+      forcedTheme !== undefined ||
+      isNestedUnderForcedProvider ||
+      normalizedThemePreference !== "auto"
+    ) {
+      return;
+    }
+
+    const mediaQuery = window.matchMedia("(prefers-color-scheme: light)");
+    setSystemTheme(mediaQuery.matches ? "light" : "dark");
+
+    const handleChange = (event: MediaQueryListEvent) => {
+      setSystemTheme(event.matches ? "light" : "dark");
+    };
+
+    if (typeof mediaQuery.addEventListener === "function") {
+      mediaQuery.addEventListener("change", handleChange);
+      return () => {
+        mediaQuery.removeEventListener("change", handleChange);
+      };
+    }
+
+    mediaQuery.addListener(handleChange);
+    return () => {
+      mediaQuery.removeListener(handleChange);
+    };
+  }, [forcedTheme, isNestedUnderForcedProvider, normalizedThemePreference]);
+
+  const resolvedPersistedTheme =
+    normalizedThemePreference === "auto" ? systemTheme : normalizedThemePreference;
 
-  // If nested under a forced provider, use parent's theme
-  // Otherwise, use forcedTheme (if provided) or persistedTheme
+  // If nested under a forced provider, use parent's resolved theme
+  // Otherwise, use forcedTheme (if provided) or resolved persisted theme
   const theme =
     isNestedUnderForcedProvider && parentContext
       ? parentContext.theme
-      : (forcedTheme ?? normalizedPersistedTheme);
+      : (forcedTheme ?? resolvedPersistedTheme);
+
+  const themePreference =
+    isNestedUnderForcedProvider && parentContext
+      ? parentContext.themePreference
+      : normalizedThemePreference;
 
   const isForced = forcedTheme !== undefined || isNestedUnderForcedProvider;
 
@@ -153,40 +205,43 @@ export function ThemeProvider({
       return;
     }
 
-    // Self-heal legacy or invalid themes persisted in localStorage.
-    if (forcedTheme === undefined && parsedPersistedTheme !== persistedTheme) {
-      setTheme(normalizedPersistedTheme);
+    // Self-heal legacy or invalid theme preferences persisted in localStorage.
+    if (forcedTheme === undefined && parsedPersistedThemePreference !== storedThemePreference) {
+      setTheme(normalizedThemePreference);
     }
 
     applyThemeToDocument(theme);
   }, [
     forcedTheme,
     isNestedUnderForcedProvider,
-    normalizedPersistedTheme,
-    parsedPersistedTheme,
-    persistedTheme,
+    normalizedThemePreference,
+    parsedPersistedThemePreference,
     setTheme,
+    storedThemePreference,
     theme,
   ]);
 
   const toggleTheme = useCallback(() => {
     if (!isNestedUnderForcedProvider) {
-      setTheme((current) => {
-        const currentIndex = THEME_VALUES.indexOf(current);
-        const nextIndex = (currentIndex + 1) % THEME_VALUES.length;
-        return THEME_VALUES[nextIndex];
+      setTheme((currentPreference) => {
+        const currentTheme = currentPreference === "auto" ? theme : currentPreference;
+        const currentIndex = MANUAL_THEME_VALUES.indexOf(currentTheme);
+        const safeCurrentIndex = currentIndex >= 0 ? currentIndex : 0;
+        const nextIndex = (safeCurrentIndex + 1) % MANUAL_THEME_VALUES.length;
+        return MANUAL_THEME_VALUES[nextIndex];
       });
     }
-  }, [setTheme, isNestedUnderForcedProvider]);
+  }, [isNestedUnderForcedProvider, setTheme, theme]);
 
   const value = useMemo<ThemeContextValue>(
     () => ({
       theme,
+      themePreference,
       setTheme,
       toggleTheme,
       isForced,
     }),
-    [setTheme, theme, toggleTheme, isForced]
+    [isForced, setTheme, theme, themePreference, toggleTheme]
   );
 
   return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
diff --git a/src/browser/utils/commands/sources.test.ts b/src/browser/utils/commands/sources.test.ts
index af21d92e38..1b879a1f93 100644
--- a/src/browser/utils/commands/sources.test.ts
+++ b/src/browser/utils/commands/sources.test.ts
@@ -32,7 +32,7 @@ const mk = (over: Partial<Parameters<typeof buildCoreSources>[0]> = {}) => {
   });
   const params: Parameters<typeof buildCoreSources>[0] = {
     projects,
-    theme: "dark",
+    themePreference: "dark",
     workspaceMetadata,
     selectedWorkspace: {
       projectPath: "/repo/a",
@@ -86,6 +86,28 @@ test("buildCoreSources includes create/switch workspace actions", () => {
   expect(titles.includes("Open Terminal Window for Workspace…")).toBe(true);
 });
 
+test("appearance commands offer auto when a manual theme is selected", () => {
+  const sources = mk({ themePreference: "dark" });
+  const actions = sources.flatMap((source) => source());
+
+  const autoAction = actions.find((action) => action.id === "appearance:theme:set:auto");
+  expect(autoAction?.title).toBe("Use Auto Theme");
+  expect(actions.some((action) => action.id === "appearance:theme:set:dark")).toBe(false);
+});
+
+test("appearance commands omit auto when auto preference is already selected", () => {
+  const sources = mk({ themePreference: "auto" });
+  const actions = sources.flatMap((source) => source());
+
+  const themeSetCommandIds = actions
+    .map((action) => action.id)
+    .filter((id) => id.startsWith("appearance:theme:set:"));
+
+  expect(themeSetCommandIds).toContain("appearance:theme:set:dark");
+  expect(themeSetCommandIds).toContain("appearance:theme:set:light");
+  expect(themeSetCommandIds).not.toContain("appearance:theme:set:auto");
+});
+
 test("buildCoreSources adds thinking effort command", () => {
   const sources = mk({ getThinkingLevel: () => "medium" });
   const actions = sources.flatMap((s) => s());
diff --git a/src/browser/utils/commands/sources.ts b/src/browser/utils/commands/sources.ts
index 65a4fdc617..7bb5ee3c05 100644
--- a/src/browser/utils/commands/sources.ts
+++ b/src/browser/utils/commands/sources.ts
@@ -1,4 +1,4 @@
-import { THEME_OPTIONS, type ThemeMode } from "@/browser/contexts/ThemeContext";
+import { THEME_OPTIONS, type ThemePreference } from "@/browser/contexts/ThemeContext";
 import type { CommandAction } from "@/browser/contexts/CommandRegistryContext";
 import type { APIClient } from "@/browser/contexts/API";
 import { formatKeybind, KEYBINDS } from "@/browser/utils/ui/keybinds";
@@ -44,7 +44,7 @@ export interface BuildSourcesParams {
   projects: Map<string, ProjectConfig>;
   /** Map of workspace ID to workspace metadata (keyed by metadata.id, not path) */
   workspaceMetadata: Map<string, FrontendWorkspaceMetadata>;
-  theme: ThemeMode;
+  themePreference: ThemePreference;
   selectedWorkspaceState?: WorkspaceState | null;
   selectedWorkspace: {
     projectPath: string;
@@ -77,7 +77,7 @@ export interface BuildSourcesParams {
   onNavigateWorkspace: (dir: "next" | "prev") => void;
   onOpenWorkspaceInTerminal: (workspaceId: string, runtimeConfig?: RuntimeConfig) => void;
   onToggleTheme: () => void;
-  onSetTheme: (theme: ThemeMode) => void;
+  onSetTheme: (theme: ThemePreference) => void;
   onOpenSettings?: (section?: string) => void;
 
   // Layout slots
@@ -661,7 +661,7 @@ export function buildCoreSources(p: BuildSourcesParams): Array<() => CommandActi
 
     // Add command for each theme the user isn't currently using
     for (const opt of THEME_OPTIONS) {
-      if (p.theme !== opt.value) {
+      if (p.themePreference !== opt.value) {
         list.push({
           id: CommandIds.themeSet(opt.value),
           title: `Use ${opt.label} Theme`,

From c7c74327b92253204cc394e4001f877f2f9614b7 Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden@coder.com>
Date: Tue, 17 Feb 2026 16:47:33 +0000
Subject: [PATCH 2/4] fix: remove object literal assertions in ThemeContext
 test

---
 src/browser/contexts/ThemeContext.test.tsx | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/browser/contexts/ThemeContext.test.tsx b/src/browser/contexts/ThemeContext.test.tsx
index 757d44fe45..4561ba6de5 100644
--- a/src/browser/contexts/ThemeContext.test.tsx
+++ b/src/browser/contexts/ThemeContext.test.tsx
@@ -18,12 +18,12 @@ import { UI_THEME_KEY } from "@/common/constants/storage";
 let prefersLight = false;
 const mediaQueryListeners = new Set<(event: MediaQueryListEvent) => void>();
 
-const mediaQueryList = {
+const mediaQueryList: MediaQueryList = {
   get matches() {
     return prefersLight;
   },
   media: "(prefers-color-scheme: light)",
-  onchange: null as ((this: MediaQueryList, event: MediaQueryListEvent) => void) | null,
+  onchange: null,
   addListener: (listener: (event: MediaQueryListEvent) => void) => {
     mediaQueryListeners.add(listener);
   },
@@ -56,16 +56,16 @@ const mediaQueryList = {
       mediaQueryListeners.delete(listener as (event: MediaQueryListEvent) => void);
     }
   },
-  dispatchEvent: () => true,
-} as MediaQueryList;
+  dispatchEvent: (_event: Event) => true,
+};
 
 function setSystemTheme(theme: "light" | "dark") {
   prefersLight = theme === "light";
 
-  const event = {
+  const event = new dom.window.MediaQueryListEvent("change", {
     matches: prefersLight,
     media: mediaQueryList.media,
-  } as MediaQueryListEvent;
+  });
 
   for (const listener of mediaQueryListeners) {
     listener(event);

From 608080d738286e314eb00d1116ba902305c1decd Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden@coder.com>
Date: Tue, 17 Feb 2026 16:50:13 +0000
Subject: [PATCH 3/4] tests: fix MediaQueryListEvent typing in ThemeContext
 test

---
 src/browser/contexts/ThemeContext.test.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/browser/contexts/ThemeContext.test.tsx b/src/browser/contexts/ThemeContext.test.tsx
index 4561ba6de5..321015925d 100644
--- a/src/browser/contexts/ThemeContext.test.tsx
+++ b/src/browser/contexts/ThemeContext.test.tsx
@@ -65,7 +65,7 @@ function setSystemTheme(theme: "light" | "dark") {
   const event = new dom.window.MediaQueryListEvent("change", {
     matches: prefersLight,
     media: mediaQueryList.media,
-  });
+  }) as unknown as MediaQueryListEvent;
 
   for (const listener of mediaQueryListeners) {
     listener(event);

From e74bd5511d83c59d7b64506dff067fe159b73d72 Mon Sep 17 00:00:00 2001
From: Jaayden Halko <jaayden@coder.com>
Date: Tue, 17 Feb 2026 17:19:21 +0000
Subject: [PATCH 4/4] fix: resolve auto theme immediately when leaving manual
 mode

---
 src/browser/contexts/ThemeContext.test.tsx | 39 +++++++++++++++++++++-
 src/browser/contexts/ThemeContext.tsx      |  7 +++-
 2 files changed, 44 insertions(+), 2 deletions(-)

diff --git a/src/browser/contexts/ThemeContext.test.tsx b/src/browser/contexts/ThemeContext.test.tsx
index 321015925d..1aa361895f 100644
--- a/src/browser/contexts/ThemeContext.test.tsx
+++ b/src/browser/contexts/ThemeContext.test.tsx
@@ -12,7 +12,7 @@ const dom = new GlobalWindow();
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 import { act, cleanup, fireEvent, render } from "@testing-library/react";
 
-import { ThemeProvider, useTheme } from "./ThemeContext";
+import { ThemeProvider, type ThemeMode, type ThemePreference, useTheme } from "./ThemeContext";
 import { UI_THEME_KEY } from "@/common/constants/storage";
 
 let prefersLight = false;
@@ -176,6 +176,43 @@ describe("ThemeContext", () => {
     expect(getByTestId("theme-value").textContent).toBe("flexoki-dark");
   });
 
+  test("switching from manual to auto resolves using the current system theme immediately", () => {
+    const renderLog: Array<{ theme: ThemeMode; themePreference: ThemePreference }> = [];
+
+    const ThemeProbe = () => {
+      const { theme, themePreference } = useTheme();
+      renderLog.push({ theme, themePreference });
+      return null;
+    };
+
+    const { getByTestId } = render(
+      <ThemeProvider>
+        <ThemeProbe />
+        <TestComponent />
+      </ThemeProvider>
+    );
+
+    fireEvent.click(getByTestId("set-flexoki-dark-btn"));
+
+    act(() => {
+      setSystemTheme("light");
+    });
+
+    expect(getByTestId("theme-value").textContent).toBe("flexoki-dark");
+
+    const renderLogStartIndex = renderLog.length;
+    fireEvent.click(getByTestId("set-auto-btn"));
+
+    const autoRendersAfterSwitch = renderLog
+      .slice(renderLogStartIndex)
+      .filter((entry) => entry.themePreference === "auto");
+
+    expect(autoRendersAfterSwitch.length).toBeGreaterThan(0);
+    expect(autoRendersAfterSwitch[0]?.theme).toBe("light");
+    expect(getByTestId("theme-preference").textContent).toBe("auto");
+    expect(getByTestId("theme-value").textContent).toBe("light");
+  });
+
   test("cycle toggle uses manual themes only", () => {
     const { getByTestId } = render(
       <ThemeProvider>
diff --git a/src/browser/contexts/ThemeContext.tsx b/src/browser/contexts/ThemeContext.tsx
index c91a66b845..2af138b7bf 100644
--- a/src/browser/contexts/ThemeContext.tsx
+++ b/src/browser/contexts/ThemeContext.tsx
@@ -183,7 +183,12 @@ export function ThemeProvider({
   }, [forcedTheme, isNestedUnderForcedProvider, normalizedThemePreference]);
 
   const resolvedPersistedTheme =
-    normalizedThemePreference === "auto" ? systemTheme : normalizedThemePreference;
+    normalizedThemePreference === "auto"
+      ? // Resolve directly from matchMedia so manual -> auto reads the current OS theme in the same render.
+        typeof window !== "undefined"
+        ? resolveSystemTheme()
+        : systemTheme
+      : normalizedThemePreference;
 
   // If nested under a forced provider, use parent's resolved theme
   // Otherwise, use forcedTheme (if provided) or resolved persisted theme