@rangojs/router 0.22.0 → 0.23.0

package/skills/migrate-react-router/SKILL.md

@@ -84,21 +84,24 @@ per app (both compose in one `urls()` tree via `include()`):
   | component (client, hooks)        | stays a client component — no conversion                 |
   | `loader` (throws `redirect`/404) | `createLoader()` — thrown `redirect()`/`notFound()` kept |
   | `useLoaderData()`                | `useLoader(Loader)` at the read site, under `<Suspense>` |
-  | `shouldRevalidate` (runs client) | `revalidate()` predicate — ALSO runs in the browser      |
+  | `shouldRevalidate` (runs client) | `revalidate()` predicate — runs on the server            |
   | `meta({ data })`                 | `ctx.use(Meta)` push from the loader body                |
   | `defer` / `Await`                | loaders stream; `<Suspense>` above each read             |
 
-  Note the `shouldRevalidate` row: a server-tree `revalidate()` runs on the
-  server, but a `clientUrls()` predicate runs in the browser with
-  client-computable args — the exact RR semantics. A group ported this way can
-  still be re-migrated to server handlers later, route by route.
+  Note the `shouldRevalidate` row: RR runs it in the browser, but a
+  `clientUrls()` loader's predicate runs on the server like a server-tree
+  `revalidate()`, with the same arguments (`actionResult` and `formData`
+  included). The build moves it out of the `"use client"` module, so it may
+  reference imports and globals only: move a predicate that captures
+  module-local values into its own module and import it. A group ported this
+  way can still be re-migrated to server handlers later, route by route.
 
 Start with server handlers; reach for `clientUrls()` when a route group's
 conversion cost is dominated by rewriting interactive components rather than
 by moving data fetching — or when the group is a **high-navigation-speed
 surface** (dashboard, admin panel, settings): browser-local matching gives
-instant optimistic pending, and browser-run predicates hold data across
-tab/param switches, so transitions are the fastest Rango offers. See
+instant optimistic pending, and per-loader `revalidate()` predicates (run on
+the server) hold data across tab/param switches, so transitions are the fastest Rango offers. See
 `/client-urls`.
 
 ## Migration Strategy

package/skills/migrate-react-router/data-and-actions.md

@@ -55,7 +55,7 @@ Use it only when you need capabilities beyond what the handler provides:
 If the React Router loader just fetches data for its page component AND the
 component can become a server component, merge it into the handler. If the
 component stays a client component, port the whole group with `clientUrls()`
-instead — loader, `useLoader` read, and browser-run `revalidate()` keep the RR
+instead — loader, `useLoader` read, and per-loader `revalidate()` keep the RR
 route-module shape (see the "Two target shapes" section in the main skill and
 `/client-urls`). See `/loader` for when the live data layer is useful.
 

package/skills/ppr/SKILL.md

@@ -1069,6 +1069,19 @@ Four hard edges (each e2e/unit-pinned):
   must be fresh on every serve, it belongs on the live lane (no `ssr: false`) or
   in a nested promise.
 
+### `prefetch: false` on a `ppr` route
+
+A `ppr` route's handler output is stored, so a `loading()` flagged with
+`prefetch: false` does not skip the handler in a `<Link>` prefetch: the shell
+and its partial replay are served as usual and only the live loaders behind
+the fallback are deferred. A live loader registered with `{ prefetch: false }` is
+skipped the same way, and the click that adopts the prefetch sends one fill
+request for it. An `ssr: false` loader is the bake lane and is served from the
+shell, so on a `ppr` route `prefetch: false` is ignored for it, and
+development logs a warning that the loader "is registered with ssr: false
+and prefetch: false on a ppr route"; drop one of the two options. See
+`/loader` → "`prefetch: false`".
+
 ### The layout-with-loaders playbook (the storefront case)
 
 The most common real-app shape: an app-wide layout registers per-user loaders

package/skills/prerender/SKILL.md

@@ -666,6 +666,16 @@ build-time shell capture runs it and bakes its settled data into the shell,
 and a shell HIT runs it only when its return carries promises (`/ppr` → "The
 bake lane"). The Flight payload collection itself still skips loaders.
 
+### `prefetch: false` skips only the loaders
+
+A `Prerender` handler's output is stored, so a `loading()` flagged with
+`prefetch: false` on the route does not skip the handler in a `<Link>` prefetch: the
+stored output is served as usual, and only the loaders behind the fallback are
+deferred (a loader registered with `{ prefetch: false }` likewise). The click
+that adopts the prefetch shows the fallback and sends one fill request for
+them. This holds in development, where there is no build artifact, as in
+production. See `/loader` → "`prefetch: false`".
+
 ### Build-time handle data is frozen
 
 Handle values pushed via `ctx.use()` DURING pre-rendering (handler pushes at
@@ -1283,8 +1293,8 @@ fresh.
 A warm replaces the entry where it runs, and on a shared store that is the
 entry other locations read on their next miss. It does not reach a copy
 another location already holds: on `CFCacheStore`, each colo keeps serving its
-own Cache API copy until it expires, and an entry whose `ttl + swr` is under
-60 seconds never reaches KV at all.
+own Cache API copy until it expires or a tag invalidation rejects it, and an
+entry whose `ttl + swr` is under 60 seconds never reaches KV at all.
 
 So after a deploy (new keys: no location holds a copy) a warm alone makes
 the route ready everywhere. For a content change, invalidate first, then
@@ -1306,12 +1316,16 @@ path.json("/hooks/product-changed", async (ctx) => {
 
 The invalidation makes every location's copy unservable, so no visitor is
 served the old content, and the warm writes the new entry where it runs and
-to the shared store. A location with no copy of its own reads that entry on
-its next request and renders nothing. On `CFCacheStore`, a colo that was
-still holding its own (now invalidated) copy renders once for itself instead
-of reading the warmed entry, unless the store uses `tagPurge`, which evicts
-those copies. Await `updateTag()` before the warm: a write that started
-before an invalidation of one of its tags is refused.
+to the shared store. Every other location reads that entry on its next
+request and renders nothing: a location with no copy of its own, and, on
+`CFCacheStore` with `kvFallThrough: true` (default false), a colo that was
+still holding its own (now invalidated) copy, which reads KV as if it held
+none. Without the option such a colo renders once for itself, unless the store
+uses `tagPurge`, which evicts those copies. With the option, a colo renders
+for itself only while KV still hands it the entry from before the invalidation,
+which it refuses: Cloudflare documents up to 60
+seconds for a KV write to spread. Await `updateTag()` before the warm: a
+write that started before an invalidation of one of its tags is refused.
 
 ### Limits worth knowing
 

package/skills/rango/SKILL.md

@@ -168,13 +168,16 @@ stated, greppable contract.
   only applies when the enclosing cache recomputes; put a value in a loader if it
   must be fresher. See `/cache-guide` → "Combining Both".
 - **A predicate runs where its effect lands.** A server-tree `revalidate()`
-  decides what the server re-sends, so it runs on the server; an `intercept({
+  and a `clientUrls()` loader's `revalidate()` decide what the server re-sends,
+  so they run on the server (the build hoists a group's predicate out of its
+  `"use client"` module and passes it the `urls()` arguments: `/client-urls`);
+  an `intercept({
 when })` selector decides what the server renders, so it runs on the server;
-  a `clientUrls()` `revalidate()` and `transition({ when })` decide a browser
-  commit, so they run in the browser. A browser predicate sees URLs, params,
-  route names, history state and action data, never `get()`, `env` or handler
-  state; in a server `urls()` it is written inline (the build hoists it into a
-  client module) or imported from a `"use client"` module (`/view-transitions`).
+  `transition({ when })` decides a browser commit, so it runs in the browser.
+  A `transition({ when })` predicate sees URLs, params, route names, history
+  state and action data, never `get()`, `env` or handler state; in a server
+  `urls()` it is written inline (the build hoists it into a client module) or
+  imported from a `"use client"` module (`/view-transitions`).
 - **Vocabulary.** `revalidate()` keeps React Router's `shouldRevalidate`
   dialect (`currentUrl`/`nextUrl`, `currentParams`/`nextParams`). Navigation
   selectors (`intercept({ when })`, `transition({ when })`) use `from`/`to`
@@ -270,6 +273,9 @@ the `path()` re-run; layouts and parallels above the route are skipped.
 revalidate((ctx) => (ctx.isAction(checkout) && ctx.actionResult?.ok) || undefined),
 ```
 
+The same `actionResult` idiom works in a `clientUrls()` group's loader
+`revalidate()`, which runs on the server with these arguments.
+
 **The source is the source of truth.** Structure, types, and update policy are
 visible and local in the tree — read top-down, no hidden global model to hold in
 your head. A snippet earns its place only if, from the code alone, you can answer:

package/skills/route/SKILL.md

@@ -238,6 +238,145 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 ])
 ```
 
+### `loading()` options
+
+`loading(fallback, options?)` takes two options:
+
+| Option            | Effect                                                                                                                      |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `ssr: false`      | Skip the fallback on document requests; it shows on client navigations only.                                                |
+| `prefetch: false` | Keep everything behind this fallback out of `<Link>` prefetches; the click shows the fallback and fetches that part itself. |
+
+```tsx
+path("/orders", OrdersPage, { name: "orders" }, () => [
+  loader(OrdersLoader),
+  loading(<OrdersSkeleton />, { prefetch: false }),
+]),
+```
+
+**What `prefetch: false` defers.** The flag applies when the entry is new to
+the browser: the page the prefetch is sent from does not show it. A prefetch
+then skips the entry's handler, its loaders, its orphan layouts and its
+parallel slots. On a `layout()` the fallback covers the whole outlet, so every
+deeper entry is skipped with it. A parallel slot with its own flagged
+`loading()` is a separate unit: the route beside it still renders in the
+prefetch. The prefetch payload carries a placeholder for each skipped piece,
+marked deferred, with its fallback: the page's skeleton.
+
+**An entry the browser already holds is never deferred.** Inside a section
+whose `layout()` has a flagged `loading()`, the layout is on screen, so its
+flag has no say: a prefetch of a sibling route renders that route's handler
+and loaders as usual, and the click sends no second request. The same goes for
+a same-route navigation (`/product/a` to `/product/b`). The rule behind it:
+a click that adopts a prefetch is never worse than the same click with no
+prefetch at all (two exceptions, under "Limits": a click before its
+prefetch has answered, and a flagged `layout()` entered from outside). It
+shows the next page, or its skeleton, at the click and never later than that
+plain navigation, the router adds no wait of its own, and it never replaces
+content that is on screen with a fallback. The deferred part arrives after
+the click and React reveals it as it reveals any streaming content: a read
+inside it can show its own fallback where the plain navigation showed the
+whole page a little later. For
+the same reason a prefetch that deferred something is used only on the page
+that made it: a page that already shows the entry makes its own prefetch,
+which defers nothing for it. To keep navigation _inside_ a section out of
+prefetches, flag the `loading()` of the routes in it:
+
+```tsx
+layout(AccountLayout, () => [
+  // From outside /account: the layout and the route below wait together.
+  loading(<AccountSkeleton />, { prefetch: false }),
+  // From another /account page: prefetched whole, the layout is on screen.
+  path("/account/profile", ProfilePage, { name: "account.profile" }),
+  // From another /account page: still deferred, by its own flag.
+  path("/account/orders", OrdersPage, { name: "account.orders" }, () => [
+    loader(OrdersLoader),
+    loading(<OrdersSkeleton />, { prefetch: false }),
+  ]),
+]),
+```
+
+**What the click looks like.** The click that adopts the prefetch commits at
+once: the URL changes, the prefetched content shows, and the fallback shows
+where the deferred part goes. The browser sends one second request (the fill)
+that runs only the deferred work. The page is built once, from the skeleton:
+the fill resolves what it is waiting for, and nothing on it is mounted a
+second time. The fill reads `cache()` and `"use cache"`
+as any request does; the prefetch read neither for the work it skipped. A hard
+load, a navigation with nothing prefetched, an action and back/forward run
+everything as before.
+
+**Under `transition()` the click commits with the fill.** A route with
+`transition()` commits in a transition: with no prefetch, React keeps the page
+being left until the response starts and then shows the new page with its
+fallback. A prefetched click to a flagged `loading()` on such a route does the
+same with its fill: the fallback shows with the fill's first chunk, as a plain
+click's shows with its response, not at the click. The same holds when the
+`transition()` is on something the fallback covers, such as a route under a
+flagged layout. Nothing changes at the click: `useNavigation()` reads
+`loading`, and the URL, the URL hooks and the page change together, fallback
+included, when the fill starts answering. So the click is the plain click's equal
+there, not ahead of it; what the prefetch saves is the rest of the page,
+which is not fetched again.
+(Shown with the click, the content could only arrive in a second commit,
+which under a `<ViewTransition>` runs a view transition of its own and delays
+the reveal.) `loader(Def, { prefetch: false })` on a `transition()` route is
+not affected: the page shows with the click.
+
+**Stored output is still served.** Under `cache()`, on a `ppr` route and for a
+`Prerender`/`Static` handler, the handler output is stored, so the prefetch
+looks it up, renders it and writes it exactly as before, hit or miss. Only the
+loaders behind the fallback are deferred: for a flagged `layout()` that is
+every loader below it, although the stored layout is served. The flag keeps
+the block's work, its loaders included, out of prefetches. See `/caching`,
+`/ppr` and `/prerender`.
+
+**Limits.**
+
+- A click before its prefetch has answered reuses that prefetch, waits for
+  it and then fetches the deferred part. The page shows no later than with no
+  prefetch; the deferred part can complete later, by up to what was left of
+  the prefetch. That is the price of keeping expensive or slow work out of
+  every prefetch, which is what the flag is for. See `/loader` →
+  "`prefetch: false`".
+- A navigation started before the fill answers cancels it, and `navigate()`
+  resolves only once the fill has answered. A newer navigation that ends
+  without replacing the page leaves the fallback up until the next one. See
+  `/loader` → "`prefetch: false`".
+- It needs a renderable fallback. `loading(false)` has nothing to show, so the
+  flag does nothing there. The last `loading()` on an entry wins, flag
+  included.
+- A loader behind the fallback cannot call `ctx.rendered()`; it throws on every
+  request kind. See `/loader` → "`prefetch: false`" for this and the other
+  loader limits (`ctx.set()` values, late `redirect()`/`notFound()`, a loader a
+  handler awaits).
+- A layout the client already holds is not deferred (its fallback would not
+  show). To keep navigation inside it out of prefetches, flag the route's own
+  `loading()`.
+- On a `layout()` entered from a page without it, the prefetch skips the
+  layout's own handler too. This is the one place where a prefetched click
+  shows a different page from a click with no prefetch, by design: it shows
+  the skeleton at once, over the layout's whole area, and the layout appears
+  once what its own `loading()` covers has arrived (the layout, its own
+  loaders, and the components below it with no `loading()` of their own), at
+  least React's 300 ms after the skeleton. A click with no prefetch, in a
+  production build, shows the layout with its first chunk and the fallback
+  inside it. The covered content is no later with the prefetch. A loader
+  below the layout streams as with no prefetch, and what is still pending
+  shows its fallback inside the layout: a route's own `loading()`, a
+  `<Suspense>` in its content, or, for a read with no boundary of its own,
+  the layout's own fallback a second time. React keeps that fallback up at
+  least 300 ms and holds the page's other reveals as long, so content that
+  would have shown sooner shows up to 300 ms later than with no prefetch.
+- An orphan layout's flagged `loading()` defers its loaders but not its
+  handler: the route's handler has already run by then.
+- `clientUrls()` routes and `intercept()` ignore the flag.
+
+To defer a single loader and keep the handler in the prefetch, use
+`loader(Def, { prefetch: false })` instead (see `/loader`).
+
+A `loading()` skeleton that has appeared stays at least about 300 ms before React reveals what replaces it (React's fallback throttle, [#1078](https://github.com/rangojs/rango/issues/1078)); see "Streaming with Suspense" in [loader](../loader/SKILL.md).
+
 ## Handler Data Ownership
 
 When a route has children (orphan layouts, parallels), the handler executes

package/skills/testing/SKILL.md

@@ -97,7 +97,7 @@ Each primitive links to its sub-file (API + recipe + caveats).
 | one middleware's ordering / short-circuit / cookie+header merge                                                                    | unit (node)  | [`runMiddleware`](./middleware.md)                                                                                    | `@rangojs/router/testing`        |
 | a `"use server"` action's cookie / header / flash output (even on `throw redirect()`)                                              | unit (node)  | [`runInRequestContext`](./server-actions.md)                                                                          | `@rangojs/router/testing`        |
 | a `transition({ when })` browser predicate against `{ kind, from, to, action }`                                                    | unit (node)  | [`runTransitionWhen`](./predicates.md) (`{ applied, gatedOff, context }`)                                             | `@rangojs/router/testing`        |
-| a `clientUrls()` `revalidate()` / `isAction(ref)` predicate                                                                        | unit (node)  | [`runClientRevalidate`](./predicates.md) (production chain evaluator + locked defaults)                               | `@rangojs/router/testing`        |
+| a `revalidate()` / `isAction(ref)` predicate, `urls()` or `clientUrls()`                                                           | unit (node)  | [`runRevalidate`](./predicates.md) (production `evaluateRevalidation`, async)                                         | `@rangojs/router/testing`        |
 | a handle's `collect`/accumulator, a seeded handle read, or a loader handle write                                                   | unit         | [`collectHandle` / seeded `handles` / `handlePushes`](./handles.md)                                                   | `@rangojs/router/testing`        |
 | a CLIENT component reading router context (`useParams`/`useReverse`/`Outlet`/`useNavigation`/`useLoader`)                          | unit (DOM)   | [`renderRoute`](./client-components.md)                                                                               | `@rangojs/router/testing/dom`    |
 | a stale indicator from `useLoader().isLoading` while a `transition()` navigation re-runs the loader                                | unit (DOM)   | [`renderRoute` + `navigate(url, { loaders })`](./client-components.md#held-navigation)                                | `@rangojs/router/testing/dom`    |
@@ -116,6 +116,7 @@ Each primitive links to its sub-file (API + recipe + caveats).
 | cache hit/miss/stale, prerender (= a cache hit by design)                                                                          | e2e + signal | [`assertCacheStatus` (header) / `assertCacheDecision` (telemetry sink)](./cache-prerender.md)                         | `@rangojs/router/testing[/e2e]`  |
 | a `ppr` route's shell: MISS -> capture -> HIT, what the shell froze vs what a HIT renders live, tag eviction, navigation replay    | RSC unit     | [`serveShellRequest`](./serve-shell-request.md)                                                                       | `@rangojs/router/testing/flight` |
 | a form submitted before hydration: a `useActionState` result the no-JS POST renders, the form state its payload carries            | RSC unit     | [`createActionForm` + `serveShellRequest({ form })`](./serve-shell-request.md)                                        | `@rangojs/router/testing/flight` |
+| a JS server action call: the segments it re-renders, what `revalidate()` sees on it                                                | RSC unit     | [`serveShellRequest({ action })`](./serve-shell-request.md#a-server-action-called-from-the-page)                      | `@rangojs/router/testing/flight` |
 | PPR shell HIT/MISS in real HTML (`ppr` path option), shell store key / getShell after flush                                        | e2e + signal | [`assertShellStatus` / `shellCacheKey` + store](./cache-prerender.md#ppr-shell-and-navigation-replay)                 | `@rangojs/router/testing[/e2e]`  |
 | generated route map drift vs runtime                                                                                               | unit (node)  | [`assertGeneratedRoutesMatch`](./reverse-and-types.md)                                                                | `@rangojs/router/testing`        |
 | a platform binding (`env.DB` / Durable Object / `env.R2`)                                                                          | unit/integr. | [your own double via `env`](./bindings.md)                                                                            | (any primitive's `env` option)   |
@@ -147,7 +148,7 @@ beside their function):
 | `@rangojs/router/testing`                 | `runLoader`, `runLoaderResult`                                                                                                                               | [`loader.md`](./loader.md)                           |
 |                                           | `runMiddleware`                                                                                                                                              | [`middleware.md`](./middleware.md)                   |
 |                                           | `runInRequestContext`, `createTestRequestContext`, `runWithRequestContext`, `toRequest`, `seedVariables`                                                     | [`server-actions.md`](./server-actions.md)           |
-|                                           | `runTransitionWhen`, `runClientRevalidate`                                                                                                                   | [`predicates.md`](./predicates.md)                   |
+|                                           | `runTransitionWhen`, `runRevalidate`                                                                                                                         | [`predicates.md`](./predicates.md)                   |
 |                                           | `collectHandle`                                                                                                                                              | [`handles.md`](./handles.md)                         |
 |                                           | `withLocationStateKey`                                                                                                                                       | [`client-components.md`](./client-components.md)     |
 |                                           | `dispatch`                                                                                                                                                   | [`response-routes.md`](./response-routes.md)         |

package/skills/testing/client-components.md

@@ -299,7 +299,7 @@ it("hydrates as the server rendered it, then shows the stored count", async () =
 | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `typeof window` / `typeof document` in render                                         | `"undefined"` in the server pass: both globals are removed for it and restored before hydration. A branch renders its server side; if the client side differs, React reports the mismatch.                                                   |
 | An unguarded `window.x` / `document.x` in render                                      | Throws `ReferenceError` in the server pass, as in SSR. Inside a `<Suspense>` the boundary is client-rendered and reported; outside one `renderRoute` rejects.                                                                                |
-| `useSyncExternalStore`                                                                | The server pass and the hydration render read `getServerSnapshot`; the render after it reads `getSnapshot`.                                                                                                                                  |
+| Hydration adopts the server HTML                                                      | `hydrateRoot` adopts the server-rendered DOM nodes instead of replacing them, and `recoverableErrors` stays empty; a client render of the same tree would replace the nodes.                                                                 |
 | A text or element mismatch                                                            | React re-renders that tree on the client and reports it: `recoverableErrors` gets `"Hydration failed because ..."` with the diff.                                                                                                            |
 | An attribute-only mismatch (`className`, `href`)                                      | NOT in `recoverableErrors`. React keeps the server attribute and logs `console.error` in development; assert it with `vi.spyOn(console, "error")`.                                                                                           |
 | `<Suspense>` whose content renders synchronously                                      | In `serverHtml`. It hydrates in a later pass than the tree above it, after that tree's effects, before `renderRoute` resolves.                                                                                                               |

package/skills/testing/predicates.md

@@ -1,8 +1,8 @@
-# Testing navigation predicates — runTransitionWhen, runClientRevalidate
+# Testing navigation predicates — runTransitionWhen, runRevalidate
 
-**Layer:** unit (node) · **Import:** `@rangojs/router/testing` · **DSL it tests:** `transition({ when })` (see `/view-transitions`) and `clientUrls()` `revalidate()` (see `/client-urls`)
+**Layer:** unit (node) · **Import:** `@rangojs/router/testing` · **DSL it tests:** `transition({ when })` (see `/view-transitions`) and `revalidate()` in `urls()` and in `clientUrls()` (see `/client-urls`)
 
-Both primitives are synchronous and run the router's own evaluation code on arguments you seed, so a predicate sees the same fields it sees at runtime. Neither renders anything: they answer "would this navigation hold?" and "would this `clientUrls()` loader re-run?". Both predicates run in the browser at runtime.
+Both primitives run the router's own evaluation code on arguments you seed, so a predicate sees the same fields it sees at runtime. Neither renders anything: they answer "would this navigation hold?" and "would this loader re-run?". `runTransitionWhen` is synchronous; `runRevalidate` returns a Promise. A `transition({ when })` predicate runs in the browser at runtime; a `revalidate()` predicate runs on the server, a `clientUrls()` loader's included (the build moves it there).
 
 ## runTransitionWhen(when | config, opts?)
 
@@ -12,12 +12,12 @@ Builds the `TransitionWhenContext` the browser builds and evaluates the predicat
 
 Every field is optional. A location (`from` / `to`) is a URL string, a `URL`, or a partial `RouteLocation`: `{ url?, params?, routeName?, state? }`. A `state` given as location-state entries (`[Def(value)]`, what `Link` and `router.push` take) is stored the way a push stores it, so `Def.read(ctx.to)` reads it back; any other value is used as the raw `history.state`.
 
-| Field    | Type                                                              | Meaning                                                                                                                                                                       |
-| -------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `kind`   | `"push" \| "replace" \| "pop" \| "action" \| "revalidate"`        | Defaults to `"action"` when `action` is given, `"push"` otherwise.                                                                                                            |
-| `from`   | location                                                          | The committed location being left. Defaults to `http://localhost/`.                                                                                                           |
-| `to`     | location                                                          | The destination. Defaults to `from`; always `from` for `"action"` and `"revalidate"`.                                                                                         |
-| `action` | imported action \| `string` \| `{ ref, formData, result, error }` | The triggering action (`isAction()` matches it; `action.id` is its id). Like `runClientRevalidate`, an imported action outside a built app needs its id passed as the string. |
+| Field    | Type                                                              | Meaning                                                                                                                                                                 |
+| -------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `kind`   | `"push" \| "replace" \| "pop" \| "action" \| "revalidate"`        | Defaults to `"action"` when `action` is given, `"push"` otherwise.                                                                                                      |
+| `from`   | location                                                          | The committed location being left. Defaults to `http://localhost/`.                                                                                                     |
+| `to`     | location                                                          | The destination. Defaults to `from`; always `from` for `"action"` and `"revalidate"`.                                                                                   |
+| `action` | imported action \| `string` \| `{ ref, formData, result, error }` | The triggering action (`isAction()` matches it; `action.id` is its id). Like `runRevalidate`, an imported action outside a built app needs its id passed as the string. |
 
 ### Returns — `RunTransitionWhenResult`
 
@@ -62,57 +62,92 @@ it("animates unless the Link pushed { animate: false }", () => {
 - A Vitest project runs neither the Vite plugin's hoist nor its validation. An inline `when` in a `urls()` file stays a plain function there, and a `"use client"` import is the plain function outside the RSC graph, so a server function is not told apart and is accepted. The loud error for an invalid `when` belongs to dev startup, the build and HMR.
 - `renderRoute` decides each commit with production's decision code: `router.navigate()` (and `useRouter().push/replace`, `<Link>`) as `kind: "push"` / `"replace"`, `router.refresh()` as `kind: "revalidate"`, and `navigate(url, { transition: false })` without calling the predicate. Pop, action and `clientUrls()` optimistic-swap decisions are e2e territory.
 
-## runClientRevalidate(fn | fn[], opts?)
+## runRevalidate(fn | fn[], opts?)
 
-Evaluates one `clientUrls()` loader `revalidate()` predicate, or a chain in declaration order, through the production chain evaluator: the locked default, boolean short-circuit, soft verdicts (`{ defaultShouldRevalidate }`), and a throwing predicate deferring to the default all behave as in the browser. Returns the final `boolean` (the locked default when every predicate defers or throws).
+Evaluates one `revalidate()` predicate, or a chain in declaration order, through the router's production `evaluateRevalidation` inside a seeded request context. It serves `urls()` and `clientUrls()` predicates alike: a `clientUrls()` loader's predicate runs on the server with the `urls()` arguments, so the argument object (`currentParams`, `currentUrl`, `nextParams`, `nextUrl`, `defaultShouldRevalidate`, `context`, `segmentType`, `actionId`, `isAction`, `actionUrl`, `actionResult`, `formData`, `method`, `routeName`/`fromRouteName`/`toRouteName`, `stale`) is the production one. Returns `Promise<boolean>`: the final decision (true re-runs the segment). The locked default, boolean short-circuit and soft verdicts are the production code paths. A throwing predicate fails open to the default (logged with `console.error`); a thrown `Response` is rethrown.
 
-### Options — `RunClientRevalidateOptions`
+### Options — `RunRevalidateOptions`
 
-Defaults model a same-URL navigation with no action.
+Defaults model a same-URL navigation with no action, for a route-owned loader: a predicate that defers resolves `false`, and with an `action` it resolves `true`.
 
-| Field           | Type                             | Meaning                                                                                                                                                                                         |
-| --------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `currentUrl`    | `string \| URL`                  | Source URL. Defaults to `http://localhost/`.                                                                                                                                                    |
-| `nextUrl`       | `string \| URL`                  | Target URL. Defaults to `currentUrl`.                                                                                                                                                           |
-| `currentParams` | `Record<string, string>`         | Source params. Defaults to `{}`.                                                                                                                                                                |
-| `nextParams`    | `Record<string, string>`         | Target params. Defaults to `currentParams`.                                                                                                                                                     |
-| `stale`         | `boolean`                        | The `stale` arg. Defaults to `false`.                                                                                                                                                           |
-| `action`        | `(...args) => unknown \| string` | The triggering action: one imported server action (its id is read from the build-injected `$id`/`$$id`) or a raw action id string. A namespace object is rejected. Omit for a plain navigation. |
-| `actionRequest` | `boolean`                        | Model the action-triggered refetch GET: `isAction()` stays true but the locked default is the navigation default. Defaults to treating `action` as the action POST itself.                      |
+| Field            | Type                                                            | Meaning                                                                                                                                                                                                                     |
+| ---------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `currentUrl`     | `string \| URL`                                                 | The page being left. Defaults to `http://localhost/`.                                                                                                                                                                       |
+| `nextUrl`        | `string \| URL`                                                 | The destination. Defaults to `currentUrl`.                                                                                                                                                                                  |
+| `currentParams`  | `Record<string, string>`                                        | Source params. Defaults to `{}`.                                                                                                                                                                                            |
+| `nextParams`     | `Record<string, string>`                                        | Target params. Defaults to `currentParams`.                                                                                                                                                                                 |
+| `action`         | imported action \| `string` \| `{ ref, result, formData, url }` | The triggering action. `ref` is an imported server action (its id is read from `$id ?? $$id`) or an action id string; `result` is `actionResult`, `formData` is `formData`, `url` is `actionUrl`. Makes the request a POST. |
+| `method`         | `string`                                                        | Overrides the request method (`POST` with an `action`, otherwise `GET`).                                                                                                                                                    |
+| `segmentType`    | `"layout" \| "route" \| "parallel" \| "loader"`                 | The segment type the predicate is attached to. Defaults to `"loader"`.                                                                                                                                                      |
+| `belongsToRoute` | `boolean`                                                       | Defaults to `true`; `false` models a layout's loader, which a navigation keeps by default.                                                                                                                                  |
+| `stale`          | `boolean`                                                       | The `stale` arg (a history-entry background revalidation). Defaults to `false`.                                                                                                                                             |
+| `routeName`      | `string`                                                        | `toRouteName` (and `routeName`).                                                                                                                                                                                            |
+| `fromRouteName`  | `string`                                                        | `fromRouteName`.                                                                                                                                                                                                            |
+| `env`            | `TEnv`                                                          | Environment bindings of the seeded context.                                                                                                                                                                                 |
+| `vars`           | `VarsInit`                                                      | Variables a middleware would have set, readable with `context.get()`.                                                                                                                                                       |
+| `context`        | the predicate's `context`                                       | Replaces the seeded context.                                                                                                                                                                                                |
 
-Outside a built app, an imported action carries no id, so pass the id string your predicate matches (for example `"src/actions/cart.ts#addToCart"`); `runClientRevalidate` throws a clear error otherwise.
+Outside a built app, an imported action carries no `$id`: pass the id string your predicate matches (for example `"src/actions/cart.ts#addToCart"`), or stamp `$id` on the imported function in the test (`Object.assign(addToCart, { $id: "src/actions/cart.ts#addToCart" })`); `runRevalidate` throws a clear error otherwise.
 
 ### Recipe
 
+The build moves a `clientUrls()` predicate to the server and accepts only imports and globals in it, so keep a predicate you want to test in its own module without `"use client"` and import it both in the group and here. Vitest does not run the plugin, so there the predicate is a plain function. To run it through the real handler instead, mount the group in the Flight project with `rangoUseClientTransform()` wired, and send a `serveShellRequest` navigation or `action` request ([`./serve-shell-request.md`](./serve-shell-request.md)).
+
 ```ts
-import { it, expect } from "vitest";
-import { runClientRevalidate } from "@rangojs/router/testing";
-import type { ClientRevalidateFn } from "@rangojs/router/client";
+// src/predicates.ts — no "use client"
+import type { ShouldRevalidateFn } from "@rangojs/router";
+import { checkout } from "./actions/cart.js";
 
-const onlyOnTabChange: ClientRevalidateFn = ({ currentUrl, nextUrl }) =>
+export const onTabChange: ShouldRevalidateFn = ({ currentUrl, nextUrl }) =>
   currentUrl.searchParams.get("tab") !== nextUrl.searchParams.get("tab");
 
-it("revalidates only when the tab changes", () => {
+export const onCheckoutOk: ShouldRevalidateFn = (ctx) =>
+  ctx.isAction(checkout) ? ctx.actionResult?.ok === true : undefined;
+```
+
+```ts
+import { it, expect } from "vitest";
+import { runRevalidate } from "@rangojs/router/testing";
+import { checkout } from "../src/actions/cart.js";
+import { onTabChange, onCheckoutOk } from "../src/predicates.js";
+
+// The build stamps a "use server" export with its id; Vitest does not.
+Object.assign(checkout, { $id: "src/actions/cart.ts#checkout" });
+
+it("revalidates only when the tab changes", async () => {
   expect(
-    runClientRevalidate(onlyOnTabChange, {
+    await runRevalidate(onTabChange, {
       currentUrl: "/settings?tab=profile",
       nextUrl: "/settings?tab=billing",
     }),
   ).toBe(true);
   expect(
-    runClientRevalidate(onlyOnTabChange, {
+    await runRevalidate(onTabChange, {
       currentUrl: "/settings?tab=profile",
       nextUrl: "/settings?tab=profile&sort=asc",
     }),
   ).toBe(false);
 });
+
+it("re-runs after checkout only when it succeeded", async () => {
+  expect(
+    await runRevalidate(onCheckoutOk, {
+      action: { ref: checkout, result: { ok: true } },
+    }),
+  ).toBe(true);
+  expect(
+    await runRevalidate(onCheckoutOk, {
+      action: { ref: checkout, result: { ok: false } },
+    }),
+  ).toBe(false);
+});
 ```
 
 ## Caveats
 
-- Server-tree `revalidate()` predicates have no dedicated primitive: they are plain functions, so call them with a hand-built args object, or assert the post-action result at e2e.
+- `runRevalidate` proves the predicate's decision, not the build: the hoist's rules (imports and globals only, no browser globals) are checked by the Vite plugin at dev startup and build, not in Vitest. Assert the post-action result of a real group at e2e.
 - `runTransitionWhen` proves the decision only. Whether the browser actually runs a view transition is e2e territory (see `./e2e-parity.md`).
-- Both are synchronous; a predicate returning a Promise is a bug in the predicate, not something to await here.
+- `runTransitionWhen` is synchronous. `runRevalidate` returns a Promise because it awaits the router's `evaluateRevalidation`, but a predicate itself must be synchronous: one returning a Promise is a bug in the predicate (the router keeps the default and warns in development), and the `clientUrls()` build rejects an `async` one.
 
 ## See also