🤖 fix: apply theme synchronously in decorator before React renders

Root cause: useLayoutEffect in ThemeStorySync still created a race condition
where Chromatic could capture snapshots before the theme was applied.

Fix (same pattern as coder/coder):
- Apply theme to document.documentElement synchronously in decorator
- Pass forcedTheme prop to ThemeProvider so it doesn't read localStorage
- Decorator runs BEFORE React tree is created, ensuring theme is correct
- ThemeProvider respects forcedTheme and skips persistence/listener

This eliminates all timing issues - theme is on document before any
component renders or useLayoutEffect runs.

Author: ethanndickson

.storybook/preview.tsx

@@ -1,24 +1,8 @@
-import React, { useLayoutEffect } from "react";
+import React from "react";
 import type { Preview } from "@storybook/react-vite";
-import {
-  ThemeProvider,
-  useTheme,
-  type ThemeMode,
-} from "../src/browser/contexts/ThemeContext";
+import { ThemeProvider, type ThemeMode } from "../src/browser/contexts/ThemeContext";
 import "../src/browser/styles/globals.css";
 
-const ThemeStorySync: React.FC<{ mode: ThemeMode }> = ({ mode }) => {
-  const { theme, setTheme } = useTheme();
-
-  useLayoutEffect(() => {
-    if (theme !== mode) {
-      setTheme(mode);
-    }
-  }, [mode, setTheme, theme]);
-
-  return null;
-};
-
 const preview: Preview = {
   globalTypes: {
     theme: {
@@ -37,10 +21,18 @@ const preview: Preview = {
   },
   decorators: [
     (Story, context) => {
-      const mode = (context.globals.theme ?? "dark") as ThemeMode;
+      const mode = context.globals.theme as ThemeMode | undefined;
+      const selected = mode ?? "dark";
+
+      // Apply theme SYNCHRONOUSLY before React renders (prevents race condition)
+      // This ensures Chromatic snapshots always capture the correct theme
+      if (typeof document !== "undefined") {
+        document.documentElement.dataset.theme = selected;
+        document.documentElement.style.colorScheme = selected;
+      }
+
       return (
-        <ThemeProvider>
-          <ThemeStorySync mode={mode} />
+        <ThemeProvider forcedTheme={mode}>
           <Story />
         </ThemeProvider>
       );

src/browser/contexts/ThemeContext.tsx

@@ -51,26 +51,36 @@ function applyThemeToDocument(theme: ThemeMode) {
   }
 }
 
-export function ThemeProvider(props: { children: ReactNode }) {
-  const [theme, setTheme] = usePersistedState<ThemeMode>(UI_THEME_KEY, resolveSystemTheme(), {
-    listener: true,
-  });
+export function ThemeProvider(props: { children: ReactNode; forcedTheme?: ThemeMode }) {
+  const [persistedTheme, setPersistedTheme] = usePersistedState<ThemeMode>(
+    UI_THEME_KEY,
+    resolveSystemTheme(),
+    {
+      listener: !props.forcedTheme, // Disable listener when theme is forced
+    }
+  );
+
+  // Use forcedTheme if provided (e.g., from Storybook), otherwise use persisted theme
+  const activeTheme = props.forcedTheme ?? persistedTheme;
 
   useLayoutEffect(() => {
-    applyThemeToDocument(theme);
-  }, [theme]);
+    applyThemeToDocument(activeTheme);
+  }, [activeTheme]);
 
   const toggleTheme = useCallback(() => {
-    setTheme((current) => (current === "dark" ? "light" : "dark"));
-  }, [setTheme]);
+    // Only allow toggling when not forced
+    if (!props.forcedTheme) {
+      setPersistedTheme((current) => (current === "dark" ? "light" : "dark"));
+    }
+  }, [props.forcedTheme, setPersistedTheme]);
 
   const value = useMemo<ThemeContextValue>(
     () => ({
-      theme,
-      setTheme,
+      theme: activeTheme,
+      setTheme: setPersistedTheme,
       toggleTheme,
     }),
-    [setTheme, theme, toggleTheme]
+    [activeTheme, setPersistedTheme, toggleTheme]
   );
 
   return <ThemeContext.Provider value={value}>{props.children}</ThemeContext.Provider>;