@rangojs/router 0.2.0 → 0.4.1

package/src/browser/rsc-router.tsx

@@ -30,6 +30,7 @@ import {
   setPrefetchConcurrency,
   setPrefetchDecoder,
 } from "./prefetch/loader.js";
+import { setDefaultPrefetchStrategy } from "./prefetch/default-strategy.js";
 import { setAppVersion } from "./app-version.js";
 import {
   isInterceptSegment,
@@ -67,8 +68,11 @@ export interface InitBrowserAppOptions {
 
   /**
    * Enable global link interception for SPA navigation.
-   * When enabled, clicks on same-origin anchor elements are intercepted
-   * and handled via client-side navigation instead of full page loads.
+   * When enabled, clicks on eligible same-origin HTML anchor elements are intercepted
+   * and handled via client-side navigation instead of full page loads. Plain
+   * anchors inside the router basename also follow its default prefetch strategy
+   * after hydration. `data-prefetch="false"`/`"none"` opts out; `"true"` allows
+   * an application route with a common static-resource suffix.
    *
    * Links rendered with the Link component handle their own navigation
    * regardless of this setting.
@@ -123,6 +127,8 @@ export interface BrowserAppContext {
   warmupEnabled?: boolean;
   /** Whether the hydrated tree should be wrapped in React.StrictMode */
   strictMode?: boolean;
+  /** Whether plain-anchor click interception and delegated prefetch are enabled */
+  linkInterceptionEnabled?: boolean;
   /** App version for prefetch version mismatch detection */
   version?: string;
   /**
@@ -195,6 +201,12 @@ export async function initBrowserApp(
   }
   const initialHistoryKey = generateHistoryKey(window.location.href);
 
+  // Resolve the state namespace before the store installs its BroadcastChannel
+  // listener. A streaming handle payload can delay hydration below; leaving the
+  // default name active during that wait would discard this router's messages.
+  const version = initialPayload.metadata?.version;
+  initRangoState(version ?? "0", initialPayload.metadata?.stateCookieName);
+
   // Create navigation store with history-based caching
   const store = createNavigationStore({
     initialLocation: window.location,
@@ -270,7 +282,6 @@ export async function initBrowserApp(
   // It is set once from the initial payload and not swapped within a session:
   // a cross-app navigation is a full document load (X-RSC-Reload), so the
   // target app establishes its own shell on load.
-  const version = initialPayload.metadata?.version;
   const appShellRef = createAppShellRef({
     routerId: initialPayload.metadata?.routerId,
     rootLayout: initialPayload.metadata?.rootLayout,
@@ -278,11 +289,6 @@ export async function initBrowserApp(
     version,
   });
 
-  // Initialize the rango state cookie for cache invalidation. The build version
-  // busts cached prefetches on deploy; the server-resolved cookie name
-  // namespaces the cookie so sibling apps on the same origin don't collide
-  // (falls back to the bare default prefix if metadata lacks the name).
-  initRangoState(version ?? "0", initialPayload.metadata?.stateCookieName);
   setAppVersion(version);
 
   // Initialize the in-memory prefetch cache (TTL + max size) and the prefetch
@@ -297,6 +303,13 @@ export async function initBrowserApp(
   if (prefetchConcurrency !== undefined) {
     setPrefetchConcurrency(prefetchConcurrency);
   }
+  // Apply the router-wide default Link prefetch strategy. Undefined (older
+  // server payload) keeps the module's environment-aware default, which equals
+  // the server resolver's default by contract — see default-strategy.ts.
+  const defaultPrefetch = initialPayload.metadata?.defaultPrefetch;
+  if (defaultPrefetch !== undefined) {
+    setDefaultPrefetchStrategy(defaultPrefetch);
+  }
 
   // Wire the RSC decoder so prefetches decode eagerly and warm the route's
   // client chunks (same createFromFetch the navigation client uses).
@@ -351,6 +364,8 @@ export async function initBrowserApp(
     onUpdate: (update) => store.emitUpdate(update),
     renderSegments,
     version: version,
+    defaultPrefetch,
+    basename: initialPayload.metadata?.basename,
   });
 
   // Connect action redirect → navigation bridge (now that both are initialized)
@@ -533,6 +548,7 @@ export async function initBrowserApp(
     initialTheme: effectiveInitialTheme,
     warmupEnabled: initialPayload.metadata?.warmupEnabled ?? true,
     strictMode: initialPayload.metadata?.strictMode ?? true,
+    linkInterceptionEnabled: linkInterception,
     version,
     appShellRef,
   };
@@ -606,6 +622,7 @@ export function Rango(_props: RangoProps): React.ReactElement {
     warmupEnabled,
     version,
     appShellRef,
+    linkInterceptionEnabled,
   } = getBrowserAppContext();
 
   // Signal that the React tree has hydrated. useEffect only fires after
@@ -613,11 +630,15 @@ export function Rango(_props: RangoProps): React.ReactElement {
   // that does not depend on React internals like __reactFiber.
   React.useEffect(() => {
     document.documentElement.dataset.hydrated = "";
+    const cleanupPrefetch = linkInterceptionEnabled
+      ? bridge.registerDelegatedPrefetch()
+      : undefined;
     if (IS_BROWSER_DEBUG && !hydrationCommitLogged) {
       hydrationCommitLogged = true;
       bootLog("hydration commit (root effect flushed)");
     }
-  }, []);
+    return cleanupPrefetch;
+  }, [bridge, linkInterceptionEnabled]);
 
   return (
     <NavigationProvider

package/src/browser/types.ts

@@ -82,6 +82,11 @@ export interface RscMetadata {
    * Sent on initial render so the browser can configure its prefetch queue.
    */
   prefetchConcurrency?: number;
+  /**
+   * Router-wide default prefetch strategy for Links without a `prefetch` prop.
+   * Sent on initial render; applied once at init (default-strategy.ts).
+   */
+  defaultPrefetch?: import("../router/prefetch-default.js").PrefetchStrategy;
   /**
    * Server-resolved rango state cookie name (`{prefix}_{routerId}`). The client
    * reads it verbatim and binds the rango state cookie to it; composition
@@ -608,6 +613,7 @@ export interface NavigationBridge {
   refresh(): Promise<void>;
   handlePopstate(): Promise<void>;
   registerLinkInterception(): () => void;
+  registerDelegatedPrefetch(): () => void;
   /** Current RSC version (live, reflects the latest updateVersion). */
   getVersion(): string | undefined;
   /** Update the RSC version (e.g. after HMR). Clears prefetch cache. */

package/src/cache/cache-key-utils.ts

@@ -7,6 +7,7 @@
  */
 
 import { encodeKV } from "../encode-kv.js";
+import type { SearchParamsFilter } from "./search-params-filter.js";
 
 /**
  * Reserved URL query params that the router owns and must never key the cache
@@ -34,12 +35,22 @@ function isReservedSearchParam(key: string): boolean {
  * Build a sorted, deterministic query string from URLSearchParams,
  * excluding the router's reserved params (see isReservedSearchParam).
  *
- * Returns empty string when no user-facing params exist.
+ * `filter` is the compiled `cache.searchParams` config (search-params-filter.ts),
+ * applied AFTER the reserved-param exclusion and BEFORE the sort, so reserved
+ * params can never be re-included (`include: ["__no_cache"]` is a no-op) and
+ * surviving params stay order-insensitive. `undefined` means no filtering --
+ * that path must stay byte-identical to the pre-filter format (cacheKeyBase
+ * output is byte-stable by contract).
+ *
+ * Returns empty string when no user-facing params survive.
  */
-export function sortedSearchString(searchParams: URLSearchParams): string {
+export function sortedSearchString(
+  searchParams: URLSearchParams,
+  filter?: SearchParamsFilter,
+): string {
   const pairs: [string, string][] = [];
   for (const [k, v] of searchParams) {
-    if (!isReservedSearchParam(k)) {
+    if (!isReservedSearchParam(k) && (filter === undefined || filter(k))) {
       pairs.push([k, v]);
     }
   }
@@ -77,9 +88,12 @@ export function cacheKeyBase(
   pathname: string,
   searchParams?: URLSearchParams,
   params?: Record<string, string>,
+  filter?: SearchParamsFilter,
 ): string {
   const paramStr = sortedRouteParams(params);
-  const searchStr = searchParams ? sortedSearchString(searchParams) : "";
+  const searchStr = searchParams
+    ? sortedSearchString(searchParams, filter)
+    : "";
 
   let key = `${host}${pathname}`;
   if (paramStr) key += `:${paramStr}`;

package/src/cache/cache-runtime.ts

@@ -302,9 +302,14 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           if (ctx._responseType) {
             keyArgs.push(ctx._responseType);
           }
-          // Include user-facing search params (exclude internal _rsc*/__ params)
+          // Include user-facing search params (exclude internal _rsc*/__
+          // params, plus the request's cache.searchParams filter -- same
+          // normalization as the URL-keyed tiers).
           if (ctx.searchParams instanceof URLSearchParams) {
-            const normalized = sortedSearchString(ctx.searchParams);
+            const normalized = sortedSearchString(
+              ctx.searchParams,
+              requestCtx?._searchParamsFilter,
+            );
             if (normalized) {
               keyArgs.push(normalized);
             }

package/src/cache/cache-scope.ts

@@ -11,6 +11,7 @@
 import type { PartialCacheOptions } from "../types.js";
 import type { ResolvedSegment } from "../types.js";
 import type { SegmentCacheStore, CachedEntryData } from "./types.js";
+import { CACHE_READ_ERROR } from "./types.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import {
   getRequestContext,
@@ -101,7 +102,7 @@ function getDefaultRouteCacheKey(
     ? "intercept"
     : (prefixOverride ?? (isPartial ? "partial" : "doc"));
 
-  return `${prefix}:${cacheKeyBase(host, pathname, searchParams, params)}`;
+  return `${prefix}:${cacheKeyBase(host, pathname, searchParams, params, ctx?._searchParamsFilter)}`;
 }
 
 // ============================================================================
@@ -110,6 +111,17 @@ function getDefaultRouteCacheKey(
 
 const CACHE_HIT_OBSERVERS = new WeakMap<CacheScope, () => void>();
 
+/**
+ * Discriminated outcome of a route cache lookup — see
+ * {@link CacheScope.lookupRouteDetailed} for what each status licenses.
+ */
+export type CacheRouteLookupOutcome =
+  | {
+      status: "hit";
+      result: { segments: ResolvedSegment[]; shouldRevalidate: boolean };
+    }
+  | { status: "miss" | "bypass" | "error" };
+
 /**
  * CacheScope represents a cache boundary in the route tree.
  *
@@ -225,30 +237,76 @@ export class CacheScope {
     return resolveCacheKey(keyFn, this.getStore(), defaultKey, "CacheScope");
   }
 
+  /**
+   * @internal Whether a cache read/write is allowed for the current request:
+   * the scope is enabled AND its `condition` (if any) returns true. "read"
+   * is consulted by the PPR navigation-replay gate BEFORE any shell-store
+   * read so a cache(false)/condition-false route reports `cache-disabled`
+   * without spending getShell I/O; "write" gates the capture's snapshot-only
+   * doc record (cache-store middleware) under the same semantics as the
+   * scope's own store write. Consumer opt-outs are absolute — the seeded
+   * fallback must never serve where the consumer refused cached serves.
+   */
+  allowsCache(op: "read" | "write"): boolean {
+    return this.enabled && this.conditionAllows(op);
+  }
+
+  /**
+   * @internal True for scopes minted from the `_shellImplicitCache` marker
+   * (createShellImplicitDocScope) — the only construction path that passes
+   * the `doc` defaultKeyPrefix; route-derived scopes (createCacheScope) never
+   * do. withCacheLookup/withCacheStore use this to tell the implicit doc
+   * scope from a route-derived scope: the two compose on the replay serve
+   * path and only the route-derived kind gets the seeded fallback /
+   * doc-record treatment.
+   */
+  get isShellImplicitDocScope(): boolean {
+    return this.defaultKeyPrefix === "doc";
+  }
+
   /**
    * Evaluate the cache `condition` predicate. Returns false (skip the cache
    * operation) when the predicate returns false or throws; returns true when
    * there is no condition or no request context to evaluate it against.
    */
+  /**
+   * One WRITE decision per (scope, request), memoized on the request context.
+   * A capture render has TWO writers consulting the same predicate — the
+   * explicit tier's cacheRoute and the snapshot-only doc record gate
+   * (recordShellCaptureDocRecord) — and a true→false flap between the two
+   * evaluations recorded a REPLAYABLE canonical snapshot for a render whose
+   * real write was refused. The first evaluation pins the answer for the
+   * whole render (the capture's derived context during captures). READ
+   * decisions stay per-lookup by design: pre-deciding a flappable predicate
+   * at the replay gate was the round-2 regression.
+   */
+  private readonly writeConditionMemo = new WeakMap<RequestContext, boolean>();
+
   private conditionAllows(op: "read" | "write"): boolean {
     if (this.config === false || !this.config.condition) return true;
     const requestCtx = getRequestContext();
     if (!requestCtx) return true;
+    if (op === "write") {
+      const memoized = this.writeConditionMemo.get(requestCtx);
+      if (memoized !== undefined) return memoized;
+    }
+    let allowed: boolean;
     try {
-      if (!this.config.condition(requestCtx)) {
+      allowed = !!this.config.condition(requestCtx);
+      if (!allowed) {
         debugCacheLog(
           `[CacheScope] condition returned false, skipping cache ${op}`,
         );
-        return false;
       }
-      return true;
     } catch (error) {
       console.error(
         `[CacheScope] condition function threw, skipping cache ${op}:`,
         error,
       );
-      return false;
+      allowed = false;
     }
+    if (op === "write") this.writeConditionMemo.set(requestCtx, allowed);
+    return allowed;
   }
 
   /**
@@ -267,11 +325,42 @@ export class CacheScope {
     segments: ResolvedSegment[];
     shouldRevalidate: boolean;
   } | null> {
-    if (!this.enabled) return null;
-    if (!this.conditionAllows("read")) return null;
+    const outcome = await this.lookupRouteDetailed(
+      pathname,
+      params,
+      isIntercept,
+    );
+    return outcome.status === "hit" ? outcome.result : null;
+  }
+
+  /**
+   * @internal lookupRoute with a discriminated outcome. The PPR replay
+   * composition (withCacheLookup) may substitute the seeded doc record ONLY on
+   * a true `miss` — the other non-hit outcomes must not be papered over:
+   *
+   * - `bypass`: the scope refused the read — cache(false), a false
+   *   `condition()`, or no resolvable store. Consumer opt-outs are absolute;
+   *   a fallback here would serve cached segments to a request the consumer
+   *   said must render fresh.
+   * - `error`: a throwing consumer key()/store keyGenerator/store.get. The
+   *   contract on that failure is "render uncached" (see the catch below) —
+   *   falling back would serve the canonical doc record across a broken key
+   *   partition, exactly the collision resolveCacheKey's no-default-fallback
+   *   rule exists to prevent.
+   *
+   * A corrupt entry that was evicted reads as `miss`: the store was consulted
+   * and holds nothing servable, which is the post-eviction truth.
+   */
+  async lookupRouteDetailed(
+    pathname: string,
+    params: Record<string, string>,
+    isIntercept?: boolean,
+  ): Promise<CacheRouteLookupOutcome> {
+    if (!this.enabled) return { status: "bypass" };
+    if (!this.conditionAllows("read")) return { status: "bypass" };
 
     const store = this.getStore();
-    if (!store) return null;
+    if (!store) return { status: "bypass" };
 
     // Resolve cache key INSIDE the try so a throwing consumer key() (or a
     // store.keyGenerator) degrades to a cache miss (return null -> render
@@ -285,9 +374,17 @@ export class CacheScope {
 
       const result = await store.get(key);
 
+      // Built-in stores swallow backend read failures internally and signal
+      // them with CACHE_READ_ERROR — classify as `error`, not `miss`, so the
+      // replay composition renders uncached instead of substituting the
+      // seeded doc record for a tier whose backend never answered.
+      if (result === CACHE_READ_ERROR) {
+        return { status: "error" };
+      }
+
       if (!result) {
         debugCacheLog(`[CacheScope] MISS: ${key}`);
-        return null;
+        return { status: "miss" };
       }
 
       const { data: cached, shouldRevalidate } = result;
@@ -320,7 +417,7 @@ export class CacheScope {
           .catch((e) =>
             reportCacheError(e, "cache-delete", `[CacheScope] ${key}: evict`),
           );
-        return null;
+        return { status: "miss" };
       }
 
       // A hit serves content that was tagged at write time, so the document
@@ -351,16 +448,18 @@ export class CacheScope {
       }
 
       CACHE_HIT_OBSERVERS.get(this)?.();
-      return { segments, shouldRevalidate };
+      return { status: "hit", result: { segments, shouldRevalidate } };
     } catch (error) {
       // Covers a store.get() failure AND a throwing consumer key()/keyGenerator
-      // (resolveKey). Either way degrade to a cache miss so the render proceeds.
+      // (resolveKey). Either way degrade to an uncached render — reported as
+      // `error`, not `miss`, so the replay composition cannot substitute the
+      // seeded doc record for a lookup that never resolved its key partition.
       reportCacheError(
         error,
         "cache-read",
         `[CacheScope] lookup ${key ?? "(key resolution failed)"}`,
       );
-      return null;
+      return { status: "error" };
     }
   }
 
@@ -422,6 +521,15 @@ export class CacheScope {
     // Resolve cache key early (while request context is available)
     const key = await this.resolveKey(pathname, params, isIntercept);
 
+    // Doc-namespaced scopes (the shell implicit scope and the capture's
+    // composed doc scope) publish the canonical document segment key so
+    // captureAndStoreShell can stamp it onto the shell entry (`docKey`).
+    // Replay eligibility then requires this exact record — "any segment
+    // record" previously counted unusable explicit-tier-keyed records too.
+    if (this.defaultKeyPrefix === "doc" && requestCtx._shellImplicitCache) {
+      requestCtx._shellImplicitCache.docKey = key;
+    }
+
     // Resolve tags early (while request context is available, before waitUntil)
     const tags = resolveCacheTags(this.config, requestCtx);
     recordRequestTags(tags, requestCtx);
@@ -538,6 +646,31 @@ export function createCacheScope(
   return new CacheScope(config.options, parent);
 }
 
+type ShellImplicitCacheMarker = NonNullable<
+  RequestContext["_shellImplicitCache"]
+>;
+
+/**
+ * Mint the implicit doc-level scope for a `_shellImplicitCache` marker: key
+ * resolution under the marker's `doc` namespace against the marker's store,
+ * with the marker's onHit wired as the hit observer. Shared by
+ * {@link resolveShellImplicitCacheScope} (routes that derived no scope) and
+ * the explicit-scope composition sites (capture doc record in the cache-store
+ * middleware, seeded replay fallback in withCacheLookup) so both ends of the
+ * shell contract resolve the SAME canonical document key.
+ */
+export function createShellImplicitDocScope(
+  marker: ShellImplicitCacheMarker,
+): CacheScope {
+  const implicitScope = new CacheScope(
+    { ttl: marker.ttl, swr: marker.swr, store: marker.store },
+    null,
+    marker.keyPrefix,
+  );
+  if (marker.onHit) CACHE_HIT_OBSERVERS.set(implicitScope, marker.onHit);
+  return implicitScope;
+}
+
 /**
  * Shell fast path: when the route tree derived NO cache scope and the current
  * request context carries the `_shellImplicitCache` marker (a shell capture,
@@ -548,9 +681,11 @@ export function createCacheScope(
  * (resolveFreshLoadersAndYield).
  *
  * An existing scope — including an explicit cache(false) opt-out — always
- * wins: the consumer's cache() semantics (their ttl/swr/store/condition) are
- * never overridden, and cache(false) keeps the tail on the full handler
- * re-run path.
+ * wins HERE: the consumer's cache() semantics (their ttl/swr/store/condition)
+ * are never overridden, and cache(false) keeps the tail on the full handler
+ * re-run path. On the navigation-replay serve path the marker still composes
+ * with an explicit scope downstream (withCacheLookup's seeded fallback after
+ * an explicit-tier miss) — see `onExplicitHit` on `_shellImplicitCache`.
  */
 export function resolveShellImplicitCacheScope(
   scope: CacheScope | null,
@@ -558,11 +693,5 @@ export function resolveShellImplicitCacheScope(
   if (scope) return scope;
   const marker = getRequestContext()?._shellImplicitCache;
   if (!marker) return null;
-  const implicitScope = new CacheScope(
-    { ttl: marker.ttl, swr: marker.swr, store: marker.store },
-    null,
-    marker.keyPrefix,
-  );
-  if (marker.onHit) CACHE_HIT_OBSERVERS.set(implicitScope, marker.onHit);
-  return implicitScope;
+  return createShellImplicitDocScope(marker);
 }

package/src/cache/cf/cf-cache-store.ts

@@ -35,7 +35,9 @@ import type {
   CacheItemResult,
   CacheItemOptions,
   ShellCacheEntry,
+  CacheReadError,
 } from "../types.js";
+import { CACHE_READ_ERROR } from "../types.js";
 import {
   _getRequestContext,
   type RequestContext,
@@ -286,6 +288,14 @@ interface KVShellEnvelope {
   i?: string;
   /** Capture data snapshot: recorded cache-store hits/writes for HIT parity */
   sn?: import("../types.js").ShellSnapshotRecord[];
+  /**
+   * ShellCacheEntry.docKey. Must round-trip: navigation-replay eligibility
+   * requires the exact canonical doc segment record named here — dropping the
+   * field reads back as "no consumable record" and every partial navigation
+   * reports `no-segment-snapshot` after a KV round trip (the memory store
+   * passes the entry by reference, so only envelope stores can lose it).
+   */
+  dk?: string;
   /**
    * ShellCacheEntry.handlerLiveHoles. Must round-trip: the serve side arms the
    * handler-free fast path on `!entry.handlerLiveHoles`, so dropping the flag
@@ -295,6 +305,8 @@ interface KVShellEnvelope {
   lh?: boolean;
   /** ShellCacheEntry.transitionWhen; conditional transitions must re-run. */
   tw?: true;
+  /** ShellCacheEntry.navigationOnly; its partial-context prelude is not document-safe. */
+  no?: true;
 }
 
 /**
@@ -881,7 +893,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * On L1 miss, falls back to KV (L2) if configured.
    * KV hits are promoted to L1 in the background.
    */
-  async get(key: string): Promise<CacheGetResult | null> {
+  async get(key: string): Promise<CacheGetResult | null | CacheReadError> {
     if (this.isReservedSegmentKey(key, "cache-read")) return null;
     try {
       const cache = await this.getCache();
@@ -895,27 +907,40 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const matchMs = Date.now() - matchStart;
 
       if (!response) {
-        // A transient L1 match error (matchError set) is reported as cache-read
-        // but, like a genuine miss or an abandoned slow match (timedOut), still
-        // degrades to L2/KV rather than failing the read.
-        if (matchError)
+        if (matchError) {
+          // A match REJECTION is reported as cache-read and still degrades to
+          // L2/KV -- a real KV value (or KV's own CACHE_READ_ERROR) stands on
+          // its own. But a null KV result (unconfigured namespace, kv-miss,
+          // kv-timeout) is NOT proof of absence under a rejected L1 match:
+          // the only real signal this read produced is the failure, so
+          // surface CACHE_READ_ERROR instead of a replayable miss (the PPR
+          // seeded fallback must render uncached, not substitute the doc
+          // record for a partition the store could not actually read).
           reportCacheError(
             matchError,
             "cache-read",
             "[CFCacheStore] get L1 match",
           );
+          if (this.debug)
+            this.emitDebug({
+              op: "get",
+              key,
+              // Distinct from a genuine absence: surface it as match-error so
+              // debug agrees with the cache-read already routed to onError,
+              // instead of masquerading as l1-miss.
+              outcome: "match-error",
+              matchMs,
+            });
+          const kvResult = await this.kvGetSegment(key);
+          return kvResult ?? CACHE_READ_ERROR;
+        }
+        // An abandoned slow match (timedOut) keeps the fail-open latency-budget
+        // policy: degrade to L2/KV, and a KV null stays a miss.
         if (this.debug)
           this.emitDebug({
             op: "get",
             key,
-            // A match REJECTION (matchError) is distinct from a genuine absence:
-            // surface it as match-error so debug agrees with the cache-read
-            // already routed to onError, instead of masquerading as l1-miss.
-            outcome: matchError
-              ? "match-error"
-              : timedOut
-                ? "match-timeout"
-                : "l1-miss",
+            outcome: timedOut ? "match-timeout" : "l1-miss",
             matchMs,
           });
         return this.kvGetSegment(key);
@@ -1096,7 +1121,9 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       // emit is the separate wrangler-tail signal. Keep both observability paths.
       reportCacheError(error, "cache-read", "[CFCacheStore] get");
       if (this.debug) this.emitDebug({ op: "get", key, outcome: "error" });
-      return null;
+      // Distinct from a miss so the PPR replay composition renders uncached
+      // instead of substituting the seeded doc record (CACHE_READ_ERROR).
+      return CACHE_READ_ERROR;
     }
   }
 
@@ -1817,8 +1844,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           buildVersion: envelope.bv,
           initialTheme: envelope.i,
           snapshot: envelope.sn,
+          docKey: envelope.dk,
           handlerLiveHoles: envelope.lh,
           transitionWhen: envelope.tw,
+          navigationOnly: envelope.no,
           createdAt: envelope.c,
         },
         shouldRevalidate,
@@ -1905,8 +1934,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
             ta: taggedAt,
             i: entry.initialTheme,
             sn: entry.snapshot,
+            dk: entry.docKey,
             lh: entry.handlerLiveHoles,
             tw: entry.transitionWhen,
+            no: entry.navigationOnly,
           };
           await this.kv!.put(kvKey, JSON.stringify(envelope), {
             expirationTtl: retentionTtl,
@@ -2813,7 +2844,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   private async kvGetSegment(
     key: string,
     opts?: { suppressRevalidate?: boolean },
-  ): Promise<CacheGetResult | null> {
+  ): Promise<CacheGetResult | null | CacheReadError> {
     if (!this.kv) return null;
 
     try {
@@ -2882,7 +2913,15 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     } catch (error) {
       reportCacheError(error, "cache-read", "[CFCacheStore] kvGetSegment");
       if (this.debug) this.emitDebug({ op: "get", key, outcome: "error" });
-      return null;
+      // A KV failure is NOT proof of absence: returning null classified it a
+      // real miss and let the PPR seeded fallback substitute the doc record
+      // for a key partition the store could not actually read. Same sentinel
+      // as get()'s own catch — lookupRouteDetailed classifies it `error` and
+      // the render stays uncached. (A kvGetOrEvict TIMEOUT above stays null
+      // by design: it is a bounded-latency degrade of a likely-healthy read,
+      // and serving the equivalent seeded record there is the fallback
+      // working as intended, not a masked failure.)
+      return CACHE_READ_ERROR;
     }
   }
 

package/src/cache/document-cache.ts

@@ -327,7 +327,13 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       // existing keys and double any host they already include).
       const cacheKey = keyGenerator
         ? keyGenerator(url) + segmentHash + typeSuffix
-        : cacheKeyBase(url.host, url.pathname, url.searchParams) +
+        : cacheKeyBase(
+            url.host,
+            url.pathname,
+            url.searchParams,
+            undefined,
+            requestCtx?._searchParamsFilter,
+          ) +
           segmentHash +
           typeSuffix;
       // 1. Check cache

package/src/cache/index.ts

@@ -7,7 +7,9 @@ export type {
   ShellCacheEntry,
   SerializedSegmentData,
   SegmentHandleData,
+  CacheReadError,
 } from "./types.js";
+export { CACHE_READ_ERROR } from "./types.js";
 
 export { MemorySegmentCacheStore } from "./memory-segment-store.js";
 
@@ -39,6 +41,11 @@ export {
   VERCEL_MAX_TAG_BYTES,
 } from "./vercel/index.js";
 
+export {
+  TRACKING_SEARCH_PARAMS,
+  type CacheSearchParams,
+} from "./search-params-filter.js";
+
 export { CacheScope, createCacheScope } from "./cache-scope.js";
 
 export {