@rangojs/router 0.22.0 → 0.23.0

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

@@ -212,6 +212,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,23 @@
+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;
+/**
+ * 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/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/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/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/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/prefetch-deferral.d.ts

@@ -0,0 +1,241 @@
+/**
+ * `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>;
+    /**
+     * 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;
+    /** 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>;
+}
+/** 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;
+/**
+ * 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;
+/**
+ * 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
+ * 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/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