@rangojs/router 0.0.0-experimental.9 → 0.0.0-experimental.91

package/skills/rango/SKILL.md

@@ -10,26 +10,30 @@ Django-inspired RSC router with composable URL patterns, type-safe href, and ser
 
 ## Skills
 
-| Skill | Description |
-|-------|-------------|
-| `/router-setup` | Create and configure the RSC router |
-| `/route` | Define routes with `urls()` and `path()` |
-| `/layout` | Layouts that wrap child routes |
-| `/loader` | Data loaders with `createLoader()` |
-| `/middleware` | Request processing and authentication |
-| `/intercept` | Modal/slide-over patterns for soft navigation |
-| `/parallel` | Multi-column layouts and sidebars |
-| `/caching` | Segment caching with memory or KV stores |
-| `/document-cache` | Edge caching with Cache-Control headers |
-| `/theme` | Light/dark mode with FOUC prevention |
-| `/links` | URL generation: ctx.reverse, href, useHref, useMount, scopedReverse |
-| `/hooks` | Client-side React hooks |
-| `/typesafety` | Type-safe routes, params, href, and environment |
-| `/host-router` | Multi-app host routing with domain/subdomain patterns |
-| `/tailwind` | Set up Tailwind CSS v4 with `?url` imports |
-| `/response-routes` | JSON/text/HTML/XML/stream endpoints with `path.json()`, `path.text()` |
-| `/mime-routes` | Content negotiation — same URL, different response types via Accept header |
-| `/fonts` | Load web fonts with preload hints |
+| Skill                   | Description                                                                |
+| ----------------------- | -------------------------------------------------------------------------- |
+| `/router-setup`         | Create and configure the RSC router                                        |
+| `/route`                | Define routes with `urls()` and `path()`                                   |
+| `/layout`               | Layouts that wrap child routes                                             |
+| `/loader`               | Data loaders with `createLoader()`                                         |
+| `/middleware`           | Request processing and authentication                                      |
+| `/intercept`            | Modal/slide-over patterns for soft navigation                              |
+| `/parallel`             | Multi-column layouts and sidebars                                          |
+| `/caching`              | Segment caching with memory or KV stores                                   |
+| `/use-cache`            | Function-level caching with `"use cache"` directive                        |
+| `/cache-guide`          | When to use `cache()` vs `"use cache"` — differences and decision guide    |
+| `/document-cache`       | Edge caching with Cache-Control headers                                    |
+| `/theme`                | Light/dark mode with FOUC prevention                                       |
+| `/links`                | URL generation: ctx.reverse, href, useHref, useMount, scopedReverse        |
+| `/hooks`                | Client-side React hooks                                                    |
+| `/typesafety`           | Type-safe routes, params, href, and environment                            |
+| `/host-router`          | Multi-app host routing with domain/subdomain patterns                      |
+| `/tailwind`             | Set up Tailwind CSS v4 with `?url` imports                                 |
+| `/response-routes`      | JSON/text/HTML/XML/stream endpoints with `path.json()`, `path.text()`      |
+| `/mime-routes`          | Content negotiation — same URL, different response types via Accept header |
+| `/fonts`                | Load web fonts with preload hints                                          |
+| `/migrate-nextjs`       | Migrate a Next.js App Router project to Rango                              |
+| `/migrate-react-router` | Migrate a React Router / Remix project to Rango                            |
 
 ## Quick Start
 
@@ -48,7 +52,69 @@ export const urlpatterns = urls(({ path, layout }) => [
 import { createRouter } from "@rangojs/router";
 import { urlpatterns } from "./urls";
 
-export default createRouter({ document: Document }).urls(urlpatterns);
+export default createRouter({ document: Document }).routes(urlpatterns);
 ```
 
 Use `/typesafety` for type-safe href and environment setup.
+
+## CLI: `npx rango generate`
+
+Single command to generate `.gen.ts` route type files. Auto-detects file type and
+generates the appropriate output.
+
+```bash
+# Single file
+npx rango generate src/urls.tsx
+
+# Multiple files
+npx rango generate src/router.tsx src/urls.tsx
+
+# Directory (recursive scan)
+npx rango generate src/
+
+# Mix of files and directories
+npx rango generate src/urls.tsx src/api/
+```
+
+### Auto-detection
+
+Each file is classified by its contents:
+
+| Contains       | Generated output                                                 |
+| -------------- | ---------------------------------------------------------------- |
+| `urls(`        | Per-module `*.gen.ts` with route names, patterns, params, search |
+| `createRouter` | Per-router `*.named-routes.gen.ts` with global route map         |
+| Both           | Both files                                                       |
+
+Directories are scanned recursively for `.ts`/`.tsx` files, skipping `node_modules`,
+dotfiles, and existing `.gen.` files.
+
+### Recursive includes
+
+The generator follows `include()` calls across files, resolving imports to build
+the full route tree. Circular includes are detected and warned about.
+
+### First-wins deduplication
+
+When a route name appears more than once, the first definition wins and duplicates
+are dropped with a warning. This applies only to the generated `.gen.ts` type files.
+Define the primary route before any fallback variant that reuses the same name.
+
+Content negotiation (see `/mime-routes`) is unaffected — negotiated routes use
+distinct names (e.g. `"product"` and `"productJson"`) and the Accept header
+dispatching happens at runtime in the trie, not in the type generator.
+
+### Limitations
+
+The CLI uses static source analysis (AST walking), not runtime execution. It cannot
+extract routes defined dynamically:
+
+- `Array.from()` or `.map()` generating path() calls
+- Conditional routes behind `import.meta.env` or feature flags
+- Routes computed from external data (databases, config files)
+- Template literal patterns with interpolated variables
+
+These routes are only discovered by the Vite plugin's runtime discovery during
+`pnpm dev` or `pnpm build`. The CLI-generated `.gen.ts` may have fewer routes
+than the runtime-generated version. During dev, the `preserveIfLarger` guard
+prevents the static parser from overwriting a larger runtime-discovered file.

package/skills/response-routes/SKILL.md

@@ -14,7 +14,7 @@ XML feeds, image proxies, and any route that returns a `Response` instead of Rea
 Inside any `urls()` callback, use `path.json()`, `path.text()`, or other tags alongside regular RSC routes:
 
 ```typescript
-import { urls, RouterError } from "@rangojs/router/server";
+import { urls, RouterError } from "@rangojs/router";
 
 export const urlpatterns = urls(({ path, layout, include }) => [
   // RSC routes (normal)
@@ -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
@@ -129,18 +157,24 @@ in a `ResponseEnvelope<T>` discriminated union:
 Throw `RouterError` to return structured error envelopes:
 
 ```typescript
-import { RouterError } from "@rangojs/router/server";
-
-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" });
+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" },
+);
 ```
 
 ### 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
@@ -188,7 +226,7 @@ if (isResponseError(result)) {
 Look up response type from a `path.json()` or `path.text()` module by route name:
 
 ```typescript
-import type { RouteResponse } from "@rangojs/router/server";
+import type { RouteResponse } from "@rangojs/router";
 
 // From the apiPatterns module (before include)
 type HealthData = RouteResponse<typeof apiPatterns, "health">;
@@ -269,25 +307,36 @@ A self-contained module with RSC pages + JSON APIs, mountable via `include()`:
 
 ```typescript
 // blog/api/urls.tsx
-import { urls, RouterError } from "@rangojs/router/server";
+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
-import { urls } from "@rangojs/router/server";
+import { urls } from "@rangojs/router";
 import { blogApiPatterns } from "./api/urls";
 
 export const blogPatterns = urls(({ path, include }) => [
@@ -299,7 +348,7 @@ export const blogPatterns = urls(({ path, include }) => [
 ]);
 
 // app/urls.tsx
-import { urls } from "@rangojs/router/server";
+import { urls } from "@rangojs/router";
 import { blogPatterns } from "./blog/urls";
 
 export const urlpatterns = urls(({ path, include }) => [
@@ -311,7 +360,7 @@ export const urlpatterns = urls(({ path, include }) => [
 ### Type safety after mounting
 
 ```typescript
-import type { RouteResponse } from "@rangojs/router/server";
+import type { RouteResponse } from "@rangojs/router";
 import type { PathResponse, ParamsFor } from "@rangojs/router/client";
 
 // Scoped (before mount) -- use the module directly
@@ -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
@@ -347,6 +400,14 @@ path("/:slug/likes", (ctx) => {
 Multiple response types can share the same URL pattern. See `/mime-routes` for the
 full content negotiation API (Accept header matching, Vary: Accept, multi-variant routes).
 
+## Long-Lived Responses (SSE / WebSocket)
+
+For Server-Sent Events (`path.stream`) and WebSocket upgrades (`path.any`
+returning a 101 / `webSocket` Response), see `/streams-and-websockets`.
+Upgrade responses flow through without reconstruction; `Vary` and
+`Server-Timing` are skipped, and stub headers are applied in place on a
+best-effort basis.
+
 ## How It Works
 
 1. `path.json()` tags the route at the trie level with a MIME type