@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.1

package/dist/types/outlet-provider.d.ts

@@ -0,0 +1,12 @@
+import { type ReactNode } from "react";
+import type { ResolvedSegment } from "./types.js";
+/**
+ * Outlet content provider — stores parent context for useLoader chain walking.
+ */
+export declare function OutletProvider({ content, parallel, segment, loaderData, children, }: {
+    content: ReactNode;
+    parallel?: ResolvedSegment[];
+    segment?: ResolvedSegment;
+    loaderData?: Record<string, any>;
+    children: ReactNode;
+}): ReactNode;

package/dist/types/prerender/build-shell-capture.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Producer B: build-time PPR shell capture for Prerender+ppr routes (#699).
+ *
+ * Runs in the RSC realm of the build's temp server, AFTER all bundles are
+ * written (the prelude embeds built client asset URLs — bootstrap module,
+ * chunk preloads — that only exist post-client-build). The capture core is
+ * producer A's, verbatim: deriveShellCaptureContext (mask funnel, liveness,
+ * snapshot recording, implicit doc-cache scope) + captureAndStoreShell (gates,
+ * quiesce, tags union, putShell barrier). Build capture first replays global
+ * and route middleware with a synthetic build request context
+ * (`ctx.build === true`, inert `ctx.waitUntil()`); middleware can seed vars or
+ * call `ctx.dynamic()` to skip this URL. The sink is an entry collector instead
+ * of a runtime store.
+ *
+ * The capture's match() re-enters withCacheLookup, HITs the in-realm prerender
+ * store seeded from the just-collected Flight payloads, and REPLAYS the
+ * build-time segments — no handler execution, exactly the runtime composition
+ * path (#697). Live-lane loaders mask into holes; bake-lane loaders execute
+ * under the build context and refuse the capture if they reject or read
+ * identity, the same eligibility rules as at runtime.
+ */
+import type { ShellCacheEntry } from "../cache/types.js";
+import type { SSRModule } from "../rsc/types.js";
+import { type ResolvedPprConfig } from "../rsc/shell-serve.js";
+/**
+ * Normalize a collected truthy `ppr` path option into the SAME concrete
+ * policy the runtime serve path derives — through resolvePprConfig itself,
+ * over a synthetic route entry — so the build-stamped ttl default can never
+ * drift from the serve-side one.
+ */
+export declare function resolveBuildPprConfig(ppr: true | {
+    ttl?: number;
+    swr?: number;
+    tags?: string[];
+    captureTimeout?: number;
+}): ResolvedPprConfig;
+export interface BuildShellCaptureOptions {
+    /** The router instance (from RouterRegistry in the same realm). */
+    router: any;
+    /** Concrete URL path to capture (e.g. "/pp/alpha"). */
+    urlPath: string;
+    /**
+     * The candidate's trie route key. The capture's match() must land on THIS
+     * route: the phase sweeps every registered router, and a router that does
+     * not own the URL matches something else (its catch-all, a 404 shape) —
+     * that capture must not be baked.
+     */
+    routeName: string;
+    /** Shell store key to stamp into the descriptor (host-free at build). */
+    key: string;
+    ttl?: number;
+    swr?: number;
+    /** The route's static ppr.tags (the capture unions render-recorded tags). */
+    tags?: string[];
+    /**
+     * The route's resolved snapshot size cap (ResolvedPprConfig.maxSnapshotBytes)
+     * — build captures apply the same over-cap skip as runtime captures, so a
+     * raised per-route cap behaves identically across both producers.
+     */
+    maxSnapshotBytes?: number;
+    /**
+     * The route's `ppr.captureTimeout` (ms) — producer B honors the same settle
+     * budget as the runtime capture. Build has no waitUntil lifetime bound, so
+     * the option is the only ceiling here.
+     */
+    captureTimeout?: number;
+    /** Build-time env bindings (rango plugin buildEnv), if configured. */
+    buildEnv?: unknown;
+    /**
+     * The MAIN build's version (the version plugin's value folded into the
+     * shipped worker) — NOT the temp server's own version-plugin value. The
+     * serve-side isValidShellHit gate compares entry.buildVersion against the
+     * running worker's ctx.version; stamping the temp server's would make every
+     * build entry an eternal MISS.
+     */
+    buildVersion: string;
+    /**
+     * The SSR half, composed by the plugin from the temp server's SSR
+     * environment runner (react-dom/static prerender + Flight client), with the
+     * bootstrap script content overridden to the BUILT client entry URL.
+     */
+    captureShellHTML: NonNullable<SSRModule["captureShellHTML"]>;
+    /** Verbose per-attempt breadcrumbs (build log). */
+    debug?: boolean;
+}
+export interface BuildShellCaptureResult {
+    outcome: "stored" | "no-shell" | "redirect" | "refused"
+    /** Middleware/handler opted this URL out of PPR shell capture. */
+     | "dynamic"
+    /** The router swept does not own this URL — try the next one. */
+     | "route-mismatch";
+    /** Present iff outcome === "stored". */
+    entry?: ShellCacheEntry;
+    /** The putShell-barrier tag union (static ppr.tags + render-recorded). */
+    tags?: string[];
+    /** On route-mismatch: what this router's match actually landed on. */
+    matchedRouteName?: string;
+}
+/**
+ * Capture the PPR shell for one prerendered URL at build time. Retries once
+ * in place on `no-shell` (the first attempt warms the temp server's SSR/Flight
+ * transform graph, mirroring producer A's cold-start retry — same delay).
+ */
+export declare function captureShellForBuild(opts: BuildShellCaptureOptions): Promise<BuildShellCaptureResult>;

package/dist/types/prerender/param-hash.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Deterministic param hashing for prerender storage keys.
+ * Used at build time and runtime; both must produce identical hashes.
+ * DJB2-based; works in all JS environments without crypto imports.
+ */
+export declare function hashParams(params: Record<string, string>): string;

package/dist/types/prerender/shell-manifest-key.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Build shell manifest key, shared by the producer (the build's shell
+ * prerender phase, vite/discovery/shell-prerender-phase.ts) and the consumer
+ * (the runtime read-through, rsc/shell-build-manifest.ts) so the format
+ * cannot drift. Dependency-free: the producer runs node-side in the plugin,
+ * the consumer in the RSC runtime.
+ *
+ * PATHNAME-ONLY by design. Host-free because the build knows no request
+ * host. Router-free because the router id ($$id) is a hash of
+ * filePath:lineNumber of the TRANSFORMED source, which differs between the
+ * discovery temp server's dev-style transform chain and the main build's —
+ * a temp-realm router id can never be looked up by the shipped worker. The
+ * producer instead detects pathname collisions across routers at build time
+ * and declines both entries (loudly), keeping the key unambiguous. This is
+ * a manifest namespace, never a store keyspace: the runtime shell key
+ * (host + pathname + search + ":shell") stays untouched.
+ */
+export declare function buildShellManifestKey(pathname: string): string;

package/dist/types/prerender/store.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Prerender Store — reads pre-rendered segment data from the worker bundle.
+ * Manifest module (injected via globalThis.__loadPrerenderManifestModule)
+ * contains key-to-specifier map and loadPrerenderAsset for import() resolution.
+ */
+import type { SerializedSegmentData } from "../cache/types.js";
+export interface PrerenderEntry {
+    segments: SerializedSegmentData[];
+    /** RSC-encoded handle map (see handle-snapshot.ts encodeHandles); "" when the
+     *  route pushed no handles. Encoded so Promise/ReactNode handle values survive
+     *  the JSON-serialized build artifact / dev wire, identical to the runtime cache. */
+    handles: string;
+}
+export interface PrerenderStore {
+    get(routeName: string, paramHash: string, meta?: {
+        pathname: string;
+        isPassthroughRoute?: boolean;
+    }): PrerenderEntry | null | Promise<PrerenderEntry | null>;
+}
+export interface StaticEntry {
+    encoded: string;
+    /** RSC-encoded single-segment handle data (see encodeHandleValue); "" when the
+     *  Static handler pushed no handles. */
+    handles: string;
+}
+export interface StaticStore {
+    get(handlerId: string): Promise<StaticEntry | null>;
+}
+interface PrerenderManifestModule {
+    default: Record<string, string>;
+    loadPrerenderAsset: (specifier: string) => Promise<{
+        default: PrerenderEntry;
+    }>;
+}
+declare global {
+    var __loadPrerenderManifestModule: (() => Promise<PrerenderManifestModule>) | undefined;
+    var __STATIC_MANIFEST: Record<string, () => Promise<{
+        default: string | StaticEntry;
+    }>> | undefined;
+    var __loadStaticManifestModule: (() => Promise<unknown>) | undefined;
+    var __PRERENDER_DEV_URL: string | undefined;
+}
+/**
+ * Create a dev-mode prerender store that fetches on-demand from the
+ * Vite dev server's /__rsc_prerender endpoint (runs in Node.js where
+ * node:fs works, unlike workerd).
+ */
+export declare function createDevPrerenderStore(devUrl: string): PrerenderStore;
+/**
+ * Create a prerender store.
+ * Dev mode: on-demand fetch from Vite dev server (node:fs works there).
+ * Production: backed by globalThis.__loadPrerenderManifestModule which lazily
+ * loads the manifest module on first access.
+ * Returns null if no prerender data is available.
+ */
+export declare function createPrerenderStore(): PrerenderStore | null;
+/**
+ * Create a static segment store.
+ * Production only: backed by globalThis.__STATIC_MANIFEST injected at build time.
+ * Returns null if no static data is available (dev mode or no Static handlers).
+ */
+export declare function createStaticStore(): StaticStore | null;
+export {};

package/dist/types/prerender.d.ts

@@ -0,0 +1,292 @@
+/**
+ * Pre-render handler definition for build-time rendering of route segments.
+ *
+ * Prerender wraps a handler so that in production (phase 2)
+ * it can be pre-rendered at build time and served as a static Flight payload.
+ * In dev mode (phase 1), it behaves as a normal handler — the handler runs
+ * on every request just like a regular path() handler.
+ *
+ * The $$id is auto-generated by the Vite exposeInternalIds plugin
+ * based on file path and export name. No manual naming required.
+ *
+ * @example
+ * ```ts
+ * // Static page — no params
+ * export const DocsPage = Prerender(async (ctx) => {
+ *   return <div>Documentation</div>;
+ * });
+ *
+ * // Dynamic page — params first, handler second
+ * export const DocsArticle = Prerender(
+ *   async () => [{ slug: "getting-started" }, { slug: "api-reference" }],
+ *   async (ctx) => {
+ *     return <div>{ctx.params.slug}</div>;
+ *   }
+ * );
+ * ```
+ */
+import type { ReactNode } from "react";
+import type { Handler, HandlerContext, DefaultEnv, ExtractParams } from "./types.js";
+import type { Handle } from "./handle.js";
+import type { HandlePush } from "./defer.js";
+import type { ContextVar } from "./context-var.js";
+import type { ReverseFunction } from "./reverse.js";
+import type { DefaultReverseRouteMap } from "./types/global-namespace.js";
+import type { UseItems, HandlerUseItem } from "./route-types.js";
+/**
+ * Reverse function for build contexts (BuildContext, StaticBuildContext, GetParamsContext).
+ * Global names get full autocomplete and param validation from the generated route map.
+ * Local `.name` calls are accepted but not validated (the include() scope is unknown
+ * at the type level).
+ */
+type BuildReverseFunction = [DefaultReverseRouteMap] extends [
+    Record<string, string>
+] ? (name: string, params?: Record<string, string>, search?: Record<string, unknown>) => string : // Generated route map available — typed globals + permissive locals
+ReverseFunction<DefaultReverseRouteMap> & {
+    (name: `.${string}`, params?: Record<string, string>, search?: Record<string, unknown>): string;
+};
+/**
+ * Default route map for Prerender named route resolution.
+ * Uses GeneratedRouteMap (from gen file) to avoid circular dependencies.
+ */
+type DefaultPrerenderRouteMap = keyof Rango.GeneratedRouteMap extends never ? {} : Rango.GeneratedRouteMap;
+/** Extract params from a route map entry (string pattern or { path } object). */
+type ExtractParamsFromEntry<TEntry> = TEntry extends string ? ExtractParams<TEntry> : TEntry extends {
+    readonly path: infer P extends string;
+} ? ExtractParams<P> : Record<string, string>;
+/**
+ * Resolve params from Prerender's type parameter.
+ * Accepts named routes (global or .local) and explicit param objects.
+ *
+ * Resolution order:
+ * 1. ".local" string → look up in TRouteMap
+ * 2. Global route name string → look up in DefaultPrerenderRouteMap
+ * 3. Record<string, any> object → use as-is (explicit params)
+ * 4. Fallback → {}
+ */
+type ResolvePrerenderParams<T, TRouteMap extends {} = DefaultPrerenderRouteMap> = T extends `.${infer Local}` ? Local extends keyof TRouteMap ? ExtractParamsFromEntry<TRouteMap[Local]> : Record<string, string> : T extends keyof DefaultPrerenderRouteMap ? ExtractParamsFromEntry<DefaultPrerenderRouteMap[T]> : T extends Record<string, any> ? T : {};
+export interface PrerenderOptions {
+    /**
+     * Maximum number of param sets to render in parallel (default: 1).
+     * Only applies to dynamic Prerender handlers with getParams().
+     * Set to higher values to speed up builds with many routes.
+     *
+     * @example
+     * ```typescript
+     * export const BlogPost = Prerender(
+     *   async () => allPosts.map(p => ({ slug: p.slug })),
+     *   async (ctx) => <PostPage slug={ctx.params.slug} />,
+     *   { concurrency: 4 },
+     * );
+     * ```
+     */
+    concurrency?: number;
+}
+/**
+ * Context passed to Prerender() handlers at build time.
+ * Has a synthetic URL from getParams, params, pathname, and optionally env.
+ * No request, headers, cookies.
+ */
+export interface BuildContext<TParams> {
+    /** Params extracted from the route pattern (populated from getParams). */
+    params: TParams;
+    /** True during build-time pre-rendering, false during passthrough live render. */
+    build: true;
+    /**
+     * True when running in Vite dev mode (on-demand prerender), false during
+     * production `vite build`. Use this to branch on runtime mode without
+     * changing build semantics.
+     */
+    dev: boolean;
+    /**
+     * Build-time environment bindings (KV, D1, etc.) supplied by the Vite plugin.
+     * Only available when `buildEnv` is configured in rango() options.
+     * Throws with a clear error if not configured.
+     *
+     * This is NOT the live request env — it is shared across all prerender
+     * invocations for the build.
+     */
+    env: DefaultEnv;
+    /** Read a variable set by getParams or a parent handler. */
+    get: {
+        <T>(contextVar: ContextVar<T>): T | undefined;
+        (key: string): any;
+    };
+    /** Set a variable readable by child layouts and parallels. */
+    set: {
+        <T>(contextVar: ContextVar<T>, value: T): void;
+        (key: string, value: any): void;
+    };
+    /**
+     * Push handle data (frozen into pre-rendered output at build time). Returns
+     * the full push function, including `.defer()` — a deferred slot resolved by
+     * a deep async component during the prerender render is awaited before the
+     * artifact is baked (resolve-by-default), so the baked output holds the
+     * resolved value.
+     */
+    use: <T>(handle: Handle<T>) => HandlePush<T>;
+    /** Synthetic URL built from pattern + params (no real request). */
+    url: URL;
+    /** Pathname portion of the synthetic URL. */
+    pathname: string;
+    /** URLSearchParams from the synthetic URL (always empty for prerender). */
+    searchParams: URLSearchParams;
+    /** Typed search params — always {} for prerender (no real query string). */
+    search: {};
+    /** URL generation by route name. */
+    reverse: BuildReverseFunction;
+    /**
+     * Signal that this param set should not produce a local prerender artifact.
+     * At runtime the live handler runs instead. Only valid on routes wrapped
+     * with `Passthrough()`.
+     */
+    passthrough: () => PrerenderPassthroughResult;
+}
+/**
+ * Context passed to Static() handlers at build time.
+ * No URL, no params, no pathname — just renders content.
+ */
+export interface StaticBuildContext {
+    /** Always true for Static handlers at build time. */
+    build: true;
+    /**
+     * True when running in Vite dev mode, false during production build.
+     */
+    dev: boolean;
+    /**
+     * Build-time environment bindings supplied by the Vite plugin.
+     * Only available when `buildEnv` is configured in rango() options.
+     */
+    env: DefaultEnv;
+    /** Read a variable (available for type consistency with BuildContext). */
+    get: {
+        <T>(contextVar: ContextVar<T>): T | undefined;
+        (key: string): any;
+    };
+    /** Set a variable (available for type consistency with BuildContext). */
+    set: {
+        <T>(contextVar: ContextVar<T>, value: T): void;
+        (key: string, value: any): void;
+    };
+    /**
+     * Push handle data (frozen into pre-rendered output at build time). Returns
+     * the full push function, including `.defer()` — a deferred slot resolved by
+     * a deep async component during the prerender render is awaited before the
+     * artifact is baked (resolve-by-default), so the baked output holds the
+     * resolved value.
+     */
+    use: <T>(handle: Handle<T>) => HandlePush<T>;
+    /** URL generation by route name. */
+    reverse: BuildReverseFunction;
+}
+/**
+ * Context passed to getParams() at build time.
+ * Allows sharing data with handler invocations via set().
+ */
+export interface GetParamsContext {
+    /** Always true during build-time getParams execution. */
+    build: true;
+    /**
+     * True when running in Vite dev mode, false during production build.
+     */
+    dev: boolean;
+    /**
+     * Build-time environment bindings supplied by the Vite plugin.
+     * Only available when `buildEnv` is configured in rango() options.
+     */
+    env: DefaultEnv;
+    /** Set a variable that will be available to each handler invocation via ctx.get(). */
+    set: {
+        <T>(contextVar: ContextVar<T>, value: T): void;
+        (key: string, value: any): void;
+    };
+    /** URL generation by route name. */
+    reverse: BuildReverseFunction;
+}
+export interface PrerenderHandlerDefinition<TParams extends Record<string, any> = any> {
+    readonly __brand: "prerenderHandler";
+    /** Auto-generated unique ID (injected by Vite plugin). */
+    $$id: string;
+    /** In dev mode, the actual handler function that path() can call. */
+    handler: Handler<TParams>;
+    /** Returns the list of param objects to pre-render (dynamic routes). */
+    getParams?: (ctx: GetParamsContext) => Promise<TParams[]> | TParams[];
+    /** Pre-render options. */
+    options?: PrerenderOptions;
+    /** Composable default DSL items merged when the handler is mounted. */
+    use?: () => UseItems<HandlerUseItem>;
+}
+export declare function Prerender<T extends keyof DefaultPrerenderRouteMap | `.${keyof TRouteMap & string}` | Record<string, any> = {}, TRouteMap extends {} = DefaultPrerenderRouteMap>(handler: (ctx: BuildContext<ResolvePrerenderParams<T, TRouteMap>>) => ReactNode | PrerenderPassthroughResult | Promise<ReactNode | PrerenderPassthroughResult>, options?: PrerenderOptions, __injectedId?: string): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
+export declare function Prerender<T extends keyof DefaultPrerenderRouteMap | `.${keyof TRouteMap & string}` | Record<string, any>, TRouteMap extends {} = DefaultPrerenderRouteMap>(getParams: (ctx: GetParamsContext) => Promise<ResolvePrerenderParams<T, TRouteMap>[]> | ResolvePrerenderParams<T, TRouteMap>[], handler: (ctx: BuildContext<ResolvePrerenderParams<T, TRouteMap>>) => ReactNode | PrerenderPassthroughResult | Promise<ReactNode | PrerenderPassthroughResult>, options?: PrerenderOptions, __injectedId?: string): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
+/**
+ * Sentinel returned by `ctx.passthrough()` to signal that a specific param set
+ * should not produce a local prerender artifact. The build skips writing the
+ * entry; at runtime the Passthrough live handler runs instead.
+ */
+export declare const PRERENDER_PASSTHROUGH: Readonly<{
+    __brand: "prerenderPassthrough";
+}>;
+export type PrerenderPassthroughResult = typeof PRERENDER_PASSTHROUGH;
+/**
+ * Type guard to check if a value is the passthrough sentinel.
+ */
+export declare function isPrerenderPassthrough(value: unknown): value is PrerenderPassthroughResult;
+/**
+ * Detect whether any resolved segment carries the passthrough sentinel.
+ *
+ * A build handler signals passthrough by returning `ctx.passthrough()` (the
+ * PRERENDER_PASSTHROUGH sentinel), which lands on the segment's `component`.
+ * But when the route declares `loading()`, the handler result is deferred
+ * upstream (segment-resolution/fresh.ts), so `component` is a thenable resolving
+ * to the sentinel rather than the sentinel itself — a synchronous
+ * `isPrerenderPassthrough(component)` on the Promise returns false and the build
+ * bakes a corrupt artifact instead of deferring. Resolve thenables first.
+ *
+ * Rejections are swallowed here: a throwing build handler resurfaces during
+ * segment serialization, preserving the prior error-handling behavior.
+ */
+export declare function detectPrerenderPassthrough(segments: ReadonlyArray<{
+    component: unknown;
+}>): Promise<boolean>;
+/**
+ * Type guard to check if a value is a PrerenderHandlerDefinition.
+ */
+export declare function isPrerenderHandler(value: unknown): value is PrerenderHandlerDefinition;
+/**
+ * A prerender route with a live fallback handler for unknown params at runtime.
+ *
+ * Wraps a `Prerender(...)` definition with a separate handler that runs at
+ * request time for params not covered by `getParams()`.
+ *
+ * - Build time: `prerenderDef` provides getParams + build handler.
+ * - Runtime: `liveHandler` runs for unknown params with full HandlerContext.
+ *
+ * @example
+ * ```ts
+ * const BlogPrerender = Prerender(
+ *   async () => [{ slug: "getting-started" }, { slug: "api-reference" }],
+ *   async (ctx) => <BlogPost slug={ctx.params.slug} />,
+ * );
+ *
+ * // In route definition:
+ * path("/blog/:slug", Passthrough(BlogPrerender, async (ctx) => {
+ *   const post = await ctx.env.DB.get(ctx.params.slug);
+ *   return <BlogPost slug={ctx.params.slug} post={post} />;
+ * }))
+ * ```
+ */
+export interface PassthroughHandlerDefinition<TParams extends Record<string, any> = any, TEnv = DefaultEnv> {
+    readonly __brand: "passthroughHandler";
+    /** The underlying prerender definition (build-time rendering). */
+    prerenderDef: PrerenderHandlerDefinition<TParams>;
+    /** Live handler for runtime fallback on unknown params. */
+    liveHandler: (ctx: HandlerContext<TParams, TEnv>) => ReactNode | Response | Promise<ReactNode | Response>;
+    /** Composable default DSL items merged when the handler is mounted. */
+    use?: () => UseItems<HandlerUseItem>;
+}
+export declare function Passthrough<TParams extends Record<string, any>, TEnv = DefaultEnv>(prerenderDef: PrerenderHandlerDefinition<TParams>, liveHandler: (ctx: HandlerContext<TParams, TEnv>) => ReactNode | Response | Promise<ReactNode | Response>): PassthroughHandlerDefinition<TParams, TEnv>;
+/**
+ * Type guard to check if a value is a PassthroughHandlerDefinition.
+ */
+export declare function isPassthroughHandler(value: unknown): value is PassthroughHandlerDefinition;
+export {};

package/dist/types/redirect-origin.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Runtime-neutral same-origin redirect rule.
+ *
+ * Shared by the client redirect guard (`browser/validate-redirect-origin.ts`,
+ * which validates redirect targets the client JS is about to navigate to), the
+ * server outgoing 3xx guard (`rsc/redirect-guard.ts`, which validates every
+ * browser-followed `Location` header before it leaves the handler), and soft
+ * Flight / `X-RSC-Redirect` construction (`resolveSoftRedirectUrl`). Kept at
+ * the `src/` root so every layer imports the ONE rule and cannot drift -- a
+ * cross-origin target blocked on the JS/fetch path is blocked identically on the
+ * no-JS (PE), full-page document, and soft SPA channels.
+ */
+/**
+ * Resolve a redirect target against the current origin.
+ *
+ * Returns the canonical (normalized) same-origin href -- which also collapses
+ * protocol-relative (`//evil.com`) and other ambiguous forms -- or `null` when
+ * the target resolves to a different origin or is unparseable. Pure: no logging,
+ * no side effects.
+ */
+export declare function resolveSameOriginRedirect(url: string, currentOrigin: string): string | null;
+/**
+ * Validate an explicit off-origin redirect target (`redirect(url, { external:
+ * true })`).
+ *
+ * `external` opts out of the same-origin rule, but NOT out of scheme safety:
+ * only `http:`/`https:` targets are allowed. A redirect ultimately reaches the
+ * browser via `window.location.assign()` on the SPA/action client paths, so a
+ * forged or mistaken `redirect("javascript:...", { external: true })` would be a
+ * scriptable navigation if the scheme were not checked here. Returns the
+ * normalized href for an http(s) target (same- or cross-origin), or `null`
+ * otherwise. Pure: no logging, no side effects.
+ */
+export declare function resolveExternalRedirect(url: string, currentOrigin: string): string | null;
+/**
+ * The safe same-origin landing for a blocked redirect.
+ *
+ * Every guard that neutralizes a cross-origin/unsafe redirect target sends the
+ * browser here instead: the app's basename root, or `"/"` when unset. Kept
+ * beside the resolvers so the "where does a blocked redirect go" answer lives
+ * in ONE place -- the server 3xx guard (`rsc/redirect-guard.ts`), the
+ * shell-HIT degradation path (`rsc/rsc-rendering.ts`), and soft Flight/
+ * X-RSC-Redirect construction must agree, or a blocked redirect lands
+ * differently depending on which exit it took.
+ */
+export declare function safeSameOriginLanding(basename: string | undefined): string;
+/**
+ * Resolve a soft (SPA/Flight) redirect target before it leaves the server.
+ *
+ * Soft redirects are 200/204 (`X-RSC-Redirect` / `metadata.redirect`), not 3xx,
+ * so they never hit `guardOutgoingRedirect`. This applies the same policy the
+ * 3xx guard uses: same-origin by default, `external` opts into http(s)-only
+ * off-host, anything else lands on {@link safeSameOriginLanding}. Returns the
+ * URL that should be written into the soft-redirect wire fields.
+ */
+export declare function resolveSoftRedirectUrl(url: string, requestOrigin: string, basename: string | undefined, external?: boolean): string;
+/** Brand a Response as an explicit `{ external: true }` redirect (out-of-band). */
+export declare function markExternalRedirect(response: Response): void;
+/** Read the out-of-band `{ external: true }` brand off a Response. */
+export declare function isExternalRedirect(response: Response): boolean;
+/**
+ * Reserved internal header name. No longer a trust signal -- the external
+ * opt-in is the out-of-band brand above. It is kept only so the redirect-rebuild
+ * paths and the guard can defensively strip any value (e.g. one forged by a
+ * proxied upstream) and guarantee it never reaches the browser.
+ */
+export declare const EXTERNAL_REDIRECT_MARKER: string;

package/dist/types/regex-escape.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Escape a string for literal use inside a RegExp. Single source of truth for
+ * the router runtime (matching) and the vite build (transform/scan); a pure,
+ * dependency-free leaf so both environments can share it.
+ */
+export declare function escapeRegExp(input: string): string;

package/dist/types/render-error-thrower.d.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from "react";
+interface RenderErrorThrowerProps {
+    error: unknown;
+}
+/**
+ * Client component that throws the given error during render, so the nearest
+ * error boundary catches it. Errors thrown during render are caught by error
+ * boundaries; async errors (rejected promises) are not -- which is why the
+ * navigation bridge funnels processing failures through this component instead
+ * of letting them surface as uncaught rejections.
+ */
+export declare function RenderErrorThrower({ error, }: RenderErrorThrowerProps): ReactNode;
+export {};

package/dist/types/response-utils.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Runtime-neutral Response shape utilities.
+ *
+ * Kept at the src/ root so both `router/` and `rsc/` can depend on it
+ * without creating a cross-layer import cycle.
+ */
+/**
+ * True when a Response represents a WebSocket upgrade handoff and must not
+ * be reconstructed or mutated:
+ *
+ * - Status 101 (Switching Protocols) is outside the standard Response
+ *   constructor's 200–599 range, so `new Response(body, { status: 101 })`
+ *   throws RangeError on Node/undici and any spec-compliant runtime.
+ * - Cloudflare's workerd attaches a non-standard `webSocket` property on
+ *   the upgrade Response (e.g. from `acceptWebSocket`/`handleWebSocketUpgrade`
+ *   or the `agents` library's `routeAgentRequest`). That property is dropped
+ *   by a `new Response(...)` copy, breaking the upgrade even on workerd
+ *   where the status range is relaxed.
+ *
+ * Callers should short-circuit header/body merges for these responses.
+ */
+export declare function isWebSocketUpgradeResponse(response: Response): boolean;
+/**
+ * Append `Accept` to a response's `Vary` header without duplicating it.
+ *
+ * Content-negotiated responses already carry `Vary: Accept` from the
+ * upstream layer (response-route-handler's callHandlerWithVary, or
+ * handleRscRendering baking `accept` into its vary list). The negotiated
+ * post-append in the handler would otherwise emit `Vary: Accept, Accept`,
+ * a redundant token some proxies/CDNs treat as a distinct cache key.
+ * Token match is case-insensitive (HTTP field tokens are case-insensitive)
+ * and whitespace-tolerant.
+ */
+export declare function appendVaryAccept(response: Response): void;
+export declare function isRedirectResponse(response: Response): boolean;