@rangojs/router 0.16.0 → 0.18.0

package/skills/testing/cache-prerender.md

@@ -19,11 +19,11 @@ Use the header path when all you have is a black-box `Response` (a Playwright `A
 
 ### Options — `assertCacheStatus(target, segment, expected)`
 
-| Field      | Type                                                                                                          | Meaning                                                                                                                                                                                                                             |
-| ---------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `target`   | `Response \| { headers: Headers }` (`CacheStatusTarget`)                                                      | The thing carrying the `X-Rango-Cache` header: a `Response` from `router.fetch(...)`, or any `{ headers: Headers }`. A Playwright `APIResponse` exposes headers as a method, so wrap it: `{ headers: new Headers(res.headers()) }`. |
-| `segment`  | `string`                                                                                                      | The route NAME (e.g. `product.detail`), the same id the header carries — NOT the URL pattern (`/products/:id`).                                                                                                                     |
-| `expected` | `"hit" \| "miss" \| "stale" \| "prerendered" \| "passthrough"` (`ExpectedCacheStatus` = `CacheSegmentStatus`) | The cache status you assert for that route.                                                                                                                                                                                         |
+| Field      | Type                                                                                                                                                                                   | Meaning                                                                                                                                                                                                                             |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `target`   | `Response \| { headers: Headers }` (`CacheStatusTarget`)                                                                                                                               | The thing carrying the `X-Rango-Cache` header: a `Response` from `router.fetch(...)`, or any `{ headers: Headers }`. A Playwright `APIResponse` exposes headers as a method, so wrap it: `{ headers: new Headers(res.headers()) }`. |
+| `segment`  | `string`                                                                                                                                                                               | The route NAME (e.g. `product.detail`), the same id the header carries — NOT the URL pattern (`/products/:id`).                                                                                                                     |
+| `expected` | `"hit" \| "miss" \| "stale" \| "prerendered"` (`ExpectedCacheStatus` = `CacheSegmentStatus`; `"passthrough"` is in the union but never emitted — a passthrough route reports `"miss"`) | The cache status you assert for that route.                                                                                                                                                                                         |
 
 ### Context — what your code under test emits
 
@@ -33,7 +33,7 @@ The header / event is produced by the router's RSC render pipeline from `ctx.rou
 | ------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------ |
 | `CacheSegmentSignal.id`               | `string`                | Segment id. v1: the route key, since status is route-level.                                |
 | `CacheSegmentSignal.type`             | `string`                | Segment type. v1: `"route"` for the coarse route-level entry.                              |
-| `CacheSegmentSignal.cacheStatus`      | `CacheSegmentStatus`    | Resolved status (`hit`/`miss`/`stale`/`prerendered`/`passthrough`).                        |
+| `CacheSegmentSignal.cacheStatus`      | `CacheSegmentStatus`    | Resolved status (`hit`/`miss`/`stale`/`prerendered`; passthrough routes report `miss`).    |
 | `CacheSegmentSignal.shouldRevalidate` | `boolean?`              | Whether stale-while-revalidate was triggered for this segment.                             |
 | `CacheDecisionEvent.segments`         | `CacheSegmentSignal[]?` | The coarse route-level signal array (present only when telemetry or the debug gate is on). |
 
@@ -92,15 +92,19 @@ parityDescribe("product page caches", (f) => {
 Zero-prod-surface alternative — the telemetry sink. No header at all; you inspect captured `cache.decision` events:
 
 ```ts
+import { expect } from "vitest";
+import { createRouter } from "@rangojs/router";
 import {
   createCacheSink,
   assertCacheDecision,
   filterCacheDecisions,
 } from "@rangojs/router/testing";
+import { urlpatterns } from "../src/urls";
 
 const { sink, events } = createCacheSink();
 const router = createRouter({ telemetry: sink }).routes(urlpatterns);
-// ...drive a request through the router's RSC fetch path...
+// ...drive a request through the router's RSC fetch path (e.g. an e2e server
+// built from this router); dispatch() never emits cache.decision...
 
 // One-call assert (counterpart of assertCacheStatus), keyed by the route NAME:
 assertCacheDecision(events, "product.detail", "stale");
@@ -115,17 +119,17 @@ expect(decision.segments?.[0].shouldRevalidate).toBe(true);
 
 ## PPR shell and navigation replay
 
-**DSL:** `ppr: true | PartialPrerenderProps` on a page route (see `/ppr`). **Not** the same header as `X-Rango-Cache` — shell is a second render axis.
+**DSL:** `ppr: true | PartialPrerenderProps` on a page route (see `/ppr`). **Not** the same header as `X-Rango-Cache` — the shell is cached separately from the segments.
 
-| Helper                                    | Import                               | Role                                                                                                   |
-| ----------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------ |
-| `assertShellStatus(res, "HIT" \| "MISS")` | `@rangojs/router/testing` or `…/e2e` | Assert `x-rango-shell` on a **real document** Response                                                 |
-| `parseShellStatus(res)`                   | same                                 | `"HIT" \| "MISS" \| null` (null = header absent / unrecognized)                                        |
-| `shellCacheKey(url)`                      | same                                 | Production shell store key (`host+pathname+sorted search+:shell`) for `store.getShell` / custom stores |
-| `SHELL_STATUS_HEADER`                     | same                                 | `"x-rango-shell"` constant                                                                             |
-| `assertPprReplayStatus(res, expected)`    | same                                 | Assert fresh/stale replay or a bounded bypass decision                                                 |
-| `parsePprReplayStatus(res)`               | same                                 | Structured replay/bypass status, or null for an absent/unrecognized header                             |
-| `PPR_REPLAY_STATUS_HEADER`                | same                                 | `"x-rango-ppr-replay"` constant                                                                        |
+| Helper                                          | Import                               | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ----------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `assertShellStatus(res, "HIT" \| "MISS")`       | `@rangojs/router/testing` or `…/e2e` | Assert `x-rango-shell` on a **real document** Response                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `parseShellStatus(res)`                         | same                                 | `"HIT" \| "MISS" \| null` (null = header absent / unrecognized)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `shellCacheKey(url, searchParams?, partition?)` | same                                 | Production shell store key (`host+pathname+sorted search+:shell`, then `\|partition`) for `store.getShell` / custom stores. Pass your router's `cache.searchParams` config as the second argument when it sets one — the production key applies it. For a route whose `cache({ key })` or store `keyGenerator` partitions its record, pass what that function returns for the request as `partition`: the shell is partitioned the same way. Under nested keyed `cache()` boundaries, pass their `key()` results as an array, outermost first. |
+| `SHELL_STATUS_HEADER`                           | same                                 | `"x-rango-shell"` constant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `assertPprReplayStatus(res, expected)`          | same                                 | Assert fresh/stale replay or a bounded bypass decision                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `parsePprReplayStatus(res)`                     | same                                 | Structured replay/bypass status, or null for an absent/unrecognized header                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `PPR_REPLAY_STATUS_HEADER`                      | same                                 | `"x-rango-ppr-replay"` constant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 
 ### What unit can prove vs e2e
 
@@ -133,33 +137,56 @@ expect(decision.segments?.[0].shouldRevalidate).toBe(true);
 | -------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | **Unit** | store family + key identity | `MemorySegmentCacheStore` + `shellCacheKey(url)` + `putShell`/`getShell` / tag eviction — dogfood in `e2e/mini/test/shell-store-family.test.ts` and `src/testing/__tests__/shell-status.test.ts` |
 | **Unit** | header helper contract      | `assertShellStatus` on a Response that already carries the header (characterizes the helper; **never** invent a HIT to claim capture worked)                                                     |
+| **Unit** | real capture → HIT, replay  | `serveShellRequest(router, url, { cacheStore })` (react-server project); only the HTML step is stubbed — [`./serve-shell-request.md`](./serve-shell-request.md)                                  |
 | **E2E**  | live MISS → capture → HIT   | document GET, poll until `x-rango-shell: HIT` (background capture) — `e2e/shell-cache.test.ts`                                                                                                   |
 | **E2E**  | partial replay decision     | soft navigation to a warmed shell and `assertPprReplayStatus(response, { outcome: "HIT", freshness: "fresh" })`                                                                                  |
 
-`dispatch` is RSC-free: it never runs shell serve/capture. `renderHandler` only surfaces `ctx.dynamic()` opt-out, not bake/serve.
+`dispatch` is RSC-free: it never runs shell serve/capture. `renderHandler` only surfaces `ctx.dynamic()` opt-out, not bake/serve. The HIT contract — no handler runs, the handler output is the capture's copy, live loaders re-run — is asserted through `serveShellRequest`: count your handler's runs and a live loader's across a MISS and the HITs after it, and check that only the loader's moves ([`./serve-shell-request.md`](./serve-shell-request.md)). A route partitioned by `cache({ key })` or a store `keyGenerator` has a shell per partition: `serveShellRequest` reports the key the serve path resolved (`result.key`), and `shellCacheKey` takes the partition as its third argument.
 
 ### Recipe (e2e)
 
 ```ts
-import { assertShellStatus, shellCacheKey } from "@rangojs/router/testing/e2e";
-// or from @rangojs/router/testing under Vitest
-
-// Document GET (not Accept: text/x-component):
-const first = await page.request.get(f.url("/products/1"));
-assertShellStatus({ headers: new Headers(first.headers()) }, "MISS");
-// After capture flushes (poll — background putShell):
-const second = await page.request.get(f.url("/products/1"));
-assertShellStatus({ headers: new Headers(second.headers()) }, "HIT");
-
-// Custom store / unit: same key the serve path uses
-const key = shellCacheKey(new URL("http://localhost/products/1"));
-expect(await store.getShell(key)).not.toBeNull();
+import { expect, test } from "@playwright/test";
+import {
+  createRangoE2E,
+  assertShellStatus,
+  parseShellStatus,
+} from "@rangojs/router/testing/e2e";
+
+const { parityDescribe } = createRangoE2E({ test, expect });
+
+parityDescribe("product shell", (f) => {
+  test("MISS captures, then HIT", async ({ page }) => {
+    // Document GET (not Accept: text/x-component):
+    const first = await page.request.get(f.url("/products/1"));
+    assertShellStatus({ headers: new Headers(first.headers()) }, "MISS");
+    // Capture runs in the background (putShell), so poll for the HIT:
+    await expect
+      .poll(async () => {
+        const res = await page.request.get(f.url("/products/1"));
+        return parseShellStatus({ headers: new Headers(res.headers()) });
+      })
+      .toBe("HIT");
+  });
+});
+```
+
+```ts
+// Unit (Vitest): the key the serve path uses, against your own store instance
+import { expect, it } from "vitest";
+import { shellCacheKey } from "@rangojs/router/testing";
+
+it("stores the shell under the production key", async () => {
+  // ...after your code under test captured a shell into `store`...
+  const key = shellCacheKey(new URL("http://localhost/products/1"));
+  expect(await store.getShell(key)).not.toBeNull();
+});
 ```
 
 ## Caveats
 
 - The `X-Rango-Cache` header is emitted ONLY when the gate is on: `createRouter({ debugCacheSignal: true })` or `process.env.RANGO_TEST_SIGNALS === "1"`. Off by default — zero production surface. With the gate off, `assertCacheStatus` throws a clear "header missing" error.
-- `x-rango-shell` is always set on document GETs the serve path considered for a ppr route (no debug gate). Absent header = axis-1 fall-open or non-ppr.
+- `x-rango-shell` is always set on document GETs the serve path considered for a ppr route (no debug gate). Absent header = a normal render (no shell): the request fell open, or the route has no `ppr`.
 - v1 is COARSE: route-level, keyed by the route NAME (e.g. `product.detail`), NOT the URL pattern (`/products/:id`); not per-individual-segment. The signal is built from `ctx.routeKey`, so a pattern-shaped key never matches. (`parseCacheHeader` exposes the raw `{ routeKey: status }` map if you need it.)
 - Prerender is indistinguishable from a cache hit by design — no static `.html`/`.rsc` files, the worker handles every request and looks up a stored Flight payload; the browser cannot tell. Do not assert "prerendered" from the DOM. Assert via the signal (`assertCacheStatus(res, seg, "prerendered")`) and run prerender assertions in PRODUCTION mode (the build-time artifacts only exist after `pnpm build`).
 - In a Playwright e2e import the cache-status / shell-status helpers from the `/e2e` entry — the `@rangojs/router/testing` barrel is Vitest-only (it pulls a build-only virtual that does not resolve in a plain Playwright runner). Zero-prod-surface alternative for segment cache: the telemetry sink (`createCacheSink`/`filterCacheDecisions`), no header at all. Note: the non-RSC `dispatch()` primitive never emits either header — get the Response from the router's real RSC fetch path.
@@ -168,5 +195,5 @@ expect(await store.getShell(key)).not.toBeNull();
 ## See also
 
 - `/caching`, `/prerender`, `/use-cache`, `/ppr` — the DSL this tests
-- Siblings: [`./e2e-parity.md`](./e2e-parity.md), [`./response-routes.md`](./response-routes.md)
+- Siblings: [`./e2e-parity.md`](./e2e-parity.md), [`./response-routes.md`](./response-routes.md), [`./serve-shell-request.md`](./serve-shell-request.md)
 - Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "Cache, SWR, and prerender"

package/skills/testing/client-components.md

@@ -2,7 +2,7 @@
 
 **Layer:** unit (DOM) · **Import:** `@rangojs/router/testing/dom` · **DSL it tests:** a client component reading router context (see `/hooks`)
 
-RTL-style stub (peer of React Router's `createRoutesStub` / Expo's `renderRouter`). It mounts the router's REAL `NavigationProvider` plus a synthetic segment tree built from the `routes` you pass, so client hooks resolve against production context — no server, no Vite build, no Flight round-trip. Loader data, location state, and handle output are SEEDED into client context; nothing is executed.
+`renderRoute(routes, options?)` is an RTL-style stub (peer of React Router's `createRoutesStub` / Expo's `renderRouter`), and it is async — `await` it. It mounts the router's REAL `NavigationProvider` plus a synthetic segment tree built from the `routes` you pass, so client hooks resolve against production context — no server, no Vite build, no Flight round-trip. Loader data, location state, and handle output are SEEDED into client context; nothing is executed.
 
 ## API
 
@@ -25,7 +25,7 @@ RTL-style stub (peer of React Router's `createRoutesStub` / Expo's `renderRouter
 | `nonce`           | `string`                                                               | CSP nonce to seed via `NonceContext`, so a component calling `useNonce()` (e.g. an analytics/GTM head script) sees it — mirroring SSR. Defaults to `undefined` (the browser default).                                                         |
 | `defaultPrefetch` | `PrefetchStrategy`                                                     | Router default for `<Link>` and eligible plain anchors. `data-prefetch="false"`/`"none"` opts out one anchor; ancestor `data-prefetch-scope="false"`/`"none"` hard-disables the subtree; `"true"` permits routed resource suffixes elsewhere. |
 
-`RenderRouteSpec = { path, Component, layout?, loaderIds?, name? }` — one node of the route definition. The array is the layout chain root-to-leaf; the LAST entry is the leaf route (its pattern is matched against `request` to extract params; layout patterns are informational). `loaderIds` attaches seeded loaders to THIS node's segment; `layout` on the leaf wraps it; `name` is informational.
+`RenderRouteSpec = { path, Component, layout?, loaderIds?, name?, transition? }` — one node of the route definition. The array is the layout chain root-to-leaf; the LAST entry is the leaf route (its pattern is matched against `request` to extract params; layout patterns are informational). `loaderIds` attaches seeded loaders to THIS node's segment; `layout` on the leaf wraps it; `name` is informational. `transition` is the `transition()` config this node declares (`{}` for a bare `transition()`), attached to its segment exactly as the DSL does — see [Held navigation](#held-navigation).
 
 ### Context — client hooks it makes resolve (what your code receives)
 
@@ -40,7 +40,7 @@ RTL-style stub (peer of React Router's `createRoutesStub` / Expo's `renderRouter
 | `usePathname`                  | Current committed pathname.                                                                   |
 | `useSearchParams`              | Search params from the `request` URL.                                                         |
 | `useNonce`                     | SEEDED CSP nonce (`options.nonce`), else `undefined` (the browser default).                   |
-| `useLoader` / `useFetchLoader` | SEEDED loader data (read path, not run path).                                                 |
+| `useLoader` / `useFetchLoader` | SEEDED loader data (read path, not run path). Held-navigation `isLoading` is modeled (below). |
 | `useLocationState`             | SEEDED `history.state` value.                                                                 |
 | `useHandle`                    | SEEDED handle output (globally accumulated).                                                  |
 | `Outlet`                       | Renders the next segment in the chain (layout nesting).                                       |
@@ -54,7 +54,13 @@ Extends RTL's `RenderResult` (`getByTestId`, `getByText`, `getByRole`, `containe
 ```ts
 type RenderRouteResult = RenderResult & {
   router: {
-    navigate(url: string): Promise<void>; // client-only nav, re-resolves the same routes
+    // client-only nav, re-resolves the same routes; `loaders` seeds THIS nav
+    navigate(
+      url: string,
+      options?: {
+        loaders?: ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>;
+      },
+    ): Promise<void>;
     pathname(): string;
     params(): Record<string, string>;
     store: NavigationStore; // advanced
@@ -108,17 +114,64 @@ it("resolves params + reverse + Outlet through the layout chain", async () => {
 });
 ```
 
+## Held navigation
+
+A stale indicator driven by `useLoader().isLoading` (see `/hooks` data.md, "A held navigation flags the data it keeps on screen") IS unit-testable. Put `transition` on the spec that declares `transition()` in your `urls()`, and pass the next navigation's loader data to `router.navigate(url, { loaders })` as a PENDING Promise. navigate() then commits through production's `commitInTransition` (browser/partial-update.ts), which calls `loaderStore.announcePendingStreams` inside the `startTransition`. The harness does not fake the flag: React holds the reader on screen and the real `useLoader` pin reports `isLoading: true` until the promise settles.
+
+```tsx
+import { act } from "@testing-library/react";
+import { useLoader } from "@rangojs/router/client";
+import { ProductLoader } from "../loaders/product"; // path("/products/:id", ..., () => [loader(ProductLoader), transition()])
+
+function ProductPrice() {
+  const { data, isLoading } = useLoader(ProductLoader);
+  return (
+    <p data-testid="price" aria-busy={isLoading}>
+      {data.price}
+    </p>
+  );
+}
+
+it("dims the held price while the next product streams", async () => {
+  const { getByTestId, router } = await renderRoute(
+    [{ path: "/products/:id", Component: ProductPrice, transition: {} }],
+    { request: "/products/1", loaders: [[ProductLoader, { price: 10 }]] },
+  );
+
+  let resolve!: (value: { price: number }) => void;
+  const next = new Promise<{ price: number }>((r) => (resolve = r));
+  await router.navigate("/products/2", { loaders: [[ProductLoader, next]] });
+  expect(getByTestId("price").getAttribute("aria-busy")).toBe("true"); // old price, stale
+
+  await act(async () => resolve({ price: 12 })); // settle INSIDE act to flush the commit
+  expect(getByTestId("price").getAttribute("aria-busy")).toBe("false");
+  expect(getByTestId("price").textContent).toBe("12");
+});
+```
+
+| Pending state                                                                                  | Under `renderRoute`                                                                                                                                            |
+| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useLoader().isLoading` on the reader a `transition` navigate() holds, pending seed            | Modeled: `true` on the OLD data until the promise settles, then `false` with the new data in the same commit.                                                  |
+| `transition` navigate(), settled seed (a plain value)                                          | `false`; the data swaps in the commit.                                                                                                                         |
+| navigate() without `transition`, pending seed                                                  | Urgent commit (production's cold-navigation lane): the read suspends to the nearest `<Suspense>` fallback (with none, React keeps the previous tree). No flag. |
+| Production's other hold lanes (same-structure search/filter nav, fully-prefetched, optimistic) | NOT modeled — without `transition` navigate() stays urgent. Assert those at e2e.                                                                               |
+| `useNavigation().state`, `useLinkStatus().pending`, `useAction().state`                        | Stay `idle` — navigate() never starts the navigation lifecycle. e2e.                                                                                           |
+
+- Per-navigation seeds merge over the render-time `loaders`/`loaderData` for THAT navigation only; a later `navigate()` without `loaders` falls back to the render-time data.
+- Pass settled data as a plain value, not `Promise.resolve(value)`: React has not observed a plain promise yet, so it counts as pending and renders one `stale` frame. (A Flight chunk that has already settled carries its status and is skipped, which a plain value mirrors.)
+- `loading()` is not a spec field: a `<Suspense>` in your layout component stands in for it.
+
 ## Caveats
 
 - Client tree ONLY. Does NOT catch server/client boundary reference-identity remount bugs, real Flight serialization errors, loader execution, middleware, or handler ordering — those are `renderServerTree` / `renderHandler` / e2e territory. Loader data is SEEDED, never run.
-- `router.navigate()` bypasses the navigation lifecycle, so the controller never leaves `idle`. `useNavigation()` / `useLinkStatus()` / `useAction()` non-idle states (loading/streaming/pending, action result/error) are NOT reachable — test those at e2e.
+- `router.navigate()` bypasses the navigation lifecycle, so the controller never leaves `idle`. `useNavigation()` / `useLinkStatus()` / `useAction()` non-idle states (loading/streaming/pending, action result/error) are NOT reachable — test those at e2e. The one modeled pending state is held-navigation `useLoader().isLoading` ([Held navigation](#held-navigation)).
 - `outletPending` seeds only the production-shaped outlet context. It is useful
   for the two settled render states of a layout that reads `useOutlet()`, but it
   does not prove the hydrated `clientUrls()` transition that toggles the value;
   keep that transition in dev + production e2e.
 - CATCH — streaming `use(promise)` Suspense content (e.g. an async breadcrumb `content: Promise<ReactNode>`): a plain `Promise.resolve(node)` does NOT flush its Suspense retry in RTL/happy-dom, so the DOM stays on the fallback. Assert the PENDING fallback with `new Promise(() => {})`; for the ARRIVED state pass an already-settled promise so `use()` reads it synchronously: `const p = Promise.resolve(node) as any; p.status = "fulfilled"; p.value = node;`. The real pending->resolved transition is an e2e concern.
 - ARIA gotcha — an explicit `role` on a `<Link>` (e.g. `<Link role="tab">` in a tablist) OVERRIDES the implicit `link` role, so `getByRole("link")` finds nothing. Query the explicit role (`getByRole("tab")`) or fall back to `getByText` / `getByTestId` and assert `getAttribute("href")`.
-- `ctx.theme` is undefined unless `theme` is passed; the typed `ctx.search` defaults to `{}` (seed `searchData` on `runLoader`, not here).
+- `useTheme()` throws unless `theme` is passed (it needs the `ThemeProvider` that option mounts). Search state comes only from the `request` URL — there is no typed-search seed here (that is `runLoader`'s `searchData`).
 - Use `mount` only for an `include()` prefix. An OPTIONAL param in the matched pattern (`/:locale?/c/:group` at `/en/c/wine`) auto-fills `locale` from the match — production parity, `useReverse` merges `useParams()` — so no `mount` is needed; a locale "dropping" from a reversed URL is usually a missing `mount` seed, not an auto-fill gap.
 - Needs a DOM env (`// @vitest-environment happy-dom`, or jsdom) and `@testing-library/react` (optional peers).
 - Don't hand-roll a `NavigationProvider`/router-context mock to test a client component — `renderRoute` mounts the REAL provider, so a hand-mock both duplicates effort and drifts from the production context shape.

package/skills/testing/e2e-parity.md

@@ -16,7 +16,7 @@ This is full-stack: the harness builds and serves your real app (`pnpm dev` or `
 | `expect`      | `Expect`   | Your Playwright `expect` (used by helpers + matchers).                   |
 | `defaultRoot` | `string?`  | Fallback app root for `parityDescribe` when a call omits `options.root`. |
 
-### Fixture options — `FixtureOptions` (`useFixture` / `parityDescribe` 3rd arg)
+### Fixture options — `FixtureOptions` (`useFixture`; `parityDescribe`'s 3rd arg takes the same fields minus `mode`)
 
 | Field            | Type               | Meaning                                                                        |
 | ---------------- | ------------------ | ------------------------------------------------------------------------------ |
@@ -54,7 +54,17 @@ This is full-stack: the harness builds and serves your real app (`pnpm dev` or `
 - `expectParity(page, intent, opts) => Promise<void>` — runs `intent` over the JS page and a fresh no-JS context, asserts observed testids' text + pathname/search/hash + `document.cookie` are equal. `opts` is the required `observe` plus optional `baseURL`, `waitFor`, and `ignoreCookies` (the rango state cookie is excluded automatically).
 - `rangoMatchers` — `{ toHaveRangoPathname }` only (pass to `expect.extend`).
 - `testNoJs` — a `test` variant with JavaScript disabled.
-- Page helpers: `waitForHydration`, `expectNoReload`, `expectNoPageError`, `testId`, `waitForNavigation`, `waitForElement`, `goBack`/`goForward`, `getHistoryState`, `waitForTextChange`/`waitForNumericChange`, timing helpers.
+- Page helpers:
+  - navigation/state: `waitForHydration(page)`, `waitForNavigation(page, url)`, `goBack(page)` / `goForward(page)`, `getHistoryState(page)`;
+  - elements: `testId(page, id)`, `waitForElement`, `isVisibleInViewport`, `parseNumber(text)`, `getNumericContent(locator)`;
+  - assertions bound to your `expect`: `expectNoReload(page)` (use with `await using`), `expectNoPageError(page)` (use with `using`), `waitForTextChange`, `waitForNumericChange`;
+  - timing: `createStopwatch()`, `measureTime(fn)`, `expectTiming`, `expectMinTiming`, `expectMaxTiming`.
+
+The entry also exports standalone functions that are NOT on the factory result:
+
+- Prefetch control: `isPrefetchRequest(req)` (true for requests carrying `X-Rango-Prefetch`), `blockPrefetch(page)` / `unblockPrefetch(page)` (abort speculative prefetches — install before `page.goto` when a test needs the click's own navigation fetch, since a warmed Link adopts its prefetch and issues none).
+- The building blocks `createRangoE2E` composes: `createUseFixture(test)`, `createParity({ test, expect, useFixture, defaultRoot? })`, `createPageHelpers(expect)`, `createRangoMatchers(expect)`.
+- The cache/shell status helpers (`assertCacheStatus`, `assertShellStatus`, ... — see `./cache-prerender.md`), re-exported so a plain Playwright runner can use them.
 
 ## Recipe
 

package/skills/testing/flight.md

@@ -4,21 +4,24 @@
 
 > **Prefer `renderServerTree` (see [`./server-tree.md`](./server-tree.md)) for assertions on a Flight render** — it deserializes to a traversable tree with TYPED boundary props (a `Date` is a `Date`, not the opaque `$D...` encoding). Reach for `renderToFlightString` + the wire matchers (`toMatchFlight`/`toMatchFlightSnapshot`) only to pin the raw wire payload SHAPE — a `toMatchFlightSnapshot` drift snapshot. That is the niche/escape-hatch case; for "testing an async Server Component (assert what it rendered)" start at `./server-tree.md`.
 
-`renderToFlightString` runs the REAL react-server-dom serializer the router uses at runtime — your async Server Component genuinely renders to its Flight wire string in plain node, with a request context active for the render. What you SEED is the request, headers, env, params, routeName, and vars that context exposes.
+`renderToFlightString(element, opts?)` runs the REAL react-server-dom serializer the router uses at runtime — your async Server Component genuinely renders to its Flight wire string in plain node, with a request context active for the render. What you SEED is the request, headers, env, params, routeName, route map, vars, theme, and cache store that context exposes.
 
 ## API
 
 ### Options — `RenderToFlightStringOptions`
 
-| Field       | Type                     | Meaning                                                                                                                                                                                                                                                                      |
-| ----------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `request`   | `Request \| string`      | The request the render runs under: a `Request`, or a URL string (absolute or path). Defaults to `http://localhost/`. A component reading `getRequestContext()` sees this request's url/cookies. When a `Request` is passed, its headers are used and `headers` is ignored.   |
-| `headers`   | `HeadersInit`            | Request headers (e.g. Cookie) visible to the server tree, used only when `request` is a string.                                                                                                                                                                              |
-| `env`       | `unknown`                | Env / bindings exposed as `ctx.env`. Defaults to `{}`.                                                                                                                                                                                                                       |
-| `params`    | `Record<string, string>` | Route params exposed via `ctx.params` and loader contexts.                                                                                                                                                                                                                   |
-| `routeName` | `string`                 | Matched route name (drives `ctx.routeName` and scoped reverse).                                                                                                                                                                                                              |
-| `routeMap`  | `Record<string, string>` | Route name -> pattern map scoping `ctx.reverse()` (like `renderHandler`). Without it, a component that reverses resolves against the GLOBAL route map and is order-dependent on whatever router registered last. Pass the router-under-test's map for deterministic reverse. |
-| `vars`      | `VarsInit`               | Variables a prior middleware would have set, visible via `ctx.get(...)`. Object form (`{ user }`) or `[key, value]` tuples (`[[userVar, u]]`).                                                                                                                               |
+| Field           | Type                           | Meaning                                                                                                                                                                                                                                                                      |
+| --------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `request`       | `Request \| string`            | The request the render runs under: a `Request`, or a URL string (absolute or path). Defaults to `http://localhost/`. A component reading `getRequestContext()` sees this request's url/cookies. When a `Request` is passed, its headers are used and `headers` is ignored.   |
+| `headers`       | `HeadersInit`                  | Request headers (e.g. Cookie) visible to the server tree, used only when `request` is a string.                                                                                                                                                                              |
+| `env`           | `unknown`                      | Env / bindings exposed as `ctx.env`. Defaults to `{}`.                                                                                                                                                                                                                       |
+| `params`        | `Record<string, string>`       | Route params exposed via `ctx.params` and loader contexts.                                                                                                                                                                                                                   |
+| `routeName`     | `string`                       | Matched route name (drives `ctx.routeName` and scoped reverse).                                                                                                                                                                                                              |
+| `routeMap`      | `Record<string, string>`       | Route name -> pattern map scoping `ctx.reverse()` (like `renderHandler`). Without it, a component that reverses resolves against the GLOBAL route map and is order-dependent on whatever router registered last. Pass the router-under-test's map for deterministic reverse. |
+| `vars`          | `VarsInit`                     | Variables a prior middleware would have set, visible via `ctx.get(...)`. Object form (`{ user }`) or `[key, value]` tuples (`[[userVar, u]]`).                                                                                                                               |
+| `theme`         | `ThemeConfig \| true`          | Theme config (`createRouter({ theme })` shape). Without it `getRequestContext().theme` is `undefined` and `setTheme` is inert.                                                                                                                                               |
+| `cacheStore`    | `SegmentCacheStore`            | Store backing a `"use cache"` function the tree calls. Without it the cached path is bypassed (the function runs uncached).                                                                                                                                                  |
+| `cacheProfiles` | `Record<string, CacheProfile>` | Profiles for `"use cache: name"`, the `createRouter({ cacheProfiles })` shape. Pair with `cacheStore`.                                                                                                                                                                       |
 
 ### Context — `RequestContext` (what your component receives)
 
@@ -42,7 +45,12 @@ expect(await renderToFlightString(<C />)).toMatchFlight("substring"); // contain
 expect(await renderToFlightString(<C />)).toMatchFlightSnapshot();     // normalized snapshot
 ```
 
-`toMatchFlight(substring)` is containment (not equality) on the normalized payload; `toMatchFlightSnapshot()` snapshots the normalized payload. Both matchers live at `@rangojs/router/testing/flight-matchers` and run ONLY under the react-server vitest project (see `./setup.md`).
+`toMatchFlight(substring)` is containment (not equality) on the normalized payload; `toMatchFlightSnapshot()` snapshots the normalized payload. Both matchers live at `@rangojs/router/testing/flight-matchers`, which imports `vitest` but not the Flight serializer — so it also loads under the plain node condition (a shared `setupFiles` can `expect.extend(flightMatchers)` for both projects). The Flight strings they assert still come from `renderToFlightString`, which runs only under the react-server project (see `./setup.md`). Importing the entry also adds the matcher types to vitest's `Assertion`.
+
+### Helpers
+
+- `normalizeFlight(flight)` — the normalization both matchers apply: strips the dev-only leading `:N<timestamp>` row and rewrites absolute `file://` paths to `file://<path>`. Use it when asserting on the raw string yourself.
+- `assertFlightRuntimeAvailable()` — throws a descriptive error when the vendored react-server-dom serializer is missing (for example after a `@vitejs/plugin-rsc` upgrade moved it). Call it in a `beforeAll` to fail fast with a clear message.
 
 ## Recipe
 

package/skills/testing/handles.md

@@ -61,10 +61,10 @@ it("runs a custom 'last wins' collect", () => {
 ```ts
 // loader-reads-handle.test.ts — a loader reading accumulated handle data after the barrier
 import { it, expect } from "vitest";
-import { runLoader } from "@rangojs/router/testing";
+import { runLoader, type TestLoaderContext } from "@rangojs/router/testing";
 import { RenderedProducts } from "../src/handles"; // a createHandle(...)
 
-const livePricesBody = async (ctx) => {
+const livePricesBody = async (ctx: TestLoaderContext) => {
   await ctx.rendered(); // barrier: handle data is now readable
   const ids = ctx.get(RenderedProducts) as string[];
   return ids.map((id) => ({ id, price: 9.99 }));
@@ -85,10 +85,13 @@ it("reads the accumulated handle value (seed the OUTPUT, mock the barrier)", asy
 ```ts
 // loader-writes-handle.test.ts — a loader PUSHING meta/breadcrumbs (handler parity)
 import { it, expect } from "vitest";
-import { runLoaderResult } from "@rangojs/router/testing";
-import { Meta } from "../src/handles";
+import {
+  runLoaderResult,
+  type TestLoaderContext,
+} from "@rangojs/router/testing";
+import { Meta } from "@rangojs/router";
 
-const productBody = async (ctx) => {
+const productBody = async (ctx: TestLoaderContext) => {
   const product = { name: "Widget", slug: "widget" };
   ctx.use(Meta)({ title: `${product.name} — Shop` });
   return product;

package/skills/testing/loader.md

@@ -2,7 +2,7 @@
 
 **Layer:** unit (node) · **Import:** `@rangojs/router/testing` · **DSL it tests:** `loader()` (see `/loader`)
 
-`runLoader` runs a loader against a real `RequestContext` (cookies, headers, `ctx.get`, `ctx.reverse` all resolve) in plain node — that machinery is REAL; what you SEED is the params, env, vars, search, route map, and any `ctx.use` dependency data. Pass a registered `createLoader()` handle (its fn is recovered from the registry) or the raw async body `(ctx) => ...`.
+`runLoader(loader, opts?)` runs a loader against a real `RequestContext` (cookies, headers, `ctx.get`, `ctx.reverse` all resolve) in plain node — that machinery is REAL; what you SEED is the params, env, vars, search, route map, and any `ctx.use` dependency data. Pass a registered `createLoader()` definition (its fn is recovered from the registry) or the raw async body `(ctx) => ...`; type a raw body's argument as `TestLoaderContext` (exported from `@rangojs/router/testing`).
 
 ## API
 
@@ -27,6 +27,7 @@
 | `use`           | `UseResolver`                                                   | Dynamic resolver for `ctx.use(OtherLoader)` composition. `loaders` wins when both match.                                                                                                                                   |
 | `cacheStore`    | `SegmentCacheStore`                                             | Cache store backing `use cache` functions. Without one, a cached function bypasses and runs uncached (its taint/profile guards never fire).                                                                                |
 | `cacheProfiles` | `Record<string, CacheProfile>`                                  | Cache profiles, the `createRouter({ cacheProfiles })` shape.                                                                                                                                                               |
+| `cache`         | `PartialCacheOptions`                                           | Run the loader through the `cache()` a route binds it with (`loader(Loader, () => [cache({...})])` takes the same options), against `cache.store`, else `cacheStore`. See the caveat below.                                |
 | `stateCookie`   | `StateCookieSeed` (`{ prefix?, routerId?, version? }`)          | Customize the rango state cookie a loader calling `invalidateClientCache()` rotates (the name is always seeded — default `rango-state_router_0`).                                                                          |
 | `rendered`      | `boolean \| (() => void \| Promise<void>)`                      | Mock the `ctx.rendered()` render barrier so a loader that `await ctx.rendered()`s can be unit-tested. By default `ctx.rendered()` throws. `true` resolves immediately; a function controls timing/side effects.            |
 | `handles`       | `ReadonlyArray<readonly [Handle<any, any>, unknown]>`           | Seed the values `ctx.get(SomeHandle)` returns — the ACCUMULATED handle data read after `await ctx.rendered()`. Matched by handle reference. (Loader handle WRITES need no seed — see `runLoaderResult(...).handlePushes`.) |
@@ -51,7 +52,7 @@
 | `formData`         | `FormData \| undefined`                                                                   | Form data (from `opts.formData`).                                                                                                                                                                                                                   |
 | `reverse`          | `(name, params?, search?) => string`                                                      | Build a URL; throws unless `opts.routeMap` was passed.                                                                                                                                                                                              |
 | `rendered`         | `() => Promise<void>`                                                                     | The render barrier; throws by default, mocked via `opts.rendered`.                                                                                                                                                                                  |
-| `waitUntil`        | `(p: Promise<unknown>) => void`                                                           | Register background work (no-op accounting in tests).                                                                                                                                                                                               |
+| `waitUntil`        | `(fn: () => Promise<void>) => void`                                                       | Register background work; takes a function, not a promise (no-op accounting in tests).                                                                                                                                                              |
 | `executionContext` | `ExecutionContext \| undefined`                                                           | Platform execution context from the backing request; pairs with `waitUntil`.                                                                                                                                                                        |
 
 ### Returns — `Promise<T>`
@@ -70,8 +71,10 @@ order). `runLoader` discards those effects.
 ## Recipe
 
 ```ts
+import { it, expect } from "vitest";
 import { runLoader, runLoaderResult } from "@rangojs/router/testing";
 import { createLoader, createVar } from "@rangojs/router";
+import { AuthLoader } from "../src/loaders/auth"; // sets a `session` cookie, then throw redirect("/")
 
 const User = createVar<{ name: string }>();
 // The registered loader — no separate body export needed for testability:
@@ -100,7 +103,6 @@ it("builds a self link via reverse", async () => {
 });
 
 it("asserts a loader's set-cookie + redirect (runLoaderResult)", async () => {
-  // AuthLoader validates, sets a `session` cookie, then `throw redirect("/")`.
   const { thrown, response, cookies } = await runLoaderResult(AuthLoader, {
     request: new Request("https://app.test/login?token=ok"),
   });
@@ -115,12 +117,30 @@ it("asserts a loader's set-cookie + redirect (runLoaderResult)", async () => {
 ## Caveats
 
 - `ctx.reverse(...)` throws unless you pass `routeMap` (and `routeName` for scoped `.name` resolution). It does NOT fall back to the global route map.
-- `ctx.rendered()` throws by default (the render barrier only exists in a full match); pass `{ rendered: true }` to mock it for post-barrier logic, and `{ handles: [[SomeHandle, data]] }` to seed the `ctx.get(SomeHandle)` read. `ctx.isAction(...)` is unavailable — cover those at e2e.
+- `ctx.rendered()` throws by default (the render barrier only exists in a full match); pass `{ rendered: true }` to mock it for post-barrier logic, and `{ handles: [[SomeHandle, data]] }` to seed the `ctx.get(SomeHandle)` read.
+- A loader has no `isAction()`: whether it re-runs after an action is decided by `revalidate()` on its registration, not inside the loader body. Assert post-action re-runs at e2e.
 - Seeded `loaders` (by-reference tuples) are NOT executed — `ctx.use(OtherLoader)` returns the seeded value. The dynamic `use` resolver, by contrast, IS executed (it is a function called to compute the value). Either way the REAL loader body is not run; real loader execution and side-effects are e2e-only. `loaders` is checked before the `use` resolver.
-- A handle imported through the CLIENT build has its body dropped — `runLoader` throws a clear error pointing to the `rangoTestConfig()` preset or the raw body. A router using `Prerender()`/`createLoader()`/`Static()` now constructs in a bare test (each assigns a runtime fallback `$$id`); only the whole router _file_ may still need the plugin (its page modules pull app deps / `virtual:` modules).
+- A `createLoader()` definition imported through the CLIENT build has its body dropped — `runLoader` throws a clear error pointing to the `rangoTestConfig()` preset or the raw body. A router using `Prerender()`/`createLoader()`/`Static()` now constructs in a bare test (each assigns a runtime fallback `$$id`); only the whole router _file_ may still need the plugin (its page modules pull app deps / `virtual:` modules).
 - No `cookies`/`headers` option: seed a cookie by passing a full Request with a Cookie header — `{ request: new Request(url, { headers: { Cookie: "sid=abc" } }) }`. (`search`/`method` are baked onto this request for you.)
 - `ctx.search` (typed) defaults to `{}`; `opts.search` only sets the raw `ctx.searchParams`. Seed the typed object with `searchData`. (The harness seeds `searchData` verbatim — it does NOT run a typed-search SCHEMA, so schema parsing/validation is e2e.)
-- `ctx.theme`/`ctx.setTheme` are NOT on the loader context — theme accessors are handler-only. (The `theme` option seeds the underlying request context for `use cache` theme resolution, but a loader body cannot read theme.) `redirect()` does no basename prefixing unless you seed `basename`.
+- `ctx.theme`/`ctx.setTheme` are NOT on the loader context — they are handler/middleware-only. The `theme` option seeds the request context's theme config, so a loader body reads the visitor's theme with `getRequestContext().theme` (seed the cookie through `request`). That read is guarded like `cookies()` (#971): allowed in a loader body, but it throws inside a `"use cache"` function. `redirect()` does no basename prefixing unless you seed `basename`.
+- A `"use cache"` hit needs real Flight, which loads only under the react-server condition. In the react-server project (a `*.rsc-test.ts` file, see [`./setup.md`](./setup.md)) with `cacheStore` seeded, the body runs once across `runLoader` calls and the value round-trips. The write is a background (`waitUntil`) task `runLoader` does not await: a call before it lands joins the still-running execution, a call after it reads the store (wait with `vi.waitFor` on a `cacheStore.setItem` spy). In the node project a call looks up the store but never writes, so every call runs the body. A function written with the directive needs `rangoUseCacheTransform()` in the project's `plugins` (see [`./render-handler.md`](./render-handler.md#a-use-cache-hit)).
+- The `cache` option runs the loader through the production loader-cache read-through, so it needs the react-server project for the same reason. A HIT returns the stored value without running the body and records the tags the body recorded when the entry was written, so `updateTag()` of one (inside `runInRequestContext(fn, { cacheStore })`) drops the entry. There is no in-flight join here: wait for the write before the next call, or that call misses too. A raw body is keyed by its function reference. `runLoaderResult(...).handlePushes` lists the body's pushes, so a HIT reports none (the replay into the page's handle store is not modeled).
+
+  ```ts
+  const load = () =>
+    runLoader(productLoader, {
+      params: { id: "1" },
+      cacheStore,
+      cache: { ttl: 300 },
+    });
+  await load(); // MISS: the body runs and calls cacheTag("product:1")
+  await vi.waitFor(() => expect(setItem).toHaveBeenCalledTimes(1));
+  await load(); // HIT: the body does not run
+  await runInRequestContext(() => updateTag("product:1"), { cacheStore });
+  await load(); // MISS again
+  ```
+
 - Platform bindings are yours to double via `env` (see `./bindings.md`).
 
 ## See also

package/skills/testing/middleware.md

@@ -2,14 +2,17 @@
 
 **Layer:** unit (node) · **Import:** `@rangojs/router/testing` · **DSL it tests:** `middleware()` (see `/middleware`)
 
-`runMiddleware` executes your chain through the router's REAL `executeLoaderMiddleware`, so `next()`, return-Response and throw-Response short-circuits, double-next guards, and header/cookie merge are production-identical. You SEED the request and any prior-middleware state (`vars`, `params`, `env`, `routeMap`); everything else (cookie/header merge, request-context resolution) is real machinery.
+`runMiddleware(mw | mw[], opts)` executes your chain through the router's REAL `executeLoaderMiddleware`, so `next()`, return-Response and throw-Response short-circuits, double-next guards, and header/cookie merge are production-identical. You SEED the request and any prior-middleware state (`vars`, `params`, `env`, `routeMap`); everything else (cookie/header merge, request-context resolution) is real machinery.
 
 ## API
 
 ### Options — `RunMiddlewareOptions<TEnv>`
 
+`opts` is a required argument (unlike `runLoader`); pass `{}` when you need no seeds.
+
 | Field           | Type                                                   | Meaning                                                                                                                                                                                                                                                                               |
 | --------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `build`         | `boolean`                                              | Seed `ctx.build` (default `false`) to test a middleware that branches on the build-time PPR shell-capture pass (e.g. `if (ctx.build) ctx.dynamic()`). With `true`, `ctx.waitUntil()` is inert, as at build time. Assert the opt-out via `result.dynamic`.                             |
 | `request`       | `Request \| string`                                    | The request the chain runs under: a `Request`, or a URL string (absolute or path). Optional — defaults to `http://localhost/`; pass it for path-, header-, or cookie-driven middleware.                                                                                               |
 | `env`           | `TEnv`                                                 | Environment bindings surfaced as `ctx.env`. Your seam for doubling platform bindings (see `./bindings.md`).                                                                                                                                                                           |
 | `params`        | `Record<string, string>`                               | Route params surfaced as `ctx.params`.                                                                                                                                                                                                                                                |
@@ -33,10 +36,11 @@ The `ctx` your middleware reads. Notable fields:
 | `env`                       | `TEnv`                  | Bindings from `opts.env`.                                                          |
 | `get` / `set`               | fns                     | Read/write context vars (shared with handlers); `get` resolves what `vars` seeded. |
 | `header(name, value)`       | fn                      | Queue a response header before `next()`, or set it directly after.                 |
-| `reverse`                   | `ScopedReverseFunction` | URL-from-name. Map-only (no auto-fill); needs `routeMap`.                          |
+| `reverse`                   | `GlobalReverseFunction` | Global names only: no auto-fill, `.name` is a type error. Needs `routeMap`.        |
 | `setLocationState(entries)` | fn                      | Attach flash/location state to the response.                                       |
 | `theme` / `setTheme`        | `Theme` / fn            | Current theme; `undefined` unless `theme` is passed.                               |
 | `routeName`                 | `string`                | Matched route name (from `opts.routeName`).                                        |
+| `build` / `dynamic()`       | `boolean` / fn          | Build-pass flag (from `opts.build`) and the PPR shell opt-out (`result.dynamic`).  |
 
 ### Returns — `RunMiddlewareResult<TEnv>`
 
@@ -45,6 +49,7 @@ The `ctx` your middleware reads. Notable fields:
 | `response`        | `Response`                | The final Response: the downstream response, or a middleware short-circuit.                                                                                                                                                                                  |
 | `ctx`             | `RequestContext<TEnv>`    | The underlying RequestContext (NOT a per-middleware `MiddlewareContext`). Use `ctx.get(...)` for anything the envelope above doesn't surface.                                                                                                                |
 | `nextCalled`      | `number`                  | Times the terminal handler ran: `0` on short-circuit, `1` on pass-through.                                                                                                                                                                                   |
+| `dynamic`         | `boolean`                 | Whether the chain called `ctx.dynamic()` (the PPR shell opt-out).                                                                                                                                                                                            |
 | `cookies`         | `Record<string, string>`  | Effective cookie view: request cookies merged with chain sets/deletes (last-write-wins), as `{ name: value }`.                                                                                                                                               |
 | `headers`         | `Record<string, string>`  | Final response headers as `{ name: value }`, lowercased, EXCLUDING `set-cookie` (use `cookies`).                                                                                                                                                             |
 | `locationState`   | `Record<string, unknown>` | Flat `{ key: value }` state set via `setLocationState()` / `redirect({ state })` (empty when none).                                                                                                                                                          |
@@ -88,7 +93,7 @@ Pass an array to run several in order. Cookies set inside middleware via the sta
 
 - No `handles`/`rendered` option by design: the middleware context has no handle APIs in production — no push (`ctx.use(Handle)` is a handler/loader API) and no post-barrier read (`ctx.get(handle)` is loader-only, and middleware runs BEFORE the render barrier anyway). Read handle data in a loader and test it with `runLoader`; assert loader pushes via `runLoaderResult(...).handlePushes` (see `./handles.md`).
 - A COMPONENT route's guard stack cannot be exercised through `dispatch` (it throws on component routes), and `renderToFlightString`/`renderRoute` don't run route middleware. Extract the middleware fn and unit-test it here, or assert the guard stack at e2e.
-- Middleware-phase `ctx.reverse` is map-only (no auto-fill from current params), matching production — enable it with `routeMap`. `routeName` only feeds `ctx.routeName`; it does NOT scope `.name` reverse (the chain reverse stays map-only by design).
+- Middleware-phase `ctx.reverse` is map-only (global names only, no auto-fill from current params), matching production — enable it with `routeMap`. `routeName` only feeds `ctx.routeName`; it does NOT scope `.name` reverse (the chain reverse stays map-only by design, and `MiddlewareContext["reverse"]` rejects `.name` at compile time).
 - `ctx.theme` is `undefined` unless `theme` is passed; `redirect()` does no basename prefixing unless `basename` is seeded.
 - Platform bindings are yours to double via `env` (see `./bindings.md`).