@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

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

@@ -92,17 +92,20 @@
  *   - Action context (if POST)
  */
 import type { ResolvedSegment } from "../../types.js";
+import type { EntryData } from "../../server/context.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
-import { getRouterContext } from "../router-context.js";
-import { resolveSink, safeEmit } from "../telemetry.js";
+import { getRouterContext, type RouterContext } from "../router-context.js";
+import { observeEvent } from "../instrument.js";
 import { pushRevalidationTraceEntry, isTraceActive } from "../logging.js";
 import { treeHasStreaming } from "./segment-resolution.js";
 import type { PrerenderStore, PrerenderEntry } from "../../prerender/store.js";
-import type { HandleStore } from "../../server/handle-store.js";
 import {
-  getRequestContext,
   _getRequestContext,
+  type RequestContext,
 } from "../../server/request-context.js";
+import { createShellImplicitDocScope } from "../../cache/cache-scope.js";
+import { prerenderStoreShortCircuits } from "../navigation-snapshot.js";
+import { paramsEqual } from "../params-util.js";
 
 // Lazily initialized prerender store singleton and dynamically imported deps.
 // Dynamic imports prevent pulling in @vitejs/plugin-rsc/rsc virtual module at
@@ -111,45 +114,32 @@ let prerenderStoreInstance: PrerenderStore | null | undefined;
 let _deserializeSegments:
   | typeof import("../../cache/segment-codec.js").deserializeSegments
   | undefined;
+let _fragmentSegments:
+  | typeof import("../../cache/segment-codec.js").fragmentSegments
+  | undefined;
 let _restoreHandles:
   | typeof import("../../cache/handle-snapshot.js").restoreHandles
   | undefined;
+let _decodeHandles:
+  | typeof import("../../cache/handle-snapshot.js").decodeHandles
+  | undefined;
 let _hashParams:
   | typeof import("../../prerender/param-hash.js").hashParams
   | undefined;
-let _lazyGetRequestContext:
-  | typeof import("../../server/request-context.js").getRequestContext
-  | undefined;
-
-function paramsEqual(
-  a: Record<string, string>,
-  b: Record<string, string>,
-): boolean {
-  if (a === b) return true;
-
-  const keysA = Object.keys(a);
-  if (keysA.length !== Object.keys(b).length) return false;
-
-  for (const key of keysA) {
-    if (a[key] !== b[key]) return false;
-  }
-
-  return true;
-}
 
 async function ensurePrerenderDeps() {
   if (!_deserializeSegments) {
-    const [codec, snapshot, paramHash, reqCtx, store] = await Promise.all([
+    const [codec, snapshot, paramHash, store] = await Promise.all([
       import("../../cache/segment-codec.js"),
       import("../../cache/handle-snapshot.js"),
       import("../../prerender/param-hash.js"),
-      import("../../server/request-context.js"),
       import("../../prerender/store.js"),
     ]);
     _deserializeSegments = codec.deserializeSegments;
+    _fragmentSegments = codec.fragmentSegments;
     _restoreHandles = snapshot.restoreHandles;
+    _decodeHandles = snapshot.decodeHandles;
     _hashParams = paramHash.hashParams;
-    _lazyGetRequestContext = reqCtx.getRequestContext;
     if (prerenderStoreInstance === undefined) {
       prerenderStoreInstance = store.createPrerenderStore();
     }
@@ -161,69 +151,21 @@ async function ensurePrerenderDeps() {
  * Deserializes segments, replays handle data, yields segments with partial
  * navigation nullification, and resolves fresh loaders.
  */
-async function* yieldFromStore<TEnv>(
-  entry: PrerenderEntry,
+// Resolve loaders fresh on a cache hit (loaders are NEVER cached) and yield
+// the loader segments, updating state.matchedIds and pushing the loader-resolve
+// + cache-hit metrics. Shared verbatim by the prerender-store path
+// (yieldFromStore) and the runtime cache-hit path (withCacheLookup). The router
+// resolve fns are passed in (captured early by the callers) rather than re-read
+// from getRouterContext() here, because that is ALS-backed and the callers run
+// awaits before reaching this point (workerd can disrupt ALS mid-pipeline).
+async function* resolveFreshLoadersAndYield<TEnv>(
   ctx: MatchContext<TEnv>,
   state: MatchPipelineState,
   pipelineStart: number,
-  handleStoreRef?: HandleStore,
+  ms: MatchContext<TEnv>["metricsStore"],
+  resolveLoadersOnly: RouterContext<TEnv>["resolveLoadersOnly"],
+  resolveLoadersOnlyWithRevalidation: RouterContext<TEnv>["resolveLoadersOnlyWithRevalidation"],
 ): AsyncGenerator<ResolvedSegment> {
-  const { resolveLoadersOnlyWithRevalidation, resolveLoadersOnly } =
-    getRouterContext<TEnv>();
-
-  if (
-    !_deserializeSegments ||
-    !_restoreHandles ||
-    !_hashParams ||
-    !_lazyGetRequestContext
-  ) {
-    throw new Error("yieldFromStore called before ensurePrerenderDeps");
-  }
-
-  const segments = await _deserializeSegments(entry.segments);
-
-  // Replay handle data (same as runtime cache hit path).
-  // Prefer the eagerly-captured handleStoreRef to avoid ALS disruption in workerd.
-  const handleStore = handleStoreRef ?? _lazyGetRequestContext()?._handleStore;
-  if (handleStore) {
-    _restoreHandles(entry.handles, handleStore);
-  }
-
-  state.cacheHit = true;
-  state.cacheSource = "prerender";
-  state.cachedSegments = segments;
-  state.cachedMatchedIds = segments.map((s) => s.id);
-
-  // Set streaming flag (once) and resolve render barrier.
-  const reqCtx = handleStoreRef ? undefined : _lazyGetRequestContext?.();
-  const barrierReqCtx = reqCtx ?? _getRequestContext();
-  if (barrierReqCtx) {
-    if (barrierReqCtx._treeHasStreaming === undefined) {
-      barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
-    }
-    barrierReqCtx._resolveRenderBarrier(segments);
-  }
-
-  // For partial navigation, nullify components the client already has
-  // so parent layouts stay live (client keeps its existing versions).
-  // When params changed (e.g., different guide slug), the segments have
-  // different content, so we must NOT nullify.
-  const paramsChanged =
-    !ctx.isFullMatch && !paramsEqual(ctx.matched.params, ctx.prevParams);
-  for (const segment of segments) {
-    if (
-      !ctx.isFullMatch &&
-      !paramsChanged &&
-      ctx.clientSegmentSet.has(segment.id)
-    ) {
-      segment.component = null;
-      segment.loading = undefined;
-    }
-    yield segment;
-  }
-
-  // Resolve loaders fresh (loaders are never pre-rendered/cached)
-  const ms = ctx.metricsStore;
   const loaderStart = performance.now();
 
   if (ctx.isFullMatch) {
@@ -251,6 +193,8 @@ async function* yieldFromStore<TEnv>(
           ctx.url,
           ctx.routeKey,
           ctx.actionContext,
+          // Loaders are never cached in the segment cache, so segment staleness
+          // must not propagate; browser-sent staleness (ctx.stale) still must.
           ctx.stale || undefined,
         ),
       );
@@ -282,6 +226,179 @@ async function* yieldFromStore<TEnv>(
   }
 }
 
+async function* yieldFromStore<TEnv>(
+  entry: PrerenderEntry,
+  ctx: MatchContext<TEnv>,
+  state: MatchPipelineState,
+  pipelineStart: number,
+  reqCtx: RequestContext<TEnv> | undefined,
+  resolveLoadersOnly: RouterContext<TEnv>["resolveLoadersOnly"],
+  resolveLoadersOnlyWithRevalidation: RouterContext<TEnv>["resolveLoadersOnlyWithRevalidation"],
+): AsyncGenerator<ResolvedSegment> {
+  if (
+    !_deserializeSegments ||
+    !_fragmentSegments ||
+    !_restoreHandles ||
+    !_decodeHandles ||
+    !_hashParams
+  ) {
+    throw new Error("yieldFromStore called before ensurePrerenderDeps");
+  }
+
+  // Shell-HIT tail (issue #700): a Prerender+ppr route's tail serves from THIS
+  // store (the prerender lookup runs before the cache scope), so the fragment
+  // splice must apply here too — otherwise producer B entries re-serialize the
+  // whole tree per request while producer A entries do not.
+  const segments = reqCtx?._shellFragmentPayload
+    ? await _fragmentSegments(entry.segments)
+    : await _deserializeSegments(entry.segments);
+
+  // Replay handle data (same as runtime cache hit path). entry.handles is a
+  // Flight-encoded string ("" when none) — decode before restore so
+  // Promise/ReactNode handle values are revived, not the corrupted JSON form.
+  const handleStore = reqCtx?._handleStore;
+  if (handleStore && entry.handles) {
+    const handlesRecord = await _decodeHandles(entry.handles);
+    if (handlesRecord) {
+      _restoreHandles(handlesRecord, handleStore);
+    }
+  }
+
+  state.cacheHit = true;
+  state.cacheSource = "prerender";
+  state.cachedSegments = segments;
+  state.cachedMatchedIds = segments.map((s) => s.id);
+
+  // Set streaming flag (once) and resolve render barrier.
+  // Post-match serve-source truth for the PPR replay reporter. This overwrites
+  // `intercept` because the prerender store is the response source.
+  if (reqCtx) {
+    reqCtx._pprReplayPostMatchReason = "prerender-store";
+    if (reqCtx._treeHasStreaming === undefined) {
+      reqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+    }
+    reqCtx._resolveRenderBarrier(segments);
+  }
+
+  // For partial navigation, nullify components the client already has
+  // so parent layouts stay live (client keeps its existing versions).
+  // When params changed (e.g., different guide slug), the segments have
+  // different content, so we must NOT nullify.
+  const paramsChanged =
+    !ctx.isFullMatch && !paramsEqual(ctx.matched.params, ctx.prevParams);
+  for (const segment of segments) {
+    if (
+      !ctx.isFullMatch &&
+      !paramsChanged &&
+      ctx.clientSegmentSet.has(segment.id)
+    ) {
+      segment.component = null;
+      segment.loading = undefined;
+    }
+    yield segment;
+  }
+
+  // Resolve loaders fresh (loaders are never pre-rendered/cached).
+  yield* resolveFreshLoadersAndYield(
+    ctx,
+    state,
+    pipelineStart,
+    ctx.metricsStore,
+    resolveLoadersOnly,
+    resolveLoadersOnlyWithRevalidation,
+  );
+}
+
+/**
+ * Whether the prerender store holds a baked entry for this route + params.
+ * Consulted by the PPR replay gate (matchPartialWithPprReplay), which must
+ * only report `prerender-store` when the short-circuit below will actually
+ * serve: a Passthrough(Prerender()) route with an unbaked/passthrough param
+ * misses the store and renders live, and replay — including its heal
+ * capture — must stay available for it (withCacheStore records the doc
+ * record on that path; state.cacheSource is not "prerender"). The store
+ * memoizes per routeKey/paramHash, so this probe and tryPrerenderLookup's
+ * subsequent get() share one underlying load.
+ */
+export async function prerenderEntryExists(
+  routeKey: string | undefined,
+  params: Record<string, string>,
+  pathname: string,
+  entries: EntryData[],
+): Promise<boolean> {
+  if (!routeKey) return false;
+  // Deliberately NOT ensurePrerenderDeps(): the probe needs only the store
+  // and the param hasher — pulling segment-codec here would drag the
+  // @vitejs/plugin-rsc virtual module onto a path that never deserializes.
+  if (!_hashParams) {
+    _hashParams = (await import("../../prerender/param-hash.js")).hashParams;
+  }
+  if (prerenderStoreInstance === undefined) {
+    prerenderStoreInstance = (
+      await import("../../prerender/store.js")
+    ).createPrerenderStore();
+  }
+  if (!prerenderStoreInstance) return false;
+  // Non-intercept variant only: whether the navigation IS an intercept (and
+  // therefore whether tryPrerenderLookup reads `paramHash + "/i"`) resolves
+  // during the match, so this pre-match fast path can only guess the normal
+  // artifact. A wrong guess is reclassified post-match from the match
+  // pipeline's `_pprReplayPostMatchReason` stamp.
+  const entry = await prerenderStoreInstance.get(
+    routeKey,
+    _hashParams!(params),
+    {
+      pathname,
+      isPassthroughRoute: entries.some(
+        (entry) => entry.type === "route" && entry.isPassthrough === true,
+      ),
+    },
+  );
+  return entry != null;
+}
+
+/**
+ * Look up a prerendered (build-time cached) entry for the current route and, on
+ * a hit, yield its segments. Returns true when an entry was served (the caller
+ * should stop the pipeline) and false on a miss. Intercept navigations consult
+ * only the intercept-specific entry (`paramHash + "/i"`); a miss there falls
+ * through to the normal pipeline so intercept-resolution can run. Callers must
+ * guard on `prerenderStoreInstance` after `ensurePrerenderDeps()`.
+ */
+async function* tryPrerenderLookup<TEnv>(
+  ctx: MatchContext<TEnv>,
+  state: MatchPipelineState,
+  pipelineStart: number,
+  reqCtx: RequestContext<TEnv> | undefined,
+  resolveLoadersOnly: RouterContext<TEnv>["resolveLoadersOnly"],
+  resolveLoadersOnlyWithRevalidation: RouterContext<TEnv>["resolveLoadersOnlyWithRevalidation"],
+): AsyncGenerator<ResolvedSegment, boolean> {
+  const paramHash = _hashParams!(ctx.matched.params);
+  const isPassthroughPrerenderRoute = ctx.entries.some(
+    (entry) => entry.type === "route" && entry.isPassthrough === true,
+  );
+  const lookupHash = ctx.isIntercept ? paramHash + "/i" : paramHash;
+  const entry = await prerenderStoreInstance!.get(
+    ctx.matched.routeKey,
+    lookupHash,
+    {
+      pathname: ctx.pathname,
+      isPassthroughRoute: isPassthroughPrerenderRoute,
+    },
+  );
+  if (!entry) return false;
+  yield* yieldFromStore(
+    entry,
+    ctx,
+    state,
+    pipelineStart,
+    reqCtx,
+    resolveLoadersOnly,
+    resolveLoadersOnlyWithRevalidation,
+  );
+  return true;
+}
+
 /**
  * Async generator middleware type
  */
@@ -317,7 +434,14 @@ export function withCacheLookup<TEnv>(
     // can disrupt AsyncLocalStorage, causing getRequestContext() to return
     // undefined afterward. Capturing the reference early ensures handle replay
     // and handler handle-push work regardless of ALS state.
-    const handleStoreRef = _getRequestContext()?._handleStore;
+    const pipelineReqCtx = _getRequestContext<TEnv>();
+    // Only the match can determine interception; the source header proves
+    // nothing in either direction. Clear a stale reason on normal matches.
+    if (pipelineReqCtx) {
+      pipelineReqCtx._pprReplayPostMatchReason = ctx.isIntercept
+        ? "intercept"
+        : undefined;
+    }
 
     const {
       evaluateRevalidation,
@@ -326,73 +450,33 @@ export function withCacheLookup<TEnv>(
       resolveLoadersOnly,
     } = getRouterContext<TEnv>();
 
-    // Prerender lookup: check build-time cached data before runtime cache.
-    // Prerender data is available regardless of runtime cache configuration.
-    // Skip for HMR requests — the dev prerender endpoint reads from a stale
-    // RouterRegistry snapshot; rendering fresh ensures edits are visible.
-    const isHmr = !!ctx.request.headers.get("X-RSC-HMR");
-    if (!ctx.isAction && !isHmr && ctx.matched.pr) {
-      await ensurePrerenderDeps();
-      if (prerenderStoreInstance) {
-        const paramHash = _hashParams!(ctx.matched.params);
-        const isPassthroughPrerenderRoute = ctx.entries.some(
-          (entry) => entry.type === "route" && entry.isPassthrough === true,
-        );
-
-        if (ctx.isIntercept) {
-          // Intercept navigation: try intercept-specific prerender entry
-          const entry = await prerenderStoreInstance.get(
-            ctx.matched.routeKey,
-            paramHash + "/i",
-            {
-              pathname: ctx.pathname,
-              isPassthroughRoute: isPassthroughPrerenderRoute,
-            },
-          );
-          if (entry) {
-            yield* yieldFromStore(
-              entry,
-              ctx,
-              state,
-              pipelineStart,
-              handleStoreRef,
-            );
-            return;
-          }
-          // No intercept prerender -- fall through to normal pipeline
-          // (skip non-intercept prerender to let intercept-resolution run)
-        } else {
-          // Normal navigation: existing behavior
-          const entry = await prerenderStoreInstance.get(
-            ctx.matched.routeKey,
-            paramHash,
-            {
-              pathname: ctx.pathname,
-              isPassthroughRoute: isPassthroughPrerenderRoute,
-            },
+    if (prerenderStoreShortCircuits(ctx.matched.pr, ctx.request)) {
+      // Actions normally re-render fresh and skip the prerender store. But a pure
+      // Prerender route's handler is evicted at build, so there is no fresh
+      // handler to run on an action re-render -- without the fallback the
+      // re-render falls through to the evicted handler and throws "No prerender
+      // data found". Serve the prerendered entry instead (the action ran already;
+      // its result is applied client-side via useActionState). Passthrough routes
+      // keep a liveHandler, so they still re-render fresh on actions.
+      const isPassthroughPrerenderRoute = ctx.entries.some(
+        (entry) => entry.type === "route" && entry.isPassthrough === true,
+      );
+      if (!ctx.isAction || !isPassthroughPrerenderRoute) {
+        await ensurePrerenderDeps();
+        if (prerenderStoreInstance) {
+          const served = yield* tryPrerenderLookup(
+            ctx,
+            state,
+            pipelineStart,
+            pipelineReqCtx,
+            resolveLoadersOnly,
+            resolveLoadersOnlyWithRevalidation,
           );
-          if (entry) {
-            yield* yieldFromStore(
-              entry,
-              ctx,
-              state,
-              pipelineStart,
-              handleStoreRef,
-            );
-            return;
-          }
+          if (served) return;
         }
       }
     }
 
-    // Dev-mode static handler interception for non-Node.js runtimes.
-    // __PRERENDER_DEV_URL is set by the Vite plugin when the RSC environment
-    // lacks a Node.js module runner (e.g. workerd, Deno workers). In those
-    // runtimes, handlers that depend on Node APIs like node:fs can't run
-    // in-process. We redirect them to the /__rsc_prerender endpoint which
-    // resolves segments in a Node.js temp server, same as prerender routes.
-    // In Node.js dev mode this variable is undefined -- handlers run
-    // in-process where Node APIs work, so no interception is needed.
     if (!ctx.isAction && !ctx.matched.pr && globalThis.__PRERENDER_DEV_URL) {
       const hasStatic = ctx.entries.some(
         (e) =>
@@ -404,58 +488,20 @@ export function withCacheLookup<TEnv>(
       if (hasStatic) {
         await ensurePrerenderDeps();
         if (prerenderStoreInstance) {
-          const paramHash = _hashParams!(ctx.matched.params);
-          const isPassthroughPrerenderRoute = ctx.entries.some(
-            (entry) => entry.type === "route" && entry.isPassthrough === true,
+          const served = yield* tryPrerenderLookup(
+            ctx,
+            state,
+            pipelineStart,
+            pipelineReqCtx,
+            resolveLoadersOnly,
+            resolveLoadersOnlyWithRevalidation,
           );
-
-          if (ctx.isIntercept) {
-            const entry = await prerenderStoreInstance.get(
-              ctx.matched.routeKey,
-              paramHash + "/i",
-              {
-                pathname: ctx.pathname,
-                isPassthroughRoute: isPassthroughPrerenderRoute,
-              },
-            );
-            if (entry) {
-              yield* yieldFromStore(
-                entry,
-                ctx,
-                state,
-                pipelineStart,
-                handleStoreRef,
-              );
-              return;
-            }
-            // No intercept prerender -- fall through to normal pipeline
-          } else {
-            const entry = await prerenderStoreInstance.get(
-              ctx.matched.routeKey,
-              paramHash,
-              {
-                pathname: ctx.pathname,
-                isPassthroughRoute: isPassthroughPrerenderRoute,
-              },
-            );
-            if (entry) {
-              yield* yieldFromStore(
-                entry,
-                ctx,
-                state,
-                pipelineStart,
-                handleStoreRef,
-              );
-              return;
-            }
-          }
+          if (served) return;
         }
       }
     }
 
-    // Skip cache during actions
     if (ctx.isAction || !ctx.cacheScope?.enabled) {
-      // Cache miss - pass through to segment resolution
       yield* source;
       if (ms) {
         ms.metrics.push({
@@ -467,15 +513,60 @@ export function withCacheLookup<TEnv>(
       return;
     }
 
-    // Lookup cache
-    const cacheResult = await ctx.cacheScope.lookupRoute(
+    const explicitLookup = await ctx.cacheScope.lookupRouteDetailed(
       ctx.pathname,
       ctx.matched.params,
       ctx.isIntercept,
     );
+    let cacheResult =
+      explicitLookup.status === "hit" ? explicitLookup.result : null;
+
+    // PPR navigation replay composed with a route-derived cache() scope. The
+    // explicit tier stays authoritative: its hit serves under its own
+    // key/ttl/swr semantics and reports `explicit-cache-hit` — never a false
+    // replay HIT. ONLY a true `miss` lets the seeded doc record supply the
+    // match (the marker's onHit observer then reports the true HIT). The
+    // other outcomes render fresh: `bypass` (cache(false), a false
+    // condition() — absolute opt-outs even when the pre-read gate saw a
+    // different condition() result — or no store) and `error` (a throwing
+    // key()/keyGenerator/store.get keeps lookupRoute's render-uncached
+    // contract; the canonical record must not serve across a broken key
+    // partition). The outcome comes from the lookup itself, not a re-run of
+    // the condition, so a flapping predicate cannot re-admit the fallback.
+    // Gated on the marker's `onExplicitHit`, set ONLY on the
+    // navigation-replay serve path: a CAPTURE render must never fall back
+    // here — its marker store reads through to the real store, and a
+    // doc-keyed hit would replay the previous generation's segments instead
+    // of re-running handlers (breaking SWR recapture freshness). Intercepts
+    // stay source-dependent on their normal cache path (match-api never arms
+    // replay for them).
+    const replayMarker = pipelineReqCtx?._shellImplicitCache;
+    if (
+      replayMarker?.onExplicitHit &&
+      !ctx.isIntercept &&
+      !ctx.cacheScope.isShellImplicitDocScope
+    ) {
+      if (explicitLookup.status === "hit") {
+        replayMarker.onExplicitHit();
+      } else if (explicitLookup.status === "miss" && replayMarker.store) {
+        // The store gate keeps report-only markers (installed on the
+        // no-eligible-snapshot path purely for truthful status) inert: a
+        // store-less marker minting a doc scope here would resolve the APP
+        // store and read the REAL doc: partition — a cross-partition serve.
+        cacheResult = await createShellImplicitDocScope(
+          replayMarker,
+        ).lookupRoute(ctx.pathname, ctx.matched.params, ctx.isIntercept);
+      } else if (explicitLookup.status === "bypass") {
+        // condition() refused at lookup time (the gate only pre-decides the
+        // static cache(false) case) — report cache-disabled truthfully.
+        replayMarker.onExplicitBypass?.();
+      }
+      // "error" stays unreported: the render is fresh and the seeded record
+      // was not consulted, which is exactly what snapshot-miss describes; the
+      // store already routed the failure through reportCacheError.
+    }
 
     if (!cacheResult) {
-      // Cache miss - pass through to segment resolution
       yield* source;
       if (ms) {
         ms.metrics.push({
@@ -487,16 +578,13 @@ export function withCacheLookup<TEnv>(
       return;
     }
 
-    // Cache HIT
     state.cacheHit = true;
     state.cacheSource = "runtime";
     state.shouldRevalidate = cacheResult.shouldRevalidate;
     state.cachedSegments = cacheResult.segments;
     state.cachedMatchedIds = cacheResult.segments.map((s) => s.id);
+    const pprTransitionDecisions = pipelineReqCtx?._pprTransitionDecisions;
 
-    // Apply revalidation to cached segments.
-    // For full matches or empty client segment sets, this map is unnecessary:
-    // we never run segment-level revalidation and can stream segments directly.
     const canCheckSegmentRevalidation =
       !ctx.isFullMatch &&
       ctx.clientSegmentSet.size > 0 &&
@@ -506,7 +594,6 @@ export function withCacheLookup<TEnv>(
       : undefined;
 
     for (const segment of cacheResult.segments) {
-      // Skip segments client doesn't have - they need their component
       if (!ctx.clientSegmentSet.has(segment.id)) {
         if (isTraceActive()) {
           pushRevalidationTraceEntry({
@@ -523,19 +610,13 @@ export function withCacheLookup<TEnv>(
         continue;
       }
 
-      // Skip intercept segments - they're handled separately
       if (segment.namespace?.startsWith("intercept:")) {
         yield segment;
         continue;
       }
 
-      // Look up revalidation rules for this segment
       const entryInfo = entryRevalidateMap?.get(segment.id);
 
-      // Even without explicit revalidation rules, route segments and their
-      // children must re-render when params or search params change — the
-      // handler reads ctx.params/ctx.searchParams so different values produce
-      // different content. Matches evaluateRevalidation's default logic.
       const searchChanged = ctx.prevUrl.search !== ctx.url.search;
       const routeParamsChanged = !paramsEqual(
         ctx.matched.params,
@@ -549,7 +630,6 @@ export function withCacheLookup<TEnv>(
 
       if (!entryInfo || entryInfo.revalidate.length === 0) {
         if (shouldDefaultRevalidate) {
-          // Params or search params changed — must re-render even without custom rules
           if (isTraceActive()) {
             pushRevalidationTraceEntry({
               segmentId: segment.id,
@@ -566,7 +646,6 @@ export function withCacheLookup<TEnv>(
           yield segment;
           continue;
         }
-        // No revalidation rules, use default behavior (skip if client has)
         if (isTraceActive()) {
           pushRevalidationTraceEntry({
             segmentId: segment.id,
@@ -578,13 +657,17 @@ export function withCacheLookup<TEnv>(
             reason: "cached-no-rules",
           });
         }
-        segment.component = null;
-        segment.loading = undefined;
+        // A PPR transition decision must reach the client even when this cached
+        // segment otherwise needs no update. Keep its replayed component so the
+        // partial result retains the segment for gateTransitions().
+        if (!pprTransitionDecisions?.has(segment.id)) {
+          segment.component = null;
+          segment.loading = undefined;
+        }
         yield segment;
         continue;
       }
 
-      // Evaluate revalidation rules
       const shouldRevalidate = await evaluateRevalidation({
         segment,
         prevParams: ctx.prevParams,
@@ -603,22 +686,16 @@ export function withCacheLookup<TEnv>(
         traceSource: "cache-hit",
       });
 
-      const routerCtx = getRouterContext<TEnv>();
-      if (routerCtx.telemetry) {
-        const tSink = resolveSink(routerCtx.telemetry);
-        safeEmit(tSink, {
-          type: "revalidation.decision",
-          timestamp: performance.now(),
-          requestId: routerCtx.requestId,
-          segmentId: segment.id,
-          pathname: ctx.pathname,
-          routeKey: ctx.routeKey,
-          shouldRevalidate,
-        });
-      }
+      observeEvent({
+        type: "revalidation.decision",
+        timestamp: performance.now(),
+        segmentId: segment.id,
+        pathname: ctx.pathname,
+        routeKey: ctx.routeKey,
+        shouldRevalidate,
+      });
 
-      if (!shouldRevalidate) {
-        // Client has it, no revalidation needed
+      if (!shouldRevalidate && !pprTransitionDecisions?.has(segment.id)) {
         segment.component = null;
         segment.loading = undefined;
       }
@@ -626,8 +703,7 @@ export function withCacheLookup<TEnv>(
       yield segment;
     }
 
-    // Set streaming flag (once) and resolve render barrier.
-    const barrierReqCtx = _getRequestContext();
+    const barrierReqCtx = pipelineReqCtx;
     if (barrierReqCtx) {
       if (barrierReqCtx._treeHasStreaming === undefined) {
         barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
@@ -635,77 +711,15 @@ export function withCacheLookup<TEnv>(
       barrierReqCtx._resolveRenderBarrier(cacheResult.segments);
     }
 
-    // Resolve loaders fresh (loaders are NOT cached by default)
-    // This ensures fresh data even on cache hit
-    const Store = ctx.Store;
-    const loaderStart = performance.now();
-
-    if (ctx.isFullMatch) {
-      // Full match (document request) - simple loader resolution without revalidation
-      if (resolveLoadersOnly) {
-        const loaderSegments = await Store.run(() =>
-          resolveLoadersOnly(ctx.entries, ctx.handlerContext),
-        );
-
-        // Update state - full match doesn't track matchedIds separately
-        state.matchedIds = state.cachedMatchedIds!;
-
-        // Yield fresh loader segments
-        for (const segment of loaderSegments) {
-          yield segment;
-        }
-      } else {
-        state.matchedIds = state.cachedMatchedIds!;
-      }
-    } else {
-      // Partial match (navigation) - loader resolution with revalidation
-      if (resolveLoadersOnlyWithRevalidation) {
-        const loaderResult = await Store.run(() =>
-          resolveLoadersOnlyWithRevalidation(
-            ctx.entries,
-            ctx.handlerContext,
-            ctx.clientSegmentSet,
-            ctx.prevParams,
-            ctx.request,
-            ctx.prevUrl,
-            ctx.url,
-            ctx.routeKey,
-            ctx.actionContext,
-            // Loaders are never cached in the segment cache, so segment
-            // staleness (cacheResult.shouldRevalidate) must not propagate.
-            // But browser-sent staleness (ctx.stale) — indicating an action
-            // happened in this or another tab — must still reach loaders.
-            ctx.stale || undefined,
-          ),
-        );
-
-        // Update state with fresh loader matchedIds
-        state.matchedIds = [
-          ...state.cachedMatchedIds!,
-          ...loaderResult.matchedIds,
-        ];
-
-        // Yield fresh loader segments
-        for (const segment of loaderResult.segments) {
-          yield segment;
-        }
-      } else {
-        state.matchedIds = state.cachedMatchedIds!;
-      }
-    }
-    if (ms) {
-      const loaderEnd = performance.now();
-      ms.metrics.push({
-        label: "pipeline:loader-resolve",
-        duration: loaderEnd - loaderStart,
-        startTime: loaderStart - ms.requestStart,
-        depth: 1,
-      });
-      ms.metrics.push({
-        label: "pipeline:cache-hit",
-        duration: loaderEnd - pipelineStart,
-        startTime: pipelineStart - ms.requestStart,
-      });
-    }
+    // Resolve loaders fresh (loaders are never cached). Shared with the
+    // prerender-store path via resolveFreshLoadersAndYield.
+    yield* resolveFreshLoadersAndYield(
+      ctx,
+      state,
+      pipelineStart,
+      ms,
+      resolveLoadersOnly,
+      resolveLoadersOnlyWithRevalidation,
+    );
   };
 }