@rangojs/router 0.22.1 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.22.1",
+  "version": "0.24.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/caching/SKILL.md

@@ -453,6 +453,28 @@ or a non-cacheable variable fails on a miss unless the loader `cache()` has a
 a `keyGenerator`. Either one switches the check off, so it must itself include
 the value (`/loader` → "Cache Key").
 
+### Loaders and `prefetch: false`
+
+A loader registered with `{ prefetch: false }` is skipped in a `<Link>`
+prefetch, and its own `cache()` is not read either, even when it would hit:
+the fill request that the click sends afterwards reads the loader cache and
+runs the loader on a miss. A route-level `cache()` boundary is unaffected: its
+stored handler output is served and written as before, hit or miss, and
+`loading(fallback, { prefetch: false })` under it defers only the loaders
+behind the fallback, never the cached handler. A `cache()` route below a
+layout with a flagged `loading()` keeps using its record whenever the browser
+already holds that layout; only a prefetch that defers the layout itself (it
+is new to the page) leaves the record unread and unwritten. A response that
+carries deferred work is never reused: the document cache refuses it, and it
+is sent `cache-control: private, no-cache` with `X-Rango-Prefetch` added to
+`Vary`, whatever `Cache-Control` the route set, so no CDN keeps it and it
+never answers a navigation. A browser may keep a copy and answer the same
+prefetch from it while it reloads the page for back/forward; the click
+completes it like any other. A fill is never answered from a stored body.
+Every body the document cache does hold is complete, so one entry answers a
+prefetch and a navigation, as without the flag. See `/loader` →
+"`prefetch: false`".
+
 ## Global Cache Configuration
 
 Configure the app-level store on the router. `cache()` boundaries, cached
@@ -621,11 +643,26 @@ const router = createRouter<AppBindings>({
 
 **How the two layers work:**
 
-| Scenario     | L1 (Cache API) | L2 (KV) | Result                        |
-| ------------ | -------------- | ------- | ----------------------------- |
-| Hot request  | HIT            | —       | Serve from L1 (fast)          |
-| Cold colo    | MISS           | HIT     | Serve from KV, promote to L1  |
-| First render | MISS           | MISS    | Render, write to both L1 + KV |
+| Scenario                             | L1 (Cache API)   | L2 (KV)                     | Result                        |
+| ------------------------------------ | ---------------- | --------------------------- | ----------------------------- |
+| Hot request                          | HIT              | —                           | Serve from L1 (fast)          |
+| Cold colo                            | MISS             | HIT                         | Serve from KV, promote to L1  |
+| First render                         | MISS             | MISS                        | Render, write to both L1 + KV |
+| After `updateTag`, `kvFallThrough`   | copy invalidated | HIT, written after the call | Serve from KV, promote to L1  |
+| After `updateTag`, `kvFallThrough`   | copy invalidated | MISS, or the old entry      | Render, write to both L1 + KV |
+| After `updateTag`, the default (off) | copy invalidated | not read                    | Render, write to both L1 + KV |
+
+By default a copy a tag invalidation rejected is a miss and the colo renders.
+`new CFCacheStore({ ctx, kv, kvFallThrough: true })` makes it read KV like a
+cold colo, so the colo serves the entry another colo already rebuilt (a
+visitor's render there, or a `router.prerender()` warm) instead of rebuilding
+it. The KV entry passes the same tag check: one written before the invalidation
+is never served. The cost is one KV get per rejected copy per colo after each
+invalidation (a `ppr` document reads a shell, a record and each `"use cache"`
+result, every copy rejected and the newer entry in KV: 150 ms added, measured
+in #1069 at 50 ms per KV read locally, not on a deployed worker).
+Turn it on for several locations where a render costs more than a KV read;
+leave it off otherwise. It needs `kv`.
 
 KV entries require `expirationTtl >= 60s`. Short-lived data entries (< 60s total
 TTL) are only cached in L1. A PPR shell is always written to KV, a short one
@@ -844,10 +881,22 @@ another, request-scoped APIs are guarded inside a cache scope:
 | Response writes: `ctx.headers.set()`, `setCookie()`, `setStatus()`, `onResponse()` | **throws** — response side effects lost on a hit           |
 | `ctx.get(var)` where the var is `{ cache: false }`                                 | **throws** on read                                         |
 | `ctx.theme`, `getRequestContext().theme`                                           | **throws** — the theme is the visitor's cookie             |
+| `ctx.rewrittenFrom` (any ctx, `getRequestContext().rewrittenFrom`)                 | **throws** — the visitor's URL of a rewritten request      |
 | `ctx.set(var, value)` for a cacheable var                                          | allowed (children are cached too)                          |
 | Any of the above **inside a registered loader** (`loader(...)`)                    | **allowed** — loaders always run fresh                     |
 | Any read in the boundary's own `key()`, `keyGenerator`, `condition()` or `tags()`  | **allowed** — it picks or labels the entry, never rendered |
 
+`ctx.rewrittenFrom` (the visitor's URL when middleware rewrote the request,
+`/middleware` → "Rewrite") throws on every read inside a `cache()` boundary
+or a `"use cache"` function, on a request nothing rewrote too, like
+`cookies()`: the entry would hold whichever URL the first caller came from,
+and a read that worked only on direct visits would break the first time a
+rewritten request reached it. A PPR shell capture and a render the document
+cache stores read it as `undefined` instead of throwing: those renders are
+the target page as a direct visit renders it, and the rewritten visitor's
+own render (outside them) still sees its URL. A response route under
+`cache()` whose handler read it is not stored.
+
 A loader body invoked from a handler with `await ctx.use(Loader)` may read
 `cookies()`/`headers()`/`ctx.request.headers`, but its response writes still throw: on a hit the
 handler is skipped, so that loader never runs.

package/skills/catalog.json

@@ -35,7 +35,7 @@
     },
     {
       "name": "client-urls",
-      "description": "Define client-component route groups with clientUrls() in a \"use client\" module — no handlers, useLoader at read sites, client-run revalidate predicates, loader-thrown notFound/redirect, loader handle writes, and the ssr:false SSR-completeness opt-in. Use when a route group's pages are client components, when building high-navigation-speed UIs (dashboards, admin panels, settings) where transitions must feel instant, when moving data reads from handler ctx.use() to useLoader at consumption sites, or when asking how routes defined in a \"use client\" file work.",
+      "description": "Define client-component route groups with clientUrls() in a \"use client\" module — no handlers, useLoader at read sites, server-run revalidate predicates, loader-thrown notFound/redirect, loader handle writes, and the ssr:false SSR-completeness opt-in. Use when a route group's pages are client components, when building high-navigation-speed UIs (dashboards, admin panels, settings) where transitions must feel instant, when moving data reads from handler ctx.use() to useLoader at consumption sites, or when asking how routes defined in a \"use client\" file work.",
       "argumentHint": "[setup]",
       "path": "skills/client-urls/SKILL.md"
     },
@@ -137,13 +137,13 @@
     },
     {
       "name": "loader",
-      "description": "Define data loaders with createLoader and register them on routes with loader(). Use when a route needs per-request data that stays fresh and streams while the page renders, a client component reads server data with useLoader, a loader should re-run after specific actions (revalidate), be cached (cache), be callable from the client (fetchable loaders), throw notFound()/redirect(), write page meta/breadcrumbs handles, or must be settled in the SSR'd document (ssr:false).",
+      "description": "Define data loaders with createLoader and register them on routes with loader(). Use when a route needs per-request data that stays fresh and streams while the page renders, a client component reads server data with useLoader, a loader should re-run after specific actions (revalidate), be cached (cache), be callable from the client (fetchable loaders), throw notFound()/redirect(), write page meta/breadcrumbs handles, must be settled in the SSR'd document (ssr:false), or must stay out of link prefetches (prefetch:false).",
       "argumentHint": "[loader]",
       "path": "skills/loader/SKILL.md"
     },
     {
       "name": "middleware",
-      "description": "Define global (router.use) and route (middleware()) middleware in @rangojs/router — auth gates, logging, response headers, context variables, redirects. Use when gating routes behind auth checks, logging requests, setting headers or ctx variables before a handler runs, or deciding whether middleware wraps server actions.",
+      "description": "Define global (router.use) and route (middleware()) middleware in @rangojs/router — auth gates, logging, response headers, context variables, redirects, rewrites (throw rewrite() renders another route at the same URL). Use when gating routes behind auth checks, logging requests, setting headers or ctx variables before a handler runs, showing a maintenance page at the visitor's URL, or deciding whether middleware wraps server actions.",
       "argumentHint": "[middleware-name]",
       "path": "skills/middleware/SKILL.md"
     },

package/skills/client-urls/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: client-urls
-description: Define client-component route groups with clientUrls() in a "use client" module — no handlers, useLoader at read sites, client-run revalidate predicates, loader-thrown notFound/redirect, loader handle writes, and the ssr:false SSR-completeness opt-in. Use when a route group's pages are client components, when building high-navigation-speed UIs (dashboards, admin panels, settings) where transitions must feel instant, when moving data reads from handler ctx.use() to useLoader at consumption sites, or when asking how routes defined in a "use client" file work.
+description: Define client-component route groups with clientUrls() in a "use client" module — no handlers, useLoader at read sites, server-run revalidate predicates, loader-thrown notFound/redirect, loader handle writes, and the ssr:false SSR-completeness opt-in. Use when a route group's pages are client components, when building high-navigation-speed UIs (dashboards, admin panels, settings) where transitions must feel instant, when moving data reads from handler ctx.use() to useLoader at consumption sites, or when asking how routes defined in a "use client" file work.
 argument-hint: "[setup]"
 ---
 
@@ -10,7 +10,8 @@ argument-hint: "[setup]"
 components are client components, and there are **no handlers at all** — every
 data read is `useLoader` at the consumption site, waiting is scoped by the
 inline `<Suspense>` above each read, and per-loader `revalidate()` predicates
-run in the browser. The server shop pattern — `await ctx.use(ProductLoader)` in
+run on the server (the build moves them out of the `"use client"` module).
+The server shop pattern — `await ctx.use(ProductLoader)` in
 a handler — is pipeline-blocking by contract: no pending UI can ever cover that
 latency. `clientUrls()` makes that shape unrepresentable.
 
@@ -20,9 +21,9 @@ layout, mostly tab/param/filter switches. Three things compound: the
 definition also matches in the browser, so a soft navigation renders the
 destination component immediately (loader reads suspend into `loading()` or
 an inline `<Suspense>`; `useOutlet().pending` flips for chrome) with no server
-round-trip to start; browser-run `revalidate()` predicates HOLD data across
-navigations that don't invalidate it (a tab switch re-runs nothing — only the
-decision crosses the wire); and any read that does refresh streams behind its
+round-trip to start; per-loader `revalidate()` predicates, run on the server
+with the same arguments as in `urls()`, HOLD data across navigations that
+don't invalidate it (a tab switch re-runs nothing); and any read that does refresh streams behind its
 own inline boundary instead of gating the commit. Add per-Link prefetch
 (`/links`) and a warmed click lands the complete page instantly.
 
@@ -131,9 +132,9 @@ flow into the generated route map, so `href()`, `ctx.reverse()` and
 | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `path()`       | Options are `name`, `search`, `trailingSlash`, `ppr` (shell caching — see `/ppr` → The loader lane rule); no response variants. Use callback may contain `loader()`, `loading()`, `transition()` |
 | `layout()`     | `layout(Component, () => [...])` — children are required and must contain at least one `path()`; may also hold `loader()`, `loading()`, `intercept()`, nested `layout()`                         |
-| `loader()`     | `loader(Def, use?)` or `loader(Def, { ssr: false }, use?)` — see below                                                                                                                           |
+| `loader()`     | `loader(Def, use?)` or `loader(Def, { ssr: false, prefetch: false }, use?)` — see below                                                                                                          |
 | `loading()`    | Route-level boundary around the optimistic render; inline `<Suspense>` at read sites keeps the destination's chrome visible while only the reads wait                                            |
-| `revalidate()` | Valid **inside a loader() use callback only**; runs in the browser                                                                                                                               |
+| `revalidate()` | Valid **inside a loader() use callback only**; runs on the server (the build hoists it out of the `"use client"` module)                                                                         |
 | `transition()` | Inside a `path()` use callback only (at most one). ViewTransition config plus a browser-run `when` predicate (see `/view-transitions`); same-route navs in a group already hold without it       |
 | `intercept()`  | Dot-local named target in the SAME definition; use may contain `loader()`/`loading()`                                                                                                            |
 
@@ -170,7 +171,8 @@ DIFFERENT schedules:
 - **Middleware runs on EVERY canonical request**, not just the first
   encounter. Every navigation inside the group — including a tab switch whose
   loaders all hold — still sends the canonical partial request (it commits
-  URL/history and carries the revalidation decisions), and middleware wraps
+  URL/history, and the server runs each loader's `revalidate()` while it
+  handles it), and middleware wraps
   each one: `requireAdmin` re-authorizes every navigation, and its
   `ctx.set()` variables are fresh for the group's loaders on every pass. The
   instant feel comes from held data and optimistic presentation, not from
@@ -187,22 +189,62 @@ All three pinned by dev + production e2e in the router repository (a
 middleware-stamped header per request, a layout run-count stamp held across
 navigations).
 
-## Revalidation runs in the browser
-
-A server-tree `revalidate()` predicate executes on the server. A `clientUrls()`
-predicate is client-module code, so it executes **in the browser** with
-client-computable args — `currentUrl`, `nextUrl`, `currentParams`,
-`nextParams`, `defaultShouldRevalidate`, `stale`, `isAction`, `actionId` — and
-only its _decision_ crosses the wire with the navigation request. Requests that
-carry no decisions (no-JS, progressive enhancement, prefetch, document loads)
-follow the locked server defaults.
-
-`isAction` is the same callable matcher as the server predicate, not a
-boolean. Action identity is `actionId`, whose FORM differs per environment:
-file-path `$id` (`path#export`) in the RSC env, hashed `$$id` in the
-browser — which is why the matcher (resolving an imported reference's
-`$id ?? $$id`) is the supported surface and a file-path substring on
-`actionId` is not:
+## Revalidation runs on the server
+
+A `clientUrls()` loader's `revalidate()` runs only on the server, with exactly
+the arguments and type of a `urls()` loader's (`ShouldRevalidateFn` from
+`@rangojs/router`): `currentParams`, `currentUrl`, `nextParams`, `nextUrl`,
+`defaultShouldRevalidate`, `context` (the handler context, so
+`context.get(var)` works), `segmentType`, `actionId`, `isAction(...refs)`,
+`actionUrl`, `actionResult`, `formData`, `method`,
+`routeName`/`fromRouteName`/`toRouteName`, and `stale`. Nothing runs in the
+browser before the request goes out; there is no client-computed decision and
+no hybrid.
+
+You still write the predicate in the `"use client"` module. The rango Vite
+plugin hoists each `revalidate()` argument into a server-only module, leaves a
+key in the browser and SSR copies, and registers the predicate when the
+group's module loads on the server (a lazy `include()` stays lazy). The cost
+is a rule: **the argument may reference imports and globals only.** Anything
+else is a build error naming `file:line:column`, starting
+`[rango] clientUrls() revalidate() at ...: revalidate() runs on the server; ...`.
+
+- Accepted: an inline arrow or function expression, an imported predicate
+  (`revalidate(isCartAction)`), a namespace member (`P.cart`), a call of an
+  imported factory (`makePredicate("cart")`), and globals such as `URL`,
+  `Boolean` and `import.meta.env`.
+- A binding declared in the same `"use client"` module is rejected: move the
+  predicate to its own module without `"use client"` and import it, or write it
+  inline. A binding of an enclosing function is rejected: read it from the
+  predicate's argument. So are `this`, `arguments`, `super`, `new.target`,
+  `import()` and `import.meta` other than `import.meta.env`.
+- A browser-only global (`window`, `document`, `navigator`, `localStorage`,
+  `sessionStorage`, `location`, `history`) is rejected: put the input on the
+  request (a cookie or a search param) and read it from the argument, or
+  refresh with `useRefreshLoaders`.
+- An `async` or generator function, a spread, a second argument, no argument,
+  or a non-function value (object, array or string literal) is rejected.
+- An import of `client-only`, or of a module whose directive prologue is
+  `"use client"`, is rejected (on the server its exports are client
+  references). A `"use server"` import is fine: on the server it is the real
+  action, which `isAction(ref)` matches. `server-only` and `node:` imports work
+  on the server, but the import also stays in the `"use client"` module
+  (imports are not pruned from the browser bundle), so it must still load in
+  the browser.
+
+Per request: a JS action POST runs the predicate with `method: "POST"`,
+`actionId`, `actionResult` (the action's return value), `formData` (the last
+`FormData` argument) and `actionUrl`; the default is true. An in-group
+navigation GET defaults to true when params or search changed. A prefetch
+partial runs the predicate, so a prefetched in-group navigation honours it. A
+stale back/forward revalidation sees `stale: true`. Document requests and
+no-JS form posts hold no segments, so every loader renders whatever a predicate
+says. On the action-triggered refetch GET (consolidation) `isAction()` is false,
+as for `urls()`. `currentParams`/`nextParams` are the server's route params,
+including the `include()` mount's params, and `actionId` is the server's
+`src/...#export` form; match actions with `isAction(ref)` rather than a
+substring. Vitest does not run the plugin, so in unit tests the predicate stays
+a plain function: test it with `runRevalidate` (`/testing`).
 
 ```ts
 import { addToCart, removeFromCart } from "./actions/cart";
@@ -211,6 +253,11 @@ import * as CartActions from "./actions/cart";
 // After an action, re-run only for cart actions; on navigation, keep the default.
 revalidate(({ isAction }) => (isAction() ? isAction(CartActions) : undefined));
 
+// Decide on what the action returned (actionResult is visible on the server):
+revalidate((ctx) =>
+  ctx.isAction(checkout) ? ctx.actionResult?.ok === true : undefined,
+);
+
 // Matcher forms (each returns a boolean):
 isAction(); // any action
 isAction(addToCart); // one action
@@ -226,6 +273,11 @@ with the ternary above instead (same rule as a server-tree loader). A bare
 `isAction(refs)` is a hard `false` on navigation too, so the loader stops
 refetching when params change.
 
+`intercept()` loaders inside `clientUrls()` do not apply their `revalidate()`
+yet (a known gap, left for a follow-up). The build still checks those
+predicates like any other, so one that captures a binding of the `"use client"`
+module fails the build although nothing runs it: import it, or drop it.
+
 Two scars worth copying:
 
 - A blunt `() => false` keeps serving the OLD product on product→product
@@ -235,6 +287,80 @@ Two scars worth copying:
   actions (`isAction(CartActions)`) while product/related loaders hold —
   three freshness outcomes in a single commit, decided per loader.
 
+## After an action: what the server decides
+
+The browser sends the action with the ids of the segments the page holds.
+Everything after that is decided on the server, while it handles that request:
+
+- **The action** runs there, and its return value is what the call resolves
+  with (`await action()`, `useActionState`).
+- **Which loaders rerun.** Each group loader's own `revalidate()` answers, with
+  the action's `actionResult` and `formData` (above). A loader that holds keeps
+  the data the page shows.
+- **The browser's caches.** When the response arrives the browser marks its
+  history cache stale and drops its prefetches, unless the action called
+  `keepClientCache()` (`/server-actions` → "Client Cache After an Action").
+- **A loader that fails on its rerun** reaches your `onError` on the server and
+  the page as an error, below.
+
+A form's React state survives an action's revalidation in a group, as on a
+`urls()` route: the commit renders into the mounted page instead of remounting
+it, so a controlled input keeps what the user typed.
+
+### A loader that fails on its rerun
+
+The action has already run when its loaders rerun, so a loader that throws
+there does not undo it. Where the error lands decides what the user sees:
+
+| The route                                                  | Called directly (`await action()`)                                                                                                                                                             | From `<form action>`, `useActionState` or `useTransition`                                                                                             |
+| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A group route, or a `urls()` route without `loading()`     | The call rejects with the loader's error (`"An error occurred"` in a build), although the action returned. Nothing of that revalidation commits: the page keeps its data and its React state.  | React hands the rejection to the nearest React error boundary above the form. With none of yours, the router's root error boundary replaces the page. |
+| A `urls()` route with `loading()`                          | The call resolves with the action's result. The commit renders, the loader's read throws, and the nearest React error boundary catches it; with none of yours, the root one replaces the page. | The same.                                                                                                                                             |
+| Under an `errorBoundary()` (for a group, around the mount) | Its fallback replaces the route: the page and its form state unmount.                                                                                                                          | The same.                                                                                                                                             |
+
+A group route's `loading()` does not change the first row. For a failure the
+user can retry (a flaky upstream, a rate limit), return it as data instead of
+throwing, and render it where the data goes:
+
+```tsx
+// stock.loader.ts
+export const StockLoader = createLoader(async (ctx) => {
+  try {
+    return { ok: true as const, stock: await inventory.count(ctx.params.sku) };
+  } catch {
+    return { ok: false as const, reason: "Stock is unavailable. Try again." };
+  }
+});
+
+// in the group's "use client" module
+function Stock() {
+  const { data } = useLoader(StockLoader);
+  return data.ok ? (
+    <p>{data.stock} in stock</p>
+  ) : (
+    <p role="status">{data.reason}</p>
+  );
+}
+```
+
+The action resolves with its result, the page and its form state stay, and the
+next action or navigation that reruns the loader replaces the message. Keep
+throwing for a failure that should stop the page, with an `errorBoundary()`
+around the mount for it.
+
+A failure returned as data is an ordinary value, so whatever stores the
+loader's value stores it too: a `cache()` on the loader serves it for its TTL,
+a `ppr` shell bakes an `ssr: false` loader's value, and a prerender stores it
+at build time. A thrown error is never stored (a stale entry keeps serving).
+To cache the expensive part, cache the call the loader makes (`"use cache"` on
+that function: a call that throws stores nothing) and turn the throw into
+data in a loader that is not cached itself.
+
+Pinned by dev + production e2e in the router repository (a group, its `urls()`
+twin, each with and without `loading()`, and the group under an
+`errorBoundary()`), and by a `serveShellRequest({ action })` test of the
+response.
+
 ## Loaders are full citizens: signals and handles
 
 Everything a DSL loader can do in the server tree works here — the loader body
@@ -321,6 +447,53 @@ need it, not the route.
 
 Pinned end to end by dev + production e2e in the router repository.
 
+**Without JavaScript.** A boundary that is not complete at the first flush
+ships its fallback and swaps the content in with a script, which a browser
+without JavaScript never runs. That includes a client component a loader's
+answer draws under an inline `<Suspense>`: a fast loader's answer usually
+makes the first flush, and `ssr: false` guarantees the loader's data does. It
+does not cover the client component's module: the first document a build's
+fresh server renders can still be waiting for it. The dev server matches a
+build here: when the shell is ready, it waits for the client components the
+payload has named and that are still loading, and for nothing else.
+
+## `prefetch: false` — keep a loader out of prefetches
+
+A `<Link>` prefetch of a group route runs its loaders. Flag the expensive one
+and the prefetch skips it:
+
+```tsx
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  loader(PriceLoader),
+  loader(ReviewsLoader, { prefetch: false }), // kept out of prefetches
+  loading(<ProductSkeleton />),
+]),
+```
+
+A click inside the group still shows the destination at once. With the
+prefetch received, the URL and the other loaders' data move with the click
+too, `useOutlet().pending` ends with that commit, and one follow-up request
+(the fill) runs only the flagged loaders. Read the flagged loader inside its
+own `<Suspense>` to show the page and that fallback at once; with no boundary
+React holds the page being left until the fill answers, as it would with no
+prefetch. Same rules as on a server route (`/loader` → "`prefetch: false`"):
+only a segment new to the page is deferred, so a same-route click
+(`/product/a` to `/product/b`) prefetches the loader as usual.
+
+- On a `layout()` of the group the flag applies to every route below it.
+- A flagged `loader()` on a server layout above the group is deferred while
+  that layout is new to the page (entering the group from outside).
+- `loading()` in `clientUrls()` takes no options, and a flagged `loading()`
+  on a server layout above the group defers nothing for the group's routes.
+- `intercept()` loaders accept the flag and ignore it, as in `urls()`.
+- With `ssr: false` on a `ppr` group route the flag is ignored (the bake
+  lane), as on a server route.
+- Test it with `serveShellRequest` in the Flight project: mount the module
+  itself, and `rangoUseClientTransform()` installs the group's projection
+  (`/testing` → `serve-shell-request.md`, "`clientUrls()` routes"). It also
+  registers the group's `revalidate()` predicates, so the server runs them
+  there as in your app.
+
 ## Intercepts
 
 ```tsx

package/skills/cloudflare/SKILL.md

@@ -292,20 +292,25 @@ traffic"). On Workers:
   the request it is called from.
 
 - **A warm fills the colo it runs in, and KV.** Another colo that already
-  holds its own Cache API copy keeps serving it until it expires; an L1 hit
-  never consults KV. After a deploy no colo holds a copy, so the warm's KV
-  entry is what each one reads next. For a content change, invalidate and then
-  warm, in this order:
+  holds its own Cache API copy keeps serving it until it expires or a tag
+  invalidation rejects it; a hit on a valid copy never consults KV. After a
+  deploy no colo holds a copy, so the warm's KV entry is what each one reads
+  next. For a content change, invalidate and then warm, in this order:
 
   ```typescript
-  await updateTag(`product:${id}`); // no colo serves the old copy any more
+  await updateTag(`product:${id}`); // a colo the marker has reached refuses its old copy
   await router.prerender({ env, ctx })(`/products/${id}`); // writes the new one
   ```
 
-  A colo with no copy of its own reads the warmed entry from KV. A colo that
-  was still holding the old copy treats it as a miss and renders once for
-  itself (it does not read the fresher KV entry). With `tagPurge` the purge
-  evicts every colo's copy, so they all read the warmed entry.
+  A colo with no copy of its own then reads the warmed entry from KV and
+  renders nothing. A colo that was still holding the old copy renders once for
+  itself by default; with `kvFallThrough: true` on the store it reads KV as if
+  it held none and renders nothing (with `tagPurge` the purge evicts the copy
+  first). That option costs one KV get per rejected copy per colo after each
+  invalidation, so turn it on where a render costs more than that. The KV
+  entry is checked against the same tag markers as
+  the colo's own copy, so a colo that KV still hands the entry from before
+  the invalidation refuses it and renders for itself.
 
 - **Entries under 60 seconds stay in one colo.** KV's minimum `expirationTtl`
   is 60 s, so a segment, item or response entry whose `ttl + swr` is shorter

package/skills/hooks/SKILL.md

@@ -111,11 +111,24 @@ cannot mismatch its server HTML.
 
 - Navigation state, params and action state: the component shows the live
   value right after it hydrates.
-- Handle data a loader pushed late, and the entry's location state: every
-  reader gets them once the whole document has streamed and hydrated, in one
-  transition. A reader re-renders only when its selection changes.
+- Handle data a loader pushed late, and the entry's location state: both wait
+  until the whole document has streamed and been revealed, and every boundary
+  has hydrated, including any boundary still suspended on the client (a lazy
+  chunk, a deferred-hydration gate; that wait has no upper bound). Then
+  location state lands in a transition and handle data in the release
+  notification. `useLocationState` readers re-render when the entry's
+  state object changes; `useHandle` readers when their selection changes.
+- State set before then by a commit that renders no new page (a shallow
+  navigation with `revalidate: false`, Back/Forward or a revalidation that
+  keeps every segment, an action's location state) waits the same way: readers
+  keep `undefined` until every boundary has hydrated, then show the latest
+  entry's state.
 - A navigation that commits before then mounts its page with the live values
   from its first render. A boundary of the document that persists across that
   navigation and has not hydrated yet then hydrates against the live values;
   where they differ from its HTML, React reports the mismatch and renders that
   boundary on the client.
+- A held navigation whose history entry commits during that window releases
+  the store for the whole hold. A boundary of the old page that hydrates during
+  the hold reads the destination's values and can mismatch its HTML; React
+  then renders that boundary on the client.

package/skills/hooks/data.md

@@ -146,7 +146,9 @@ clears the shared error.
 **`load()` calls that stay local** (no broadcast, per-hook state, same
 semantics as the old per-component `useState`):
 
-- `load({ params: { ... } })` — explicit params.
+- `load({ params: { ... } })` — explicit params. They are string values; a
+  `__proto__`, `constructor` or `prototype` key or a non-string value is
+  rejected and `load()` fails with `Invalid loader params`.
 - `load({ method: "POST", body })` — mutations.
 - Any `load()` on a `useFetchLoader(loader)` whose loader is **not**
   registered on the current route. Two unrelated components calling

package/skills/links/SKILL.md

@@ -479,6 +479,30 @@ 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.
 
+### What a prefetch renders
+
+A prefetch is a navigation sent early (a partial request with an
+`X-Rango-Prefetch` header), and by default the server renders everything for
+it: every handler and every loader. That is the point, a click then commits
+without a request, but it is also forty renders for a grid of forty links.
+Keep the expensive part out of the prefetch on the route, not on the link:
+
+```tsx
+// skip one loader
+loader(ReviewsLoader, { prefetch: false }),
+// skip what the fallback covers
+loading(<OrdersSkeleton />, { prefetch: false }),
+```
+
+A click that adopts such a prefetch commits what was prefetched, shows the
+fallback for the deferred part, and sends one extra request for it. Only what
+is new to the page is deferred: a segment already on screen (the layout of the
+section you are in, the route itself on `/product/a` to `/product/b`) is
+prefetched as usual. See
+`/loader` → "`prefetch: false`" and `/route` → "`loading()` options". To stop
+a link or a whole section from prefetching at all, use the `prefetch` prop or
+`data-prefetch-scope` above.
+
 ## When to use what
 
 | Context          | API                                                | Resolves                                  | Use for                                                          |