@rangojs/router 0.24.4 → 0.25.0

package/skills/links/SKILL.md

@@ -24,14 +24,62 @@ links to JSON/text endpoints see `/response-routes`.
 
 Available on the handler context (route handlers, layouts, parallels), on
 middleware and loader contexts, and on `getRequestContext()` inside server
-actions. Resolves named routes using the full route map. This is the default
+actions. In loaders and in actions (after the route match) params the matched
+route carries are optional, as in handlers: `ctx.reverse("account.settings")`
+fills `accountId` from the matched params. In global middleware before `next()`
+nothing is matched, so a route with a required param throws `Missing param`.
+Resolves named routes using the full route map. This is the default
 way to generate URLs on the server. Patterns in the map already include the
 router `basename`, so results are basename-prefixed.
 
 Middleware and response routes (`path.json()`, `path.text()`, …) get a
 global-only `ctx.reverse` (`GlobalReverseFunction`): no `include()` scope and no
 param auto-fill, so pass the fully qualified name and every param. A dot-local
-`.name` is a type error there. See `/middleware` and `/response-routes`.
+`.name` is a type error there. A missing required param throws
+`Missing param`, with or without a params object. Route
+middleware can use `getRequestContext().reverse` instead: it is rebound after
+the match, takes `.name` and global names, and fills mount params. In global
+middleware (`router.use`) it fills only after `next()`. See `/middleware` and
+`/response-routes`.
+
+A server action's `getRequestContext().reverse("global.name")` fills mount
+params from the page URL the action was called on, so
+`throw redirect(getRequestContext().reverse("account.settings"))` needs no
+hardcoded path. A `.name` there resolves in that page's module; an action
+shared by pages in different modules should use global names.
+
+### The module never knows its mount
+
+Inside a module, link by local name: `ctx.reverse(".x")` on the server,
+`useReverse(routes)` with the module's own `.gen.ts` on the client. Both
+resolve against wherever the module is mounted and fill the mount's params
+from the current URL, so the same module can be mounted twice:
+
+```typescript
+include("/:locale", shopPatterns, { name: "shop" });
+include("/outlet", shopPatterns, { name: "outlet" });
+
+// in shopPatterns, on /en/... and on /outlet/...
+ctx.reverse(".product", { slug: "b" }); // "/en/product/b" and "/outlet/product/b"
+ctx.reverse(".product", { slug: "b", locale: "de" }); // "/de/product/b" (switch)
+```
+
+`/:locale?` and `/:locale` both auto-fill. `{ locale: undefined }` drops an
+optional locale (`/product/b`) and throws `Missing param "locale"` for a
+required one. Don't rebuild this by hand: `useParams().accountId` in a template
+string, `ctx.params` threaded through props, or a "current account" context
+all duplicate what the mount already knows.
+
+- A server layout stays held across navigations, its own mount param
+  (`:projectId`) changing included: partial rendering by design (`/layout`,
+  "Layout Revalidation"). Links it rendered keep the old params. Render
+  param-dependent nav links in a client component with `useReverse` (it
+  re-renders from `useParams()`), or give the layout a `revalidate()` that
+  compares the param.
+- A layout, a parallel slot and the loaders declared on them resolve `.name`
+  in the module that declares them, whichever route below them matched: a
+  parent module's layout links within its own module on every page (see
+  "Local names" below).
 
 ```typescript
 import { urls } from "@rangojs/router";
@@ -47,7 +95,7 @@ export const shopPatterns = urls(({ path, layout }) => [
 
 ### Resolution rules
 
-- **`.name`** — local route, resolved within the current `include()` scope
+- **`.name`** — local route, resolved within the `include()` scope of the module that defines the calling route, layout, parallel slot or loader
 - **`name`** — global route, from the named-routes definition
 
 The include site decides which global names exist:
@@ -87,6 +135,24 @@ Prefix a name with `.` to resolve it within the current `include()` scope. The r
 };
 ```
 
+The scope is the module that **defines** the code calling `ctx.reverse`. A route handler resolves from its own module. A `layout()`, a `parallel()` slot and the loaders declared on them resolve from the module where they are declared, whichever route below them matched. So a parent module's layout gives the same link on every page:
+
+```typescript
+// mounted at include("/:accountId", accountPatterns, { name: "account" })
+export const accountPatterns = urls(({ path, layout, include }) => [
+  layout(
+    (ctx) => <AccountNav settings={ctx.reverse(".settings")} />, // "/acme/settings" on every page below
+    () => [
+      path("/settings", AccountSettings, { name: "settings" }),
+      // projectPatterns also has a "settings" route
+      include("/:projectId", projectPatterns, { name: "project" }),
+    ],
+  ),
+]);
+// On /acme/web/issues, the account layout still links to "/acme/settings".
+// The project's issues handler's ctx.reverse(".settings") gives "/acme/web/settings".
+```
+
 ### Auto-fill of mount params
 
 When routes are mounted via a parameterized `include()`, `ctx.reverse()` automatically fills mount params from `ctx.params`. Inner handlers don't need to pass params that are already known from the current URL match. Explicitly passed params override auto-filled values.
@@ -109,7 +175,7 @@ export const tenantPatterns = urls(({ path }) => [
 ]);
 ```
 
-Auto-fill uses `{ ...ctx.params, ...hrefParams }` — current request params are defaults, explicit params win. Params not needed by the target route are silently ignored. Because every current param is a default, drop an optional one explicitly with `undefined` or `""` — under `include("/:locale?", ...)` on `/en/...`, a bare `ctx.reverse("menu.index")` keeps `/en`, while `ctx.reverse("menu.index", { locale: undefined })` returns `/` (see `/i18n`). A missing required param throws `Missing param "slug" for route "…"`; an unknown name throws `Unknown route: "…"`.
+Auto-fill uses `{ ...ctx.params, ...hrefParams }` — current request params are defaults, explicit params win. Params not needed by the target route are silently ignored. Because every current param is a default, drop an optional one explicitly with `undefined` or `""` — under `include("/:locale?", ...)` on `/en/...`, a bare `ctx.reverse("menu.index")` keeps `/en`, while `ctx.reverse("menu.index", { locale: undefined })` returns `/` (see `/i18n`). A missing required param throws `Missing param "slug" for route "…"` (in middleware and response routes too, with or without a params object); an unknown name throws `Unknown route: "…"`.
 
 ### Global names (unprefixed)
 
@@ -213,6 +279,48 @@ function Nav() {
 
 `useLoader()` requires the loader to be attached to an active route. If you need on-demand fetching instead, use `useFetchLoader()`.
 
+A loader on a layout is held on navigation, like the layout. When its links follow a param of the layout's own mount (`:projectId`), give it a `revalidate()` that compares that param; links that never change can come from the layout's RSC as props:
+
+```tsx
+// urls/project.tsx (server): build the links where the names resolve
+export const ProjectNavLoader = createLoader((ctx) => ({
+  issues: ctx.reverse(".issues"), // /acme/web/issues
+  settings: ctx.reverse(".settings"), // /acme/web/settings
+  account: ctx.reverse("account.settings"), // /acme/settings, another module
+}));
+
+export const projectUrls = urls(({ layout, path, loader, revalidate }) => [
+  layout(
+    // From the RSC: fine for links that do not follow :projectId.
+    (ctx) => <ProjectShell accountHref={ctx.reverse("account.settings")} />,
+    () => [
+      // From a loader: held like the layout, re-run when the project changes.
+      loader(ProjectNavLoader, () => [
+        revalidate(({ currentParams, nextParams }) =>
+          currentParams.projectId !== nextParams.projectId ? true : undefined,
+        ),
+      ]),
+      path("/issues", Issues, { name: "issues" }),
+      path("/settings", Settings, { name: "settings" }),
+    ],
+  ),
+]);
+```
+
+```tsx
+"use client";
+export function ProjectNav() {
+  const { data: links } = useLoader(ProjectNavLoader);
+  return (
+    <nav>
+      <Link to={links.issues}>Issues</Link>
+      <Link to={links.settings}>Settings</Link>
+      <Link to={links.account}>Account</Link>
+    </nav>
+  );
+}
+```
+
 3. Return from a server action:
 
 ```tsx
@@ -286,9 +394,9 @@ function ShopNav() {
 }
 ```
 
-Use `useHref()` for local navigation within a mounted module. Use the bare `href()` function for absolute paths outside the current mount.
+Use `useHref()` for local navigation within a mounted module (`include("/shop", ...)` or `include("/tenant/:tenantId", ...)`). Use the bare `href()` function for absolute paths outside the current mount.
 
-`useHref()` concatenates the mount **pattern** as-is and does not substitute params, and its argument is not checked against your routes. Under a parameterized mount (`include("/tenant/:tenantId", ...)`) it would produce `/tenant/:tenantId/cart` — use `useReverse(routes)` there, which substitutes mount params from `useParams()`.
+Under a parameterized mount (`include("/tenant/:tenantId", ...)`, `/:locale`, `/:locale?`), `useHref()` fills the mount's params from `useParams()`, the same way `useReverse` does: at `/tenant/acme/board`, `href("/cart")` returns `/tenant/acme/cart`. A mount param missing from the current match makes the returned function throw `Missing param "tenantId" for route "/tenant/:tenantId"`; it never returns a URL with a literal `:tenantId`. Relative `useRouter().push("cart")` / `replace` / `prefetch` fill the mount from the committed route params at call time; a missing one rejects the `push`/`replace` promise and skips the `prefetch`. Only the mount is filled: the path argument is appended verbatim and is not checked against your routes, so for a link to a named route with its own params prefer `useReverse(routes)`.
 
 ## Client: useMount()
 
@@ -306,7 +414,7 @@ function MountInfo() {
 }
 ```
 
-`useMount()` reads from `MountContext`, which is automatically set by `include()` in the segment tree. Nested includes return the nearest mount's full URL prefix (e.g. `/shop/admin`), and a parameterized include returns its pattern (`/tenant/:tenantId`), not the matched URL. `href(path, mount)` is the non-hook equivalent of `useHref()`.
+`useMount()` reads from `MountContext`, which is automatically set by `include()` in the segment tree. Nested includes return the nearest mount's full URL prefix (e.g. `/shop/admin`), and a parameterized include returns its pattern (`/tenant/:tenantId`), not the matched URL. `href(path, mount)` concatenates the mount it is given as-is; it is the non-hook equivalent of `useHref()` only under a static mount (`useHref()` also fills mount params).
 
 ## Client: useReverse(routes)
 
@@ -331,6 +439,27 @@ export function BlogNav() {
 }
 ```
 
+### One hook per module, in a userland file
+
+Wrap the map once instead of importing it in every component:
+
+```ts
+// src/lib/links.ts
+"use client";
+import { useReverse } from "@rangojs/router/client";
+import { routes as blogRoutes } from "../urls/blog.gen.js";
+import { routes as accountRoutes } from "../urls/account.gen.js";
+
+export const useBlogReverse = () => useReverse(blogRoutes);
+export const useAccountReverse = () => useReverse(accountRoutes);
+```
+
+Components call `useAccountReverse()`; a renamed or moved module changes one
+file. The wrapper resolves like `useReverse`: against the nearest `include()`
+mount, so call a module's hook from components under that module's own mount.
+Inside a nested module it builds a wrong URL with no error (dc-t57); pass
+cross-module links from the server there.
+
 ### How it resolves
 
 1. Strips an optional leading `.` and looks up the name in the imported `routes` map.
@@ -413,24 +542,29 @@ Both happen synchronously during `reverse()` — wrap calls in try/catch (or an
 
 ### The leading dot is optional
 
-`reverse("post")` and `reverse(".post")` resolve **identically** — the leading dot is cosmetic. The map you import IS the scope, so there is no separate global namespace to disambiguate and the dot carries no meaning; it exists only as a readability convention and for parity with `ctx.reverse(".name")` on the server. To link into a different module, import that module's `routes`:
+`reverse("post")` and `reverse(".post")` resolve **identically** — the leading dot is cosmetic. The map you import IS the scope, so there is no separate global namespace to disambiguate and the dot carries no meaning; it exists only as a readability convention and for parity with `ctx.reverse(".name")` on the server. A module's `routes` map is right only inside that module's own mount: it resolves against the current mount, so another module's map gives a wrong URL with no error, and `useReverse(NamedRoutes)` is correct only at the root mount (under a mount it double-prefixes). There is no client API for links that cross modules under a nested mount (dc-t57). Build them on the server, where global names resolve fully, and pass them down:
 
 ```tsx
-import { routes as blogRoutes } from "../urls/blog.gen.js";
-import { routes as shopRoutes } from "../urls/shop.gen.js";
+// server layout or handler
+const links = {
+  blog: ctx.reverse("blog.index"),
+  cart: ctx.reverse("shop.cart"),
+};
+return <CrossNav links={links} />;
 
-function CrossNav() {
-  const blog = useReverse(blogRoutes);
-  const shop = useReverse(shopRoutes);
+// client component
+function CrossNav({ links }: { links: { blog: string; cart: string } }) {
   return (
     <nav>
-      <Link to={blog("index")}>Blog</Link>
-      <Link to={shop("cart")}>Cart</Link>
+      <Link to={links.blog}>Blog</Link>
+      <Link to={links.cart}>Cart</Link>
     </nav>
   );
 }
 ```
 
+Loader data is the better carrier for chrome that follows a param: a layout handler is kept across param changes, while a layout loader re-runs when its `revalidate()` compares that param (a layout loader is held on navigation by default).
+
 ### Codegen
 
 Each `urls()` module gets a sibling `.gen.ts` with the local route names and patterns, produced by `rango generate`:
@@ -512,10 +646,10 @@ a link or a whole section from prefetching at all, use the `prefetch` prop or
 | Client component | `useReverse(routes)`                               | Local names from an imported `routes` map | Typed in-module URL generation without round-tripping the server |
 | Client component | (URL passed as prop / loader data / action return) | Named routes                              | Cross-module URLs or one-off names you don't want to import      |
 | Client component | `href("/path")`                                    | Absolute paths (static strings)           | Static navigation where no named-route lookup is needed          |
-| Client component | `useHref()`                                        | Mount-prefixed paths                      | Local navigation inside `include()`                              |
+| Client component | `useHref()`                                        | Mount-prefixed paths                      | Local paths inside `include()`; fills `:param` mount segments    |
 | Client component | `useMount()`                                       | Raw mount path                            | Custom mount-aware logic                                         |
 
-> `ctx.reverse()` is server-only. On the client, either generate URLs on the server and pass them in, or import the `routes` map and use `useReverse(routes)` for in-module names.
+> `ctx.reverse()` is server-only. On the client, either generate URLs on the server and pass them in, or import the `routes` map and use `useReverse(routes)` for in-module names, inside that module's own mount.
 
 ## Complete example: mounted module
 

package/skills/loader/SKILL.md

@@ -241,7 +241,7 @@ so response-shaping belongs in middleware or the handler).
 | `method`           | `string`                        | HTTP method. `"GET"` for SSR loader runs; reflects real method for fetchable loaders.                                                                                                          |
 | `body`             | `TBody \| undefined`            | Parsed request body for fetchable POST/PUT/PATCH/DELETE calls.                                                                                                                                 |
 | `formData`         | `FormData \| undefined`         | Present when a fetchable loader is invoked via form submission.                                                                                                                                |
-| `reverse`          | `ScopedReverseFunction`         | Generate type-checked URLs from route names (same scoped semantics as route handlers).                                                                                                         |
+| `reverse`          | `AutofillAwareReverseFunction`  | Generate type-checked URLs from route names (same scoped semantics as route handlers; params the matched route carries are optional).                                                          |
 
 ### Example
 
@@ -266,9 +266,10 @@ export const ProductLoader = createLoader(async (ctx) => {
   // Variables set by middleware (from Rango.Vars augmentation)
   const user = ctx.get("user");
 
-  // Type-checked URLs for payloads. `.name` resolves within the current
-  // include() scope; a bare `name` resolves globally. See /route and
-  // /typesafety for scope rules and route-name autocomplete.
+  // Type-checked URLs for payloads. `.name` resolves within the include()
+  // scope of the module that declares this loader (a layout's loader in a
+  // parent module links within that module); a bare `name` resolves
+  // globally. See /links and /typesafety for scope rules and autocomplete.
   const detailUrl = ctx.reverse(".detail", { slug });
 
   return {
@@ -321,7 +322,7 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 
   // Loader with revalidation control
   loader(RelatedProductsLoader, () => [
-    revalidate(() => false), // Never revalidate
+    revalidate(false), // Never revalidate
   ]),
 
   // Loader that re-runs only after cart actions. Loaders re-run after every
@@ -355,6 +356,7 @@ chain continues:
 ```typescript
 // 1) Hard decision — short-circuits the chain, used as the final answer.
 revalidate(() => true);
+revalidate(true); // shorthand for () => true; revalidate(false) for () => false
 revalidate(({ actionId }) => actionId?.includes("Cart") ?? false);
 
 // 2) Soft decision — updates the running suggestion for downstream
@@ -377,6 +379,14 @@ revalidate(() => null); // explicit defer
 If every revalidator on a segment defers, the segment default is used
 (`defaultShouldRevalidate`, see the table below).
 
+`revalidate(true)` and `revalidate(false)` are shorthand for the constant hard
+decisions `revalidate(() => true)` and `revalidate(() => false)`: `true`
+re-runs the segment on every navigation and action, `false` keeps the client's
+copy once it holds one. A defer has no shorthand: write the function. The
+shorthand works everywhere `revalidate()` does, `clientUrls()` loaders
+included. There the build checks the argument: a literal at its call site,
+any other expression when the server mounts the group.
+
 The callback must be **synchronous**. A returned Promise is ignored (dev
 warning) and the running suggestion is kept, so move async work into a loader.
 A callback that throws is logged and treated as a defer; a thrown `Response`
@@ -944,6 +954,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).
 
+A loader that throws (anything but `notFound()` or `redirect()`) throws at its `useLoader` read on every client lane: a plain or fully prefetched click, Back/Forward restored from the history cache, and the rerun after a server action. A prefetch in which a loader threw is never used, in memory or from the browser's HTTP cache: the click asks the server again, so a loader that has recovered shows its data. The nearest boundary to the read catches it (your React error boundary around the read, else the route's `errorBoundary()`, else the router's root one), and the layouts above keep their instance. The background refresh after Back/Forward onto a stale page is the exception: a loader that fails there leaves the page on screen and logs `[Browser] Background revalidation failed`. Not covered: an `intercept()`'s loaders, and a parallel slot's loaders under its own `loading()`, which are decoded above the slot's content.
+
 ## Loader Authority: notFound() and redirect()
 
 A loader may **throw** `notFound()` and `redirect()` — data-dependent
@@ -955,7 +967,7 @@ import { createLoader, notFound, redirect } from "@rangojs/router";
 
 export const ProductLoader = createLoader(async (ctx) => {
   const moved = LEGACY_SLUGS[ctx.params.slug];
-  if (moved) throw redirect(`/shop/product/${moved}`);
+  if (moved) throw redirect(ctx.reverse("shop.product", { slug: moved }));
 
   // Existence check BEFORE the expensive fetch: a near-instant rejection
   // usually wins the race to first flush (see the semantics below).
@@ -1012,6 +1024,7 @@ Delivery is async **by the race model**: pushes that settle before the handler
 barrier ride the SSR handle snapshot (in the SSR'd document — `<Html.Meta />`,
 `useHandle` reads); later pushes stream to the client and apply post-hydration
 on document loads (`metadata.handlesLate`) or progressively on navigations.
+Handle values land on their own channel and never hold the page, so an effect that needs a late push keys on the handle value, not the URL (see [hooks](../hooks/handle-and-actions.md#when-handle-values-change-by-design)).
 A push before your slow fetch usually beats the barrier; a push derived from
 the fetched data usually does not. When it MUST be in the document, use
 `ssr: false` below. A loader with its own `cache()` keeps its pushes on a hit —
@@ -1021,7 +1034,9 @@ there every push a loader makes on that request applies post-hydration (see
 `/ppr`, "Handles on a shell HIT"). A `useHandle` reader inside this loader's
 `loading()` or `<Suspense>` hydrates with the data its HTML was rendered
 from and shows a later push right after, so a push after an `await` causes
-no hydration mismatch there.
+no hydration mismatch there. A loader body may push after an `await`; a server
+component that does throws `LateHandlePushError`, so it resolves a slot its
+handler reserved with `.defer()` instead (`/breadcrumbs`, "Deferred content").
 
 Under `cache()`, loader pushes are not stored with the cached segments: the
 loader re-runs on every hit and its live push is the only copy. (`ppr` keeps
@@ -1279,9 +1294,16 @@ The limits:
   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.
+- **Inside `intercept()`.** In `urls()` and in `clientUrls()`, a prefetch of
+  the intercept's target from its source page defers the flagged loader: the
+  click opens the modal at once, with its `loading()`, and one fill, sent
+  from the source, runs the loader. The page under the modal stays. With no
+  `loading()` the slot is empty until the fill answers, as on a plain click
+  until its response. The modal's loaders resolve together: it shows its
+  `loading()` until every one has arrived. A flagged `loading()` inside
+  `intercept()` defers nothing. Each intercept loader also runs its own
+  `revalidate()`, so an action from the modal re-runs only those that say so
+  (see `/intercept`).
 - **`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

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),
       ]
     ),