@rangojs/router 0.31.0 → 0.33.0

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,
@@ -340,14 +343,25 @@ export function interceptRedirectForPartial(
 /**
  * Attach location state set during a request to a payload's metadata.
  * No-op if no location state was set. Callers must ensure payload.metadata
- * is populated (the non-null assertion holds for the partial/action payloads
- * that reach this helper).
+ * 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). `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): void {
-  const locationState = getLocationState();
-  if (locationState) {
+export function attachLocationStateIfPresent(
+  payload: RscPayload,
+  document = false,
+  locationState: LocationStateEntry[] | undefined = getLocationState(),
+): void {
+  if (locationState && locationState.length > 0) {
     payload.metadata!.locationState =
       resolveLocationStateEntries(locationState);
+    if (document) {
+      const ctx = _getRequestContext();
+      if (ctx) ctx._documentLocationState = true;
+    }
   }
 }
 

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";
@@ -25,6 +26,7 @@ import type { RscPayload, ReactFormState } from "./types.js";
 import type { MatchResult } from "../types.js";
 import {
   actionRenderRequest,
+  attachLocationStateIfPresent,
   createResponseWithMergedHeaders,
   finalizeResponse,
   buildRouteMiddlewareEntries,
@@ -186,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'))
@@ -215,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'))
@@ -448,6 +450,10 @@ function renderPeResponse<TEnv>(
     // slot instead of failing the payload root and the whole document.
     ...(reactFormState ? { formState: Promise.resolve(reactFormState) } : {}),
   };
+  // The action's location state rides the re-rendered document's bootstrap
+  // payload, as a JS action's rides its response. Not on a failure render,
+  // like the JS path.
+  if (!failure) attachLocationStateIfPresent(payload, true);
 
   const trace = getRequestContext()._activeRoutine;
 

package/src/rsc/request-stages.ts

@@ -84,6 +84,14 @@ 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,
+  markDocumentResponsePrivate,
+} from "../server/document-location-state.js";
 
 /**
  * The router members the stages read. The handler's `RangoInternal` carries
@@ -96,6 +104,10 @@ export interface StageRouter<TEnv = unknown> {
   readonly telemetry?: TelemetrySink;
   readonly timeouts?: ResolvedTimeouts;
   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. */
@@ -409,6 +421,14 @@ export async function runRequestPasses<TEnv>(
   opts: RequestPassesOptions<TEnv>,
 ): Promise<RequestPassesResult> {
   const { ctx, env, variables } = opts;
+  // Before any middleware: a document cache lookup, a PPR shell serve and the
+  // render all see the state a document redirect carried here.
+  consumeDocumentLocationState(
+    opts.reqCtx,
+    opts.request,
+    opts.url,
+    ctx.router.resolvedStateCookieName,
+  );
   let passIndex = 0;
   let hasMiddleware = false;
   const runChain = (
@@ -667,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
@@ -679,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) ||
@@ -689,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);
@@ -700,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,
@@ -707,7 +781,19 @@ export function finalizeRequestResponse<TEnv>(
   // guarding browser-followed (3xx) redirects once covers them all and any
   // future redirect exit. Soft SPA/Flight redirects are 200/204 and pass
   // through untouched (validated client-side instead).
-  const guarded = guardOutgoingRedirect(response, url.origin, router.basename);
+  // After the guard, so the cookie names the target the browser follows.
+  // A document carrying location state, or a redirect carrying it on, leaves
+  // private: set after every middleware, so none can make it shared.
+  const guarded = markDocumentResponsePrivate(
+    carryLocationStateAcrossRedirect(
+      guardOutgoingRedirect(response, url.origin, router.basename),
+      reqCtx,
+      request,
+      url,
+      router.resolvedStateCookieName,
+    ),
+    reqCtx,
+  );
 
   // Stream-idle watchdog (opt-in via timeouts.streamIdleMs): bounds
   // end-to-end idle flow on the streamed body — see rsc/stream-idle.ts

package/src/rsc/rsc-rendering.ts

@@ -102,6 +102,7 @@ import { contextGet } from "../context-var.js";
 import { rewriteShellAudience, rewriteTrail } from "../server/rewrite-trail.js";
 import { visitorShellKey } from "./shell-capture-constants.js";
 import { PREFETCH_HEADER } from "../prefetch-markers.js";
+import { isPrefetchKind } from "../router/segment-resolution/prefetch-deferral.js";
 import { WIRE } from "../wire-params.js";
 import {
   isWarmReplace,
@@ -140,6 +141,7 @@ import {
   SEGMENT_FRAGMENT_CAPABILITY_HEADER,
   SEGMENT_FRAGMENT_RECOVERY_HEADER,
 } from "../segment-fragments.js";
+import { prefetchScopeOf } from "../router/source-reads.js";
 
 type PprReplayStatus =
   | { outcome: "HIT"; freshness: "fresh" | "stale" }
@@ -361,10 +363,10 @@ type PreparedRender =
       kind: "payload";
       payload: RscPayload;
       /**
-       * The response depends on the source page: an intercept targets the
-       * route, or it carries deferred units (`prefetch: false`).
+       * `x-rsc-prefetch-scope`, when the response depends on the source
+       * page (prefetchScopeOf).
        */
-      sourceScoped: boolean;
+      prefetchScope: string | undefined;
       pprReplayStatus?: PprReplayStatus;
       /** The key a navigation-only heal capture stores under, when one is needed. */
       healKey?: string;
@@ -430,6 +432,12 @@ function* requestRenderPlan<TEnv>(
   // chain (executeRender wraps it), so no shell byte can precede a guard
   // decision — that ordering is what makes a shared shell safe. Routes
   // without the `ppr` option stay pure axis 1 at zero cost.
+  //
+  // Location state set by now (middleware, a document redirect's cookie) does
+  // not keep a request off the shell: a HIT attaches it to the live tail's
+  // payload, and a capture builds its own payload without it, so no shell
+  // ever holds a visitor's state (server/document-location-state.ts).
+  const stateBeforeRender = reqCtx._locationState?.length ?? 0;
   const shell = yield* scope("shell-serve", shellServePlan(input));
   if (shell.kind === "serve") return shell.response;
 
@@ -441,11 +449,12 @@ function* requestRenderPlan<TEnv>(
   );
   if (prepared.kind === "control") return prepared.response;
 
-  // For partial requests, include any server-set location state in the payload.
-  // SSR (full page) requests ignore location state since there's no history.state
-  // to write to on a fresh page load.
-  if (isPartial && prepared.payload.metadata) {
-    attachLocationStateIfPresent(prepared.payload);
+  // Server-set location state rides the payload: a navigation's, merged at
+  // its commit, or a document's bootstrap payload, merged when the client
+  // starts (browser/rsc-router.tsx). A document carrying it is per visitor
+  // (server/document-location-state.ts).
+  if (prepared.payload.metadata) {
+    attachLocationStateIfPresent(prepared.payload, !isPartial);
   }
 
   const response = yield* step("render", () =>
@@ -457,8 +466,14 @@ function* requestRenderPlan<TEnv>(
   // shell). Capture does not flow through the HTTP pipeline — middleware never
   // re-runs (it already ran for this request; guarding is serve-time).
   // reqCtx._dynamic is re-read here on purpose: a loader may have marked the
-  // request dynamic while rendering.
-  if (shell.kind === "miss" && !reqCtx._dynamic) {
+  // request dynamic while rendering. State a handler set in this render is
+  // not captured: a HIT replays the handler's output without running it, so
+  // the state would be lost on every HIT. The route renders in full instead.
+  if (
+    shell.kind === "miss" &&
+    !reqCtx._dynamic &&
+    (reqCtx._locationState?.length ?? 0) <= stateBeforeRender
+  ) {
     if (
       response.status === 200 &&
       (response.headers.get("content-type") ?? "").includes("text/html")
@@ -844,7 +859,7 @@ function* preparePayloadPlan<TEnv>(
       return {
         kind: "payload",
         payload: buildFullPayload(match, ctx, url, reqCtx, handleStore),
-        sourceScoped: false,
+        prefetchScope: undefined,
         pprReplayStatus,
         healKey,
       };
@@ -856,6 +871,7 @@ function* preparePayloadPlan<TEnv>(
     // showed at once, and ran held work again.
     const deferring = result.segments.some((s) => s.deferred);
     if (deferring) reqCtx._payloadDeferred = true;
+    if (result.fromStorage) reqCtx._servedFromStorage = true;
     return {
       kind: "payload",
       payload: {
@@ -885,7 +901,11 @@ function* preparePayloadPlan<TEnv>(
           stateCookieName: ctx.router.resolvedStateCookieName,
         },
       },
-      sourceScoped: result.interceptTargeted === true || deferring,
+      prefetchScope: prefetchScopeOf(
+        result.interceptTargeted === true || deferring,
+        result.sourceHeld,
+        result.diff.length === 0,
+      ),
       pprReplayStatus,
       healKey,
     };
@@ -909,7 +929,7 @@ function* preparePayloadPlan<TEnv>(
   return {
     kind: "payload",
     payload: buildFullPayload(match, ctx, url, reqCtx, handleStore),
-    sourceScoped: false,
+    prefetchScope: undefined,
   };
 }
 
@@ -1095,7 +1115,7 @@ function renderPreparedRscResponse<TEnv>(
 ): Promise<Response> {
   const { ctx, request, env, url, isPartial, nonce, reqCtx, renderSpan } =
     input;
-  const { payload, pprReplayStatus, sourceScoped } = prepared;
+  const { payload, pprReplayStatus, prefetchScope } = prepared;
   const metricsStore = reqCtx._metricsStore;
 
   const rscHeaders: Record<string, string> = {
@@ -1112,22 +1132,24 @@ function renderPreparedRscResponse<TEnv>(
       serializePprReplayStatus(pprReplayStatus);
   }
   // Tell the client's prefetch cache to scope this response to its source
-  // URL (instead of the default source-agnostic wildcard). A route an
-  // intercept targets renders the modal or the full page depending on the
-  // source, so neither response may be reused from another source: a full
-  // page prefetched where the intercept does not apply would otherwise
-  // serve a later click where it does (#1007).
-  if (sourceScoped) {
-    rscHeaders["x-rsc-prefetch-scope"] = "source";
+  // (instead of the default source-agnostic wildcard). See prefetchScopeOf.
+  if (prefetchScope !== undefined) {
+    rscHeaders["x-rsc-prefetch-scope"] = prefetchScope;
+    // A shared cache keys a partial by URL and the ids the client holds, not
+    // by its source page (document-cache.ts): stored, a scoped answer would
+    // serve its diff to another page that holds the same ids.
+    reqCtx._payloadSourceScoped = true;
   }
-  // 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; so is a stale partial render, which
-  // a shared cache keyed by URL must not store or serve. A route with no flag
-  // keeps its headers.
+  // Not reused by a shared cache or the document cache (which also refuses a
+  // payload marked `_payloadDeferred` or `_payloadSourceScoped`), whatever
+  // Cache-Control the route set: a partial scoped to its source page (above);
+  // a response that carries deferred units, which answers one page's prefetch,
+  // and a fill, the second half of one adoption (prefetch: false,
+  // docs/design/prefetch-false.md, R7); and a stale partial render, which a
+  // shared cache keyed by URL must not store or serve. Any other route keeps
+  // its headers.
   if (
+    reqCtx._payloadSourceScoped ||
     reqCtx._payloadDeferred ||
     (isPartial &&
       (reqCtx._requestKind === "fill" ||
@@ -1177,7 +1199,7 @@ function renderPreparedRscResponse<TEnv>(
         },
   );
   // A prefetch whose render reported an error is not kept (#1170).
-  if (reqCtx._requestKind !== "prefetch" || !isPartial) return rendered;
+  if (!isPrefetchKind(reqCtx._requestKind) || !isPartial) return rendered;
   return rendered.then((response) =>
     markPrefetchOnRenderError(response, reqCtx._renderErrors ?? []),
   );
@@ -1712,6 +1734,21 @@ function serveShellHit(
   // A visitor-keyed shell shows the visitor's URL: the document cache keys
   // this response by the target.
   if (entry.pathname !== undefined) reqCtx._payloadVisitorLocation = true;
+  // Location state set before the render (middleware, a document redirect's
+  // cookie) rides the tail's payload, not the shell. Marked here, on the
+  // request's own context and before the response leaves (the tail runs on a
+  // derived context, after an await), so the response goes
+  // `private, no-store` and stays out of the document cache
+  // (server/document-location-state.ts). The tail carries exactly this
+  // state: a write during the tail (a loader's, through getRequestContext())
+  // comes after these headers chose the response's caching, so it is not
+  // sent, as the skill documents (skills/hooks/state.md).
+  // Never undefined: attachLocationStateIfPresent would read the tail's
+  // context instead.
+  const tailLocationState = reqCtx._locationState ?? [];
+  if (tailLocationState.length > 0) {
+    reqCtx._documentLocationState = true;
+  }
   const metricsStore = reqCtx._metricsStore;
   // Per-stage tail timing for the `ppr:tail` Server-Timing mirror and the
   // perf console line: always in dev, in production only when this request
@@ -1739,7 +1776,7 @@ function serveShellHit(
       reportCacheError(error, "cache-write", "[ShellServe] retire");
     }
   };
-  /** The first loader pin of the entry that failed to decode (dc-t89). */
+  /** The first loader pin of the entry that failed to decode. */
   let undecodablePin: string | undefined;
 
   const renderTail = async (
@@ -1768,6 +1805,9 @@ function serveShellHit(
         | undefined;
       // Same for the location: the key's URL, or a visitor-keyed shell's.
       payload.metadata.pathname = entry.pathname ?? url.pathname;
+      // The visitor's location state, as a MISS document's payload carries
+      // it. The request was marked per visitor above.
+      attachLocationStateIfPresent(payload, false, tailLocationState);
     }
     // Full Flight render per request: hydration needs the whole payload (there
     // is no Flight-side resume — a React limitation, not ours).
@@ -2031,7 +2071,13 @@ function serveShellHit(
               "the doc record could not supply the handler layer",
             );
           }
-          controller.enqueue(new TextEncoder().encode(shellReloadScript()));
+          // A document redirect's state cookie: this response's headers
+          // cleared it, and the reload must read it again.
+          controller.enqueue(
+            new TextEncoder().encode(
+              shellReloadScript(reqCtx._carriedLocationStateCookie),
+            ),
+          );
           if (tailTiming) {
             tailTiming.outcome = "error";
             tailTiming.completeMs = Math.round(performance.now() - tailT0);
@@ -2057,7 +2103,7 @@ function serveShellHit(
       }
       // A pin that failed to decode left its loader to this request's run:
       // this response hydrated once over a prelude rendered from the
-      // capture's value (dc-t89). Retire the entry once the response is
+      // capture's value. Retire the entry once the response is
       // closed, and back the key off so a pin that keeps failing costs one
       // mismatch per window. No reload: that would cost a second page load.
       if (undecodablePin !== undefined) {