@rangojs/router 0.0.0-experimental.f3c21dba → 0.0.0-experimental.f4a8e8de

package/dist/types/testing/shell-status.d.ts

@@ -0,0 +1,81 @@
+/**
+ * PPR shell-status testing primitives for @rangojs/router consumers.
+ *
+ * Companion to `cache-status.ts` (segment/document cache): this module covers
+ * the **shell axis** (`ppr` path option → `x-rango-shell: HIT | MISS`) and
+ * partial-navigation segment replay (`x-rango-ppr-replay: HIT`).
+ *
+ * ## Spike conclusions (plan 009)
+ *
+ * 1. **`dispatch` cannot exercise PPR.** It is deliberately RSC-free: no Flight,
+ *    no SSR, no `handleRscRendering` commit point. Seeding `MemorySegmentCacheStore`
+ *    + `ppr: true` on a response route is a no-op for shell serve/capture. The
+ *    production path lives in `rsc/rsc-rendering.ts` + `rsc/shell-capture.ts`.
+ *
+ * 2. **Smallest status signals:** `x-rango-shell` (`HIT` | `MISS`) on document
+ *    GETs, and `x-rango-ppr-replay` on partial requests to ppr routes. A replay
+ *    HIT is reported only when matching consumes the captured segment record.
+ *    Secondary unit signal: `store.getShell(shellCacheKey(url))` after a real
+ *    capture flush (background `putShell`). There is no Flight flag for shell HIT.
+ *
+ * 3. **Stays e2e-only:** live MISS → background capture → HIT (needs real
+ *    `captureShellHTML` / React `prerender` + resume fizz), browser resume of
+ *    holes, Cloudflare/Vercel live stores, nonce/eligibility fall-open, and
+ *    build-time producer B bake. Unit layer dogfoods the **store family + key
+ *    identity + header assert**; it must never stub a shell HIT response.
+ *
+ * Import from `@rangojs/router/testing` (Vitest) or `@rangojs/router/testing/e2e`
+ * (Playwright — same pure helpers, no Vite virtuals).
+ */
+import { type CacheSearchParams } from "../cache/search-params-filter.js";
+/** Production header name (`rsc/shell-serve.ts` `SHELL_STATUS_HEADER`). */
+export declare const SHELL_STATUS_HEADER: string;
+/** Partial-navigation replay decision header from `rsc/rsc-rendering.ts`. */
+export declare const PPR_REPLAY_STATUS_HEADER: string;
+/** Values the serve path writes on `x-rango-shell`. */
+export type ShellStatus = "HIT" | "MISS";
+declare const PPR_REPLAY_BYPASS_REASONS: readonly ["method", "dynamic", "nonce", "store-unavailable", "passive-read-unsupported", "no-navigation-context", "prerender-store", "intercept", "cache-disabled", "read-error", "no-entry", "invalid-version", "corrupt-entry", "handler-live-holes", "transition-when", "no-segment-snapshot", "snapshot-miss", "explicit-cache-hit", "stale-build-entry"];
+/** Bounded reasons a PPR partial request can fall open to ordinary matching. */
+export type PprReplayBypassReason = (typeof PPR_REPLAY_BYPASS_REASONS)[number];
+/** Parsed `x-rango-ppr-replay` value. */
+export type PprReplayStatus = {
+    outcome: "HIT";
+    freshness: "fresh" | "stale";
+} | {
+    outcome: "BYPASS";
+    reason: PprReplayBypassReason;
+};
+/** A target carrying response headers (a Response or a `{ headers }` object). */
+export type ShellStatusTarget = Response | {
+    headers: Headers;
+};
+/**
+ * Shell store key for a document URL — same formula as production
+ * `buildShellKey` in `rsc/shell-serve.ts` (host + pathname + sorted search +
+ * `:shell`). Kept here so the testing barrel never imports the shell-serve
+ * module (it pulls React). A parity test pins the two implementations.
+ *
+ * Accepts a `URL` or an absolute/relative request URL string (relative strings
+ * resolve against `http://localhost`). Pass the router's `cache.searchParams`
+ * config as `searchParams` when the app under test sets one — the production
+ * key applies it, so the expected key must too.
+ */
+export declare function shellCacheKey(url: URL | string, searchParams?: CacheSearchParams): string;
+/**
+ * Read `x-rango-shell` from a response. Returns `null` when the header is
+ * absent (axis-1 / non-ppr / ineligible request).
+ */
+export declare function parseShellStatus(target: ShellStatusTarget): ShellStatus | null;
+/**
+ * Assert a document response's `x-rango-shell` header equals `expected`.
+ * Throws when the header is missing, unrecognized, or mismatched.
+ *
+ * Use on real document GETs (e2e `page.request.get` / `router.fetch`). Do not
+ * invent a HIT Response in unit tests — that fakes the serve path.
+ */
+export declare function assertShellStatus(target: ShellStatusTarget, expected: ShellStatus): void;
+/** Parse the dedicated PPR partial-navigation replay decision header. */
+export declare function parsePprReplayStatus(target: ShellStatusTarget): PprReplayStatus | null;
+/** Assert a partial response's PPR replay outcome and freshness/reason. */
+export declare function assertPprReplayStatus(target: ShellStatusTarget, expected: PprReplayStatus): void;
+export {};

package/dist/types/testing/vitest-stubs/cloudflare-email.d.ts

@@ -0,0 +1,6 @@
+export declare class EmailMessage {
+    from: string;
+    to: string;
+    raw: unknown;
+    constructor(from: string, to: string, raw: unknown);
+}

package/dist/types/testing/vitest-stubs/cloudflare-workers.d.ts

@@ -0,0 +1,13 @@
+export declare const env: Record<string, unknown>;
+export declare class DurableObject<Env = unknown> {
+    ctx: unknown;
+    env: Env;
+    constructor(ctx: unknown, env: Env);
+}
+export declare class WorkerEntrypoint<Env = unknown> {
+    ctx: unknown;
+    env: Env;
+    constructor(ctx: unknown, env: Env);
+}
+export declare class RpcTarget {
+}

package/dist/types/testing/vitest-stubs/plugin-rsc.d.ts

@@ -0,0 +1,7 @@
+export declare const createFromReadableStream: () => never;
+export declare const renderToReadableStream: () => never;
+export declare const loadServerAction: () => undefined;
+export declare const decodeReply: () => undefined;
+export declare const decodeAction: () => undefined;
+export declare const decodeFormState: () => undefined;
+export declare const createTemporaryReferenceSet: () => Record<string, never>;

package/dist/types/testing/vitest-stubs/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "";

package/dist/types/testing/vitest.d.ts

@@ -0,0 +1,205 @@
+/**
+ * @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.
+ */
+/** 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";
+}
+/**
+ * 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 declare function rangoTestAliases(opts?: RangoTestAliasOptions): TestAlias[];
+/**
+ * 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 declare const rangoInlineDeps: RegExp[];
+/** 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 declare function rangoTestConfig(opts?: RangoTestAliasOptions): RangoTestConfig;
+/** 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 declare function rangoUseClientTransform(): FlightTransformPlugin;
+export {};

package/dist/types/theme/ThemeProvider.d.ts

@@ -0,0 +1,13 @@
+/**
+ * ThemeProvider - Client component that provides theme state and management.
+ *
+ * Features:
+ * - Syncs theme to cookie/localStorage
+ * - Detects system preference changes
+ * - Cross-tab synchronization via storage events
+ * - Updates HTML element attribute when theme changes
+ * - Handles SSR hydration by deferring system theme detection
+ */
+import React from "react";
+import type { ThemeProviderProps } from "./types.js";
+export declare function ThemeProvider({ config, initialTheme, children, }: ThemeProviderProps): React.ReactNode;

package/dist/types/theme/ThemeScript.d.ts

@@ -0,0 +1,45 @@
+/**
+ * ThemeScript - Server component that renders an inline script for FOUC prevention.
+ *
+ * This component renders a blocking inline script that:
+ * 1. Reads theme from cookie/localStorage before paint
+ * 2. Applies the theme to the HTML element immediately
+ * 3. Prevents flash of unstyled content (FOUC)
+ *
+ * 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. 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 config={config} />
+ *       </head>
+ *       <body>{children}</body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+import React from "react";
+import type { ResolvedThemeConfig } from "./types.js";
+export interface ThemeScriptProps {
+    /**
+     * Theme configuration - passed from router.themeConfig
+     */
+    config: ResolvedThemeConfig;
+    /**
+     * Optional nonce for CSP
+     */
+    nonce?: string;
+}
+export declare function ThemeScript({ config, nonce, }: ThemeScriptProps): React.ReactNode;

package/dist/types/theme/constants.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Default values for theme configuration
+ */
+import type { ResolvedThemeConfig, ThemeConfig } from "./types.js";
+export declare const THEME_DEFAULTS: {
+    readonly defaultTheme: "system";
+    readonly themes: readonly ["light", "dark"];
+    readonly attribute: "class";
+    readonly storageKey: "theme";
+    readonly enableSystem: true;
+    readonly enableColorScheme: true;
+};
+export declare const THEME_COOKIE: {
+    readonly maxAge: number;
+    readonly path: string;
+    readonly sameSite: "lax";
+};
+/**
+ * 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 declare function isValidTheme(theme: string, config: Pick<ResolvedThemeConfig, "themes" | "enableSystem">): boolean;
+/**
+ * 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 declare function warnInvalidTheme(theme: string, config: Pick<ResolvedThemeConfig, "themes" | "enableSystem">): void;
+export declare function resolveThemeConfig(config: ThemeConfig | true): ResolvedThemeConfig;

package/dist/types/theme/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Theme module exports for @rangojs/router/theme
+ *
+ * This module provides the public theme API:
+ * - useTheme: Hook for accessing theme state in client components
+ * - ThemeProvider: Component for manual theme provider setup (typically not needed)
+ * - ThemeScript: FOUC-prevention script component for document/head usage
+ * - Types for theme configuration
+ *
+ * @example
+ * ```tsx
+ * // In a client component
+ * import { useTheme } from "@rangojs/router/theme";
+ *
+ * function ThemeToggle() {
+ *   const { theme, setTheme, themes } = useTheme();
+ *   return (
+ *     <select value={theme} onChange={e => setTheme(e.target.value)}>
+ *       {themes.map(t => <option key={t}>{t}</option>)}
+ *     </select>
+ *   );
+ * }
+ * ```
+ */
+export { useTheme } from "./use-theme.js";
+export { ThemeProvider } from "./ThemeProvider.js";
+export { ThemeScript, type ThemeScriptProps } from "./ThemeScript.js";
+export type { Theme, ResolvedTheme, ThemeAttribute, ThemeConfig, ResolvedThemeConfig, UseThemeReturn, ThemeProviderProps, ThemeContextValue, } from "./types.js";
+export { THEME_DEFAULTS, THEME_COOKIE } from "./constants.js";

package/dist/types/theme/theme-context.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Theme context for sharing theme state and configuration.
+ *
+ * Used by:
+ * - ThemeProvider to provide theme state
+ * - useTheme hook to access theme state
+ * - MetaTags to check if theme is enabled and render script
+ */
+import { type Context } from "react";
+import type { ThemeContextValue } from "./types.js";
+/**
+ * React context for theme state
+ * null when theme is not enabled in router config
+ */
+export declare const ThemeContext: Context<ThemeContextValue | null>;
+export declare function useThemeContext(): ThemeContextValue | null;
+/**
+ * Get theme context, throwing if not available
+ * Used by useTheme hook
+ */
+export declare function requireThemeContext(): ThemeContextValue;

package/dist/types/theme/theme-script.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Generates an inline script for FOUC prevention.
+ *
+ * This script runs synchronously before page paint to:
+ * 1. Read theme from cookie or localStorage
+ * 2. Detect system preference if theme is "system"
+ * 3. Apply theme to HTML element via class or data attribute
+ * 4. Optionally set color-scheme CSS property
+ *
+ * The script is minified and inlined in <head> before any other content.
+ */
+import type { ResolvedThemeConfig } from "./types.js";
+/**
+ * Generate the inline script for theme initialization
+ *
+ * The script is designed to:
+ * - Run synchronously before paint (blocking)
+ * - Be as small as possible to minimize blocking time
+ * - Work without any external dependencies
+ * - Handle all edge cases (no localStorage, no cookie, etc.)
+ */
+export declare function generateThemeScript(config: ResolvedThemeConfig): string;
+/**
+ * Generate nonce attribute string if nonce is provided
+ */
+export declare function getNonceAttribute(nonce?: string): string;

package/dist/types/theme/types.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Theme type definitions for rsc-router theme system.
+ *
+ * The theme system provides:
+ * - Opt-in via router config
+ * - FOUC prevention via inline script
+ * - Server-side theme access via ctx.theme/ctx.setTheme
+ * - Client-side theme access via useTheme hook
+ */
+/**
+ * Theme value - stored in cookies/localStorage
+ */
+export type Theme = "light" | "dark" | "system";
+/**
+ * Resolved theme - actual visual appearance (system preference resolved)
+ */
+export type ResolvedTheme = "light" | "dark";
+/**
+ * Attribute used to apply theme to HTML element
+ * - "class": Adds theme value as CSS class (e.g., <html class="dark">)
+ * - "data-*": Sets data attribute (e.g., <html data-theme="dark">)
+ */
+export type ThemeAttribute = "class" | `data-${string}`;
+/**
+ * Theme configuration for router
+ *
+ * @example
+ * ```typescript
+ * const router = createRouter<Env>({
+ *   theme: {
+ *     defaultTheme: "system",
+ *     themes: ["light", "dark"],
+ *     attribute: "class",
+ *     storageKey: "theme",
+ *   }
+ * });
+ * ```
+ */
+export interface ThemeConfig {
+    /**
+     * Default theme when no preference is stored
+     * @default "system"
+     */
+    defaultTheme?: Theme;
+    /**
+     * Available theme options
+     * @default ["light", "dark"]
+     */
+    themes?: string[];
+    /**
+     * Attribute to apply to HTML element
+     * @default "class"
+     */
+    attribute?: ThemeAttribute;
+    /**
+     * Key for cookie and localStorage
+     * @default "theme"
+     */
+    storageKey?: string;
+    /**
+     * Enable system preference detection
+     * When true, "system" theme will resolve based on prefers-color-scheme
+     * @default true
+     */
+    enableSystem?: boolean;
+    /**
+     * Set CSS color-scheme property on HTML element
+     * This enables native dark mode for form controls, scrollbars, etc.
+     * @default true
+     */
+    enableColorScheme?: boolean;
+    /**
+     * Custom mapping of theme names to attribute values
+     * Useful when theme names don't match desired attribute values
+     *
+     * @example
+     * ```typescript
+     * value: {
+     *   light: "light-mode",
+     *   dark: "dark-mode",
+     * }
+     * ```
+     */
+    value?: Record<string, string>;
+}
+/**
+ * Resolved theme configuration with defaults applied
+ */
+export interface ResolvedThemeConfig {
+    defaultTheme: Theme;
+    themes: string[];
+    attribute: ThemeAttribute;
+    storageKey: string;
+    enableSystem: boolean;
+    enableColorScheme: boolean;
+    value: Record<string, string>;
+}
+/**
+ * Return type from useTheme hook
+ *
+ * @example
+ * ```tsx
+ * function ThemeToggle() {
+ *   const { theme, setTheme, resolvedTheme, themes } = useTheme();
+ *
+ *   return (
+ *     <select value={theme} onChange={e => setTheme(e.target.value as Theme)}>
+ *       {themes.map(t => <option key={t}>{t}</option>)}
+ *     </select>
+ *   );
+ * }
+ * ```
+ */
+export interface UseThemeReturn {
+    /**
+     * Current theme setting ("light" | "dark" | "system")
+     */
+    theme: Theme;
+    /**
+     * Set the theme
+     */
+    setTheme: (theme: Theme) => void;
+    /**
+     * Resolved theme based on system preference
+     * When theme is "system", this reflects the actual appearance
+     */
+    resolvedTheme: ResolvedTheme;
+    /**
+     * Current system preference ("light" | "dark")
+     */
+    systemTheme: ResolvedTheme;
+    /**
+     * Available theme options (includes "system" if enableSystem is true)
+     */
+    themes: string[];
+}
+/**
+ * Props for ThemeProvider component
+ */
+export interface ThemeProviderProps {
+    /**
+     * Theme configuration
+     */
+    config: ResolvedThemeConfig;
+    /**
+     * Initial theme from server (from cookie)
+     */
+    initialTheme?: Theme;
+    /**
+     * Children to render
+     */
+    children: React.ReactNode;
+}
+/**
+ * Context value for ThemeContext
+ */
+export interface ThemeContextValue extends UseThemeReturn {
+    /**
+     * Full theme configuration
+     */
+    config: ResolvedThemeConfig;
+}

package/dist/types/theme/use-theme.d.ts

@@ -0,0 +1,8 @@
+import type { UseThemeReturn } from "./types.js";
+/**
+ * Hook to access theme state and methods.
+ *
+ * Must be used within a ThemeProvider (which is automatically included
+ * in NavigationProvider when theme is enabled in router config).
+ */
+export declare function useTheme(): UseThemeReturn;