@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.0

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

@@ -0,0 +1,115 @@
+/**
+ * renderToFlightString — REAL React Server Component (Flight) rendering for
+ * unit tests of @rangojs/router consumer apps.
+ *
+ * This module renders a server component tree to its Flight wire string using
+ * the same react-server-dom serializer the router uses at runtime. It runs in
+ * plain node (no Vite, no browser), but ONLY under the `react-server` export
+ * condition. The serializer is the VENDORED build shipped with
+ * @vitejs/plugin-rsc — the public `@vitejs/plugin-rsc/rsc` entry top-level
+ * imports Vite virtual modules and is not usable outside a Vite build.
+ *
+ * Run the example/tests for this module via the dedicated rsc vitest project
+ * (vitest.rsc.config.ts), which forces `--conditions=react-server` on the
+ * worker. The main vitest project must NOT use that condition (it would flip
+ * React to the no-hooks server build and break the ~50 tests that mock
+ * @vitejs/plugin-rsc/rsc).
+ *
+ * Scope / limitations (v1):
+ * - Server-only / leaf trees. A tree containing a CLIENT component emits an
+ *   `I[...]` import row whose module id will not resolve against the empty `{}`
+ *   client manifest used here — fine for snapshotting the SHAPE of the payload.
+ *   To inspect a client boundary's deserialized props instead, use
+ *   `renderServerTree` (flight-tree.ts). Interactive hydration stays at the e2e tier.
+ * - The vendored subpath is a private plugin-rsc path; a minor bump could move
+ *   it. `assertFlightRuntimeAvailable()` provides a smoke check.
+ * - For stable snapshots, run under NODE_ENV=production: the production
+ *   serializer drops the dev-only debug-info rows (the `N<timestamp>` reference
+ *   row, the per-component `stack`/`env` rows, and `D{...}` timing rows),
+ *   leaving just the rendered tree row(s).
+ */
+import type { ReactNode } from "react";
+import { type VarsInit } from "./internal/seed-vars.js";
+import { normalizeFlight } from "./flight-normalize.js";
+import type { ThemeConfig } from "../theme/types.js";
+import type { SegmentCacheStore } from "../cache/types.js";
+import type { CacheProfile } from "../cache/profile-registry.js";
+export { normalizeFlight };
+/**
+ * Options for {@link renderToFlightString}.
+ */
+export interface RenderToFlightStringOptions {
+    /**
+     * The request the render runs under: a `Request`, or a URL string (absolute or
+     * path). Defaults to `http://localhost/`. A server component reading
+     * `getRequestContext()` sees this request's url/cookies. When a `Request` is
+     * passed, its headers are used and `headers` below is ignored.
+     */
+    request?: Request | string;
+    /** Request headers (e.g. Cookie) visible to the server tree (when `request` is a string). */
+    headers?: HeadersInit;
+    /** Env / bindings exposed as `ctx.env`. Defaults to `{}`. */
+    env?: unknown;
+    /** Route params exposed via `ctx.params` and loader contexts. */
+    params?: Record<string, string>;
+    /** Matched route name (drives `ctx.routeName` and scoped reverse). */
+    routeName?: string;
+    /**
+     * Route name -> pattern map enabling a SCOPED `ctx.reverse()` (like
+     * `renderHandler`). Without it, a server component that reverses resolves
+     * against the GLOBAL route map and is order-dependent on whatever router
+     * registered last. Pass the router-under-test's map to make reversing
+     * deterministic.
+     */
+    routeMap?: Record<string, string>;
+    /**
+     * Context variables visible to the rendered tree via `ctx.get(...)` — as a
+     * prior middleware would have set them. Seeds the SAME way the handler-test
+     * primitives (`runInRequestContext`/`runLoader`) do, so a server component
+     * that reads `getRequestContext().get(MyVar)` during render is testable.
+     * Object form (`{ user }`) or `[key, value]` tuples (`[[userVar, u]]`).
+     */
+    vars?: VarsInit;
+    /**
+     * Theme config in the same shape `createRouter({ theme })` takes (e.g. `true`
+     * or `{ themes: [...] }`). Without it `getRequestContext().theme` is `undefined`
+     * and `ctx.setTheme` is inert — pass one to render a server component that
+     * reads `ctx.theme`. Threaded into the SAME createRequestContext renderHandler
+     * uses, so the two Flight primitives expose theme identically.
+     */
+    theme?: ThemeConfig | true;
+    /**
+     * Cache store backing a `"use cache"` function the rendered server tree
+     * invokes. Without it, `registerCachedFunction` takes the uncached bypass and
+     * the cached path is NOT exercised. Pair with `cacheProfiles` so a
+     * `"use cache: profileName"` directive resolves its profile.
+     */
+    cacheStore?: SegmentCacheStore;
+    /** Cache profiles in the `createRouter({ cacheProfiles })` shape. */
+    cacheProfiles?: Record<string, CacheProfile>;
+}
+/**
+ * True when `error` is the out-of-react-server stub thrown by index.ts's
+ * server-only exports (getRequestContext/cookies/headers/...) — i.e. the bare
+ * `@rangojs/router` specifier resolved to index.ts, not index.rsc.ts, because
+ * the rsc Vitest project is missing the `rangoTestAliases` alias. Matches both
+ * substrings of `serverOnlyStubError` (index.ts) so a normal app error cannot
+ * over-match. Shared with render-handler.ts so the two Flight primitives report
+ * the same misconfiguration identically.
+ */
+export declare function isServerOnlyStubError(error: unknown): boolean;
+export declare function assertNoLegacyUrlOption(opts: object, fnName: string): void;
+/**
+ * Render a server component (or any ReactNode) to its Flight wire string.
+ *
+ * The element is wrapped in a minimal Rango segment + payload, then serialized
+ * with the vendored react-server-dom server. A request context is active for
+ * the duration of the render (drained INSIDE runWithRequestContext) so async
+ * server components can call getRequestContext(), read params, cookies, etc.
+ *
+ * Must run under the `react-server` export condition (see module header).
+ */
+export declare function renderToFlightString(element: ReactNode, opts?: RenderToFlightStringOptions): Promise<string>;
+export declare function serializeToFlightString(element: ReactNode, opts: RenderToFlightStringOptions, clientManifest: unknown): Promise<string>;
+export declare function serializeNodeToFlight(node: ReactNode, clientManifest: unknown, pathname: string): Promise<string>;
+export declare function assertFlightRuntimeAvailable(): void;

package/dist/types/testing/flight.entry.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @rangojs/router/testing/flight
+ *
+ * Real React Server Component (Flight) rendering for unit tests. This entry is
+ * SEPARATE from the main ./testing barrel because its serializer (the vendored
+ * react-server-dom build) can only be imported under the `react-server` node
+ * condition; importing it elsewhere throws. Use it only from a Vitest project
+ * configured with that condition (see vitest.rsc.config.ts) — name those test
+ * files `*.rsc-test.{ts,tsx}` and run `pnpm test:unit:rsc`.
+ *
+ * This entry deliberately does NOT pull in Vitest. The `toMatchFlight` /
+ * `toMatchFlightSnapshot` matchers (which import `vitest`) live at the separate
+ * `@rangojs/router/testing/flight-matchers` subpath, so a consumer can import
+ * `renderToFlightString` without taking a hard dependency on Vitest.
+ *
+ * `renderToFlightString` returns the wire STRING (for `toMatchFlight`).
+ * `renderServerTree` additionally deserializes it back to an inspectable React
+ * element tree, so you can assert typed prop fidelity across the client boundary
+ * (a `Date` comes back a `Date`) and detect inlined-vs-island. Serialize +
+ * deserialize only — no hydration/interaction (that is the e2e tier).
+ */
+export { renderToFlightString, normalizeFlight, assertFlightRuntimeAvailable, } from "./flight.js";
+export type { RenderToFlightStringOptions } from "./flight.js";
+export { renderServerTree, findClientBoundaries, findElements, textContent, assertFlightTreeRuntimeAvailable, } from "./flight-tree.js";
+export type { RenderServerTreeOptions, RenderServerTreeResult, ClientBoundary, BoundarySelector, FoundElement, ElementSelector, } from "./flight-tree.js";
+export { renderHandler } from "./render-handler.js";
+export type { TestableHandler, RenderHandlerOptions, RenderHandlerResult, StateCookieSeed, } from "./render-handler.js";

package/dist/types/testing/generated-routes.d.ts

@@ -0,0 +1,66 @@
+/**
+ * assertGeneratedRoutesMatch — pin the generated named-routes map against the
+ * router's runtime route map.
+ *
+ * The Vite plugin writes a `*.named-routes.gen.ts` file mapping route names to
+ * URL patterns; consumers import that map and pass it here. The check compares
+ * it to the router's runtime `routeMap`, catching drift when a route is added,
+ * removed, renamed, or its pattern changes without regenerating the file.
+ *
+ * Directionality (relative to the generated map):
+ * - missing:  present in the generated map but NOT at runtime (stale entry).
+ * - extra:    present at runtime but NOT in the generated map (ungenerated route).
+ *             Auto-generated internal names (the "$path_" / "$prefix_" prefixes)
+ *             are excluded — they live in the runtime map but are never written
+ *             to the generated file, so they are not drift.
+ * - mismatch: present in both under the same name, but the patterns differ.
+ *
+ * When `generatedMap` is omitted, the global route map (getGlobalRouteMap()) is
+ * used as the generated side — useful when a single router has registered into
+ * the global map.
+ */
+/**
+ * Router shape this check depends on: a runtime route map, plus the optional
+ * `findMatch` used to force-expand lazy `include()`d routes (see below).
+ */
+interface RouterWithRouteMap {
+    routeMap: Record<string, unknown>;
+    findMatch?: (pathname: string) => unknown;
+}
+/**
+ * A single name/pattern mismatch: [routeName, generatedPattern, runtimePattern].
+ */
+export type GeneratedRouteMismatch = [
+    name: string,
+    generated: string,
+    runtime: string
+];
+/**
+ * Structured diff between the generated route map and the runtime route map.
+ */
+export interface GeneratedRoutesDiff {
+    /** Names in the generated map but absent at runtime. */
+    missing: string[];
+    /** Names at runtime but absent from the generated map. */
+    extra: string[];
+    /** Names in both with differing patterns. */
+    mismatch: GeneratedRouteMismatch[];
+    /** True when missing, extra, and mismatch are all empty. */
+    ok: boolean;
+}
+export declare function diffGeneratedRoutes(router: RouterWithRouteMap, generatedMap?: Record<string, unknown>): Promise<GeneratedRoutesDiff>;
+/**
+ * Assert the router's runtime route map matches the generated map. Throws a
+ * descriptive Error listing every missing, extra, and mismatched route when
+ * they diverge.
+ *
+ * @example
+ * ```ts
+ * import generated from "./router.named-routes.gen";
+ * import { router } from "./router";
+ *
+ * await assertGeneratedRoutesMatch(router, generated);
+ * ```
+ */
+export declare function assertGeneratedRoutesMatch(router: RouterWithRouteMap, generatedMap?: Record<string, unknown>): Promise<void>;
+export {};

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

@@ -0,0 +1,54 @@
+/**
+ * @rangojs/router/testing
+ *
+ * Consumer-facing testing primitives for apps built on @rangojs/router.
+ *
+ * This is the entry for UNIT and INTEGRATION tests, meant to run under a
+ * Vite-driven Vitest project (the rango Vite plugin must be active so the
+ * `@rangojs/router:version` and related virtual modules the router internals
+ * import can resolve; alternatively alias `@rangojs/router:version`). Importing
+ * this module references neither React, @testing-library/react, @playwright/test,
+ * nor the RSC runtime — a unit suite testing only loaders/middleware/dispatch
+ * pulls in none of them.
+ *
+ * The other surfaces are SEPARATE entries because each pulls a dependency or
+ * runtime this barrel deliberately keeps out:
+ * - `@rangojs/router/testing/dom` — `renderRoute` (the RTL component stub). Kept
+ *   separate so this barrel never references React, the browser runtime, or
+ *   `@testing-library/react` types — a unit suite testing only loaders/middleware
+ *   needs none of them.
+ * - `@rangojs/router/testing/e2e` — the Playwright harness (createRangoE2E,
+ *   useFixture, parityDescribe, expectParity, matchers). Kept separate so it is
+ *   loadable in a plain (non-Vite) Playwright runner, which cannot resolve the
+ *   router-manifest virtual modules this barrel pulls in.
+ * - `@rangojs/router/testing/flight` — real Flight rendering. Its serializer
+ *   (vendored react-server-dom) loads only under the `react-server` node
+ *   condition and would throw if pulled into this barrel.
+ *
+ * Layers:
+ * - Unit:        runMiddleware, runLoader
+ * - Integration: dispatch (request -> Response)
+ * - Cross-cut:   assertCacheStatus, assertShellStatus, assertGeneratedRoutesMatch
+ * - Component:   see @rangojs/router/testing/dom (renderRoute)
+ * - E2E:         see @rangojs/router/testing/e2e
+ * - RSC:         see @rangojs/router/testing/flight
+ */
+export { runMiddleware } from "./run-middleware.js";
+export type { RunMiddlewareOptions, RunMiddlewareResult, } from "./run-middleware.js";
+export { runLoader, runLoaderResult } from "./run-loader.js";
+export type { RunLoaderOptions, RunLoaderResult, UseResolver, TestLoaderContext, } from "./run-loader.js";
+export { runTransitionWhen } from "./run-transition-when.js";
+export type { RunTransitionWhenOptions, RunTransitionWhenResult, } from "./run-transition-when.js";
+export { dispatch } from "./dispatch.js";
+export type { DispatchOptions } from "./dispatch.js";
+export { assertCacheStatus, assertCacheDecision, parseCacheHeader, createCacheSink, filterCacheDecisions, } from "./cache-status.js";
+export type { ExpectedCacheStatus, CacheStatusTarget, CacheSink, } from "./cache-status.js";
+export type { TelemetryEvent, TelemetrySink, CacheDecisionEvent, CacheSegmentSignal, CacheSegmentStatus, } from "../router/telemetry.js";
+export { assertShellStatus, parseShellStatus, shellCacheKey, SHELL_STATUS_HEADER, } from "./shell-status.js";
+export type { ShellStatus, ShellStatusTarget } from "./shell-status.js";
+export { collectHandle } from "./collect-handle.js";
+export { diffGeneratedRoutes, assertGeneratedRoutesMatch, } from "./generated-routes.js";
+export type { GeneratedRoutesDiff, GeneratedRouteMismatch, } from "./generated-routes.js";
+export { createTestRequestContext, runInRequestContext, toRequest, seedVariables, } from "./internal/context.js";
+export type { CreateTestContextOptions, TestRequestContext, TestRequestContextObject, RunInRequestContextResult, VarsInit, StateCookieSeed, } from "./internal/context.js";
+export { runWithRequestContext } from "../server/request-context.js";

package/dist/types/testing/internal/context.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Shared internals for the consumer testing primitives.
+ *
+ * Builds a real RequestContext via the same createRequestContext the RSC
+ * handler uses, with test-friendly defaults, so loaders and middleware run
+ * with production-fidelity context (cookies, headers, get/set, use, reverse)
+ * instead of a hand-rolled mock.
+ */
+import { type RequestContext } from "../../server/request-context.js";
+import { seedVariables, type VarsInit, type StateCookieSeed } from "./seed-vars.js";
+import type { ThemeConfig } from "../../theme/types.js";
+import type { SegmentCacheStore } from "../../cache/types.js";
+import type { CacheProfile } from "../../cache/profile-registry.js";
+export type { VarsInit, StateCookieSeed };
+export { seedVariables };
+/** Normalize a Request | string | undefined into a concrete Request. */
+export declare function toRequest(request: Request | string | undefined, init?: RequestInit): Request;
+export interface CreateTestContextOptions<TEnv> {
+    env?: TEnv;
+    request?: Request | string;
+    requestInit?: RequestInit;
+    /** Backing store for ctx.get()/ctx.set(); pre-seeded from `vars`. */
+    variables?: Record<string, unknown>;
+    /** Variables a prior middleware would have set (object or [key, value] list). */
+    vars?: VarsInit;
+    /** Route name -> pattern map enabling ctx.reverse() without global state. */
+    routeMap?: Record<string, string>;
+    routeName?: string;
+    params?: Record<string, string>;
+    /**
+     * Seed `ctx.build` (default false). Set `true` to unit-test middleware or a
+     * handler that branches on the build-time PPR shell-capture pass — e.g.
+     * `if (ctx.build) ctx.dynamic()`. Mirrors the synthetic build request the
+     * shell-capture producer creates; also makes `ctx.waitUntil()` inert, as at
+     * build time.
+     */
+    build?: boolean;
+    /**
+     * Router basename for this request (what the RSC handler stores on the
+     * context). Drives redirect() prefixing. Normalized exactly like
+     * createRouter({ basename }) (leading slash forced, trailing stripped, bare
+     * "/" -> undefined) so passing the same value your router takes yields the
+     * same redirect Location. Defaults to undefined (no basename).
+     */
+    basename?: string;
+    /**
+     * Cache store backing `use cache` functions invoked during the test, the
+     * same shape `createRouter({ cache })` resolves. Without it,
+     * registerCachedFunction bypasses (it checks for a store FIRST), so a cached
+     * function runs uncached and its taint/profile guards never fire. Wire one
+     * (e.g. `new MemorySegmentCacheStore()`) to exercise real cache behavior.
+     */
+    cacheStore?: SegmentCacheStore;
+    /**
+     * Cache profiles in the `createRouter({ cacheProfiles })` shape. Required for
+     * a `use cache: "profileName"` function to resolve its profile (an unknown
+     * profile throws), once a `cacheStore` is wired.
+     */
+    cacheProfiles?: Record<string, CacheProfile>;
+    /**
+     * Theme config in the same shape `createRouter({ theme })` takes (resolved
+     * internally). Without it `ctx.theme`/`ctx.setTheme` are inert (undefined),
+     * mirroring an app with no theme configured. Pass one (e.g. `true`, or
+     * `{ themes: [...] }`) to exercise a handler that reads them.
+     */
+    theme?: ThemeConfig | true;
+    /**
+     * Customize the rango state cookie that `invalidateClientCache()` rotates.
+     * The name is ALWAYS seeded (default `rango-state_router_0`) so a call to
+     * `invalidateClientCache()` rotates and emits the `Set-Cookie` exactly as in
+     * production, rather than silently no-opping. Override `prefix`/`routerId` to
+     * match your `createRouter({ stateCookiePrefix, id })` so the test asserts the
+     * same name, or `version` (the build identifier prefixed to the rotated
+     * `{version}:{timestamp}` value, default `"0"`). Assert
+     * `response.headers.getSetCookie()` against the resolved `stateCookieName`
+     * (returned by `runInRequestContext`).
+     */
+    stateCookie?: StateCookieSeed;
+}
+/**
+ * The seeded RequestContext with its `reverse` RELAXED to accept any route NAME
+ * from the `routeMap` you passed, rather than the global `Rango.GeneratedRouteMap`
+ * union — so reversing a test-only route name is not a type error (it works at
+ * runtime; the names come from your `routeMap`). Mirrors runLoader's
+ * `TestLoaderContext.reverse`. Everything else is the real `RequestContext`.
+ */
+export type TestRequestContextObject<TEnv> = Omit<RequestContext<TEnv>, "reverse"> & {
+    reverse: (name: string, params?: Record<string, string>, search?: Record<string, unknown>) => string;
+};
+export interface TestRequestContext<TEnv> {
+    ctx: TestRequestContextObject<TEnv>;
+    request: Request;
+    url: URL;
+    variables: Record<string, unknown>;
+    /**
+     * The resolved rango state cookie name seeded into the context (default
+     * `rango-state_router_0`, or composed from `opts.stateCookie`). The name a
+     * call to `invalidateClientCache()` rotates.
+     */
+    stateCookieName: string;
+}
+/**
+ * Create a real RequestContext for unit-testing loaders/middleware.
+ *
+ * The returned `ctx` must be ENTERED before use — wrap your call in
+ * `runWithRequestContext(ctx, fn)` (re-exported from `@rangojs/router/testing`)
+ * so that cookie/header mutations and `getRequestContext()` resolve. For the
+ * common case prefer {@link runInRequestContext}, which builds AND enters the
+ * context in a single call.
+ */
+export declare function createTestRequestContext<TEnv>(opts?: CreateTestContextOptions<TEnv>): TestRequestContext<TEnv>;
+/**
+ * What a run accumulated on the request context, surfaced as PUBLIC values so a
+ * test never has to cast through the `@internal` `ctx.res` / `ctx.cookies()` to
+ * assert what an action produced.
+ */
+export interface RunInRequestContextResult<T> {
+    /**
+     * The value `fn` returned (awaited), or `undefined` if `fn` threw — in which
+     * case the thrown value is on {@link thrown}. The snapshot below is captured
+     * either way.
+     */
+    result: T | undefined;
+    /**
+     * The value `fn` threw, or `undefined` if it returned normally. Commonly a
+     * `Response` from `throw redirect(...)` / `throw notFound()` — the dominant
+     * cookie+flash case is an action that sets them then throws a redirect — so
+     * this (and the snapshot below) is observable WITHOUT wrapping the action in
+     * your own try/catch. NOTE: the value is captured, NOT re-thrown; assert on it
+     * for a throwing action.
+     */
+    thrown: unknown;
+    /**
+     * A Response carrying the status, headers, and Set-Cookie the run set (via
+     * `cookies().set()`, `ctx.header()`, etc.). Assert Set-Cookie with
+     * `response.headers.getSetCookie()`. When `fn` threw a `Response` (a redirect),
+     * THIS is that Response with the accumulated Set-Cookie/headers merged in
+     * (mirroring how the framework merges them in production), so a redirect's
+     * Location AND the cookies it set are both observable here.
+     */
+    response: Response;
+    /**
+     * The effective cookie view after the run: request cookies merged with
+     * anything the run set or deleted (last-write-wins), as `{ name: value }`.
+     */
+    cookies: Record<string, string>;
+    /**
+     * The response headers the run set (via `ctx.header(...)`, plus a thrown
+     * redirect's `Location`), as a plain `{ name: value }` object — the same view
+     * as `response.headers`, but assertable like `cookies`/`locationState`.
+     * EXCLUDES `set-cookie` (use `cookies`, or `response.headers.getSetCookie()`).
+     * Header names are lowercased (HTTP headers are case-insensitive).
+     */
+    headers: Record<string, string>;
+    /**
+     * Location state the run set via `ctx.setLocationState()` / `redirect({ state })`,
+     * resolved to the flat `{ key: value }` shape the client reads off
+     * `history.state` (empty object when none) — so a post-action flash ("Saved!")
+     * is assertable at the unit layer.
+     */
+    locationState: Record<string, unknown>;
+    /**
+     * The resolved rango state cookie name seeded into the run (default
+     * `rango-state_router_0`, or composed from `opts.stateCookie`). Assert an
+     * action's `invalidateClientCache()` rotation against it without recomputing:
+     * `response.headers.getSetCookie().some((c) => c.startsWith(stateCookieName + "="))`.
+     */
+    stateCookieName: string;
+}
+export declare function snapshotRunEffects<TEnv>(ctx: RequestContext<TEnv>): {
+    cookies: Record<string, string>;
+    locationState: Record<string, unknown>;
+};
+export declare function headersToObject(headers: Headers): Record<string, string>;
+export declare function buildRunResponse<TEnv>(ctx: RequestContext<TEnv>, thrown: unknown): Response;
+export declare function buildRunSnapshot<TEnv>(ctx: RequestContext<TEnv>, thrown: unknown, stateCookieName: string): {
+    thrown: unknown;
+    response: Response;
+    cookies: Record<string, string>;
+    headers: Record<string, string>;
+    locationState: Record<string, unknown>;
+    stateCookieName: string;
+};
+/**
+ * Build a seeded RequestContext (via {@link createTestRequestContext}) and run
+ * `fn` inside it, so code under test that calls `getRequestContext()`,
+ * `cookies()`, or reads/mutates request headers resolves exactly as in
+ * production.
+ *
+ * This is the entry point for the advanced cases the unit wrappers
+ * (`runLoader` / `runMiddleware`) do not model — most notably a server ACTION
+ * that authenticates off the request cookie or sets a session cookie / flash:
+ * an action has no loader context, so `runLoader` is the wrong shape, yet it
+ * still needs a real request context to read the cookie and resolve
+ * `getRequestContext()`.
+ *
+ * Returns `{ result, thrown, response, cookies, headers, locationState }` so the
+ * action's OUTPUT (Set-Cookie, response headers, flash) is assertable without
+ * casting through the `@internal` `ctx.res` / `ctx.cookies()`. `fn` may be async — the context stays
+ * active across its awaits (AsyncLocalStorage), and the snapshot is captured
+ * whether `fn` returns OR throws. The throw path matters: the most common
+ * cookie+flash case is an auth action that sets a cookie + flash then
+ * `throw redirect(...)` on success — the thrown redirect is on `thrown` (NOT
+ * re-thrown) and its Location plus the cookies are on `response`/`cookies`.
+ *
+ * @example
+ * ```ts
+ * const { result, cookies, response, thrown } = await runInRequestContext(
+ *   () => loginAction(input), // sets a session cookie, then `throw redirect("/app")`
+ *   {
+ *     env,
+ *     request: new Request("https://app.test/", {
+ *       headers: { Cookie: "sid=abc" },
+ *     }),
+ *   },
+ * );
+ * expect(cookies.session).toBe("new-token");
+ * expect(headers.location).toBe("/app"); // response headers as a plain object
+ * expect((thrown as Response).headers.get("Location")).toBe("/app");
+ * expect(response.headers.getSetCookie()).toContainEqual(
+ *   expect.stringContaining("session="),
+ * );
+ * ```
+ */
+export declare function runInRequestContext<T, TEnv = unknown>(fn: (ctx: RequestContext<TEnv>) => T | Promise<T>, opts?: CreateTestContextOptions<TEnv>): Promise<RunInRequestContextResult<T>>;

package/dist/types/testing/internal/flight-client-globals.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/testing/internal/seed-vars.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Variable seeding shared by the node/DOM testing tier (internal/context.ts)
+ * AND the react-server Flight tier (flight.ts). Depends only on the
+ * dependency-free `context-var` module and the env-agnostic state-cookie-name
+ * composition (no window/document), so it is safe to import under the
+ * `react-server` condition (unlike internal/context.ts, which pulls
+ * client/browser modules).
+ */
+import { type ContextVar } from "../../context-var.js";
+export interface StateCookieSeed {
+    /**
+     * Cookie-name prefix, sanitized then composed with `routerId` exactly like
+     * `createRouter({ stateCookiePrefix })`. Defaults to `"rango-state"`.
+     */
+    prefix?: string;
+    /**
+     * Router id; the resolved name is `{sanitizedPrefix}_{sanitizedRouterId}`.
+     * Defaults to `"router_0"` (the name a single default router resolves to), so
+     * the default name is `rango-state_router_0`.
+     */
+    routerId?: string;
+    /**
+     * Build version used as the rotated value's prefix (`{version}:{timestamp}`).
+     * Defaults to `"0"` (resolved inside createRequestContext).
+     */
+    version?: string;
+}
+export declare function resolveSeededStateCookieName(seed?: StateCookieSeed): string;
+export type VarsInit = Record<string, unknown> | ReadonlyArray<readonly [ContextVar<unknown> | string, unknown]>;
+export declare function seedVariables(variables: Record<string, unknown>, vars?: VarsInit): Record<string, unknown>;