@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.0

package/dist/types/testing/run-middleware.d.ts

@@ -0,0 +1,132 @@
+/**
+ * runMiddleware — unit-test one or more middleware functions in isolation.
+ *
+ * Executes the middleware chain via the SAME executeLoaderMiddleware the router
+ * uses, so ordering, `next()`, short-circuit (return OR throw Response),
+ * double-next guards, and header/cookie merging behave identically to
+ * production. The chain runs inside runWithRequestContext, so cookie/header
+ * mutations and getRequestContext() resolve.
+ *
+ * The returned `ctx` is the underlying RequestContext (not the per-middleware
+ * MiddlewareContext), exposing `ctx.cookies()`, `ctx.get()`, and
+ * `ctx.res.headers` for assertions on what the chain produced.
+ *
+ * `nextCalled` counts how many times the terminal `next()` (the finalHandler)
+ * ran: 0 when the chain short-circuited, 1 when it ran to completion.
+ */
+import { type RequestContext } from "../server/request-context.js";
+import type { MiddlewareFn } from "../router/middleware-types.js";
+import { type VarsInit, type StateCookieSeed } from "./internal/context.js";
+import type { ThemeConfig } from "../theme/types.js";
+import type { SegmentCacheStore } from "../cache/types.js";
+import type { CacheProfile } from "../cache/profile-registry.js";
+/**
+ * Options for runMiddleware.
+ */
+export interface RunMiddlewareOptions<TEnv = any> {
+    /**
+     * The request the chain runs under: a `Request`, or a URL string (absolute or
+     * path). Optional for parity with `runLoader`/`runInRequestContext` — when
+     * omitted it defaults to `http://localhost/`. Pass it for path-, header-, or
+     * cookie-driven middleware.
+     */
+    request?: Request | string;
+    /** Environment bindings surfaced as `ctx.env`. */
+    env?: TEnv;
+    /** Route params surfaced as `ctx.params`. */
+    params?: Record<string, string>;
+    /**
+     * Seed `ctx.build` (default false) so a middleware that branches on the
+     * build-time PPR shell-capture pass (e.g. `if (ctx.build) ctx.dynamic()`) is
+     * unit-testable. With `build: true`, `ctx.waitUntil()` is inert, matching the
+     * build producer. Assert a `ctx.dynamic()` call via `result.dynamic`.
+     */
+    build?: boolean;
+    /** Variables a prior middleware would have set (object or [key, value] list). */
+    vars?: VarsInit;
+    /** Route name -> pattern map enabling `ctx.reverse()`. */
+    routeMap?: Record<string, string>;
+    /**
+     * Matched route name surfaced as `ctx.routeName`. Does NOT scope `.name`
+     * reverse: the chain receives a map-only `reverse` (built from `routeMap`
+     * alone), matching production app/response middleware — see the reverse
+     * construction below.
+     */
+    routeName?: string;
+    /** Router basename surfaced on the context (drives redirect() prefixing). */
+    basename?: string;
+    /** Theme config in the `createRouter({ theme })` shape (enables ctx.theme). */
+    theme?: ThemeConfig | true;
+    /**
+     * Terminal handler invoked when the chain calls `next()` all the way through.
+     * Defaults to a 200 empty Response. Use this to model the downstream
+     * route/handler response.
+     */
+    next?: () => Promise<Response>;
+    /**
+     * Cache store backing any `use cache` function a middleware invokes. Without
+     * it, registerCachedFunction bypasses (it checks for a store first), so the
+     * cached function runs uncached and its taint/profile guards never fire.
+     */
+    cacheStore?: SegmentCacheStore;
+    /** Cache profiles (the `createRouter({ cacheProfiles })` shape). */
+    cacheProfiles?: Record<string, CacheProfile>;
+    /**
+     * Customize the rango state cookie a middleware that calls
+     * `invalidateClientCache()` rotates (the name is always seeded — default
+     * `rango-state_router_0` — so it rotates like production). Assert via the
+     * `Set-Cookie` on `result.response` / `result.cookies`.
+     */
+    stateCookie?: StateCookieSeed;
+}
+/**
+ * Result of runMiddleware.
+ */
+export interface RunMiddlewareResult<TEnv = any> {
+    /** The final Response (downstream response, or a middleware short-circuit). */
+    response: Response;
+    /**
+     * The underlying RequestContext. Read `ctx.cookies()`, `ctx.get(...)`, and
+     * `ctx.res.headers` to assert on the chain's effects. (This is always the
+     * RequestContext the chain ran under — not a per-middleware MiddlewareContext —
+     * so `ctx.cookies()` and the other RequestContext accessors are available.)
+     */
+    ctx: RequestContext<TEnv>;
+    /** Number of times the terminal handler ran (0 = short-circuited, 1 = passed through). */
+    nextCalled: number;
+    /**
+     * Whether the chain called `ctx.dynamic()` (the PPR shell opt-out). The public
+     * way to assert the opt-out without reading the `@internal` `ctx._dynamic`.
+     */
+    dynamic: boolean;
+    /**
+     * The effective cookie view after the chain ran: request cookies merged with
+     * anything the chain set or deleted (last-write-wins), as `{ name: value }`.
+     * The public way to assert a cookie a middleware set, without casting through
+     * the `@internal` `ctx.cookies()`. Set-Cookie headers are also on `response`.
+     */
+    cookies: Record<string, string>;
+    /**
+     * The final response's headers as a plain `{ name: value }` object (the same
+     * view as `response.headers`), EXCLUDING `set-cookie` (use `cookies`). The
+     * public way to assert a header a middleware set (e.g. a security header)
+     * without reading `ctx.res.headers`. Header names are lowercased.
+     */
+    headers: Record<string, string>;
+    /**
+     * Location state the chain set via `ctx.setLocationState()` / `redirect({ state })`,
+     * resolved to the flat `{ key: value }` shape the client reads off
+     * `history.state` (empty object when none) — parity with `runInRequestContext`
+     * and `renderHandler`.
+     */
+    locationState: Record<string, unknown>;
+    /**
+     * The resolved rango state cookie name seeded for the run (default
+     * `rango-state_router_0`, or composed from `opts.stateCookie`). Assert a
+     * middleware's `invalidateClientCache()` rotation against it without
+     * recomputing — parity with `runInRequestContext` / `runLoaderResult` /
+     * `renderHandler`.
+     */
+    stateCookieName: string;
+}
+export declare function runMiddleware<TEnv = any>(mw: MiddlewareFn<TEnv> | MiddlewareFn<TEnv>[], opts: RunMiddlewareOptions<TEnv>): Promise<RunMiddlewareResult<TEnv>>;

package/dist/types/testing/run-transition-when.d.ts

@@ -0,0 +1,77 @@
+/**
+ * runTransitionWhen — unit-test a transition({ when }) predicate in isolation.
+ *
+ * Runs the SAME two server functions the router uses — applyViewTransitionDefault
+ * (strips the `when` function from the serialized config and records the
+ * predicate on the request context) and gateTransitions (assembles the
+ * TransitionWhenContext and evaluates the predicate post-handler). So the
+ * predicate sees exactly the navigation/action metadata it would at runtime
+ * (currentUrl/currentParams/fromRouteName, nextUrl/nextParams/toRouteName,
+ * actionId/actionUrl/actionResult/formData/method, get/env), and `kept` reflects
+ * whether the transition would apply this request. The result also exposes the
+ * assembled `whenContext` so tests can assert the exact fields without reaching
+ * into private request-context state.
+ *
+ * This is the public way to exercise a transition gate: the full
+ * match -> render pipeline that wires these together only runs under real RSC
+ * rendering (which the Flight primitives do not drive), so without this primitive
+ * a consumer could not test their predicate through @rangojs/router/testing.
+ *
+ * Synchronous: a transition predicate returns a boolean and the gate has no I/O.
+ */
+import { type RequestContext } from "../server/request-context.js";
+import { type VarsInit } from "./internal/context.js";
+import type { TransitionConfig, TransitionWhenContext } from "../types/segments.js";
+import type { OnErrorCallback } from "../types/error-types.js";
+/**
+ * Options for runTransitionWhen. All navigation/action fields are optional and
+ * default to "absent", matching what the gate sees for an initial full load with
+ * no action: omit `currentUrl`/`currentParams`/`fromRouteName` to model the
+ * navigation source being unavailable, and omit the `action*` fields to model a
+ * plain (non-action) navigation.
+ */
+export interface RunTransitionWhenOptions<TEnv = any> {
+    /** The navigation TARGET request (drives `nextUrl`): a Request or URL/path string. Defaults to `http://localhost/`. */
+    request?: Request | string;
+    /** Route params for the target (`nextParams`). */
+    params?: Record<string, string>;
+    /** Target route name (`toRouteName`). */
+    toRouteName?: string;
+    /** Environment bindings surfaced as `env` (and `ctx.env`). */
+    env?: TEnv;
+    /** Variables a handler/middleware would have set this request, readable via the predicate's `get()`. */
+    vars?: VarsInit;
+    /** Navigation SOURCE url (`currentUrl`): a URL or path string. */
+    currentUrl?: string | URL;
+    /** Source route params (`currentParams`). */
+    currentParams?: Record<string, string>;
+    /** Source route name (`fromRouteName`). */
+    fromRouteName?: string;
+    /** Id of the action that triggered a revalidation (`actionId`). */
+    actionId?: string;
+    /** Url the action was submitted from (`actionUrl`). */
+    actionUrl?: string | URL;
+    /** The action's return value (`actionResult`). */
+    actionResult?: unknown;
+    /** FormData from a form action (`formData`). */
+    formData?: FormData;
+    /** Receives an error thrown by the predicate (the gate reports to `router.onError`, phase `"rendering"`). */
+    onError?: OnErrorCallback;
+}
+/**
+ * Result of runTransitionWhen.
+ */
+export interface RunTransitionWhenResult<TEnv = any> {
+    /** True if the transition would apply this request (predicate returned non-false, or there is no `when`). */
+    kept: boolean;
+    /** Convenience inverse of `kept`. */
+    dropped: boolean;
+    /**
+     * The production-assembled predicate context. Undefined when the config has
+     * no `when` predicate.
+     */
+    whenContext?: TransitionWhenContext<Record<string, string>, TEnv>;
+    /** The underlying RequestContext, for additional assertions (`ctx.get(...)`, etc.). */
+    ctx: RequestContext<TEnv>;
+}
+export declare function runTransitionWhen<TEnv = any>(config: TransitionConfig, opts?: RunTransitionWhenOptions<TEnv>): RunTransitionWhenResult<TEnv>;

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

@@ -0,0 +1,58 @@
+/**
+ * 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`).
+ *
+ * ## 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 HIT signal:** response header `x-rango-shell` (`HIT` | `MISS`),
+ *    always on document GETs to a ppr route that the serve path considered.
+ *    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).
+ */
+/** Production header name (`rsc/shell-serve.ts` `SHELL_STATUS_HEADER`). */
+export declare const SHELL_STATUS_HEADER: string;
+/** Values the serve path writes on `x-rango-shell`. */
+export type ShellStatus = "HIT" | "MISS";
+/** 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`).
+ */
+export declare function shellCacheKey(url: URL | string): 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;

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;