@rangojs/router 0.22.0 → 0.23.0

package/src/handles/pushed-by.ts

@@ -0,0 +1,122 @@
+import { LOADER_SEGMENT_ID } from "../browser/react/filter-segment-order.js";
+import type { HandleData } from "../server/handle-store.js";
+
+/**
+ * Which run pushed each handle value, so a partial response replaces only the
+ * pushes of what it re-ran (#1103).
+ *
+ * A segment's handle bucket holds its handler's pushes and those of the
+ * loaders registered on it: a loader pushes under its owning segment's id
+ * (fresh.ts, revalidation.ts pin `_currentSegmentId`). A navigation or an
+ * action response decides each of them on its own: the handler re-runs and a
+ * loader whose revalidate() answers false keeps its data on the client. The
+ * response carries only what re-ran, so replacing the whole bucket with it
+ * dropped the pushes of the loader whose data the page still shows (the
+ * document title, a breadcrumb), and a loader re-run under a handler that did
+ * not re-run took the handler's pushes with it.
+ *
+ * The record rides in the snapshot itself, beside each handle, under a name
+ * no handle has: `data[pushedByKey(h)][segmentId][i]` is the $$id of the
+ * loader whose run pushed `data[h][segmentId][i]`, or null for the segment's
+ * handler. A bucket without a loader push has no entry. Inside the snapshot it
+ * crosses Flight and every clone and history-cache copy with the values;
+ * collectHandleData reads a handle by its $$id, so no collect sees it.
+ * resolveDeferredHandleValues keeps it aligned when it drops a value.
+ */
+const PUSHED_BY_SUFFIX = "\u0000pushedBy";
+
+/** The snapshot key holding `handleName`'s pushedBy record. */
+export function pushedByKey(handleName: string): string {
+  return handleName + PUSHED_BY_SUFFIX;
+}
+
+/** True for a pushedBy record's key, false for a handle's. */
+export function isPushedByKey(name: string): boolean {
+  return name.endsWith(PUSHED_BY_SUFFIX);
+}
+
+/** `data` without its pushedBy records, as a reader outside the router sees it. */
+export function withoutPushedBy(data: HandleData): HandleData {
+  const out: HandleData = {};
+  for (const name in data) {
+    if (!isPushedByKey(name)) out[name] = data[name];
+  }
+  return out;
+}
+
+type PushedBy = readonly (string | null)[] | undefined;
+
+const keysOf = (a: object | undefined, b: object | undefined): Set<string> =>
+  new Set([...Object.keys(a ?? {}), ...Object.keys(b ?? {})]);
+
+/**
+ * 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 function mergePartialHandleData(
+  current: HandleData,
+  incoming: HandleData,
+  segmentOrder: readonly string[],
+  matched: readonly string[],
+  resolvedIds: readonly string[] | undefined,
+): HandleData {
+  // A run's key: a segment's id for its handler, `${segmentId}\0${$$id}` for
+  // a loader (its segment id with the `D${index}.` marker replaced).
+  const runKey = (id: string): string =>
+    id.replace(LOADER_SEGMENT_ID, "\u0000");
+  const inOrder = new Set(segmentOrder);
+  const registered = new Set(matched.map(runKey));
+  const ran = new Set(resolvedIds?.map(runKey));
+  const out: HandleData = {};
+  for (const name of keysOf(current, incoming)) {
+    if (isPushedByKey(name)) continue;
+    const byName = pushedByKey(name);
+    const buckets: Record<string, unknown[]> = (out[name] = {});
+    for (const segmentId of keysOf(current[name], incoming[name])) {
+      if (!inOrder.has(segmentId)) continue;
+      const run = (by: PushedBy, i: number): string => {
+        const key = `${segmentId}\u0000${by?.[i]}`;
+        return registered.has(key) ? key : segmentId;
+      };
+      const currentBy = current[byName]?.[segmentId] as PushedBy;
+      const incomingValues = incoming[name]?.[segmentId] ?? [];
+      const incomingBy = incoming[byName]?.[segmentId] as PushedBy;
+      const delivered = new Set(
+        incomingValues.map((_, i) => run(incomingBy, i)),
+      );
+      const values: unknown[] = [];
+      const by: (string | null)[] = [];
+      let at = -1;
+      (current[name]?.[segmentId] ?? []).forEach((value, i) => {
+        const key = run(currentBy, i);
+        if (delivered.has(key) || ran.has(key)) {
+          if (at < 0) at = values.length;
+        } else {
+          values.push(value);
+          by.push(currentBy?.[i] ?? null);
+        }
+      });
+      if (at < 0) at = values.length;
+      values.splice(at, 0, ...incomingValues);
+      by.splice(
+        at,
+        0,
+        ...incomingValues.map((_, i) => incomingBy?.[i] ?? null),
+      );
+      if (values.length > 0) buckets[segmentId] = values;
+      if (by.some((run) => run !== null)) (out[byName] ??= {})[segmentId] = by;
+    }
+  }
+  return out;
+}

package/src/loader-store.ts

@@ -36,6 +36,7 @@
  */
 
 import { unwrapsSynchronously } from "./thenable-status.js";
+import { asStream } from "./browser/defer.js";
 
 /** The loader-segment shape announcePendingStreams reads (ResolvedSegment). */
 export interface PendingStreamSource {
@@ -538,14 +539,23 @@ export class LoaderStore {
       this.pendingStreams.set(loaderId, set);
     }
     set.add(stream);
-    const release = () => {
-      const current = this.pendingStreams.get(loaderId);
-      if (!current || !current.delete(stream)) return;
-      if (current.size === 0) this.pendingStreams.delete(loaderId);
-    };
+    const release = () => this.releasePendingStream(loaderId, stream);
     stream.then(release, release);
   }
 
+  /**
+   * 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 {
+    const current = this.pendingStreams.get(loaderId);
+    if (!current || !current.delete(stream)) return;
+    if (current.size === 0) this.pendingStreams.delete(loaderId);
+  }
+
   /** True while any navigation stream for `loaderId` is still pending. */
   isStreamPending(loaderId: string): boolean {
     return this.pendingStreams.has(loaderId);
@@ -566,12 +576,13 @@ export class LoaderStore {
    */
   announcePendingStreams(segments: readonly PendingStreamSource[]): void {
     for (const segment of segments) {
+      const data = asStream(segment.loaderData);
       if (
         segment.type === "loader" &&
         segment.loaderId &&
-        segment.loaderData instanceof Promise
+        data instanceof Promise
       ) {
-        this.trackPendingStream(segment.loaderId, segment.loaderData);
+        this.trackPendingStream(segment.loaderId, data);
       }
     }
     for (const loaderId of this.pendingStreams.keys()) {

package/src/prefetch-markers.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 const PREFETCH_HEADER = "X-Rango-Prefetch";
+
+/** Query param of a fill request (browser/navigation-client.ts). */
+export const FILL_PARAM = "_rsc_fill";

package/src/route-content-wrapper.tsx

@@ -10,12 +10,14 @@ import {
   LOADER_REDIRECT,
 } from "./decode-loader-results.js";
 import { LoaderRedirect } from "./loader-redirect.js";
+import { Defer, readDefer } from "./browser/defer.js";
 import type { BoundaryAudit } from "./suspense-audit.js";
 import {
   AuditedFallback,
   useBoundaryAudit,
   useRevealAudit,
 } from "./suspense-audit-react.js";
+import { SETTLED_THENABLE } from "./thenable-status.js";
 
 /**
  * Router-owned error boundary for read-site loader errors. segment-system
@@ -141,7 +143,7 @@ export function AuditedRouteContent({
   const audit = useBoundaryAudit(
     `content:${segmentId}`,
     segmentId ?? "",
-    content,
+    content instanceof Defer ? content.promise : content,
   );
   return (
     <Suspense
@@ -174,8 +176,16 @@ const Suspender = ({
   // A pending promise suspends here and the wrapping Suspense shows the
   // loading() fallback; a node renders without suspending. The wrapper tree
   // (RouteContentWrapper > Suspense > Suspender) is identical either way (see
-  // docs/tree-structure.md), like LoaderResolver's resolved-data branch.
-  return content instanceof Promise ? use(content) : content;
+  // docs/tree-structure.md), like LoaderResolver's resolved-data branch. A
+  // `prefetch: false` hole is read here, by the read rule, so the filled
+  // page's node later takes the same place. The content can be a pending
+  // promise in one tree and its node in the next: use() at this place on
+  // every render, as LoaderResolver does.
+  return content instanceof Defer
+    ? (readDefer(content) as ReactNode)
+    : content instanceof Promise
+      ? use(content)
+      : (use(SETTLED_THENABLE), content);
 };
 
 /**
@@ -329,10 +339,14 @@ function LoaderResolver({
     );
   }
 
+  // A slot's aggregate can be a pending promise on one render and its arrived
+  // array on the next (segment-loader-promise.ts): use() at this place on
+  // every render, or React reports a component that suspended in use() and
+  // then finished without it (the useLoader pattern, use-loader.tsx).
   const resolvedData =
     loaderDataPromise instanceof Promise
       ? use(loaderDataPromise)
-      : loaderDataPromise;
+      : (use(SETTLED_THENABLE), loaderDataPromise);
 
   const { loaderData, errorFallback } = decodeLoaderResults(
     resolvedData,

package/src/route-definition/dsl-helpers.ts

@@ -22,7 +22,7 @@ import {
   type InterceptConfig,
   type LoaderEntry,
 } from "../server/context";
-import { invariant } from "../errors";
+import { assertBooleanOption, invariant } from "../errors";
 import { validateUserRouteName } from "../route-name.js";
 import { isCachedFunction } from "../cache/taint.js";
 import { RangoContext } from "../server/context";
@@ -44,6 +44,7 @@ import type {
   TransitionItem,
   UseItems,
 } from "../route-types.js";
+import { isRenderableLoading } from "../types/boundaries.js";
 import type { RouteHelpers } from "./helpers-types.js";
 import {
   resolveHandlerUse,
@@ -899,9 +900,15 @@ const loader: RouteHelpers<any, any>["loader"] = (
     (optionsGiven as { stream?: unknown } | undefined)?.stream === undefined,
     "loader() stream was replaced: use loader(Def, { ssr: false }) — the same knob as loading(fallback, { ssr: false }) — to await the loader before first flush on document requests.",
   );
-  invariant(
-    optionsGiven?.ssr === undefined || typeof optionsGiven.ssr === "boolean",
-    `loader() ssr must be a boolean (got ${JSON.stringify(optionsGiven?.ssr)}). Omit it (or pass true) to stream on every render.`,
+  assertBooleanOption(
+    optionsGiven?.ssr,
+    "loader() ssr",
+    "stream on every render",
+  );
+  assertBooleanOption(
+    optionsGiven?.prefetch,
+    "loader() prefetch",
+    "run the loader in prefetches",
   );
 
   const name = `${ctx.namespace}.$${store.getNextIndex("loader")}`;
@@ -917,6 +924,7 @@ const loader: RouteHelpers<any, any>["loader"] = (
     ...(optionsGiven?.ssr === false && { bake: true as const }),
     ...(optionsGiven?.ssr === false &&
       ctx.isSSR && { awaitBeforeFlush: true as const }),
+    ...(optionsGiven?.prefetch === false && { prefetch: false as const }),
   };
 
   // Merge handler.use defaults (attached to the loader definition) with explicit use
@@ -969,6 +977,12 @@ const loading: RouteHelpers<any, any>["loading"] = (component, options) => {
     invariant(false, "No parent entry available for loading()");
   }
 
+  assertBooleanOption(
+    options?.prefetch,
+    "loading() prefetch",
+    "render what the fallback covers in prefetches",
+  );
+
   // Unwrap function form: loading(() => <Skeleton />) → loading(<Skeleton />)
   const resolved =
     typeof component === "function" ? (component as () => any)() : component;
@@ -980,6 +994,15 @@ const loading: RouteHelpers<any, any>["loading"] = (component, options) => {
     parent.loading = resolved;
   }
 
+  // The flag means "what this fallback covers": without a fallback to show
+  // there is nothing to defer behind. Recorded from `resolved`, not
+  // `parent.loading`, so the document evaluation (ssr: false) agrees with
+  // the navigation one. Last loading() wins, like `loading` itself.
+  parent.loadingPrefetch =
+    options?.prefetch === false && isRenderableLoading(resolved)
+      ? false
+      : undefined;
+
   const name = `$${store.getNextIndex("loading")}`;
   return { name, type: "loading" } as LoadingItem;
 };

package/src/route-definition/helpers-types.ts

@@ -328,6 +328,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
@@ -345,14 +355,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 },
+    options?: { ssr?: boolean; prefetch?: boolean },
   ) => LoadingItem;
   /**
    * Attach an error boundary to catch errors in this segment and children

package/src/router/intercept-resolution.ts

@@ -331,8 +331,9 @@ export async function resolveInterceptEntry<TEnv>(
       deps.wrapLoaderPromise(
         // The DSL binding's funnel, as for route loaders: a loader's own
         // cache() applies here too.
-        runInsideLoaderScope(() =>
-          resolveLoaderData(loaderEntry, context, context.pathname),
+        runInsideLoaderScope(
+          () => resolveLoaderData(loaderEntry, context, context.pathname),
+          loader.$$id,
         ),
         parentEntry,
         segmentId,
@@ -564,8 +565,9 @@ export async function resolveInterceptLoadersOnly<TEnv>(
       deps.wrapLoaderPromise(
         // The DSL binding's funnel, as for route loaders: a loader's own
         // cache() applies here too.
-        runInsideLoaderScope(() =>
-          resolveLoaderData(loaderEntry, context, context.pathname),
+        runInsideLoaderScope(
+          () => resolveLoaderData(loaderEntry, context, context.pathname),
+          loader.$$id,
         ),
         parentEntry,
         segmentId,

package/src/router/is-action.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/src/router/loader-resolution.ts

@@ -55,6 +55,12 @@ import {
 } from "../server/handle-store.js";
 import { getFetchableLoader } from "../server/fetchable-loader-store.js";
 import { _getRequestContext } from "../server/request-context.js";
+import {
+  firstUnitCandidate,
+  loaderOwner,
+  startDeferredLoader,
+  type PrefetchDeferral,
+} from "./segment-resolution/prefetch-deferral.js";
 import {
   assertNonCacheableReadAllowed,
   isInsideLoaderScope,
@@ -372,6 +378,29 @@ function detectLoaderCycle(
   return dfs(to);
 }
 
+const warnedRenderedBesideUnit = new Set<string>();
+
+/**
+ * Dev only, once per loader: a loader that is not deferrable awaits
+ * ctx.rendered() in a tree where a prefetch can skip a handler. The prefetch
+ * rejects that call (see rendered() below); saying so on a document or a
+ * navigation shows it before production, where prefetch is automatic.
+ */
+function warnRenderedBesideUnit(
+  deferral: PrefetchDeferral,
+  loaderId: string,
+): void {
+  if (warnedRenderedBesideUnit.has(loaderId)) return;
+  const unit = firstUnitCandidate(deferral);
+  if (!unit) return;
+  warnedRenderedBesideUnit.add(loaderId);
+  console.warn(
+    `[rango] loader "${loaderId}" awaits ctx.rendered() on a route where "${unit.shortCode}" (${unit.id}) has loading(fallback, { prefetch: false }). ` +
+      `A prefetch of this route skips that handler, so ctx.rendered() throws in the prefetch and this loader is an error on the click that adopts it. ` +
+      `Remove { prefetch: false } from that loading(), or stop calling ctx.rendered() in this loader.`,
+  );
+}
+
 /**
  * Creates a memoizing loader executor with cycle detection.
  * Shared by setupLoaderAccess and setupLoaderAccessSilent; only the handle
@@ -397,7 +426,9 @@ function createLoaderExecutor<TEnv>(
     /**
      * A stale refresh's executor (setupLoaderAccess _runLoaderIsolated): its
      * runs' pushes are diverted from the page's store, so a run's end says
-     * nothing about the page's replayed values (HandleStore.settleLoaderRun).
+     * nothing about the page's replayed values (HandleStore.settleLoaderRun),
+     * and it never starts a loader the page's prefetch deferred
+     * (startDeferredLoader): a refresh reads each loader fresh.
      */
     detached?: boolean;
     /**
@@ -472,7 +503,14 @@ function createLoaderExecutor<TEnv>(
     const bound =
       callerLoaderId !== null &&
       internal._loaderCacheOverrides?.get(loader.$$id);
-    const memo = bound || loaderPromises.get(loader.$$id);
+    // A loader the prefetch deferred starts through its registration, cache()
+    // binding included, as a navigation's run of it does.
+    const memo =
+      bound ||
+      loaderPromises.get(loader.$$id) ||
+      (executorOptions?.detached
+        ? undefined
+        : startDeferredLoader(ctx, loader.$$id));
     if (memo) {
       if (recordTags) readValueTags(memo);
       // A "use cache" body reading it refuses an identity read the run made
@@ -511,8 +549,9 @@ function createLoaderExecutor<TEnv>(
     // resolution continues — by the time the async body pushes, it would be
     // stale. Attributing to the owning route/layout segment gives handle
     // pushes the same granularity handler pushes have (segmentOrder-correct
-    // for breadcrumb accumulation).
-    const owningSegmentId = internal._currentSegmentId;
+    // for breadcrumb accumulation). A loader a prefetch deferred and a reader
+    // starts anyway keeps the segment that registers it (loaderOwner).
+    const owningSegmentId = loaderOwner(ctx, loader.$$id);
 
     let renderedResolved = false;
     let renderedPromise: Promise<void> | null = null;
@@ -633,6 +672,32 @@ function createLoaderExecutor<TEnv>(
           );
         }
 
+        // prefetch: false (segment-resolution/prefetch-deferral.ts). A
+        // deferrable loader runs in a fill request, where its entry is held
+        // and its handler does not run: there is no render to wait for.
+        // Refused on every request kind, so it is seen on a document load.
+        const deferral = internal._prefetchDeferral;
+        if (deferral?.scope.loaderIds.has(currentLoaderId)) {
+          throw new Error(
+            `ctx.rendered() is not available to loader "${currentLoaderId}": it is deferred in prefetches ` +
+              `(registered with loader(Def, { prefetch: false }), or behind a loading(fallback, { prefetch: false })), ` +
+              `and the fill request that runs it afterwards does not re-run its entry's handler, so there is no render to wait for and no handle data to read. ` +
+              `Remove { prefetch: false } from the loader (or from the loading() above it), or stop calling ctx.rendered() in this loader.`,
+          );
+        }
+        if (deferral?.mode === "fill") {
+          throw new Error(
+            `ctx.rendered() is not available to loader "${currentLoaderId}" in a fill request: the handlers the client already holds do not run, so their handle data is missing.`,
+          );
+        }
+        if (
+          process.env.NODE_ENV !== "production" &&
+          deferral &&
+          !deferral.mode
+        ) {
+          warnRenderedBesideUnit(deferral, currentLoaderId);
+        }
+
         // awaitBeforeFlush cycle: segment resolution awaits this loader
         // (loader(Def, { ssr: false })), the barrier awaits segment
         // resolution, and rendered() awaits the barrier — waiting here can
@@ -684,6 +749,17 @@ function createLoaderExecutor<TEnv>(
         // keeps a handler from depending on this loader.
         const streaming = reqCtx._treeHasStreaming === true;
         renderedPromise = reqCtx._renderBarrier.then(async () => {
+          // A prefetch that skipped a handler unit has none of that handler's
+          // pushes, and the fill never re-runs this loader: an error, never
+          // a handle list with a hole in it. Known only once resolution has
+          // decided the unit, which is what the barrier waits for.
+          if (deferral?.mode === "prefetch" && deferral.deferredUnit) {
+            throw new Error(
+              `ctx.rendered() in loader "${currentLoaderId}" cannot settle in a prefetch of this route: segment "${deferral.deferredUnit}" has loading(fallback, { prefetch: false }), ` +
+                `so the prefetch skipped its handler and its handle data does not exist. ` +
+                `Remove { prefetch: false } from that loading(), or stop calling ctx.rendered() in this loader.`,
+            );
+          }
           if (streaming) {
             reqCtx._handleStore.seal();
             await reqCtx._handleStore.settled;
@@ -807,6 +883,9 @@ export function setupLoaderAccess<TEnv>(
   // pushes, and a later run here replaces them (HandleStore.pushReplayed).
   const claimed = new Set<string>();
   const internal = ctx as InternalHandlerContext<any, TEnv>;
+  internal._loaderStarted = (loaderId) =>
+    loaderPromises.has(loaderId) ||
+    internal._loaderCacheOverrides?.has(loaderId) === true;
   internal._claimLoaderPushes = (loaderId) => {
     if (loaderPromises.has(loaderId) || claimed.has(loaderId)) return false;
     claimed.add(loaderId);

package/src/router/match-api.ts

@@ -32,7 +32,12 @@ import {
   getContext,
   type InterceptSelectorContext,
 } from "../server/context";
-import type { ErrorBoundaryHandler, ErrorInfo, MatchResult } from "../types";
+import type {
+  ErrorBoundaryHandler,
+  ErrorInfo,
+  InternalHandlerContext,
+  MatchResult,
+} from "../types";
 import type { ReactNode } from "react";
 import type { MatchContext } from "./match-context.js";
 import type { MatchApiDeps, ActionContext } from "./types.js";
@@ -49,6 +54,11 @@ import {
   type RouteSnapshot,
 } from "./route-snapshot.js";
 import { resolveNavigation } from "./navigation-snapshot.js";
+import {
+  partialDeferralMode,
+  planPrefetchDeferral,
+  requestKind,
+} from "./segment-resolution/prefetch-deferral.js";
 
 /**
  * Create match context for full requests (document/SSR).
@@ -174,6 +184,9 @@ export async function createMatchContextForFull<TEnv>(
   if (reqCtx?._shellCaptureRun) {
     reqCtx._shellCaptureLoaderLanes = routeLoaderLanes(snapshot.entries);
   }
+  // A document never defers; the plan feeds the ctx.rendered() guards.
+  (handlerContext as InternalHandlerContext<any, TEnv>)._prefetchDeferral =
+    planPrefetchDeferral(snapshot.entries, undefined, matched, cacheScope);
 
   return {
     request,
@@ -453,6 +466,28 @@ export async function createMatchContextForPartial<TEnv>(
   if (cacheScope) armRecordTagOwners();
   if (bindsLoaderCache(snapshot.entries)) armLoaderTagSets();
 
+  // `prefetch: false` (segment-resolution/prefetch-deferral.ts). With no
+  // request context (a match run on its own) the request is asked directly.
+  const kind = reqCtx ? reqCtx._requestKind : requestKind(request, rawUrl);
+  const deferral = planPrefetchDeferral(
+    snapshot.entries,
+    partialDeferralMode({
+      fill: kind === "fill",
+      prefetch: kind === "prefetch",
+      method: request.method,
+      isAction,
+      isIntercept,
+      isShellCapture: reqCtx?._shellCaptureRun === true,
+    }),
+    matched,
+    cacheScope,
+    // As the request listed them, not the copy forced above: see
+    // prefetch-deferral.ts.
+    nav.clientSegmentSet,
+  );
+  (handlerContext as InternalHandlerContext<any, TEnv>)._prefetchDeferral =
+    deferral;
+
   return {
     request,
     url: cleanUrl,

package/src/router/match-middleware/background-revalidation.ts

@@ -113,6 +113,7 @@ import {
   runWithRequestContext,
   type RequestContext,
 } from "../../server/request-context.js";
+import { isFillRequest } from "../segment-resolution/prefetch-deferral.js";
 
 /**
  * Re-render a cached route in the background and write it with
@@ -281,7 +282,16 @@ export function withBackgroundRevalidation<TEnv>(
     // Only trigger background revalidation if:
     // 1. Cache was hit and stale
     // 2. Cache scope exists
-    if (!state.shouldRevalidate || !state.cacheHit || !ctx.cacheScope) {
+    // 3. The request is not a fill (prefetch: false). A fill runs no handler
+    //    of a segment the client holds, and the re-render runs every handler
+    //    of the route. The record stays stale until a request that reads it
+    //    arrives: the prefetch before the fill already was one.
+    if (
+      !state.shouldRevalidate ||
+      !state.cacheHit ||
+      !ctx.cacheScope ||
+      isFillRequest(ctx.handlerContext)
+    ) {
       return;
     }