@rangojs/router 0.0.0-experimental.eb0645d3 → 0.0.0-experimental.f1468e3c

package/skills/testing/setup.md

@@ -0,0 +1,123 @@
+# Testing setup — the two vitest projects
+
+**Layer:** cross-cutting (vitest config) · **Import:** `@rangojs/router/testing/vitest`
+
+Real machinery: Vite transpiles `@rangojs/router`'s shipped TS source and resolves the bare specifier to its react-server impls so your app's router / loaders / middleware import in a bare Vitest process. You SEED nothing here — this file only wires the two projects every other recipe builds on. The node/DOM project keeps React on its CLIENT build; the Flight project flips to the `react-server` condition.
+
+## API
+
+### Options — `RangoTestAliasOptions`
+
+| Field    | Type                     | Meaning                                                                                                                                                                                                                                                                                      |
+| -------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `preset` | `"node" \| "cloudflare"` | Deployment preset, matching `rango({ preset })` in the Vite plugin. `"cloudflare"` additionally stubs the `cloudflare:workers` / `cloudflare:email` runtime virtuals a CF route tree imports. A string (not a boolean) so more presets can be added without an API change. Default `"node"`. |
+
+### Functions
+
+| Function                    | Returns                                   | Use                                                                                                                                                                                                         |
+| --------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rangoTestConfig(opts?)`    | `{ alias, server: { deps: { inline } } }` | Recommended. Spread into the node/DOM project's `test` block. Bundles the resolve aliases AND `server.deps.inline`.                                                                                         |
+| `rangoTestAliases(opts?)`   | `TestAlias[]` (`{ find, replacement }[]`) | Lower-level. The bare `@rangojs/router` -> `index.rsc.ts` alias plus the `:version` / `@vitejs/plugin-rsc/rsc` stubs (and CF stubs under `preset:"cloudflare"`). Used in the rsc project's `resolve.alias`. |
+| `rangoUseClientTransform()` | a Vite plugin (`{ name, transform }`)     | Add to the rsc project `plugins`. Applies the `"use client"` transform so `renderServerTree` auto-discovers client islands from the server tree's imports.                                                  |
+
+### Returns — `RangoTestConfig` (from `rangoTestConfig`)
+
+```ts
+interface RangoTestConfig {
+  alias: TestAlias[]; // -> test.alias
+  server: { deps: { inline: RegExp[] } }; // [/@rangojs[/\\]router/] -> test.server.deps.inline
+}
+```
+
+## Recipe
+
+```ts
+// vitest.config.ts — the node + DOM project (keeps React on its CLIENT build)
+import { defineConfig } from "vitest/config";
+import { rangoTestConfig } from "@rangojs/router/testing/vitest";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    include: ["test/**/*.test.{ts,tsx}"],
+    environment: "node", // renderRoute tests add a `// @vitest-environment happy-dom` pragma
+    // `preset: "cloudflare"` also stubs cloudflare:workers / cloudflare:email (default "node").
+    ...rangoTestConfig({ preset: "cloudflare" }),
+  },
+});
+```
+
+```ts
+// vitest.rsc.config.ts — the Flight project (react-server condition)
+import { defineConfig } from "vitest/config";
+import {
+  rangoTestAliases,
+  rangoUseClientTransform,
+  rangoInlineDeps,
+} from "@rangojs/router/testing/vitest";
+
+// Production React in this process AND any forked worker (forks inherit env).
+process.env.NODE_ENV = "production";
+
+export default defineConfig({
+  plugins: [rangoUseClientTransform()],
+  resolve: {
+    conditions: ["react-server"],
+    alias: rangoTestAliases({ preset: "cloudflare" }), // or { preset: "node" }
+  },
+  test: {
+    globals: true,
+    include: ["**/*.rsc-test.{ts,tsx}"],
+    pool: "forks",
+    execArgv: ["--conditions=react-server"], // or React throws "react-server condition must be enabled"
+    // Required for an installed consumer on Node >= 23 (rango ships TS source).
+    server: { deps: { inline: rangoInlineDeps } },
+  },
+});
+```
+
+```ts
+// example.test.ts — one test in the node/DOM project, importing real app code
+import { describe, it, expect } from "vitest";
+import { dispatch } from "@rangojs/router/testing";
+import { createRouter } from "@rangojs/router";
+import { apiPatterns } from "../src/api/urls"; // path.json(...) routes only, no Prerender()
+
+const router = createRouter().routes(apiPatterns);
+
+describe("api", () => {
+  it("serializes a JSON response route", async () => {
+    const res = await dispatch(router, { request: "/health" });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ status: "ok" });
+  });
+});
+```
+
+Scripts:
+
+```jsonc
+{
+  "scripts": {
+    "test:unit": "vitest run",
+    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts",
+  },
+}
+```
+
+## Caveats
+
+- Node >= 23 requires `rangoTestConfig()`, not bare `rangoTestAliases()`. `@rangojs/router` is consumed as SOURCE (exports -> `./src/*.ts`), and Node >= 23 refuses to type-strip `.ts` under `node_modules` (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`). `rangoTestConfig` ships as compiled JS AND adds `server.deps.inline: [/@rangojs[/\\]router/]` so Vite (not Node) transpiles rango source. With bare `rangoTestAliases` you must wire `deps.inline` yourself.
+- Two separate projects. The node/DOM project keeps React on its CLIENT build; the Flight project uses the `react-server` condition in a separate `vitest.rsc.config.ts`. The main project must NOT set `react-server` — it flips React to the no-hooks server build and breaks every `renderRoute` / client test.
+- The rsc project needs BOTH `resolve.conditions: ["react-server"]` AND the bare `@rangojs/router` -> `index.rsc.ts` alias from `rangoTestAliases({ preset })`. `resolve.conditions` alone is not reliably applied to bare-package export resolution; without the alias a handler/component reading `getRequestContext()` / `cookies()` resolves the throwing out-of-react-server stub (symptom: `renderHandler` returns `tree: undefined`). `renderToFlightString` / `renderServerTree` now self-diagnose this exact misconfiguration — they reject with an actionable message naming `rangoTestAliases`, rather than surfacing the opaque stub error.
+- `NODE_ENV` must be `"production"` in the rsc project. Dev `NODE_ENV` crashes the bare worker (jsxDEV owner-stack machinery uninitialized) and emits volatile debug rows that defeat stable Flight snapshots.
+- The forked rsc worker (`pool: "forks"`) must force the condition via `execArgv: ["--conditions=react-server"]`, or React throws "the react-server condition must be enabled".
+- The `@rangojs/router:version` and `@vitejs/plugin-rsc/rsc` virtuals must be stubbed; the preset does it. A bare router import without stubbing throws.
+- The rango fragment goes under `test` (`test.alias` + `test.server.deps.inline`, both returned by `rangoTestConfig`), NOT under top-level `resolve`.
+- Wire `rangoUseClientTransform()` into the rsc project `plugins` so islands auto-discover from the server tree imports (see `./server-tree.md`); without it, register islands explicitly with `clientComponents`.
+
+## See also
+
+- (cross-cutting)
+- Siblings: `./flight.md`, `./server-tree.md`, `./render-handler.md`, `./response-routes.md`
+- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Setup" (and the subsections "Resolving @rangojs/router in a unit test — use the preset" and "Two vitest projects")

package/skills/typesafety/SKILL.md

@@ -32,12 +32,34 @@ is only needed when you want the richer `typeof router.routeMap` shape
 available globally.
 
 - `GeneratedRouteMap` — auto-registered by `router.named-routes.gen.ts`
-  Use for `Handler<"name">`, `Prerender<"name">`, server `ctx.reverse()`,
-  and named-route param/search inference.
+  Use for `Handler<"name">` (type annotation), `Prerender<"name">(...)` (function
+  call with type arg for param inference), server `ctx.reverse()`, and
+  named-route param/search inference.
 - `typeof router.routeMap` — the real merged route map from your router
   instance, including response-route metadata such as `{ path, response }`.
 - `RegisteredRoutes` — manual global hook for exposing `typeof router.routeMap`
-  to utilities like `href()`, `ValidPaths`, and `PathResponse`.
+  to global utilities that need the exact router-builder map, especially
+  `Rango.PathResponse`.
+
+### Generated Route Type Surfaces
+
+There are three distinct typing surfaces. They are **not** interchangeable —
+pick the one that matches what you need to type:
+
+| Surface             | Source                                   | Scope  | Gives                                    | Does not give                                                                                    |
+| ------------------- | ---------------------------------------- | ------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `GeneratedRouteMap` | `router.named-routes.gen.ts` (auto)      | global | route names, path params, search schemas | response/MIME payloads                                                                           |
+| `routes`            | per-module `*.gen.ts` (`rango generate`) | local  | local names, params, search              | the global app map                                                                               |
+| `RegisteredRoutes`  | manual `extends typeof router.routeMap`  | global | paths, params, **response payloads**     | the `Handler`/`Prerender` default (those read `GeneratedRouteMap` to avoid a `router.tsx` cycle) |
+
+Key consequence: `href()` and the ambient `Rango.Path` type are typed from
+whichever map is present — they prefer `RegisteredRoutes` when you wire it, otherwise fall back to
+the auto-generated `GeneratedRouteMap`, so **`rango generate` alone gives you
+path-checked `href()`** with no manual augmentation. Response and MIME payload
+inference is the exception: it comes only from `typeof router.routeMap` (via
+`RegisteredRoutes`), because `GeneratedRouteMap` carries paths + search but no
+payloads — so `Rango.PathResponse` resolves to `never` until you wire
+`RegisteredRoutes`.
 
 Recommended setup:
 
@@ -50,7 +72,7 @@ import type { AppBindings, AppVars } from "./env";
 export const router = createRouter<AppBindings>({}).routes(urlpatterns);
 
 declare global {
-  namespace RSCRouter {
+  namespace Rango {
     interface Env extends AppBindings {}
     interface Vars extends AppVars {}
     interface RegisteredRoutes extends typeof router.routeMap {}
@@ -58,6 +80,54 @@ declare global {
 }
 ```
 
+### Single-App Setup Checklist
+
+For one app, keep the ambient types, generated named-routes file, and router
+instance in the same TypeScript program:
+
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "strict": true,
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "noEmit": true,
+  },
+  "include": ["src"],
+  "files": ["src/router.tsx"],
+}
+```
+
+Then generate the route types from the router file:
+
+```bash
+npx rango generate src/router.tsx
+```
+
+This creates `src/router.named-routes.gen.ts`, which augments
+`Rango.GeneratedRouteMap`. Keep that generated file committed with the router
+source. The `files` entry keeps `router.tsx` in the program even when nothing
+imports it directly, so `Rango.Env`, `Rango.Vars`, and optional
+`Rango.RegisteredRoutes` augmentation are visible to handlers, loaders, actions,
+and client helpers.
+
+### Named Routes, `$$routeNames`, And `router.routeMap`
+
+There are two runtime/type surfaces with similar names:
+
+- `router.named-routes.gen.ts` exports `NamedRoutes` and augments
+  `Rango.GeneratedRouteMap`. The Vite plugin imports that file internally and
+  injects it as `$$routeNames` so `router.reverse` has the static route-name map.
+  App code should not pass or import `$$routeNames` directly.
+- `router.routeMap` is the public router instance property for type extraction.
+  Use `typeof router.routeMap` when augmenting `Rango.RegisteredRoutes` for
+  global response payload helpers such as `Rango.PathResponse`.
+
+Do not document or use a public `router.routeNames` API unless one is
+intentionally added. Today, the public extraction surface is `router.routeMap`;
+the generated file and `$$routeNames` are build machinery.
+
 ## Route Definition with Type-Safe Names
 
 ```typescript
@@ -127,17 +197,107 @@ function ShopNav() {
 }
 ```
 
-`href()` and path-based response utilities read from `RegisteredRoutes`, so if
-you want them typed globally you should augment:
+`href()` and the `Rango.Path` type read from `RegisteredRoutes` when you augment
+it, otherwise from the auto-generated `GeneratedRouteMap` — so `rango generate`
+alone type-checks `href()` paths with no manual augmentation. The augmentation
+below is only needed for **`Rango.PathResponse`** (response-payload inference), which
+`GeneratedRouteMap` cannot provide:
 
 ```typescript
 declare global {
-  namespace RSCRouter {
+  namespace Rango {
     interface RegisteredRoutes extends typeof router.routeMap {}
   }
 }
 ```
 
+For wrapper helpers, type the path parameter as `Rango.Path`. It is ambient (no
+import) and shares `href()`'s compile-time path checking, so a wrapper stays in
+sync with your routes automatically:
+
+```typescript
+import { href } from "@rangojs/router/client";
+
+export const appHref = (path: Rango.Path): string => href(path);
+```
+
+For response-route payloads, `Rango.PathResponse<T>` is the ambient lookup. It
+accepts a route _pattern_ **or** a concrete path, so it also serves as the return
+type of a typed `fetch` wrapper. It only resolves once `RegisteredRoutes` carries
+response metadata:
+
+```typescript
+import { href } from "@rangojs/router/client";
+
+type Product = Rango.PathResponse<"/api/products/:id">; // by pattern
+type Same = Rango.PathResponse<"/api/products/42">; // by concrete path
+
+// Response inferred from the concrete path passed in:
+async function get<T extends Rango.Path>(
+  path: T,
+): Promise<Rango.PathResponse<T>> {
+  return fetch(href(path)).then((r) => r.json());
+}
+const product = await get("/api/products/42"); // Product (bare value)
+```
+
+Pattern keys (`/:id`) match exactly; a concrete path under a _nested_ dynamic
+route can match several patterns and union their responses.
+
+`Rango.PathResponse` describes the JSON **wire** shape, not the handler's raw
+return. A `path.json()` handler returning `{ createdAt: Date }` resolves here to
+`{ createdAt: string }` (bare value), matching what `r.json()` yields. This
+is applied via the ambient `Rango.JsonSerialize<T>` transform (`Date -> string`,
+honors `toJSON()`, drops functions/`undefined`, `bigint -> never`). A separate
+`Rango.FlightSerialize<T>` models the higher-fidelity RSC Flight boundary
+(loaders / RSC props, where `Date` is preserved) — do **not** use it for
+`path.json()`.
+
+### Overriding serialization globally
+
+For your own types, the zero-config way to control the JSON wire shape is a
+`toJSON()` method — `Rango.JsonSerialize` honors it, and it matches the runtime
+exactly (`JSON.stringify` calls `toJSON()`):
+
+```typescript
+class Money {
+  constructor(private cents: number) {}
+  toJSON(): number {
+    return this.cents;
+  }
+}
+// Rango.JsonSerialize<Money> is number; Rango.PathResponse reflects it.
+```
+
+To override a transform for types you **don't** own (or for the Flight boundary,
+which has no `toJSON()`), augment its override slot. Because `Rango.JsonSerialize`
+/ `Rango.FlightSerialize` are type _aliases_ (TS can't merge those), you provide a
+single member that is your **complete** transform, delegating to the built-in for
+the cases you don't change:
+
+```typescript
+declare global {
+  namespace Rango {
+    interface JsonSerializeOverride<T> {
+      app: T extends Decimal ? string : Rango.JsonSerializeBuiltin<T>;
+    }
+    interface FlightSerializeOverride<T> {
+      app: T extends Money ? number : Rango.FlightSerializeBuiltin<T>;
+    }
+  }
+}
+// Rango.JsonSerialize<Decimal> -> string; Rango.FlightSerialize<Money> -> number;
+// everything else stays on the built-in, recursively (nested fields too).
+```
+
+Rules: provide **exactly one** member (the slot is read as
+`Override<T>[keyof Override<T>]`, so multiple members union and conflict).
+Overrides win over `toJSON()` and apply at every nesting level. Caveat for JSON:
+the `path.json()` runtime is plain `JSON.stringify`, which only honors `toJSON()`,
+so a `JsonSerializeOverride` that disagrees with what the runtime emits will lie —
+prefer `toJSON()` for your own types and use the slot only for types you can't
+modify.
+
 See `/links` for full URL generation guide.
 
 ## Environment Type Setup
@@ -155,7 +315,7 @@ export interface AppBindings {
   AI: Ai;
 }
 
-// Variables set by middleware — declared via module augmentation
+// Variables set by middleware — declared via global namespace augmentation
 export interface AppVariables {
   user?: { id: string; email: string; role: string };
   requestId?: string;
@@ -175,7 +335,7 @@ const router = createRouter<AppBindings>({
 
 // Register bindings and variables globally for implicit typing
 declare global {
-  namespace RSCRouter {
+  namespace Rango {
     interface Env extends AppBindings {}
     interface Vars extends AppVariables {}
   }
@@ -196,7 +356,7 @@ export const authMiddleware: Middleware = async (ctx, next) => {
 // loaders - typed context
 export const UserLoader = createLoader(async (ctx) => {
   const db = ctx.env.DB; // D1Database (plain bindings)
-  const userId = ctx.get("user")?.id; // from RSCRouter.Vars
+  const userId = ctx.get("user")?.id; // from Rango.Vars
   return db.prepare("SELECT * FROM users WHERE id = ?").bind(userId).first();
 });
 ```
@@ -208,7 +368,7 @@ Register environment types globally for implicit typing:
 ```typescript
 // router.tsx
 declare global {
-  namespace RSCRouter {
+  namespace Rango {
     interface Env extends AppBindings {}
     interface Vars extends AppVariables {}
   }
@@ -220,8 +380,8 @@ Now handlers have typed context without explicit imports:
 ```typescript
 // In loaders
 export const DashboardLoader = createLoader(async (ctx) => {
-  // ctx.env.DB is typed from global RSCRouter.Env
-  // ctx.get("user") is typed from global RSCRouter.Vars
+  // ctx.env.DB is typed from global Rango.Env
+  // ctx.get("user") is typed from global Rango.Vars
   const user = ctx.get("user");
   return { user };
 });
@@ -259,15 +419,21 @@ This avoids circular references because `Handler` defaults to `GeneratedRouteMap
 (from `router.named-routes.gen.ts`) instead of `RegisteredRoutes` (which depends on `router.tsx`).
 
 You can also pass an explicit route map for per-module isolation (opt-in,
-after running `npx rango generate`):
+after running `npx rango generate`). With a local map, the route name is
+**dot-prefixed** so params and search resolve from `routes`, not the global map:
 
 ```typescript
 import type { Handler } from "@rangojs/router";
 import type { routes } from "./urls.gen.js";
 
-export const SearchPage: Handler<"search", routes> = (ctx) => { ... };
+export const SearchPage: Handler<".search", routes> = (ctx) => { ... };
 ```
 
+Note the difference: `Handler<"search">` (no dot) resolves against the global
+`GeneratedRouteMap`; `Handler<".search", routes>` resolves against the local
+`routes` map. Mixing them — `Handler<"search", routes>` — silently ignores
+`routes` for param/search inference and only uses it for local `ctx.reverse(".x")`.
+
 Supported types: `"string"`, `"number"`, `"boolean"`, with `?` suffix for optional.
 Values are automatically coerced from query string (e.g., `"2"` becomes `2` for numbers).
 Routes without a `search` schema keep the standard `URLSearchParams` behavior.
@@ -287,6 +453,12 @@ type SP = RouteSearchParams<"search">;
 type P = RouteParams<"blogPost">;
 // { slug: string }
 
+// Optional URL params (`:slug?`) resolve to `string | undefined`
+// because absent segments are omitted from `ctx.params` at runtime.
+type C = RouteParams<"checkout">;
+// { step?: string }
+// → ctx.params.step is `string | undefined`; use `?? "default"` to coalesce.
+
 // Use in component props
 interface SearchResultsProps {
   params: RouteSearchParams<"search">;
@@ -319,6 +491,19 @@ export const NamedRoutes = {
 } as const;
 ```
 
+You never open a `.gen.ts` by hand. Treat the generated types as call-site
+honesty checks, not modules to read:
+
+- **Do not import `router.named-routes.gen.ts` directly**, and don't reach for
+  `Rango.GeneratedRouteMap`. It is the whole-app manifest, auto-wired
+  globally — `Handler<"name">` and `ctx.reverse("name")` already see it.
+- **Per-module `*.gen.ts` imports are fine** — they are the opt-in local-route
+  pattern for `useReverse(routes)` and explicit local handler typing
+  (`Handler<".name", routes>`). See `/links`.
+
+If a type error points at a generated map instead of your call site, that's a
+smell — fix the call site (or regenerate), never edit the generated file.
+
 ## Loader Type Safety
 
 Loaders have typed return values:
@@ -408,9 +593,9 @@ export function PaginationLayout(ctx: any) {
 }
 ```
 
-### Why not just use RSCRouter.Vars?
+### Why not just use Rango.Vars?
 
-`RSCRouter.Vars` (via module augmentation) provides app-global typing for
+`Rango.Vars` (via global namespace augmentation) provides app-global typing for
 `ctx.get("key")` / `ctx.set("key", value)`. It works for middleware state
 shared app-wide. `createVar<T>()` is for route-local or feature-scoped
 context -- the producer and consumer import the same token, creating a
@@ -462,9 +647,11 @@ export const ProductLoader = createLoader(async (ctx) => {
 });
 
 // Built-in Breadcrumbs — or any custom handle created with createHandle()
+```
 
+```tsx
 // Client component — typeof infers all generics
-("use client");
+"use client";
 import { useLoader, useHandle, type Breadcrumbs } from "@rangojs/router/client";
 import type { ProductLoader } from "../loaders";
 
@@ -485,6 +672,42 @@ RSC Flight serialization calls `toJSON()` on both loaders and handles,
 sending only `{ __brand, $$id }` to the client. The hooks recover the
 full functionality from module-level registries.
 
+## Stable identity: `path#export`
+
+Loaders, handles, cached functions (`functionId`), and server actions
+(`actionId`) all share one identity scheme: `{modulePath}#{exportName}`,
+injected at build by the `exposeInternalIds` and `exposeActionId` Vite plugins.
+This is also the identity React server actions carry across the Flight boundary,
+which is why a `revalidate()` predicate sees an action as a `path#export` string:
+
+```typescript
+revalidate(
+  ({ actionId }) => actionId === "src/actions/cart.ts#addToCart" || undefined,
+);
+```
+
+`actionId` is the only stable reference React exposes across the Flight boundary,
+so it stays as the floor and escape hatch. The hand-written-string surface
+(`actionId?.includes("cart.ts#")`) is brittle: a renamed action or moved file
+silently stops matching with no compile error. Prefer **`ctx.isAction()`** in a
+revalidate predicate — it resolves the action's id from an imported reference, so
+a rename is a type error in one place instead of silent drift:
+
+```ts
+import { addToCart, removeFromCart } from "./actions/cart";
+import * as CartActions from "./actions/cart";
+
+revalidate((ctx) => ctx.isAction(addToCart) || undefined); // one action
+revalidate((ctx) => ctx.isAction(addToCart, removeFromCart) || undefined); // several
+revalidate((ctx) => ctx.isAction(CartActions) || undefined); // any action in the module
+```
+
+`ctx.isAction()` (only available on the revalidate predicate's context) returns a
+raw boolean — combine with `|| undefined` for the "revalidate on match, else
+defer" intent. It resolves the reference the same way the router derives
+`actionId` (`$id` in production, `$$id` in dev), so matching
+works in both modes. `actionId` stays available for advanced cases.
+
 ## Location State Type Safety
 
 ```typescript
@@ -520,9 +743,37 @@ function ProductHeader() {
 
 ## Multi-Project tsconfig Setup
 
-For monorepos or multi-app setups, use a shared base tsconfig. Each app only needs
-to extend the base and add its `router.tsx` to `files` so TypeScript picks up the
-global type declarations (like `RSCRouter.Env`).
+For monorepos or multi-app setups, each app should have its own TypeScript
+program. Do not typecheck two Rango apps with different `Rango.Env`,
+`Rango.Vars`, or `Rango.RegisteredRoutes` declarations in one tsconfig, because
+ambient global interfaces merge across the whole program.
+
+### Multiple routers in one program
+
+`Rango.GeneratedRouteMap` is a **single global interface**. Each router's
+generated `router.named-routes.gen.ts` augments it, so two routers in the **same
+TS program** that define overlapping route names (e.g. both have a `home`) make
+the augmentations collide:
+
+```text
+Interface 'GeneratedRouteMap' cannot simultaneously extend ...
+Named property 'home' ... are not identical.
+```
+
+This is the multi-router / host-router case. Resolve it by:
+
+- **Separate TS programs** — give each router its own tsconfig (as below) so only
+  one generated map is in scope per program. Recommended.
+- **Unique route-name prefixes** — name routes per router (`appA.home`,
+  `appB.home`) so the merged global map has no duplicate keys.
+
+A single global generated map is a single-router convenience; global named-route
+typing across multiple routers in one program is not supported today (it would
+need per-router scoping in the generated map).
+
+Use a shared base tsconfig for common compiler options, then make every app
+tsconfig include its own source tree, its own `router.tsx`, and the generated
+`router.named-routes.gen.ts` that lives beside that router.
 
 ```jsonc
 // tsconfig.base.json (root)
@@ -561,10 +812,49 @@ global type declarations (like `RSCRouter.Env`).
 }
 ```
 
-The `files` array ensures `router.tsx` (which contains `declare global { namespace RSCRouter { interface Env; interface Vars } }`)
-is always included in the compilation even if nothing directly imports it. Route types come from the
-auto-generated `*.named-routes.gen.ts` file (via `rango generate`), not from manual declaration.
-Each app gets its own typed environment without interfering with other apps.
+Run generation per app:
+
+```bash
+npx rango generate apps/shop/src/router.tsx
+npx rango generate apps/blog/src/router.tsx
+```
+
+If an app has multiple tsconfigs (`tsconfig.app.json`, `tsconfig.test.json`,
+`tsconfig.worker.json`), every tsconfig that typechecks Rango handlers,
+components, loaders, actions, or client navigation must see the same app-local
+type surfaces:
+
+```jsonc
+// apps/shop/tsconfig.test.json
+{
+  "extends": "./tsconfig.json",
+  "include": ["src", "tests"],
+  "files": ["src/router.tsx"],
+}
+```
+
+The `files` array ensures `router.tsx` is always included even if nothing
+directly imports it. The generated `router.named-routes.gen.ts` is normally
+covered by `include: ["src"]`; if a tsconfig uses a narrow `include`, add the
+generated file explicitly. Each app gets its own typed environment and named
+route map without interfering with other apps.
+
+For response and MIME payload lookup in each app, augment `RegisteredRoutes`
+inside that app's router file:
+
+```typescript
+// apps/shop/src/router.tsx
+export const router = createRouter<ShopEnv>({ document: Document }).routes(
+  urlpatterns,
+);
+
+declare global {
+  namespace Rango {
+    interface Env extends ShopEnv {}
+    interface RegisteredRoutes extends typeof router.routeMap {}
+  }
+}
+```
 
 ## Complete Type-Safe Setup
 
@@ -600,7 +890,7 @@ const router = createRouter<AppBindings>({
 
 // Register bindings and variables globally for implicit typing
 declare global {
-  namespace RSCRouter {
+  namespace Rango {
     interface Env extends AppBindings {}
     interface Vars extends AppVariables {}
   }
@@ -611,13 +901,16 @@ export default router;
 
 // 4. Run `npx rango generate src/router.tsx` to generate
 //    router.named-routes.gen.ts (auto-registers GeneratedRouteMap globally).
-//    No manual RegisteredRoutes declaration needed.
+//    No manual RegisteredRoutes declaration is needed for named-route handlers,
+//    ctx.reverse, prerender, href(), or Rango.Path. Add `RegisteredRoutes
+//    extends typeof router.routeMap` when global response payload helpers such
+//    as Rango.PathResponse need the richer router.routeMap metadata.
 
 // 5. loaders/*.ts - Type-safe loaders
 export const ProductLoader = createLoader(async (ctx) => {
   // ctx.params: { slug: string }
-  // ctx.get("user"): User | undefined  (from RSCRouter.Vars)
-  // ctx.env.DB: D1Database  (plain bindings from RSCRouter.Env)
+  // ctx.get("user"): User | undefined  (from Rango.Vars)
+  // ctx.env.DB: D1Database  (plain bindings from Rango.Env)
   return { product: await fetchProduct(ctx.params.slug) };
 });