@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.0

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

@@ -0,0 +1,233 @@
+import React from "react";
+import type { ErrorPhase } from "../types.js";
+import type { HeadScriptsOption } from "../vite/plugin-types.js";
+export { installClientReferencePreinit } from "./preinit-client-references.js";
+/**
+ * Options for injectRSCPayload
+ */
+export interface InjectRSCPayloadOptions {
+    /**
+     * Nonce for Content Security Policy (CSP)
+     */
+    nonce?: string;
+}
+/**
+ * Options for renderToReadableStream from react-dom/server
+ */
+interface RenderToReadableStreamOptions {
+    bootstrapScriptContent?: string;
+    bootstrapModules?: string[];
+    nonce?: string;
+    formState?: unknown;
+}
+/**
+ * ReadableStream with the allReady promise added by react-dom/server.edge.
+ */
+interface ReactDOMReadableStream extends ReadableStream<Uint8Array> {
+    allReady: Promise<void>;
+}
+/**
+ * Options for prerender from react-dom/static.edge
+ */
+interface PrerenderOptions {
+    signal?: AbortSignal;
+    bootstrapScriptContent?: string;
+    bootstrapModules?: string[];
+    onError?: (error: unknown) => void;
+}
+/**
+ * Result of prerender from react-dom/static.edge. `postponed` is React's
+ * opaque resume state — non-null when the render was aborted with pending
+ * holes, null when the shell completed with nothing left to stream.
+ */
+interface PrerenderResult {
+    prelude: ReadableStream<Uint8Array>;
+    postponed: unknown;
+}
+/**
+ * prerender from react-dom/static.edge
+ */
+type PrerenderFn = (element: React.ReactNode, options?: PrerenderOptions) => Promise<PrerenderResult>;
+/**
+ * Options for resume from react-dom/server.edge
+ */
+interface ResumeOptions {
+    onError?: (error: unknown) => void;
+    nonce?: string;
+}
+/**
+ * resume from react-dom/server.edge — continues a prerendered render, emitting
+ * only the postponed holes.
+ */
+type ResumeFn = (element: React.ReactNode, postponedState: unknown, options?: ResumeOptions) => Promise<ReactDOMReadableStream>;
+/**
+ * Options for the renderHTML function
+ */
+export interface SSRRenderOptions {
+    /**
+     * Form state for useActionState progressive enhancement.
+     * This is the result of decodeFormState() and should be passed to
+     * react-dom's renderToReadableStream to enable useActionState to
+     * receive the action result during SSR.
+     */
+    formState?: unknown;
+    /**
+     * Nonce for Content Security Policy (CSP)
+     */
+    nonce?: string;
+    /**
+     * SSR stream mode.
+     *
+     * - `"stream"` (default) — start flushing HTML immediately.
+     * - `"allReady"` — await `stream.allReady` before returning.
+     */
+    streamMode?: import("../router/router-options.js").SSRStreamMode;
+}
+/**
+ * SSR dependencies from external packages
+ */
+export interface SSRDependencies<TEnv = unknown> {
+    /**
+     * createFromReadableStream from @rangojs/router/internal/deps/ssr
+     */
+    createFromReadableStream: <T>(stream: ReadableStream<Uint8Array>) => Promise<T>;
+    /**
+     * renderToReadableStream from react-dom/server.edge
+     */
+    renderToReadableStream: (element: React.ReactNode, options?: RenderToReadableStreamOptions) => Promise<ReactDOMReadableStream>;
+    /**
+     * injectRSCPayload from @rangojs/router/internal/deps/html-stream-server
+     */
+    injectRSCPayload: (rscStream: ReadableStream<Uint8Array>, options?: InjectRSCPayloadOptions) => TransformStream<Uint8Array, Uint8Array>;
+    /**
+     * Function to load bootstrap script content
+     * Typically: () => import.meta.viteRsc.loadBootstrapScriptContent("index")
+     */
+    loadBootstrapScriptContent: () => Promise<string>;
+    /**
+     * Document script strategy; the generated virtual SSR entry threads the
+     * `rango({ headScripts })` plugin option here (canonical docs on
+     * `RangoBaseOptions.headScripts` in vite/plugin-types.ts). The
+     * bootstrapModules conversion runs ONLY on an explicit `"preinit"`:
+     * undefined keeps the inline bootstrap verbatim, so a custom SSR entry that
+     * never installed the preinit hook cannot drift into the half-converted
+     * state on upgrade (the generated entry always passes an explicit value).
+     */
+    headScripts?: HeadScriptsOption;
+    /**
+     * prerender from react-dom/static.edge. Optional; required only by
+     * {@link createShellCaptureHandler} for PPR shell capture.
+     */
+    prerender?: PrerenderFn;
+    /**
+     * resume from react-dom/server.edge. Optional; required only by
+     * {@link createShellResumeHandler} for resuming a postponed shell.
+     */
+    resume?: ResumeFn;
+    /**
+     * Optional callback invoked when an error occurs during SSR rendering.
+     *
+     * This callback is for notification/logging purposes.
+     *
+     * @example
+     * ```typescript
+     * export const renderHTML = createSSRHandler({
+     *   // ... other deps
+     *   onError: (error, context) => {
+     *     console.error('[SSR] Rendering error:', error);
+     *     Sentry.captureException(error);
+     *   },
+     * });
+     * ```
+     */
+    onError?: (error: Error, context: {
+        phase: ErrorPhase;
+    }) => void;
+}
+/**
+ * True when a debugger is attached outside a production build: a breakpoint
+ * pauses script execution but not wall-clock, so the capture deadline would
+ * expire mid-inspection and push the key into refusal/backoff while debugging.
+ * Next.js precedent (packages/next/src/export/worker.ts): its static-page
+ * timeout race is disabled when NODE_OPTIONS contains --inspect. The gate is
+ * the bare `process.env.NODE_ENV !== "production"` token — the build define
+ * folds exactly that token to a literal (same dev signal as shell-capture.ts's
+ * isDevMode), and it covers dev servers that never set NODE_ENV, the common
+ * debug case. A production worker launched with --inspect in NODE_OPTIONS
+ * keeps the capture's safety bound unconditionally. Every probe is guarded:
+ * `process` reads are optional-chained and the node:inspector import is
+ * try/caught, so non-Node runtimes (workerd) resolve to false instead of
+ * breaking.
+ */
+export declare function isDebuggerAttached(): Promise<boolean>;
+/**
+ * Options for the captureShellHTML function returned by
+ * {@link createShellCaptureHandler}.
+ */
+interface ShellCaptureOptions {
+    /** Caller-provided promise that resolves once the cached content settled. */
+    quiesce: Promise<void>;
+    /** Upper bound on how long to wait for `quiesce`. Default SHELL_CAPTURE_MAX_WAIT_MS. */
+    maxWaitMs?: number;
+}
+/**
+ * Result of a successful shell capture. `prelude` is the raw prelude bytes;
+ * `postponed` is React's resume state serialized to JSON, or null when the
+ * shell completed with no holes (the DATA variant).
+ */
+interface ShellCaptureResult {
+    prelude: Uint8Array;
+    postponed: string | null;
+}
+/**
+ * Options for the resumeShellHTML function returned by
+ * {@link createShellResumeHandler}.
+ */
+interface ShellResumeOptions {
+    /** JSON from capture; null selects the DATA variant (no fizz). */
+    postponed: string | null;
+    /** Nonce for CSP. */
+    nonce?: string;
+}
+/**
+ * Create an SSR handler that converts RSC streams to HTML.
+ *
+ * @example
+ * ```tsx
+ * import { createSSRHandler } from "@rangojs/router/ssr";
+ * import { createFromReadableStream } from "@rangojs/router/internal/deps/ssr";
+ * import { renderToReadableStream } from "react-dom/server.edge";
+ * import { injectRSCPayload } from "@rangojs/router/internal/deps/html-stream-server";
+ *
+ * export const renderHTML = createSSRHandler({
+ *   createFromReadableStream,
+ *   renderToReadableStream,
+ *   injectRSCPayload,
+ *   loadBootstrapScriptContent: () =>
+ *     import.meta.viteRsc.loadBootstrapScriptContent("index"),
+ * });
+ * ```
+ */
+export declare function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>): (rscStream: ReadableStream<Uint8Array>, options?: SSRRenderOptions) => Promise<ReadableStream<Uint8Array>>;
+/**
+ * Create the PPR shell capture handler.
+ *
+ * captureShellHTML prerenders the shell over the (cached, loader-masked) Flight
+ * stream, aborts once the shell settles, and returns the prelude bytes plus the
+ * postponed resume state for storage. The stored pair is later served by
+ * {@link createShellResumeHandler}. See docs/design/ppr-shell-resume.md.
+ *
+ * Throws at creation if `deps.prerender` is missing — capture cannot run
+ * without react-dom/static.edge's prerender.
+ */
+export declare function createShellCaptureHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>): (rscStream: ReadableStream<Uint8Array>, opts: ShellCaptureOptions) => Promise<ShellCaptureResult | null>;
+/**
+ * Create the PPR shell resume handler.
+ *
+ * resumeShellHTML produces the per-request live portion of the document: for a
+ * postponed shell it resumes fizz over a fresh SsrRoot to emit only the holes;
+ * for the DATA variant it emits only the fresh Flight payload scripts. The
+ * caller (shell-cache middleware) prepends the stored prelude bytes to form the
+ * composite response. See docs/design/ppr-shell-resume.md.
+ */
+export declare function createShellResumeHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>): (rscStream: ReadableStream<Uint8Array>, opts: ShellResumeOptions) => Promise<ReadableStream<Uint8Array>>;

package/dist/types/ssr/inject-rsc-eager.d.ts

@@ -0,0 +1,3 @@
+export declare function injectRSCPayloadEager(rscStream: ReadableStream<Uint8Array>, options?: {
+    nonce?: string;
+}): TransformStream<Uint8Array, Uint8Array>;

package/dist/types/ssr/preinit-client-references.d.ts

@@ -0,0 +1,71 @@
+/**
+ * JS/CSS asset deps plugin-rsc resolves for a client reference. Structural
+ * mirror of @vitejs/plugin-rsc's ResolvedAssetDeps — deliberately not imported:
+ * @rangojs/router/ssr never imports plugin-rsc directly; every plugin binding
+ * is injected by the virtual SSR entry (see SSRDependencies).
+ */
+export interface ClientReferenceDeps {
+    js: string[];
+    css: string[];
+}
+/**
+ * Callback shape of @vitejs/plugin-rsc/ssr's setOnClientReference. Fired
+ * (synchronously, inside the Fizz render) whenever a client reference module
+ * is accessed during SSR — the same moment plugin-rsc issues its own
+ * ReactDOM.preloadModule calls for the reference's chunks.
+ */
+export type OnClientReference = (reference: {
+    id: string;
+    deps: ClientReferenceDeps;
+}) => void;
+/** setOnClientReference from @vitejs/plugin-rsc/ssr (injected). */
+export type SetOnClientReference = (callback: OnClientReference | undefined) => void;
+/**
+ * Run a Fizz render (renderToReadableStream / prerender / resume) with the
+ * request's nonce visible to the client-reference preinit hook. Nonce-less
+ * requests (the common non-CSP configuration) skip the ALS frame entirely —
+ * getStore() on an unentered storage already returns undefined, so the hook
+ * reads the same value either way.
+ */
+export declare function runWithPreinitNonce<T>(nonce: string | undefined, fn: () => T): T;
+/**
+ * Upgrade plugin-rsc's client-reference modulepreload hints to executing
+ * scripts: for every JS chunk a client reference needs, emit
+ * `<script type="module" src async>` hoisted into the document head instead of
+ * only `<link rel="modulepreload">`.
+ *
+ * Why: modulepreload fetches + compiles but never executes; the chunks then
+ * execute only when the entry's hydration import walks the graph — after the
+ * whole document has streamed. preinitModule starts execution as soon as each
+ * chunk arrives, overlapping it with body streaming (the pattern Next.js uses
+ * via ReactDOM.preinit for all non-bootstrap chunks). Under PPR the preinits
+ * run during shell capture, so the executing tags live in the stored prelude
+ * and chunk execution starts on the first flushed bytes.
+ *
+ * No duplicate tags: plugin-rsc's preloadModule fires first in the same
+ * synchronous block; Fizz's preinitModuleScript then clears the queued preload
+ * chunks for that URL and adopts its credentials (ReactFizzConfigDOM,
+ * renderState.preloads.moduleScripts). Capture→resume double-emission is
+ * prevented the same way: the `moduleScriptResources[src] = null` markers
+ * serialize inside the postponed state, so the resume pass preinits only
+ * references the shell never saw.
+ *
+ * crossOrigin "" matches plugin-rsc's preloadModule creds so the upgrade path
+ * reuses the same resource instead of forking on credential mismatch.
+ *
+ * Known trades (deliberate, measured neutral-to-positive on the e2e apps —
+ * PR #694 has the Lighthouse/hydration numbers):
+ * - Fetch priority: an executing async module script fetches at Chromium's
+ *   async-script priority, below a bare modulepreload hint; preinitModule
+ *   forwards no fetchPriority (react-dom's public API drops it — only
+ *   `preinit` forwards it). Execution-overlap is bought with hint priority,
+ *   the same trade Next.js ships via ReactDOM.preinit.
+ * - Build only: plugin-rsc's dev load path reports `js: []` per reference, so
+ *   dev documents have no head chunk scripts — a client module whose module
+ *   scope assumes body-parsed DOM can break in production only. The
+ *   `rango({ headScripts: "preload" })` escape hatch restores hint-only.
+ * - plugin-rsc's setOnClientReference is a single-slot, last-write-wins
+ *   setter: another registrant in the SSR environment silently replaces this
+ *   hook (or is replaced by it). No composition API exists upstream yet.
+ */
+export declare function installClientReferencePreinit(setOnClientReference: SetOnClientReference): void;

package/dist/types/ssr/ssr-root.d.ts

@@ -0,0 +1,69 @@
+import React from "react";
+import type { HandleData } from "../browser/types.js";
+import type { ResolvedSegment } from "../types.js";
+import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
+/**
+ * createFromReadableStream from @rangojs/router/internal/deps/ssr.
+ * Deserializes the Flight branch used to build the SSR VDOM.
+ */
+export type CreateFromReadableStream = <T>(stream: ReadableStream<Uint8Array>) => Promise<T>;
+/**
+ * RSC payload type (minimal interface for SSR)
+ */
+export interface RscPayload {
+    metadata?: {
+        segments?: ResolvedSegment[];
+        rootLayout?: React.ComponentType<{
+            children: React.ReactNode;
+        }>;
+        handles?: AsyncGenerator<HandleData, void, unknown>;
+        matched?: string[];
+        pathname?: string;
+        params?: Record<string, string>;
+        basename?: string;
+        themeConfig?: ResolvedThemeConfig | null;
+        initialTheme?: Theme;
+        version?: string;
+    };
+}
+/**
+ * Options for {@link createSsrRootComponent}.
+ */
+export interface SsrRootOptions {
+    /** createFromReadableStream for the SSR branch of the Flight stream. */
+    createFromReadableStream: CreateFromReadableStream;
+    /** The Flight stream branch to deserialize into the SSR VDOM. */
+    rscStream: ReadableStream<Uint8Array>;
+    /** Nonce for CSP; propagated to NonceContext. */
+    nonce?: string;
+    /**
+     * Fires once when the Flight payload root settles (resolve OR reject) — the
+     * signal that every client-module load the payload references completed and
+     * fizz can start emitting the tree. The capture pass gates its abort on
+     * this: a fully REPLAYED (prerendered) route's Flight stream goes
+     * byte-quiet in ~1-3ms, but fizz cannot render even <html> until the
+     * module loads finish (real module-runner I/O in dev; 100ms+ on a cold
+     * graph), so an abort gated on Flight quiet alone fires first and freezes
+     * a zero-byte prelude. Masked-loader holes do NOT block this signal —
+     * they postpone below the root.
+     */
+    onPayloadSettled?: () => void;
+}
+/**
+ * Build the closure component that deserializes the Flight payload, consumes
+ * handles to completion, builds the segment tree, and wraps it in the
+ * NavigationStore / Nonce / Theme providers.
+ *
+ * The full-fizz path (renderHTML), the shell prerender pass (capture), and the
+ * shell resume pass all render this identical tree. `resume` requires the tree
+ * above the postponed holes to match the prerendered tree; rendering the same
+ * builder over the same replayed segments is what makes that hold. A fresh
+ * component instance per pass is fine — replay matches structure, not function
+ * identity.
+ *
+ * The memo slots (payload/handles/context/root) are closure-scoped to the
+ * returned instance, so each render pass memoizes independently. renderSegments
+ * is async: React.use() on a fresh promise would suspend and replay SsrRoot,
+ * re-running the whole segment-tree build unless the promise is memoized.
+ */
+export declare function createSsrRootComponent(opts: SsrRootOptions): React.FC;

package/dist/types/static-handler.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Static handler definition for build-time rendering of individual segments.
+ *
+ * Static wraps a handler so that in production the segment is
+ * rendered once at build time. The handler is then replaced with a static
+ * asset import -- no runtime store lookup needed.
+ *
+ * In dev mode, Static behaves as a normal handler: the wrapped
+ * function runs on every request, identical to a regular layout/path handler.
+ *
+ * The $$id is auto-generated by the Vite exposeInternalIds plugin based on
+ * file path and export name. No manual naming required.
+ *
+ * Key difference from Prerender:
+ *   - Prerender: route-scoped, produces URLs via getParams, renders subtree per-params
+ *   - Static: segment-scoped, renders once, no URLs, no params
+ *
+ * Works on: layout(), parallel(), and path().
+ *
+ * @example
+ * ```ts
+ * export const DocsNav = Static((ctx) => <Nav docs={readDocsSync()} />);
+ * export const DocShell = Static((ctx) => <Shell />);
+ *
+ * urls(({ path, layout }) => [
+ *   layout(DocsNav, () => [
+ *     path("/getting-started", DocShell, { name: "doc.gs" }),
+ *     path("/:slug", Prerender(getParams, DocPageHandler)),
+ *   ]),
+ * ]);
+ * ```
+ */
+import type { ReactNode } from "react";
+import type { Handler } from "./types.js";
+import type { StaticBuildContext } from "./prerender.js";
+import type { UseItems, HandlerUseItem } from "./route-types.js";
+export interface StaticHandlerOptions {
+    /**
+     * Keep handler in server bundle for live fallback (default: false).
+     * false: handler replaced with stub, source-only APIs excluded from bundle.
+     * true: handler stays in bundle, renders live at request time.
+     */
+    passthrough?: boolean;
+}
+export interface StaticHandlerDefinition<TParams extends Record<string, any> = any> {
+    readonly __brand: "staticHandler";
+    /** Auto-generated unique ID (injected by Vite plugin). */
+    $$id: string;
+    /** In dev mode, the actual handler function that layout/path/parallel can call. */
+    handler: Handler<TParams>;
+    /** Static handler options (passthrough support). */
+    options?: StaticHandlerOptions;
+    /** Composable default DSL items merged when the handler is mounted. */
+    use?: () => UseItems<HandlerUseItem>;
+}
+export declare function Static<TParams extends Record<string, any> = {}>(handler: (ctx: StaticBuildContext) => ReactNode | Promise<ReactNode>, options?: StaticHandlerOptions, __injectedId?: string): StaticHandlerDefinition<TParams>;
+export declare function isStaticHandler(value: unknown): value is StaticHandlerDefinition;

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

@@ -0,0 +1,63 @@
+/**
+ * Cache-status testing primitives for @rangojs/router consumers.
+ *
+ * Two complementary paths, both DEVELOPMENT/TEST ONLY:
+ *
+ * 1. Header path — `parseCacheHeader` / `assertCacheStatus` read the
+ *    `X-Rango-Cache` response header. The header is emitted only when the
+ *    router's debug cache signal gate is on (the `debugCacheSignal` option or
+ *    `RANGO_TEST_SIGNALS=1`). With the gate off there is no header and these
+ *    helpers throw a clear "header missing" error.
+ *
+ * 2. Telemetry path — `createCacheSink` returns a `{ sink, events }` pair the
+ *    consumer wires via `createRouter({ telemetry: sink })`. This has ZERO
+ *    production surface: no header, just structured `cache.decision` events
+ *    (which carry the same coarse `segments` cache signal). Assert with
+ *    `assertCacheDecision(events, routeKey, expected)` (the one-call counterpart
+ *    of `assertCacheStatus`) or filter raw via `filterCacheDecisions`.
+ *
+ * Both paths report the SAME coarse route-level signal — pick by TRANSPORT, not
+ * by meaning: the header is the only signal a black-box Playwright `Response`
+ * carries (needs the debug gate ON); the sink is the only zero-production-surface
+ * option and the only one exposing per-segment `shouldRevalidate`.
+ *
+ * v1 cache status is COARSE (route-level): the router reports a single entry
+ * keyed by the route key (the route NAME), not per individual segment.
+ *
+ * Import path: from a Vitest unit/integration test use `@rangojs/router/testing`;
+ * from a Playwright e2e use `@rangojs/router/testing/e2e` (the barrel pulls a
+ * build-only virtual that does not resolve in a plain Playwright runner).
+ */
+import type { CacheDecisionEvent, CacheSegmentStatus, TelemetryEvent, TelemetrySink } from "../router/telemetry.js";
+/** Expected cache status passed to assertCacheStatus. */
+export type ExpectedCacheStatus = CacheSegmentStatus;
+/** A target carrying response headers (a Response or a `{ headers }` object). */
+export type CacheStatusTarget = Response | {
+    headers: Headers;
+};
+export declare function parseCacheHeader(headerValue: string | null | undefined): Record<string, string>;
+export declare function assertCacheStatus(target: CacheStatusTarget, segment: string, expected: ExpectedCacheStatus): void;
+/**
+ * A telemetry sink paired with the array it records events into.
+ */
+export interface CacheSink {
+    /** Wire into `createRouter({ telemetry: sink })`. */
+    sink: TelemetrySink;
+    /** All telemetry events captured so far, in emit order. */
+    events: TelemetryEvent[];
+}
+export declare function createCacheSink(): CacheSink;
+export declare function filterCacheDecisions(events: readonly TelemetryEvent[]): CacheDecisionEvent[];
+/**
+ * Telemetry-path counterpart of {@link assertCacheStatus}: assert a captured
+ * `cache.decision` event reported `expected` for the segment keyed by `routeKey`
+ * (the route NAME, the same coarse key the header path uses). Throws an
+ * actionable error when no matching segment was captured, or on a mismatch.
+ *
+ * Pairs with {@link createCacheSink}: wire `createRouter({ telemetry: sink })`,
+ * drive an RSC request, then assert against the recorded `events`. This is the
+ * zero-production-surface path (no header to enable). NOTE: `events` accumulates
+ * across requests, so the FIRST matching segment wins — slice or recreate the
+ * sink between requests for the same `routeKey`.
+ */
+export declare function assertCacheDecision(events: readonly TelemetryEvent[], routeKey: string, expected: ExpectedCacheStatus): void;

package/dist/types/testing/collect-handle.d.ts

@@ -0,0 +1,20 @@
+/**
+ * collectHandle — unit-test a handle's `collect`/accumulator function directly.
+ *
+ * A handle's collect function (the `createHandle(collect)` argument that maps the
+ * per-segment pushed values into the accumulated result) is otherwise not
+ * directly reachable: createHandle keeps it in a private registry keyed by the
+ * handle's `$$id` and returns only `{ __brand, $$id }`. This primitive runs that
+ * REAL registered collect on per-segment values you provide and returns the
+ * accumulated result — so the mapper/accumulator is unit-testable without a full
+ * route match.
+ *
+ * It relies on createHandle registering the collect even in a bare test (it
+ * assigns a runtime fallback id when the Vite plugin did not inject one). If a
+ * handle's module was never imported (so createHandle never ran), the collect is
+ * unregistered and this falls back to the default identity collect — with a
+ * warning, since a CUSTOM collect that failed to register silently returns the
+ * wrong shape.
+ */
+import { type Handle } from "../handle.js";
+export declare function collectHandle<TData, TAccumulated>(handle: Handle<TData, TAccumulated>, segments: ReadonlyArray<ReadonlyArray<TData>>): TAccumulated;

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

@@ -0,0 +1,127 @@
+/**
+ * dispatch — in-process request -> Response for unit/integration tests,
+ * WITHOUT the Flight RSC runtime.
+ *
+ * dispatch runs the router's real matching and middleware execution so that
+ * redirects, 404s, response routes (path.json / path.text / path.html / ...),
+ * and middleware short-circuits behave exactly as in production. It deliberately
+ * does NOT render React Server Components: there is no Flight stream, no SSR,
+ * and no DOM. Hit an RSC (component) route and dispatch throws a clear error
+ * directing you to renderToFlightString/renderServerTree/renderHandler or an e2e test.
+ *
+ * What dispatch DOES support:
+ * - Trailing-slash and other findMatch() redirects   -> 308 with Location
+ * - Unmatched paths                                  -> 404 Response
+ *   Both the 308 and the 404 are produced INSIDE the global middleware chain
+ *   (mirroring production, where coreHandler runs wrapped by executeMiddleware),
+ *   so a global auth middleware can 401/redirect them and middleware-set
+ *   cookies/headers merge onto the 308/404 the way createResponseWithMergedHeaders
+ *   merges them in production.
+ * - Response routes (non-RSC)                         -> serialized Response
+ *   - json:           JSON.stringify(result) (bare value) with application/json
+ *   - text/html/xml/md: String(result) with the mapped MIME type
+ *   - handler returning or throwing a Response:         re-wrapped like
+ *     handleResponseRoute (stub headers/cookies merged, Set-Cookie preserved,
+ *     WebSocket upgrade passed through without reconstruction)
+ *   - handler throwing a non-Response error:            typed 500 / RouterError
+ *     status, matching handleResponseRoute (RFC 9457 problem+json body with
+ *     application/problem+json for json routes, text/plain message otherwise)
+ *   - content-negotiated route:                         Vary: Accept appended
+ *   - cached response route (cache({...})):             getResponse/putResponse
+ *     hit/SWR/tag write, resolved from the matched entry tree exactly as
+ *     handleResponseRoute does. The write is scheduled via ctx.waitUntil
+ *     (a microtask without an executionContext), so a HIT-asserting test must
+ *     flush microtasks between the seeding dispatch and the asserting one.
+ * - Global middleware (router.use(...)) AND route-level middleware, with full
+ *   next()/short-circuit/throw-Response/header+cookie-merge fidelity.
+ * - Partial (client-navigation) requests to a RESPONSE route (?_rsc_partial):
+ *   global middleware runs first (so an auth gate can still 401/redirect),
+ *   then — if it passes through — an X-RSC-Reload is returned. Route-level
+ *   middleware is skipped on a partial, exactly as production skips it.
+ * - A middleware redirect (3xx + Location) on a partial/action request
+ *   (?_rsc_partial / ?_rsc_action): converted to a 204 + X-RSC-Redirect via the
+ *   real interceptRedirectForPartial, so fetch() does not auto-follow the 3xx —
+ *   identical to production's no-location-state path.
+ * - The open-redirect guard (rsc/redirect-guard.ts) on full (browser-followed)
+ *   redirects: a cross-origin Location is rewritten to the basename root unless
+ *   redirect(url, { external: true }) opted out, mirroring production's single
+ *   handler chokepoint. Soft partial/action redirects are 204 and pass through.
+ * - createRouter({ onError }) for CACHE / background-error degradation. dispatch
+ *   wires the request context's _reportBackgroundError to the router's onError the
+ *   same way the production RSC handler does, so a cache-read/cache-write/
+ *   stale-revalidation failure on a cached response route (a throwing route
+ *   cache({ key })/cache({ tags }), or a custom store whose keyGenerator/
+ *   getResponse/putResponse throws) fires onError with phase "cache" and
+ *   metadata.category, while the request still degrades-to-miss exactly as before.
+ *   (A thrown non-Response route HANDLER error is the one onError path NOT covered —
+ *   see "DOES NOT support" below.)
+ * - createRouter({ telemetry }) match-transaction lifecycle: request.start opens
+ *   the transaction before the global middleware chain, request.end closes it
+ *   after finalizeResponse (segmentCount 0 / cacheHit false — dispatch renders no
+ *   RSC segments and holds no match-cache state), and a thrown non-Response error
+ *   emits request.error with phase "routing". All three carry the same requestId
+ *   (getRequestId). Emission is gated entirely on a configured sink; with none,
+ *   dispatch does zero new work and stays byte-identical for existing callers.
+ *   Lets a consumer unit-test their sink wiring in-process instead of only at e2e.
+ * - Response-route `renderStartMs` timeouts and `onTimeout`: dispatch races the
+ *   same terminal response work, reports the timeout through onError/telemetry,
+ *   and invokes the configured callback. `context.render` is absent because this
+ *   primitive deliberately does not run the Flight/HTML render driver.
+ *
+ * What dispatch DOES NOT support (and why):
+ * - RSC component routes — rendering requires the Flight serializer + React
+ *   server runtime, which is the boundary this primitive is defined to avoid.
+ *   This includes partial requests that resolve to a component route.
+ * - Server actions (?_rsc_action) — RSC protocol concerns handled by
+ *   router.fetch().
+ * - createRouter({ onError }) on a thrown non-Response route HANDLER error: the
+ *   error is serialized into the same typed 500 / RouterError Response as
+ *   production, but onError is NOT invoked for that path here. Cover handler-error
+ *   onError side effects with an e2e test. (This is the unchanged boundary; cache
+ *   and other background errors DO route through onError — see below.)
+ * - Location-state-carrying redirects on a partial/action request: production
+ *   embeds a Flight payload (createRedirectFlightResponse) so the client can
+ *   restore location state across the redirect. dispatch is RSC-free, so it
+ *   cannot emit that Flight stream. It falls back to the no-state behavior — a
+ *   204 + X-RSC-Redirect via createSimpleRedirectResponse — dropping the
+ *   embedded location state. The 204 status, the X-RSC-Redirect header, and the
+ *   merged cookies/headers all match production; only the Flight-embedded
+ *   location-state entries are absent. Cover location-state restoration across a
+ *   partial redirect with an e2e test.
+ * - Telemetry cache.decision / loader.* / handler.error events: these fire from
+ *   the real match()/matchPartial() + RSC render + loader pipeline (match-
+ *   handlers.ts, loader-resolution.ts, segment-resolution), none of which
+ *   dispatch runs. Synthesizing them here would be faking (the events would not
+ *   reflect a real cache lookup or loader run), so dispatch emits only the
+ *   request.start/end/error lifecycle above; cover cache/loader telemetry with an
+ *   e2e test driving a real RSC request.
+ *
+ * dispatch reuses router.previewMatch(), which itself runs content negotiation
+ * and resolves route middleware from the matched entry tree, so dispatch's
+ * route-middleware collection is exactly the router's, not a re-implementation.
+ */
+import type { Rango } from "../router/router-interfaces.js";
+/**
+ * Options for dispatch.
+ */
+export interface DispatchOptions<TEnv = any> {
+    /** The request to dispatch: a `Request`, or a URL string (absolute or path). */
+    request: Request | string;
+    /** Environment bindings forwarded to matching and middleware. */
+    env?: TEnv;
+}
+/**
+ * Run a request through the router in-process and return the Response.
+ *
+ * @example
+ * ```ts
+ * const router = createRouter<Env>({}).routes(urls(({ path }) => [
+ *   path.json("/api/health", () => ({ ok: true }), { name: "health" }),
+ * ]));
+ *
+ * const res = await dispatch(router, { request: "/api/health" });
+ * expect(res.status).toBe(200);
+ * expect(await res.json()).toEqual({ ok: true });
+ * ```
+ */
+export declare function dispatch<TEnv = any>(publicRouter: Rango<TEnv, any>, opts: DispatchOptions<TEnv>): Promise<Response>;

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

@@ -0,0 +1,15 @@
+/**
+ * @rangojs/router/testing/dom
+ *
+ * Component-render testing: `renderRoute`, the React-Testing-Library-style stub
+ * for client components that read router context (useParams / useReverse /
+ * Outlet / useNavigation / useLoader).
+ *
+ * Separate from the main `@rangojs/router/testing` barrel so unit suites that
+ * only test loaders, middleware, or `dispatch` never reference React, the
+ * browser runtime, or `@testing-library/react` (an optional peer that
+ * `renderRoute` lazy-loads at call time). Run these tests in a DOM environment
+ * (`happy-dom` or `jsdom`).
+ */
+export { renderRoute } from "./render-route.js";
+export type { RenderRouteSpec, RenderRouteOptions, TestRouterHandle, RenderRouteResult, HandleDataSeed, } from "./render-route.js";