@rangojs/router 0.16.0 → 0.18.0

package/skills/shell-manifest/SKILL.md

@@ -9,8 +9,8 @@ argument-hint:
 Use this when a cached or prerendered shell has dynamic holes, and the live
 data layer needs to know **what the shell actually contains** — which
 products, which slots, which keys. The frozen render describes itself
-through a handle; loaders (always live) read that description and fetch
-exactly the dynamic data the shell needs, in one batch.
+through a handle; live loaders (no `ssr: false`) read that description and
+fetch exactly the dynamic data the shell needs, in one batch.
 
 Canonical case: a prerendered product list where prices must stay live.
 
@@ -32,14 +32,19 @@ batched.
 ## The mechanism (three features composed)
 
 1. **Handles record data at render time.** The handler pushes to a handle
-   (`ctx.use(Handle)`) while it renders — at build time for `Prerender`, on
-   the cache miss for `cache()`. (Loader bodies can push handles too — see
-   `/loader` — but a loader push is request-time and is NOT part of the
-   replayed artifact; a manifest handle must be pushed by the code that gets
-   frozen with the shell.)
+   (`ctx.use(Handle)`) while it renders — at build time for `Prerender`, on the
+   cache miss for `cache()`. (Loader bodies can push handles too — see `/loader`
+   — but a live loader's push is request-time and is NOT part of the replayed
+   artifact; a manifest handle must be pushed by the code that gets frozen with
+   the shell. An `ssr: false` loader on a `ppr` route is the exception: its
+   settled pushes are recorded with the shell. On a HIT, one whose return has no
+   promises does not run (unless the capture marked it to run), so the recorded
+   pushes are what the page shows; one whose return carries promises runs on
+   every HIT, and its pushes replace the recorded ones — `/ppr` "On a shell
+   HIT".)
 2. **Replay on every hit.** Handle data is stored with the Flight payload
-   and replayed into the handle store on cache/prerender hits — handler code
-   does not re-run, but its pushes do.
+   and replayed into the handle store on cache, prerender and `ppr` shell
+   hits — handler code does not re-run, but its pushes do.
 3. **Loaders read after the render barrier.** A DSL loader can
    `await ctx.rendered()` (waits for all non-loader segments to settle —
    fresh render or replay alike), then `ctx.get(Handle)` returns the
@@ -94,7 +99,7 @@ import { RenderedProducts } from "../handles/rendered-products";
 export const PriceLoader = createLoader(async (ctx) => {
   await ctx.rendered();
   const ids = ctx.get(RenderedProducts);
-  return db.pricesFor(ids); // Map<string, number> keyed by product id
+  return db.pricesFor(ids); // Record<string, number> keyed by product id
 });
 ```
 
@@ -138,9 +143,11 @@ cache({ ttl: 600, tags: ["products"] }, () => [
 ## Contract and gotchas
 
 - **The manifest is exactly as fresh as the shell.** Replayed handle data is
-  frozen with the payload. To change _which_ products render, invalidate the
-  shell (`updateTag("products")`, TTL expiry, rebuild) — never treat the
-  loader as the refresh path for the list itself. This is the point:
+  frozen with the payload. To change _which_ products render, refresh the
+  shell — for `cache()`, `updateTag("products")` or TTL expiry; for
+  `Prerender`, a rebuild (tag invalidation does not reach build-time payloads,
+  see `/prerender`). Never treat the loader as the refresh path for the list
+  itself. This is the point:
   shell and holes cannot desync because they share one artifact.
 - **No request-scoped data in a manifest handle.** The handle data is baked
   into a shared artifact — the same cross-user rule as any cached content.
@@ -181,12 +188,19 @@ const prices = await runLoader(PriceLoader, {
 
 This tests the loader's post-barrier logic. The real
 push → store → replay → barrier wiring is covered at the e2e tier (dev +
-production), like every cache-path behavior.
+production), like every cache-path behavior. On a `ppr` route,
+`serveShellRequest(router, url, { cacheStore })` from
+`@rangojs/router/testing/flight` runs the real capture and HIT in a unit test
+(react-server Vitest): serve the URL twice with the same store; the second
+response is a HIT, and its `flight` carries the live loader's output for the
+replayed ids. Call `resetShellTestState()` in `beforeEach`. Recipe:
+`/testing` → `serve-shell-request.md`.
 
 ## Related
 
 - `/prerender` — `Prerender`/`Passthrough`, build flow, passthrough fallback
 - `/caching` — segment `cache()`, stores, tags
+- `/ppr` — cached HTML shells; its holes are the same live loaders
 - `/loader` — loader context, `ctx.rendered()`, streaming
 - `/hooks` — `useHandle` for reading handle data in client components
 - `/rango` → "Passing data down the tree" — this pattern is the frozen→live

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, serveShellRequest for PPR shells), 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,31 @@ 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`        |
+| a loader's own `cache()` (HIT, `updateTag()` of a tag its body recorded)                                                           | RSC unit     | [`runLoader` + `cache` + 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]`  |
+| a `ppr` route's shell: MISS -> capture -> HIT, what the shell froze vs what a HIT renders live, tag eviction, navigation replay    | RSC unit     | [`serveShellRequest`](./serve-shell-request.md)                                                          | `@rangojs/router/testing/flight` |
+| PPR shell HIT/MISS in real HTML (`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 +124,49 @@ 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)
+  [`render-handler.md`](./render-handler.md),
+  [`serve-shell-request.md`](./serve-shell-request.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)           |
+|                                           | `serveShellRequest`, `resetShellTestState`                                                                                                                   | [`serve-shell-request.md`](./serve-shell-request.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.