@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.204030a9

package/skills/typesafety/SKILL.md

@@ -1,175 +1,375 @@
 ---
 name: typesafety
-description: Set up type-safe routes, params, and environment types in rsc-router
+description: Set up type-safe routes, params, and environment types in @rangojs/router
 argument-hint: [setup]
 ---
 
 # Type Safety Setup
 
-rsc-router provides end-to-end type safety for routes, parameters, and environment.
+@rangojs/router provides end-to-end type safety for routes, parameters, and environment.
 
-## Route Type Registration
-
-Register route types globally for type-safe `href()` and params:
+## Router Setup
 
 ```typescript
 // router.tsx
-import { createRSCRouter } from "rsc-router/server";
-import { homeRoutes } from "./routes/home";
-import { shopRoutes } from "./routes/shop";
+import { createRouter } from "@rangojs/router";
+import { urlpatterns } from "./urls";
+
+const router = createRouter<AppBindings>({
+  document: Document,
+}).routes(urlpatterns);
+
+// Server-side named-route reverse (type-safe via routeMap)
+export const reverse = router.reverse;
+
+export default router;
+```
+
+### Which global type should I use?
+
+Use the generated route map by default. Manual `RegisteredRoutes` augmentation
+is only needed when you want the richer `typeof router.routeMap` shape
+available globally.
 
-const _router = createRSCRouter<AppEnv>({ document: Document })
-  .routes(homeRoutes)
-  .map(() => import("./handlers/home"))
-  .routes("/shop", shopRoutes)
-  .map(() => import("./handlers/shop"));
+- `GeneratedRouteMap` — auto-registered by `router.named-routes.gen.ts`
+  Use for `Handler<"name">`, `Prerender<"name">`, 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 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 `ResponseEnvelope<never>` until you wire
+`RegisteredRoutes`.
+
+Recommended setup:
+
+```typescript
+// router.tsx
+import { createRouter } from "@rangojs/router";
+import { urlpatterns } from "./urls";
+import type { AppBindings, AppVars } from "./env";
 
-// Extract accumulated route types
-type AppRoutes = typeof _router.routeMap;
+export const router = createRouter<AppBindings>({}).routes(urlpatterns);
 
-// Register globally via module augmentation
 declare global {
-  namespace RSCRouter {
-    interface RegisteredRoutes extends AppRoutes {}
+  namespace Rango {
+    interface Env extends AppBindings {}
+    interface Vars extends AppVars {}
+    interface RegisteredRoutes extends typeof router.routeMap {}
   }
 }
+```
 
-export default _router;
-export const href = _router.href;
+### 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"],
+}
 ```
 
-## Route Definition with Type-Safe Keys
+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
-// routes/shop.ts
-import { route } from "rsc-router";
-
-export const shopRoutes = route({
-  "shop.index": "/",
-  "shop.products": "/products",
-  "shop.product": "/products/:slug",
-  "shop.cart": "/cart",
-  "shop.checkout": "/checkout/:step?",
-});
+// urls.tsx
+import { urls } from "@rangojs/router";
+
+export const urlpatterns = urls(({ path, layout }) => [
+  path("/", HomePage, { name: "home" }),
+  path("/products", ProductsPage, { name: "products" }),
+  path("/product/:slug", ProductPage, { name: "product" }),
+  path("/cart", CartPage, { name: "cart" }),
+  path("/checkout/:step?", CheckoutPage, { name: "checkout" }),
+]);
 
-// Type is inferred:
-// {
-//   "shop.index": "/",
-//   "shop.products": "/products",
-//   "shop.product": "/products/:slug",
-//   ...
-// }
+// Route names are inferred from the { name } option
 ```
 
 ## Type-Safe href()
 
-After registration, `href()` has full autocomplete:
+### Server: ctx.reverse with route names
+
+In route handlers, `ctx.reverse()` uses two namespaces:
+
+- **`.name`** — local route, resolved within the current `include()` scope
+- **`name`** — global route, from the named-routes definition
 
 ```typescript
-import { href } from "./router";
+import type { Handler } from "@rangojs/router";
+
+export const ProductHandler: Handler<"shop.product"> = (ctx) => {
+  ctx.reverse(".cart"); // Local: /shop/cart
+  ctx.reverse(".product", { slug: "widget" }); // Local: /shop/product/widget
+  ctx.reverse("blog.post", { slug: "1" }); // Global: /blog/1
+};
+```
 
-// Autocomplete shows all registered routes
-href("shop.index");                          // "/shop"
-href("shop.products");                       // "/shop/products"
-href("shop.product", { slug: "widget" });    // "/shop/products/widget"
+For type-safe local names, generate a route types file with `npx rango generate urls/shop.tsx`
+and pass it as the second generic to `Handler` or `Prerender`:
 
-// TypeScript errors for:
-href("invalid.route");                       // Error: not a valid route
-href("shop.product");                        // Error: missing required param 'slug'
-href("shop.product", { wrong: "param" });    // Error: 'wrong' not in params
+```typescript
+import type { Handler } from "@rangojs/router";
+import type { routes } from "./shop.gen.js";
+
+export const ProductHandler: Handler<"shop.product", routes> = (ctx) => {
+  ctx.reverse(".cart"); // Type-safe local name
+  ctx.reverse(".product", { slug: "widget" }); // Type-safe local with params
+  ctx.reverse("blog.post", { slug: "hi" }); // Type-safe global name
+};
 ```
 
-## Type-Safe Params in Handlers
+### Client: href + useHref
 
-Params are automatically typed based on route patterns:
+On the client, `href()` validates paths against registered route patterns at compile time:
 
 ```typescript
-// handlers/shop.tsx
-import { map } from "rsc-router/server";
-import type { shopRoutes } from "../routes/shop";
-
-export default map<typeof shopRoutes>(({ route }) => [
-  // ctx.params is typed as { slug: string }
-  route("shop.product", (ctx) => {
-    const { slug } = ctx.params;  // TypeScript knows slug exists
-    return <ProductPage slug={slug} />;
-  }),
-
-  // ctx.params is typed as { step?: string }
-  route("shop.checkout", (ctx) => {
-    const step = ctx.params.step ?? "shipping";  // Optional param
-    return <CheckoutPage step={step} />;
-  }),
-]);
+"use client";
+import { href, useHref, Link } from "@rangojs/router/client";
+
+// href() validates absolute paths via PatternToPath types
+href("/about");                        // Valid path
+href("/blog/hello");                   // Matches /blog/:slug
+
+// useHref() auto-prefixes with include() mount
+function ShopNav() {
+  const href = useHref();
+  return <Link to={href("/cart")}>Cart</Link>; // "/shop/cart"
+}
 ```
 
+`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 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"); // ResponseEnvelope<Product>
+```
+
+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
+`ResponseEnvelope<{ createdAt: string }>`, 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
 
 Define your app's environment for type-safe bindings and variables:
 
 ```typescript
 // env.ts
-import type { RouterEnv } from "rsc-router/server";
 
-// Cloudflare bindings
-interface AppBindings {
+// Cloudflare bindings — passed as TEnv to createRouter<TEnv>()
+export interface AppBindings {
   DB: D1Database;
   KV: KVNamespace;
   CACHE: KVNamespace;
   AI: Ai;
 }
 
-// Variables set by middleware (ctx.set/ctx.get)
-interface AppVariables {
+// Variables set by middleware — declared via global namespace augmentation
+export interface AppVariables {
   user?: { id: string; email: string; role: string };
   requestId?: string;
   permissions?: string[];
 }
-
-// Combined environment type
-export type AppEnv = RouterEnv<AppBindings, AppVariables>;
 ```
 
 ### Using Environment Types
 
 ```typescript
 // router.tsx
-import type { AppEnv } from "./env";
+import type { AppBindings, AppVariables } from "./env";
 
-const router = createRSCRouter<AppEnv>({ document: Document })
-  // ...
+const router = createRouter<AppBindings>({
+  document: Document,
+}).routes(urlpatterns);
+
+// Register bindings and variables globally for implicit typing
+declare global {
+  namespace Rango {
+    interface Env extends AppBindings {}
+    interface Vars extends AppVariables {}
+  }
+}
 
-// middleware - typed ctx.set/ctx.get
-const authMiddleware = async (ctx: MiddlewareContext<AppEnv>, next) => {
-  ctx.set("user", { id: "123", email: "user@example.com", role: "admin" });
+// middleware - typed via ctx.set / ctx.get
+import type { Middleware } from "@rangojs/router";
+
+export const authMiddleware: Middleware = async (ctx, next) => {
+  ctx.set("user", {
+    id: "123",
+    email: "user@example.com",
+    role: "admin",
+  });
   await next();
 };
 
-// handlers - typed access
-route("dashboard", (ctx) => {
-  const user = ctx.get("user");  // { id: string; email: string; role: string } | undefined
-  const db = ctx.env.Bindings.DB;  // D1Database
-  return <Dashboard user={user} />;
-});
-
 // loaders - typed context
-export const UserLoader = createLoader<AppEnv>(async (ctx) => {
-  const db = ctx.env.Bindings.DB;
-  const userId = ctx.get("user")?.id;
+export const UserLoader = createLoader(async (ctx) => {
+  const db = ctx.env.DB; // D1Database (plain bindings)
+  const userId = ctx.get("user")?.id; // from Rango.Vars
   return db.prepare("SELECT * FROM users WHERE id = ?").bind(userId).first();
 });
 ```
 
-## Global Type Registration
+## Global Environment Registration
 
 Register environment types globally for implicit typing:
 
 ```typescript
 // router.tsx
 declare global {
-  namespace RSCRouter {
-    interface RegisteredRoutes extends AppRoutes {}
-    interface Env extends AppEnv {}
+  namespace Rango {
+    interface Env extends AppBindings {}
+    interface Vars extends AppVariables {}
   }
 }
 ```
@@ -177,52 +377,132 @@ declare global {
 Now handlers have typed context without explicit imports:
 
 ```typescript
-// handlers/dashboard.tsx - no type imports needed
-export default map(({ route }) => [
-  route("dashboard", (ctx) => {
-    // ctx.get("user") is typed from global Env
-    // ctx.params is typed from global RegisteredRoutes
-    const user = ctx.get("user");
-    return <Dashboard user={user} />;
-  }),
-]);
+// In loaders
+export const DashboardLoader = createLoader(async (ctx) => {
+  // 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 };
+});
+```
+
+## Typed Search Params
+
+Add a `search` schema to `path()` options for type-safe query parameters:
+
+```typescript
+// Route definition with search schema
+path("/search", SearchPage, {
+  name: "search",
+  search: { q: "string", page: "number?", sort: "string?" },
+});
 ```
 
-## Route Key Conflict Detection
+### Handler with typed search params
 
-TypeScript detects duplicate keys with different URL patterns:
+`Handler<"name">` automatically resolves route params and search params from the
+global `GeneratedRouteMap` (the gen file). No explicit route map import needed:
 
 ```typescript
-// This causes a type error:
-const router = createRSCRouter<AppEnv>({ document: Document })
-  .routes({ index: "/" })
-  .map(() => import("./home"))
-  .routes({ index: "/other" })  // Error! 'index' already exists with different pattern
-  .map(() => import("./other"));
+// pages/search.tsx
+import type { Handler } from "@rangojs/router";
 
-// Error message:
-// Property 'map' does not exist on type '{
-//   __error: "Route key conflict! Keys [index] already exist with different URL patterns.";
-//   hint: "Use unique key names for each route definition.";
-// }'
+export const SearchPage: Handler<"search"> = (ctx) => {
+  // ctx.search is typed: { q: string; page?: number; sort?: string }
+  const { q, page, sort } = ctx.search;
+  return <SearchResults q={q} page={page} sort={sort} />;
+};
 ```
 
-### Avoiding Conflicts
+This avoids circular references because `Handler` defaults to `GeneratedRouteMap`
+(from `router.named-routes.gen.ts`) instead of `RegisteredRoutes` (which depends on `router.tsx`).
 
-Use namespaced keys:
+You can also pass an explicit route map for per-module isolation (opt-in,
+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
-// Good - unique keys
-export const homeRoutes = route({ "home.index": "/" });
-export const blogRoutes = route({ "blog.index": "/", "blog.post": "/:slug" });
+import type { Handler } from "@rangojs/router";
+import type { routes } from "./urls.gen.js";
 
-// router.tsx
-.routes(homeRoutes)
-.map(() => import("./home"))
-.routes("/blog", blogRoutes)  // Keys stay: blog.index, blog.post
-.map(() => import("./blog"))  // URLs become: /blog/, /blog/:slug
+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.
+
+### RouteSearchParams and RouteParams utility types
+
+Extract typed params by route name for use in component props, return types, or anywhere:
+
+```typescript
+import type { RouteSearchParams, RouteParams } from "@rangojs/router";
+
+// RouteSearchParams<"name"> resolves the search schema to a typed object
+type SP = RouteSearchParams<"search">;
+// { q: string | undefined; page?: number; sort?: string }
+
+// RouteParams<"name"> resolves URL params from the route pattern
+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">;
+}
+```
+
+Both default to the global route map (`RegisteredRoutes` or `GeneratedRouteMap`).
+Pass an explicit route map as the second type argument when needed:
+
+```typescript
+import type { routes } from "./urls.gen.js";
+
+type SP = RouteSearchParams<"search", routes>;
+type P = RouteParams<"blogPost", routes>;
+```
+
+### Generated route types
+
+In the generated `router.named-routes.gen.ts`, routes with search schemas
+use `{ path, search }` objects:
+
+```typescript
+// router.named-routes.gen.ts (auto-generated)
+export const NamedRoutes = {
+  "search.index": {
+    path: "/search",
+    search: { q: "string", page: "number?", sort: "string?" },
+  },
+  "home.index": "/", // No search schema -> plain string
+} 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:
@@ -237,52 +517,203 @@ export const ProductLoader = createLoader(async (ctx) => {
   };
 });
 
-// In handler - type is inferred
-route("shop.product", async (ctx) => {
-  const product = await ctx.use(ProductLoader);
+// In server component - type is inferred
+import { useLoader } from "@rangojs/router/client";
+
+async function ProductPage() {
+  const product = await useLoader(ProductLoader);
   // product: { id: string; name: string; price: number }
-  return <ProductPage product={product} />;
-});
+  return <h1>{product.name}</h1>;
+}
 
 // In client component - same type
+"use client";
+import { useLoader } from "@rangojs/router/client";
+
 function ProductPrice() {
   const { data } = useLoader(ProductLoader);
   // data: { id: string; name: string; price: number }
-  return <span>${data.price}</span>;
+  const product = data;
+  return <span>${product.price}</span>;
 }
 ```
 
-## Handle Type Safety
+## Typed Context Variables
 
-Handles have typed data:
+`createVar<T>()` creates a typed token for `ctx.set()`/`ctx.get()`, making
+handler-to-layout data contracts explicit and compile-time verified:
+
+```typescript
+import { createVar } from "@rangojs/router";
+
+// Define a typed token (shared between producer and consumer)
+interface PaginationData {
+  current: number;
+  total: number;
+  perPage: number;
+}
+export const Pagination = createVar<PaginationData>();
+
+// Non-cacheable var — reading inside cache() or "use cache" throws at runtime
+const Session = createVar<SessionData>({ cache: false });
+```
+
+`createVar` accepts an optional options object. The `cache` option (default
+`true`) controls whether the var's values can be read inside cache scopes.
+Write-level escalation is also supported: `ctx.set(Var, value, { cache: false })`
+marks a specific write as non-cacheable even if the var itself is cacheable.
+"Least cacheable wins" — if either says `cache: false`, the value throws on
+read inside `cache()` or `"use cache"`.
+
+### Producer (handler or middleware)
 
 ```typescript
-// handles/breadcrumbs.ts
-import { createHandle } from "rsc-router";
+import { Pagination } from "../vars/pagination.js";
+
+const ArticleList: Handler<"articles.list"> = async (ctx) => {
+  ctx.set(Pagination, {       // type-checked
+    current: 1,
+    total: 10,
+    perPage: 5,
+  });
+  return <Articles />;
+};
+```
 
-export const Breadcrumbs = createHandle<{ label: string; href: string }>();
+### Consumer (layout, parallel, or any context with get)
 
-// In handler - typed push
-route("shop.product", (ctx) => {
-  const push = ctx.use(Breadcrumbs);
-  push({ label: "Products", href: "/shop/products" });  // Typed
-  push({ wrong: "data" });  // Error!
+```typescript
+import { Pagination } from "../vars/pagination.js";
+
+export function PaginationLayout(ctx: any) {
+  const pagination = ctx.get(Pagination);  // typed as PaginationData | undefined
+  if (!pagination) return <Outlet />;
+  return <nav>Page {pagination.current} of {pagination.total}</nav>;
+}
+```
+
+### Why not just use Rango.Vars?
+
+`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
+scoped contract without polluting global types.
+
+Both approaches coexist: `ctx.get("user")` (global via Vars) and
+`ctx.get(Pagination)` (scoped via createVar) work side by side.
+
+## Handle Type Safety
+
+Handles have typed data:
+
+```typescript
+// Built-in Breadcrumbs handle — import from "@rangojs/router"
+import { Breadcrumbs } from "@rangojs/router";
+// Type: Handle<BreadcrumbItem, BreadcrumbItem[]>
+// BreadcrumbItem: { label: string; href: string; content?: ReactNode | Promise<ReactNode> }
+
+// In route handler — push is fully typed
+path("/shop/product/:slug", (ctx) => {
+  const breadcrumb = ctx.use(Breadcrumbs);
+  breadcrumb({ label: "Products", href: "/shop/products" });
   return <ProductPage />;
-});
+}, { name: "product" });
 
-// In client - typed array
+// In client — typed array
+import { useHandle, Breadcrumbs } from "@rangojs/router/client";
 function BreadcrumbNav() {
   const crumbs = useHandle(Breadcrumbs);
-  // crumbs: Array<{ label: string; href: string }>
+  // crumbs: BreadcrumbItem[]
 }
+
+// Custom handles also work the same way
+import { createHandle } from "@rangojs/router";
+export const PageTitle = createHandle<string, string>(
+  (segments) => segments.flat().at(-1) ?? "Default Title"
+);
 ```
 
+## Ref Prop Type Safety (Loaders & Handles)
+
+Loaders and handles can be passed as props from server to client components.
+Use `typeof` to get the full typed definition without manually specifying generics:
+
+```typescript
+// loaders.ts
+export const ProductLoader = createLoader(async (ctx) => {
+  return { product: await fetchProduct(ctx.params.slug) };
+});
+
+// Built-in Breadcrumbs — or any custom handle created with createHandle()
+```
+
+```tsx
+// Client component — typeof infers all generics
+"use client";
+import { useLoader, useHandle, type Breadcrumbs } from "@rangojs/router/client";
+import type { ProductLoader } from "../loaders";
+
+function MyComponent({
+  loader,
+  handle,
+}: {
+  loader: typeof ProductLoader; // LoaderDefinition<{ product: Product }>
+  handle: typeof Breadcrumbs; // Handle<{ label: string; href: string }>
+}) {
+  const { data } = useLoader(loader); // data is typed
+  const crumbs = useHandle(handle); // crumbs is typed array
+  // ...
+}
+```
+
+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
 // location-states.ts
-import { createLocationState } from "rsc-router";
+import { createLocationState } from "@rangojs/router";
 
+// All export patterns work: export const, const + export { X }, export { X as Y }
 export const ProductPreview = createLocationState<{
   name: string;
   price: number;
@@ -291,7 +722,7 @@ export const ProductPreview = createLocationState<{
 
 // Passing state through Link
 <Link
-  to={href("shop.product", { slug: "widget" })}
+  to={href("product", { slug: "widget" })}
   state={[ProductPreview({ name: "Widget", price: 99, image: "/img.jpg" })]}
 >
   View Product
@@ -309,44 +740,186 @@ function ProductHeader() {
 }
 ```
 
+## Multi-Project tsconfig Setup
+
+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)
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+  },
+}
+```
+
+```jsonc
+// apps/shop/tsconfig.json
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["src"],
+  "files": ["src/router.tsx"],
+}
+```
+
+```jsonc
+// apps/blog/tsconfig.json
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["src"],
+  "files": ["src/router.tsx"],
+}
+```
+
+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
 
 ```typescript
 // 1. env.ts - Environment types
-export type AppEnv = RouterEnv<AppBindings, AppVariables>;
+export interface AppBindings {
+  DB: D1Database;
+  KV: KVNamespace;
+}
 
-// 2. routes/*.ts - Route definitions
-export const shopRoutes = route({
-  "shop.index": "/",
-  "shop.product": "/products/:slug",
-});
+export interface AppVariables {
+  user?: { id: string; email: string; role: string };
+}
+
+// 2. urls.tsx - Route definitions with names
+import { urls } from "@rangojs/router";
 
-// 3. router.tsx - Registration
-const _router = createRSCRouter<AppEnv>({ document: Document })
-  .routes(shopRoutes)
-  .map(() => import("./handlers/shop"));
+export const urlpatterns = urls(({ path, layout, loader }) => [
+  path("/", HomePage, { name: "home" }),
 
-type AppRoutes = typeof _router.routeMap;
+  layout(<ShopLayout />, () => [
+    path("/shop", ShopIndex, { name: "shop" }),
+    path("/shop/product/:slug", ProductPage, { name: "product" }, () => [
+      loader(ProductLoader),
+    ]),
+  ]),
+]);
 
+// 3. router.tsx - Create router and export reverse
+const router = createRouter<AppBindings>({
+  document: Document,
+}).routes(urlpatterns);
+
+// Register bindings and variables globally for implicit typing
 declare global {
-  namespace RSCRouter {
-    interface RegisteredRoutes extends AppRoutes {}
-    interface Env extends AppEnv {}
+  namespace Rango {
+    interface Env extends AppBindings {}
+    interface Vars extends AppVariables {}
   }
 }
 
-export default _router;
-export const href = _router.href;
+export const reverse = router.reverse;
+export default router;
 
-// 4. handlers/*.tsx - Type-safe handlers
-export default map<typeof shopRoutes>(({ route }) => [
-  route("shop.product", (ctx) => {
-    // ctx.params: { slug: string }
-    // ctx.get("user"): User | undefined
-    // ctx.env.Bindings.DB: D1Database
-  }),
-]);
+// 4. Run `npx rango generate src/router.tsx` to generate
+//    router.named-routes.gen.ts (auto-registers GeneratedRouteMap globally).
+//    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 Rango.Vars)
+  // ctx.env.DB: D1Database  (plain bindings from Rango.Env)
+  return { product: await fetchProduct(ctx.params.slug) };
+});
+
+// 6. Server: ctx.reverse for named routes
+path("/product/:slug", (ctx) => {
+  return <Link to={ctx.reverse("shop")}>Back to Shop</Link>;
+}, { name: "product" })
 
-// 5. components/*.tsx - Type-safe client code
-<Link to={href("shop.product", { slug: "widget" })}>Widget</Link>
+// 7. Client: useHref for mounted paths, href for absolute
+"use client";
+import { useHref, href, Link } from "@rangojs/router/client";
+<Link to={href("/shop/product/widget")}>Widget</Link>
 ```