@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.0

package/dist/types/router/url-params.d.ts

@@ -0,0 +1,26 @@
+/**
+ * URL param encode/decode at the route boundary.
+ *
+ * Extraction (decode): regex/trie matchers keep param values URL-encoded;
+ * `safeDecodeURIComponent` turns them back into raw strings so `ctx.params`
+ * matches the contract apps expect (Express/React Router/Fastify/Koa) and
+ * round-trips through reverse stay stable. Malformed %-encoding is
+ * preserved as-is so a broken URL doesn't crash matching.
+ *
+ * Reversal (encode): `encodePathSegment` escapes only what RFC 3986
+ * requires for a path segment — `/`, `?`, `#`, space, control chars,
+ * non-ASCII — and leaves pchar sub-delims (`@ : $ & + , ; =` and friends)
+ * readable. `encodeURIComponent` over-encodes for path segments, which
+ * makes generated URLs harder for humans to read in the address bar
+ * (e.g. mailbox IDs like `ivo@example.com` would become
+ * `ivo%40example.com` even though `@` is path-legal).
+ */
+export declare function safeDecodeURIComponent(raw: string): string;
+export declare function encodePathSegment(value: string): string;
+/**
+ * Encode a catch-all remainder: encode each `/`-separated segment but keep the
+ * separators, so `a/b c` -> `a/b%20c` (not `a%2Fb%20c`). Shared by the reverse
+ * helper and the build-time prerender substitution so both produce identical
+ * URLs. `encode` defaults to the path-safe `encodePathSegment`.
+ */
+export declare function encodePathRemainder(value: string, encode?: (segment: string) => string): string;

package/dist/types/router.d.ts

@@ -0,0 +1,7 @@
+import type { RangoOptions } from "./router/router-options.js";
+import type { Rango } from "./router/router-interfaces.js";
+export { RSC_ROUTER_BRAND, RouterRegistry } from "./router/router-registry.js";
+export type { RangoOptions, RootLayoutProps, SSRStreamMode, SSROptions, ResolveStreamingContext, } from "./router/router-options.js";
+export type { Rango, RangoInternal, RouterRequestInput, } from "./router/router-interfaces.js";
+export { toInternal } from "./router/router-interfaces.js";
+export declare function createRouter<TEnv = any>(options?: RangoOptions<TEnv>): Rango<TEnv, {}>;

package/dist/types/rsc/capture-queue.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Run `task` after every previously enqueued capture has settled. Returns a
+ * promise for THIS task's completion (rejections propagate to the caller —
+ * the queue itself is insulated).
+ */
+export declare function enqueueSerializedCapture(task: () => Promise<void>): Promise<void>;

package/dist/types/rsc/full-payload.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Full (initial-load / document) RSC payload builder.
+ *
+ * Extracted from rsc-rendering.ts so both the foreground render AND the PPR
+ * background shell capture (shell-capture.ts) build the SAME payload shape over
+ * their own handle store. `resume` requires the captured tree to match the served
+ * tree; building an identical payload over the same replayed segments is what
+ * makes that hold. Keep this byte-identical to the normal full-render path.
+ */
+import type { MatchResult } from "../types.js";
+import type { RscPayload } from "./types.js";
+import type { HandlerContext } from "./handler-context.js";
+import type { RequestContext } from "../server/request-context.js";
+import type { HandleStore } from "../server/handle-store.js";
+/**
+ * Build the metadata payload for a full (non-partial) document render.
+ *
+ * @param handleStore - the store whose resolved handle stream feeds the payload;
+ *   the foreground passes reqCtx's store, the background capture passes its fresh
+ *   derived-context store.
+ */
+export declare function buildFullPayload(m: MatchResult, ctx: HandlerContext<any>, url: URL, reqCtx: RequestContext<any>, handleStore: HandleStore): RscPayload;

package/dist/types/rsc/handler-context.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared dependencies for extracted RSC handler functions.
+ *
+ * Bundled into a single object by createRSCHandler() and passed to
+ * each leaf handler (progressive enhancement, server action, loader fetch,
+ * RSC rendering) so they can be standalone modules without closure coupling.
+ */
+import type { RangoInternal } from "../router/router-interfaces.js";
+import type { ErrorPhase } from "../types.js";
+import type { InvokeOnErrorContext } from "../router/error-handling.js";
+import type { RSCDependencies, LoadSSRModule } from "./types.js";
+import type { SSRStreamMode } from "../router/router-options.js";
+export interface HandlerContext<TEnv = unknown> {
+    router: RangoInternal<TEnv, any>;
+    version: string;
+    renderToReadableStream: RSCDependencies["renderToReadableStream"];
+    decodeReply: RSCDependencies["decodeReply"];
+    createTemporaryReferenceSet: RSCDependencies["createTemporaryReferenceSet"];
+    loadServerAction: RSCDependencies["loadServerAction"];
+    decodeAction: RSCDependencies["decodeAction"];
+    decodeFormState: RSCDependencies["decodeFormState"];
+    loadSSRModule: LoadSSRModule;
+    callOnError: (error: unknown, phase: ErrorPhase, context: InvokeOnErrorContext<TEnv>) => void;
+    getRequiredRouteMap: () => Record<string, string>;
+    createRedirectFlightResponse: (redirectUrl: string, locationState?: Record<string, unknown>, external?: boolean) => Response;
+    /**
+     * Resolve the SSR stream mode for a given request.
+     * Returns "stream" when no resolveStreaming callback is configured.
+     */
+    resolveStreamMode: (request: Request, env: TEnv, url: URL) => Promise<SSRStreamMode>;
+}

package/dist/types/rsc/handler.d.ts

@@ -0,0 +1,9 @@
+/**
+ * RSC Request Handler
+ *
+ * Main request handler for RSC rendering, server actions, loader fetching,
+ * and progressive enhancement (no-JS form submissions).
+ */
+import type { CreateRSCHandlerOptions } from "./types.js";
+import type { RouterRequestInput } from "../router/router-interfaces.js";
+export declare function createRSCHandler<TEnv = unknown, TRoutes extends Record<string, string> = Record<string, string>>(options: CreateRSCHandlerOptions<TEnv, TRoutes>): (request: Request, input?: RouterRequestInput<TEnv>) => Promise<Response>;

package/dist/types/rsc/helpers.d.ts

@@ -0,0 +1,124 @@
+/**
+ * RSC Handler Helpers
+ *
+ * Utility functions for RSC request handling.
+ */
+import type { RequestContext } from "../server/request-context.js";
+import type { MiddlewareEntry, MiddlewareFn } from "../router/middleware.js";
+import type { RscPayload } from "./types.js";
+/**
+ * Drain ctx._onResponseCallbacks onto a response. Swapping the array before
+ * iteration prevents re-entrant registrations from double-firing and matches
+ * the contract that each callback runs at most once per request.
+ *
+ * Exported so the testing primitives' buildRunResponse can reuse the exact
+ * production drain (swap-before-iterate + external-redirect brand preservation)
+ * rather than maintain a hand-synced copy. This module is plugin-rsc-free on its
+ * eager graph (dispatch.ts already statically imports from here in the same
+ * testing barrel), so importing it adds nothing to the unit runner's graph.
+ */
+export declare function drainOnResponseCallbacks(ctx: RequestContext, response: Response): Response;
+/** Apply a saved callback batch while preserving an external-redirect brand. */
+export declare function applyOnResponseCallbacks(callbacks: Array<(response: Response) => Response>, response: Response): Response;
+/**
+ * Check if a request body has content to decode
+ */
+export declare function hasBodyContent(body: FormData | string): boolean;
+/**
+ * Create a Response with headers merged from the request context's stub response.
+ * This ensures headers/cookies set during middleware or handler execution are included.
+ * Also triggers any registered onResponse callbacks.
+ */
+export declare function createResponseWithMergedHeaders(body: BodyInit | null, init: ResponseInit): Response;
+/**
+ * Rebuild a Response returned or thrown by a response-route handler so request
+ * effects merge consistently in production and the public dispatch primitive.
+ */
+export declare function rewrapResponseRouteResponse(result: Response): Response;
+/** Origin/basename needed to resolve soft redirect targets server-side. */
+export type SoftRedirectResolveOpts = {
+    requestOrigin: string;
+    basename?: string;
+};
+/**
+ * Create a 204 response with X-RSC-Redirect header for stateless redirects.
+ * Used during partial/action requests where fetch would auto-follow a raw
+ * 3xx to a URL that renders full HTML instead of Flight data. The 204 status
+ * prevents auto-follow; the client reads the header and re-navigates via
+ * the router.
+ *
+ * The header value is resolved with {@link resolveSoftRedirectUrl} so a
+ * cross-origin / unsafe-scheme target is neutralized before it leaves the
+ * server (defense-in-depth; client validators still run).
+ */
+export declare function createSimpleRedirectResponse(redirectUrl: string, opts: SoftRedirectResolveOpts & {
+    external?: boolean;
+}): Response;
+/**
+ * Carry over headers from a source redirect Response to a wrapper Response.
+ * Skips Location and X-RSC-Redirect (intentionally replaced by the wrapper) and
+ * appends Set-Cookie to avoid clobbering multiple cookie headers.
+ *
+ * This is a GENERIC copier used by every redirect-rebuild path (PE
+ * extractRedirectResponse, the SPA intercept below, the guard's neutralize
+ * rebuild), so it has two redirect-specific jobs:
+ *
+ * 1. NEVER copy the reserved external-redirect header: it is no longer a trust
+ *    signal (the opt-in is the out-of-band brand), and a forged value from a
+ *    proxied upstream must not ride a rebuilt response to the browser.
+ * 2. Transfer the out-of-band external brand: a rebuilt document-native redirect
+ *    has to carry the opt-in to the guard chokepoint, which reads and clears it.
+ *    Without this transfer, redirect(url, { external: true }) would be silently
+ *    neutralized on any rebuild path (fail-closed, but a feature regression).
+ */
+export declare function carryOverRedirectHeaders(source: Response, target: Response): void;
+/**
+ * If a response is a 3xx redirect during a partial (client-side) request,
+ * intercept it and return a Flight-compatible redirect instead.
+ * fetch() auto-follows 3xx which would hit a URL that renders full HTML
+ * the client can't parse. Returns null if the response is not a redirect.
+ *
+ * Soft redirect targets are resolved server-side (same-origin / external
+ * scheme rules) via `opts` before they are written into X-RSC-Redirect or
+ * handed to the Flight factory.
+ */
+export declare function interceptRedirectForPartial(response: Response, createRedirectFlightResponse: (redirectUrl: string, locationState?: Record<string, unknown>, external?: boolean) => Response, opts: SoftRedirectResolveOpts): Response | null;
+/**
+ * Attach location state set during a request to a payload's metadata.
+ * No-op if no location state was set. Callers must ensure payload.metadata
+ * is populated (the non-null assertion holds for the partial/action payloads
+ * that reach this helper).
+ */
+export declare function attachLocationStateIfPresent(payload: RscPayload): void;
+/**
+ * Only cache successful responses. Non-200 statuses (errors, redirects) are
+ * not cached -- notFound() produces 500 in response routes, and explicit
+ * non-200 Responses are rare enough that caching them would be surprising.
+ */
+export declare function isCacheableStatus(status: number): boolean;
+/**
+ * Convert route-level middleware entries to the format expected by
+ * executeMiddleware. Route middleware from previewMatch carries just
+ * { handler, params }; this wraps them in the full MiddlewareEntry shape.
+ */
+export declare function buildRouteMiddlewareEntries<TEnv>(routeMiddleware: Array<{
+    handler: MiddlewareFn;
+    params: Record<string, string>;
+}>): Array<{
+    entry: MiddlewareEntry<TEnv>;
+    params: Record<string, string>;
+}>;
+/**
+ * Merge stub headers from the request context onto an existing Response in
+ * place, then drain onResponse callbacks. Used when a Response cannot flow
+ * through `new Response()` — status 101 is outside the constructor's
+ * 200-599 range, and the Cloudflare-specific `webSocket` property would be
+ * lost on reconstruction.
+ */
+export declare function mergeStubHeadersAndFinalize(response: Response): Response;
+/**
+ * Run onResponse callbacks on an existing Response. Used by code paths that
+ * bypass createResponseWithMergedHeaders (e.g. middleware short-circuits)
+ * but still need ctx.onResponse() callbacks to fire.
+ */
+export declare function finalizeResponse(response: Response): Response;

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

@@ -0,0 +1,17 @@
+/**
+ * Rango - RSC Entry Point
+ *
+ * This module provides RSC utilities for server-side rendering,
+ * server actions, loader fetching, and progressive enhancement.
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { router } from "./router.js";
+ *
+ * // Use router.fetch to handle requests
+ * export default { fetch: router.fetch };
+ * ```
+ */
+export { createRSCHandler } from "./handler.js";
+export type { RscPayload, ReactFormState, RSCDependencies, SSRRenderOptions, SSRModule, LoadSSRModule, CreateRSCHandlerOptions, HandlerCacheConfig, NonceProvider, } from "./types.js";
+export { getRequestContext } from "../server/request-context.js";

package/dist/types/rsc/json-route-result.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared serialization for `json()` response-route results.
+ *
+ * Kept in its own lightweight module (depends only on `errors.js`) so the
+ * `dispatch()` testing primitive can import it WITHOUT dragging in
+ * `response-route-handler.ts`'s heavy runtime graph, which transitively reaches
+ * a Vite virtual module and breaks a plain (non-Vite) vitest import.
+ */
+/**
+ * Serialize a `json()` response-route result, rejecting a nested unresolved
+ * Promise (the forgotten-await footgun: `() => ({ data: fetchSomething() })`).
+ * `JSON.stringify` would silently emit `{}` for a Promise, shipping empty data;
+ * the RSC pipeline awaits nested promises but this path does not. Throwing
+ * `RESPONSE_NOT_SERIALIZABLE` makes the failure loud.
+ *
+ * Shared by the production response-route handler and the `dispatch()` testing
+ * primitive so a `dispatch` json test of a forgotten await fails exactly where
+ * production 500s, instead of going green.
+ */
+export declare function stringifyJsonRouteResult(result: unknown): string;

package/dist/types/rsc/loader-fetch.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Loader Fetch Handler
+ *
+ * Handles load() requests (GET, POST, PUT, PATCH, DELETE) from the client.
+ * All loader data fetching and mutations go through this endpoint.
+ *
+ * Route params (e.g. slug from /blog/:slug) come from previewMatch() in the
+ * outer coreRequestHandler, threaded through coreRequestHandlerInner as
+ * routeParams. This is necessary because handleLoaderFetch doesn't do its
+ * own route matching -- the URL is the page's pathname, and previewMatch
+ * has already extracted params from it.
+ */
+import type { HandlerContext } from "./handler-context.js";
+export declare function handleLoaderFetch<TEnv>(ctx: HandlerContext<TEnv>, request: Request, env: TEnv, url: URL, variables: Record<string, any>, routeParams?: Record<string, string>): Promise<Response>;

package/dist/types/rsc/manifest-init.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Router Manifest Initialization
+ *
+ * Builds a fresh route trie from router.urlpatterns for dev/HMR scenarios
+ * where the manifest exists but the trie needs rebuilding.
+ */
+/**
+ * Build a fresh route trie from router.urlpatterns and store it in the
+ * per-router cache. Also sets the per-router manifest and merges into
+ * the global manifest for reverse()/href().
+ *
+ * Called when manifest data may exist but the per-router trie is missing,
+ * which happens in dev mode after HMR: the virtual module sets the manifest
+ * from fresh gen files but skips the trie (which would be stale from initial
+ * discovery). The trie is essential for correct wildcard priority -- without
+ * it, the regex fallback matches catch-all patterns before specific routes.
+ */
+export declare function buildRouterTrieFromUrlpatterns(router: any): Promise<void>;

package/dist/types/rsc/nonce.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Nonce generation for Content Security Policy (CSP)
+ */
+import type { ContextVar } from "../context-var.js";
+/**
+ * Typed ContextVar token for CSP nonce.
+ *
+ * Use this to READ the nonce in middleware or handlers:
+ * ```ts
+ * import { nonce } from "@rangojs/router";
+ * const value = ctx.get(nonce); // string | undefined
+ * ```
+ *
+ * Supply the nonce via the `createRouter({ nonce })` provider, not by writing
+ * this token yourself. The provider value is threaded into the router's SSR
+ * machinery (NonceContext/useNonce, Scripts/MetaTags attributes, the inlined
+ * Flight payload scripts) AND sets this token. A direct `ctx.set(nonce, value)`
+ * in middleware runs AFTER the SSR nonce is resolved: the value is readable via
+ * `ctx.get(nonce)` and gates PPR shell capture (a per-request nonce must never
+ * bake into a shared shell), but the router will not apply it to its own
+ * scripts — useNonce() stays undefined for that request.
+ */
+export declare const nonce: ContextVar<string>;
+/**
+ * Generate a cryptographic nonce for CSP.
+ * Returns a 16-byte random value encoded as base64.
+ */
+export declare function generateNonce(): string;

package/dist/types/rsc/origin-guard.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Origin Guard
+ *
+ * Cross-origin request protection for server actions, loader fetches, and
+ * progressive enhancement form submissions. Validates that the Origin header
+ * (or Referer fallback) matches the request Host before executing.
+ *
+ * Requests without an Origin or Referer header are allowed — same-origin
+ * navigations, bookmarks, and non-browser clients don't send Origin.
+ */
+import type { RequestPlan } from "../router/request-classification.js";
+/**
+ * Request phase that triggered the origin check.
+ */
+export type OriginCheckPhase = "action" | "loader" | "pe-form";
+export declare const ORIGIN_CHECK_PHASE_BY_MODE: Record<RequestPlan["mode"], OriginCheckPhase | null>;
+/**
+ * Context passed to the originCheck callback.
+ */
+export interface OriginCheckContext<TEnv = any> {
+    request: Request;
+    url: URL;
+    env: TEnv;
+    routerId: string;
+    phase: OriginCheckPhase;
+    /** Run the built-in conservative check (Origin/Referer vs Host + url.protocol). */
+    defaultCheck: () => boolean;
+}
+/**
+ * Configuration for the origin check.
+ *
+ * - `true` (default) — built-in conservative check
+ * - `false` — disabled
+ * - function — custom control; return true to allow, false to reject with
+ *   default 403, or a Response for custom rejection
+ */
+export type OriginCheckConfig<TEnv = any> = boolean | ((ctx: OriginCheckContext<TEnv>) => boolean | Response | Promise<boolean | Response>);
+/**
+ * Built-in conservative origin check.
+ * Compares Origin (or Referer fallback) against Host + url.protocol.
+ * Does NOT trust X-Forwarded-Host/Proto headers.
+ *
+ * Returns true to allow, false to reject.
+ */
+export declare function defaultOriginCheck(request: Request, url: URL): boolean;
+/**
+ * Configuration-aware origin check dispatcher.
+ * Builds the OriginCheckContext and delegates to the configured check.
+ */
+export declare function checkRequestOrigin<TEnv = any>(request: Request, url: URL, config: OriginCheckConfig<TEnv> | undefined, env: TEnv, routerId: string, phase: OriginCheckPhase): Promise<Response | null>;

package/dist/types/rsc/progressive-enhancement.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Progressive Enhancement Handler
+ *
+ * Handles no-JS form submissions. When JavaScript is disabled, React renders
+ * forms with hidden fields ($ACTION_REF_*, $ACTION_KEY) containing the action
+ * reference. We detect these and return HTML instead of RSC stream.
+ */
+import { getRequestContext } from "../server/request-context.js";
+import type { MiddlewareFn } from "../router/middleware.js";
+import type { HandlerContext } from "./handler-context.js";
+export interface PeRouteMiddlewareInfo {
+    routeMiddleware?: Array<{
+        handler: MiddlewareFn;
+        params: Record<string, string>;
+    }>;
+    variables: Record<string, any>;
+    routeReverse?: (name: string, params?: Record<string, string>, search?: Record<string, unknown>) => string;
+}
+export declare function handleProgressiveEnhancement<TEnv>(ctx: HandlerContext<TEnv>, request: Request, env: TEnv, url: URL, isAction: boolean, handleStore: ReturnType<typeof getRequestContext>["_handleStore"], nonce: string | undefined, routeMwInfo?: PeRouteMiddlewareInfo): Promise<Response | null>;

package/dist/types/rsc/redirect-guard.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Server-side open-redirect guard.
+ *
+ * Applied to the FINAL handler response (the single top-level return in
+ * `handler.ts`) so every browser-followed redirect honors the same same-origin
+ * rule the client enforces (`browser/validate-redirect-origin.ts`), via the one
+ * shared resolver in `redirect-origin.ts`. This is the server half of the
+ * client's existing guard: the client can only validate redirects its own JS
+ * navigates to (the SPA/fetch channel), so document-native redirects -- a no-JS
+ * PE form POST, a full-page GET `match.redirect`, a middleware `redirect()`
+ * short-circuit, a response-route 3xx -- reach the browser with no client in the
+ * loop. They all funnel through one handler return, so guarding there covers
+ * every one and any future redirect exit.
+ *
+ * Soft (SPA/Flight) redirects are 200/204 responses (`X-RSC-Redirect` header or
+ * `metadata.redirect` payload) and are NOT redirect Responses, so they never
+ * reach this guard. They are resolved at construction time via
+ * `resolveSoftRedirectUrl` (same shared rules) so unsafe targets never leave
+ * the server; client validators remain defense-in-depth.
+ *
+ * Behavior on a `Location` header:
+ * - same-origin / relative  -> passes through unchanged
+ * - `redirect(url, { external: true })` (out-of-band brand present) and an
+ *   http(s) target -> allowed (explicit, auditable, unforgeable opt-in)
+ * - branded but a non-http(s) target (e.g. `javascript:`) -> neutralized: the
+ *   opt-in waives the same-origin rule, NOT scheme safety
+ * - cross-origin without the brand -> Location rewritten to the basename root
+ *   (a safe same-origin landing, the document analog of the client's "stay put");
+ *   dev logs the blocked target and points to `{ external: true }`.
+ *
+ * The opt-in is an out-of-band brand on the Response object (isExternalRedirect),
+ * never a wire header: a header is forgeable by an attacker-controlled upstream
+ * response a proxy-style response route copies through, which would defeat the
+ * guard without app code ever opting in. The reserved header name is stripped
+ * defensively so a forged value can never reach the browser.
+ */
+export declare function guardOutgoingRedirect(response: Response, requestOrigin: string, basename: string | undefined): Response;

package/dist/types/rsc/render-pipeline.d.ts

@@ -0,0 +1,138 @@
+import type { TraceSpan } from "../router/tracing.js";
+import type { RenderMode, RenderPhase } from "../router/timeout.js";
+import type { HandlerContext } from "./handler-context.js";
+import type { RscPayload } from "./types.js";
+export type RscRenderMode = RenderMode;
+export type RscRenderPhase = RenderPhase;
+export interface RscRenderStageProgress {
+    completed: number;
+    total: number;
+}
+export interface RscRenderStageContext {
+    mode: RscRenderMode;
+    phase: RscRenderPhase;
+    pathname: string;
+    progress: RscRenderStageProgress;
+    startedAt: number;
+    phaseStartedAt: number;
+    routeKey?: string;
+    actionId?: string;
+}
+export type RscRenderStageEvent = {
+    type: "stage:start";
+    context: RscRenderStageContext;
+} | {
+    type: "stage:complete";
+    context: RscRenderStageContext;
+    durationMs: number;
+} | {
+    type: "stage:error";
+    context: RscRenderStageContext;
+    durationMs: number;
+    error: unknown;
+};
+export interface RscRenderStageTracking {
+    mode?: RscRenderMode;
+    routeKey?: string;
+    actionId?: string;
+    onEvent?: (event: RscRenderStageEvent) => void;
+    /** Whole-render span receiving low-cardinality current/error phase attrs. */
+    span?: TraceSpan;
+}
+export interface RscRenderInput<TEnv> {
+    ctx: Pick<HandlerContext<TEnv>, "renderToReadableStream" | "callOnError">;
+    request: Request;
+    url: URL;
+    env: TEnv;
+    payload: RscPayload;
+    init: ResponseInit;
+    temporaryReferences?: unknown;
+    recordSerializeMetric?: boolean;
+    tracking?: RscRenderStageTracking;
+}
+export interface RscFlightStageInput<TEnv> {
+    ctx: Pick<HandlerContext<TEnv>, "renderToReadableStream" | "callOnError">;
+    request: Request;
+    url: URL;
+    env: TEnv;
+    payload: RscPayload;
+    temporaryReferences?: unknown;
+    recordSerializeMetric?: boolean;
+    tracking?: RscRenderStageTracking;
+}
+export interface RscFlightStage {
+    type: "flight";
+    payload: RscPayload;
+    stream: ReadableStream<Uint8Array>;
+    init: ResponseInit;
+}
+export interface RscPreparedHtmlRender {
+    render: () => BodyInit | null | Promise<BodyInit | null>;
+    init?: ResponseInit;
+}
+export interface RscRenderOptions {
+    html?: (flight: RscFlightStage) => RscPreparedHtmlRender | Promise<RscPreparedHtmlRender>;
+}
+interface RscFlightCommand<TEnv> {
+    type: "flight";
+    execute: () => RscFlightStage;
+    recordSerializeMetric: boolean;
+}
+interface RscHtmlCommand {
+    type: "html";
+    prepare: () => RscPreparedHtmlRender | Promise<RscPreparedHtmlRender>;
+}
+interface RscResponseCommand {
+    type: "response";
+    execute: () => Response;
+}
+export type RscRenderCommand<TEnv> = RscFlightCommand<TEnv> | RscHtmlCommand | RscResponseCommand;
+export type RscRenderCommandResult = {
+    type: "flight";
+    value: RscFlightStage;
+} | {
+    type: "html";
+    value: RscHtmlResult;
+} | {
+    type: "response";
+    value: Response;
+};
+interface RscHtmlResult {
+    body: BodyInit | null;
+    init?: ResponseInit;
+}
+export interface RscRenderDriverOptions {
+    url: URL;
+    tracking?: RscRenderStageTracking;
+    /**
+     * The plan's command sequence. Required (not defaulted): the driver reports
+     * `total` from its length, and a wrong/absent list made progress read
+     * `completed > total`. Callers of createRscRenderPlan pass rscRenderPlanPhases.
+     */
+    phases: readonly RscRenderPhase[];
+}
+type RscRenderPlan<TEnv> = Generator<RscRenderCommand<TEnv>, Response | undefined, RscRenderCommandResult>;
+/**
+ * Describe the foreground response-construction work without executing it.
+ * Each command is yielded before its work starts; the driver owns execution,
+ * attribution, and resumption.
+ */
+export declare function createRscRenderPlan<TEnv>(input: RscRenderInput<TEnv>, options?: RscRenderOptions): RscRenderPlan<TEnv>;
+/**
+ * The exact command sequence createRscRenderPlan yields, derived from the SAME
+ * `options.html` branch that shapes the plan. Callers pass this as the driver's
+ * `phases` so `total` mirrors the number of commands and progress can never
+ * report `completed > total`. Keep in lockstep with createRscRenderPlan.
+ */
+export declare function rscRenderPlanPhases(options?: RscRenderOptions): readonly RscRenderPhase[];
+/** Execute a render plan while preserving the exact result/error identities. */
+export declare function driveRscRenderPlan<TEnv>(plan: RscRenderPlan<TEnv>, options: RscRenderDriverOptions): Promise<Response>;
+/** Build a standard Flight or Flight+HTML response through the shared driver. */
+export declare function renderRscResponse<TEnv>(input: RscRenderInput<TEnv>, options?: RscRenderOptions): Promise<Response>;
+/**
+ * Construct Flight directly for specialized post-commit paths such as PPR.
+ * Standard responses use renderRscResponse so the driver owns every phase.
+ */
+export declare function renderRscFlightStage<TEnv>(input: RscFlightStageInput<TEnv>, init?: ResponseInit): RscFlightStage;
+export declare function createRscStageDebugSink(log?: (message: string, details?: Record<string, unknown>) => void): (event: RscRenderStageEvent) => void;
+export {};

package/dist/types/rsc/response-cache-serve.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared response-route cache serve.
+ *
+ * Owns the single response-cache contract — cache-scope resolution from the
+ * matched entry tree, condition eval, key resolution (route key() > store
+ * keyGenerator > default), tag resolution, pre-handler-callback timing, and the
+ * fresh-hit / SWR-revalidate / miss-write branches — for BOTH the production
+ * response-route handler (rsc/response-route-handler.ts) and the dispatch testing
+ * primitive (testing/dispatch.ts), so the two can never drift.
+ *
+ * Plugin-rsc hazard: cache-scope.ts pulls @vitejs/plugin-rsc (via segment-codec),
+ * which the non-Vite unit-test runner cannot resolve, and this module is on the
+ * testing barrel's EAGER graph (dispatch imports it). So `createCacheScope` and
+ * `resolveCacheTags` are NOT imported here at runtime — they are INJECTED by the
+ * caller (production imports them statically; dispatch lazy-imports them only once
+ * a response route matches). The only runtime imports here are plugin-rsc-free
+ * (helpers' isCacheableStatus/finalizeResponse, traverseBack); cache-scope is a
+ * type-only import (erased at build).
+ */
+import type { CacheScope } from "../cache/cache-scope.js";
+import type { PartialCacheOptions } from "../types.js";
+import type { RequestContext } from "../server/request-context.js";
+import type { EntryCacheConfig, EntryData } from "../server/context.js";
+/** Injected cache-scope builders (kept off this module's runtime import graph). */
+export interface CacheScopeDeps {
+    createCacheScope: (config: EntryCacheConfig | undefined, parent?: CacheScope | null) => CacheScope | null;
+    resolveCacheTags: (config: PartialCacheOptions | false, ctx: RequestContext | undefined) => string[] | undefined;
+}
+export interface ServeResponseRouteWithCacheArgs {
+    reqCtx: RequestContext;
+    manifestEntry: EntryData;
+    responseType: string;
+    url: URL;
+    /** callHandler wrapped by route-level middleware — the unit the cache wraps. */
+    executeHandler: () => Promise<Response>;
+    deps: CacheScopeDeps;
+}
+/**
+ * Serve a response route through its cache, or return `undefined` when no cache
+ * applies (no scope, disabled, condition false, or store lacks get/putResponse)
+ * so the caller falls through to a plain `executeHandler()` run.
+ *
+ * Must run inside runWithRequestContext (reads the ambient request context via
+ * the helpers and reqCtx.waitUntil for background writes).
+ */
+export declare function serveResponseRouteWithCache(args: ServeResponseRouteWithCacheArgs): Promise<Response | undefined>;

package/dist/types/rsc/response-error.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Problem Details (RFC 9457) Builder
+ *
+ * Builds a problem+json error body from a caught error, controlling what
+ * information is exposed based on error type and environment.
+ */
+import type { ProblemDetails } from "../urls.js";
+/**
+ * Build an RFC 9457 problem+json body from a caught error.
+ * RouterError messages/codes are always exposed (developer-crafted).
+ * Standard Error messages are hidden in production.
+ *
+ * The `type` member is omitted in this phase: per RFC 9457 an absent `type` is
+ * treated as `"about:blank"` (no semantics beyond the HTTP status), so emitting
+ * it adds nothing. Per-route problem-type URIs arrive with the declared-errors
+ * map later. `code` is always present so consumers can branch on it
+ * (`"INTERNAL"` for non-RouterError failures).
+ */
+export declare function createProblemDetails(error: unknown, status: number, isDev: boolean): ProblemDetails;