@rangojs/router 0.0.0-experimental.ea6d5eec → 0.0.0-experimental.ea9f40f2

package/src/theme/ThemeProvider.tsx

@@ -26,11 +26,8 @@ import type {
   ThemeContextValue,
   ThemeProviderProps,
 } from "./types.js";
-import { THEME_COOKIE } from "./constants.js";
+import { THEME_COOKIE, isValidTheme, warnInvalidTheme } from "./constants.js";
 
-/**
- * Get system preference for color scheme
- */
 function getSystemTheme(): ResolvedTheme {
   if (typeof window !== "undefined" && window.matchMedia) {
     return window.matchMedia("(prefers-color-scheme: dark)").matches
@@ -40,9 +37,6 @@ function getSystemTheme(): ResolvedTheme {
   return "light";
 }
 
-/**
- * Read theme from cookie
- */
 function readThemeFromCookie(storageKey: string): string | null {
   if (typeof document === "undefined") return null;
 
@@ -61,9 +55,6 @@ function readThemeFromCookie(storageKey: string): string | null {
   return null;
 }
 
-/**
- * Read theme from localStorage
- */
 function readThemeFromStorage(storageKey: string): string | null {
   if (typeof localStorage === "undefined") return null;
 
@@ -74,9 +65,6 @@ function readThemeFromStorage(storageKey: string): string | null {
   }
 }
 
-/**
- * Write theme to cookie
- */
 function writeThemeToCookie(storageKey: string, theme: Theme): void {
   if (typeof document === "undefined") return;
 
@@ -85,9 +73,6 @@ function writeThemeToCookie(storageKey: string, theme: Theme): void {
   document.cookie = cookie;
 }
 
-/**
- * Write theme to localStorage
- */
 function writeThemeToStorage(storageKey: string, theme: Theme): void {
   if (typeof localStorage === "undefined") return;
 
@@ -98,9 +83,6 @@ function writeThemeToStorage(storageKey: string, theme: Theme): void {
   }
 }
 
-/**
- * Apply theme to HTML element
- */
 function applyThemeToDocument(theme: Theme, config: ResolvedThemeConfig): void {
   if (typeof document === "undefined") return;
 
@@ -112,86 +94,83 @@ function applyThemeToDocument(theme: Theme, config: ResolvedThemeConfig): void {
   const value = config.value[resolved] || resolved;
   const el = document.documentElement;
 
-  // Apply attribute
   if (config.attribute === "class") {
-    // Remove all theme classes
     for (const t of config.themes) {
       const v = config.value[t] || t;
       el.classList.remove(v);
     }
-    // Add current theme class
     el.classList.add(value);
   } else {
     el.setAttribute(config.attribute, value);
   }
 
-  // Set color-scheme for native dark mode support
   if (config.enableColorScheme) {
     el.style.colorScheme = resolved;
   }
 }
 
-/**
- * Get the resolved stored theme (validated against available themes)
- */
-function getStoredTheme(config: ResolvedThemeConfig): Theme {
-  const { storageKey, themes, defaultTheme, enableSystem } = config;
-
-  // Try cookie first (for SSR consistency)
-  let stored = readThemeFromCookie(storageKey);
-
-  // Fall back to localStorage
-  if (!stored) {
-    stored = readThemeFromStorage(storageKey);
-  }
-
-  // Validate stored value
-  if (stored) {
-    if (stored === "system" && enableSystem) {
-      return "system";
-    }
-    if (themes.includes(stored)) {
-      return stored as Theme;
-    }
-  }
-
-  return defaultTheme;
-}
-
-/**
- * ThemeProvider component
- *
- * Provides theme state to the component tree via context.
- * Handles theme persistence, system preference detection, and cross-tab sync.
- */
 export function ThemeProvider({
   config,
   initialTheme,
   children,
 }: ThemeProviderProps): React.ReactNode {
-  // Track mount state to avoid hydration mismatches
-  // During SSR and initial hydration, mounted is false
   const [mounted, setMounted] = useState(false);
 
-  // Initialize theme from prop, storage, or default
-  const [theme, setThemeState] = useState<Theme>(() => {
-    if (initialTheme) return initialTheme;
-    if (typeof window === "undefined") return config.defaultTheme;
-    return getStoredTheme(config);
-  });
+  // HYDRATION PARITY: this initializer is the server (SSR/resume) render AND
+  // the client's hydration render — both must produce the same value. It must
+  // NEVER read cookie/localStorage: whenever the payload's initialTheme
+  // differs from the visitor's stored theme (a PPR shell HIT deliberately
+  // replays the CAPTURE's initialTheme), a storage-reading initializer makes
+  // the client's first render diverge from the server tree. Any raw-theme text
+  // (a toggle label) then fails hydration, React regenerates the tree, and the
+  // FOUC-applied class is wiped from <html>. The visitor's stored theme is
+  // applied by the post-mount re-sync effect below instead.
+  const [theme, setThemeState] = useState<Theme>(
+    () => initialTheme ?? config.defaultTheme,
+  );
 
-  // Track system preference - use stable default during SSR
   const [systemTheme, setSystemTheme] = useState<ResolvedTheme>("light");
 
-  // Set mounted after hydration and detect actual system theme
   useEffect(() => {
     setMounted(true);
     setSystemTheme(getSystemTheme());
+    // Re-sync state from an EXPLICITLY stored theme after mount. initialTheme
+    // comes from the payload and can legitimately differ from the visitor's
+    // stored theme — on a PPR shell HIT it is deliberately the CAPTURE's theme
+    // (the resume tree must match the frozen prelude; see
+    // ShellCacheEntry.initialTheme). The FOUC script already applied the stored
+    // theme to the document pre-paint; this brings the provider state (toggles,
+    // useTheme readers) in line with it, and is the ONLY place the provider
+    // reads storage (the initializer must not — see the parity note above).
+    // Only an explicit cookie/localStorage value re-syncs — a defaultTheme
+    // fallback must not override a server-provided initialTheme when the
+    // visitor never chose a theme.
+    // First VALID candidate wins — an empty/garbage cookie value (e.g. a
+    // deleted cookie leaving "theme=") must not shadow a valid localStorage
+    // value behind a bare null-coalesce.
+    const explicit =
+      [
+        readThemeFromCookie(config.storageKey),
+        readThemeFromStorage(config.storageKey),
+      ].find((v) => v !== null && isValidTheme(v, config)) ?? null;
+    if (explicit !== null && explicit !== theme) {
+      setThemeState(explicit as Theme);
+      applyThemeToDocument(explicit as Theme, config);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
-  // Set theme and persist to storage
   const setTheme = useCallback(
     (newTheme: Theme) => {
+      // Shared guard (isValidTheme) used by the server ctx.setTheme too: reject
+      // any value not in the configured theme set, AND reject "system" when
+      // system detection is off (applyThemeToDocument would write a bogus
+      // class="system"). Keeps the cookie from holding a value the server would
+      // reinterpret as defaultTheme on the next SSR (desyncing markup).
+      if (!isValidTheme(newTheme, config)) {
+        warnInvalidTheme(newTheme, config);
+        return;
+      }
       setThemeState(newTheme);
       writeThemeToCookie(config.storageKey, newTheme);
       writeThemeToStorage(config.storageKey, newTheme);
@@ -200,7 +179,6 @@ export function ThemeProvider({
     [config],
   );
 
-  // Listen for system preference changes
   useEffect(() => {
     if (!config.enableSystem) return;
     if (typeof window === "undefined" || !window.matchMedia) return;
@@ -211,13 +189,11 @@ export function ThemeProvider({
       const newSystemTheme = e.matches ? "dark" : "light";
       setSystemTheme(newSystemTheme);
 
-      // If current theme is "system", re-apply to update document
       if (theme === "system") {
         applyThemeToDocument("system", config);
       }
     };
 
-    // Modern browsers
     mediaQuery.addEventListener("change", handleChange);
 
     return () => {
@@ -225,7 +201,6 @@ export function ThemeProvider({
     };
   }, [config, theme]);
 
-  // Cross-tab synchronization via localStorage storage event
   useEffect(() => {
     if (typeof window === "undefined") return;
 
@@ -235,11 +210,16 @@ export function ThemeProvider({
       const newTheme = e.newValue;
       if (!newTheme) return;
 
-      // Validate and apply
-      if (newTheme === "system" || config.themes.includes(newTheme)) {
-        setThemeState(newTheme as Theme);
-        applyThemeToDocument(newTheme as Theme, config);
-      }
+      // A cross-tab storage event can carry any value (another tab, or stale
+      // localStorage). Reuse the shared validity rule: reject anything not a
+      // configured theme, AND reject "system" when system detection is off (it
+      // would apply a bogus class="system"). An invalid received value falls back
+      // to defaultTheme rather than applying as-is.
+      const applied: Theme = isValidTheme(newTheme, config)
+        ? (newTheme as Theme)
+        : config.defaultTheme;
+      setThemeState(applied);
+      applyThemeToDocument(applied, config);
     };
 
     window.addEventListener("storage", handleStorageChange);
@@ -249,12 +229,8 @@ export function ThemeProvider({
     };
   }, [config]);
 
-  // Compute resolved theme
-  // During SSR (not mounted), use the initial theme or default to avoid hydration mismatch
   const resolvedTheme: ResolvedTheme = useMemo(() => {
     if (!mounted) {
-      // During SSR, return the initial theme if it's not "system", otherwise "light"
-      // The inline script will apply the correct class before hydration
       if (initialTheme && initialTheme !== "system") {
         return initialTheme as ResolvedTheme;
       }
@@ -266,7 +242,6 @@ export function ThemeProvider({
     return theme as ResolvedTheme;
   }, [theme, systemTheme, config.enableSystem, mounted, initialTheme]);
 
-  // Build themes list (include "system" if enabled)
   const themes = useMemo(() => {
     if (config.enableSystem) {
       return ["system", ...config.themes.filter((t) => t !== "system")];
@@ -274,14 +249,11 @@ export function ThemeProvider({
     return config.themes;
   }, [config.themes, config.enableSystem]);
 
-  // Context value
-  // During SSR (not mounted), return stable values to avoid hydration mismatch
   const contextValue: ThemeContextValue = useMemo(
     () => ({
       theme,
       setTheme,
       resolvedTheme,
-      // Return stable "light" for systemTheme during SSR - actual value updates after mount
       systemTheme: mounted ? systemTheme : "light",
       themes,
       config,

package/src/theme/ThemeScript.tsx

@@ -8,17 +8,21 @@
  *
  * Must be placed in the <head> element of your document, before any stylesheets.
  *
+ * Note: when theme is enabled in the router config, `<MetaTags />` ALREADY
+ * renders this FOUC script. Use `<ThemeScript />` only if you do NOT render
+ * `<MetaTags />`. Rendering both is safe — the inline script guards the
+ * matchMedia listener registration against double-running — but it is redundant.
+ *
  * @example
  * ```tsx
- * // In your document component
+ * // In your document component. Use ThemeScript only when you do not render MetaTags.
  * import { ThemeScript } from "@rangojs/router/theme";
  *
  * export function Document({ children }) {
  *   return (
  *     <html lang="en" suppressHydrationWarning>
  *       <head>
- *         <ThemeScript />
- *         <MetaTags />
+ *         <ThemeScript config={config} />
  *       </head>
  *       <body>{children}</body>
  *     </html>
@@ -43,12 +47,6 @@ export interface ThemeScriptProps {
   nonce?: string;
 }
 
-/**
- * Server component that renders the theme initialization script.
- *
- * This renders a synchronous inline script that applies the theme
- * to the HTML element before React hydration, preventing FOUC.
- */
 export function ThemeScript({
   config,
   nonce,

package/src/theme/constants.ts

@@ -2,11 +2,8 @@
  * Default values for theme configuration
  */
 
-import type { ResolvedThemeConfig, ThemeConfig } from "./types.js";
+import type { ResolvedThemeConfig, Theme, ThemeConfig } from "./types.js";
 
-/**
- * Default theme configuration values
- */
 export const THEME_DEFAULTS = {
   defaultTheme: "system",
   themes: ["light", "dark"],
@@ -16,9 +13,6 @@ export const THEME_DEFAULTS = {
   enableColorScheme: true,
 } as const;
 
-/**
- * Cookie configuration for theme persistence
- */
 export const THEME_COOKIE: {
   readonly maxAge: number;
   readonly path: string;
@@ -30,31 +24,76 @@ export const THEME_COOKIE: {
 };
 
 /**
- * Resolve theme config by applying defaults.
- * Accepts `true` to enable with all defaults, or a config object.
+ * Single owner of the setTheme validity rule, shared by the client
+ * (ThemeProvider) and server (ctx.setTheme) guards so they cannot drift.
+ *
+ * A theme is valid when it is one of the configured concrete themes, OR
+ * "system" but only while system detection is enabled. Rejecting "system" when
+ * `enableSystem` is false is load-bearing: applyThemeToDocument would otherwise
+ * leave "system" unresolved and write a bogus class="system" / colorScheme
+ * ="system" on <html> (the same bogus value resolveThemeConfig coerces away for
+ * the default).
+ */
+export function isValidTheme(
+  theme: string,
+  config: Pick<ResolvedThemeConfig, "themes" | "enableSystem">,
+): boolean {
+  if (theme === "system") return config.enableSystem;
+  return config.themes.includes(theme);
+}
+
+/**
+ * Emit the shared "[Theme] Invalid theme value" warning. One owner of the
+ * message string so the client and server guards stay byte-identical.
+ *
+ * The valid-values list mirrors isValidTheme: "system" is only listed when
+ * enableSystem is true, otherwise the message would advertise a value the guard
+ * itself rejects.
  */
+export function warnInvalidTheme(
+  theme: string,
+  config: Pick<ResolvedThemeConfig, "themes" | "enableSystem">,
+): void {
+  const validValues = config.enableSystem
+    ? ["system", ...config.themes]
+    : config.themes;
+  console.warn(
+    `[Theme] Invalid theme value: "${theme}". Valid values: ${validValues.join(", ")}`,
+  );
+}
+
 export function resolveThemeConfig(
   config: ThemeConfig | true,
 ): ResolvedThemeConfig {
-  // Handle `theme: true` shorthand
   if (config === true) {
     config = {};
   }
 
   const themes = config.themes ?? [...THEME_DEFAULTS.themes];
 
-  // Build value mapping - default to identity mapping
   const value: Record<string, string> = {};
   for (const theme of themes) {
     value[theme] = config.value?.[theme] ?? theme;
   }
 
+  const enableSystem = config.enableSystem ?? THEME_DEFAULTS.enableSystem;
+
+  // When system detection is disabled, "system" is not a valid resolved theme.
+  // Coerce both the unset default and an explicit defaultTheme:"system" to the
+  // first concrete theme, so the FOUC script / ThemeProvider never apply a bogus
+  // class="system" / colorScheme="system" on <html>.
+  const requestedDefault = config.defaultTheme ?? THEME_DEFAULTS.defaultTheme;
+  const defaultTheme =
+    !enableSystem && requestedDefault === "system"
+      ? (themes[0] as Theme)
+      : requestedDefault;
+
   return {
-    defaultTheme: config.defaultTheme ?? THEME_DEFAULTS.defaultTheme,
+    defaultTheme,
     themes,
     attribute: config.attribute ?? THEME_DEFAULTS.attribute,
     storageKey: config.storageKey ?? THEME_DEFAULTS.storageKey,
-    enableSystem: config.enableSystem ?? THEME_DEFAULTS.enableSystem,
+    enableSystem,
     enableColorScheme:
       config.enableColorScheme ?? THEME_DEFAULTS.enableColorScheme,
     value,

package/src/theme/index.ts

@@ -23,16 +23,10 @@
  * ```
  */
 
-// Main hook for accessing theme
 export { useTheme } from "./use-theme.js";
-
-// Provider (typically auto-included via NavigationProvider when theme is enabled)
 export { ThemeProvider } from "./ThemeProvider.js";
-
-// Script component for FOUC prevention (use in document head)
 export { ThemeScript, type ThemeScriptProps } from "./ThemeScript.js";
 
-// Types
 export type {
   Theme,
   ResolvedTheme,
@@ -44,5 +38,4 @@ export type {
   ThemeContextValue,
 } from "./types.js";
 
-// Constants
 export { THEME_DEFAULTS, THEME_COOKIE } from "./constants.js";

package/src/theme/theme-context.ts

@@ -19,17 +19,13 @@ import type { ThemeContextValue } from "./types.js";
 export const ThemeContext: Context<ThemeContextValue | null> =
   createContext<ThemeContextValue | null>(null);
 
-/**
- * Get theme context (internal use)
- * Returns null if theme is not enabled
- */
 export function useThemeContext(): ThemeContextValue | null {
   return useContext(ThemeContext);
 }
 
 /**
  * Get theme context, throwing if not available
- * Use this in useTheme hook
+ * Used by useTheme hook
  */
 export function requireThemeContext(): ThemeContextValue {
   const ctx = useContext(ThemeContext);

package/src/theme/theme-script.ts

@@ -11,6 +11,7 @@
  */
 
 import type { ResolvedThemeConfig } from "./types.js";
+import { escapeJsonForScript } from "../escape-script.js";
 
 /**
  * Generate the inline script for theme initialization
@@ -22,20 +23,17 @@ import type { ResolvedThemeConfig } from "./types.js";
  * - Handle all edge cases (no localStorage, no cookie, etc.)
  */
 export function generateThemeScript(config: ResolvedThemeConfig): string {
-  // Build the script as a string, then minify
   const script = `
 (function() {
-  var storageKey = ${JSON.stringify(config.storageKey)};
-  var defaultTheme = ${JSON.stringify(config.defaultTheme)};
-  var attribute = ${JSON.stringify(config.attribute)};
+  var storageKey = ${escapeJsonForScript(JSON.stringify(config.storageKey))};
+  var defaultTheme = ${escapeJsonForScript(JSON.stringify(config.defaultTheme))};
+  var attribute = ${escapeJsonForScript(JSON.stringify(config.attribute))};
   var enableSystem = ${config.enableSystem};
   var enableColorScheme = ${config.enableColorScheme};
-  var valueMap = ${JSON.stringify(config.value)};
-  var themes = ${JSON.stringify(config.themes)};
+  var valueMap = ${escapeJsonForScript(JSON.stringify(config.value))};
+  var themes = ${escapeJsonForScript(JSON.stringify(config.themes))};
 
-  // Read theme from cookie or localStorage
   function getStoredTheme() {
-    // Try cookie first (for SSR consistency)
     var cookies = document.cookie.split(';');
     for (var i = 0; i < cookies.length; i++) {
       var cookie = cookies[i].trim();
@@ -44,7 +42,6 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
         catch (e) { return cookie.substring(storageKey.length + 1); }
       }
     }
-    // Fall back to localStorage
     try {
       return localStorage.getItem(storageKey);
     } catch (e) {
@@ -52,7 +49,6 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
     }
   }
 
-  // Get system preference
   function getSystemTheme() {
     if (typeof window !== 'undefined' && window.matchMedia) {
       return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
@@ -60,7 +56,6 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
     return 'light';
   }
 
-  // Resolve "system" to actual theme
   function resolveTheme(theme) {
     if (theme === 'system' && enableSystem) {
       return getSystemTheme();
@@ -68,15 +63,12 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
     return theme;
   }
 
-  // Apply theme to HTML element
   function applyTheme(theme) {
     var resolved = resolveTheme(theme);
     var value = valueMap[resolved] || resolved;
     var el = document.documentElement;
 
-    // Apply attribute
     if (attribute === 'class') {
-      // Remove all theme classes, then add current
       for (var i = 0; i < themes.length; i++) {
         var v = valueMap[themes[i]] || themes[i];
         el.classList.remove(v);
@@ -86,23 +78,32 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
       el.setAttribute(attribute, value);
     }
 
-    // Set color-scheme for native dark mode support
     if (enableColorScheme) {
       el.style.colorScheme = resolved;
     }
   }
 
-  // Get stored theme or use default
   var stored = getStoredTheme();
-  var theme = stored && (stored === 'system' || themes.indexOf(stored) !== -1)
+  // A stored value is valid when it is a configured theme, OR "system" but only
+  // while system detection is enabled. A stored "system" with enableSystem=false
+  // (an old cookie/localStorage, or a value pushed cross-tab) must fall back to
+  // defaultTheme — otherwise resolveTheme returns "system" unresolved and
+  // applyTheme writes a bogus class="system" / colorScheme="system" on <html>.
+  // Same rule as isValidTheme (constants.ts), inlined since this is a string.
+  var systemAllowed = stored === 'system' && enableSystem;
+  var theme = stored && (systemAllowed || themes.indexOf(stored) !== -1)
     ? stored
     : defaultTheme;
 
-  // Apply immediately
   applyTheme(theme);
 
-  // Listen for system preference changes (for "system" theme)
-  if (enableSystem && typeof window !== 'undefined' && window.matchMedia) {
+  // Idempotency guard: MetaTags auto-injects this script when theme is enabled,
+  // and ThemeScript is also a public component for the same job. If a consumer
+  // renders both, the IIFE runs twice; without this guard the second run would
+  // register a SECOND, never-removed matchMedia('change') listener (a leak).
+  // The flag is keyed by storageKey so independent theme configs don't collide.
+  var flagKey = '__rangoThemeListener_' + storageKey;
+  if (enableSystem && typeof window !== 'undefined' && window.matchMedia && !window[flagKey]) {
     try {
       window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', function() {
         var current = getStoredTheme() || defaultTheme;
@@ -110,6 +111,7 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
           applyTheme('system');
         }
       });
+      window[flagKey] = true;
     } catch (e) {
       // Older browsers may not support addEventListener on MediaQueryList
     }
@@ -117,7 +119,6 @@ export function generateThemeScript(config: ResolvedThemeConfig): string {
 })();
 `;
 
-  // Minify by removing comments, extra whitespace, and newlines
   return minifyScript(script);
 }
 

package/src/theme/use-theme.ts

@@ -27,9 +27,6 @@ import type { UseThemeReturn } from "./types.js";
  *
  * Must be used within a ThemeProvider (which is automatically included
  * in NavigationProvider when theme is enabled in router config).
- *
- * @returns Theme state and methods
- * @throws Error if used outside ThemeProvider
  */
 export function useTheme(): UseThemeReturn {
   const ctx = requireThemeContext();