@rangojs/router 0.0.0-experimental.124 → 0.0.0-experimental.125

package/src/testing/render-route.tsx

@@ -63,11 +63,6 @@ const TEST_ORIGIN = "http://localhost";
  */
 export type HandleDataSeed = Record<string, Record<string, unknown[]>>;
 
-// Loaders and location-state defs carry an id (`$$id` / `__rsc_ls_key`) that the
-// Vite plugin injects at build time; in a bare test it is "". These helpers
-// assign a synthetic stable id (mutating the handle, tracked per-object) so that
-// seeding by reference lines up with the read path (useLoader / useLocationState
-// both read the id off the handle at call time).
 const syntheticIds = new WeakMap<object, string>();
 let syntheticIdCounter = 0;
 
@@ -86,7 +81,6 @@ function ensureSyntheticId(
   return id;
 }
 
-/** One-level clone of a raw handle seed so we don't mutate the caller's object. */
 function cloneHandleSeed(seed?: HandleDataSeed): HandleDataSeed {
   const out: HandleDataSeed = {};
   for (const [name, segMap] of Object.entries(seed ?? {})) {
@@ -95,12 +89,6 @@ function cloneHandleSeed(seed?: HandleDataSeed): HandleDataSeed {
   return out;
 }
 
-/**
- * One node of the route definition passed to renderRoute. The array models a
- * single matched route plus its optional layout chain — element order is
- * outermost layout first, the leaf route last (the same root-to-leaf order the
- * real matcher produces).
- */
 export interface RenderRouteSpec {
   /**
    * The route pattern this node matches, e.g. "/products/:productId". The LAST
@@ -281,11 +269,6 @@ interface ResolvedMatch {
   pathname: string;
 }
 
-/**
- * Match a pathname against the leaf spec's pattern and extract params.
- * Returns null when the pattern does not match (params then fall back to the
- * caller-provided `options.params`).
- */
 function matchLeaf(
   pattern: string,
   pathname: string,
@@ -303,7 +286,6 @@ function matchLeaf(
   return params;
 }
 
-/** Derive a usable initial pathname from a leaf pattern when none is given. */
 function staticPrefix(pattern: string): string {
   const out: string[] = [];
   for (const part of pattern.split("/")) {
@@ -314,13 +296,6 @@ function staticPrefix(pattern: string): string {
   return "/" + out.join("/");
 }
 
-/**
- * Build the synthetic ResolvedSegment[] for a matched route. Produces, in
- * root-to-leaf order: one layout segment per non-leaf spec, then the leaf route
- * segment, plus a loader segment for each seeded loader id attached to the
- * owning spec. Segment ids follow the real convention (L0, L0L1, ..., the leaf
- * route as L0...R{n}; loaders as {parentId}D{i}.{loaderId}).
- */
 function buildSegments(
   routes: RenderRouteSpec[],
   params: Record<string, string>,
@@ -353,20 +328,13 @@ function buildSegments(
       params,
       belongsToRoute: true,
     };
-    // Model an include() mount: every component segment in the chain shares the
-    // same prefix, so renderSegments wraps each in a MountContextProvider and
-    // useMount() resolves the mounted prefix (production sets mountPath on every
-    // segment of an included subtree). Must be applied identically at both
-    // buildSegments call sites or segment-structure-assert flags a remount.
     if (mount) node.mountPath = mount;
-    // A leaf-owned layout component wraps the route via its own layout element.
     if (isLeaf && spec.layout) {
       const Layout = spec.layout;
       node.layout = <Layout />;
     }
     segments.push(node);
 
-    // Determine which seeded loader ids this spec owns.
     const ownedIds = spec.loaderIds
       ? spec.loaderIds.filter((id) => id in loaderData)
       : isLeaf
@@ -390,30 +358,6 @@ function buildSegments(
   return segments;
 }
 
-/**
- * Render a CLIENT component (and its layout chain) inside the router's
- * NavigationProvider for unit testing. Exported from `@rangojs/router/testing/dom`
- * (its own entry, kept out of the main `@rangojs/router/testing` barrel so that
- * barrel never references React/@testing-library/react). Async so the heavy
- * @testing-library/react dependency is loaded only at call time.
- *
- * @example
- * ```tsx
- * // @vitest-environment happy-dom
- * import { renderRoute } from "@rangojs/router/testing/dom";
- *
- * function Product() {
- *   const { productId } = useParams<{ productId: string }>();
- *   const reverse = useReverse({ product: "/products/:productId" });
- *   return <a href={reverse("product", { productId: "2" })}>{productId}</a>;
- * }
- *
- * const { getByText, router } = await renderRoute(
- *   [{ path: "/products/:productId", Component: Product }],
- *   { request: "/products/1" },
- * );
- * ```
- */
 export async function renderRoute(
   routes: RenderRouteSpec[],
   options: RenderRouteOptions = {},
@@ -421,9 +365,6 @@ export async function renderRoute(
   if (routes.length === 0) {
     throw new Error("renderRoute: `routes` must contain at least one entry");
   }
-  // The pre-rename `initialUrl` option was renamed to `request`. A plain-JS or
-  // spread-defeated caller still passing it would otherwise be silently ignored;
-  // fail loud with the migration name instead.
   if ("initialUrl" in options) {
     throw new Error(
       "renderRoute: the `initialUrl` option was renamed to `request`. " +
@@ -439,30 +380,19 @@ export async function renderRoute(
   const initialUrl = requestUrl ?? staticPrefix(leaf.path) ?? "/";
   const url = new URL(initialUrl, TEST_ORIGIN);
 
-  // Seed loader data: explicit-id entries from `loaderData`, plus by-reference
-  // entries from `loaders` (assigning synthetic ids to real handles whose `$$id`
-  // is empty in a bare test).
   const loaderData: Record<string, unknown> = { ...(options.loaderData ?? {}) };
   for (const [loader, data] of options.loaders ?? []) {
     loaderData[ensureSyntheticId(loader as object, "$$id")] = data;
   }
 
-  // Seed location state into history.state so useLocationState(def) resolves.
-  // Keyed defs read history.state[def.__rsc_ls_key]; assign a synthetic key when
-  // the injected one is empty (bare test). RESET history.state to only this
-  // call's seeds (not a merge) so a previous render's seeded state does not leak
-  // into a later render in the same DOM environment.
   if (typeof window !== "undefined") {
     const stateObj: Record<string, unknown> = {};
     for (const [def, value] of options.locationState ?? []) {
       stateObj[ensureSyntheticId(def as object, "__rsc_ls_key")] = value;
     }
-    // No URL arg: useLocationState reads history.state (not the URL), and passing
-    // a TEST_ORIGIN URL would trip the DOM env's same-origin check.
     window.history.replaceState(stateObj, "");
   }
 
-  // Resolve params: URL-extracted params first, explicit params override.
   const resolve = (pathname: string): ResolvedMatch => {
     const matched = matchLeaf(leaf.path, pathname) ?? {};
     return {
@@ -472,10 +402,7 @@ export async function renderRoute(
   };
   const initialMatch = resolve(url.pathname);
 
-  // Reuse the real browser primitives so context shape matches production.
   const historyKey = generateHistoryKey(url.href);
-  // Normalize the include() mount prefix once and apply it at BOTH buildSegments
-  // call sites (initial + navigate) so mountPath is consistent across renders.
   const mount = normalizeBasename(options.mount);
   const initialSegments = buildSegments(
     routes,
@@ -490,20 +417,12 @@ export async function renderRoute(
     initialSegments,
     crossTabSync: false,
   });
-  // Seed handle data: raw `handle` entries plus by-reference `handles` attached
-  // to the leaf route segment under each handle's id (so useHandle(handle)
-  // resolves the pushed values).
   const leafRouteSegmentId =
     [...initialSegments].reverse().find((s) => s.type === "route")?.id ??
     initialSegments[initialSegments.length - 1]?.id;
   const handleSeed: HandleDataSeed = cloneHandleSeed(options.handle);
   for (const [handle, values] of options.handles ?? []) {
     if (leafRouteSegmentId === undefined) continue;
-    // createHandle always has a non-empty $$id (the Vite plugin injects one, and
-    // createHandle assigns a runtime fallback otherwise) with its REAL collect
-    // registered — so seeding under handle.$$id makes useHandle(handle) run the
-    // handle's actual collect/accumulator (custom collects included), not just a
-    // default flatten.
     const id = (handle as unknown as { $$id: string }).$$id;
     (handleSeed[id] ??= {})[leafRouteSegmentId] = values;
   }
@@ -515,14 +434,6 @@ export async function renderRoute(
     initialSegments.map((s) => s.id),
   );
 
-  // Client-only navigation: re-resolve against the in-memory routes and emit a
-  // re-render. No server fetch — only routes passed to renderRoute exist. The
-  // store update is flushed inside act() so React commits before callers
-  // assert, mirroring how a real navigation lands a single payload swap.
-  // NOTE: the seeded `loaderData` is reused for the target route too (no
-  // per-route loader fetch in a unit test), so every seeded loader stays
-  // available after navigate() — unlike a real navigation, which would fetch
-  // the target route's own loaders. This is a deliberate test-isolation design.
   const navigate = async (target: string): Promise<void> => {
     const nextUrl = new URL(target, TEST_ORIGIN);
     const match = resolve(nextUrl.pathname);
@@ -578,7 +489,6 @@ export async function renderRoute(
   return Object.assign(result, { router });
 }
 
-/** Minimal RscMetadata for client-side re-renders (no server-only fields). */
 function makeMetadata(
   pathname: string,
   segments: ResolvedSegment[],

package/src/testing/run-loader.ts

@@ -177,10 +177,6 @@ export interface RunLoaderOptions<TEnv = any> {
   handles?: ReadonlyArray<readonly [Handle<any, any>, unknown]>;
 }
 
-/**
- * Merge `search` into a request's URL, returning a value `toRequest` can build.
- * Keeps the original method/headers/body when a Request was passed.
- */
 function withSearch(
   request: Request | string | undefined,
   search: Record<string, string> | undefined,
@@ -206,16 +202,6 @@ export type RunnableLoader<T> =
   | ((ctx: TestLoaderContext) => Promise<T> | T)
   | LoaderDefinition<T, any>;
 
-/**
- * Resolve the function to run from either a raw body or a `createLoader()` handle.
- *
- * A handle carries no inline body (`createLoader` registers it in the fetchable
- * registry by `$$id`), so recover it from there — `def.fn` first (a hand-built
- * def), then the registry. This works when the handle resolves through the
- * SERVER build (the consumer's `@rangojs/router` under `rangoTestConfig`, which
- * registers the fn); the CLIENT stub drops the body, so a handle imported that
- * way is unrecoverable and we say so explicitly.
- */
 function resolveLoaderFn<T>(
   loader: RunnableLoader<T>,
 ): (ctx: TestLoaderContext) => Promise<T> | T {
@@ -237,31 +223,11 @@ function resolveLoaderFn<T>(
   return fn as (ctx: TestLoaderContext) => Promise<T> | T;
 }
 
-/**
- * Run a loader and return its resolved data. Pass the RAW loader body, or a
- * registered `createLoader()` handle (its fn is recovered from the registry).
- *
- * @example
- * ```ts
- * // raw body
- * const a = await runLoader(
- *   async (ctx) => ({ id: ctx.params.id, user: ctx.get("user") }),
- *   { params: { id: "42" }, vars: { user: { name: "Ada" } } },
- * );
- * // registered createLoader() handle (recovered from the registry)
- * const b = await runLoader(ProductLoader, { params: { id: "42" } });
- * ```
- */
-// Build the createTestRequestContext options from runLoader's options. Shared by
-// runLoader (returns the loader data) and runLoaderResult (also snapshots effects).
 function buildLoaderCtxOpts(
   opts: RunLoaderOptions,
 ): CreateTestContextOptions<any> {
   return {
     env: opts.env,
-    // Bake opts.search into the request URL itself so ctx.request.url, ctx.url,
-    // and ctx.searchParams all agree (production carries the query string on the
-    // real request — a loader reading ctx.request.url must see it too).
     request: withSearch(opts.request, opts.search),
     requestInit: opts.method ? { method: opts.method } : undefined,
     vars: opts.vars,
@@ -276,33 +242,19 @@ function buildLoaderCtxOpts(
   };
 }
 
-// Enter `reqCtx` and run `fn` with a seeded TestLoaderContext (the same ctx shape
-// a real loader receives). The single place the loader context is built, so
-// runLoader and runLoaderResult share identical loader-context semantics.
 function runWithLoaderContext<R>(
   reqCtx: RequestContext<any>,
   opts: RunLoaderOptions,
   fn: (ctx: TestLoaderContext) => R,
 ): R {
-  // Seed values for ctx.use(SomeHandle), matched by handle reference (so a real
-  // handle resolves regardless of its build-injected $$id).
   const handleSeeds = new Map<unknown, unknown>(opts.handles ?? []);
-
-  // Seed values for ctx.use(OtherLoader), matched by loader reference (same model
-  // as renderHandler/renderRoute). Checked before the `use` resolver.
   const loaderSeeds = new Map<unknown, unknown>(opts.loaders ?? []);
-
-  // Tracks whether the mocked render barrier has settled. ctx.use(handle)
-  // reads are gated on this, matching production (loader-resolution.ts).
   let renderedResolved = false;
 
   return runWithRequestContext(reqCtx, () => {
     const reverse = opts.routeMap
       ? createReverseFunction(opts.routeMap, opts.routeName, opts.params ?? {})
       : ((() => {
-          // Documented contract: reverse requires routeMap. Do NOT fall back to
-          // reqCtx.reverse (the global route map) — that leaks whichever routes
-          // another test registered and contradicts the documented behavior.
           throw new Error(
             "ctx.reverse() requires the `routeMap` option in runLoader(). " +
               "Pass { routeMap: { name: pattern, ... } } to enable reverse().",
@@ -323,10 +275,6 @@ function runWithLoaderContext<R>(
       executionContext: reqCtx.executionContext,
       get: reqCtx.get as TestLoaderContext["get"],
       use: ((dep: LoaderDefinition<any, any> | Handle<any, any>) => {
-        // Match production (loader-resolution.ts): reading a handle in a loader
-        // requires the render barrier to have settled. Gate BEFORE returning a
-        // seed, so a loader that forgets `await ctx.rendered()` fails in the
-        // test exactly as it would at runtime.
         if (isHandle(dep) && !renderedResolved) {
           throw new Error(
             `ctx.use(handle) in a loader requires "await ctx.rendered()" first. ` +
@@ -334,16 +282,8 @@ function runWithLoaderContext<R>(
               `the render tree has settled.`,
           );
         }
-        // Handle reads (ctx.use(SomeHandle)) resolve from the seeded map first.
         if (handleSeeds.has(dep)) return handleSeeds.get(dep);
-        // Post-barrier, an UNSEEDED handle must match production
-        // (loader-resolution.ts -> collectHandleData), which runs the handle's
-        // registered collect over empty segments (collect([])) rather than
-        // throwing or leaking into the loader resolver. Resolve it via
-        // collectHandle, which recovers and runs that same collect.
         if (isHandle(dep)) return collectHandle(dep, []);
-        // Loader reads (ctx.use(OtherLoader)) resolve from the seeded map next,
-        // then the dynamic `use` resolver, then the real request-context use().
         if (loaderSeeds.has(dep)) return loaderSeeds.get(dep);
         if (opts.use) return opts.use(dep as LoaderDefinition<any, any>);
         return reqCtx.use(dep as LoaderDefinition<any, any>);
@@ -358,7 +298,6 @@ function runWithLoaderContext<R>(
               if (typeof opts.rendered === "function") {
                 await opts.rendered();
               }
-              // Barrier has settled: subsequent ctx.use(handle) reads resolve.
               renderedResolved = true;
             }
           : () => {
@@ -377,13 +316,6 @@ function runWithLoaderContext<R>(
   });
 }
 
-/**
- * Run a loader and return its resolved data.
- *
- * Effects the loader sets (cookies, response headers, a thrown redirect) are NOT
- * observable here — use {@link runLoaderResult} for an auth-style loader that
- * sets a `Set-Cookie` and/or `throw redirect(...)`.
- */
 export async function runLoader<T>(
   loader: RunnableLoader<T>,
   opts: RunLoaderOptions = {},
@@ -395,12 +327,6 @@ export async function runLoader<T>(
   );
 }
 
-/**
- * What a loader run accumulated: its data PLUS the response effects it produced,
- * surfaced as PUBLIC values (parity with `runMiddleware`/`runInRequestContext`)
- * so an effect-setting loader is assertable without casting through the
- * `@internal` request context.
- */
 export interface RunLoaderResult<T> {
   /**
    * The loader's resolved data (the value bare `runLoader` returns), or
@@ -430,25 +356,6 @@ export interface RunLoaderResult<T> {
   stateCookieName: string;
 }
 
-/**
- * Run a loader AND surface the response effects it produced. The richer sibling
- * of {@link runLoader} (which returns the bare data): use this when the loader
- * sets a cookie / response header / location-state, or `throw redirect(...)`, and
- * the test must assert that output.
- *
- * @example
- * ```ts
- * // AuthLoader: validates, sets a `session` cookie, then `throw redirect("/")`.
- * const { thrown, response, cookies } = await runLoaderResult(AuthLoader, {
- *   request: new Request("https://app.test/login?token=ok"),
- * });
- * expect((thrown as Response).headers.get("Location")).toBe("/");
- * expect(cookies.session).toBeDefined();
- * expect(
- *   response.headers.getSetCookie().some((c) => c.startsWith("session=")),
- * ).toBe(true);
- * ```
- */
 export async function runLoaderResult<T>(
   loader: RunnableLoader<T>,
   opts: RunLoaderOptions = {},
@@ -465,9 +372,6 @@ export async function runLoaderResult<T>(
       Promise.resolve(loaderFn(loaderCtx)),
     );
   } catch (error) {
-    // Capture (do NOT re-throw): a loader's success path is often
-    // `throw redirect(...)`, and the cookie/flash it set before the throw must
-    // stay observable (parity with runInRequestContext).
     thrown = error;
   }
   return { result, ...buildRunSnapshot(reqCtx, thrown, stateCookieName) };

package/src/testing/run-middleware.ts

@@ -133,21 +133,6 @@ export interface RunMiddlewareResult<TEnv = any> {
   stateCookieName: string;
 }
 
-/**
- * Run a middleware chain and return the response plus observable context.
- *
- * @example
- * ```ts
- * const { response, ctx, nextCalled } = await runMiddleware(
- *   async (ctx, next) => {
- *     if (!ctx.get("user")) return new Response(null, { status: 401 });
- *     return next();
- *   },
- *   { request: "/dashboard", vars: [["user", { id: 1 }]] },
- * );
- * // nextCalled === 1, response.status === 200
- * ```
- */
 export async function runMiddleware<TEnv = any>(
   mw: MiddlewareFn<TEnv> | MiddlewareFn<TEnv>[],
   opts: RunMiddlewareOptions<TEnv>,
@@ -181,11 +166,6 @@ export async function runMiddleware<TEnv = any>(
     return opts.next?.() ?? new Response(null, { status: 200 });
   };
 
-  // Match production: app/response middleware receive ctx.reverse built from the
-  // route map ALONE (no matched route name or current params), so reversing a
-  // parameterized route without explicit params does NOT auto-fill from the
-  // current request. Passing routeName/params here would recreate the
-  // false-confidence class fixed in dispatch.
   const reverse = opts.routeMap
     ? (createReverseFunction(opts.routeMap) as (
         name: string,
@@ -194,12 +174,6 @@ export async function runMiddleware<TEnv = any>(
       ) => string)
     : undefined;
 
-  // Keep the RETURNED ctx.reverse consistent with the map-only reverse the
-  // chain receives. createTestRequestContext installs an auto-fill reverse
-  // (correct for the loader phase) when routeName/params are passed, but
-  // production app/response middleware see a map-only reverse. Without this,
-  // a middleware reading getRequestContext().reverse — or a consumer asserting
-  // on result.ctx.reverse — would observe auto-fill that production never does.
   if (reverse) {
     (ctx as RequestContext<TEnv>).reverse =
       reverse as RequestContext<TEnv>["reverse"];

package/src/theme/ThemeProvider.tsx

@@ -28,9 +28,6 @@ import type {
 } from "./types.js";
 import { THEME_COOKIE } 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,38 +130,26 @@ 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) => {
       setThemeState(newTheme);
@@ -200,7 +160,6 @@ export function ThemeProvider({
     [config],
   );
 
-  // Listen for system preference changes
   useEffect(() => {
     if (!config.enableSystem) return;
     if (typeof window === "undefined" || !window.matchMedia) return;
@@ -211,13 +170,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 +182,6 @@ export function ThemeProvider({
     };
   }, [config, theme]);
 
-  // Cross-tab synchronization via localStorage storage event
   useEffect(() => {
     if (typeof window === "undefined") return;
 
@@ -249,12 +205,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 +218,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 +225,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

@@ -43,12 +43,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,