@rangojs/router 0.5.1 → 0.6.0

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

@@ -1,27 +0,0 @@
-/**
- * @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.backup/testing/generated-routes.d.ts

@@ -1,66 +0,0 @@
-/**
- * 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.backup/testing/index.d.ts

@@ -1,52 +0,0 @@
-/**
- * @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, 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 { 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.backup/testing/internal/context.d.ts

@@ -1,225 +0,0 @@
-/**
- * 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.backup/testing/internal/flight-client-globals.d.ts

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

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

@@ -1,30 +0,0 @@
-/**
- * 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>;

package/dist/types.backup/testing/render-handler.d.ts

@@ -1,160 +0,0 @@
-/**
- * renderHandler — run a REAL route handler and assert what it renders.
- *
- * A Rango route handler is a pure function `(ctx) => RSC` (what you pass to
- * `path("/p/:slug", ProductPage)`), NOT a component. To test one faithfully you
- * must give it the HandlerContext the router builds at runtime, so `ctx.params`,
- * `ctx.use(Loader)`, `ctx.use(Meta)` / `ctx.use(Breadcrumbs)` (handles),
- * `ctx.reverse`, `ctx.get`/`ctx.header`/`cookies()` all work. renderHandler does
- * exactly that, then serializes the handler's returned RSC and deserializes it
- * to an inspectable tree (same serialize/deserialize core as renderServerTree).
- *
- * Loaders are SEEDED (no real loader execution) the same way `runLoader` seeds
- * them — pass `loaders: [[ProductLoader, data]]`. Handle pushes
- * (`ctx.use(Meta)({...})`) are captured on `result.handles`. The handler's
- * cookie/header/flash effects and a thrown/returned redirect are surfaced too
- * (like `runInRequestContext`). If the handler returns/throws a `Response`
- * (a response route / `throw redirect()`), there is no RSC `tree`.
- *
- * Must run under the `react-server` export condition (the rsc Vitest project).
- * Wire `rangoUseClientTransform()` so `"use client"` islands in the handler's RSC
- * auto-register (or pass `clientComponents`).
- */
-import type { ReactNode } from "react";
-import { type Handle } from "../handle.js";
-import type { HandlerContext } from "../types/handler-context.js";
-import type { LoaderDefinition } from "../types.js";
-import { type VarsInit, type StateCookieSeed } from "./internal/seed-vars.js";
-export type { StateCookieSeed } from "./internal/seed-vars.js";
-import type { SegmentCacheStore } from "../cache/types.js";
-import type { CacheProfile } from "../cache/profile-registry.js";
-import type { ThemeConfig } from "../theme/types.js";
-/** A route handler under test: the `(ctx) => RSC | Response` function you pass to `path(...)`. */
-export type TestableHandler<TEnv = any> = (ctx: HandlerContext<any, TEnv>) => ReactNode | Response | Promise<ReactNode | Response>;
-/** Options for {@link renderHandler}. */
-export interface RenderHandlerOptions<TEnv = any> {
-    /** Route params surfaced as `ctx.params`. */
-    params?: Record<string, string>;
-    /** Environment bindings surfaced as `ctx.env`. */
-    env?: TEnv;
-    /** Backing Request (string or Request); defaults to a localhost GET. */
-    request?: Request | string;
-    /** Request headers (e.g. Cookie) the handler reads via `cookies()`. */
-    headers?: HeadersInit;
-    /** Variables a prior middleware set, read via `ctx.get(...)`. Object or tuples. */
-    vars?: VarsInit;
-    /** Matched route name (drives `ctx.routeName` and scoped reverse). */
-    routeName?: string;
-    /** Route name -> pattern map enabling `ctx.reverse()`. */
-    routeMap?: Record<string, string>;
-    /**
-     * Seed `ctx.build` (default false) so a handler that branches on the
-     * build-time pass — including calling `ctx.dynamic()` on a MISS — is
-     * unit-testable. Assert a `ctx.dynamic()` call via `result.dynamic`.
-     */
-    build?: boolean;
-    /**
-     * Seed the data `ctx.use(SomeLoader)` returns — NO real loader runs (same model
-     * as `runLoader`'s `loaders`). Matched by loader reference, so a real
-     * `createLoader()` handle resolves regardless of its build-injected `$$id`.
-     */
-    loaders?: ReadonlyArray<readonly [LoaderDefinition<any, any>, unknown]>;
-    /**
-     * `"use client"` components in the handler's RSC, so they serialize as real
-     * boundaries when `rangoUseClientTransform()` is not wired. Keyed by name; see
-     * renderServerTree's `clientComponents`.
-     */
-    clientComponents?: Record<string, unknown>;
-    /**
-     * Customize the rango state cookie a handler that calls
-     * `invalidateClientCache()` rotates. The name is ALWAYS seeded (default
-     * `rango-state_router_0`) so the rotation `Set-Cookie` is emitted like
-     * production rather than no-opping; override `prefix`/`routerId` to match your
-     * `createRouter({ stateCookiePrefix, id })`, or `version` (the build
-     * identifier prefixed to the rotated `{version}:{timestamp}` value, default
-     * `"0"`). Assert via `result.response.headers.getSetCookie()` against
-     * `result.stateCookieName`.
-     */
-    stateCookie?: StateCookieSeed;
-    /**
-     * Segment cache store backing a `"use cache"` function the handler invokes
-     * (e.g. `new MemorySegmentCacheStore()`). Without it, `registerCachedFunction`
-     * takes the uncached bypass and the cached path is NOT exercised (the runtime
-     * emits a one-time warning under the test runner). Pair with `cacheProfiles`
-     * so the profile the directive names resolves.
-     */
-    cacheStore?: SegmentCacheStore;
-    /**
-     * Cache profiles in the `createRouter({ cacheProfiles })` shape, required for
-     * `"use cache: profileName"` resolution once a `cacheStore` is wired.
-     */
-    cacheProfiles?: Record<string, CacheProfile>;
-    /**
-     * Render as if inside a server action's revalidation render (production sets
-     * this in revalidateAfterAction). A stale `"use cache"` entry whose profile
-     * opts into `foregroundOnAction` then re-executes in the FOREGROUND (fresh
-     * result in this render) instead of being served stale + revalidated in the
-     * background. Without it, a stale entry keeps SWR. Pair with `cacheStore` +
-     * `cacheProfiles` to exercise the `foregroundOnAction` opt-in.
-     */
-    inActionRevalidation?: boolean;
-    /**
-     * Theme config in the same shape `createRouter({ theme })` takes (e.g. `true`
-     * or `{ themes: [...] }`). Without it `ctx.theme`/`ctx.setTheme` are inert,
-     * mirroring an app with no theme configured. Pass one to exercise a handler
-     * that reads `ctx.theme` or writes the theme cookie via `ctx.setTheme(...)`.
-     */
-    theme?: ThemeConfig | true;
-}
-/** Result of {@link renderHandler}. */
-export interface RenderHandlerResult {
-    /**
-     * The deserialized RSC the handler returned, as an inspectable React element
-     * tree — `undefined` when the handler returned or threw a `Response`. Use
-     * `findClientBoundaries` (from testing/flight) to locate client islands.
-     */
-    tree: unknown;
-    /** The raw Flight wire string; `undefined` when the handler produced a `Response`. */
-    flight: string | undefined;
-    /** The value the handler THREW (a `redirect()`/`notFound()` Response), captured not re-thrown. */
-    thrown: unknown;
-    /** The merged Response (status + headers + Set-Cookie); a thrown/returned redirect merged with accumulated effects. */
-    response: Response;
-    /** Effective cookie view after the handler ran, as `{ name: value }`. */
-    cookies: Record<string, string>;
-    /** Response headers as `{ name: value }` (excludes set-cookie; includes a redirect Location). */
-    headers: Record<string, string>;
-    /**
-     * The resolved rango state cookie name this run seeded (default
-     * `rango-state_router_0`, or composed from `opts.stateCookie`). Assert the
-     * `invalidateClientCache()` rotation against it without recomputing:
-     * `response.headers.getSetCookie().some((c) => c.startsWith(stateCookieName + "="))`.
-     */
-    stateCookieName: string;
-    /** Location state the handler set (`ctx.setLocationState`/`redirect({ state })`), as `{ key: value }`. */
-    locationState: Record<string, unknown>;
-    /** What the handler pushed via `ctx.use(Handle)(...)` (e.g. Meta, Breadcrumbs), keyed by handle. */
-    handles: Map<Handle<any, any>, unknown[]>;
-    /**
-     * Whether the handler called `ctx.dynamic()` (the PPR shell opt-out). The
-     * public way to assert the opt-out without reading the `@internal`
-     * `ctx._dynamic`.
-     */
-    dynamic: boolean;
-}
-/**
- * Run a route handler with a seeded HandlerContext and return its rendered RSC
- * (deserialized tree) plus the effects it produced. See the module header.
- *
- * @example
- * ```ts
- * // ProductPage is the real handler: (ctx) => <main>{ctx.params.slug}...</main>
- * const { tree, handles } = await renderHandler(ProductPage, {
- *   params: { slug: "wine" },
- *   loaders: [[ProductLoader, { name: "Wine", price: 9 }]],
- *   vars: [[Tenant, tenant]],
- *   routeMap: { product: "/p/:slug" },
- * });
- * ```
- */
-export declare function renderHandler<TEnv = any>(handler: TestableHandler<TEnv>, opts?: RenderHandlerOptions<TEnv>): Promise<RenderHandlerResult>;