@rangojs/router 0.22.1 → 0.24.0

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

@@ -9,11 +9,15 @@
 import type { ReactNode } from "react";
 import { invariant } from "../../errors";
 import { revalidate } from "../loader-resolution.js";
-import { evaluateRevalidation } from "../revalidation.js";
+import {
+  evaluateRevalidation,
+  type EvaluateRevalidationOptions,
+} from "../revalidation.js";
 import {
   getParallelEntries,
   getParallelSlotEntries,
   type EntryData,
+  type LoaderEntry,
   type ParallelEntryData,
 } from "../../server/context";
 import type {
@@ -34,6 +38,13 @@ import {
 } from "../logging.js";
 import { resolveLoaderData } from "./loader-cache.js";
 import { entryLoadingMasksLoaders } from "./loader-mask.js";
+import {
+  defersLoader,
+  deferUnit,
+  fillSends,
+  getPrefetchDeferral,
+  registerDeferredLoader,
+} from "./prefetch-deferral.js";
 import {
   handleHandlerResult,
   warnOnStreamedResponse,
@@ -102,6 +113,67 @@ function emitRevalidationDecision(
   });
 }
 
+/**
+ * Whether a segment the client holds (`held`, the set resolution works on)
+ * renders again. A fill keeps it (prefetch-deferral.ts fillSends): no
+ * revalidate() predicate runs and nothing is traced or observed. Any other
+ * request asks the segment's revalidate() chain, and `onEvaluated` sees that
+ * answer.
+ */
+async function revalidateHeld<TEnv>({
+  held,
+  onEvaluated,
+  ...options
+}: EvaluateRevalidationOptions<TEnv> & {
+  held: ReadonlySet<string>;
+  onEvaluated?: (shouldRevalidate: boolean) => void;
+}): Promise<boolean> {
+  const fill = fillSends(options.context, options.segment.id, held);
+  if (fill !== undefined) return fill;
+  const shouldRevalidate = await evaluateRevalidation(options);
+  onEvaluated?.(shouldRevalidate);
+  return shouldRevalidate;
+}
+
+// ---------------------------------------------------------------------------
+// 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)
 // ---------------------------------------------------------------------------
@@ -185,7 +257,7 @@ export async function resolveLoadersWithRevalidation<TEnv>(
               belongsToRoute,
             };
 
-            return await evaluateRevalidation({
+            return await revalidateHeld({
               segment: dummySegment,
               prevParams,
               getPrevSegment: null,
@@ -201,6 +273,7 @@ export async function resolveLoadersWithRevalidation<TEnv>(
               actionContext,
               stale,
               traceSource: "loader",
+              held: clientSegmentIds,
             });
           },
           async () => true,
@@ -226,35 +299,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 +482,7 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
     await collectEntryLoaders(entry, entry.type === "route");
   }
 
+  deliverStartedLoaders(context, allLoaderSegments);
   return { segments: allLoaderSegments, matchedIds: allMatchedIds };
 }
 
@@ -612,8 +723,19 @@ 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");
+    // A fill sends exactly the slots the client lacks, ahead of every rule
+    // below (fillSends).
+    const fill = fillSends(context, parallelId, clientSegmentIds);
     let shouldResolve: boolean;
-    if (isFullRefetch) {
+    if (fill !== undefined) {
+      shouldResolve = fill;
+    } 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 +809,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 +845,7 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
       ...(parallelEntry.mountPath
         ? { mountPath: parallelEntry.mountPath }
         : {}),
+      ...deferred,
     });
 
     if (loaderOrder === "after") {
@@ -750,6 +877,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);
@@ -795,7 +923,7 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
         ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
       };
 
-      const shouldRevalidate = await evaluateRevalidation({
+      return revalidateHeld({
         segment: dummySegment,
         prevParams,
         getPrevSegment: null,
@@ -812,20 +940,26 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
         stale,
         traceSource:
           entry.type === "route" ? "route-handler" : "layout-handler",
+        held: clientSegmentIds,
+        onEvaluated: (shouldRevalidate) => {
+          emitRevalidationDecision(
+            entry.shortCode,
+            context.pathname,
+            routeKey,
+            shouldRevalidate,
+          );
+          debugLog("segment.revalidate", "entry revalidation decision", {
+            segmentId: entry.shortCode,
+            shouldRevalidate,
+          });
+        },
       });
-      emitRevalidationDecision(
-        entry.shortCode,
-        context.pathname,
-        routeKey,
-        shouldRevalidate,
-      );
-      debugLog("segment.revalidate", "entry revalidation decision", {
-        segmentId: entry.shortCode,
-        shouldRevalidate,
-      });
-      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 +1062,7 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
       : {}),
     ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
     _handlerRan: handlerRan,
+    ...deferred,
   };
 
   return { segment, matchedId };
@@ -1020,10 +1155,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 +1171,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 +1202,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 +1316,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)) {
@@ -1221,7 +1346,7 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
         ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
       };
 
-      const shouldRevalidate = await evaluateRevalidation({
+      return revalidateHeld({
         segment: dummySegment,
         prevParams,
         getPrevSegment: null,
@@ -1237,16 +1362,22 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
         actionContext,
         stale,
         traceSource: "orphan-layout",
+        held: clientSegmentIds,
+        onEvaluated: (shouldRevalidate) =>
+          emitRevalidationDecision(
+            orphan.shortCode,
+            context.pathname,
+            routeKey,
+            shouldRevalidate,
+          ),
       });
-      emitRevalidationDecision(
-        orphan.shortCode,
-        context.pathname,
-        routeKey,
-        shouldRevalidate,
-      );
-      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 +1396,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 +1557,6 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
     }
   }
 
+  deliverStartedLoaders(context, allSegments);
   return { segments: allSegments, matchedIds };
 }

package/src/rsc/full-payload.ts

@@ -14,7 +14,11 @@ import type { HandlerContext } from "./handler-context.js";
 import type { RequestContext } from "../server/request-context.js";
 import type { HandleStore } from "../server/handle-store.js";
 import type { Theme } from "../theme/types.js";
-import { documentCacheStoresRender } from "../cache/document-cache.js";
+import {
+  rendersForSharedAudience,
+  rewriteTrail,
+  visitorUrl,
+} from "../server/rewrite-trail.js";
 import { attachTransitionWhen } from "./attach-transition-when.js";
 import { publicRouteName } from "../route-name.js";
 import { resolvedHandleStream } from "../handles/deferred-resolution.js";
@@ -38,7 +42,7 @@ export function buildFullPayload(
 ): RscPayload {
   return {
     metadata: {
-      pathname: url.pathname,
+      pathname: renderedLocation(reqCtx, url).pathname,
       routerId: ctx.router.id,
       basename: ctx.router.basename,
       segments: attachTransitionWhen(m.segments, reqCtx),
@@ -84,6 +88,36 @@ export function buildFullPayload(
   };
 }
 
+/**
+ * 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 function renderedLocation(
+  reqCtx:
+    | Pick<
+        RequestContext<any>,
+        | "_variables"
+        | "_shellCaptureRun"
+        | "_documentCacheRender"
+        | "_payloadVisitorLocation"
+        | "res"
+      >
+    | undefined,
+  url: URL,
+): URL {
+  if (!reqCtx || !rewriteTrail(reqCtx) || rendersForSharedAudience(reqCtx)) {
+    return url;
+  }
+  reqCtx._payloadVisitorLocation = true;
+  return visitorUrl(reqCtx, url);
+}
+
 /**
  * The theme a document payload carries as `metadata.initialTheme` (the
  * ThemeProvider's first state), read with no identity guard: it is the
@@ -116,9 +150,7 @@ export function payloadInitialTheme(
 ): Theme | undefined {
   const config = reqCtx._themeConfig;
   if (!config) return undefined;
-  if (reqCtx._shellCaptureRun || documentCacheStoresRender(reqCtx)) {
-    return config.defaultTheme;
-  }
+  if (rendersForSharedAudience(reqCtx)) return config.defaultTheme;
   const theme = reqCtx._readTheme();
   if (theme !== config.defaultTheme) reqCtx._payloadVisitorTheme = true;
   return theme;