@rangojs/router 0.4.0 → 0.4.1

package/README.md

@@ -13,7 +13,25 @@ the end. For the design rationale behind these APIs, read
 [Why Rango](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/why-rango.md); this page shows how it feels, that page
 argues why it's right.
 
-## Install
+## Start a new app
+
+The recommended path is to scaffold a complete app with
+[`create-rango`](https://github.com/rangojs/templates):
+
+```bash
+pnpm create rango my-app
+```
+
+Select a deployment target with `--template basic`, `--template cloudflare`, or
+`--template vercel`. The templates include streaming RSC, typed routes, Server
+Actions, Tailwind CSS, and production deployment configuration. For a plain
+JavaScript Node app, add `--template basic --js`. With npm, run
+`npm create rango@latest my-app`. The scaffolder currently requires Node.js 24
+or newer.
+
+## Install manually
+
+If you are adding Rango to an existing Vite RSC project:
 
 ```bash
 npm install @rangojs/router@experimental react @vitejs/plugin-rsc

package/dist/types/browser/event-controller.d.ts

@@ -205,6 +205,9 @@ export interface EventController {
     /** Whether any concurrent actions have occurred (shared across all handles) */
     hadAnyConcurrentActions(): boolean;
 }
+type LocationChangeController = Pick<EventController, "getState" | "subscribe">;
+/** Share one controller subscription across all location-change consumers. */
+export declare function subscribeToLocationChange(eventController: LocationChangeController, listener: (href: string) => void): () => void;
 export interface EventControllerConfig {
     initialLocation?: NavigationLocation;
 }
@@ -219,3 +222,4 @@ export interface EventControllerConfig {
  * Actions use mergeMap semantics (all run concurrently, consolidate at end).
  */
 export declare function createEventController(config?: EventControllerConfig): EventController;
+export {};

package/dist/types/browser/link-interceptor.d.ts

@@ -1,9 +1,8 @@
 import type { LinkInterceptorOptions, NavigateOptions } from "./types.js";
-/**
- * Check if an anchor points to the same page with only a hash change.
- * Used by both Link component and link-interceptor to let the browser
- * handle anchor scrolling natively.
- */
+import { type EventController } from "./event-controller.js";
+import type { PrefetchStrategy } from "../router/prefetch-default.js";
+type PrefetchScopeChangeListener = () => void;
+export declare function subscribeToPrefetchScopeChange(element: HTMLAnchorElement, listener: PrefetchScopeChangeListener): () => void;
 export declare function isHashOnlyNavigation(anchor: HTMLAnchorElement): boolean;
 /**
  * Default link interception predicate
@@ -19,11 +18,12 @@ export declare function isHashOnlyNavigation(anchor: HTMLAnchorElement): boolean
  * @returns true if the link should be intercepted
  */
 export declare function defaultShouldIntercept(link: HTMLAnchorElement): boolean;
+export declare function isPrefetchScopeDisabled(element: Element): boolean;
 /**
  * Set up link interception for SPA navigation
  *
- * Attaches a global click handler to intercept clicks on anchor elements
- * and call the onNavigate callback instead of performing a full page load.
+ * Attaches a global click handler to intercept clicks on anchor elements and
+ * call the onNavigate callback instead of performing a full page load.
  *
  * @param onNavigate - Callback when a link should navigate via SPA
  * @param options - Configuration options
@@ -41,3 +41,13 @@ export declare function defaultShouldIntercept(link: HTMLAnchorElement): boolean
  * ```
  */
 export declare function setupLinkInterception(onNavigate: (url: string, options?: NavigateOptions) => void, options?: LinkInterceptorOptions): () => void;
+export type DelegatedPrefetchCallback = (url: string, priority: "direct" | "queued") => void | (() => void);
+export interface DelegatedPrefetchOptions {
+    eventController: Pick<EventController, "getState" | "subscribe">;
+    shouldPrefetch?: (link: HTMLAnchorElement) => boolean;
+    defaultPrefetch?: PrefetchStrategy;
+    root?: HTMLElement;
+    basename?: string;
+}
+export declare function setupDelegatedLinkPrefetch(onPrefetch: DelegatedPrefetchCallback, options: DelegatedPrefetchOptions): () => void;
+export {};

package/dist/types/browser/navigation-bridge.d.ts

@@ -1,6 +1,7 @@
-import type { NavigationBridge, NavigationBridgeConfig } from "./types.js";
+import type { NavigationBridge, NavigationBridgeConfig, NavigationStore } from "./types.js";
 import { createNavigationTransaction } from "./navigation-transaction.js";
 import type { EventController } from "./event-controller.js";
+import type { PrefetchStrategy } from "../router/prefetch-default.js";
 export { createNavigationTransaction };
 /**
  * Extended configuration for navigation bridge with event controller
@@ -9,7 +10,18 @@ export interface NavigationBridgeConfigWithController extends NavigationBridgeCo
     eventController: EventController;
     /** RSC version from initial payload metadata. */
     version?: string;
+    /** Server-resolved default used by both Links and delegated anchors. */
+    defaultPrefetch?: PrefetchStrategy;
+    /** Canonical router basename used to scope delegated anchor prefetch. */
+    basename?: string;
 }
+export interface NavigationBridgeDelegatedPrefetchOptions {
+    defaultPrefetch?: PrefetchStrategy;
+    root?: HTMLElement;
+    basename?: string;
+}
+/** Register delegated anchor prefetch with the production bridge wiring. */
+export declare function setupNavigationBridgeDelegatedPrefetch(store: NavigationStore, eventController: EventController, getVersion: () => string | undefined, options?: NavigationBridgeDelegatedPrefetchOptions): () => void;
 /**
  * Create a navigation bridge for handling client-side navigation
  *

package/dist/types/browser/notify-listeners.d.ts

@@ -0,0 +1,2 @@
+/** Notify every active listener and surface every callback failure. */
+export declare function notifyListeners<T>(entries: Iterable<T>, notify: (entry: T) => void, isActive?: (entry: T) => boolean, shouldContinue?: () => boolean): void;

package/dist/types/browser/prefetch/cache.d.ts

@@ -180,4 +180,4 @@ export declare function setInflightPromise(key: string, promise: Promise<Decoded
  */
 export declare function setInflightPromiseWithAliases(keys: string[], promise: Promise<DecodedPrefetch | null>): void;
 export declare function clearPrefetchInflight(key: string): void;
-export declare function clearPrefetchCache(): void;
+export declare function clearPrefetchCache(rotateRangoState?: boolean): void;

package/dist/types/browser/prefetch/default-strategy.d.ts

@@ -1,11 +1,14 @@
 /**
- * Router-wide default Link prefetch strategy (client seat).
+ * Router-wide default prefetch strategy (client seat).
  *
  * The server resolves `createRouter({ defaultPrefetch })` once at router init
  * (router/prefetch-default.ts) and ships it in initial payload metadata; the
  * browser entry applies it here before hydration — same lifecycle as
  * `initPrefetchCache` / `setPrefetchConcurrency`. Every `<Link>` without an
- * explicit `prefetch` prop reads the value at render time.
+ * explicit `prefetch` prop and every eligible intercepted plain anchor that has
+ * not opted out with `data-prefetch="false"` or `data-prefetch="none"` uses it.
+ * Containers use the same `false`/`none` vocabulary via
+ * `data-prefetch-scope`.
  *
  * The module initial value must equal the server resolver's environment default:
  * `"none"` in development and `"viewport"` in production. During SSR this
@@ -13,10 +16,16 @@
  * gives metadata-less payloads the documented behavior.
  */
 import type { PrefetchStrategy } from "../../router/prefetch-default.js";
+/** Reset module state between tests that replace browser media globals. */
+export declare function resetAdaptiveStrategyForTesting(): void;
 /**
  * Apply the server-resolved default strategy. Called once at browser app init
  * from payload metadata; also used by tests to reset state.
  */
 export declare function setDefaultPrefetchStrategy(strategy: PrefetchStrategy): void;
-/** Current default strategy for Links without an explicit `prefetch` prop. */
+/** Current default strategy for Links and delegated plain anchors. */
 export declare function getDefaultPrefetchStrategy(): PrefetchStrategy;
+/** Resolve adaptive to the strategy for the current input capability. */
+export declare function resolveAdaptiveStrategy(strategy: PrefetchStrategy): PrefetchStrategy;
+/** Subscribe to changes in the input capability used by adaptive prefetch. */
+export declare function subscribeToAdaptiveStrategyChange(listener: () => void): () => void;

package/dist/types/browser/prefetch/invalidation.d.ts

@@ -0,0 +1,6 @@
+type PrefetchCacheInvalidationListener = () => void;
+/** Subscribe to completed local prefetch-cache invalidations. */
+export declare function subscribeToPrefetchCacheInvalidation(listener: PrefetchCacheInvalidationListener): () => void;
+/** Notify the registrations that existed when the cache was invalidated. */
+export declare function notifyPrefetchCacheInvalidated(): void;
+export {};

package/dist/types/browser/prefetch/loader.d.ts

@@ -1,10 +1,12 @@
 import type { RscPayload } from "../types.js";
+import type { EventController } from "../event-controller.js";
 type PrefetchDecoder = (response: Promise<Response>) => Promise<RscPayload>;
 export declare function setPrefetchDecoder(fn: PrefetchDecoder): void;
 export declare function setPrefetchConcurrency(value: number): void;
 export declare function prefetchDirect(url: string, segmentIds: string[], version?: string, routerId?: string, prefetchKey?: ":source"): void;
 export declare function prefetchQueued(url: string, segmentIds: string[], version?: string, routerId?: string, prefetchKey?: ":source"): void;
-export declare function observeForPrefetch(element: Element, callback: () => void): () => void;
+/** Run speculative work only when no navigation or stream is active. */
+export declare function schedulePrefetchWhenRouterIdle(eventController: Pick<EventController, "getState" | "subscribe">, callback: () => void): (() => void) | undefined;
 export declare function cancelAllPrefetches(keepUrl?: string | null): void;
 export declare function abortAllPrefetches(): void;
 export {};

package/dist/types/browser/prefetch/observer.d.ts

@@ -12,16 +12,13 @@
  * scrolls in and out repeatedly.
  */
 type PrefetchCallback = () => void;
+/** Reset module state between tests that replace browser observer globals. */
+export declare function resetPrefetchObserverForTesting(): void;
 /**
  * Observe an element for viewport intersection.
  * When the element becomes visible (within 200px margin), the callback fires
  * and the element is automatically unobserved.
  * No-op in environments without IntersectionObserver (SSR, some test runners).
  */
-export declare function observeForPrefetch(element: Element, onVisible: PrefetchCallback): void;
-/**
- * Stop observing an element. Used for cleanup when a Link unmounts
- * before entering the viewport.
- */
-export declare function unobserveForPrefetch(element: Element): void;
+export declare function observeForPrefetch(element: Element, onVisible: PrefetchCallback): () => void;
 export {};

package/dist/types/browser/rango-state.d.ts

@@ -29,6 +29,8 @@
  * (invalidateRangoState) update the mirror synchronously and never fire it.
  */
 export declare function setRangoStateObserver(observer: ((value: string) => void) | null): void;
+/** Return the resolved cookie name used to namespace cross-tab messages. */
+export declare function getRangoStateCookieName(): string;
 /**
  * Initialize the Rango state cookie at app startup. `version` is the build
  * version; `stateCookieName` is the server-resolved cookie name from payload
@@ -50,3 +52,5 @@ export declare function getRangoState(): string;
  * the external-rotation observer is NOT triggered by our own write.
  */
 export declare function invalidateRangoState(): void;
+/** Adopt the state carried by a same-origin cache-invalidation broadcast. */
+export declare function adoptRangoState(value: string): boolean;

package/dist/types/browser/react/Link.d.ts

@@ -10,14 +10,7 @@ export type StateOrGetter<T = unknown> = T | (() => T);
 export type LinkState = LocationStateEntry[] | StateOrGetter<Record<string, unknown>>;
 import type { PrefetchStrategy } from "../../router/prefetch-default.js";
 export type { PrefetchStrategy } from "../../router/prefetch-default.js";
-/**
- * Resolve a prefetch strategy, expanding "adaptive" to the concrete strategy
- * for the CURRENT input capability: "viewport" on touch (no-hover) devices,
- * "hover" on pointer devices. Non-adaptive strategies pass through unchanged.
- * Reads touch capability live (not a module-load snapshot) so the result
- * tracks input-capability changes.
- */
-export declare function resolveAdaptiveStrategy(prefetch: PrefetchStrategy): PrefetchStrategy;
+export { resolveAdaptiveStrategy } from "../prefetch/default-strategy.js";
 /**
  * Link component props
  */
@@ -52,7 +45,9 @@ export interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorEle
      * Prefetch strategy for the link destination. When omitted, falls back to
      * the router-wide default (`createRouter({ defaultPrefetch })`: `"none"` in
      * development, `"viewport"` in production). An explicit value always wins
-     * over the router default, including `"none"` to opt a single Link out.
+     * over the router default, including `"none"` to opt a single Link out. An
+     * ancestor with `data-prefetch-scope="false"` or `"none"` remains a hard
+     * subtree opt-out.
      *
      * @default the router's environment-aware `defaultPrefetch`
      */

package/dist/types/browser/react/context.d.ts

@@ -1,6 +1,7 @@
 import { type Context } from "react";
 import type { NavigationStore, NavigateOptions } from "../types.js";
 import type { EventController } from "../event-controller.js";
+import type { PrefetchStrategy } from "../../router/prefetch-default.js";
 /**
  * Navigation context value provided by NavigationProvider
  *
@@ -44,6 +45,8 @@ export interface NavigationStoreContextValue {
      * Used by Link and useRouter() to auto-prefix app-local paths.
      */
     basename: string | undefined;
+    /** Router default from this instance's initial payload. */
+    defaultPrefetch?: PrefetchStrategy;
 }
 /**
  * React context for navigation store

package/dist/types/browser/rsc-router.d.ts

@@ -26,8 +26,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.
@@ -79,6 +82,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;
     /**

package/dist/types/browser/types.d.ts

@@ -499,6 +499,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/dist/types/cache/cache-key-utils.d.ts

@@ -5,13 +5,21 @@
  * for cache key generation. Used by cache-runtime, cache-scope,
  * document-cache, and loader-cache.
  */
+import type { SearchParamsFilter } from "./search-params-filter.js";
 /**
  * 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 declare function sortedSearchString(searchParams: URLSearchParams): string;
+export declare function sortedSearchString(searchParams: URLSearchParams, filter?: SearchParamsFilter): string;
 /**
  * Build a sorted, deterministic string from route params.
  *
@@ -32,4 +40,4 @@ export declare function sortedRouteParams(params: Record<string, string> | undef
  * invalidates every persisted cache entry on upgrade. Callers append their own
  * tier-specific suffixes (`:rsc`/`:html`, segment hash) after this base.
  */
-export declare function cacheKeyBase(host: string, pathname: string, searchParams?: URLSearchParams, params?: Record<string, string>): string;
+export declare function cacheKeyBase(host: string, pathname: string, searchParams?: URLSearchParams, params?: Record<string, string>, filter?: SearchParamsFilter): string;

package/dist/types/cache/cache-scope.d.ts

@@ -12,6 +12,19 @@ import type { ResolvedSegment } from "../types.js";
 import type { SegmentCacheStore } from "./types.js";
 import type { RequestContext } from "../server/request-context.js";
 export declare function resolveCacheTags(config: PartialCacheOptions | false, ctx: RequestContext | undefined): string[] | undefined;
+/**
+ * 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.
  *
@@ -68,11 +81,44 @@ export declare class CacheScope {
      * @internal
      */
     private resolveKey;
+    /**
+     * @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;
+    /**
+     * @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;
     /**
      * 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;
     private conditionAllows;
     /**
      * Lookup cached segments for a route (single cache entry per request).
@@ -86,6 +132,25 @@ export declare class CacheScope {
         segments: ResolvedSegment[];
         shouldRevalidate: boolean;
     } | 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.
+     */
+    lookupRouteDetailed(pathname: string, params: Record<string, string>, isIntercept?: boolean): Promise<CacheRouteLookupOutcome>;
     /**
      * Record this scope's segment-DSL cache({ tags }) into the request tag union
      * synchronously, under the same gate cacheRoute() uses for a write.
@@ -119,6 +184,17 @@ export declare class CacheScope {
 export declare function createCacheScope(config: {
     options: PartialCacheOptions | false;
 } | undefined, parent?: CacheScope | null): CacheScope | null;
+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 declare function createShellImplicitDocScope(marker: ShellImplicitCacheMarker): CacheScope;
 /**
  * Shell fast path: when the route tree derived NO cache scope and the current
  * request context carries the `_shellImplicitCache` marker (a shell capture,
@@ -129,8 +205,11 @@ export declare function createCacheScope(config: {
  * (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 declare function resolveShellImplicitCacheScope(scope: CacheScope | null): CacheScope | null;
+export {};

package/dist/types/cache/cf/cf-cache-store.d.ts

@@ -22,7 +22,7 @@ declare global {
  * - Non-blocking writes via waitUntil
  * - KV L2 for cross-colo cache persistence
  */
-import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry } from "../types.js";
+import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, CacheReadError } from "../types.js";
 import { type RequestContext } from "../../server/request-context.js";
 import { CACHE_STALE_AT_HEADER, CACHE_STATUS_HEADER, CACHE_TAGS_HEADER, CACHE_TAGGED_AT_HEADER, TAG_MARKER_PREFIX, CACHE_REVALIDATING_AT_HEADER, MAX_REVALIDATION_INTERVAL, EDGE_LOOKUP_TIMEOUT_MS, EDGE_READ_TIMEOUT_MS, KV_READ_TIMEOUT_MS } from "./cf-cache-constants.js";
 export { CACHE_STALE_AT_HEADER, CACHE_STATUS_HEADER, CACHE_TAGS_HEADER, CACHE_TAGGED_AT_HEADER, TAG_MARKER_PREFIX, CACHE_REVALIDATING_AT_HEADER, MAX_REVALIDATION_INTERVAL, EDGE_LOOKUP_TIMEOUT_MS, EDGE_READ_TIMEOUT_MS, KV_READ_TIMEOUT_MS, };
@@ -209,7 +209,7 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * On L1 miss, falls back to KV (L2) if configured.
      * KV hits are promoted to L1 in the background.
      */
-    get(key: string): Promise<CacheGetResult | null>;
+    get(key: string): Promise<CacheGetResult | null | CacheReadError>;
     /**
      * Store entry data with TTL and optional SWR window.
      * Uses waitUntil for non-blocking write when available.

package/dist/types/cache/index.d.ts

@@ -1,7 +1,9 @@
-export type { SegmentCacheStore, CachedEntryData, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, SerializedSegmentData, SegmentHandleData, } from "./types.js";
+export type { SegmentCacheStore, CachedEntryData, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, SerializedSegmentData, SegmentHandleData, CacheReadError, } from "./types.js";
+export { CACHE_READ_ERROR } from "./types.js";
 export { MemorySegmentCacheStore } from "./memory-segment-store.js";
 export { CFCacheStore, type CFCacheStoreOptions, type CFCacheDebug, type CFCacheReadDebugEvent, type KVNamespace, CACHE_STALE_AT_HEADER, CACHE_STATUS_HEADER, CACHE_REVALIDATING_AT_HEADER, EDGE_LOOKUP_TIMEOUT_MS, EDGE_READ_TIMEOUT_MS, KV_READ_TIMEOUT_MS, createCloudflareZonePurge, type CloudflareZonePurgeOptions, } from "./cf/index.js";
 export { VercelCacheStore, type VercelCacheStoreOptions, type VercelRuntimeCache, type VercelCacheDebug, type VercelCacheReadDebugEvent, type VercelCacheReadOutcome, VERCEL_MAX_ITEM_BYTES, VERCEL_MAX_TAGS_PER_ITEM, 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 { createDocumentCacheMiddleware, type DocumentCacheOptions, } from "./document-cache.js";
 export type { CacheErrorCategory } from "./cache-error.js";

package/dist/types/cache/search-params-filter.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Global search-param cache-key filtering (`cache.searchParams` on the
+ * handler/createRouter cache config).
+ *
+ * Controls WHICH query params participate in default cache-key generation
+ * across every tier that keys by URL (segment, document, response, PPR shell,
+ * "use cache" ctx normalization, prerendered-shell manifest matching). The
+ * filter affects cache keys ONLY -- `ctx.searchParams` and the request URL are
+ * untouched, handlers and loaders still see the full query string.
+ *
+ * Design doc: docs/design/caching.md ("Search param filtering").
+ *
+ * The footgun this must not soften: 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 (the classic CDN cache-key mistake). The
+ * default therefore stays "all" -- correct by default, opt into collapsing.
+ */
+/**
+ * `cache.searchParams` config value.
+ *
+ * - `"all"` (default) -- every non-reserved param keys the cache (today's
+ *   behavior; reserved = the router's own `_rsc*` / `__` allowlist params,
+ *   see cache-key-utils.ts).
+ * - `"none"` -- query params never key the cache.
+ * - `{ include }` -- allowlist: only the named params key the cache.
+ * - `{ exclude }` -- denylist: every param except the named ones keys the cache.
+ *
+ * Names match exactly, plus a `*` SUFFIX wildcard (`"utm_*"` matches every
+ * param starting with `utm_`). No RegExp: keeps the config serializable and
+ * deterministic. `include` + `exclude` together is unrepresentable -- the
+ * union forces exactly one mode.
+ */
+export type CacheSearchParams = "all" | "none" | {
+    include: readonly string[];
+    exclude?: never;
+} | {
+    exclude: readonly string[];
+    include?: never;
+};
+/**
+ * Compiled form of a `CacheSearchParams` config: returns true when the param
+ * name should participate in the cache key. `undefined` means "no filter"
+ * ("all") so the unfiltered path stays byte-identical to the pre-feature key
+ * format (cacheKeyBase output is byte-stable by contract).
+ */
+export type SearchParamsFilter = (name: string) => boolean;
+/**
+ * Well-known tracking/click-id params that fragment caches without changing
+ * rendered output for (almost) every app. Exported so the common case is one
+ * line: `searchParams: { exclude: TRACKING_SEARCH_PARAMS }`.
+ *
+ * Sources: Google (gclid/gclsrc/dclid/gbraid/wbraid + utm_*), Meta (fbclid),
+ * Microsoft (msclkid), TikTok (ttclid), Twitter/X (twclid), LinkedIn
+ * (li_fat_id), Mailchimp (mc_cid/mc_eid), Instagram (igshid), Yandex (yclid),
+ * HubSpot (_hsenc/_hsmi).
+ */
+export declare const TRACKING_SEARCH_PARAMS: readonly string[];
+/**
+ * Compile a `cache.searchParams` config into a predicate, once per resolved
+ * cache config (handler.ts). Returns `undefined` for the default ("all") so
+ * every call site can cheaply skip filtering and keep the shipped key format
+ * byte-stable.
+ */
+export declare function compileSearchParamsFilter(config: CacheSearchParams | undefined): SearchParamsFilter | undefined;

package/dist/types/cache/shell-snapshot.d.ts

@@ -22,7 +22,7 @@
  * the capture render performed; replaying them on a HIT reproduces the shell
  * content byte-identically; everything not recorded stays live.
  */
-import type { SegmentCacheStore, CacheGetResult, CacheItemResult, CacheItemOptions, CachedEntryData, ShellCacheEntry, ShellSnapshotRecord } from "./types.js";
+import type { SegmentCacheStore, CacheGetResult, CacheItemResult, CacheItemOptions, CachedEntryData, ShellCacheEntry, ShellSnapshotRecord, CacheReadError } from "./types.js";
 /**
  * A store wrapper the CAPTURE render reads through. Every call passes through to
  * the underlying store unchanged; for the item/segment/response families it also
@@ -73,7 +73,7 @@ export declare class RecordingShellStore<TEnv = unknown> implements SegmentCache
     settleWrites(timeoutMs: number): Promise<void>;
     /** The recorded snapshot (last-write-wins per family+key), or undefined if empty. */
     drainSnapshot(): ShellSnapshotRecord[] | undefined;
-    get(key: string): Promise<CacheGetResult | null>;
+    get(key: string): Promise<CacheGetResult | null | CacheReadError>;
     set(key: string, data: CachedEntryData, ttl: number, swr?: number): Promise<void>;
     delete(key: string): Promise<boolean>;
     clear(): Promise<void>;
@@ -109,7 +109,7 @@ export declare class SnapshotOnlySegmentStore<TEnv = unknown> implements Segment
     constructor(recording: RecordingShellStore<TEnv>);
     get defaults(): SegmentCacheStore<TEnv>["defaults"];
     get keyGenerator(): SegmentCacheStore<TEnv>["keyGenerator"];
-    get(key: string): Promise<CacheGetResult | null>;
+    get(key: string): Promise<CacheGetResult | null | CacheReadError>;
     set(key: string, data: CachedEntryData): Promise<void>;
     delete(key: string): Promise<boolean>;
 }
@@ -164,7 +164,7 @@ export declare class SeededShellStore<TEnv = unknown> implements SegmentCacheSto
     get defaults(): SegmentCacheStore<TEnv>["defaults"];
     get keyGenerator(): SegmentCacheStore<TEnv>["keyGenerator"];
     get supportsPassiveShellReads(): true | undefined;
-    get(key: string): Promise<CacheGetResult | null>;
+    get(key: string): Promise<CacheGetResult | null | CacheReadError>;
     set(key: string, data: CachedEntryData, ttl: number, swr?: number): Promise<void>;
     delete(key: string): Promise<boolean>;
     clear(): Promise<void>;

package/dist/types/cache/types.d.ts

@@ -10,6 +10,19 @@
  */
 import type { ResolvedSegment } from "../types.js";
 import type { RequestContext } from "../server/request-context.js";
+/**
+ * Sentinel a `SegmentCacheStore.get` MAY return instead of `null` when the
+ * read FAILED (backend error) rather than genuinely missing. For the render
+ * outcome the two are identical — render fresh, re-cache — so hit/miss-only
+ * consumers can treat it as a miss. The PPR replay composition needs the
+ * distinction: an errored explicit-tier read must render uncached
+ * (`lookupRouteDetailed` classifies it `error`), never be substituted by the
+ * seeded doc record — the built-in stores swallow backend errors internally,
+ * so without this signal their failures read as replayable misses. Third-party
+ * stores returning plain `null` on error keep the miss classification.
+ */
+export declare const CACHE_READ_ERROR: unique symbol;
+export type CacheReadError = typeof CACHE_READ_ERROR;
 /**
  * Result from cache get() including data and revalidation status
  */
@@ -81,9 +94,10 @@ export interface SegmentCacheStore<TEnv = unknown> {
     readonly keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
     /**
      * Get cached entry data by key
-     * @returns Cache result with data and staleness, or null if not found/expired
+     * @returns Cache result with data and staleness, null if not found/expired,
+     * or CACHE_READ_ERROR when the read failed (optional — see the sentinel).
      */
-    get(key: string): Promise<CacheGetResult | null>;
+    get(key: string): Promise<CacheGetResult | null | CacheReadError>;
     /**
      * Store entry data with TTL
      * @param key - Cache key
@@ -265,6 +279,20 @@ export interface ShellCacheEntry {
      * heals it. See docs/design/ppr-shell-resume.md ("the capture data snapshot").
      */
     snapshot?: ShellSnapshotRecord[];
+    /**
+     * The key of the CANONICAL document segment record inside `snapshot` — the
+     * one navigation replay can actually consume (resolved under the implicit
+     * doc namespace at capture; see CacheScope.cacheRoute). Replay eligibility
+     * requires this exact record: the snapshot also carries incidentally
+     * recorded explicit-tier records (RecordingShellStore passthroughs) whose
+     * keys a partial lookup can never resolve, and counting those declared
+     * entries "replayable" that always missed (`snapshot-miss` flip-flop).
+     * Absent on entries captured before the field existed OR when the capture
+     * recorded no doc record (cache(false)/condition-false routes, prerender
+     * short-circuit) — both read as `no-segment-snapshot`; recapture heals the
+     * former.
+     */
+    docKey?: string;
     /**
      * The entry was captured from a partial request only to produce an eligible
      * segment snapshot. Document serving must treat its HTML prelude as a miss;