@rangojs/router 0.4.0 → 0.4.2

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

@@ -92,17 +92,19 @@
  *   - 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, 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.
@@ -124,17 +126,13 @@ let _decodeHandles:
 let _hashParams:
   | typeof import("../../prerender/param-hash.js").hashParams
   | undefined;
-let _lazyGetRequestContext:
-  | typeof import("../../server/request-context.js").getRequestContext
-  | undefined;
 
 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;
@@ -142,7 +140,6 @@ async function ensurePrerenderDeps() {
     _restoreHandles = snapshot.restoreHandles;
     _decodeHandles = snapshot.decodeHandles;
     _hashParams = paramHash.hashParams;
-    _lazyGetRequestContext = reqCtx.getRequestContext;
     if (prerenderStoreInstance === undefined) {
       prerenderStoreInstance = store.createPrerenderStore();
     }
@@ -234,18 +231,16 @@ async function* yieldFromStore<TEnv>(
   ctx: MatchContext<TEnv>,
   state: MatchPipelineState,
   pipelineStart: number,
-  handleStoreRef?: HandleStore,
+  reqCtx: RequestContext<TEnv> | undefined,
+  resolveLoadersOnly: RouterContext<TEnv>["resolveLoadersOnly"],
+  resolveLoadersOnlyWithRevalidation: RouterContext<TEnv>["resolveLoadersOnlyWithRevalidation"],
 ): AsyncGenerator<ResolvedSegment> {
-  const { resolveLoadersOnlyWithRevalidation, resolveLoadersOnly } =
-    getRouterContext<TEnv>();
-
   if (
     !_deserializeSegments ||
     !_fragmentSegments ||
     !_restoreHandles ||
     !_decodeHandles ||
-    !_hashParams ||
-    !_lazyGetRequestContext
+    !_hashParams
   ) {
     throw new Error("yieldFromStore called before ensurePrerenderDeps");
   }
@@ -254,14 +249,14 @@ async function* yieldFromStore<TEnv>(
   // 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 = _getRequestContext()?._shellFragmentPayload
+  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 = handleStoreRef ?? _lazyGetRequestContext()?._handleStore;
+  const handleStore = reqCtx?._handleStore;
   if (handleStore && entry.handles) {
     const handlesRecord = await _decodeHandles(entry.handles);
     if (handlesRecord) {
@@ -275,13 +270,14 @@ async function* yieldFromStore<TEnv>(
   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);
+  // 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);
     }
-    barrierReqCtx._resolveRenderBarrier(segments);
+    reqCtx._resolveRenderBarrier(segments);
   }
 
   // For partial navigation, nullify components the client already has
@@ -313,6 +309,54 @@ async function* yieldFromStore<TEnv>(
   );
 }
 
+/**
+ * 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
@@ -325,7 +369,9 @@ async function* tryPrerenderLookup<TEnv>(
   ctx: MatchContext<TEnv>,
   state: MatchPipelineState,
   pipelineStart: number,
-  handleStoreRef?: HandleStore,
+  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(
@@ -341,7 +387,15 @@ async function* tryPrerenderLookup<TEnv>(
     },
   );
   if (!entry) return false;
-  yield* yieldFromStore(entry, ctx, state, pipelineStart, handleStoreRef);
+  yield* yieldFromStore(
+    entry,
+    ctx,
+    state,
+    pipelineStart,
+    reqCtx,
+    resolveLoadersOnly,
+    resolveLoadersOnlyWithRevalidation,
+  );
   return true;
 }
 
@@ -380,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,
@@ -389,15 +450,19 @@ export function withCacheLookup<TEnv>(
       resolveLoadersOnly,
     } = getRouterContext<TEnv>();
 
-    const isHmr = !!ctx.request.headers.get("X-RSC-HMR");
-    if (!ctx.isAction && !isHmr && ctx.matched.pr) {
+    if (
+      !ctx.isAction &&
+      prerenderStoreShortCircuits(ctx.matched.pr, ctx.request)
+    ) {
       await ensurePrerenderDeps();
       if (prerenderStoreInstance) {
         const served = yield* tryPrerenderLookup(
           ctx,
           state,
           pipelineStart,
-          handleStoreRef,
+          pipelineReqCtx,
+          resolveLoadersOnly,
+          resolveLoadersOnlyWithRevalidation,
         );
         if (served) return;
       }
@@ -418,7 +483,9 @@ export function withCacheLookup<TEnv>(
             ctx,
             state,
             pipelineStart,
-            handleStoreRef,
+            pipelineReqCtx,
+            resolveLoadersOnly,
+            resolveLoadersOnlyWithRevalidation,
           );
           if (served) return;
         }
@@ -437,11 +504,58 @@ export function withCacheLookup<TEnv>(
       return;
     }
 
-    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) {
       yield* source;
@@ -460,8 +574,7 @@ export function withCacheLookup<TEnv>(
     state.shouldRevalidate = cacheResult.shouldRevalidate;
     state.cachedSegments = cacheResult.segments;
     state.cachedMatchedIds = cacheResult.segments.map((s) => s.id);
-    const pprTransitionDecisions =
-      _getRequestContext()?._pprTransitionDecisions;
+    const pprTransitionDecisions = pipelineReqCtx?._pprTransitionDecisions;
 
     const canCheckSegmentRevalidation =
       !ctx.isFullMatch &&
@@ -581,7 +694,7 @@ export function withCacheLookup<TEnv>(
       yield segment;
     }
 
-    const barrierReqCtx = _getRequestContext();
+    const barrierReqCtx = pipelineReqCtx;
     if (barrierReqCtx) {
       if (barrierReqCtx._treeHasStreaming === undefined) {
         barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);

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).