fix(app): add 3-way theme preference with system-follow, bootstrap, and accessibility

- Refactor theme state to support light/dark/system preference model
- Add pre-paint bootstrap script in index.html to prevent first-load flash
- Persist preference (not resolved theme) to avoid overwriting system choice
- Add live OS theme change listener for system-follow behavior
- Sync meta theme-color on theme changes
- Suppress transitions during theme apply to reduce visual flash
- Replace custom radio with accessible RadioGroup + RadioGroupItem
- Expand tests for preference persistence and theme-color updates
- Add sync comments between bootstrap and runtime logic

Author: AchuAshwath

apps/app/index.html

@@ -14,6 +14,57 @@
     <meta property="og:url" content="" />
     <meta property="og:image" content="" />
     <meta name="theme-color" content="#fafafa" />
+    <script>
+      (() => {
+        // Keep this bootstrap logic in sync with runtime theme resolution in lib/theme.tsx.
+        const STORAGE_KEY = "app-theme-preference";
+        const LEGACY_STORAGE_KEY = "app-theme";
+        const LIGHT_THEME_COLOR = "#fafafa";
+        const DARK_THEME_COLOR = "#0f0f0f";
+
+        function parsePreference(value) {
+          if (value === "light" || value === "dark" || value === "system") {
+            return value;
+          }
+          return null;
+        }
+
+        function getSystemTheme() {
+          return window.matchMedia?.("(prefers-color-scheme: dark)").matches
+            ? "dark"
+            : "light";
+        }
+
+        let preference = "system";
+
+        try {
+          const stored = parsePreference(
+            window.localStorage.getItem(STORAGE_KEY),
+          );
+          if (stored) {
+            preference = stored;
+          } else {
+            const legacy = parsePreference(
+              window.localStorage.getItem(LEGACY_STORAGE_KEY),
+            );
+            if (legacy === "light" || legacy === "dark") {
+              preference = legacy;
+            }
+          }
+        } catch {
+          preference = "system";
+        }
+
+        const theme = preference === "system" ? getSystemTheme() : preference;
+        document.documentElement.classList.toggle("dark", theme === "dark");
+
+        const meta = document.querySelector('meta[name="theme-color"]');
+        meta?.setAttribute(
+          "content",
+          theme === "dark" ? DARK_THEME_COLOR : LIGHT_THEME_COLOR,
+        );
+      })();
+    </script>
 
     <link rel="icon" href="/favicon.ico" sizes="any" />
     <link rel="apple-touch-icon" href="/logo192.png" />

apps/app/lib/theme.test.tsx

@@ -9,19 +9,20 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { ThemeProvider, useTheme } from "./theme";
 
 function ThemeProbe() {
-  const { theme, setTheme, toggleTheme } = useTheme();
+  const { theme, preference, setPreference } = useTheme();
 
   return (
     <>
-      <div data-testid="theme-value">{theme}</div>
-      <button onClick={() => setTheme("dark")} type="button">
-        set-dark
-      </button>
-      <button onClick={() => setTheme("light")} type="button">
+      <div data-testid="resolved-theme">{theme}</div>
+      <div data-testid="preference">{preference}</div>
+      <button onClick={() => setPreference("light")} type="button">
         set-light
       </button>
-      <button onClick={toggleTheme} type="button">
-        toggle-theme
+      <button onClick={() => setPreference("dark")} type="button">
+        set-dark
+      </button>
+      <button onClick={() => setPreference("system")} type="button">
+        set-system
       </button>
     </>
   );
@@ -32,6 +33,19 @@ describe("ThemeProvider", () => {
   let originalMatchMedia: typeof window.matchMedia | undefined;
   let originalLocalStorage: Storage;
 
+  function createMediaQueryList(matches: boolean): MediaQueryList {
+    return {
+      matches,
+      media: "(prefers-color-scheme: dark)",
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    } as unknown as MediaQueryList;
+  }
+
   const localStorageMock: Storage = {
     getItem: (key: string) => storage.get(key) ?? null,
     setItem: (key: string, value: string) => {
@@ -56,13 +70,30 @@ describe("ThemeProvider", () => {
     originalMatchMedia = window.matchMedia;
     originalLocalStorage = window.localStorage;
 
+    Object.defineProperty(window, "matchMedia", {
+      configurable: true,
+      writable: true,
+      value: vi.fn().mockReturnValue(createMediaQueryList(false)),
+    });
+
     Object.defineProperty(window, "localStorage", {
       configurable: true,
       writable: true,
       value: localStorageMock,
     });
+
     window.localStorage.clear();
     document.documentElement.classList.remove("dark");
+
+    const existingMeta = document.querySelector('meta[name="theme-color"]');
+    if (!existingMeta) {
+      const meta = document.createElement("meta");
+      meta.setAttribute("name", "theme-color");
+      meta.setAttribute("content", "#fafafa");
+      document.head.appendChild(meta);
+    } else {
+      existingMeta.setAttribute("content", "#fafafa");
+    }
   });
 
   afterEach(() => {
@@ -85,89 +116,103 @@ describe("ThemeProvider", () => {
     vi.restoreAllMocks();
   });
 
-  it("uses persisted localStorage theme on first render", () => {
-    window.localStorage.setItem("app-theme", "dark");
+  it("defaults to system preference when nothing is stored", () => {
+    Object.defineProperty(window, "matchMedia", {
+      configurable: true,
+      writable: true,
+      value: vi.fn().mockReturnValue(createMediaQueryList(true)),
+    });
 
     render(
       <ThemeProvider>
         <ThemeProbe />
       </ThemeProvider>,
     );
 
-    expect(screen.getByTestId("theme-value")).toHaveTextContent("dark");
-    expect(document.documentElement.classList.contains("dark")).toBe(true);
+    expect(screen.getByTestId("preference")).toHaveTextContent("system");
+    expect(screen.getByTestId("resolved-theme")).toHaveTextContent("dark");
+    expect(window.localStorage.getItem("app-theme-preference")).toBe("system");
   });
 
-  it("falls back to system preference when no theme is persisted", () => {
-    Object.defineProperty(window, "matchMedia", {
-      configurable: true,
-      writable: true,
-      value: vi.fn().mockImplementation((query: string) => ({
-        matches: query === "(prefers-color-scheme: dark)",
-        media: query,
-        onchange: null,
-        addEventListener: vi.fn(),
-        removeEventListener: vi.fn(),
-        dispatchEvent: vi.fn(),
-      })),
-    });
+  it("uses persisted explicit preference", () => {
+    window.localStorage.setItem("app-theme-preference", "dark");
 
     render(
       <ThemeProvider>
         <ThemeProbe />
       </ThemeProvider>,
     );
 
-    expect(screen.getByTestId("theme-value")).toHaveTextContent("dark");
+    expect(screen.getByTestId("preference")).toHaveTextContent("dark");
+    expect(screen.getByTestId("resolved-theme")).toHaveTextContent("dark");
     expect(document.documentElement.classList.contains("dark")).toBe(true);
+    expect(
+      document
+        .querySelector('meta[name="theme-color"]')
+        ?.getAttribute("content"),
+    ).toBe("#0f0f0f");
   });
 
-  it("writes updates to localStorage and keeps DOM class in sync", () => {
+  it("migrates legacy app-theme values", () => {
+    window.localStorage.setItem("app-theme", "light");
+
     render(
       <ThemeProvider>
         <ThemeProbe />
       </ThemeProvider>,
     );
 
-    fireEvent.click(screen.getByRole("button", { name: "set-dark" }));
-    expect(window.localStorage.getItem("app-theme")).toBe("dark");
-    expect(document.documentElement.classList.contains("dark")).toBe(true);
-
-    fireEvent.click(screen.getByRole("button", { name: "set-light" }));
-    expect(window.localStorage.getItem("app-theme")).toBe("light");
-    expect(document.documentElement.classList.contains("dark")).toBe(false);
+    expect(screen.getByTestId("preference")).toHaveTextContent("light");
+    expect(window.localStorage.getItem("app-theme-preference")).toBe("light");
   });
 
-  it("reacts to theme updates from storage events", async () => {
+  it("updates preference and stores only the preference", () => {
     render(
       <ThemeProvider>
         <ThemeProbe />
       </ThemeProvider>,
     );
 
-    const event = new Event("storage");
-    Object.defineProperty(event, "key", { value: "app-theme" });
-    Object.defineProperty(event, "newValue", { value: "dark" });
-    window.dispatchEvent(event);
+    fireEvent.click(screen.getByRole("button", { name: "set-dark" }));
+    expect(screen.getByTestId("preference")).toHaveTextContent("dark");
+    expect(window.localStorage.getItem("app-theme-preference")).toBe("dark");
+    expect(
+      document
+        .querySelector('meta[name="theme-color"]')
+        ?.getAttribute("content"),
+    ).toBe("#0f0f0f");
 
-    await waitFor(() => {
-      expect(screen.getByTestId("theme-value")).toHaveTextContent("dark");
-      expect(document.documentElement.classList.contains("dark")).toBe(true);
-    });
+    fireEvent.click(screen.getByRole("button", { name: "set-light" }));
+    expect(screen.getByTestId("preference")).toHaveTextContent("light");
+    expect(window.localStorage.getItem("app-theme-preference")).toBe("light");
+    expect(
+      document
+        .querySelector('meta[name="theme-color"]')
+        ?.getAttribute("content"),
+    ).toBe("#fafafa");
+
+    fireEvent.click(screen.getByRole("button", { name: "set-system" }));
+    expect(screen.getByTestId("preference")).toHaveTextContent("system");
+    expect(window.localStorage.getItem("app-theme-preference")).toBe("system");
   });
 
-  it("falls back to system preference when storage key is cleared", async () => {
+  it("reacts to OS theme changes while preference is system", async () => {
+    const listeners = new Set<(event: MediaQueryListEvent) => void>();
+
     Object.defineProperty(window, "matchMedia", {
       configurable: true,
       writable: true,
-      value: vi.fn().mockImplementation((query: string) => ({
-        matches: query === "(prefers-color-scheme: dark)",
-        media: query,
-        onchange: null,
-        addEventListener: vi.fn(),
-        removeEventListener: vi.fn(),
-        dispatchEvent: vi.fn(),
-      })),
+      value: vi.fn().mockReturnValue({
+        ...createMediaQueryList(false),
+        addEventListener: (
+          _: string,
+          cb: (event: MediaQueryListEvent) => void,
+        ) => listeners.add(cb),
+        removeEventListener: (
+          _: string,
+          cb: (event: MediaQueryListEvent) => void,
+        ) => listeners.delete(cb),
+      }),
     });
 
     render(
@@ -176,65 +221,46 @@ describe("ThemeProvider", () => {
       </ThemeProvider>,
     );
 
-    fireEvent.click(screen.getByRole("button", { name: "set-light" }));
-    window.localStorage.removeItem("app-theme");
+    expect(screen.getByTestId("resolved-theme")).toHaveTextContent("light");
 
-    const event = new Event("storage");
-    Object.defineProperty(event, "key", { value: "app-theme" });
-    Object.defineProperty(event, "newValue", { value: null });
-    window.dispatchEvent(event);
+    listeners.forEach((listener) =>
+      listener({ matches: true } as MediaQueryListEvent),
+    );
 
     await waitFor(() => {
-      expect(screen.getByTestId("theme-value")).toHaveTextContent("dark");
+      expect(screen.getByTestId("resolved-theme")).toHaveTextContent("dark");
+      expect(document.documentElement.classList.contains("dark")).toBe(true);
+      expect(
+        document
+          .querySelector('meta[name="theme-color"]')
+          ?.getAttribute("content"),
+      ).toBe("#0f0f0f");
     });
   });
 
-  it("recovers when storage read throws", () => {
-    Object.defineProperty(window, "localStorage", {
-      configurable: true,
-      writable: true,
-      value: {
-        ...localStorageMock,
-        getItem: () => {
-          throw new Error("read denied");
-        },
-      } as Storage,
-    });
-
-    Object.defineProperty(window, "matchMedia", {
-      configurable: true,
-      writable: true,
-      value: vi.fn().mockImplementation((query: string) => ({
-        matches: query === "(prefers-color-scheme: dark)",
-        media: query,
-        onchange: null,
-        addEventListener: vi.fn(),
-        removeEventListener: vi.fn(),
-        dispatchEvent: vi.fn(),
-      })),
-    });
-
+  it("syncs preference across tabs via storage events", async () => {
     render(
       <ThemeProvider>
         <ThemeProbe />
       </ThemeProvider>,
     );
 
-    expect(screen.getByTestId("theme-value")).toHaveTextContent("dark");
-  });
+    const event = new Event("storage");
+    Object.defineProperty(event, "key", { value: "app-theme-preference" });
+    Object.defineProperty(event, "newValue", { value: "dark" });
+    window.dispatchEvent(event);
 
-  it("ignores storage write failures", () => {
-    const setItem = vi.fn(() => {
-      throw new Error("write denied");
+    await waitFor(() => {
+      expect(screen.getByTestId("preference")).toHaveTextContent("dark");
+      expect(screen.getByTestId("resolved-theme")).toHaveTextContent("dark");
     });
+  });
 
-    Object.defineProperty(window, "localStorage", {
+  it("does not overwrite preference with resolved system theme", () => {
+    Object.defineProperty(window, "matchMedia", {
       configurable: true,
       writable: true,
-      value: {
-        ...localStorageMock,
-        setItem,
-      } as Storage,
+      value: vi.fn().mockReturnValue(createMediaQueryList(true)),
     });
 
     render(
@@ -243,9 +269,8 @@ describe("ThemeProvider", () => {
       </ThemeProvider>,
     );
 
-    fireEvent.click(screen.getByRole("button", { name: "set-dark" }));
-    expect(screen.getByTestId("theme-value")).toHaveTextContent("dark");
-    expect(document.documentElement.classList.contains("dark")).toBe(true);
-    expect(setItem).toHaveBeenCalled();
+    expect(screen.getByTestId("preference")).toHaveTextContent("system");
+    expect(screen.getByTestId("resolved-theme")).toHaveTextContent("dark");
+    expect(window.localStorage.getItem("app-theme-preference")).toBe("system");
   });
 });