@rangojs/router 0.4.0 → 0.4.2

package/src/rsc/rsc-rendering.ts

@@ -61,18 +61,32 @@ 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,
   ShellCacheEntry,
   ShellSnapshotRecord,
 } from "../cache/types.js";
+import {
+  SEGMENT_FRAGMENT_CAPABILITY_HEADER,
+  SEGMENT_FRAGMENT_RECOVERY_HEADER,
+} from "../segment-fragments.js";
 
 type PprReplayBypassReason =
   | "method"
@@ -80,6 +94,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 +106,7 @@ type PprReplayBypassReason =
   | "transition-when"
   | "no-segment-snapshot"
   | "snapshot-miss"
+  | "explicit-cache-hit"
   | "stale-build-entry";
 
 type PprReplayStatus =
@@ -110,8 +129,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 +169,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 +215,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" };
 }
@@ -236,6 +289,7 @@ async function handleRscRenderingInner<TEnv>(
   let hasInterceptSlots = false;
   let pprReplayStatus: PprReplayStatus | undefined;
   let partialCaptureNeeded = false;
+  let partialCaptureKey: string | undefined;
 
   // --- Axis 2: integrated PPR shell serve (docs/design/ppr-shell-resume.md) ---
   //
@@ -263,7 +317,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 +471,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.
@@ -444,6 +499,7 @@ async function handleRscRenderingInner<TEnv>(
     pprReplayStatus = replay.status;
     partialCaptureNeeded =
       "captureNeeded" in replay && replay.captureNeeded === true;
+    partialCaptureKey = "captureKey" in replay ? replay.captureKey : undefined;
 
     if (!result) {
       // Fall back to full render
@@ -562,7 +618,7 @@ async function handleRscRenderingInner<TEnv>(
 
   const rscHeaders: Record<string, string> = {
     "content-type": "text/x-component;charset=utf-8",
-    vary: "accept, X-Rango-State, X-RSC-Router-Client-Path",
+    vary: `accept, X-Rango-State, X-RSC-Router-Client-Path, ${SEGMENT_FRAGMENT_CAPABILITY_HEADER}, ${SEGMENT_FRAGMENT_RECOVERY_HEADER}`,
     // Router identity, so the client can verify pre-decode (before importing
     // chunks) that this content payload belongs to its app and refuse a
     // foreign one (cache/proxy/bug). Control-only reload/redirect responses
@@ -671,7 +727,8 @@ async function handleRscRenderingInner<TEnv>(
       },
       createShellCaptureDescriptor(
         ctx,
-        buildNavigationShellKey(url),
+        partialCaptureKey ??
+          buildNavigationShellKey(url, reqCtx._searchParamsFilter),
         pprConfig,
         store,
         true,
@@ -710,10 +767,39 @@ async function matchPartialWithPprReplay<TEnv>(
       describePprReplayStatus(status),
     );
   };
+  const finalizeReplayStatus = (status: PprReplayStatus): PprReplayStatus => {
+    const finalStatus = reclassifyReplayStatus(reqCtx, status);
+    recordReplayStatus(finalStatus);
+    return finalStatus;
+  };
+  let armFragments = false;
+  /**
+   * Every matchPartial in this function runs through this helper so the
+   * fragment flag (#700 passthrough, armed below the navigation-context gate)
+   * can never outlive a match or miss a lane — a thrown-Response redirect
+   * exit included. Mutate-restore on the SHARED reqCtx, never a derived
+   * context: the pipeline writes ambient state during the match that must
+   * land on reqCtx (_pprReplayPostMatchReason, location state,
+   * _treeHasStreaming read by the render-barrier closure). Assign-back
+   * restore leaves an own `undefined` after the first arm, matching the
+   * _shellImplicitCache idiom.
+   */
+  const matchPartialForReplay = async () => {
+    if (!armFragments) return ctx.router.matchPartial(request, { env });
+    const prevFragmentPayload = reqCtx._shellFragmentPayload;
+    reqCtx._shellFragmentPayload = true;
+    try {
+      return await ctx.router.matchPartial(request, { env });
+    } finally {
+      reqCtx._shellFragmentPayload = prevFragmentPayload;
+    }
+  };
   const runMatch = async (status?: PprReplayStatus) => {
-    const result = await ctx.router.matchPartial(request, { env });
-    if (status) recordReplayStatus(status);
-    return { result, status };
+    const result = await matchPartialForReplay();
+    // 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 +824,72 @@ 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" });
+  }
+  // Fragment passthrough (#700), extended to partial replay. Navigation
+  // context proves the request can be matched; the separate capability header
+  // proves its payload consumer can expand envelopes. Older clients and the
+  // one-shot corruption recovery request still replay the same segment record,
+  // but through the server decode path.
+  armFragments =
+    request.headers.get(SEGMENT_FRAGMENT_RECOVERY_HEADER) !== "1" &&
+    request.headers.get(SEGMENT_FRAGMENT_CAPABILITY_HEADER) === "1";
+  // 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 });
@@ -751,11 +900,13 @@ async function matchPartialWithPprReplay<TEnv>(
 
   let bypassReason: PprReplayBypassReason | undefined;
   let snapshot: ShellSnapshotRecord[] | undefined;
+  let snapshotStoreKey: string | undefined;
   let freshness: "fresh" | "stale" = "fresh";
   if (cached) {
     const decision = replayableShellSnapshot(cached.entry, ctx.version);
     if ("snapshot" in decision) {
       snapshot = decision.snapshot;
+      snapshotStoreKey = key;
       freshness = cached.shouldRevalidate ? "stale" : "fresh";
     } else {
       bypassReason = decision.reason;
@@ -783,6 +934,7 @@ async function matchPartialWithPprReplay<TEnv>(
       );
       if ("snapshot" in decision) {
         snapshot = decision.snapshot;
+        snapshotStoreKey = navigationKey;
         freshness = navigationCached.shouldRevalidate ? "stale" : "fresh";
       } else {
         bypassReason = decision.reason;
@@ -794,7 +946,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 +969,79 @@ 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 matchPartialForReplay();
+        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 segmentReplayCorrupt = false;
+  let explicitCacheHit = false;
+  let explicitCacheBypass = false;
   reqCtx._shellImplicitCache = {
     ttl: pprConfig.ttl,
     swr: pprConfig.swr,
@@ -830,20 +1052,78 @@ async function matchPartialWithPprReplay<TEnv>(
     onHit: () => {
       segmentReplayHit = true;
     },
+    onCorrupt: () => {
+      segmentReplayCorrupt = 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 result = await matchPartialForReplay();
+    const provisionalStatus: PprReplayStatus = segmentReplayHit
       ? { outcome: "HIT", freshness }
-      : { outcome: "BYPASS", reason: "snapshot-miss" };
-    recordReplayStatus(status);
-    return { result, 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,
+      captureNeeded:
+        segmentReplayCorrupt && reqCtx._pprReplayPostMatchReason === undefined,
+      // A corrupt document snapshot must be overwritten at the document key;
+      // writing only the secondary navigation key would leave the preferred
+      // document entry shadowing the repair forever. The capture remains marked
+      // navigationOnly, so a document request ignores it and recaptures a
+      // document-safe shell under the same key.
+      captureKey: segmentReplayCorrupt ? snapshotStoreKey : undefined,
+    };
   } 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

package/src/rsc/shell-build-manifest.ts

@@ -27,6 +27,7 @@
 
 import type { SegmentCacheStore, ShellCacheEntry } from "../cache/types.js";
 import { sortedSearchString } from "../cache/cache-key-utils.js";
+import type { SearchParamsFilter } from "../cache/search-params-filter.js";
 import {
   DEV_SHELL_PROBE_TIMEOUT_MS,
   hasIntactShellPayload,
@@ -252,12 +253,18 @@ async function fetchDevShellEntry(
  * version validity, payload integrity, and tag-invalidation markers. Returns
  * null on any gate failure — the caller degrades to the ordinary MISS path
  * (axis 1 + runtime capture), never a broken serve.
+ *
+ * "Search-less" is evaluated AFTER the request's `cache.searchParams` filter:
+ * a URL whose only params are excluded ones (`?fbclid=…` under a tracking
+ * exclusion) matches the baked shell — ad-click traffic is exactly the
+ * traffic the shell was prerendered for.
  */
 export async function lookupBuildShell(
   url: URL,
   buildVersion: string,
   store: SegmentCacheStore,
   dev?: DevShellLookup,
+  filter?: SearchParamsFilter,
 ): Promise<BuildShellHit | null> {
   try {
     // Source-presence first: with no manifest and no dev context this is the
@@ -265,7 +272,7 @@ export async function lookupBuildShell(
     // the searchParams sort/allocation below.
     const hasManifest = globalThis.__loadShellManifestModule !== undefined;
     if (!hasManifest && !dev) return null;
-    if (sortedSearchString(url.searchParams) !== "") return null;
+    if (sortedSearchString(url.searchParams, filter) !== "") return null;
     let record: BuildShellEntry | undefined;
     if (hasManifest) {
       const mod = await loadManifest();

package/src/rsc/shell-capture.ts

@@ -945,8 +945,9 @@ export function scheduleShellCapture(
  *   I/O failure is reported separately and does NOT make the attempt retryable —
  *   the capture itself worked).
  * - `redirect`: the matched route redirects, so there is no shell to capture.
- * - `no-shell`: the prelude came back trivial (no <body>) OR captureShellHTML
- *   rejected with our own abort. This is the only RETRYABLE outcome.
+ * - `no-shell`: captureShellHTML returned null because the prelude was unusable
+ *   or its private capture abort landed before the shell completed. This is the
+ *   only RETRYABLE outcome.
  */
 type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused";
 
@@ -995,9 +996,9 @@ type CaptureAttemptStats = Pick<
  * when we froze the shell; the attempt itself warmed the module graph, so a second
  * attempt a short beat later usually completes the shell in the SAME background
  * task. That kills the old multi-request warmup where the caller had to re-issue
- * several HTTP requests before a capture stuck. We retry ONLY on `no-shell` (and a
- * defensively-caught abort); a genuine render error is NOT retried — it propagates
- * to scheduleShellCapture's reportCacheError. See docs/design/ppr-shell-resume.md.
+ * several HTTP requests before a capture stuck. We retry ONLY on `no-shell`; a
+ * genuine render error is NOT retried — it propagates to scheduleShellCapture's
+ * reportCacheError. See docs/design/ppr-shell-resume.md.
  *
  * `retryDelayMs` is a parameter (defaulting to the module const) so unit tests can
  * drive the retry without a real 400ms wall-clock wait.
@@ -1329,6 +1330,10 @@ export function deriveShellCaptureContext(
   derivedCtx._explicitTaggedStores = new Set();
   derivedCtx._transitionWhen = [];
   derivedCtx._shellCaptureRun = true;
+  // Own-property reset: an inherited flag would make serializeSegments store
+  // a double-encoded fragment. No current arming site reaches a capture
+  // render (kept as defense-in-depth for a future one).
+  derivedCtx._shellFragmentPayload = false;
   derivedCtx._metricsStore = undefined;
   // Spans, like perf metrics above, are a FOREGROUND surface: the capture
   // re-render must not emit a second rango.render/loader/ssr set after the
@@ -1395,9 +1400,10 @@ export function deriveShellCaptureContext(
  * capture worked; only the store I/O failed). `ssrModule.captureShellHTML` MUST be
  * present (eligibility is checked before scheduling).
  *
- * A `no-shell` result (trivial prelude, or a defensively-caught abort) is the only
- * retryable outcome; a genuine (non-abort) captureShellHTML error propagates so it
- * reaches reportCacheError and is NOT retried.
+ * A `no-shell` result from captureShellHTML is the only retryable outcome. Every
+ * captureShellHTML error propagates to reportCacheError and is NOT retried. The
+ * capture handler converts only its own private abort sentinel to null before this
+ * layer sees it.
  */
 async function captureAndStoreShell(
   ssrModule: SSRModule,
@@ -1504,19 +1510,13 @@ async function captureAndStoreShell(
         }),
       );
     } catch (error) {
-      // Guard-tripped rejection arrives here (not at the drain) — refuse
-      // BEFORE the AbortError-vs-rethrow decision below.
+      // Guard-tripped rejection arrives here (not at the drain), so refuse it
+      // before propagating other capture errors.
       const refused = refuseOnGuardTrip();
       if (refused) return refused;
-      // captureShellHTML normally converts its OWN deliberate abort to a null
-      // return (index.tsx). This catch is defensive: if an AbortError still escapes
-      // (a runtime where the abort surfaces as a stream rejection outside its
-      // guard), treat it as the same retryable "no usable shell" degradation rather
-      // than a failure — do NOT report it as an error. A genuine (non-abort) render
-      // error is a real failure: rethrow so it reaches reportCacheError (no retry).
-      if ((error as { name?: string } | null)?.name === "AbortError") {
-        return "no-shell";
-      }
+      // captureShellHTML converts its OWN deliberate abort to null by sentinel
+      // identity. An escaped AbortError can therefore be a component's real
+      // cancellation and must not be hidden or retried by name.
       throw error;
     }
 
@@ -1707,6 +1707,11 @@ async function captureAndStoreShell(
           // ShellCacheEntry.initialTheme.
           initialTheme: reqCtx.theme,
           snapshot,
+          // The canonical doc segment record's key, published by the doc
+          // scope's cacheRoute during this capture's match (undefined when no
+          // doc record was recorded — the entry then never claims navigation
+          // replayability). Only meaningful alongside a snapshot.
+          docKey: snapshot ? reqCtx._shellImplicitCache?.docKey : undefined,
           navigationOnly: capture.navigationOnly,
           // Handler-layer liveness folded at the barrier: nested thenables in
           // handler-scoped pushes, handler pushes still pending (liveness

package/src/rsc/shell-serve.ts

@@ -19,6 +19,7 @@
 import React from "react";
 import { isPprEntry, type EntryData } from "../server/context.js";
 import { sortedSearchString } from "../cache/cache-key-utils.js";
+import type { SearchParamsFilter } from "../cache/search-params-filter.js";
 import type { ShellCacheEntry, SegmentCacheStore } from "../cache/types.js";
 import { SHELL_CAPTURE_MAX_WAIT_MS } from "./shell-capture-constants.js";
 
@@ -117,9 +118,14 @@ export function resolvePprConfig(
  * The key includes the request HOST: in a multi-tenant host-router deployment
  * (one worker, one shared KV/runtime-cache store) a host-less key would serve
  * tenant A's captured shell to tenant B's users.
+ *
+ * `filter` is the request's compiled `cache.searchParams` config
+ * (ctx._searchParamsFilter): excluded params collapse onto one shell slot.
+ * Callers on the serve/capture path MUST pass it -- key drift between capture
+ * and lookup makes every shell request a permanent miss.
  */
-export function buildShellKey(url: URL): string {
-  const sorted = sortedSearchString(url.searchParams);
+export function buildShellKey(url: URL, filter?: SearchParamsFilter): string {
+  const sorted = sortedSearchString(url.searchParams, filter);
   const searchSuffix = sorted ? `?${sorted}` : "";
   return `${url.host}${url.pathname}${searchSuffix}:shell`;
 }