@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.1

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

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

package/dist/types/testing/render-route.d.ts

@@ -0,0 +1,246 @@
+/**
+ * renderRoute — a React-Testing-Library-style helper for unit-testing CLIENT
+ * components that read @rangojs/router client context (useParams, useReverse,
+ * Outlet, useNavigation, useLoader).
+ *
+ * Peer of React Router's createRoutesStub and Expo Router's renderRouter. It
+ * mounts the router's NavigationProvider plus a synthetic segment tree so that
+ * a component under test sees real router context, without spinning up a
+ * server, a Vite build, or a real Flight round-trip.
+ *
+ * FIDELITY CONTRACT — read before relying on this helper:
+ * This renders the CLIENT tree ONLY. The segment tree is built synthetically
+ * from the `routes` you pass; there is no server render and no Flight
+ * (de)serialization. Consequences:
+ *   - It will NOT catch server/client boundary reference-identity remount bugs
+ *     (a server-serialized component reference differing from the client
+ *     reference). Use renderServerTree / e2e for those.
+ *   - It will NOT catch real Flight serialization errors (non-serializable
+ *     props crossing the RSC boundary), loader execution on the server,
+ *     middleware, or handler ordering. Those are renderServerTree / renderHandler
+ *     / e2e territory.
+ *   - Loader data, location state, and handle output are SEEDED directly into
+ *     client context (see the `loaders` / `locationState` / `handles` options) —
+ *     nothing is executed on the server. This exercises the read path
+ *     (useLoader / useLocationState / useHandle from context), not the run path.
+ *   - navigate() commits synchronously, so it does NOT drive the navigation
+ *     lifecycle: useNavigation().state, useLinkStatus().pending, and
+ *     useAction().state stay "idle". Assert pending/loading/submitting transition
+ *     states with renderServerTree / e2e instead (navigate() warns once if used).
+ * What it DOES cover: client hooks that read NavigationProvider /
+ * OutletContext — useParams, useReverse, useHref, useMount, useNavigation,
+ * useRouter, usePathname, useSearchParams, Outlet nesting, useLoader /
+ * useFetchLoader (seeded data), useLocationState (seeded), and useHandle (seeded).
+ * Basename-mounted apps: pass the `basename` option so useRouter().basename,
+ * <Link> prefixing, and useMount/useHref resolve against the mount prefix
+ * (without it they resolve at the root "/"). For an include("/shop", ...)
+ * subtree, pass the `mount` option so useMount() returns the mounted prefix
+ * (the segment chain is wrapped in a MountContext exactly as in production).
+ */
+import type { ComponentType } from "react";
+import type { RenderResult } from "@testing-library/react";
+import type { NavigationStore } from "../browser/types.js";
+import type { EventController } from "../browser/event-controller.js";
+import type { LoaderDefinition } from "../types.js";
+import type { LocationStateDefinition } from "../browser/react/location-state-shared.js";
+import type { Handle } from "../handle.js";
+import type { ThemeConfig } from "../theme/types.js";
+/**
+ * Seed shape for `options.handle`, matching the handle wire format:
+ * `{ [handleName]: { [segmentId]: pushedValues[] } }` (each segment accumulates
+ * an array of values pushed for that handle).
+ */
+export type HandleDataSeed = Record<string, Record<string, unknown[]>>;
+export interface RenderRouteSpec {
+    /**
+     * The route pattern this node matches, e.g. "/products/:productId". The LAST
+     * spec in the array is treated as the leaf route; earlier specs are layouts
+     * wrapping it. Only the leaf pattern is matched against the `request` URL to
+     * extract params; layout patterns are informational.
+     */
+    path: string;
+    /** The component rendered for this node (the leaf route or a layout body). */
+    Component: ComponentType;
+    /**
+     * Optional layout component. When set on the LEAF spec it wraps the route in
+     * its own layout segment (useful for a route that owns a layout). Prefer
+     * expressing layouts as their own array entries instead.
+     */
+    layout?: ComponentType;
+    /**
+     * Loader ids ($$id) whose seeded data (from `options.loaderData`) should be
+     * attached to THIS node's segment so useLoader/useFetchLoader resolve it from
+     * context. When omitted, every key in `options.loaderData` is attached to the
+     * leaf route segment.
+     */
+    loaderIds?: string[];
+    /** Optional route name (informational; not used for matching). */
+    name?: string;
+}
+/**
+ * Options for renderRoute.
+ */
+export interface RenderRouteOptions {
+    /**
+     * The initial location to render at: a `Request`, or a URL string (absolute or
+     * path). Only the URL is read (this is a client render — headers/method are
+     * ignored); named `request` for parity with the other primitives. Defaults to
+     * the leaf spec's static prefix or "/".
+     */
+    request?: Request | string;
+    /**
+     * Loader data to seed into client context, keyed by loader id ($$id). A
+     * component calling useLoader(SomeLoader) reads `loaderData[SomeLoader.$$id]`.
+     * Seeded values are placed in the route segment's OutletProvider context, so
+     * the read path is exercised without executing any loader.
+     */
+    loaderData?: Record<string, unknown>;
+    /**
+     * Loaders to seed by REFERENCE — the robust way to test a component that calls
+     * `useLoader(loader)`. A real `createLoader()` handle has an empty `$$id` in a
+     * bare test (the id is injected by the Vite plugin at build time), so keying
+     * `loaderData` by `$$id` collides under `""` and `useLoader` resolves nothing.
+     * Passing `[loader, data]` pairs lets renderRoute assign a synthetic stable id
+     * and wire `useLoader` to it. Prefer this over `loaderData` for real handles.
+     *
+     * NOTE: when a real handle has no `$$id`, renderRoute MUTATES it to assign a
+     * synthetic stable id (so repeat renders key consistently). This is a side
+     * effect on your input object; a handle reused across tests keeps that id.
+     *
+     * @example
+     * // useLoader returns an ENVELOPE — destructure `data`, it is not the bare value.
+     * function CartBadge() {
+     *   const { data } = useLoader(CartLoader); // NOT `useLoader(CartLoader).itemCount`
+     *   return <span>{data.itemCount}</span>;
+     * }
+     * renderRoute([{ path: "/cart", Component: CartBadge }], {
+     *   loaders: [[CartLoader, { itemCount: 3, total: 89.97 }]],
+     * });
+     */
+    loaders?: ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>;
+    /**
+     * Explicit params. Merged over (and overriding) params extracted from the
+     * `request` URL. Use this when the URL alone cannot express the params, or to
+     * avoid relying on URL parsing. Supplying params also OPTS OUT of the
+     * request/leaf match check: a `request` whose pathname does not resolve the
+     * leaf is normally rejected under the test runner, but passing params here
+     * tells renderRoute the request is intentionally not the param source.
+     */
+    params?: Record<string, string>;
+    /**
+     * Location-state values to seed by REFERENCE, for components that call
+     * `useLocationState(StateDef)`. Like loaders, a real `createLocationState()`
+     * handle has an empty injected key in a bare test, so pass `[def, value]`
+     * pairs; renderRoute assigns a synthetic key and writes it to `history.state`.
+     *
+     * @example
+     * renderRoute([{ path: "/", Component: FlashBanner }], {
+     *   locationState: [[FlashMessage, { text: "Saved" }]],
+     * });
+     */
+    locationState?: ReadonlyArray<readonly [LocationStateDefinition<any, any>, unknown]>;
+    /**
+     * Handles to seed by REFERENCE, for components that read handle output via
+     * `useHandle(SomeHandle)` (e.g. a client `Breadcrumbs` trail). Each entry is
+     * `[handle, pushedValues[]]` — the values a route's handlers would have pushed;
+     * renderRoute attaches them to the leaf route segment under the handle's id.
+     * Built-in handles (Breadcrumbs/Meta) have stable ids and work directly.
+     *
+     * Handle data is accumulated GLOBALLY on the event controller, not scoped per
+     * segment like loaders — so ANY component in the chain reads the seeded values,
+     * a LAYOUT (e.g. a DetailLayout/ActionToolbar reading a handle) just as much as
+     * the leaf route. Most handle usage is server-side (`ctx.use(...)`) and is
+     * better covered by `renderToFlightString`/e2e; this seeds the client read path
+     * only.
+     *
+     * @example
+     * renderRoute([{ path: "/p", Component: BreadcrumbTrail }], {
+     *   handles: [[Breadcrumbs, [{ label: "Home", href: "/" }, { label: "P", href: "/p" }]]],
+     * });
+     */
+    handles?: ReadonlyArray<readonly [Handle<any, any>, unknown[]]>;
+    /**
+     * Advanced: raw handle data in wire format
+     * `{ [handleId]: { [segmentId]: pushedValues[] } }`. Prefer `handles` (which
+     * computes the segment id for you). Merged with `handles`.
+     */
+    handle?: HandleDataSeed;
+    /**
+     * Route name -> pattern map. Informational for parity with the server test
+     * context; client useReverse takes its map directly as an argument, so this
+     * is not consumed by the client hooks.
+     */
+    routeMap?: Record<string, string>;
+    /**
+     * Router basename (the `createRouter({ basename })` value). Wired into
+     * NavigationProvider so `useRouter().basename`, `<Link>` href prefixing, and
+     * `useMount`/`useHref` resolve against the mounted prefix instead of the root.
+     * Normalized exactly like createRouter (leading slash forced, trailing
+     * stripped, bare "/" -> undefined). Defaults to undefined (root mount).
+     */
+    basename?: string;
+    /**
+     * include() mount prefix, to model an `include("/shop", ...)` subtree so a
+     * component (route OR layout in the chain) calling `useMount()` returns the
+     * mounted prefix instead of "/". Wraps the segment chain in a MountContext
+     * exactly as `renderSegments` does in production (a segment whose `mountPath`
+     * is set is wrapped in a MountContextProvider). Normalized like a path prefix
+     * (leading slash forced, trailing stripped, bare "/" -> root). Defaults to "/".
+     * An explicitly-passed `request` must match the leaf `path` directly (paths are
+     * include-RELATIVE; the mount does NOT rewrite the request) — pass the relative
+     * path, not the mount-prefixed one, or renderRoute throws rather than silently
+     * rendering empty params.
+     *
+     * @example
+     * renderRoute([{ path: "/c/wine", Component: ProductPage }], { mount: "/shop" });
+     * // useMount() inside ProductPage returns "/shop"
+     */
+    mount?: string;
+    /**
+     * Theme config in the `createRouter({ theme })` shape (resolved internally) to
+     * wrap the tree in a ThemeProvider. Defaults to no provider. Note: a component
+     * that calls `useTheme()` REQUIRES a provider — it throws "used outside
+     * ThemeProvider" without one — so pass a config (e.g. `true`) to test such a
+     * component.
+     */
+    theme?: ThemeConfig | true;
+    /**
+     * CSP nonce to seed via NonceContext, so a component calling `useNonce()`
+     * (e.g. an analytics/GTM head-script component) sees this value — mirroring
+     * what the SSR renderer provides per request. Defaults to undefined (the
+     * browser default), matching production client behavior.
+     *
+     * @example
+     * const { getByTestId } = await renderRoute(
+     *   [{ path: "/", Component: NonceProbe }],
+     *   { nonce: "test-nonce" },
+     * );
+     * expect(getByTestId("nonce").textContent).toBe("test-nonce");
+     */
+    nonce?: string;
+}
+/**
+ * Imperative handle returned alongside the RTL result.
+ */
+export interface TestRouterHandle {
+    /**
+     * Navigate to a new URL. Re-resolves the URL against the supplied `routes`,
+     * updates params + location, and re-renders the segment tree. This is a
+     * client-only navigation: no server fetch occurs, so only the components in
+     * `routes` can be reached.
+     */
+    navigate(url: string): Promise<void>;
+    /** The current committed pathname. */
+    pathname(): string;
+    /** The current committed params. */
+    params(): Record<string, string>;
+    /** The underlying navigation store (advanced use). */
+    store: NavigationStore;
+    /** The underlying event controller (advanced use). */
+    eventController: EventController;
+}
+/** Result of renderRoute: RTL's render result plus the router handle. */
+export type RenderRouteResult = RenderResult & {
+    router: TestRouterHandle;
+};
+export declare function renderRoute(routes: RenderRouteSpec[], options?: RenderRouteOptions): Promise<RenderRouteResult>;

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

@@ -0,0 +1,186 @@
+/**
+ * runLoader — unit-test a loader function in isolation.
+ *
+ * Pass the RAW async loader body `(ctx) => ...`, or a registered `createLoader()`
+ * handle (its fn is recovered from the fetchable registry by `$$id`). The raw
+ * body needs no build step; the handle works because `createLoader` assigns a
+ * runtime-fallback `$$id` and registers its fn even without the Vite plugin (when
+ * imported through the server build — the consumer's `@rangojs/router` under the
+ * `rangoTestConfig()` preset). Either way the function is invoked directly with a
+ * constructed LoaderContext.
+ *
+ * The LoaderContext mirrors the canonical shape the router builds at runtime
+ * (see createUseFunction in server/request-context.ts). The loader runs inside
+ * runWithRequestContext so getRequestContext(), cookie reads, and header
+ * mutations resolve exactly as in production.
+ *
+ * Limitations (v1):
+ * - `ctx.rendered()` is not available — it requires the DSL render barrier,
+ *   which only exists inside a full match. Calling it throws.
+ * - `ctx.reverse()` throws unless `routeMap` is provided (it does NOT fall back
+ *   to the global route map — that would leak whichever routes another test
+ *   registered).
+ * - `ctx.use(handle)` follows the production rule: reading a handle before
+ *   `await ctx.rendered()` throws (pass `rendered` to mock the barrier).
+ * - `use cache` functions only cache (and only fire their taint/profile guards)
+ *   when a `cacheStore` is provided — without one, registerCachedFunction
+ *   bypasses (it checks for a store first). Pass `cacheStore`/`cacheProfiles`
+ *   to exercise cached loaders; otherwise such a call runs uncached, like an
+ *   app with no cache configured.
+ * - `formData` is exposed verbatim; no multipart parsing is performed.
+ * - Scoped dot-local reverse (`.sibling`) uses only the supplied `routeMap`;
+ *   the production root-scoping signal (derived from the global registry) is
+ *   not modeled, so a dotted name resolves against `routeMap` as given.
+ */
+import type { LoaderContext, LoaderDefinition } from "../types.js";
+import type { ContextVar } from "../context-var.js";
+import { type Handle } from "../handle.js";
+import type { ThemeConfig } from "../theme/types.js";
+import type { SegmentCacheStore } from "../cache/types.js";
+import type { CacheProfile } from "../cache/profile-registry.js";
+import { type VarsInit, type StateCookieSeed } from "./internal/context.js";
+/**
+ * The loader context surfaced to a `runLoader` body. It mirrors the runtime
+ * LoaderContext but RELAXES the two members that are otherwise bound to the
+ * app's global route/var augmentation, because in a unit test they are driven by
+ * the `routeMap` / `vars` options instead:
+ * - `reverse` accepts any route name (the names come from `routeMap`, not the
+ *   registered route map), and
+ * - `get` accepts any string key or ContextVar (keys come from `vars`).
+ */
+export type TestLoaderContext<TEnv = any> = Omit<LoaderContext<any, TEnv>, "reverse" | "get"> & {
+    reverse: (name: string, params?: Record<string, string>, search?: Record<string, unknown>) => string;
+    get: {
+        <T>(contextVar: ContextVar<T>): T | undefined;
+        <T = unknown>(key: string): T | undefined;
+    };
+};
+/**
+ * A resolver for `ctx.use(OtherLoader)` composition. Receives the dependency
+ * loader definition and returns its data (or a promise of it). When omitted,
+ * `ctx.use` delegates to the real request-context use(), which executes the
+ * dependency's own `fn` if present.
+ */
+export type UseResolver = <T>(loader: LoaderDefinition<T, any>) => Promise<T> | T;
+/**
+ * Options for runLoader.
+ */
+export interface RunLoaderOptions<TEnv = any> {
+    /** Route params surfaced as `ctx.params` and `ctx.routeParams`. */
+    params?: Record<string, string>;
+    /** Search params; merged into the request URL so `ctx.searchParams` reflects them. */
+    search?: Record<string, string>;
+    /**
+     * The TYPED `ctx.search` object a route's search schema would produce. Distinct
+     * from `search` (which sets the raw `ctx.searchParams`): a loader on a typed
+     * search route reads `ctx.search`, which is otherwise `{}` in a test.
+     */
+    searchData?: Record<string, unknown>;
+    /** Router basename surfaced on the context (drives redirect() prefixing). */
+    basename?: string;
+    /**
+     * Theme config in the same shape `createRouter({ theme })` takes (e.g. `true`
+     * or `{ themes: [...] }`). Seeds the request's theme config so nested handler
+     * or cache contexts created from this loader observe it. Loaders themselves do
+     * not expose `ctx.theme`/`ctx.setTheme` (those are handler/middleware-only).
+     */
+    theme?: ThemeConfig | true;
+    /** Environment bindings surfaced as `ctx.env`. */
+    env?: TEnv;
+    /** Override the backing Request (string or Request). Defaults to a localhost GET. */
+    request?: Request | string;
+    /** 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 for scoped `.name` reverse resolution. */
+    routeName?: string;
+    /** HTTP method surfaced as `ctx.method`. Defaults to "GET". */
+    method?: string;
+    /** Request body surfaced as `ctx.body`. */
+    body?: unknown;
+    /** Form data surfaced as `ctx.formData`. */
+    formData?: FormData;
+    /**
+     * Seed the data `ctx.use(OtherLoader)` returns, by loader REFERENCE — the same
+     * tuple form `renderHandler` / `renderRoute` use (`[[OtherLoader, data]]`).
+     * Matched by reference, so a real `createLoader()` handle resolves regardless
+     * of its build-injected `$$id`. For dynamic resolution (compute per dependency)
+     * use `use` instead; `loaders` is checked first.
+     */
+    loaders?: ReadonlyArray<readonly [LoaderDefinition<any, any>, unknown]>;
+    /** Resolver for `ctx.use(OtherLoader)` composition (dynamic; `loaders` wins if both match). */
+    use?: UseResolver;
+    /**
+     * Cache store backing `use cache` functions the loader invokes. Without it,
+     * a cached function bypasses (registerCachedFunction checks for a store
+     * first) and runs uncached — its taint/profile guards never fire. Pass one
+     * (e.g. `new MemorySegmentCacheStore()`) to test a cached loader.
+     */
+    cacheStore?: SegmentCacheStore;
+    /** Cache profiles (the `createRouter({ cacheProfiles })` shape). */
+    cacheProfiles?: Record<string, CacheProfile>;
+    /**
+     * Customize the rango state cookie a loader 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 the request context's response.
+     */
+    stateCookie?: StateCookieSeed;
+    /**
+     * Mock the `ctx.rendered()` render barrier so a loader that does
+     * `await ctx.rendered()` (to read handle data pushed during render) can be
+     * unit-tested. By default `ctx.rendered()` throws, because the real barrier
+     * only exists during a full route match. Pass `true` to resolve it
+     * immediately, or a function to control its timing/side effects.
+     *
+     * This tests the loader's POST-barrier compute logic against the seeded
+     * `handles` below — it does NOT exercise the real push -> accumulate -> barrier
+     * wiring (that stays e2e). Pair with `handles` to feed `ctx.use(SomeHandle)`.
+     */
+    rendered?: boolean | (() => void | Promise<void>);
+    /**
+     * Seed the values `ctx.use(SomeHandle)` returns — the ACCUMULATED handle data a
+     * loader reads after `await ctx.rendered()`. Matched by handle reference, so a
+     * real handle works regardless of its (build-injected) `$$id`.
+     *
+     * @example
+     * await runLoader(livePricesBody, {
+     *   rendered: true,
+     *   handles: [[RenderedProducts, ["widget-a", "widget-b"]]],
+     * });
+     */
+    handles?: ReadonlyArray<readonly [Handle<any, any>, unknown]>;
+}
+/** A raw loader body, or a registered `createLoader()` handle (its fn is recovered). */
+export type RunnableLoader<T> = ((ctx: TestLoaderContext) => Promise<T> | T) | LoaderDefinition<T, any>;
+export declare function runLoader<T>(loader: RunnableLoader<T>, opts?: RunLoaderOptions): Promise<T>;
+export interface RunLoaderResult<T> {
+    /**
+     * The loader's resolved data (the value bare `runLoader` returns), or
+     * `undefined` if it threw (see {@link thrown}). Named `result` for parity with
+     * `runInRequestContext`'s envelope.
+     */
+    result: T | undefined;
+    /**
+     * What the loader threw (commonly a `Response` from `throw redirect(...)` on a
+     * success path) — captured, NOT re-thrown; assert on it. `undefined` if the
+     * loader returned normally.
+     */
+    thrown: unknown;
+    /**
+     * The merged `Response` (status + headers + Set-Cookie). On a thrown redirect,
+     * that redirect's `Location` merged with the accumulated cookies/headers — so a
+     * loader that sets a session cookie then `throw redirect("/")` exposes BOTH.
+     */
+    response: Response;
+    /** Effective cookie view: request cookies + the loader's mutations, last-write-wins. */
+    cookies: Record<string, string>;
+    /** Response headers as `{ name: value }`, EXCLUDING set-cookie (use `cookies`). Lowercased. */
+    headers: Record<string, string>;
+    /** Location state the loader set (`ctx.setLocationState()` / `redirect({ state })`). */
+    locationState: Record<string, unknown>;
+    /** The resolved rango state cookie name seeded for the run (default `rango-state_router_0`). */
+    stateCookieName: string;
+}
+export declare function runLoaderResult<T>(loader: RunnableLoader<T>, opts?: RunLoaderOptions): Promise<RunLoaderResult<T>>;