@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.140

package/skills/testing/SKILL.md

@@ -1,226 +1,130 @@
 ---
 name: testing
-description: Unit test route trees with buildRouteTree()
-argument-hint:
+description: Test @rangojs/router apps — unit (loaders/middleware/reverse/components), integration (dispatch/Flight), and e2e (dev+prod parity, progressive enhancement)
+argument-hint: [layer]
 ---
 
-# Route Tree Unit Testing
-
-Unit test route definitions by inspecting the route tree, segment IDs, middleware, intercepts, loaders, and pattern matching without running a dev server.
-
-## Setup
-
-The `buildRouteTree` helper lives in `src/__tests__/helpers/route-tree.ts` (not shipped with npm). Import it in your test files:
-
-```typescript
-import { buildRouteTree } from "./helpers/route-tree.js";
-```
-
-## buildRouteTree(urlPatterns)
-
-Takes a `urls()` result and returns a `RouteTree` with inspection methods:
-
-```typescript
-import { urls } from "@rangojs/router";
-import { buildRouteTree } from "./helpers/route-tree.js";
-
-const tree = buildRouteTree(
-  urls(({ path, layout, middleware, loader, intercept, when }) => [
-    layout(RootLayout, () => [
-      middleware(authMiddleware),
-      path("/", HomePage, { name: "home" }),
-      path("/blog/:slug", BlogPost, { name: "blog.post" }, () => [
-        loader(PostLoader),
-      ]),
-    ]),
-  ])
-);
-```
-
-## RouteTree API
-
-### Route Patterns
-
-```typescript
-tree.routes()       // { home: "/", "blog.post": "/blog/:slug" }
-tree.routeNames()   // ["home", "blog.post"]
-```
-
-### URL Matching
-
-```typescript
-const m = tree.match("/blog/hello");
-m.routeKey  // "blog.post"
-m.params    // { slug: "hello" }
-
-tree.match("/nonexistent")  // null
-```
-
-### Segment IDs
-
-```typescript
-tree.segmentId("home")       // "M0L0L0R0"
-tree.segmentIds()            // { home: "M0L0L0R0", "blog.post": "M0L0L0R1" }
-tree.segmentPath("blog.post")
-// [
-//   { id: "M0L0",     type: "layout" },  // synthetic root
-//   { id: "M0L0L0",   type: "layout" },  // RootLayout
-//   { id: "M0L0L0R1", type: "route", pattern: "/blog/:slug" },
-// ]
-```
-
-### Entry Access
-
-```typescript
-tree.entry("blog.post")                   // EntryData
-tree.entry("blog.post")!.parent!.type     // "layout"
-tree.entryByPattern("/blog/:slug")        // EntryData (lookup by URL pattern)
-```
-
-### Middleware
-
-```typescript
-tree.hasMiddleware("home")                // true (inherited from layout)
-tree.middleware("home")                   // [authMiddleware] (direct only)
-tree.middlewareChain("home")
-// [{ segmentId: "M0L0L0", count: 1 }]   // all middleware root-to-route
-```
-
-### Loaders
-
-```typescript
-tree.hasLoaders("blog.post")  // true
-tree.loaders("blog.post")     // [LoaderEntry { loader, revalidate, cache? }]
-```
-
-### Intercepts
-
-```typescript
-tree.intercepts("home")
-// [{ slotName: "@modal", routeName: "card", hasWhen: true, whenCount: 1, hasLoader: false, hasMiddleware: false }]
-tree.interceptEntries("home")  // raw InterceptEntry[]
-```
-
-### Parallel Slots
-
-```typescript
-tree.parallelSlots("home")       // EntryData[] of type="parallel"
-tree.parallelSlotNames("home")   // ["@sidebar", "@main"]
-```
-
-### Boundaries
-
-```typescript
-tree.hasErrorBoundary("home")      // boolean
-tree.hasNotFoundBoundary("home")   // boolean
-```
-
-### Cache & Loading
-
-```typescript
-tree.hasCache("home")     // boolean
-tree.hasLoading("home")   // boolean
-```
-
-### Debug
-
-```typescript
-console.log(tree.debug());
-// Route Tree:
-//   home: / [M0L0L0R0] (M0L0 > M0L0L0 > M0L0L0R0) {mw:1}
-//   blog.post: /blog/:slug [M0L0L0R1] (M0L0 > M0L0L0 > M0L0L0R1) {mw:1, ld:1}
-```
-
-## Segment ID Format
-
-| Prefix | Meaning |
-|--------|---------|
-| `M0`   | Mount index (router instance) |
-| `L`    | Layout |
-| `R`    | Route |
-| `P`    | Parallel slot |
-| `D`    | Loader (data) |
-| `C`    | Cache boundary |
-
-Example: `M0L0L0R1` = mount 0, synthetic root layout, user layout, second route.
-
-## Examples
-
-### include() with prefix
-
-```typescript
-const blogPatterns = urls(({ path }) => [
-  path("/", BlogIndex, { name: "index" }),
-  path("/:slug", BlogPost, { name: "post" }),
-]);
-
-const tree = buildRouteTree(
-  urls(({ path, include }) => [
-    path("/", HomePage, { name: "home" }),
-    include("/blog", blogPatterns, { name: "blog" }),
-  ])
-);
-
-expect(tree.routes()).toEqual({
-  home: "/",
-  "blog.index": "/blog",
-  "blog.post": "/blog/:slug",
-});
-```
-
-### Middleware chain
-
-```typescript
-const authMw = async (ctx, next) => next();
-const logMw = async (ctx, next) => next();
-
-const tree = buildRouteTree(
-  urls(({ path, layout, middleware }) => [
-    layout(RootLayout, () => [
-      middleware(logMw),
-      layout(AuthLayout, () => [
-        middleware(authMw),
-        path("/dashboard", Dashboard, { name: "dashboard" }),
-      ]),
-    ]),
-  ])
-);
-
-expect(tree.middlewareChain("dashboard")).toEqual([
-  { segmentId: "M0L0L0", count: 1 },   // logMw on RootLayout
-  { segmentId: "M0L0L0L0", count: 1 }, // authMw on AuthLayout
-]);
-```
-
-### Intercepts with when()
-
-```typescript
-const tree = buildRouteTree(
-  urls(({ path, layout, intercept, when }) => [
-    layout(ShopLayout, () => [
-      path("/products", ProductList, { name: "products" }),
-      path("/products/:id", ProductDetail, { name: "product.detail" }),
-      intercept("@modal", "product.detail", ProductModal, () => [
-        when((ctx) => ctx.from.pathname.startsWith("/products")),
-      ]),
-    ]),
-  ])
-);
-
-const intercepts = tree.intercepts("products");
-// Note: intercepts are on the parent where intercept() is called
-```
-
-### Constrained parameters
-
-```typescript
-const tree = buildRouteTree(
-  urls(({ path }) => [
-    path("/:locale(en|fr)?/about", AboutPage, { name: "about" }),
-  ])
-);
-
-expect(tree.match("/about")).not.toBeNull();
-expect(tree.match("/fr/about")!.params).toEqual({ locale: "fr" });
-expect(tree.match("/de/about")).toBeNull();
-```
+# Testing @rangojs/router apps
+
+Rango ships six consumer-facing testing entries, one per test runtime/dependency:
+`@rangojs/router/testing` (unit + integration, under a Vite-driven Vitest
+project), `@rangojs/router/testing/vitest` (the `rangoTestConfig`/`rangoTestAliases`
+setup preset), `@rangojs/router/testing/dom` (`renderRoute`, needs RTL + a DOM
+env), `@rangojs/router/testing/e2e` (the Playwright harness),
+`@rangojs/router/testing/flight` (real Flight, react-server condition only), and
+`@rangojs/router/testing/flight-matchers` (the Flight matchers).
+
+The hard problem in an RSC app is that the layer you reach for is dictated by
+**what the behavior touches** — a pure predicate is a one-line vitest test; a real
+async Server Component cannot be a plain node test at all. Pick the layer
+**first**, then the primitive. Reaching one layer too high (e2e for a reverse
+function) is slow; one too low (a node test for Flight) fails to compile or
+silently asserts nothing.
+
+This page is the router. Each primitive's full API (options, the seeded context
+your code receives, the return shape), a minimal recipe, and its caveats live in a
+dedicated sub-file linked from the decision tree below. Read the one for your case.
+
+> **Setup is the first wall.** The vitest projects, the `rangoTestConfig` vs
+> `rangoTestAliases` choice (Node >= 23), and the react-server `@rangojs/router ->
+index.rsc.ts` alias are all in [`./setup.md`](./setup.md). Read it before writing
+> `vitest.config.ts`. Platform bindings (`env.DB`/DO/R2) are your own double —
+> [`./bindings.md`](./bindings.md).
+
+For the long-form prose guide (setup walkthrough + migration), see
+[`docs/testing.md`](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md)
+(the `docs/` directory is not shipped in the published package, so this is an
+absolute link).
+
+## When to use
+
+Use this skill when adding or changing tests for a Rango app: a loader,
+middleware, a server action, a route map, a client component, a response route,
+cache/SWR behavior, prerender, or a navigation/PE flow.
+
+Two non-negotiable mandates (from the repo's `CLAUDE.md`, and they apply to
+consumer apps too):
+
+- **Every e2e covers BOTH dev and production.** A dev-only e2e is not acceptable.
+  Use `parityDescribe` — it generates the dev and production describes from one
+  body, so you cannot forget the prod half. See [`./e2e-parity.md`](./e2e-parity.md).
+- **Progressive-enhancement parity** is a first-class assertion. A form-driven
+  flow must produce the same observable result with JS on and JS off. Use
+  `expectParity`.
+
+## The read-first shape
+
+Four import roots, each matched to the dependency/runtime that can load it — this
+split is forced by hard walls, not preference:
+
+- `@rangojs/router/testing` — unit + integration primitives. Run these under a
+  **Vite-driven Vitest** project with the rango Vite plugin active (the router
+  internals import the `@rangojs/router:version` virtual; without the plugin, the
+  preset stubs it). References neither React, RTL, Playwright, nor the RSC runtime.
+- `@rangojs/router/testing/dom` — `renderRoute` (the RTL component stub). Kept
+  separate so the unit barrel stays free of React/RTL; it lazy-loads
+  `@testing-library/react` and needs a DOM env (happy-dom/jsdom).
+- `@rangojs/router/testing/e2e` — the Playwright harness. Kept separate so it
+  loads in a plain (non-Vite) Playwright runner; the helpers take your
+  `test`/`expect`, so this entry never imports `@playwright/test` at runtime.
+- `@rangojs/router/testing/flight` — real Flight rendering. Its serializer loads
+  only under the `react-server` node condition; pulling it elsewhere throws.
+
+The single rule that drives everything:
+
+> **If the behavior needs a real Flight render, it cannot be a plain vitest node
+> test.** It is either `renderToFlightString`/`renderServerTree`/`renderHandler`
+> (under the react-server vitest project) or an e2e test. There is no middle
+> ground in node.
+
+## Decision tree: behavior -> layer -> primitive
+
+Each primitive links to its sub-file (API + recipe + caveats).
+
+| The behavior is…                                                                                                                   | Layer        | Primitive                                                                                     | Import root                      |
+| ---------------------------------------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------- | -------------------------------- |
+| a pure function / `reverse` / `href` / a predicate (`revalidate`, `isAction`)                                                      | unit + types | [`reverse`/`@ts-expect-error`](./reverse-and-types.md)                                        | `@rangojs/router/testing`        |
+| one loader's data logic                                                                                                            | unit (node)  | [`runLoader`](./loader.md)                                                                    | `@rangojs/router/testing`        |
+| a loader's cookie / header / redirect output (auth-loader pattern)                                                                 | unit (node)  | [`runLoaderResult`](./loader.md)                                                              | `@rangojs/router/testing`        |
+| one middleware's ordering / short-circuit / cookie+header merge                                                                    | unit (node)  | [`runMiddleware`](./middleware.md)                                                            | `@rangojs/router/testing`        |
+| a `"use server"` action's cookie / header / flash output (even on `throw redirect()`)                                              | unit (node)  | [`runInRequestContext`](./server-actions.md)                                                  | `@rangojs/router/testing`        |
+| a `transition({ when })` gate (keep/drop) against nav source / target / action metadata                                            | unit (node)  | `runTransitionWhen` (`{ kept, whenContext }`)                                                 | `@rangojs/router/testing`        |
+| a handle's `collect`/accumulator, or a seeded handle read                                                                          | unit         | [`collectHandle` / seeded `handles`](./handles.md)                                            | `@rangojs/router/testing`        |
+| a CLIENT component reading router context (`useParams`/`useReverse`/`Outlet`/`useNavigation`/`useLoader`)                          | unit (DOM)   | [`renderRoute`](./client-components.md)                                                       | `@rangojs/router/testing/dom`    |
+| a redirect / status / headers / cookies / **response route** (json/text/html/xml/md), no Flight                                    | integration  | [`dispatch`](./response-routes.md)                                                            | `@rangojs/router/testing`        |
+| a real async **Server Component** (assert what it rendered: typed boundary props, server-rendered host content, inlined-vs-island) | RSC unit     | [`renderServerTree` + `findClientBoundaries`/`findElements`](./server-tree.md)                | `@rangojs/router/testing/flight` |
+| the exact Flight **wire payload** shape (a drift snapshot)                                                                         | RSC unit     | [`renderToFlightString` + `toMatchFlightSnapshot`](./flight.md)                               | `@rangojs/router/testing/flight` |
+| a real route **handler** `(ctx) => rsc` (params/loaders/vars -> rendered RSC + effects)                                            | RSC unit     | [`renderHandler`](./render-handler.md)                                                        | `@rangojs/router/testing/flight` |
+| navigation, hydration, PE parity, view transitions, real SSR                                                                       | e2e          | [`createRangoE2E` -> `parityDescribe`/`expectParity`](./e2e-parity.md)                        | `@rangojs/router/testing/e2e`    |
+| cache hit/miss/stale, prerender (= a cache hit by design)                                                                          | e2e + signal | [`assertCacheStatus` (header) / `assertCacheDecision` (telemetry sink)](./cache-prerender.md) | `@rangojs/router/testing[/e2e]`  |
+| generated route map drift vs runtime                                                                                               | unit (node)  | [`assertGeneratedRoutesMatch`](./reverse-and-types.md)                                        | `@rangojs/router/testing`        |
+| a platform binding (`env.DB` / Durable Object / `env.R2`)                                                                          | unit/integr. | [your own double via `env`](./bindings.md)                                                    | (any primitive's `env` option)   |
+
+Cross-references to the DSL skills: `/loader`, `/middleware`, `/server-actions`,
+`/handler-use`, `/hooks`, `/response-routes`, `/route`, `/caching`, `/prerender`,
+`/typesafety`.
+
+## Sub-files
+
+- Cross-cutting: [`setup.md`](./setup.md), [`bindings.md`](./bindings.md)
+- Unit (node): [`loader.md`](./loader.md), [`middleware.md`](./middleware.md),
+  [`server-actions.md`](./server-actions.md), [`handles.md`](./handles.md),
+  [`reverse-and-types.md`](./reverse-and-types.md)
+- Unit (DOM): [`client-components.md`](./client-components.md)
+- RSC unit: [`flight.md`](./flight.md), [`server-tree.md`](./server-tree.md),
+  [`render-handler.md`](./render-handler.md)
+- Integration: [`response-routes.md`](./response-routes.md)
+- E2E: [`e2e-parity.md`](./e2e-parity.md), [`cache-prerender.md`](./cache-prerender.md)
+
+## Pre-push checklist (mirror CLAUDE.md)
+
+Before pushing, run all of these and fix any failure:
+
+1. `pnpm run typecheck` (or `pnpm exec tsc --noEmit`)
+2. `pnpm run test:unit` (node + DOM vitest)
+3. `pnpm run test:unit:rsc` (the react-server Flight project)
+4. `pnpm run lint`
+5. `pnpm run format`
+
+And: **every e2e has a production counterpart.** `parityDescribe` makes this
+automatic — if you wrote a plain `test.describe` for a behavior, convert it.

package/skills/testing/bindings.md

@@ -0,0 +1,103 @@
+# Testing platform bindings — your double is the seam
+
+**Layer:** cross-cutting (unit/integration) · **Seam:** the `env` option every primitive takes
+
+The node primitives test the router's seams; the moment your loader/middleware/action calls a **platform binding** (`env.DB`, a Durable Object stub, `env.R2`), you have crossed out of rango and into your app's I/O. The router machinery is real — what you seed is the binding double behind it, injected through `env`.
+
+## Where it plugs in
+
+rango ships **no doubles** for platform bindings — they are app- and schema-specific. You build the double and inject it through the `env` option that every primitive already accepts:
+
+- `runLoader(body, { env })`
+- `runMiddleware(fn, { request, env })`
+- `runInRequestContext(fn, { request, env })`
+- `renderHandler(handler, { request, env })`
+- `dispatch(router, { request, env })`
+- `renderToFlightString(el, { env })`
+
+Inside the run, `getRequestContext().env` (and anything that reads it — `cache()`, your loaders, your middleware) sees the object you passed.
+
+## Driver contract
+
+The work here is matching the binding's **driver contract**, not its public API. A double that satisfies the public surface but not the driver's wire shape mounts green and proves nothing.
+
+- **Per-method shapes.** `drizzle-orm/d1` serves SELECTs through `.raw()` and writes (INSERT/UPDATE/DELETE) through `.run()`. The two return different shapes and hit different code paths in the decoder. Model **both**.
+- **`.raw()` (reads).** Must serve **positional row arrays in schema-column order**, with the driver-level encodings so the decoder round-trips `Date`/JSON. NOT `{ column: value }` objects.
+- **`.run()` (writes).** Returns `{ success, meta }` — no rows — and bypasses the row responder entirely.
+
+## Recipe
+
+```ts
+import { describe, it, expect } from "vitest";
+import {
+  runLoader,
+  runMiddleware,
+  runInRequestContext,
+} from "@rangojs/router/testing";
+import { bundleLoaderBody } from "../app/loaders";
+import { requireMembership } from "../app/middleware";
+import { authorizeAction } from "../app/actions";
+
+// A D1Database double satisfying drizzle-orm/d1's driver contract.
+// rango ships no double for D1 — build your own to match the driver.
+const fakeD1 = {
+  prepare: () => ({
+    // .raw() serves positional rows in schema-column order, driver-encoded.
+    raw: async () => [[1, "acme", "2026-01-01T00:00:00.000Z"]],
+    // .run() returns { success, meta }, no rows.
+    run: async () => ({ success: true, meta: { changes: 1 } }),
+    all: async () => ({ results: [], success: true, meta: {} }),
+    first: async () => null,
+    bind: (..._args: unknown[]) => ({
+      raw: async () => [[1, "acme", "2026-01-01T00:00:00.000Z"]],
+      run: async () => ({ success: true, meta: { changes: 1 } }),
+      all: async () => ({ results: [], success: true, meta: {} }),
+      first: async () => null,
+    }),
+  }),
+  batch: async (stmts: unknown[]) =>
+    stmts.map(() => ({ results: [], success: true, meta: {} })),
+  exec: async (_sql: string) => ({ count: 0, duration: 0 }),
+};
+
+describe("bindings seam", () => {
+  it("loader reads through env.DB", async () => {
+    const result = await runLoader(bundleLoaderBody, { env: { DB: fakeD1 } });
+    expect(result).toMatchObject({ slug: "acme" });
+  });
+
+  it("middleware reads through env.DB", async () => {
+    const { nextCalled, response } = await runMiddleware(requireMembership, {
+      request: "/t/acme/edit",
+      env: { DB: fakeD1 },
+    });
+    expect(nextCalled).toBe(1); // membership passed, chain continued
+    expect(response.status).toBe(200);
+  });
+
+  it("action reads through env.DB", async () => {
+    const { result } = await runInRequestContext(
+      () => authorizeAction({ id: 1 }),
+      {
+        env: { DB: fakeD1 },
+        request: "/t/acme/edit",
+      },
+    );
+    expect(result).toBe(true);
+  });
+});
+```
+
+## Caveats
+
+- rango ships **no doubles** for platform bindings (`env.DB`, Durable Objects, `env.R2`) by design — they are app- and schema-specific. Inject your own double through the `env` option every primitive takes.
+- This is usually the **single biggest effort** in a consumer unit suite, and the work is matching the **driver contract**, not the binding's public API.
+- `drizzle-orm/d1`: a `D1Database` double must serve **positional row arrays in schema-column order** for drizzle's `.raw()` path (with driver-level encodings so the decoder round-trips `Date`/JSON), NOT `{ column: value }` objects — an object-shaped double returns silently-wrong or empty rows.
+- The contract is **per-method**: SELECTs go through `.raw()` (positional rows); writes (INSERT/UPDATE/DELETE) go through `.run()`, which returns `{ success, meta }` (no rows) and bypasses the row responder entirely. Model **both** paths — a read-only `.raw()` double silently no-ops every write.
+- Keep the double at the **binding boundary**; never mock a rango primitive to dodge building it.
+
+## See also
+
+- (cross-cutting)
+- Siblings: `./loader.md`, `./middleware.md`, `./server-actions.md`
+- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "What these primitives deliberately don't cover (the platform-bindings paragraph)"

package/skills/testing/cache-prerender.md

@@ -0,0 +1,127 @@
+# Testing cache / SWR / prerender — assertCacheStatus
+
+**Layer:** e2e + signal · **Import:** the cache-status helpers (`assertCacheStatus`/`parseCacheHeader`/`createCacheSink`/`assertCacheDecision`/`filterCacheDecisions`) are re-exported from BOTH entries — use `@rangojs/router/testing` from a Vitest unit/integration test, and `@rangojs/router/testing/e2e` from a plain Playwright runner (the e2e barrel avoids the Vite-only virtuals the main barrel pulls in). · **DSL it tests:** `cache()` / `"use cache"` / loader cache / `Prerender(...)` (see `/caching`, `/prerender`, `/use-cache`)
+
+The router's REAL cache pipeline runs (runtime cache, SWR revalidation, prerender lookup); you SEED nothing — you drive a request through the real fetch path and read the resulting cache decision. The decision surfaces two ways: the `X-Rango-Cache` response header (a debug gate) or a captured `cache.decision` telemetry event.
+
+## Which path to use
+
+Both report the SAME coarse route-level signal (keyed by the route NAME). Pick by **transport**, not by meaning:
+
+| Path          | Helper                                                                     | Transport                                                                                       | Needs the debug gate?                             | Production surface                | Per-segment `shouldRevalidate`? |
+| ------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------- | --------------------------------- | ------------------------------- |
+| **Header**    | `assertCacheStatus(res, routeKey, expected)` / `parseCacheHeader`          | the `X-Rango-Cache` response header — the ONLY signal a black-box Playwright `Response` carries | Yes (`debugCacheSignal` / `RANGO_TEST_SIGNALS=1`) | the header (gated off by default) | no                              |
+| **Telemetry** | `assertCacheDecision(events, routeKey, expected)` / `filterCacheDecisions` | a captured `cache.decision` event off a `createCacheSink()` sink                                | No                                                | zero                              | yes (the only path exposing it) |
+
+Use the header path when all you have is a black-box `Response` (a Playwright `APIResponse`); use the telemetry path when you can wire `createRouter({ telemetry: sink })` and want zero production surface or per-segment `shouldRevalidate`. `assertCacheDecision` is the one-call counterpart of `assertCacheStatus` (parallel `(…, routeKey, expected)` shape — captured `events` in place of a `Response`); reach for raw `filterCacheDecisions` only when you need the per-segment event fields directly.
+
+## API
+
+### 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.                                                                                                                                                                                         |
+
+### Context — what your code under test emits
+
+The header / event is produced by the router's RSC render pipeline from `ctx.routeKey`. Your code does not call these helpers — it just runs under a router with the gate (or telemetry sink) wired. The helpers READ the emitted signal.
+
+| Field                                 | Type                    | Meaning                                                                                    |
+| ------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------ |
+| `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.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). |
+
+### Returns
+
+```ts
+// assertCacheStatus throws on mismatch / missing header / unknown segment; returns void.
+assertCacheStatus(target, segment, expected): void
+
+// parseCacheHeader -> the raw { routeKey: status } map. "a=hit, b=stale" -> { a: "hit", b: "stale" }.
+parseCacheHeader(headerValue: string | null | undefined): Record<string, string>
+
+// createCacheSink -> a sink to wire via createRouter({ telemetry: sink }), plus the array it records into.
+createCacheSink(): { sink: TelemetrySink; events: TelemetryEvent[] }
+
+// assertCacheDecision -> the one-call telemetry assert (counterpart of assertCacheStatus).
+// Throws on mismatch / no matching segment / unknown routeKey; returns void.
+assertCacheDecision(events: readonly TelemetryEvent[], routeKey: string, expected: ExpectedCacheStatus): void
+
+// filterCacheDecisions -> narrow captured events to cache.decision events (raw form).
+filterCacheDecisions(events: readonly TelemetryEvent[]): CacheDecisionEvent[]
+```
+
+## Recipe
+
+```ts
+// In a Playwright e2e, import from the e2e entry —
+// the @rangojs/router/testing barrel pulls a build-only virtual that does not
+// resolve in a plain Playwright runner.
+import { expect, test } from "@playwright/test";
+import { assertCacheStatus, createRangoE2E } from "@rangojs/router/testing/e2e";
+
+const { parityDescribe } = createRangoE2E({ test, expect });
+
+parityDescribe("product page caches", (f) => {
+  test("second request is a hit", async ({ page }) => {
+    // The key is the route NAME (the X-Rango-Cache id), NOT the URL pattern.
+    // Playwright APIResponse.headers() is a method returning a plain record, so
+    // wrap it in a Headers to match CacheStatusTarget (`{ headers: Headers }`).
+    const first = await page.request.get(f.url("/products/1"));
+    assertCacheStatus(
+      { headers: new Headers(first.headers()) },
+      "product.detail",
+      "miss",
+    );
+    const second = await page.request.get(f.url("/products/1"));
+    assertCacheStatus(
+      { headers: new Headers(second.headers()) },
+      "product.detail",
+      "hit",
+    );
+  });
+});
+```
+
+Zero-prod-surface alternative — the telemetry sink. No header at all; you inspect captured `cache.decision` events:
+
+```ts
+import {
+  createCacheSink,
+  assertCacheDecision,
+  filterCacheDecisions,
+} from "@rangojs/router/testing";
+
+const { sink, events } = createCacheSink();
+const router = createRouter({ telemetry: sink }).routes(urlpatterns);
+// ...drive a request through the router's RSC fetch path...
+
+// One-call assert (counterpart of assertCacheStatus), keyed by the route NAME:
+assertCacheDecision(events, "product.detail", "stale");
+
+// Or read the raw event when you need per-segment fields (shouldRevalidate):
+const decision = filterCacheDecisions(events)[0];
+expect(decision.segments?.[0].cacheStatus).toBe("stale");
+expect(decision.segments?.[0].shouldRevalidate).toBe(true);
+```
+
+`events` accumulates across requests, so the FIRST matching segment for a `routeKey` wins — slice or recreate the sink between requests for the same route.
+
+## 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.
+- 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 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: the telemetry sink (`createCacheSink`/`filterCacheDecisions`), no header at all. Note: the non-RSC `dispatch()` primitive never emits this header — get the Response from the router's real RSC fetch path.
+
+## See also
+
+- `/caching`, `/prerender`, `/use-cache` — the DSL this tests
+- Siblings: [`./e2e-parity.md`](./e2e-parity.md), [`./response-routes.md`](./response-routes.md)
+- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Cache, SWR, and prerender"