🤖 fix: apply Storybook theme synchronously before React renders

Root cause: Original code used useEffect to set theme, which is async.
Chromatic sometimes captured snapshots before the effect ran.

Also removed:
- preview-head.html (not needed, decorator handles theme)
- ThemeProvider.forcedTheme prop (not needed, decorator sets localStorage)

Fix:
- Restored defaultValue: 'dark' in globalTypes (ensures context.globals.theme always has value)
- Apply theme synchronously in decorator BEFORE React renders
- Write to localStorage, document.dataset.theme, and colorScheme directly

Net: -25 lines

Author: ethanndickson

.storybook/preview-head.html

@@ -1,13 +1,15 @@
 import React from "react";
 import type { Preview } from "@storybook/react-vite";
 import { ThemeProvider, type ThemeMode } from "../src/browser/contexts/ThemeContext";
+import { UI_THEME_KEY } from "../src/common/constants/storage";
 import "../src/browser/styles/globals.css";
 
 const preview: Preview = {
   globalTypes: {
     theme: {
       name: "Theme",
       description: "Choose between light and dark UI themes",
+      defaultValue: "dark",
       toolbar: {
         icon: "mirror",
         items: [
@@ -20,17 +22,19 @@ const preview: Preview = {
   },
   decorators: [
     (Story, context) => {
-      const mode = context.globals.theme as ThemeMode | undefined;
+      const mode = (context.globals.theme ?? "dark") as ThemeMode;
 
-      // Apply theme synchronously to document BEFORE React renders
-      // This ensures Chromatic snapshots capture the correct theme without flashing
-      if (mode && typeof document !== "undefined") {
+      // Apply theme synchronously BEFORE React renders
+      // This ensures Chromatic snapshots capture the correct theme without timing issues
+      if (typeof window !== "undefined") {
+        const serialized = JSON.stringify(mode);
+        window.localStorage.setItem(UI_THEME_KEY, serialized);
         document.documentElement.dataset.theme = mode;
         document.documentElement.style.colorScheme = mode;
       }
 
       return (
-        <ThemeProvider forcedTheme={mode}>
+        <ThemeProvider>
           <Story />
         </ThemeProvider>
       );

.storybook/preview.tsx

@@ -51,39 +51,26 @@ function applyThemeToDocument(theme: ThemeMode) {
   }
 }
 
-export function ThemeProvider(props: { children: ReactNode; forcedTheme?: ThemeMode }) {
-  // Only use persistence when theme is NOT forced
-  // When forcedTheme is provided (e.g., from Chromatic modes), bypass persistence entirely
-  const [persistedTheme, setPersistedTheme] = usePersistedState<ThemeMode>(
-    UI_THEME_KEY,
-    resolveSystemTheme(),
-    {
-      listener: !props.forcedTheme, // Disable listener when theme is forced (avoids conflicts)
-    }
-  );
-
-  // Use forcedTheme if provided, otherwise use persisted theme
-  // This ensures Chromatic modes (which set forcedTheme) are respected
-  const activeTheme = props.forcedTheme ?? persistedTheme;
+export function ThemeProvider(props: { children: ReactNode }) {
+  const [theme, setTheme] = usePersistedState<ThemeMode>(UI_THEME_KEY, resolveSystemTheme(), {
+    listener: true,
+  });
 
   useLayoutEffect(() => {
-    applyThemeToDocument(activeTheme);
-  }, [activeTheme]);
+    applyThemeToDocument(theme);
+  }, [theme]);
 
   const toggleTheme = useCallback(() => {
-    // Only allow toggling when not forced
-    if (!props.forcedTheme) {
-      setPersistedTheme((current) => (current === "dark" ? "light" : "dark"));
-    }
-  }, [props.forcedTheme, setPersistedTheme]);
+    setTheme((current) => (current === "dark" ? "light" : "dark"));
+  }, [setTheme]);
 
   const value = useMemo<ThemeContextValue>(
     () => ({
-      theme: activeTheme,
-      setTheme: setPersistedTheme,
+      theme,
+      setTheme,
       toggleTheme,
     }),
-    [activeTheme, setPersistedTheme, toggleTheme]
+    [setTheme, theme, toggleTheme]
   );
 
   return <ThemeContext.Provider value={value}>{props.children}</ThemeContext.Provider>;