@rangojs/router 0.22.1 → 0.24.0

package/dist/types/cache/document-cache.d.ts

@@ -13,16 +13,8 @@
  * 4. If miss → run handler, cache if response has cache headers
  */
 import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
-import { type RequestContext } from "../server/request-context.js";
-/**
- * Whether this cache will store the response the current render produces, as
- * far as the render can tell: the middleware runs it (a MISS or a stale
- * refresh) and the response stub already opts in. payloadInitialTheme
- * (rsc/full-payload.ts) then renders the no-cookie default theme (#978). A
- * Cache-Control written after next() is not on the stub yet; for that render
- * shouldCacheResponse refuses a payload marked `_payloadVisitorTheme`.
- */
-export declare function documentCacheStoresRender(reqCtx: Pick<RequestContext, "_documentCacheRender" | "res">): boolean;
+import { documentCacheStoresRender } from "./document-cache-policy.js";
+export { documentCacheStoresRender };
 export interface DocumentCacheOptions<TEnv = any> {
     /**
      * Skip caching for specific paths (e.g., API routes)

package/dist/types/client-urls/client-urls.d.ts

@@ -2,4 +2,4 @@ import type { ClientUrlBuilder, ClientUrlPatterns } from "./types.js";
 import type { ExtractRoutes } from "../urls/type-extraction.js";
 import type { ClientUrlItems } from "./types.js";
 export declare function clientUrls<const TItems extends ClientUrlItems>(builder: ClientUrlBuilder<TItems>): ClientUrlPatterns<ExtractRoutes<TItems>>;
-export type { ClientRevalidateArgs, ClientRevalidateFn, ClientTransitionConfig, ClientUrlBuilder, ClientUrlHelpers, ClientUrlInterceptRecord, ClientUrlItem, ClientUrlItemInput, ClientUrlItems, ClientLayoutFn, ClientPathOptions, ClientUrlLoaderRecord, ClientPathFn, ClientUrlPatterns, ClientUrlRouteRecord, ClientUrlUse, } from "./types.js";
+export type { ClientTransitionConfig, ClientUrlBuilder, ClientUrlHelpers, ClientUrlInterceptRecord, ClientUrlItem, ClientUrlItemInput, ClientUrlItems, ClientLayoutFn, ClientPathOptions, ClientUrlLoaderRecord, ClientPathFn, ClientUrlPatterns, ClientUrlRouteRecord, ClientUrlUse, } from "./types.js";

package/dist/types/client-urls/hoisted-revalidate.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The value the build leaves in place of a clientUrls() `revalidate()`
+ * predicate in the browser and SSR copies of a "use client" module
+ * (vite/plugins/client-urls-revalidate-hoist.ts): the predicate itself moves
+ * to a server module, registered under the same content key
+ * (revalidate-registry.ts). The projection carries the key; the materialized
+ * loader stub calls the registered predicate.
+ */
+export declare const HOISTED_REVALIDATE_KEY = "$$rangoRevalidate";
+export interface HoistedRevalidateRef {
+    readonly $$rangoRevalidate: string;
+}
+export declare function isHoistedRevalidateRef(value: unknown): value is HoistedRevalidateRef;

package/dist/types/client-urls/navigation.d.ts

@@ -46,41 +46,4 @@ export declare function registerClientUrlGroup(definition: ClientUrlPatterns, mo
 export declare function beginClientUrlNavigation(targetUrl: URL, signal: AbortSignal, 
 /** Builds the entry state; called only when the group presents the target. */
 buildState?: () => unknown, decideTransition?: (destination: ClientUrlDestination) => boolean): ClientUrlNavigationPresentation | null;
-/**
- * Run the held clientUrls route's per-loader revalidate() predicates and
- * encode their decisions for the request header. Predicates are CLIENT code
- * (declared in the "use client" definition module); only decisions cross the
- * wire — the synthesized per-loader revalidate() on every materialized stub
- * (server-projection.ts) reads them back by loader $$id.
- *
- * Decisions exist only for the loaders the client currently HOLDS: the local
- * match of currentUrl. They matter when the server would re-evaluate those
- * held loader segments — same-route param/search navs, actions, and stale
- * restores. Cross-route targets render new segments unconditionally, so a
- * decision would be ignored; we still compute against the current route since
- * only its held segments are addressable.
- *
- * Returns null when no group is active, the current location is not a client
- * route, or no predicate produced a decision that differs from the locked
- * default — the server then applies defaults, which is also the behavior for
- * requests that cannot carry decisions (no-JS, PE, prefetch, document loads).
- */
-export declare function collectClientRevalidationDecisions(options: {
-    currentUrl: URL;
-    nextUrl: URL;
-    /**
-     * True only when the decisions ride the action POST itself — the one
-     * request the server evaluates with actionContext (locked default true).
-     * Action-triggered refetch GETs (partial-update terminals) pass false:
-     * the server gives those navigation defaults, and the delta gate below
-     * must diff against the default the SERVER will use, or a force decision
-     * on the refetch would be silently swallowed as "equals default".
-     */
-    actionRequest: boolean;
-    /** Action TRUTH for the predicates' isAction() matcher; may be true on
-     * refetch GETs where actionRequest is false. */
-    isAction: boolean;
-    actionId?: string;
-    stale: boolean;
-}): string | null;
 export declare function clearClientUrlNavigationRegistry(): void;

package/dist/types/client-urls/revalidate-registry.d.ts

@@ -0,0 +1,4 @@
+import type { ShouldRevalidateFn } from "../types.js";
+export declare function registerClientUrlRevalidators(fns: Readonly<Record<string, ShouldRevalidateFn<any, any>>>): void;
+export declare function getClientUrlRevalidator(key: string): ShouldRevalidateFn<any, any> | undefined;
+export declare function clearClientUrlRevalidators(): void;

package/dist/types/client-urls/server-projection.d.ts

@@ -32,6 +32,16 @@ export interface ClientUrlProjectionRoute {
      *  document renders await them before first flush. Absent (= none) in
      *  projections serialized before the option existed. */
     readonly awaitedLoaderIndices?: readonly number[];
+    /** Indices into loaderIds of loaders declared loader(Def, { prefetch:
+     *  false }); materialization passes the option through to the server
+     *  loader(), so a prefetch of the route defers them. Absent (= none) in
+     *  projections serialized before the option existed. */
+    readonly deferrableLoaderIndices?: readonly number[];
+    /** Per loader (aligned with loaderIds), the keys of its hoisted
+     *  revalidate() predicates in declaration order; materialization attaches
+     *  the registered predicates (revalidate-registry.ts). Absent when no
+     *  loader declares one. */
+    readonly loaderRevalidate?: readonly (readonly string[])[];
     /** Data-only transition config (never `when`); absent in projections
      *  serialized before transition support. */
     readonly transition?: Readonly<ClientTransitionConfig>;
@@ -54,7 +64,25 @@ export interface ClientUrlProjection {
      *  must treat missing as empty. */
     readonly intercepts?: readonly ClientUrlProjectionIntercept[];
 }
-export declare function serializeClientUrlPatterns(patterns: ClientUrlPatterns): ClientUrlProjection;
+/** Options for {@link serializeClientUrlPatterns}. */
+export interface SerializeClientUrlPatternsOptions {
+    /**
+     * The definition was loaded through the rango Vite plugin (route
+     * discovery), which moves every revalidate() predicate to the server and
+     * leaves a marker: a plain function then is a site the build could not
+     * see, and fails loudly.
+     */
+    readonly hoisted?: boolean;
+}
+export declare function serializeClientUrlPatterns(patterns: ClientUrlPatterns, options?: SerializeClientUrlPatternsOptions): ClientUrlProjection;
+/**
+ * The projection of a clientUrls() module from its namespace, or undefined
+ * when its default export is not a clientUrls() definition. Discovery
+ * (vite/discovery/client-urls-projection.ts) and the testing "use client"
+ * transform (testing/internal/client-urls-projection.ts) both project a
+ * module through it.
+ */
+export declare function projectClientUrlsModule(namespace: Readonly<Record<string, unknown>>, options?: SerializeClientUrlPatternsOptions): ClientUrlProjection | undefined;
 export declare function isClientUrlPatterns(value: unknown): value is ClientUrlPatterns;
 export declare function isClientUrlReference(value: unknown): value is ClientUrlReference;
 /**

package/dist/types/client-urls/types.d.ts

@@ -1,5 +1,7 @@
 import type { ComponentType, ReactNode } from "react";
-import type { IsActionFn, LoaderDefinition, LoaderOptions, TransitionConfig } from "../types.js";
+import type { LoaderDefinition, LoaderOptions, ShouldRevalidateFn, TransitionConfig } from "../types.js";
+import type { DefaultEnv } from "../types/global-namespace.js";
+import type { HoistedRevalidateRef } from "./hoisted-revalidate.js";
 import type { TrieMatchResult } from "../router/trie-matching.js";
 import type { PathOptions } from "../urls/pattern-types.js";
 import type { SearchSchema } from "../search-params.js";
@@ -18,67 +20,14 @@ export type ClientUrlUse = () => ClientUrlItems;
 export type ClientPathOptions<TName extends string = string, TSearch extends SearchSchema = SearchSchema> = Pick<PathOptions<TName, TSearch>, "name" | "search" | "trailingSlash" | "ppr">;
 export type ClientPathFn = <const TPattern extends string, const TName extends string = UnnamedRoute, const TSearch extends SearchSchema = {}>(pattern: TPattern, component: ComponentType, optionsOrUse?: ClientPathOptions<TName, TSearch> | ClientUrlUse, use?: ClientUrlUse) => ClientUrlItem & TypedRouteItem<TName, TPattern, unknown, TSearch>;
 export type ClientLayoutFn = <const TItems extends ClientUrlItems>(component: ComponentType, children: () => TItems) => ClientUrlItem & TypedLayoutItem<ExtractRoutes<TItems>>;
-/**
- * Arguments a clientUrls() revalidate() predicate receives. A client-computable
- * subset of the server ShouldRevalidateFn args — the predicate RUNS IN THE
- * BROWSER (it is declared in a "use client" module and never crosses the
- * projection boundary); only its decision is sent to the server. There is no
- * `context` — no server handler context exists where this executes. `isAction`
- * is the same callable matcher as on the server, not a boolean.
- */
-export interface ClientRevalidateArgs {
-    /** Full URL of the page being navigated away from (current location). */
-    readonly currentUrl: URL;
-    /** Full URL of the navigation target (equals currentUrl for actions). */
-    readonly nextUrl: URL;
-    /** Route params of the held client route (definition-local match). */
-    readonly currentParams: Record<string, string>;
-    /** Route params for the navigation target (definition-local match). */
-    readonly nextParams: Record<string, string>;
-    /**
-     * The current default decision for this loader, computed client-side with
-     * the same rules the server applies to the request the decisions ride on:
-     * `true` when they ride the action POST itself, otherwise `true` when
-     * params/search changed. (An action-triggered refetch GET gets navigation
-     * defaults — matching the server — even though `isAction()` is true.)
-     * Earlier predicates' `{ defaultShouldRevalidate }` verdicts thread into
-     * this value, exactly like the server chain. Return it for default
-     * behavior plus your own conditions.
-     */
-    readonly defaultShouldRevalidate: boolean;
-    /** True when this is a stale history-entry background revalidation. */
-    readonly stale: boolean;
-    /**
-     * Same {@link IsActionFn} the server `revalidate()` predicate receives.
-     * In the browser the match is against the action stub's hashed `$$id`
-     * (the id the action request carries) — not the RSC file-path `$id`.
-     */
-    readonly isAction: IsActionFn;
-    /**
-     * The triggering server action's id, when this is an action. In the
-     * browser this is the hashed `hash#export` form (`$$id`), not the RSC
-     * file-path `src/...#export`. Prefer `isAction(ref)` — a substring of
-     * `path#export` will not match here in production.
-     */
-    readonly actionId?: string;
-}
-/**
- * Client-run per-loader predicate, with the same chain semantics as the
- * server's `revalidate()` (src/router/revalidation.ts): a boolean is a HARD
- * decision that short-circuits the rest of the chain; a
- * `{ defaultShouldRevalidate }` object updates the running suggestion, which
- * later predicates receive as their `defaultShouldRevalidate`; `void` /
- * `null` / `undefined` defers to the current suggestion — so
- * `isAction(CartActions) || undefined` defers to the locked default.
- * Predicates must be synchronous; the object form requires a boolean value.
- */
-export type ClientRevalidateFn = (args: ClientRevalidateArgs) => boolean | {
-    defaultShouldRevalidate: boolean;
-} | null | void;
 export interface ClientUrlLoaderRecord {
     readonly loader: LoaderDefinition<any, any>;
-    /** Client-run per-loader revalidation predicates; empty = locked defaults. */
-    readonly revalidate: readonly ClientRevalidateFn[];
+    /**
+     * Per-loader revalidate() predicates, run on the server; empty = the
+     * router's defaults. Under the rango Vite plugin the browser and SSR copies
+     * hold the marker the build left in place of each hoisted predicate.
+     */
+    readonly revalidate: readonly (ShouldRevalidateFn<any, DefaultEnv> | HoistedRevalidateRef)[];
     /**
      * loader(Def, { ssr: false }): document renders await this loader before
      * first flush (see {@link LoaderOptions}). Projected into the server tree,
@@ -86,6 +35,14 @@ export interface ClientUrlLoaderRecord {
      * regardless.
      */
     readonly ssr?: false;
+    /**
+     * loader(Def, { prefetch: false }): a prefetch of the route defers this
+     * loader and the click that adopts it runs it in its fill request (see
+     * {@link LoaderOptions}). Projected onto the materialized stub. Inside
+     * intercept() it is not recorded: intercept loaders ignore the flag, as in
+     * urls().
+     */
+    readonly prefetch?: false;
 }
 /**
  * The TransitionConfig subset a clientUrls() route may declare: ViewTransition
@@ -124,8 +81,7 @@ export interface ClientUrlHelpers {
     readonly layout: ClientLayoutFn;
     /**
      * Attach a projected loader. The optional use callback may contain
-     * revalidate() only — a CLIENT-RUN per-loader predicate; its decision (not
-     * the function) is sent with the revalidation request.
+     * revalidate() only: a per-loader predicate the server runs, as in urls().
      *
      * Pass `{ ssr: false }` — the same knob as loading(fallback, { ssr:
      * false }) — to await this loader before first flush on DOCUMENT requests
@@ -135,18 +91,27 @@ export interface ClientUrlHelpers {
      * route the flag BAKES: the loader executes at shell capture and its
      * settled return freezes into the shell (nested promises stay live
      * holes).
+     *
+     * Pass `{ prefetch: false }` to keep this loader out of the route's
+     * prefetches (see {@link LoaderOptions}): an in-group click still shows
+     * the destination at once, commits the adopted prefetch with the other
+     * loaders' data, and runs only the flagged loaders in its one fill
+     * request. A `layout()` loader with the flag is flagged on every route
+     * below it. Inside intercept() the flag is accepted and ignored, as in
+     * urls().
      */
-    readonly loader: <TData>(definition: LoaderDefinition<TData>, optionsOrUse?: LoaderOptions | ClientUrlUse, use?: ClientUrlUse) => ClientUrlItem;
+    readonly loader: <TData>(definition: LoaderDefinition<TData>, optionsOrUse?: Pick<LoaderOptions, "ssr" | "prefetch"> | ClientUrlUse, use?: ClientUrlUse) => ClientUrlItem;
     readonly loading: (component: ReactNode) => ClientUrlItem;
     /**
      * Per-loader revalidation predicate, valid inside a loader() use callback
-     * only. Runs IN THE BROWSER with client-computable args (including the
-     * callable `isAction(...refs)` matcher); return true to re-run the loader,
-     * false to keep held data. Absent predicates (and requests that carry no
-     * decisions: no-JS, PE, prefetch, document loads) follow the locked server
-     * defaults.
+     * only. It runs ON THE SERVER with the same arguments as a urls() loader's
+     * revalidate() (`actionResult`, `formData`, `context`, `isAction`, route
+     * names, ...): the build moves it out of this "use client" module. It may
+     * reference imports and globals only; a binding of this module, `this`,
+     * `import()`, a browser global, an `async` function or an import from a
+     * "use client" module fails the build with its file and line.
      */
-    readonly revalidate: (fn: ClientRevalidateFn) => ClientUrlItem;
+    readonly revalidate: (fn: ShouldRevalidateFn<any, DefaultEnv>) => ClientUrlItem;
     /**
      * Declare an intercept for a named route in THIS definition. The target is
      * dot-local (`.detail`); scoping is module-local — only navigations whose

package/dist/types/client.d.ts

@@ -191,4 +191,3 @@ export { useReverse } from "./browser/react/use-reverse.js";
 export type { ScopedReverseFunction, LocalReverseFunction } from "./reverse.js";
 export type { LoaderDefinition } from "./types.js";
 export type { ActionRef, IsActionFn } from "./types.js";
-export type { ClientRevalidateArgs, ClientRevalidateFn, } from "./client-urls/types.js";

package/dist/types/context-var.d.ts

@@ -68,6 +68,18 @@ export declare function isNonCacheable(variables: any, keyOrVar: string | Contex
  * Accepts either a string key (legacy) or a ContextVar token (typed).
  */
 export declare function contextGet(variables: any, keyOrVar: string | ContextVar<any>): any;
+/**
+ * Keys that must never be used as string variable names, nor as a fetchable
+ * loader's request params (rsc/loader-fetch.ts).
+ */
+export declare const FORBIDDEN_KEYS: ReadonlySet<string>;
+/**
+ * `target[key] = value` as an own data property, `__proto__` included: that
+ * assignment would call Object.prototype's setter and replace the target's
+ * prototype, which Flight refuses to serialize (#1109). Loader data parsed
+ * from JSON, cookie names and the like can carry the key.
+ */
+export declare function assignOwn(target: Record<string, unknown>, key: string, value: unknown): void;
 export interface ContextSetOptions {
     /**
      * When false, marks this specific write as non-cacheable.

package/dist/types/errors.d.ts

@@ -176,6 +176,16 @@ export declare class Skip extends Error {
  * Type guard to check if a thrown value is a Skip signal.
  */
 export declare function isSkip(value: unknown): value is Skip;
+/**
+ * A request middleware rewrote (`throw rewrite()`) more than `maxHops` times,
+ * or to the URL it was on. Reported through `onError` (phase "routing") and
+ * answered with 508. `trail` lists the URLs, the visitor's first.
+ */
+export declare class RewriteLoopError extends Error {
+    name: "RewriteLoopError";
+    readonly trail: readonly string[];
+    constructor(trail: readonly string[], maxHops: number);
+}
 /**
  * Thrown by the partial updater when the server responds with a redirect payload
  * that carries location state. Caught by navigate() to re-navigate to the
@@ -212,6 +222,11 @@ export declare class InvalidHandlerError extends Error {
  * ```
  */
 export declare function invariant(condition: any, message: string): asserts condition;
+/**
+ * Rejects a boolean-only DSL option that holds anything else (undefined
+ * passes), as an invariant.
+ */
+export declare function assertBooleanOption(value: unknown, option: string, effect: string): void;
 /**
  * Sanitize errors for production - prevents leaking sensitive information
  *

package/dist/types/handles/deferred-resolution.d.ts

@@ -24,7 +24,8 @@ export declare function deferredHandleNames(data: HandleData): Set<string>;
  * thenables). A rejected deferred is dropped, and a deferred that resolves to
  * `null`/`undefined` is dropped (the `.defer({ else })` skip semantics), so a
  * nullish deferred slot never reaches a collector. Sync (non-thenable) values —
- * including a legitimate sync `null` push — pass through unchanged.
+ * including a legitimate sync `null` push — pass through unchanged. A
+ * pushedBy record (pushed-by.ts) loses the entries of the dropped values.
  */
 export declare function resolveDeferredHandleValues(data: HandleData): Promise<HandleData>;
 /**

package/dist/types/handles/pushed-by.d.ts

@@ -0,0 +1,31 @@
+import type { HandleData } from "../server/handle-store.js";
+/** The snapshot key holding `handleName`'s pushedBy record. */
+export declare function pushedByKey(handleName: string): string;
+/** True for a pushedBy record's key, false for a handle's. */
+export declare function isPushedByKey(name: string): boolean;
+/** `data` without its pushedBy records, as a reader outside the router sees it. */
+export declare function withoutPushedBy(data: HandleData): HandleData;
+/**
+ * `target` with the buckets of the segments in `ids` taken from `source`.
+ * A pushedBy record is a snapshot key like a handle's, so a bucket's values
+ * and the record of the runs that pushed them always come from the same
+ * snapshot. New containers; the value arrays are shared, as cloneHandleData
+ * (navigation-store.ts) shares them.
+ */
+export declare function withSegmentHandles(target: HandleData, source: HandleData, ids: ReadonlySet<string>): HandleData;
+/**
+ * The handle data after a partial response's snapshot `incoming` (each stream
+ * yield holds everything the response pushed so far). A segment outside
+ * `segmentOrder` loses its buckets. In the others a value stands for the run
+ * that pushed it: the segment's handler, or a loader `matched` registers on
+ * the segment (`${shortCode}D${index}.${$$id}`, a loader's pushes being filed
+ * under its shortCode; an id it does not register, a dependency or a loader a
+ * handler read, counts as the handler's). A run that has values in the
+ * response, or ran for it (`resolvedIds`: the handlers and loaders that ran),
+ * replaces its values with the ones it delivered, nothing when it delivered
+ * none. The other runs keep theirs in place, and the response's values take
+ * the position of the first value they replace (the end when they replace
+ * none). New containers throughout: an object a reader was handed (a history
+ * entry's data) is never written to.
+ */
+export declare function mergePartialHandleData(current: HandleData, incoming: HandleData, segmentOrder: readonly string[], matched: readonly string[], resolvedIds: readonly string[] | undefined): HandleData;

package/dist/types/index.d.ts

@@ -32,6 +32,10 @@ export declare function createRouter(): never;
  * Error-throwing stub for server-only `redirect` function.
  */
 export declare function redirect(): never;
+/**
+ * Error-throwing stub for server-only `rewrite` function.
+ */
+export declare function rewrite(): never;
 export { createHandle, isHandle, type Handle } from "./handle.js";
 export { DEFAULT_DEFER_TIMEOUT_MS, type DeferOptions, type HandlePush, type HandlePushFn, } from "./defer.js";
 export { createVar, type ContextVar } from "./context-var.js";

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

@@ -14,6 +14,8 @@ export type { RangoOptions, SSRStreamMode, SSROptions, ResolveStreamingContext,
 export type { OriginCheckConfig, OriginCheckContext, OriginCheckPhase, } from "./rsc/origin-guard.js";
 export type { ShellCaptureDebug, ShellCaptureDebugEvent, } from "./rsc/shell-capture.js";
 export { createLoader, redirect, type RouteHelpers, type RouteHandlers, layout, cache, middleware, revalidate, loader, loading, parallel, intercept, errorBoundary, notFoundBoundary, transition, } from "./route-definition.js";
+export { rewrite, type Rewrite, type RewriteFunction, } from "./route-definition/rewrite.js";
+export { RewriteLoopError } from "./errors.js";
 export type { RouteUseItem, LayoutUseItem, AllUseItems, UseItems, HandlerUseItem, } from "./route-types.js";
 export { createHandle, isHandle, type Handle } from "./handle.js";
 export { DEFAULT_DEFER_TIMEOUT_MS, type DeferOptions, type HandlePush, type HandlePushFn, } from "./defer.js";

package/dist/types/loader-store.d.ts

@@ -215,6 +215,14 @@ export declare class LoaderStore {
      * awaited before flush. Released as the stream settles, either way.
      */
     trackPendingStream(loaderId: string, stream: Promise<unknown>): void;
+    /**
+     * Stop tracking a stream. trackPendingStream does it as the stream settles;
+     * an abandoned fill's hole (browser/partial-update.ts releaseHoles) never
+     * settles, and
+     * left tracked it would pin the family's held readers on every later
+     * transition.
+     */
+    releasePendingStream(loaderId: string, stream: Promise<unknown>): void;
     /** True while any navigation stream for `loaderId` is still pending. */
     isStreamPending(loaderId: string): boolean;
     /**

package/dist/types/prefetch-markers.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The wire markers of `prefetch: false` (docs/design/prefetch-false.md):
+ * shared by the browser that sends them and the server that reads them
+ * (router/segment-resolution/prefetch-deferral.ts requestKind). Dependency
+ * free, like segment-fragments.ts: the browser must not import the server
+ * module that reads them.
+ */
+/** Request header of a `<Link>` prefetch (browser/prefetch/fetch.ts). */
+export declare const PREFETCH_HEADER = "X-Rango-Prefetch";
+/** Query param of a fill request (browser/navigation-client.ts). */
+export declare const FILL_PARAM = "_rsc_fill";

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

@@ -33,3 +33,10 @@ export declare function isWebSocketUpgradeResponse(response: Response): boolean;
  */
 export declare function appendVaryAccept(response: Response): void;
 export declare function isRedirectResponse(response: Response): boolean;
+/**
+ * Set a header on a response the router hands to the host, skipping a
+ * WebSocket upgrade (its headers are not to be touched) and swallowing the
+ * TypeError of immutable headers (a passed-through platform Response):
+ * instrumentation and debug headers never fail a request.
+ */
+export declare function trySetHeader(response: Response, name: string, value: string): void;

package/dist/types/reverse.d.ts

@@ -93,31 +93,31 @@ export type ReverseFunction<TRoutes> = {
  * reverse("typo")                             // ✗ Compile error (not in global routes)
  * ```
  */
-export type ScopedReverseFunction<TLocalRoutes, TGlobalRoutes = TLocalRoutes> = {
+export type ScopedReverseFunction<TLocalRoutes, TGlobalRoutes = TLocalRoutes, TResult = string> = {
     /**
      * Global route without params
      */
-    <TName extends keyof TGlobalRoutes & string>(name: IsEmptyObject<ExtractParams<RoutePatternFor<TGlobalRoutes, TName>>> extends true ? TName : never): string;
+    <TName extends keyof TGlobalRoutes & string>(name: IsEmptyObject<ExtractParams<RoutePatternFor<TGlobalRoutes, TName>>> extends true ? TName : never): TResult;
     /**
      * Global route with params
      */
-    <TName extends keyof TGlobalRoutes & string>(name: TName, params: ExtractParams<RoutePatternFor<TGlobalRoutes, TName>>): string;
+    <TName extends keyof TGlobalRoutes & string>(name: TName, params: ExtractParams<RoutePatternFor<TGlobalRoutes, TName>>): TResult;
     /**
      * Global route with params and search
      */
-    <TName extends keyof TGlobalRoutes & string>(name: TName, params: ExtractParams<RoutePatternFor<TGlobalRoutes, TName>>, search: ResolveSearchSchema<ExtractSearchSchema<TGlobalRoutes, TName>>): string;
+    <TName extends keyof TGlobalRoutes & string>(name: TName, params: ExtractParams<RoutePatternFor<TGlobalRoutes, TName>>, search: ResolveSearchSchema<ExtractSearchSchema<TGlobalRoutes, TName>>): TResult;
     /**
      * Dot-prefixed local route without params
      */
-    <TName extends keyof TLocalRoutes & string>(name: IsEmptyObject<ExtractParams<RoutePatternFor<TLocalRoutes, TName>>> extends true ? `.${TName}` : never): string;
+    <TName extends keyof TLocalRoutes & string>(name: IsEmptyObject<ExtractParams<RoutePatternFor<TLocalRoutes, TName>>> extends true ? `.${TName}` : never): TResult;
     /**
      * Dot-prefixed local route with params
      */
-    <TName extends keyof TLocalRoutes & string>(name: `.${TName}`, params: ExtractParams<RoutePatternFor<TLocalRoutes, TName>>): string;
+    <TName extends keyof TLocalRoutes & string>(name: `.${TName}`, params: ExtractParams<RoutePatternFor<TLocalRoutes, TName>>): TResult;
     /**
      * Dot-prefixed local route with params and search
      */
-    <TName extends keyof TLocalRoutes & string>(name: `.${TName}`, params: ExtractParams<RoutePatternFor<TLocalRoutes, TName>>, search: ResolveSearchSchema<ExtractSearchSchema<TLocalRoutes, TName>>): string;
+    <TName extends keyof TLocalRoutes & string>(name: `.${TName}`, params: ExtractParams<RoutePatternFor<TLocalRoutes, TName>>, search: ResolveSearchSchema<ExtractSearchSchema<TLocalRoutes, TName>>): TResult;
 };
 /**
  * Reverse function that resolves global route names only: no include() scope,
@@ -147,7 +147,7 @@ export type ScopedReverseFunction<TLocalRoutes, TGlobalRoutes = TLocalRoutes> =
  * reverse(".post", { slug: "hello" })     // compile error: no include() scope
  * ```
  */
-export type GlobalReverseFunction<TGlobalRoutes> = string extends keyof TGlobalRoutes ? <TName extends string>(name: Exclude<TName, `.${string}`>, params?: Record<string, string>, search?: Record<string, unknown>) => string : ScopedReverseFunction<{}, TGlobalRoutes>;
+export type GlobalReverseFunction<TGlobalRoutes, TResult = string> = string extends keyof TGlobalRoutes ? <TName extends string>(name: Exclude<TName, `.${string}`>, params?: Record<string, string>, search?: Record<string, unknown>) => TResult : ScopedReverseFunction<{}, TGlobalRoutes, TResult>;
 /**
  * Extract local routes type from UrlPatterns
  * Used with scopedReverse() to get the routes type from patterns

package/dist/types/route-definition/helpers-types.d.ts

@@ -226,6 +226,16 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      * loader(RecommendationsLoader),  // still streams behind loading()
      * ```
      *
+     * Pass `{ prefetch: false }` to keep the loader out of prefetches: a
+     * prefetch skips it and the click that adopts the prefetch fetches it in
+     * one follow-up request (see {@link LoaderOptions}). Only on a segment the
+     * client does not have yet: a loader the client already holds runs in the
+     * prefetch when it revalidates.
+     *
+     * ```typescript
+     * loader(ReviewsLoader, { prefetch: false }),
+     * ```
+     *
      * @param loaderDef - Loader created with createLoader()
      * @param optionsOrUse - Delivery options, or the use() callback when passing none
      * @param use - Optional callback for loader-specific revalidation rules
@@ -239,13 +249,30 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
      *
      * // Skip loading on SSR, only show on client navigation
      * loading(<Skeleton />, { ssr: false })
+     *
+     * // Keep everything behind this fallback out of prefetches
+     * loading(<Skeleton />, { prefetch: false })
      * ```
      * @param component - The loading UI to show during navigation
      * @param options - Configuration options
      * @param options.ssr - If false, skip showing loading on document requests (SSR)
+     * @param options.prefetch - If false, the flag applies when this entry's
+     *   segment is new to the client. A prefetch then skips the whole unit: the
+     *   handler, its loaders, its orphan layouts and parallel slots and, for a
+     *   layout, every deeper entry; the click that adopts the prefetch shows
+     *   this fallback and fetches them in one follow-up request, which reads
+     *   cache() and "use cache" as any request does (a prefetch reads neither
+     *   for skipped work). A segment the client already holds is never
+     *   deferred: a prefetch renders it as usual when it revalidates, and what
+     *   is below it follows its own flags. To keep a child out of prefetches
+     *   while moving inside a section, flag the child's own loading(). An entry
+     *   whose handler output is stored (cache(), ppr, Prerender/Static) is
+     *   served as usual and only its loaders are skipped. Loaders behind the
+     *   fallback cannot call ctx.rendered().
      */
     loading: (component: ReactNode | (() => ReactNode), options?: {
         ssr?: boolean;
+        prefetch?: boolean;
     }) => LoadingItem;
     /**
      * Attach an error boundary to catch errors in this segment and children

package/dist/types/route-definition/rewrite.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `throw rewrite(target)`: middleware renders another route at the same URL.
+ *
+ * The value only: what middleware throws and how the router recognizes it.
+ * The pass loop that honors it lives in rsc/rewrite-passes.ts, the hop trail
+ * in server/rewrite-trail.ts.
+ */
+import type { GlobalReverseFunction } from "../reverse.js";
+import type { DefaultReverseRouteMap } from "../types/global-namespace.js";
+/** The target as written: a path, or a global route name with its params. */
+export type RewriteTarget = {
+    readonly path: string;
+} | {
+    readonly name: string;
+    readonly params?: Record<string, string>;
+    readonly search?: Record<string, unknown>;
+};
+export declare function describeRewriteTarget(target: RewriteTarget): string;
+/**
+ * The value `rewrite()` returns, thrown by middleware. An Error, so a throw
+ * where a rewrite is not supported fails loudly with the rule in its message.
+ */
+export declare class Rewrite extends Error {
+    name: "Rewrite";
+    readonly target: RewriteTarget;
+    constructor(target: RewriteTarget);
+}
+/** Whether `value` is a Rewrite thrown by `rewrite()` (ctx.isRewrite). */
+export declare function isRewrite(value: unknown): value is Rewrite;
+/**
+ * `rewrite(path)` or `rewrite(name, params?, search?)`: a path in this app
+ * (basename-prefixed like `redirect()`, may carry `?search`), or a global
+ * route name with the params and search `ctx.reverse` takes.
+ */
+export type RewriteFunction<TRoutes = DefaultReverseRouteMap> = ((path: `/${string}`) => Rewrite) & GlobalReverseFunction<TRoutes, Rewrite>;
+/**
+ * Render another route at the same URL. Throw it from middleware, before
+ * `await next()`:
+ *
+ * ```ts
+ * router.use(async (ctx, next) => {
+ *   if (!locked || ctx.pathname === "/maintenance") return next();
+ *   throw rewrite("maintenance");
+ * });
+ * ```
+ *
+ * The request runs again as the target (global middleware, route
+ * middleware, render) with the same request context: values set before the
+ * throw stay readable. `ctx.url` is the target; `ctx.rewrittenFrom` is the
+ * visitor's URL. See the `/middleware` skill.
+ */
+export declare const rewrite: RewriteFunction;
+/** A dispatch site that cannot honor a rewrite. */
+export type RewriteSite = "mutation" | "loader-fetch" | "intercept";
+/** The error a rewrite becomes at a site that cannot honor it. */
+export declare function rewriteNotSupported(rewrite: Rewrite, site: RewriteSite): Error;

package/dist/types/route-map-builder.d.ts

@@ -7,6 +7,7 @@
  *
  * See docs/manifests.md for the full data flow.
  */
+import { type TrieNode } from "./router/route-trie-builder.js";
 /**
  * Register routes into the global route map.
  * Routes are merged with any existing registered routes.
@@ -71,10 +72,14 @@ export declare function clearAllRouterData(): void;
 export declare function setRouterManifest(routerId: string, manifest: Record<string, string>): void;
 /** @internal */
 export declare function getRouterManifest(routerId: string): Record<string, string> | undefined;
-export declare function setRouterTrie(routerId: string, trie: import("./build/route-trie.js").TrieNode): void;
+/**
+ * Install a router's trie. A trie that arrives as JSON (the build manifest)
+ * or across the dev runner boundary gets null-prototype static maps first.
+ */
+export declare function setRouterTrie(routerId: string, trie: TrieNode): void;
 export declare function markRouterTrieAuthoritative(routerId: string): void;
 export declare function isRouterTrieAuthoritative(routerId: string): boolean;
-export declare function getRouterTrie(routerId: string): import("./build/route-trie.js").TrieNode | undefined;
+export declare function getRouterTrie(routerId: string): TrieNode | undefined;
 export declare function setRouterPrecomputedEntries(routerId: string, entries: Array<{
     staticPrefix: string;
     routes: Record<string, string>;

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

@@ -8,3 +8,10 @@
  * createRouter() accepts and observe the same redirect() prefixing).
  */
 export declare function normalizeBasename(basename?: string): string | undefined;
+/**
+ * Prefix a root-relative path with the basename unless it already carries it
+ * (the basename followed by "/", "?", "#" or the end), so "/admin?tab=x" and
+ * "/admin#frag" under basename "/admin" are not prefixed twice. Shared by
+ * redirect(), rewrite() and useRouter().
+ */
+export declare function prefixBasename(path: string, basename?: string): string;