@rangojs/router 0.2.0 → 0.4.1

package/src/rsc/shell-capture.ts

@@ -20,7 +20,10 @@ import React from "react";
 import { bufferToBase64 } from "../cache/cf/cf-base64.js";
 import { reportCacheError } from "../cache/cache-error.js";
 import { runBackground } from "../cache/background-task.js";
-import { enqueueSerializedCapture } from "./capture-queue.js";
+import {
+  CaptureQueueFullError,
+  enqueueSerializedCapture,
+} from "./capture-queue.js";
 import { SHELL_CAPTURE_MAX_WAIT_MS } from "./shell-capture-constants.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import { observePhase, PHASES } from "../router/instrument.js";
@@ -57,6 +60,7 @@ import type { SSRModule } from "./types.js";
 import { buildFullPayload } from "./full-payload.js";
 import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
 import { renderRscFlightStage } from "./render-pipeline.js";
+import { stripInternalParams } from "../router/handler-context.js";
 
 /**
  * Task-quantized quiesce: the number of consecutive macrotask hops with zero new
@@ -344,39 +348,6 @@ function warnCaptureRefusedOnce(key: string, reason: string): void {
   );
 }
 
-/** Keys already warned about untagged bake-lane data baked into the shell. */
-const warnedUntaggedShellBakes = new Set<string>();
-
-/**
- * Warn once per shell key that a bake-lane loader baked material into the shell
- * but the capture recorded ZERO tags (no render-collected _requestTags, no
- * static ppr.tags). Such data is frozen in the shared shell until TTL and is
- * un-evictable by tag: a server action refreshes the CLIENT only (rotates Rango
- * state, busts the browser HTTP cache) and never touches the server shell store,
- * and updateTag()/revalidateTag() cannot drop data that was baked WITHOUT a tag.
- *
- * Coarse per-shell-key signal, not per-loader attribution — the tag set is
- * unioned globally at the write barrier, not tracked per loader, so we cannot
- * name the offending loader without adding attribution plumbing (deliberately
- * not done). Dev-only + once-per-key so it never spams production or fires on
- * every capture.
- */
-function warnUntaggedShellBakeOnce(key: string): void {
-  if (warnedUntaggedShellBakes.has(key)) return;
-  warnedUntaggedShellBakes.add(key);
-  console.warn(
-    `[rango] Shell capture for "${key}" baked bake-lane loader data into the ` +
-      "shell with NO cache tag. That data is frozen in the shared shell until " +
-      "TTL and cannot be tag-invalidated: a server action refresh touches the " +
-      "client only (not the server shell store), and updateTag() cannot evict " +
-      "data that was baked without a tag.\n" +
-      'Fix: tag the data (cacheTag() / "use cache" / cache({ tags })) so ' +
-      "updateTag() drops the shell, or move the volatile read under a loading() " +
-      "hole so it stays on the live lane and is never baked. See the /ppr skill " +
-      "(node_modules/@rangojs/router/skills/ppr/SKILL.md).",
-  );
-}
-
 /**
  * Default cap (serialized UTF-8 bytes) on the capture data snapshot riding
  * inside a shell entry, when the route's `ppr` option does not set
@@ -444,6 +415,7 @@ export interface ShellCaptureDebugEvent {
    *   the key (stampede guard) and scheduled nothing
    * - skip-backoff: the key is inside its refused-capture backoff window and
    *   the capture was not attempted
+   * - skip-capacity: the isolate capture queue is full; a later request may retry
    * - backoff: the key entered (or escalated) backoff after a terminal
    *   no-shell — carries the new backoff state
    */
@@ -455,6 +427,7 @@ export interface ShellCaptureDebugEvent {
     | "error"
     | "skip-in-flight"
     | "skip-backoff"
+    | "skip-capacity"
     | "backoff";
   /** Attempt number (1 = first, 2 = in-place retry). Absent on skips. */
   attempt?: number;
@@ -476,6 +449,8 @@ export interface ShellCaptureDebugEvent {
   snapshotBytes?: number;
   /** True when the snapshot exceeded maxSnapshotBytes and was dropped. */
   snapshotSkipped?: boolean;
+  /** A bake-lane loader settled into a shell that uses TTL/SWR-only invalidation. */
+  untaggedBake?: true;
   /** Outcome reported by a store that supports shell-write acknowledgements. */
   storeWrite?: "stored" | "invalidated";
   /** Consecutive failure count in the key's backoff entry, when one exists. */
@@ -518,6 +493,7 @@ export function describeShellCaptureEvent(
       `snapshot=${event.snapshotBytes}b${event.snapshotSkipped ? " (over cap, skipped)" : ""}`,
     );
   }
+  if (event.untaggedBake) parts.push("untagged-bake");
   if (event.storeWrite !== undefined) {
     parts.push(`store-write=${event.storeWrite}`);
   }
@@ -835,6 +811,8 @@ export interface ShellCaptureDescriptor {
    * {@link ShellCaptureDebugEvent} per attempt/skip.
    */
   debugSink?: (event: ShellCaptureDebugEvent) => void;
+  /** Store the snapshot for navigation replay, never the captured HTML prelude. */
+  navigationOnly?: true;
 }
 
 /**
@@ -844,9 +822,9 @@ export interface ShellCaptureDescriptor {
  * error is routed through reportCacheError — capture is best-effort; a failure just
  * means the next request recaptures.
  *
- * Eligibility (nonce/allReady/partial/status/strategy) is decided by the caller
- * (rsc-rendering.ts maybeScheduleShellCapture); this function only owns the
- * stampede guard and the background dispatch.
+ * Eligibility (nonce/partial/status/strategy) is decided by the caller. An SSR
+ * module loader may be passed for cold partial requests; it runs only after the
+ * capture enters the guarded background queue, never on response latency.
  */
 export function scheduleShellCapture(
   ctx: HandlerContext<any>,
@@ -854,7 +832,9 @@ export function scheduleShellCapture(
   env: any,
   url: URL,
   reqCtx: RequestContext<any>,
-  ssrModule: SSRModule,
+  ssrModule:
+    | SSRModule
+    | ((request: Request, url: URL) => Promise<SSRModule | null>),
   descriptor: ShellCaptureDescriptor,
 ): void {
   const key = descriptor.key;
@@ -875,13 +855,30 @@ export function scheduleShellCapture(
   inFlightCaptures.add(key);
   const captureTask = async () => {
     try {
+      const setupUrl = descriptor.navigationOnly
+        ? stripInternalParams(url)
+        : url;
+      const setupRequest = descriptor.navigationOnly
+        ? createNavigationCaptureRequest(request, setupUrl)
+        : request;
+      const resolvedSsrModule =
+        typeof ssrModule === "function"
+          ? await ssrModule(setupRequest, setupUrl)
+          : ssrModule;
+      if (
+        !resolvedSsrModule ||
+        !resolvedSsrModule.resumeShellHTML ||
+        !resolvedSsrModule.captureShellHTML
+      ) {
+        return;
+      }
       const outcome = await runShellCapture(
         ctx,
         request,
         env,
         url,
         reqCtx,
-        ssrModule,
+        resolvedSsrModule,
         descriptor,
       );
       // Update the negative cache off the terminal outcome. A stored shell clears
@@ -917,7 +914,21 @@ export function scheduleShellCapture(
   // capture makes the sibling freeze a trivial prelude and store nothing
   // (rotating eternal-MISS victims on GH runners). The stampede guard above
   // stays per-key (dedupe while queued); the queue is cross-key.
-  const serializedTask = () => enqueueSerializedCapture(captureTask);
+  const serializedTask = async () => {
+    try {
+      await enqueueSerializedCapture(captureTask);
+    } catch (error) {
+      if (error instanceof CaptureQueueFullError) {
+        inFlightCaptures.delete(key);
+        publishCaptureDebugEvent(descriptor, {
+          key,
+          outcome: "skip-capacity",
+        });
+        return;
+      }
+      throw error;
+    }
+  };
   // The capture's own task must NOT enter reqCtx._pendingBackgroundTasks: the
   // capture drains that list before rendering (the write-barrier ordering edge),
   // and awaiting its own still-running promise would burn the whole barrier
@@ -939,6 +950,22 @@ export function scheduleShellCapture(
  */
 type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused";
 
+function createNavigationCaptureRequest(request: Request, url: URL): Request {
+  const headers = new Headers(request.headers);
+  headers.set("accept", "text/html");
+  for (const name of [
+    "rsc-action",
+    "x-rango-prefetch",
+    "x-rango-state",
+    "x-rsc-hmr",
+    "x-rsc-router-client-path",
+    "x-rsc-router-intercept-source",
+  ]) {
+    headers.delete(name);
+  }
+  return new Request(url, { method: request.method, headers });
+}
+
 /**
  * Per-attempt observability fields, filled along the capture path (barrier in
  * attemptCapture, the rest in captureAndStoreShell) and folded into the
@@ -953,6 +980,7 @@ type CaptureAttemptStats = Pick<
   | "preludeBytes"
   | "snapshotBytes"
   | "snapshotSkipped"
+  | "untaggedBake"
   | "storeWrite"
 >;
 
@@ -984,6 +1012,10 @@ async function runShellCapture(
   descriptor: ShellCaptureDescriptor,
   retryDelayMs: number = SHELL_CAPTURE_RETRY_DELAY_MS,
 ): Promise<CaptureAttemptOutcome> {
+  const captureUrl = descriptor.navigationOnly ? stripInternalParams(url) : url;
+  const captureRequest = descriptor.navigationOnly
+    ? createNavigationCaptureRequest(request, captureUrl)
+    : request;
   const log = descriptor.debug
     ? (message: string) => console.log(message)
     : () => {};
@@ -1000,9 +1032,9 @@ async function runShellCapture(
     const start = performance.now();
     const outcome = await attemptCapture(
       ctx,
-      request,
+      captureRequest,
       env,
-      url,
+      captureUrl,
       reqCtx,
       ssrModule,
       descriptor,
@@ -1122,6 +1154,7 @@ async function attemptCapture(
   const { derivedCtx, freshHandleStore } = deriveShellCaptureContext(
     reqCtx,
     descriptor,
+    descriptor.navigationOnly ? { request, url } : undefined,
   );
   const captureStartedAt = Date.now();
 
@@ -1195,6 +1228,7 @@ export interface CaptureContextDerivation {
 export function deriveShellCaptureContext(
   reqCtx: RequestContext<any>,
   descriptor: Pick<ShellCaptureDescriptor, "ttl" | "swr">,
+  identity?: { request: Request; url: URL },
 ): CaptureContextDerivation {
   const freshHandleStore = createHandleStore();
   freshHandleStore.onError = reqCtx._handleStore.onError;
@@ -1266,6 +1300,13 @@ export function deriveShellCaptureContext(
   };
 
   const derivedCtx: RequestContext = Object.create(reqCtx);
+  if (identity) {
+    derivedCtx.request = identity.request;
+    derivedCtx.url = identity.url;
+    derivedCtx.originalUrl = new URL(identity.url);
+    derivedCtx.pathname = identity.url.pathname;
+    derivedCtx.searchParams = identity.url.searchParams;
+  }
   derivedCtx._handleStore = freshHandleStore;
   // Own render barrier, closure-bound to the derived ctx and the fresh store
   // (issue #684, plan 009). Without this every _renderBarrier* read fell
@@ -1553,7 +1594,7 @@ async function captureAndStoreShell(
     const loaderRecords = reqCtx._shellCaptureLoaderRecords;
     // Set once a bake-lane loader settles with real (non-hole) material: its data
     // is frozen into the shell prelude regardless of whether snapshot
-    // serialization succeeds. Drives the untagged-bake dev warning below.
+    // serialization succeeds. Drives the opt-in debug metadata below.
     let bakedLoaderMaterial = false;
     if (loaderRecords && loaderRecords.size > 0) {
       // The codec import is deferred past the elide probes: a rejected record
@@ -1638,13 +1679,15 @@ async function captureAndStoreShell(
     const union = new Set<string>([...(capture.tags ?? []), ...collected]);
     const shellTags = union.size > 0 ? [...union] : undefined;
 
-    // Untagged-bake diagnostic: a bake-lane loader froze mutable data into the
-    // shell but nothing tags the entry, so it is un-invalidatable except by TTL —
-    // a read-your-own-writes gap on the document channel (an action refresh skips
-    // the server shell; updateTag cannot drop untagged data). Coarse per-shell-key
-    // signal; dev-only and once-per-key so it never spams production.
-    if (isDevMode() && bakedLoaderMaterial && shellTags === undefined) {
-      warnUntaggedShellBakeOnce(capture.key);
+    // Missing tags are valid: the shell follows TTL/SWR-only invalidation. Expose
+    // that choice only to operators who enabled structured capture diagnostics.
+    if (
+      capture.debugSink &&
+      stats &&
+      bakedLoaderMaterial &&
+      shellTags === undefined
+    ) {
+      stats.untaggedBake = true;
     }
 
     const store = capture.store ?? reqCtx._cacheStore;
@@ -1664,6 +1707,12 @@ 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
           // unknowable), or a handler-invoked loader execution — any of them

package/src/rsc/shell-serve.ts

@@ -19,7 +19,9 @@
 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";
 
 /** Debug/status header the browser (and e2e assertions) can read: HIT | MISS. */
 export const SHELL_STATUS_HEADER = "x-rango-shell";
@@ -62,9 +64,10 @@ export interface ResolvedPprConfig {
 }
 
 /**
- * Validate the raw `ppr.captureTimeout` option: a finite number >= 1ms passes
- * through; anything else (including 0/negative/NaN/Infinity/non-number)
- * resolves to undefined, which means "use the capture default" downstream.
+ * Validate the raw `ppr.captureTimeout` option: a finite number >= 1ms is
+ * clamped to the default ceiling; anything else (including
+ * 0/negative/NaN/Infinity/non-number) resolves to undefined, which means "use
+ * the capture default" downstream.
  * Mirrors the prefetch-limit option policy: invalid values silently fall back
  * to the default rather than throwing at request time. Also the boundary
  * re-normalizer for the dev /__rsc_shell endpoint (vite/router-discovery.ts),
@@ -72,7 +75,7 @@ export interface ResolvedPprConfig {
  */
 export function normalizeCaptureTimeout(value: unknown): number | undefined {
   return typeof value === "number" && Number.isFinite(value) && value >= 1
-    ? value
+    ? Math.min(value, SHELL_CAPTURE_MAX_WAIT_MS)
     : undefined;
 }
 
@@ -115,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`;
 }

package/src/rsc/types.ts

@@ -49,6 +49,8 @@ export interface RscPayload {
     prefetchCacheSize?: number;
     /** Max concurrent speculative prefetch requests on the client */
     prefetchConcurrency?: number;
+    /** Router-wide default prefetch strategy for Links without a `prefetch` prop */
+    defaultPrefetch?: import("../router/prefetch-default.js").PrefetchStrategy;
     /** Server-resolved rango state cookie name; the client reads it verbatim. */
     stateCookieName?: string;
     /** Theme configuration for FOUC prevention */
@@ -208,6 +210,23 @@ export interface HandlerCacheConfig {
   store: import("../cache/types.js").SegmentCacheStore;
   /** Enable/disable caching (default: true) */
   enabled?: boolean;
+  /**
+   * Which query params key the cache (default: `"all"`). Affects cache keys
+   * ONLY -- handlers and loaders still see the full query string. Global by
+   * design: the per-route case is already reachable through `cache({ key })`.
+   *
+   * 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
+   * ```typescript
+   * cache: {
+   *   store: cacheStore,
+   *   searchParams: { exclude: TRACKING_SEARCH_PARAMS },
+   * }
+   * ```
+   */
+  searchParams?: import("../cache/search-params-filter.js").CacheSearchParams;
 }
 
 /**

package/src/server/request-context.ts

@@ -211,9 +211,27 @@ export interface RequestContext<
   /** @internal PPR transition decisions evaluated before cache lookup/handlers. */
   _pprTransitionDecisions?: Map<string, boolean>;
 
+  /**
+   * @internal Post-match serve-source truth for the PPR replay reporter.
+   * Stamped from the match context as `intercept`, then overwritten as
+   * `prerender-store` if that lookup actually serves. The latter wins because
+   * it identifies the response source. matchPartialWithPprReplay reads this
+   * AFTER matching to reclassify its pre-match guess and suppress pointless
+   * heal captures.
+   */
+  _pprReplayPostMatchReason?: "prerender-store" | "intercept";
+
   /** @internal Cache store for segment caching (optional, used by CacheScope) */
   _cacheStore?: SegmentCacheStore;
 
+  /**
+   * @internal Compiled `cache.searchParams` filter for default cache-key
+   * generation (undefined = "all", the byte-stable unfiltered format). Set
+   * once per request by handler.ts; every URL-keyed tier (segment, document,
+   * response, shell, "use cache") reads it so the tiers cannot drift.
+   */
+  _searchParamsFilter?: import("../cache/search-params-filter.js").SearchParamsFilter;
+
   /**
    * @internal PPR shell-capture ACTIVE marker. True ONLY inside the background
    * capture task's derived request context (built by shell-capture.ts). This is
@@ -265,9 +283,13 @@ export interface RequestContext<
    * (b) a HIT tail's seeded context, and (c) an eligible normal-route partial
    * replay, where `store` is a request-local segment overlay. Handler-live holes
    * and conditional transitions decline replay.
-   * Routes with their own cache() config (including cache(false)) are never
-   * overridden: the marker only applies when the route tree derived NO cache
-   * scope.
+   * Routes with their own cache() config are never overridden — their scope's
+   * store/key/ttl/swr/condition semantics stay authoritative. On the
+   * navigation-replay serve path (`onExplicitHit` set) the marker COMPOSES with
+   * such a scope instead of being ignored: the seeded doc record supplies the match
+   * only when the explicit tier misses (withCacheLookup). cache(false) and a
+   * false condition() stay absolute opt-outs — replay bypasses before any
+   * shell read (`cache-disabled`).
    */
   _shellImplicitCache?: {
     ttl?: number;
@@ -281,6 +303,34 @@ export interface RequestContext<
     keyPrefix?: "doc";
     /** @internal Called only after the implicit cache hit decodes successfully. */
     onHit?: () => void;
+    /**
+     * @internal The resolved key of the canonical document segment record.
+     * Written during a CAPTURE render by CacheScope.cacheRoute when a
+     * doc-namespaced scope records the matched segments; captureAndStoreShell
+     * stamps it onto the ShellCacheEntry (`docKey`) so replay eligibility can
+     * require the exact consumable record instead of "any segment record".
+     */
+    docKey?: string;
+    /**
+     * @internal Set ONLY by matchPartialWithPprReplay on the navigation-replay
+     * serve path. Its presence arms the explicit-scope composition in
+     * withCacheLookup: a route-derived cache() scope stays authoritative, and
+     * only when its lookup MISSes does the seeded doc record supply the match.
+     * A capture render must never set this (its match must re-run handlers so
+     * SWR recapture stays fresh), which is why the fallback keys off this
+     * field and not off the marker itself. Fired when the route-derived
+     * scope's own lookup supplied the match — the header then reports
+     * `BYPASS; reason=explicit-cache-hit`, never a false replay HIT.
+     */
+    onExplicitHit?: () => void;
+    /**
+     * @internal Companion to onExplicitHit, same lifecycle: fired when the
+     * route-derived scope's lookup REFUSED the read (`bypass` outcome — a
+     * false condition() or no store). The gate only pre-decides the static
+     * cache(false) case; a predicate refusal is known only at lookup time and
+     * reports `BYPASS; reason=cache-disabled` post-match.
+     */
+    onExplicitBypass?: () => void;
   };
 
   /**
@@ -656,7 +706,9 @@ export type PublicRequestContext<
   | "_handleStore"
   | "_transitionWhen"
   | "_pprTransitionDecisions"
+  | "_pprReplayPostMatchReason"
   | "_cacheStore"
+  | "_searchParamsFilter"
   | "_shellCaptureRun"
   | "_shellImplicitCache"
   | "_shellLoaderSeed"
@@ -842,6 +894,11 @@ export interface CreateRequestContextOptions<TEnv> {
   initialResponse?: Response;
   /** Optional cache store for segment caching (used by CacheScope) */
   cacheStore?: SegmentCacheStore;
+  /**
+   * Compiled `cache.searchParams` filter from the resolved handler cache
+   * config (handler.ts). Stored as _searchParamsFilter.
+   */
+  searchParamsFilter?: import("../cache/search-params-filter.js").SearchParamsFilter;
   /**
    * Handler-owned registry of explicit per-scope stores for cross-store tag
    * invalidation. Created once per handler, reused across requests.
@@ -882,6 +939,7 @@ export function createRequestContext<TEnv>(
     variables,
     initialResponse,
     cacheStore,
+    searchParamsFilter,
     explicitTaggedStores,
     cacheProfiles,
     executionContext,
@@ -1176,6 +1234,7 @@ export function createRequestContext<TEnv>(
     _handleStore: handleStore,
     _transitionWhen: [],
     _cacheStore: cacheStore,
+    _searchParamsFilter: searchParamsFilter,
     _explicitTaggedStores: explicitTaggedStores,
     _requestTags: new Set<string>(),
     _cacheProfiles: cacheProfiles,

package/src/testing/dispatch.ts

@@ -116,6 +116,11 @@ import {
   stripInternalParams,
 } from "../router/handler-context.js";
 import { NOCACHE_SYMBOL } from "../cache/taint.js";
+import {
+  compileSearchParamsFilter,
+  type CacheSearchParams,
+  type SearchParamsFilter,
+} from "../cache/search-params-filter.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { CacheProfile } from "../cache/profile-registry.js";
 // cache-scope is loaded LAZILY inside the response-route cache path (below):
@@ -193,11 +198,19 @@ interface DispatchableRouter<TEnv> {
   } | null>;
   basename?: string;
   cache?:
-    | { enabled?: boolean; store?: SegmentCacheStore }
+    | {
+        enabled?: boolean;
+        store?: SegmentCacheStore;
+        searchParams?: CacheSearchParams;
+      }
     | ((
         env: TEnv,
         executionContext: unknown,
-      ) => { enabled?: boolean; store?: SegmentCacheStore });
+      ) => {
+        enabled?: boolean;
+        store?: SegmentCacheStore;
+        searchParams?: CacheSearchParams;
+      });
   cacheProfiles?: Record<string, CacheProfile>;
 }
 
@@ -375,13 +388,17 @@ export async function dispatch<TEnv = any>(
   // "use cache" inside a response-route handler reaches the request-scope
   // (NOCACHE) detection below instead of bypassing on a missing store.
   let cacheStore: SegmentCacheStore | undefined;
+  let searchParamsFilter: SearchParamsFilter | undefined;
   const cacheOption = router.cache;
   if (cacheOption && !url.searchParams.has("__no_cache")) {
     const cacheConfig =
       typeof cacheOption === "function"
         ? cacheOption(env, undefined)
         : cacheOption;
-    if (cacheConfig.enabled !== false) cacheStore = cacheConfig.store;
+    if (cacheConfig.enabled !== false) {
+      cacheStore = cacheConfig.store;
+      searchParamsFilter = compileSearchParamsFilter(cacheConfig.searchParams);
+    }
   }
 
   const requestContext = createRequestContext<TEnv>({
@@ -390,6 +407,7 @@ export async function dispatch<TEnv = any>(
     url,
     variables,
     cacheStore,
+    searchParamsFilter,
     cacheProfiles: router.cacheProfiles,
   });
   // Wire background error reporting so cache degradation (reportCacheError ->

package/src/testing/e2e/index.ts

@@ -5,12 +5,15 @@ import {
   type FixtureOptions,
 } from "./fixture.js";
 import {
+  blockPrefetch,
+  unblockPrefetch,
   createPageHelpers,
   createStopwatch,
   getHistoryState,
   getNumericContent,
   goBack,
   goForward,
+  isPrefetchRequest,
   isVisibleInViewport,
   measureTime,
   type PageHelpers,
@@ -62,6 +65,9 @@ export {
   getHistoryState,
   waitForElement,
   isVisibleInViewport,
+  isPrefetchRequest,
+  blockPrefetch,
+  unblockPrefetch,
   parseNumber,
   getNumericContent,
   createStopwatch,

package/src/testing/e2e/page-helpers.ts

@@ -159,6 +159,53 @@ export async function measureTime<T>(
   return { elapsed, result };
 }
 
+/**
+ * True when the request is a speculative prefetch (Link viewport/hover/render
+ * strategies or `useRouter().prefetch()`). Every prefetch fetch carries the
+ * `X-Rango-Prefetch` header. Links prefetch by default in production unless
+ * the router opts out, so tests that track `_rsc_partial` requests to pin
+ * NAVIGATION behavior must skip these — a request-count or first-request
+ * assertion otherwise races background prefetch traffic.
+ */
+export function isPrefetchRequest(req: {
+  headers: () => Record<string, string>;
+}): boolean {
+  return !!req.headers()["x-rango-prefetch"];
+}
+
+// Module-level matcher + handler so blockPrefetch/unblockPrefetch share
+// stable references — Playwright's unroute matches by identity.
+const rscPartialUrl = (url: URL): boolean =>
+  url.searchParams.has("_rsc_partial");
+async function abortPrefetchRoute(
+  route: import("@playwright/test").Route,
+): Promise<void> {
+  if (isPrefetchRequest(route.request())) {
+    await route.abort("aborted");
+  } else {
+    await route.fallback();
+  }
+}
+
+/**
+ * Abort every speculative prefetch request on this page. Install BEFORE
+ * `page.goto` so no prefetch can complete first. For tests whose semantics
+ * need a virgin prefetch cache: a click on a Link whose target was already
+ * prefetched ADOPTS the warmed entry and issues no navigation fetch at all —
+ * a `page.route` override, a request waiter, or a Set-Cookie assertion aimed
+ * at the navigation request then sees nothing (or sees the prefetch's side
+ * effects instead). Aborted prefetches are benign by design (evicted, never
+ * adopted, no page error), so the click's real fetch is guaranteed live.
+ */
+export async function blockPrefetch(page: Page): Promise<void> {
+  await page.route(rscPartialUrl, abortPrefetchRoute);
+}
+
+/** Remove a `blockPrefetch` guard, restoring normal prefetch traffic. */
+export async function unblockPrefetch(page: Page): Promise<void> {
+  await page.unroute(rscPartialUrl, abortPrefetchRoute);
+}
+
 // ============================================================================
 //  Factory-bound helpers (need the injected `expect`)
 // ============================================================================

package/src/testing/e2e/parity.ts

@@ -7,6 +7,7 @@
 import type { Expect, Page, TestType } from "@playwright/test";
 import type { Fixture, FixtureOptions } from "./fixture.js";
 import { DEFAULT_STATE_COOKIE_PREFIX } from "../../browser/cookie-name.js";
+import { blockPrefetch, unblockPrefetch } from "./page-helpers.js";
 
 export interface ParityDescribeOptions extends Partial<
   Omit<FixtureOptions, "mode">
@@ -318,6 +319,15 @@ export function createParity({
     // navigation away from it.
     const originUrl = page.url();
 
+    // Exclude speculative prefetch traffic from the parity window. Links
+    // prefetch by default in production unless the router opts out, and a
+    // prefetched route's middleware/loader side effects
+    // (Set-Cookie, session state) land in the JS jar only — a no-JS context
+    // cannot prefetch, so that traffic would diverge the jars on requests the
+    // intent never caused. Aborted prefetches are benign by design (evicted,
+    // never adopted), so the intent's real navigation always fetches live.
+    await blockPrefetch(page);
+
     // Settle the intent's observable effect before snapshotting. A `navigate`
     // intent already awaited its navigation in applyIntent (page.goto), so only
     // `submit` needs the DOM-driven settle, and only when no `waitFor` override
@@ -380,6 +390,9 @@ export function createParity({
       );
     } finally {
       await noJsContext.close();
+      // Restore the caller's page: the prefetch guard is scoped to the parity
+      // window, not the rest of the test.
+      await unblockPrefetch(page);
     }
   }