From af10481ac19fa7930b351c70857cb95aa935ee60 Mon Sep 17 00:00:00 2001
From: Michael Suchacz <203725896+ibetitsmike@users.noreply.github.com>
Date: Fri, 16 Jan 2026 16:44:05 +0000
Subject: [PATCH 1/5] =?UTF-8?q?=F0=9F=A4=96=20feat:=20add=20system=20theme?=
 =?UTF-8?q?=20matching=20(light/dark=20based=20on=20OS)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add 'System' theme preference that follows OS light/dark live
- Persisted preference: 'system' | 'light' | 'dark' (defaults to 'system')
- Live updates: subscribe to matchMedia changes when preference is 'system'
- Update index.html and terminal.html early bootstrap for FOUC prevention
- Wrap terminal window in ThemeProvider for theme consistency
- Remove flexoki themes, keeping only light/dark
- Self-heal invalid/legacy stored values to 'system'
---
 index.html                                    |  52 ++-----
 src/browser/App.tsx                           |  10 +-
 .../Settings/sections/GeneralSection.tsx      |  15 +-
 src/browser/components/ThemeSelector.tsx      |  18 ++-
 src/browser/contexts/ThemeContext.tsx         | 146 +++++++++---------
 src/browser/terminal-window.tsx               |  13 +-
 src/browser/utils/commands/sources.test.ts    |   4 +-
 src/browser/utils/commands/sources.ts         |  14 +-
 terminal.html                                 |  43 +++++-
 9 files changed, 174 insertions(+), 141 deletions(-)

diff --git a/index.html b/index.html
index 20943cff1f..0d82b23c0e 100644
--- a/index.html
+++ b/index.html
@@ -106,23 +106,8 @@
     <script>
       (function () {
         const THEME_KEY = "uiTheme";
-        const VALID_THEMES = new Set([
-          "light",
-          "dark",
-          "flexoki-light",
-          "flexoki-dark",
-        ]);
-
-        const THEME_COLORS = {
-          dark: "#1e1e1e",
-          light: "#f5f6f8",
-          "flexoki-light": "#fffcf0",
-          "flexoki-dark": "#100f0f",
-        };
-
-        function getColorScheme(theme) {
-          return theme === "light" || theme.endsWith("-light") ? "light" : "dark";
-        }
+        const VALID_PREFERENCES = new Set(["system", "light", "dark"]);
+        const THEME_COLORS = { dark: "#1e1e1e", light: "#f5f6f8" };
 
         try {
           const stored = window.localStorage.getItem(THEME_KEY);
@@ -137,34 +122,23 @@
             }
           }
 
-          const prefersLight = window.matchMedia
-            ? window.matchMedia("(prefers-color-scheme: light)").matches
-            : false;
-
-          const fallbackTheme = prefersLight ? "light" : "dark";
-          let theme = fallbackTheme;
-
-          if (typeof parsed === "string") {
-            if (VALID_THEMES.has(parsed)) {
-              theme = parsed;
-            } else if (parsed.endsWith("-light")) {
-              theme = "light";
-            } else if (parsed.endsWith("-dark")) {
-              theme = "dark";
-            }
-          }
+          // Normalize preference: "system" | "light" | "dark" (unknown → "system")
+          const preference =
+            typeof parsed === "string" && VALID_PREFERENCES.has(parsed) ? parsed : "system";
 
-          const colorScheme = getColorScheme(theme);
+          // Resolve system preference to actual theme
+          const systemTheme =
+            window.matchMedia && window.matchMedia("(prefers-color-scheme: light)").matches
+              ? "light"
+              : "dark";
+          const theme = preference === "system" ? systemTheme : preference;
 
           document.documentElement.dataset.theme = theme;
-          document.documentElement.style.colorScheme = colorScheme;
+          document.documentElement.style.colorScheme = theme;
 
           const metaThemeColor = document.querySelector('meta[name="theme-color"]');
           if (metaThemeColor) {
-            metaThemeColor.setAttribute(
-              "content",
-              THEME_COLORS[theme] ?? THEME_COLORS[colorScheme] ?? "#1e1e1e"
-            );
+            metaThemeColor.setAttribute("content", THEME_COLORS[theme] ?? "#1e1e1e");
           }
         } catch (error) {
           console.warn("Failed to apply preferred theme early", error);
diff --git a/src/browser/App.tsx b/src/browser/App.tsx
index b06870061a..1b3e67b587 100644
--- a/src/browser/App.tsx
+++ b/src/browser/App.tsx
@@ -23,7 +23,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 } from "./contexts/ThemeContext";
 import { CommandPalette } from "./components/CommandPalette";
 import { buildCoreSources, type BuildSourcesParams } from "./utils/commands/sources";
 
@@ -77,12 +77,6 @@ function AppInner() {
   } = useWorkspaceContext();
   const { theme, setTheme, toggleTheme } = useTheme();
   const { open: openSettings } = useSettings();
-  const setThemePreference = useCallback(
-    (nextTheme: ThemeMode) => {
-      setTheme(nextTheme);
-    },
-    [setTheme]
-  );
   const { api, status, error, authenticate } = useAPI();
 
   const {
@@ -455,7 +449,7 @@ function AppInner() {
       });
     },
     onToggleTheme: toggleTheme,
-    onSetTheme: setThemePreference,
+    onSetTheme: setTheme,
     onOpenSettings: openSettings,
     onClearTimingStats: (workspaceId: string) => workspaceStore.clearTimingStats(workspaceId),
     api,
diff --git a/src/browser/components/Settings/sections/GeneralSection.tsx b/src/browser/components/Settings/sections/GeneralSection.tsx
index fcf6be82b4..4e258c2bdc 100644
--- a/src/browser/components/Settings/sections/GeneralSection.tsx
+++ b/src/browser/components/Settings/sections/GeneralSection.tsx
@@ -1,5 +1,9 @@
 import React, { useEffect, useState, useCallback } from "react";
-import { useTheme, THEME_OPTIONS, type ThemeMode } from "@/browser/contexts/ThemeContext";
+import {
+  useTheme,
+  THEME_PREFERENCE_OPTIONS,
+  type ThemePreference,
+} from "@/browser/contexts/ThemeContext";
 import {
   Select,
   SelectContent,
@@ -28,7 +32,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, setThemePreference } = useTheme();
   const { api } = useAPI();
   const [editorConfig, setEditorConfig] = usePersistedState<EditorConfig>(
     EDITOR_CONFIG_KEY,
@@ -73,12 +77,15 @@ 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) => setThemePreference(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>
             <SelectContent>
-              {THEME_OPTIONS.map((option) => (
+              {THEME_PREFERENCE_OPTIONS.map((option) => (
                 <SelectItem key={option.value} value={option.value}>
                   {option.label}
                 </SelectItem>
diff --git a/src/browser/components/ThemeSelector.tsx b/src/browser/components/ThemeSelector.tsx
index 161e62a9ac..80438f2c53 100644
--- a/src/browser/components/ThemeSelector.tsx
+++ b/src/browser/components/ThemeSelector.tsx
@@ -1,4 +1,8 @@
-import { useTheme, THEME_OPTIONS, type ThemeMode } from "@/browser/contexts/ThemeContext";
+import {
+  useTheme,
+  THEME_PREFERENCE_OPTIONS,
+  type ThemePreference,
+} from "@/browser/contexts/ThemeContext";
 import { Tooltip, TooltipTrigger, TooltipContent } from "./ui/tooltip";
 import {
   Select,
@@ -9,13 +13,17 @@ 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, setThemePreference } = useTheme();
+  const currentLabel =
+    THEME_PREFERENCE_OPTIONS.find((t) => t.value === themePreference)?.label ?? themePreference;
 
   return (
     <Tooltip>
       <TooltipTrigger asChild>
-        <Select value={theme} onValueChange={(value) => setTheme(value as ThemeMode)}>
+        <Select
+          value={themePreference}
+          onValueChange={(value) => setThemePreference(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"
@@ -24,7 +32,7 @@ export function ThemeSelector() {
             <SelectValue />
           </SelectTrigger>
           <SelectContent>
-            {THEME_OPTIONS.map((option) => (
+            {THEME_PREFERENCE_OPTIONS.map((option) => (
               <SelectItem key={option.value} value={option.value}>
                 {option.label}
               </SelectItem>
diff --git a/src/browser/contexts/ThemeContext.tsx b/src/browser/contexts/ThemeContext.tsx
index 52238a574e..9d66598207 100644
--- a/src/browser/contexts/ThemeContext.tsx
+++ b/src/browser/contexts/ThemeContext.tsx
@@ -2,48 +2,43 @@ import React, {
   createContext,
   useCallback,
   useContext,
+  useEffect,
   useLayoutEffect,
   useMemo,
+  useState,
   type ReactNode,
 } from "react";
 import { usePersistedState } from "@/browser/hooks/usePersistedState";
 import { UI_THEME_KEY } from "@/common/constants/storage";
 
-export type ThemeMode = "light" | "dark" | "flexoki-light" | "flexoki-dark";
+/** Concrete theme applied to the document */
+export type ThemeMode = "light" | "dark";
 
-export const THEME_OPTIONS: Array<{ value: ThemeMode; label: string }> = [
+/** User preference: explicit theme or follow system */
+export type ThemePreference = ThemeMode | "system";
+
+export const THEME_PREFERENCE_OPTIONS: Array<{ value: ThemePreference; label: string }> = [
+  { value: "system", label: "System" },
   { 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);
-
-function normalizeThemeMode(value: unknown): ThemeMode | undefined {
-  if (typeof value !== "string") {
-    return undefined;
-  }
-
-  if (THEME_VALUES.includes(value as ThemeMode)) {
-    return value as ThemeMode;
-  }
-
-  // Preserve intent for removed themes (e.g. legacy solarized-light/dark).
-  if (value.endsWith("-light")) {
-    return "light";
-  }
+const PREFERENCE_VALUES = THEME_PREFERENCE_OPTIONS.map((t) => t.value);
 
-  if (value.endsWith("-dark")) {
-    return "dark";
+function normalizeThemePreference(value: unknown): ThemePreference {
+  if (typeof value === "string" && PREFERENCE_VALUES.includes(value as ThemePreference)) {
+    return value as ThemePreference;
   }
-
-  return undefined;
+  // Self-heal: unknown/legacy values become "system"
+  return "system";
 }
 
 interface ThemeContextValue {
+  /** The resolved theme applied to the document */
   theme: ThemeMode;
-  setTheme: React.Dispatch<React.SetStateAction<ThemeMode>>;
+  /** The user's preference (system, light, or dark) */
+  themePreference: ThemePreference;
+  setThemePreference: (preference: ThemePreference) => void;
   toggleTheme: () => void;
   /** True if this provider has a forcedTheme - nested providers should not override */
   isForced: boolean;
@@ -54,20 +49,12 @@ const ThemeContext = createContext<ThemeContextValue | null>(null);
 const THEME_COLORS: Record<ThemeMode, string> = {
   dark: "#1e1e1e",
   light: "#f5f6f8",
-  "flexoki-light": "#fffcf0",
-  "flexoki-dark": "#100f0f",
 };
 
-/** Map theme mode to CSS color-scheme value */
-function getColorScheme(theme: ThemeMode): "light" | "dark" {
-  return theme === "light" || theme === "flexoki-light" ? "light" : "dark";
-}
-
-function resolveSystemTheme(): ThemeMode {
+function getSystemTheme(): ThemeMode {
   if (typeof window === "undefined" || !window.matchMedia) {
     return "dark";
   }
-
   return window.matchMedia("(prefers-color-scheme: light)").matches ? "light" : "dark";
 }
 
@@ -78,7 +65,7 @@ function applyThemeToDocument(theme: ThemeMode) {
 
   const root = document.documentElement;
   root.dataset.theme = theme;
-  root.style.colorScheme = getColorScheme(theme);
+  root.style.colorScheme = theme;
 
   const themeColor = THEME_COLORS[theme];
   const meta = document.querySelector<HTMLMetaElement>('meta[name="theme-color"]');
@@ -103,66 +90,85 @@ export function ThemeProvider({
   const parentContext = useContext(ThemeContext);
   const isNestedUnderForcedProvider = parentContext?.isForced ?? false;
 
-  const [persistedTheme, setTheme] = usePersistedState<ThemeMode>(
+  // Track OS theme for "system" preference
+  const [systemTheme, setSystemTheme] = useState<ThemeMode>(getSystemTheme);
+
+  // Persist the user's preference (system | light | dark)
+  const [rawPreference, setRawPreference] = usePersistedState<ThemePreference>(
     UI_THEME_KEY,
-    resolveSystemTheme(),
-    {
-      listener: true,
-    }
+    "system",
+    { listener: true }
   );
 
-  const parsedPersistedTheme = normalizeThemeMode(persistedTheme);
-  const normalizedPersistedTheme = parsedPersistedTheme ?? resolveSystemTheme();
+  const themePreference = normalizeThemePreference(rawPreference);
+
+  // Self-heal invalid persisted values
+  useEffect(() => {
+    if (rawPreference !== themePreference) {
+      setRawPreference(themePreference);
+    }
+  }, [rawPreference, themePreference, setRawPreference]);
+
+  // Subscribe to OS theme changes (only when authoritative provider)
+  useEffect(() => {
+    if (isNestedUnderForcedProvider || typeof window === "undefined" || !window.matchMedia) {
+      return;
+    }
+
+    const mediaQuery = window.matchMedia("(prefers-color-scheme: light)");
+    const handleChange = () => {
+      setSystemTheme(mediaQuery.matches ? "light" : "dark");
+    };
+
+    mediaQuery.addEventListener("change", handleChange);
+    return () => mediaQuery.removeEventListener("change", handleChange);
+  }, [isNestedUnderForcedProvider]);
+
+  // Resolve the actual theme to apply
+  const resolvedTheme: ThemeMode = themePreference === "system" ? systemTheme : themePreference;
 
   // If nested under a forced provider, use parent's theme
-  // Otherwise, use forcedTheme (if provided) or persistedTheme
+  // Otherwise, use forcedTheme (if provided) or resolved preference
   const theme =
     isNestedUnderForcedProvider && parentContext
       ? parentContext.theme
-      : (forcedTheme ?? normalizedPersistedTheme);
+      : (forcedTheme ?? resolvedTheme);
 
   const isForced = forcedTheme !== undefined || isNestedUnderForcedProvider;
 
-  // Only apply to document if we're the authoritative provider
+  // Apply theme to document (authoritative provider only)
   useLayoutEffect(() => {
-    if (isNestedUnderForcedProvider) {
-      return;
-    }
-
-    // Self-heal legacy or invalid themes persisted in localStorage.
-    if (forcedTheme === undefined && parsedPersistedTheme !== persistedTheme) {
-      setTheme(normalizedPersistedTheme);
+    if (!isNestedUnderForcedProvider) {
+      applyThemeToDocument(theme);
     }
-
-    applyThemeToDocument(theme);
-  }, [
-    forcedTheme,
-    isNestedUnderForcedProvider,
-    normalizedPersistedTheme,
-    parsedPersistedTheme,
-    persistedTheme,
-    setTheme,
-    theme,
-  ]);
+  }, [theme, isNestedUnderForcedProvider]);
+
+  const setThemePreference = useCallback(
+    (preference: ThemePreference) => {
+      if (!isNestedUnderForcedProvider) {
+        setRawPreference(preference);
+      }
+    },
+    [setRawPreference, isNestedUnderForcedProvider]
+  );
 
   const toggleTheme = useCallback(() => {
     if (!isNestedUnderForcedProvider) {
-      setTheme((current) => {
-        const currentIndex = THEME_VALUES.indexOf(current);
-        const nextIndex = (currentIndex + 1) % THEME_VALUES.length;
-        return THEME_VALUES[nextIndex];
-      });
+      const currentIndex = PREFERENCE_VALUES.indexOf(themePreference);
+      const nextIndex = (currentIndex + 1) % PREFERENCE_VALUES.length;
+      setRawPreference(PREFERENCE_VALUES[nextIndex]);
     }
-  }, [setTheme, isNestedUnderForcedProvider]);
+  }, [themePreference, setRawPreference, isNestedUnderForcedProvider]);
 
   const value = useMemo<ThemeContextValue>(
     () => ({
       theme,
-      setTheme,
+      themePreference,
+      setThemePreference,
       toggleTheme,
       isForced,
     }),
-    [setTheme, theme, toggleTheme, isForced]
+    [theme, themePreference, setThemePreference, toggleTheme, isForced]
   );
 
   return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
diff --git a/src/browser/terminal-window.tsx b/src/browser/terminal-window.tsx
index f19f084662..4fb673e5f9 100644
--- a/src/browser/terminal-window.tsx
+++ b/src/browser/terminal-window.tsx
@@ -10,6 +10,7 @@ import ReactDOM from "react-dom/client";
 import { TerminalView } from "@/browser/components/TerminalView";
 import { APIProvider } from "@/browser/contexts/API";
 import { TerminalRouterProvider } from "@/browser/terminal/TerminalRouterContext";
+import { ThemeProvider } from "@/browser/contexts/ThemeContext";
 import "./styles/globals.css";
 
 // Get workspace ID from query parameter
@@ -30,10 +31,12 @@ if (!workspaceId || !sessionId) {
   // StrictMode intentionally double-mounts components in dev, which causes
   // race conditions with WebSocket connections and terminal lifecycle
   ReactDOM.createRoot(document.getElementById("root")!).render(
-    <APIProvider>
-      <TerminalRouterProvider>
-        <TerminalView workspaceId={workspaceId} sessionId={sessionId} visible={true} />
-      </TerminalRouterProvider>
-    </APIProvider>
+    <ThemeProvider>
+      <APIProvider>
+        <TerminalRouterProvider>
+          <TerminalView workspaceId={workspaceId} sessionId={sessionId} visible={true} />
+        </TerminalRouterProvider>
+      </APIProvider>
+    </ThemeProvider>
   );
 }
diff --git a/src/browser/utils/commands/sources.test.ts b/src/browser/utils/commands/sources.test.ts
index 7a59684b48..d68a968d6e 100644
--- a/src/browser/utils/commands/sources.test.ts
+++ b/src/browser/utils/commands/sources.test.ts
@@ -29,7 +29,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",
@@ -50,7 +50,7 @@ const mk = (over: Partial<Parameters<typeof buildCoreSources>[0]> = {}) => {
     onNavigateWorkspace: () => undefined,
     onOpenWorkspaceInTerminal: () => undefined,
     onToggleTheme: () => undefined,
-    onSetTheme: () => undefined,
+    onSetThemePreference: () => undefined,
     api: {
       workspace: {
         truncateHistory: () => Promise.resolve({ success: true, data: undefined }),
diff --git a/src/browser/utils/commands/sources.ts b/src/browser/utils/commands/sources.ts
index d69a9d6dc2..e9e00f678c 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_PREFERENCE_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";
@@ -32,7 +32,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;
@@ -64,7 +64,7 @@ export interface BuildSourcesParams {
   onNavigateWorkspace: (dir: "next" | "prev") => void;
   onOpenWorkspaceInTerminal: (workspaceId: string, runtimeConfig?: RuntimeConfig) => void;
   onToggleTheme: () => void;
-  onSetTheme: (theme: ThemeMode) => void;
+  onSetThemePreference: (preference: ThemePreference) => void;
   onOpenSettings?: (section?: string) => void;
   onClearTimingStats?: (workspaceId: string) => void;
 }
@@ -490,14 +490,14 @@ 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) {
+    // Add command for each theme preference the user isn't currently using
+    for (const opt of THEME_PREFERENCE_OPTIONS) {
+      if (p.themePreference !== opt.value) {
         list.push({
           id: CommandIds.themeSet(opt.value),
           title: `Use ${opt.label} Theme`,
           section: section.appearance,
-          run: () => p.onSetTheme(opt.value),
+          run: () => p.onSetThemePreference(opt.value),
         });
       }
     }
diff --git a/terminal.html b/terminal.html
index 40bce29ac8..bd367e13aa 100644
--- a/terminal.html
+++ b/terminal.html
@@ -3,12 +3,16 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#1e1e1e" />
     <style>
       body {
         margin: 0;
         padding: 0;
         overflow: hidden;
-        background: #1e1e1e;
+        background: var(--color-background, #1e1e1e);
+      }
+      :root[data-theme="light"] body {
+        background: #f5f6f8;
       }
       #root {
         height: 100vh;
@@ -16,6 +20,43 @@
         overflow: hidden;
       }
     </style>
+    <script>
+      (function () {
+        const THEME_KEY = "uiTheme";
+        const VALID_PREFERENCES = new Set(["system", "light", "dark"]);
+        const THEME_COLORS = { dark: "#1e1e1e", light: "#f5f6f8" };
+
+        try {
+          const stored = window.localStorage.getItem(THEME_KEY);
+          let parsed = null;
+          if (stored) {
+            try {
+              parsed = JSON.parse(stored);
+            } catch {
+              parsed = stored;
+            }
+          }
+          const preference =
+            typeof parsed === "string" && VALID_PREFERENCES.has(parsed) ? parsed : "system";
+          const systemTheme =
+            window.matchMedia && window.matchMedia("(prefers-color-scheme: light)").matches
+              ? "light"
+              : "dark";
+          const theme = preference === "system" ? systemTheme : preference;
+
+          document.documentElement.dataset.theme = theme;
+          document.documentElement.style.colorScheme = theme;
+
+          const metaThemeColor = document.querySelector('meta[name="theme-color"]');
+          if (metaThemeColor) {
+            metaThemeColor.setAttribute("content", THEME_COLORS[theme] ?? "#1e1e1e");
+          }
+        } catch {
+          document.documentElement.dataset.theme = "dark";
+          document.documentElement.style.colorScheme = "dark";
+        }
+      })();
+    </script>
   </head>
   <body>
     <div id="root"></div>

From adfb84aa49e9a06f212b16a093f531127c6d8182 Mon Sep 17 00:00:00 2001
From: Michael Suchacz <203725896+ibetitsmike@users.noreply.github.com>
Date: Fri, 16 Jan 2026 16:48:51 +0000
Subject: [PATCH 2/5] fix: toggleTheme now toggles resolved theme, not
 preference cycle

When preference is 'system', toggling now switches to the opposite of
the currently displayed theme, making the toggle button behavior intuitive.
Clicking 'Switch to dark theme' always switches to dark.
---
 src/browser/components/ThemeToggleButton.tsx | 2 +-
 src/browser/contexts/ThemeContext.tsx        | 8 ++++----
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/browser/components/ThemeToggleButton.tsx b/src/browser/components/ThemeToggleButton.tsx
index 12ddfdfd7c..ce467d6082 100644
--- a/src/browser/components/ThemeToggleButton.tsx
+++ b/src/browser/components/ThemeToggleButton.tsx
@@ -4,7 +4,7 @@ import { Tooltip, TooltipTrigger, TooltipContent } from "./ui/tooltip";
 
 export function ThemeToggleButton() {
   const { theme, toggleTheme } = useTheme();
-  const isLightTheme = theme === "light" || theme.endsWith("-light");
+  const isLightTheme = theme === "light";
   const label = isLightTheme ? "Switch to dark theme" : "Switch to light theme";
   const Icon = isLightTheme ? MoonStar : SunMedium;
 
diff --git a/src/browser/contexts/ThemeContext.tsx b/src/browser/contexts/ThemeContext.tsx
index 9d66598207..44747f17fc 100644
--- a/src/browser/contexts/ThemeContext.tsx
+++ b/src/browser/contexts/ThemeContext.tsx
@@ -152,13 +152,13 @@ export function ThemeProvider({
     [setRawPreference, isNestedUnderForcedProvider]
   );
 
+  // Toggle between light and dark based on current resolved theme.
+  // This gives intuitive behavior: if it looks light, toggle to dark (and vice versa).
   const toggleTheme = useCallback(() => {
     if (!isNestedUnderForcedProvider) {
-      const currentIndex = PREFERENCE_VALUES.indexOf(themePreference);
-      const nextIndex = (currentIndex + 1) % PREFERENCE_VALUES.length;
-      setRawPreference(PREFERENCE_VALUES[nextIndex]);
+      setRawPreference(theme === "light" ? "dark" : "light");
     }
-  }, [themePreference, setRawPreference, isNestedUnderForcedProvider]);
+  }, [theme, setRawPreference, isNestedUnderForcedProvider]);
 
   const value = useMemo<ThemeContextValue>(
     () => ({

From 04c661e7e451d1f8d8e084f481922df4e2959367 Mon Sep 17 00:00:00 2001
From: Michael Suchacz <203725896+ibetitsmike@users.noreply.github.com>
Date: Fri, 16 Jan 2026 17:08:02 +0000
Subject: [PATCH 3/5] feat: restore Flexoki themes with system preference
 support
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Keep Flexoki Light/Dark themes alongside System/Light/Dark options.
Toggle now cycles between light/dark variants of the current theme family:
- light ↔ dark
- flexoki-light ↔ flexoki-dark
---
 index.html                                   | 24 ++++++++++++++++----
 src/browser/components/ThemeToggleButton.tsx |  2 +-
 src/browser/contexts/ThemeContext.tsx        | 23 +++++++++++++++----
 terminal.html                                | 22 +++++++++++++++---
 4 files changed, 59 insertions(+), 12 deletions(-)

diff --git a/index.html b/index.html
index 0d82b23c0e..de6d634810 100644
--- a/index.html
+++ b/index.html
@@ -106,8 +106,23 @@
     <script>
       (function () {
         const THEME_KEY = "uiTheme";
-        const VALID_PREFERENCES = new Set(["system", "light", "dark"]);
-        const THEME_COLORS = { dark: "#1e1e1e", light: "#f5f6f8" };
+        const VALID_PREFERENCES = new Set([
+          "system",
+          "light",
+          "dark",
+          "flexoki-light",
+          "flexoki-dark",
+        ]);
+        const THEME_COLORS = {
+          dark: "#1e1e1e",
+          light: "#f5f6f8",
+          "flexoki-light": "#fffcf0",
+          "flexoki-dark": "#100f0f",
+        };
+
+        function getColorScheme(theme) {
+          return theme === "light" || theme === "flexoki-light" ? "light" : "dark";
+        }
 
         try {
           const stored = window.localStorage.getItem(THEME_KEY);
@@ -122,7 +137,7 @@
             }
           }
 
-          // Normalize preference: "system" | "light" | "dark" (unknown → "system")
+          // Normalize preference (unknown → "system")
           const preference =
             typeof parsed === "string" && VALID_PREFERENCES.has(parsed) ? parsed : "system";
 
@@ -132,9 +147,10 @@
               ? "light"
               : "dark";
           const theme = preference === "system" ? systemTheme : preference;
+          const colorScheme = getColorScheme(theme);
 
           document.documentElement.dataset.theme = theme;
-          document.documentElement.style.colorScheme = theme;
+          document.documentElement.style.colorScheme = colorScheme;
 
           const metaThemeColor = document.querySelector('meta[name="theme-color"]');
           if (metaThemeColor) {
diff --git a/src/browser/components/ThemeToggleButton.tsx b/src/browser/components/ThemeToggleButton.tsx
index ce467d6082..fb5dd84ede 100644
--- a/src/browser/components/ThemeToggleButton.tsx
+++ b/src/browser/components/ThemeToggleButton.tsx
@@ -4,7 +4,7 @@ import { Tooltip, TooltipTrigger, TooltipContent } from "./ui/tooltip";
 
 export function ThemeToggleButton() {
   const { theme, toggleTheme } = useTheme();
-  const isLightTheme = theme === "light";
+  const isLightTheme = theme === "light" || theme === "flexoki-light";
   const label = isLightTheme ? "Switch to dark theme" : "Switch to light theme";
   const Icon = isLightTheme ? MoonStar : SunMedium;
 
diff --git a/src/browser/contexts/ThemeContext.tsx b/src/browser/contexts/ThemeContext.tsx
index 44747f17fc..2bbe9e2f41 100644
--- a/src/browser/contexts/ThemeContext.tsx
+++ b/src/browser/contexts/ThemeContext.tsx
@@ -12,7 +12,7 @@ import { usePersistedState } from "@/browser/hooks/usePersistedState";
 import { UI_THEME_KEY } from "@/common/constants/storage";
 
 /** Concrete theme applied to the document */
-export type ThemeMode = "light" | "dark";
+export type ThemeMode = "light" | "dark" | "flexoki-light" | "flexoki-dark";
 
 /** User preference: explicit theme or follow system */
 export type ThemePreference = ThemeMode | "system";
@@ -21,6 +21,8 @@ export const THEME_PREFERENCE_OPTIONS: Array<{ value: ThemePreference; label: st
   { value: "system", label: "System" },
   { value: "light", label: "Light" },
   { value: "dark", label: "Dark" },
+  { value: "flexoki-light", label: "Flexoki Light" },
+  { value: "flexoki-dark", label: "Flexoki Dark" },
 ];
 
 const PREFERENCE_VALUES = THEME_PREFERENCE_OPTIONS.map((t) => t.value);
@@ -49,8 +51,15 @@ const ThemeContext = createContext<ThemeContextValue | null>(null);
 const THEME_COLORS: Record<ThemeMode, string> = {
   dark: "#1e1e1e",
   light: "#f5f6f8",
+  "flexoki-light": "#fffcf0",
+  "flexoki-dark": "#100f0f",
 };
 
+/** Map theme mode to CSS color-scheme value */
+function getColorScheme(theme: ThemeMode): "light" | "dark" {
+  return theme === "light" || theme === "flexoki-light" ? "light" : "dark";
+}
+
 function getSystemTheme(): ThemeMode {
   if (typeof window === "undefined" || !window.matchMedia) {
     return "dark";
@@ -65,7 +74,7 @@ function applyThemeToDocument(theme: ThemeMode) {
 
   const root = document.documentElement;
   root.dataset.theme = theme;
-  root.style.colorScheme = theme;
+  root.style.colorScheme = getColorScheme(theme);
 
   const themeColor = THEME_COLORS[theme];
   const meta = document.querySelector<HTMLMetaElement>('meta[name="theme-color"]');
@@ -152,11 +161,17 @@ export function ThemeProvider({
     [setRawPreference, isNestedUnderForcedProvider]
   );
 
-  // Toggle between light and dark based on current resolved theme.
+  // Toggle between light and dark variants of the current theme family.
   // This gives intuitive behavior: if it looks light, toggle to dark (and vice versa).
   const toggleTheme = useCallback(() => {
     if (!isNestedUnderForcedProvider) {
-      setRawPreference(theme === "light" ? "dark" : "light");
+      const themeMap: Record<ThemeMode, ThemeMode> = {
+        light: "dark",
+        dark: "light",
+        "flexoki-light": "flexoki-dark",
+        "flexoki-dark": "flexoki-light",
+      };
+      setRawPreference(themeMap[theme]);
     }
   }, [theme, setRawPreference, isNestedUnderForcedProvider]);
 
diff --git a/terminal.html b/terminal.html
index bd367e13aa..4136788ce5 100644
--- a/terminal.html
+++ b/terminal.html
@@ -23,8 +23,23 @@
     <script>
       (function () {
         const THEME_KEY = "uiTheme";
-        const VALID_PREFERENCES = new Set(["system", "light", "dark"]);
-        const THEME_COLORS = { dark: "#1e1e1e", light: "#f5f6f8" };
+        const VALID_PREFERENCES = new Set([
+          "system",
+          "light",
+          "dark",
+          "flexoki-light",
+          "flexoki-dark",
+        ]);
+        const THEME_COLORS = {
+          dark: "#1e1e1e",
+          light: "#f5f6f8",
+          "flexoki-light": "#fffcf0",
+          "flexoki-dark": "#100f0f",
+        };
+
+        function getColorScheme(theme) {
+          return theme === "light" || theme === "flexoki-light" ? "light" : "dark";
+        }
 
         try {
           const stored = window.localStorage.getItem(THEME_KEY);
@@ -43,9 +58,10 @@
               ? "light"
               : "dark";
           const theme = preference === "system" ? systemTheme : preference;
+          const colorScheme = getColorScheme(theme);
 
           document.documentElement.dataset.theme = theme;
-          document.documentElement.style.colorScheme = theme;
+          document.documentElement.style.colorScheme = colorScheme;
 
           const metaThemeColor = document.querySelector('meta[name="theme-color"]');
           if (metaThemeColor) {

From 52f392dd6f42e3d9a77593bd17b07d7b6350f433 Mon Sep 17 00:00:00 2001
From: Michael Suchacz <203725896+ibetitsmike@users.noreply.github.com>
Date: Fri, 16 Jan 2026 17:24:50 +0000
Subject: [PATCH 4/5] refactor: simplify ThemeContext API - revert
 setThemePreference to setTheme

- ThemeMode now includes 'system' (user's selection)
- ResolvedThemeMode for the actual applied theme (never 'system')
- setTheme/theme for the user's preference
- resolvedTheme for places that need the actual applied theme
- Net LoC reduction (-36 lines)
---
 .storybook/preview.tsx                        |  4 +-
 .../Settings/sections/GeneralSection.tsx      | 15 +--
 src/browser/components/ThemeSelector.tsx      | 18 +---
 src/browser/components/ThemeToggleButton.tsx  |  4 +-
 src/browser/contexts/ThemeContext.test.tsx    | 43 +++------
 src/browser/contexts/ThemeContext.tsx         | 93 +++++++++----------
 src/browser/utils/commands/sources.test.ts    |  4 +-
 src/browser/utils/commands/sources.ts         | 14 +--
 8 files changed, 80 insertions(+), 115 deletions(-)

diff --git a/.storybook/preview.tsx b/.storybook/preview.tsx
index 39f8940932..2eb24f8f0b 100644
--- a/.storybook/preview.tsx
+++ b/.storybook/preview.tsx
@@ -1,6 +1,6 @@
 import React from "react";
 import type { Preview } from "@storybook/react-vite";
-import { ThemeProvider, type ThemeMode } from "../src/browser/contexts/ThemeContext";
+import { ThemeProvider, type ResolvedThemeMode } from "../src/browser/contexts/ThemeContext";
 import "../src/browser/styles/globals.css";
 import {
   TUTORIAL_STATE_KEY,
@@ -91,7 +91,7 @@ const preview: Preview = {
     // Theme provider
     (Story, context) => {
       // Default to dark if mode not set (e.g., Chromatic headless browser defaults to light)
-      const mode = (context.globals.theme as ThemeMode | undefined) ?? "dark";
+      const mode = (context.globals.theme as ResolvedThemeMode | undefined) ?? "dark";
 
       // Apply theme synchronously before React renders - critical for Chromatic snapshots
       if (typeof document !== "undefined") {
diff --git a/src/browser/components/Settings/sections/GeneralSection.tsx b/src/browser/components/Settings/sections/GeneralSection.tsx
index 4e258c2bdc..fcf6be82b4 100644
--- a/src/browser/components/Settings/sections/GeneralSection.tsx
+++ b/src/browser/components/Settings/sections/GeneralSection.tsx
@@ -1,9 +1,5 @@
 import React, { useEffect, useState, useCallback } from "react";
-import {
-  useTheme,
-  THEME_PREFERENCE_OPTIONS,
-  type ThemePreference,
-} from "@/browser/contexts/ThemeContext";
+import { useTheme, THEME_OPTIONS, type ThemeMode } from "@/browser/contexts/ThemeContext";
 import {
   Select,
   SelectContent,
@@ -32,7 +28,7 @@ const EDITOR_OPTIONS: Array<{ value: EditorType; label: string }> = [
 const isBrowserMode = typeof window !== "undefined" && !window.api;
 
 export function GeneralSection() {
-  const { themePreference, setThemePreference } = useTheme();
+  const { theme, setTheme } = useTheme();
   const { api } = useAPI();
   const [editorConfig, setEditorConfig] = usePersistedState<EditorConfig>(
     EDITOR_CONFIG_KEY,
@@ -77,15 +73,12 @@ 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={themePreference}
-            onValueChange={(value) => setThemePreference(value as ThemePreference)}
-          >
+          <Select value={theme} onValueChange={(value) => setTheme(value as ThemeMode)}>
             <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>
             <SelectContent>
-              {THEME_PREFERENCE_OPTIONS.map((option) => (
+              {THEME_OPTIONS.map((option) => (
                 <SelectItem key={option.value} value={option.value}>
                   {option.label}
                 </SelectItem>
diff --git a/src/browser/components/ThemeSelector.tsx b/src/browser/components/ThemeSelector.tsx
index 80438f2c53..161e62a9ac 100644
--- a/src/browser/components/ThemeSelector.tsx
+++ b/src/browser/components/ThemeSelector.tsx
@@ -1,8 +1,4 @@
-import {
-  useTheme,
-  THEME_PREFERENCE_OPTIONS,
-  type ThemePreference,
-} from "@/browser/contexts/ThemeContext";
+import { useTheme, THEME_OPTIONS, type ThemeMode } from "@/browser/contexts/ThemeContext";
 import { Tooltip, TooltipTrigger, TooltipContent } from "./ui/tooltip";
 import {
   Select,
@@ -13,17 +9,13 @@ import {
 } from "@/browser/components/ui/select";
 
 export function ThemeSelector() {
-  const { themePreference, setThemePreference } = useTheme();
-  const currentLabel =
-    THEME_PREFERENCE_OPTIONS.find((t) => t.value === themePreference)?.label ?? themePreference;
+  const { theme, setTheme } = useTheme();
+  const currentLabel = THEME_OPTIONS.find((t) => t.value === theme)?.label ?? theme;
 
   return (
     <Tooltip>
       <TooltipTrigger asChild>
-        <Select
-          value={themePreference}
-          onValueChange={(value) => setThemePreference(value as ThemePreference)}
-        >
+        <Select value={theme} onValueChange={(value) => setTheme(value as ThemeMode)}>
           <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 +24,7 @@ export function ThemeSelector() {
             <SelectValue />
           </SelectTrigger>
           <SelectContent>
-            {THEME_PREFERENCE_OPTIONS.map((option) => (
+            {THEME_OPTIONS.map((option) => (
               <SelectItem key={option.value} value={option.value}>
                 {option.label}
               </SelectItem>
diff --git a/src/browser/components/ThemeToggleButton.tsx b/src/browser/components/ThemeToggleButton.tsx
index fb5dd84ede..4bb5c48965 100644
--- a/src/browser/components/ThemeToggleButton.tsx
+++ b/src/browser/components/ThemeToggleButton.tsx
@@ -3,8 +3,8 @@ import { useTheme } from "@/browser/contexts/ThemeContext";
 import { Tooltip, TooltipTrigger, TooltipContent } from "./ui/tooltip";
 
 export function ThemeToggleButton() {
-  const { theme, toggleTheme } = useTheme();
-  const isLightTheme = theme === "light" || theme === "flexoki-light";
+  const { resolvedTheme, toggleTheme } = useTheme();
+  const isLightTheme = resolvedTheme === "light" || resolvedTheme === "flexoki-light";
   const label = isLightTheme ? "Switch to dark theme" : "Switch to light theme";
   const Icon = isLightTheme ? MoonStar : SunMedium;
 
diff --git a/src/browser/contexts/ThemeContext.test.tsx b/src/browser/contexts/ThemeContext.test.tsx
index f04542468f..bb86827a37 100644
--- a/src/browser/contexts/ThemeContext.test.tsx
+++ b/src/browser/contexts/ThemeContext.test.tsx
@@ -19,13 +19,12 @@ import { UI_THEME_KEY } from "@/common/constants/storage";
 
 // Helper to access internals
 const TestComponent = () => {
-  const { theme, toggleTheme } = useTheme();
+  const { theme, resolvedTheme, toggleTheme } = useTheme();
   return (
     <div>
-      <span data-testid="theme-value">{theme}</span>
-      <button onClick={toggleTheme} data-testid="toggle-btn">
-        Toggle
-      </button>
+      <span data-testid="theme">{theme}</span>
+      <span data-testid="resolved">{resolvedTheme}</span>
+      <button onClick={toggleTheme}>Toggle</button>
     </div>
   );
 };
@@ -66,44 +65,26 @@ describe("ThemeContext", () => {
     }
   });
 
-  test("uses persisted state by default", () => {
+  test("defaults to system theme", () => {
     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-value").textContent).toBe("dark");
+    // Default is "system", which resolves to "dark" when matchMedia returns false for prefers-color-scheme: light
+    expect(getByTestId("theme").textContent).toBe("system");
+    expect(getByTestId("resolved").textContent).toBe("dark");
   });
 
-  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");
-  });
-
-  test("forcedTheme overrides persisted state", () => {
+  test("forcedTheme overrides resolved theme without changing preference", () => {
     window.localStorage.setItem(UI_THEME_KEY, JSON.stringify("light"));
-
     const { getByTestId } = render(
       <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");
+    // Preference unchanged, but resolved theme is forced
+    expect(getByTestId("theme").textContent).toBe("light");
+    expect(getByTestId("resolved").textContent).toBe("dark");
   });
 });
diff --git a/src/browser/contexts/ThemeContext.tsx b/src/browser/contexts/ThemeContext.tsx
index 2bbe9e2f41..95ab07d4c6 100644
--- a/src/browser/contexts/ThemeContext.tsx
+++ b/src/browser/contexts/ThemeContext.tsx
@@ -11,13 +11,13 @@ import React, {
 import { usePersistedState } from "@/browser/hooks/usePersistedState";
 import { UI_THEME_KEY } from "@/common/constants/storage";
 
-/** Concrete theme applied to the document */
-export type ThemeMode = "light" | "dark" | "flexoki-light" | "flexoki-dark";
+/** User's theme selection (includes "system" for OS-matching) */
+export type ThemeMode = "system" | "light" | "dark" | "flexoki-light" | "flexoki-dark";
 
-/** User preference: explicit theme or follow system */
-export type ThemePreference = ThemeMode | "system";
+/** Concrete theme applied to the document (never "system") */
+export type ResolvedThemeMode = Exclude<ThemeMode, "system">;
 
-export const THEME_PREFERENCE_OPTIONS: Array<{ value: ThemePreference; label: string }> = [
+export const THEME_OPTIONS: Array<{ value: ThemeMode; label: string }> = [
   { value: "system", label: "System" },
   { value: "light", label: "Light" },
   { value: "dark", label: "Dark" },
@@ -25,22 +25,22 @@ export const THEME_PREFERENCE_OPTIONS: Array<{ value: ThemePreference; label: st
   { value: "flexoki-dark", label: "Flexoki Dark" },
 ];
 
-const PREFERENCE_VALUES = THEME_PREFERENCE_OPTIONS.map((t) => t.value);
+const THEME_VALUES = THEME_OPTIONS.map((t) => t.value);
 
-function normalizeThemePreference(value: unknown): ThemePreference {
-  if (typeof value === "string" && PREFERENCE_VALUES.includes(value as ThemePreference)) {
-    return value as ThemePreference;
+function normalizeTheme(value: unknown): ThemeMode {
+  if (typeof value === "string" && THEME_VALUES.includes(value as ThemeMode)) {
+    return value as ThemeMode;
   }
   // Self-heal: unknown/legacy values become "system"
   return "system";
 }
 
 interface ThemeContextValue {
-  /** The resolved theme applied to the document */
+  /** The user's theme selection (system, light, dark, etc.) */
   theme: ThemeMode;
-  /** The user's preference (system, light, or dark) */
-  themePreference: ThemePreference;
-  setThemePreference: (preference: ThemePreference) => void;
+  /** The resolved theme applied to the document (never "system") */
+  resolvedTheme: ResolvedThemeMode;
+  setTheme: (theme: ThemeMode) => void;
   toggleTheme: () => void;
   /** True if this provider has a forcedTheme - nested providers should not override */
   isForced: boolean;
@@ -48,7 +48,7 @@ interface ThemeContextValue {
 
 const ThemeContext = createContext<ThemeContextValue | null>(null);
 
-const THEME_COLORS: Record<ThemeMode, string> = {
+const THEME_COLORS: Record<ResolvedThemeMode, string> = {
   dark: "#1e1e1e",
   light: "#f5f6f8",
   "flexoki-light": "#fffcf0",
@@ -56,18 +56,18 @@ const THEME_COLORS: Record<ThemeMode, string> = {
 };
 
 /** Map theme mode to CSS color-scheme value */
-function getColorScheme(theme: ThemeMode): "light" | "dark" {
+function getColorScheme(theme: ResolvedThemeMode): "light" | "dark" {
   return theme === "light" || theme === "flexoki-light" ? "light" : "dark";
 }
 
-function getSystemTheme(): ThemeMode {
+function getSystemTheme(): ResolvedThemeMode {
   if (typeof window === "undefined" || !window.matchMedia) {
     return "dark";
   }
   return window.matchMedia("(prefers-color-scheme: light)").matches ? "light" : "dark";
 }
 
-function applyThemeToDocument(theme: ThemeMode) {
+function applyThemeToDocument(theme: ResolvedThemeMode) {
   if (typeof document === "undefined") {
     return;
   }
@@ -93,30 +93,28 @@ export function ThemeProvider({
   forcedTheme,
 }: {
   children: ReactNode;
-  forcedTheme?: ThemeMode;
+  forcedTheme?: ResolvedThemeMode;
 }) {
   // Check if we're nested inside a forced theme provider
   const parentContext = useContext(ThemeContext);
   const isNestedUnderForcedProvider = parentContext?.isForced ?? false;
 
   // Track OS theme for "system" preference
-  const [systemTheme, setSystemTheme] = useState<ThemeMode>(getSystemTheme);
+  const [systemTheme, setSystemTheme] = useState<ResolvedThemeMode>(getSystemTheme);
 
-  // Persist the user's preference (system | light | dark)
-  const [rawPreference, setRawPreference] = usePersistedState<ThemePreference>(
-    UI_THEME_KEY,
-    "system",
-    { listener: true }
-  );
+  // Persist the user's theme selection
+  const [rawTheme, setRawTheme] = usePersistedState<ThemeMode>(UI_THEME_KEY, "system", {
+    listener: true,
+  });
 
-  const themePreference = normalizeThemePreference(rawPreference);
+  const theme = normalizeTheme(rawTheme);
 
   // Self-heal invalid persisted values
   useEffect(() => {
-    if (rawPreference !== themePreference) {
-      setRawPreference(themePreference);
+    if (rawTheme !== theme) {
+      setRawTheme(theme);
     }
-  }, [rawPreference, themePreference, setRawPreference]);
+  }, [rawTheme, theme, setRawTheme]);
 
   // Subscribe to OS theme changes (only when authoritative provider)
   useEffect(() => {
@@ -133,57 +131,58 @@ export function ThemeProvider({
     return () => mediaQuery.removeEventListener("change", handleChange);
   }, [isNestedUnderForcedProvider]);
 
-  // Resolve the actual theme to apply
-  const resolvedTheme: ThemeMode = themePreference === "system" ? systemTheme : themePreference;
+  // Resolve the actual theme to apply (never "system")
+  const resolved: ResolvedThemeMode =
+    theme === "system" ? systemTheme : (theme as ResolvedThemeMode);
 
-  // If nested under a forced provider, use parent's theme
+  // If nested under a forced provider, use parent's resolved theme
   // Otherwise, use forcedTheme (if provided) or resolved preference
-  const theme =
+  const resolvedTheme: ResolvedThemeMode =
     isNestedUnderForcedProvider && parentContext
-      ? parentContext.theme
-      : (forcedTheme ?? resolvedTheme);
+      ? parentContext.resolvedTheme
+      : (forcedTheme ?? resolved);
 
   const isForced = forcedTheme !== undefined || isNestedUnderForcedProvider;
 
   // Apply theme to document (authoritative provider only)
   useLayoutEffect(() => {
     if (!isNestedUnderForcedProvider) {
-      applyThemeToDocument(theme);
+      applyThemeToDocument(resolvedTheme);
     }
-  }, [theme, isNestedUnderForcedProvider]);
+  }, [resolvedTheme, isNestedUnderForcedProvider]);
 
-  const setThemePreference = useCallback(
-    (preference: ThemePreference) => {
+  const setTheme = useCallback(
+    (newTheme: ThemeMode) => {
       if (!isNestedUnderForcedProvider) {
-        setRawPreference(preference);
+        setRawTheme(newTheme);
       }
     },
-    [setRawPreference, isNestedUnderForcedProvider]
+    [setRawTheme, isNestedUnderForcedProvider]
   );
 
   // Toggle between light and dark variants of the current theme family.
   // This gives intuitive behavior: if it looks light, toggle to dark (and vice versa).
   const toggleTheme = useCallback(() => {
     if (!isNestedUnderForcedProvider) {
-      const themeMap: Record<ThemeMode, ThemeMode> = {
+      const themeMap: Record<ResolvedThemeMode, ResolvedThemeMode> = {
         light: "dark",
         dark: "light",
         "flexoki-light": "flexoki-dark",
         "flexoki-dark": "flexoki-light",
       };
-      setRawPreference(themeMap[theme]);
+      setRawTheme(themeMap[resolvedTheme]);
     }
-  }, [theme, setRawPreference, isNestedUnderForcedProvider]);
+  }, [resolvedTheme, setRawTheme, isNestedUnderForcedProvider]);
 
   const value = useMemo<ThemeContextValue>(
     () => ({
       theme,
-      themePreference,
-      setThemePreference,
+      resolvedTheme,
+      setTheme,
       toggleTheme,
       isForced,
     }),
-    [theme, themePreference, setThemePreference, toggleTheme, isForced]
+    [theme, resolvedTheme, setTheme, toggleTheme, isForced]
   );
 
   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 d68a968d6e..7a59684b48 100644
--- a/src/browser/utils/commands/sources.test.ts
+++ b/src/browser/utils/commands/sources.test.ts
@@ -29,7 +29,7 @@ const mk = (over: Partial<Parameters<typeof buildCoreSources>[0]> = {}) => {
   });
   const params: Parameters<typeof buildCoreSources>[0] = {
     projects,
-    themePreference: "dark",
+    theme: "dark",
     workspaceMetadata,
     selectedWorkspace: {
       projectPath: "/repo/a",
@@ -50,7 +50,7 @@ const mk = (over: Partial<Parameters<typeof buildCoreSources>[0]> = {}) => {
     onNavigateWorkspace: () => undefined,
     onOpenWorkspaceInTerminal: () => undefined,
     onToggleTheme: () => undefined,
-    onSetThemePreference: () => undefined,
+    onSetTheme: () => undefined,
     api: {
       workspace: {
         truncateHistory: () => Promise.resolve({ success: true, data: undefined }),
diff --git a/src/browser/utils/commands/sources.ts b/src/browser/utils/commands/sources.ts
index e9e00f678c..d69a9d6dc2 100644
--- a/src/browser/utils/commands/sources.ts
+++ b/src/browser/utils/commands/sources.ts
@@ -1,4 +1,4 @@
-import { THEME_PREFERENCE_OPTIONS, type ThemePreference } from "@/browser/contexts/ThemeContext";
+import { THEME_OPTIONS, type ThemeMode } 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";
@@ -32,7 +32,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>;
-  themePreference: ThemePreference;
+  theme: ThemeMode;
   selectedWorkspaceState?: WorkspaceState | null;
   selectedWorkspace: {
     projectPath: string;
@@ -64,7 +64,7 @@ export interface BuildSourcesParams {
   onNavigateWorkspace: (dir: "next" | "prev") => void;
   onOpenWorkspaceInTerminal: (workspaceId: string, runtimeConfig?: RuntimeConfig) => void;
   onToggleTheme: () => void;
-  onSetThemePreference: (preference: ThemePreference) => void;
+  onSetTheme: (theme: ThemeMode) => void;
   onOpenSettings?: (section?: string) => void;
   onClearTimingStats?: (workspaceId: string) => void;
 }
@@ -490,14 +490,14 @@ export function buildCoreSources(p: BuildSourcesParams): Array<() => CommandActi
       },
     ];
 
-    // Add command for each theme preference the user isn't currently using
-    for (const opt of THEME_PREFERENCE_OPTIONS) {
-      if (p.themePreference !== opt.value) {
+    // Add command for each theme the user isn't currently using
+    for (const opt of THEME_OPTIONS) {
+      if (p.theme !== opt.value) {
         list.push({
           id: CommandIds.themeSet(opt.value),
           title: `Use ${opt.label} Theme`,
           section: section.appearance,
-          run: () => p.onSetThemePreference(opt.value),
+          run: () => p.onSetTheme(opt.value),
         });
       }
     }

From 6900a91222677e8f8329173d7dfab0c277b8b3be Mon Sep 17 00:00:00 2001
From: Michael Suchacz <203725896+ibetitsmike@users.noreply.github.com>
Date: Fri, 16 Jan 2026 18:54:24 +0000
Subject: [PATCH 5/5] =?UTF-8?q?=F0=9F=A4=96=20fix:=20use=20resolved=20them?=
 =?UTF-8?q?e=20for=20visual=20rendering?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../components/Messages/MarkdownComponents.tsx     |  6 +++---
 src/browser/components/ProjectSidebar.tsx          |  5 +++--
 .../RightSidebar/FileViewer/TextFileViewer.tsx     |  6 +++---
 src/browser/components/shared/DiffRenderer.tsx     | 14 ++++++++++----
 .../components/tools/shared/HighlightedCode.tsx    |  6 +++---
 5 files changed, 22 insertions(+), 15 deletions(-)

diff --git a/src/browser/components/Messages/MarkdownComponents.tsx b/src/browser/components/Messages/MarkdownComponents.tsx
index 4a65e2fd3d..1c29f7e803 100644
--- a/src/browser/components/Messages/MarkdownComponents.tsx
+++ b/src/browser/components/Messages/MarkdownComponents.tsx
@@ -42,7 +42,7 @@ interface CodeBlockProps {
  */
 const CodeBlock: React.FC<CodeBlockProps> = ({ code, language }) => {
   const [highlightedLines, setHighlightedLines] = useState<string[] | null>(null);
-  const { theme: themeMode } = useTheme();
+  const { resolvedTheme } = useTheme();
 
   // Split code into lines, removing trailing empty line
   const plainLines = code
@@ -51,7 +51,7 @@ const CodeBlock: React.FC<CodeBlockProps> = ({ code, language }) => {
 
   useEffect(() => {
     let cancelled = false;
-    const isLight = themeMode === "light" || themeMode.endsWith("-light");
+    const isLight = resolvedTheme === "light" || resolvedTheme.endsWith("-light");
     const theme = isLight ? "light" : "dark";
 
     setHighlightedLines(null);
@@ -78,7 +78,7 @@ const CodeBlock: React.FC<CodeBlockProps> = ({ code, language }) => {
     return () => {
       cancelled = true;
     };
-  }, [code, language, themeMode]);
+  }, [code, language, resolvedTheme]);
 
   const lines = highlightedLines ?? plainLines;
   const isSingleLine = lines.length === 1;
diff --git a/src/browser/components/ProjectSidebar.tsx b/src/browser/components/ProjectSidebar.tsx
index 7b984a46e4..a013af86f2 100644
--- a/src/browser/components/ProjectSidebar.tsx
+++ b/src/browser/components/ProjectSidebar.tsx
@@ -245,8 +245,9 @@ const ProjectSidebarInner: React.FC<ProjectSidebarProps> = ({
   } = useProjectContext();
 
   // Theme for logo variant
-  const { theme } = useTheme();
-  const MuxLogo = theme === "dark" || theme.endsWith("-dark") ? MuxLogoDark : MuxLogoLight;
+  const { resolvedTheme } = useTheme();
+  const MuxLogo =
+    resolvedTheme === "dark" || resolvedTheme.endsWith("-dark") ? MuxLogoDark : MuxLogoLight;
 
   // Mobile breakpoint for auto-closing sidebar
   const MOBILE_BREAKPOINT = 768;
diff --git a/src/browser/components/RightSidebar/FileViewer/TextFileViewer.tsx b/src/browser/components/RightSidebar/FileViewer/TextFileViewer.tsx
index f294a2c790..633bc4e4c7 100644
--- a/src/browser/components/RightSidebar/FileViewer/TextFileViewer.tsx
+++ b/src/browser/components/RightSidebar/FileViewer/TextFileViewer.tsx
@@ -137,7 +137,7 @@ function buildUnifiedView(content: string, diffText: string): UnifiedLine[] | nu
 }
 
 export const TextFileViewer: React.FC<TextFileViewerProps> = (props) => {
-  const { theme: themeMode } = useTheme();
+  const { resolvedTheme } = useTheme();
   const language = getLanguageFromPath(props.filePath);
   const languageDisplayName = getLanguageDisplayName(language);
 
@@ -160,7 +160,7 @@ export const TextFileViewer: React.FC<TextFileViewerProps> = (props) => {
       ? unifiedLines.map((l) => l.content)
       : fileLines.filter((l, i, arr) => i < arr.length - 1 || l !== "");
 
-    const theme = themeMode === "light" || themeMode.endsWith("-light") ? "light" : "dark";
+    const theme = resolvedTheme === "light" || resolvedTheme.endsWith("-light") ? "light" : "dark";
 
     let cancelled = false;
 
@@ -181,7 +181,7 @@ export const TextFileViewer: React.FC<TextFileViewerProps> = (props) => {
     return () => {
       cancelled = true;
     };
-  }, [unifiedLines, fileLines, language, themeMode]);
+  }, [unifiedLines, fileLines, language, resolvedTheme]);
 
   const addedCount = unifiedLines?.filter((l) => l.type === "added").length ?? 0;
   const removedCount = unifiedLines?.filter((l) => l.type === "removed").length ?? 0;
diff --git a/src/browser/components/shared/DiffRenderer.tsx b/src/browser/components/shared/DiffRenderer.tsx
index de08c38341..9c8f739eef 100644
--- a/src/browser/components/shared/DiffRenderer.tsx
+++ b/src/browser/components/shared/DiffRenderer.tsx
@@ -500,13 +500,19 @@ export const DiffRenderer: React.FC<DiffRendererProps> = ({
   className,
 }) => {
   // Detect language for syntax highlighting (memoized to prevent repeated detection)
-  const { theme } = useTheme();
+  const { resolvedTheme } = useTheme();
   const language = React.useMemo(
     () => (filePath ? getLanguageFromPath(filePath) : "text"),
     [filePath]
   );
 
-  const highlightedChunks = useHighlightedDiff(content, language, oldStart, newStart, theme);
+  const highlightedChunks = useHighlightedDiff(
+    content,
+    language,
+    oldStart,
+    newStart,
+    resolvedTheme
+  );
 
   const lineNumberWidths = React.useMemo(() => {
     if (!showLineNumbers || !highlightedChunks) {
@@ -866,7 +872,7 @@ export const SelectableDiffRenderer = React.memo<SelectableDiffRendererProps>(
         window.removeEventListener("blur", stopDragging);
       };
     }, []);
-    const { theme } = useTheme();
+    const { resolvedTheme } = useTheme();
     const [selection, setSelection] = React.useState<LineSelection | null>(null);
 
     // Notify parent when composition state changes
@@ -895,7 +901,7 @@ export const SelectableDiffRenderer = React.memo<SelectableDiffRendererProps>(
       enableHighlighting ? language : "text",
       oldStart,
       newStart,
-      theme
+      resolvedTheme
     );
 
     // Parse raw lines once for use in lineData
diff --git a/src/browser/components/tools/shared/HighlightedCode.tsx b/src/browser/components/tools/shared/HighlightedCode.tsx
index 1b2d4bcef2..2deb4e59b8 100644
--- a/src/browser/components/tools/shared/HighlightedCode.tsx
+++ b/src/browser/components/tools/shared/HighlightedCode.tsx
@@ -25,13 +25,13 @@ export const HighlightedCode: React.FC<HighlightedCodeProps> = ({
   startLineNumber = 1,
 }) => {
   const [highlightedLines, setHighlightedLines] = useState<string[] | null>(null);
-  const { theme: themeMode } = useTheme();
+  const { resolvedTheme } = useTheme();
 
   const plainLines = code.split("\n").filter((line, i, arr) => i < arr.length - 1 || line !== "");
 
   useEffect(() => {
     let cancelled = false;
-    const theme = themeMode === "light" || themeMode.endsWith("-light") ? "light" : "dark";
+    const theme = resolvedTheme === "light" || resolvedTheme.endsWith("-light") ? "light" : "dark";
 
     setHighlightedLines(null);
 
@@ -53,7 +53,7 @@ export const HighlightedCode: React.FC<HighlightedCodeProps> = ({
     return () => {
       cancelled = true;
     };
-  }, [code, language, themeMode]);
+  }, [code, language, resolvedTheme]);
 
   const lines = highlightedLines ?? plainLines;