@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

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>;
+}
+```

package/skills/typesafety/generated-files-and-cli.md

@@ -0,0 +1,342 @@
+# Generated Files and CLI Setup
+
+## Router Setup
+
+```typescript
+// router.tsx
+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.
+
+- `GeneratedRouteMap` — auto-registered by `router.named-routes.gen.ts`
+  Use for `Handler<"name">` (type annotation), `Prerender<"name">(...)` (function
+  call with type arg for param inference), server `ctx.reverse()`, and
+  named-route param/search inference.
+- `typeof router.routeMap` — the real merged route map from your router
+  instance, including response-route metadata such as `{ path, response }`.
+- `RegisteredRoutes` — manual global hook for exposing `typeof router.routeMap`
+  to 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` of a `typeof router.routeMap` alias | global | paths, params, **response payloads**     | the `Handler`/`Prerender` default (those read `GeneratedRouteMap` to avoid a `router.tsx` cycle) |
+
+Key consequence: `href()` and the ambient `Rango.Path` type are typed from
+whichever map is present — they prefer `RegisteredRoutes` when you wire it, otherwise fall back to
+the auto-generated `GeneratedRouteMap`, so **`rango generate` alone gives you
+path-checked `href()`** with no manual augmentation. Response and MIME payload
+inference is the exception: it comes only from `typeof router.routeMap` (via
+`RegisteredRoutes`), because `GeneratedRouteMap` carries paths + search but no
+payloads — so `Rango.PathResponse` resolves to `never` until you wire
+`RegisteredRoutes`.
+
+Recommended setup:
+
+```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);
+
+// The alias is required: an interface heritage clause cannot take a `typeof`
+// type query directly (TS1109).
+type AppRoutes = typeof router.routeMap;
+
+declare global {
+  namespace Rango {
+    interface Env extends AppBindings {}
+    interface Vars extends AppVars {}
+    interface RegisteredRoutes extends AppRoutes {}
+  }
+}
+```
+
+### Single-App Setup Checklist
+
+For one app, keep the ambient types, generated named-routes file, and router
+instance in the same TypeScript program:
+
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "strict": true,
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "noEmit": true,
+  },
+  "include": ["src"],
+  "files": ["src/router.tsx"],
+}
+```
+
+Then generate the route types from the router file:
+
+```bash
+npx rango generate src/router.tsx
+```
+
+This creates `src/router.named-routes.gen.ts`, which augments
+`Rango.GeneratedRouteMap`. Keep that generated file committed with the router
+source. The `files` entry keeps `router.tsx` in the program even when nothing
+imports it directly, so `Rango.Env`, `Rango.Vars`, and optional
+`Rango.RegisteredRoutes` augmentation are visible to handlers, loaders, actions,
+and client helpers.
+
+### Named Routes, `$$routeNames`, And `router.routeMap`
+
+There are two runtime/type surfaces with similar names:
+
+- `router.named-routes.gen.ts` exports `NamedRoutes` and augments
+  `Rango.GeneratedRouteMap`. The Vite plugin imports that file internally and
+  injects it as `$$routeNames` so `router.reverse` has the static route-name map.
+  App code should not pass or import `$$routeNames` directly.
+- `router.routeMap` is the public router instance property for type extraction.
+  Use `typeof router.routeMap` when augmenting `Rango.RegisteredRoutes` for
+  global response payload helpers such as `Rango.PathResponse`.
+
+Do not document or use a public `router.routeNames` API unless one is
+intentionally added. Today, the public extraction surface is `router.routeMap`;
+the generated file and `$$routeNames` are build machinery.
+
+### Typecheck cost when composing many include modules
+
+`urls()` infers a route registry from everything in its array — including the
+module types behind every `include()` thunk, recursively. In an app composing
+MANY include modules (dozens of groups, or factory-produced groups), that
+inference chain can explode: measured on a 26k-route app with 50 nested
+include modules, root inference hit 4.05M type instantiations / 20 s check
+time; the same app checks at ~140k / 3.6 s after widening.
+
+The fix is to annotate the intermediate modules' exports with the wide
+`UrlPatterns` type, which stops per-route literal types from propagating
+upward:
+
+```typescript
+import { urls, type UrlPatterns } from "@rangojs/router";
+
+export const shopPatterns: UrlPatterns<any> = urls(({ path }) => [
+  // ...hundreds of routes
+]);
+export default shopPatterns;
+```
+
+Nothing is lost: named-route typing (`Handler<"name">`, `ctx.reverse`,
+`href`) comes from the generated `router.named-routes.gen.ts`, not from the
+inferred `urls()` type. Keep full inference on modules whose
+`Rango.PathResponse` payloads you assert (e.g. `path.json` response routes);
+widen the big mechanical groups. Use `UrlPatterns<any>` (not
+`UrlPatterns<unknown>` — `unknown` env breaks handler assignability).
+Diagnose with `tsc --extendedDiagnostics` and watch the Instantiations count.
+
+## 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,
+);
+
+type ShopRoutes = typeof router.routeMap;
+
+declare global {
+  namespace Rango {
+    interface Env extends ShopEnv {}
+    interface RegisteredRoutes extends ShopRoutes {}
+  }
+}
+```
+
+## Complete Type-Safe Setup
+
+```typescript
+// 1. env.ts - Environment types
+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";
+
+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 - Create router and export reverse
+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 {}
+  }
+}
+
+export const reverse = router.reverse;
+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 is needed for named-route handlers,
+//    ctx.reverse, prerender, href(), or Rango.Path. Add `RegisteredRoutes
+//    extends AppRoutes` (an alias of 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" })
+
+// 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>
+```