@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.80daa23e

package/skills/typesafety/SKILL.md

@@ -1,394 +1,52 @@
 ---
 name: typesafety
-description: Set up type-safe routes, params, and environment types in @rangojs/router
+description: Set up type-safe routes, params, and environment types in @rangojs/router. Use when route or search params aren't typed, TypeScript can't infer a loader's return type, or wiring up typed environment bindings.
 argument-hint: [setup]
 ---
 
 # Type Safety Setup
 
-@rangojs/router provides end-to-end type safety for routes, parameters, and environment.
-
-## Router Setup
-
-```typescript
-// router.tsx
-import { createRouter } from "@rangojs/router";
-import { urlpatterns } from "./urls";
-
-const router = createRouter<AppEnv>({
-  document: Document,
-  urls: urlpatterns,
-});
-
-// Server-side named-route href (type-safe via routeMap)
-export const href = router.href;
-
-export default router;
-```
-
-## Route Definition with Type-Safe Names
-
-```typescript
-// 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" }),
-]);
-
-// Route names are inferred from the { name } option
-```
-
-## Type-Safe href()
-
-### Server: ctx.href + scopedHref
-
-In route handlers, use `scopedHref()` for local route name autocomplete:
-
-```typescript
-import { scopedHref } from "@rangojs/router";
-
-path("/product/:slug", (ctx) => {
-  const href = scopedHref<typeof shopPatterns>(ctx.href);
-
-  href("cart");                        // Type-safe local name
-  href("product", { slug: "widget" }); // Type-safe with params
-  href("blog.post");                   // Absolute names always allowed
-
-  return <ProductPage slug={ctx.params.slug} />;
-}, { name: "product" })
-```
-
-### 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"
-}
-```
-
-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";
-
-// Cloudflare bindings
-interface AppBindings {
-  DB: D1Database;
-  KV: KVNamespace;
-  CACHE: KVNamespace;
-  AI: Ai;
-}
-
-// Variables set by middleware
-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";
-
-const router = createRouter<AppEnv>({
-  document: Document,
-  urls: urlpatterns,
-});
-
-// middleware - typed ctx.env.Variables
-import { createMiddleware } from "@rangojs/router";
-
-export const authMiddleware = createMiddleware(async (ctx, next) => {
-  ctx.env.Variables.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;
-  return db.prepare("SELECT * FROM users WHERE id = ?").bind(userId).first();
-});
-```
-
-## Global Environment Registration
-
-Register environment types globally for implicit typing:
-
-```typescript
-// router.tsx
-declare global {
-  namespace RSCRouter {
-    interface Env extends AppEnv {}
-  }
-}
-```
-
-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;
-  return { user };
-});
-```
-
-## Loader Type Safety
-
-Loaders have typed return values:
-
-```typescript
-// loaders/product.ts
-export const ProductLoader = createLoader("product", async (ctx) => {
-  return {
-    id: ctx.params.slug,
-    name: "Widget",
-    price: 99,
-  };
-});
-
-// In server component - type is inferred
-import { useLoader } from "@rangojs/router";
-
-async function ProductPage() {
-  const product = await useLoader(ProductLoader);
-  // product: { id: string; name: string; price: number }
-  return <h1>{product.name}</h1>;
-}
-
-// In client component - same type
-"use client";
-import { useLoaderData } from "@rangojs/router/client";
-
-function ProductPrice() {
-  const { product } = useLoaderData(ProductLoader);
-  // product: { id: string; name: string; price: number }
-  return <span>${product.price}</span>;
-}
-```
-
-## Handle Type Safety
-
-Handles have typed data:
-
-```typescript
-// handles/breadcrumbs.ts
-import { createHandle } from "@rangojs/router";
-
-export const Breadcrumbs = createHandle<{ label: string; href: string }>();
-
-// In route definition - use handle() DSL
-import { urls } from "@rangojs/router";
-
-export const urlpatterns = urls(({ path, handle }) => [
-  path("/shop/product/:slug", ProductPage, { name: "product" }, () => [
-    handle(Breadcrumbs, { label: "Products", href: "/shop/products" }),
-  ]),
-]);
-
-// In client - typed array
-function BreadcrumbNav() {
-  const crumbs = useHandle(Breadcrumbs);
-  // crumbs: Array<{ label: string; href: string }>
-}
-```
-
-## 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) };
-});
-
-// handles.ts
-export const Breadcrumbs = createHandle<{ label: string; href: string }>();
-
-// Client component — typeof infers all generics
-"use client";
-import { useLoader, useHandle } from "@rangojs/router/client";
-import type { ProductLoader } from "../loaders";
-import type { Breadcrumbs } from "../handles";
-
-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";
-
-export const ProductPreview = createLocationState<{
-  name: string;
-  price: number;
-  image: string;
-}>();
-
-// Passing state through Link
-<Link
-  to={href("product", { slug: "widget" })}
-  state={[ProductPreview({ name: "Widget", price: 99, image: "/img.jpg" })]}
->
-  View Product
-</Link>
-
-// Reading state in component
-function ProductHeader() {
-  const preview = useLocationState(ProductPreview);
-  // preview: { name: string; price: number; image: string } | undefined
-
-  if (preview) {
-    return <h1>{preview.name} - ${preview.price}</h1>;
-  }
-  return <h1>Loading...</h1>;
-}
-```
-
-## 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 { ... } }`)
-is always included in the compilation even if nothing directly imports it. 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>;
-
-// 2. urls.tsx - Route definitions with names
-import { urls } from "@rangojs/router";
-
-export const urlpatterns = urls(({ path, layout, loader }) => [
-  path("/", HomePage, { name: "home" }),
-
-  layout(<ShopLayout />, () => [
-    path("/shop", ShopIndex, { name: "shop" }),
-    path("/shop/product/:slug", ProductPage, { name: "product" }, () => [
-      loader(ProductLoader),
-    ]),
-  ]),
-]);
-
-// 3. router.tsx - Registration
-const router = createRouter<AppEnv>({
-  document: Document,
-  urls: urlpatterns,
-});
-
-declare global {
-  namespace RSCRouter {
-    interface Env extends AppEnv {}
-  }
-}
-
-export default router;
-
-// 4. loaders/*.ts - Type-safe loaders
-export const ProductLoader = createLoader("product", async (ctx) => {
-  // ctx.params: { slug: string }
-  // ctx.env.Variables.user: User | undefined
-  // ctx.env.Bindings.DB: D1Database
-  return { product: await fetchProduct(ctx.params.slug) };
-});
-
-// 5. Server: ctx.href for named routes
-path("/product/:slug", (ctx) => {
-  const href = scopedHref<typeof urlpatterns>(ctx.href);
-  return <Link to={href("shop")}>Back to Shop</Link>;
-}, { name: "product" })
-
-// 6. 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>
-```
+@rangojs/router provides end-to-end type safety for routes, parameters, and
+environment. Without it: `ctx.reverse()`/`href()` accept any string (typos
+404 at runtime, not compile time), `ctx.search`/`ctx.params` fall back to
+loose `Record<string, string>`, and `ctx.env`/`ctx.get()` are untyped so a
+missing binding surfaces as `undefined` in production instead of a build
+error.
+
+Each topic's full setup, code, and caveats live in a companion file linked
+below. Read the one for your case.
+
+## Routing table
+
+| I need...                                                                                                            | Topic                                  | File                                                           |
+| -------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | -------------------------------------------------------------- |
+| Named routes, `.gen.ts` surfaces, `RegisteredRoutes` vs `GeneratedRouteMap`, tsconfig checklist                      | Router setup & generated route types   | [`./generated-files-and-cli.md`](./generated-files-and-cli.md) |
+| Type-safe `path()` names, `ctx.reverse()`, `href()`/`useHref()`, `Rango.PathResponse`, stable `path#export` identity | Route & href typing                    | [`./route-types.md`](./route-types.md)                         |
+| Typed `search` schemas, `RouteSearchParams`/`RouteParams`, loader return types                                       | Search params & loader typing          | [`./params-and-search.md`](./params-and-search.md)             |
+| Typed `env`/bindings, `Rango.Vars`, `createVar()`, handle typing, loader/handle ref props, location state typing     | Environment, context, and state typing | [`./env-and-bindings.md`](./env-and-bindings.md)               |
+| Multi-app / multi-router tsconfig setup, avoiding `GeneratedRouteMap` collisions                                     | Multi-project setup & full walkthrough | [`./generated-files-and-cli.md`](./generated-files-and-cli.md) |
+| Slow typecheck with many `include()` modules (instantiation blowup), wide `UrlPatterns<any>` annotations             | Typecheck cost at route scale          | [`./generated-files-and-cli.md`](./generated-files-and-cli.md) |
+
+## Companion files
+
+- [`./generated-files-and-cli.md`](./generated-files-and-cli.md) — Router
+  setup, the three route-typing surfaces (`GeneratedRouteMap` /
+  per-module `routes` / `RegisteredRoutes`), the single-app setup checklist,
+  `$$routeNames` vs `router.routeMap`, multi-project tsconfig setup, and the
+  complete end-to-end setup walkthrough.
+- [`./route-types.md`](./route-types.md) — Type-safe route names, server
+  `ctx.reverse()`, client `href()`/`useHref()`, `Rango.Path`,
+  `Rango.PathResponse` (incl. overriding JSON/Flight serialization), and the
+  `path#export` stable identity scheme shared by loaders/handles/cached
+  functions/actions.
+- [`./params-and-search.md`](./params-and-search.md) — Typed `search`
+  schemas on `path()`, `Handler<"name">` param/search inference,
+  `RouteSearchParams`/`RouteParams` utility types, and loader return-type
+  inference.
+- [`./env-and-bindings.md`](./env-and-bindings.md) — Environment bindings
+  (`TEnv`) and `Rango.Env`/`Rango.Vars` registration, `createVar<T>()`
+  scoped context tokens, handle typing, passing loaders/handles as typed
+  props, and location state typing.
+
+See `/links` for the full URL generation guide (per-module `*.gen.ts`,
+`useReverse`).

package/skills/typesafety/env-and-bindings.md

@@ -0,0 +1,254 @@
+# Environment, Context, and State Types
+
+## Environment Type Setup
+
+Define your app's environment for type-safe bindings and variables:
+
+```typescript
+// env.ts
+
+// Cloudflare bindings — passed as TEnv to createRouter<TEnv>()
+export interface AppBindings {
+  DB: D1Database;
+  KV: KVNamespace;
+  CACHE: KVNamespace;
+  AI: Ai;
+}
+
+// Variables set by middleware — declared via global namespace augmentation
+export interface AppVariables {
+  user?: { id: string; email: string; role: string };
+  requestId?: string;
+  permissions?: string[];
+}
+```
+
+### Using Environment Types
+
+```typescript
+// router.tsx
+import type { AppBindings, AppVariables } from "./env";
+
+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 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(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 Environment Registration
+
+Register environment types globally for implicit typing:
+
+```typescript
+// router.tsx
+declare global {
+  namespace Rango {
+    interface Env extends AppBindings {}
+    interface Vars extends AppVariables {}
+  }
+}
+```
+
+Now handlers have typed context without explicit imports:
+
+```typescript
+// 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 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>();
+
+// 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
+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 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
+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"
+);
+```
+
+## 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.
+
+## 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;
+  image: string;
+}>();
+
+// Passing state through Link
+<Link
+  to={href("product", { slug: "widget" })}
+  state={[ProductPreview({ name: "Widget", price: 99, image: "/img.jpg" })]}
+>
+  View Product
+</Link>
+
+// Reading state in component
+function ProductHeader() {
+  const preview = useLocationState(ProductPreview);
+  // preview: { name: string; price: number; image: string } | undefined
+
+  if (preview) {
+    return <h1>{preview.name} - ${preview.price}</h1>;
+  }
+  return <h1>Loading...</h1>;
+}
+```