@rangojs/router 0.24.3 → 0.25.0

package/skills/hooks/urls.md

@@ -172,7 +172,7 @@ function ShopNav() {
 }
 ```
 
-Use `useHref()` for local navigation. Use the bare `href()` function for absolute paths. The function `useHref()` returns is referentially stable within a mount, so it is safe as a hook dependency or memoized prop.
+Use `useHref()` for local navigation. Use the bare `href()` function for absolute paths. Under a parameterized mount (`include("/:accountId", ...)`) it fills the mount's params from the current route params (`/acme/cart` at `/acme/board`); a missing one makes the returned function throw `Missing param`. The function is referentially stable while the mount's own param values stay the same, so it is safe as a hook dependency or memoized prop.
 
 ### useMount()
 

package/skills/i18n/SKILL.md

@@ -162,7 +162,8 @@ ctx.reverse("menu.category", { slug: "breads" }); // → "/c/breads" on an unpre
 `ctx.reverse()` auto-fills missing params from the current request, so the
 last call returns `/en/c/breads` when the current URL is `/en/...`. That is
 what you want for in-locale links; to leave the locale, pass it explicitly
-(`{ locale: "fr" }`, or `undefined`/`""` for the bare default). Middleware and
+(`{ locale: "fr" }`, or `undefined`/`""` for the bare default; under a
+required `/:locale`, `undefined` throws `Missing param "locale"`). Middleware and
 response routes are the exception: their `ctx.reverse` fills nothing from the
 request, so pass `locale` there explicitly.
 

package/skills/intercept/SKILL.md

@@ -92,35 +92,39 @@ Only the first `layout()` in an intercept's `use()` is applied. It is modal
 chrome only: a `layout(Chrome, () => [...])` with its own `use()` items throws.
 Attach loaders and the rest to the intercept itself.
 
-## Intercept Middleware
+## Middleware and an Intercept
 
-Intercepts support their own middleware chain via the use callback. The full chain for an intercept request is:
+An intercept has no middleware of its own. The target route's middleware runs
+for the modal on every request that renders it, a `cache()` hit and a
+`Prerender()` target included. The chain for an intercept request is:
 
 ```
-global mw (router.use) -> route mw (urls middleware()) -> intercept mw -> intercept loaders + handler
+global mw (router.use) -> route mw (the target route's middleware()) -> intercept loaders + handler
 ```
 
 The intercept's loaders are started before its handler is called, so they run
-in parallel with it. If intercept middleware returns a `Response` (e.g. a
-redirect), the intercept stops there.
+in parallel with it. If route middleware returns a `Response` (e.g. a
+redirect), the request stops there, the modal with it.
 
 ```typescript
-intercept(
-  "@modal",
-  "product",
-  <ProductModal />,
-  () => [
-    middleware(async (ctx, next) => {
-      // Runs only for this intercept, after global and route middleware
-      ctx.set("interceptSource", "modal");
-      await next();
-    }),
-    loader(ProductLoader),
-  ]
-)
+path("/product/:id", ProductPage, { name: "product" }, () => [
+  middleware(async (ctx, next) => {
+    // Runs for the full page and for the modal
+    ctx.set(Viewer, await getViewer(ctx.request));
+    await next();
+  }),
+]),
+intercept("@modal", "product", <ProductModal />, () => [
+  loader(ProductLoader), // ctx.get(Viewer) is set here
+]),
 ```
 
-The intercept handler can read context variables set by all upstream middleware layers (global, route, and intercept-specific).
+`middleware()` in an intercept's `use()`, or in its handler's `.use`, throws
+when the routes are defined: move it to the route's `middleware()`, or do the
+work in the intercept's loader.
+
+The intercept handler and its loaders read the context variables global and
+route middleware set.
 
 Handler/layout `ctx.set()` data follows the same rule as elsewhere:
 intercepts see data produced in the current render pass, but partial
@@ -136,7 +140,11 @@ re-render every time the intercept resolves live — each intercepted
 navigation, and each action submitted while the modal is open. When the
 segment cache or a prerendered intercept variant serves the modal, the stored
 handler output is reused and only the loaders run. Each loader decides for
-itself through its own `revalidate()`, with the normal loader defaults.
+itself through its own `revalidate()`, with the normal loader defaults: an
+action from the modal re-runs only the loaders whose predicate says so, and
+the modal keeps the data of the others, as it does on a link to another
+intercepted route that reads the same loader. In `clientUrls()` the predicate
+runs on the server too (`/client-urls`).
 
 A `revalidate()` placed directly in the intercept's `use()` (or returned from
 its handler's `.use`) throws at definition time. Attach it to the loader:
@@ -144,13 +152,13 @@ its handler's `.use`) throws at definition time. Attach it to the loader:
 ```typescript
 // Throws: revalidate() is not valid inside intercept("@modal", "product") use()
 intercept("@modal", "product", <ProductModal />, () => [
-  revalidate(() => false),
+  revalidate(false),
   loader(ProductLoader),
 ]);
 
 // Correct: the loader owns the decision
 intercept("@modal", "product", <ProductModal />, () => [
-  loader(ProductLoader, () => [revalidate(() => false)]),
+  loader(ProductLoader, () => [revalidate(false)]),
 ]);
 ```
 
@@ -176,7 +184,7 @@ layout(ProductLayout, () => [
   intercept("@modal", "product", <ProductModal />, () => [
     loader(ProductLoader, () => [
       revalidate(revalidateProductShell), // reruns with the producer
-      revalidate(() => false), // otherwise keep the loaded data
+      revalidate(false), // otherwise keep the loaded data
     ]),
   ]),
 ]);
@@ -197,7 +205,7 @@ export const revalidateProduct = () => [
 layout(ProductLayout, () => [
   revalidateProduct(),
   intercept("@modal", "product", <ProductModal />, () => [
-    loader(ProductLoader, () => [revalidateProduct(), revalidate(() => false)]),
+    loader(ProductLoader, () => [revalidateProduct(), revalidate(false)]),
   ]),
 ]);
 ```
@@ -244,6 +252,29 @@ back to `Referer`, and only when that `Referer` is on the request's own origin
 (scheme, host and port). A request with no usable navigation context is not
 intercepted: it gets the full page.
 
+### `prefetch: false` on an intercept's loaders
+
+`loader(Def, { prefetch: false })` inside `intercept()` keeps that loader out
+of a prefetch of the target from the source page:
+
+```typescript
+intercept("@modal", "product", <ProductModal />, () => [
+  loader(ProductLoader),
+  loader(ReviewsLoader, { prefetch: false }), // skipped in the prefetch
+  loading(<ModalSkeleton />),
+]);
+```
+
+The click that adopts the prefetch opens the modal at once over the page, with
+its `loading()` while one fill request, sent from the source page, runs the
+flagged loader. The page under the modal is not re-rendered or remounted.
+Without `loading()` the slot shows nothing until the fill answers, as a plain
+click shows nothing until its response. The modal's loaders resolve together,
+so its `loading()` shows until the last one arrives. A handler that reads the
+flagged loader with `ctx.use()` before its first `await` (or one with no
+`loading()`) gets it run in the prefetch instead: one run, no fill for it.
+`loading(…, { prefetch: false })` inside `intercept()` defers nothing.
+
 A prefetch of a route an intercept targets is stored per source page, whether
 or not the intercept applies from that page (`rsc-rendering.ts`
 `x-rsc-prefetch-scope: source`, set from `MatchResult.interceptTargeted`). A
@@ -284,7 +315,7 @@ intercept(
   <ProductModal />,
   () => [
     loader(ProductLoader, () => [cache()]),
-    loader(ProductCartLoader, () => [revalidate(() => true)]),
+    loader(ProductCartLoader, () => [revalidate(true)]),
     loader(RecommendationsLoader),
   ]
 )
@@ -295,15 +326,15 @@ intercept(
 An intercept's `use()` (and its handler's `.use`) accepts:
 
 - `loader()`, with its own `revalidate()` and `cache()` inside it
-- `middleware()`
 - `loading()`
 - `layout(Chrome)`: the modal chrome, without `use()` items of its own
 - `route`, the item type a `path()` call produces
 - `transition()`
 
 Everything else throws at definition time with a pointer to where it goes:
-`revalidate()` onto the loader, `errorBoundary()` / `notFoundBoundary()` onto
-the enclosing layout (see below), and `cache()` onto the target route.
+`middleware()` onto the target route, `revalidate()` onto the loader,
+`errorBoundary()` / `notFoundBoundary()` onto the enclosing layout (see
+below), and `cache()` onto the target route.
 
 ## Caching an Intercept
 
@@ -526,7 +557,7 @@ export const shopPatterns = urls(({
 
 ## Handler-attached `.use`
 
-Intercept handlers can carry their own middleware, loaders, loading state, and even nested `layout`/`route` defaults via `.use` — useful for self-contained modal components that travel with their own data and chrome. (Conditional activation is set via the `when` config on the mount-site `intercept()` call, not inside `.use`; boundaries go on the enclosing layout, see [Errors in an Intercept](#errors-in-an-intercept).)
+Intercept handlers can carry their own loaders, loading state, and even nested `layout`/`route` defaults via `.use` — useful for self-contained modal components that travel with their own data and chrome. (Conditional activation is set via the `when` config on the mount-site `intercept()` call, not inside `.use`; boundaries go on the enclosing layout, see [Errors in an Intercept](#errors-in-an-intercept).)
 
 ```typescript
 import { layout, loader, loading, type Handler } from "@rangojs/router";

package/skills/layout/SKILL.md

@@ -234,7 +234,9 @@ among the path's children (`/caching`).
 A standalone `layout()` renders when it is first mounted and is then kept as-is:
 
 - **Navigation** between routes it already wraps does not re-render it — even
-  when the URL params change.
+  when the URL params change. Links it rendered with `ctx.reverse` (mount
+  params auto-filled) keep the old params too; render param-dependent nav in a
+  client component with `useReverse(routes)` (`/links`).
 - **Actions** skip it too (the revalidation trace calls this
   `action:parent-chain-skip`).
 
@@ -264,9 +266,10 @@ layout(LocaleLayout, () => [
 ])
 ```
 
-`revalidate(() => false)` on a standalone layout only restates the default.
+`revalidate(false)` on a standalone layout only restates the default.
 The return shapes (hard boolean, soft `{ defaultShouldRevalidate }`, or defer)
-are covered in `/loader` → "`revalidate()` return shapes".
+and the `revalidate(true | false)` shorthand are covered in `/loader` →
+"`revalidate()` return shapes".
 
 If child segments read data that was established by this layout or by a
 route handler above them, revalidate the outer segment too. Partial

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