@rangojs/router 0.2.0 → 0.4.1

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.2.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,
@@ -4715,10 +4715,13 @@ var PUSH_CALLBACK_SCOPE_KEY = /* @__PURE__ */ Symbol.for(
 );
 var pushCallbackScopeALS = globalThis[PUSH_CALLBACK_SCOPE_KEY] ??= new AsyncLocalStorage();
 
+// src/rsc/shell-capture-constants.ts
+var SHELL_CAPTURE_MAX_WAIT_MS = 15e3;
+
 // src/rsc/shell-serve.ts
 var DEV_SHELL_PROBE_TIMEOUT_MS = 1e4;
 function normalizeCaptureTimeout(value) {
-  return typeof value === "number" && Number.isFinite(value) && value >= 1 ? value : void 0;
+  return typeof value === "number" && Number.isFinite(value) && value >= 1 ? Math.min(value, SHELL_CAPTURE_MAX_WAIT_MS) : void 0;
 }
 
 // src/vite/inject-client-debug.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.2.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

@@ -539,9 +539,16 @@ analog but operates on loader/query reload, not RSC-segment render.
 
 ### Prefetching: stability and control
 
-`<Link prefetch="hover|viewport|render|adaptive|none">` (default `"none"`), plus
+`<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                                                          |

package/skills/ppr/SKILL.md

@@ -175,12 +175,14 @@ On a document GET to a ppr route the router runs:
 point is after the chain, an unauthorized request NEVER sees shell bytes — put
 auth middleware anywhere (global or route DSL) and it guards PPR for free.
 
-### Soft navigation reuses the captured segment shell
+### Soft navigation caches and reuses the handler layer
 
-A usable shell snapshot also accelerates ordinary partial RSC navigations to
-the same URL. The capture records the canonical document segment tree alongside
-the HTML prelude. On a partial request the server replays only that segment
-record through the normal `matchPartial()` pipeline, which then:
+Ordinary partial RSC navigations to a `ppr` URL use the same handler-layer cache
+contract even when no document request has captured an HTML shell yet. When a
+shell snapshot exists, the server replays its canonical document segment record.
+On a cold partial request, normal matching renders the response and schedules a
+background navigation-only shell capture; later navigations and prefetches
+replay its eligible snapshot. In both cases `matchPartial()`:
 
 - preserves client-owned shared layouts by segment id;
 - returns only new or revalidating destination segments;
@@ -190,10 +192,30 @@ record through the normal `matchPartial()` pipeline, which then:
 This is deliberately invisible to the browser: the response is the same
 `RscPayload` shape as any other partial navigation. Captured item/response values
 and loader-container pins are NOT replayed on this path, so loader reads stay
-live. A route's own `cache()` scope still resolves its normal store, key, TTL,
-SWR, tags, and condition; only the implicit document scope sees the replay
-overlay, and fresh segment writes there stay request-local rather than polluting
-the canonical `doc:` namespace. `transition({ when })` is evaluated from the
+live.
+
+A route's own `cache()` scope — including one inherited from an ancestor, the
+common app-wide storefront shape — COMPOSES with replay instead of disabling
+it. The explicit tier stays authoritative: its lookup runs first with its
+normal store, key, TTL, SWR, tags, and condition, and when it supplies the
+match the response reports `BYPASS; reason=explicit-cache-hit` (never a false
+replay `HIT`). Only when the explicit tier misses does the shell snapshot's
+canonical doc segment record supply the match and report `HIT`. To make that
+possible, a capture of such a route records the doc segment record into the
+shell snapshot IN ADDITION to the scope's normal store write; the record rides
+only inside the shell entry, never the real store. Two opt-outs stay absolute:
+`cache(false)` and a `condition()` returning false mean "do not serve this
+request's segments from any cache" — no doc record is captured for them and
+the seeded fallback never rescues a refused read. `cache(false)` is static, so
+replay reports `BYPASS; reason=cache-disabled` before performing a single
+shell read; a `condition()` refusal is request-time state, decided at the
+lookup itself and reported as the same `cache-disabled` post-match (the gate
+must not pre-decide a predicate that could flap between the two evaluations).
+An errored explicit read — a throwing `key()`, or a built-in store's swallowed
+backend failure (`CACHE_READ_ERROR`) — also never falls back: it renders
+uncached, exactly as without ppr.
+
+`transition({ when })` is evaluated from the
 matched manifest before route handlers on every PPR match, so it can vary by
 URL/params/action or middleware context without disabling replay; handler-set
 context is unavailable by design. Intercepts, handler-live holes, an active
@@ -201,23 +223,60 @@ nonce, and an absent/corrupt segment snapshot fall open to the ordinary partial
 path when encountered by the shell capture. A transition already replayed from
 an explicit cache tier remains frozen by that tier's normal semantics.
 
+Two more decisions are made before any shell-store read, so probes and
+prerendered routes never spend passive `getShell` I/O:
+
+- A partial request carrying neither `X-RSC-Router-Client-Path` nor `Referer`
+  (a curl probe, a synthetic monitor) can never produce a partial match; it
+  reports `BYPASS; reason=no-navigation-context`. Alert on replay hit-rate
+  with this in mind — such probes are not cache misses.
+- A `Prerender()` route's partial is served from the build-time prerender
+  store inside matching (a better-than-HIT outcome); it reports
+  `BYPASS; reason=prerender-store`. Its captures never record a doc segment
+  record (the prerender store short-circuits the cache write), so replay
+  seeding would be impossible anyway.
+
 Fresh and stale-within-SWR runtime shells replay. The stale read is passive: it
 uses `getShell(key, { claimRevalidation: false })`, does not claim SWR ownership,
 and cannot recapture HTML. A later document request owns the background
-recapture; hard-expired entries fall open. Production may also use a fresh local
-build manifest; development stays runtime-only because probing `/__rsc_shell`
-would block navigation on an on-demand capture. Custom `SegmentCacheStore`
+recapture; hard-expired entries schedule a navigation-only capture. Production
+may also use a fresh local build manifest. Development does not probe
+`/__rsc_shell`; it schedules the same local background capture instead. Custom `SegmentCacheStore`
 implementations must set `supportsPassiveShellReads: true` and honor the
 non-claiming read option.
 
+The first cold partial request reports `BYPASS; reason=no-entry` because no
+artifact could supply that response; its successful render schedules
+`scheduleShellCapture` with a navigation-only marker. The next request reports
+`HIT` when the capture produced an eligible snapshot. Navigation snapshots use
+a separate shell key, so they cannot overwrite or be served as a document shell.
+The capture runs with the stripped target document URL and loads SSR support in
+the bounded background queue, outside the triggering partial response's latency.
+An `allReady` decision still declines capture.
+
 Partial responses expose the actual decision as `x-rango-ppr-replay`:
 `HIT; freshness=fresh|stale` or `BYPASS; reason=<bounded-token>`. With
 performance metrics enabled, the same decision appears as
 `ppr-navigation-replay` in `Server-Timing`. `HIT` means matching consumed the
 seeded segment record after it decoded successfully, not merely that a snapshot
 existed. An explicit `cache()` scope that supplies the match cannot produce a
-false HIT. There is still no Flight resume API; this is segment replay followed
-by normal Flight streaming, not reuse of the HTML `prelude`/`postponed` bytes.
+false HIT — it reports `explicit-cache-hit`. There is still no Flight resume
+API; this is segment replay followed by normal Flight streaming, not reuse of
+the HTML `prelude`/`postponed` bytes.
+
+The bounded bypass tokens, grouped by when they are decided:
+
+| Token                                                                             | Decided           | Meaning                                                                                                                                                                                                                                                                   |
+| --------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `method`, `dynamic`, `nonce`, `store-unavailable`, `passive-read-unsupported`     | pre-read          | request/route/store ineligible for replay                                                                                                                                                                                                                                 |
+| `no-navigation-context`                                                           | pre-read          | no `X-RSC-Router-Client-Path`/`Referer`; a partial match is impossible                                                                                                                                                                                                    |
+| `prerender-store`                                                                 | pre-read or match | `Prerender()` route served by its baked artifact (pre-read probe of the normal variant; reclassified post-match when the store actually served, either variant)                                                                                                           |
+| `intercept`                                                                       | match             | the navigation resolved to an intercept — replay is never armed for intercepts (they keep their normal cache path); no heal capture                                                                                                                                       |
+| `cache-disabled`                                                                  | pre-read or match | `cache(false)` (pre-read, static) or `condition()` false (decided at the lookup); consumer opt-out is absolute                                                                                                                                                            |
+| `read-error`, `no-entry`, `invalid-version`, `corrupt-entry`, `stale-build-entry` | shell read        | no usable shell entry (`no-entry`/`invalid-version`/`corrupt-entry`/`stale-build-entry` schedule the navigation-only heal capture)                                                                                                                                        |
+| `handler-live-holes`, `transition-when`, `no-segment-snapshot`                    | eligibility       | entry exists but its snapshot cannot replay (no canonical doc record, or handler/transition liveness); on a route with an enabled `cache()` scope, `no-segment-snapshot` heals when the lookup did not refuse (a `condition()` false-at-capture entry becomes replayable) |
+| `explicit-cache-hit`                                                              | match             | the route's own `cache()` tier supplied the match                                                                                                                                                                                                                         |
+| `snapshot-miss`                                                                   | match             | an eligible snapshot was seeded but matching did not consume it                                                                                                                                                                                                           |
 
 ### Capture-generation invalidation
 
@@ -292,7 +351,9 @@ curl -s -D - -o /dev/null https://app.example.com/products/1 | grep -i x-rango-s
 - Structured capture diagnostics: `createRouter({ debugShellCapture: true })`
   logs one line per capture attempt/skip (outcome, durations, prelude and
   snapshot bytes, backoff state); pass a function to receive each
-  `ShellCaptureDebugEvent` instead. In dev, with `debugPerformance` on, the
+  `ShellCaptureDebugEvent` instead. `skip-capacity` means the isolate already
+  has 32 queued/running captures; the dropped best-effort capture can retry on a
+  later request. In dev, with `debugPerformance` on, the
   last capture outcome for a key also rides the next document GET's
   `Server-Timing` as `ppr-capture;desc="…"`.
 
@@ -750,7 +811,10 @@ cache"` value baked into the shell is PINNED at capture (the capture data
   it: call `cacheTag(...)` from the shell-material render code (the render-time
   lever), or add the tag to `ppr.tags` (operational tags the render cannot know —
   a tenant id, a deploy marker). Ring-1/ring-3 tag invalidation does NOT drop the
-  shell.
+  shell. Tags are optional: if TTL/SWR is the complete freshness policy, leave
+  the shell untagged. Rango does not warn for that choice; with
+  `debugShellCapture` enabled, a stored event reports `untaggedBake: true` when
+  bake-lane loader material uses TTL/SWR-only invalidation.
 - **Uncached nondeterminism in the shell is a hydration hazard**: a raw
   `Date.now()` / `Math.random()` / uncached `fetch` rendered directly in shell
   material (outside any cache ring) drifts between capture and hit and the

package/skills/router-setup/SKILL.md

@@ -120,6 +120,15 @@ interface RangoOptions<TEnv> {
   // Set to false to disable prefetch caching.
   prefetchCacheTTL?: number | false;
 
+  // Default prefetch strategy for Links without a `prefetch` prop and for
+  // intercepted plain anchors inside basename. false/none opts out; true allows
+  // an application route whose path has a common static-resource extension.
+  // data-prefetch-scope="false"/"none" on a container is a hard subtree
+  // opt-out for both Links and plain anchors, including explicit opt-ins.
+  // (dev: "none", production: "viewport").
+  // Per-Link props win over the router default, not a disabled container scope.
+  defaultPrefetch?: "hover" | "viewport" | "render" | "adaptive" | "none";
+
   // CSP nonce provider (for router.fetch)
   nonce?: (
     request: Request,

package/skills/testing/client-components.md

@@ -8,20 +8,21 @@ RTL-style stub (peer of React Router's `createRoutesStub` / Expo's `renderRouter
 
 ### Options — `RenderRouteOptions`
 
-| Field           | Type                                                                   | Meaning                                                                                                                                                                                                              |
-| --------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `request`       | `Request \| string`                                                    | Initial location. Only the URL is read (client render — headers/method ignored). Defaults to the leaf spec's static prefix or `"/"`.                                                                                 |
-| `loaderData`    | `Record<string, unknown>`                                              | Loader data keyed by loader `$$id`. `useLoader(L)` reads `loaderData[L.$$id]`.                                                                                                                                       |
-| `loaders`       | `ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>`             | Seed by REFERENCE: `[loader, data]` pairs. Robust for real `createLoader()` handles whose `$$id` is empty in a bare test. Prefer over `loaderData`.                                                                  |
-| `params`        | `Record<string, string>`                                               | Explicit params, merged over (and overriding) params extracted from the `request` URL.                                                                                                                               |
-| `locationState` | `ReadonlyArray<readonly [LocationStateDefinition<any, any>, unknown]>` | Seed `useLocationState(def)` by REFERENCE: `[def, value]` pairs; written to `history.state`.                                                                                                                         |
-| `handles`       | `ReadonlyArray<readonly [Handle<any, any>, unknown[]]>`                | Seed `useHandle(handle)` by REFERENCE: `[handle, pushedValues[]]`. Accumulated GLOBALLY (not segment-scoped).                                                                                                        |
-| `handle`        | `HandleDataSeed`                                                       | Advanced: raw wire format `{ [handleId]: { [segmentId]: pushedValues[] } }`. Prefer `handles`. Merged with it.                                                                                                       |
-| `routeMap`      | `Record<string, string>`                                               | Name -> pattern map (informational; client `useReverse` takes its map as an argument, so this is not consumed).                                                                                                      |
-| `basename`      | `string`                                                               | `createRouter({ basename })` value. Wired into `NavigationProvider` so `useRouter().basename`, `<Link>` prefixing, `useMount`/`useHref` resolve against the mount. Normalized like `createRouter`. Defaults to root. |
-| `mount`         | `string`                                                               | `include()` mount prefix. Wraps the segment chain in a `MountContext` so `useMount()` returns the prefix. Normalized like a path prefix. Defaults to `"/"`.                                                          |
-| `theme`         | `ThemeConfig \| true`                                                  | Theme config (`createRouter({ theme })` shape) to wrap the tree in a `ThemeProvider`. Defaults to no provider. A component calling `useTheme()` REQUIRES one.                                                        |
-| `nonce`         | `string`                                                               | CSP nonce to seed via `NonceContext`, so a component calling `useNonce()` (e.g. an analytics/GTM head script) sees it — mirroring SSR. Defaults to `undefined` (the browser default).                                |
+| Field             | Type                                                                   | Meaning                                                                                                                                                                                                                                       |
+| ----------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `request`         | `Request \| string`                                                    | Initial location. Only the URL is read (client render — headers/method ignored). Defaults to the leaf spec's static prefix or `"/"`.                                                                                                          |
+| `loaderData`      | `Record<string, unknown>`                                              | Loader data keyed by loader `$$id`. `useLoader(L)` reads `loaderData[L.$$id]`.                                                                                                                                                                |
+| `loaders`         | `ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>`             | Seed by REFERENCE: `[loader, data]` pairs. Robust for real `createLoader()` handles whose `$$id` is empty in a bare test. Prefer over `loaderData`.                                                                                           |
+| `params`          | `Record<string, string>`                                               | Explicit params, merged over (and overriding) params extracted from the `request` URL.                                                                                                                                                        |
+| `locationState`   | `ReadonlyArray<readonly [LocationStateDefinition<any, any>, unknown]>` | Seed `useLocationState(def)` by REFERENCE: `[def, value]` pairs; written to `history.state`.                                                                                                                                                  |
+| `handles`         | `ReadonlyArray<readonly [Handle<any, any>, unknown[]]>`                | Seed `useHandle(handle)` by REFERENCE: `[handle, pushedValues[]]`. Accumulated GLOBALLY (not segment-scoped).                                                                                                                                 |
+| `handle`          | `HandleDataSeed`                                                       | Advanced: raw wire format `{ [handleId]: { [segmentId]: pushedValues[] } }`. Prefer `handles`. Merged with it.                                                                                                                                |
+| `routeMap`        | `Record<string, string>`                                               | Name -> pattern map (informational; client `useReverse` takes its map as an argument, so this is not consumed).                                                                                                                               |
+| `basename`        | `string`                                                               | `createRouter({ basename })` value. Wired into `NavigationProvider` so `useRouter().basename`, `<Link>` prefixing, `useMount`/`useHref` resolve against the mount. Normalized like `createRouter`. Defaults to root.                          |
+| `mount`           | `string`                                                               | `include()` mount prefix. Wraps the segment chain in a `MountContext` so `useMount()` returns the prefix. Normalized like a path prefix. Defaults to `"/"`.                                                                                   |
+| `theme`           | `ThemeConfig \| true`                                                  | Theme config (`createRouter({ theme })` shape) to wrap the tree in a `ThemeProvider`. Defaults to no provider. A component calling `useTheme()` REQUIRES one.                                                                                 |
+| `nonce`           | `string`                                                               | CSP nonce to seed via `NonceContext`, so a component calling `useNonce()` (e.g. an analytics/GTM head script) sees it — mirroring SSR. Defaults to `undefined` (the browser default).                                                         |
+| `defaultPrefetch` | `PrefetchStrategy`                                                     | Router default for `<Link>` and eligible plain anchors. `data-prefetch="false"`/`"none"` opts out one anchor; ancestor `data-prefetch-scope="false"`/`"none"` hard-disables the subtree; `"true"` permits routed resource suffixes elsewhere. |
 
 `RenderRouteSpec = { path, Component, layout?, loaderIds?, name? }` — one node of the route definition. The array is the layout chain root-to-leaf; the LAST entry is the leaf route (its pattern is matched against `request` to extract params; layout patterns are informational). `loaderIds` attaches seeded loaders to THIS node's segment; `layout` on the leaf wraps it; `name` is informational.
 

package/skills/vercel/SKILL.md

@@ -56,7 +56,7 @@ Per-function knobs go under `vercel` and are written into `.vc-config.json`:
 rango({
   preset: "vercel",
   vercel: {
-    runtime: "nodejs22.x", // default
+    runtime: "nodejs24.x", // default
     maxDuration: 30, // seconds, default
     memory: 1024, // MB (platform default when omitted)
     regions: ["fra1"], // pin regions (platform default when omitted)