@rangojs/router 0.2.0 → 0.4.1

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,26 @@ 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;
+     * the partial request's headers and middleware state are not document state.
+     */
+    navigationOnly?: true;
     /**
      * True when the capture's HANDLER layer declared per-request liveness: a
      * handle pushed OUTSIDE a DSL loader scope carried a nested thenable (the

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

@@ -30,7 +30,7 @@
  * `getCache(...)` result, which satisfies the shape structurally. That keeps the
  * router free of a hard Vercel dependency.
  */
-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";
 /**
  * Minimal structural shape of the Vercel Runtime Cache returned by `getCache()`
@@ -194,7 +194,7 @@ export declare class VercelCacheStore<TEnv = unknown> implements SegmentCacheSto
     private readonly name?;
     private readonly debug?;
     constructor(options: VercelCacheStoreOptions<TEnv>);
-    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>;
     getResponse(key: string): Promise<{

package/dist/types/index.d.ts

@@ -13,6 +13,7 @@ export { RouteNotFoundError, DataNotFoundError, notFound, MiddlewareError, Handl
 export type { DocumentProps, DefaultEnv, RouteDefinition, RouteConfig, RouteDefinitionOptions, TrailingSlashMode, Handler, // Supports params object, path pattern, or route name
 HandlerContext, ExtractParams, GenericParams, Middleware, RevalidateParams, Revalidate, ActionRef, RouteKeys, LoaderDefinition, LoaderFn, LoaderContext, FetchableLoaderOptions, LoadOptions, ErrorInfo, ErrorBoundaryFallbackProps, ErrorBoundaryHandler, ClientErrorBoundaryFallbackProps, NotFoundInfo, NotFoundBoundaryFallbackProps, NotFoundBoundaryHandler, ErrorPhase, OnErrorContext, OnErrorCallback, } from "./types.js";
 export type { SearchSchema, SearchSchemaValue, ResolveSearchSchema, RouteSearchParams, RouteParams, } from "./search-params.js";
+export { TRACKING_SEARCH_PARAMS, type CacheSearchParams, } from "./cache/search-params-filter.js";
 export { createLoader } from "./loader.js";
 export type { RouteHelpers, RouteHandlers } from "./route-definition.js";
 export type { TransitionConfig, TransitionWhenFn, TransitionWhenContext, ViewTransitionClass, } from "./types.js";

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

@@ -24,6 +24,7 @@ export { Static, type StaticHandlerDefinition, type StaticHandlerOptions, } from
 export { urls, type PathHelpers, type PathOptions, type PartialPrerenderProps, type UrlPatterns, type IncludeOptions, type IncludeItem, type RouteResponse, type ProblemDetails, type ResponseHandler, type ResponseHandlerContext, type JsonResponseHandler, type TextResponseHandler, type JsonValue, type ResponsePathFn, type JsonResponsePathFn, type TextResponsePathFn, } from "./urls.js";
 export { createRouter, type Rango, type RootLayoutProps, type RouterRequestInput, } from "./router.js";
 export type { HandlerCacheConfig } from "./rsc/types.js";
+export { TRACKING_SEARCH_PARAMS, type CacheSearchParams, } from "./cache/search-params-filter.js";
 export { Meta } from "./handles/meta.js";
 export { Script, type ScriptConfig, type ScriptAttributes, } from "./handles/script.js";
 export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";

package/dist/types/router/match-middleware/cache-lookup.d.ts

@@ -92,7 +92,20 @@
  *   - 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";
+/**
+ * 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 declare function prerenderEntryExists(routeKey: string | undefined, params: Record<string, string>, pathname: string, entries: EntryData[]): Promise<boolean>;
 /**
  * Async generator middleware type
  */

package/dist/types/router/navigation-snapshot.d.ts

@@ -18,5 +18,34 @@ export interface NavigationSnapshot {
 export interface ResolveNavigationDeps {
     findMatch: (pathname: string) => 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 declare function getNavigationContextHeader(request: Request): string | null;
+/**
+ * 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 declare function prerenderStoreShortCircuits(pr: true | undefined, request: Request): boolean;
+/**
+ * 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 declare function getInterceptSourceHeader(request: Request): string | null;
 export declare function resolveNavigation(request: Request, url: URL, currentRouteKey: string, deps: ResolveNavigationDeps): Promise<NavigationSnapshot | null>;
 export declare function createNavigationSnapshot(overrides?: Partial<NavigationSnapshot>): NavigationSnapshot;

package/dist/types/router/prefetch-default.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Resolve the router-wide default Link prefetch strategy once, at router init.
+ * The resolved value ships to the client in payload metadata; the browser
+ * entry applies it via `setDefaultPrefetchStrategy` (browser/prefetch/
+ * default-strategy.ts) and every `<Link>` without an explicit `prefetch` prop
+ * falls back to it.
+ *
+ * The type lives HERE (not in browser/react/Link.tsx) because both seats need
+ * it: this server-side resolver and the client Link/default-strategy modules.
+ * Link.tsx re-exports it so the public `PrefetchStrategy` export path is
+ * unchanged.
+ *
+ * Policy note: automatic prefetch stays quiet in development, matching the
+ * production-only default used by Next.js. Explicit router and per-Link
+ * strategies still work in every mode. Invalid untyped inputs fall back to the
+ * current environment's default.
+ */
+/**
+ * Prefetch strategy for the Link component
+ * - "hover": Prefetch on mouse enter (direct, no queue)
+ * - "viewport": Prefetch when link enters viewport (queued, waits for idle)
+ * - "render": Prefetch on component mount regardless of visibility (queued, waits for idle)
+ * - "adaptive": Hover on pointer devices, viewport on touch devices
+ * - "none": No prefetching
+ */
+export type PrefetchStrategy = "hover" | "viewport" | "render" | "adaptive" | "none";
+export declare const DEFAULT_PREFETCH_STRATEGY: PrefetchStrategy;
+export declare function resolveDefaultPrefetch(raw: PrefetchStrategy | undefined, nodeEnv?: string | undefined): PrefetchStrategy;

package/dist/types/router/router-interfaces.d.ts

@@ -249,6 +249,13 @@ export interface RangoInternal<TEnv = any, TRoutes extends Record<string, unknow
      * prefetchConcurrency.
      */
     readonly prefetchConcurrency: number;
+    /**
+     * Router-wide default Link prefetch strategy for Links without an explicit
+     * `prefetch` prop. Shipped to the client in payload metadata. Derived from
+     * the `defaultPrefetch` option (default "none" in development and
+     * "viewport" in production).
+     */
+    readonly defaultPrefetch: import("./prefetch-default.js").PrefetchStrategy;
     /**
      * Resolved rango state cookie name (`{prefix}_{routerId}`), composed once at
      * router init and shipped to the client in payload metadata. The server-side

package/dist/types/router/router-options.d.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, OnErrorCallback } from "../types";
 import type { NonceProvider } from "../rsc/types.js";
 import type { ShellCaptureDebug } from "../rsc/shell-capture.js";
@@ -7,6 +8,7 @@ import type { ExecutionContext } from "../server/request-context.js";
 import type { UrlPatterns } from "../urls.js";
 import type { UrlBuilder } from "../urls/pattern-types.js";
 import type { NamedRouteEntry } from "./content-negotiation.js";
+import type { PrefetchStrategy } from "./prefetch-default.js";
 import type { TelemetrySink } from "./telemetry.js";
 import type { RouterTracingConfig } from "./tracing.js";
 import type { RouterTimeouts, OnTimeoutCallback } from "./timeout.js";
@@ -282,13 +284,32 @@ 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;
+        searchParams?: CacheSearchParams;
     } | ((env: TEnv, ctx?: ExecutionContext) => {
         store: SegmentCacheStore;
         enabled?: boolean;
+        searchParams?: CacheSearchParams;
     });
     /**
      * Named cache profiles for "use cache" directive.
@@ -495,6 +516,39 @@ export interface RangoOptions<TEnv = any> {
      * @default 2
      */
     prefetchConcurrency?: number;
+    /**
+     * Default prefetch strategy for every `<Link>` that does not set its own
+     * `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
+     *   compete with hydration or an active navigation.
+     * - `"hover"`: prefetch on mouse enter only. Much lighter on the server —
+     *   only links the pointer approaches are fetched — at the cost of the
+     *   ~100-300ms head start viewport prefetch gives.
+     * - `"adaptive"`: `"hover"` on pointer devices, `"viewport"` on touch
+     *   devices (no hover to wait for).
+     * - `"render"`: prefetch on mount regardless of visibility.
+     * - `"none"`: manual mode — nothing prefetches unless a Link opts in.
+     *
+     * Automatic prefetch defaults to `"none"` in development and `"viewport"`
+     * in production. With the production default, every visible Link triggers an
+     * RSC render (loaders included) on the server. Routes served from cache/PPR
+     * absorb this cheaply; per-user dynamic routes pay full price per viewport
+     * entry. Set `"hover"`, `"adaptive"`, or `"none"` when that cost matters.
+     *
+     * To disable the prefetch subsystem entirely (including per-Link opt-ins
+     * and `useRouter().prefetch()`), set `prefetchCacheTTL: false` instead.
+     *
+     * @default "none" in development; "viewport" in production
+     */
+    defaultPrefetch?: PrefetchStrategy;
     /**
      * Prefix for the rango state cookie name. The resolved name is
      * `{prefix}_{routerId}`; the prefix is sanitized to cookie-name-safe

package/dist/types/rsc/capture-queue.d.ts

@@ -1,3 +1,9 @@
+/** Bound queued/running capture closures retained by one isolate. */
+export declare const MAX_ADMITTED_CAPTURES: number;
+/** The caller may drop this best-effort capture and retry on a later request. */
+export declare class CaptureQueueFullError extends Error {
+    constructor();
+}
 /**
  * Run `task` after every previously enqueued capture has settled. Returns a
  * promise for THIS task's completion (rejections propagate to the caller —

package/dist/types/rsc/shell-build-manifest.d.ts

@@ -25,6 +25,7 @@
  *   markers say whether it is still current.
  */
 import type { SegmentCacheStore, ShellCacheEntry } from "../cache/types.js";
+import type { SearchParamsFilter } from "../cache/search-params-filter.js";
 /** One baked manifest record (the __ps asset module's default export). */
 export interface BuildShellEntry {
     entry: ShellCacheEntry;
@@ -79,6 +80,11 @@ export interface DevShellLookup {
  * version validity, payload integrity, and tag-invalidation markers. Returns
  * null on any gate failure — the caller degrades to the ordinary MISS path
  * (axis 1 + runtime capture), never a broken serve.
+ *
+ * "Search-less" is evaluated AFTER the request's `cache.searchParams` filter:
+ * a URL whose only params are excluded ones (`?fbclid=…` under a tracking
+ * exclusion) matches the baked shell — ad-click traffic is exactly the
+ * traffic the shell was prerendered for.
  */
-export declare function lookupBuildShell(url: URL, buildVersion: string, store: SegmentCacheStore, dev?: DevShellLookup): Promise<BuildShellHit | null>;
+export declare function lookupBuildShell(url: URL, buildVersion: string, store: SegmentCacheStore, dev?: DevShellLookup, filter?: SearchParamsFilter): Promise<BuildShellHit | null>;
 export {};

package/dist/types/rsc/shell-capture.d.ts

@@ -124,10 +124,11 @@ 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
      */
-    outcome: "stored" | "redirect" | "no-shell" | "refused" | "error" | "skip-in-flight" | "skip-backoff" | "backoff";
+    outcome: "stored" | "redirect" | "no-shell" | "refused" | "error" | "skip-in-flight" | "skip-backoff" | "skip-capacity" | "backoff";
     /** Attempt number (1 = first, 2 = in-place retry). Absent on skips. */
     attempt?: number;
     /** Wall-clock ms of the whole attempt (barrier + render + drain + put). */
@@ -148,6 +149,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. */
@@ -280,6 +283,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;
 }
 /**
  * Schedule the background shell capture for a served document. Stampede-guarded:
@@ -288,11 +293,11 @@ 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 declare function scheduleShellCapture(ctx: HandlerContext<any>, request: Request, env: any, url: URL, reqCtx: RequestContext<any>, ssrModule: SSRModule, descriptor: ShellCaptureDescriptor): void;
+export declare function scheduleShellCapture(ctx: HandlerContext<any>, request: Request, env: any, url: URL, reqCtx: RequestContext<any>, ssrModule: SSRModule | ((request: Request, url: URL) => Promise<SSRModule | null>), descriptor: ShellCaptureDescriptor): void;
 /**
  * The outcome of one capture attempt.
  * - `stored`: a usable shell was captured (and a putShell was attempted; a store
@@ -310,7 +315,7 @@ type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused";
  * bag, not a return value: captureAndStoreShell's outcome type stays a string
  * union its existing callers (producer B, tests) consume unchanged.
  */
-type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "writeSettleMs" | "preludeBytes" | "snapshotBytes" | "snapshotSkipped" | "storeWrite">;
+type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "writeSettleMs" | "preludeBytes" | "snapshotBytes" | "snapshotSkipped" | "untaggedBake" | "storeWrite">;
 /**
  * Run the shell capture with a single in-place retry, then store the result.
  *
@@ -351,7 +356,10 @@ export interface CaptureContextDerivation {
  * createRequestContext over the build env, with a fresh MemorySegmentCacheStore
  * as `_cacheStore` so the recording/snapshot machinery arms identically.
  */
-export declare function deriveShellCaptureContext(reqCtx: RequestContext<any>, descriptor: Pick<ShellCaptureDescriptor, "ttl" | "swr">): CaptureContextDerivation;
+export declare function deriveShellCaptureContext(reqCtx: RequestContext<any>, descriptor: Pick<ShellCaptureDescriptor, "ttl" | "swr">, identity?: {
+    request: Request;
+    url: URL;
+}): CaptureContextDerivation;
 /**
  * Seal handles, derive the quiesce signal, prerender + abort via the SSR module's
  * captureShellHTML, and store the result. Returns the attempt outcome (the caller

package/dist/types/rsc/shell-serve.d.ts

@@ -16,6 +16,7 @@
  * intent cannot be honored — unlike an undeclared route, which is silent).
  */
 import { type EntryData } from "../server/context.js";
+import type { SearchParamsFilter } from "../cache/search-params-filter.js";
 import type { ShellCacheEntry, SegmentCacheStore } from "../cache/types.js";
 /** Debug/status header the browser (and e2e assertions) can read: HIT | MISS. */
 export declare const SHELL_STATUS_HEADER = "x-rango-shell";
@@ -53,9 +54,10 @@ export interface ResolvedPprConfig {
     captureTimeout?: number;
 }
 /**
- * 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),
@@ -85,8 +87,13 @@ export declare function resolvePprConfig(entry: EntryData | undefined | null): R
  * 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 declare function buildShellKey(url: URL): string;
+export declare function buildShellKey(url: URL, filter?: SearchParamsFilter): string;
 /**
  * Version gates for a stored shell: reactVersion AND buildVersion must both
  * match the running server. The postponed blob encodes hole positions against

package/dist/types/rsc/types.d.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 */
@@ -192,6 +194,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;
 }
 /**
  * Nonce provider function type.

package/dist/types/server/request-context.d.ts

@@ -143,8 +143,24 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     }>;
     /** @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
@@ -190,9 +206,13 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * (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;
@@ -206,6 +226,34 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
         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;
     };
     /**
      * @internal Shell-HIT tail marker: cache/prerender-store hits during THIS
@@ -518,7 +566,7 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
  * This is the type exported to library consumers. Internal code should
  * use the full RequestContext interface directly.
  */
-export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhen" | "_pprTransitionDecisions" | "_cacheStore" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureHandleLiveness" | "_shellCaptureLoaderHandleValues" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_locationState" | "_routeName" | "_prevRouteKey" | "_gateCurrentUrl" | "_gateCurrentParams" | "_gateActionId" | "_gateActionUrl" | "_gateActionResult" | "_gateFormData" | "_inActionRevalidation" | "_reportedErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_variables" | "_classifiedRoute" | "_cacheSignal" | "_dynamic" | "res">;
+export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhen" | "_pprTransitionDecisions" | "_pprReplayPostMatchReason" | "_cacheStore" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureHandleLiveness" | "_shellCaptureLoaderHandleValues" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_locationState" | "_routeName" | "_prevRouteKey" | "_gateCurrentUrl" | "_gateCurrentParams" | "_gateActionId" | "_gateActionUrl" | "_gateActionResult" | "_gateFormData" | "_inActionRevalidation" | "_reportedErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_variables" | "_classifiedRoute" | "_cacheSignal" | "_dynamic" | "res">;
 /**
  * Marker for a waitUntil-scheduled fn whose task promise must NOT enter
  * _pendingBackgroundTasks. Used by the PPR shell capture for its own task:
@@ -574,6 +622,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.

package/dist/types/testing/e2e/index.d.ts

@@ -1,11 +1,11 @@
 import type { Expect, TestType } from "@playwright/test";
 import { createUseFixture, type Fixture, type FixtureOptions } from "./fixture.js";
-import { createPageHelpers, createStopwatch, getHistoryState, getNumericContent, goBack, goForward, isVisibleInViewport, measureTime, type PageHelpers, parseNumber, type Stopwatch, testId, waitForElement, waitForHydration, waitForNavigation } from "./page-helpers.js";
+import { blockPrefetch, unblockPrefetch, createPageHelpers, createStopwatch, getHistoryState, getNumericContent, goBack, goForward, isPrefetchRequest, isVisibleInViewport, measureTime, type PageHelpers, parseNumber, type Stopwatch, testId, waitForElement, waitForHydration, waitForNavigation } from "./page-helpers.js";
 import { createParity, type ExpectParityOptions, type Parity, type ParityDescribeOptions, type ParityIntent } from "./parity.js";
 import { createRangoMatchers, type RangoMatchers } from "./matchers.js";
 export { assertCacheStatus, assertCacheDecision, parseCacheHeader, createCacheSink, filterCacheDecisions, type CacheSink, type ExpectedCacheStatus, type CacheStatusTarget, } from "../cache-status.js";
 export { assertPprReplayStatus, assertShellStatus, parsePprReplayStatus, parseShellStatus, PPR_REPLAY_STATUS_HEADER, shellCacheKey, SHELL_STATUS_HEADER, type PprReplayBypassReason, type PprReplayStatus, type ShellStatus, type ShellStatusTarget, } from "../shell-status.js";
-export { testId, waitForHydration, waitForNavigation, goBack, goForward, getHistoryState, waitForElement, isVisibleInViewport, parseNumber, getNumericContent, createStopwatch, measureTime, createPageHelpers, createUseFixture, createParity, createRangoMatchers, };
+export { testId, waitForHydration, waitForNavigation, goBack, goForward, getHistoryState, waitForElement, isVisibleInViewport, isPrefetchRequest, blockPrefetch, unblockPrefetch, parseNumber, getNumericContent, createStopwatch, measureTime, createPageHelpers, createUseFixture, createParity, createRangoMatchers, };
 export type { Fixture, FixtureOptions, PageHelpers, Stopwatch, Parity, ParityIntent, ParityDescribeOptions, ExpectParityOptions, RangoMatchers, };
 export interface RangoE2E extends PageHelpers, Parity {
     useFixture: (options: FixtureOptions) => Fixture;

package/dist/types/testing/e2e/page-helpers.d.ts

@@ -43,6 +43,30 @@ export declare function measureTime<T>(fn: () => Promise<T>): Promise<{
     elapsed: number;
     result: T;
 }>;
+/**
+ * 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 declare function isPrefetchRequest(req: {
+    headers: () => Record<string, string>;
+}): boolean;
+/**
+ * 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 declare function blockPrefetch(page: Page): Promise<void>;
+/** Remove a `blockPrefetch` guard, restoring normal prefetch traffic. */
+export declare function unblockPrefetch(page: Page): Promise<void>;
 export interface PageHelpers {
     /** Assert that no full page reload occurred between scope entry and exit. */
     expectNoReload: (page: Page) => AsyncDisposable;