@rangojs/router 0.0.0-experimental.dfdb0387 → 0.0.0-experimental.e16b7c00

package/skills/handler-use/SKILL.md

@@ -0,0 +1,364 @@
+---
+name: handler-use
+description: Attach default loaders, middleware, parallels, and other use items directly to handlers via handler.use, and compose them with explicit use() at mount sites
+argument-hint: "[handler]"
+---
+
+# Handler-Attached `.use`
+
+A handler function (or branded `Static`/`Prerender`/`Passthrough` definition) can carry its own defaults via a `.use` callback that returns an array of `use` items (loader, middleware, parallel, intercept, layout, loading, etc.). The mount-site DSL (`path()`, `layout()`, `parallel()`, `intercept()`) merges those defaults with any explicit `use()` callback supplied at the registration site.
+
+This lets handlers be **self-contained, reusable units** — a page brings its own loader, a layout brings its own middleware, a parallel slot brings its own data + skeleton — without forcing every caller to wire the same items at every mount site.
+
+Canonical implementation reference:
+[src/route-definition/resolve-handler-use.ts](../../src/route-definition/resolve-handler-use.ts)
+
+## Defining a handler with `.use`
+
+Attach `.use` to the function (or to the branded definition for `Static()`/`Prerender()`/`Passthrough()`):
+
+```typescript
+import {
+  loader,
+  middleware,
+  loading,
+  createLoader,
+  type Handler,
+} from "@rangojs/router";
+
+export const ProductLoader = createLoader(async (ctx) =>
+  fetchProduct(ctx.params.slug),
+);
+
+const ProductPage: Handler<"/product/:slug"> = async (ctx) => {
+  const product = await ctx.use(ProductLoader);
+  return <ProductView product={product} />;
+};
+
+ProductPage.use = () => [
+  loader(ProductLoader),
+  loading(<ProductSkeleton />),
+  middleware(async (ctx, next) => {
+    await next();
+    ctx.header("Cache-Control", "private, max-age=60");
+  }),
+];
+```
+
+Now `ProductPage` carries its loader, loading state, and response-header middleware regardless of where it is mounted.
+
+## Allowed items per mount site
+
+`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()` / `route()`                              | `layout`, `parallel`, `intercept`, `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `cache`, `transition` |
+| `layout()`                                        | All of the above, plus `route`, `include`                                                                                                      |
+| `parallel()` (per slot)                           | `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `transition`                                                           |
+| `intercept()`                                     | `middleware`, `revalidate`, `loader`, `loading`, `errorBoundary`, `notFoundBoundary`, `layout`, `route`, `when`, `transition`                  |
+| Response routes (`path.json()`, `path.text()`, …) | `middleware`, `cache`                                                                                                                          |
+
+For per-item semantics see the dedicated skills: [middleware](../middleware/SKILL.md), [loader](../loader/SKILL.md), [parallel](../parallel/SKILL.md), [intercept](../intercept/SKILL.md), [layout](../layout/SKILL.md), [view-transitions](../view-transitions/SKILL.md).
+
+If `handler.use()` returns a disallowed item for a mount site, registration throws:
+
+```
+handler.use() returned middleware() which is not valid inside parallel().
+Allowed types: revalidate, loader, loading, errorBoundary, notFoundBoundary, transition.
+```
+
+The narrowest contract is `parallel()` — slots cannot bring their own middleware or layout; only data, loading, error/notFound boundaries, revalidation, and transitions.
+
+## Composition with explicit `use()`
+
+Every mount site that takes a `use` callback merges in this order:
+
+1. **`handler.use()` items first** — the handler's defaults.
+2. **Explicit `use()` items second** — overrides specified at the mount site.
+
+Items of the same kind from the explicit `use()` follow the existing override rules of that item type. The most important ones for composition:
+
+- **`loading()`** — last definition wins, so explicit `loading()` replaces the handler's default.
+- **`parallel({ "@slot": … })`** — the last `parallel()` call wins per slot name. Other slots from earlier calls are preserved (see `skills/parallel`).
+- **`loader()`, `middleware()`, etc.** — accumulate; both the handler's and the explicit ones run.
+
+Skip the boilerplate: if neither `handler.use` nor explicit `use()` is provided, no merge happens.
+
+```typescript
+// Handler brings a loader + a (placeholder) loading; explicit use replaces loading.
+const SidebarSlot: Handler = async (ctx) => {
+  const data = await ctx.use(SidebarLoader);
+  return <Sidebar data={data} />;
+};
+SidebarSlot.use = () => [
+  loader(SidebarLoader),
+  loading(<DefaultSidebarSkeleton />),
+];
+
+parallel({ "@sidebar": SidebarSlot }, () => [
+  // Replaces the default skeleton; SidebarLoader from handler.use still runs.
+  loading(<SiteSpecificSidebarSkeleton />),
+]);
+```
+
+## Composable parallel slots (the main pay-off)
+
+The parallel slot site is where `handler.use` shines. A slot handler that owns its data/loading lets a layout declare **just** the slot names — every loader, skeleton, and revalidation contract travels with the slot itself.
+
+### Without `handler.use` (every caller wires it up)
+
+```typescript
+layout(<DashboardLayout />, () => [
+  parallel({ "@cart": CartSummary }, () => [
+    loader(CartLoader),
+    loading(<CartSkeleton />),
+    revalidate(revalidateCartData),
+  ]),
+  parallel({ "@notifs": NotificationPanel }, () => [
+    loader(NotificationsLoader),
+    loading(<NotifsSkeleton />),
+    revalidate(revalidateNotifs),
+  ]),
+  path("/dashboard", DashboardIndex, { name: "dashboard.index" }),
+]);
+```
+
+Every layout that wants `@cart` must repeat the same loader/loading/revalidate triplet.
+
+### With `handler.use` (slot owns its dependencies)
+
+```typescript
+const CartSummary: Handler = async (ctx) => {
+  const cart = await ctx.use(CartLoader);
+  return <CartSummaryView cart={cart} />;
+};
+CartSummary.use = () => [
+  loader(CartLoader),
+  loading(<CartSkeleton />),
+  revalidate(revalidateCartData),
+];
+
+const NotificationPanel: Handler = async (ctx) => {
+  const items = await ctx.use(NotificationsLoader);
+  return <NotificationsView items={items} />;
+};
+NotificationPanel.use = () => [
+  loader(NotificationsLoader),
+  loading(<NotifsSkeleton />),
+  revalidate(revalidateNotifs),
+];
+
+// Mount sites become declarative — no per-call data wiring.
+layout(<DashboardLayout />, () => [
+  parallel({ "@cart": CartSummary, "@notifs": NotificationPanel }),
+  path("/dashboard", DashboardIndex, { name: "dashboard.index" }),
+]);
+
+layout(<AccountLayout />, () => [
+  // Same slot, same defaults, zero re-wiring.
+  parallel({ "@cart": CartSummary }),
+  path("/account", AccountIndex, { name: "account.index" }),
+]);
+```
+
+Each slot handler is now a portable, self-contained unit. Different layouts can use the same slot without copying data plumbing.
+
+### Streaming behavior is per-slot
+
+A slot's `loading()` (whether from `handler.use` or explicit) makes that slot an independent streaming unit — its loader does not block the parent layout. Two slot handlers with their own loading skeletons stream independently.
+
+```typescript
+parallel({
+  "@cart": CartSummary, // handler.use loading() → streams independently
+  "@cartBadge": CartBadge, // no loading() anywhere → awaited before paint
+});
+```
+
+### Two scopes for explicit `use` at the mount site: shared (broadcast) and slot-local
+
+`parallel()` accepts an explicit `use()` callback that **broadcasts** to every slot in the call ([dsl-helpers.ts](../../src/route-definition/dsl-helpers.ts)). That's the right behavior for the items the parallel allow-list permits and that accumulate (`loader`, `revalidate`, `errorBoundary`, `notFoundBoundary`, `transition`) — every slot gets them. (Note: `middleware` is not allowed inside `parallel()`; see the allowed-types table above.)
+
+For single-assignment items like `loading()`, broadcasting overwrites every slot's `handler.use` default. Pass a **slot descriptor** `{ handler, use }` instead: items in the descriptor's `use` apply only to that slot.
+
+```typescript
+parallel({
+  "@meta": MetaSlot,
+  "@sidebar": {
+    handler: SidebarSlot,
+    use: () => [loading(<SidebarSkeleton />)], // ← only @sidebar
+  },
+});
+```
+
+Per-slot merge order is **handler.use → shared use → slot-local use** (narrowest scope wins for last-write-wins items like `loading()`):
+
+```typescript
+parallel(
+  {
+    "@cart": {
+      handler: Cart,
+      use: () => [loading(<CartSkeleton />)], // wins for @cart
+    },
+    "@notifs": Notifs, // gets <BroadcastSkeleton />
+  },
+  () => [
+    loader(SharedAnalyticsLoader), // accumulates on every slot
+    loading(<BroadcastSkeleton />), // applies to slots without slot-local
+  ],
+);
+```
+
+Use the descriptor's `use` for `loading(false)` too — opting one slot out of streaming without affecting siblings:
+
+```typescript
+parallel(
+  {
+    "@cart": { handler: Cart, use: () => [loading(false)] }, // @cart awaits
+    "@notifs": Notifs, // @notifs still streams with broadcast skeleton
+  },
+  () => [loading(<BroadcastSkeleton />)],
+);
+```
+
+Rule of thumb: shared `use` is for items that legitimately apply to every slot. Slot-local `use` is for per-slot precision — especially `loading()` and `loading(false)`.
+
+### Replacing a whole slot from a parent's `handler.use`
+
+A handler can publish a default `parallel({...})` set via its `.use`, and the mount site can replace any individual slot by re-declaring it. Last `parallel()` per slot name wins (see `skills/parallel` § Slot Override Semantics).
+
+```typescript
+const ProductPage: Handler<"/product/:slug"> = (ctx) => (
+  <article>
+    <ProductHero slug={ctx.params.slug} />
+    <ParallelOutlet name="@related" />
+    <ParallelOutlet name="@reviews" />
+  </article>
+);
+ProductPage.use = () => [
+  parallel({
+    "@related": DefaultRelatedProducts,
+    "@reviews": DefaultReviews,
+  }),
+];
+
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  // Override @related only; @reviews keeps the default from handler.use.
+  parallel({ "@related": SiteSpecificRelated }),
+]);
+```
+
+## Other mount sites
+
+### Pages (`path()`)
+
+Page handlers can carry middleware, loaders, error boundaries, parallel slots, etc. — anything from the `path` row of the table above.
+
+```typescript
+const CheckoutPage: Handler<"/checkout"> = async (ctx) => { /* … */ };
+CheckoutPage.use = () => [
+  middleware(requireAuth),
+  loader(CartLoader),
+  errorBoundary(<CheckoutError />),
+  notFoundBoundary(<CheckoutNotFound />),
+];
+```
+
+### Layouts (`layout()`)
+
+Layout handlers can carry middleware that runs for every child route, plus default parallels, includes, etc.
+
+```typescript
+const AdminLayout: Handler = (ctx) => {
+  const user = ctx.get(CurrentUser);
+  return <Admin user={user} />;
+};
+AdminLayout.use = () => [
+  middleware(requireAdmin),
+  parallel({ "@adminNotifs": AdminNotifsSlot }),
+];
+```
+
+### Intercepts (`intercept()`)
+
+Intercept handlers can carry their own middleware chain, loaders, and even nested layouts/routes for the modal shell.
+
+```typescript
+const QuickViewModal: Handler = async (ctx) => {
+  const product = await ctx.use(ProductLoader);
+  return <QuickView product={product} />;
+};
+QuickViewModal.use = () => [
+  loader(ProductLoader),
+  loading(<QuickViewSkeleton />),
+  layout(<ModalChrome />),
+];
+```
+
+## `loading()` is a single-assignment item — scope it correctly
+
+Most `use` items accumulate when merged: `handler.use` `middleware()` runs _and_ explicit `middleware()` runs; both `loader()` registrations apply. `loading()` is different — it mutates `entry.loading` directly, last call wins ([dsl-helpers.ts `loading`](../../src/route-definition/dsl-helpers.ts)).
+
+For pages, layouts, and intercepts that's straightforward: explicit `loading()` at the mount site replaces any `loading()` from `handler.use`. The merge order is `handler.use → explicit`, so the explicit one is the last writer and wins.
+
+For parallel slots, the shared `parallel(..., () => [...])` callback is **broadcast** to every slot in the call. A single `loading()` placed there lands on every slot, overwriting each slot's `handler.use` default. To scope `loading()` to one slot, use the **slot descriptor** form:
+
+```typescript
+const Cart: Handler = async (ctx) => { /* … */ };
+Cart.use = () => [loader(CartLoader), loading(<CartSkeleton />)];
+
+const Notifs: Handler = async (ctx) => { /* … */ };
+Notifs.use = () => [loader(NotifsLoader), loading(<NotifsSkeleton />)];
+
+// ✅ @cart gets a custom skeleton; @notifs keeps its handler.use default.
+parallel({
+  "@cart": {
+    handler: Cart,
+    use: () => [loading(<CustomCartSkeleton />)],
+  },
+  "@notifs": Notifs,
+});
+
+// ✅ Opt one slot out of streaming while siblings still stream the broadcast.
+parallel(
+  {
+    "@cart": { handler: Cart, use: () => [loading(false)] },
+    "@notifs": Notifs,
+  },
+  () => [loading(<BroadcastSkeleton />)],
+);
+```
+
+Per-slot merge order is **handler.use → shared use → slot-local use**. Slot-local is the narrowest scope, so it wins for last-write-wins items like `loading()`. Items that accumulate within the parallel allow-list (`loader`, `revalidate`, `errorBoundary`, `notFoundBoundary`, `transition`) compose across all three layers regardless.
+
+Other things to keep in mind about `loading()`:
+
+- Any `loading()` (regardless of source) makes the segment a streaming unit. A handler that includes `loading()` in its `.use` opts every mount site into streaming by default. To opt back out, pass `loading(false)` at the mount site (`loading: false` handling in [match-middleware/segment-resolution.ts](../../src/router/match-middleware/segment-resolution.ts)) — use the slot descriptor form for parallel slots so the opt-out doesn't broadcast.
+
+Rule of thumb: only put `loading()` in `handler.use` if you genuinely want every mount site to stream by default. Use the slot descriptor's `use` for any per-slot intent at a `parallel()` call.
+
+## Edge cases & gotchas
+
+- **ReactNode handlers cannot have `.use`.** A bare JSX element passed as a handler (e.g., `path("/about", <About />)`) has no function to attach properties to. Pass a function or branded definition instead.
+- **Branded handlers** — `Static()`, `Prerender()`, and `Passthrough()` are positional constructors (not object-arg). Construct first, then attach `.use` to the returned definition:
+
+  ```typescript
+  const ProductPage = Prerender(async (ctx) => {
+    const product = await fetchProduct(ctx.params.slug);
+    return <ProductView product={product} />;
+  });
+  ProductPage.use = () => [loader(ProductLoader)];
+  ```
+
+- **Items can be flat or nested arrays.** `handler.use()` results are flattened with `.flat(3)` before validation, so factory helpers that return arrays inline work the same as in regular `use()` callbacks.
+- **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.
+
+## Cross-references
+
+- `skills/route` — `path()` mount site basics
+- `skills/layout` — `layout()` mount site basics
+- `skills/parallel` — parallel slot semantics, slot override rules, streaming behavior
+- `skills/intercept` — intercept mount site basics
+- `skills/loader` — defining `createLoader` and reading via `ctx.use()`
+- `skills/middleware` — middleware semantics and ordering

package/skills/hooks/SKILL.md

@@ -190,6 +190,141 @@ function SearchResults() {
 }
 ```
 
+**Shared refetch behavior**:
+
+When the loader is registered on the route via `loader()`, a plain
+`load()` call (no options, or a trivially-defaulted GET with no
+`params` and no `body`) broadcasts its result to every component
+reading the same loader id. Layout, page, and parallel-slot reads
+all converge on the new value:
+
+```tsx
+// Layout button calls load() — the page read below sees the update too.
+function Layout() {
+  const { data, load } = useLoader(CartLoader);
+  return <button onClick={() => load()}>Refresh ({data.count})</button>;
+}
+function Page() {
+  const { data } = useLoader(CartLoader); // updates with the layout's load()
+  return <span>{data.count} items</span>;
+}
+```
+
+`isLoading` and `error` follow the same scope. `throwOnError: true`
+render-throws are scoped to the **originating** hook — sibling readers
+see the error in their `error` state but their boundaries are not
+triggered by someone else's failure. A successful follow-up `load()`
+clears the shared error.
+
+**`load()` calls that stay local** (no broadcast, per-hook state, same
+semantics as the old per-component `useState`):
+
+- `load({ params: { ... } })` — explicit params.
+- `load({ method: "POST", body })` — mutations.
+- Any `load()` on a `useFetchLoader(loader)` whose loader is **not**
+  registered on the current route. Two unrelated components calling
+  `load()` on the same fetchable-but-unregistered loader keep
+  independent results.
+
+So the search/list pattern still works — two components calling
+`load({ params: { q } })` with different `q` values each keep their
+own result; they do not collapse to last-write-wins through a shared
+store.
+
+**Scoping refetch with a `key`**:
+
+Pass a `key` to partition the shared refresh store. Only hooks using the
+**same** `key` refresh together when one of them calls `load()`. This is a
+client-side refresh identity only — it never changes the request sent to the
+server, and is unrelated to the server `cache({ key })` option and to
+`revalidate()`.
+
+```tsx
+// Two independent dashboards using the same loader. Without a key, one
+// dashboard's load() would flip the other's spinner and value. With a key,
+// they refresh independently.
+function Dashboard({ id }: { id: string }) {
+  const { data, load } = useLoader(StatsLoader, { key: `dashboard:${id}` });
+  return <button onClick={() => load()}>Refresh {data.total}</button>;
+}
+```
+
+The `key` widens sharing in two ways the default cannot:
+
+- **Parameterized GETs share.** `useFetchLoader(SearchLoader, { key: q })`
+  with the same `q` in two components share one result and refresh together —
+  a keyed `load({ params: { q } })` broadcasts to the group instead of staying
+  local. (Mutations — non-GET or `body` — stay local even with a key.)
+- **Unregistered loaders share.** A `key` makes `useFetchLoader` of a loader
+  that is **not** registered on the route share too, letting unrelated
+  components opt into a common refresh group.
+
+Lifecycle: a keyed read of an unregistered loader is reference-counted — its
+shared value lives as long as at least one component using that key is mounted.
+A persistent component (e.g. a header) keeps the value across navigations; a
+route-scoped component's value is reclaimed when it unmounts. Registered-loader
+reads (keyed or not) reset on navigation from fresh route data, as before.
+
+**Refreshing multiple loaders together (`refreshGroup` + `useRefreshLoaders`)**:
+
+`key` groups readers of one loader. To refresh **different** loaders together,
+tag them with a shared `refreshGroup` name and trigger them with
+`useRefreshLoaders()`. The hook takes no argument; you pass the group(s) to the
+function it returns, so one `useRefreshLoaders()` can refresh different groups
+depending on context. A read may carry **several** tags — pass an array — and is
+refreshed when **any** of its groups is refreshed:
+
+```tsx
+function Profile() {
+  const { data } = useLoader(ProfileLoader, {
+    key: userId,
+    refreshGroup: "account",
+  });
+  return <span>{data.name}</span>;
+}
+function Orders() {
+  // Tagged into two groups: refreshed by "account" (the whole set) or the
+  // finer "orders" tag.
+  const { data } = useLoader(OrdersLoader, {
+    key: userId,
+    refreshGroup: ["account", "orders"],
+  });
+  return <span>{data.count} orders</span>;
+}
+function RefreshButtons() {
+  const refresh = useRefreshLoaders();
+  return (
+    <>
+      <button onClick={() => refresh("account")}>Refresh account</button>
+      <button onClick={() => refresh("orders")}>Refresh orders only</button>
+      <button onClick={() => refresh(["account", "orders"])}>
+        Refresh both
+      </button>
+    </>
+  );
+}
+```
+
+`refresh(groups)` accepts one name or an array and re-runs every currently-mounted
+member tagged with **any** of them, with a **plain GET** against the current route
+URL — no params, no body, no mutation methods, because a group spans loaders with
+different shapes. A member that sits in two of the requested groups is fetched
+once (members are unioned and deduped by read). It returns a promise that resolves
+when all members settle and **rejects with an `AggregateError`** if any fail;
+group refresh never render-throws, so handle failures at the await site
+(`await refresh("account").catch(...)`). Each failing member also exposes its
+error via its own read's `error`.
+
+Multiple tags give you granular vs. whole-set refresh from one place: a coarse
+tag (`"account"`) covers everything, while a finer tag (`"orders"`) targets a
+subset. Sharing within a group is opt-in via `key`: members that share a `key`
+share one value (and one fetch); a grouped reader **without** a `key` gets its own
+private bucket, so a group refresh updates only that read and never leaks into
+unrelated unkeyed reads of the same loader. A bucket may belong to several groups
+at once (one read tagged with multiple names, or different reads tagging the same
+keyed bucket with different names). Keep parameterized loaders on the single-loader
+`key` — a plain-GET group refresh sends no params.
+
 **Load options**:
 
 ```tsx
@@ -298,9 +433,11 @@ path("/dashboard", (ctx) => {
   push({ label: "Dashboard", href: "/dashboard" });
   return <DashboardNav handle={Breadcrumbs} />;
 });
+```
 
+```tsx
 // Client component — typeof infers the full Handle<T> type
-("use client");
+"use client";
 import { useHandle, type Breadcrumbs } from "@rangojs/router/client";
 
 function DashboardNav({ handle }: { handle: typeof Breadcrumbs }) {
@@ -321,6 +458,11 @@ RSC serialization strips the `collect` function via `toJSON()`. On the client,
 
 ## Action Hooks
 
+For the full server-action guide (defining actions, `useActionState`,
+`useOptimistic`, validation, revalidation, error handling, file uploads),
+see `/server-actions`. `useAction()` below is a Rango-specific hook for
+tracking actions called outside a `<form action={...}>` flow.
+
 ### useAction()
 
 Track state of server action invocations:
@@ -504,6 +646,43 @@ const flash = FlashMessage.read();
 const product = ProductState.read();
 ```
 
+> **Hydration:** `.read()` returns `undefined` on the server but may return
+> a real value on the first client render (history state survives reload).
+> Do not call `.read()` directly during the initial render of a component;
+> call it from an event handler or inside a `useEffect` post-mount. For
+> reactive hydration-safe access, use `useLocationState()` instead.
+
+### .write() / .delete() (static, non-reactive)
+
+Static counterparts to `.read()`. Both mutate the current history entry's
+`history.state` via `replaceState`, preserving any other keys (router
+bookkeeping, other location state slots). Both are client-only; they throw
+when called on the server.
+
+Neither dispatches an event, so components reading via `useLocationState`
+will NOT re-render until the next navigation/popstate. Pair with `.read()`
+(or a fresh mount via back/forward/reload) instead.
+
+```tsx
+"use client";
+import { ProductState } from "./state";
+
+// Persisted across hard refresh and back/forward of this entry.
+ProductState.write({ name: "Widget", price: 9.99 });
+
+// Read later (or on next mount).
+const current = ProductState.read();
+
+// Manually clear the slot. Idempotent if it isn't set.
+ProductState.delete();
+```
+
+| Method      | Updates `history.state` | Fires `useLocationState` rerender | SSR behavior        |
+| ----------- | ----------------------- | --------------------------------- | ------------------- |
+| `.read()`   | no                      | n/a (returns snapshot)            | returns `undefined` |
+| `.write()`  | yes (replace this slot) | no                                | throws              |
+| `.delete()` | yes (remove this slot)  | no                                | throws              |
+
 ## Cache Hooks
 
 ### useClientCache()
@@ -593,6 +772,12 @@ function ProductPage() {
   return <h1>Product {params.productId}</h1>;
 }
 
+// Annotate the expected shape via a generic
+function ProductPageTyped() {
+  const { productId } = useParams<{ productId: string }>();
+  return <h1>Product {productId}</h1>;
+}
+
 // With selector for performance (re-renders only when selected value changes)
 function ProductId() {
   const productId = useParams((p) => p.productId);
@@ -600,7 +785,7 @@ function ProductId() {
 }
 ```
 
-Returns merged params from all matched route segments. Updates on navigation commit (not during pending navigation).
+Returns merged params from all matched route segments as a `Readonly<T>` map. Updates on navigation commit (not during pending navigation).
 
 ### usePathname()
 
@@ -681,24 +866,48 @@ function MountInfo() {
 }
 ```
 
-See `/links` for full URL generation guide including server-side `ctx.reverse`.
+### useReverse(routes)
+
+Mount-aware local reverse for client components. Import the generated `routes` map from a `urls()` module's `.gen.ts` and call `reverse("name", params?)` — the leading dot is optional. Auto-fills params from `useParams()`; explicit params override.
+
+> Per-module `*.gen.ts` files are **CLI opt-in and not Vite-watched** — run `rango generate <urls-file>` (or wire it into `predev`) and re-run it whenever the module's routes change. See `/links` for the full generated-file setup and exposure-boundary rules.
+
+```tsx
+"use client";
+import { Link, useReverse } from "@rangojs/router/client";
+import { routes as blogRoutes } from "../urls/blog.gen.js";
+
+function BlogNav() {
+  const reverse = useReverse(blogRoutes);
+  return (
+    <nav>
+      <Link to={reverse("index")}>Blog</Link>
+      <Link to={reverse("post", { postId: "hello" })}>Post</Link>
+    </nav>
+  );
+}
+```
+
+See `/links` for the full URL generation guide. `ctx.reverse()` is server-only; on the client, prefer `useReverse(routes)` for in-module names and pass URLs as props for cross-module ones.
 
 ## Hook Summary
 
-| Hook                 | Purpose                           | Returns                                         |
-| -------------------- | --------------------------------- | ----------------------------------------------- |
-| `useParams()`        | Route params                      | `Record<string, string>` or selected value      |
-| `usePathname()`      | Current pathname                  | `string`                                        |
-| `useSearchParams()`  | URL search params                 | `ReadonlyURLSearchParams`                       |
-| `useHref()`          | Mount-aware href                  | `(path) => string`                              |
-| `useMount()`         | Current include() mount path      | `string`                                        |
-| `useNavigation()`    | Reactive navigation state         | state, location, isStreaming                    |
-| `useRouter()`        | Stable router actions             | push, replace, refresh, prefetch, back, forward |
-| `useSegments()`      | URL path & segment IDs            | path, segmentIds, location                      |
-| `useLinkStatus()`    | Link pending state                | { pending }                                     |
-| `useLoader()`        | Loader data (strict)              | data, isLoading, error                          |
-| `useFetchLoader()`   | Loader with on-demand fetch       | data, load, isLoading                           |
-| `useHandle()`        | Accumulated handle data           | T (handle type)                                 |
-| `useAction()`        | Server action state               | state, error, result                            |
-| `useLocationState()` | History state (persists or flash) | T \| undefined                                  |
-| `useClientCache()`   | Cache control                     | { clear }                                       |
+| Hook                  | Purpose                           | Returns                                                            |
+| --------------------- | --------------------------------- | ------------------------------------------------------------------ |
+| `useParams()`         | Route params                      | `Readonly<T>` (default `Record<string, string>`) or selected value |
+| `usePathname()`       | Current pathname                  | `string`                                                           |
+| `useSearchParams()`   | URL search params                 | `ReadonlyURLSearchParams`                                          |
+| `useHref()`           | Mount-aware href                  | `(path) => string`                                                 |
+| `useMount()`          | Current include() mount path      | `string`                                                           |
+| `useReverse()`        | Local reverse for imported routes | `(name, params?, search?) => string`                               |
+| `useNavigation()`     | Reactive navigation state         | state, location, isStreaming                                       |
+| `useRouter()`         | Stable router actions             | push, replace, refresh, prefetch, back, forward                    |
+| `useSegments()`       | URL path & segment IDs            | path, segmentIds, location                                         |
+| `useLinkStatus()`     | Link pending state                | { pending }                                                        |
+| `useLoader()`         | Loader data (strict)              | data, isLoading, error                                             |
+| `useFetchLoader()`    | Loader with on-demand fetch       | data, load, isLoading                                              |
+| `useRefreshLoaders()` | Refresh cross-loader group(s)     | `() => (groups: string \| string[]) => Promise<void>`              |
+| `useHandle()`         | Accumulated handle data           | T (handle type)                                                    |
+| `useAction()`         | Server action state               | state, error, result                                               |
+| `useLocationState()`  | History state (persists or flash) | T \| undefined                                                     |
+| `useClientCache()`    | Cache control                     | { clear }                                                          |