@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/dist/types/router/types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Router Internal Types
+ *
+ * Shared types for router module utilities.
+ */
+import type { ReactNode } from "react";
+import type { EntryData, InterceptEntry, InterceptSelectorContext } from "../server/context";
+import type { ErrorPhase, LoaderDataResult, ResolvedSegment, ErrorBoundaryHandler, NotFoundBoundaryHandler } from "../types";
+export interface SegmentRevalidationResult {
+    segments: ResolvedSegment[];
+    matchedIds: string[];
+}
+export type ActionContext = {
+    actionId?: string;
+    actionUrl?: URL;
+    actionResult?: any;
+    formData?: FormData;
+};
+export interface SegmentResolutionDeps<TEnv = any> {
+    wrapLoaderPromise: <T>(promise: Promise<T>, entry: EntryData, segmentId: string, pathname: string, errorContext?: {
+        request: Request;
+        url: URL;
+        routeKey?: string;
+        params?: Record<string, string>;
+        env?: TEnv;
+        isPartial?: boolean;
+        requestStartTime?: number;
+    }) => Promise<LoaderDataResult<T>>;
+    trackHandler: <T>(promise: Promise<T>, errorContext?: {
+        segmentId?: string;
+        segmentType?: string;
+    }) => Promise<T>;
+    findNearestErrorBoundary: (entry: EntryData | null) => ReactNode | ErrorBoundaryHandler | null;
+    findNearestNotFoundBoundary: (entry: EntryData | null) => ReactNode | NotFoundBoundaryHandler | null;
+    notFoundComponent?: ReactNode | ((props: {
+        pathname: string;
+    }) => ReactNode);
+    callOnError: (error: unknown, phase: ErrorPhase, context: any) => void;
+    /**
+     * Router-level default for the per-segment `transition({ viewTransition })`
+     * flag, from createRouter({ viewTransition }). Resolved into each segment's
+     * transition config during resolution (only `false` is stamped) so the render
+     * gate reads the boundary decision off the segment on both server and client.
+     * Undefined is treated as "auto" (wrap).
+     */
+    viewTransitionDefault?: "auto" | false;
+}
+export interface MatchApiDeps<TEnv = any> {
+    findMatch: (pathname: string, ms?: any) => any;
+    getMetricsStore: () => any;
+    findInterceptForRoute: (routeKey: string, parentEntry: EntryData | null, selectorContext: InterceptSelectorContext | null, isAction: boolean) => {
+        intercept: InterceptEntry;
+        entry: EntryData;
+    } | null;
+    callOnError: SegmentResolutionDeps<TEnv>["callOnError"];
+    findNearestErrorBoundary: SegmentResolutionDeps<TEnv>["findNearestErrorBoundary"];
+    getRouteMap: () => Record<string, string>;
+}
+export type TitleDescriptor = string | {
+    template: string;
+    default: string;
+} | {
+    absolute: string;
+};
+export type UnsetDescriptor = {
+    unset: string;
+};
+export type MetaDescriptorBase = {
+    charSet: "utf-8";
+} | {
+    title: TitleDescriptor;
+} | {
+    name: string;
+    content: string;
+} | {
+    property: string;
+    content: string;
+} | {
+    httpEquiv: string;
+    content: string;
+} | {
+    "script:ld+json": LdJsonObject;
+} | {
+    tagName: "meta" | "link";
+    [name: string]: string;
+} | UnsetDescriptor | {
+    [name: string]: unknown;
+};
+export type MetaDescriptor = MetaDescriptorBase | Promise<MetaDescriptorBase>;
+type LdJsonObject = {
+    [Key in string]: LdJsonValue;
+} & {
+    [Key in string]?: LdJsonValue | undefined;
+};
+type LdJsonArray = LdJsonValue[] | readonly LdJsonValue[];
+type LdJsonPrimitive = string | number | boolean | null;
+type LdJsonValue = LdJsonPrimitive | LdJsonObject | LdJsonArray;
+export {};

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,49 @@
+/** Bound queued/running capture closures retained by one isolate. */
+export declare const MAX_ADMITTED_CAPTURES: number;
+/** Point-in-time queue occupancy, for capture-scheduling telemetry. */
+export interface CaptureQueueDepths {
+    /** A capture is currently executing (never preempted). */
+    running: boolean;
+    /** Waiting document-priority captures (run before every navigation capture). */
+    document: number;
+    /** Waiting navigation-priority captures. */
+    navigation: number;
+}
+/**
+ * Snapshot the queue's waiting/running state. Wait-timed-out entries still
+ * sitting in the arrays (pruned lazily by takeNextCapture) are excluded — they
+ * will never run, so counting them would overstate the backlog.
+ */
+export declare function captureQueueDepths(): CaptureQueueDepths;
+/** The caller may drop this best-effort capture and retry on a later request. */
+export declare class CaptureQueueFullError extends Error {
+    constructor();
+}
+/**
+ * Budget on how long a capture may WAIT in the queue before it is dropped
+ * instead of run. On workerd a queued capture rides the scheduling request's
+ * waitUntil, whose post-response lifetime is bounded (~30s): a capture that
+ * already burned 15s+ parked behind a slow predecessor would start its own
+ * up-to-15s attempt (captureTimeout) with no budget left and risk being
+ * killed mid-store-write. Dropping at the budget is safe — captures are
+ * best-effort by contract, and a later request re-probes the key (the drop
+ * does NOT mark backoff: the route is not doomed, the isolate was busy).
+ * Matches one attempt's SHELL_CAPTURE_MAX_WAIT_MS so wait + attempt fits the
+ * platform budget. Field-observed: a navigation-shell capture parked ~24s
+ * behind a predecessor's two-attempt cycle.
+ */
+export declare const CAPTURE_QUEUE_WAIT_BUDGET_MS: number;
+/** Thrown (async) when the queue wait exceeded the budget; the task never ran. */
+export declare class CaptureQueueWaitTimeoutError extends Error {
+    readonly waitedMs: number;
+    constructor(waitedMs: number);
+}
+/**
+ * Run `task` after the active capture and every higher/equal-priority capture
+ * ahead of it have 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>, opts?: {
+    maxQueueWaitMs?: number;
+    priority?: "document" | "navigation";
+}): 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,32 @@
+/**
+ * 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;
+    devDiscoveryEpoch?: number;
+    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,127 @@
+/**
+ * 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";
+/**
+ * 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;
+/** Match and stamp params/routeName on the request context as one operation. */
+export declare function matchAndRecordParams<TEnv>(ctx: HandlerContext<TEnv>, request: Request, env: TEnv): Promise<Awaited<ReturnType<HandlerContext<TEnv>["router"]["match"]>>>;

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 every registered URL-pattern mount for
+ * dev/HMR scenarios where the manifest exists but the trie needs rebuilding.
+ */
+/**
+ * Build a fresh route trie from the router's URL-pattern mounts 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;