@rangojs/router 0.24.4 → 0.25.0

package/skills/app-structure/multi-app.md

@@ -0,0 +1,280 @@
+# Several apps under createHostRouter()
+
+One deployment, several independently routed apps: marketing on the apex
+(`example.com`, `www.example.com`), the product on `app.`, the staff tools
+on `admin.`, the docs on `docs.`. Each app is an ordinary `createRouter()`
+app with its own `urls()`, Document and generated route map; the host router
+only picks which one handles a request.
+
+Reach for this when parts of the product want different documents, chrome,
+deploy cadence or hostnames. Sections that share one document belong in one
+router as `include()`s ([`./large-app.md`](./large-app.md)): a navigation
+between apps is always a document load.
+
+References in the router repository: `examples/cloudflare-multi-router` (a
+Cloudflare host entry, path-mounted and host-mounted apps, a shared cache)
+and `packages/rangojs-router/e2e/test-app/.host-fixture` (the Node preset,
+the host-override cookie, two apps on one store).
+
+## File tree
+
+```
+src/
+  worker.rsc.tsx              the host router (Cloudflare: you own the entry)
+  env.ts                      bindings shared by every app
+  shared/
+    document.tsx              "use client" Document the apps pass to createRouter()
+    styles.css                one stylesheet (e.g. @import "tailwindcss")
+    theme.ts                  one ThemeConfig
+    cache.ts                  one cache store factory
+    origins.ts                each app's origin, per environment
+    top-nav.tsx               components every app renders
+  apps/
+    site/   router.tsx  handler.ts  urls.tsx  router.named-routes.gen.ts  tsconfig.json
+    app/    router.tsx  handler.ts  urls.tsx  router.named-routes.gen.ts  tsconfig.json  …
+    admin/  …
+    docs/   …
+tsconfig.json                 the host entry's program only
+```
+
+## The host router
+
+```tsx
+// src/worker.rsc.tsx
+import {
+  createHostRouter,
+  defineHosts,
+  isNoRouteMatchError,
+} from "@rangojs/router/host";
+import type { AppBindings } from "./env";
+
+export const hosts = defineHosts({
+  site: [".", "www.*"],
+  app: "app.*",
+  admin: "admin.*",
+  docs: "docs.*",
+});
+
+// Dev: every app answers on localhost, and the x-rango-host cookie picks one
+// (x-rango-host=admin.example.com). The request is forwarded unchanged.
+const hostRouter = createHostRouter({
+  hostOverride: { cookieName: "x-rango-host", allowedHosts: ["localhost"] },
+});
+
+// Lazy mounts: an app's module graph loads on its first request, and each app
+// keeps its own cache version.
+hostRouter.host(hosts.admin).lazy(() => import("./apps/admin/handler"));
+hostRouter.host(hosts.app).lazy(() => import("./apps/app/handler"));
+hostRouter.host(hosts.docs).lazy(() => import("./apps/docs/handler"));
+hostRouter.host(hosts.site).lazy(() => import("./apps/site/handler"));
+// localhost has one label: neither "." nor "*." matches it.
+hostRouter.host(["localhost"]).lazy(() => import("./apps/site/handler"));
+
+export default {
+  async fetch(request, env, ctx) {
+    try {
+      return await hostRouter.match(request, { env, ctx });
+    } catch (err) {
+      if (isNoRouteMatchError(err))
+        return new Response("Not Found", { status: 404 });
+      throw err;
+    }
+  },
+} satisfies ExportedHandler<AppBindings>;
+```
+
+Patterns are tried in registration order, first match wins; "apex" means
+exactly two labels (no public-suffix list), so `example.co.uk` needs its own
+pattern (`/host-router` → "Pattern Syntax").
+
+On the `node` and `vercel` presets rango owns the entry: export the instance
+(`export default hostRouter`), drop the `fetch` wrapper, and an unmatched host
+answers 404 on its own. Point `rango({ hostRouter: "./src/worker.rsc.tsx" })`
+at the module when auto-detection cannot pick it.
+
+## Each app
+
+```ts
+// src/apps/app/handler.ts: what the host router's lazy mount imports
+import { router } from "./router";
+
+export default (request: Request, input: any) => router.fetch(request, input);
+```
+
+```tsx
+// src/apps/app/router.tsx
+import { createRouter } from "@rangojs/router";
+import { Document } from "../../shared/document";
+import { appCache } from "../../shared/cache";
+import { theme } from "../../shared/theme";
+import type { AppBindings } from "../../env";
+import { loadSession } from "./session";
+import { appPatterns } from "./urls";
+
+export const router = createRouter<AppBindings>({
+  document: Document,
+  cache: appCache,
+  theme,
+})
+  .use(loadSession)
+  .routes(appPatterns);
+```
+
+```tsx
+// src/apps/app/urls.tsx
+import { urls } from "@rangojs/router";
+import { Outlet } from "@rangojs/router/client";
+import { TopNav } from "../../shared/top-nav";
+import { DashboardPage, LoginPage } from "./pages";
+import { requireUser } from "./session";
+
+function Shell() {
+  return (
+    <>
+      <TopNav />
+      <Outlet />
+    </>
+  );
+}
+
+export const appPatterns = urls(({ path, layout, middleware }) => [
+  path("/login", LoginPage, { name: "login" }),
+  layout(Shell, () => [
+    middleware(requireUser),
+    path("/", DashboardPage, { name: "dashboard" }),
+    // … the app's sections as includes, as in ./large-app.md
+  ]),
+]);
+```
+
+Inside an app, everything in the other recipes applies unchanged: the `app.`
+app is [`./large-app.md`](./large-app.md) without its marketing pages, the
+`docs.` app is [`./content-site.md`](./content-site.md), and `site` is a
+handful of `ppr` pages:
+
+```tsx
+// src/apps/site/urls.tsx (excerpt)
+export const sitePatterns = urls(({ path, layout }) => [
+  layout(SiteLayout, () => [
+    path("/", Home, { name: "home", ppr: true }),
+    path("/pricing", Pricing, { name: "pricing", ppr: true }),
+  ]),
+]);
+```
+
+## What is shared, and how
+
+| Shared        | How                                                                                            | Notes                                                                                                                                                                                                                       |
+| ------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Components    | ordinary imports from `src/shared/`                                                            | One Vite build and one client manifest: a shared client component ships as the same hashed asset to every app. Keep route-name-typed calls (`ctx.reverse("…")`, `href()`) out of shared code; each app's names are its own. |
+| The Document  | one `"use client"` component every `createRouter({ document })` passes, or one per app         | Each document load is that app's own; apps may differ freely                                                                                                                                                                |
+| CSS           | `import styles from "../../shared/styles.css?url"` in the Document, `<link precedence>`        | Compiles to one hashed asset, cached across apps. Apps need not agree on `precedence`: a cross-app navigation is a document load (`/css`)                                                                                   |
+| Theme         | one `ThemeConfig` object passed as `theme` to every router                                     | The stored choice is a host-only cookie (`src/theme/ThemeProvider.tsx`, no `Domain`), so a theme picked on `app.` does not follow the user to `docs.`                                                                       |
+| Cache store   | one factory (`cache: appCache`), one KV namespace                                              | Keys holding one router's output start with that router's id, so two apps never read each other's shells, records or loader entries. Keep `createRouter({ ... })` an inline object literal (or pass `id`) so ids are stable |
+| Session       | a cookie on the parent domain, `cookies().set("session", token, { domain: "example.com", … })` | Set by the app that signs users in; every app resolves it in its own `router.use()`                                                                                                                                         |
+| Client caches | not shared                                                                                     | The state cookie is `rango-state_{routerId}`, one per app, so sibling apps on one origin do not collide                                                                                                                     |
+
+## TypeScript: one program per app
+
+Every router's `router.named-routes.gen.ts` augments the one global
+`Rango.GeneratedRouteMap`, so two apps with overlapping route names
+(`home`, `login`) collide in one program. Give each app its own
+`tsconfig.json`, and keep the root program to the host entry:
+
+```jsonc
+// tsconfig.json: the host entry only
+{ "extends": "./tsconfig.base.json", "include": ["src/env.ts", "src/worker.rsc.tsx"] }
+
+// src/apps/app/tsconfig.json: one app, its generated map, the shared code
+{ "extends": "../../../tsconfig.base.json", "include": ["**/*", "../../shared/**/*", "../../env.ts"] }
+```
+
+The root program still type-checks the apps' source through the lazy
+`import()`s, but not their generated maps, as long as no app source imports
+its own `*.named-routes.gen.ts`. Run `tsc -p` for each program in CI.
+Generated and committed: one `router.named-routes.gen.ts` per app (plus
+per-module `*.gen.ts` where an app uses `useReverse(routes)`). See
+`/typesafety` → multi-project setup.
+
+## Dev: the host-override cookie
+
+`vite dev` serves every app on one origin, `localhost`. The
+`hostOverride` option picks the app from a cookie when the request's real
+host matches `allowedHosts`:
+
+```js
+// browser devtools, on http://localhost:5173
+document.cookie = "x-rango-host=admin.example.com; path=/";
+```
+
+Reload and the admin app answers; delete the cookie for the site. Without a
+`fallback()`, a cookie the router refuses (a malformed hostname, a host not
+in `allowedHosts`) answers 400 and clears the cookie. Playwright sets it with
+`context.addCookies([{ name: "x-rango-host", value: "admin.example.com", url }])`,
+which is how both reference apps run their dev and production e2e.
+
+All apps answer under one origin in this mode, so links to another app's
+production host leave the dev server; switch apps by changing the cookie.
+
+## Links between apps
+
+A navigation from one app to another is a full document load, by design. A
+soft in-place swap between apps shipped once (#476) and was replaced by a
+document navigation (#555): a stylesheet two apps share by `href` could drop
+on the swap (React dedups stylesheets by `href`), and the theme, warmup and
+prefetch settings, which are document-lifetime, would remount or never take
+effect. A document load re-establishes the target app's whole document.
+
+| The other app is                                               | Link with                                                                                         | What happens                                                                                                                                                                         |
+| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| On another host (`app.example.com`)                            | an absolute URL: `<Link to="https://app.example.com/">` or `<a href>`                             | Another origin is external to `<Link>` (`src/browser/react/Link.tsx`) and to the plain-anchor interceptor: the browser navigates, nothing is prefetched                              |
+| On the same origin under a path (`host(["example.com/docs"])`) | `<Link to="/docs" reloadDocument prefetch="none">` or `<a href="/docs" data-no-intercept="true">` | A document navigation at the click. A plain same-origin `<Link>` also ends in a document load, after a wasted round trip: the server answers the partial request with `X-RSC-Reload` |
+
+```tsx
+// src/shared/origins.ts
+export const ORIGINS = {
+  site: import.meta.env.VITE_SITE_ORIGIN ?? "https://example.com",
+  app: import.meta.env.VITE_APP_ORIGIN ?? "https://app.example.com",
+  docs: import.meta.env.VITE_DOCS_ORIGIN ?? "https://docs.example.com",
+} as const;
+
+// src/shared/top-nav.tsx: a server component every app renders
+import { Link } from "@rangojs/router/client";
+import { ORIGINS } from "./origins";
+
+export function TopNav() {
+  return (
+    <nav>
+      <Link to={`${ORIGINS.site}/`}>Home</Link>
+      <Link to={`${ORIGINS.docs}/`}>Docs</Link>
+      <Link to={`${ORIGINS.app}/`}>Open the app</Link>
+    </nav>
+  );
+}
+```
+
+`reloadDocument` alone does not stop the prefetch: without
+`prefetch="none"`, a visible link still sends one, which the other app
+answers with `X-RSC-Reload` and the client drops. Make each app's entry pages
+fast as documents (`ppr`, or `Prerender`), since every cross-app click lands
+on one.
+
+## Deploys
+
+Each `createRouter()` app has its own cache version, computed from the code
+its router can run up to a lazy mount. A deploy that changes the admin app's
+server code clears the admin app's cached data and stored HTML and reloads
+its open tabs; the other apps keep theirs. Code shared by statically
+importing modules moves every app that imports it (`/host-router` →
+"Deploys and the cache").
+
+## Why
+
+| Choice                       | Why                                                                                           |
+| ---------------------------- | --------------------------------------------------------------------------------------------- |
+| One `createRouter()` per app | Own document, routes, names, middleware, cache version                                        |
+| `.lazy()` mounts             | An app's graph loads on its first request, and the mount is where its cache version stops     |
+| `defineHosts`                | One typed table of patterns, reused by tests                                                  |
+| The cookie override in dev   | One dev origin, hydration same-origin; the reference apps' e2e drive every app through it     |
+| Absolute URLs between hosts  | Another origin is another document; no request is wasted on a prefetch or a reload round trip |
+| A program per app            | Route-name augmentations of different apps cannot collide                                     |

package/skills/breadcrumbs/SKILL.md

@@ -137,6 +137,11 @@ path("/product/:id", async (ctx) => {
 Async content is a `Promise<ReactNode>`. Resolve it in your component
 with React's `use()` hook wrapped in `<Suspense>`.
 
+A server component that pushes a crumb after an `await` throws
+`LateHandlePushError`. Reserve the crumb in the handler with `.defer()` and
+resolve it from the component (see "Deferred content" below); the same works
+for a `Meta` title.
+
 A crumb the HANDLER pushes is handler output. In a route `cache()` entry and
 in a `ppr` shell it is stored resolved: the cache write, or the shell capture
 (within `ppr.captureTimeout`), waits for a `content` promise and for a
@@ -202,7 +207,7 @@ consumer sees it — `useHandle(Breadcrumbs)` returns the resolved item, never a
 `Promise`, so you read it like any sync crumb (no `use()`, no thenable narrowing).
 On a full/SSR load the value is resolved server-side; on a soft navigation the
 breadcrumbs HOLD the previous resolved value until the deferred value lands, then
-swap in — no blank, no pending entry. If the slot times out to `else: null`/
+swap in — no blank, no pending entry. The hold-then-swap is deliberate: a handle never holds the page and never shows the next page's values over the old one (see [hooks](../hooks/handle-and-actions.md#when-handle-values-change-by-design)). If the slot times out to `else: null`/
 undefined, the entry is simply dropped. Use `.defer()` only when even
 `label`/`href` are unknown at handler time AND the producer is a component,
 not a loader — a loader-produced crumb pushes directly from the loader body

package/skills/caching/SKILL.md

@@ -894,7 +894,9 @@ and a read that worked only on direct visits would break the first time a
 rewritten request reached it. A PPR shell capture and a render the document
 cache stores read it as `undefined` instead of throwing: those renders are
 the target page as a direct visit renders it, and the rewritten visitor's
-own render (outside them) still sees its URL. A response route under
+own render (outside them) still sees its URL. A shell keyed by the visitor's
+URL (`rewrite(...).shell("visitor")`, `/ppr`) reads it, since its key covers
+that URL. A response route under
 `cache()` whose handler read it is not stored.
 
 A loader body invoked from a handler with `await ctx.use(Loader)` may read

package/skills/catalog.json

@@ -9,6 +9,12 @@
       "argumentHint": "",
       "path": "skills/api-client/SKILL.md"
     },
+    {
+      "name": "app-structure",
+      "description": "Concrete urls() layouts for whole Rango apps, with the file tree, router.tsx, the root urls.tsx with sync include() of section modules, and where middleware, server layouts, clientUrls() groups, response routes, caching, prerender, PPR and boundaries sit. Recipes for a large signed-in app with a protected admin area (auth, onboarding, app, settings and admin as clientUrls() groups under one server shell), several apps under createHostRouter(), a docs site or blog, and a shop. Use when starting or restructuring a Rango app, laying out urls() files, splitting an app into sections or separate apps, or setting up a dashboard, SaaS, multi-app, static or content site, or e-commerce app.",
+      "argumentHint": "[large-app|multi-app|content-site|e-commerce]",
+      "path": "skills/app-structure/SKILL.md"
+    },
     {
       "name": "breadcrumbs",
       "description": "Built-in Breadcrumbs handle for accumulating breadcrumb navigation across route segments. Use when building a breadcrumb trail for nested routes, or asking how to show the current navigation path in a layout.",
@@ -273,6 +279,12 @@
       "argumentHint": "[profile-name]",
       "path": "skills/use-cache/SKILL.md"
     },
+    {
+      "name": "ux-architecture",
+      "description": "Architect a Rango app so navigation is instant and stable — when a server urls() page or a clientUrls() group wins, where layouts, loaders, Suspense boundaries, revalidate() rules, prefetch, transition(), intercept() modals and actions go, with worked recipes (shop, dashboard tabs, settings forms, search filters, a modal over a list) and the anti-patterns behind remounts, skeleton flashes and slow clicks. Use when designing or reviewing a Rango app's routing, layout, loading or navigation UX, choosing between urls() and clientUrls(), placing a loader or a boundary, writing revalidate() rules, or debugging a remount, a re-shown fallback or a click that waits.",
+      "argumentHint": "[shop|dashboard|settings|search|modal]",
+      "path": "skills/ux-architecture/SKILL.md"
+    },
     {
       "name": "vercel",
       "description": "Deploy a Rango app to Vercel Functions (Build Output API v3). Use when deploying a Rango app to Vercel, or asking how the router works with Vercel Functions and the Build Output API.",

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
@@ -573,9 +724,11 @@ a hard load of the target URL renders the full route.
   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