@rangojs/router 0.0.0-experimental.15 → 0.0.0-experimental.151

package/skills/layout/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: layout
-description: Define layout routes that wrap child routes in @rangojs/router
+description: Define layout routes that wrap child routes in @rangojs/router. Use when sharing a persistent UI shell (nav, sidebar) across nested routes, or asking how to wrap child pages with a common layout.
 argument-hint: [component]
 ---
 
@@ -45,9 +45,7 @@ layout(<ShopLayout />, () => [
 ### Component Function
 
 ```typescript
-layout(ShopLayout, () => [
-  path("/shop", ShopIndex, { name: "shop" }),
-])
+layout(ShopLayout, () => [path("/shop", ShopIndex, { name: "shop" })]);
 ```
 
 ### Handler with Context
@@ -117,6 +115,8 @@ function ShopLayout() {
 }
 ```
 
+A layout's `transition()` config wraps the content that flows through `<Outlet />` — not the layout chrome itself, and not sibling `<ParallelOutlet />` slots. Stacking transitions across nested layouts collapses around the deepest default outlet content. See [skills/view-transitions](../view-transitions/SKILL.md) for the full wrap rules and intercept-modal interaction.
+
 ## Named Outlets
 
 For parallel routes, use named outlets:
@@ -141,9 +141,69 @@ function DashboardLayout() {
 }
 ```
 
+## Orphan Layout (inside route)
+
+A layout as a child of `path()` wraps the route content and can read
+data set by the route handler via `ctx.get()`. The handler always
+executes before its children.
+
+This is the recommended way to pass handler data downward, and it is
+safe under partial action revalidation with zero configuration: orphan
+layouts (and their parallels) belong to the route entry, and on an
+action the whole entry re-runs together by default — route segment,
+loaders, and `belongsToRoute` children all seed revalidate-true, with
+handler-first ordering preserved. Producer and consumer cannot desync
+unless you narrow one side with a predicate that returns a hard `false`
+(then put the same contract on both — see "Revalidation Contracts").
+
+Data from an **outer** handler or layout entry is the opposite case:
+outer entries do not revalidate on actions by default (parent-chain
+skip). If an orphan layout depends on data established above its own
+route entry, that outer segment must share a revalidation contract, or
+the orphan must guard/reload the data independently. See `/rango` →
+"Passing data down the tree" for the full safest-first ladder.
+
+```typescript
+import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+
+urls(({ path, layout, parallel }) => [
+  path("/product/:slug", (ctx) => {
+    const product = await fetchProduct(ctx.params.slug);
+    ctx.set("product", product);
+    return <ProductPage product={product} />;
+  }, { name: "product" }, () => [
+    layout((ctx) => {
+      const product = ctx.get("product");
+      return (
+        <div>
+          <Breadcrumb name={product?.name} />
+          <Outlet />
+          <ParallelOutlet name="@related" />
+        </div>
+      );
+    }, () => [
+      parallel({
+        "@related": (ctx) => {
+          const product = ctx.get("product");
+          return <RelatedProducts category={product?.category} />;
+        },
+      }),
+    ]),
+  ]),
+])
+```
+
+Orphan layouts can call `ctx.get()` to read data set by their parent
+handler. They can also call `ctx.set()`, though the primary pattern is
+for route handlers and middleware to write context variables and for
+orphan layouts to read them.
+
 ## Layout Revalidation
 
-Layouts don't revalidate by default. Control with `revalidate()`:
+Standalone `layout()` entries don't revalidate by default — on an action,
+parent-chain segments are skipped unless a `revalidate()` opts them in.
+(Orphan layouts inside a `path()` are the opposite: they ride along with
+the route entry by default.) Control with `revalidate()`:
 
 ```typescript
 layout(<ShopLayout />, () => [
@@ -154,18 +214,76 @@ layout(<ShopLayout />, () => [
 ])
 
 // Or revalidate based on conditions
+import * as CartActions from "./actions/cart";
+
 layout(<CartLayout />, () => [
-  revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+  revalidate((ctx) => ctx.isAction(CartActions) || undefined),
 
   path("/cart", CartPage, { name: "cart" }),
 ])
 ```
 
+If child segments read data that was established by this layout or by a
+route handler above them, revalidate the outer segment too. Partial
+revalidation does not re-run non-revalidated ancestors just to rebuild
+their `ctx.set()` state.
+
+### Revalidation Contracts
+
+Contracts are the tool for cross-entry sharing — the bottom rung of the
+data-passing ladder (`/rango` → "Passing data down the tree"). Before
+writing one, check whether the producer can move down a rung: into the
+consumer's own entry as an orphan layout, into middleware, or into a
+loader. When the data genuinely must flow from an outer entry, define
+named revalidation functions and reuse them on both producer and
+consumer segments:
+
+```typescript
+// revalidation-contracts.ts
+import { addToCart } from "./actions/cart";
+
+export const revalidateCartData = (ctx) => ctx.isAction(addToCart) || undefined;
+```
+
+```typescript
+layout(<CartLayout />, () => [
+  revalidate(revalidateCartData), // producer
+  path("/cart", CartPage, { name: "cart" }, () => [
+    revalidate(revalidateCartData), // consumer
+  ]),
+]);
+```
+
+If a segment depends on multiple upstream domains, compose multiple
+contracts (`revalidateAuthData`, `revalidateCartData`, and so on).
+
+You can also package them as importable handoff helpers:
+
+```typescript
+// revalidation-contracts.ts
+import { revalidate } from "@rangojs/router";
+import * as AuthActions from "./actions/auth";
+
+export const revalidateAuthData = (ctx) =>
+  ctx.isAction(AuthActions) || undefined;
+export const revalidateAuth = () => [revalidate(revalidateAuthData)];
+```
+
+```typescript
+layout(<ShellLayout />, () => [
+  revalidateAuth(),
+  path("/account", AccountPage, { name: "account" }, () => [
+    revalidateAuth(),
+  ]),
+]);
+```
+
 ## Complete Example
 
 ```typescript
 import { urls } from "@rangojs/router";
 import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+import * as CartActions from "./actions/cart";
 
 function ShopLayout() {
   return (
@@ -195,7 +313,7 @@ export const shopPatterns = urls(({ path, layout, parallel, loader, revalidate }
   }, () => [
     // Layout loaders
     loader(CartLoader, () => [
-      revalidate(({ actionId }) => actionId?.includes("Cart") ?? false),
+      revalidate((ctx) => ctx.isAction(CartActions) || undefined),
     ]),
 
     // Parallel routes
@@ -211,3 +329,25 @@ export const shopPatterns = urls(({ path, layout, parallel, loader, revalidate }
   ]),
 ]);
 ```
+
+## Handler-attached `.use`
+
+Layout handlers can carry their own middleware, default parallels, and includes via `.use` so a layout becomes a self-contained unit reusable across mount sites.
+
+```typescript
+const AdminLayout: Handler = (ctx) => {
+  const user = ctx.get(CurrentUser);
+  return <Admin user={user} />;
+};
+AdminLayout.use = () => [
+  middleware(requireAdmin),
+  parallel({ "@adminNotifs": AdminNotifsSlot }),
+];
+
+// Mount site declares structure only; defaults travel with the layout.
+layout(AdminLayout, () => [
+  path("/admin", AdminIndex, { name: "admin.index" }),
+]);
+```
+
+Allowed item types in a layout's `.use` mirror the layout `use()` callback (the broadest set). Explicit `use()` at the mount site merges with `handler.use` (handler defaults first, explicit second). See [skills/handler-use](../handler-use/SKILL.md) for merge order and per-mount-site allowed types.

package/skills/links/SKILL.md

@@ -1,16 +1,25 @@
 ---
 name: links
-description: URL generation with ctx.reverse (server), href (client), useHref (mounted), useMount, and scopedReverse
-argument-hint: [href|useHref|useMount|scopedReverse]
+description: URL generation with ctx.reverse (server default), href (client), useHref (mounted), useMount, useReverse, and scopedReverse. Use when generating a link to a route by name instead of hardcoding a path, or a link breaks after routes move or get mounted elsewhere.
+argument-hint: [ctx.reverse|href|useHref|useMount|useReverse|scopedReverse]
 ---
 
 # Links & URL Generation
 
 @rangojs/router provides different href APIs for server and client contexts.
 
+**Default server API: `ctx.reverse()`.** Generate URLs from the handler context — it's typed, auto-fills mount params, and resolves local (`.name`) and absolute (`name.sub`) names.
+
+**On the client, two patterns:**
+
+1. **Receive URLs as props / loader data / action return.** The default. The server has the full route manifest and handler context — generate URLs there and hand strings to client components.
+2. **`useReverse(routes)`.** Import a generated `routes` map from a `urls()` module's `.gen.ts` and call `reverse("name", params?)` (the leading dot is optional). Mount-aware via `useMount()`, auto-fills params from `useParams()`, fully typed from the imported map. Use this when a client component needs to generate URLs into a known module without round-tripping through the server.
+
+`ctx.reverse()` itself is **server-only** — it depends on the full route manifest and handler context. Client components never import or call it.
+
 ## Server: ctx.reverse()
 
-Available in route handlers via HandlerContext. Resolves named routes using the full route map.
+Available in route handlers via HandlerContext. Resolves named routes using the full route map. This is the default way to generate URLs on the server.
 
 ```typescript
 import { urls, scopedReverse } from "@rangojs/router";
@@ -24,24 +33,71 @@ export const shopPatterns = urls(({ path, layout }) => [
 ]);
 ```
 
-### Resolution priority
+### Resolution rules
 
-1. **Path-based** (`/...`) - returned as-is
-2. **Absolute name** (contains dot: `blog.post`) - global lookup
-3. **Local name** (`cart`) - resolved relative to current route's namespace
+- **`.name`** — local route, resolved within the current `include()` scope
+- **`name`** — global route, from the named-routes definition
 
 ```typescript
 // Inside a handler within shopPatterns (mounted at /shop)
 path("/product/:slug", (ctx) => {
-  ctx.reverse("cart");                        // "/shop/cart" (local)
-  ctx.reverse("product", { slug: "widget" }); // "/shop/product/widget" (local + params)
-  ctx.reverse("blog.post", { slug: "hi" });   // "/blog/hi" (absolute)
-  ctx.reverse("/about");                      // "/about" (path-based)
+  ctx.reverse(".cart");                        // "/shop/cart" (local)
+  ctx.reverse(".product", { slug: "widget" }); // "/shop/product/widget" (local + params)
+  ctx.reverse("blog.post", { slug: "hi" });    // "/blog/hi" (global)
 
   return <ProductPage slug={ctx.params.slug} />;
 }, { name: "product" })
 ```
 
+### Local names (dot-prefixed)
+
+Prefix a name with `.` to resolve it within the current `include()` scope. The route is looked up using the include's mount namespace.
+
+```typescript
+// urls/magazine.tsx — mounted at include("/magazine", magazinePatterns, { name: "magazine" })
+(ctx) => {
+  ctx.reverse(".article", { slug: "design" }); // "/magazine/design"
+  ctx.reverse(".author.posts", { authorSlug: "alice" }); // "/magazine/author/alice/posts"
+  ctx.reverse(".index"); // "/magazine"
+  ctx.reverse(".blog.index"); // THROWS — no magazine.blog.index
+};
+```
+
+### Auto-fill of mount params
+
+When routes are mounted via a parameterized `include()`, `ctx.reverse()` automatically fills mount params from `ctx.params`. Inner handlers don't need to pass params that are already known from the current URL match. Explicitly passed params override auto-filled values.
+
+```typescript
+// urls/tenant.tsx — mounted at include("/tenant/:tenantId", tenantPatterns, { name: "tenant" })
+export const tenantPatterns = urls(({ path }) => [
+  path("/", (ctx) => {
+    // tenantId is auto-filled from ctx.params — no need to pass it
+    ctx.reverse(".settings");                              // "/tenant/acme/settings" (when visiting /tenant/acme)
+    ctx.reverse(".user", { userId: "u1" });                // "/tenant/acme/users/u1" (tenantId auto-filled, userId explicit)
+    ctx.reverse(".settings", { tenantId: "other" });       // "/tenant/other/settings" (explicit override)
+
+    // Global names also get auto-filled params
+    ctx.reverse("tenant.settings");                        // "/tenant/acme/settings"
+    return <TenantIndex />;
+  }, { name: "index" }),
+  path("/settings", SettingsPage, { name: "settings" }),
+  path("/users/:userId", UserPage, { name: "user" }),
+]);
+```
+
+Auto-fill uses `{ ...ctx.params, ...hrefParams }` — current request params are defaults, explicit params win. Params not needed by the target route are silently ignored.
+
+### Global names (unprefixed)
+
+Unprefixed names resolve against the full named-routes map (the generated `router.named-routes.gen.ts`).
+
+```typescript
+(ctx) => {
+  ctx.reverse("magazine.index"); // "/magazine"
+  ctx.reverse("blog.post", { slug: "hello" }); // "/blog/hello"
+};
+```
+
 ### reverse with search params
 
 When a route has a `search` schema, pass a typed search object as the third argument:
@@ -56,7 +112,7 @@ path("/search", (ctx) => {
 
 ### scopedReverse() - type-safe ctx.reverse
 
-Wraps `ctx.reverse` with local route type information for autocomplete and validation:
+Wraps `ctx.reverse` with local route type information for autocomplete and validation. Runtime behavior is identical to `ctx.reverse` — `scopedReverse` is a type-only cast. The same dot-prefix rule applies: local names use `.name`, global names use `name.sub`.
 
 ```typescript
 import { scopedReverse } from "@rangojs/router";
@@ -64,18 +120,83 @@ import { scopedReverse } from "@rangojs/router";
 path("/product/:slug", (ctx) => {
   const reverse = scopedReverse<typeof shopPatterns>(ctx.reverse);
 
-  reverse("cart");                        // Type-safe local name
-  reverse("product", { slug: "widget" }); // Type-safe with params
-  reverse("blog.post");                   // Absolute names (dot notation) always allowed
-  reverse("/about");                      // Path-based always allowed
+  reverse(".cart");                        // Local name (dot-prefixed) — resolves in include scope
+  reverse(".product", { slug: "widget" }); // Local name with params
+  reverse("blog.post", { slug: "hi" });    // Global name (dotted) — full route map
 
   return <ProductPage slug={ctx.params.slug} />;
 }, { name: "product" })
 ```
 
+`reverse()` does not accept raw path strings (`"/about"`). For static paths in client components, use `href("/about")`; on the server, look up the route by name.
+
+## Client components: receive URLs as props
+
+`ctx.reverse()` is not available inside `"use client"` modules — there is no handler context in the browser bundle. For in-module names, prefer `useReverse(routes)` (see below) and import the relevant `urls/*.gen.js`. For cross-module URLs or one-off names, generate the URL on the server and hand it to the client component using one of these three patterns:
+
+1. Pass as a prop from a server component:
+
+```tsx
+// server
+function BlogPostPage(ctx: HandlerContext) {
+  return <ShareButton url={ctx.reverse(".post", { slug: ctx.params.slug })} />;
+}
+```
+
+```tsx
+"use client";
+
+export function ShareButton({ url }: { url: string }) {
+  return (
+    <button onClick={() => navigator.clipboard.writeText(url)}>Share</button>
+  );
+}
+```
+
+2. Return from a loader (attached to the route via the DSL):
+
+```tsx
+// server — loaders/nav.ts
+export const NavLoader = createLoader((ctx) => ({
+  home: ctx.reverse("home"),
+  blog: ctx.reverse("blog.index"),
+}));
+
+// server — urls.tsx: attach the loader so useLoader has data in context
+const urlpatterns = urls(({ path, loader }) => [
+  path("/", HomePage, { name: "home" }, () => [loader(NavLoader)]),
+]);
+```
+
+```tsx
+"use client";
+
+function Nav() {
+  const { data } = useLoader(NavLoader);
+  return <Link to={data.home}>Home</Link>;
+}
+```
+
+`useLoader()` requires the loader to be attached to an active route. If you need on-demand fetching instead, use `useFetchLoader()`.
+
+3. Return from a server action:
+
+```tsx
+"use server";
+
+export async function getProductUrl(slug: string) {
+  const ctx = getRequestContext();
+  return ctx.reverse("product", { slug });
+}
+```
+
+See `/server-actions` for the full action surface (`getRequestContext()` is the same context middleware and handlers use).
+
+For static path strings (not named routes), client components can use `href()` — see below.
+
 ## Client: href()
 
-Plain function for absolute path-based URLs. No hook needed - works anywhere.
+Plain function for absolute path-based URLs. No hook needed - works anywhere in client components. `href()` validates paths at compile time, but does **not** resolve named routes — for named routes, use one of the patterns above.
 
 ```typescript
 "use client";
@@ -92,7 +213,19 @@ function GlobalNav() {
 }
 ```
 
-`href()` is an identity function at runtime but provides compile-time validation via `ValidPaths` type. Paths are validated against registered route patterns using `PatternToPath`.
+`href()` provides compile-time validation via the `Rango.Path` type. Paths are validated against registered route patterns using `PatternToPath`.
+
+When wrapping `href()`, type the wrapper's path parameter as `Rango.Path` so it
+keeps the same generated-route validation. `Rango.Path` is ambient — no import,
+just like `Rango.Env` / `Rango.Vars`:
+
+```typescript
+import { href } from "@rangojs/router/client";
+
+export const appHref = (path: Rango.Path): string => href(path);
+```
+
+`href()` is a raw path helper — it is **not** basename-aware. It returns the path as-is (or with the include mount prefix via `useHref()`). For basename-aware navigation, use `Link`, `useRouter().push()`, or `reverse()`, which auto-prefix root-relative paths with the router's basename.
 
 ## Client: useHref()
 
@@ -136,15 +269,161 @@ function MountInfo() {
 
 `useMount()` reads from `MountContext`, which is automatically set by `include()` in the segment tree.
 
+## Client: useReverse(routes)
+
+Hook that returns a typed local reverse function for a `routes` map imported from a generated `.gen.ts` next to a `urls()` module. The route map is the **exposure boundary** — `useReverse` only knows about names in that map, never the full app manifest.
+
+> **Which map?** `useReverse` accepts any routes map. Prefer the per-module `routes` (e.g. `urls/blog.gen.ts`): it gives **mount-aware** local `.name` reverse (auto-prefixes the `include()` mount) and only that module's names enter the client bundle. You _can_ instead pass `router.named-routes.gen.ts` (`NamedRoutes`) for **global** names (`blog.post`; the leading dot is optional) — it is a plain importable map and works on the client (it is **not** server-only) — but its paths are **absolute** while `useReverse` mount-prefixes, so it is correct only at the root mount (under a non-root mount it double-prefixes), and importing it pulls every route name and pattern in the app into the client bundle (a small names-to-paths map — not components or loaders), versus the per-module map which exposes only one module's names. So the per-module map is preferred for in-module links; the named-routes map is the escape hatch for global names.
+
+```tsx
+"use client";
+import { Link, useReverse } from "@rangojs/router/client";
+import { routes as blogRoutes } from "../urls/blog.gen.js";
+
+export function BlogNav() {
+  const reverse = useReverse(blogRoutes);
+
+  return (
+    <nav>
+      <Link to={reverse("index")}>Blog</Link>
+      <Link to={reverse("post", { postId: "hello" })}>Post</Link>
+    </nav>
+  );
+}
+```
+
+### How it resolves
+
+1. Strips an optional leading `.` and looks up the name in the imported `routes` map.
+2. Joins the local pattern with the surrounding `useMount()` value — the include's URL pattern.
+3. Substitutes params: explicit params from the call, then auto-filled from `useParams()` for anything still unresolved (mount params like `:tenantId` flow in this way).
+4. Appends a query string if a search object is passed and the route has a `search` schema.
+
+### Mount-relativity
+
+Patterns in the generated `routes` map are **mount-relative** — they're the patterns as defined inside the `urls()` module, _not_ the full app paths. Mount-joining happens at runtime via `useMount()`, so the same component works under any include:
+
+```typescript
+// urls/blog.tsx
+export const blogPatterns = urls(({ path }) => [
+  path("/", BlogIndex, { name: "index" }),
+  path("/:postId", BlogPost, { name: "post" }),
+]);
+
+// Generated urls/blog.gen.ts
+// export const routes = { index: "/", post: "/:postId" } as const;
+
+// urls.tsx — same module mounted twice
+include("/news", blogPatterns, { name: "news" }),    // <BlogNav> renders /news, /news/hello
+include("/journal", blogPatterns, { name: "diary" }), // <BlogNav> renders /journal, /journal/hello
+```
+
+The `/` pattern under a non-root mount collapses cleanly: under `/news`, `reverse(".index")` returns `/news` (no trailing slash), matching `ctx.reverse(".index")` on the server.
+
+### Auto-filled params (mount params)
+
+When the include itself carries `:params`, those are auto-filled from `useParams()` so the caller doesn't have to thread them through:
+
+```typescript
+// urls.tsx
+include("/tenant/:tenantId", clientReversePatterns, { name: "tenant" });
+```
+
+```tsx
+// At /tenant/acme/posts/p1, useParams() = { tenantId: "acme", postId: "p1" }
+const reverse = useReverse(clientReverseRoutes);
+
+reverse(".index"); // "/tenant/acme"
+reverse(".post", { postId: "p2" }); // "/tenant/acme/posts/p2"   (tenantId auto-filled)
+reverse(".post", { tenantId: "other", postId: "p2" }); // "/tenant/other/posts/p2" (explicit override)
+```
+
+Auto-fill follows soft navigation — when the matched route changes, `useReverse` re-renders with the new params.
+
+### Search schemas
+
+Routes declared with a `search` schema accept a typed search object as the third argument:
+
+```typescript
+// urls/blog.tsx
+path("/search", SearchPage, {
+  name: "search",
+  search: { q: "string", page: "number?" },
+}),
+
+// Generated as: search: { path: "/search", search: { q: "string", page: "number?" } }
+```
+
+```tsx
+const reverse = useReverse(blogRoutes);
+reverse(".search", {}, { q: "hello world", page: 2 });
+// "/news/search?q=hello%20world&page=2"
+```
+
+### Errors
+
+- Unknown name: throws `Unknown route: ".not-a-route"`.
+- Missing required param: throws `Missing param "postId" for route ".detail"`.
+
+Both happen synchronously during `reverse()` — wrap calls in try/catch (or an ErrorBoundary if the throw happens during render) when you need to surface them as UI.
+
+### The leading dot is optional
+
+`reverse("post")` and `reverse(".post")` resolve **identically** — the leading dot is cosmetic. The map you import IS the scope, so there is no separate global namespace to disambiguate and the dot carries no meaning; it exists only as a readability convention and for parity with `ctx.reverse(".name")` on the server. To link into a different module, import that module's `routes`:
+
+```tsx
+import { routes as blogRoutes } from "../urls/blog.gen.js";
+import { routes as shopRoutes } from "../urls/shop.gen.js";
+
+function CrossNav() {
+  const blog = useReverse(blogRoutes);
+  const shop = useReverse(shopRoutes);
+  return (
+    <nav>
+      <Link to={blog("index")}>Blog</Link>
+      <Link to={shop("cart")}>Cart</Link>
+    </nav>
+  );
+}
+```
+
+### Codegen
+
+Each `urls()` module gets a sibling `.gen.ts` with the local route names and patterns, produced by `rango generate`:
+
+```bash
+pnpm exec rango generate src/urls/blog.tsx
+# or generate everything under a directory:
+pnpm exec rango generate src/urls --static
+```
+
+Don't edit the file by hand — re-run codegen when patterns change.
+
+**Today the Vite plugin only regenerates the router-level `*.named-routes.gen.ts`.** Per-module `urls/*.gen.ts` files are emitted only by the CLI (or `writePerModuleRouteTypesForFile` programmatically). Commit the generated files and re-run `rango generate` whenever a `urls()` module's `path()`/`include()` shape changes. A common workflow is to wire it into a `predev` script:
+
+```jsonc
+// package.json
+{
+  "scripts": {
+    "predev": "rango generate src",
+    "dev": "vite",
+  },
+}
+```
+
 ## When to use what
 
-| Context | API | Resolves | Use for |
-|---------|-----|----------|---------|
-| Server handler | `ctx.reverse("name")` | Named routes (local + absolute) | Server-side URL generation |
-| Server handler | `scopedReverse<T>(ctx.reverse)` | Same, with type safety | Type-safe server URLs |
-| Client component | `href("/path")` | Absolute paths | Global navigation |
-| Client component | `useHref()` | Mount-prefixed paths | Local navigation inside `include()` |
-| Client component | `useMount()` | Raw mount path | Custom mount-aware logic |
+| Context          | API                                                | Resolves                                  | Use for                                                          |
+| ---------------- | -------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------- |
+| Server handler   | `ctx.reverse("name")`                              | Named routes (local + absolute)           | **Default** server-side URL generation                           |
+| Server handler   | `scopedReverse<T>(ctx.reverse)`                    | Same, with type safety                    | Type-safe server URLs                                            |
+| Client component | `useReverse(routes)`                               | Local names from an imported `routes` map | Typed in-module URL generation without round-tripping the server |
+| Client component | (URL passed as prop / loader data / action return) | Named routes                              | Cross-module URLs or one-off names you don't want to import      |
+| Client component | `href("/path")`                                    | Absolute paths (static strings)           | Static navigation where no named-route lookup is needed          |
+| Client component | `useHref()`                                        | Mount-prefixed paths                      | Local navigation inside `include()`                              |
+| Client component | `useMount()`                                       | Raw mount path                            | Custom mount-aware logic                                         |
+
+> `ctx.reverse()` is server-only. On the client, either generate URLs on the server and pass them in, or import the `routes` map and use `useReverse(routes)` for in-module names.
 
 ## Complete example: mounted module