@rangojs/router 0.16.0 → 0.17.0

package/skills/streams-and-websockets/SKILL.md

@@ -38,11 +38,12 @@ export const urlpatterns = urls(({ path }) => [
     "/events/ticks",
     (ctx) => {
       const encoder = new TextEncoder();
+      let interval: ReturnType<typeof setInterval> | undefined;
 
       const stream = new ReadableStream({
-        async start(controller) {
+        start(controller) {
           let count = 0;
-          const interval = setInterval(() => {
+          interval = setInterval(() => {
             controller.enqueue(
               encoder.encode(`event: tick\ndata: ${++count}\n\n`),
             );
@@ -51,9 +52,17 @@ export const urlpatterns = urls(({ path }) => [
           // Honor client disconnect — signal comes from ctx.request.signal
           ctx.request.signal.addEventListener("abort", () => {
             clearInterval(interval);
-            controller.close();
+            try {
+              controller.close();
+            } catch {
+              // already closed or cancelled
+            }
           });
         },
+        // The runtime cancels the stream when the reader goes away
+        cancel() {
+          clearInterval(interval);
+        },
       });
 
       return new Response(stream, {
@@ -80,18 +89,21 @@ source.addEventListener("tick", (e) => console.log("tick", e.data));
 
 ### SSE caveats
 
-- **Never wrap SSE routes in `cache()`** — a cached `ReadableStream` is read
-  once and would replay an empty body on the next hit. `path.stream` is
-  already excluded from response-route caching, but don't layer a custom
-  cache() middleware on top.
+- **Never put an SSE route inside a `cache()` scope.** Response-route
+  `cache()` does not special-case `path.stream`: an SSE response is a `200`
+  like any other, so a `cache()` above it would try to store the stream. Keep
+  SSE routes outside every `cache()` boundary, and don't layer a custom
+  caching middleware on top either.
 - **Middleware is fine.** Global/route middleware rewraps the SSE `Response`
   as `new Response(response.body, { status, headers })` to merge stub headers.
   The `ReadableStream` body is passed by reference, not consumed, so the
   client sees the stream unchanged. (WebSocket upgrades are the exception —
   those bypass rewrap entirely; see below.)
-- **Honor `ctx.request.signal`.** Without wiring abort to your source
-  (timer, DB cursor, upstream fetch), the stream leaks when the client
-  disconnects.
+- **Honor `ctx.request.signal` and `cancel()`.** Without wiring disconnect to
+  your source (timer, DB cursor, upstream fetch), the stream leaks when the
+  client goes away. Clean up in both places: depending on the runtime, a
+  disconnect surfaces as the request signal aborting, the stream being
+  cancelled, or both.
 - **Disable Nginx/CDN buffering** via `x-accel-buffering: no` and ensure
   no intermediate proxy rebuffers. On Cloudflare Workers this is a non-issue.
 
@@ -210,6 +222,8 @@ HTTP request instead (e.g. during login), then read them at upgrade time
 via `ctx.request.headers.get("cookie")`.
 
 ```typescript
+import { cookies } from "@rangojs/router";
+
 // Avoid: this cookie may not land on the upgrade response, and the client
 // never reads it during the handshake regardless.
 router.use(async (ctx, next) => {
@@ -219,7 +233,7 @@ router.use(async (ctx, next) => {
 
 // Prefer: authenticate by reading a cookie set on a prior HTTP request.
 path.any("/ws", (ctx) => {
-  const session = parseCookie(ctx.request.headers.get("cookie"))?.session;
+  const session = cookies().get("session")?.value;
   if (!verify(session)) return new Response("unauthorized", { status: 401 });
   // ...upgrade
 });
@@ -240,7 +254,8 @@ router.use(async (ctx, next) => {
 
 ## Caching
 
-- **SSE** — do not combine with `cache()` (streams can't be replayed).
+- **SSE** — do not place under `cache()`: it is a cacheable `200`, and an
+  endless stream cannot be stored or replayed.
 - **WebSocket** — `cache()` is inert because only `status === 200` is cacheable.
 
 ## Runtime caveats
@@ -279,5 +294,8 @@ Object.defineProperty(upgrade, "webSocket", {
 
 ## See also
 
-- `response-routes` — the parent skill for `path.json/text/html/stream/any`.
-- `middleware` — how global and route-level middleware compose with handlers.
+- `/response-routes` — the parent skill for `path.json/text/html/stream/any`
+  and `ResponseHandlerContext` (`ctx.header()`, `ctx.waitUntil()`,
+  `ctx.executionContext`).
+- `/middleware` — how global and route-level middleware compose with handlers.
+- `/cloudflare` — Workers bindings and Durable Object setup.

package/skills/tailwind/SKILL.md

@@ -6,7 +6,9 @@ argument-hint: [setup]
 
 # Tailwind CSS
 
-Set up Tailwind CSS v4 with the Rango router. Styles are loaded through the Document component using Vite's `?url` CSS import.
+Set up Tailwind CSS v4 in a Rango app: the Vite plugin, the CSS entry, loading
+it from the Document with Vite's `?url` import, theme tokens, class-based dark
+mode, and fonts. The general stylesheet pattern is explained in `/css`.
 
 ## Install
 
@@ -18,11 +20,14 @@ pnpm add -D tailwindcss @tailwindcss/vite
 
 ```typescript
 // vite.config.ts
+import { defineConfig } from "vite";
 import tailwindcss from "@tailwindcss/vite";
+import { rango } from "@rangojs/router/vite";
 
 export default defineConfig({
   plugins: [
     tailwindcss(),
+    rango(),
     // ... other plugins
   ],
 });
@@ -37,18 +42,17 @@ export default defineConfig({
 
 ## Document Component
 
-Import the CSS file with `?url` to get a hashed URL, then preload and link it in
-`<head>`. Give the `<link rel="stylesheet">` a `precedence` prop so React 19
-manages it as a resource — de-duped by `href`, ordered, and loaded before paint
-(no flash of unstyled content). See
-[Stylesheets and cross-app navigation](#stylesheets-and-cross-app-navigation):
+Import the CSS file with `?url` to get its hashed URL, then preload and link it
+in `<head>`. Give the `<link rel="stylesheet">` a `precedence` prop so React 19
+manages it as a resource: de-duped by `href`, ordered, and loaded before paint
+(no flash of unstyled content).
 
 ```tsx
 // src/document.tsx
 "use client";
 
 import type { ReactNode } from "react";
-import { MetaTags } from "@rangojs/router/client";
+import { Html } from "@rangojs/router/client";
 import styles from "./index.css?url";
 
 export function Document({ children }: { children: ReactNode }) {
@@ -57,7 +61,7 @@ export function Document({ children }: { children: ReactNode }) {
       <head>
         <link rel="preload" href={styles} as="style" precedence="default" />
         <link rel="stylesheet" href={styles} precedence="default" />
-        <MetaTags />
+        <Html.Meta />
       </head>
       <body className="font-sans antialiased text-slate-900 bg-slate-50">
         {children}
@@ -67,27 +71,15 @@ export function Document({ children }: { children: ReactNode }) {
 }
 ```
 
-## Stylesheets and cross-app navigation
+The `?url` suffix tells Vite to return the processed CSS file's URL instead of
+injecting it as a side effect, giving a stable, hashed asset path in both
+development and production. A bare `import "./index.css"` also produces managed
+CSS, but it is not guaranteed to be in the initial streamed `<head>`; prefer
+`?url` + `<link precedence>` for document CSS (see `/css`).
 
-The `precedence` prop opts a `<link rel="stylesheet">` into React 19's managed
-stylesheet model — React de-duplicates it by `href`, orders it by precedence, and
-loads it before paint (avoiding a flash of unstyled content). It is the
-recommended way to render a stylesheet link, which is why the example above uses
-it. (A bare side-effect `import "./index.css"` also produces managed CSS via
-`@vitejs/plugin-rsc`, but carries an SSR-streaming caveat — prefer the `?url` +
-`<link precedence>` form for document CSS. See `/css`.)
-
-For **host-router** apps (`/host-router`), a client-side navigation that crosses
-an app boundary is a **full document load**, not a soft swap — the framework
-redirects on an app switch. So each app's document (its stylesheets, theme, meta)
-is always re-established cleanly by the target app's own load; you do not have to
-coordinate stylesheet `href`s or `precedence` across apps. (This replaced an
-earlier soft cross-app swap, under which a stylesheet shared across apps — every
-app's `@import "tailwindcss"` compiles to one hashed asset — could be dropped by
-React's by-`href` resource dedup if the apps disagreed on `precedence`. The full
-reload removes that footgun entirely.)
-
-The `?url` suffix tells Vite to return the processed CSS file's URL instead of injecting it as a side effect. This gives you a stable, hashed asset path that works in both development and production.
+For **host-router** apps (`/host-router`), navigating between apps is a full
+document load, so each app's Tailwind stylesheet is loaded by its own Document;
+there is nothing to coordinate across apps.
 
 ## Customizing the Theme
 
@@ -107,17 +99,29 @@ Tailwind v4 uses CSS `@theme` for customization:
 
 ## Dark Mode
 
-Combine with the Rango theme system (see `/theme`):
+Combine with the Rango theme system (see `/theme`). With `attribute: "class"`
+(the default) the theme script puts `class="dark"` or `class="light"` on
+`<html>` before first paint; add `suppressHydrationWarning` to the Document's
+`<html>` so React accepts that change:
 
 ```typescript
-const router = createRouter({
+export const router = createRouter({
   document: Document,
   urls: urlpatterns,
   theme: { attribute: "class" },
 });
 ```
 
-Then use Tailwind's `dark:` variant which reads the `class` attribute:
+Tailwind v4's `dark:` variant follows `prefers-color-scheme` by default. Point
+it at the class instead, so the user's stored choice wins over the OS setting:
+
+```css
+/* src/index.css */
+@import "tailwindcss";
+@custom-variant dark (&:where(.dark, .dark *));
+```
+
+Then use the `dark:` variant as usual:
 
 ```tsx
 <div className="bg-white dark:bg-slate-900 text-slate-900 dark:text-white">
@@ -147,7 +151,7 @@ No extra `<link>` tags needed in the Document -- Vite bundles the font files fro
 
 ## Notes
 
-- `?url` import is required -- bare CSS imports inject styles as a side effect and do not work with SSR streaming
-- `<link rel="preload" as="style">` eliminates render-blocking by starting the download early
+- Use the `?url` import for the document stylesheet: a bare side-effect import is not guaranteed to be in the initial streamed `<head>` (see `/css`)
+- `<link rel="preload" as="style">` starts the stylesheet download early
 - Tailwind v4 does not need a `tailwind.config.js` -- use `@theme` in CSS instead
 - The `@tailwindcss/vite` plugin handles content detection automatically

package/skills/testing/SKILL.md

@@ -1,18 +1,24 @@
 ---
 name: testing
-description: Test @rangojs/router apps — unit (loaders/middleware/reverse/components), integration (dispatch/Flight), and e2e (dev+prod parity, progressive enhancement). Use when writing a unit test for a loader or middleware, or asking how to test a route end-to-end in dev and production.
+description: Test @rangojs/router apps — unit (loaders, middleware, server actions, handles, transition/clientUrls predicates), client components (renderRoute), RSC/Flight (renderServerTree, renderHandler), integration (dispatch), and e2e (dev+prod parity, progressive enhancement). Use when writing a unit test for a loader, middleware, action, or handler, setting up vitest for a Rango app, or testing a route end-to-end in dev and production.
 argument-hint: [layer]
 ---
 
 # Testing @rangojs/router apps
 
+This skill picks the right test layer for a behavior in a Rango app and gives
+the API, a recipe, and the caveats for each testing primitive. Use it when
+adding or changing tests, or when wiring the vitest/Playwright setup.
+
 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).
+`@rangojs/router/testing/flight-matchers` (the Flight matchers). Host-router
+pattern helpers live separately at `@rangojs/router/host/testing` (see
+`/host-router`).
 
 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
@@ -42,8 +48,8 @@ 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):
+Two non-negotiable mandates (the Rango repo holds itself to these, 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
@@ -54,8 +60,10 @@ consumer apps too):
 
 ## 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:
+Four of the six entries hold the test primitives, each matched to the
+dependency/runtime that can load it — this split is forced by hard walls, not
+preference. (The other two are helpers: `/testing/vitest` is config-only, and
+`/testing/flight-matchers` holds `toMatchFlight`/`toMatchFlightSnapshot`.)
 
 - `@rangojs/router/testing` — unit + integration primitives. Run these under a
   **Vite-driven Vitest** project with the rango Vite plugin active (the router
@@ -81,26 +89,29 @@ The single rule that drives everything:
 
 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 / thrown `redirect()`/`notFound()` / handle-push output                                                 | 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 }`; pass `{ ppr: true }` for pre-handler timing)    | `@rangojs/router/testing`        |
-| a `clientUrls()` `revalidate()` / `isAction(ref)` predicate                                                                        | unit (node)  | `runClientRevalidate` (production `makeIsAction` + locked defaults)                           | `@rangojs/router/testing`        |
-| a handle's `collect`/accumulator, a seeded handle read, or a loader handle write                                                   | unit         | [`collectHandle` / seeded `handles` / `handlePushes`](./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]`  |
-| PPR shell HIT/MISS (`ppr` path option), shell store key / getShell after flush                                                     | e2e + signal | [`assertShellStatus` / `shellCacheKey` + store](./cache-prerender.md#ppr-shell-x-rango-shell) | `@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)   |
+| The behavior is…                                                                                                                   | Layer        | Primitive                                                                                                | Import root                      |
+| ---------------------------------------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| a `reverse` / `href` / params / env TYPE contract (a wrong name or missing param must not compile)                                 | types (tsc)  | [`@ts-expect-error` / `expectTypeOf`](./reverse-and-types.md)                                            | `@rangojs/router/client` + `tsc` |
+| one loader's data logic                                                                                                            | unit (node)  | [`runLoader`](./loader.md)                                                                               | `@rangojs/router/testing`        |
+| a loader's cookie / header / thrown `redirect()`/`notFound()` / handle-push output                                                 | 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`](./predicates.md) (`{ kept, whenContext }`; `{ ppr: true }` for pre-handler timing) | `@rangojs/router/testing`        |
+| a `clientUrls()` `revalidate()` / `isAction(ref)` predicate                                                                        | unit (node)  | [`runClientRevalidate`](./predicates.md) (production chain evaluator + locked defaults)                  | `@rangojs/router/testing`        |
+| a handle's `collect`/accumulator, a seeded handle read, or a loader handle write                                                   | unit         | [`collectHandle` / seeded `handles` / `handlePushes`](./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 stale indicator from `useLoader().isLoading` while a `transition()` navigation re-runs the loader                                | unit (DOM)   | [`renderRoute` + `navigate(url, { loaders })`](./client-components.md#held-navigation)                   | `@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`    |
+| a `"use cache"` hit in a handler (the body runs once across renders; the value round-trips)                                        | RSC unit     | [`renderHandler` + seeded `cacheStore`](./render-handler.md#a-use-cache-hit)                             | `@rangojs/router/testing/flight` |
+| a `"use cache"` hit in a loader (the same, in the react-server project)                                                            | RSC unit     | [`runLoader` + seeded `cacheStore`](./loader.md)                                                         | `@rangojs/router/testing`        |
+| cache hit/miss/stale, prerender (= a cache hit by design)                                                                          | e2e + signal | [`assertCacheStatus` (header) / `assertCacheDecision` (telemetry sink)](./cache-prerender.md)            | `@rangojs/router/testing[/e2e]`  |
+| PPR shell HIT/MISS (`ppr` path option), shell store key / getShell after flush                                                     | e2e + signal | [`assertShellStatus` / `shellCacheKey` + store](./cache-prerender.md#ppr-shell-and-navigation-replay)    | `@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`,
@@ -111,22 +122,47 @@ Cross-references to the DSL skills: `/loader`, `/middleware`, `/server-actions`,
 - 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)
+  [`predicates.md`](./predicates.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:
+## Every export, by entry
+
+Where each runtime export is documented (types such as `RunLoaderOptions` sit
+beside their function):
+
+| Entry                                     | Exports                                                                                                                                                      | Documented in                                    |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
+| `@rangojs/router/testing`                 | `runLoader`, `runLoaderResult`                                                                                                                               | [`loader.md`](./loader.md)                       |
+|                                           | `runMiddleware`                                                                                                                                              | [`middleware.md`](./middleware.md)               |
+|                                           | `runInRequestContext`, `createTestRequestContext`, `runWithRequestContext`, `toRequest`, `seedVariables`                                                     | [`server-actions.md`](./server-actions.md)       |
+|                                           | `runTransitionWhen`, `runClientRevalidate`                                                                                                                   | [`predicates.md`](./predicates.md)               |
+|                                           | `collectHandle`                                                                                                                                              | [`handles.md`](./handles.md)                     |
+|                                           | `dispatch`                                                                                                                                                   | [`response-routes.md`](./response-routes.md)     |
+|                                           | `assertCacheStatus`, `assertCacheDecision`, `parseCacheHeader`, `createCacheSink`, `filterCacheDecisions`                                                    | [`cache-prerender.md`](./cache-prerender.md)     |
+|                                           | `assertShellStatus`, `parseShellStatus`, `shellCacheKey`, `SHELL_STATUS_HEADER`, `assertPprReplayStatus`, `parsePprReplayStatus`, `PPR_REPLAY_STATUS_HEADER` | [`cache-prerender.md`](./cache-prerender.md)     |
+|                                           | `assertGeneratedRoutesMatch`, `diffGeneratedRoutes`                                                                                                          | [`reverse-and-types.md`](./reverse-and-types.md) |
+| `@rangojs/router/testing/dom`             | `renderRoute`                                                                                                                                                | [`client-components.md`](./client-components.md) |
+| `@rangojs/router/testing/flight`          | `renderToFlightString`, `normalizeFlight`, `assertFlightRuntimeAvailable`                                                                                    | [`flight.md`](./flight.md)                       |
+|                                           | `renderServerTree`, `findClientBoundaries`, `findElements`, `textContent`, `assertFlightTreeRuntimeAvailable`                                                | [`server-tree.md`](./server-tree.md)             |
+|                                           | `renderHandler`                                                                                                                                              | [`render-handler.md`](./render-handler.md)       |
+| `@rangojs/router/testing/flight-matchers` | `flightMatchers` (`toMatchFlight`, `toMatchFlightSnapshot`)                                                                                                  | [`flight.md`](./flight.md)                       |
+| `@rangojs/router/testing/vitest`          | `rangoTestConfig`, `rangoTestAliases`, `rangoInlineDeps`, `rangoUseClientTransform`, `rangoUseCacheTransform`                                                | [`setup.md`](./setup.md)                         |
+| `@rangojs/router/testing/e2e`             | `createRangoE2E` and its standalone helpers; the cache/shell status helpers above are re-exported here                                                       | [`e2e-parity.md`](./e2e-parity.md)               |
+
+## Pre-push checklist
+
+Before pushing, run all of these and fix any failure (script names follow
+[`./setup.md`](./setup.md); adjust to your `package.json`):
 
 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`
+4. your lint and format scripts
+5. your Playwright suite (dev AND production projects)
 
 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/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");
@@ -117,15 +121,15 @@ expect(decision.segments?.[0].shouldRevalidate).toBe(true);
 
 **DSL:** `ppr: true | PartialPrerenderProps` on a page route (see `/ppr`). **Not** the same header as `X-Rango-Cache` — shell is a second render axis.
 
-| 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?)`       | same                                 | Production shell store key (`host+pathname+sorted search+:shell`) 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. |
+| `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
 
@@ -141,19 +145,41 @@ expect(decision.segments?.[0].shouldRevalidate).toBe(true);
 ### 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