@rangojs/router 0.0.0-experimental.ea6d5eec → 0.0.0-experimental.ea9f40f2

package/skills/shell-manifest/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: shell-manifest
+description: Shell manifest pattern — replayed handles as cache metadata that live loaders read, e.g. a prerendered product list with batched live prices. Use when a cached/prerendered shell needs to feed IDs or metadata to a live loader for freshly-fetched data.
+argument-hint:
+---
+
+# Shell Manifest — cache metadata for live loaders
+
+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.
+
+Canonical case: a prerendered product list where prices must stay live.
+
+## The problem this solves
+
+Any cached-shell-plus-live-holes design has a coordination gap: how does the
+live layer know what the holes need?
+
+- **Per-hole fetching** (each `<Price>` component fetching for itself) is the
+  N+1 default — N visible products, N queries.
+- **A loader that re-queries the list** ("current top products") drifts from
+  a stale shell — right prices attached to wrong products.
+
+The shell manifest closes the gap with a consistency guarantee: the loader
+reads the ids the shell _actually rendered_, replayed from the same stored
+artifact, so the holes can never desync from the shell and the query is
+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()`.
+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.
+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.use(Handle)` returns the
+   **collected** handle data.
+
+Loaders are live by default, so the read happens on every request even when
+the shell is a hit.
+
+## Canonical example: prerendered list, live prices
+
+```tsx
+// handles/rendered-products.ts
+import { createHandle } from "@rangojs/router";
+
+// TData = string (one push per product id), collected to a flat string[]
+export const RenderedProducts = createHandle<string, string[]>((segments) =>
+  segments.flat(),
+);
+```
+
+```tsx
+// routes/products.tsx — the list is baked at build time; prices are not
+import { Prerender } from "@rangojs/router";
+import { RenderedProducts } from "../handles/rendered-products";
+import { Price } from "../components/price";
+
+export const ProductList = Prerender(
+  async () => [{ category: "espresso" }, { category: "filter" }],
+  async (ctx) => {
+    const products = await db.productsByCategory(ctx.params.category);
+    const track = ctx.use(RenderedProducts);
+    for (const p of products) track(p.id);
+    return (
+      <ul>
+        {products.map((p) => (
+          <li key={p.id}>
+            {p.name} <Price id={p.id} />
+          </li>
+        ))}
+      </ul>
+    );
+  },
+);
+```
+
+```ts
+// loaders/prices.ts — one batched query for exactly the rendered products
+import { createLoader } from "@rangojs/router";
+import { RenderedProducts } from "../handles/rendered-products";
+
+export const PriceLoader = createLoader(async (ctx) => {
+  "use server";
+  await ctx.rendered();
+  const ids = ctx.use(RenderedProducts);
+  return db.pricesFor(ids); // Map<string, number> keyed by product id
+});
+```
+
+```tsx
+// urls.tsx — wire the route and register the loader
+path("/products/:category", ProductList, { name: "products" }, () => [
+  loader(PriceLoader),
+]);
+```
+
+```tsx
+// components/price.tsx — live hole in the frozen shell
+"use client";
+import { useLoader } from "@rangojs/router/client";
+import { PriceLoader } from "../loaders/prices";
+
+export function Price({ id }: { id: string }) {
+  const { data } = useLoader(PriceLoader);
+  return <span>{formatPrice(data[id])}</span>;
+}
+```
+
+Request flow on a hit: stored payload replays (handler never runs) → handle
+data lands in the store → render barrier resolves → `PriceLoader` reads the
+replayed ids → one query → prices stream into `<Price>` components.
+
+## Works with runtime cache() too
+
+`Prerender` is build-time caching; the replay mechanism is identical for the
+runtime segment cache. Wrap the route in `cache()` instead and the handler
+pushes on the miss, replays on every hit:
+
+```tsx
+cache({ ttl: 600, tags: ["products"] }, () => [
+  path("/products/:category", ProductList, { name: "products" }, () => [
+    loader(PriceLoader),
+  ]),
+]);
+```
+
+## 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:
+  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.
+  Ids, slugs, slot names, variant keys: yes. Anything derived from
+  `cookies()`/`headers()`: no.
+- **`ctx.rendered()` is experimental and DSL-loaders-only.** It throws in
+  fetchable/standalone loader calls that run outside a route render.
+- **The reading loader serializes after the shell.** `await ctx.rendered()`
+  deliberately gives up loader/render parallelism — on a miss the loader
+  waits for segment resolution; on a hit (the common case for a cached
+  shell) replay is immediate and the wait is negligible. A
+  `debugPerformance` waterfall shows this loader after the render bar; for
+  this pattern that is the contract, not a regression.
+- **`ctx.use(Handle)` before `await ctx.rendered()` throws** in a loader,
+  with an error saying to await the barrier first.
+- **Deferred handle values are resolved before storage** (resolve-by-default),
+  so the manifest read always sees plain values, never promises.
+
+## Testing
+
+`runLoader` seeds the barrier and the collected handle value directly —
+matched by handle reference (the same seeding style as loader deps):
+
+```ts
+import { runLoader } from "@rangojs/router/testing";
+
+const prices = await runLoader(PriceLoader, {
+  rendered: true,
+  handles: [[RenderedProducts, ["widget-a", "widget-b"]]],
+  env: { DB: fakeDb },
+});
+```
+
+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.
+
+## Related
+
+- `/prerender` — `Prerender`/`Passthrough`, build flow, passthrough fallback
+- `/caching` — segment `cache()`, stores, tags
+- `/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
+  counterpart of that ladder

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

@@ -0,0 +1,283 @@
+---
+name: streams-and-websockets
+description: Long-lived Response handlers — Server-Sent Events (SSE) via path.stream and WebSocket upgrades via path.any on Cloudflare Workers, including middleware interaction and runtime caveats. Use when streaming live updates to the browser, or opening a WebSocket connection from a route on Cloudflare Workers.
+argument-hint: "[sse | websocket | agents]"
+---
+
+# Streams and WebSockets
+
+Response routes can return long-lived responses — SSE streams and WebSocket
+upgrades. Both require a `Response` that the router must forward through the
+middleware chain without reconstruction.
+
+## When each fits
+
+| Shape       | Tag             | Status | Body                            | Runtime                          |
+| ----------- | --------------- | ------ | ------------------------------- | -------------------------------- |
+| Server-Sent | `path.stream()` | 200    | `ReadableStream` (event-stream) | any runtime (Node, workerd, bun) |
+| WebSocket   | `path.any()`    | 101    | `null` + `webSocket` property   | Cloudflare Workers (workerd)     |
+
+- **SSE** is a regular 200 response with `content-type: text/event-stream`
+  and a `ReadableStream` body. Works everywhere, flows through middleware
+  normally.
+- **WebSocket upgrades** produce a status-101 response with a non-standard
+  `webSocket` property (Cloudflare). The router detects these and forwards
+  them without reconstruction; `Vary` and `Server-Timing` are skipped, and
+  stub headers are merged in place on a best-effort basis.
+
+## Server-Sent Events (SSE)
+
+Use `path.stream()` (or `path.any()` if you need full control) to return a
+`ReadableStream`. Each chunk is an `event-stream` frame:
+
+```typescript
+import { urls } from "@rangojs/router";
+
+export const urlpatterns = urls(({ path }) => [
+  path.stream(
+    "/events/ticks",
+    (ctx) => {
+      const encoder = new TextEncoder();
+
+      const stream = new ReadableStream({
+        async start(controller) {
+          let count = 0;
+          const interval = setInterval(() => {
+            controller.enqueue(
+              encoder.encode(`event: tick\ndata: ${++count}\n\n`),
+            );
+          }, 1000);
+
+          // Honor client disconnect — signal comes from ctx.request.signal
+          ctx.request.signal.addEventListener("abort", () => {
+            clearInterval(interval);
+            controller.close();
+          });
+        },
+      });
+
+      return new Response(stream, {
+        headers: {
+          "content-type": "text/event-stream",
+          "cache-control": "no-store",
+          // Disable proxy buffering on Nginx/Traefik deployments
+          "x-accel-buffering": "no",
+        },
+      });
+    },
+    { name: "ticks" },
+  ),
+]);
+```
+
+### Client
+
+```typescript
+"use client";
+const source = new EventSource("/events/ticks");
+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.
+- **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.
+- **Disable Nginx/CDN buffering** via `x-accel-buffering: no` and ensure
+  no intermediate proxy rebuffers. On Cloudflare Workers this is a non-issue.
+
+## WebSockets (Cloudflare Workers)
+
+WebSocket upgrades on workerd produce a response with `status: 101` and a
+non-standard `webSocket` property. The router detects this shape and forwards
+the `Response` without reconstruction — the 101 status and the `webSocket`
+property are preserved. `Vary` and `Server-Timing` writes are skipped, and
+stub-header merging (cookies/custom headers set via `ctx.header()` or
+`cookies().set()`) is best-effort: the router attempts to apply them in
+place, but silently skips any write rejected by a runtime that exposes
+immutable upgrade headers.
+
+### Minimal upgrade handler
+
+```typescript
+import { urls } from "@rangojs/router";
+
+export const urlpatterns = urls(({ path }) => [
+  path.any(
+    "/ws",
+    (ctx) => {
+      // Manual WebSocketPair on workerd
+      const upgrade = ctx.request.headers.get("upgrade");
+      if (upgrade !== "websocket") {
+        return new Response("expected upgrade: websocket", { status: 426 });
+      }
+
+      const { 0: client, 1: server } = new WebSocketPair();
+      server.accept();
+      server.addEventListener("message", (e) => {
+        server.send(`echo: ${e.data}`);
+      });
+
+      return new Response(null, {
+        status: 101,
+        webSocket: client,
+      } as ResponseInit);
+    },
+    { name: "ws" },
+  ),
+]);
+```
+
+### Durable Object pattern
+
+Route into a Durable Object that owns the connection:
+
+```typescript
+export const urlpatterns = urls(({ path }) => [
+  path.any(
+    "/rooms/:roomId",
+    async (ctx) => {
+      const id = ctx.env.ROOMS.idFromName(ctx.params.roomId);
+      const stub = ctx.env.ROOMS.get(id);
+      // The DO's fetch handler calls handleWebSocketUpgrade(request)
+      // and returns the 101 Response. We forward it unchanged.
+      return stub.fetch(ctx.request);
+    },
+    { name: "room" },
+  ),
+]);
+```
+
+### Using the `agents` library
+
+`routeAgentRequest` from `agents` returns a 101 `Response` targeted at a
+Durable Object. Return it directly from `path.any()`:
+
+```typescript
+import { routeAgentRequest } from "agents";
+import { urls } from "@rangojs/router";
+
+export const urlpatterns = urls(({ path }) => [
+  path.any("/agents/*", async (ctx) => {
+    const response = await routeAgentRequest(ctx.request, ctx.env);
+    if (!response) {
+      return new Response("not found", { status: 404 });
+    }
+    return response;
+  }),
+]);
+```
+
+## Middleware interaction
+
+### Forwarded, not reconstructed
+
+When a middleware is matched for the upgrade URL, the middleware still runs
+**before** `next()` — but the Response from `next()` is forwarded as-is
+rather than re-wrapped. This preserves:
+
+- The 101 status (which would otherwise throw `RangeError: Responses may
+only be constructed with status codes in the range 200 to 599, inclusive`
+  on standards-compliant runtimes).
+- The Cloudflare `webSocket` property (which would otherwise be silently
+  dropped by `new Response(body, ...)` on workerd).
+
+```typescript
+// This works — logger runs, but the 101 flows through unchanged.
+router.use(async (ctx, next) => {
+  console.log("ws request", ctx.url.pathname);
+  return next();
+});
+```
+
+### Don't try to set cookies on an upgrade
+
+Stub cookie/header writes made before `await next()` are applied to the
+upgrade response on a best-effort basis — the router attempts an in-place
+merge and skips any write rejected by runtimes that expose immutable 101
+headers. Either way, a browser completing a WS handshake never reads them.
+Do not rely on this for auth or state propagation: set cookies via a prior
+HTTP request instead (e.g. during login), then read them at upgrade time
+via `ctx.request.headers.get("cookie")`.
+
+```typescript
+// 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) => {
+  cookies().set("last-ws-at", Date.now().toString());
+  return 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;
+  if (!verify(session)) return new Response("unauthorized", { status: 401 });
+  // ...upgrade
+});
+```
+
+### Short-circuit before upgrade
+
+Middleware can return a non-101 Response to deny the upgrade outright:
+
+```typescript
+router.use(async (ctx, next) => {
+  if (!isAllowed(ctx.request)) {
+    return new Response("forbidden", { status: 403 });
+  }
+  return next();
+});
+```
+
+## Caching
+
+- **SSE** — do not combine with `cache()` (streams can't be replayed).
+- **WebSocket** — `cache()` is inert because only `status === 200` is cacheable.
+
+## Runtime caveats
+
+| Runtime                                | SSE | WebSocket upgrade (101)                              |
+| -------------------------------------- | --- | ---------------------------------------------------- |
+| Cloudflare Workers (workerd)           | OK  | OK (native `WebSocketPair`, DO, `agents`)            |
+| Node (undici fetch)                    | OK  | N/A — Node's HTTP server must upgrade                |
+| Bun                                    | OK  | Bun's native `upgrade()` — not a Response-based path |
+| Dev (Vite + `@cloudflare/vite-plugin`) | OK  | OK via workerd emulation                             |
+
+When running in pure Node without workerd, a `status: 101` Response cannot
+even be constructed (`new Response(null, { status: 101 })` throws). For
+tests, fabricate upgrade-style responses by overriding `.status` on a real
+Response instance:
+
+```typescript
+const upgrade = new Response(null, { status: 200 });
+Object.defineProperty(upgrade, "status", { value: 101, configurable: true });
+// optional: attach a webSocket stub
+Object.defineProperty(upgrade, "webSocket", {
+  value: { stub: "ws" },
+  configurable: true,
+  enumerable: true,
+});
+```
+
+## Testing
+
+- Unit tests: `isWebSocketUpgradeResponse` and `executeMiddleware` passthrough
+  cases live in `src/rsc/__tests__/helpers.test.ts` and
+  `src/router/middleware.test.ts`.
+- E2E: cover both dev and production modes against a workerd target. SSE
+  can be tested on any runtime; WS upgrades need workerd (use
+  `@cloudflare/vite-plugin` or `wrangler dev`).
+
+## See also
+
+- `response-routes` — the parent skill for `path.json/text/html/stream/any`.
+- `middleware` — how global and route-level middleware compose with handlers.

package/skills/tailwind/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tailwind
-description: Set up Tailwind CSS v4 with the Document component and CSS imports
+description: Set up Tailwind CSS v4 with the Document component and CSS imports. Use when adding Tailwind CSS to a Rango app, or Tailwind classes aren't being applied or generated.
 argument-hint: [setup]
 ---
 
@@ -37,7 +37,11 @@ export default defineConfig({
 
 ## Document Component
 
-Import the CSS file with `?url` to get a hashed URL, then preload and link it in `<head>`:
+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):
 
 ```tsx
 // src/document.tsx
@@ -51,8 +55,8 @@ export function Document({ children }: { children: ReactNode }) {
   return (
     <html lang="en">
       <head>
-        <link rel="preload" href={styles} as="style" />
-        <link rel="stylesheet" href={styles} />
+        <link rel="preload" href={styles} as="style" precedence="default" />
+        <link rel="stylesheet" href={styles} precedence="default" />
         <MetaTags />
       </head>
       <body className="font-sans antialiased text-slate-900 bg-slate-50">
@@ -63,6 +67,26 @@ export function Document({ children }: { children: ReactNode }) {
 }
 ```
 
+## Stylesheets and cross-app navigation
+
+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.
 
 ## Customizing the Theme

package/skills/testing/SKILL.md

@@ -0,0 +1,130 @@
+---
+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.
+argument-hint: [layer]
+---
+
+# Testing @rangojs/router apps
+
+Rango ships six consumer-facing testing entries, one per test runtime/dependency:
+`@rangojs/router/testing` (unit + integration, under a Vite-driven Vitest
+project), `@rangojs/router/testing/vitest` (the `rangoTestConfig`/`rangoTestAliases`
+setup preset), `@rangojs/router/testing/dom` (`renderRoute`, needs RTL + a DOM
+env), `@rangojs/router/testing/e2e` (the Playwright harness),
+`@rangojs/router/testing/flight` (real Flight, react-server condition only), and
+`@rangojs/router/testing/flight-matchers` (the Flight matchers).
+
+The hard problem in an RSC app is that the layer you reach for is dictated by
+**what the behavior touches** — a pure predicate is a one-line vitest test; a real
+async Server Component cannot be a plain node test at all. Pick the layer
+**first**, then the primitive. Reaching one layer too high (e2e for a reverse
+function) is slow; one too low (a node test for Flight) fails to compile or
+silently asserts nothing.
+
+This page is the router. Each primitive's full API (options, the seeded context
+your code receives, the return shape), a minimal recipe, and its caveats live in a
+dedicated sub-file linked from the decision tree below. Read the one for your case.
+
+> **Setup is the first wall.** The vitest projects, the `rangoTestConfig` vs
+> `rangoTestAliases` choice (Node >= 23), and the react-server `@rangojs/router ->
+index.rsc.ts` alias are all in [`./setup.md`](./setup.md). Read it before writing
+> `vitest.config.ts`. Platform bindings (`env.DB`/DO/R2) are your own double —
+> [`./bindings.md`](./bindings.md).
+
+For the long-form prose guide (setup walkthrough + migration), see
+[`docs/testing.md`](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md)
+(the `docs/` directory is not shipped in the published package, so this is an
+absolute link).
+
+## When to use
+
+Use this skill when adding or changing tests for a Rango app: a loader,
+middleware, a server action, a route map, a client component, a response route,
+cache/SWR behavior, prerender, or a navigation/PE flow.
+
+Two non-negotiable mandates (from the repo's `CLAUDE.md`, and they apply to
+consumer apps too):
+
+- **Every e2e covers BOTH dev and production.** A dev-only e2e is not acceptable.
+  Use `parityDescribe` — it generates the dev and production describes from one
+  body, so you cannot forget the prod half. See [`./e2e-parity.md`](./e2e-parity.md).
+- **Progressive-enhancement parity** is a first-class assertion. A form-driven
+  flow must produce the same observable result with JS on and JS off. Use
+  `expectParity`.
+
+## The read-first shape
+
+Four import roots, each matched to the dependency/runtime that can load it — this
+split is forced by hard walls, not preference:
+
+- `@rangojs/router/testing` — unit + integration primitives. Run these under a
+  **Vite-driven Vitest** project with the rango Vite plugin active (the router
+  internals import the `@rangojs/router:version` virtual; without the plugin, the
+  preset stubs it). References neither React, RTL, Playwright, nor the RSC runtime.
+- `@rangojs/router/testing/dom` — `renderRoute` (the RTL component stub). Kept
+  separate so the unit barrel stays free of React/RTL; it lazy-loads
+  `@testing-library/react` and needs a DOM env (happy-dom/jsdom).
+- `@rangojs/router/testing/e2e` — the Playwright harness. Kept separate so it
+  loads in a plain (non-Vite) Playwright runner; the helpers take your
+  `test`/`expect`, so this entry never imports `@playwright/test` at runtime.
+- `@rangojs/router/testing/flight` — real Flight rendering. Its serializer loads
+  only under the `react-server` node condition; pulling it elsewhere throws.
+
+The single rule that drives everything:
+
+> **If the behavior needs a real Flight render, it cannot be a plain vitest node
+> test.** It is either `renderToFlightString`/`renderServerTree`/`renderHandler`
+> (under the react-server vitest project) or an e2e test. There is no middle
+> ground in node.
+
+## Decision tree: behavior -> layer -> primitive
+
+Each primitive links to its sub-file (API + recipe + caveats).
+
+| The behavior is…                                                                                                                   | Layer        | Primitive                                                                                     | Import root                      |
+| ---------------------------------------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------- | -------------------------------- |
+| a pure function / `reverse` / `href` / a predicate (`revalidate`, `isAction`)                                                      | unit + types | [`reverse`/`@ts-expect-error`](./reverse-and-types.md)                                        | `@rangojs/router/testing`        |
+| one loader's data logic                                                                                                            | unit (node)  | [`runLoader`](./loader.md)                                                                    | `@rangojs/router/testing`        |
+| a loader's cookie / header / redirect output (auth-loader pattern)                                                                 | unit (node)  | [`runLoaderResult`](./loader.md)                                                              | `@rangojs/router/testing`        |
+| one middleware's ordering / short-circuit / cookie+header merge                                                                    | unit (node)  | [`runMiddleware`](./middleware.md)                                                            | `@rangojs/router/testing`        |
+| a `"use server"` action's cookie / header / flash output (even on `throw redirect()`)                                              | unit (node)  | [`runInRequestContext`](./server-actions.md)                                                  | `@rangojs/router/testing`        |
+| a `transition({ when })` gate (keep/drop) against nav source / target / action metadata                                            | unit (node)  | `runTransitionWhen` (`{ kept, whenContext }`)                                                 | `@rangojs/router/testing`        |
+| a handle's `collect`/accumulator, or a seeded handle read                                                                          | unit         | [`collectHandle` / seeded `handles`](./handles.md)                                            | `@rangojs/router/testing`        |
+| a CLIENT component reading router context (`useParams`/`useReverse`/`Outlet`/`useNavigation`/`useLoader`)                          | unit (DOM)   | [`renderRoute`](./client-components.md)                                                       | `@rangojs/router/testing/dom`    |
+| a redirect / status / headers / cookies / **response route** (json/text/html/xml/md), no Flight                                    | integration  | [`dispatch`](./response-routes.md)                                                            | `@rangojs/router/testing`        |
+| a real async **Server Component** (assert what it rendered: typed boundary props, server-rendered host content, inlined-vs-island) | RSC unit     | [`renderServerTree` + `findClientBoundaries`/`findElements`](./server-tree.md)                | `@rangojs/router/testing/flight` |
+| the exact Flight **wire payload** shape (a drift snapshot)                                                                         | RSC unit     | [`renderToFlightString` + `toMatchFlightSnapshot`](./flight.md)                               | `@rangojs/router/testing/flight` |
+| a real route **handler** `(ctx) => rsc` (params/loaders/vars -> rendered RSC + effects)                                            | RSC unit     | [`renderHandler`](./render-handler.md)                                                        | `@rangojs/router/testing/flight` |
+| navigation, hydration, PE parity, view transitions, real SSR                                                                       | e2e          | [`createRangoE2E` -> `parityDescribe`/`expectParity`](./e2e-parity.md)                        | `@rangojs/router/testing/e2e`    |
+| cache hit/miss/stale, prerender (= a cache hit by design)                                                                          | e2e + signal | [`assertCacheStatus` (header) / `assertCacheDecision` (telemetry sink)](./cache-prerender.md) | `@rangojs/router/testing[/e2e]`  |
+| generated route map drift vs runtime                                                                                               | unit (node)  | [`assertGeneratedRoutesMatch`](./reverse-and-types.md)                                        | `@rangojs/router/testing`        |
+| a platform binding (`env.DB` / Durable Object / `env.R2`)                                                                          | unit/integr. | [your own double via `env`](./bindings.md)                                                    | (any primitive's `env` option)   |
+
+Cross-references to the DSL skills: `/loader`, `/middleware`, `/server-actions`,
+`/handler-use`, `/hooks`, `/response-routes`, `/route`, `/caching`, `/prerender`,
+`/typesafety`.
+
+## Sub-files
+
+- Cross-cutting: [`setup.md`](./setup.md), [`bindings.md`](./bindings.md)
+- Unit (node): [`loader.md`](./loader.md), [`middleware.md`](./middleware.md),
+  [`server-actions.md`](./server-actions.md), [`handles.md`](./handles.md),
+  [`reverse-and-types.md`](./reverse-and-types.md)
+- Unit (DOM): [`client-components.md`](./client-components.md)
+- RSC unit: [`flight.md`](./flight.md), [`server-tree.md`](./server-tree.md),
+  [`render-handler.md`](./render-handler.md)
+- Integration: [`response-routes.md`](./response-routes.md)
+- E2E: [`e2e-parity.md`](./e2e-parity.md), [`cache-prerender.md`](./cache-prerender.md)
+
+## Pre-push checklist (mirror CLAUDE.md)
+
+Before pushing, run all of these and fix any failure:
+
+1. `pnpm run typecheck` (or `pnpm exec tsc --noEmit`)
+2. `pnpm run test:unit` (node + DOM vitest)
+3. `pnpm run test:unit:rsc` (the react-server Flight project)
+4. `pnpm run lint`
+5. `pnpm run format`
+
+And: **every e2e has a production counterpart.** `parityDescribe` makes this
+automatic — if you wrote a plain `test.describe` for a behavior, convert it.