@rangojs/router 0.1.1 → 0.4.0

package/dist/types.backup/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.backup/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.backup/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.backup/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.backup/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.backup/rsc/helpers.d.ts

@@ -0,0 +1,213 @@
+/**
+ * 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";
+import type { HandlerContext } from "./handler-context.js";
+export interface RscRenderStageInput<TEnv> {
+    ctx: Pick<HandlerContext<TEnv>, "renderToReadableStream" | "callOnError">;
+    request: Request;
+    url: URL;
+    env: TEnv;
+    payload: RscPayload;
+    init: ResponseInit;
+    temporaryReferences?: unknown;
+    recordSerializeMetric?: boolean;
+    tracking?: RscRenderStageTracking;
+}
+export type RscRenderMode = "unknown" | "full" | "partial" | "action-revalidation" | "progressive-enhancement" | "progressive-enhancement-error";
+export type RscRenderPhase = "payload" | "flight" | "html" | "response";
+export declare const RSC_RENDER_FLIGHT_RESPONSE_PHASES: readonly RscRenderPhase[];
+export declare const RSC_RENDER_HTML_RESPONSE_PHASES: readonly RscRenderPhase[];
+export declare const RSC_FLIGHT_ONLY_PHASES: readonly RscRenderPhase[];
+export declare const RSC_FLIGHT_HTML_PHASES: readonly RscRenderPhase[];
+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:yield";
+    context: RscRenderStageContext;
+} | {
+    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;
+    phases?: readonly RscRenderPhase[];
+    totalStages?: number;
+    onEvent?: (event: RscRenderStageEvent) => void;
+}
+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 RscHtmlStageInput {
+    url: URL;
+    tracking?: RscRenderStageTracking;
+}
+export type RscRenderStage = {
+    type: "payload";
+    payload: RscPayload;
+    init: ResponseInit;
+    context: RscRenderStageContext;
+} | {
+    type: "flight";
+    payload: RscPayload;
+    stream: ReadableStream<Uint8Array>;
+    init: ResponseInit;
+    durationMs: number;
+    context: RscRenderStageContext;
+};
+export type RscFlightStage = Extract<RscRenderStage, {
+    type: "flight";
+}>;
+export interface RscRenderStageControl {
+    payload?: RscPayload;
+    init?: ResponseInit;
+    body?: BodyInit | null;
+}
+export declare function renderRscFlightStage<TEnv>(input: RscFlightStageInput<TEnv>, startedAt: number, init?: ResponseInit): RscFlightStage;
+export declare function observeRscHtmlStage<T>(input: RscHtmlStageInput, fn: () => Promise<T>): Promise<T>;
+export declare function createRscStageDebugSink(log?: (message: string, details?: Record<string, unknown>) => void): (event: RscRenderStageEvent) => void;
+/**
+ * Stage the common RSC render flow as a resumable async generator:
+ * payload inspection/mutation -> Flight stream creation -> response finalization.
+ * HTML callers pause at the Flight stage, render SSR from that stream, then
+ * resume with the HTML body/init so header merging still happens once.
+ */
+export declare function createRscRenderStages<TEnv>(input: RscRenderStageInput<TEnv>): AsyncGenerator<RscRenderStage, Response, RscRenderStageControl | undefined>;
+export declare function runRscRenderStages(stages: AsyncGenerator<RscRenderStage, Response, RscRenderStageControl | undefined>): Promise<Response>;
+export declare function readRscFlightStage(stages: AsyncGenerator<RscRenderStage, Response, RscRenderStageControl | undefined>): Promise<RscFlightStage>;
+export declare function finishRscRenderStages(stages: AsyncGenerator<RscRenderStage, Response, RscRenderStageControl | undefined>, control?: RscRenderStageControl): Promise<Response>;
+/**
+ * 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;
+/**
+ * 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.
+ */
+export declare function createSimpleRedirectResponse(redirectUrl: string): 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.
+ */
+export declare function interceptRedirectForPartial(response: Response, createRedirectFlightResponse: (redirectUrl: string, locationState?: Record<string, unknown>, external?: boolean) => Response): 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.backup/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.backup/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.backup/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.backup/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.backup/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.backup/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.backup/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.backup/rsc/redirect-guard.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 stay validated client-side.
+ *
+ * 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.backup/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.backup/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;

package/dist/types.backup/rsc/response-route-handler.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Response Route Handler
+ *
+ * Handles response routes (JSON, text, HTML, XML, markdown, image, stream)
+ * that bypass the RSC rendering pipeline entirely. Includes content-type
+ * dispatch, route middleware execution, and response caching with SWR.
+ */
+import type { MiddlewareFn } from "../router/middleware.js";
+import type { EntryData } from "../server/context.js";
+import type { HandlerContext } from "./handler-context.js";
+export interface ResponseRouteMatch {
+    responseType: string;
+    handler: Function;
+    params?: Record<string, string>;
+    negotiated?: boolean;
+    manifestEntry?: EntryData;
+    routeMiddleware?: Array<{
+        handler: MiddlewareFn;
+        params: Record<string, string>;
+    }>;
+}
+/**
+ * Handle a response route (non-RSC). Dispatches by content type, wraps
+ * with route middleware and response caching when configured.
+ *
+ * For partial (client-side navigation) requests, returns X-RSC-Reload
+ * so the browser triggers a hard navigation to the response route URL.
+ */
+export declare function handleResponseRoute<TEnv>(handlerCtx: HandlerContext<TEnv>, preview: ResponseRouteMatch, request: Request, env: TEnv, url: URL, variables: Record<string, any>): Promise<Response>;

package/dist/types.backup/rsc/rsc-rendering.d.ts

@@ -0,0 +1,23 @@
+/**
+ * RSC Rendering Handler (Navigation)
+ *
+ * Handles RSC rendering for both partial (client-side navigation) and full
+ * (initial page load) requests. Includes prerender collection for build-time
+ * static generation.
+ */
+import { getRequestContext } from "../server/request-context.js";
+import type { HandlerContext } from "./handler-context.js";
+export declare function handleRscRendering<TEnv>(ctx: HandlerContext<TEnv>, request: Request, env: TEnv, url: URL, isPartial: boolean, handleStore: ReturnType<typeof getRequestContext>["_handleStore"], nonce: string | undefined): Promise<Response>;
+/**
+ * Neutralize the shell-HIT degradation redirect target.
+ *
+ * The inline `location.replace` emitted by serveShellHit when a shell HIT lands
+ * on a URL whose route became redirecting mid-TTL is a document-native redirect
+ * exit that BYPASSES the 3xx chokepoint (guardOutgoingRedirect acts only on 3xx
+ * + Location responses, never a committed 200 body). So it reuses the ONE
+ * same-origin resolver directly: a cross-origin/unparseable/unsafe target
+ * neutralizes to the same safe same-origin landing as redirect-guard.ts
+ * (basename root, or "/" when unset) rather than navigating the user off-host.
+ * A safe same-origin/relative target passes through as its normalized href.
+ */
+export declare function resolveShellHitRedirectTarget(rawTarget: string, requestOrigin: string, basename: string | undefined): string;

package/dist/types.backup/rsc/runtime-warnings.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Runtime guardrail warnings (dev-only).
+ *
+ * W3: PE action redirect / Response handling.
+ */
+/**
+ * Extract a redirect Response from a thrown or returned value.
+ * Returns a redirect Response to send to the client, or null if the value
+ * is not a redirect Response.
+ */
+export declare function extractRedirectResponse(value: unknown): Response | null;
+/**
+ * Warn when a non-redirect Response is returned from an action during PE.
+ */
+export declare function warnNonRedirectPeResponse(): void;
+/**
+ * Warn when a non-redirect Response is returned (not thrown) from an action
+ * on the JS (fetch) path. A raw Response cannot be serialized into Flight, so
+ * it is discarded — mirroring the PE path. Use `throw redirect('/path')` for
+ * redirects.
+ */
+export declare function warnNonRedirectActionResponse(actionId: string): void;