@rangojs/router 0.24.4 → 0.25.0

package/skills/composability/SKILL.md

@@ -214,14 +214,16 @@ export const shopPatterns = urls(({ path, include }) => [
 export default shopPatterns; // async include() resolves this
 ```
 
-**Prefer the async form** for any route group that is a natural,
-independently-loadable unit (a localized section, an admin area, an API surface
-with heavy handlers) — it trims the eagerly-parsed entry bundle and keeps that
-subgraph off the cold-start path. The **eager form is still fully valid** (not
-deprecated): keep it for small groups, or ones that share most of their module
-graph with the entry (the bundler keeps shared modules common regardless, so
-splitting a thin group buys little). Both match identically at runtime — only the
-module's runtime evaluation timing differs.
+**Default to the eager (sync) form.** Reach for the async form when a group is
+large and rarely visited, and is a natural, independently-loadable unit (a big
+localized section, a heavy admin area, an API surface with heavy handlers): it
+trims the eagerly-parsed entry bundle and keeps that subgraph off the cold-start
+path, at the cost of the group's first request paying its chunk import (see the
+measurements below). A thin group, or one that shares most of its module graph
+with the entry, gains little from splitting, since the bundler keeps shared
+modules common regardless. Both match identically at runtime — only the module's
+runtime evaluation timing differs. `/app-structure` shows both in whole-app
+layouts.
 
 What you do NOT lose by splitting: build-time discovery `await`s the provider, so
 `href()`, `ctx.reverse()`, generated route types, and prerender still see every route

package/skills/handler-use/SKILL.md

@@ -51,14 +51,14 @@ Now `ProductPage` carries its loader, loading state, and response-header middlew
 
 `handler.use()` is the same callback shape regardless of where the handler runs, but the runtime validates that the items it returns are valid for the mount site. Driven by `MOUNT_SITE_ALLOWED_TYPES` in [resolve-handler-use.ts](../../src/route-definition/resolve-handler-use.ts):
 
-| Mount site                                        | Allowed item types                                                                                                                                                                                                                                                                                                                                                                                      |
-| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `path()`                                          | `layout`, `parallel`, `intercept`, `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `cache`, `transition`                                                                                                                                                                                                                                                          |
-| `layout()`                                        | All of the above, plus `route` (nested `path()` items) and `include`                                                                                                                                                                                                                                                                                                                                    |
-| `parallel()` (per slot)                           | `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `transition`                                                                                                                                                                                                                                                                                                                    |
-| `intercept()`                                     | `middleware`, `loader`, `loading`, `layout` (modal chrome, without its own `use()` items), `route`, `transition`. Conditional activation is config-only: `intercept(..., { when })`. Anything else throws with a pointer: `revalidate` goes on the intercept's loader (`loader(Def, () => [revalidate(...)])`), `errorBoundary`/`notFoundBoundary` on the enclosing layout, `cache` on the target route |
-| Response routes (`path.json()`, `path.text()`, …) | `middleware`, `cache`                                                                                                                                                                                                                                                                                                                                                                                   |
-| `loader()` (a `createLoader()` definition)        | `revalidate`, `cache`                                                                                                                                                                                                                                                                                                                                                                                   |
+| Mount site                                        | Allowed item types                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `path()`                                          | `layout`, `parallel`, `intercept`, `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `cache`, `transition`                                                                                                                                                                                                                                                                                                          |
+| `layout()`                                        | All of the above, plus `route` (nested `path()` items) and `include`                                                                                                                                                                                                                                                                                                                                                                                    |
+| `parallel()` (per slot)                           | `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `transition`                                                                                                                                                                                                                                                                                                                                                                    |
+| `intercept()`                                     | `loader`, `loading`, `layout` (modal chrome, without its own `use()` items), `route`, `transition`. Conditional activation is config-only: `intercept(..., { when })`. Anything else throws with a pointer: `middleware` goes on the target route (it runs for the modal too), `revalidate` on the intercept's loader (`loader(Def, () => [revalidate(...)])`), `errorBoundary`/`notFoundBoundary` on the enclosing layout, `cache` on the target route |
+| Response routes (`path.json()`, `path.text()`, …) | `middleware`, `cache`                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `loader()` (a `createLoader()` definition)        | `revalidate`, `cache`                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 
 `route` is the item type a `path()` call produces.
 
@@ -292,7 +292,7 @@ AdminLayout.use = () => [
 
 ### Intercepts (`intercept()`)
 
-Intercept handlers can carry their own middleware chain, loaders, `loading()`, and the modal chrome: a `layout(Chrome)` with no `use()` items of its own. Boundaries, `cache()` and `revalidate()` throw here (see the table above and [intercept](../intercept/SKILL.md)).
+Intercept handlers can carry their own loaders, `loading()`, and the modal chrome: a `layout(Chrome)` with no `use()` items of its own. `middleware()`, boundaries, `cache()` and `revalidate()` throw here (see the table above and [intercept](../intercept/SKILL.md)); the target route's middleware runs for the modal.
 
 ```typescript
 const QuickViewModal: Handler = async (ctx) => {
@@ -392,6 +392,44 @@ Rule of thumb: only put `loading()` in `handler.use` if you genuinely want every
 - **Validation runs at registration / first match**, not at handler definition. A handler doesn't know its mount site at definition time — the same handler used in a `path()` and an `intercept()` is validated against each mount's allowed-types set when registered.
 - **No silent shadowing.** If a disallowed item slips through (e.g., a layout factory returning `cache()` from a slot's `handler.use`), the runtime throws with the offending type and mount site named.
 
+## In `clientUrls()`: `Component.use`
+
+A client route group (`/client-urls`) takes the same pattern for its
+components: `Dashboard.use = () => [...]` on a page, layout or intercept
+component mounted by the group's `path()`, `layout()` or `intercept()`. Build
+the items with the helpers `@rangojs/router/client` exports (`loader`,
+`loading`, `revalidate`, `transition`); the `@rangojs/router` ones are the
+server DSL's and throw in a client module.
+
+```tsx
+"use client";
+import { loader, loading, revalidate } from "@rangojs/router/client";
+
+Dashboard.use = () => [
+  loader(StatsLoader, () => [
+    revalidate(({ isAction }) => isAction(StatsActions)),
+  ]),
+  loading(<DashboardSkeleton />),
+];
+```
+
+The composition rules are this skill's: the component's items first, the
+mount site's explicit items second, `loading()` and `transition()` last-wins,
+loaders accumulate. What differs:
+
+| Mount site in `clientUrls()` | The component's `.use` may return          |
+| ---------------------------- | ------------------------------------------ |
+| `path()`                     | `loader`, `loading`, `transition`          |
+| `layout()`                   | `loader`, `loading`                        |
+| `intercept()`                | `loader` (without `ssr: false`), `loading` |
+
+- No `route`, `layout`, `intercept` or `include` items: a group's routes and
+  its generated types come from the builder's own items.
+- A `revalidate()` predicate still runs on the server: the build hoists it
+  out of the component's module (see `/client-urls`, "Revalidation runs on
+  the server").
+- A `createLoader()` definition's `.use` is not read inside a group yet.
+
 ## Cross-references
 
 - `skills/route` — `path()` mount site basics
@@ -400,3 +438,4 @@ Rule of thumb: only put `loading()` in `handler.use` if you genuinely want every
 - `skills/intercept` — intercept mount site basics
 - `skills/loader` — defining `createLoader` and reading via `ctx.use()`
 - `skills/middleware` — middleware semantics and ordering
+- `skills/client-urls` — `Component.use` in a client route group

package/skills/hooks/handle-and-actions.md

@@ -39,6 +39,107 @@ the capture, so its pushes always apply client-side; with `ssr: false` they
 bake into the shell. See `/loader` → "Writing Handles from Loaders". `useHandle`
 re-renders on every handle update, late loader pushes included.
 
+### When handle values change (by design)
+
+Handle values are reactive and arrive on their own channel, by design. A value
+belongs to the segment that pushed it and reaches `useHandle` when that push
+settles. The page never waits for a handle, and a handle never shows the next
+page's values over the page being left:
+
+| Case                                                                                                                                       | What `useHandle` returns                                                                                                                |
+| ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Document load                                                                                                                              | The values the HTML was rendered from. `push(promise)` and `.defer()` are awaited during SSR, so the document ships the resolved value. |
+| Navigation to a page that commits at once (a cold click that mounts new segments)                                                          | The destination's values, in the page's commit; the page's effects read them                                                            |
+| Navigation to a page React holds in a transition (`transition()`, same-route search change, fully prefetched click, a handler that awaits) | The page being left keeps its values; the destination's land in the commit right after the page, in the same task, before paint         |
+| `push(promise)` or `.defer()` on a client navigation                                                                                       | The previous value, then the new one when the promise resolves, possibly well after the page                                            |
+
+You never see a pending value, a blank, or the destination's title over the old
+page. A crumb whose `content` is a promise read with `use()` in `<Suspense>`
+never holds the page either; only that boundary waits for it.
+
+**What this means for effects.** An effect keyed only on the URL
+(`usePathname()`) can run before the destination's values arrive and read the
+previous page's value. That is the contract, not a bug. When a reader must tie a
+handle value to a page (an analytics `page_view`), put the page's path in the
+handle value and key the effect on the value, deduped by path:
+
+```ts
+// handles/page-view.ts
+import { createHandle } from "@rangojs/router";
+
+export interface PageView {
+  path: string;
+  title?: string;
+}
+
+// Collect the item, not the array of segment arrays.
+export const PageView = createHandle<PageView, PageView | undefined>(
+  (segments) => segments.flat().at(-1),
+);
+```
+
+```tsx
+// urls: a root slot that re-runs on every navigation
+parallel(
+  {
+    "@pageView": (ctx) => {
+      ctx.use(PageView)({ path: ctx.pathname + ctx.url.search });
+      return null;
+    },
+  },
+  () => [revalidate(true)],
+);
+```
+
+```tsx
+"use client";
+import { useEffect, useRef } from "react";
+import { useHandle } from "@rangojs/router/client";
+import { PageView } from "./handles/page-view";
+
+export function PageViews() {
+  const pv = useHandle(PageView);
+  // Seeded with the landing path: the first page_view is sent elsewhere (a
+  // bootstrap script). Start from `null` to send it from here instead. The
+  // component also renders on the server, where there is no `window`.
+  const last = useRef(
+    typeof window === "undefined"
+      ? null
+      : window.location.pathname + window.location.search,
+  );
+  useEffect(() => {
+    if (!pv || pv.path === last.current) return;
+    last.current = pv.path;
+    gtag("event", "page_view", { page_path: pv.path, page_title: pv.title });
+  }, [pv]);
+  return null;
+}
+```
+
+The effect fires once per page, because the value carries its own path: the
+previous page's value has the previous path and is skipped, and the destination's
+fires when it arrives. Trade-offs:
+
+- Dedupe is by path. Include `ctx.url.search` in `path` if search-only
+  navigations count; a same-URL refresh or an action's revalidation re-delivers
+  an equal value and sends nothing. Under dev StrictMode the mount effect runs
+  twice; the path check covers it.
+- Select or collect the item, not an array: `useHandle` keeps its reference
+  while the value is equal one level deep, and an array of objects is rebuilt on
+  every delivery (an action's included). With the default collector, use
+  `useHandle(PageView, (s) => s.at(-1)?.at(-1))`.
+- Async values arrive later. With `push(promise)` the page_view fires when the
+  promise resolves, with the resolved value; read the title from the value, not
+  from `document.title`.
+- A page that pushes nothing under its own `PageView` keeps the previous value
+  and fires nothing for itself; the root slot above stamps the path on every
+  navigation so every route counts.
+- Back/Forward fires (the entry's path differs from the current one).
+
+A server component that pushes after an `await` throws `LateHandlePushError`:
+reserve the slot in the handler with `ctx.use(Handle).defer()` and resolve it
+from the component (`/breadcrumbs`, "Deferred content").
+
 On a document load `useHandle` hydrates with the handle data its HTML was
 rendered from, wherever the reader sits; late loader pushes reach every reader
 once the document has finished streaming and every boundary has hydrated (see
@@ -107,6 +208,9 @@ function AddToCartButton({ productId }: { productId: string }) {
   // payload: unknown[] | FormData | null (the call's arguments)
   // error: unknown | null (whatever the action threw)
   // result: unknown | null (return value)
+  // revalidationError: unknown | null (a loader that threw while it reran
+  //   after the action; the action succeeded and the loader threw at its
+  //   read: /client-urls -> "A loader that fails on its rerun")
 
   return (
     // .bind keeps the form progressively enhanced; useAction still matches it

package/skills/hooks/navigation.md

@@ -35,15 +35,23 @@ on screen:
 
 | What you want to show                          | Read                                                                                |
 | ---------------------------------------------- | ----------------------------------------------------------------------------------- |
-| a request is out, nothing has arrived          | `state === "loading"`; `pendingUrl` is the URL being fetched                        |
+| a request is out, nothing has arrived          | `pendingUrl` is the URL being fetched; `null` once the response arrives             |
+| the new page is not on screen yet              | `state === "loading"`; `"idle"` commits together with the new page and its URL      |
 | the page has not fully arrived yet             | `isStreaming`: true from the start of the request until the stream ends             |
 | which page is on screen while the request runs | `location`, or `usePathname()` / `useSearchParams()` (see [`./urls.md`](./urls.md)) |
 
-`state` and `pendingUrl` cover the network wait. Once the response has
-arrived a loader may still be streaming, and React keeps the page being left
-on screen where a navigation holds its content (a same-route change, a
-`transition()` route); `isStreaming` covers that part too, so use it for a
-progress indicator that should last until the new page is complete.
+`pendingUrl` covers the network wait. Once the response has arrived a loader
+may still be streaming, and React keeps the page being left on screen where a
+navigation holds its content (a same-route change, a `transition()` route,
+with or without a view transition). `state` stays `"loading"` through that
+part: for a navigation on its own, `"idle"` commits in the same commit as the
+destination's `useSearchParams()`, `usePathname()` and `useParams()`, so a
+component that reads both does not see the navigation finished on the URL it
+is leaving. A server action, or another navigation started and aborted,
+while React holds that page can still bring `"idle"` with the URL being left.
+`isStreaming` can outlast that commit (a loader still streaming below a
+boundary that already showed), so use it for a progress indicator that should
+last until the new page is complete.
 
 On Back/Forward the address bar changes at once, before any of this: during
 the wait `window.location` is the entry being fetched, the same URL as
@@ -51,9 +59,9 @@ the wait `window.location` is the entry being fetched, the same URL as
 from the client's history cache restores its page in one commit and reports
 no pending state.
 
-`location` moves when the response arrives. Where React then holds the page
-being left, it is ahead of the screen for that last part of the wait, and so
-is a URL hook in a component that first mounts then (issue #1046).
+`location` moves in that commit too. A component that first mounts while
+React holds the page being left reads the destination's `location` and URL
+hooks (issue #1046).
 
 ### useRouter()
 
@@ -103,7 +111,10 @@ structured-clone-safe data; see [`./state.md`](./state.md)).
 Target resolution: a path starting with `/` is app-absolute and gets the
 router `basename` prefixed. A relative path (`"cart"`, `"./cart"`) resolves
 against the current `include()` mount, so `router.push("cart")` inside
-`include("/shop", ...)` navigates to `/shop/cart`.
+`include("/shop", ...)` navigates to `/shop/cart`. A parameterized mount is
+filled from the current route params: inside `include("/:accountId", ...)` at
+`/acme/board`, `router.push("cart")` navigates to `/acme/cart`; a missing
+mount param rejects the returned promise.
 
 #### Skipping revalidation
 
@@ -176,6 +187,9 @@ const segments = useSegments();
 const part = segments.path[depth];
 ```
 
+Like `useHandle`, it commits with the page: while React holds the page being
+left, `useSegments()` keeps that page's path and segments.
+
 ### useLinkStatus()
 
 Track pending state inside a Link component. `pending` is `true` while a

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