@rangojs/router 0.4.0 → 0.4.2

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

@@ -1,233 +0,0 @@
-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.backup/ssr/inject-rsc-eager.d.ts

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

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

@@ -1,71 +0,0 @@
-/**
- * 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.backup/ssr/ssr-root.d.ts

@@ -1,69 +0,0 @@
-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.backup/static-handler.d.ts

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

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

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

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

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