@rangojs/router 0.15.1 → 0.17.0

package/skills/rango/SKILL.md

@@ -33,7 +33,7 @@ with the shape, then pick a primitive.
   index by tag and invalidate via `updateTag(...tags)` (awaitable, read-your-own-writes)
   or `revalidateTag(...tags)` (background, non-blocking).
 - **Type-safe end to end** — route names, params, search schemas, loader return
-  types, context vars, and `href` / `reverse` are checked at compile time
+  types, context vars, and `href()` / `ctx.reverse()` are checked at compile time
   (`/typesafety`).
 - **See where time goes** — turn on `debugPerformance` early (router option, or
   `ctx.debugPerformance()` in middleware for per-request opt-in). It prints a
@@ -42,7 +42,9 @@ with the shape, then pick a primitive.
   console, OpenTelemetry, or custom sink. See `/observability`.
 
 Most features are **just-in-time**: the core is `urls()`, `path()`, `layout()`,
-`include()`, and `reverse()`. Caching, parallel routes, intercepts, prerender,
+`include()`, and URL generation (`ctx.reverse()` on the server, `href()` /
+`useReverse()` on the client; there is no standalone `reverse()` export — see
+`/links`). Caching, parallel routes, intercepts, prerender,
 i18n, themes, and the rest are opt-in — reach for them when a requirement
 appears, not up front.
 
@@ -128,12 +130,12 @@ stated, greppable contract.
   freezes into the shared artifact (a documented footgun; see `/caching` →
   "Cache purity & tainted objects"). Client-side consumption (`useLoader` in
   a `"use client"` component) is the LIVE lane. DSL `loader()` segments
-  follow their lane machinery (live under renderable `loading()`, bake
-  otherwise). Pinned by semantic-matrix row PPR3.
+  follow their PPR lane (only `ssr: false` bakes; see `/ppr` → The loader
+  lane rule). Pinned by semantic-matrix row PPR3.
 - Inside `"use cache"`: `cookies()`/`headers()` and `ctx` side-effects
   (`set`/`header`/`setTheme`/`onResponse`/`setLocationState`) throw; `ctx.use(Handle)`
-  is captured on miss and replayed on hit. (The non-cacheable read guard is a
-  separate `cache()`-boundary check — see the correctness bullet below.)
+  is captured on miss and replayed on hit. A non-cacheable variable read
+  (`createVar({ cache: false })`) throws too — see the correctness bullet below.
 - One identity `path#export` (`functionId`/`$$id`/`actionId`); one store. Freshness
   is TTL/SWR expiry plus tag-based invalidation: tag via `cache({ tags })` /
   `cacheTag(...tags)`, then `updateTag(...tags)` (awaitable) or `revalidateTag(...tags)`
@@ -142,7 +144,7 @@ stated, greppable contract.
 - Caches are correctness-first: persistent store keys are version-segmented (no
   cross-deploy drift), the forward/back cache is mutation-aware, and
   `createVar({ cache: false })` throws on a **direct** read inside a `cache()`
-  boundary (a deliberately non-propagating guard). See `/cache-guide` →
+  boundary or a `"use cache"` function (a deliberately non-propagating guard). See `/cache-guide` →
   "Correctness & invalidation".
 - Nested caches: the outer cache window bounds the inner — an inner shorter TTL
   only applies when the enclosing cache recomputes; put a value in a loader if it
@@ -178,9 +180,10 @@ See `/cache-guide` for the axis-1 decision guide, `/loader` and `/route` for
 export const urlpatterns = urls(({ path, layout, loader, loading, cache, revalidate }) => [
   layout(<ShopLayout />, () => [                 // structure: wraps children
     loader(CartLoader, () => [                   // config: live data
-      // partial-render axis: re-run on cart actions, defer otherwise.
+      // partial-render axis: after an action, re-run only for cart actions;
+      // on navigation, undefined keeps the default.
       // ctx.isAction() matches by reference (rename-safe), not by string.
-      revalidate((ctx) => ctx.isAction(CartActions) || undefined),
+      revalidate((ctx) => (ctx.isAction() ? ctx.isAction(CartActions) : undefined)),
     ]),
     path("/shop/:slug", ProductPage, { name: "product" }, () => [  // structure: leaf
       loader(ProductLoader, () => [cache({ ttl: 60 })]),  // config: cache loader DATA
@@ -201,17 +204,29 @@ The predicate arg carries the action's full context, not just its identity. Matc
 _which_ action with `ctx.isAction(addToCart)` (rename-safe); branch on _what it
 returned_ with `ctx.actionResult` — the value your `"use server"` function
 returned, for outcome-conditional revalidation. The arg also exposes `actionId`
-(raw `path#export`), `actionUrl`, `formData`, `method`, and `stale` (cross-tab
-`_rsc_stale` signal). All are `undefined` on plain navigation (no action).
-
-Two idioms, picked by what an _unrelated_ action should do. `ctx.isAction()`
-returns a raw boolean, so combine it with `|| undefined` to **defer** ("mine,
-else let the default decide": `ctx.isAction(CartActions) || undefined`) or leave
-it bare to **suppress** ("mine only": `ctx.isAction(CartActions)`). Prefer the
-defer form unless a sibling segment must own the unrelated-action decision.
+(raw `path#export`), `actionUrl`, `formData` (form-based actions only), `method`,
+and `stale` (the `_rsc_stale` signal that an action ran in this or another tab).
+`actionId`, `actionUrl`, `actionResult`, and `formData` are `undefined` on plain
+navigation; `method` is `"GET"` there and `"POST"` for an action. Call
+`ctx.isAction()` with no arguments to ask "was this any action?".
+
+`ctx.isAction()` returns a raw boolean. Pick the idiom by what the segment's
+default already does: after an action, loaders, the route, and segments inside
+the `path()` re-run; layouts and parallels above the route are skipped.
+
+- **Add a signal** where the default skips: `ctx.isAction(CartActions) || undefined`
+  on a parent layout re-renders it after cart actions and defers otherwise. On a
+  loader or route segment it changes nothing.
+- **Narrow after actions** where the default re-runs:
+  `ctx.isAction() ? ctx.isAction(CartActions) : undefined` re-runs only for cart
+  actions and keeps the navigation default (params or search changed).
+- **Avoid bare `ctx.isAction(CartActions)`.** It is a hard `false` on navigation
+  too, so a loader stops refetching when params change, and it ends the chain for
+  any later revalidator on the segment.
 
 ```ts
-// re-render only when checkout actually succeeded; defer otherwise
+// on a parent layout (skipped after actions by default): also re-render when
+// checkout succeeded; defer to the default otherwise
 revalidate((ctx) => (ctx.isAction(checkout) && ctx.actionResult?.ok) || undefined),
 ```
 
@@ -326,6 +341,8 @@ Grouped by concern — read when you need to…
 ```typescript
 // urls.tsx
 import { urls } from "@rangojs/router";
+import { RootLayout } from "./layouts/root"; // renders <Outlet />
+import { HomePage, AboutPage } from "./pages";
 
 export const urlpatterns = urls(({ path, layout }) => [
   layout(RootLayout, () => [
@@ -336,12 +353,15 @@ export const urlpatterns = urls(({ path, layout }) => [
 
 // router.tsx
 import { createRouter } from "@rangojs/router";
+import { Document } from "./document"; // <html>/<head>/<body> shell
 import { urlpatterns } from "./urls";
 
-export default createRouter({ document: Document }).routes(urlpatterns);
+export const router = createRouter({ document: Document, urls: urlpatterns });
 ```
 
-Use `/typesafety` for type-safe href and environment setup.
+`createRouter({ ... }).routes(urlpatterns)` is equivalent to passing `urls`.
+See `/router-setup` for the Document component and router options, and
+`/typesafety` for type-safe href and environment setup.
 
 ## CLI: `npx rango generate`
 
@@ -362,27 +382,37 @@ npx rango generate src/
 npx rango generate src/urls.tsx src/api/
 ```
 
+Three modes:
+
+| Flag        | Behavior                                                                                                                  |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------- |
+| (none)      | Static parser. Exits with an error, writing nothing, if an `include()` can't be resolved statically (factory or dynamic). |
+| `--static`  | Static parser, but writes partial output and prints the unresolvable includes as warnings.                                |
+| `--runtime` | Vite-based runtime discovery (full coverage; needs `vite` and `@vitejs/plugin-rsc`). `--config <path>` picks the config.  |
+
 ### 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                                                       |
+| Contains                 | Generated output                                                 |
+| ------------------------ | ---------------------------------------------------------------- |
+| `urls(` or `clientUrls(` | 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.
+Directories are scanned recursively for `.ts`/`.tsx`/`.js`/`.jsx` files, skipping
+`node_modules`, `dist`, `build`, `coverage`, dot-directories, and existing
+`.gen.` files.
 
 > The two generated files are **not interchangeable surfaces**.
 > `router.named-routes.gen.ts` augments the global `GeneratedRouteMap` for
 > named-route typing (`Handler<"name">`, `ctx.reverse("name")`, prerender).
 > Per-module `*.gen.ts` exports a local `routes` map for `useReverse(routes)`
 > and explicit local handler typing (`Handler<".name", routes>`). Neither
-> carries response payloads — response/MIME payload inference comes from
-> `typeof router.routeMap` via `RegisteredRoutes`, not `*.named-routes.gen.ts`.
-> See `/typesafety` for the full surface breakdown.
+> carries response payloads: `RouteResponse<typeof patterns, "name">` reads
+> them from the `urls()` value directly, and `Rango.PathResponse` reads them from
+> `RegisteredRoutes` (`typeof router.routeMap`). See `/typesafety` for the full
+> surface breakdown.
 
 ### Recursive includes
 
@@ -413,7 +443,8 @@ extract routes defined dynamically:
 - 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.
+These routes are only discovered at runtime: by the Vite plugin during
+`pnpm dev` / `pnpm build`, or by `rango generate --runtime`. A statically
+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/react-compiler/SKILL.md

@@ -74,7 +74,7 @@ export default defineConfig({
     react({ compiler: true }),
     rango({ preset: "cloudflare" }),
     cloudflare({
-      /* ... */
+      viteEnvironment: { name: "rsc", childEnvironments: ["ssr"] },
     }),
   ],
 });
@@ -200,7 +200,8 @@ import babel from "@rolldown/plugin-babel";
 ## Reference
 
 A worked, tested wiring (dev + production e2e markers, incl. the client-only
-contract and the Fast Refresh check) lives in the `@rangojs/router` repository —
-not shipped in this package: `docs/react-compiler.md` and the
-`react-compiler.test.ts` files under `e2e/e2e-basic`, `tests/cloudflare-basic`,
-and `tests/vite-rsc-demo`.
+contract and the Fast Refresh check) lives in the `@rangojs/router` repository,
+not shipped in this package: `packages/rangojs-router/docs/react-compiler.md`,
+`packages/rangojs-router/e2e/react-compiler.test.ts` (covers the
+`e2e/e2e-basic` app), `tests/cloudflare-basic/e2e/react-compiler.test.ts`, and
+`tests/vite-rsc-demo/e2e/react-compiler.test.ts`.

package/skills/response-routes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: response-routes
-description: Response routes (path.json, path.text, etc.) for non-RSC endpoints with typed responses. Use when building a JSON/text API endpoint alongside your pages, or asking how to return raw JSON instead of RSC from a route.
+description: Response routes (path.json, path.text, etc.) for non-RSC endpoints with typed responses. Use when building a JSON/text API endpoint alongside your pages, asking how to return raw JSON instead of RSC from a route, or protecting a state-changing endpoint from CSRF.
 argument-hint: [json|text|html|xml|md|image|stream]
 ---
 
@@ -8,13 +8,15 @@ argument-hint: [json|text|html|xml|md|image|stream]
 
 Response routes skip the RSC pipeline entirely. Use them for JSON APIs, plain text endpoints,
 XML feeds, image proxies, and any route that returns a `Response` instead of React components.
+Serving several representations from one URL is `/mime-routes`; a typed client for
+calling your JSON routes is `/api-client`.
 
 ## Route-Level Tags: path.json(), path.text(), etc.
 
-Inside any `urls()` callback, use `path.json()`, `path.text()`, or other tags alongside regular RSC routes:
+Inside any `urls()` callback, use `path.json()`, `path.text()`, or other tags alongside regular RSC routes. Each takes `(pattern, handler, options?, use?)` like `path()`:
 
 ```typescript
-import { urls, RouterError } from "@rangojs/router";
+import { urls } from "@rangojs/router";
 
 export const urlpatterns = urls(({ path, layout, include }) => [
   // RSC routes (normal)
@@ -81,18 +83,27 @@ export const urlpatterns = urls(({ path, layout, include }) => [
 
 ## ResponseHandlerContext
 
-Response route handlers receive a lighter context (no `ctx.use()`, no `ctx.res`):
+Response route handlers receive a lighter context (no `ctx.use()`, no `ctx.set()`, no `ctx.res`):
 
 ```typescript
 interface ResponseHandlerContext<TParams, TEnv> {
-  request: Request;
-  params: TParams; // Typed from URL pattern
-  env: TEnv; // Plain bindings (DB, KV, etc.)
-  searchParams: URLSearchParams;
-  url: URL;
+  // Shared request scope (same as every Rango context)
+  request: Request; // raw request: headers, method, body
+  url: URL; // internal _rsc* params stripped
+  originalUrl: URL; // transport URL, unmodified
   pathname: string;
-  reverse: (name: string, params?: Record<string, string>) => string;
-  get: GetVariableFn; // Read middleware variables
+  searchParams: URLSearchParams;
+  env: TEnv; // Plain bindings (DB, KV, etc.)
+  waitUntil(fn: () => Promise<void>): void; // work after the response
+  executionContext?: ExecutionContext; // Cloudflare only
+  // Response-route specific
+  params: TParams; // Typed from URL pattern
+  reverse: (
+    name: string,
+    params?: Record<string, string>,
+    search?: Record<string, unknown>,
+  ) => string; // GlobalReverseFunction: global names only, ".name" is a type error
+  get: GetVariableFn; // Read middleware variables (string key or createVar token)
   header: (name: string, value: string) => void;
   // Use cookies().set(name, value, opts) for cookie mutations (standalone API)
 }
@@ -104,6 +115,8 @@ String-returning handlers (json, text, html, xml, md) can set custom headers and
 without constructing a full Response:
 
 ```typescript
+import { cookies } from "@rangojs/router";
+
 path.md(
   "/docs/:slug.md",
   (ctx) => {
@@ -127,10 +140,12 @@ merge, and router `onError` is not invoked. Throw ordinary errors (including
 
 ### Environment Access
 
-`ctx.env` is always the plain bindings passed as TEnv to `createRouter<TEnv>()`:
+`ctx.env` is the plain bindings object the router received for the request. Its
+type comes from the global `Rango.Env` registration (`/typesafety`), not from
+the `createRouter<TEnv>()` generic, which `urls()` modules cannot see:
 
 ```typescript
-// createRouter<{ DB: D1Database; KV: KVNamespace }>({ ... })
+// Rango.Env registered as { DB: D1Database; KV: KVNamespace }
 
 // In a response handler:
 path.json(
@@ -192,6 +207,13 @@ path.json(
 );
 ```
 
+`RouterError` defaults to status 500 when `status` is omitted. Any other thrown
+error becomes a 500 with `code: "INTERNAL"`, and its message is hidden in
+production (`RouterError` messages are always sent). Only `path.json()` produces
+`problem+json`: the other response types answer errors with `text/plain` — the
+`RouterError` message, or for other errors the message in development and
+`Internal Server Error` in production.
+
 ### Returning Response Directly
 
 JSON handlers can return `Response` to bypass auto-wrap (custom status, headers, streaming):
@@ -223,6 +245,8 @@ For an OAuth, SSO, or payment callback, validate the registered target and
 return an explicitly external redirect:
 
 ```typescript
+import { redirect } from "@rangojs/router";
+
 path.any("/oauth/decision", async (ctx) => {
   const redirectUri = await readAndValidateRedirectUri(ctx.request);
   return redirect(redirectUri, { status: 303, external: true });
@@ -341,16 +365,19 @@ For local/scoped response typing without global augmentation, prefer
 the response payload straight from the `urls()` patterns and needs no
 `RegisteredRoutes` wiring.
 
-### ParamsFor with Response Routes
+### RouteParams with Response Routes
 
 ```typescript
-import type { ParamsFor } from "@rangojs/router";
+import type { RouteParams } from "@rangojs/router";
 
-// Works for both RSC and response routes
-type ProductParams = ParamsFor<"api.productDetail">;
+// Works for both RSC and response routes (reads the global route map)
+type ProductParams = RouteParams<"api.productDetail">;
 // = { id: string }
 ```
 
+`ParamsFor<TRoutes, "name">` is the lower-level form that takes an explicit
+route map first (e.g. `ParamsFor<typeof router.routeMap, "api.productDetail">`).
+
 ## Links to Response Routes
 
 ### Client: href.json(), href.text(), etc.
@@ -401,6 +428,80 @@ Response-route `cache()` stores whole `Response`s. The serve leaf
 | **Per-client signals** | A response with `Set-Cookie` or `x-rango-keep-cache` is returned live but **not** stored (MISS + SWR revalidation also skip put).                                                       |
 | **Default key**        | `response:{type}:{cacheKeyBase(host, path, searchParams)}` — sorted search, reserved `_rsc*` / allowlisted `__*` params excluded. Custom `key()` / store `keyGenerator` still override. |
 
+## CSRF
+
+The router's built-in `originCheck` guards server actions, fetchable loaders,
+and progressive-enhancement form posts (`/server-actions` → "CSRF
+Protection"). Response routes are **outside** that gate: the check is never
+consulted for them, not even a custom `originCheck` function.
+
+That matters for a response route that changes state **and** authenticates
+with cookies. Another site can make the victim's browser send a POST to it —
+an HTML form (`urlencoded`, `multipart`, or `text/plain`) or a `no-cors`
+`fetch()` — and the browser attaches the session cookie. Being a "JSON API" is
+no protection: `path.json()` does not parse the request body, and
+`await ctx.request.json()` parses a `text/plain` body just as happily. Routes
+authenticated only by an `Authorization` header are not exposed, because a
+cross-site request cannot set it.
+
+Guard state-changing response routes with middleware that applies the same
+rule as `originCheck`:
+
+```typescript
+import type { Middleware } from "@rangojs/router";
+
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+
+// Mirrors the built-in originCheck: Origin (or Referer) must equal the request
+// protocol + Host; no Origin/Referer means a non-browser client; "null" and a
+// missing Host fail closed.
+export const requireSameOrigin: Middleware = async (ctx, next) => {
+  if (SAFE_METHODS.has(ctx.request.method)) return next();
+
+  const headers = ctx.request.headers;
+  let origin = headers.get("origin");
+  if (!origin) {
+    const referer = headers.get("referer");
+    if (referer) {
+      try {
+        origin = new URL(referer).origin;
+      } catch {
+        // Malformed Referer: treat as absent
+      }
+    }
+  }
+  if (!origin) return next();
+
+  const host = headers.get("host");
+  const expected = host ? `${ctx.url.protocol}//${host}` : null;
+  if (!expected || origin.toLowerCase() !== expected.toLowerCase()) {
+    throw new Response("Forbidden", { status: 403 });
+  }
+  return next();
+};
+```
+
+Attach it with a pattern-scoped `router.use()` to cover a whole API prefix, or
+as a `middleware()` use item on a single route:
+
+```typescript
+// router.tsx — every response route under the API prefix
+const router = createRouter()
+  .use("/api/*", requireSameOrigin)
+  .routes(urlpatterns);
+
+// urls.tsx — one route
+path.json("/api/cart", updateCart, { name: "cart" }, () => [
+  middleware(requireSameOrigin),
+]);
+```
+
+Server-to-server callers (signed webhooks, cron, other backends) send no
+`Origin`, so they pass this check; verify their signature or credentials in the
+handler. Behind a proxy that rewrites `Host`, derive `expected` from the header
+your proxy sets, as with a custom `originCheck` (`/router-setup` → "Origin
+check").
+
 ## Mountable Module Pattern
 
 A self-contained module with RSC pages + JSON APIs, mountable via `include()`:
@@ -474,8 +575,7 @@ the `_responses` phantom are inferred from the resolved `urls()` value, so
 ### Type safety after mounting
 
 ```typescript
-import type { RouteResponse } from "@rangojs/router";
-import type { ParamsFor } from "@rangojs/router";
+import type { RouteResponse, RouteParams } from "@rangojs/router";
 
 // Scoped (before mount) -- use the module directly, no global wiring needed
 type Stats = RouteResponse<typeof blogApiPatterns, "stats">;
@@ -488,21 +588,25 @@ type BlogStats = Rango.PathResponse<"/blog/api/stats">;
 // = { views: number; visitors: number }
 
 // Params work through nested includes
-type LikesParams = ParamsFor<"blog.api.likes">;
+type LikesParams = RouteParams<"blog.api.likes">;
 // = { slug: string }
 ```
 
 ### ctx.reverse inside mounted modules
 
-Response route handlers inside a mounted module can reference local names:
+A response handler's `ctx.reverse` resolves **global** names only: it has no
+`include()` scope and does not auto-fill params from the current request. Use
+the fully qualified name and pass every param:
 
 ```typescript
-// Inside blogApiPatterns handler
-path(
+// Inside blogApiPatterns (mounted via include("/api", ..., { name: "api" })
+// inside blogPatterns, mounted via include("/blog", ..., { name: "blog" }))
+path.json(
   "/:slug/likes",
   (ctx) => {
-    // ctx.reverse resolves names relative to the mount point
-    const commentsUrl = ctx.reverse("comments", { slug: ctx.params.slug });
+    const commentsUrl = ctx.reverse("blog.api.comments", {
+      slug: ctx.params.slug,
+    });
     // -> "/blog/api/my-post/comments"
 
     return { slug: ctx.params.slug, count: 42, commentsUrl };
@@ -511,6 +615,10 @@ path(
 );
 ```
 
+A dot-local name (`ctx.reverse(".comments")`) is a type error here. The
+runtime reverse has no scope to resolve it against, so untyped (JS) code that
+calls it throws `Unknown route` and the route answers 500.
+
 ## Content Negotiation
 
 Multiple response types can share the same URL pattern. See `/mime-routes` for the