@rangojs/router 0.4.0 → 0.4.1

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

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/render-route.d.ts

@@ -37,7 +37,7 @@
  * subtree, pass the `mount` option so useMount() returns the mounted prefix
  * (the segment chain is wrapped in a MountContext exactly as in production).
  */
-import type { ComponentType } from "react";
+import { type ComponentType } from "react";
 import type { RenderResult } from "@testing-library/react";
 import type { NavigationStore } from "../browser/types.js";
 import type { EventController } from "../browser/event-controller.js";
@@ -45,6 +45,7 @@ import type { LoaderDefinition } from "../types.js";
 import type { LocationStateDefinition } from "../browser/react/location-state-shared.js";
 import type { Handle } from "../handle.js";
 import type { ThemeConfig } from "../theme/types.js";
+import type { PrefetchStrategy } from "../router/prefetch-default.js";
 /**
  * Seed shape for `options.handle`, matching the handle wire format:
  * `{ [handleName]: { [segmentId]: pushedValues[] } }` (each segment accumulates
@@ -218,6 +219,14 @@ export interface RenderRouteOptions {
      * expect(getByTestId("nonce").textContent).toBe("test-nonce");
      */
     nonce?: string;
+    /**
+     * Router default prefetch strategy scoped to this rendered tree. This mirrors
+     * `createRouter({ defaultPrefetch })` for Links and eligible plain anchors
+     * inside `basename`. `data-prefetch="false"`/`"none"` opts out; `"true"`
+     * allows an application route with a common static-resource suffix but does
+     * not override a `"none"` default.
+     */
+    defaultPrefetch?: PrefetchStrategy;
 }
 /**
  * Imperative handle returned alongside the RTL result.

package/dist/types/testing/shell-status.d.ts

@@ -27,13 +27,14 @@
  * Import from `@rangojs/router/testing` (Vitest) or `@rangojs/router/testing/e2e`
  * (Playwright — same pure helpers, no Vite virtuals).
  */
+import { type CacheSearchParams } from "../cache/search-params-filter.js";
 /** Production header name (`rsc/shell-serve.ts` `SHELL_STATUS_HEADER`). */
 export declare const SHELL_STATUS_HEADER: string;
 /** Partial-navigation replay decision header from `rsc/rsc-rendering.ts`. */
 export declare const PPR_REPLAY_STATUS_HEADER: string;
 /** Values the serve path writes on `x-rango-shell`. */
 export type ShellStatus = "HIT" | "MISS";
-declare const PPR_REPLAY_BYPASS_REASONS: readonly ["method", "dynamic", "nonce", "store-unavailable", "passive-read-unsupported", "read-error", "no-entry", "invalid-version", "corrupt-entry", "handler-live-holes", "transition-when", "no-segment-snapshot", "snapshot-miss", "stale-build-entry"];
+declare const PPR_REPLAY_BYPASS_REASONS: readonly ["method", "dynamic", "nonce", "store-unavailable", "passive-read-unsupported", "no-navigation-context", "prerender-store", "intercept", "cache-disabled", "read-error", "no-entry", "invalid-version", "corrupt-entry", "handler-live-holes", "transition-when", "no-segment-snapshot", "snapshot-miss", "explicit-cache-hit", "stale-build-entry"];
 /** Bounded reasons a PPR partial request can fall open to ordinary matching. */
 export type PprReplayBypassReason = (typeof PPR_REPLAY_BYPASS_REASONS)[number];
 /** Parsed `x-rango-ppr-replay` value. */
@@ -55,9 +56,11 @@ export type ShellStatusTarget = Response | {
  * module (it pulls React). A parity test pins the two implementations.
  *
  * Accepts a `URL` or an absolute/relative request URL string (relative strings
- * resolve against `http://localhost`).
+ * resolve against `http://localhost`). Pass the router's `cache.searchParams`
+ * config as `searchParams` when the app under test sets one — the production
+ * key applies it, so the expected key must too.
  */
-export declare function shellCacheKey(url: URL | string): string;
+export declare function shellCacheKey(url: URL | string, searchParams?: CacheSearchParams): string;
 /**
  * Read `x-rango-shell` from a response. Returns `null` when the header is
  * absent (axis-1 / non-ppr / ineligible request).

package/dist/types/vite/plugin-types.d.ts

@@ -236,7 +236,7 @@ export interface RangoCloudflareOptions extends RangoBaseOptions {
  * `.vc-config.json` (and `config.json` for `functionName`).
  */
 export interface VercelPresetOptions {
-    /** Node runtime for the function. @default "nodejs22.x" */
+    /** Node runtime for the function. @default "nodejs24.x" */
     runtime?: string;
     /** Max execution time in seconds. @default 30 */
     maxDuration?: number;

package/dist/vite/index.js

@@ -2530,7 +2530,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.4.0",
+  version: "0.4.1",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -2727,7 +2727,8 @@ var package_default = {
     picomatch: "^4.0.4",
     "rsc-html-stream": "^0.0.7",
     srvx: "^0.11.15",
-    tinyexec: "^0.3.2"
+    tinyexec: "^0.3.2",
+    typescript: "^5.3.0 || ^6.0.0"
   },
   devDependencies: {
     "@opentelemetry/api": "^1.9.0",
@@ -2745,7 +2746,6 @@ var package_default = {
     jiti: "^2.7.0",
     react: "catalog:",
     "react-dom": "catalog:",
-    typescript: "^5.3.0",
     vitest: "^4.1.9"
   },
   peerDependencies: {
@@ -4353,7 +4353,7 @@ export default toNodeHandler(fetchHandler);
 function assertVercelNodeRuntime(runtime) {
   if (runtime != null && !runtime.startsWith("nodejs")) {
     throw new Error(
-      `[rango] preset "vercel": runtime "${runtime}" is not supported. This preset emits a Node serverless function; use a "nodejs*" runtime (default "nodejs22.x"). The Edge runtime is not supported.`
+      `[rango] preset "vercel": runtime "${runtime}" is not supported. This preset emits a Node serverless function; use a "nodejs*" runtime (default "nodejs24.x"). The Edge runtime is not supported.`
     );
   }
 }
@@ -4368,7 +4368,7 @@ function assertValidVercelFunctionName(functionName) {
 }
 function buildVercelVcConfig(vercel) {
   const vcConfig = {
-    runtime: vercel.runtime ?? "nodejs22.x",
+    runtime: vercel.runtime ?? "nodejs24.x",
     handler: "index.mjs",
     launcherType: "Nodejs",
     shouldAddHelpers: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -176,6 +176,19 @@
     "access": "public",
     "tag": "latest"
   },
+  "scripts": {
+    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
+    "prepublishOnly": "pnpm build",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
+    "test": "playwright test",
+    "test:ui": "playwright test --ui",
+    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-basename --project=hmr-prerender --no-deps --workers=1 && RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
+    "test:hmr-routes-local": "RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
+    "test:unit": "pnpm run build:types && vitest run",
+    "test:unit:watch": "vitest",
+    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
+  },
   "dependencies": {
     "@types/debug": "^4.1.12",
     "@vitejs/plugin-rsc": "^0.5.27",
@@ -184,26 +197,26 @@
     "picomatch": "^4.0.4",
     "rsc-html-stream": "^0.0.7",
     "srvx": "^0.11.15",
-    "tinyexec": "^0.3.2"
+    "tinyexec": "^0.3.2",
+    "typescript": "^5.3.0 || ^6.0.0"
   },
   "devDependencies": {
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/context-async-hooks": "^2.9.0",
     "@opentelemetry/sdk-trace-base": "^2.9.0",
     "@playwright/test": "^1.49.1",
+    "@shared/e2e": "workspace:*",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^24.10.1",
-    "@types/react": "^19.2.7",
-    "@types/react-dom": "^19.2.3",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
     "esbuild": "^0.28.1",
     "happy-dom": "^20.10.1",
     "jiti": "^2.7.0",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
-    "typescript": "^5.3.0",
-    "vitest": "^4.1.9",
-    "@shared/e2e": "0.0.1"
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "vitest": "^4.1.9"
   },
   "peerDependencies": {
     "@cloudflare/vite-plugin": "^1.42.1",
@@ -242,17 +255,5 @@
   },
   "engines": {
     "node": ">=24.0.0"
-  },
-  "scripts": {
-    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
-    "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
-    "test": "playwright test",
-    "test:ui": "playwright test --ui",
-    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-basename --project=hmr-prerender --no-deps --workers=1 && RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
-    "test:hmr-routes-local": "RANGO_E2E_ROUTE_HMR_ONLY=1 playwright test --project=hmr-routes --no-deps --workers=1",
-    "test:unit": "pnpm run build:types && vitest run",
-    "test:unit:watch": "vitest",
-    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
   }
-}
+}

package/skills/caching/SKILL.md

@@ -267,6 +267,45 @@ const router = createRouter({
 });
 ```
 
+### Search param key filtering (`cache.searchParams`)
+
+By default every non-reserved query param keys the cache, so
+`?utm_source=tw` and `?utm_source=ig` occupy separate slots in every tier.
+The global `searchParams` option controls which params participate in default
+cache-key generation:
+
+```typescript
+import { createRouter, TRACKING_SEARCH_PARAMS } from "@rangojs/router";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  cache: {
+    store,
+    // "all" (default) | "none" | { include: string[] } | { exclude: string[] }
+    searchParams: { exclude: TRACKING_SEARCH_PARAMS },
+  },
+});
+```
+
+- **Key-only**: `ctx.searchParams` and the request URL are untouched — handlers
+  and loaders still see the full query string.
+- **Matching**: exact names plus a `*` SUFFIX wildcard (`"utm_*"`). No RegExp.
+- **All tiers**: segment, document, response, PPR shell capture/lookup, the
+  baked-shell manifest gate (a URL whose only params are excluded ones now
+  matches the prerendered shell), and `"use cache"` ctx key normalization.
+- **`cache({ key })` override wins**: a custom key bypasses the filter along
+  with the rest of default key generation.
+- **The footgun**: excluding a param promises the rendered output does not
+  depend on it. If it does, the first variant is cached and served to everyone.
+  That is why the default is `"all"`.
+- `TRACKING_SEARCH_PARAMS` (also exported from `@rangojs/router/cache`) covers
+  `utm_*`, `gclid`, `fbclid`, `msclkid`, `ttclid`, `mc_cid`/`mc_eid`, and the
+  other common click-id params.
+
+Global-only by design — the per-route "this page varies only by `q`" case is
+already expressible with `cache({ key })`.
+
 ## Cache Stores
 
 ### Memory Store

package/skills/comparison/references/framework-comparison.md

@@ -542,7 +542,13 @@ analog but operates on loader/query reload, not RSC-segment render.
 `<Link prefetch="hover|viewport|render|adaptive|none">` (default: the router's
 `defaultPrefetch`, `"none"` in development and `"viewport"` in production), plus
 `prefetchKey` (`":source"` scopes a prefetch to the originating page for routes
-whose response branches on `currentUrl`). The distinguishing part is the stability
+whose response branches on `currentUrl`). Intercepted plain `<a href>` elements
+inside the router basename follow the same default; common static-resource
+extensions are excluded unless `data-prefetch="true"` identifies an application
+route, and `data-prefetch="false"` or `"none"` opts out unsafe GET links. A
+container with `data-prefetch-scope="false"` or `"none"` is a hard subtree boundary for both
+Links and plain anchors, so one annotation suppresses speculative work for a
+whole navigation section. The distinguishing part is the stability
 gating: a queued prefetch (`viewport`/`render`) will not fire until **both** the
 main thread is idle (`requestIdleCallback`, 200ms fallback) **and**
 `waitForViewportImages()` resolves — in-viewport images that are not `.complete`

package/skills/links/SKILL.md

@@ -423,6 +423,30 @@ Don't edit the file by hand — re-run codegen when patterns change.
 }
 ```
 
+## Prefetch boundaries
+
+`Link` follows its `prefetch` prop or the router's `defaultPrefetch`; eligible
+plain anchors follow the router default. When a whole DOM section must never
+speculate, mark its container instead of repeating per-link opt-outs:
+
+```tsx
+<section data-prefetch-scope="none">
+  <Link to="/activity" prefetch="viewport">
+    Activity
+  </Link>
+  <a href="/export">Export</a>
+</section>
+```
+
+The scope is a hard opt-out for every descendant Link and plain anchor; `"false"`
+and `"none"` are equivalent. An explicit `prefetch` prop or
+`data-prefetch="true"` cannot override it, and navigation still works normally.
+Use `data-prefetch="false"` or `"none"` directly on a plain anchor when only that
+anchor is unsafe. Dynamic scope changes re-evaluate only descendant anchors and
+mounted viewport/render Links. Links share one document-level scope observer,
+not one observer per Link or container. Adding a scope cannot recall work already
+queued or in flight; removing it re-arms both Link types.
+
 ## When to use what
 
 | Context          | API                                                | Resolves                                  | Use for                                                          |