@rangojs/router 0.0.0-experimental.e16b7c00 → 0.0.0-experimental.e9c0b2f2

package/src/testing/vitest.ts

@@ -0,0 +1,305 @@
+/**
+ * @rangojs/router/testing/vitest
+ *
+ * Vitest setup helper for the UNIT + INTEGRATION + DOM test project of a
+ * @rangojs/router consumer app. It returns the `resolve.alias` entries that make
+ * a real app's router / loaders / middleware importable in a bare Vitest process.
+ *
+ * Why this is needed (the documented "vi.mock(plugin-rsc) + import router"
+ * recipe is not sufficient for a real app):
+ *
+ * - `@rangojs/router` resolves to SERVER-ONLY STUBS outside the `react-server`
+ *   condition — `urls()`, `createRouter()`, `cookies()`, `getRequestContext()`
+ *   throw "only available in a react-server environment". Importing the app's own
+ *   router/loaders/middleware then fails immediately. Vitest does NOT apply the
+ *   `react-server` condition to bare-package exports resolution, and enabling it
+ *   globally flips React to its server build (no `createContext`), crashing the
+ *   router's client-boundary imports. The surgical fix is to alias ONLY the bare
+ *   `@rangojs/router` specifier to its react-server entry (real impls) while
+ *   leaving React as the client build — which is exactly what this helper does.
+ * - The build-only `@rangojs/router:version` virtual and `@vitejs/plugin-rsc/rsc`
+ *   (whose real body imports unresolvable Vite virtuals) are stubbed.
+ * - Cloudflare apps additionally import the `cloudflare:workers` /
+ *   `cloudflare:email` runtime virtuals; pass `{ preset: "cloudflare" }` to stub them.
+ *
+ * Usage (recommended one-call form — see {@link rangoTestConfig}):
+ *
+ * ```ts
+ * // vitest.config.ts
+ * import { defineConfig } from "vitest/config";
+ * import { rangoTestConfig } from "@rangojs/router/testing/vitest";
+ *
+ * export default defineConfig({
+ *   test: {
+ *     globals: true,
+ *     include: ["test/**\/*.test.{ts,tsx}"],
+ *     environment: "node",
+ *     ...rangoTestConfig({ preset: "cloudflare" }),
+ *   },
+ * });
+ * ```
+ *
+ * `rangoTestConfig` bundles the resolve aliases ({@link rangoTestAliases}) with
+ * the `server.deps.inline` contract ({@link rangoInlineDeps}) an installed
+ * consumer needs — @rangojs/router ships as TS source, and without `deps.inline`
+ * Vitest hands those `.ts` files to Node, which on Node >= 23 throws
+ * `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`. Use the lower-level
+ * `rangoTestAliases` directly only if you wire `deps.inline` yourself.
+ *
+ * Notes:
+ * - The Flight project (real RSC rendering via `@rangojs/router/testing/flight`)
+ *   uses the `react-server` condition AND needs this same alias whenever a
+ *   rendered handler/component imports a server API (`getRequestContext`,
+ *   `cookies`) from the bare `@rangojs/router` — without it that import resolves
+ *   to the throwing out-of-react-server stub (`resolve.conditions` alone is not
+ *   reliably applied to bare-package export resolution). The alias points at
+ *   `index.rsc.ts` (the real react-server build) and leaves React itself
+ *   untouched, so it does NOT crash the server React build. The router's OWN
+ *   Flight tests omit it only because they import via RELATIVE paths, not the
+ *   bare specifier; a consumer importing the bare specifier must include it. See
+ *   the testing skill (`skills/testing/setup.md`, shipped in the package) for
+ *   the complete Flight config.
+ * - `renderRoute` (`@rangojs/router/testing/dom`) tests run in this same project
+ *   under a DOM environment (`happy-dom`/`jsdom`); the alias does not affect them.
+ * - A router using `Prerender()` / `createLoader()` / `Static()` now CONSTRUCTS in
+ *   a bare test: each assigns a process-stable runtime fallback `$$id` ONLY under
+ *   a test runner (`process.env.VITEST`), so `createRouter().routes(...)` builds
+ *   without the "missing `$$id`" throw (for `dispatch` / `assertGeneratedRoutesMatch`).
+ *   Outside a test runner (a real build) a missing id still THROWS — so an
+ *   unsupported handler shape the plugin skipped (e.g. `export let`) fails loud
+ *   rather than getting a silent synthetic id. (The plugin always injects for
+ *   supported `export const` shapes, and the static manifest keys on that id.)
+ * - Importing your app's whole router *file* can still fail for app-specific
+ *   reasons (page modules pulling their own deps, or plugin `virtual:` modules
+ *   that need the rango plugin) — build whole-router `dispatch`/drift checks from
+ *   a focused include, or use e2e.
+ */
+
+import { fileURLToPath } from "node:url";
+
+/** A single Vite/Vitest resolve alias entry. Structurally a Vite `Alias`. */
+export interface TestAlias {
+  find: string | RegExp;
+  replacement: string;
+}
+
+/** Options for {@link rangoTestAliases}. */
+export interface RangoTestAliasOptions {
+  /**
+   * Deployment preset, matching `rango({ preset })` in the Vite plugin. With
+   * `"cloudflare"` the helper additionally stubs the Cloudflare Workers runtime
+   * virtuals (`cloudflare:workers` / `cloudflare:email`) a CF app's route tree
+   * imports. A string (not a boolean) so more presets can be added without an
+   * API change. Default: `"node"`.
+   */
+  preset?: "node" | "cloudflare";
+}
+
+/**
+ * Resolve a path relative to this module. Anchored at the PACKAGE ROOT
+ * (`../../` from both `src/testing/vitest.ts` and the shipped
+ * `dist/testing/vitest.js` — each is two levels below the root), so the alias
+ * targets always point at the `src/*.ts` files Vite transpiles at test time,
+ * regardless of whether this helper is loaded as source (in-repo) or as the
+ * compiled `dist` entry (an installed consumer).
+ */
+function here(relativeFromRoot: string): string {
+  return fileURLToPath(new URL(`../../${relativeFromRoot}`, import.meta.url));
+}
+
+/**
+ * Build the `resolve.alias` entries a consumer's node/DOM Vitest project needs to
+ * import a real @rangojs/router app's router/loaders/middleware. Spread into a
+ * Vitest config: `resolve: { alias: rangoTestAliases(...) }` (concat your own
+ * aliases as needed).
+ */
+export function rangoTestAliases(
+  opts: RangoTestAliasOptions = {},
+): TestAlias[] {
+  const aliases: TestAlias[] = [
+    // Real impls (index.rsc.ts) for the bare specifier ONLY — exact regex so
+    // subpaths (/testing, /client, /cache, ...) are untouched. React stays the
+    // client build, so createContext and "use client" modules work.
+    { find: /^@rangojs\/router$/, replacement: here("src/index.rsc.ts") },
+    {
+      find: "@rangojs/router:version",
+      replacement: here("src/testing/vitest-stubs/version.ts"),
+    },
+    {
+      find: /^@vitejs\/plugin-rsc\/rsc$/,
+      replacement: here("src/testing/vitest-stubs/plugin-rsc.ts"),
+    },
+  ];
+
+  if (opts.preset === "cloudflare") {
+    aliases.push(
+      {
+        find: "cloudflare:workers",
+        replacement: here("src/testing/vitest-stubs/cloudflare-workers.ts"),
+      },
+      {
+        find: "cloudflare:email",
+        replacement: here("src/testing/vitest-stubs/cloudflare-email.ts"),
+      },
+    );
+  }
+
+  return aliases;
+}
+
+/**
+ * Vitest `server.deps.inline` patterns that force Vite (not Node) to transpile
+ * @rangojs/router's TypeScript source under test.
+ *
+ * REQUIRED for an installed (node_modules) consumer: @rangojs/router ships as TS
+ * source, and Vitest externalizes node_modules by default — so without this Node
+ * loads the `.ts` files directly and, on Node >= 23, throws
+ * `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`. In this monorepo it is a no-op
+ * (the workspace symlink resolves to a realpath outside node_modules, which Vite
+ * already transpiles), which is precisely why an in-repo dogfood never surfaces
+ * the need and the contract has to be shipped explicitly.
+ */
+export const rangoInlineDeps: RegExp[] = [/@rangojs[/\\]router/];
+
+/** The Vitest `test`-block fragment {@link rangoTestConfig} returns. */
+export interface RangoTestConfig {
+  alias: TestAlias[];
+  server: { deps: { inline: RegExp[] } };
+}
+
+/**
+ * The complete Vitest `test`-block fragment a consumer needs: the resolve
+ * aliases ({@link rangoTestAliases}) AND the `server.deps.inline` contract
+ * ({@link rangoInlineDeps}). Spread it into your `test` block so both land in
+ * one place and a consumer cannot forget the `deps.inline` half (omitting it
+ * loads rango's TS source through Node and breaks on Node >= 23):
+ *
+ * ```ts
+ * // vitest.config.ts
+ * import { defineConfig } from "vitest/config";
+ * import { rangoTestConfig } from "@rangojs/router/testing/vitest";
+ *
+ * export default defineConfig({
+ *   test: {
+ *     globals: true,
+ *     include: ["test/**\/*.test.{ts,tsx}"],
+ *     environment: "node",
+ *     ...rangoTestConfig({ preset: "cloudflare" }),
+ *   },
+ * });
+ * ```
+ */
+export function rangoTestConfig(
+  opts: RangoTestAliasOptions = {},
+): RangoTestConfig {
+  return {
+    alias: rangoTestAliases(opts),
+    // fresh copy so the shared rangoInlineDeps const is never aliased into (or
+    // mutated through) a consumer's resolved config
+    server: { deps: { inline: [...rangoInlineDeps] } },
+  };
+}
+
+/** A minimal Vite plugin shape (avoids a hard dependency on Vite's types). */
+interface FlightTransformPlugin {
+  name: string;
+  transform(
+    code: string,
+    id: string,
+  ): Promise<{ code: string; map: unknown } | undefined>;
+}
+
+/**
+ * A Vite plugin for the FLIGHT (react-server) Vitest project that applies the
+ * `"use client"` transform to a consumer's client modules — the same transform a
+ * real build applies. With it, `renderServerTree` (`@rangojs/router/testing/flight`)
+ * resolves client islands AUTOMATICALLY from the server tree's own imports: no
+ * `clientComponents` to pass, no filename convention. Without it, a `"use client"`
+ * module is imported as a plain (unmarked) function and would render server-side,
+ * so you must list islands via `renderServerTree(..., { clientComponents })`.
+ *
+ * Add it to your react-server Vitest project. This is the COMPLETE config — the
+ * alias, `server.deps.inline`, and `NODE_ENV` are load-bearing, not optional (see
+ * the inline notes). The testing skill (`skills/testing/setup.md`, shipped in the
+ * package) has the annotated walkthrough.
+ *
+ * ```ts
+ * // vitest.rsc.config.ts
+ * import { defineConfig } from "vitest/config";
+ * import {
+ *   rangoUseClientTransform,
+ *   rangoTestAliases,
+ *   rangoInlineDeps,
+ * } from "@rangojs/router/testing/vitest";
+ *
+ * // Flight serialization needs React's production build; the dev build's jsxDEV
+ * // crashes / yields unstable snapshots.
+ * process.env.NODE_ENV = "production";
+ *
+ * export default defineConfig({
+ *   plugins: [rangoUseClientTransform()],
+ *   resolve: {
+ *     conditions: ["react-server"],
+ *     // Bare `@rangojs/router` -> its react-server build, so a handler/component
+ *     // reading getRequestContext()/cookies() resolves the real impl, not the
+ *     // throwing stub. Pass { preset: "cloudflare" } for a CF app.
+ *     alias: rangoTestAliases(),
+ *   },
+ *   test: {
+ *     include: ["test/**\/*.rsc-test.{ts,tsx}"],
+ *     pool: "forks",
+ *     execArgv: ["--conditions=react-server"],
+ *     // Required for an INSTALLED consumer on Node >= 23 (rango ships TS source).
+ *     server: { deps: { inline: rangoInlineDeps } },
+ *   },
+ * });
+ * ```
+ *
+ * Each `"use client"` module's exports are replaced with client references keyed
+ * by the module's absolute path (the boundary id), the export name becoming the
+ * boundary name. Modules without the directive (server components) are untouched,
+ * so `renderToFlightString` of pure leaf trees is unaffected.
+ */
+export function rangoUseClientTransform(): FlightTransformPlugin {
+  return {
+    name: "rango:testing-use-client",
+    async transform(code, id) {
+      if (id.includes("/node_modules/")) return undefined;
+      // Fast path: only parse modules that mention the directive.
+      if (!code.includes("use client")) return undefined;
+      const { parseAstAsync } = await import("vite");
+      const { hasDirective, transformDirectiveProxyExport } =
+        await import("@vitejs/plugin-rsc/transforms");
+      // vite's parser and the transforms ship structurally-compatible but
+      // distinctly-typed ASTs (oxc vs estree); cast through the transform's own
+      // parameter type, exactly as plugin-rsc does at runtime.
+      type TransformAst = Parameters<typeof transformDirectiveProxyExport>[0];
+      let ast: TransformAst;
+      try {
+        ast = (await parseAstAsync(code)) as unknown as TransformAst;
+      } catch {
+        return undefined;
+      }
+      if (!hasDirective(ast.body, "use client")) return undefined;
+      const result = transformDirectiveProxyExport(ast, {
+        directive: "use client",
+        code,
+        runtime: (name: string) =>
+          `$$RangoRSD.registerClientReference(` +
+          `() => { throw new Error("client reference " + ${JSON.stringify(name)} + " is not callable on the server"); }, ` +
+          `${JSON.stringify(id)}, ${JSON.stringify(name)})`,
+      });
+      if (!result) return undefined;
+      const { output } = result;
+      // The vendored server serializer is the one renderToFlightString uses;
+      // resolvable here under the react-server condition.
+      output.prepend(
+        `import * as $$RangoRSD from "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge";\n`,
+      );
+      return {
+        code: output.toString(),
+        map: output.generateMap({ hires: true }),
+      };
+    },
+  };
+}

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,40 +94,30 @@ 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";
@@ -158,40 +130,37 @@ function getStoredTheme(config: ResolvedThemeConfig): 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);
   });
 
-  // 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());
   }, []);
 
-  // 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 +169,6 @@ export function ThemeProvider({
     [config],
   );
 
-  // Listen for system preference changes
   useEffect(() => {
     if (!config.enableSystem) return;
     if (typeof window === "undefined" || !window.matchMedia) return;
@@ -211,13 +179,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 +191,6 @@ export function ThemeProvider({
     };
   }, [config, theme]);
 
-  // Cross-tab synchronization via localStorage storage event
   useEffect(() => {
     if (typeof window === "undefined") return;
 
@@ -235,11 +200,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 +219,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 +232,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 +239,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,