@rangojs/router 0.22.1 → 0.23.0

package/package.json

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

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,7 +137,7 @@
     },
     {
       "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"
     },

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
@@ -321,6 +373,43 @@ need it, not the route.
 
 Pinned end to end by dev + production e2e in the router repository.
 
+## `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,19 @@ 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. Location state
+  lands in the barrier commit (one transition that also hydrates every
+  boundary still dehydrated); handle data lands in the release notification
+  right after that commit. `useLocationState` readers re-render when the
+  entry's state object changes; `useHandle` readers when their selection
+  changes.
 - 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/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                                                          |

package/skills/loader/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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).
 argument-hint: "[loader]"
 ---
 
@@ -936,6 +936,8 @@ function ProductPage() {
 }
 ```
 
+A skeleton that has appeared stays on screen for at least about 300 ms before React replaces it with what it was waiting for: React does not replace a fallback sooner than 300 ms after the last fallback committed ([#1078](https://github.com/rangojs/rango/issues/1078)). On a cold click that mounts the `loading()` boundary, a loader that finishes sooner than that still shows its skeleton for about 300 ms, while a slower loader is not delayed. The router leaves this to React: an early skeleton is preferred to holding the click, and a fully prefetched click commits complete and shows none. A nested `loading()` whose data lands after the outer one has been revealed shows its own fallback, and the 300 ms starts again. The loaders feature page on the docs site has the measured figures. Under `transition()` a related cost applies; see [view-transitions](../view-transitions/SKILL.md).
+
 ## Loader Authority: notFound() and redirect()
 
 A loader may **throw** `notFound()` and `redirect()` — data-dependent
@@ -1094,6 +1096,195 @@ The costs and constraints:
 Also available in `clientUrls()` route groups (`/client-urls`), where the
 loader-heavy shape makes it most useful.
 
+## `prefetch: false` — Keep a Loader Out of Prefetches
+
+A `<Link>` prefetch is a navigation sent early: the server renders every
+handler and every loader for it. With the default `"viewport"` strategy that
+means a grid of forty product links runs forty copies of your slowest loader
+for pages most visitors never open. Pass `prefetch: false` to keep one loader
+out:
+
+```tsx
+import { Suspense } from "react";
+
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  loader(PriceLoader), // cheap: still runs in the prefetch
+  loader(ReviewsLoader, { prefetch: false }), // expensive: skipped in a prefetch
+  loading(<ProductSkeleton />),
+]),
+```
+
+(`prefetch` sits beside `ssr` in `LoaderOptions`; combine them as
+`{ ssr: false, prefetch: false }` if you need both.)
+
+What happens:
+
+- A **prefetch** of the route does not run the loader and does not read its
+  `cache()`; the payload marks it deferred. The rest of the page prefetches as
+  usual.
+- Only on a route the browser does not show yet. A loader the page already
+  holds, on a same-route navigation such as `/product/a` to `/product/b`, runs
+  in the prefetch when it revalidates, exactly as without the flag, and the
+  click sends no second request. The rule: a click that adopts a prefetch is
+  never worse than the same click with no prefetch at all (one exception: a
+  click before its prefetch has answered, under "The limits"), and content on
+  screen is never swapped for a fallback because of the flag. For the same
+  reason a prefetch that deferred something is used only on the page that
+  made it: a page that already shows the segment makes its own prefetch.
+- A **click** that adopts that prefetch is never blocked by the loader. A
+  deferred loader behaves like a loader that is still streaming, and where
+  the page reads it (`useLoader(ReviewsLoader)`) React does what it does for
+  one:
+  - the read has its own `<Suspense>`: the page shows at once with that
+    fallback in it. This can be a finer fallback than the same click shows
+    with no prefetch, where the whole route is still streaming behind its
+    `loading()`;
+  - the nearest boundary is the route's `loading()`: that fallback shows;
+  - no boundary at all: React holds the page being left until the value
+    arrives.
+
+  Meanwhile the browser sends one second request, the fill, that runs only
+  the deferred loader. Its value arrives in the page that is already on
+  screen, as a streamed loader's does; nothing remounts.
+
+- A **document request** (hard load), a **navigation with no prefetch to
+  adopt**, an action, back/forward and a no-JS form post run the loader as
+  they always did. Leaving the option out is the old behavior.
+
+Read the loader behind a boundary, as you would any streamed loader:
+
+```tsx
+"use client";
+function Reviews() {
+  const { data } = useLoader(ReviewsLoader);
+  return <ReviewList items={data} />;
+}
+
+// in the server component:
+<Suspense fallback={<ReviewsSkeleton />}>
+  <Reviews />
+</Suspense>;
+```
+
+The limits:
+
+- **A click before its prefetch has answered waits for it, then fetches the
+  deferred part.** The flag is there to keep expensive or slow work out of
+  every prefetch, so that an API that is costly to call is not called for
+  every link a visitor might click. A click that comes while the link's
+  prefetch is still in flight reuses that prefetch, as it does without the
+  flag, and sends the fill when the prefetch answers. The page shows no later
+  than with no prefetch; the deferred part shows its fallback until the fill
+  lands, and can complete later than a click with no prefetch, by up to what
+  was left of the prefetch. That is the price of keeping the work out of the
+  prefetch.
+- **A navigation started before the fill answers cancels it.** It is
+  cancelled when the newer navigation starts, not when that one commits. If
+  the newer navigation then ends without replacing the page (a redirect the
+  client refuses, an action refetch that drops its response), the deferred
+  part keeps its fallback until the next navigation. Every other ending
+  replaces the page anyway.
+- **`navigate()` resolves after the fill has answered.** The click's
+  navigation fills the deferred part itself, so `await navigate(url)` (and a
+  `router.push()` you await) settles a round trip after the page committed.
+  `useNavigation()` reads `idle` from the commit, with `isStreaming` true
+  until the fill has streamed in.
+- **A boundary is required for a fallback.** With no `loading()` on the entry
+  and no `<Suspense>` around the read, nothing can show a fallback, so React
+  holds the page being left on screen until the fill returns.
+  `useNavigation()` reads `state: "loading"` for that time, as on any
+  navigation that is still streaming, so a progress bar shows, and the URL
+  hooks (`useNavigation().location`) change with the page. The address bar
+  has already changed: it moves with the click, where a click with no
+  prefetch moves it when its response starts. There is no definition-time
+  error.
+- **`ctx.rendered()` is refused.** A loader that can be deferred throws on
+  every request kind (a document load included, so you see it the first time
+  you open the page in development) if it calls `await ctx.rendered()`. The
+  fill does not re-run the entry's handler, so there is no render to wait for
+  and no handle data to read. Remove `{ prefetch: false }` from the loader, or
+  stop calling `ctx.rendered()`. Pushing a handle from the loader is fine.
+- **`ctx.set()` values from held handlers are not visible.** The fill runs the
+  deferred work and middleware only. A handler or layout the client already
+  holds does not run again, so a variable it set with `ctx.set()` is missing
+  when the loader reads it with `ctx.get()`. Variables set by middleware are
+  there, as middleware runs on every request; so are `ctx.params` and
+  `ctx.request`.
+- **`redirect()`, `notFound()` and handle pushes arrive late.** They behave as
+  for a loader that streams behind `loading()`, but they come with the fill,
+  after the page is already on screen: a redirect becomes a replace
+  navigation, `notFound()` renders the nearest not-found boundary, an error
+  reaches the error boundary.
+- **The fill reads through the loader's own caching; a prefetch reads none
+  of it, by intent.** A loader with `cache()` that nothing in the prefetch
+  reads is skipped even when its entry is warm, and so is a `"use cache"`
+  function it calls: a prefetch that looked would have to run the loader on
+  a miss, which is the work the flag keeps out. The fill is where the loader
+  runs. It serves a warm `cache()` entry without running the loader, runs
+  the loader and stores on a cold one, and a `"use cache"` function inside
+  the loader hits or stores as on any request.
+- **A loader something else reads with `ctx.use()` runs in the prefetch.**
+  The reader needs the value, so the flag cannot keep the loader out. When
+  the read is in time, the loader is an ordinary loader for that prefetch,
+  its own `cache()` included: one run (none on a warm entry), the reader and
+  the loader's data agree, nothing deferred, no fill for it. In time means:
+  inside a handler that has no `loading()` (the router waits for it), or
+  before the reader's first `await`.
+- **Two late readers make it run twice.** The loader runs in the prefetch for
+  its reader and again in the fill, because by the time the read happens the
+  loader's own segment has already been sent as deferred:
+
+  ```tsx
+  // 1. A handler under loading() is streamed: the router does not wait for
+  //    it, so a read after its first await comes late.
+  path(
+    "/product/:id",
+    async (ctx) => {
+      const product = await getProduct(ctx.params.id);
+      const reviews = await ctx.use(ReviewsLoader); // late: runs it here
+      return <Product product={product} reviews={reviews} />;
+    },
+    { name: "product" },
+    () => [
+      loader(ReviewsLoader, { prefetch: false }), // and the fill runs it again
+      loading(<ProductSkeleton />),
+    ],
+  );
+
+  // 2. A loader that is not deferred itself and reads it after an await.
+  const SummaryLoader = createLoader(async (ctx) => {
+    const product = await getProduct(ctx.params.id);
+    const reviews = await ctx.use(ReviewsLoader); // late: two runs
+    return summarize(product, reviews);
+  });
+  ```
+
+  Data is never missing, only fetched twice, and the page shows the fill's
+  value. To get one run, start the read before the first `await`
+  (`const reviews = ctx.use(ReviewsLoader)` at the top, awaited where you
+  need it), or drop the flag from a loader the page cannot render without.
+
+- **`clientUrls()` routes take it on `loader()`.** In a `clientUrls()`
+  definition `loader(Def, { prefetch: false })` works as here: a click
+  inside the group shows the destination at once, commits the prefetched
+  data with the URL, and one fill runs the flagged loaders (see
+  `/client-urls` → "`prefetch: false`"). A flagged `loading()` defers nothing
+  on a group route, from the group or from a server layout above it.
+- **No effect inside `intercept()`.** Its loaders accept the flag and ignore
+  it, in `urls()` and in `clientUrls()`: a prefetch that resolves an
+  intercept defers nothing.
+- **`ppr` and `ssr: false`.** On a `ppr` route an `ssr: false` loader is the
+  bake lane and is served from the shell, so `prefetch: false` is ignored for
+  it and development logs a warning. Under `cache()` and `Prerender` the flag
+  works as above (see `/caching`, `/prerender`, `/ppr`).
+
+To skip a handler along with its loaders, flag the `loading()` instead (see
+`/route` → "`loading()` options"). `loader(Def, { prefetch: false })` accepts
+only a boolean; anything else throws `loader() prefetch must be a boolean`.
+
+Test it with `serveShellRequest(router, url, { partial: { prefetch: true } })`
+and `result.readDeferred()` (see `/testing`).
+
 ## Fetchable Loaders
 
 By default, loaders only run as part of a render (document, navigation, or

package/skills/migrate-nextjs/SKILL.md

@@ -850,8 +850,8 @@ For **dashboard / admin / settings-shaped sections** — high navigation
 frequency inside one layout, mostly tab/param/filter switches — also consider
 porting that route group to `clientUrls()` (`/client-urls`): the definition
 matches in the browser (instant optimistic pending, no server round-trip to
-start a transition) and browser-run `revalidate()` predicates hold data across
-switches that don't invalidate it, which is the fastest transition shape Rango
+start a transition) and per-loader `revalidate()` predicates (run on the
+server) hold data across switches that don't invalidate it, which is the fastest transition shape Rango
 has. Server-component routes and `clientUrls()` groups compose in one tree.
 
 ## 7. Server Actions