@rangojs/router 0.15.1 → 0.17.0

package/skills/testing/render-handler.md

@@ -13,7 +13,9 @@ A Rango route handler is a pure function `(ctx) => rsc` — the function you pas
 | `params`               | `Record<string, string>`                               | Route params surfaced as `ctx.params`.                                                                                                                                                                                                                                                                                                                                               |
 | `env`                  | `TEnv`                                                 | Environment bindings surfaced as `ctx.env`.                                                                                                                                                                                                                                                                                                                                          |
 | `request`              | `Request \| string`                                    | Backing Request (string or `Request`); defaults to a localhost GET.                                                                                                                                                                                                                                                                                                                  |
-| `headers`              | `HeadersInit`                                          | Request headers (e.g. `Cookie`) the handler reads via `cookies()`.                                                                                                                                                                                                                                                                                                                   |
+| `headers`              | `HeadersInit`                                          | Request headers (e.g. `Cookie`) the handler reads via `cookies()`. Used only when `request` is a string or omitted; a passed `Request` keeps its own headers.                                                                                                                                                                                                                        |
+| `build`                | `boolean`                                              | Seed `ctx.build` (default `false`) to test a handler that branches on the build-time pass, including calling `ctx.dynamic()` on a miss. Assert the opt-out via `result.dynamic`.                                                                                                                                                                                                     |
+| `theme`                | `ThemeConfig \| true`                                  | Theme config (`createRouter({ theme })` shape). Without it `ctx.theme`/`ctx.setTheme` are inert; pass one to test a handler that reads the theme or writes the theme cookie.                                                                                                                                                                                                         |
 | `vars`                 | `VarsInit` (object or `[[Var, value]]` tuples)         | Variables a prior middleware set, read via `ctx.get(...)`.                                                                                                                                                                                                                                                                                                                           |
 | `routeName`            | `string`                                               | Matched route name (drives `ctx.routeName` and scoped reverse).                                                                                                                                                                                                                                                                                                                      |
 | `routeMap`             | `Record<string, string>`                               | Route name -> pattern map enabling `ctx.reverse()`.                                                                                                                                                                                                                                                                                                                                  |
@@ -26,21 +28,21 @@ A Rango route handler is a pure function `(ctx) => rsc` — the function you pas
 
 ### Context — `HandlerContext` (what your handler receives)
 
-| Field              | Type                                 | Meaning                                                                                        |
-| ------------------ | ------------------------------------ | ---------------------------------------------------------------------------------------------- |
-| `params`           | `Record<string, string>`             | The seeded route params.                                                                       |
-| `env`              | `TEnv`                               | The seeded environment bindings.                                                               |
-| `request`          | `Request`                            | The backing request.                                                                           |
-| `searchParams`     | `URLSearchParams`                    | Parsed query of `request.url`.                                                                 |
-| `pathname`         | `string`                             | Pathname of `request.url`.                                                                     |
-| `url`              | `URL`                                | Parsed `request.url`.                                                                          |
-| `routeName`        | `string \| undefined`                | The matched route name (from `routeName`).                                                     |
-| `use`              | `(loaderOrHandle) => data \| pushFn` | A loader returns its seeded data; a handle returns a push fn that RECORDS to `result.handles`. |
-| `reverse`          | `(name, params?) => string`          | Build a URL from `routeMap`.                                                                   |
-| `get`              | `(Var) => value`                     | Read a seeded `vars` variable.                                                                 |
-| `headers`          | `Headers`                            | Response headers; set via `ctx.headers.set(...)` (merged into `result.response`).              |
-| `setLocationState` | `(entries) => void`                  | Set location state (surfaced on `result.locationState`).                                       |
-| `waitUntil`        | `(fn: () => Promise<void>) => void`  | Register background work.                                                                      |
+| Field              | Type                                          | Meaning                                                                                                                       |
+| ------------------ | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `params`           | `Record<string, string>`                      | The seeded route params.                                                                                                      |
+| `env`              | `TEnv`                                        | The seeded environment bindings.                                                                                              |
+| `request`          | `Request`                                     | The backing request.                                                                                                          |
+| `searchParams`     | `URLSearchParams`                             | Parsed query of `request.url`.                                                                                                |
+| `pathname`         | `string`                                      | Pathname of `request.url`.                                                                                                    |
+| `url`              | `URL`                                         | Parsed `request.url`.                                                                                                         |
+| `routeName`        | `string \| undefined`                         | The matched route name (from `routeName`).                                                                                    |
+| `use`              | `(loaderOrHandle) => Promise<data> \| pushFn` | A loader returns a Promise of its seeded data (like production); a handle returns a push fn that RECORDS to `result.handles`. |
+| `reverse`          | `(name, params?) => string`                   | Build a URL from `routeMap`.                                                                                                  |
+| `get`              | `(Var) => value`                              | Read a seeded `vars` variable.                                                                                                |
+| `headers`          | `Headers`                                     | Response headers; set via `ctx.headers.set(...)` (merged into `result.response`).                                             |
+| `setLocationState` | `(entries) => void`                           | Set location state (surfaced on `result.locationState`).                                                                      |
+| `waitUntil`        | `(fn: () => Promise<void>) => void`           | Register background work.                                                                                                     |
 
 ### Returns — `RenderHandlerResult`
 
@@ -55,18 +57,22 @@ A Rango route handler is a pure function `(ctx) => rsc` — the function you pas
 | `stateCookieName` | `string`                  | The resolved rango state cookie name this run seeded (default `rango-state_router_0`). Assert an `invalidateClientCache()` rotation against it without recomputing. |
 | `locationState`   | `Record<string, unknown>` | Location state the handler set (`ctx.setLocationState`/`redirect({ state })`).                                                                                      |
 | `handles`         | `Map<Handle, unknown[]>`  | What the handler pushed via `ctx.use(Handle)(...)` (e.g. `Meta`, `Breadcrumbs`), keyed by handle.                                                                   |
+| `dynamic`         | `boolean`                 | Whether the handler called `ctx.dynamic()` (the PPR shell opt-out).                                                                                                 |
 
 ## Recipe
 
 ```tsx
+import { it, expect } from "vitest";
 import {
   renderHandler,
   findClientBoundaries,
+  textContent,
 } from "@rangojs/router/testing/flight";
+import { Meta } from "@rangojs/router";
 import { ProductPage } from "../src/pages/product"; // the real handler: (ctx) => rsc
+import { LogoutPage, QuietPage } from "../src/pages/account"; // call invalidateClientCache() / keepClientCache()
 import { ProductLoader } from "../src/loaders/product";
-import { Tenant } from "../src/middleware/tenant";
-import { Meta } from "../src/handles";
+import { Tenant } from "../src/middleware/tenant"; // a createVar()
 
 it("renders the product page for a tenant", async () => {
   const { tree, handles } = await renderHandler(ProductPage, {
@@ -76,8 +82,9 @@ it("renders the product page for a tenant", async () => {
     routeMap: { product: "/p/:slug" }, // enables ctx.reverse
   });
 
-  expect(JSON.stringify(tree)).toContain("Wine");
-  const [counter] = findClientBoundaries(tree, "Counter"); // islands inspectable too
+  expect(textContent(tree)).toContain("Wine");
+  const [addToCart] = findClientBoundaries(tree, "AddToCart"); // islands inspectable too
+  expect(addToCart.props.slug).toBe("wine");
   expect(handles.get(Meta)).toEqual([{ title: "Wine - Shop" }]); // ctx.use(Meta) pushes
 });
 
@@ -106,14 +113,55 @@ it("asserts the client-cache directives", async () => {
 });
 ```
 
+## A `"use cache"` hit
+
+With `cacheStore` seeded, a `"use cache"` function the handler calls runs the real cache runtime on real Flight. The first call runs the body and writes the entry in a background (`waitUntil`) task that `renderHandler` does not await. A call made before that write lands joins the still-running execution; a call made after it reads the store. Either way the body runs once, and the value comes back through a Flight round trip, so a `Date`, a `Map`, a client island or a server action keeps its type and reference. A value Flight encodes as an error row, such as a rejected promise, is not stored. The stale (SWR) path is not covered here; assert it at e2e.
+
+The rango plugin's `"use cache"` transform runs only in its `rsc` environment (dev or build), and Vitest transforms in `ssr`, so add `rangoUseCacheTransform()` to the react-server project's `plugins` (see [`./setup.md`](./setup.md)). It runs the same transform, with the ids `vite dev` emits (`src/data/products.ts#...`). Without it the directive is an inert string and the function runs on every call.
+
+```tsx
+// src/data/products.ts
+export async function getProduct(slug: string) {
+  "use cache: short";
+  return db.products.find(slug);
+}
+```
+
+```tsx
+import { it, expect, vi } from "vitest";
+import { renderHandler } from "@rangojs/router/testing/flight";
+import { MemorySegmentCacheStore } from "@rangojs/router/cache";
+import { ProductPage } from "../src/pages/product"; // calls getProduct(ctx.params.slug)
+import { db } from "../src/db";
+
+it("reads the second render's product from the store", async () => {
+  const find = vi.spyOn(db.products, "find");
+  const cacheStore = new MemorySegmentCacheStore();
+  const setItem = vi.spyOn(cacheStore, "setItem");
+  const options = {
+    params: { slug: "wine" },
+    cacheStore,
+    cacheProfiles: { short: { ttl: 60 } },
+  };
+
+  await renderHandler(ProductPage, options);
+  await vi.waitFor(() => expect(setItem).toHaveBeenCalled()); // the background write
+  await renderHandler(ProductPage, options);
+
+  expect(find).toHaveBeenCalledTimes(1);
+});
+```
+
+Without the plugin, wrap a function yourself with the call the transform emits, `registerCachedFunction(fn, id, profile)` from `@rangojs/router/cache-runtime`.
+
 ## Caveats
 
 - An unseeded `ctx.use(loader)` REJECTS with a setup error — seed every dependency via `{ loaders: [[OtherLoader, data]] }`, matched by reference. Loaders are SEEDED, not executed (same as `runLoader`).
-- Same alias requirement as flight tests: without the `@rangojs/router -> index.rsc.ts` alias (see [`./setup.md`](./setup.md)), a handler reading `getRequestContext()`/`cookies()` hits the throwing out-of-react-server stub. Symptom: `tree: undefined` with the stub error on `thrown`.
+- Same alias requirement as flight tests: without the `@rangojs/router -> index.rsc.ts` alias (see [`./setup.md`](./setup.md)), a handler reading `getRequestContext()`/`cookies()` hits the throwing out-of-react-server stub. `renderHandler` detects this and REJECTS with a setup error naming `rangoTestAliases` (it is not captured on `thrown`).
 - A `throw redirect()` is captured on `thrown` (with `tree` undefined, since it produced a `Response`) — assert on `thrown`/`response`, no try/catch needed.
 - No hydration and no interaction — for clicks, forms, and navigation use e2e.
 - `renderHandler` runs a handler FUNCTION `(ctx) => rsc`; for a plain ELEMENT `<Page/>` use `renderServerTree` (see [`./server-tree.md`](./server-tree.md)).
-- A handler that calls a `"use cache"` function runs UNCACHED unless you seed `cacheStore` (and `cacheProfiles` for a named profile). With nothing seeded the runtime bypasses to the live body and warns once under the test runner — assert real cache behavior by passing `{ cacheStore: new MemorySegmentCacheStore(), cacheProfiles: { default: { ttl: 60 } } }`.
+- A handler that calls a `"use cache"` function runs UNCACHED unless you seed `cacheStore` (and `cacheProfiles` for a named profile). With nothing seeded the runtime bypasses to the live body and warns once under the test runner. With a store seeded, the body runs once across renders and a render after the background write reads the store — see [A `"use cache"` hit](#a-use-cache-hit), including `rangoUseCacheTransform()`, without which Vitest leaves the directive unwrapped.
 
 ## See also
 

package/skills/testing/response-routes.md

@@ -25,7 +25,7 @@ The lightweight context a RESPONSE-route handler reads (mirrors the production `
 | `searchParams`        | `URLSearchParams`        | Query params with internal `_rsc*` params stripped.                                                         |
 | `url`                 | `URL`                    | Cleaned request URL (internal `_rsc*` params removed).                                                      |
 | `pathname`            | `string`                 | Matched pathname.                                                                                           |
-| `reverse`             | `ReverseFunction`        | URL-from-name. Map-only (NO auto-fill from current params), matching the production response-route handler. |
+| `reverse`             | `GlobalReverseFunction`  | Global names only (NO auto-fill, `.name` is a type error), matching the production response-route handlers. |
 | `get`                 | fn                       | Read context vars set by prior middleware.                                                                  |
 | `header(name, value)` | fn                       | Set a response header; surfaces on the returned `Response`.                                                 |
 | `waitUntil`           | fn                       | Register a deferred task (no-op fidelity in tests).                                                         |
@@ -76,17 +76,24 @@ describe("api routes via dispatch", () => {
 });
 ```
 
-`dispatch` also covers trailing-slash/redirect targets (`findMatch`) — a redirected path returns a 308 with the `Location` (query preserved). Pass `env` via `{ env }`.
+`dispatch` also covers, with production code paths:
+
+- trailing-slash/redirect targets (`findMatch`) — a redirected path returns a 308 with the `Location` (query preserved);
+- the open-redirect guard on browser-followed redirects (a cross-origin `Location` is rewritten to the basename root unless `redirect(url, { external: true })`);
+- content-negotiated routes (`Vary: Accept` appended);
+- cached response routes (`cache({ ... })` around a `path.json` etc.): hit, SWR, and tag writes. The cache write is scheduled via `waitUntil` (a microtask in tests), so flush microtasks between the seeding `dispatch` and the one that asserts the hit;
+- `createRouter({ telemetry })` `request.start` / `request.end` / `request.error` events, and `createRouter({ onError })` for cache-read/write failures.
 
 ## Caveats
 
 - Hitting a COMPONENT (RSC) route throws a clear directive error: `dispatch` is for response routes + redirects + 404 + content negotiation, plus the global + route-level middleware guard stack on RESPONSE routes — it never renders React. Use Flight primitives or e2e to exercise component rendering.
 - A COMPONENT route's guard stack cannot run here. Assert it at e2e, or extract the middleware fn and unit-test it with `runMiddleware` (see `./middleware.md`).
-- JSON serialization is bare, applied in `response-route-handler.ts`: a `path.json` handler that returns a value is serialized verbatim (`JSON.stringify(value)`, status 200, `application/json`) — no envelope. Returning or throwing a `Response` (e.g. `Response.json(x)`) uses the same control-flow path. Any other thrown error yields an RFC 9457 problem+json body `{ title, status, detail, code }` (`application/problem+json`) with the error's status (`RouterError.status`, else 500, or a non-200 `ctx.res.status` already set upstream in the request pipeline); `code` is the `RouterError.code`, else `"INTERNAL"`. The `type` member is omitted this phase. Assert the shape matching what your handler returns.
+- JSON serialization is bare, applied in `response-route-handler.ts`: a `path.json` handler that returns a value is serialized verbatim (`JSON.stringify(value)`, status 200, `application/json`) — no envelope. Returning or throwing a `Response` (e.g. `Response.json(x)`) uses the same control-flow path. Any other thrown error takes the error's status (`RouterError.status`, else 500, or a non-200 status already set upstream in the request pipeline). On a `path.json` route the body is an RFC 9457 problem+json object `{ title, status, detail, code }` (`application/problem+json;charset=utf-8`), where `code` is the `RouterError.code`, else `"INTERNAL"`, and the `type` member is omitted. On text/html/xml/md routes the body is `text/plain`: the `RouterError` message, the error message in dev, or `"Internal Server Error"` in production. Assert the shape matching what your handler returns.
 - Setup: needs the preset (alias + virtual stubs) or a Vite-RSC env (see `./setup.md`); a bare router import throws on Vite virtuals.
 - A router using `Prerender()`/`createLoader()`/`Static()` now constructs in a bare test (each assigns a runtime fallback `$$id`). Importing the whole router _file_ may still need the plugin (its page modules pull app deps / `virtual:` modules) — build from a focused include (your API routes) for whole-router dispatch.
 - A `_rsc_partial` request to a response route runs global middleware first (an auth gate can still 401/redirect), then returns `X-RSC-Reload` — route-level middleware is skipped, exactly like production.
-- `dispatch` does NOT execute server actions (`?_rsc_action`), but it DOES run the global middleware chain on an action request — middleware can still 401/redirect it, and any 3xx redirect on a partial OR action request becomes a `204` + `X-RSC-Redirect` (fetch-safe interception), the raw `Location` dropped.
+- `dispatch` does NOT execute server actions (`?_rsc_action`), but it DOES run the global middleware chain on an action request — middleware can still 401/redirect it, and any 3xx redirect on a partial OR action request becomes a `204` + `X-RSC-Redirect` (fetch-safe interception), the raw `Location` dropped. Location state carried on such a redirect is dropped too (production embeds it in a Flight payload); cover that at e2e.
+- `createRouter({ onError })` is NOT invoked for a thrown non-Response HANDLER error here (the typed error Response still matches production), and `cache.decision` / `loader.*` telemetry never fires (no RSC render runs). Cover both at e2e.
 
 ## See also
 

package/skills/testing/reverse-and-types.md

@@ -1,6 +1,6 @@
 # Testing reverse/href and type-level contracts
 
-**Layer:** unit (node) + typecheck · **Import:** `@rangojs/router/client` (useReverse), `@rangojs/router/testing` (assertGeneratedRoutesMatch) · **DSL it tests:** `reverse`/`href`/`useReverse` (see `/typesafety`, `/links`)
+**Layer:** unit (node) + typecheck · **Import:** `@rangojs/router/client` (useReverse), `@rangojs/router/testing` (assertGeneratedRoutesMatch) · **DSL it tests:** `ctx.reverse`/`href`/`useReverse` (see `/typesafety`, `/links`)
 
 The reverse/href/params/env types are a real contract: a wrong route name, a missing param, or an unknown env binding should be a COMPILE error, not a runtime surprise. The type-test recipes have no runtime API — `tsc --noEmit` IS the assertion. `assertGeneratedRoutesMatch` is the one runtime helper here: it runs the router's real matching to expand lazy includes, then diffs the live `routeMap` against the generated named-routes map you seed. It (and `diffGeneratedRoutes`) are **async — `await` them** — because expanding an async `include(prefix, () => import("./routes"))` group means importing that module first.
 
@@ -8,10 +8,10 @@ The reverse/href/params/env types are a real contract: a wrong route name, a mis
 
 ### Options — `assertGeneratedRoutesMatch(router, generatedMap?)`
 
-| Field          | Type                                 | Meaning                                                                                                                                                    |
-| -------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `router`       | `{ routeMap; findMatch? }`           | Your router (real impl). `routeMap` is the live name→pattern map; `findMatch` (when present) is called to force-expand lazy `include()`d routes.           |
-| `generatedMap` | `Record<string, unknown>` (optional) | The imported `*.named-routes.gen.ts` map (name→pattern, or `{ path }` objects). Omit to diff against the global route map (`getGlobalRouteMap()`) instead. |
+| Field          | Type                                 | Meaning                                                                                                                                                 |
+| -------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `router`       | `{ routeMap; findMatch? }`           | Your router (real impl). `routeMap` is the live name→pattern map; `findMatch` (when present) is called to force-expand lazy `include()`d routes.        |
+| `generatedMap` | `Record<string, unknown>` (optional) | The `NamedRoutes` export of your `*.named-routes.gen.ts` file (name→pattern, or `{ path }` objects). Omit to diff against the global route map instead. |
 
 ### Context — `GeneratedRoutesDiff` (what `diffGeneratedRoutes` resolves to)
 
@@ -32,14 +32,19 @@ The reverse/href/params/env types are a real contract: a wrong route name, a mis
 // 1. Negative assertions inline with @ts-expect-error — the directive ERRORS if
 //    the line below it ever starts compiling (i.e. if the type guard regresses).
 //    Validated by `tsc --noEmit`; a runtime test cannot assert this.
+//    Keep the hook call inside a function that is never invoked: tsc checks it,
+//    and a runtime test file that imports it does not execute a hook outside
+//    a component.
 import { useReverse } from "@rangojs/router/client";
 
-const reverse = useReverse({ post: "/blog/:slug" });
-reverse("post", { slug: "hi" }); // ok
-// @ts-expect-error - missing required :slug param
-reverse("post", {});
-// @ts-expect-error - "comment" is not a route in this map
-reverse("comment", { id: "1" });
+function typeOnly() {
+  const reverse = useReverse({ post: "/blog/:slug" });
+  reverse("post", { slug: "hi" }); // ok
+  // @ts-expect-error - missing required :slug param
+  reverse("post", {});
+  // @ts-expect-error - "comment" is not a route in this map
+  reverse("comment", { id: "1" });
+}
 ```
 
 ```ts
@@ -62,10 +67,11 @@ expectTypeOf<
 import { it } from "vitest";
 import { assertGeneratedRoutesMatch } from "@rangojs/router/testing";
 import { router } from "../src/router";
-import generated from "../src/router.named-routes.gen";
+// The generated file has no default export; it exports `NamedRoutes`.
+import { NamedRoutes } from "../src/router.named-routes.gen";
 
 it("generated named-routes map is in sync with the router", async () => {
-  await assertGeneratedRoutesMatch(router, generated);
+  await assertGeneratedRoutesMatch(router, NamedRoutes);
 });
 ```
 
@@ -76,7 +82,7 @@ For a large type-only suite, collect recipe-1/2 assertions in `*.test-d.ts` file
 - Type tests run at TYPECHECK time (`tsc --noEmit`), NOT in the vitest runner. They are their own layer — wire them into CI as a real step (`pnpm run typecheck`). A type test nobody runs is just a comment.
 - `@ts-expect-error` ERRORS if the line below it ever starts compiling, so a regressed guard fails the typecheck. A runtime test cannot assert "this should not type-check".
 - `assertGeneratedRoutesMatch` force-expands lazy `include()`d routes (awaits `findMatch` on a concrete path derived from each generated pattern) before diffing — otherwise every included route reads as a false `missing`. It is **async** so it can await the module import behind an async `include(() => import())` group; `await` the call (or the async group's routes read as `missing`). This makes the whole-app drift check work in a plain unit test. Routers without `findMatch` (a bare `{ routeMap }`) are left as-is.
-- MULTI-APP route-map isolation. `href()`/`reverse()` typing is GLOBAL — each app's generated file augments the one `Rango.GeneratedRouteMap` interface. A `renderRoute` suite that imports a client component from app B (which calls `href("/b-route")`) won't typecheck if the same tsconfig program also carries app A's augmentation: A's route union rejects B's name. `renderRoute` is app-agnostic at RUNTIME; the collision is purely the global `href` typing. Keep a `renderRoute` suite single-app, or give each app its OWN tsconfig program (see `/typesafety`); a quick sidestep is to probe `useMount`/`useHref` inline instead of importing the cross-app component.
+- MULTI-APP route-map isolation. `href()`/`ctx.reverse()` typing is GLOBAL — each app's generated file augments the one `Rango.GeneratedRouteMap` interface. A `renderRoute` suite that imports a client component from app B (which calls `href("/b-route")`) won't typecheck if the same tsconfig program also carries app A's augmentation: A's route union rejects B's name. `renderRoute` is app-agnostic at RUNTIME; the collision is purely the global `href` typing. Keep a `renderRoute` suite single-app, or give each app its OWN tsconfig program (see `/typesafety`); a quick sidestep is to probe `useMount`/`useHref` inline instead of importing the cross-app component.
 
 ## See also
 

package/skills/testing/server-actions.md

@@ -22,6 +22,7 @@
 | `cacheStore`    | `SegmentCacheStore`                                    | Backing store for `use cache` functions (same shape as `createRouter({ cache })`). Without it, cached functions run uncached and their guards never fire.                                                                                                                                                                                             |
 | `cacheProfiles` | `Record<string, CacheProfile>`                         | Profiles for `use cache: "name"`, same shape as `createRouter({ cacheProfiles })`. An unknown profile throws.                                                                                                                                                                                                                                         |
 | `theme`         | `ThemeConfig \| true`                                  | Theme config (same shape as `createRouter({ theme })`). Without it `ctx.theme` / `ctx.setTheme` are inert.                                                                                                                                                                                                                                            |
+| `build`         | `boolean`                                              | Seed `ctx.build` (default `false`) for code that branches on the build-time PPR shell-capture pass. With `true`, `ctx.waitUntil()` is inert, as at build time.                                                                                                                                                                                        |
 | `stateCookie`   | `StateCookieSeed` (`{ prefix?, routerId?, version? }`) | Customize the rango state cookie an action calling `invalidateClientCache()` rotates. The name is ALWAYS seeded (default `rango-state_router_0`) so the rotation `Set-Cookie` fires like production; override `prefix`/`routerId` to match `createRouter({ stateCookiePrefix, id })`, or `version` (value is `{version}:{timestamp}`, default `"0"`). |
 
 ### Context — `RequestContext<TEnv>` (what your code receives)
@@ -52,7 +53,12 @@
 | `stateCookieName` | `string`                  | The resolved rango state cookie name this run seeded (default `rango-state_router_0`). Assert an `invalidateClientCache()` rotation against it without recomputing.                               |
 | `locationState`   | `Record<string, unknown>` | The flash set via `ctx.setLocationState()` / `redirect({ state })`, as the flat `{ key: value }` the client reads.                                                                                |
 
-Low-level variant: when you already hold a context from `createTestRequestContext(opts)`, call `runWithRequestContext(ctx, fn)` (re-exported from `@rangojs/router/testing`) to enter it directly. `runInRequestContext` is the one-call convenience over `createTestRequestContext` + `runWithRequestContext`.
+Low-level building blocks (all from `@rangojs/router/testing`):
+
+- `createTestRequestContext(opts)` builds the context WITHOUT entering it and returns `{ ctx, request, url, variables, stateCookieName }`. Its `ctx.reverse` accepts any name from your `routeMap`.
+- `runWithRequestContext(ctx, fn)` enters a context you already hold. `runInRequestContext` is the one-call convenience over these two, plus the result snapshot.
+- `toRequest(request?, init?)` normalizes a `Request | string | undefined` into a `Request` (strings resolve against `http://localhost/`).
+- `seedVariables(variables, vars?)` writes a `VarsInit` (object or `[key, value]` tuples) into a raw variables record, the same way the `vars` option does.
 
 ## Recipe
 
@@ -60,10 +66,13 @@ Low-level variant: when you already hold a context from `createTestRequestContex
 import { it, expect } from "vitest";
 import { runInRequestContext } from "@rangojs/router/testing";
 import { loginAction } from "../src/actions/login"; // sets a session cookie + flash, then throw redirect("/app")
+import { logoutAction, dismissBannerAction } from "../src/actions/session"; // invalidateClientCache() / keepClientCache()
+
+const env = { DB: fakeDb }; // your binding double (see ./bindings.md)
 
 it("sets the session cookie + flash and redirects", async () => {
   const { thrown, cookies, locationState } = await runInRequestContext(
-    () => loginAction(input),
+    () => loginAction({ email: "ada@example.com", password: "pw" }),
     {
       env,
       request: new Request("https://app.test/admin", {
@@ -97,7 +106,7 @@ it("asserts the client-cache directives an action issued", async () => {
 
 - The snapshot fires whether `fn` RETURNS or THROWS. A `throw redirect("/app")` on the success path is captured on `thrown` (NOT re-thrown), so no try/catch is needed; assert on `thrown` for a throwing action.
 - There is no cookies / headers option. Seed a request cookie by passing a full `Request` with the `Cookie` header (as in the recipe).
-- `runWithRequestContext(ctx, fn)` is the low-level entry when you already hold a context; `runInRequestContext` is the one-call convenience over `createTestRequestContext` + `runWithRequestContext`.
+- An action has no loader context, so `runLoader` is the wrong shape for it even when the action reads cookies or vars; use `runInRequestContext`.
 - Platform bindings are yours to double via `env` (see `./bindings.md`).
 
 ## See also

package/skills/testing/server-tree.md

@@ -18,6 +18,8 @@
 | `vars`             | `VarsInit`                | Context variables visible via `ctx.get(...)`, as a prior middleware would have set them. Object form (`{ user }`) or `[key, value]` tuples.                                                                                                                                                                                            |
 | `clientComponents` | `Record<string, unknown>` | The `"use client"` components reachable from the tree, keyed by the boundary name to register each as a client reference (in place) so it serializes as an `I` row. Omit when `rangoUseClientTransform()` auto-discovers them, or for pure server-only trees. First-wins per worker; already-registered references are left untouched. |
 
+It also accepts the rest of `RenderToFlightStringOptions` — `routeMap`, `theme`, `cacheStore`, `cacheProfiles` — with the same meaning as in [`./flight.md`](./flight.md).
+
 ### Context — what your code receives
 
 A server component rendered here runs under a real request context: `getRequestContext()` resolves, `ctx.params`/`ctx.routeName`/`ctx.env` reflect the options, `ctx.get(MyVar)` reads a seeded `var`, and cookies come off the request. Same seeding as the handler-test primitives — you render an **element** you build (`<Page />`); to run a route **handler** `(ctx) => rsc` use `renderHandler` (see `./render-handler.md`).
@@ -64,6 +66,10 @@ Every SERVER/HOST element a server component produced (`<article>`, `<h2>`), in
 
 Concatenates every string/number leaf of a node's subtree in document order — the clean way to assert rendered text, instead of `JSON.stringify(tree).toContain(...)`.
 
+#### `assertFlightTreeRuntimeAvailable()`
+
+Throws a descriptive error when a `@vitejs/plugin-rsc` subpath the round trip relies on (the vendored client deserializer or `registerClientReference`) no longer exports the expected function — the counterpart of `assertFlightRuntimeAvailable()` in `./flight.md`. Call it in a `beforeAll` to fail fast after a plugin-rsc upgrade.
+
 ## Recipe
 
 ```tsx
@@ -74,8 +80,11 @@ import {
   findElements,
   textContent,
 } from "@rangojs/router/testing/flight";
+import { flightMatchers } from "@rangojs/router/testing/flight-matchers";
 import { PriceTag } from "./PriceTag.js"; // a "use client" component (any filename)
 
+expect.extend(flightMatchers); // for toMatchFlight below
+
 async function ProductPanel({ amount, asOf }: { amount: number; asOf: Date }) {
   await Promise.resolve();
   return (

package/skills/testing/setup.md

@@ -12,13 +12,15 @@ Real machinery: Vite transpiles `@rangojs/router`'s shipped TS source and resolv
 | -------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `preset` | `"node" \| "cloudflare"` | Deployment preset, matching `rango({ preset })` in the Vite plugin. `"cloudflare"` additionally stubs the `cloudflare:workers` / `cloudflare:email` runtime virtuals a CF route tree imports. A string (not a boolean) so more presets can be added without an API change. Default `"node"`. |
 
-### Functions
+### Exports
 
-| Function                    | Returns                                   | Use                                                                                                                                                                                                                                        |
+| Export                      | Returns / value                           | Use                                                                                                                                                                                                                                        |
 | --------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `rangoTestConfig(opts?)`    | `{ alias, server: { deps: { inline } } }` | Recommended. Spread into the node/DOM project's `test` block. Bundles the resolve aliases AND `server.deps.inline`.                                                                                                                        |
 | `rangoTestAliases(opts?)`   | `TestAlias[]` (`{ find, replacement }[]`) | Lower-level. The bare `@rangojs/router` -> `index.rsc.ts` alias plus the `:version` / `@vitejs/plugin-rsc/rsc` (`/rsc/server`, `/rsc/client`) stubs (and CF stubs under `preset:"cloudflare"`). Used in the rsc project's `resolve.alias`. |
-| `rangoUseClientTransform()` | a Vite plugin (`{ name, transform }`)     | Add to the rsc project `plugins`. Applies the `"use client"` transform so `renderServerTree` auto-discovers client islands from the server tree's imports.                                                                                 |
+| `rangoInlineDeps`           | `RegExp[]` (`[/@rangojs[/\\]router/]`)    | The `server.deps.inline` patterns on their own. Use in the rsc project (`test.server.deps.inline`), or wherever you call `rangoTestAliases` directly instead of `rangoTestConfig`.                                                         |
+| `rangoUseClientTransform()` | a Vite plugin (`{ name, transform }`)     | Add to the rsc project `plugins`. Applies the `"use client"` transform so `renderServerTree` / `renderHandler` auto-discover client islands from the server tree's imports.                                                                |
+| `rangoUseCacheTransform()`  | a Vite plugin (`enforce: "post"`)         | Add to the rsc project `plugins`. Runs the rango plugin's `"use cache"` transform with dev ids (`<path>#<name>`, the path relative to the root its `configResolved` reads) so a directive function caches.                                 |
 
 ### Returns — `RangoTestConfig` (from `rangoTestConfig`)
 
@@ -53,6 +55,7 @@ import { defineConfig } from "vitest/config";
 import {
   rangoTestAliases,
   rangoUseClientTransform,
+  rangoUseCacheTransform,
   rangoInlineDeps,
 } from "@rangojs/router/testing/vitest";
 
@@ -60,7 +63,7 @@ import {
 process.env.NODE_ENV = "production";
 
 export default defineConfig({
-  plugins: [rangoUseClientTransform()],
+  plugins: [rangoUseClientTransform(), rangoUseCacheTransform()],
   resolve: {
     conditions: ["react-server"],
     alias: rangoTestAliases({ preset: "cloudflare" }), // or { preset: "node" }
@@ -109,12 +112,13 @@ Scripts:
 
 - Node >= 23 requires `rangoTestConfig()`, not bare `rangoTestAliases()`. `@rangojs/router` is consumed as SOURCE (exports -> `./src/*.ts`), and Node >= 23 refuses to type-strip `.ts` under `node_modules` (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`). `rangoTestConfig` ships as compiled JS AND adds `server.deps.inline: [/@rangojs[/\\]router/]` so Vite (not Node) transpiles rango source. With bare `rangoTestAliases` you must wire `deps.inline` yourself.
 - Two separate projects. The node/DOM project keeps React on its CLIENT build; the Flight project uses the `react-server` condition in a separate `vitest.rsc.config.ts`. The main project must NOT set `react-server` — it flips React to the no-hooks server build and breaks every `renderRoute` / client test.
-- The rsc project needs BOTH `resolve.conditions: ["react-server"]` AND the bare `@rangojs/router` -> `index.rsc.ts` alias from `rangoTestAliases({ preset })`. `resolve.conditions` alone is not reliably applied to bare-package export resolution; without the alias a handler/component reading `getRequestContext()` / `cookies()` resolves the throwing out-of-react-server stub (symptom: `renderHandler` returns `tree: undefined`). `renderToFlightString` / `renderServerTree` now self-diagnose this exact misconfiguration — they reject with an actionable message naming `rangoTestAliases`, rather than surfacing the opaque stub error.
+- The rsc project needs BOTH `resolve.conditions: ["react-server"]` AND the bare `@rangojs/router` -> `index.rsc.ts` alias from `rangoTestAliases({ preset })`. `resolve.conditions` alone is not reliably applied to bare-package export resolution; without the alias a handler/component reading `getRequestContext()` / `cookies()` resolves the throwing out-of-react-server stub. `renderToFlightString`, `renderServerTree`, and `renderHandler` all detect this exact misconfiguration and reject with an actionable message naming `rangoTestAliases`, rather than surfacing the opaque stub error.
 - `NODE_ENV` must be `"production"` in the rsc project. Dev `NODE_ENV` crashes the bare worker (jsxDEV owner-stack machinery uninitialized) and emits volatile debug rows that defeat stable Flight snapshots.
 - The forked rsc worker (`pool: "forks"`) must force the condition via `execArgv: ["--conditions=react-server"]`, or React throws "the react-server condition must be enabled".
 - The `@rangojs/router:version` and `@vitejs/plugin-rsc/rsc` (`/rsc/server`, `/rsc/client`) virtuals must be stubbed; the preset does it. A bare router import without stubbing throws.
 - The rango fragment goes under `test` (`test.alias` + `test.server.deps.inline`, both returned by `rangoTestConfig`), NOT under top-level `resolve`.
 - Wire `rangoUseClientTransform()` into the rsc project `plugins` so islands auto-discover from the server tree imports (see `./server-tree.md`); without it, register islands explicitly with `clientComponents`. The transform's `registerClientReference` import is resolved from `@rangojs/router`'s `@vitejs/plugin-rsc` — the consumer does not need a direct plugin-rsc dependency.
+- Wire `rangoUseCacheTransform()` into the rsc project `plugins` so a function written with `"use cache"` is wrapped as in dev. `rango()` runs that transform only in its `rsc` environment and Vitest transforms in `ssr`, so without it the directive is inert and the function runs on every call. See [`./render-handler.md`](./render-handler.md#a-use-cache-hit).
 
 ## See also
 

package/skills/theme/SKILL.md

@@ -1,82 +1,159 @@
 ---
 name: theme
-description: Opt-in theme system with FOUC prevention for light/dark mode. Use when adding a light/dark mode toggle, or the page flashes the wrong theme on load (FOUC).
+description: Opt-in light/dark theme system with FOUC prevention, server-side theme access, and a useTheme() hook. Use when adding a light/dark mode toggle, reading or setting the theme in handlers or middleware, or when the page flashes the wrong theme on load (FOUC).
 argument-hint: [setup]
 ---
 
 # Theme Support
 
-Opt-in theme system with FOUC prevention.
+Opt-in theme system. Enabling it gives you:
+
+- an inline script (rendered by `<Html.Meta />`) that applies the stored theme
+  to `<html>` before first paint, so there is no flash of the wrong theme;
+- `ctx.theme` / `ctx.setTheme()` in handlers and middleware;
+- the `useTheme()` hook in client components (the provider is added for you).
+
+The theme is stored in a cookie (so the server can read it) and in
+localStorage.
 
 ## Enable
 
 ```typescript
 import { createRouter } from "@rangojs/router";
 
-// Simple - all defaults
-const router = createRouter<Env>({
+// All defaults
+export const router = createRouter<AppBindings>({
   document: Document,
   urls: urlpatterns,
   theme: true,
 });
 
-// Custom config
-const router = createRouter<Env>({
+// Custom config (values shown are the defaults unless noted)
+export const router = createRouter<AppBindings>({
   document: Document,
   urls: urlpatterns,
   theme: {
     defaultTheme: "system", // "light" | "dark" | "system"
     themes: ["light", "dark"],
-    attribute: "class", // or "data-theme"
-    storageKey: "theme",
+    attribute: "class", // or any "data-*" attribute, e.g. "data-theme"
+    storageKey: "theme", // cookie and localStorage key
+    enableSystem: true, // resolve "system" via prefers-color-scheme
+    enableColorScheme: true, // set style="color-scheme: ..." on <html>
+    value: { dark: "theme-dark" }, // optional: attribute value per theme (not a default)
   },
 });
 ```
 
-## Server (in handlers/middleware)
+With `attribute: "class"` the resolved theme is added as a class on `<html>`
+(`<html class="dark">`); with a `data-*` attribute it is set as that
+attribute's value (`<html data-theme="dark">`). `"system"` resolves to
+`"light"` or `"dark"` before it is applied. With `enableSystem: false`,
+`"system"` is not a valid theme and a `"system"` default falls back to the
+first entry in `themes`.
+
+## Document requirements
+
+- Render `<Html.Meta />` in `<head>`: it emits the FOUC-prevention script
+  first, before the meta tags. The default Document already does this.
+- Add `suppressHydrationWarning` to `<html>`: the script changes its
+  `class`/`style` before React hydrates.
+
+```tsx
+"use client";
+import type { ReactNode } from "react";
+import { Html } from "@rangojs/router/client";
+
+export function Document({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <Html.Meta />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+A Document that does not render `<Html.Meta />` can place `<ThemeScript />`
+from `@rangojs/router/theme` in `<head>` instead. It takes the resolved config
+(`config: ResolvedThemeConfig`) and an optional `nonce`.
+
+## Server (handlers and middleware)
+
+`ctx.theme` is the stored theme, or `defaultTheme` when there is none.
+`ctx.setTheme(theme)` sets the theme cookie on the response; invalid values
+are rejected with a console warning. Both are typed optional because they only
+exist when `theme` is configured.
 
 ```typescript
 import type { Middleware } from "@rangojs/router";
 
 // In a handler
 path("/settings", (ctx) => {
-  const currentTheme = ctx.theme; // read from cookie
+  const currentTheme = ctx.theme; // "light" | "dark" | "system" | undefined
   return <SettingsPage theme={currentTheme} />;
 });
 
-// In middleware
-export const themeMiddleware: Middleware = async (ctx, next) => {
-  // Set theme based on user preference
-  ctx.setTheme("dark");
+// In middleware: apply a theme chosen through a query param
+export const themeFromQuery: Middleware = async (ctx, next) => {
+  const requested = ctx.url.searchParams.get("theme");
+  if (requested === "light" || requested === "dark") {
+    ctx.setTheme?.(requested);
+  }
   await next();
 };
 ```
 
-Theme accessors are handler/middleware-only — the loader context has no
-`ctx.theme`/`ctx.setTheme`. A loader that needs the theme reads the cookie
-directly via `cookies()` (loaders always run fresh, so the read is safe).
+Loaders do not get `ctx.theme` or `ctx.setTheme`. A loader that needs the
+theme reads the cookie directly (loaders run fresh on every request, so the
+read is safe):
+
+```typescript
+import { cookies, createLoader } from "@rangojs/router";
+
+export const ThemedLoader = createLoader(async () => {
+  const theme = cookies().get("theme")?.value ?? "system"; // storageKey
+  return loadThemedAssets(theme);
+});
+```
 
 ## Client
 
 ```tsx
 "use client";
-import { useTheme } from "@rangojs/router/theme";
+import { useTheme, type Theme } from "@rangojs/router/theme";
 
-function ThemeToggle() {
-  const { theme, setTheme, resolvedTheme, systemTheme, themes } = useTheme();
+export function ThemeToggle() {
+  const { theme, setTheme, resolvedTheme, themes } = useTheme();
 
   return (
-    <select value={theme} onChange={(e) => setTheme(e.target.value)}>
-      <option value="system">System</option>
-      <option value="light">Light</option>
-      <option value="dark">Dark</option>
-    </select>
+    <label>
+      Theme ({resolvedTheme})
+      <select value={theme} onChange={(e) => setTheme(e.target.value as Theme)}>
+        {themes.map((t) => (
+          <option key={t} value={t}>
+            {t}
+          </option>
+        ))}
+      </select>
+    </label>
   );
 }
 ```
 
-## Notes
+`useTheme()` returns:
+
+- `theme`: the stored setting (`"light" | "dark" | "system"`)
+- `setTheme(theme)`: update the theme; writes the cookie and localStorage
+- `resolvedTheme`: what is actually shown (`"system"` resolved)
+- `systemTheme`: the current OS preference (`"light" | "dark"`)
+- `themes`: the configured themes, with `"system"` first when `enableSystem` is on
+
+`useTheme()` throws when `theme` is not enabled in `createRouter()`.
+
+## Related
 
-- `<MetaTags />` auto-renders inline script for FOUC prevention
-- Add `suppressHydrationWarning` to `<html>`
-- Theme persists in localStorage + cookie (for SSR)
+- `/tailwind`: pairing `attribute: "class"` with Tailwind's `dark:` variant
+- `/css`: where document stylesheets go
+- `/router-setup`: the Document component