@rangojs/router 0.22.1 → 0.23.0

package/src/router/segment-resolution/revalidation.ts

@@ -14,6 +14,7 @@ import {
   getParallelEntries,
   getParallelSlotEntries,
   type EntryData,
+  type LoaderEntry,
   type ParallelEntryData,
 } from "../../server/context";
 import type {
@@ -34,6 +35,13 @@ import {
 } from "../logging.js";
 import { resolveLoaderData } from "./loader-cache.js";
 import { entryLoadingMasksLoaders } from "./loader-mask.js";
+import {
+  defersLoader,
+  deferUnit,
+  getPrefetchDeferral,
+  isFillRequest,
+  registerDeferredLoader,
+} from "./prefetch-deferral.js";
 import {
   handleHandlerResult,
   warnOnStreamedResponse,
@@ -102,6 +110,45 @@ function emitRevalidationDecision(
   });
 }
 
+// ---------------------------------------------------------------------------
+// prefetch: false (prefetch-deferral.ts)
+// ---------------------------------------------------------------------------
+
+/**
+ * How to deliver a loader a prefetch deferred, kept so deliverStartedLoaders
+ * can deliver it after all. Keyed by the emitted segment object.
+ */
+const deferredLoaderRuns = new WeakMap<ResolvedSegment, () => unknown>();
+
+/**
+ * A deferred loader something started in this request (a handler that awaits
+ * it with ctx.use(), or another loader) ran in the prefetch whatever its flag
+ * says: deliver that run instead of having the fill run it a second time. A
+ * reader starts it through its registration (prefetch-deferral.ts
+ * startDeferredLoader), so the delivery's resolveLoaderData finds the same
+ * run or cache() binding. Called once resolution has awaited every handler it
+ * awaits; a streamed handler that reads the loader later is not seen, and
+ * that loader runs again in the fill.
+ */
+function deliverStartedLoaders<TEnv>(
+  ctx: HandlerContext<any, TEnv>,
+  segments: ResolvedSegment[],
+): void {
+  const plan = getPrefetchDeferral(ctx);
+  if (plan?.mode !== "prefetch") return;
+  const internal = ctx as InternalHandlerContext<any, TEnv>;
+  const started = (loaderId: string): boolean =>
+    plan.deferredLoaders?.get(loaderId)?.started === true ||
+    internal._loaderStarted?.(loaderId) === true;
+  for (const segment of segments) {
+    if (!segment.deferred || segment.type !== "loader") continue;
+    const run = deferredLoaderRuns.get(segment);
+    if (!run || !started(segment.loaderId!)) continue;
+    delete segment.deferred;
+    segment.loaderData = run();
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Revalidation path (partial match)
 // ---------------------------------------------------------------------------
@@ -147,6 +194,7 @@ export async function resolveLoadersWithRevalidation<TEnv>(
   }));
 
   const matchedIds = loaderMeta.map((m) => m.segmentId);
+  const fill = isFillRequest(ctx);
 
   const revalidationChecks = await Promise.all(
     loaderMeta.map(
@@ -173,6 +221,8 @@ export async function resolveLoadersWithRevalidation<TEnv>(
               }
               return true;
             }
+            // Fill: a held segment is skipped outright, no predicate runs.
+            if (fill) return false;
 
             const dummySegment: ResolvedSegment = {
               id: segmentId,
@@ -226,35 +276,72 @@ export async function resolveLoadersWithRevalidation<TEnv>(
   // (matchPartialWithPprReplay) seeds once its doc record hits.
   const bakeLane = !entryLoadingMasksLoaders(entry.loading);
 
+  const kickoff = (
+    loaderEntry: LoaderEntry,
+    segmentId: string,
+    loaderId: string,
+  ): Promise<unknown> =>
+    runInsideLoaderScope(
+      () =>
+        resolveLoaderData(
+          loaderEntry,
+          ctx,
+          ctx.pathname,
+          // `bake`, not awaitBeforeFlush: a navigation evaluation never
+          // carries awaitBeforeFlush, and an ssr: false loader must pin
+          // here exactly as on the document HIT.
+          bakeLane || loaderEntry.bake === true ? segmentId : null,
+        ),
+      loaderId,
+    );
+  const start = (
+    loaderEntry: LoaderEntry,
+    segmentId: string,
+    loaderId: string,
+  ) =>
+    deps.wrapLoaderPromise(
+      kickoff(loaderEntry, segmentId, loaderId),
+      entry,
+      segmentId,
+      ctx.pathname,
+      errorContext,
+    );
+
   const loadersToRun = revalidationChecks.filter((c) => c.shouldRun);
   const segments: ResolvedSegment[] = loadersToRun.map(
-    ({ loaderEntry, loader, segmentId, index }) => ({
-      id: segmentId,
-      namespace: entry.id,
-      type: "loader" as const,
-      index,
-      component: null,
-      params: ctx.params,
-      loaderId: loader.$$id,
-      loaderData: deps.wrapLoaderPromise(
-        runInsideLoaderScope(() =>
-          resolveLoaderData(
-            loaderEntry,
-            ctx,
-            ctx.pathname,
-            // `bake`, not awaitBeforeFlush: a navigation evaluation never
-            // carries awaitBeforeFlush, and an ssr: false loader must pin
-            // here exactly as on the document HIT.
-            bakeLane || loaderEntry.bake === true ? segmentId : null,
-          ),
-        ),
-        entry,
-        segmentId,
-        ctx.pathname,
-        errorContext,
-      ),
-      belongsToRoute,
-    }),
+    ({ loaderEntry, loader, segmentId, index }) => {
+      const base = {
+        id: segmentId,
+        namespace: entry.id,
+        type: "loader" as const,
+        index,
+        component: null,
+        params: ctx.params,
+        loaderId: loader.$$id,
+      };
+      // Only a loader on a segment the client lacks (defersLoader). It
+      // would have run. Registered, not started: it runs, and reads its
+      // cache(), only if a reader starts it (startDeferredLoader).
+      if (defersLoader(ctx, loaderEntry, segmentId)) {
+        registerDeferredLoader(ctx, loader.$$id, shortCode, () =>
+          kickoff(loaderEntry, segmentId, loader.$$id),
+        );
+        const deferred: ResolvedSegment = {
+          ...base,
+          belongsToRoute,
+          deferred: true,
+        };
+        deferredLoaderRuns.set(deferred, () =>
+          start(loaderEntry, segmentId, loader.$$id),
+        );
+        return deferred;
+      }
+      return {
+        ...base,
+        loaderData: start(loaderEntry, segmentId, loader.$$id),
+        belongsToRoute,
+      };
+    },
   );
 
   return { segments, matchedIds };
@@ -372,6 +459,7 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
     await collectEntryLoaders(entry, entry.type === "route");
   }
 
+  deliverStartedLoaders(context, allLoaderSegments);
   return { segments: allLoaderSegments, matchedIds: allMatchedIds };
 }
 
@@ -612,8 +700,17 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
     // on the next request, perpetuating the staleness).
     matchedIds.push(parallelId);
 
+    // A slot below a unit a prefetch skipped goes with it, and no predicate
+    // runs: a prefetch sends what the slot declares instead of running its
+    // handler.
+    let deferred = deferUnit(context, parallelId, "below");
     let shouldResolve: boolean;
-    if (isFullRefetch) {
+    if (isFillRequest(context)) {
+      // Fill: only what the client does not hold renders, no predicate runs.
+      shouldResolve = !clientSegmentIds.has(parallelId);
+    } else if (deferred) {
+      shouldResolve = true;
+    } else if (isFullRefetch) {
       // Client has nothing cached — slot MUST render. User revalidate fns are
       // bypassed here because returning false would leave the segment blank
       // with no client-side fallback.
@@ -687,18 +784,22 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
       shouldResolve,
     );
 
-    const { component, handlerRan } = await resolveParallelSlotComponent({
-      shouldResolve,
-      parallelEntry,
-      slot,
-      parallelId,
-      handler,
-      context,
-      deps,
-      routeKey,
-      params,
-      boundaryEntry: options?.boundaryEntry ?? entry,
-    });
+    // A slot with its own flagged loading() is its own unit.
+    if (shouldResolve) deferred ??= deferUnit(context, parallelId, "slot");
+    const { component, handlerRan } = deferred
+      ? { component: null, handlerRan: false }
+      : await resolveParallelSlotComponent({
+          shouldResolve,
+          parallelEntry,
+          slot,
+          parallelId,
+          handler,
+          context,
+          deps,
+          routeKey,
+          params,
+          boundaryEntry: options?.boundaryEntry ?? entry,
+        });
 
     segments.push({
       id: parallelId,
@@ -719,6 +820,7 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
       ...(parallelEntry.mountPath
         ? { mountPath: parallelEntry.mountPath }
         : {}),
+      ...deferred,
     });
 
     if (loaderOrder === "after") {
@@ -750,6 +852,7 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
   const matchedId = entry.shortCode;
 
   let handlerRan = false;
+  let deferred: { readonly deferred: true } | undefined;
   const component = await revalidate(
     async () => {
       const hasSegment = clientSegmentIds.has(entry.shortCode);
@@ -777,6 +880,8 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
         }
         return true;
       }
+      // Fill: a held segment is skipped outright, no predicate runs.
+      if (isFillRequest(context)) return false;
 
       const dummySegment: ResolvedSegment = {
         id: entry.shortCode,
@@ -826,6 +931,10 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
       return shouldRevalidate;
     },
     async () => {
+      // Only an entry the client lacks (defersUnit). Its handler would
+      // have run, and a prefetch sends the entry's fallback in its place.
+      deferred = deferUnit(context, entry.shortCode, "chain");
+      if (deferred) return null;
       handlerRan = true;
       const doneHandler = track(`handler:${entry.id}`, 2);
       (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
@@ -928,6 +1037,7 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
       : {}),
     ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
     _handlerRan: handlerRan,
+    ...deferred,
   };
 
   return { segment, matchedId };
@@ -1020,10 +1130,8 @@ export async function resolveSegmentWithRevalidation<TEnv>(
     }
   }
 
-  if (routeHandlerResult) {
-    // Route entry: handler already executed above; resolve parallels
-    // (handler data visible) then push handler segment last for tree order.
-    const parallelResult = await resolveParallelSegmentsWithRevalidation(
+  const resolveSlots = () =>
+    resolveParallelSegmentsWithRevalidation(
       entry,
       params,
       context,
@@ -1038,6 +1146,11 @@ export async function resolveSegmentWithRevalidation<TEnv>(
       actionContext,
       stale,
     );
+
+  if (routeHandlerResult) {
+    // Route entry: handler already executed above; resolve parallels
+    // (handler data visible) then push handler segment last for tree order.
+    const parallelResult = await resolveSlots();
     segments.push(...parallelResult.segments);
     matchedIds.push(...parallelResult.matchedIds);
 
@@ -1064,21 +1177,7 @@ export async function resolveSegmentWithRevalidation<TEnv>(
     segments.push(handlerResult.segment);
     matchedIds.push(handlerResult.matchedId);
 
-    const parallelResult = await resolveParallelSegmentsWithRevalidation(
-      entry,
-      params,
-      context,
-      belongsToRoute,
-      clientSegmentIds,
-      prevParams,
-      request,
-      prevUrl,
-      nextUrl,
-      routeKey,
-      deps,
-      actionContext,
-      stale,
-    );
+    const parallelResult = await resolveSlots();
     segments.push(...parallelResult.segments);
     matchedIds.push(...parallelResult.matchedIds);
 
@@ -1192,6 +1291,7 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
   // so ctx.set() values are visible to parallel children.
   matchedIds.push(orphan.shortCode);
 
+  let deferred: { readonly deferred: true } | undefined;
   const component = await revalidate(
     async () => {
       if (!clientSegmentIds.has(orphan.shortCode)) {
@@ -1208,6 +1308,8 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
         }
         return true;
       }
+      // Fill: a held segment is skipped outright, no predicate runs.
+      if (isFillRequest(context)) return false;
 
       const dummySegment: ResolvedSegment = {
         id: orphan.shortCode,
@@ -1246,7 +1348,12 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
       );
       return shouldRevalidate;
     },
-    async () => resolveLayoutComponent(orphan, context),
+    async () => {
+      // Below a unit a prefetch skipped: the orphan goes with it.
+      deferred = deferUnit(context, orphan.shortCode, "below");
+      if (deferred) return null;
+      return resolveLayoutComponent(orphan, context);
+    },
     () => null,
   );
 
@@ -1265,6 +1372,7 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
       deps.viewTransitionDefault,
     ),
     ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
+    ...deferred,
   });
 
   // Resolve the orphan layout's parallel slots through the shared main-path
@@ -1425,5 +1533,6 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
     }
   }
 
+  deliverStartedLoaders(context, allSegments);
   return { segments: allSegments, matchedIds };
 }

package/src/rsc/rsc-rendering.ts

@@ -94,6 +94,7 @@ import {
   type DevShellLookup,
 } from "./shell-build-manifest.js";
 import { contextGet } from "../context-var.js";
+import { PREFETCH_HEADER } from "../prefetch-markers.js";
 import {
   isWarmReplace,
   noteWarmShellEvent,
@@ -302,7 +303,10 @@ type PreparedRender =
   | {
       kind: "payload";
       payload: RscPayload;
-      /** The response depends on the source page: an intercept targets the route. */
+      /**
+       * The response depends on the source page: an intercept targets the
+       * route, or it carries deferred units (`prefetch: false`).
+       */
       sourceScoped: boolean;
       pprReplayStatus?: PprReplayStatus;
       /** The key a navigation-only heal capture stores under, when one is needed. */
@@ -831,6 +835,12 @@ function* preparePayloadPlan<TEnv>(
       };
     }
 
+    // What a prefetch defers depends on what the source page holds: a page
+    // that holds the segment gets it rendered. Adopted from another page, a
+    // deferring payload held the click on a fill for content a plain click
+    // showed at once, and ran held work again.
+    const deferring = result.segments.some((s) => s.deferred);
+    if (deferring) reqCtx._payloadDeferred = true;
     return {
       kind: "payload",
       payload: {
@@ -860,7 +870,7 @@ function* preparePayloadPlan<TEnv>(
           stateCookieName: ctx.router.resolvedStateCookieName,
         },
       },
-      sourceScoped: result.interceptTargeted === true,
+      sourceScoped: result.interceptTargeted === true || deferring,
       pprReplayStatus,
       healKey,
     };
@@ -1200,16 +1210,34 @@ function renderPreparedRscResponse<TEnv>(
     rscHeaders["x-rsc-prefetch-scope"] = "source";
   }
   // Enable browser HTTP caching for prefetch responses only.
-  // Requires X-Rango-Prefetch header (sent by Link prefetch fetch),
-  // a source-agnostic response (see sourceScoped above), and a configured
-  // cache-control value (false disables caching).
-  const isPrefetch = requestHeaders(request).has("X-Rango-Prefetch");
-  if (isPrefetch && isPartial && !sourceScoped) {
+  // Requires a prefetch request (X-Rango-Prefetch, sent by Link prefetch
+  // fetch), a source-agnostic response (see sourceScoped above), and a
+  // configured cache-control value (false disables caching).
+  if (reqCtx._requestKind === "prefetch" && isPartial && !sourceScoped) {
     const cc = ctx.router.prefetchCacheControl;
     if (cc) {
       rscHeaders["cache-control"] = cc;
     }
   }
+  // prefetch: false (docs/design/prefetch-false.md, R7). A response that
+  // carries deferred units answers one page's prefetch, and a fill is the
+  // second half of one adoption: neither is reused by a shared cache or the
+  // document cache (which also refuses a payload marked `_payloadDeferred`),
+  // whatever Cache-Control the route set. A route with no flag keeps its
+  // headers.
+  if (
+    reqCtx._payloadDeferred ||
+    (isPartial && reqCtx._requestKind === "fill")
+  ) {
+    rscHeaders["cache-control"] = NOT_REUSED;
+  }
+  // The browser may still keep the body, and answers from it without asking
+  // while it reloads a document for back/forward. A navigation is the same
+  // URL as its prefetch: the header that tells them apart keeps the deferring
+  // body from answering one.
+  if (reqCtx._payloadDeferred) {
+    rscHeaders.vary += `, ${PREFETCH_HEADER}`;
+  }
 
   const isFlightResponse = isRscRequest(request, url, isPartial);
   const stageTracking = {
@@ -1694,6 +1722,21 @@ function publishTailTiming(
 
 const PENDING = Symbol("pending");
 
+/**
+ * Cache-Control of a response that is not to be reused: one that carries
+ * deferred units (`prefetch: false`), and a fill. `private` keeps it out of
+ * shared caches; `no-cache` makes the browser ask again, and with no
+ * validator on the response that is a full request. The browser may keep the
+ * body all the same (Chromium does) and answers from it, without asking,
+ * while it reloads a document for back/forward. That is harmless: the client
+ * completes any payload that carries deferred work, wherever it came from.
+ * Not `no-store`:
+ * Chromium reports a `no-store` fetch whose body is read through a stream
+ * as canceled (net::ERR_ABORTED in DevTools, and Playwright's
+ * response.finished() never settles), though every byte arrived.
+ */
+const NOT_REUSED = "private, no-cache";
+
 /**
  * Whether `value` is not a promise, or a promise that has already settled:
  * racing it against an already-resolved promise, a settled one's reaction is

package/src/rsc/shell-capture.ts

@@ -73,6 +73,7 @@ import {
 } from "../server/context.js";
 import { isThenable } from "../handles/is-thenable.js";
 import { requestHeaders } from "../server/request-headers.js";
+import { PREFETCH_HEADER } from "../prefetch-markers.js";
 import type {
   CachedEntryData,
   ShellCacheEntry,
@@ -1448,7 +1449,7 @@ function createNavigationCaptureRequest(request: Request, url: URL): Request {
   headers.set("accept", "text/html");
   for (const name of [
     "rsc-action",
-    "x-rango-prefetch",
+    PREFETCH_HEADER,
     "x-rango-state",
     "x-rsc-hmr",
     "x-rsc-router-client-path",

package/src/segment-loader-promise.ts

@@ -1,5 +1,6 @@
 import type { ResolvedSegment } from "./types.js";
 import { INTERNAL_RANGO_DEBUG } from "./internal-debug.js";
+import { asStream } from "./browser/defer.js";
 
 /**
  * Browser: a boundary is handed the settled value. React treats a promise as
@@ -7,7 +8,13 @@ import { INTERNAL_RANGO_DEBUG } from "./internal-debug.js";
  * promise it has not read, in a render that cannot wait, shows its fallback.
  * So a cache entry records its array once the aggregate fulfils and later
  * calls return that same array; until then (and when it rejects) they return
- * the promise. A boundary with no loaders gets one shared empty array.
+ * the promise. A boundary with no loaders gets one shared empty array. An
+ * aggregate whose sources are all streams that have fulfilled (React's
+ * `status` on the thenable, which Flight sets itself; a plain value is not a
+ * stream, whatever fields it carries) is known on its first
+ * call and is the array from the start: the sources of a page whose entry was
+ * rewritten without a render (browser/partial-update.ts fillHoles) are
+ * first aggregated by the next navigation that keeps them.
  *
  * Server: a fresh promise per call, so Suspense emits the fallback in the
  * streamed HTML. A shared resolved promise would carry React's `.status`
@@ -22,10 +29,10 @@ const IS_BROWSER = typeof window !== "undefined";
 
 interface LoaderCacheEntry {
   sources: any[];
-  // Resolves to the same array it records in `value`; a rejection passes
-  // through untouched.
-  promise: Promise<any[]>;
-  value?: any[];
+  // The aggregate while it is pending (a rejection passes through untouched),
+  // then the array it fulfilled with. The array from the start for sources
+  // that have all fulfilled.
+  result: Promise<any[]> | any[];
 }
 
 // Cap the per-key entries array. A stable first-ref (e.g. a layout loader whose
@@ -91,13 +98,7 @@ export function buildLoaderPromise(loaders: ResolvedSegment[]): Promise<any[]> {
       }
     }
   }
-  return Promise.all(
-    loaders.map((loader) =>
-      loader.loaderData instanceof Promise
-        ? loader.loaderData
-        : Promise.resolve(loader.loaderData),
-    ),
-  );
+  return Promise.all(loaders.map((loader) => asStream(loader.loaderData)));
 }
 
 function isObjectLike(value: unknown): value is object {
@@ -131,17 +132,19 @@ export function getMemoizedLoaderPromise(
   if (entries) {
     for (const entry of entries) {
       if (hasSameReferences(entry.sources, sources)) {
-        return entry.value ?? entry.promise;
+        return entry.result;
       }
     }
   }
 
-  const newEntry = { sources } as LoaderCacheEntry;
-  const promise = buildLoaderPromise(loaders).then((values) => {
-    newEntry.value = values;
-    return values;
-  });
-  newEntry.promise = promise;
+  const newEntry: LoaderCacheEntry = { sources, result: [] };
+  newEntry.result = sources.every(
+    (source) =>
+      source instanceof Promise &&
+      (source as { status?: string }).status === "fulfilled",
+  )
+    ? sources.map((source) => source.value)
+    : buildLoaderPromise(loaders).then((values) => (newEntry.result = values));
   if (entries) {
     // Bound the array: drop the oldest entry before appending when at the cap.
     if (entries.length >= MAX_ENTRIES_PER_KEY) {
@@ -153,5 +156,5 @@ export function getMemoizedLoaderPromise(
   } else {
     primitiveLoaderCache.set(first, [newEntry]);
   }
-  return promise;
+  return newEntry.result;
 }