@rangojs/router 0.16.0 → 0.17.0

package/skills/typesafety/SKILL.md

@@ -1,17 +1,27 @@
 ---
 name: typesafety
-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.
+description: Set up type-safe route names, params, search params, response payloads, and environment types in @rangojs/router. Use when route or search params aren't typed, ctx.env or ctx.get() is untyped, TypeScript can't infer a loader's return type, or wiring RegisteredRoutes / the generated route map.
 argument-hint: [setup]
 ---
 
 # Type Safety Setup
 
-@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.
+This skill covers how route names, params, search params, response payloads,
+environment bindings, and context variables get their types. Use it when
+setting up a new app's type surfaces or when one of them resolves to
+`any`/`unknown`/`never` unexpectedly.
+
+What you lose without the setup:
+
+- `ctx.reverse()` accepts any name and `href()` any `/${string}` path, so a
+  typo 404s at runtime instead of failing to compile.
+- `Handler<"name">` is rejected (there is no generated map to look the name
+  up in), so `ctx.params`/`ctx.search` can't be inferred from the route.
+- `ctx.env` is `unknown` until `Rango.Env` is registered (every binding access
+  is a compile error), and string-key `ctx.get("key")` returns `any` until
+  `Rango.Vars` is registered (a typo'd key is silently accepted).
+- `Rango.PathResponse` resolves to `never` until `Rango.RegisteredRoutes` is
+  registered.
 
 Each topic's full setup, code, and caveats live in a companion file linked
 below. Read the one for your case.
@@ -48,5 +58,6 @@ below. Read the one for your case.
   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`).
+Related skills: `/links` (URL generation: `ctx.reverse`, `href`,
+`useReverse`, per-module `*.gen.ts`), `/response-routes` (response payload
+typing), `/api-client` (typed fetch client over `RouteResponse`).

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

@@ -27,6 +27,7 @@ export interface AppVariables {
 
 ```typescript
 // router.tsx
+import { createRouter } from "@rangojs/router";
 import type { AppBindings, AppVariables } from "./env";
 
 const router = createRouter<AppBindings>({
@@ -40,7 +41,9 @@ declare global {
     interface Vars extends AppVariables {}
   }
 }
+```
 
+```typescript
 // middleware - typed via ctx.set / ctx.get
 import type { Middleware } from "@rangojs/router";
 
@@ -52,38 +55,35 @@ export const authMiddleware: Middleware = async (ctx, next) => {
   });
   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:
+The `declare global` block above is what types the contexts. `createRouter<TEnv>()`
+types the router instance, but `urls()` modules, `Handler`, middleware, and
+response routes read `Rango.Env` / `Rango.Vars` — they cannot see the router's
+generic. Put the block in a file that is part of every TypeScript program that
+typechecks handlers (usually `router.tsx`, kept in via tsconfig `files`).
 
-```typescript
-// router.tsx
-declare global {
-  namespace Rango {
-    interface Env extends AppBindings {}
-    interface Vars extends AppVariables {}
-  }
-}
-```
+What each context sees:
 
-Now handlers have typed context without explicit imports:
+| Context                               | `ctx.env`                                 | `ctx.get("key")`                       |
+| ------------------------------------- | ----------------------------------------- | -------------------------------------- |
+| Handlers, middleware, response routes | `Rango.Env` (`unknown` if not registered) | `Rango.Vars` (`any` if not registered) |
+| Loaders (`createLoader`)              | `any` (not typed from `Rango.Env`)        | `Rango.Vars` (`any` if not registered) |
+
+An unregistered `Rango.Env` is deliberately `unknown`, so `ctx.env.DB` is a
+compile error rather than a silent `any`. An unregistered `Rango.Vars` falls
+back to `any` so string-key vars work with zero config.
 
 ```typescript
 // In loaders
+import { createLoader } from "@rangojs/router";
+
 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 };
+  const user = ctx.get("user"); // typed from global Rango.Vars
+  const db = ctx.env.DB as D1Database; // ctx.env is `any` in loaders
+  return { user, count: await countOrders(db, user?.id) };
 });
 ```
 
@@ -104,7 +104,10 @@ interface PaginationData {
 export const Pagination = createVar<PaginationData>();
 
 // Non-cacheable var — reading inside cache() or "use cache" throws at runtime
-const Session = createVar<SessionData>({ cache: false });
+interface SessionData {
+  userId: string;
+}
+export const Session = createVar<SessionData>({ cache: false });
 ```
 
 `createVar` accepts an optional options object. The `cache` option (default
@@ -114,9 +117,16 @@ 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)
+### Producer (handler, layout, or middleware)
+
+Write with `ctx.set()` from middleware, route handlers, or layout handlers;
+read with `ctx.get()` in the segments they wrap. A route handler runs before
+the layouts and parallels declared in its own use callback (handler-first), so
+those see the value; an outer layout wrapping the route renders first and
+does not. See `/route` for the full ordering.
 
 ```typescript
+import type { Handler } from "@rangojs/router";
 import { Pagination } from "../vars/pagination.js";
 
 const ArticleList: Handler<"articles.list"> = async (ctx) => {
@@ -132,15 +142,30 @@ const ArticleList: Handler<"articles.list"> = async (ctx) => {
 ### Consumer (layout, parallel, or any context with get)
 
 ```typescript
+import type { Handler } from "@rangojs/router";
+import { Outlet } from "@rangojs/router/client";
 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>;
-}
+// Mounted inside the producer's use callback:
+// path("/articles", ArticleList, { name: "articles.list" }, () => [layout(PaginationLayout)])
+export const PaginationLayout: Handler = (ctx) => {
+  const pagination = ctx.get(Pagination); // typed as PaginationData | undefined
+  return (
+    <>
+      <Outlet />
+      {pagination && (
+        <nav>
+          Page {pagination.current} of {pagination.total}
+        </nav>
+      )}
+    </>
+  );
+};
 ```
 
+Type the layout (`Handler`) rather than annotating `ctx: any`: with `any`,
+`ctx.get(Pagination)` is `any` too and the token contract is lost.
+
 ### Why not just use Rango.Vars?
 
 `Rango.Vars` (via global namespace augmentation) provides app-global typing for
@@ -154,7 +179,9 @@ Both approaches coexist: `ctx.get("user")` (global via Vars) and
 
 ## Handle Type Safety
 
-Handles have typed data:
+A handle is typed by two parameters: `Handle<TData, TAccumulated>`. `TData` is
+what each segment pushes; `TAccumulated` is what readers get after the collect
+function runs (default `TData[][]`, one array per segment).
 
 ```typescript
 // Built-in Breadcrumbs handle — import from "@rangojs/router"
@@ -168,18 +195,33 @@ path("/shop/product/:slug", (ctx) => {
   breadcrumb({ label: "Products", href: "/shop/products" });
   return <ProductPage />;
 }, { name: "product" });
+```
 
+```tsx
 // In client — typed array
+"use client";
 import { useHandle, Breadcrumbs } from "@rangojs/router/client";
+
 function BreadcrumbNav() {
-  const crumbs = useHandle(Breadcrumbs);
-  // crumbs: BreadcrumbItem[]
+  const crumbs = useHandle(Breadcrumbs); // crumbs: BreadcrumbItem[]
+  return (
+    <nav>
+      {crumbs.map((c) => (
+        <a key={c.href} href={c.href}>
+          {c.label}
+        </a>
+      ))}
+    </nav>
+  );
 }
+```
 
-// Custom handles also work the same way
+```typescript
+// Custom handle: give TAccumulated whenever collect changes the shape
 import { createHandle } from "@rangojs/router";
+
 export const PageTitle = createHandle<string, string>(
-  (segments) => segments.flat().at(-1) ?? "Default Title"
+  (segments) => segments.flat().at(-1) ?? "Default Title",
 );
 ```
 
@@ -190,11 +232,16 @@ Use `typeof` to get the full typed definition without manually specifying generi
 
 ```typescript
 // loaders.ts
+import { createLoader } from "@rangojs/router";
+
 export const ProductLoader = createLoader(async (ctx) => {
   return { product: await fetchProduct(ctx.params.slug) };
 });
 
-// Built-in Breadcrumbs — or any custom handle created with createHandle()
+// Server: pass the definitions as props
+path("/product/:slug", () => (
+  <MyComponent loader={ProductLoader} handle={Breadcrumbs} />
+), { name: "product" }, () => [loader(ProductLoader)]);
 ```
 
 ```tsx
@@ -208,20 +255,27 @@ function MyComponent({
   handle,
 }: {
   loader: typeof ProductLoader; // LoaderDefinition<{ product: Product }>
-  handle: typeof Breadcrumbs; // Handle<{ label: string; href: string }>
+  handle: typeof Breadcrumbs; // Handle<BreadcrumbItem, BreadcrumbItem[]>
 }) {
   const { data } = useLoader(loader); // data is typed
-  const crumbs = useHandle(handle); // crumbs is typed array
+  const crumbs = useHandle(handle); // crumbs: BreadcrumbItem[]
   // ...
 }
 ```
 
-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.
+Loader and handle definitions are plain `{ __brand, $$id }` objects — the
+loader function and the handle's collect function live in module-level
+registries keyed by `$$id` — so they cross the RSC boundary as-is and the
+hooks look the rest up by id. `useLoader()` still needs the loader registered
+on the route with `loader()` (or use `useFetchLoader()` for on-demand fetching).
 
 ## Location State Type Safety
 
+`createLocationState<T>()` returns a typed definition; the Vite plugin injects
+its key, so it must be exported from a module. Values are stored in
+`history.state`, so `T` must be structured-cloneable: functions, symbols,
+class constructors, React elements, and `unknown` are compile errors.
+
 ```typescript
 // location-states.ts
 import { createLocationState } from "@rangojs/router";
@@ -233,13 +287,28 @@ export const ProductPreview = createLocationState<{
   image: string;
 }>();
 
+// Flash state: cleared after the first read
+export const FlashMessage = createLocationState<{ text: string }>({
+  flash: true,
+});
+```
+
+```tsx
+"use client";
+import { Link, href, useLocationState } from "@rangojs/router/client";
+import { ProductPreview } from "./location-states";
+
 // Passing state through Link
-<Link
-  to={href("product", { slug: "widget" })}
-  state={[ProductPreview({ name: "Widget", price: 99, image: "/img.jpg" })]}
->
-  View Product
-</Link>
+function ProductCard() {
+  return (
+    <Link
+      to={href("/product/widget")}
+      state={[ProductPreview({ name: "Widget", price: 99, image: "/img.jpg" })]}
+    >
+      View Product
+    </Link>
+  );
+}
 
 // Reading state in component
 function ProductHeader() {
@@ -247,8 +316,18 @@ function ProductHeader() {
   // preview: { name: string; price: number; image: string } | undefined
 
   if (preview) {
-    return <h1>{preview.name} - ${preview.price}</h1>;
+    return (
+      <h1>
+        {preview.name} - ${preview.price}
+      </h1>
+    );
   }
   return <h1>Loading...</h1>;
 }
 ```
+
+Other entry points: pass a getter (`ProductPreview(() => ({ ... }))`) to compute
+the value at click time; `ctx.setLocationState(entry)` attaches state from a
+handler; `redirect(url, { state })` carries it through a redirect; and
+`ProductPreview.read()` / `.write(value)` / `.delete()` access the current
+history entry outside React (client-only, non-reactive).

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

@@ -5,23 +5,23 @@
 ```typescript
 // router.tsx
 import { createRouter } from "@rangojs/router";
+import { Document } from "./document";
 import { urlpatterns } from "./urls";
+import type { AppBindings } from "./env";
 
-const router = createRouter<AppBindings>({
+export 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.
+available globally — in practice, for `Rango.PathResponse`.
 
 - `GeneratedRouteMap` — auto-registered by `router.named-routes.gen.ts`
   Use for `Handler<"name">` (type annotation), `Prerender<"name">(...)` (function
@@ -95,19 +95,27 @@ instance in the same TypeScript program:
 }
 ```
 
-Then generate the route types from the router file:
+The Vite plugin writes `src/router.named-routes.gen.ts` (next to the router
+file) automatically: before the dev server starts, again when route files
+change, and during build. To produce it without starting Vite (a fresh clone,
+a CI typecheck step), run the CLI against 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
+The file augments `Rango.GeneratedRouteMap`. Keep it 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.
 
+CLI flags: the default mode fails (and writes nothing) when an `include()` cannot
+be resolved statically (factory functions, dynamic expressions); `--static`
+accepts partial output with warnings; `--runtime` uses Vite-based discovery for
+full coverage (needs `vite` and `@vitejs/plugin-rsc`, optional
+`--config <path>`). Passing a directory scans it for router and `urls()` files.
+
 ### Named Routes, `$$routeNames`, And `router.routeMap`
 
 There are two runtime/type surfaces with similar names:
@@ -299,7 +307,9 @@ export const urlpatterns = urls(({ path, layout, loader }) => [
 ]);
 
 // 3. router.tsx - Create router and export reverse
-const router = createRouter<AppBindings>({
+import { createRouter } from "@rangojs/router";
+
+export const router = createRouter<AppBindings>({
   document: Document,
 }).routes(urlpatterns);
 
@@ -312,10 +322,10 @@ declare global {
 }
 
 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).
+// 4. router.named-routes.gen.ts is written by the Vite plugin (dev + build);
+//    run `npx rango generate src/router.tsx` to produce it without Vite.
+//    It 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
@@ -323,10 +333,12 @@ export default router;
 //    router.routeMap metadata.
 
 // 5. loaders/*.ts - Type-safe loaders
+import { createLoader } from "@rangojs/router";
+
 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)
+  // ctx.params.slug: string | undefined  (a loader is not bound to one route)
+  // ctx.get("user"): AppVariables["user"]  (from Rango.Vars)
+  // ctx.env: any  (createLoader does not apply Rango.Env; cast if you need types)
   return { product: await fetchProduct(ctx.params.slug) };
 });
 

package/skills/typesafety/params-and-search.md

@@ -22,12 +22,17 @@ global `GeneratedRouteMap` (the gen file). No explicit route map import needed:
 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;
+  // ctx.search is typed: { q: string | undefined; page?: number; sort?: string }
+  const { q = "", page = 1, sort } = ctx.search;
   return <SearchResults q={q} page={page} sort={sort} />;
 };
 ```
 
+Required keys (no `?`) still resolve to `T | undefined` inside the handler:
+the schema tells callers (`ctx.reverse`, `useReverse`) what to send, but the
+server cannot trust the client to send it, so the handler must handle a
+missing value.
+
 This avoids circular references because `Handler` defaults to `GeneratedRouteMap`
 (from `router.named-routes.gen.ts`) instead of `RegisteredRoutes` (which depends on `router.tsx`).
 
@@ -48,8 +53,12 @@ Note the difference: `Handler<"search">` (no dot) resolves against the global
 `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.
+Values are automatically coerced from the query string: numbers accept finite
+decimal values (`"2"` becomes `2`; `"0x10"`, `"Infinity"` or an empty value are
+treated as missing), and a present boolean is `true` for `"true"`/`"1"` and
+`false` otherwise. Absent keys are omitted, required or not. Routes without a
+`search` schema get `ctx.search` as an empty object; read the raw query from
+`ctx.searchParams` (a `URLSearchParams`).
 
 ### RouteSearchParams and RouteParams utility types
 
@@ -104,12 +113,15 @@ export const NamedRoutes = {
 } as const;
 ```
 
-You never open a `.gen.ts` by hand. Treat the generated types as call-site
-honesty checks, not modules to read:
+You never edit a `.gen.ts` by hand. Treat the generated types as call-site
+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.
+- **You rarely need to import `router.named-routes.gen.ts`**, and you don't
+  need to reference `Rango.GeneratedRouteMap`. It is the whole-app manifest,
+  auto-wired globally — `Handler<"name">` and `ctx.reverse("name")` already
+  see it. Importing its `NamedRoutes` value is an escape hatch (global names
+  in `useReverse`, an absolute-path map for `/api-client`); on the client it
+  ships every route name and pattern in the app.
 - **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`.
@@ -119,35 +131,48 @@ smell — fix the call site (or regenerate), never edit the generated file.
 
 ## Loader Type Safety
 
-Loaders have typed return values:
+A loader's return type is inferred from its function and flows to every
+consumer. `createLoader` is not bound to one route, so `ctx.params` is
+`Record<string, string | undefined>`:
 
 ```typescript
 // loaders/product.ts
+import { createLoader } from "@rangojs/router";
+
 export const ProductLoader = createLoader(async (ctx) => {
   return {
-    id: ctx.params.slug,
+    id: ctx.params.slug ?? "",
     name: "Widget",
     price: 99,
   };
 });
+```
 
-// In server component - type is inferred
-import { useLoader } from "@rangojs/router/client";
+Server handler (escape hatch — reads the data in the handler itself):
 
-async function ProductPage() {
-  const product = await useLoader(ProductLoader);
+```typescript
+path("/product/:slug", async (ctx) => {
+  const product = await ctx.use(ProductLoader);
   // product: { id: string; name: string; price: number }
   return <h1>{product.name}</h1>;
-}
+}, { name: "product" }, () => [loader(ProductLoader)]);
+```
+
+Client component (the default consumption site):
 
-// In client component - same type
+```typescript
 "use client";
 import { useLoader } from "@rangojs/router/client";
+import { ProductLoader } from "../loaders/product";
 
 function ProductPrice() {
   const { data } = useLoader(ProductLoader);
   // data: { id: string; name: string; price: number }
-  const product = data;
-  return <span>${product.price}</span>;
+  return <span>${data.price}</span>;
 }
 ```
+
+`useLoader()` is a client hook — never call it in a server component.
+Client-side data is typed through `Rango.FlightSerialize<T>` (the RSC Flight
+boundary), so values Flight preserves (such as `Date`) keep their type. See
+`/loader` for when to use `ctx.use()` versus `useLoader()`.