@rangojs/router 0.4.0 → 0.4.1

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

@@ -106,6 +106,7 @@ import {
   runWithRequestContext,
 } from "../../server/request-context.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
+import { createShellImplicitDocScope } from "../../cache/cache-scope.js";
 import { getRouterContext } from "../router-context.js";
 import { debugLog, debugWarn, getOrCreateRequestId } from "../logging.js";
 import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
@@ -134,6 +135,14 @@ export function withCacheStore<TEnv>(
 
     const ownStart = performance.now();
 
+    // Shell capture composition (capture side): a route-derived cache() scope
+    // keeps its normal store write below, but the capture's shell entry still
+    // needs the CANONICAL doc segment record for navigation replay. Recorded
+    // before the skip check because it must run on the explicit tier's hit
+    // path too (state.cacheHit skips the normal write, yet the served
+    // segments were collected into allSegments either way).
+    recordShellCaptureDocRecord(ctx, state, allSegments);
+
     if (
       !ctx.cacheScope?.enabled ||
       ctx.isAction ||
@@ -348,3 +357,64 @@ export function withCacheStore<TEnv>(
     }
   };
 }
+
+/**
+ * During a SHELL CAPTURE of a route with a route-derived cache() scope, write
+ * the matched non-loader segments as the canonical doc segment record through
+ * the capture marker's SnapshotOnlySegmentStore — IN ADDITION to the explicit
+ * scope's normal real-store write. The record rides only inside the shell
+ * entry (a real doc-keyed write would poison the next capture's lookup; see
+ * RecordingShellStore.recordSegmentWrite), so no real-store behavior changes.
+ * Without it, navigation replay was structurally dead for any ppr route under
+ * a cache() scope (including an app-wide one): the snapshot held only
+ * explicit-tier-keyed records a partial lookup can never resolve.
+ *
+ * Records nothing when:
+ * - not a capture render, or the route derived no scope (the implicit doc
+ *   scope's own cacheRoute below already records the doc record);
+ * - the scope is STATICALLY disabled (cache(false)) — the replay gate
+ *   pre-decides that shape as `cache-disabled` before any shell read, so a
+ *   record would be dead weight;
+ * - the prerender store supplied the match: those partials are served from
+ *   build-time segments and report `prerender-store`.
+ *
+ * A false condition() suppresses the record too — the consumer's write
+ * refusal is absolute. The prelude-already-bakes-it argument does NOT excuse
+ * recording: a NAVIGATION-ONLY capture's prelude is never served as a
+ * document, so for those entries the segment record would be the sole
+ * persisted copy of a render the consumer refused to cache — and a later
+ * request where condition() flips true could consume it through the seeded
+ * fallback. The lookup-time `cache-disabled` report stays reachable without
+ * the record: matchPartialWithPprReplay installs a REPORT-ONLY marker (no
+ * store) on the no-eligible-snapshot path, so the lookup's own refusal is
+ * still surfaced while the fallback has nothing to serve.
+ *
+ * Wrapped in requestCtx.waitUntil — during a capture that is the tracked-write
+ * override, so captureAndStoreShell's settleWrites awaits the record before
+ * draining the snapshot.
+ */
+function recordShellCaptureDocRecord<TEnv>(
+  ctx: MatchContext<TEnv>,
+  state: MatchPipelineState,
+  segments: ResolvedSegment[],
+): void {
+  const requestCtx = getRequestContext();
+  if (!requestCtx?._shellCaptureRun) return;
+  const marker = requestCtx._shellImplicitCache;
+  if (!marker?.store) return;
+  const scope = ctx.cacheScope;
+  if (!scope || scope.isShellImplicitDocScope) return;
+  if (ctx.isAction || ctx.isIntercept || ctx.request.method !== "GET") return;
+  if (state.cacheSource === "prerender") return;
+  if (!scope.allowsCache("write")) return;
+
+  const docScope = createShellImplicitDocScope(marker);
+  requestCtx.waitUntil(() =>
+    docScope.cacheRoute(
+      ctx.pathname,
+      ctx.matched.params,
+      segments,
+      ctx.isIntercept,
+    ),
+  );
+}

package/src/router/navigation-snapshot.ts

@@ -30,6 +30,50 @@ export interface ResolveNavigationDeps {
   ) => RouteMatchResult | null | Promise<RouteMatchResult | null>;
 }
 
+/**
+ * The raw navigation-context header for a partial request, or null when the
+ * request carries none. Single source of truth shared by resolveNavigation and
+ * the PPR replay gate (matchPartialWithPprReplay): a context-less partial can
+ * never produce a partial match, so the replay path must decide
+ * `no-navigation-context` BEFORE spending shell-store reads — the two
+ * predicates drifting apart would misattribute the bypass again.
+ */
+export function getNavigationContextHeader(request: Request): string | null {
+  return (
+    request.headers.get("X-RSC-Router-Client-Path") ||
+    request.headers.get("Referer")
+  );
+}
+
+/**
+ * Whether withCacheLookup's prerender short-circuit will serve this partial
+ * from the build-time prerender store: a Prerender() match (`matched.pr`)
+ * outside dev HMR — the short-circuit is disabled on X-RSC-HMR so HMR
+ * navigations pick up edited modules. Shared by withCacheLookup and the PPR
+ * replay gate (matchPartialWithPprReplay) for the same drift reason as
+ * getNavigationContextHeader: the gate's `prerender-store` bypass must decide
+ * exactly what the middleware will actually do. (Both callers additionally
+ * exclude actions on their own paths — the gate via its GET-only check.)
+ */
+export function prerenderStoreShortCircuits(
+  pr: true | undefined,
+  request: Request,
+): boolean {
+  return pr === true && !request.headers.get("X-RSC-HMR");
+}
+
+/**
+ * The intercept-source header for a partial request, or null when the request
+ * carries none. Shared by resolveNavigation and the PPR replay gate's
+ * prerender probe: intercept navigations consult the intercept-specific
+ * prerender artifact (`paramHash + "/i"`), so the probe must check the same
+ * variant the middleware will — probing the bare hash for an intercept
+ * request would report `prerender-store` for an artifact that cannot serve.
+ */
+export function getInterceptSourceHeader(request: Request): string | null {
+  return request.headers.get("X-RSC-Router-Intercept-Source");
+}
+
 export async function resolveNavigation(
   request: Request,
   url: URL,
@@ -39,12 +83,8 @@ export async function resolveNavigation(
   const clientSegmentIds =
     url.searchParams.get("_rsc_segments")?.split(",").filter(Boolean) || [];
   const stale = url.searchParams.get("_rsc_stale") === "true";
-  const previousUrl =
-    request.headers.get("X-RSC-Router-Client-Path") ||
-    request.headers.get("Referer");
-  const interceptSourceUrl = request.headers.get(
-    "X-RSC-Router-Intercept-Source",
-  );
+  const previousUrl = getNavigationContextHeader(request);
+  const interceptSourceUrl = getInterceptSourceHeader(request);
   const isHmr = !!request.headers.get("X-RSC-HMR");
 
   if (!previousUrl) {

package/src/router/router-options.ts

@@ -1,5 +1,6 @@
 import type { ComponentType, ReactNode } from "react";
 import type { SegmentCacheStore } from "../cache/types.js";
+import type { CacheSearchParams } from "../cache/search-params-filter.js";
 import type {
   ErrorBoundaryHandler,
   NotFoundBoundaryHandler,
@@ -304,15 +305,37 @@ export interface RangoOptions<TEnv = any> {
    *   }),
    * });
    * ```
+   *
+   * `searchParams` controls which query params key the cache (default:
+   * `"all"`). Cache keys only -- handlers still see the full query string.
+   * Excluding a param is a promise that rendered output does not depend on
+   * it; if it does, the first variant is cached and served to everyone.
+   *
+   * @example Ignore tracking params for cache keys
+   * ```typescript
+   * import { TRACKING_SEARCH_PARAMS } from "@rangojs/router";
+   *
+   * const router = createRouter({
+   *   cache: {
+   *     store: cacheStore,
+   *     searchParams: { exclude: TRACKING_SEARCH_PARAMS },
+   *   },
+   * });
+   * ```
    */
   cache?:
-    | { store: SegmentCacheStore; enabled?: boolean }
+    | {
+        store: SegmentCacheStore;
+        enabled?: boolean;
+        searchParams?: CacheSearchParams;
+      }
     | ((
         env: TEnv,
         ctx?: ExecutionContext,
       ) => {
         store: SegmentCacheStore;
         enabled?: boolean;
+        searchParams?: CacheSearchParams;
       });
 
   /**
@@ -535,9 +558,13 @@ export interface RangoOptions<TEnv = any> {
 
   /**
    * Default prefetch strategy for every `<Link>` that does not set its own
-   * `prefetch` prop. A per-Link `prefetch` prop always wins, in both
-   * directions (a Link can opt out of an aggressive default with
-   * `prefetch="none"`, or opt in under `defaultPrefetch: "none"`).
+   * `prefetch` prop and every eligible intercepted plain anchor. Plain anchors
+   * can opt out with `data-prefetch="false"` or `data-prefetch="none"`. Common
+   * static-resource suffixes are excluded unless `data-prefetch="true"` marks
+   * the URL as an application route. Mark side-effectful GET links such as
+   * `/logout` with an opt-out because the router cannot infer endpoint safety.
+   * A per-Link `prefetch` prop always wins in both directions (a Link can opt
+   * out with `prefetch="none"`, or opt in under `defaultPrefetch: "none"`).
    *
    * - `"viewport"` (production default): prefetch when the link enters the viewport —
    *   idle-gated and queued (see `prefetchConcurrency`), so prefetches never

package/src/rsc/handler.ts

@@ -64,6 +64,10 @@ import {
 } from "../route-map-builder.js";
 import type { HandlerContext } from "./handler-context.js";
 import type { CacheErrorCategory } from "../cache/cache-error.js";
+import {
+  compileSearchParamsFilter,
+  type SearchParamsFilter,
+} from "../cache/search-params-filter.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import { buildRouterTrieFromUrlpatterns } from "./manifest-init.js";
 import { handleProgressiveEnhancement } from "./progressive-enhancement.js";
@@ -460,6 +464,7 @@ export function createRSCHandler<
     // Priority: options.cache (handler override) > router.cache (router default)
     // Store is enabled only if: config provided, enabled, and no ?__no_cache query param
     let cacheStore: SegmentCacheStore | undefined;
+    let searchParamsFilter: SearchParamsFilter | undefined;
     const cacheOption = options.cache ?? router.cache;
     if (cacheOption && !url.searchParams.has("__no_cache")) {
       const cacheConfig =
@@ -469,6 +474,9 @@ export function createRSCHandler<
 
       if (cacheConfig.enabled !== false) {
         cacheStore = cacheConfig.store;
+        searchParamsFilter = compileSearchParamsFilter(
+          cacheConfig.searchParams,
+        );
       }
     }
 
@@ -526,6 +534,7 @@ export function createRSCHandler<
       url,
       variables,
       cacheStore,
+      searchParamsFilter,
       explicitTaggedStores,
       cacheProfiles: router.cacheProfiles,
       executionContext: executionCtx,

package/src/rsc/response-cache-serve.ts

@@ -103,7 +103,7 @@ export async function serveResponseRouteWithCache(
   // Default key: response:{type}: + host-namespaced base (sorted search, reserved
   // _rsc*/__* params excluded). Same composition as document/segment tiers so
   // the host-namespacing and search-normalization rules cannot drift.
-  let cacheKey = `response:${responseType}:${cacheKeyBase(url.host, url.pathname, url.searchParams)}`;
+  let cacheKey = `response:${responseType}:${cacheKeyBase(url.host, url.pathname, url.searchParams, undefined, reqCtx._searchParamsFilter)}`;
 
   // Priority 1: route-level key() (full override). Priority 2: store-level
   // keyGenerator (modifies the default key).

package/src/rsc/rsc-rendering.ts

@@ -61,12 +61,22 @@ import {
   type DevShellLookup,
 } from "./shell-build-manifest.js";
 import { contextGet } from "../context-var.js";
+import {
+  getNavigationContextHeader,
+  prerenderStoreShortCircuits,
+} from "../router/navigation-snapshot.js";
+import {
+  ensureFullRouteSnapshot,
+  type RouteSnapshot,
+} from "../router/route-snapshot.js";
+import { prerenderEntryExists } from "../router/match-middleware/cache-lookup.js";
 import {
   resolveSameOriginRedirect,
   safeSameOriginLanding,
 } from "../redirect-origin.js";
 import { nonce as nonceToken } from "./nonce.js";
 import { reportCacheError } from "../cache/cache-error.js";
+import type { SearchParamsFilter } from "../cache/search-params-filter.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import type {
   SegmentCacheStore,
@@ -80,6 +90,10 @@ type PprReplayBypassReason =
   | "nonce"
   | "store-unavailable"
   | "passive-read-unsupported"
+  | "no-navigation-context"
+  | "prerender-store"
+  | "intercept"
+  | "cache-disabled"
   | "read-error"
   | "no-entry"
   | "invalid-version"
@@ -88,6 +102,7 @@ type PprReplayBypassReason =
   | "transition-when"
   | "no-segment-snapshot"
   | "snapshot-miss"
+  | "explicit-cache-hit"
   | "stale-build-entry";
 
 type PprReplayStatus =
@@ -110,8 +125,11 @@ function describePprReplayStatus(status: PprReplayStatus): string {
     : `bypass:${status.reason}`;
 }
 
-function buildNavigationShellKey(url: URL): string {
-  return `${buildShellKey(url)}:navigation`;
+function buildNavigationShellKey(
+  url: URL,
+  filter?: SearchParamsFilter,
+): string {
+  return `${buildShellKey(url, filter)}:navigation`;
 }
 
 function createShellCaptureDescriptor(
@@ -147,6 +165,26 @@ function shouldHealReplayMiss(
   );
 }
 
+/**
+ * Post-match truth override for a pre-match BYPASS classification. The gate
+ * decides before matchPartial runs, but two facts only the match can settle:
+ * whether the prerender store ACTUALLY served (either artifact variant — the
+ * gate's probe reads only the non-intercept one), and whether the navigation
+ * resolved to an intercept (findInterceptForRoute runs during the match; the
+ * intercept-source header proves nothing in either direction). The resulting
+ * reason is stamped on the request context by withCacheLookup. A replay HIT is
+ * never overridden — the seeded record was demonstrably consumed, so neither
+ * fact can be true.
+ */
+function reclassifyReplayStatus(
+  reqCtx: RequestContext<any>,
+  status: PprReplayStatus,
+): PprReplayStatus {
+  if (status.outcome === "HIT") return status;
+  const reason = reqCtx._pprReplayPostMatchReason;
+  return reason ? { outcome: "BYPASS", reason } : status;
+}
+
 function resolveDevShellLookup(
   reqCtx: RequestContext<any>,
   pprConfig: ResolvedPprConfig,
@@ -173,21 +211,32 @@ function replayableShellSnapshot(
   if (!hasIntactShellPayload(entry)) return { reason: "corrupt-entry" };
   if (entry.handlerLiveHoles) return { reason: "handler-live-holes" };
   if (entry.transitionWhen) return { reason: "transition-when" };
+  // Eligibility requires the CANONICAL doc segment record (`docKey`), not just
+  // any segment record: captures under an explicit cache() scope also record
+  // that tier's reads/writes under keys a partial lookup can never resolve,
+  // and counting those declared entries "replayable" that then always missed
+  // (a timing-dependent snapshot-miss/no-segment-snapshot flip-flop). Entries
+  // captured before the field existed read as no-segment-snapshot and heal on
+  // recapture (pre-release, same treatment as the buildVersion field).
+  const docKey = entry.docKey;
   const snapshot = entry.snapshot;
-  const hasSegments = snapshot?.some((record) => {
-    if (
-      !record ||
-      typeof record !== "object" ||
-      record.family !== "segment" ||
-      typeof record.value !== "object" ||
-      record.value === null
-    ) {
-      return false;
-    }
-    const segments = (record.value as { segments?: unknown }).segments;
-    return Array.isArray(segments) && segments.length > 0;
-  });
-  return hasSegments && snapshot
+  const hasDocRecord =
+    docKey !== undefined &&
+    snapshot?.some((record) => {
+      if (
+        !record ||
+        typeof record !== "object" ||
+        record.family !== "segment" ||
+        record.key !== docKey ||
+        typeof record.value !== "object" ||
+        record.value === null
+      ) {
+        return false;
+      }
+      const segments = (record.value as { segments?: unknown }).segments;
+      return Array.isArray(segments) && segments.length > 0;
+    });
+  return hasDocRecord && snapshot
     ? { snapshot }
     : { reason: "no-segment-snapshot" };
 }
@@ -263,7 +312,7 @@ async function handleRscRenderingInner<TEnv>(
       // the provider-only check missed the latter (issue #656).
       const activeNonce = nonce ?? contextGet(reqCtx._variables, nonceToken);
       const store = reqCtx._cacheStore;
-      const key = buildShellKey(url);
+      const key = buildShellKey(url, reqCtx._searchParamsFilter);
       // Dev Server-Timing mirror (issue #651): a capture completes AFTER its
       // triggering response committed, so its outcome can only ride a LATER
       // response's header. Read-and-clear keeps one capture = one report;
@@ -417,6 +466,7 @@ async function handleRscRenderingInner<TEnv>(
             // only (production's exact candidate set). Folded away in
             // production builds (NODE_ENV is a compile-time constant).
             resolveDevShellLookup(reqCtx, pprConfig),
+            reqCtx._searchParamsFilter,
           );
           if (buildHit) {
             // Past ppr.ttl: still serve the baked entry, recapture upgrades it.
@@ -671,7 +721,7 @@ async function handleRscRenderingInner<TEnv>(
       },
       createShellCaptureDescriptor(
         ctx,
-        buildNavigationShellKey(url),
+        buildNavigationShellKey(url, reqCtx._searchParamsFilter),
         pprConfig,
         store,
         true,
@@ -710,10 +760,17 @@ async function matchPartialWithPprReplay<TEnv>(
       describePprReplayStatus(status),
     );
   };
+  const finalizeReplayStatus = (status: PprReplayStatus): PprReplayStatus => {
+    const finalStatus = reclassifyReplayStatus(reqCtx, status);
+    recordReplayStatus(finalStatus);
+    return finalStatus;
+  };
   const runMatch = async (status?: PprReplayStatus) => {
     const result = await ctx.router.matchPartial(request, { env });
-    if (status) recordReplayStatus(status);
-    return { result, status };
+    // The match may have settled a fact the pre-match gate could only guess
+    // at (prerender serve, intercept resolution) — report the truth.
+    const finalStatus = status ? finalizeReplayStatus(status) : undefined;
+    return { result, status: finalStatus };
   };
   const pprConfig = resolvePprConfig(reqCtx._classifiedRoute?.manifestEntry);
   const activeNonce = nonce ?? contextGet(reqCtx._variables, nonceToken);
@@ -738,9 +795,64 @@ async function matchPartialWithPprReplay<TEnv>(
       reason: "passive-read-unsupported",
     });
   }
+  // A partial without navigation context (curl probes, synthetic monitors)
+  // can never produce a partial match — createMatchContextForPartial returns
+  // null and the seeded record could not have been consulted, which used to
+  // read as a misleading `snapshot-miss` AFTER two wasted getShell reads.
+  // Same predicate as resolveNavigation, decided before any store I/O.
+  if (!getNavigationContextHeader(request)) {
+    return runMatch({ outcome: "BYPASS", reason: "no-navigation-context" });
+  }
+  // The prerender probe and the cache-opt-out gate below both need the
+  // classified snapshot; resolve (and persist) it once.
+  const routeSnapshot = classifiedRouteSnapshot(reqCtx);
+  // Prerender routes short-circuit in withCacheLookup and serve the partial
+  // from build-time segments — a better-than-HIT outcome. Their captures
+  // record no doc segment record (withCacheStore skips on the prerender hit),
+  // so seeding could never succeed; skip the reads and report the store that
+  // actually serves instead of blaming a "broken" capture. Bypass ONLY when
+  // the baked artifact actually exists — the trie's pr flag alone is not a
+  // serve guarantee: a Passthrough(Prerender()) route with an unbaked or
+  // ctx.passthrough()-skipped param misses the store and renders live, and
+  // replay (including its heal capture) must stay available for it. The
+  // probe goes through the same memoized store the middleware serves from.
+  // Shared predicate with the middleware (it declines on dev HMR — such
+  // partials fall through to the ordinary replay decision here too).
+  //
+  // The probe is a PRE-match fast path, not the truth: it reads only the
+  // non-intercept artifact, and whether the navigation IS an intercept (and
+  // therefore whether tryPrerenderLookup reads `paramHash` or
+  // `paramHash + "/i"`) is resolved during the match by match-api's
+  // findInterceptForRoute — an intercept-source header proves nothing in
+  // either direction. runMatch reclassifies every BYPASS from the stamped
+  // post-match facts (reclassifyReplayStatus), so a wrong guess here can
+  // skip the two getShell reads but never mis-report or mis-heal.
+  if (
+    prerenderStoreShortCircuits(routeSnapshot?.matched?.pr, request) &&
+    (await prerenderEntryExists(
+      routeSnapshot?.matched?.routeKey,
+      routeSnapshot?.params ?? {},
+      url.pathname,
+      routeSnapshot?.entries ?? [],
+    ))
+  ) {
+    return runMatch({ outcome: "BYPASS", reason: "prerender-store" });
+  }
+  // Consumer cache opt-outs are absolute: a STATICALLY disabled scope
+  // (cache(false)) bypasses before any shell read — no heal capture (its
+  // snapshot would be equally unusable). A `condition()` predicate is
+  // request-time state and must NOT be pre-decided here: evaluating it at the
+  // gate and again at the lookup lets a false-then-true flap report
+  // cache-disabled while the explicit tier serves. The lookup's own
+  // evaluation governs (withCacheLookup fires the marker's onExplicitBypass,
+  // reported as cache-disabled post-match).
+  const routeCacheScope = routeSnapshot?.cacheScope ?? null;
+  if (routeCacheScope && !routeCacheScope.enabled) {
+    return runMatch({ outcome: "BYPASS", reason: "cache-disabled" });
+  }
 
-  const key = buildShellKey(url);
-  const navigationKey = buildNavigationShellKey(url);
+  const key = buildShellKey(url, reqCtx._searchParamsFilter);
+  const navigationKey = `${key}:navigation`;
   let cached: Awaited<ReturnType<typeof store.getShell>> = null;
   try {
     cached = await store.getShell(key, { claimRevalidation: false });
@@ -794,7 +906,13 @@ async function matchPartialWithPprReplay<TEnv>(
     // Production build manifests are local module data. In dev, resolving a
     // missing build shell would foreground-fetch /__rsc_shell and block an
     // otherwise ordinary navigation on capture, so replay remains runtime-only.
-    const buildHit = await lookupBuildShell(url, ctx.version, store);
+    const buildHit = await lookupBuildShell(
+      url,
+      ctx.version,
+      store,
+      undefined,
+      reqCtx._searchParamsFilter,
+    );
     if (buildHit?.stale) {
       bypassReason ??= "stale-build-entry";
     } else if (buildHit) {
@@ -811,15 +929,78 @@ async function matchPartialWithPprReplay<TEnv>(
   }
 
   if (!snapshot) {
+    // Report-only marker for routes with an ENABLED route-derived scope: the
+    // lookup's own outcome must stay reportable even without a replayable
+    // snapshot. An always-false condition() route never produces a doc
+    // record (the consumer's write refusal is absolute — see
+    // recordShellCaptureDocRecord), so without this its lookup-time refusal
+    // would be misreported as the eligibility reason and heal captures would
+    // be scheduled for snapshots that can never become consumable. The
+    // marker carries NO store: the seeded fallback in withCacheLookup
+    // requires one, so nothing can be served through it — it only reports.
+    // Bare routes never see it (an installed marker would otherwise mint an
+    // implicit scope over the REAL doc: partition in
+    // resolveShellImplicitCacheScope).
+    if (routeCacheScope?.enabled) {
+      let explicitCacheHit = false;
+      let explicitCacheBypass = false;
+      const previousImplicitCache = reqCtx._shellImplicitCache;
+      reqCtx._shellImplicitCache = {
+        onExplicitHit: () => {
+          explicitCacheHit = true;
+        },
+        onExplicitBypass: () => {
+          explicitCacheBypass = true;
+        },
+      };
+      try {
+        const result = await ctx.router.matchPartial(request, { env });
+        const provisionalStatus: PprReplayStatus = explicitCacheBypass
+          ? { outcome: "BYPASS", reason: "cache-disabled" }
+          : explicitCacheHit
+            ? { outcome: "BYPASS", reason: "explicit-cache-hit" }
+            : { outcome: "BYPASS", reason: bypassReason ?? "no-entry" };
+        const status = finalizeReplayStatus(provisionalStatus);
+        return {
+          result,
+          status,
+          // A lookup-time opt-out makes every heal snapshot unusable
+          // (recordShellCaptureDocRecord refuses under the same predicate),
+          // and a prerender-served or intercept match never consults a heal
+          // snapshot at all. Otherwise heal the shouldHealReplayMiss set PLUS
+          // `no-segment-snapshot`: an entry captured while condition() was
+          // false legitimately lacks a snapshot, and a later request whose
+          // lookup did NOT refuse (condition true now) can heal it — the
+          // capture derives from THIS request's context, so its doc record
+          // records. Excluding it left replay dead until the document
+          // recaptured. The always-false route stays protected: its every
+          // lookup refuses, so explicitCacheBypass suppresses the heal.
+          captureNeeded:
+            !explicitCacheBypass &&
+            reqCtx._pprReplayPostMatchReason === undefined &&
+            (shouldHealReplayMiss(bypassReason) ||
+              bypassReason === "no-segment-snapshot"),
+        };
+      } finally {
+        reqCtx._shellImplicitCache = previousImplicitCache;
+      }
+    }
     const match = await runMatch({
       outcome: "BYPASS",
       reason: bypassReason ?? "no-entry",
     });
-    return { ...match, captureNeeded: shouldHealReplayMiss(bypassReason) };
+    return {
+      ...match,
+      captureNeeded:
+        reqCtx._pprReplayPostMatchReason === undefined &&
+        shouldHealReplayMiss(bypassReason),
+    };
   }
 
   const previousImplicitCache = reqCtx._shellImplicitCache;
   let segmentReplayHit = false;
+  let explicitCacheHit = false;
+  let explicitCacheBypass = false;
   reqCtx._shellImplicitCache = {
     ttl: pprConfig.ttl,
     swr: pprConfig.swr,
@@ -830,20 +1011,64 @@ async function matchPartialWithPprReplay<TEnv>(
     onHit: () => {
       segmentReplayHit = true;
     },
+    // Arms the explicit-scope composition in withCacheLookup: a route-derived
+    // cache() scope stays authoritative, the seeded doc record supplies the
+    // match only on its miss. An explicit-tier hit must NOT report a replay
+    // HIT — it served under the consumer's own semantics.
+    onExplicitHit: () => {
+      explicitCacheHit = true;
+    },
+    // Lookup-time condition() refusal (or a scope with no store): the gate
+    // deliberately does not pre-decide predicates, so the truthful
+    // cache-disabled report comes from the lookup that actually refused.
+    onExplicitBypass: () => {
+      explicitCacheBypass = true;
+    },
   };
 
   try {
     const result = await ctx.router.matchPartial(request, { env });
-    const status: PprReplayStatus = segmentReplayHit
+    const provisionalStatus: PprReplayStatus = segmentReplayHit
       ? { outcome: "HIT", freshness }
-      : { outcome: "BYPASS", reason: "snapshot-miss" };
-    recordReplayStatus(status);
+      : explicitCacheHit
+        ? { outcome: "BYPASS", reason: "explicit-cache-hit" }
+        : explicitCacheBypass
+          ? { outcome: "BYPASS", reason: "cache-disabled" }
+          : { outcome: "BYPASS", reason: "snapshot-miss" };
+    // A prerender serve or intercept resolution leaves the seeded record
+    // unconsulted (prerender short-circuits before the scope; intercepts
+    // keep snapshot.cacheScope) — the "snapshot-miss" guess would blame the
+    // capture for a lane that was never in play.
+    const status = finalizeReplayStatus(provisionalStatus);
     return { result, status };
   } finally {
     reqCtx._shellImplicitCache = previousImplicitCache;
   }
 }
 
+/**
+ * The full route snapshot for the classified route, or null when
+ * classification is unavailable (the gates then fall open to the ordinary
+ * replay decision). Persists the enriched snapshot back onto
+ * `_classifiedRoute` so the manifest-chain walk runs once per request:
+ * matchPartial's createMatchContextForPartial re-reads `_classifiedRoute` and
+ * calls ensureFullRouteSnapshot again, and the write-back lets that call hit
+ * the entries-already-built fast path and reuse this same scope chain instead
+ * of rebuilding it.
+ */
+function classifiedRouteSnapshot(
+  reqCtx: RequestContext<any>,
+): RouteSnapshot<any> | null {
+  const classified = reqCtx._classifiedRoute;
+  if (!classified?.manifestEntry) return null;
+  const full = ensureFullRouteSnapshot({
+    ...classified,
+    entries: classified.entries ?? [],
+  });
+  reqCtx._classifiedRoute = full;
+  return full;
+}
+
 /**
  * Neutralize the shell-HIT degradation redirect target. The inline
  * `location.replace` in a committed 200 body bypasses the 3xx chokepoint