@rangojs/router 0.24.3 → 0.25.0

package/skills/client-urls/SKILL.md

@@ -142,6 +142,85 @@ At the top level of the builder only `path()`, `layout()` and `intercept()`
 are accepted, and the builder must define at least one `path()`. Any helper
 name not in this table throws (`clientUrls() has no route() helper`).
 
+`loader`, `loading`, `revalidate` and `transition` are also exported from
+`@rangojs/router/client`, the same functions the builder hands out, for a
+component's own items (next section).
+
+## A component's own items: `Component.use`
+
+A page, layout or intercept component can carry its own items, as a server
+handler does with `.use` (`/handler-use`): its loaders, its skeleton and its
+revalidation rules travel with it instead of being repeated at every `path()`
+that mounts it. Build them with the helpers from `@rangojs/router/client`. The
+component's module needs no `clientUrls()`, and no `"use client"` of its own
+when a group imports it.
+
+```tsx
+// src/dash/Dashboard.tsx
+"use client";
+import { loader, loading, revalidate, useLoader } from "@rangojs/router/client";
+import * as StatsActions from "./stats.actions";
+import { StatsLoader } from "./stats.loader";
+
+export function Dashboard() {
+  const { data } = useLoader(StatsLoader);
+  return <StatsView stats={data} />;
+}
+Dashboard.use = () => [
+  loader(StatsLoader, () => [
+    revalidate(({ isAction }) => isAction(StatsActions)),
+  ]),
+  loading(<DashboardSkeleton />),
+];
+```
+
+```tsx
+// src/urls/app.client.tsx
+"use client";
+import { clientUrls } from "@rangojs/router/client";
+import { Dashboard } from "../dash/Dashboard";
+
+export default clientUrls(({ path }) => [
+  path("/dash", Dashboard, { name: "dash" }),
+]);
+```
+
+| Component mounted by | Its `.use` may return                          |
+| -------------------- | ---------------------------------------------- |
+| `path()`             | `loader()`, `loading()`, `transition()`        |
+| `layout()`           | `loader()`, `loading()`                        |
+| `intercept()`        | `loader()` (without `ssr: false`), `loading()` |
+
+- **Merge order is the server's.** The component's items come first and the
+  mount site's own items second: an explicit `loading()` or `transition()`
+  wins, loaders accumulate (the same definition in both gives two loaders, as
+  `loader(Def)` twice does). A layout component's loaders are layout loaders,
+  shared by every route below it.
+- **No routes inside `.use`.** `path()`, `layout()` and `intercept()` there
+  throw (`clientUrls() does not support path() inside Dashboard.use`): route
+  types and the generated `.gen.ts` are read from the builder's own items.
+  Unlike a server layout handler's `.use`, a client layout's cannot add
+  routes.
+- **`.use` runs when the group is defined**, once per mount site (in the
+  browser, during SSR and in discovery), never at render. The error for an
+  item the site does not take names the component.
+- **A predicate in `.use` runs on the server,** as one in the builder does:
+  the build hoists it out of the component's module with the rules below,
+  and it registers when a group whose routes use the component loads on the
+  server, wherever the module sits: behind barrels or in another workspace
+  package. A predicate in `node_modules` is not hoisted,
+  and route discovery fails naming its loader.
+- **Import the helpers from `@rangojs/router/client`.** The same names from
+  `@rangojs/router` are the server DSL's; called in a client module they
+  throw, pointing to `@rangojs/router/client`.
+- In dev, an edit of a component's `.use` refreshes its groups' projections
+  and predicates, as an edit of the group does.
+- Under `isolatedDeclarations` (a library's sources), an exported function
+  cannot take an assigned property: declare the component unexported,
+  assign `.use`, and export it through a const typed `ClientUrlComponent`.
+- A `createLoader()` definition's own `.use` (`Def.use`) is not read inside
+  `clientUrls()` yet: put its `revalidate()` on the `loader()` call.
+
 `include`, `parallel`, `cache`, `middleware`, `errorBoundary`,
 `notFoundBoundary` **throw** — and that is a design position, not a gap.
 Client route groups are a PERFORMANCE surface (instant presentation, held
@@ -201,10 +280,11 @@ the arguments and type of a `urls()` loader's (`ShouldRevalidateFn` from
 browser before the request goes out; there is no client-computed decision and
 no hybrid.
 
-You still write the predicate in the `"use client"` module. The rango Vite
-plugin hoists each `revalidate()` argument into a server-only module, leaves a
-key in the browser and SSR copies, and registers the predicate when the
-group's module loads on the server (a lazy `include()` stays lazy). The cost
+You still write the predicate in the `"use client"` module, or in a
+component's `.use`. The rango Vite plugin hoists each `revalidate()` argument
+into a server-only module, leaves a key in the browser and SSR copies, and
+registers the predicate when the group's module loads on the server, with
+those of the modules it imports (a lazy `include()` stays lazy). The cost
 is a rule: **the argument may reference imports and globals only.** Anything
 else is a build error naming `file:line:column`, starting
 `[rango] clientUrls() revalidate() at ...: revalidate() runs on the server; ...`.
@@ -213,6 +293,14 @@ else is a build error naming `file:line:column`, starting
   (`revalidate(isCartAction)`), a namespace member (`P.cart`), a call of an
   imported factory (`makePredicate("cart")`), and globals such as `URL`,
   `Boolean` and `import.meta.env`.
+- `revalidate(true)` / `revalidate(false)`, shorthand for `() => true` /
+  `() => false`: a boolean LITERAL stays in place (nothing to hoist). Any
+  other argument is hoisted whatever it evaluates to, because the build cannot
+  tell an imported boolean from an imported predicate: the server evaluates
+  it, and a boolean result is the same constant answer
+  (`revalidate(HOLD_SESSION)` with an imported flag works). A value that is
+  neither fails when the server mounts the group, naming the route and
+  loader.
 - A binding declared in the same `"use client"` module is rejected: move the
   predicate to its own module without `"use client"` and import it, or write it
   inline. A binding of an enclosing function is rejected: read it from the
@@ -223,7 +311,8 @@ else is a build error naming `file:line:column`, starting
   request (a cookie or a search param) and read it from the argument, or
   refresh with `useRefreshLoaders`.
 - An `async` or generator function, a spread, a second argument, no argument,
-  or a non-function value (object, array or string literal) is rejected.
+  or a literal that is neither a function nor a boolean (object, array,
+  string, number or `null`) is rejected.
 - An import of `client-only`, or of a module whose directive prologue is
   `"use client"`, is rejected (on the server its exports are client
   references). A `"use server"` import is fine: on the server it is the real
@@ -273,10 +362,10 @@ with the ternary above instead (same rule as a server-tree loader). A bare
 `isAction(refs)` is a hard `false` on navigation too, so the loader stops
 refetching when params change.
 
-`intercept()` loaders inside `clientUrls()` do not apply their `revalidate()`
-yet (a known gap, left for a follow-up). The build still checks those
-predicates like any other, so one that captures a binding of the `"use client"`
-module fails the build although nothing runs it: import it, or drop it.
+`intercept()` loaders inside `clientUrls()` take `revalidate()` the same way:
+the build moves the predicate to the server, and it runs there with the same
+arguments, `actionResult` included, so an action from the modal re-runs only
+the loaders whose predicate says so.
 
 A group `layout()` loader revalidates as a server layout's loader does. With no
 `revalidate()` a navigation keeps it, whichever route of the layout it goes to
@@ -292,7 +381,7 @@ currentParams.slug !== nextParams.slug ? true : defaultShouldRevalidate)`.
 
 Two scars worth copying:
 
-- A blunt `() => false` keeps serving the OLD product on product→product
+- A blunt `revalidate(false)` keeps serving the OLD product on product→product
   navigations (same route, new param). Make predicates param-sensitive:
   return `defaultShouldRevalidate` when the identifying param changed.
 - One action, per-loader outcomes: a cart badge loader revalidates on cart
@@ -312,8 +401,8 @@ Everything after that is decided on the server, while it handles that request:
 - **The browser's caches.** When the response arrives the browser marks its
   history cache stale and drops its prefetches, unless the action called
   `keepClientCache()` (`/server-actions` → "Client Cache After an Action").
-- **A loader that fails on its rerun** reaches your `onError` on the server and
-  the page as an error, below.
+- **A loader that fails on its rerun** reaches your `onError` on the server,
+  and in the browser it throws at its read, below.
 
 A form's React state survives an action's revalidation in a group, as on a
 `urls()` route: the commit renders into the mounted page instead of remounting
@@ -322,17 +411,79 @@ it, so a controlled input keeps what the user typed.
 ### A loader that fails on its rerun
 
 The action has already run when its loaders rerun, so a loader that throws
-there does not undo it. Where the error lands decides what the user sees:
+there does not undo it. It behaves as on a navigation, on every route (a group
+route or a `urls()` route, with or without `loading()`), and whether the
+action was called directly or from `<form action>`, `useActionState` or
+`useTransition`:
+
+- **The call resolves** with the action's return value.
+- **The loader throws in place,** at its `useLoader` read. The nearest
+  boundary to the read catches it: your own React error boundary around the
+  read, else the `errorBoundary()` around the group's `include()` mount (or
+  the route's, in `urls()`), else the router's root error boundary.
+- **Everything outside that boundary stays,** with its React state: a form
+  next to the failed list keeps what the user typed. Loaders that reran
+  without error commit their new data in the same commit.
+- **The error is reported**: to your `onError` on the server (phase
+  `"loader"`), and in the browser as `revalidationError` on the action's
+  `useAction()` state. `error` stays `null` there and `result` holds the
+  action's return value, so "saved, but the list could not refresh" reads
+  apart from "the save failed".
+- **A later rerun that succeeds clears it.** An `errorBoundary()` fallback
+  clears on the next action or navigation that reruns the loader without
+  error. Your own boundary resets by its own rule: key the reset on data that
+  reruns with the loader and is read outside the boundary, so the reset lands
+  in the same render as the new data. A reset when the action settles can run
+  before React rendered the commit and catch the old failure again.
+
+```tsx
+// in the group's "use client" module
+function StockPanel() {
+  // Reruns with every save and never throws.
+  const { data: status } = useLoader(SaveStatusLoader);
+  return (
+    <StockBoundary resetKey={status.version}>
+      <StockList /> {/* useLoader(StockLoader) throws here on a failed rerun */}
+    </StockBoundary>
+  );
+}
 
-| The route                                                  | Called directly (`await action()`)                                                                                                                                                             | From `<form action>`, `useActionState` or `useTransition`                                                                                             |
-| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| A group route, or a `urls()` route without `loading()`     | The call rejects with the loader's error (`"An error occurred"` in a build), although the action returned. Nothing of that revalidation commits: the page keeps its data and its React state.  | React hands the rejection to the nearest React error boundary above the form. With none of yours, the router's root error boundary replaces the page. |
-| A `urls()` route with `loading()`                          | The call resolves with the action's result. The commit renders, the loader's read throws, and the nearest React error boundary catches it; with none of yours, the root one replaces the page. | The same.                                                                                                                                             |
-| Under an `errorBoundary()` (for a group, around the mount) | Its fallback replaces the route: the page and its form state unmount.                                                                                                                          | The same.                                                                                                                                             |
+function SaveStock({ sku }: { sku: string }) {
+  const { revalidationError } = useAction(saveStock);
+  const [stale, setStale] = useState(false);
+  // useAction resets to idle once the action has settled: keep the notice.
+  useEffect(() => {
+    if (revalidationError) setStale(true);
+  }, [revalidationError]);
+  return (
+    <form action={saveStock.bind(null, sku)}>
+      <button>Save</button>
+      {stale && (
+        <p role="status">Saved. The stock count could not be refreshed.</p>
+      )}
+    </form>
+  );
+}
+```
 
-A group route's `loading()` does not change the first row. For a failure the
-user can retry (a flaky upstream, a rate limit), return it as data instead of
-throwing, and render it where the data goes:
+`StockBoundary` is an ordinary React error boundary whose
+`getDerivedStateFromProps` clears its error when `resetKey` changes. A loader
+that throws `notFound()` or `redirect()` is not a failure and keeps its path:
+a `redirect()` (a deleted record's page) replaces the route's content and
+navigates, and the layouts above keep their instance. A no-JS form post
+renders the whole document after the action, so a loader that throws there
+behaves as on a page load. Every refetch the router runs for an action
+follows the same rule (after several actions at once, after a navigation
+during it), and the action that ran it reports the error as its
+`revalidationError`; with several actions at once, that is the one whose
+refetch covers them all. Not covered yet: an `intercept()`'s loaders, and a
+parallel slot's loaders under its own `loading()`, decoded above the slot's
+content, so a boundary inside the slot does not see the error.
+
+For a failure the user should see in place of the data without an error
+boundary (a flaky upstream, a
+rate limit), return it as data instead of throwing, and render it where the
+data goes:
 
 ```tsx
 // stock.loader.ts
@@ -355,10 +506,7 @@ function Stock() {
 }
 ```
 
-The action resolves with its result, the page and its form state stay, and the
-next action or navigation that reruns the loader replaces the message. Keep
-throwing for a failure that should stop the page, with an `errorBoundary()`
-around the mount for it.
+The next action or navigation that reruns the loader replaces the message.
 
 A failure returned as data is an ordinary value, so whatever stores the
 loader's value stores it too: a `cache()` on the loader serves it for its TTL,
@@ -370,8 +518,9 @@ data in a loader that is not cached itself.
 
 Pinned by dev + production e2e in the router repository (a group, its `urls()`
 twin, each with and without `loading()`, and the group under an
-`errorBoundary()`), and by a `serveShellRequest({ action })` test of the
-response.
+`errorBoundary()`), and by `serveShellRequest({ action })` tests whose
+`readAction()` reads the call's answer as the browser does: the result and
+the `revalidationError`.
 
 ## Loaders are full citizens: signals and handles
 
@@ -386,7 +535,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 }));
   if (!(await exists(ctx.params.slug))) notFound(`No "${ctx.params.slug}"`);
   return getProduct(ctx.params.slug);
 });
@@ -507,7 +656,9 @@ rest of the destination; otherwise it is held. A same-route click
   that layout is new to the page (entering the group from outside).
 - `loading()` in `clientUrls()` takes no options, and a flagged `loading()`
   on a server layout above the group defers nothing for the group's routes.
-- `intercept()` loaders accept the flag and ignore it, as in `urls()`.
+- On an `intercept()` loader the flag works as in `urls()`: an in-group
+  prefetch of the intercept's target defers it, and the click opens the modal
+  at once with one fill for it.
 - With `ssr: false` on a `ppr` group route the flag is ignored (the bake
   lane), as on a server route.
 - Test it with `serveShellRequest` in the Flight project: mount the module
@@ -557,15 +708,27 @@ a hard load of the target URL renders the full route.
   hold; it adds the view-transition animation. Inline `<Suspense>` above each
   `useLoader` read is still the finer-grained tool when different reads on
   one route should wait independently.
+- **Parameterized mounts.** A group under `include("/:locale", ...)`,
+  `include("/:locale?", ...)` or `include("/:accountId/:projectId", ...)`
+  presents at the click like one under a literal mount, and `useParams()` in
+  the destination carries the mount's params. A click that changes a mount
+  param (`/en/...` to `/de/...`) is another instance of the include: no
+  optimistic frame, a plain navigation. The group's intercepts open only from
+  one of its routes in the same mount instance. A URL the server routes
+  elsewhere (a root route that a group `/:slug` under `/:locale?` also
+  matches) never renders as a group route: the server ships the competing
+  routes with the group.
 - **Two parallel loaders with equal latency look "SSR'd" together.** Loaders
   kick off in parallel, so awaiting one (`ssr: false`) gives
   same-or-faster siblings time to settle coincidentally. Do not read "it was
   in the HTML once" as a guarantee — only the flagged loader is guaranteed.
 - **Hook semantics shift inside a group.** `usePathname` is ABSOLUTE (mount
   included) — never compare it to your own `path()` patterns; build local
-  links with `useHref()` (`groupHref("/items/1")` composes the mount).
-  `useRouter().push("cart")` (RELATIVE,
-  no leading slash) resolves against the mount; `push("/x")` stays
+  links with `useReverse(routes)` from the group's `.gen.ts`: it composes the
+  mount and fills its params. `useHref()` (`groupHref("/items/1")`) and a
+  relative `useRouter().push("cart")` also fill `:param` mount segments from
+  the current params (a missing one throws, or rejects the push), but append
+  the rest unchecked. `push("/x")` stays
   app-absolute by design (never auto-prefixed). `useSearchParams` carries REAL
   values during SSR (live request seeds the SSR store; on ppr routes the
   capture/resume renders seed the shell key's own sorted search — search is

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