@rangojs/router 0.0.0-experimental.106 → 0.0.0-experimental.108

package/skills/hooks/SKILL.md

@@ -776,6 +776,8 @@ function MountInfo() {
 
 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.
 
+> Per-module `*.gen.ts` files are **CLI opt-in and not Vite-watched** — run `rango generate <urls-file>` (or wire it into `predev`) and re-run it whenever the module's routes change. See `/links` for the full generated-file setup and exposure-boundary rules.
+
 ```tsx
 "use client";
 import { Link, useReverse } from "@rangojs/router/client";

package/skills/links/SKILL.md

@@ -263,6 +263,8 @@ function MountInfo() {
 
 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.
 
+> Import the per-module `routes` (e.g. `urls/blog.gen.ts`), **not** `router.named-routes.gen.ts`. The named-routes file is the whole app manifest and is server-only data — importing it into a client component pulls every route name into the client bundle.
+
 ```tsx
 "use client";
 import { Link, useReverse } from "@rangojs/router/client";

package/skills/loader/SKILL.md

@@ -185,7 +185,7 @@ export const ProductLoader = createLoader(async (ctx) => {
   // Request headers
   const auth = ctx.request.headers.get("Authorization");
 
-  // Variables set by middleware (from RSCRouter.Vars augmentation)
+  // Variables set by middleware (from Rango.Vars augmentation)
   const user = ctx.get("user");
 
   // Type-checked URLs for payloads. `.name` resolves within the current

package/skills/middleware/SKILL.md

@@ -196,7 +196,7 @@ export const myMiddleware: Middleware = async (ctx, next) => {
   ctx.env.DB; // D1Database
   ctx.env.KV; // KVNamespace
 
-  // Set variables for downstream handlers (typed via RSCRouter.Vars)
+  // Set variables for downstream handlers (typed via Rango.Vars)
   ctx.set("user", { id: "123", name: "John" });
 
   // Continue to next middleware/handler
@@ -237,8 +237,8 @@ const Dashboard: Handler<"dashboard"> = (ctx) => {
 ```
 
 This works alongside `ctx.get("key")` / `ctx.set("key", value)` (global typing
-via RSCRouter.Vars augmentation). Use `createVar` for route-local or feature-scoped
-data; use RSCRouter.Vars for app-wide middleware state.
+via Rango.Vars augmentation). Use `createVar` for route-local or feature-scoped
+data; use Rango.Vars for app-wide middleware state.
 
 ## Redirect with State in Middleware
 

package/skills/mime-routes/SKILL.md

@@ -108,6 +108,33 @@ path.text("/api/data", () => "plain text version", { name: "dataText" }),
 Without an RSC primary, there is no `text/html` candidate — the Accept header
 picks among the response-type candidates directly.
 
+## Type Safety For Negotiated Paths
+
+`router.named-routes.gen.ts` validates route names, params, search, `href()`, and
+`ValidPaths`, but it does not carry response payload metadata. For MIME or
+response payload types, use one of these surfaces:
+
+- `RouteResponse<typeof patterns, "routeName">` for a specific response variant
+  by route name. This is the clearest option when several MIME variants share
+  one URL pattern.
+- `PathResponse<"/products/:id">` for global URL-pattern lookup after the app
+  registers `typeof router.routeMap`:
+
+```typescript
+// router.tsx
+export const router = createRouter({ document: Document }).routes(urlpatterns);
+
+declare global {
+  namespace Rango {
+    interface RegisteredRoutes extends typeof router.routeMap {}
+  }
+}
+```
+
+`RegisteredRoutes` is what exposes the richer routeMap entries containing
+response payload metadata. Without it, URL-pattern response lookup has paths but
+no payloads, so response types resolve to `ResponseEnvelope<never>`.
+
 ## How It Works
 
 1. **Build time**: `buildRouteTrie()` calls `mergeLeaves()` when multiple routes share a pattern.

package/skills/observability/SKILL.md

@@ -17,7 +17,9 @@ Rango exposes two complementary observability surfaces:
 2. **Structured telemetry** (`telemetry`) — lifecycle events sent to a pluggable
    sink for production monitoring, OpenTelemetry, or custom metrics.
 
-See `packages/rangojs-router/docs/telemetry.md` for the complete event contract.
+The essentials are below. The exported `TelemetryEvent` union type
+(`import type { TelemetryEvent } from "@rangojs/router"`) is the full event
+contract — every event kind and its fields are typed there.
 
 ## Performance timeline
 

package/skills/prerender/SKILL.md

@@ -358,16 +358,16 @@ Both error types propagate to the router's `onError` callback with phase
 The build produces per-URL timing logs:
 
 ```
-[rsc-router] Pre-rendering 12 URL(s) (concurrency: 4)...
-[rsc-router]   OK   /articles/hello            (42ms)
-[rsc-router]   PASS /articles/remote-only      (5ms) - live fallback
-[rsc-router]   SKIP /articles/draft-post       (3ms) - Article is a draft
-[rsc-router] Pre-render complete: 11 done, 1 skipped (1204ms total)
-
-[rsc-router] Rendering 3 static handler(s)...
-[rsc-router]   OK   DocsLayout                 (28ms)
-[rsc-router]   SKIP TocSidebar                 (1ms) - Not ready
-[rsc-router] Static render complete: 2 done, 1 skipped (120ms total)
+[rango] Pre-rendering 12 URL(s) (concurrency: 4)...
+[rango]   OK   /articles/hello            (42ms)
+[rango]   PASS /articles/remote-only      (5ms) - live fallback
+[rango]   SKIP /articles/draft-post       (3ms) - Article is a draft
+[rango] Pre-render complete: 11 done, 1 skipped (1204ms total)
+
+[rango] Rendering 3 static handler(s)...
+[rango]   OK   DocsLayout                 (28ms)
+[rango]   SKIP TocSidebar                 (1ms) - Not ready
+[rango] Static render complete: 2 done, 1 skipped (120ms total)
 ```
 
 A `FAIL` line is logged per-URL when a handler throws a non-Skip error. The
@@ -463,9 +463,9 @@ export const Product = Passthrough(ProductDef, async (ctx) => {
 Passthrough entries are logged distinctly:
 
 ```
-[rsc-router]   OK   /blog/a                          (42ms)
-[rsc-router]   PASS /blog/b                          (3ms) - live fallback
-[rsc-router]   OK   /blog/c                          (38ms)
+[rango]   OK   /blog/a                          (42ms)
+[rango]   PASS /blog/b                          (3ms) - live fallback
+[rango]   OK   /blog/c                          (38ms)
 ```
 
 ## Edge Cases and Constraints

package/skills/rango/SKILL.md

@@ -266,6 +266,15 @@ Each file is classified by its contents:
 Directories are scanned recursively for `.ts`/`.tsx` files, skipping `node_modules`,
 dotfiles, and existing `.gen.` files.
 
+> The two generated files are **not interchangeable surfaces**.
+> `router.named-routes.gen.ts` augments the global `GeneratedRouteMap` for
+> named-route typing (`Handler<"name">`, `ctx.reverse("name")`, prerender).
+> Per-module `*.gen.ts` exports a local `routes` map for `useReverse(routes)`
+> and explicit local handler typing (`Handler<".name", routes>`). Neither
+> carries response payloads — response/MIME payload inference comes from
+> `typeof router.routeMap` via `RegisteredRoutes`, not `*.named-routes.gen.ts`.
+> See `/typesafety` for the full surface breakdown.
+
 ### Recursive includes
 
 The generator follows `include()` calls across files, resolving imports to build

package/skills/response-routes/SKILL.md

@@ -238,7 +238,24 @@ type ProductsData = RouteResponse<typeof apiPatterns, "products">;
 
 ### PathResponse (global lookup by URL pattern)
 
-Look up response type from the merged route map by URL pattern:
+`PathResponse` reads from `RegisteredRoutes`, which carries response payload
+metadata. That surface is **not** auto-wired — without the augmentation below,
+`PathResponse` falls back to the generated path/search map, or to a permissive
+map when nothing is generated. Either way, it has no response payload metadata,
+so response routes resolve to `ResponseEnvelope<never>`:
+
+```typescript
+// router.tsx
+export const router = createRouter({ document: Document }).routes(urlpatterns);
+
+declare global {
+  namespace Rango {
+    interface RegisteredRoutes extends typeof router.routeMap {}
+  }
+}
+```
+
+With that in place, look up the response type by URL pattern:
 
 ```typescript
 import type { PathResponse } from "@rangojs/router/client";
@@ -252,6 +269,11 @@ type Home = PathResponse<"/">;
 // = ResponseEnvelope<never>
 ```
 
+For local/scoped response typing without global augmentation, prefer
+`RouteResponse<typeof patterns, "routeName">` (see the section above) — it reads
+the response payload straight from the `urls()` patterns and needs no
+`RegisteredRoutes` wiring.
+
 ### ParamsFor with Response Routes
 
 ```typescript
@@ -363,11 +385,13 @@ export const urlpatterns = urls(({ path, include }) => [
 import type { RouteResponse } from "@rangojs/router";
 import type { PathResponse, ParamsFor } from "@rangojs/router/client";
 
-// Scoped (before mount) -- use the module directly
+// Scoped (before mount) -- use the module directly, no global wiring needed
 type Stats = RouteResponse<typeof blogApiPatterns, "stats">;
 // = ResponseEnvelope<{ views: number; visitors: number }>
 
-// After mounting -- names get prefixed
+// After mounting -- names get prefixed.
+// PathResponse needs `RegisteredRoutes extends typeof router.routeMap` (see above),
+// otherwise it resolves to ResponseEnvelope<never>.
 type BlogStats = PathResponse<"/blog/api/stats">;
 // = ResponseEnvelope<{ views: number; visitors: number }>
 

package/skills/router-setup/SKILL.md

@@ -71,7 +71,7 @@ urls(
 ## Router Options
 
 ```typescript
-interface RSCRouterOptions<TEnv> {
+interface RangoOptions<TEnv> {
   // URL patterns from urls() function
   urls: UrlPatterns;
 
@@ -405,7 +405,7 @@ interface AppBindings {
   KV: KVNamespace;
 }
 
-// Variables declared via module augmentation
+// Variables declared via global namespace augmentation
 interface AppVariables {
   user?: { id: string; name: string };
 }
@@ -417,7 +417,7 @@ const router = createRouter<AppBindings>({
 
 // Register types globally for implicit typing
 declare global {
-  namespace RSCRouter {
+  namespace Rango {
     interface Env extends AppBindings {}
     interface Vars extends AppVariables {}
   }

package/skills/typesafety/SKILL.md

@@ -37,7 +37,28 @@ available globally.
 - `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
+  `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 `ValidPaths` 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 `PathResponse` resolves to `ResponseEnvelope<never>` until you wire
+`RegisteredRoutes`.
 
 Recommended setup:
 
@@ -50,7 +71,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 +79,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 `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,12 +196,15 @@ function ShopNav() {
 }
 ```
 
-`href()` and path-based response utilities read from `RegisteredRoutes`, so if
-you want them typed globally you should augment:
+`href()` and `ValidPaths` 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 **`PathResponse`** (response-payload inference), which
+`GeneratedRouteMap` cannot provide:
 
 ```typescript
 declare global {
-  namespace RSCRouter {
+  namespace Rango {
     interface RegisteredRoutes extends typeof router.routeMap {}
   }
 }
@@ -155,7 +227,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 +247,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 +268,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 +280,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 +292,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 +331,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.
@@ -325,11 +403,18 @@ export const NamedRoutes = {
 } as const;
 ```
 
-You never open a `.gen.ts` by hand — the generated types exist only to make call
-sites honest. Treat the generated machinery as invisible: don't import from
-`*.gen.ts`, don't reach for `RSCRouter.GeneratedRouteMap` directly, and if a type
-error points at the generated map instead of your call site, that's a smell — fix
-the call site (or regenerate), never edit the generated file.
+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
 
@@ -420,9 +505,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
@@ -570,9 +655,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)
@@ -611,10 +724,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
 
@@ -650,7 +802,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 {}
   }
@@ -661,13 +813,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 ValidPaths. Add `RegisteredRoutes
+//    extends typeof router.routeMap` when global response payload helpers such
+//    as 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) };
 });
 

package/src/__augment-tests__/augment.ts

@@ -0,0 +1,37 @@
+/**
+ * Simulates a consumer augmenting the Rango global namespace, the way a real
+ * app does in router.tsx (Env/Vars) and via the generated router.named-routes.gen.ts
+ * (GeneratedRouteMap).
+ *
+ * This file is compiled ONLY by tsconfig.augment-check.json and is excluded from
+ * the main program, so the global augmentation here does not leak into the rest
+ * of the type tests, which assert the UNAUGMENTED fallbacks
+ * (see src/__tests__/augmentation-fallback-types.test.ts).
+ */
+
+export interface TestBindings {
+  DB: { query: (sql: string) => string };
+  SECRET: string;
+}
+
+export interface TestVars {
+  user?: { id: string; role: "admin" | "user" };
+  requestId?: string;
+}
+
+declare global {
+  namespace Rango {
+    interface Env extends TestBindings {}
+    interface Vars extends TestVars {}
+    // Mirrors the shape emitted into router.named-routes.gen.ts: plain string
+    // patterns, plus { path, search } objects for routes with a search schema.
+    interface GeneratedRouteMap {
+      readonly home: "/";
+      readonly "blog.post": "/blog/:slug";
+      readonly search: {
+        readonly path: "/search";
+        readonly search: { readonly q: "string"; readonly page: "number?" };
+      };
+    }
+  }
+}