@rangojs/router 0.23.0 → 0.24.0

package/dist/bin/rango.js

@@ -216,6 +216,9 @@ import picomatch from "picomatch";
 function isUniversallySkippedScanDir(name) {
   return name === "node_modules" || name === "dist" || name === "coverage" || name.startsWith(".");
 }
+function isSkippedSourceScanDir(name) {
+  return isUniversallySkippedScanDir(name) || name === "build";
+}
 function findTsFiles(dir, filter) {
   const results = [];
   let entries;
@@ -230,9 +233,7 @@ function findTsFiles(dir, filter) {
   for (const entry of entries) {
     const fullPath = join(dir, entry.name);
     if (entry.isDirectory()) {
-      if (isUniversallySkippedScanDir(entry.name) || entry.name === "build") {
-        continue;
-      }
+      if (isSkippedSourceScanDir(entry.name)) continue;
       results.push(...findTsFiles(fullPath, filter));
     } else if ((entry.name.endsWith(".ts") || entry.name.endsWith(".tsx") || entry.name.endsWith(".js") || entry.name.endsWith(".jsx")) && !entry.name.includes(".gen.")) {
       if (filter && !filter(fullPath)) continue;

package/dist/types/browser/merge-segment-loaders.d.ts

@@ -3,8 +3,11 @@ import type { ResolvedSegment } from "./types.js";
  * Merge partial loader data from server with cached loader data.
  *
  * During partial revalidation (stale or action), the server may return only
- * some loaders that pass the revalidation check. The component still needs
- * all loader data, so we merge fresh data with cached data.
+ * some loaders that pass the revalidation check, none when every one is held.
+ * The component still needs all loader data, so we merge fresh data with
+ * cached data. Two settled aggregates merge into the array itself: a fresh
+ * Promise.all over settled parts is a promise React has not read, and content
+ * on screen handed one suspends (docs/internal/suspense-contract.md, rule 2).
  *
  * @param fromServer - Segment returned from server with partial loaders
  * @param fromCache - Cached segment with full loader data

package/dist/types/browser/partial-update.d.ts

@@ -2,7 +2,7 @@ import type { NavigationStore, NavigationClient, UpdateSubscriber, ResolvedSegme
 import type { ReactNode } from "react";
 import type { RenderSegmentsOptions } from "../segment-system.js";
 import type { BoundTransaction } from "./navigation-transaction.js";
-import type { NavigationUpdate, RscMetadata } from "./types.js";
+import type { HandleData, NavigationUpdate, RscMetadata } from "./types.js";
 import type { LoaderStore } from "../loader-store.js";
 import { type TransitionWhenActionInput } from "./transition-when.js";
 /**
@@ -83,9 +83,11 @@ export type UpdateMode = {
      * when we send cached segment IDs to the server - if the server returns empty diff,
      * we use the same segments we told the server we have. */
     targetCacheSegments?: ResolvedSegment[];
-    /** Cached handle data for the target URL. When server returns empty diff and we're
-     * rendering from cache, this is passed to the UI to restore breadcrumbs etc. */
-    targetCacheHandleData?: Record<string, Record<string, unknown[]>>;
+    /** The handle state of `targetCacheSegments`: the entry's pushes, and
+     * the live pushes of the page on screen for each segment taken from it.
+     * Read at commit; the page starts from it and the response's handles,
+     * when it has any, merge onto it (NavigationProvider). */
+    targetCacheHandleData?: () => HandleData;
     /** Source URL for intercept restore (popstate cache miss) */
     interceptSourceUrl?: string;
     /**

package/dist/types/browser/react/NavigationProvider.d.ts

@@ -74,13 +74,17 @@ export interface NavigationProviderProps {
      * The document this provider hydrates (initBrowserApp; renderRoute with
      * `hydrate: true`), whose store EventController.lockHydration locked.
      * `settled` resolves once the stream has ended and React has revealed every
-     * boundary. Until then location state is `undefined`, as SSR rendered it;
-     * then one transition gives the entry's state and changes
-     * HydrationBarrierContext, and the store is released after that commit
-     * (handle data lands in that release notification). A navigation committed
-     * earlier releases the store before its update, for the whole hold when the
-     * navigation is held: an old-page boundary hydrating meanwhile reads
-     * the destination's values and can mismatch.
+     * boundary. Then a transition changes HydrationBarrierContext alone, and
+     * React commits it once every boundary has hydrated, one still suspended on
+     * the client (a lazy chunk, a deferred-hydration gate) included. Until that
+     * commit location state is `undefined`, as SSR rendered it, through any
+     * commit no payload follows (a shallow navigation), and the store is
+     * locked; after it the entry's state lands in a transition of its own
+     * and the store is released (handle data lands in that release
+     * notification). A navigation committed earlier releases the store before
+     * its update, for the whole hold when the navigation is held: an old-page
+     * boundary hydrating meanwhile reads the destination's values and can
+     * mismatch.
      * Absent for a provider mounted on the client.
      */
     hydration?: {

package/dist/types/browser/react/context.d.ts

@@ -76,7 +76,8 @@ export declare const LocationStateContext: Context<LocationStateSnapshot>;
  * Read by no component. NavigationProvider changes its value in a transition so
  * that React hydrates every boundary still dehydrated beneath it before that
  * commit: React hydrates a dehydrated boundary first when a provider above it
- * changes, and nothing re-renders for a value nobody reads. See
- * NavigationProviderProps.hydration.
+ * changes, and nothing re-renders for a value nobody reads. It must stay
+ * unread and alone in its lane (docs/internal/execution-model.md, "The reveal
+ * barrier is alone in its lane"). See NavigationProviderProps.hydration.
  */
 export declare const HydrationBarrierContext: Context<number>;

package/dist/types/browser/types.d.ts

@@ -80,7 +80,11 @@ export interface RscMetadata {
      * positions and must complete at the handler barrier.
      */
     handlesLate?: AsyncGenerator<HandleData, void, unknown>;
-    /** Cached handle data (for back/forward navigation from cache) */
+    /**
+     * Handle data of the history-cache entry the update renders from (a
+     * back/forward restore, or a link to a cached page). It replaces the handle
+     * state, and `handles`, when present, merge onto it.
+     */
     cachedHandleData?: HandleData;
     /**
      * RSC version string from the server.

package/dist/types/build/route-types/scan-filter.d.ts

@@ -24,8 +24,14 @@ export declare function isUniversallySkippedScanDir(name: string): boolean;
  * files discovery would never find. A path outside `root` is false.
  */
 export declare function isInSkippedScanDir(root: string, absolutePath: string): boolean;
+/**
+ * Directory names the source-file scans skip: findTsFiles() and the build
+ * loader pre-scan (expose-internal-ids.ts). The isUniversallySkippedScanDir()
+ * set plus `build`, which the router scans still enter.
+ */
+export declare function isSkippedSourceScanDir(name: string): boolean;
 /**
  * Recursively find .ts/.tsx files under a directory, skipping the directories
- * isUniversallySkippedScanDir() names, `build`, and .gen. files.
+ * isSkippedSourceScanDir() names and .gen. files.
  */
 export declare function findTsFiles(dir: string, filter?: ScanFilter): string[];

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

@@ -0,0 +1,24 @@
+/**
+ * Document cache storage policy: which responses the document cache stores.
+ * A leaf (types and the per-client signal only), so request-scoped code can
+ * ask whether a render will be stored (documentCacheStoresRender) without
+ * importing the cache middleware.
+ */
+import type { RequestContext } from "../server/request-context.js";
+export interface CacheDirectives {
+    sMaxAge?: number;
+    staleWhileRevalidate?: number;
+}
+/**
+ * Check if response should be cached based on Cache-Control headers
+ */
+export declare function shouldCacheResponse(response: Response, requestCtx?: Pick<RequestContext, "_payloadVisitorTheme" | "_payloadDeferred" | "_payloadVisitorLocation">): CacheDirectives | null;
+/**
+ * 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;

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/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

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

@@ -5,6 +5,14 @@ export declare function pushedByKey(handleName: string): string;
 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

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/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/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;

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

@@ -10,11 +10,7 @@ import type { InternalHandlerContext } from "../types";
  * (createMiddlewareContext).
  */
 export declare function guardHeaderWrites(headers: Headers, assertWrite: (method: string | symbol) => void): Headers;
-/**
- * Strip internal _rsc* query params from a URL.
- * Returns a new URL with only user-facing params.
- */
-export declare function stripInternalParams(url: URL): URL;
+export { stripInternalParams } from "./internal-params.js";
 /**
  * Create a reverse function for URL generation from route names.
  * Used by both HandlerContext and MiddlewareContext.

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

@@ -0,0 +1,8 @@
+/**
+ * Strip internal _rsc* query params from a URL.
+ * Returns a new URL with only user-facing params.
+ *
+ * A leaf, so request-scoped modules (server/rewrite-trail.ts) can strip
+ * without importing the handler context's graph.
+ */
+export declare function stripInternalParams(url: URL): URL;

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

@@ -4,6 +4,7 @@ import type { GlobalReverseFunction } from "../reverse.js";
 import type { Theme } from "../theme/types.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
 import type { RequestScope } from "../types/request-scope.js";
+import type { Rewrite } from "../route-definition/rewrite.js";
 type GetVariableFn = {
     <T>(contextVar: ContextVar<T>): T | undefined;
     <K extends keyof DefaultVars>(key: K): DefaultVars[K];
@@ -58,6 +59,20 @@ export interface MiddlewareContext<TEnv = any, TParams = Record<string, string |
     setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void;
     /** Global route names only; see {@link GlobalReverseFunction}. */
     reverse: GlobalReverseFunction<DefaultReverseRouteMap>;
+    /**
+     * Whether `value` is a `rewrite()` thrown downstream. A middleware that
+     * wraps `next()` in try/catch rethrows it, so the request re-dispatches:
+     *
+     * ```ts
+     * try {
+     *   return await next();
+     * } catch (error) {
+     *   if (ctx.isRewrite(error)) throw error;
+     *   return new Response("Error", { status: 500 });
+     * }
+     * ```
+     */
+    isRewrite(value: unknown): value is Rewrite;
 }
 export type MiddlewareFn<TEnv = any, TParams = Record<string, string | undefined>> = (ctx: MiddlewareContext<TEnv, TParams>, next: () => Promise<Response>) => Response | void | Promise<Response | void>;
 export interface MiddlewareEntry<TEnv = any> {

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

@@ -9,7 +9,7 @@ import type { RevalidationTraceEntry } from "./logging.js";
 /**
  * Options for revalidation evaluation
  */
-interface EvaluateRevalidationOptions<TEnv> {
+export interface EvaluateRevalidationOptions<TEnv> {
     /** Current segment to evaluate */
     segment: ResolvedSegment;
     /** Previous route params (from route match, not segment) */
@@ -61,4 +61,3 @@ interface EvaluateRevalidationOptions<TEnv> {
  * Optimized to use prevParams directly and avoid building previous segments
  */
 export declare function evaluateRevalidation<TEnv>(options: EvaluateRevalidationOptions<TEnv>): Promise<boolean>;
-export {};

package/dist/types/router/route-trie-builder.d.ts

@@ -82,3 +82,13 @@ export interface TrieNode {
  * @param onDemandRouteNames - Optional set of on-demand-eligible route names (sets leaf.od)
  */
 export declare function buildRouteTrie(routeManifest: Record<string, string>, routeToStaticPrefix: Record<string, string>, routeTrailingSlash?: Record<string, string>, prerenderRouteNames?: Set<string>, passthroughRouteNames?: Set<string>, responseTypeRoutes?: Record<string, string>, onDemandRouteNames?: Set<string>): TrieNode;
+/**
+ * Give every static-children map in the trie a null prototype, in place, and
+ * return the trie (#1109). The walker indexes `node.s` with raw URL segments,
+ * so a map with Object.prototype would answer `/constructor` or `/__proto__`
+ * with an inherited member. The builder creates null-prototype maps; a trie
+ * that arrives as JSON (the build manifest) or across the dev runner boundary
+ * gets them here. Object.setPrototypeOf keeps a JSON-parsed map's fast
+ * properties, where Object.create(null) starts in dictionary mode.
+ */
+export declare function nullPrototypeStaticChildren(node: TrieNode): TrieNode;

package/dist/types/router/segment-resolution/mask-nested.d.ts

@@ -8,7 +8,8 @@
  *
  * Deliberately a LEAF module: loader-mask (the other natural home) imports
  * request-context, so any funnel importing the mask from there inherits that
- * graph. This module imports only is-thenable and react.
+ * graph. This module imports only react and two leaves, is-thenable and
+ * context-var.
  */
 import { type ReactElement } from "react";
 /**
@@ -36,7 +37,8 @@ export declare function isPlainDataObject(value: unknown): value is Record<strin
  * keyless child of a static children list (validated at creation) would warn
  * "Each child in a list should have a unique key" once cloned. Pass only the
  * props that change: cloneElement re-parents the element (owner) when its
- * config carries `ref`.
+ * config carries `ref`. cloneElement copies props by assignment, so a prop
+ * key named `__proto__` can't survive a clone; prop copies don't use assignOwn.
  */
 export declare function cloneElementWithProps(element: ReactElement, props: Record<string, unknown>): ReactElement;
 /**

package/dist/types/router/segment-resolution/prefetch-deferral.d.ts

@@ -80,11 +80,8 @@ export interface PrefetchDeferral {
      * not stored and not held. Empty outside a prefetch.
      */
     readonly skipped: ReadonlySet<string>;
-    /**
-     * One of `skipped` is a chain entry: nothing below it runs, so the response
-     * has no content for it, a route cache() record included.
-     */
-    readonly skipsChain: boolean;
+    /** How this request may use the route's cache() record (recordUse). */
+    readonly record: RecordUse;
     /** Segment id of the handler unit this prefetch skipped. */
     deferredUnit?: string;
     /**
@@ -105,6 +102,30 @@ export interface PrefetchDeferral {
      */
     deferredLoaders?: Map<string, DeferredLoader>;
 }
+/**
+ * How a request may use the route's cache() record, decided once per match
+ * (planPrefetchDeferral) for the cache middleware.
+ */
+export interface RecordUse {
+    /**
+     * withCacheLookup reads it. False when this prefetch skips a chain unit
+     * (PrefetchDeferral.skipped): the unit takes everything below it, so the
+     * read would replay the record's handle pushes for segments the response
+     * does not carry. Decided from what the client holds, never per tree: a
+     * prefetch that holds the flagged layout reads and writes the record like
+     * any other request.
+     */
+    readonly read: boolean;
+    /** withCacheStore writes it. False where `read` is: the record would be incomplete. */
+    readonly write: boolean;
+    /**
+     * A background re-render of the whole route may write it: the stale-hit
+     * refresh (withBackgroundRevalidation) and the proactive write a partial
+     * response needs (withCacheStore). False for a fill: the re-render runs
+     * the handlers of segments the client holds, which a fill does not run.
+     */
+    readonly refresh: boolean;
+}
 /** A loader this prefetch deferred: PrefetchDeferral.deferredLoaders. */
 export interface DeferredLoader {
     /**
@@ -157,6 +178,16 @@ export declare function planPrefetchDeferral(entries: readonly EntryData[], mode
 export declare function getPrefetchDeferral(ctx: HandlerContext<any, any> | undefined): PrefetchDeferral | undefined;
 /** The request is a fill: a held segment is skipped without consulting anything. */
 export declare function isFillRequest(ctx: HandlerContext<any, any>): boolean;
+/**
+ * A fill's whole revalidation rule (R5): send a segment the client does not
+ * hold, keep one it holds, and consult nothing else (no revalidate()
+ * predicate, no params or search comparison, no trace entry). Undefined on
+ * any other request, where revalidation decides. `held` is the set the
+ * deciding site resolves with.
+ */
+export declare function fillSends(ctx: HandlerContext<any, any>, segmentId: string, held: ReadonlySet<string>): boolean | undefined;
+/** PrefetchDeferral.record, or all of it open when the match has no plan. */
+export declare function recordUse(ctx: HandlerContext<any, any> | undefined): RecordUse;
 /**
  * Register a loader this prefetch deferred, with the segment that registers
  * it and how to start it there (PrefetchDeferral.deferredLoaders). The first
@@ -209,14 +240,6 @@ export declare function belowDeferredUnit(ctx: HandlerContext<any, any>, segment
  * ctx.rendered() guards (loader-resolution.ts).
  */
 export declare function firstUnitCandidate(plan: PrefetchDeferral): EntryData | undefined;
-/**
- * This prefetch skips a layout above the route cache's boundary, and with it
- * everything the record below holds: withCacheLookup and withCacheStore leave
- * the record alone for it. Decided per request, from what the client holds:
- * a prefetch of the same tree that holds the layout reads and writes the
- * record like any other request.
- */
-export declare function defersAboveRecord(ctx: HandlerContext<any, any>): boolean;
 /**
  * Record the handler unit this prefetch skipped. A `chain` entry takes what
  * the walk reaches after it (PrefetchDeferral.below); a slot is skipped

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

@@ -21,6 +21,17 @@ import type { Theme } from "../theme/types.js";
  *   derived-context store.
  */
 export declare function buildFullPayload(m: MatchResult, ctx: HandlerContext<any>, url: URL, reqCtx: RequestContext<any>, handleStore: HandleStore): RscPayload;
+/**
+ * The URL a render shows as the page's location (payload `pathname`, the SSR
+ * search and origin seed). For a request middleware rewrote, the visitor's
+ * URL, so the server markup and the hydrating client (which reads the address
+ * bar) agree on `usePathname()` and `useSearchParams()`. A render other
+ * visitors may be served shows `url`, the target, as a direct visit does: a
+ * shell capture, and a render the document cache stores (its key is the
+ * target). A render that shows the visitor's URL marks
+ * `_payloadVisitorLocation`, and the document cache does not store it.
+ */
+export declare function renderedLocation(reqCtx: Pick<RequestContext<any>, "_variables" | "_shellCaptureRun" | "_documentCacheRender" | "_payloadVisitorLocation" | "res"> | undefined, url: URL): URL;
 /**
  * The theme a document payload carries as `metadata.initialTheme` (the
  * ThemeProvider's first state), read with no identity guard: it is the