@rangojs/router 0.0.0-experimental.99 → 0.0.0-experimental.9b7a7784

package/README.md

@@ -602,7 +602,7 @@ export function Nav({ home, post }: { home: string; post: string }) {
 }
 ```
 
-For client-side navigation to static paths (no named-route lookup), use `href()` — see below. For URLs tied to named routes, always generate on the server and pass the string in.
+For client-side navigation to static paths (no named-route lookup), use `href()` — see below. For URLs tied to named routes, you have two options: import the per-module generated `routes` map and use `useReverse(routes)` for in-module names (see [`/links` skill](./skills/links/SKILL.md)), or generate the URL on the server and pass the string in for cross-module URLs.
 
 ### `href()` for Path Validation (Client Components)
 

package/dist/vite/index.js

@@ -2040,7 +2040,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.99",
+  version: "0.0.0-experimental.9b7a7784",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.99",
+  "version": "0.0.0-experimental.9b7a7784",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/hooks/SKILL.md

@@ -694,7 +694,27 @@ function MountInfo() {
 }
 ```
 
-See `/links` for full URL generation guide. The default server API is `ctx.reverse()`; in client components, receive URLs as props, loader data, or server-action return values — `reverse()` is not available in the browser.
+### 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?)`. Auto-fills params from `useParams()`; explicit params override.
+
+```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
 
@@ -705,6 +725,7 @@ See `/links` for full URL generation guide. The default server API is `ctx.rever
 | `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                                         |

package/skills/links/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: links
-description: URL generation with ctx.reverse (server default), href (client), useHref (mounted), useMount, and scopedReverse
-argument-hint: [ctx.reverse|href|useHref|useMount|scopedReverse]
+description: URL generation with ctx.reverse (server default), href (client), useHref (mounted), useMount, useReverse, and scopedReverse
+argument-hint: [ctx.reverse|href|useHref|useMount|useReverse|scopedReverse]
 ---
 
 # Links & URL Generation
@@ -10,7 +10,12 @@ argument-hint: [ctx.reverse|href|useHref|useMount|scopedReverse]
 
 **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.
 
-**`reverse()` is server-only.** It depends on the route manifest and handler context, neither of which are available in the browser. Client components receive URLs as props, loader data, or server-action return values — they never call `reverse` directly.
+**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?)`. 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()
 
@@ -127,9 +132,7 @@ path("/product/:slug", (ctx) => {
 
 ## Client components: receive URLs as props
 
-`reverse()` is not available inside `"use client"` modules — there is no handler context and no route manifest in the browser bundle. Generate the URL on the server and hand it to the client component.
-
-Three patterns, in order of preference:
+`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:
 
@@ -256,18 +259,159 @@ function MountInfo() {
 
 `useMount()` reads from `MountContext`, which is automatically set by `include()` in the segment tree.
 
-## When to use what
+## 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.
+
+```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 the 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 local 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.
+
+### Names are dot-only on the client
+
+`useReverse` accepts only `.name` (and dotted variants like `.nested.index`). There is no global namespace on the client — the import IS the scope. 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";
 
-| 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 | (URL passed as prop / loader data / action return) | Named routes                    | Any URL derived from a named route — generate on server, pass in |
-| 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                                         |
+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
 
-> `reverse()` is server-only. Client components never import or call it — they receive the already-resolved string.
+| 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
 

package/src/browser/navigation-bridge.ts

@@ -675,6 +675,53 @@ export function createNavigationBridge(
         this.handlePopstate();
       };
 
+      // React's experimental ViewTransition integration deliberately skips
+      // animations for commits originating from a popstate event handler —
+      // popstate must finish synchronously to preserve scroll/form
+      // restoration, which conflicts with running a transition. The
+      // Navigation API's `navigate` event runs in an async-safe context
+      // (`event.intercept({ handler })` lets us await), so commits made
+      // inside the intercept handler are NOT popstate-originated from
+      // React's perspective and the VT walker fires normally for
+      // back-/forward-navigations. Falls back to popstate on browsers
+      // without Navigation API support (Firefox today); on those browsers
+      // back-nav view transitions won't fire — matching the React
+      // limitation and current behavior.
+      // See https://react.dev/reference/react/ViewTransition.
+      const navigationApi: any = (window as any).navigation;
+      const supportsNavigationApi =
+        !!navigationApi && typeof navigationApi.addEventListener === "function";
+
+      const handleNavigateEvent = (event: any): void => {
+        // Only handle browser history traversal (back/forward).
+        // Push/replace are still driven by setupLinkInterception →
+        // this.navigate(...) (which calls history.pushState/replaceState).
+        if (event.navigationType !== "traverse") return;
+        if (!event.canIntercept) return;
+        // canIntercept doesn't exclude every cross-document case (e.g., back
+        // to a previous same-origin non-Rango document, or a doc-level
+        // history.go() target). Without this guard, event.intercept() would
+        // forcibly turn that into a same-document navigation and route it
+        // through handlePopstate — silently breaking the destination page.
+        if (!event.destination?.sameDocument) return;
+        if (event.hashChange || event.downloadRequest) return;
+        // Snapshot the destination's history.state BEFORE running our async
+        // handler. The Navigation API's intercept treats the intercepted
+        // navigation as a fresh same-document commit at flush time —
+        // which has the side effect of replacing the entry's state with
+        // null, clobbering the scroll-restoration `key` rango stamps onto
+        // each history entry. Restore the original state synchronously
+        // before the handler runs so that subsequent reads of
+        // window.history.state inside the handler (and inside React's
+        // useLayoutEffect that fires from the resulting commit) see the
+        // entry's pre-intercept state.
+        event.intercept({
+          handler: async () => {
+            await this.handlePopstate();
+          },
+        });
+      };
+
       // When the browser restores a page from bfcache (back-forward cache),
       // any in-flight navigation state is stale. This happens when:
       // 1. A navigation triggers X-RSC-Reload (e.g., response route hit via SPA)
@@ -700,13 +747,22 @@ export function createNavigationBridge(
         this.refresh();
       });
 
-      window.addEventListener("popstate", handlePopstate);
+      if (supportsNavigationApi) {
+        navigationApi.addEventListener("navigate", handleNavigateEvent);
+        debugLog("[Browser] Navigation bridge ready (Navigation API)");
+      } else {
+        window.addEventListener("popstate", handlePopstate);
+        debugLog("[Browser] Navigation bridge ready (popstate fallback)");
+      }
       window.addEventListener("pageshow", handlePageShow);
-      debugLog("[Browser] Navigation bridge ready");
 
       return () => {
         cleanupLinks();
-        window.removeEventListener("popstate", handlePopstate);
+        if (supportsNavigationApi) {
+          navigationApi.removeEventListener("navigate", handleNavigateEvent);
+        } else {
+          window.removeEventListener("popstate", handlePopstate);
+        }
         window.removeEventListener("pageshow", handlePageShow);
       };
     },

package/src/browser/react/index.ts

@@ -20,6 +20,9 @@ export { useSegments, type SegmentsState } from "./use-segments.js";
 // Handle data hook
 export { useHandle } from "./use-handle.js";
 
+// Mount-aware reverse hook
+export { useReverse } from "./use-reverse.js";
+
 // Client cache controls hook
 export {
   useClientCache,

package/src/browser/react/use-reverse.ts

@@ -0,0 +1,99 @@
+"use client";
+
+import { useCallback } from "react";
+import type { LocalReverseFunction } from "../../reverse.js";
+import { substitutePatternParams } from "../../router/substitute-pattern-params.js";
+import { serializeSearchParams } from "../../search-params.js";
+import { useMount } from "./use-mount.js";
+import { useParams } from "./use-params.js";
+
+type RouteEntry = string | { readonly path: string };
+type LocalRouteMap = Readonly<Record<string, RouteEntry>>;
+
+function getPattern(entry: RouteEntry | undefined): string | undefined {
+  if (entry === undefined) return undefined;
+  return typeof entry === "string" ? entry : entry.path;
+}
+
+/**
+ * Join an include mount prefix with a mount-relative pattern.
+ *
+ * `pattern === "/"` is the index of the local module — under a non-root
+ * mount it must collapse so `/` under `/blog` becomes `/blog`, not
+ * `/blog/`. This matches `ctx.reverse(".index")` on the server.
+ */
+function joinMount(mount: string, pattern: string): string {
+  if (pattern === "/") {
+    if (mount === "" || mount === "/") return "/";
+    return mount.endsWith("/") ? mount.slice(0, -1) : mount;
+  }
+  const normalizedMount = mount === "/" ? "" : mount.replace(/\/+$/, "");
+  return normalizedMount + pattern;
+}
+
+/**
+ * Mount-aware reverse function for a locally-imported `routes` map.
+ *
+ * Resolves dot-prefixed route names against the passed `routes` (typically
+ * a generated `routes` from a `urls()` module's `.gen.ts`), prefixes the
+ * result with the surrounding `include()` mount path, and substitutes
+ * params — auto-filling from the current matched route's params and
+ * letting explicit params override.
+ *
+ * @example
+ * ```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 (
+ *     <>
+ *       <Link to={reverse(".index")}>Blog</Link>
+ *       <Link to={reverse(".post", { postId: "hello" })}>Post</Link>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function useReverse<const TRoutes extends LocalRouteMap>(
+  routes: TRoutes,
+): LocalReverseFunction<TRoutes> {
+  const mount = useMount();
+  const currentParams = useParams();
+
+  return useCallback(
+    ((
+      name: string,
+      explicitParams?: Record<string, string | undefined>,
+      search?: Record<string, unknown>,
+    ): string => {
+      if (!name.startsWith(".")) {
+        throw new Error(`Local route names must start with ".": "${name}"`);
+      }
+      const lookupName = name.slice(1);
+      const entry = (routes as LocalRouteMap)[lookupName];
+      const pattern = getPattern(entry);
+      if (pattern === undefined) {
+        throw new Error(`Unknown local route: "${name}"`);
+      }
+
+      const joined = joinMount(mount, pattern);
+
+      const mergedParams = explicitParams
+        ? { ...currentParams, ...explicitParams }
+        : currentParams;
+
+      const substituted = substitutePatternParams(joined, mergedParams, name);
+
+      if (search) {
+        const qs = serializeSearchParams(search);
+        if (qs) return `${substituted}?${qs}`;
+      }
+
+      return substituted;
+    }) as LocalReverseFunction<TRoutes>,
+    [routes, mount, currentParams],
+  );
+}

package/src/browser/scroll-restoration.ts

@@ -10,15 +10,6 @@
 
 import { debugLog } from "./logging.js";
 
-/**
- * Defers a callback to the next animation frame.
- * Falls back to setTimeout(0) in environments without requestAnimationFrame.
- */
-const deferToNextPaint: (fn: () => void) => void =
-  typeof requestAnimationFrame === "function"
-    ? requestAnimationFrame
-    : (fn) => setTimeout(fn, 0);
-
 const SCROLL_STORAGE_KEY = "rsc-router-scroll-positions";
 
 /**
@@ -294,13 +285,19 @@ export function restoreScrollPosition(options?: {
     return true;
   }
 
-  // Not streaming — scroll after React commits and browser paints.
-  // startTransition defers the DOM commit, so scrolling synchronously
-  // would be overwritten when React replaces the content.
-  deferToNextPaint(() => {
+  // Not streaming — scroll synchronously. handleNavigationEnd is invoked
+  // from NavigationProvider's useLayoutEffect, which runs after React's
+  // commit and before paint, so sync scrollTo is captured by the upcoming
+  // paint or the View Transition snapshot. Deferring to rAF here pushed
+  // the scrollTo past startViewTransition's snapshot capture, which made
+  // forward navigations skip scroll-to-top whenever a layout/route VT was
+  // active (the rAF callback ran during the animation, but the captured
+  // snapshot was taken at the pre-scroll position, leaving the live DOM
+  // visually clamped at the previous scroll).
+  if (typeof window.scrollTo === "function") {
     window.scrollTo(0, savedY);
-    debugLog("[Scroll] Restored position:", savedY, "for key:", key);
-  });
+  }
+  debugLog("[Scroll] Restored position:", savedY, "for key:", key);
   return true;
 }
 
@@ -332,6 +329,8 @@ export function scrollToHash(): boolean {
  * Scroll to top of page
  */
 export function scrollToTop(): void {
+  if (typeof window === "undefined") return;
+  if (typeof window.scrollTo !== "function") return;
   window.scrollTo(0, 0);
 }
 
@@ -374,20 +373,15 @@ export function handleNavigationEnd(options: {
     // Fall through to hash or top if no saved position
   }
 
-  // Defer hash and scroll-to-top to after React paints the new content,
-  // so the user doesn't see the current page jump before the new route appears.
-  deferToNextPaint(() => {
-    // Re-check: the deferred callback may fire after environment teardown
-    if (typeof window === "undefined") return;
-
-    // Try hash scrolling first
-    if (scrollToHash()) {
-      return;
-    }
-
-    // Default: scroll to top
-    scrollToTop();
-  });
+  // Sync hash scroll / scroll-to-top — see the long comment in
+  // restoreScrollPosition above. handleNavigationEnd runs from
+  // NavigationProvider's useLayoutEffect (post-commit, pre-paint) and from
+  // bridge sites that don't trigger a React commit, so a synchronous
+  // scrollTo is captured by the next paint / startViewTransition snapshot.
+  if (scrollToHash()) {
+    return;
+  }
+  scrollToTop();
 }
 
 /**

package/src/client.rsc.tsx

@@ -78,6 +78,9 @@ export {
 // Re-export useHref - it's a "use client" hook
 export { useHref } from "./browser/react/use-href.js";
 
+// Re-export useReverse - it's a "use client" hook
+export { useReverse } from "./browser/react/use-reverse.js";
+
 // Re-export useHandle - it's a "use client" hook
 export { useHandle } from "./browser/react/use-handle.js";
 

package/src/client.tsx

@@ -448,8 +448,12 @@ export { MountContext } from "./browser/react/mount-context.js";
 // Mount-aware href hook - auto-prefixes paths with include() mount
 export { useHref } from "./browser/react/use-href.js";
 
+// Mount-aware reverse hook - resolves dot-prefixed names against an imported
+// generated routes map (from a urls() module's .gen.ts).
+export { useReverse } from "./browser/react/use-reverse.js";
+
 // Type-safe scoped reverse function for scopedReverse<typeof patterns>()
-export type { ScopedReverseFunction } from "./reverse.js";
+export type { ScopedReverseFunction, LocalReverseFunction } from "./reverse.js";
 
 // Loader definition type - for typing loader props in client components
 export type { LoaderDefinition } from "./types.js";

package/src/href-client.ts

@@ -186,7 +186,10 @@ export function href<T extends ValidPaths>(path: T, mount?: string): string {
     const normalizedMount = mount.endsWith("/") ? mount.slice(0, -1) : mount;
     return normalizedMount + path;
   }
-  return path;
+  // ValidPaths is built from template literals so T does extend string at
+  // runtime, but the inference can fail past a certain route-union complexity
+  // and TypeScript reports T as not assignable to string.
+  return path as string;
 }
 
 /**

package/src/reverse.ts

@@ -1,7 +1,7 @@
 import type { ExtractParams } from "./types.js";
 import type { SearchSchema, ResolveSearchSchema } from "./search-params.js";
 import { serializeSearchParams } from "./search-params.js";
-import { encodePathSegment } from "./router/url-params.js";
+import { substitutePatternParams } from "./router/substitute-pattern-params.js";
 
 /**
  * Sanitize prefix string by removing leading slash
@@ -219,6 +219,64 @@ export type ExtractLocalRoutes<TPatterns> = TPatterns extends {
     ? TPatterns
     : Record<string, string>;
 
+/**
+ * Params accepted by `useReverse(routes)`. The route's own params are
+ * required, and additional string keys are permitted so callers can
+ * override values that would otherwise be auto-filled from the matched
+ * route's `useParams()` (e.g. an enclosing `:tenantId` mount segment).
+ */
+export type LocalReverseParams<TPattern extends string> =
+  ExtractParams<TPattern> & {
+    readonly [extra: string]: string | undefined;
+  };
+
+/**
+ * Type-safe local reverse function with dot-prefixed names only.
+ *
+ * Returned by `useReverse(routes)` on the client. The route map is the
+ * exposure boundary (a generated `routes` from a `urls()` module) and the
+ * scope is implicit from that import — there is no global namespace, so
+ * names must be dot-prefixed to mirror `ctx.reverse(".name")`.
+ *
+ * @example
+ * ```typescript
+ * const reverse = useReverse(blogRoutes);
+ * reverse(".index");                         // ✓ no params
+ * reverse(".post", { postId: "hello" });     // ✓ with params
+ * reverse(".search", {}, { q: "hi" });       // ✓ with search schema
+ * reverse(".typo");                          // ✗ compile error
+ * ```
+ */
+export type LocalReverseFunction<TLocalRoutes> = {
+  /**
+   * Dot-prefixed local route without params
+   */
+  <TName extends keyof TLocalRoutes & string>(
+    name: IsEmptyObject<
+      ExtractParams<RoutePatternFor<TLocalRoutes, TName>>
+    > extends true
+      ? `.${TName}`
+      : never,
+  ): string;
+
+  /**
+   * Dot-prefixed local route with params
+   */
+  <TName extends keyof TLocalRoutes & string>(
+    name: `.${TName}`,
+    params: LocalReverseParams<RoutePatternFor<TLocalRoutes, TName>>,
+  ): string;
+
+  /**
+   * Dot-prefixed local route with params and search
+   */
+  <TName extends keyof TLocalRoutes & string>(
+    name: `.${TName}`,
+    params: LocalReverseParams<RoutePatternFor<TLocalRoutes, TName>>,
+    search: ResolveSearchSchema<ExtractSearchSchema<TLocalRoutes, TName>>,
+  ): string;
+};
+
 /**
  * Extract the response data type for a named route from a UrlPatterns instance.
  * Re-exported from urls.ts for consumer convenience.
@@ -302,46 +360,9 @@ export function createReverse<TRoutes extends Record<string, string>>(
       throw new Error(`Unknown route: ${name}`);
     }
 
-    let result = pattern;
-    if (params) {
-      // Replace :param placeholders with actual values
-      // Strip constraint syntax: :param(a|b) -> use "param" as key
-      // Optional params (:param?) are omitted when not provided
-      let hadOmittedOptional = false;
-      result = result.replace(
-        /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(\?)/g,
-        (_, key, _constraint, optional) => {
-          const value = params[key];
-          // The matcher omits absent optional params (so `value` is
-          // `undefined` here), but caller-supplied params or `getParams()`
-          // shapes may still pass `""` explicitly. Treat both as the
-          // absent form so the segment collapses cleanly.
-          if (value === undefined || value === "") {
-            hadOmittedOptional = true;
-            return "";
-          }
-          return encodePathSegment(value);
-        },
-      );
-      // Second pass: required params (no trailing ?)
-      result = result.replace(
-        /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(?!\?)/g,
-        (_, key) => {
-          const value = params[key];
-          if (value === undefined) {
-            throw new Error(`Missing param "${key}" for route "${name}"`);
-          }
-          return encodePathSegment(value);
-        },
-      );
-      // Clean up slashes only when an optional param was actually omitted,
-      // so intentional trailing-slash patterns like "/blog/" are preserved.
-      if (hadOmittedOptional) {
-        const hadTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
-        result = result.replace(/\/\/+/g, "/").replace(/\/+$/, "") || "/";
-        if (hadTrailingSlash && !result.endsWith("/")) result += "/";
-      }
-    }
+    let result = params
+      ? substitutePatternParams(pattern, params, name)
+      : pattern;
 
     // Append search params as query string
     if (search) {

package/src/router/handler-context.ts

@@ -18,7 +18,7 @@ import { isInsideCacheScope } from "../server/context.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { PRERENDER_PASSTHROUGH } from "../prerender.js";
-import { encodePathSegment } from "./url-params.js";
+import { substitutePatternParams } from "./substitute-pattern-params.js";
 import { fireAndForgetWaitUntil } from "../types/request-scope.js";
 
 /**
@@ -160,52 +160,14 @@ export function createReverseFunction(
       );
     }
 
-    let result = pattern;
-
     // Merge current request params as defaults, explicit params override
     const effectiveParams = currentParams
       ? { ...currentParams, ...hrefParams }
       : hrefParams;
 
-    // Substitute params (strip constraint and optional syntax: :param(a|b)? -> value)
-    // Optional params (:param?) are omitted when not provided
-    if (effectiveParams) {
-      let hadOmittedOptional = false;
-      // First pass: optional params (trailing ?)
-      result = result.replace(
-        /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(\?)/g,
-        (_, key) => {
-          const value = effectiveParams[key];
-          // The matcher omits absent optional params (so `value` is
-          // `undefined` here), but caller-supplied params or `getParams()`
-          // shapes may still pass `""` explicitly. Treat both as the
-          // absent form so the segment collapses cleanly.
-          if (value === undefined || value === "") {
-            hadOmittedOptional = true;
-            return "";
-          }
-          return encodePathSegment(value);
-        },
-      );
-      // Second pass: required params (no trailing ?)
-      result = result.replace(
-        /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(?!\?)/g,
-        (_, key) => {
-          const value = effectiveParams[key];
-          if (value === undefined) {
-            throw new Error(`Missing param "${key}" for route "${name}"`);
-          }
-          return encodePathSegment(value);
-        },
-      );
-      // Clean up slashes only when an optional param was actually omitted,
-      // so intentional trailing-slash patterns like "/blog/" are preserved.
-      if (hadOmittedOptional) {
-        const hadTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
-        result = result.replace(/\/\/+/g, "/").replace(/\/+$/, "") || "/";
-        if (hadTrailingSlash && !result.endsWith("/")) result += "/";
-      }
-    }
+    let result = effectiveParams
+      ? substitutePatternParams(pattern, effectiveParams, name)
+      : pattern;
 
     // Append search params as query string
     if (search) {

package/src/router/substitute-pattern-params.ts

@@ -0,0 +1,56 @@
+import { encodePathSegment } from "./url-params.js";
+
+/**
+ * Substitute `:param` placeholders in a route pattern with values from
+ * `params`. Two-pass: optional params (`:name?`) first so absent values
+ * collapse cleanly, then required params (throws on missing). Constraint
+ * syntax (`:name(en|gb)`) is stripped from the result. Trailing-slash
+ * patterns like `/blog/` are preserved unless an optional segment was
+ * actually omitted.
+ *
+ * Shared by `ctx.reverse()` (server), `createReverse()` (typed runtime
+ * helper), and `useReverse()` (client hook). The behavior must stay
+ * identical across all three call sites.
+ */
+export function substitutePatternParams(
+  pattern: string,
+  params: Record<string, string | undefined>,
+  routeName: string,
+): string {
+  let result = pattern;
+  let hadOmittedOptional = false;
+
+  result = result.replace(
+    /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(\?)/g,
+    (_match, key) => {
+      const value = params[key as string];
+      // The matcher omits absent optional params (so `value` is `undefined`
+      // here), but caller-supplied params or `getParams()` shapes may still
+      // pass `""` explicitly. Treat both as the absent form.
+      if (value === undefined || value === "") {
+        hadOmittedOptional = true;
+        return "";
+      }
+      return encodePathSegment(value);
+    },
+  );
+
+  result = result.replace(
+    /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(?!\?)/g,
+    (_match, key) => {
+      const value = params[key as string];
+      if (value === undefined) {
+        throw new Error(`Missing param "${key}" for route "${routeName}"`);
+      }
+      return encodePathSegment(value);
+    },
+  );
+
+  if (hadOmittedOptional) {
+    const hadTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
+    result = result.replace(/\/\/+/g, "/").replace(/\/+$/, "") || "/";
+    if (hadTrailingSlash && !result.endsWith("/")) result += "/";
+  }
+
+  return result;
+}