@rangojs/router 0.4.0 → 0.4.2

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, };
@@ -70,6 +70,8 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * @internal
      */
     private emitDebug;
+    /** Build-time-gated shell tier trace for deployed cross-colo diagnostics. */
+    private debugShell;
     /**
      * Resolve the cache-key base URL for the current cache operation.
      * Prefers an explicit `baseUrl` option; otherwise derives it from the live
@@ -209,7 +211,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.
@@ -263,10 +265,10 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      */
     private warnShellFamilyInertOnce;
     /**
-     * Get a cached PPR shell entry by key from KV (no L1). Applies the KV read
-     * budget, corrupt-entry eviction, hard-expiry, and tag invalidation exactly
-     * like kvGetItem, minus the L1 promote. SWR is a plain staleness flag — KV has
-     * no REVALIDATING herd guard, so the capture scheduler's module-level
+     * Get a cached PPR shell entry from Cache API, falling through to KV and
+     * promoting a valid KV hit. Both tiers store one envelope so the prelude,
+     * postponed state, snapshot, versions, and generation metadata cannot mix.
+     * SWR remains a plain staleness flag; the capture scheduler's module-level
      * in-flight set is the recapture stampede guard.
      */
     getShell(key: string): Promise<{
@@ -274,12 +276,21 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
         shouldRevalidate?: boolean;
     } | null>;
     /**
-     * Store a PPR shell entry in KV with TTL and optional SWR window. The write is
-     * registered with waitUntil and awaited so invalidation rejection can be
-     * acknowledged to the capture scheduler. The tags/taggedAt ride in the envelope
-     * so isGloballyInvalidated() can invalidate the shell via the shared KV markers.
+     * Store a PPR shell envelope in Cache API and, when its retention meets KV's
+     * 60-second floor, KV. The shared write is registered with waitUntil and
+     * awaited so invalidation rejection can be acknowledged to the capture
+     * scheduler. Short-lived shells remain useful in L1 even though KV rejects
+     * them.
      */
     putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | void>;
+    /** Rebuild the public shell entry from its validated storage envelope. */
+    private shellEnvelopeToEntry;
+    /** Build the Cache API representation of the coupled shell envelope. */
+    private shellEnvelopeResponse;
+    /** KV shell fallback with corruption checks and background L1 promotion. */
+    private kvGetShell;
+    /** Promote a valid KV shell into the per-colo Cache API tier. */
+    private promoteShellToL1;
     /**
      * Convert string key to Request object for CF Cache API.
      * Includes version in URL if specified (for cache invalidation on code changes).

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

@@ -189,8 +189,10 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
      *   per-request memo is consulted (synchronously, no KV read), so a request
      *   that ran `updateTag()` still masks its own not-yet-purged entries
      *   (read-your-own-writes).
-     * - The KV tier and PPR shells still use the KV markers — those are written
-     *   regardless, and purge cannot reach KV — so keep `kv` configured for L2.
+     * - The KV tier and PPR shell reads still use the KV markers. Runtime shell
+     *   L1 entries are purgeable, but their taggedAt is the capture-start time: a
+     *   capture can finish after an invalidation purge, so eviction alone cannot
+     *   reject that older generation. Keep `kv` configured for shell L2 + markers.
      *   Without `kv`, purge mode is the ONLY tag invalidation and the store is
      *   L1-only: a supported configuration (previously tag invalidation without
      *   KV had no read-side effect at all). One KV-less caveat: an entry whose

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;

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/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";
@@ -283,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.
@@ -498,9 +518,13 @@ export interface RangoOptions<TEnv = any> {
     prefetchConcurrency?: number;
     /**
      * Default prefetch strategy for every `<Link>` that does not set its own
-     * `prefetch` prop. A per-Link `prefetch` prop always wins, in both
-     * directions (a Link can opt out of an aggressive default with
-     * `prefetch="none"`, or opt in under `defaultPrefetch: "none"`).
+     * `prefetch` prop and every eligible intercepted plain anchor. Plain anchors
+     * can opt out with `data-prefetch="false"` or `data-prefetch="none"`. Common
+     * static-resource suffixes are excluded unless `data-prefetch="true"` marks
+     * the URL as an application route. Mark side-effectful GET links such as
+     * `/logout` with an opt-out because the router cannot infer endpoint safety.
+     * A per-Link `prefetch` prop always wins in both directions (a Link can opt
+     * out with `prefetch="none"`, or opt in under `defaultPrefetch: "none"`).
      *
      * - `"viewport"` (production default): prefetch when the link enters the viewport —
      *   idle-gated and queued (see `prefetchConcurrency`), so prefetches never

package/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

@@ -304,8 +304,9 @@ export declare function scheduleShellCapture(ctx: HandlerContext<any>, request:
  *   I/O failure is reported separately and does NOT make the attempt retryable —
  *   the capture itself worked).
  * - `redirect`: the matched route redirects, so there is no shell to capture.
- * - `no-shell`: the prelude came back trivial (no <body>) OR captureShellHTML
- *   rejected with our own abort. This is the only RETRYABLE outcome.
+ * - `no-shell`: captureShellHTML returned null because the prelude was unusable
+ *   or its private capture abort landed before the shell completed. This is the
+ *   only RETRYABLE outcome.
  */
 type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused";
 /**
@@ -327,9 +328,9 @@ type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "write
  * when we froze the shell; the attempt itself warmed the module graph, so a second
  * attempt a short beat later usually completes the shell in the SAME background
  * task. That kills the old multi-request warmup where the caller had to re-issue
- * several HTTP requests before a capture stuck. We retry ONLY on `no-shell` (and a
- * defensively-caught abort); a genuine render error is NOT retried — it propagates
- * to scheduleShellCapture's reportCacheError. See docs/design/ppr-shell-resume.md.
+ * several HTTP requests before a capture stuck. We retry ONLY on `no-shell`; a
+ * genuine render error is NOT retried — it propagates to scheduleShellCapture's
+ * reportCacheError. See docs/design/ppr-shell-resume.md.
  *
  * `retryDelayMs` is a parameter (defaulting to the module const) so unit tests can
  * drive the retry without a real 400ms wall-clock wait.
@@ -369,9 +370,10 @@ export declare function deriveShellCaptureContext(reqCtx: RequestContext<any>, d
  * capture worked; only the store I/O failed). `ssrModule.captureShellHTML` MUST be
  * present (eligibility is checked before scheduling).
  *
- * A `no-shell` result (trivial prelude, or a defensively-caught abort) is the only
- * retryable outcome; a genuine (non-abort) captureShellHTML error propagates so it
- * reaches reportCacheError and is NOT retried.
+ * A `no-shell` result from captureShellHTML is the only retryable outcome. Every
+ * captureShellHTML error propagates to reportCacheError and is NOT retried. The
+ * capture handler converts only its own private abort sentinel to null before this
+ * layer sees it.
  */
 declare function captureAndStoreShell(ssrModule: SSRModule, rscStream: ReadableStream<Uint8Array>, handleStore: HandleStore, reqCtx: RequestContext<any>, capture: ShellCaptureDescriptor, stats?: CaptureAttemptStats, captureStartedAt?: number): Promise<Exclude<CaptureAttemptOutcome, "redirect">>;
 export { runShellCapture, captureAndStoreShell, delay, SHELL_CAPTURE_RETRY_DELAY_MS, };

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";
@@ -86,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

@@ -194,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.