@rangojs/router 0.32.0 → 0.33.0

package/src/router/segment-resolution/prefetch-deferral.ts

@@ -32,27 +32,41 @@ import {
   type EntryData,
   type InterceptEntry,
   type LoaderEntry,
+  segmentPinOf,
 } from "../../server/context.js";
 import { requestHeaders } from "../../server/request-headers.js";
 import type { HandlerContext, InternalHandlerContext } from "../../types.js";
 import type { CacheScope } from "../../cache/cache-scope.js";
-import { PREFETCH_HEADER } from "../../prefetch-markers.js";
+import { PREFETCH_HEADER, PREFETCH_INTENT } from "../../prefetch-markers.js";
 import { WIRE } from "../../wire-params.js";
 import { isInterceptSegment } from "../../browser/intercept-utils.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.
+ * over the prefetch header. `"prefetch"` is a speculative prefetch (viewport,
+ * render) and `"intent"` a hover or an explicit `prefetch()` call
+ * (PREFETCH_INTENT): both are prefetches, and only the first defers. 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 function requestKind(
   request: Request,
   rawUrl: URL,
-): "prefetch" | "fill" | undefined {
+): RequestKind | undefined {
   if (rawUrl.searchParams.has(WIRE.fill)) return "fill";
-  return requestHeaders(request).has(PREFETCH_HEADER) ? "prefetch" : undefined;
+  const prefetch = requestHeaders(request).get(PREFETCH_HEADER);
+  if (prefetch === null) return undefined;
+  return prefetch === PREFETCH_INTENT ? "intent" : "prefetch";
+}
+
+/** requestKind's answer for a marked request. */
+export type RequestKind = "prefetch" | "intent" | "fill";
+
+/** A prefetch of either kind: speculative or intent. */
+export function isPrefetchKind(kind: RequestKind | undefined): boolean {
+  return kind === "prefetch" || kind === "intent";
 }
 
 /** Static, per matched chain. */
@@ -173,7 +187,6 @@ const EMPTY_SCOPE: DeferralScope = {
 };
 
 const scopes = new WeakMap<EntryData, DeferralScope>();
-const warnedBakeLoaders = new Set<string>();
 
 /**
  * The deferral scope of a matched chain, memoized on its leaf entry (entries
@@ -192,9 +205,6 @@ export function resolveDeferralScope(
   const loaderIds = new Set<string>();
   const units = new Map<EntryData, DeferralUnit>();
   const chain = new Set(entries);
-  // ssr: false on a ppr route is the bake lane (loader-cache.ts
-  // resolveLoaderData): shell material, served from the record.
-  const pprRoute = isPprEntry(leaf);
   // A clientUrls() group route renders loading() itself and its handler is
   // ClientUrlsRoot (segment-system.tsx keys it by group): a unit would hand
   // React a promise in place of the optimistic destination on screen. So
@@ -214,20 +224,8 @@ export function resolveDeferralScope(
     for (const loaderEntry of entry.loader ?? []) {
       const own = loaderEntry.prefetch === false;
       if (!own && behind.length === 0) continue;
-      if (pprRoute && loaderEntry.bake) {
-        if (
-          process.env.NODE_ENV !== "production" &&
-          loaderEntry.prefetch === false &&
-          !warnedBakeLoaders.has(loaderEntry.loader.$$id)
-        ) {
-          warnedBakeLoaders.add(loaderEntry.loader.$$id);
-          console.warn(
-            `[rango] loader "${loaderEntry.loader.$$id}" is registered with ssr: false and prefetch: false on a ppr route ("${leaf.id}"). ` +
-              `Under ppr an ssr: false loader is baked into the shell and served from it, so prefetch: false is ignored there. Drop one of the two options.`,
-          );
-        }
-        continue;
-      }
+      // An ssr: false loader on a ppr route is in scope too: whether this
+      // request serves it from a shell pin is per request (defersLoader).
       loaders.set(loaderEntry, own ? true : behind);
       loaderIds.add(loaderEntry.loader.$$id);
     }
@@ -303,7 +301,9 @@ export function resolveInterceptDeferralScope(
 
 /**
  * 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
+ * `prefetch` are requestKind's answer). `prefetch` is a speculative prefetch
+ * only: an intent prefetch defers nothing, like the navigation it starts
+ * early (R16). 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, and a shell capture is never a prefetch whatever the request that
@@ -496,7 +496,7 @@ export function startDeferredLoader(
 /**
  * The segment a run of `loaderId` files its handle pushes under: the one
  * that registers it when it is registered (registerDeferredLoader), else the
- * segment being resolved.
+ * segment whose code starts it (segmentPinOf).
  */
 export function loaderOwner(
   ctx: HandlerContext<any, any>,
@@ -504,8 +504,7 @@ export function loaderOwner(
 ): string | undefined {
   const internal = ctx as InternalHandlerContext<any, any>;
   return (
-    internal._deferredLoaders?.get(loaderId)?.owner ??
-    internal._currentSegmentId
+    internal._deferredLoaders?.get(loaderId)?.owner ?? segmentPinOf(internal)
   );
 }
 
@@ -514,18 +513,26 @@ export function loaderOwner(
  * 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.
+ *
+ * `servesPin` (loader-cache.ts servesLoaderPin) answers whether this request
+ * serves the loader from a pin of a document-captured shell. Such a loader
+ * is not deferred: its body does not decide the value, and the pin is what
+ * the document shows. On every other request it would run, so it is
+ * deferred as on a route without ppr. Asked when loaders resolve, after a
+ * replay HIT has armed the pins (rsc-rendering.ts matchPartialWithPprReplay).
  */
 export function defersLoader(
   ctx: HandlerContext<any, any>,
   loaderEntry: LoaderEntry,
   segmentId: string,
+  servesPin: (loaderEntry: LoaderEntry) => boolean,
 ): boolean {
   const plan = getPrefetchDeferral(ctx);
   if (plan?.mode !== "prefetch" || plan.held.has(segmentId)) return false;
   const by = plan.scope.loaders.get(loaderEntry);
-  return (
-    by === true || (by !== undefined && by.some((id) => !plan.held.has(id)))
-  );
+  const deferrable =
+    by === true || (by !== undefined && by.some((id) => !plan.held.has(id)));
+  return deferrable && !servesPin(loaderEntry);
 }
 
 /** A unit whose handler output is not stored: a prefetch can skip it. */

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

@@ -40,7 +40,7 @@ import {
   pushRevalidationTraceEntry,
   isTraceActive,
 } from "../logging.js";
-import { resolveLoaderData } from "./loader-cache.js";
+import { resolveLoaderData, servesLoaderPin } from "./loader-cache.js";
 import {
   entryLoadingMasksLoaders,
   isShellCaptureActive,
@@ -65,6 +65,7 @@ import {
   noteThrower,
 } from "./helpers.js";
 import { applyViewTransitionDefault } from "./view-transition-default.js";
+import { isRenderableLoading } from "../../types/boundaries.js";
 import { isLayoutLoaderCopy } from "../../client-urls/layout-loader-copies.js";
 import { getRouterContext } from "../router-context.js";
 import { observeEvent, observeSegmentHandler } from "../instrument.js";
@@ -74,6 +75,7 @@ import {
   track,
   RangoContext,
   runInsideLoaderScope,
+  runAsSegment,
   latchCachedHeaderScope,
   latchPprHeaderScopeForEntries,
 } from "../../server/context.js";
@@ -267,6 +269,28 @@ export function ownerOf(
   };
 }
 
+/**
+ * A route's loader copies inherited into a child layout with parallel slots
+ * are redundant beside the route's own loader segments: true when the route
+ * renders no loading() fallback on any request, so nothing hides the route's
+ * copy from useLoader() in the slots. A redundant copy is never resolved, on
+ * any request: the walkers check this before they inherit.
+ *
+ * Decided from the entry, never from the route segment's `loading`, which
+ * differs between requests: `loading(fallback, { ssr: false })` is `null` on
+ * a document (applyDocumentModeLoading) and the fallback on partials, and the
+ * walkers emit `loading(false)` as `null` too. A copy sent on one request and
+ * not on the next gives the layout a loader entry it did not have, so
+ * renderSegments wraps it in StreamedLoaderErrorBoundary and React remounts
+ * it with its Outlet (docs/tree-structure.md). Resolving a redundant copy and
+ * dropping it from the payload later is not enough: when the route's own
+ * loader is held (its revalidate() declines), the copy is new to the client,
+ * so it re-runs and is sent without the route's copy beside it.
+ */
+export function inheritedCopyRedundant(route: EntryData): boolean {
+  return !isRenderableLoading(route.loading) && route.loadingSsr !== false;
+}
+
 /**
  * resolveOwnerLoaders has something to resolve for `entry`'s loaders. The
  * walker checks before the call: most entries own none, and the async call
@@ -526,10 +550,14 @@ export async function resolveOwnerLoaders<TEnv>(
     // 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)) {
+    if (defersLoader(ctx, loaderEntry, segmentId, servesLoaderPin)) {
       registerDeferredLoader(ctx, loader.$$id, shortCode, () =>
         kickoff(loaderEntry, segmentId),
       );
+      // A ppr shell record this request restored keeps an ssr: false
+      // loader's pushes as copies that wait for its run (loaderPins "hole").
+      // No run is made here: drop them, the fill sends the run's pushes.
+      _getRequestContext()?._handleStore?.settleLoaderRun(loader.$$id);
       const deferred: ResolvedSegment = {
         id: segmentId,
         namespace: owner.namespace,
@@ -656,7 +684,8 @@ export async function resolveLoadersOnly<TEnv>(
         entry.type === "route" &&
         entry.loader &&
         entry.loader.length > 0 &&
-        Object.keys(layoutEntry.parallel).length > 0
+        Object.keys(layoutEntry.parallel).length > 0 &&
+        !inheritedCopyRedundant(entry)
       ) {
         const inherited = await resolveOwnerLoaders(
           pass,
@@ -666,7 +695,6 @@ export async function resolveLoadersOnly<TEnv>(
         for (const seg of inherited.segments) {
           if (!seenIds.has(seg.id)) {
             seenIds.add(seg.id);
-            seg._inherited = true;
             allLoaderSegments.push(seg);
           }
         }
@@ -805,7 +833,7 @@ async function resolveParallelSlotComponent<TEnv>(
       // A throw before the slot streams reaches the owning entry's boundary.
       try {
         if (hasLoadingFallback) {
-          const result = run();
+          const result = runAsSegment(parallelId, run);
           if (result instanceof Promise) {
             warnOnStreamedResponse(result, parallelId);
             result.finally(doneHandler).catch(() => {});
@@ -1174,7 +1202,9 @@ async function resolveRouteComponent<TEnv>(
   }
   if (!actionContext) {
     const result = handleHandlerResult(
-      observeSegmentHandler(entry.shortCode, entry.id, handler, context),
+      runAsSegment(entry.shortCode, () =>
+        observeSegmentHandler(entry.shortCode, entry.id, handler, context),
+      ),
     );
     if (result instanceof Promise) {
       warnOnStreamedResponse(result, entry.id);
@@ -1475,17 +1505,14 @@ export async function resolveOrphanLayout<TEnv>(
     parentRouteEntry &&
     parentRouteEntry.loader &&
     parentRouteEntry.loader.length > 0 &&
-    Object.keys(orphan.parallel).length > 0
+    Object.keys(orphan.parallel).length > 0 &&
+    !inheritedCopyRedundant(parentRouteEntry)
   ) {
     const inheritedResult = await resolveOwnerLoaders(
       pass,
       ownerOf(parentRouteEntry, orphan.shortCode),
       belongsToRoute,
     );
-    // Tag as inherited so buildMatchResult can deduplicate when safe
-    for (const s of inheritedResult.segments) {
-      s._inherited = true;
-    }
     segments.push(...inheritedResult.segments);
     matchedIds.push(...inheritedResult.matchedIds);
   }
@@ -1505,7 +1532,8 @@ export async function resolveOrphanLayout<TEnv>(
       handlerRan = true;
       // Its handler's pushes are its own. Pinned only while it runs: a route
       // under loading() streams its handler, whose pushes after an await
-      // read the pin after this returns.
+      // read the pin after this returns where a runtime lost its
+      // runAsSegment scope (segmentPinOf).
       const internal = context as InternalHandlerContext<any, TEnv>;
       const pinned = internal._currentSegmentId;
       internal._currentSegmentId = orphan.shortCode;

package/src/router/source-reads.ts

@@ -0,0 +1,122 @@
+/**
+ * Recording what revalidate() rules read of the source page, so a prefetch
+ * answer a rule kept is shared between the pages with equal values of what
+ * was read (prefetch-source-scope.ts).
+ */
+
+import {
+  createSourceReads,
+  formatSourceLabel,
+  mergeSourceReads,
+  PARAMS_SCOPE_PREFIX,
+  shapeOfReads,
+  type SourcePage,
+  type SourceReads,
+} from "../prefetch-source-scope.js";
+
+/**
+ * The source group of a match whose diff a source read decided: the reads
+ * every kept decision made, unioned, and the source page they read.
+ */
+export interface SourceHeld extends SourcePage {
+  reads: SourceReads;
+}
+
+/**
+ * A copy of `params` whose reads land in `reads`: an enumerable getter per
+ * key, so a spread, Object.entries, JSON.stringify or structuredClone reads
+ * every key. Not a Proxy: structuredClone refuses one. A read of an absent
+ * key is not recorded and needs no record: the key set is part of the group
+ * (`reads.keys`), so a page in the group lacks that key too.
+ */
+export function recordingParams(
+  params: Readonly<Record<string, string>>,
+  reads: SourceReads,
+): Record<string, string> {
+  reads.keys = true;
+  const view: Record<string, string> = {};
+  for (const name of Object.keys(params)) {
+    Object.defineProperty(view, name, {
+      enumerable: true,
+      configurable: true,
+      get() {
+        reads.params.add(name);
+        return params[name];
+      },
+      // A rule may write to the object, as to the plain one it replaces:
+      // what it wrote is its own value, not the source's.
+      set(value: string) {
+        Object.defineProperty(view, name, {
+          value,
+          writable: true,
+          enumerable: true,
+          configurable: true,
+        });
+      },
+    });
+  }
+  return view;
+}
+
+/**
+ * Add `reads` to the source group of the match `context` decides for. All
+ * of one match's decisions read the same source page; a caller that reads
+ * no route name passes none.
+ */
+export function markSourceHeld(
+  context: { _sourceHeld?: SourceHeld },
+  reads: SourceReads,
+  page: SourcePage,
+): void {
+  const held = (context._sourceHeld ??= {
+    reads: createSourceReads(),
+    params: page.params,
+    routeName: undefined,
+  });
+  if (page.routeName !== undefined) held.routeName = page.routeName;
+  mergeSourceReads(held.reads, reads);
+}
+
+/**
+ * The `x-rsc-prefetch-scope` of a partial response, or undefined when every
+ * source page may share it.
+ *
+ * - `source`: the exact source page's. A route an intercept targets renders
+ *   the modal or the full page depending on the source, so a full page
+ *   prefetched where the intercept does not apply would otherwise serve a
+ *   later click where it does (#1007); a response with deferred units
+ *   answers one page's prefetch (`sourceOnly`); a kept rule that read
+ *   `currentUrl` can depend on anything in it; and a source-held answer that
+ *   sends nothing (`sentNothing`) commits treeless on the page that adopts
+ *   it, which keeps its whole tree without checking it holds the ids the
+ *   answer kept (partial-update.ts): only the source is known to hold them.
+ * - `params; <label>`: a revalidate() rule read the source's params or route
+ *   name and kept a segment. A page that adopted the answer would keep its
+ *   own copy of that segment (#1331), which is right only where the rule
+ *   decides the same: on pages with equal values of what it read. The label
+ *   names them (prefetch-source-scope.ts); the browser stores the answer
+ *   under it. A page that lacks a kept id refetches (the commit's
+ *   missing-segment check), as for a shared answer.
+ */
+export function prefetchScopeOf(
+  sourceOnly: boolean,
+  held: SourceHeld | undefined,
+  sentNothing: boolean,
+): string | undefined {
+  if (sourceOnly) return "source";
+  if (!held) return undefined;
+  if (held.reads.url || sentNothing) return "source";
+  return (
+    PARAMS_SCOPE_PREFIX + formatSourceLabel(shapeOfReads(held.reads), held)
+  );
+}
+
+/** Every param of the source read: its params must equal the page's. */
+export function readsOfAllParams(
+  params: Readonly<Record<string, string>>,
+): SourceReads {
+  const reads = createSourceReads();
+  reads.keys = true;
+  for (const name of Object.keys(params)) reads.params.add(name);
+  return reads;
+}

package/src/router/types.ts

@@ -91,10 +91,11 @@ export interface MatchApiDeps<TEnv = any> {
   findMatch: (pathname: string, ms?: any) => any;
   getMetricsStore: () => any;
   findInterceptForRoute: (
-    routeKey: string,
+    routeKeys: string | readonly string[],
     parentEntry: EntryData | null,
     selectorContext: InterceptSelectorContext | null,
     isAction: boolean,
+    held?: ReadonlySet<string>,
   ) => { intercept: InterceptEntry; entry: EntryData } | null;
   callOnError: SegmentResolutionDeps<TEnv>["callOnError"];
   findNearestErrorBoundary: SegmentResolutionDeps<TEnv>["findNearestErrorBoundary"];

package/src/router.ts

@@ -654,12 +654,21 @@ export function createRouter<TEnv = any>(
     viewTransitionDefault: viewTransitionOption,
   };
 
+  // Create segment resolution wrappers bound to segmentDeps
+  const {
+    resolveLoadersOnly,
+    buildEntryRevalidateMap,
+    resolveAllSegments,
+    findInterceptForRoute,
+    resolveInterceptEntry,
+    resolveInterceptLoadersOnly,
+  } = createSegmentWrappers<TEnv>(segmentDeps);
+
   // Match API dependencies
   const matchApiDeps: MatchApiDeps<TEnv> = {
     findMatch: (pathname: string, ms?: any) => findMatch(pathname, ms),
     getMetricsStore,
-    findInterceptForRoute: (routeKey, parentEntry, selectorContext, isAction) =>
-      findInterceptForRoute(routeKey, parentEntry, selectorContext, isAction),
+    findInterceptForRoute,
     callOnError,
     findNearestErrorBoundary,
     // Use per-router manifest when available, otherwise the static named map
@@ -667,16 +676,6 @@ export function createRouter<TEnv = any>(
     getRouteMap: () => getRouterManifest(routerId) ?? mergedRouteMap,
   };
 
-  // Create segment resolution wrappers bound to segmentDeps
-  const {
-    resolveLoadersOnly,
-    buildEntryRevalidateMap,
-    resolveAllSegments,
-    findInterceptForRoute,
-    resolveInterceptEntry,
-    resolveInterceptLoadersOnly,
-  } = createSegmentWrappers<TEnv>(segmentDeps);
-
   // Lazy evaluation deps — captures closure state for extracted evaluateLazyEntry
   const lazyEvalDeps: LazyEvalDeps<TEnv> = {
     routesEntries,

package/src/rsc/helpers.ts

@@ -10,7 +10,10 @@ import {
   setRequestContextParams,
 } from "../server/request-context.js";
 import type { RequestContext } from "../server/request-context.js";
-import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
+import {
+  resolveLocationStateEntries,
+  type LocationStateEntry,
+} from "../browser/react/location-state-shared.js";
 import {
   isRedirectResponse,
   isWebSocketUpgradeResponse,
@@ -343,13 +346,15 @@ export function interceptRedirectForPartial(
  * is populated. A `document` payload (a page load's or a no-JS form post's
  * bootstrap payload) that carries state marks the request
  * `_documentLocationState`: it is the visitor's, so no shared cache keeps it
- * (server/document-location-state.ts).
+ * (server/document-location-state.ts). `locationState` defaults to the
+ * current request context's; a shell HIT's tail passes the state set before
+ * its render (rsc/rsc-rendering.ts serveShellHit).
  */
 export function attachLocationStateIfPresent(
   payload: RscPayload,
   document = false,
+  locationState: LocationStateEntry[] | undefined = getLocationState(),
 ): void {
-  const locationState = getLocationState();
   if (locationState && locationState.length > 0) {
     payload.metadata!.locationState =
       resolveLocationStateEntries(locationState);

package/src/rsc/prefetch-render-error.ts

@@ -11,8 +11,13 @@
  * So the body ends cleanly with one more row, PREFETCH_FAILED_ROW, which the
  * Flight decoder skips and teeWithCompletion (browser/response-adapter.ts)
  * reads as a stream that did not end cleanly: the client evicts the prefetch
- * and never respawns it. Prefetch responses carry no Cache-Control, so the
- * browser HTTP cache keeps none of it either.
+ * and never respawns it. The router puts no Cache-Control of its own on a
+ * prefetch with a live part, the only kind whose render can report an error
+ * here, so the browser HTTP cache keeps none of it unless the route sets one;
+ * a prefetch with nothing live in it carries `private, max-age`
+ * (request-stages.ts applyStoredPrefetchCacheControl); a prefetch
+ * scoped to its source page or carrying deferred units is sent
+ * `private, no-cache` (rsc-rendering.ts NOT_REUSED).
  *
  * The errors are the render's `_renderErrors`: a Flight error row, a streamed
  * handler recovered into its boundary, a loader that threw (redirect() and

package/src/rsc/progressive-enhancement.ts

@@ -13,6 +13,7 @@ import {
   setRequestContextParams,
 } from "../server/request-context.js";
 import { printServerError } from "../server/print-server-error.js";
+import { runActionBody } from "../server/cookie-store.js";
 import { createSsrHtmlStage } from "./ssr-setup.js";
 import type { MiddlewareFn } from "../router/middleware.js";
 import { executeMiddleware } from "../router/middleware.js";
@@ -187,7 +188,7 @@ async function runFormAction<TEnv>(
       // Meter the no-JS form action as the action phase, same as the JS path.
       actionResult = await observePhase(
         PHASES.action(useActionStateId ?? "useActionState"),
-        () => boundAction(),
+        () => runActionBody(() => boundAction()),
       );
     } catch (error) {
       // Handle thrown redirect (e.g., throw redirect('/path'))
@@ -216,7 +217,7 @@ async function runFormAction<TEnv>(
     try {
       const loadedAction = await ctx.loadServerAction(directActionId);
       actionResult = await observePhase(PHASES.action(directActionId), () =>
-        loadedAction.apply(null, args),
+        runActionBody(() => loadedAction.apply(null, args)),
       );
     } catch (error) {
       // Handle thrown redirect (e.g., throw redirect('/path'))

package/src/rsc/request-stages.ts

@@ -84,6 +84,9 @@ import {
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import type { CacheErrorCategory } from "../cache/cache-error.js";
 import { WIRE } from "../wire-params.js";
+import { isPrefetchKind } from "../router/segment-resolution/prefetch-deferral.js";
+import { storedPrefetchCacheControl } from "../router/prefetch-cache-ttl.js";
+import { carriesClientState } from "../cache/document-cache-policy.js";
 import {
   carryLocationStateAcrossRedirect,
   consumeDocumentLocationState,
@@ -103,6 +106,8 @@ export interface StageRouter<TEnv = unknown> {
   readonly onTimeout?: OnTimeoutCallback<TEnv>;
   /** Names the cookie location state crosses a document redirect in. */
   readonly resolvedStateCookieName: string;
+  /** The in-memory prefetch TTL in ms; also a stored prefetch's max-age. */
+  readonly prefetchCacheTTL: number;
 }
 
 /** Report an error through the router's onError. */
@@ -682,6 +687,57 @@ export interface FinalizeRequestOptions<TEnv> {
   beforeGuard?: (response: Response) => void;
 }
 
+/**
+ * A prefetch with nothing live in it (`_servedFromStorage`: a document cache
+ * HIT, or a partial whose every sent segment came from storage and ran no
+ * loader) leaves with the router's prefetch Cache-Control, so the browser
+ * HTTP cache can answer a later prefetch or the click with it.
+ * Nothing in such an answer can fail after its 200 left; any other prefetch
+ * carries none (#1170). Set here, after every middleware: the document cache
+ * reads the route's own header when it stores the response (s-maxage), the
+ * browser gets this one, in place of any other the route set.
+ *
+ * Left as it is: a partial sent NOT_REUSED (scoped to its source page, or
+ * carrying deferred units), a header that forbids storing it (`no-store`,
+ * `no-cache`, a zero `max-age`), a redirect a middleware returned after the render (`redirect`,
+ * converted to a Flight redirect above), and a response carrying one
+ * client's state (a per-client signal header, location state), which a
+ * stored copy would replay to later requests.
+ */
+function applyStoredPrefetchCacheControl(
+  response: Response,
+  reqCtx: RequestContext<any>,
+  url: URL,
+  router: StageRouter<any>,
+  redirect: boolean,
+): void {
+  if (
+    redirect ||
+    !reqCtx._servedFromStorage ||
+    !isPrefetchKind(reqCtx._requestKind) ||
+    !url.searchParams.has(WIRE.partial) ||
+    reqCtx._payloadSourceScoped ||
+    reqCtx._payloadDeferred ||
+    response.status !== 200 ||
+    !response.headers.get("content-type")?.startsWith("text/x-component") ||
+    FORBIDS_STORE.test(response.headers.get("cache-control") ?? "") ||
+    carriesClientState(response, reqCtx)
+  ) {
+    return;
+  }
+  const cacheControl = storedPrefetchCacheControl(router.prefetchCacheTTL);
+  if (cacheControl) trySetHeader(response, "cache-control", cacheControl);
+}
+
+/**
+ * A Cache-Control directive that forbids reusing the response unvalidated:
+ * `no-store`, `no-cache`, or a zero `max-age` (`s-maxage` is the shared
+ * caches' and does not match). The route asked for a fresh answer each time;
+ * the router's `max-age` would override it.
+ */
+const FORBIDS_STORE =
+  /(^|[\s,;])(no-store|no-cache|max-age=["']?0+["']?)(?=$|[\s,;=])/i;
+
 /**
  * The response the global chain returned, made ready to leave: a partial or
  * action request's redirect converted, onResponse callbacks drained, the
@@ -694,6 +750,7 @@ export function finalizeRequestResponse<TEnv>(
   const { ctx, reqCtx, request, url, env } = opts;
   const router = ctx.router;
   let response: Response;
+  let redirect = false;
   if (opts.hasMiddleware) {
     if (
       url.searchParams.has(WIRE.partial) ||
@@ -704,6 +761,7 @@ export function finalizeRequestResponse<TEnv>(
         ctx.createRedirectFlightResponse,
         { requestOrigin: url.origin, basename: router.basename },
       );
+      redirect = intercepted !== null;
       response = intercepted ?? finalizeResponse(downstream);
     } else {
       response = finalizeResponse(downstream);
@@ -715,6 +773,7 @@ export function finalizeRequestResponse<TEnv>(
   if (opts.rewrittenTo !== undefined) {
     trySetHeader(response, REWRITE_HEADER, opts.rewrittenTo);
   }
+  applyStoredPrefetchCacheControl(response, reqCtx, url, router, redirect);
   opts.beforeGuard?.(response);
 
   // Single open-redirect chokepoint: every response (PE, full-page,