@rangojs/router 0.16.0 → 0.18.0

package/skills/testing/predicates.md

@@ -0,0 +1,120 @@
+# Testing navigation predicates — runTransitionWhen, runClientRevalidate
+
+**Layer:** unit (node) · **Import:** `@rangojs/router/testing` · **DSL it tests:** `transition({ when })` (see `/view-transitions`) and `clientUrls()` `revalidate()` (see `/client-urls`)
+
+Both primitives are synchronous and run the router's own evaluation code on arguments you seed, so a predicate sees the same fields it sees at runtime. Neither renders anything: they answer "would this gate keep the transition?" and "would this `clientUrls()` loader re-run?".
+
+## runTransitionWhen(config, opts?)
+
+Runs a `transition()` config through the production gate (`gateTransitions`, plus the PPR pre-handler evaluator when `ppr: true`) and reports whether the transition survives this request.
+
+### Options — `RunTransitionWhenOptions<TEnv>`
+
+Every field is optional. Omitted navigation fields model "source unavailable" (an initial document load); omitted `action*` fields model a plain navigation.
+
+| Field           | Type                     | Meaning                                                                                           |
+| --------------- | ------------------------ | ------------------------------------------------------------------------------------------------- |
+| `request`       | `Request \| string`      | Navigation TARGET (drives `nextUrl`). Defaults to `http://localhost/`.                            |
+| `params`        | `Record<string, string>` | Target params (`nextParams`).                                                                     |
+| `toRouteName`   | `string`                 | Target route name (`toRouteName`).                                                                |
+| `currentUrl`    | `string \| URL`          | Navigation SOURCE (`currentUrl`).                                                                 |
+| `currentParams` | `Record<string, string>` | Source params (`currentParams`).                                                                  |
+| `fromRouteName` | `string`                 | Source route name (`fromRouteName`).                                                              |
+| `actionId`      | `string`                 | Id of the action that triggered the render.                                                       |
+| `actionUrl`     | `string \| URL`          | URL the action was submitted from.                                                                |
+| `actionResult`  | `unknown`                | The action's return value.                                                                        |
+| `formData`      | `FormData`               | Form data from a form action.                                                                     |
+| `env`           | `TEnv`                   | Bindings surfaced as `env`.                                                                       |
+| `vars`          | `VarsInit`               | Values the predicate reads through `get()`. With `ppr`, these model pre-handler middleware state. |
+| `onError`       | `OnErrorCallback`        | Receives an error the predicate throws (the gate reports it with phase `"rendering"`).            |
+| `ppr`           | `boolean`                | Model a `ppr` route, where the predicate runs before route handlers and the cache lookup.         |
+
+### Returns — `RunTransitionWhenResult<TEnv>`
+
+| Field         | Type                                 | Meaning                                                                                         |
+| ------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `kept`        | `boolean`                            | True when the transition applies (the predicate did not return `false`, or there is no `when`). |
+| `dropped`     | `boolean`                            | `!kept`.                                                                                        |
+| `whenContext` | `TransitionWhenContext \| undefined` | The context the predicate received; `undefined` when the config has no `when`.                  |
+| `ctx`         | `RequestContext<TEnv>`               | The underlying request context, for extra assertions.                                           |
+
+### Recipe
+
+```ts
+import { it, expect } from "vitest";
+import { runTransitionWhen } from "@rangojs/router/testing";
+import type { TransitionConfig } from "@rangojs/router";
+
+const slide: TransitionConfig = {
+  when: (c) => c.fromRouteName === "products",
+};
+
+it("animates only when coming from the product list", () => {
+  expect(
+    runTransitionWhen(slide, {
+      request: "/products/1",
+      fromRouteName: "products",
+    }).kept,
+  ).toBe(true);
+  expect(runTransitionWhen(slide, { request: "/products/1" }).dropped).toBe(
+    true,
+  );
+});
+```
+
+## runClientRevalidate(fn | fn[], opts?)
+
+Evaluates one `clientUrls()` loader `revalidate()` predicate, or a chain in declaration order, through the production chain evaluator: the locked default, boolean short-circuit, soft verdicts (`{ defaultShouldRevalidate }`), and a throwing predicate deferring to the default all behave as in the browser. Returns the final `boolean` (the locked default when every predicate defers or throws).
+
+### Options — `RunClientRevalidateOptions`
+
+Defaults model a same-URL navigation with no action.
+
+| Field           | Type                             | Meaning                                                                                                                                                                                         |
+| --------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `currentUrl`    | `string \| URL`                  | Source URL. Defaults to `http://localhost/`.                                                                                                                                                    |
+| `nextUrl`       | `string \| URL`                  | Target URL. Defaults to `currentUrl`.                                                                                                                                                           |
+| `currentParams` | `Record<string, string>`         | Source params. Defaults to `{}`.                                                                                                                                                                |
+| `nextParams`    | `Record<string, string>`         | Target params. Defaults to `currentParams`.                                                                                                                                                     |
+| `stale`         | `boolean`                        | The `stale` arg. Defaults to `false`.                                                                                                                                                           |
+| `action`        | `(...args) => unknown \| string` | The triggering action: one imported server action (its id is read from the build-injected `$id`/`$$id`) or a raw action id string. A namespace object is rejected. Omit for a plain navigation. |
+| `actionRequest` | `boolean`                        | Model the action-triggered refetch GET: `isAction()` stays true but the locked default is the navigation default. Defaults to treating `action` as the action POST itself.                      |
+
+Outside a built app, an imported action carries no id, so pass the id string your predicate matches (for example `"src/actions/cart.ts#addToCart"`); `runClientRevalidate` throws a clear error otherwise.
+
+### Recipe
+
+```ts
+import { it, expect } from "vitest";
+import { runClientRevalidate } from "@rangojs/router/testing";
+import type { ClientRevalidateFn } from "@rangojs/router/client";
+
+const onlyOnTabChange: ClientRevalidateFn = ({ currentUrl, nextUrl }) =>
+  currentUrl.searchParams.get("tab") !== nextUrl.searchParams.get("tab");
+
+it("revalidates only when the tab changes", () => {
+  expect(
+    runClientRevalidate(onlyOnTabChange, {
+      currentUrl: "/settings?tab=profile",
+      nextUrl: "/settings?tab=billing",
+    }),
+  ).toBe(true);
+  expect(
+    runClientRevalidate(onlyOnTabChange, {
+      currentUrl: "/settings?tab=profile",
+      nextUrl: "/settings?tab=profile&sort=asc",
+    }),
+  ).toBe(false);
+});
+```
+
+## Caveats
+
+- Server-tree `revalidate()` predicates have no dedicated primitive: they are plain functions, so call them with a hand-built args object, or assert the post-action result at e2e.
+- `runTransitionWhen` proves the GATE decision only. Whether the browser actually runs a view transition is e2e territory (see `./e2e-parity.md`).
+- Both are synchronous; a predicate returning a Promise is a bug in the predicate, not something to await here.
+
+## See also
+
+- `/view-transitions`, `/client-urls` — the DSL these test
+- Siblings: `./client-components.md`, `./e2e-parity.md`

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/serve-shell-request.md

@@ -0,0 +1,188 @@
+# Testing a PPR shell — serveShellRequest
+
+**Layer:** RSC unit (react-server project) · **Import:** `@rangojs/router/testing/flight` · **DSL it tests:** the `ppr` path option (see `/ppr`)
+
+`serveShellRequest(router, url, options?)` serves one GET through your router's production request handler — built as `router.fetch` builds it, with the router's `nonce`, `version`, `cache` config and middleware — and settles every background task the request scheduled before it resolves. So the first request for a `ppr` route is a MISS whose real capture has stored its shell (`putShell` landed), and the next request with the same store is a real HIT: shell read, version gates, the tail replaying the handler output the capture baked (no handler runs), live loaders. A `partial` request is a real client navigation with its `x-rango-ppr-replay` decision. Flight is real.
+
+The one stub is the HTML step (the SSR module), because `react-dom/server` does not load under the react-server condition:
+
+| SSR step           | Under `serveShellRequest`                                                                              |
+| ------------------ | ------------------------------------------------------------------------------------------------------ |
+| `renderHTML`       | passes the Flight stream through: a document body is its Flight payload                                |
+| `captureShellHTML` | stores, as the prelude, the Flight text the capture rendered before it went quiet; `postponed` is null |
+| `resumeShellHTML`  | passes the tail's Flight through: a HIT body is the stored prelude, then the tail's Flight payload     |
+
+So `prelude` is the shell as captured (Flight text, not HTML): a value the shell froze appears there, and a hole (a live loader under `loading()`) does not.
+
+## API
+
+### Options — `ServeShellRequestOptions`
+
+| Field        | Type                                             | Meaning                                                                                                                                                                                                    |
+| ------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cacheStore` | `SegmentCacheStore`                              | The store for this request, in place of the store your `createRouter({ cache })` config returns. The rest of that config (`enabled`, `searchParams`) still applies. Omit it to use the router's own store. |
+| `env`        | `TEnv`                                           | Bindings, as `router.fetch(request, { env })` passes them. A function `cache` config receives them.                                                                                                        |
+| `headers`    | `HeadersInit`                                    | Request headers (e.g. `cookie`). A document request defaults `accept` to `text/html`.                                                                                                                      |
+| `partial`    | `true \| { from?: string; segments?: string[] }` | Serve the navigation request the browser sends instead of a document GET: from `from` (default the site root) with `segments` mounted (default none).                                                      |
+
+### Returns — `ServeShellRequestResult`
+
+| Field          | Type                                     | Meaning                                                                                                                                                                             |
+| -------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `shellStatus`  | `"HIT" \| "MISS" \| null`                | `x-rango-shell`; null when the serve path did not consider the request (not a `ppr` route, a nonce'd request, a partial request).                                                   |
+| `replayStatus` | `PprReplayStatus \| null`                | `x-rango-ppr-replay` on a partial request: `{ outcome: "HIT", freshness }` or `{ outcome: "BYPASS", reason }`.                                                                      |
+| `prelude`      | `string \| undefined`                    | The prelude a HIT served (the capture's Flight text). `undefined` unless `shellStatus` is `"HIT"`.                                                                                  |
+| `flight`       | `string \| undefined`                    | The Flight payload this request rendered: a HIT's tail, a document render, or a partial response. `undefined` when no Flight rendered (a redirect, a middleware response).          |
+| `key`          | `string`                                 | The shell key the serve path resolved for a document it read (MISS or HIT), request partition included. Otherwise (no `ppr`, a partial request) the URL's key without a partition.  |
+| `readEntry`    | `() => Promise<ShellCacheEntry \| null>` | Reads the document entry under `key` from the request's store (a passive `getShell`). A read: on a store with a shell memo it warms the memo, so call it after the reads you count. |
+| `response`     | `Response`                               | Status and headers. Its body is already read.                                                                                                                                       |
+| `body`         | `string`                                 | The body text.                                                                                                                                                                      |
+
+### `resetShellTestState(): Promise<void>`
+
+A worker keeps some PPR state across requests, and so does the test process across tests: the capture's stampede guard and backoff (a refused capture backs its URL off for later tests too), the capture's and the serve path's once-per-key warnings, the build-shell manifest memo, and `CFCacheStore`'s isolate memos (shells, tag markers, tag hints), which every `CFCacheStore` shares by namespace and URL — a later test's first request can be a HIT from an earlier test's shell. `resetShellTestState()` clears all of it. Call it in `beforeEach`, never while a request is in flight. `VercelCacheStore`'s memos live on the `cache` handle you pass it: a new handle per test starts empty.
+
+## Recipe
+
+```ts
+// test/product-shell.rsc-test.tsx — in the react-server project (./setup.md)
+import { beforeEach, expect, it } from "vitest";
+import { createRouter, updateTag, urls } from "@rangojs/router";
+import { MemorySegmentCacheStore } from "@rangojs/router/cache";
+import { runInRequestContext } from "@rangojs/router/testing";
+import {
+  resetShellTestState,
+  serveShellRequest,
+} from "@rangojs/router/testing/flight";
+import { ProductPage } from "../src/pages/product"; // renders the product name
+import { StockLoader } from "../src/loaders/stock"; // live stock count
+
+const router = createRouter().routes(
+  urls(({ path, loader, loading }) => [
+    path("/product/:id", ProductPage, { name: "product", ppr: { tags: ["catalog"] } }, () => [
+      loader(StockLoader),
+      loading(<p>Checking stock…</p>),
+    ]),
+  ]),
+);
+
+beforeEach(() => resetShellTestState());
+
+it("serves the captured shell and fills the stock hole live", async () => {
+  const cacheStore = new MemorySegmentCacheStore();
+
+  const miss = await serveShellRequest(router, "/product/1", { cacheStore });
+  expect(miss.shellStatus).toBe("MISS"); // a normal render; the capture stored the shell
+
+  const hit = await serveShellRequest(router, "/product/1", { cacheStore });
+  expect(hit.shellStatus).toBe("HIT");
+  expect(hit.prelude).toContain("Widget"); // frozen at capture
+  expect(hit.prelude).not.toContain("in stock"); // the hole
+  expect(hit.flight).toContain("in stock"); // rendered by this request
+
+  await runInRequestContext(() => updateTag("catalog"), { cacheStore });
+  const recapture = await serveShellRequest(router, "/product/1", { cacheStore });
+  expect(recapture.shellStatus).toBe("MISS");
+});
+
+it("replays the captured segments on a client navigation", async () => {
+  const cacheStore = new MemorySegmentCacheStore();
+  await serveShellRequest(router, "/product/2", { cacheStore });
+
+  const nav = await serveShellRequest(router, "/product/2", {
+    cacheStore,
+    partial: { from: "/" },
+  });
+  expect(nav.replayStatus).toEqual({ outcome: "HIT", freshness: "fresh" });
+});
+```
+
+A store built per request from a function `cache` config gets the request's execution context (`ctx`), so its own `waitUntil` writes (`CFCacheStore({ ctx })`) settle with the call. A store built outside the request with its own `waitUntil` (`VercelCacheStore`'s option) is not settled by the call. For `CFCacheStore`, stub the `caches` global and pass a KV double in `env`; for `VercelCacheStore`, pass a `cache` double. A store's shell memo then behaves as in production (count your double's reads across two HITs).
+
+## A HIT runs no handler
+
+A HIT replays what the capture's handlers produced — their elements, the promises they passed or pushed, their handle values — and runs only middleware and loaders. Count runs to pin it:
+
+```ts
+let pageRuns = 0;
+// the page handler does `pageRuns += 1` and renders `page-run-${pageRuns}`
+
+it("a HIT runs no handler", async () => {
+  const cacheStore = new MemorySegmentCacheStore();
+  await serveShellRequest(router, "/product/3", { cacheStore }); // MISS + capture
+  const baked = pageRuns; // the capture's run
+
+  const hit = await serveShellRequest(router, "/product/3", { cacheStore });
+  expect(hit.shellStatus).toBe("HIT");
+  expect(pageRuns).toBe(baked);
+  expect(hit.flight).toContain(`page-run-${baked}`);
+});
+```
+
+## Request-partitioned shells
+
+A route whose `cache()` record is partitioned by the request (`cache({ key })`, or the store's `keyGenerator`) has a shell per partition. Serve each partition with the request headers or cookies its key reads; the result's `key` is the key the serve path resolved, partition included, and `readEntry()` reads it:
+
+```ts
+// cache({ ttl: 300, key: (ctx) => `tier:${ctx.request.headers.get("x-tier")}` }, () => [
+//   path("/pricing", PricingPage, { ppr: true }),
+// ])
+const tier = (name: string) => ({ cacheStore, headers: { "x-tier": name } });
+
+await serveShellRequest(router, "/pricing", tier("gold")); // MISS + capture
+const silver = await serveShellRequest(router, "/pricing", tier("silver"));
+expect(silver.shellStatus).toBe("MISS"); // its own capture, never gold's shell
+const gold = await serveShellRequest(router, "/pricing", tier("gold"));
+expect(gold.shellStatus).toBe("HIT");
+expect(gold.key).toBe(shellCacheKey("/pricing", undefined, "tier:gold"));
+expect(await gold.readEntry()).not.toBeNull();
+```
+
+Under nested keyed `cache()` boundaries the partition is their `key()` results composed, outermost first (see `/caching`, "Keys nest"). Pass them to `shellCacheKey` as an array and it composes them the same way:
+
+```ts
+// cache({ key: tierKey }, () => [
+//   layout(TierLayout, () => [
+//     cache({ key: (ctx) => `v:${variantOf(ctx)}` }, () => [path("/plans", PlansPage, { ppr: true })]),
+//   ]),
+// ])
+expect(result.key).toBe(
+  shellCacheKey("/plans", undefined, ["tier:gold", "v:a"]),
+);
+```
+
+A partial request has no HTML step, so its `key` is the URL's key without a partition: read a partitioned route's entry from a document request's result.
+
+## Handles and loader data
+
+The result carries no structured `handles` map (unlike `renderHandler`): a handle value and loader data ride the payload, so you assert them as text in `prelude` and `flight`. A value the handler pushed is in the prelude and in every HIT's tail; a live loader's data is only in the tail. No public helper decodes a payload string into values: `normalizeFlight` and the `flightMatchers` (`toMatchFlight`) work on the text too.
+
+```ts
+// The handler pushed ctx.use(Meta)({ title: "Widget - Shop" })
+expect(hit.prelude).toContain('"title":"Widget - Shop"');
+expect(hit.flight).toContain('"title":"Widget - Shop"');
+```
+
+## Caveats
+
+What the HTML stub cannot reproduce, so keep it in e2e:
+
+- The prelude's `<body` sanity gate. A route whose production capture refuses for a root postpone (a live loader read with no `loading()` or `<Suspense>` above it) stores a shell here.
+- The capture deadline. `ppr.captureTimeout` (default 15s) bounds the whole capture: the match, the handler output, then the shell render. A capture that runs out of it stores nothing and is not retried in place, here as in production, so the call waits one deadline: give such a route a short `captureTimeout` in a test (Vitest's default test timeout is 5s). One difference: when the handler output settled but the shell render does not go quiet in what is left, the stub returns no shell, while production goes on to its abort and can still store the prelude rendered by then.
+- SSR render errors. In production a fizz render error during the capture refuses it (#915). The stub renders no HTML and reports none, so a shell whose client component throws during SSR is stored here. A server component that throws still refuses the capture, as in production.
+- Fizz resume of the holes, bootstrap scripts, nonce injection, and browser resume.
+
+Other caveats:
+
+- A HIT's tail carries replayed segments as Flight fragments inside JSON strings, so their quotes are escaped (`\"`). Match plain text, or unescape before matching JSON-shaped text.
+- Call `resetShellTestState()` in `beforeEach` (see above). Without it, a URL a previous test left backed off, or a shell memoized by another `CFCacheStore`, changes what the next test sees.
+- `readEntry()` reads the document entry under `key`. A partial request that finds no entry captures a navigation-only entry, which is stored apart from it.
+- `updateTag()` needs a request context with the store: call it through `runInRequestContext(fn, { cacheStore })` or your app's own endpoint (`dispatch`). A store refuses a capture that starts in the invalidation's millisecond (the invalidation wins) and backs the key off; `serveShellRequest` starts each request in a later millisecond than the call, so an invalidation made before the call cannot collide with it.
+- GET only. Server actions are not served; test their effects with `runInRequestContext`.
+- Same setup as every Flight test: the react-server condition and `rangoTestAliases()` (see [`./setup.md`](./setup.md)).
+
+## See also
+
+- `/ppr` — the DSL this tests; `/caching` — stores and tags
+- Siblings: [`./cache-prerender.md`](./cache-prerender.md) (the shell-status helpers and the e2e recipe), [`./render-handler.md`](./render-handler.md)
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "serveShellRequest — a real PPR capture and HIT"