@rangojs/router 0.0.0-experimental.ce770c9a → 0.0.0-experimental.d5d3070a

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"

package/skills/testing/client-components.md

@@ -0,0 +1,124 @@
+# Testing a client component — renderRoute
+
+**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.
+
+## API
+
+### Options — `RenderRouteOptions`
+
+| Field           | Type                                                                   | Meaning                                                                                                                                                                                                              |
+| --------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `request`       | `Request \| string`                                                    | Initial location. Only the URL is read (client render — headers/method ignored). Defaults to the leaf spec's static prefix or `"/"`.                                                                                 |
+| `loaderData`    | `Record<string, unknown>`                                              | Loader data keyed by loader `$$id`. `useLoader(L)` reads `loaderData[L.$$id]`.                                                                                                                                       |
+| `loaders`       | `ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>`             | Seed by REFERENCE: `[loader, data]` pairs. Robust for real `createLoader()` handles whose `$$id` is empty in a bare test. Prefer over `loaderData`.                                                                  |
+| `params`        | `Record<string, string>`                                               | Explicit params, merged over (and overriding) params extracted from the `request` URL.                                                                                                                               |
+| `locationState` | `ReadonlyArray<readonly [LocationStateDefinition<any, any>, unknown]>` | Seed `useLocationState(def)` by REFERENCE: `[def, value]` pairs; written to `history.state`.                                                                                                                         |
+| `handles`       | `ReadonlyArray<readonly [Handle<any, any>, unknown[]]>`                | Seed `useHandle(handle)` by REFERENCE: `[handle, pushedValues[]]`. Accumulated GLOBALLY (not segment-scoped).                                                                                                        |
+| `handle`        | `HandleDataSeed`                                                       | Advanced: raw wire format `{ [handleId]: { [segmentId]: pushedValues[] } }`. Prefer `handles`. Merged with it.                                                                                                       |
+| `routeMap`      | `Record<string, string>`                                               | Name -> pattern map (informational; client `useReverse` takes its map as an argument, so this is not consumed).                                                                                                      |
+| `basename`      | `string`                                                               | `createRouter({ basename })` value. Wired into `NavigationProvider` so `useRouter().basename`, `<Link>` prefixing, `useMount`/`useHref` resolve against the mount. Normalized like `createRouter`. Defaults to root. |
+| `mount`         | `string`                                                               | `include()` mount prefix. Wraps the segment chain in a `MountContext` so `useMount()` returns the prefix. Normalized like a path prefix. Defaults to `"/"`.                                                          |
+| `theme`         | `ThemeConfig \| true`                                                  | Theme config (`createRouter({ theme })` shape) to wrap the tree in a `ThemeProvider`. Defaults to no provider. A component calling `useTheme()` REQUIRES one.                                                        |
+| `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).                                |
+
+`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.
+
+### Context — client hooks it makes resolve (what your code receives)
+
+| Hook                           | Meaning                                                                                       |
+| ------------------------------ | --------------------------------------------------------------------------------------------- |
+| `useParams`                    | Params from the matched leaf pattern, with `options.params` merged over.                      |
+| `useReverse`                   | Reverse a name->pattern map to a URL; merges `useParams()` and the `mount`/`basename` prefix. |
+| `useHref`                      | Resolve an href against the mount/basename.                                                   |
+| `useMount`                     | The `include()` mount prefix (`options.mount`), else `"/"`.                                   |
+| `useNavigation`                | Navigation controller state — stays `idle` (see caveat).                                      |
+| `useRouter`                    | The router handle, including `.basename`.                                                     |
+| `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).                                                 |
+| `useLocationState`             | SEEDED `history.state` value.                                                                 |
+| `useHandle`                    | SEEDED handle output (globally accumulated).                                                  |
+| `Outlet`                       | Renders the next segment in the chain (layout nesting).                                       |
+| `useTheme`                     | Theme; throws without `options.theme` (see caveat).                                           |
+
+### Returns — `RenderRouteResult`
+
+Extends RTL's `RenderResult` (`getByTestId`, `getByText`, `getByRole`, `container`, ...) with:
+
+```ts
+type RenderRouteResult = RenderResult & {
+  router: {
+    navigate(url: string): Promise<void>; // client-only nav, re-resolves the same routes
+    pathname(): string;
+    params(): Record<string, string>;
+    store: NavigationStore; // advanced
+    eventController: EventController; // advanced
+  };
+};
+```
+
+## Recipe
+
+```tsx
+// @vitest-environment happy-dom
+import { describe, it, expect, afterEach } from "vitest";
+import { cleanup } from "@testing-library/react";
+import { renderRoute } from "@rangojs/router/testing/dom";
+import { Outlet, useParams, useReverse } from "@rangojs/router/client";
+
+afterEach(cleanup);
+
+function Layout() {
+  return (
+    <div>
+      <span data-testid="shell">shell</span>
+      <Outlet />
+    </div>
+  );
+}
+function Product() {
+  const { productId } = useParams<{ productId: string }>();
+  const reverse = useReverse({ product: "/products/:productId" });
+  return (
+    <a data-testid="link" href={reverse("product", { productId: "2" })}>
+      {productId}
+    </a>
+  );
+}
+
+it("resolves params + reverse + Outlet through the layout chain", async () => {
+  const { getByTestId, router } = await renderRoute(
+    [
+      { path: "/products", Component: Layout }, // layout (root)
+      { path: "/products/:productId", Component: Product }, // leaf (last)
+    ],
+    { request: "/products/1" },
+  );
+  expect(getByTestId("shell").textContent).toBe("shell");
+  expect(getByTestId("link").getAttribute("href")).toBe("/products/2");
+
+  await router.navigate("/products/2"); // client-only nav, re-resolves the same routes
+  expect(router.pathname()).toBe("/products/2");
+});
+```
+
+## 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.
+- 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).
+- 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.
+- MULTI-APP `href` typing. When a `renderRoute` suite imports client components across apps, the global `Rango.GeneratedRouteMap` augmentations collide and `href()` stops typechecking (app A's route union rejects app B's name). Runtime is unaffected — it is purely the global `href` typing. Keep the suite single-app, or split tsconfig programs per app (see [`./reverse-and-types.md`](./reverse-and-types.md) and `/typesafety`).
+
+## See also
+
+- `/hooks` — the DSL this tests
+- Siblings: `./handles.md`, `./reverse-and-types.md`, `./render-handler.md`, `./e2e-parity.md`
+- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Reverse and components" (and the "Catch: streaming `use(promise)` Suspense content" subsection)

package/skills/testing/e2e-parity.md

@@ -0,0 +1,125 @@
+# E2E with dev/prod and PE parity — createRangoE2E
+
+**Layer:** e2e (Playwright) · **Import:** `@rangojs/router/testing/e2e` · **DSL it tests:** navigation, hydration, server actions + revalidation, view transitions, PE parity (see `/hooks`, `/view-transitions`)
+
+This is full-stack: the harness builds and serves your real app (`pnpm dev` or `pnpm build` + `pnpm preview`) and drives a real browser. Nothing is seeded — you SEED only the URL you navigate to and the form data you submit; everything else (SSR, hydration, the RSC stream, actions, revalidation) is the real machinery.
+
+## API
+
+`createRangoE2E({ test, expect, defaultRoot })` takes your Playwright `test`/`expect` and returns `{ useFixture, parityDescribe, expectParity, rangoMatchers, testNoJs, ...pageHelpers }`. The factory never imports `@playwright/test` at runtime — the helpers run on the objects you pass, so this entry is loadable in a plain Playwright runner.
+
+### Factory options — `createRangoE2E({ ... })`
+
+| Field         | Type       | Meaning                                                                  |
+| ------------- | ---------- | ------------------------------------------------------------------------ |
+| `test`        | `TestType` | Your Playwright `test` (drives `describe`/`beforeAll`/`afterAll`).       |
+| `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)
+
+| Field            | Type               | Meaning                                                                        |
+| ---------------- | ------------------ | ------------------------------------------------------------------------------ |
+| `root`           | `string`           | App path under test (abs or cwd-relative). Required here or via `defaultRoot`. |
+| `mode`           | `"dev" \| "build"` | Server mode. `parityDescribe` sets this for you (dev + build).                 |
+| `command`        | `string?`          | Override server command (default `pnpm dev` / `pnpm preview`).                 |
+| `buildCommand`   | `string?`          | Override build command (default `pnpm build`).                                 |
+| `cliOptions`     | `SpawnOptions?`    | Extra spawn options (`env`, etc.).                                             |
+| `isolatedServer` | `boolean?`         | Per-suite server with an isolated Vite cache dir (warms dep optimizer; dev).   |
+| `readyPath`      | `string?`          | Readiness poll path (default `/`); use when a basename moves routes off `/`.   |
+| `skipBuild`      | `boolean?`         | Skip the production build (assumes an existing build).                         |
+
+### Parity intent — `ParityIntent` (what `expectParity` applies)
+
+| Shape                           | Meaning                                                                       |
+| ------------------------------- | ----------------------------------------------------------------------------- |
+| `{ navigate: string }`          | Go to a URL (resolved against `opts.baseURL` if relative).                    |
+| `{ submit: { testId, data? } }` | Fill `data` into named inputs under `[data-testid=testId]`, click its submit. |
+
+### expectParity options — `ExpectParityOptions`
+
+| Field           | Type                               | Meaning                                                                                                                                                                                                                                                                         |
+| --------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `observe`       | `string[]`                         | data-testid values whose text must match across JS and no-JS.                                                                                                                                                                                                                   |
+| `baseURL`       | `string?`                          | Base URL for a relative `navigate` intent.                                                                                                                                                                                                                                      |
+| `waitFor`       | `(page) => Promise<void>?`         | Post-intent settle hook on BOTH transports; for `submit` it REPLACES the generic change/stability wait.                                                                                                                                                                         |
+| `ignoreCookies` | `ReadonlyArray<string \| RegExp>?` | Cookie names to exclude from the JS/no-JS jar comparison (exact string or RegExp). The rango state cookie (default prefix `rango-state`) is ALWAYS excluded — it is client-only; use this for a custom `stateCookiePrefix` or other volatile/JS-only cookies (analytics, CSRF). |
+
+### Returns
+
+`createRangoE2E(...)` -> `RangoE2E`:
+
+- `useFixture(options)` -> `Fixture` (`{ mode, root, url(url?), proc() }`). `url(path)` resolves against the running server.
+- `parityDescribe(name, (f) => { ... }, options?)` -> registers a dev describe `name` AND a production describe `` `${name} (production)` ``. Body runs once per describe with that describe's `Fixture`.
+- `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.
+
+## Recipe
+
+```ts
+// helper.ts — wire the harness once around your Playwright test/expect.
+import { test, expect } from "@playwright/test";
+import { createRangoE2E } from "@rangojs/router/testing/e2e";
+
+export const { parityDescribe, expectParity, rangoMatchers, useFixture } =
+  createRangoE2E({ test, expect, defaultRoot: "." });
+export { test, expect };
+```
+
+```ts
+// nav.test.ts — one body -> dev describe AND `(production)` describe.
+import {
+  test,
+  expect,
+  parityDescribe,
+  expectParity,
+  rangoMatchers,
+} from "./helper";
+expect.extend(rangoMatchers);
+
+parityDescribe("product navigation", (f) => {
+  test("client-navigates without a reload", async ({ page }) => {
+    await page.goto(f.url("/"));
+    await page.getByTestId("product-link").click();
+    await page.waitForURL("**/products/1");
+    await expect(page).toHaveRangoPathname("/products/1"); // typed via the shipped augmentation
+  });
+});
+
+parityDescribe("add to cart parity", (f) => {
+  test("JS and no-JS produce the same observable result", async ({ page }) => {
+    await page.goto(f.url("/products/1"));
+    await expectParity(
+      page,
+      { submit: { testId: "add-to-cart-form", data: { qty: "2" } } },
+      { observe: ["cart-count", "flash-message"] },
+    );
+  });
+});
+```
+
+This add-to-cart example only works because the cart is **session-scoped**. A `submit` intent runs against the one live server TWICE — once on the JS page, once in a fresh no-JS context — so `cart-count` lands on the same value on both transports only if each context has its own cart (two distinct sessions, each going 0 -> 2). If the cart were a single global counter shared across contexts, the no-JS pass would observe the JS pass's mutation too (2 then 4) and the snapshots would diverge. See the submit caveats below before reaching for a `submit` intent.
+
+## Caveats
+
+- Every e2e covers BOTH dev and production — a dev-only e2e is not acceptable. `parityDescribe` enforces it structurally: one body registers the dev describe AND the `(production)` describe.
+- Bucketing footgun: a `useFixture({ mode: "build" })` describe whose title omits `(production)` silently lands in the DEV bucket — prod coverage lost, no error. Never hand-title a build describe; the bucketing matches the literal `(production)`, so `(prod)`, `-build`, `-prod` do NOT count. Use `parityDescribe`.
+- `expectParity` contract: PE parity only holds if the submit target is a real `<form>` (with JS off the browser does a native POST). Cookie observation is `document.cookie` — non-HttpOnly cookies only in v1; an HttpOnly (session/auth) divergence is NOT caught here.
+
+### `submit`-intent parity — two scar-tissue hazards
+
+A `submit` intent does NOT replay against a snapshot of the server — it submits for real, twice, against the one running instance, and then compares two whole browser jars. Both of these have bitten before; read them before you write a `submit` parity test.
+
+- **Double execution.** The JS path submits on the page you handed `expectParity`. The no-JS pass then reloads the SAME `originUrl` in a fresh, scripting-disabled context and submits AGAIN. So a non-idempotent action (anything that mutates server state) runs twice against one server, and the no-JS snapshot sees BOTH mutations — UNLESS the mutated state is per-session / per-context. The add-to-cart example above only passes because the cart is session-scoped: each context owns its own cart and independently goes 0 -> 2, so both snapshots read 2. A globally-shared counter would read 2 after the JS submit and 4 after the no-JS submit, and the equality assertion would fail with no obvious cause. Increment-shaped actions are the trap; make the observable state session-scoped, or assert the submit path outside `expectParity`.
+- **Whole jar, not the delta.** The cookie assertion compares `document.cookie` of the JS context against `document.cookie` of the fresh no-JS context (`parity.ts`, the final `cookies` equality). The JS context carries every cookie it accumulated before the intent — consent banners, analytics, cookies set during earlier navigation in the same test. The no-JS context starts empty and only picks up what THIS submit sets. So a pre-existing, intent-unrelated cookie in the JS context false-mismatches: the helper is diffing two jars, not the per-submit cookie delta. Keep the JS context's pre-intent cookie state minimal (a fresh page goto, no prior cookie-setting steps), or assert the specific Set-Cookie in a dedicated test.
+- `rangoMatchers` ships `toHaveRangoPathname` only. `toHaveSegments`/`toHaveParams` are a documented future addition — they need a client-emitted signal that does not exist yet; do not assume them.
+- Subset run: add `--no-deps`. `--grep` does NOT filter dependency projects, so grepping one production test otherwise pulls in the whole dev suite. `--grep` is a regex: a pasted title containing `(production)` / `:locale?` / `[...]` mis-matches — grep a metacharacter-free fragment (or escape it). Example: `pnpm exec playwright test --project=production --no-deps --grep "add to cart parity"`.
+- Import the harness from the `/e2e` entry — the unit barrel (`@rangojs/router/testing`) is not loadable in a plain Playwright runner (it pulls a build-only virtual). The helpers take your `test`/`expect`, so this entry never imports `@playwright/test` at runtime.
+
+## See also
+
+- `/hooks`, `/view-transitions` — the DSL this tests
+- Siblings: [`./cache-prerender.md`](./cache-prerender.md), [`./client-components.md`](./client-components.md)
+- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "E2E with dev/prod and PE parity" (and "Running a subset locally")

package/skills/testing/flight.md

@@ -0,0 +1,91 @@
+# Pinning the Flight wire payload — renderToFlightString
+
+**Layer:** RSC unit (react-server project) · **Import:** `@rangojs/router/testing/flight` + `@rangojs/router/testing/flight-matchers` · **DSL it tests:** an async Server Component / Flight output (see `/route`)
+
+> **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.
+
+## 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]]`).                                                                                                                               |
+
+### Context — `RequestContext` (what your component receives)
+
+A request context is active for the whole render, so an async Server Component can read it via `getRequestContext()` / the router's server APIs. The notable surfaces seeded from the options above:
+
+| Field       | Type                                                                       | Meaning                                                               |
+| ----------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `request`   | `Request`                                                                  | The backing request (from `request`/`headers`).                       |
+| `url`       | `URL`                                                                      | The request URL.                                                      |
+| `env`       | `unknown`                                                                  | Env / bindings (from `env`).                                          |
+| `params`    | `Record<string, string>`                                                   | Route params (from `params`).                                         |
+| `routeName` | `string \| undefined`                                                      | Matched route name (from `routeName`).                                |
+| `get`       | `<T>(v: ContextVar<T>) => T \| undefined; <K extends string>(key: K): any` | Read a var seeded via `vars` (by `createVar()` handle or string key). |
+
+### Returns — `Promise<string>`
+
+The Flight wire string for the rendered tree. Assert on it with the matchers (register via `expect.extend(flightMatchers)`):
+
+```ts
+expect(await renderToFlightString(<C />)).toMatchFlight("substring"); // containment
+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`).
+
+## Recipe
+
+Name the file `*.rsc-test.{ts,tsx}` and run `pnpm test:unit:rsc`:
+
+```tsx
+import { it, expect } from "vitest";
+import { renderToFlightString } from "@rangojs/router/testing/flight";
+import { flightMatchers } from "@rangojs/router/testing/flight-matchers";
+expect.extend(flightMatchers);
+
+// Pure leaf server components: data comes in as props, not getRequestContext.
+async function Greeting({ name }: { name: string }) {
+  const who = await Promise.resolve(name);
+  return <h1>Hello {who}</h1>;
+}
+
+async function ItemView({ id }: { id: string }) {
+  const item = await Promise.resolve({ id, label: `Item ${id}` });
+  return <article>{item.label}</article>;
+}
+
+it("renders an async server component to Flight", async () => {
+  const flight = await renderToFlightString(<Greeting name="Ada" />);
+  expect(flight).toMatchFlight("Ada");
+});
+
+it("snapshots the normalized payload", async () => {
+  const flight = await renderToFlightString(<ItemView id="7" />);
+  expect(flight).toMatchFlightSnapshot();
+});
+```
+
+## Caveats
+
+- Leaf / server-only: a client island in the tree emits an un-hydratable `I[...]` import row against the empty client manifest. Keep Flight tests to leaf server components; test full pages at e2e.
+- Requires the react-server vitest project (see `./setup.md`): `resolve.conditions` includes `react-server`, the `@rangojs/router -> index.rsc.ts` alias, `NODE_ENV=production`, and the worker `execArgv`. Name files `*.rsc-test.{ts,tsx}` and run `pnpm test:unit:rsc`. The main vitest project must NOT set `react-server` (it would flip React to the no-hooks server build).
+- A component that imports a server API (`getRequestContext`, `cookies`) from the bare `@rangojs/router` barrel works ONLY with the `index.rsc.ts` alias wired (see `./setup.md`); without it the bare import resolves to the throwing out-of-react-server stub. `renderToFlightString` / `renderServerTree` self-diagnose this exact misconfiguration — they reject with an actionable message naming `rangoTestAliases`, rather than surfacing the opaque stub error. Pure-leaf components that take all data as props need no barrel import and are the simplest case.
+- `toMatchFlight` is containment (substring), not equality — the row framing (prefixes/quoting) is an internal serializer detail, so pin the rendered text/shape, not the framing. `toMatchFlightSnapshot()` snapshots the normalized payload; run under `NODE_ENV=production` for the cleanest, most stable bytes.
+- No hydration / no interaction here — that is the e2e tier. For typed assertions on a client boundary's props (a `Date` back as a `Date`), or to confirm an island actually crossed the boundary, use `renderServerTree` (see `./server-tree.md`).
+
+## See also
+
+- `/route` — the DSL this tests
+- Siblings: `./setup.md`, `./server-tree.md`, `./render-handler.md`
+- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "renderToFlightString — real async Server Components"

package/skills/testing/handles.md

@@ -0,0 +1,129 @@
+# Testing a handle — collectHandle, plus the loader and client read paths
+
+**Layer:** unit (node + DOM) · **Import:** `@rangojs/router/testing` (collectHandle), `@rangojs/router/testing/dom` (renderRoute) · **DSL it tests:** a handle e.g. Breadcrumbs/Meta (see `/handler-use`, `/breadcrumbs`)
+
+A handle's `collect`/accumulator (the `createHandle(collect)` argument that maps per-segment pushed values into one accumulated result) is otherwise unreachable — `createHandle` keeps it in a private registry keyed by `$$id`. These three primitives test it from different angles: `collectHandle` runs the REAL registered collect on per-segment values you SEED; `runLoader` seeds the POST-collect accumulated value a loader reads after the barrier; `renderRoute` seeds the RAW pushed values for a client component reading `useHandle`. None of them run the real push -> accumulate -> barrier wiring (that stays e2e).
+
+## API
+
+### `collectHandle(handle, segments)` — `src/testing/collect-handle.ts`
+
+| Param      | Type                                  | Meaning                                                                                                                                                                                                                                              |
+| ---------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `handle`   | `Handle<TData, TAccumulated>`         | The handle whose registered collect to run.                                                                                                                                                                                                          |
+| `segments` | `ReadonlyArray<ReadonlyArray<TData>>` | Per-segment pushed values, one inner array per route segment, in **parent -> child** order. Empty inner arrays are filtered before the collect runs (matching production `collectHandleData` — a segment that pushed nothing is not passed through). |
+
+**Returns** `TAccumulated` — exactly what the handle's collect produces (a default-flatten array, or a custom accumulator's value). If the handle's module was never imported (collect unregistered), it warns and falls back to `segments.flat()`.
+
+### runLoader option — `handles` — `src/testing/run-loader.ts`
+
+| Field      | Type                                        | Meaning                                                                                                                                                                                                                |
+| ---------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `handles`  | `ReadonlyArray<readonly [Handle, unknown]>` | Seeds the value `ctx.use(SomeHandle)` returns — the POST-collect **ACCUMULATED** value (singular `unknown`), what a loader reads after `await ctx.rendered()`. Matched by handle reference. Pair with `rendered`.      |
+| `rendered` | `boolean \| (() => void \| Promise<void>)`  | Mocks the `ctx.rendered()` barrier (throws by default). `true` resolves it immediately; a function controls timing/side effects. A `ctx.use(handle)` read before the barrier settles throws, exactly as in production. |
+
+### renderRoute option — `handles` — `src/testing/render-route.tsx`
+
+| Field     | Type                                          | Meaning                                                                                                                                                                                                                                                                   |
+| --------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `handles` | `ReadonlyArray<readonly [Handle, unknown[]]>` | Seeds the CLIENT read path for `useHandle(handle)` — the RAW **pushed values array** (`unknown[]`), the values a route's handlers would have pushed. Attached to the leaf route segment under the handle's `$$id`, so `useHandle` runs the handle's REAL collect on them. |
+
+**Shape contrast:** `renderRoute` feeds the barrier INPUT (the pushes, `unknown[]`); `runLoader` feeds its OUTPUT (the single accumulated value, `unknown`).
+
+**Across navigation:** seeded `handles` are applied once at the initial render and PERSIST across `router.navigate()` within the same test (like `loaderData`) — unlike a real navigation, which re-runs handlers. A layout/page reading `useHandle` still resolves the seeded values after `navigate()`.
+
+## Recipe
+
+```ts
+// collectHandle.test.ts — the pure collect, no route match
+import { describe, it, expect } from "vitest";
+import { collectHandle } from "@rangojs/router/testing";
+import { createHandle } from "@rangojs/router";
+
+const Breadcrumbs = createHandle<{ label: string; href: string }>(); // default flatten
+
+it("flattens per-segment crumbs in parent->child order", () => {
+  const home = { label: "Home", href: "/" };
+  const post = { label: "P", href: "/p" };
+  expect(collectHandle(Breadcrumbs, [[home], [post]])).toEqual([home, post]);
+});
+
+it("runs a custom 'last wins' collect", () => {
+  const PageTitle = createHandle<string, string>((s) => s.flat().at(-1) ?? "");
+  expect(collectHandle(PageTitle, [["Home"], ["Products"], ["Shoes"]])).toBe(
+    "Shoes",
+  );
+});
+```
+
+```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 { RenderedProducts } from "../src/handles"; // a createHandle(...)
+
+const livePricesBody = async (ctx) => {
+  await ctx.rendered(); // barrier: handle data is now readable
+  const ids = ctx.use(RenderedProducts) as string[];
+  return ids.map((id) => ({ id, price: 9.99 }));
+};
+
+it("reads the accumulated handle value (seed the OUTPUT, mock the barrier)", async () => {
+  const data = await runLoader(livePricesBody, {
+    rendered: true,
+    handles: [[RenderedProducts, ["widget-a", "widget-b"]]], // singular accumulated value
+  });
+  expect(data).toEqual([
+    { id: "widget-a", price: 9.99 },
+    { id: "widget-b", price: 9.99 },
+  ]);
+});
+```
+
+```tsx
+// breadcrumb-trail.test.tsx — a client component reading useHandle
+// @vitest-environment happy-dom
+import { it, expect, afterEach } from "vitest";
+import { cleanup } from "@testing-library/react";
+import { renderRoute } from "@rangojs/router/testing/dom";
+import { useHandle } from "@rangojs/router/client";
+import { Breadcrumbs } from "../src/handles";
+
+afterEach(cleanup);
+
+function BreadcrumbTrail() {
+  const crumbs = useHandle(Breadcrumbs); // accumulated client-side via the real collect
+  return <nav>{crumbs.map((c) => c.label).join(" / ")}</nav>;
+}
+
+it("renders the seeded trail (seed the INPUT pushes, the collect runs)", async () => {
+  const { getByText } = await renderRoute(
+    [{ path: "/p", Component: BreadcrumbTrail }],
+    {
+      handles: [
+        [
+          Breadcrumbs,
+          [
+            { label: "Home", href: "/" },
+            { label: "P", href: "/p" },
+          ],
+        ],
+      ], // raw pushes array
+    },
+  );
+  expect(getByText("Home / P")).toBeTruthy();
+});
+```
+
+## Caveats
+
+- `collectHandle` tests the pure collect/accumulator in ISOLATION (parent -> child segment order, empty arrays filtered to match production). It does NOT run the real push -> accumulate -> barrier wiring — that stays e2e.
+- renderRoute `handles` seeds the CLIENT read path with the RAW pushed values array (`unknown[]`), attached to the leaf segment. Handle data accumulates GLOBALLY (not segment-scoped like loaders), so a LAYOUT reading the same handle sees the seeded values too, not just the leaf route.
+- runLoader `handles` seeds the POST-collect ACCUMULATED value (singular `unknown`) a loader reads after `await ctx.rendered()`; pair with `{ rendered: true }`. Shape contrast: renderRoute feeds the barrier INPUT (pushes[]), runLoader feeds its OUTPUT (the accumulated value).
+- The renderRoute path is the CLIENT tree only: it does NOT catch server/client boundary remount bugs, real Flight serialization errors, or loader execution.
+
+## See also
+
+- `/handler-use`, `/breadcrumbs` — the DSL this tests
+- Siblings: `./loader.md`, `./client-components.md`, `./render-handler.md`
+- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Testing a handle's collect/accumulator"