Merge branch 'pr-164'

Author: mikewheeleer

docs/theme-storage.md

@@ -0,0 +1,10 @@
+# Theme Storage
+
+StableRoute stores the appearance preference in `localStorage` under
+`stableroute.theme`. The only accepted values are `light`, `dark`, and
+`system`.
+
+If storage is unavailable, throws, or contains an unknown value, `readTheme`
+falls back to `system`. `writeTheme` is best-effort and silently skips the write
+when storage rejects access, so theme persistence cannot crash hydration or
+rendering.

src/lib/__tests__/theme.test.ts

@@ -0,0 +1,73 @@
+import { effectiveTheme, readTheme, writeTheme } from "../theme";
+
+const originalLocalStorage = window.localStorage;
+const originalMatchMedia = window.matchMedia;
+
+function replaceLocalStorage(storage: Partial<Storage>) {
+  Object.defineProperty(window, "localStorage", {
+    configurable: true,
+    value: storage,
+  });
+}
+
+afterEach(() => {
+  Object.defineProperty(window, "localStorage", {
+    configurable: true,
+    value: originalLocalStorage,
+  });
+  window.localStorage.clear();
+  window.matchMedia = originalMatchMedia;
+  jest.restoreAllMocks();
+});
+
+describe("theme storage helpers", () => {
+  it("round-trips valid stored themes", () => {
+    writeTheme("dark");
+
+    expect(window.localStorage.getItem("stableroute.theme")).toBe("dark");
+    expect(readTheme()).toBe("dark");
+  });
+
+  it("falls back to system for missing or corrupted stored values", () => {
+    expect(readTheme()).toBe("system");
+
+    window.localStorage.setItem("stableroute.theme", "midnight");
+    expect(readTheme()).toBe("system");
+  });
+
+  it("falls back to system when localStorage.getItem throws", () => {
+    replaceLocalStorage({
+      getItem: jest.fn(() => {
+        throw new Error("storage disabled");
+      }),
+    });
+
+    expect(readTheme()).toBe("system");
+  });
+
+  it("treats write failures as a no-op", () => {
+    const setItem = jest.fn(() => {
+      throw new Error("quota exceeded");
+    });
+    replaceLocalStorage({ setItem });
+
+    expect(() => writeTheme("light")).not.toThrow();
+    expect(setItem).toHaveBeenCalledWith("stableroute.theme", "light");
+  });
+});
+
+describe("effectiveTheme", () => {
+  it("returns explicit light or dark themes without media queries", () => {
+    expect(effectiveTheme("light")).toBe("light");
+    expect(effectiveTheme("dark")).toBe("dark");
+  });
+
+  it("resolves system through prefers-color-scheme", () => {
+    window.matchMedia = jest.fn().mockReturnValue({ matches: true });
+
+    expect(effectiveTheme("system")).toBe("dark");
+    expect(window.matchMedia).toHaveBeenCalledWith(
+      "(prefers-color-scheme: dark)",
+    );
+  });
+});

src/lib/theme.ts

@@ -2,15 +2,29 @@ export type Theme = "light" | "dark" | "system";
 
 const KEY = "stableroute.theme";
 
+function isTheme(value: string | null): value is Theme {
+  return value === "light" || value === "dark" || value === "system";
+}
+
 export function readTheme(): Theme {
   if (typeof window === "undefined") return "system";
-  const v = window.localStorage.getItem(KEY);
-  return v === "light" || v === "dark" || v === "system" ? v : "system";
+
+  try {
+    const v = window.localStorage.getItem(KEY);
+    return isTheme(v) ? v : "system";
+  } catch {
+    return "system";
+  }
 }
 
 export function writeTheme(theme: Theme) {
   if (typeof window === "undefined") return;
-  window.localStorage.setItem(KEY, theme);
+
+  try {
+    window.localStorage.setItem(KEY, theme);
+  } catch {
+    // Storage can throw in privacy modes; theme writes are best-effort only.
+  }
 }
 
 export function effectiveTheme(theme: Theme): "light" | "dark" {