@rangojs/router 0.22.1 → 0.24.0

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/is-action.d.ts

@@ -1,5 +1,6 @@
 /**
- * Shared `isAction()` matcher for revalidate predicates (server + clientUrls).
+ * Shared `isAction()` matcher for revalidate() predicates (server) and
+ * transition({ when }) (browser).
  *
  * Action identity is `actionId`. The helper resolves an imported reference the
  * same way the action boundary derives that id (`$id ?? $$id`), so a

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/loader-mask.d.ts

@@ -24,8 +24,9 @@ import { type RequestContext } from "../../server/request-context.js";
 export declare function isShellCaptureActive(reqCtx?: RequestContext<any> | undefined): boolean;
 export { createMaskedLoaderPromise } from "./mask-nested.js";
 /**
- * True when the entry's loading() is renderable (mirrors segment-system's
- * isRenderableLoading). Not the lane decision (lane rule: see
+ * True when the entry's loading() is renderable (the shared
+ * isRenderableLoading, types/boundaries.ts, that segment-system gates on).
+ * Not the lane decision (lane rule: see
  * resolveLoaderData, loader-cache.ts): callers only use it to decide whether
  * an unflagged loader's segment key rides as the bake/seed key, which is inert
  * at capture.

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

@@ -0,0 +1,264 @@
+/**
+ * `prefetch: false`: what a prefetch request defers and what its fill request
+ * runs (docs/design/prefetch-false.md).
+ *
+ * Two layers. The SCOPE is static per matched chain: which loader
+ * registrations are deferrable and which entries can be a handler unit. The
+ * PLAN is per match and rides the handler context
+ * (InternalHandlerContext._prefetchDeferral): the request's mode and where the
+ * chain's stored handler output starts. A request context cannot carry it: a
+ * shell capture derives its context from the request that scheduled it and
+ * would inherit a prefetch's mode.
+ *
+ * The decisions themselves are made in revalidation.ts, by asking this module.
+ *
+ * One rule runs through every decision: the flag applies only to a segment
+ * the client does not have yet. A segment the client holds is never deferred,
+ * whether or not it re-renders, and nothing is deferred because of it. A
+ * placeholder over content that is on screen would replace it with a fallback,
+ * or make the click wait where a plain navigation would not.
+ *
+ * "Holds" is what the request listed in `_rsc_segments` (PrefetchDeferral.held),
+ * the set buildMatchResult (match-result.ts) filters the response with. Not
+ * the set resolution works on: the match deletes a route's id from that one to
+ * force a same-route render from an intercept source (match-api.ts), and a
+ * unit deferred on that ground would be dropped from the response as held.
+ */
+import { type EntryData, type LoaderEntry } from "../../server/context.js";
+import type { HandlerContext } from "../../types.js";
+import type { CacheScope } from "../../cache/cache-scope.js";
+/**
+ * What a request says it is, read once when its context is created
+ * (RequestContext._requestKind). A fill is marked on the raw URL and wins
+ * over the prefetch header. Whether a prefetch defers anything is decided per
+ * match, by partialDeferralMode: a shell capture inherits the context of the
+ * request that scheduled it and is never a prefetch.
+ */
+export declare function requestKind(request: Request, rawUrl: URL): "prefetch" | "fill" | undefined;
+/** Static, per matched chain. */
+interface DeferralScope {
+    /**
+     * Loader registrations a prefetch can defer, each with what makes it so:
+     * `true` for its own flag, else the segment ids of the flagged entries whose
+     * fallback covers it. A covered loader is deferred only while one of those
+     * segments is new to the client.
+     */
+    readonly loaders: ReadonlyMap<LoaderEntry, true | readonly string[]>;
+    /** `$$id`s of `loaders`: the loaders that cannot call ctx.rendered(). */
+    readonly loaderIds: ReadonlySet<string>;
+    /**
+     * Entries whose handler a prefetch can skip (a flagged loading() with a
+     * fallback to show). `index` is the chain index that owns the entry: its
+     * own for a chain entry, its parent's for a parallel entry. `ids` are its
+     * segment ids: the entry's for a chain entry, one per slot for a parallel
+     * entry.
+     */
+    readonly units: ReadonlyMap<EntryData, DeferralUnit>;
+}
+interface DeferralUnit {
+    readonly index: number;
+    readonly ids: readonly string[];
+}
+/** Per match: InternalHandlerContext._prefetchDeferral. */
+export interface PrefetchDeferral {
+    readonly scope: DeferralScope;
+    /**
+     * "prefetch": deferral replaces execution. "fill": the request that follows
+     * an adopted prefetch; a held segment is skipped outright. Unset on every
+     * other request, where the plan only feeds the ctx.rendered() guards.
+     */
+    readonly mode?: "prefetch" | "fill";
+    /**
+     * First chain index whose handler output is stored or about to be (a
+     * cache() boundary, a ppr or Prerender route): no unit at or below it.
+     */
+    readonly storedFrom: number;
+    /** The segment ids the request listed as held (`_rsc_segments`). */
+    readonly held: ReadonlySet<string>;
+    /**
+     * Segment ids of the handler units this prefetch skips: every unit that is
+     * not stored and not held. Empty outside a prefetch.
+     */
+    readonly skipped: ReadonlySet<string>;
+    /** 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;
+    /**
+     * The walk is below a chain unit it skipped (resolution is in chain order,
+     * a route's orphan layouts and slots after its handler): every handler it
+     * reaches from here on is skipped too, and sends a placeholder with what
+     * the entry declares. The browser builds the page's tree once, from those
+     * (browser/partial-update.ts armHoles), so they have to list every segment
+     * a navigation to the page lists.
+     */
+    below?: true;
+    /**
+     * The loaders this prefetch deferred, by `$$id` (registerDeferredLoader).
+     * A deferred loader runs only if something reads it: a handler's or another
+     * loader's ctx.use() starts it through its registration
+     * (startDeferredLoader), and revalidation.ts deliverStartedLoaders delivers
+     * what was started by the end of resolution.
+     */
+    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 {
+    /**
+     * The segment that registers it. Its run files its handle pushes there,
+     * where a navigation's run of it files them, not under the reader
+     * (loaderOwner).
+     */
+    readonly owner: string;
+    /**
+     * Starts it as resolution would have: resolveLoaderData with its cache()
+     * binding, so the reader and the delivered segment share one value.
+     */
+    readonly start: () => Promise<unknown>;
+    /** A reader started it. */
+    started?: true;
+}
+/**
+ * The deferral scope of a matched chain, memoized on its leaf entry (entries
+ * are per-isSSR manifest objects, replaced on HMR). EMPTY_SCOPE when nothing
+ * in the tree declares `prefetch: false`.
+ */
+export declare function resolveDeferralScope(entries: readonly EntryData[]): DeferralScope;
+/**
+ * Which half of the feature a partial request is, if either (`fill` and
+ * `prefetch` are requestKind's answer). Both halves are GETs: a request of
+ * another method that carries either marker is a normal request. A prefetch
+ * defers only on a plain GET navigation: an action re-renders what it
+ * changed, an intercept resolves its loaders outside the shared funnel, and a
+ * shell capture is never a prefetch whatever the request that scheduled it
+ * sent. The four conditions overlap today (an action is a POST, a capture
+ * runs the full match): each one states its own reason.
+ */
+export declare function partialDeferralMode(request: {
+    fill: boolean;
+    prefetch: boolean;
+    method: string;
+    isAction: boolean;
+    isIntercept: boolean;
+    isShellCapture: boolean;
+}): PrefetchDeferral["mode"];
+/**
+ * The plan for one match, or undefined when the tree declares no flag and the
+ * request is not a fill (the common case: nothing to carry). `held` is the
+ * client's segment ids as the request listed them.
+ */
+export declare function planPrefetchDeferral(entries: readonly EntryData[], mode: PrefetchDeferral["mode"], matched: {
+    pr?: boolean;
+    od?: boolean;
+}, cacheScope: CacheScope | null | undefined, held?: ReadonlySet<string>): PrefetchDeferral | undefined;
+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
+ * registration wins, as the loader's one run per request does.
+ */
+export declare function registerDeferredLoader(ctx: HandlerContext<any, any>, loaderId: string, owner: string, start: () => Promise<unknown>): void;
+/**
+ * A reader asks for a loader this prefetch deferred and nothing has started:
+ * start it through its registration and return the run, or undefined when
+ * the read takes the ordinary path. Without this the reader ran the loader
+ * bare, without its cache() binding, and the segment delivered afterwards
+ * read the binding: two values on one page and an extra run on a HIT.
+ *
+ * A started cache() binding of the loader (`_loaderCacheOverrides`) is never
+ * redirected here: the read is that binding's own MISS execution, and
+ * starting the registration would hand the binding its own pending value.
+ */
+export declare function startDeferredLoader(ctx: HandlerContext<any, any>, loaderId: string): Promise<unknown> | undefined;
+/**
+ * The segment a run of `loaderId` files its handle pushes under: the one
+ * that registers it when this prefetch deferred it, else the segment being
+ * resolved.
+ */
+export declare function loaderOwner(ctx: HandlerContext<any, any>, loaderId: string): string | undefined;
+/**
+ * This prefetch defers `loaderEntry`, whose segment is `segmentId`: the client
+ * does not hold that segment, and the loader is flagged itself or sits behind
+ * the fallback of a flagged entry the client does not hold either. Under a
+ * flagged layout the client holds, a new route's loaders run.
+ */
+export declare function defersLoader(ctx: HandlerContext<any, any>, loaderEntry: LoaderEntry, segmentId: string): boolean;
+/**
+ * This prefetch skips the handler of the entry whose segment is `segmentId`:
+ * a unit the client does not hold, or anything the client does not hold
+ * below one (belowDeferredUnit). A held segment that re-renders is rendered
+ * by the prefetch, as by a navigation.
+ */
+export declare function defersUnit(ctx: HandlerContext<any, any>, segmentId: string): boolean;
+/**
+ * `segmentId` is new to the client and the walk is below a chain unit this
+ * prefetch skipped (PrefetchDeferral.below). Nothing of such a segment runs
+ * in the prefetch, a slot's revalidate() predicates included: on a new
+ * segment they cannot change the outcome, and what they would read from
+ * context was set by handlers that did not run.
+ */
+export declare function belowDeferredUnit(ctx: HandlerContext<any, any>, segmentId: string): boolean;
+/**
+ * A unit candidate that is not stored: a prefetch of this tree can skip a
+ * handler. Returns its entry (the first in chain order), for the
+ * ctx.rendered() guards (loader-resolution.ts).
+ */
+export declare function firstUnitCandidate(plan: PrefetchDeferral): EntryData | undefined;
+/**
+ * Record the handler unit this prefetch skipped. A `chain` entry takes what
+ * the walk reaches after it (PrefetchDeferral.below); a slot is skipped
+ * alone.
+ */
+export declare function markUnitDeferred(ctx: HandlerContext<any, any>, segmentId: string, chain?: boolean): void;
+/**
+ * Whether this prefetch skips the handler of the unit whose segment is
+ * `segmentId`, recorded: the flag the segment carries
+ * (ResolvedSegment.deferred), or undefined when the handler runs.
+ * - `chain`: a chain entry, its own unit or below one (defersUnit). The walk
+ *   takes what it reaches after it (markUnitDeferred).
+ * - `slot`: a slot that is its own unit, skipped alone.
+ * - `below`: what the walk reaches below a chain unit it skipped
+ *   (belowDeferredUnit): a slot, before its predicates run, and an orphan
+ *   layout, which is never a unit of its own (resolveDeferralScope). The unit
+ *   above is recorded already.
+ */
+export declare function deferUnit(ctx: HandlerContext<any, any>, segmentId: string, kind: "chain" | "slot" | "below"): {
+    readonly deferred: true;
+} | undefined;
+export {};

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

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

@@ -6,4 +6,37 @@
  */
 import type { CreateRSCHandlerOptions } from "./types.js";
 import type { RouterRequestInput } from "../router/router-interfaces.js";
+/**
+ * Create an RSC request handler.
+ *
+ * **Recommended:** Use `router.createHandler()` instead for simpler setup:
+ * ```tsx
+ * const router = createRouter({ document, urls, nonce: () => true });
+ * export const fetch = router.createHandler();
+ * ```
+ *
+ * This function is still useful for advanced cases like per-request cache
+ * configuration (e.g., Cloudflare Workers with ExecutionContext).
+ *
+ * @example Basic usage (deps and loadSSRModule have sensible defaults)
+ * ```tsx
+ * import { createRSCHandler } from "@rangojs/router/rsc";
+ * import { router } from "./router.js";
+ *
+ * export default createRSCHandler({ router });
+ * ```
+ *
+ * @example With custom deps (advanced)
+ * ```tsx
+ * import { createRSCHandler } from "@rangojs/router/rsc";
+ * import * as rsc from "@vitejs/plugin-rsc/rsc/server";
+ * import { router } from "./router.js";
+ *
+ * export default createRSCHandler({
+ *   router,
+ *   deps: rsc,
+ *   loadSSRModule: () => import.meta.viteRsc.loadModule("ssr", "index"),
+ * });
+ * ```
+ */
 export declare function createRSCHandler<TEnv = unknown, TRoutes extends Record<string, string> = Record<string, string>>(options: CreateRSCHandlerOptions<TEnv, TRoutes>): (incomingRequest: Request, input?: RouterRequestInput<TEnv>) => Promise<Response>;

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

@@ -31,6 +31,14 @@ export declare function hasBodyContent(body: FormData | string): boolean;
  * Also triggers any registered onResponse callbacks.
  */
 export declare function createResponseWithMergedHeaders(body: BodyInit | null, init: ResponseInit): Response;
+/**
+ * An empty 200 carrying X-RSC-Reload: the client turns it into a document
+ * navigation (window.location.href). It points at the visitor's URL: the
+ * first URL of a rewritten request (server/rewrite-trail.ts visitorUrl),
+ * else `url` with the internal `_rsc*` params stripped, or `url` as given
+ * when it is a string the caller resolved (an action's referer).
+ */
+export declare function createReloadResponse(reqCtx: RequestContext<any> | undefined, url: URL | string): Response;
 /**
  * Rebuild a Response returned or thrown by a response-route handler so request
  * effects merge consistently in production and the public dispatch primitive.

package/dist/types/rsc/loader-fetch.d.ts

@@ -11,4 +11,20 @@
  * has already extracted params from it.
  */
 import type { HandlerContext } from "./handler-context.js";
+export interface LoaderErrorMeta<TEnv> {
+    request: Request;
+    url: URL;
+    env: TEnv;
+    loaderId: string;
+}
+/**
+ * A text/x-component Response carrying `{ loaderResult: null, loaderError }`,
+ * the payload `load()` turns into a rejection with `loaderError.message`. A
+ * plain-text body would reject with React's opaque "Connection closed.".
+ * Render failures report through onError("rendering").
+ */
+export declare function renderLoaderError<TEnv>(ctx: HandlerContext<TEnv>, loaderError: {
+    message: string;
+    name: string;
+}, status: number, meta: LoaderErrorMeta<TEnv>): Response;
 export declare function handleLoaderFetch<TEnv>(ctx: HandlerContext<TEnv>, request: Request, env: TEnv, url: URL, variables: Record<string, any>, routeParams?: Record<string, string>): Promise<Response>;

package/dist/types/rsc/rewrite-passes.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The pass loop that honors `throw rewrite()` (route-definition/rewrite.ts):
+ * one catch around the global middleware chain moves the same request
+ * context to the target (server/request-context.ts rebaseRequestContext) and
+ * runs the request again from the top, as a direct visit to the target
+ * would run it. Shared by the request handler (rsc/handler.ts) and the
+ * dispatch testing primitive, so the two cannot drift.
+ */
+import { type Rewrite } from "../route-definition/rewrite.js";
+import { type RequestContext } from "../server/request-context.js";
+/** Response header naming the route path a rewritten request rendered. */
+export declare const REWRITE_HEADER = "x-rango-rewrite";
+/**
+ * Resolve a rewrite's target against the router's route map (global names,
+ * no param auto-fill, as middleware `ctx.reverse`) and the request origin.
+ * A path is basename-prefixed like `redirect()` and must stay under the
+ * basename once normalized (`/../admin` cannot step out of it). The
+ * target's own `_rsc*` params are dropped: only the visitor's transport
+ * params carry over. Throws for an unknown name, a missing param, another
+ * origin or a path outside the basename.
+ */
+export declare function resolveRewriteTarget(rewrite: Rewrite, routeMap: Record<string, string>, base: URL, basename?: string): URL;
+/** The next pass of a rewritten request. */
+export interface RewritePass {
+    request: Request;
+    /** The pass's raw URL, `_rsc*` params included. */
+    url: URL;
+    /** The target's clean URL. */
+    target: URL;
+    hops: number;
+}
+/**
+ * Move the request context to `rewrite`'s target for the next pass: check
+ * that this request can be rewritten, resolve the target, count the hop,
+ * then rebase the context. Throws the site error for a mutation or a loader
+ * fetch, a resolution error, and RewriteLoopError.
+ */
+export declare function applyRewrite(rewrite: Rewrite, passRequest: Request, reqCtx: RequestContext<any>, routeMap: Record<string, string>, basename: string | undefined): RewritePass;
+/** The response to a rewrite loop. */
+export declare function loopDetectedResponse(): Response;
+export interface RewritePassesOptions {
+    reqCtx: RequestContext<any>;
+    /** The visitor's request and raw URL: the first pass. */
+    request: Request;
+    url: URL;
+    routeMap: () => Record<string, string>;
+    basename: string | undefined;
+    /** One pass: the global chain matched on `url`'s path around the core handler. */
+    runPass: (request: Request, url: URL) => Promise<Response>;
+    /** After a hop moved the context to its target. */
+    onHop?: (pass: RewritePass) => void;
+    /** Report a rewrite the request cannot take (onError, phase "routing"). */
+    report: (error: unknown, at: {
+        request: Request;
+        url: URL;
+    }) => void;
+    /**
+     * The response for a refused rewrite other than a loop (a loader fetch's
+     * error response); undefined rethrows the error.
+     */
+    refuse?: (error: unknown, rewrite: Rewrite) => Response | undefined;
+}
+export interface RewritePassesResult {
+    response: Response;
+    /** The pathname the final pass rendered, when a rewrite took the request there. */
+    rewrittenTo?: string;
+}
+/**
+ * Run the request pass by pass until one produces a response. A `Rewrite`
+ * that unwinds a pass moves the context to its target and runs the next;
+ * a loop answers 508; a rewrite the request cannot take is reported and
+ * becomes `refuse`'s response, or is thrown.
+ */
+export declare function runRewritePasses(opts: RewritePassesOptions): Promise<RewritePassesResult>;

package/dist/types/rsc/ssr-setup.d.ts

@@ -23,8 +23,10 @@ export declare const SSR_SETUP_VAR = "__ssrSetup";
  * lazily so stores created after kickoff are still captured). Without a
  * getter the promises run bare — no `.then()` microtasks, no
  * `performance.now()` calls — keeping the non-debug hot path lean.
+ * `ssrModule` reuses a load already started (a rewritten request's earlier
+ * pass).
  */
-export declare function startSSRSetup<TEnv>(ctx: HandlerContext<TEnv>, request: Request, env: TEnv, url: URL, getMetricsStore?: () => MetricsStore | undefined): Promise<SSRSetup>;
+export declare function startSSRSetup<TEnv>(ctx: HandlerContext<TEnv>, request: Request, env: TEnv, url: URL, getMetricsStore?: () => MetricsStore | undefined, ssrModule?: Promise<SSRModule>): Promise<SSRSetup>;
 export interface SsrHtmlStageOptions<TEnv> {
     ctx: HandlerContext<TEnv>;
     request: Request;

package/dist/types/server/context.d.ts

@@ -84,6 +84,13 @@ export type EntryPropDatas = {
  */
 export type EntryPropRender = {
     loading?: ReactNode | false;
+    /**
+     * loading(fallback, { prefetch: false }) with a renderable fallback: a
+     * prefetch defers what the fallback covers while the entry's segment is
+     * new to the client (router/segment-resolution/prefetch-deferral.ts). Set
+     * on both DSL evaluations, whatever `ssr` did to `loading`.
+     */
+    loadingPrefetch?: false;
     transition?: TransitionConfig;
 };
 /**
@@ -116,6 +123,12 @@ export type LoaderEntry = {
      * navigation evaluation never has it.
      */
     bake?: true;
+    /**
+     * loader(Def, { prefetch: false }): a prefetch defers this registration
+     * while its segment is new to the client
+     * (router/segment-resolution/prefetch-deferral.ts).
+     */
+    prefetch?: false;
 };
 /**
  * Segments state for intercept context
@@ -668,7 +681,14 @@ export declare function assertCachedHeaderWriteAllowed(surface: string, surfaceP
  * are bypassed because loaders are always fresh (never cached) and
  * their side effects (setCookie, header, etc.) are safe.
  */
-export declare function runInsideLoaderScope<T>(fn: () => T): T;
+export declare function runInsideLoaderScope<T>(fn: () => T, loaderId?: string): T;
+/**
+ * The loader whose run a handle push here belongs to, for the browser's
+ * merge of a partial response (handles/pushed-by.ts): the DSL loader
+ * this scope resolves, else the outermost loader body around the push (a
+ * loader a handler reads with ctx.use). Undefined for a handler's own push.
+ */
+export declare function getHandlePushOwner(): string | undefined;
 /**
  * Run `fn` inside a loader BODY scope. Marks loader-function execution for the
  * cache() purity guard only (isInsideCacheScope), WITHOUT affecting

package/dist/types/server/handle-store.d.ts

@@ -186,7 +186,8 @@ export interface HandleStore {
      * nav/action payloads, whose consumer applies each yield progressively) or
      * "settled" (the document lane, whose consumers drain to completion in
      * blocking positions and must not wait on loader bodies).
-     * Each yield contains the full accumulated state (not just the delta).
+     * Each yield contains the full accumulated state (not just the delta),
+     * with the pushedBy records of its buckets (handles/pushed-by.ts).
      * Safe for concurrent consumers (per-consumer version cursor).
      * The "settled" lane of a frozen store (freezeDocumentSnapshot) yields the
      * frozen state once, at once, and ends. That yield is the store's own
@@ -212,6 +213,13 @@ export interface HandleStore {
      * time (see push); see captureHandles.
      */
     getDataForSegment(segmentId: string, excludeLoaderPushes?: boolean): Record<string, unknown[]>;
+    /**
+     * The loader whose run pushed each value in getDataForSegment(segmentId,
+     * excludeLoaderPushes), index-aligned per handle (null: the handler's).
+     * Handles without such a value are omitted; undefined when none has one.
+     * The browser's pushedBy record (handles/pushed-by.ts).
+     */
+    getPushedBy(segmentId: string, excludeLoaderPushes?: boolean): Record<string, (string | null)[]> | undefined;
     /**
      * The push `owner` of each value in getDataForSegment(segmentId, true),
      * index-aligned per handle (null: no owner). Handles without an owned