@rangojs/router 0.24.3 → 0.25.0

package/skills/middleware/SKILL.md

@@ -59,7 +59,9 @@ only between a route handler and its child/orphan layouts and parallels (so
 their latency overlaps rendering rather than blocking it. See `/loader` →
 "Parallel and streaming".
 
-The contract is: **route middleware wraps rendering regardless of transport** (JS-enabled RSC stream or no-JS HTML). During PE re-render, route middleware observes action-set state (cookies, context variables) the same way it does during JS-enabled post-action revalidation.
+The contract is: **route middleware wraps rendering regardless of transport** (JS-enabled RSC stream or no-JS HTML). During PE re-render, route middleware observes action-set state (cookies, context variables) the same way it does during JS-enabled post-action revalidation. When the action throws, the `errorBoundary()` render is wrapped too, in both transports: the boundary reads the middleware's `ctx.set()` values and the response carries its headers.
+
+Around the render after an action, route middleware's `ctx.request` is the page's GET: `method` is `"GET"`, with no body, and the headers are the POST's without `content-type` and `content-length`. It decides as it would for a GET of the page. Global middleware, which wraps the action, sees the POST, and so does `getRequestContext().request`. So a method check in route middleware never sees the mutation: it cannot block or answer one, since the action already ran. A header its GET branch sets also lands on the action's response. If a header must stay off mutation responses (a public `Cache-Control`), set it from global middleware.
 
 Revalidation is still partial. Route middleware wraps the render pass that
 does happen, but it does not force unrelated outer segments to recompute.
@@ -256,7 +258,7 @@ export const myMiddleware: Middleware = async (ctx, next) => {
   ctx.header("X-Frame-Options", "DENY"); // set one response header
   ctx.headers; // response Headers (stub before next(), the real response after)
   ctx.setLocationState(FlashMessage({ text: "Saved" })); // history state for the client
-  ctx.reverse("home"); // URL for a global route name (no ".name", no param auto-fill)
+  ctx.reverse("home"); // URL for a global route name (no ".name", no param auto-fill; a missing required param throws)
   ctx.rewrittenFrom; // the visitor's URL when this request was rewritten, else undefined
   ctx.isRewrite(error); // true for a thrown rewrite() (rethrow it from a try/catch)
 
@@ -442,8 +444,10 @@ import type { Middleware } from "@rangojs/router";
 
 export const maintenance: Middleware = async (ctx, next) => {
   if (!locked || ctx.pathname === "/maintenance") return next();
-  // Mutations get a Response: a rewrite cannot answer a server action or a form post.
-  if (ctx.request.method !== "GET") {
+  // A rewrite moves a server action or form post to its target, where the
+  // action runs. A lock answers mutations itself, so none runs under
+  // maintenance. HEAD rewrites like GET, as under .disallowMutations().
+  if (ctx.request.method !== "GET" && ctx.request.method !== "HEAD") {
     return new Response("Maintenance", {
       status: 503,
       headers: { "Retry-After": "600" },
@@ -463,6 +467,16 @@ path("/maintenance", MaintenancePage, { name: "maintenance" }, () => [
 ]);
 ```
 
+Without the `Response` branch, `.disallowMutations()` keeps a lock from
+running mutations: a server action or form post under it is an error before
+the action runs (a 500 the client shows as an error, reported through
+`onError` with phase `"routing"`), and GET and HEAD rewrite as usual. The
+`Response` above gives the caller a proper 503 instead.
+
+```typescript
+throw rewrite("maintenance").disallowMutations();
+```
+
 Targets, like `ctx.reverse` with a path form:
 
 ```typescript
@@ -519,7 +533,9 @@ carries `x-rango-rewrite: <target pathname>`.
 inside a `cache()` boundary or a `"use cache"` function throws (pass what
 you need in from middleware), and a render other visitors may be served (a
 PPR shell capture, a page the document cache stores) reads `undefined`, as a
-direct visit does.
+direct visit does. A shell keyed by the visitor's URL
+(`rewrite(...).shell("visitor")`, see Caches) reads it, since its key covers
+that URL.
 
 **Middleware only, by design.** `rewrite()` is a middleware tool. A route
 handler or a loader (any loader, `ssr: false` included) cannot rewrite: its
@@ -540,12 +556,59 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 ]);
 ```
 
+**Mutations: where the middleware sits decides.** A server action or a no-JS
+form post from a rewritten page is posted to the visitor's URL, so the same
+middleware sees it:
+
+- **Global middleware** on the visitor's URL runs before the action. A
+  rewrite there moves the mutation to the target first, with its body: the
+  target's global middleware, then the action, once, then the target's
+  route middleware and render, as a direct post to the target. So a
+  routing rewrite (a multi-tenant host, an A/B split, a visitor URL with no
+  route) keeps its page's forms working, in JS and no-JS. Rewrite every
+  method: a rewrite written for GETs only leaves the mutation on the
+  visitor's URL, so the action runs on the visitor's route and its render
+  replaces the page. A lock must not run the mutation: return a `Response`
+  for mutations, or throw `rewrite(...).disallowMutations()`, which refuses
+  it with an error before the action runs. It chains with `.shell()` in
+  either order.
+- **Route middleware** runs after the action, around the re-render, and
+  sees it as the page's GET. A routing rewrite there (A/B, URL override,
+  the `discontinued` example above) fires as on a GET, including one
+  written for GETs only (`if (ctx.request.method !== "GET") return next()`).
+  The action runs once, then the re-render runs as the target (its global
+  and route middleware, its render, or its error boundary when the action
+  threw), and the page keeps its layout and state. Route middleware cannot
+  refuse the action, so `.disallowMutations()` has no effect there: the
+  render moves to the target, dev logs a warning on each throw, and
+  production logs one `console.error`. Put a lock in global middleware.
+- Global middleware on the target's pass sees the POST, with its headers.
+  A no-JS form post keeps its body, so a form-field check (a CSRF token
+  read from `ctx.request.clone().formData()`) passes on every pass, and so
+  does a mutation a global rewrite moved before its action, whose action
+  runs on the target's pass: do not skip a body check when
+  `ctx.rewrittenFrom` is set. Always read a clone; a rewrite after middleware
+  read the body itself is an error, since the action would get no
+  arguments. After a route-middleware rewrite, a JS action's body is gone
+  (the action read it), and that pass drops the `content-type` too, so a
+  body check gated on the content-type passes over it; that pass never runs
+  the action. Global middleware runs once per pass, as for any rewrite, so a
+  one-time token belongs in the action. An action's target must be a page
+  route: a rewrite that sends a server action or form post that already ran,
+  or a JS action before it runs, to a response route (`path.json()`) or a
+  path that redirects is an error. A plain POST a global rewrite moves
+  reaches a response route with its body, as a direct post would, and so
+  does a no-JS form post, whose action the router finds only on a page
+  route.
+
 **Throw it, don't return it.** A returned rewrite is an error. Where a
 rewrite cannot be honored it is an error that names the rule: a route
 handler or a loader (see above), a server action (use `redirect()`),
-intercept middleware, a loader fetch (`useFetchLoader`, `load()`: it
-rejects with the rule) or its middleware, and middleware handling a non-GET
-request (a JS action or a no-JS form post: return a `Response`).
+a loader fetch (`useFetchLoader`, `load()`: it
+rejects with the rule) or its middleware. A `.disallowMutations()` rewrite
+from global middleware handling a non-GET, non-HEAD request (a JS action or
+a no-JS form post) is an error too, by your choice: it reads
+`rewrite("…") refused a mutation: .disallowMutations() was set`.
 
 **try/catch around next().** A thrown rewrite passes through your
 middleware's `catch`. Rethrow it:
@@ -570,12 +633,26 @@ the trail, `/a -> /b -> /a`) through `onError` with phase `"routing"`.
 - The document cache keys a rewritten request by the target's URL, as a
   direct visit. Register the rewriting middleware **before**
   `createDocumentCacheMiddleware()`: a cache hit for the visitor's URL would
-  be served before your middleware runs. A page the document cache stores,
-  and a PPR shell of the target, are rendered as a direct visit to the
-  target: they carry the target's pathname and `ctx.rewrittenFrom` is
-  `undefined` there, so a component that renders `usePathname()` can
-  mismatch on hydration at the visitor's URL when such a page is served to
-  a rewritten request.
+  be served before your middleware runs. A page the document cache stores
+  is rendered as a direct visit to the target: it carries the target's
+  pathname and `ctx.rewrittenFrom` is `undefined` there, so a component that
+  renders `usePathname()` can mismatch on hydration at the visitor's URL
+  when such a page is served to a rewritten request.
+- A PPR shell (`ppr` target) is read and written only by requests on its
+  URL. A rewritten request renders live at the visitor's URL, and a direct
+  visit captures the target's shell, so values you set before the throw
+  never reach it. Pick a shell for the rewritten request with `.shell()` on
+  the thrown value: `"visitor"` keys a shell by the visitor's URL, captured
+  with the visitor's location and `ctx.rewrittenFrom` (one shell per public
+  URL, the right choice for a routing catch-all); `"target"` reads and
+  captures the target's shared shell, which shows the target's URL to the
+  visitor on a HIT and bakes in what the rewriting middleware set, so keep it
+  for a lock or promo page that renders neither:
+
+  ```typescript
+  throw rewrite("item", { id }).shell("visitor");
+  ```
+
 - The client's prefetch and history caches keep a rewritten page under the
   visitor's URL, and nothing tells them about the rewrite: a page prefetched
   during a lock shows the lock page for up to `prefetchCacheTTL` after the
@@ -600,10 +677,29 @@ the trail, `/a -> /b -> /a`) through `onError` with phase `"routing"`.
   };
   ```
 
+**Navigating from a rewritten page.** A navigation, prefetch or action from
+the page diffs against the route that rendered it, as one from a direct
+visit does: the payload carries the target (`metadata.rewriteTarget`), and
+the browser sends it back with the next request from that page. A
+`revalidate()` sees the target's params and URL (`currentParams.id` against
+`nextParams.id` holds a loader on a sort change), and a navigation to the
+page already shown re-renders nothing. A move to another visitor URL with
+the same target (`/promo/a` to `/promo/b`, both rewritten to
+`/promo/landing`) re-runs the route and its loaders, which may read
+`ctx.rewrittenFrom`. The browser only names the page being left: what
+renders still comes from the request's URL and your middleware.
+
 **Testing.** `runMiddleware` reports a thrown rewrite as `result.rewrite`
-(`{ pathname, search, routeName? }`). `serveShellRequest` takes a rewritten
+(`{ pathname, search, routeName?, mutationsDisallowed? }`, the last `true`
+only for `.disallowMutations()`). `serveShellRequest` takes a rewritten
 page request through the full production pipeline (document or `partial`
 navigation): the target's middleware, render, status and `x-rango-rewrite`.
+Pass the page's `metadata.rewriteTarget` as `partial.rewriteTarget` (or
+`action.rewriteTarget`) to send a request from it as the browser does.
+With `action` or `form` (from `createActionForm`) it posts a mutation to the
+visitor's URL, so a global rewrite's move, a `.disallowMutations()` refusal
+(it rejects with the refusal) and a route-middleware rewrite's re-render are
+testable too.
 `dispatch` re-dispatches too, for response routes only: it matches the
 visitor's URL first and throws on a component (RSC) route.
 `renderRoute(..., { request: "/shop", rewrite: "/maintenance" })` renders

package/skills/observability/SKILL.md

@@ -302,6 +302,17 @@ Then inspect:
   first paint.
 - the `Server-Timing` header to compare local logs with browser-network timing.
 
+## Telling a page is a Rango app
+
+Every page sets `window.__rango = { version }` (frozen, one key) from the
+bundled client entry before hydration. `version` is the exact npm semver of
+`@rangojs/router`, nothing else: no build hash, router id or config. It is for
+devtools and support; the router never reads it and no option turns it off.
+
+```js
+window.__rango; // { version: "0.24.2" }
+```
+
 ## Zero-overhead defaults
 
 `debugPerformance` is off by default, `telemetry` emits nothing unless a sink

package/skills/parallel/SKILL.md

@@ -206,9 +206,9 @@ parallel(
   () => [
     // The loader keeps its own revalidation: by default it re-runs after
     // every action. Scope it here to stop that.
-    loader(CategoriesLoader, () => [revalidate(() => false)]),
+    loader(CategoriesLoader, () => [revalidate(false)]),
     loading(<SidebarSkeleton />),
-    revalidate(() => false), // the slot component renders once, then is kept
+    revalidate(false), // the slot component renders once, then is kept
   ]
 )
 ```
@@ -430,7 +430,7 @@ boundary above it: the route's `loading()`, replacing the entire route content
 with the route skeleton while one slot refetches. Either scope the slot's
 `revalidate()` (share the route's named contract, as above) or give the slot
 its own `loading()` so the fallback stays local. Don't reach for a bare
-`revalidate(() => false)`: the slot then never refreshes on param changes
+`revalidate(false)`: the slot then never refreshes on param changes
 either, and keeps the previous param's content on e.g. a product-to-product
 navigation.
 
@@ -438,7 +438,7 @@ navigation.
 it the first time. A slot the browser has not rendered yet has nothing to keep
 showing, so on that first render the decision is clamped to `true` and your
 callback's `false` is ignored; from then on it is honored and the browser keeps
-the copy it already has. So `revalidate(() => false)` means "render once, then
+the copy it already has. So `revalidate(false)` means "render once, then
 never re-render", never "don't appear".
 
 Revalidate callbacks must be synchronous. A callback that returns a Promise is
@@ -565,7 +565,7 @@ export const shopPatterns = urls(({
       { "@sidebar": () => <CategorySidebar /> },
       () => [
         loader(CategoriesLoader),
-        revalidate(() => false),
+        revalidate(false),
       ]
     ),
 

package/skills/ppr/SKILL.md

@@ -151,12 +151,42 @@ cache miss (no shell).
 
 ### A request middleware rewrote
 
-A request middleware rewrote (`throw rewrite()`, `/middleware`) to a `ppr`
-route is served the target's shell under the target's key. The capture
-renders the target as a direct visit: `ctx.rewrittenFrom` reads `undefined`
-there and the payload carries the target's pathname, so the shell is the
-same for direct and rewritten visitors (a component that renders
-`usePathname()` shows the target's URL to a rewritten visitor on a HIT).
+A URL's shared shell is read and written only by requests on that URL. A
+request middleware rewrote (`throw rewrite()`, `/middleware`) to a `ppr` route
+neither reads the target's shell nor captures it: it renders live, at the
+visitor's location (`usePathname()`, `ctx.rewrittenFrom`), on every request.
+The target's shell is captured by a direct visit or a `router.prerender()` warm
+of the target's URL, so nothing a rewriting middleware set (a variable, the
+visitor's URL) ends up in the shell every direct visitor gets.
+
+The rewrite chooses a shell for the rewritten request with `.shell()`:
+
+```ts
+// A routing catch-all: each public URL gets a shell of its own.
+throw rewrite("item", { id }).shell("visitor");
+
+// A lock or promo page that renders nothing of the visitor's URL. A lock
+// also refuses mutations, which a rewrite otherwise moves to the target.
+throw rewrite("maintenance").shell("target").disallowMutations();
+```
+
+- `.shell("visitor")` keys the shell by the visitor's URL and the target
+  (`visitorShellCacheKey(router, "/summer", "/item/1")` in a test; the target
+  route's `cache.searchParams` filter and its own partition apply). The
+  capture renders the visitor's location and `ctx.rewrittenFrom`, and a
+  variable set before the throw may be baked in, since the key covers the URL
+  it came from. Navigation replay uses the same key. A build shell of the
+  target is never served to it. Store growth is one shell per public URL;
+  `updateTag()` reaches every one of them through the shell's tags.
+- `.shell("target")` reads and captures the target's shared shell from the
+  rewritten request. The shell then shows the target's URL to a rewritten
+  visitor on a HIT (`usePathname()` hydrates against the address bar, so a
+  component that renders it mismatches), and a variable set before the throw
+  is baked into the shell direct visitors get. Use it only for a page that
+  renders neither.
+
+A rewritten navigation without `.shell()` reports
+`x-rango-ppr-replay: BYPASS; reason=rewritten`.
 
 ### Request-partitioned shells
 
@@ -1299,7 +1329,10 @@ shell-cache only public/shared pages, keep per-user content in live-lane
 loaders (no `ssr: false`) or nested promises in bake-lane loader data — NOT in
 handler output or plain bake-lane container data — mark the variable
 `{ cache: false }` so a stray shell read refuses the capture, or key per
-variant at the CDN tier.
+variant at the CDN tier. A variable a middleware sets before `throw rewrite()`
+never reaches the target's shared shell: a rewritten request captures none
+unless its rewrite opts in with `.shell("target")` (see "A request middleware
+rewrote"); with `.shell("visitor")` it lands only in that URL's own shell.
 
 ## What always renders without a shell
 
@@ -1307,7 +1340,9 @@ Non-GET, non-partial RSC/action/loader fetches, partial requests without an
 eligible captured segment snapshot, per-request CSP nonce, `streamMode:
 "allReady"`, redirects, 404s, error renders, routes without `ppr`, a document
 request the route's own `cache()` scope refuses (`cache(false)`, or a
-`condition()` returning false for it), and any store without the shell family.
+`condition()` returning false for it), a request middleware rewrote whose
+rewrite chose no shell (`rewrite(...).shell()`), and any store without the
+shell family.
 A stored shell is invalidated when
 `React.version` changes (postponed state is build-coupled) or when the router's
 document version changes, so a deploy that changes the router self-heals via

package/skills/prerender/SKILL.md

@@ -1020,8 +1020,7 @@ in dev. A removed page is the exception: its marker answers 404 in dev too.
   that only a refresh produced.
 - **Connected clients can lag.** A refresh has no response to reach open tabs:
   a client that prefetched the page keeps its copy for `prefetchCacheTTL`
-  (default 300s) and the browser HTTP cache (`prefetchCacheControl`). Lower
-  them if the window matters.
+  (default 300s, in memory only). Lower it if the window matters.
 - **Entries are per deploy.** Keys carry the router's data version, so a deploy
   that changes server code starts from the build entries again; a client-only
   deploy keeps refreshed pages.

package/skills/rango/SKILL.md

@@ -111,6 +111,7 @@ stated, greppable contract.
 | debug a slow request                    | `debugPerformance` / telemetry     | /observability          |
 | share config across routes              | factory returning a helper array   | /composability          |
 | compose a sub-app / module              | `include()`                        | /route                  |
+| lay out a whole app                     | section modules, guards, groups    | /app-structure          |
 | modal / soft navigation                 | `intercept()`                      | /intercept              |
 | route group of client components        | `clientUrls()` in `"use client"`   | /client-urls            |
 | set meta/breadcrumbs from loader data   | `ctx.use(Handle)` in the loader    | /loader                 |
@@ -306,8 +307,10 @@ Grouped by concern — read when you need to…
 | Skill                     | Description                                                                |
 | ------------------------- | -------------------------------------------------------------------------- |
 | `/router-setup`           | Create and configure the RSC router                                        |
+| `/app-structure`          | Whole-app recipes: large app with admin, multi-app, content site, shop     |
 | `/route`                  | Define routes with `urls()`, `path()`, and `include()`                     |
 | `/client-urls`            | Client-component route groups with `clientUrls()` — no handlers            |
+| `/ux-architecture`        | Recipes for fast, stable navigation with `urls()` and `clientUrls()`       |
 | `/layout`                 | Layouts that wrap child routes                                             |
 | `/parallel`               | Multi-column layouts and sidebars                                          |
 | `/intercept`              | Modal/slide-over patterns for soft navigation                              |

package/skills/response-routes/SKILL.md

@@ -617,7 +617,10 @@ path.json(
 
 A dot-local name (`ctx.reverse(".comments")`) is a type error here. The
 runtime reverse has no scope to resolve it against, so untyped (JS) code that
-calls it throws `Unknown route` and the route answers 500.
+calls it throws `Unknown route` and the route answers 500. Leaving out a
+required param (`ctx.reverse("blog.api.comments")`) throws
+`Missing param "slug" for route "blog.api.comments"`, with or without a params
+object; it never returns the `/:slug` pattern as a URL.
 
 ## Content Negotiation
 

package/skills/scripts/SKILL.md

@@ -133,6 +133,17 @@ re-pushed inline script. The GTM demo does exactly this: a root-layout `Script`
 bootstrap fires the first page_view on document load, and a `"use client"`
 `<GtmPageViews>` component fires a page_view on every subsequent soft navigation.
 
+**Key that component on a handle value that carries the page's path, not on the
+URL.** Handle values arrive on their own channel, by design: on a page React
+holds in a transition (`transition()`, a same-route search change, a prefetched
+click) the URL changes before the destination's `content_group` and title land,
+so an effect keyed on `usePathname()` sends the previous page's tagging. Push
+the navigation's `pathname + search` into your `Gtm` handle (collected as `page.path`) from a root
+`parallel()` slot with `revalidate(true)`, read the tagging with `useHandle(Gtm)`,
+and send the page_view when `page.path` differs from the last path sent (seed it
+with the landing path, which the bootstrap already sent). The pattern, its
+trade-offs and the code are in [hooks](../hooks/handle-and-actions.md#when-handle-values-change-by-design).
+
 ## The inline-self-inject rule (GTM/GA4/Segment)
 
 If an inline bootstrap must run **before** an external loader, do NOT push the
@@ -202,6 +213,6 @@ warns once per key. See `/ppr` → "What always renders without a shell".
 - **Partytown / web-worker offloading** — push the worker config with
   `type: "text/partytown"` and wire Partytown's own nonce config manually.
 
-A full GTM + GA4-style integration (page_view on first render + soft nav, nonce,
+A full GTM + GA4-style integration (page_view on first render + soft nav keyed on a path-carrying handle value, nonce,
 ecommerce events) lives in the router repository's `tests/vite-rsc-demo` app
 (not shipped in this package).

package/skills/server-actions/SKILL.md

@@ -446,8 +446,8 @@ import * as CartActions from "./actions/cart";
 
 urls(({ path, loader, revalidate }) => [
   path("/", HomePage, { name: "home" }, () => [
-    // Loader data re-runs by default after any action. Opt out with revalidate(() => false).
-    loader(StaticHomepageLoader, () => [revalidate(() => false)]),
+    // Loader data re-runs by default after any action. Opt out with revalidate(false).
+    loader(StaticHomepageLoader, () => [revalidate(false)]),
   ]),
 
   // Re-render the cart page handler AND re-resolve its loader only after cart
@@ -603,6 +603,12 @@ Redirects from actions render the **target** route tree's matched segments
 source page's — the target is what the user sees next. See `/hooks
 useLocationState` for reading flash state on the target page.
 
+Build the target by name rather than a literal path:
+`throw redirect(getRequestContext().reverse("account.settings"))`. It fills
+mount params (`:accountId`, `:locale`) from the page URL the action was called
+on, so the module that owns the action does not need to know its mount
+(`/links`).
+
 ### Same-origin by default (open-redirect protection)
 
 `redirect()` is same-origin by default on every path — JS, no-JS PE, and
@@ -624,6 +630,28 @@ model). Omit it and off-host targets stay blocked. `external` only waives the
 `javascript:` or `data:` URL is still neutralized, so a forged or mistaken
 `external` target can never become a scriptable navigation.
 
+## Actions on a Rewritten Page
+
+An action cannot `throw rewrite()`; use `redirect()`. But a page that
+middleware reached through `throw rewrite()` can call actions. The action
+(JS or a no-JS form post) is posted to the visitor's URL, so the same
+middleware sees it:
+
+- A rewrite in **route middleware** runs after the action, around the
+  re-render, which route middleware sees as the page's GET, so a rewrite
+  written for GETs only fires too. The action runs once, then the re-render
+  runs as the target: its global and route middleware, its handlers and
+  loaders. The page on screen is revalidated in place, as at the target's
+  own URL.
+- A rewrite in **global middleware** runs before the action and moves the
+  mutation to the target first: the target's global middleware, then the
+  action, once, then the target's route middleware and render, as a direct
+  post to the target. A page a routing rewrite showed (a multi-tenant host,
+  an A/B split) keeps its forms working, in JS and no-JS. A lock refuses
+  mutations instead: `throw rewrite("maintenance").disallowMutations()` is an
+  error before the action runs, or return a `Response` for mutations. See
+  `/middleware` ("Mutations: where the middleware sits decides").
+
 ## Error Handling
 
 ### Validation errors — return them as state
@@ -688,24 +716,36 @@ For a recoverable "already gone" case, return a result the form can show
 ### A loader that fails on the revalidation render
 
 A loader that throws while it reruns after the action does not undo the
-action, which has already run and returned. What follows depends on the route:
-
-- **No `loading()` on the route (and any `clientUrls()` route):** the action
-  call rejects with the loader's error, nothing of that revalidation commits,
-  and the page keeps its data and its React state. A `<form action>`,
-  `useActionState` or `useTransition` call hands that rejection to the nearest
-  React error boundary above the form.
-- **A `urls()` route with `loading()`:** the call resolves with the action's
-  result, the page renders, and the loader's read throws to the nearest React
-  error boundary.
-- **An `errorBoundary()` above the route:** its fallback replaces the route.
-
-For a failure the user can retry, return it from the loader as data
-(`{ ok: false, reason }`) and render it where the data goes. A failure returned
-as data is a value like any other, so a `cache()` on the loader (or a `ppr`
-bake, or a prerender) stores and serves it; a thrown error is never stored.
-See `/client-urls` → "A loader that fails on its rerun" for the table and an
-example.
+action, which has already run and returned. It behaves as on a navigation (a
+plain or fully prefetched click, Back/Forward), on every route, called
+directly or from `<form action>`, `useActionState` or `useTransition`:
+
+- The call resolves with the action's result.
+- The loader throws in place, at its `useLoader` read, and the nearest
+  boundary to the read catches it: your own React error boundary around the
+  read, else the route's `errorBoundary()`, else the router's root one.
+  Everything outside that boundary keeps its React state; loaders that reran
+  without error commit their new data.
+- The error goes to `onError` on the server (phase `"loader"`) and to
+  `useAction(action).revalidationError` in the browser (`error` stays `null`,
+  `result` is set).
+- A later rerun that succeeds clears an `errorBoundary()` fallback. Your own
+  boundary resets by its own rule: key it on data that reruns with the loader
+  and is read outside the boundary.
+
+`notFound()` and `redirect()` from the loader keep their path: a `redirect()`
+replaces the route's content and navigates, and the layouts keep their
+instance. Every refetch the router runs for an action follows the same rule
+(after several actions at once, after a navigation during it), and the action
+that ran it reports the loader's error as its `revalidationError`. Not
+covered yet: an `intercept()`'s loaders, and a parallel slot's loaders under
+its own `loading()`. For a failure the user should see in place of the
+data without an error boundary, return it from the loader as data
+(`{ ok: false, reason }`) and render it where the data goes. A failure
+returned as data is a value like any other, so a `cache()` on the loader (or
+a `ppr` bake, or a prerender) stores and serves it; a thrown error is never
+stored. See `/client-urls` → "A loader that fails on its rerun" for the
+details and examples.
 
 ### Authorization in actions
 

package/skills/testing/SKILL.md

@@ -155,6 +155,7 @@ beside their function):
 |                                           | `setBuildVersions`                                                                                                                                           | [`serve-shell-request.md`](./serve-shell-request.md) |
 |                                           | `assertCacheStatus`, `assertCacheDecision`, `parseCacheHeader`, `createCacheSink`, `filterCacheDecisions`                                                    | [`cache-prerender.md`](./cache-prerender.md)         |
 |                                           | `assertShellStatus`, `parseShellStatus`, `shellCacheKey`, `SHELL_STATUS_HEADER`, `assertPprReplayStatus`, `parsePprReplayStatus`, `PPR_REPLAY_STATUS_HEADER` | [`cache-prerender.md`](./cache-prerender.md)         |
+|                                           | `visitorShellCacheKey`                                                                                                                                       | [`serve-shell-request.md`](./serve-shell-request.md) |
 |                                           | `assertGeneratedRoutesMatch`, `diffGeneratedRoutes`                                                                                                          | [`reverse-and-types.md`](./reverse-and-types.md)     |
 | `@rangojs/router/testing/dom`             | `renderRoute`                                                                                                                                                | [`client-components.md`](./client-components.md)     |
 | `@rangojs/router/testing/flight`          | `renderToFlightString`, `normalizeFlight`, `assertFlightRuntimeAvailable`                                                                                    | [`flight.md`](./flight.md)                           |

package/skills/testing/client-components.md

@@ -38,7 +38,7 @@
 | `useReverse`                   | Reverse a name->pattern map to a URL; merges `useParams()` and the `mount`/`basename` prefix. |
 | `useHref`                      | Resolve an href against the mount/basename.                                                   |
 | `useMount`                     | The `include()` mount prefix (`options.mount`), else `"/"`.                                   |
-| `useNavigation`                | Navigation controller state — stays `idle` (see caveat).                                      |
+| `useNavigation`                | Navigation controller state: `loading` from a `navigate()` call to its commit, else `idle`.   |
 | `useRouter`                    | The router handle, including `.basename`.                                                     |
 | `usePathname`                  | Current committed pathname.                                                                   |
 | `useSearchParams`              | Search params from the `request` URL.                                                         |
@@ -376,14 +376,17 @@ it("dims the held price while the next product streams", async () => {
 });
 ```
 
-| Pending state                                                                                  | Under `renderRoute`                                                                                                                                            |
-| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `useLoader().isLoading` on the reader a `transition` navigate() holds, pending seed            | Modeled: `true` on the OLD data until the promise settles, then `false` with the new data in the same commit.                                                  |
-| `transition` navigate(), settled seed (a plain value)                                          | `false`; the data swaps in the commit.                                                                                                                         |
-| navigate() without `transition`, pending seed                                                  | Urgent commit (production's cold-navigation lane): the read suspends to the nearest `<Suspense>` fallback (with none, React keeps the previous tree). No flag. |
-| `transition: { when }` returning false, or `navigate(url, { transition: false })`              | Same as without `transition`: urgent, with production's decision (`kind: "push"`; `refresh()` is `"revalidate"`). `transition: false` calls no predicate.      |
-| Production's other hold lanes (same-structure search/filter nav, fully-prefetched, optimistic) | NOT modeled — without `transition` navigate() stays urgent. Assert those at e2e.                                                                               |
-| `useNavigation().state`, `useLinkStatus().pending`, `useAction().state`                        | Stay `idle` — navigate() never starts the navigation lifecycle. e2e.                                                                                           |
+| Pending state                                                                                  | Under `renderRoute`                                                                                                                                                                                    |
+| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `useLoader().isLoading` on the reader a `transition` navigate() holds, pending seed            | Modeled: `true` on the OLD data until the promise settles, then `false` with the new data in the same commit.                                                                                          |
+| `transition` navigate(), settled seed (a plain value)                                          | `false`; the data swaps in the commit.                                                                                                                                                                 |
+| navigate() without `transition`, pending seed                                                  | Urgent commit (production's cold-navigation lane): the read suspends to the nearest `<Suspense>` fallback (with none, React keeps the previous tree). No flag.                                         |
+| `transition: { when }` returning false, or `navigate(url, { transition: false })`              | Same as without `transition`: urgent, with production's decision (`kind: "push"`; `refresh()` is `"revalidate"`). `transition: false` calls no predicate.                                              |
+| Production's other hold lanes (same-structure search/filter nav, fully-prefetched, optimistic) | NOT modeled — without `transition` navigate() stays urgent. Assert those at e2e.                                                                                                                       |
+| `useNavigation().state`, `useLinkStatus().pending`                                             | Modeled: navigate() starts the navigation as a click does. `loading` from the call, `idle` in the commit, held with it; `pending` true for the destination's link until the commit is handed to React. |
+| `useAction().state`                                                                            | Stays `idle`: navigate() runs no action. e2e.                                                                                                                                                          |
+| `useHandle()` on a held navigation, `navigate(url, { handles, loaders })`                      | Modeled: `handles` arrive on the response's handle stream, so readers keep the page being left's values while React holds the page and take the new ones with its commit.                              |
+| A back/forward restored from the history cache (its view transition, `pop`)                    | NOT modeled: the tree has one location and navigate() caches no entries, so a `popstate` restores nothing. Assert it at e2e.                                                                           |
 
 - Per-navigation seeds merge over the render-time `loaders`/`loaderData` for THAT navigation only; a later `navigate()` without `loaders` falls back to the render-time data.
 - Pass settled data as a plain value, not `Promise.resolve(value)`: React has not observed a plain promise yet, so it counts as pending and renders one `stale` frame. (A Flight chunk that has already settled carries its status and is skipped, which a plain value mirrors.)
@@ -392,7 +395,7 @@ it("dims the held price while the next product streams", async () => {
 ## Caveats
 
 - Client tree ONLY. Does NOT catch server/client boundary reference-identity remount bugs, real Flight serialization errors, loader execution, middleware, or handler ordering — those are `renderServerTree` / `renderHandler` / e2e territory. Loader data is SEEDED, never run. `hydrate: true` adds an HTML pass of this same client tree ([Hydration](#hydration)), not a render of your routes on a server.
-- `router.navigate()` bypasses the navigation lifecycle, so the controller never leaves `idle`. `useNavigation()` / `useLinkStatus()` / `useAction()` non-idle states (loading/streaming/pending, action result/error) are NOT reachable — test those at e2e. The one modeled pending state is held-navigation `useLoader().isLoading` ([Held navigation](#held-navigation)).
+- `router.navigate()` drives the navigation lifecycle: `useNavigation()` reads `loading` from the call and `idle` in the commit, held with it for a `transition` spec ([Held navigation](#held-navigation)). `useAction()` non-idle states (action loading/streaming, result/error) are NOT reachable — no action runs; test those at e2e.
 - `outletPending` seeds only the production-shaped outlet context. It is useful
   for the two settled render states of a layout that reads `useOutlet()`, but it
   does not prove the hydrated `clientUrls()` transition that toggles the value;