@rangojs/router 0.2.0 → 0.4.1

package/src/router/match-middleware/cache-store.ts

@@ -106,6 +106,7 @@ import {
   runWithRequestContext,
 } from "../../server/request-context.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
+import { createShellImplicitDocScope } from "../../cache/cache-scope.js";
 import { getRouterContext } from "../router-context.js";
 import { debugLog, debugWarn, getOrCreateRequestId } from "../logging.js";
 import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
@@ -134,6 +135,14 @@ export function withCacheStore<TEnv>(
 
     const ownStart = performance.now();
 
+    // Shell capture composition (capture side): a route-derived cache() scope
+    // keeps its normal store write below, but the capture's shell entry still
+    // needs the CANONICAL doc segment record for navigation replay. Recorded
+    // before the skip check because it must run on the explicit tier's hit
+    // path too (state.cacheHit skips the normal write, yet the served
+    // segments were collected into allSegments either way).
+    recordShellCaptureDocRecord(ctx, state, allSegments);
+
     if (
       !ctx.cacheScope?.enabled ||
       ctx.isAction ||
@@ -348,3 +357,64 @@ export function withCacheStore<TEnv>(
     }
   };
 }
+
+/**
+ * During a SHELL CAPTURE of a route with a route-derived cache() scope, write
+ * the matched non-loader segments as the canonical doc segment record through
+ * the capture marker's SnapshotOnlySegmentStore — IN ADDITION to the explicit
+ * scope's normal real-store write. The record rides only inside the shell
+ * entry (a real doc-keyed write would poison the next capture's lookup; see
+ * RecordingShellStore.recordSegmentWrite), so no real-store behavior changes.
+ * Without it, navigation replay was structurally dead for any ppr route under
+ * a cache() scope (including an app-wide one): the snapshot held only
+ * explicit-tier-keyed records a partial lookup can never resolve.
+ *
+ * Records nothing when:
+ * - not a capture render, or the route derived no scope (the implicit doc
+ *   scope's own cacheRoute below already records the doc record);
+ * - the scope is STATICALLY disabled (cache(false)) — the replay gate
+ *   pre-decides that shape as `cache-disabled` before any shell read, so a
+ *   record would be dead weight;
+ * - the prerender store supplied the match: those partials are served from
+ *   build-time segments and report `prerender-store`.
+ *
+ * A false condition() suppresses the record too — the consumer's write
+ * refusal is absolute. The prelude-already-bakes-it argument does NOT excuse
+ * recording: a NAVIGATION-ONLY capture's prelude is never served as a
+ * document, so for those entries the segment record would be the sole
+ * persisted copy of a render the consumer refused to cache — and a later
+ * request where condition() flips true could consume it through the seeded
+ * fallback. The lookup-time `cache-disabled` report stays reachable without
+ * the record: matchPartialWithPprReplay installs a REPORT-ONLY marker (no
+ * store) on the no-eligible-snapshot path, so the lookup's own refusal is
+ * still surfaced while the fallback has nothing to serve.
+ *
+ * Wrapped in requestCtx.waitUntil — during a capture that is the tracked-write
+ * override, so captureAndStoreShell's settleWrites awaits the record before
+ * draining the snapshot.
+ */
+function recordShellCaptureDocRecord<TEnv>(
+  ctx: MatchContext<TEnv>,
+  state: MatchPipelineState,
+  segments: ResolvedSegment[],
+): void {
+  const requestCtx = getRequestContext();
+  if (!requestCtx?._shellCaptureRun) return;
+  const marker = requestCtx._shellImplicitCache;
+  if (!marker?.store) return;
+  const scope = ctx.cacheScope;
+  if (!scope || scope.isShellImplicitDocScope) return;
+  if (ctx.isAction || ctx.isIntercept || ctx.request.method !== "GET") return;
+  if (state.cacheSource === "prerender") return;
+  if (!scope.allowsCache("write")) return;
+
+  const docScope = createShellImplicitDocScope(marker);
+  requestCtx.waitUntil(() =>
+    docScope.cacheRoute(
+      ctx.pathname,
+      ctx.matched.params,
+      segments,
+      ctx.isIntercept,
+    ),
+  );
+}

package/src/router/navigation-snapshot.ts

@@ -30,6 +30,50 @@ export interface ResolveNavigationDeps {
   ) => 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 function getNavigationContextHeader(request: Request): string | null {
+  return (
+    request.headers.get("X-RSC-Router-Client-Path") ||
+    request.headers.get("Referer")
+  );
+}
+
+/**
+ * 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 function prerenderStoreShortCircuits(
+  pr: true | undefined,
+  request: Request,
+): boolean {
+  return pr === true && !request.headers.get("X-RSC-HMR");
+}
+
+/**
+ * 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 function getInterceptSourceHeader(request: Request): string | null {
+  return request.headers.get("X-RSC-Router-Intercept-Source");
+}
+
 export async function resolveNavigation(
   request: Request,
   url: URL,
@@ -39,12 +83,8 @@ export async function resolveNavigation(
   const clientSegmentIds =
     url.searchParams.get("_rsc_segments")?.split(",").filter(Boolean) || [];
   const stale = url.searchParams.get("_rsc_stale") === "true";
-  const previousUrl =
-    request.headers.get("X-RSC-Router-Client-Path") ||
-    request.headers.get("Referer");
-  const interceptSourceUrl = request.headers.get(
-    "X-RSC-Router-Intercept-Source",
-  );
+  const previousUrl = getNavigationContextHeader(request);
+  const interceptSourceUrl = getInterceptSourceHeader(request);
   const isHmr = !!request.headers.get("X-RSC-HMR");
 
   if (!previousUrl) {

package/src/router/prefetch-default.ts

@@ -0,0 +1,59 @@
+/**
+ * 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";
+
+function defaultPrefetchForEnvironment(
+  nodeEnv: string | undefined,
+): PrefetchStrategy {
+  return nodeEnv === "production" ? "viewport" : "none";
+}
+
+export const DEFAULT_PREFETCH_STRATEGY: PrefetchStrategy =
+  defaultPrefetchForEnvironment(process.env.NODE_ENV);
+
+const VALID_STRATEGIES: ReadonlySet<string> = new Set([
+  "hover",
+  "viewport",
+  "render",
+  "adaptive",
+  "none",
+] satisfies PrefetchStrategy[]);
+
+export function resolveDefaultPrefetch(
+  raw: PrefetchStrategy | undefined,
+  nodeEnv: string | undefined = process.env.NODE_ENV,
+): PrefetchStrategy {
+  if (typeof raw === "string" && VALID_STRATEGIES.has(raw)) {
+    return raw;
+  }
+  return defaultPrefetchForEnvironment(nodeEnv);
+}

package/src/router/router-interfaces.ts

@@ -318,6 +318,14 @@ export interface RangoInternal<
    */
   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/src/router/router-options.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,
@@ -11,6 +12,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";
@@ -303,15 +305,37 @@ 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 }
+    | {
+        store: SegmentCacheStore;
+        enabled?: boolean;
+        searchParams?: CacheSearchParams;
+      }
     | ((
         env: TEnv,
         ctx?: ExecutionContext,
       ) => {
         store: SegmentCacheStore;
         enabled?: boolean;
+        searchParams?: CacheSearchParams;
       });
 
   /**
@@ -532,6 +556,40 @@ export interface RangoOptions<TEnv = any> {
    */
   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/src/router.ts

@@ -115,6 +115,7 @@ import {
 } from "./router/prerender-match.js";
 import { resolveStateCookieName } from "./router/state-cookie-name.js";
 import { resolvePrefetchCacheTTL } from "./router/prefetch-cache-ttl.js";
+import { resolveDefaultPrefetch } from "./router/prefetch-default.js";
 import {
   resolvePrefetchCacheSize,
   resolvePrefetchConcurrency,
@@ -160,6 +161,7 @@ export function createRouter<TEnv = any>(
     prefetchCacheTTL: prefetchCacheTTLOption,
     prefetchCacheSize: prefetchCacheSizeOption,
     prefetchConcurrency: prefetchConcurrencyOption,
+    defaultPrefetch: defaultPrefetchOption,
     stateCookiePrefix: stateCookiePrefixOption,
     warmup: warmupOption,
     telemetry: telemetrySink,
@@ -268,6 +270,10 @@ export function createRouter<TEnv = any>(
     prefetchConcurrencyOption,
   );
 
+  // Resolve the router-wide default Link prefetch strategy ("none" in dev,
+  // "viewport" in production). Links without an explicit prop fall back to it.
+  const defaultPrefetch = resolveDefaultPrefetch(defaultPrefetchOption);
+
   // Resolve warmup enabled flag (default: true)
   const warmupEnabled = warmupOption !== false;
 
@@ -1009,6 +1015,7 @@ export function createRouter<TEnv = any>(
     prefetchCacheTTL,
     prefetchCacheSize,
     prefetchConcurrency,
+    defaultPrefetch,
 
     // Expose the resolved rango state cookie name for the server-side writer
     // (invalidateClientCache) and for shipping to the client in metadata.

package/src/rsc/capture-queue.ts

@@ -23,6 +23,18 @@
  * swallow, so one rejected capture can never wedge every later one.
  */
 let captureQueue: Promise<void> = Promise.resolve();
+let admittedCaptures = 0;
+
+/** Bound queued/running capture closures retained by one isolate. */
+export const MAX_ADMITTED_CAPTURES: number = 32;
+
+/** The caller may drop this best-effort capture and retry on a later request. */
+export class CaptureQueueFullError extends Error {
+  constructor() {
+    super(`shell capture queue is full (${MAX_ADMITTED_CAPTURES})`);
+    this.name = "CaptureQueueFullError";
+  }
+}
 
 /**
  * Upper bound on how long one queue link may hold the queue. A capture task
@@ -43,6 +55,10 @@ const QUEUE_LINK_CAP_MS = 60_000;
 export function enqueueSerializedCapture(
   task: () => Promise<void>,
 ): Promise<void> {
+  if (admittedCaptures >= MAX_ADMITTED_CAPTURES) {
+    return Promise.reject(new CaptureQueueFullError());
+  }
+  admittedCaptures++;
   const prior = captureQueue;
   let releaseQueue!: () => void;
   captureQueue = new Promise<void>((resolve) => {
@@ -51,9 +67,16 @@ export function enqueueSerializedCapture(
   return (async () => {
     await prior.catch(() => {});
     let capTimer: ReturnType<typeof setTimeout> | undefined;
+    const taskPromise = Promise.resolve()
+      .then(task)
+      .finally(() => {
+        // A timed-out link releases serialization, but its detached task still
+        // counts against admission until it actually settles.
+        admittedCaptures--;
+      });
     try {
       await Promise.race([
-        task(),
+        taskPromise,
         new Promise<void>((resolve) => {
           capTimer = setTimeout(resolve, QUEUE_LINK_CAP_MS);
           (capTimer as { unref?: () => void }).unref?.();

package/src/rsc/full-payload.ts

@@ -53,6 +53,7 @@ export function buildFullPayload(
       prefetchCacheTTL: ctx.router.prefetchCacheTTL,
       prefetchCacheSize: ctx.router.prefetchCacheSize,
       prefetchConcurrency: ctx.router.prefetchConcurrency,
+      defaultPrefetch: ctx.router.defaultPrefetch,
       stateCookieName: ctx.router.resolvedStateCookieName,
       themeConfig: ctx.router.themeConfig,
       // Carry warmupEnabled on the initial full-render payload so the client

package/src/rsc/handler.ts

@@ -64,6 +64,10 @@ import {
 } from "../route-map-builder.js";
 import type { HandlerContext } from "./handler-context.js";
 import type { CacheErrorCategory } from "../cache/cache-error.js";
+import {
+  compileSearchParamsFilter,
+  type SearchParamsFilter,
+} from "../cache/search-params-filter.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import { buildRouterTrieFromUrlpatterns } from "./manifest-init.js";
 import { handleProgressiveEnhancement } from "./progressive-enhancement.js";
@@ -460,6 +464,7 @@ export function createRSCHandler<
     // Priority: options.cache (handler override) > router.cache (router default)
     // Store is enabled only if: config provided, enabled, and no ?__no_cache query param
     let cacheStore: SegmentCacheStore | undefined;
+    let searchParamsFilter: SearchParamsFilter | undefined;
     const cacheOption = options.cache ?? router.cache;
     if (cacheOption && !url.searchParams.has("__no_cache")) {
       const cacheConfig =
@@ -469,6 +474,9 @@ export function createRSCHandler<
 
       if (cacheConfig.enabled !== false) {
         cacheStore = cacheConfig.store;
+        searchParamsFilter = compileSearchParamsFilter(
+          cacheConfig.searchParams,
+        );
       }
     }
 
@@ -526,6 +534,7 @@ export function createRSCHandler<
       url,
       variables,
       cacheStore,
+      searchParamsFilter,
       explicitTaggedStores,
       cacheProfiles: router.cacheProfiles,
       executionContext: executionCtx,
@@ -1219,6 +1228,7 @@ export function createRSCHandler<
               prefetchCacheTTL: router.prefetchCacheTTL,
               prefetchCacheSize: router.prefetchCacheSize,
               prefetchConcurrency: router.prefetchConcurrency,
+              defaultPrefetch: router.defaultPrefetch,
               stateCookieName: router.resolvedStateCookieName,
               themeConfig: router.themeConfig,
               warmupEnabled: router.warmupEnabled,

package/src/rsc/response-cache-serve.ts

@@ -103,7 +103,7 @@ export async function serveResponseRouteWithCache(
   // Default key: response:{type}: + host-namespaced base (sorted search, reserved
   // _rsc*/__* params excluded). Same composition as document/segment tiers so
   // the host-namespacing and search-normalization rules cannot drift.
-  let cacheKey = `response:${responseType}:${cacheKeyBase(url.host, url.pathname, url.searchParams)}`;
+  let cacheKey = `response:${responseType}:${cacheKeyBase(url.host, url.pathname, url.searchParams, undefined, reqCtx._searchParamsFilter)}`;
 
   // Priority 1: route-level key() (full override). Priority 2: store-level
   // keyGenerator (modifies the default key).