@rangojs/router 0.0.0-experimental.3 → 0.0.0-experimental.31

package/skills/typesafety/SKILL.md

@@ -8,40 +8,61 @@ argument-hint: [setup]
 
 @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 "@rangojs/router/server";
+import { createRouter } from "@rangojs/router";
 import { urlpatterns } from "./urls";
 
-const router = createRSCRouter<AppEnv>({
+const router = createRouter<AppBindings>({
   document: Document,
-  urls: urlpatterns,
-});
+}).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.
+
+- `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 utilities like `href()`, `ValidPaths`, and `PathResponse`.
 
-// Extract route types for href()
-export const href = router.href;
+Recommended setup:
 
-// Register globally via module augmentation
-type AppRoutes = typeof router.routeMap;
+```typescript
+// router.tsx
+import { createRouter } from "@rangojs/router";
+import { urlpatterns } from "./urls";
+import type { AppBindings, AppVars } from "./env";
+
+export const router = createRouter<AppBindings>({}).routes(urlpatterns);
 
 declare global {
   namespace RSCRouter {
-    interface RegisteredRoutes extends AppRoutes {}
+    interface Env extends AppBindings {}
+    interface Vars extends AppVars {}
+    interface RegisteredRoutes extends typeof router.routeMap {}
   }
 }
-
-export default router;
 ```
 
 ## Route Definition with Type-Safe Names
 
 ```typescript
 // urls.tsx
-import { urls } from "@rangojs/router/server";
+import { urls } from "@rangojs/router";
 
 export const urlpatterns = urls(({ path, layout }) => [
   path("/", HomePage, { name: "home" }),
@@ -56,77 +77,131 @@ export const urlpatterns = urls(({ path, layout }) => [
 
 ## 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";
 
-// Autocomplete shows all registered route names
-href("home");                          // "/"
-href("products");                      // "/products"
-href("product", { slug: "widget" });   // "/product/widget"
+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
+};
+```
 
-// TypeScript errors for:
-href("invalid");                       // Error: not a valid route name
-href("product");                       // Error: missing required param 'slug'
-href("product", { wrong: "param" });   // Error: 'wrong' not in params
+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
+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
+};
 ```
 
+### Client: href + useHref
+
+On the client, `href()` validates paths against registered route patterns at compile time:
+
+```typescript
+"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 path-based response utilities read from `RegisteredRoutes`, so if
+you want them typed globally you should augment:
+
+```typescript
+declare global {
+  namespace RSCRouter {
+    interface RegisteredRoutes extends typeof router.routeMap {}
+  }
+}
+```
+
+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 "@rangojs/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
-interface AppVariables {
+// Variables set by middleware — declared via module 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>({
+const router = createRouter<AppBindings>({
   document: Document,
-  urls: urlpatterns,
-});
+}).routes(urlpatterns);
 
-// middleware - typed ctx.env.Variables
-import { createMiddleware } from "@rangojs/router/server";
+// Register bindings and variables globally for implicit typing
+declare global {
+  namespace RSCRouter {
+    interface Env extends AppBindings {}
+    interface Vars extends AppVariables {}
+  }
+}
 
-export const authMiddleware = createMiddleware(async (ctx, next) => {
-  ctx.env.Variables.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();
-});
+};
 
 // loaders - typed context
-export const UserLoader = createLoader("user", async (ctx) => {
-  const db = ctx.env.Bindings.DB;  // D1Database
-  const userId = ctx.env.Variables.user?.id;
+export const UserLoader = createLoader(async (ctx) => {
+  const db = ctx.env.DB; // D1Database (plain bindings)
+  const userId = ctx.get("user")?.id; // from RSCRouter.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:
 
@@ -134,8 +209,8 @@ Register environment types globally for implicit typing:
 // router.tsx
 declare global {
   namespace RSCRouter {
-    interface RegisteredRoutes extends AppRoutes {}
-    interface Env extends AppEnv {}
+    interface Env extends AppBindings {}
+    interface Vars extends AppVariables {}
   }
 }
 ```
@@ -144,21 +219,113 @@ Now handlers have typed context without explicit imports:
 
 ```typescript
 // In loaders
-export const DashboardLoader = createLoader("dashboard", async (ctx) => {
-  // ctx.env.Variables.user is typed from global Env
-  // ctx.params is typed from route pattern
-  const user = ctx.env.Variables.user;
+export const DashboardLoader = createLoader(async (ctx) => {
+  // ctx.env.DB is typed from global RSCRouter.Env
+  // ctx.get("user") is typed from global RSCRouter.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?" },
+});
+```
+
+### Handler with typed search params
+
+`Handler<"name">` automatically resolves route params and search params from the
+global `GeneratedRouteMap` (the gen file). No explicit route map import needed:
+
+```typescript
+// pages/search.tsx
+import type { Handler } from "@rangojs/router";
+
+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} />;
+};
+```
+
+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`):
+
+```typescript
+import type { Handler } from "@rangojs/router";
+import type { routes } from "./urls.gen.js";
+
+export const SearchPage: Handler<"search", routes> = (ctx) => { ... };
+```
+
+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 }
+
+// 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;
+```
+
 ## Loader Type Safety
 
 Loaders have typed return values:
 
 ```typescript
 // loaders/product.ts
-export const ProductLoader = createLoader("product", async (ctx) => {
+export const ProductLoader = createLoader(async (ctx) => {
   return {
     id: ctx.params.slug,
     name: "Widget",
@@ -167,7 +334,7 @@ export const ProductLoader = createLoader("product", async (ctx) => {
 });
 
 // In server component - type is inferred
-import { useLoader } from "@rangojs/router/server";
+import { useLoader } from "@rangojs/router/client";
 
 async function ProductPage() {
   const product = await useLoader(ProductLoader);
@@ -177,47 +344,144 @@ async function ProductPage() {
 
 // In client component - same type
 "use client";
-import { useLoaderData } from "@rangojs/router/client";
+import { useLoader } from "@rangojs/router/client";
 
 function ProductPrice() {
-  const { product } = useLoaderData(ProductLoader);
-  // product: { id: string; name: string; price: number }
+  const { data } = useLoader(ProductLoader);
+  // data: { id: string; name: string; price: number }
+  const product = data;
   return <span>${product.price}</span>;
 }
 ```
 
+## Typed Context Variables
+
+`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>();
+```
+
+### Producer (handler or middleware)
+
+```typescript
+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 />;
+};
+```
+
+### Consumer (layout, parallel, or any context with get)
+
+```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 RSCRouter.Vars?
+
+`RSCRouter.Vars` (via module 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
-// handles/breadcrumbs.ts
+// 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
+import { useHandle, Breadcrumbs } from "@rangojs/router/client";
+function BreadcrumbNav() {
+  const crumbs = useHandle(Breadcrumbs);
+  // 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"
+);
+```
 
-export const Breadcrumbs = createHandle<{ label: string; href: string }>();
+## Ref Prop Type Safety (Loaders & Handles)
 
-// In route definition - use handle() DSL
-import { urls } from "@rangojs/router/server";
+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:
 
-export const urlpatterns = urls(({ path, handle }) => [
-  path("/shop/product/:slug", ProductPage, { name: "product" }, () => [
-    handle(Breadcrumbs, { label: "Products", href: "/shop/products" }),
-  ]),
-]);
+```typescript
+// loaders.ts
+export const ProductLoader = createLoader(async (ctx) => {
+  return { product: await fetchProduct(ctx.params.slug) };
+});
 
-// In client - typed array
-function BreadcrumbNav() {
-  const crumbs = useHandle(Breadcrumbs);
-  // crumbs: Array<{ label: string; href: string }>
+// Built-in Breadcrumbs — or any custom handle created with createHandle()
+
+// 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.
+
 ## Location State Type Safety
 
 ```typescript
 // location-states.ts
 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;
@@ -244,14 +508,69 @@ 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`).
+
+```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"],
+}
+```
+
+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.
+
 ## Complete Type-Safe Setup
 
 ```typescript
 // 1. env.ts - Environment types
-export type AppEnv = RouterEnv<AppBindings, AppVariables>;
+export interface AppBindings {
+  DB: D1Database;
+  KV: KVNamespace;
+}
+
+export interface AppVariables {
+  user?: { id: string; email: string; role: string };
+}
 
 // 2. urls.tsx - Route definitions with names
-import { urls } from "@rangojs/router/server";
+import { urls } from "@rangojs/router";
 
 export const urlpatterns = urls(({ path, layout, loader }) => [
   path("/", HomePage, { name: "home" }),
@@ -264,32 +583,41 @@ export const urlpatterns = urls(({ path, layout, loader }) => [
   ]),
 ]);
 
-// 3. router.tsx - Registration
-const router = createRSCRouter<AppEnv>({
+// 3. router.tsx - Create router and export reverse
+const router = createRouter<AppBindings>({
   document: Document,
-  urls: urlpatterns,
-});
-
-type AppRoutes = typeof router.routeMap;
+}).routes(urlpatterns);
 
+// Register bindings and variables globally for implicit typing
 declare global {
   namespace RSCRouter {
-    interface RegisteredRoutes extends AppRoutes {}
-    interface Env extends AppEnv {}
+    interface Env extends AppBindings {}
+    interface Vars extends AppVariables {}
   }
 }
 
+export const reverse = router.reverse;
 export default router;
-export const href = router.href;
 
-// 4. loaders/*.ts - Type-safe loaders
-export const ProductLoader = createLoader("product", async (ctx) => {
+// 4. Run `npx rango generate src/router.tsx` to generate
+//    router.named-routes.gen.ts (auto-registers GeneratedRouteMap globally).
+//    No manual RegisteredRoutes declaration needed.
+
+// 5. loaders/*.ts - Type-safe loaders
+export const ProductLoader = createLoader(async (ctx) => {
   // ctx.params: { slug: string }
-  // ctx.env.Variables.user: User | undefined
-  // ctx.env.Bindings.DB: D1Database
+  // ctx.get("user"): User | undefined  (from RSCRouter.Vars)
+  // ctx.env.DB: D1Database  (plain bindings from RSCRouter.Env)
   return { product: await fetchProduct(ctx.params.slug) };
 });
 
-// 5. components/*.tsx - Type-safe client code
-<Link to={href("product", { slug: "widget" })}>Widget</Link>
+// 6. Server: ctx.reverse for named routes
+path("/product/:slug", (ctx) => {
+  return <Link to={ctx.reverse("shop")}>Back to Shop</Link>;
+}, { name: "product" })
+
+// 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>
 ```