@rangojs/router 0.31.0 → 0.33.0

package/src/router/intercept-resolution.ts

@@ -26,11 +26,12 @@ import {
 } from "./segment-resolution/revalidation.js";
 import { fillSends } from "./segment-resolution/prefetch-deferral.js";
 import type { ResolutionPass } from "./segment-resolution/resolution-pass.js";
-import { getRouterContext } from "./router-context.js";
+import { getRouterContext, type InterceptResult } from "./router-context.js";
 import { runInSegmentTagScope } from "../cache/cache-tag.js";
 import {
   RangoContext,
   latchPprHeaderScopeForEntries,
+  runAsSegment,
 } from "../server/context.js";
 import { _getRequestContext } from "../server/request-context.js";
 
@@ -60,18 +61,11 @@ function latchPprHeaderScopeForInterceptTarget(
  * If no when() conditions are defined, the intercept always activates.
  * A selector that throws yields the conservative default, no intercept (the
  * full page renders), and is logged; it never fails the request.
- *
- * During action revalidation, when() is NOT evaluated.
  */
 export function evaluateInterceptWhen(
   intercept: InterceptEntry,
   selectorContext: InterceptSelectorContext | null,
-  isAction: boolean,
 ): boolean {
-  if (isAction) {
-    return true;
-  }
-
   if (!intercept.when || intercept.when.length === 0) {
     return true;
   }
@@ -92,9 +86,34 @@ export function evaluateInterceptWhen(
 }
 
 /**
- * Find an intercept for the target route by walking up the entry chain.
- * Returns the first (innermost) matching intercept along with the entry that defines it.
+ * Walk the intercepts declared along `fromEntry`'s chain in selection order,
+ * an entry's own and then its orphans' (nested ones included) in render
+ * order, from `fromEntry` up, until `pick` returns a value. Tolerates partial
+ * entries (unit-test mocks omit the arrays); real registration always
+ * populates layout/intercept.
  */
+function findOnChain<T>(
+  fromEntry: EntryData | null,
+  pick: (intercept: InterceptEntry, entry: EntryData) => T | undefined,
+): T | undefined {
+  const visit = (entry: EntryData): T | undefined => {
+    for (const intercept of entry.intercept ?? []) {
+      const found = pick(intercept, entry);
+      if (found !== undefined) return found;
+    }
+    return undefined;
+  };
+  let current: EntryData | null = fromEntry;
+  let prev: EntryData | null = null;
+  while (current) {
+    const found = visit(current) ?? findInOrphans(current, visit, prev);
+    if (found !== undefined) return found;
+    prev = current;
+    current = current.parent;
+  }
+  return undefined;
+}
+
 /**
  * Collect every intercept TARGET route name reachable from an origin entry —
  * the same chain walk findInterceptForRoute() performs when this location is
@@ -110,55 +129,78 @@ export function collectInterceptTargetNames(
   fromEntry: EntryData | null,
 ): string[] {
   const names = new Set<string>();
-  // Tolerate partial entries (unit-test mocks omit the arrays); real
-  // registration always populates layout/intercept.
-  const add = (source: EntryData): undefined => {
-    for (const intercept of source.intercept ?? []) {
-      names.add(intercept.routeName);
-    }
+  findOnChain(fromEntry, (intercept) => {
+    names.add(intercept.routeName);
     return undefined;
-  };
-  let current: EntryData | null = fromEntry;
-  let prev: EntryData | null = null;
-  while (current) {
-    add(current);
-    findInOrphans(current, add, prev);
-    prev = current;
-    current = current.parent;
-  }
+  });
   return [...names];
 }
 
+/**
+ * The intercept for the target route, with the entry that declares it.
+ * `targetRouteKeys` are the names it may be declared for, in precedence
+ * order: the route's own name, then its local name inside include()
+ * (match-api.ts). A navigation, or an action with no `held`, takes the first
+ * along the chain from `fromEntry` up under the first name that has one: on a
+ * navigation, the first whose when() passes; on an action, the first, when()
+ * not evaluated.
+ *
+ * An action given `held` (the request's segment ids) re-renders the intercept
+ * on screen: one whose slot id the client holds, null when it holds none. Its
+ * candidates are collected under every name in one walk, the route's own
+ * name's first: a held id under the own name (a parallel() default of the
+ * slot's name) must not win before the local name is looked at. One held:
+ * that one, when() not evaluated, so an open intercept stays open when its
+ * when() would now reject. Several held (intercepts on one entry that fill one
+ * slot share its id, as does a parallel() slot of that name): the ones whose
+ * slot has no parallel() default on their entry, if any (a default holds its
+ * slot id whether or not an intercept is open there). One left: that one,
+ * when() not evaluated. Else the first whose when() passes against the
+ * action's intercept source, else the first.
+ */
 export function findInterceptForRoute(
-  targetRouteKey: string,
+  targetRouteKeys: string | readonly string[],
   fromEntry: EntryData | null,
   selectorContext: InterceptSelectorContext | null = null,
   isAction: boolean = false,
-): { intercept: InterceptEntry; entry: EntryData } | null {
-  const match = (source: EntryData) => {
-    for (const intercept of source.intercept) {
-      if (
-        intercept.routeName === targetRouteKey &&
-        evaluateInterceptWhen(intercept, selectorContext, isAction)
-      ) {
-        return { intercept, entry: source };
-      }
+  held?: ReadonlySet<string>,
+): InterceptResult | null {
+  const names =
+    typeof targetRouteKeys === "string" ? [targetRouteKeys] : targetRouteKeys;
+  if (!isAction || !held) {
+    for (const name of names) {
+      const found = findOnChain(fromEntry, (intercept, entry) =>
+        intercept.routeName === name &&
+        (isAction || evaluateInterceptWhen(intercept, selectorContext))
+          ? { intercept, entry }
+          : undefined,
+      );
+      if (found) return found;
     }
-    return undefined;
-  };
-  let current: EntryData | null = fromEntry;
-  let prev: EntryData | null = null;
-
-  while (current) {
-    // current first, then its orphans (nested ones included) in render order.
-    const found = match(current) ?? findInOrphans(current, match, prev);
-    if (found) return found;
-
-    prev = current;
-    current = current.parent;
+    return null;
   }
-
-  return null;
+  const byName: InterceptResult[][] = names.map(() => []);
+  findOnChain(fromEntry, (intercept, entry) => {
+    const rank = names.indexOf(intercept.routeName);
+    if (rank !== -1 && held.has(interceptSlotId(entry, intercept))) {
+      byName[rank]!.push({ intercept, entry });
+    }
+    return undefined;
+  });
+  const open = byName.flat();
+  if (open.length < 2) return open[0] ?? null;
+  // A parallel() default of the slot's name holds its slot id whichever
+  // intercept is open, so a candidate that has one proves nothing about what
+  // is on screen: among several, the ones without a default are the open ones.
+  const unshadowed = open.filter(
+    (c) => !c.entry.parallel?.[c.intercept.slotName],
+  );
+  const pool = unshadowed.length > 0 ? unshadowed : open;
+  if (pool.length === 1) return pool[0]!;
+  return (
+    pool.find((c) => evaluateInterceptWhen(c.intercept, selectorContext)) ??
+    pool[0]!
+  );
 }
 
 /**
@@ -357,7 +399,9 @@ export async function resolveInterceptEntry<TEnv>(
     handlerResult =
       typeof handler === "function"
         ? handleHandlerResult(
-            runInSegmentTagScope(slotSegmentId, handler, context),
+            runAsSegment(slotSegmentId, () =>
+              runInSegmentTagScope(slotSegmentId, handler, context),
+            ),
           )
         : handler;
   } catch (error) {

package/src/router/loader-resolution.ts

@@ -70,6 +70,8 @@ import {
   scopeReverse,
   runInsideLoaderBodyScope,
   runInsideLoaderRun,
+  runAsSegment,
+  segmentPinOf,
   isInsidePushCallbackScope,
   runInsidePushCallbackScope,
   type LoaderRunIdentity,
@@ -871,8 +873,10 @@ function createLoaderExecutor<TEnv>(
       Promise.resolve(
         runInsideLoaderBodyScope(
           () =>
-            runInsideLoaderRun(identity, () =>
-              loaderFn(loaderCtx as LoaderContext<any, TEnv>),
+            runAsSegment(owningSegmentId, () =>
+              runInsideLoaderRun(identity, () =>
+                loaderFn(loaderCtx as LoaderContext<any, TEnv>),
+              ),
             ),
           loader.$$id,
           recordedTags,
@@ -982,8 +986,7 @@ export function setupLoaderAccess<TEnv>(
     if (isHandle(item)) {
       const handle = item;
       const store = handleStoreRef;
-      const segmentId = (ctx as InternalHandlerContext<any, TEnv>)
-        ._currentSegmentId;
+      const segmentId = segmentPinOf(ctx as InternalHandlerContext<any, TEnv>);
 
       if (!segmentId) {
         throw new Error(
@@ -1057,8 +1060,7 @@ export function setupBuildUse<TEnv>(ctx: HandlerContext<any, TEnv>): void {
     if (isHandle(item)) {
       const handle = item;
       const store = handleStoreRef;
-      const segmentId = (ctx as InternalHandlerContext<any, TEnv>)
-        ._currentSegmentId;
+      const segmentId = segmentPinOf(ctx as InternalHandlerContext<any, TEnv>);
 
       if (!segmentId) {
         throw new Error(

package/src/router/match-api.ts

@@ -410,23 +410,29 @@ export async function createMatchContextForPartial<TEnv>(
     id.includes(".@"),
   );
   const skipInterceptForAction = isAction && !clientHasInterceptSegments;
+  // The names an intercept may target this route by, in precedence order:
+  // its own name, then its local name inside include().
+  const interceptNames =
+    snapshot.localRouteName !== matched.routeKey
+      ? [matched.routeKey, snapshot.localRouteName]
+      : [matched.routeKey];
+  const findIntercept = (held?: ReadonlySet<string>) =>
+    findInterceptForRoute(
+      interceptNames,
+      snapshot.manifestEntry.parent,
+      interceptSelectorContext,
+      isAction,
+      held,
+    );
+  // An action re-renders the intercept the client holds, under either name
+  // (one walk over both, findInterceptForRoute); holding none, the first
+  // declared.
   const interceptResult =
     nav.isSameRouteNavigation || skipInterceptForAction
       ? null
-      : findInterceptForRoute(
-          matched.routeKey,
-          snapshot.manifestEntry.parent,
-          interceptSelectorContext,
-          isAction,
-        ) ||
-        (snapshot.localRouteName !== matched.routeKey
-          ? findInterceptForRoute(
-              snapshot.localRouteName,
-              snapshot.manifestEntry.parent,
-              interceptSelectorContext,
-              isAction,
-            )
-          : null);
+      : isAction
+        ? findIntercept(nav.clientSegmentSet) || findIntercept()
+        : findIntercept();
 
   // The page's copy of a clientUrls() layout() loader under the route it
   // leaves holds the destination route's (client-urls/layout-loader-copies.ts).
@@ -451,24 +457,21 @@ export async function createMatchContextForPartial<TEnv>(
   }
 
   // Whether an intercept targets this route at all: the same walk as above
-  // with isAction=true, which skips when(). If one does, the response depends
-  // on the source even when none applied (a when() that rejected it, a
-  // same-route navigation), so it must not share the source-agnostic prefetch
-  // slot (#1007). The walk is over the TARGET's chain, so a route no
-  // intercept targets never depends on the source this way.
-  const targetsIntercept = (routeKey: string): boolean =>
-    findInterceptForRoute(
-      routeKey,
-      snapshot.manifestEntry.parent,
-      null,
-      true,
-    ) !== null;
+  // with isAction=true and nothing held, which skips when(). If one does, the
+  // response depends on the source even when none applied (a when() that
+  // rejected it, a same-route navigation), so it must not share the
+  // source-agnostic prefetch slot (#1007). The walk is over the TARGET's
+  // chain, so a route no intercept targets never depends on the source this
+  // way.
   const interceptTargeted =
     !!interceptResult ||
     (!skipInterceptForAction &&
-      (targetsIntercept(matched.routeKey) ||
-        (snapshot.localRouteName !== matched.routeKey &&
-          targetsIntercept(snapshot.localRouteName))));
+      findInterceptForRoute(
+        interceptNames,
+        snapshot.manifestEntry.parent,
+        null,
+        true,
+      ) !== null);
 
   const isIntercept = !!interceptResult;
   // A normal-route navigation may replay a PPR shell's canonical segment
@@ -489,6 +492,7 @@ export async function createMatchContextForPartial<TEnv>(
     snapshot.entries,
     partialDeferralMode({
       fill: kind === "fill",
+      // Speculative only: an intent prefetch defers nothing.
       prefetch: kind === "prefetch",
       method: request.method,
       isAction,

package/src/router/match-context.ts

@@ -239,6 +239,11 @@ export interface MatchPipelineState {
   // Whether cache should be revalidated (SWR)
   shouldRevalidate?: boolean;
 
+  // Whether the prerender entry that answered is past its soft staleAt: it
+  // serves while a refresh is due, so it is not what the page will hold once
+  // that lands (MatchResult.fromStorage counts it live)
+  storedStale?: boolean;
+
   // Source of cache hit ("runtime" or "prerender")
   cacheSource?: "runtime" | "prerender";
 

package/src/router/match-handlers.ts

@@ -155,10 +155,11 @@ export interface MatchHandlerDeps<TEnv = any> {
   defaultErrorBoundary: ReactNode | ErrorBoundaryHandler | undefined;
   findMatch: (pathname: string, ms?: any) => any;
   findInterceptForRoute: (
-    routeKey: string,
+    routeKeys: string | readonly string[],
     parentEntry: EntryData | null,
     selectorContext: InterceptSelectorContext | null,
     isAction: boolean,
+    held?: ReadonlySet<string>,
   ) => { intercept: InterceptEntry; entry: EntryData } | null;
   telemetry?: TelemetrySink;
   /**

package/src/router/match-middleware/cache-lookup.ts

@@ -83,6 +83,7 @@ import {
 import { ShellRecordUnavailableError } from "../../cache/shell-snapshot.js";
 import { prerenderStoreShortCircuits } from "../navigation-snapshot.js";
 import { paramsEqual } from "../params-util.js";
+import { markSourceHeld, readsOfAllParams } from "../source-reads.js";
 import { requestHeaders } from "../../server/request-headers.js";
 import { isInterceptSegment } from "../../browser/intercept-utils.js";
 import {
@@ -144,7 +145,8 @@ async function ensurePrerenderDeps(): Promise<void> {
  * - `prerender-build`: the bundled build manifest (immutable).
  * - `prerender-overlay`: the writable on-demand overlay. Its entry may be
  *   newer than the client's copy: one that a refresh (possibly inside this
- *   very action) replaced.
+ *   very action) replaced. `stale`: it is past its soft `staleAt` (serves
+ *   while a refresh is due).
  */
 type StoredSegmentSource =
   | {
@@ -154,7 +156,8 @@ type StoredSegmentSource =
       scope: CacheScope;
       restoreHandles?: (sentIds: ReadonlySet<string>) => Promise<void>;
     }
-  | { kind: "prerender-build" | "prerender-overlay"; entry: PrerenderEntry };
+  | { kind: "prerender-build"; entry: PrerenderEntry }
+  | { kind: "prerender-overlay"; entry: PrerenderEntry; stale: boolean };
 
 /**
  * Decode a prerender entry's segments and replay its handle data into the
@@ -313,12 +316,15 @@ function cachedSegmentSends<TEnv>(
  * Whether a prerender entry's segment is sent. On a partial navigation the
  * client keeps the segments it holds. The route's own segments (an
  * intercept's included) are sent again when the params changed (e.g., a
- * different guide slug). An overlay entry may be newer than the client's
- * copy: on an action or a stale request they are re-sent too, as a live
+ * different guide slug), and kept on equal params whatever the search: a
+ * prerender does not vary by search. An overlay entry may be newer than the
+ * client's copy: on an action or a stale request they are re-sent too, as a live
  * action re-render re-sends them (revalidation.ts "action:route-segment");
  * the immutable bundled manifest keeps the client's copy. A held segment
  * above the route stays held, as a live walk keeps it ("nav:non-route-skip"),
- * unless its revalidate() rules ask for it when the params changed.
+ * unless its revalidate() rules ask for it when the params changed. A route
+ * segment, or one with rules, kept on equal params marks the match
+ * source-held: the decision hangs on the source's params.
  *
  * Decided once per decoded segment, by object: an intercept variant can hold
  * a layout's parallel and the intercept's slot under one id. decodeStoredEntry
@@ -333,9 +339,20 @@ function storedEntrySends<TEnv>(
   const paramsChanged = !paramsEqual(ctx.matched.params, ctx.prevParams);
   const resendRouteSegments = replaceable && (ctx.isAction || ctx.stale);
   const entryRevalidateMap =
-    paramsChanged && router.buildEntryRevalidateMap
-      ? router.buildEntryRevalidateMap(ctx.entries)
+    ctx.clientSegmentSet.size > 0
+      ? router.buildEntryRevalidateMap?.(ctx.entries)
       : undefined;
+  // A keep that hangs on the source's params is right for the pages with
+  // the same params only: scope a prefetch of the answer to them, as a
+  // predicate that compared every param would (#1331).
+  const heldForSource = (): false => {
+    markSourceHeld(
+      ctx.handlerContext as InternalHandlerContext<any, TEnv>,
+      readsOfAllParams(ctx.prevParams),
+      { params: ctx.prevParams, routeName: undefined },
+    );
+    return false;
+  };
   const decide = (segment: ResolvedSegment): boolean | Promise<boolean> => {
     if (!ctx.clientSegmentSet.has(segment.id)) return true;
     // A fill keeps it (fillSends).
@@ -346,10 +363,16 @@ function storedEntrySends<TEnv>(
     );
     if (fill !== undefined) return fill;
     if (segment.type === "route" || segment.belongsToRoute === true) {
-      return paramsChanged || resendRouteSegments;
+      if (paramsChanged || resendRouteSegments) return true;
+      // Kept on equal params, whatever the search: a source with other
+      // params is sent it.
+      return heldForSource();
     }
     const revalidate = entryRevalidateMap?.get(segment.id)?.revalidate;
     if (!revalidate?.length) return false;
+    // Kept on equal params: from another source the rules run and may send
+    // it.
+    if (!paramsChanged) return heldForSource();
     return router.evaluateRevalidation({
       segment,
       prevParams: ctx.prevParams,
@@ -546,6 +569,11 @@ async function* serveStoredSegments<TEnv>(
   state.cacheHit = true;
   state.cacheSource = fromCache ? "runtime" : "prerender";
   if (fromCache) state.shouldRevalidate = source.shouldRevalidate;
+  // Not shouldRevalidate: that one starts the cache() scope's background
+  // revalidation.
+  if (source.kind === "prerender-overlay" && source.stale) {
+    state.storedStale = true;
+  }
   state.cachedSegments = segments;
   const cachedMatchedIds = [...liveMatchedIds, ...segments.map((s) => s.id)];
   state.cachedMatchedIds = cachedMatchedIds;
@@ -790,11 +818,8 @@ async function readPrerenderSource<TEnv>(
       // A stale "removed" marker is rechecked like a stale page: only a
       // refresh that hit notFound() (or declined) stamps one with a ttl or
       // tags. A prerender.remove() marker has neither and never gets here.
-      if (
-        overlay.config.onRevalidate &&
-        reqCtx &&
-        isStoredEntryStale(stored, Date.now())
-      ) {
+      const stale = isStoredEntryStale(stored, Date.now());
+      if (overlay.config.onRevalidate && reqCtx && stale) {
         scheduleOverlayRevalidation(
           serializePrerenderKey(key),
           overlay.config.onRevalidate,
@@ -816,7 +841,7 @@ async function readPrerenderSource<TEnv>(
         )._prerenderRemoved = true;
         return null;
       }
-      return { kind: "prerender-overlay", entry: stored.entry };
+      return { kind: "prerender-overlay", entry: stored.entry, stale };
     }
   }
 

package/src/router/match-result.ts

@@ -107,11 +107,14 @@
  *   3. Diff against previous state with diff[]
  *   4. Render slot content if slots present
  */
-import type { MatchResult, ResolvedSegment } from "../types.js";
+import type {
+  InternalHandlerContext,
+  MatchResult,
+  ResolvedSegment,
+} from "../types.js";
 import { isPlaceholder } from "../types/segments.js";
 import { interceptMatched } from "../browser/intercept-utils.js";
 import type { MatchContext, MatchPipelineState } from "./match-context.js";
-import { debugLog } from "./logging.js";
 import { appendMetric } from "./metrics.js";
 import {
   collectInterceptTargetNames,
@@ -128,83 +131,11 @@ export async function collectSegments(
   return segments;
 }
 
-/**
- * Deduplicate inherited loader segments by loaderId.
- *
- * When a route has loaders and a child layout has parallel slots, the same
- * loader is resolved twice: once for the route and once inherited into the
- * layout (tagged with `_inherited`). The inherited copy is only needed when
- * the route uses `loading()` — in that case, the loader data is inside a
- * LoaderBoundary/Suspense that parallel slots can't reach through. Without
- * loading(), useLoader() traverses parent contexts and finds the data.
- */
-function deduplicateLoaderSegments(
-  segments: ResolvedSegment[],
-  logPrefix: string,
-): { segments: ResolvedSegment[]; removedIds: Set<string> } {
-  // Single pass: original (non-inherited) loaderIds, all loaderIds grouped by
-  // namespace, and namespaces of segments that declare loading().
-  const originalLoaders = new Set<string>();
-  const loaderIdsByNamespace = new Map<string, string[]>();
-  const namespacesWithLoading = new Set<string>();
-  for (const s of segments) {
-    if (s.type === "loader" && s.loaderId) {
-      if (!s._inherited) originalLoaders.add(s.loaderId);
-      const ids = loaderIdsByNamespace.get(s.namespace);
-      if (ids) ids.push(s.loaderId);
-      else loaderIdsByNamespace.set(s.namespace, [s.loaderId]);
-    } else if (
-      s.type !== "loader" &&
-      s.loading !== undefined &&
-      s.loading !== false
-    ) {
-      namespacesWithLoading.add(s.namespace);
-    }
-  }
-
-  const loadersWithLoading = new Set<string>();
-  for (const ns of namespacesWithLoading) {
-    for (const id of loaderIdsByNamespace.get(ns) ?? []) {
-      loadersWithLoading.add(id);
-    }
-  }
-
-  const result: ResolvedSegment[] = [];
-  const removedIds = new Set<string>();
-
-  for (const s of segments) {
-    if (
-      s.type === "loader" &&
-      s.loaderId &&
-      s._inherited &&
-      originalLoaders.has(s.loaderId) &&
-      !loadersWithLoading.has(s.loaderId)
-    ) {
-      removedIds.add(s.id);
-      continue;
-    }
-    result.push(s);
-  }
-
-  if (removedIds.size > 0) {
-    debugLog(
-      logPrefix,
-      `deduped ${removedIds.size} inherited loader segment(s)`,
-    );
-  }
-
-  return { segments: result, removedIds };
-}
-
 export function buildMatchResult<TEnv>(
   allSegments: ResolvedSegment[],
   ctx: MatchContext<TEnv>,
   state: MatchPipelineState,
 ): MatchResult {
-  const logPrefix = ctx.isFullMatch
-    ? "[Router.match]"
-    : "[Router.matchPartial]";
-
   let allIds: string[];
   let segmentsToRender: ResolvedSegment[];
   let resolvedIds: string[];
@@ -267,19 +198,11 @@ export function buildMatchResult<TEnv>(
     }
   }
 
-  const { segments: dedupedSegments, removedIds } = deduplicateLoaderSegments(
-    segmentsToRender,
-    logPrefix,
-  );
-
-  const matchedIds =
-    removedIds.size > 0 ? allIds.filter((id) => !removedIds.has(id)) : allIds;
-
-  // One pass over dedupedSegments: strip the internal _handlerRan marker and
+  // One pass over segmentsToRender: strip the internal _handlerRan marker and
   // collect the diff ids (id is unchanged by the strip) together.
   const cleanedSegments: ResolvedSegment[] = [];
   const diff: string[] = [];
-  for (const s of dedupedSegments) {
+  for (const s of segmentsToRender) {
     if (s._handlerRan === undefined) {
       cleanedSegments.push(s);
     } else {
@@ -293,10 +216,13 @@ export function buildMatchResult<TEnv>(
   // origin — the browser-local clientUrls matcher declines its optimistic
   // presentation for these (see collectInterceptTargetNames).
   const interceptTargets = collectInterceptTargetNames(ctx.manifestEntry);
+  const sourceHeld = (
+    ctx.handlerContext as InternalHandlerContext<any, TEnv> | undefined
+  )?._sourceHeld;
 
   return {
     segments: cleanedSegments,
-    matched: matchedIds,
+    matched: allIds,
     diff,
     resolvedIds,
     params: ctx.matched.params,
@@ -304,11 +230,45 @@ export function buildMatchResult<TEnv>(
     slots: Object.keys(state.slots).length > 0 ? state.slots : undefined,
     ...(interceptTargets.length > 0 ? { interceptTargets } : {}),
     ...(ctx.interceptTargeted ? { interceptTargeted: true } : {}),
+    ...(sourceHeld ? { sourceHeld } : {}),
+    ...(!ctx.isFullMatch && sendsOnlyStored(segmentsToRender, state)
+      ? { fromStorage: true as const }
+      : {}),
     routeMiddleware:
       ctx.routeMiddleware.length > 0 ? ctx.routeMiddleware : undefined,
   };
 }
 
+/**
+ * Whether a partial answer sends only what the cache lookup decoded from
+ * storage (MatchResult.fromStorage). By object, not by id: a
+ * segment the live walk resolved under a stored one's id (a live layout above
+ * a cache() boundary, an intercept resolved live) is not the stored copy.
+ * Any loader segment ran in this request, so it is live. Defaults to live:
+ * counted stored by mistake, a segment brings back the cached failures #1170
+ * removed. A stale cache() record (state.shouldRevalidate, refreshed in the
+ * background), a stale on-demand Prerender overlay entry (state.storedStale,
+ * which only the overlay can be: the build manifest never goes stale) and an
+ * answer that sends nothing count as live too: the browser would keep the
+ * first two past their refresh, and the third is a source page's answer.
+ */
+function sendsOnlyStored(
+  sent: readonly ResolvedSegment[],
+  state: MatchPipelineState,
+): boolean {
+  if (
+    !state.cacheHit ||
+    !state.cachedSegments ||
+    state.shouldRevalidate ||
+    state.storedStale ||
+    sent.length === 0
+  ) {
+    return false;
+  }
+  const stored = new Set(state.cachedSegments);
+  return sent.every((s) => s.type !== "loader" && stored.has(s));
+}
+
 export async function collectMatchResult<TEnv>(
   pipeline: AsyncGenerator<ResolvedSegment>,
   ctx: MatchContext<TEnv>,

package/src/router/middleware-types.ts

@@ -78,6 +78,12 @@ export interface MiddlewareContext<
 
   setTheme?: (theme: Theme) => void;
 
+  /**
+   * Attach location state entries to this response (see the handler
+   * context's `setLocationState`). Entries accumulate across definitions;
+   * for one definition the last write wins. Set it here rather than in a
+   * handler on a `ppr` route: a shell HIT runs no handler.
+   */
   setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void;
 
   /** Global route names only; see {@link GlobalReverseFunction}. */