@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.13221847

package/skills/response-routes/SKILL.md

@@ -22,43 +22,62 @@ export const urlpatterns = urls(({ path, layout, include }) => [
   path("/about", AboutPage, { name: "about" }),
 
   // JSON API route (inline, alongside RSC routes)
-  path.json("/api/status", (ctx) => ({
-    status: "ok",
-    timestamp: Date.now(),
-  }), { name: "status" }),
+  path.json(
+    "/api/status",
+    (ctx) => ({
+      status: "ok",
+      timestamp: Date.now(),
+    }),
+    { name: "status" },
+  ),
 
   // Text route
-  path.text("/robots.txt", (ctx) => {
-    return "User-agent: *\nAllow: /\nDisallow: /api/\n";
-  }, { name: "robots" }),
+  path.text(
+    "/robots.txt",
+    (ctx) => {
+      return "User-agent: *\nAllow: /\nDisallow: /api/\n";
+    },
+    { name: "robots" },
+  ),
 
   // Markdown route
-  path.md("/docs/:slug.md", (ctx) => {
-    return `# ${ctx.params.slug}\n\nDocumentation content here.`;
-  }, { name: "docs" }),
+  path.md(
+    "/docs/:slug.md",
+    (ctx) => {
+      return `# ${ctx.params.slug}\n\nDocumentation content here.`;
+    },
+    { name: "docs" },
+  ),
 
   // Response route (full control, returns Response directly)
-  path.image("/og/:slug.png", async (ctx) => {
-    const image = await generateOgImage(ctx.params.slug);
-    return new Response(image, {
-      headers: { "Content-Type": "image/png", "Cache-Control": "public, max-age=86400" },
-    });
-  }, { name: "ogImage" }),
+  path.image(
+    "/og/:slug.png",
+    async (ctx) => {
+      const image = await generateOgImage(ctx.params.slug);
+      return new Response(image, {
+        headers: {
+          "Content-Type": "image/png",
+          "Cache-Control": "public, max-age=86400",
+        },
+      });
+    },
+    { name: "ogImage" },
+  ),
 ]);
 ```
 
 ## Available Tags
 
-| Tag | Usage | Handler returns | Auto-wrap |
-|-----|-------|-----------------|-----------|
-| `json` | `path.json()` | plain object/array | `{ data: T }` envelope |
-| `text` | `path.text()` | string | text/plain Response |
-| `html` | `path.html()` | string | text/html Response |
-| `xml` | `path.xml()` | string | application/xml Response |
-| `md` | `path.md()` | string | text/markdown Response |
-| `image` | `path.image()` | Response | pass-through |
-| `stream` | `path.stream()` | Response | pass-through |
-| `any` | `path.any()` | Response | pass-through |
+| Tag      | Usage           | Handler returns    | Auto-wrap                |
+| -------- | --------------- | ------------------ | ------------------------ |
+| `json`   | `path.json()`   | plain object/array | `{ data: T }` envelope   |
+| `text`   | `path.text()`   | string             | text/plain Response      |
+| `html`   | `path.html()`   | string             | text/html Response       |
+| `xml`    | `path.xml()`    | string             | application/xml Response |
+| `md`     | `path.md()`     | string             | text/markdown Response   |
+| `image`  | `path.image()`  | Response           | pass-through             |
+| `stream` | `path.stream()` | Response           | pass-through             |
+| `any`    | `path.any()`    | Response           | pass-through             |
 
 ## ResponseHandlerContext
 
@@ -67,14 +86,15 @@ Response route handlers receive a lighter context (no `ctx.use()`, no `ctx.res`)
 ```typescript
 interface ResponseHandlerContext<TParams, TEnv> {
   request: Request;
-  params: TParams;             // Typed from URL pattern
-  env: Bindings;               // Extracted from RouterEnv (DB, KV, etc.)
+  params: TParams; // Typed from URL pattern
+  env: TEnv; // Plain bindings (DB, KV, etc.)
   searchParams: URLSearchParams;
   url: URL;
   pathname: string;
-  href: (name: string, params?: Record<string, string>) => string;
+  reverse: (name: string, params?: Record<string, string>) => string;
+  get: GetVariableFn; // Read middleware variables
   header: (name: string, value: string) => void;
-  setCookie: (name: string, value: string, options?: CookieOptions) => void;
+  // Use cookies().set(name, value, opts) for cookie mutations (standalone API)
 }
 ```
 
@@ -84,31 +104,39 @@ String-returning handlers (json, text, html, xml, md) can set custom headers and
 without constructing a full Response:
 
 ```typescript
-path.md("/docs/:slug.md", (ctx) => {
-  ctx.header("Cache-Control", "public, max-age=3600");
-  ctx.setCookie("last-doc", ctx.params.slug, { path: "/" });
-  return `# ${ctx.params.slug}\n\nContent here.`;
-}, { name: "docs" });
+path.md(
+  "/docs/:slug.md",
+  (ctx) => {
+    ctx.header("Cache-Control", "public, max-age=3600");
+    cookies().set("last-doc", ctx.params.slug, { path: "/" });
+    return `# ${ctx.params.slug}\n\nContent here.`;
+  },
+  { name: "docs" },
+);
 ```
 
-Headers and cookies set via `ctx.header()` / `ctx.setCookie()` are merged into the
+Headers set via `ctx.header()` and cookies set via `cookies().set()` are merged into the
 auto-wrapped Response. If the handler returns a `Response` directly, these are ignored
 (use the Response headers instead).
 
-### Environment Type Extraction
+### Environment Access
 
-`env` extracts bindings from `RouterEnv`, not the full env:
+`ctx.env` is always the plain bindings passed as TEnv to `createRouter<TEnv>()`:
 
 ```typescript
-type AppEnv = RouterEnv<{ DB: D1Database; KV: KVNamespace }, { user: User }>;
+// createRouter<{ DB: D1Database; KV: KVNamespace }>({ ... })
 
 // In a response handler:
-path.json("/api/data", (ctx) => {
-  ctx.env.DB;    // D1Database (bindings extracted)
-  ctx.env.KV;    // KVNamespace
-  // ctx.env.user  -- NOT available (variables are not on response ctx.env)
-  return { data: "ok" };
-}, { name: "data" });
+path.json(
+  "/api/data",
+  (ctx) => {
+    ctx.env.DB; // D1Database (plain bindings)
+    ctx.env.KV; // KVNamespace
+    // Variables are accessed via ctx.get("key") or ctx.get(ContextVar)
+    return { data: "ok" };
+  },
+  { name: "data" },
+);
 ```
 
 ## JSON Envelope
@@ -131,16 +159,22 @@ Throw `RouterError` to return structured error envelopes:
 ```typescript
 import { RouterError } from "@rangojs/router";
 
-path.json("/api/users/:id", (ctx) => {
-  const user = users.get(ctx.params.id);
-  if (!user) {
-    throw new RouterError("NOT_FOUND", `User ${ctx.params.id} not found`, { status: 404 });
-  }
-  if (!hasPermission(ctx)) {
-    throw new RouterError("FORBIDDEN", "Access denied", { status: 403 });
-  }
-  return user;
-}, { name: "user" });
+path.json(
+  "/api/users/:id",
+  (ctx) => {
+    const user = users.get(ctx.params.id);
+    if (!user) {
+      throw new RouterError("NOT_FOUND", `User ${ctx.params.id} not found`, {
+        status: 404,
+      });
+    }
+    if (!hasPermission(ctx)) {
+      throw new RouterError("FORBIDDEN", "Access denied", { status: 403 });
+    }
+    return user;
+  },
+  { name: "user" },
+);
 ```
 
 ### Returning Response Directly
@@ -148,15 +182,19 @@ path.json("/api/users/:id", (ctx) => {
 JSON handlers can return `Response` to bypass auto-wrap (custom status, headers, streaming):
 
 ```typescript
-path.json("/api/export", (ctx) => {
-  const csv = generateCsv();
-  return new Response(csv, {
-    headers: {
-      "Content-Type": "text/csv",
-      "Content-Disposition": "attachment; filename=export.csv",
-    },
-  });
-}, { name: "export" });
+path.json(
+  "/api/export",
+  (ctx) => {
+    const csv = generateCsv();
+    return new Response(csv, {
+      headers: {
+        "Content-Type": "text/csv",
+        "Content-Disposition": "attachment; filename=export.csv",
+      },
+    });
+  },
+  { name: "export" },
+);
 ```
 
 ## Client-Side Type Safety
@@ -272,18 +310,29 @@ A self-contained module with RSC pages + JSON APIs, mountable via `include()`:
 import { urls, RouterError } from "@rangojs/router";
 
 export const blogApiPatterns = urls(({ path }) => [
-  path.json("/stats", (ctx) => ({
-    views: 1200, visitors: 450,
-  }), { name: "stats" }),
-
-  path.json("/:slug/likes", (ctx) => ({
-    slug: ctx.params.slug,
-    count: 42,
-  }), { name: "likes" }),
-
-  path.json("/:slug/comments", (ctx) => ([
-    { id: "c1", body: "Great post", author: "alice" },
-  ]), { name: "comments" }),
+  path.json(
+    "/stats",
+    (ctx) => ({
+      views: 1200,
+      visitors: 450,
+    }),
+    { name: "stats" },
+  ),
+
+  path.json(
+    "/:slug/likes",
+    (ctx) => ({
+      slug: ctx.params.slug,
+      count: 42,
+    }),
+    { name: "likes" },
+  ),
+
+  path.json(
+    "/:slug/comments",
+    (ctx) => [{ id: "c1", body: "Great post", author: "alice" }],
+    { name: "comments" },
+  ),
 ]);
 
 // blog/urls.tsx
@@ -333,13 +382,17 @@ Response route handlers inside a mounted module can reference local names:
 
 ```typescript
 // Inside blogApiPatterns handler
-path("/:slug/likes", (ctx) => {
-  // ctx.reverse resolves names relative to the mount point
-  const commentsUrl = ctx.reverse("comments", { slug: ctx.params.slug });
-  // -> "/blog/api/my-post/comments"
-
-  return { slug: ctx.params.slug, count: 42, commentsUrl };
-}, { name: "likes" });
+path(
+  "/:slug/likes",
+  (ctx) => {
+    // ctx.reverse resolves names relative to the mount point
+    const commentsUrl = ctx.reverse("comments", { slug: ctx.params.slug });
+    // -> "/blog/api/my-post/comments"
+
+    return { slug: ctx.params.slug, count: 42, commentsUrl };
+  },
+  { name: "likes" },
+);
 ```
 
 ## Content Negotiation

package/skills/route/SKILL.md

@@ -74,19 +74,19 @@ path("/product/:slug", async (ctx) => {
 
 ```typescript
 path("/product/:slug", ProductPage, {
-  name: "product",  // Route name for href() and navigation
-})
+  name: "product", // Route name for href() and navigation
+});
 ```
 
 ### Typed Search Params
 
-Add a `search` schema to get typed `ctx.searchParams` instead of `URLSearchParams`:
+Add a `search` schema to get typed `ctx.search`:
 
 ```typescript
 path("/search", SearchPage, {
   name: "search",
   search: { q: "string", page: "number?", sort: "string?" },
-})
+});
 ```
 
 Use `Handler<"name">` for typed search params (resolves from the generated route map automatically):
@@ -95,23 +95,24 @@ Use `Handler<"name">` for typed search params (resolves from the generated route
 import type { Handler } from "@rangojs/router";
 
 export const SearchPage: Handler<"search"> = (ctx) => {
-  // ctx.searchParams is typed: { q: string; page?: number; sort?: string }
-  const { q, page, sort } = ctx.searchParams;
+  // ctx.search is typed: { q: string; page?: number; sort?: string }
+  const { q, page, sort } = ctx.search;
+  // ctx.searchParams is always URLSearchParams
   return <SearchResults q={q} page={page} sort={sort} />;
 };
 ```
 
 Supported types: `"string"`, `"number"`, `"boolean"`, with `?` suffix for optional.
-Required params default to zero values when missing (`""`, `0`, `false`).
-Optional params are omitted from the result when not in the query string.
+Missing params are `undefined` regardless of required/optional. The required/optional
+distinction is a consumer-facing contract (for `href()` and `reverse()` autocomplete).
 
 Use `RouteSearchParams<"name">` and `RouteParams<"name">` to extract types for props:
 
 ```typescript
 import type { RouteSearchParams, RouteParams } from "@rangojs/router";
 
-type SP = RouteSearchParams<"search">;   // { q: string; page?: number; sort?: string }
-type P = RouteParams<"blogPost">;        // { slug: string }
+type SP = RouteSearchParams<"search">; // { q: string; page?: number; sort?: string }
+type P = RouteParams<"blogPost">; // { slug: string }
 ```
 
 ## Route Children
@@ -126,19 +127,193 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 ])
 ```
 
+## Handler Data Ownership
+
+When a route has children (orphan layouts, parallels), the handler executes
+first. Use `ctx.set(key, value)` to share data with children, who read it
+via `ctx.get(key)`. Caching wraps all segments together, so either all run
+or none do.
+
+### Typed context variables with createVar
+
+Use `createVar<T>()` to create a typed token for `ctx.set()`/`ctx.get()`.
+The token is imported by both the handler (producer) and layout (consumer),
+making the data contract explicit and compile-time verified:
+
+```typescript
+import { createVar } from "@rangojs/router";
+import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+
+// Typed token -- shared between handler and layout
+interface DashboardData {
+  title: string;
+  stats: { views: number };
+}
+const Dashboard = createVar<DashboardData>();
+
+path("/dashboard/:id", async (ctx) => {
+  const data = await fetchDashboard(ctx.params.id);
+  ctx.set(Dashboard, data);   // type-checked
+  return <DashboardPage data={data} />;
+}, { name: "dashboard" }, () => [
+  layout((ctx) => {
+    const data = ctx.get(Dashboard);  // typed as DashboardData | undefined
+    return (
+      <div>
+        <h1>{data?.title}</h1>
+        <Outlet />
+        <ParallelOutlet name="@sidebar" />
+      </div>
+    );
+  }),
+  parallel({
+    "@sidebar": (ctx) => {
+      const data = ctx.get(Dashboard);
+      return <Sidebar stats={data?.stats} />;
+    },
+  }),
+])
+```
+
+String keys still work (`ctx.set("key", value)` / `ctx.get("key")`), but
+`createVar<T>()` is preferred for type safety.
+
+Only route handlers and middleware can call `ctx.set()`. Layouts, parallels,
+and intercepts can only read via `ctx.get()`.
+
+### Revalidation Contracts for Handler Data
+
+Handler-first guarantees apply within a single full render pass. For partial
+action revalidation, define named revalidation contracts and reuse them on both
+the producer route and the consumer child segments.
+
+```typescript
+// revalidation-contracts.ts
+export const revalidateCheckoutData = ({ actionId }) =>
+  actionId?.includes("src/actions/checkout.ts#") ?? false;
+
+path("/checkout", CheckoutPage, { name: "checkout" }, () => [
+  revalidate(revalidateCheckoutData), // producer (route handler) reruns
+  layout(CheckoutLayout, () => [
+    revalidate(revalidateCheckoutData), // consumer reruns
+    parallel({ "@summary": CheckoutSummary }, () => [
+      revalidate(revalidateCheckoutData),
+    ]),
+  ]),
+]);
+```
+
+If children depend on multiple upstream domains, compose multiple contracts on
+the same segment (`revalidateAuthData`, `revalidateCheckoutData`, and so on).
+
+For cleaner route trees, expose contract helpers and spread them:
+
+```typescript
+import { revalidate } from "@rangojs/router";
+
+export const revalidateCheckout = () => [revalidate(revalidateCheckoutData)];
+
+path("/checkout", CheckoutPage, { name: "checkout" }, () => [
+  revalidateCheckout(),
+  layout(CheckoutLayout, () => [revalidateCheckout()]),
+]);
+```
+
+For scope/revalidation guarantees and non-guarantees, see:
+[docs/execution-model.md](../../docs/internal/execution-model.md)
+
+## Redirects
+
+### Basic redirect
+
+```typescript
+import { redirect } from "@rangojs/router";
+
+path("/old-page", () => redirect("/new-page"), { name: "oldPage" });
+```
+
+### Redirect with custom status
+
+```typescript
+path("/moved", () => redirect("/new-location", 301), { name: "moved" });
+```
+
+### Redirect with location state
+
+Carry typed state through redirects (e.g. flash messages):
+
+```typescript
+import { redirect, createLocationState } from "@rangojs/router";
+
+export const FlashMessage = createLocationState<{ text: string }>({
+  flash: true,
+});
+
+path(
+  "/save",
+  (ctx) => {
+    // ... save logic
+    return redirect("/dashboard", {
+      state: [FlashMessage({ text: "Item saved!" })],
+    });
+  },
+  { name: "save" },
+);
+
+// With custom status + state
+path(
+  "/action",
+  (ctx) => {
+    return redirect("/target", {
+      status: 303,
+      state: [FlashMessage({ text: "Action complete" })],
+    });
+  },
+  { name: "action" },
+);
+```
+
+Read the state on the target page with `useLocationState(FlashMessage)`. The
+`{ flash: true }` option makes it auto-clear. Without `{ flash: true }`,
+state persists on back/forward. See `/hooks` for details.
+
+### ctx.setLocationState()
+
+Attach location state to any server response (not just redirects):
+
+```typescript
+path("/dashboard", (ctx) => {
+  ctx.setLocationState(ServerInfo({ data: "welcome" }));
+  return <Dashboard />;
+}, { name: "dashboard" })
+```
+
+State flows to the browser via the RSC payload and is merged into
+`history.pushState()`. Only works for SPA (partial) navigations.
+
 ## Handler Context
 
 Every handler receives a context object:
 
 ```typescript
 interface HandlerContext<TParams = {}, TEnv = DefaultEnv, TSearch = {}> {
-  params: TParams;           // URL parameters
-  request: Request;          // Original request
-  searchParams: URLSearchParams | ResolveSearchSchema<TSearch>;  // Query params (typed when search schema is set)
-  url: URL;                  // Parsed URL
-  env: TEnv;                 // Environment (bindings + variables)
-  use<T>(handle: Handle<T>): T;  // Access handles
-  reverse(name: string, params?: Record<string, string>, search?: Record<string, unknown>): string;  // URL generation
+  params: TParams; // URL parameters
+  request: Request; // Original request
+  searchParams: URLSearchParams; // Query params (always URLSearchParams)
+  search: {} | ResolveSearchSchema<TSearch>; // Typed search params (from search schema)
+  url: URL; // Parsed URL
+  env: TEnv; // Environment (bindings + variables)
+  set(key: string, value: any): void; // Set context variable (untyped string key)
+  set<T>(contextVar: ContextVar<T>, value: T): void; // Set typed context variable
+  get(key: string): any; // Read context variable (untyped string key)
+  get<T>(contextVar: ContextVar<T>): T | undefined; // Read typed context variable
+  use<T>(handle: Handle<T>): T; // Access handles
+  reverse(
+    name: string,
+    params?: Record<string, string>,
+    search?: Record<string, unknown>,
+  ): string; // URL generation
+  setLocationState(entries: LocationStateEntry[]): void; // Attach state to response
 }
 ```
 
@@ -152,8 +327,8 @@ path("/product/:slug", (ctx) => {
   // Access query params (untyped - use search schema for typed access)
   const tab = ctx.searchParams.get("tab");
 
-  // Access environment
-  const db = ctx.env.Bindings.DB;
+  // Access platform bindings
+  const db = ctx.env.DB;
 
   // Access handles
   const breadcrumbs = ctx.use(Breadcrumbs);
@@ -180,8 +355,7 @@ urls(({ path, layout }) => [
 ## Complete Example
 
 ```typescript
-import { urls } from "@rangojs/router";
-import { Breadcrumbs } from "./handles/breadcrumbs";
+import { urls, Breadcrumbs } from "@rangojs/router";
 
 export const urlpatterns = urls(({ path, layout, loader, loading }) => [
   // Simple route