@rangojs/router 0.0.0-experimental.d20dd405 → 0.0.0-experimental.d98a8e9d

package/skills/response-routes/SKILL.md

@@ -68,16 +68,16 @@ export const urlpatterns = urls(({ path, layout, include }) => [
 
 ## Available Tags
 
-| Tag      | Usage           | Handler returns    | Auto-wrap                |
-| -------- | --------------- | ------------------ | ------------------------ |
-| `json`   | `path.json()`   | plain object/array | `{ data: T }` envelope   |
-| `text`   | `path.text()`   | string             | text/plain Response      |
-| `html`   | `path.html()`   | string             | text/html Response       |
-| `xml`    | `path.xml()`    | string             | application/xml Response |
-| `md`     | `path.md()`     | string             | text/markdown Response   |
-| `image`  | `path.image()`  | Response           | pass-through             |
-| `stream` | `path.stream()` | Response           | pass-through             |
-| `any`    | `path.any()`    | Response           | pass-through             |
+| Tag      | Usage           | Handler returns    | Auto-wrap                     |
+| -------- | --------------- | ------------------ | ----------------------------- |
+| `json`   | `path.json()`   | plain object/array | bare JSON value (no envelope) |
+| `text`   | `path.text()`   | string             | text/plain Response           |
+| `html`   | `path.html()`   | string             | text/html Response            |
+| `xml`    | `path.xml()`    | string             | application/xml Response      |
+| `md`     | `path.md()`     | string             | text/markdown Response        |
+| `image`  | `path.image()`  | Response           | pass-through                  |
+| `stream` | `path.stream()` | Response           | pass-through                  |
+| `any`    | `path.any()`    | Response           | pass-through                  |
 
 ## ResponseHandlerContext
 
@@ -139,22 +139,31 @@ path.json(
 );
 ```
 
-## JSON Envelope
+## JSON Wire Shape
 
-`path.json()` handlers return plain data. The framework auto-wraps it
-in a `ResponseEnvelope<T>` discriminated union:
+`path.json()` handlers return plain data. The framework serializes the handler's
+return value **verbatim** (no envelope) on success, and an RFC 9457 `problem+json`
+body on error. Discriminate with `res.ok` / the HTTP status — there is no in-body
+`data`/`error` union:
 
 ```typescript
-// Success: HTTP 200
-{ "data": { "status": "ok", "timestamp": 1700000000 } }
-
-// Error: HTTP 404 (or whatever status RouterError specifies)
-{ "error": { "message": "Product 999 not found", "code": "NOT_FOUND" } }
+// Success: HTTP 200, content-type application/json
+{ "status": "ok", "timestamp": 1700000000 }
+
+// Error: HTTP 404 (or whatever status RouterError specifies),
+//        content-type application/problem+json
+{
+  "title": "Not Found",
+  "status": 404,
+  "detail": "Product 999 not found",
+  "code": "NOT_FOUND"
+  // "stack": included in development only
+}
 ```
 
 ### Error Handling with RouterError
 
-Throw `RouterError` to return structured error envelopes:
+Throw `RouterError` to return a structured `problem+json` body:
 
 ```typescript
 import { RouterError } from "@rangojs/router";
@@ -199,25 +208,27 @@ path.json(
 
 ## Client-Side Type Safety
 
-### ResponseEnvelope and isResponseError
+### Discriminating success vs. error with res.ok
+
+Success bodies are the bare value; error bodies are RFC 9457 `ProblemDetails`.
+Branch on `res.ok` (or the HTTP status) — not an in-body union:
 
 ```typescript
 "use client";
-import type { ResponseEnvelope, ResponseError } from "@rangojs/router/client";
-import { isResponseError } from "@rangojs/router/client";
+import type { ProblemDetails } from "@rangojs/router";
 
 // Fetch a typed response
 const res = await fetch("/api/products/1");
-const result: ResponseEnvelope<Product> = await res.json();
 
-if (isResponseError(result)) {
-  // result.error: ResponseError  (message, code?, type?)
-  // result.data: undefined
-  console.error(result.error.message);
+if (!res.ok) {
+  // Error body: application/problem+json
+  const problem: ProblemDetails = await res.json();
+  // problem.detail: string, problem.code: string, problem.status: number
+  console.error(problem.code, problem.detail);
 } else {
-  // result.data: Product
-  // result.error: undefined
-  console.log(result.data.name);
+  // Success body: the bare value (no envelope)
+  const product: Product = await res.json();
+  console.log(product.name);
 }
 ```
 
@@ -230,28 +241,78 @@ import type { RouteResponse } from "@rangojs/router";
 
 // From the apiPatterns module (before include)
 type HealthData = RouteResponse<typeof apiPatterns, "health">;
-// = ResponseEnvelope<{ status: string; timestamp: number }>
+// = { status: string; timestamp: number }
 
 type ProductsData = RouteResponse<typeof apiPatterns, "products">;
-// = ResponseEnvelope<{ id: string; name: string; price: number }[]>
+// = { id: string; name: string; price: number }[]
 ```
 
-### PathResponse (global lookup by URL pattern)
+`RouteResponse` is the bare success payload (the JSON wire shape) — the same value
+a `fetch().then(r => r.json())` yields on a 2xx. Error bodies are `ProblemDetails`,
+keyed off `res.ok` at runtime, not part of this type.
 
-Look up response type from the merged route map by URL pattern:
+### Rango.PathResponse (global lookup by URL pattern or concrete path)
+
+`Rango.PathResponse` is ambient (no import) and reads from `RegisteredRoutes`,
+which carries response payload metadata. That surface is **not** auto-wired —
+without the augmentation below, `Rango.PathResponse` falls back to the generated
+path/search map, or to a permissive map when nothing is generated. Either way, it
+has no response payload metadata, so response routes resolve to `never`:
 
 ```typescript
-import type { PathResponse } from "@rangojs/router/client";
+// router.tsx
+export const router = createRouter({ document: Document }).routes(urlpatterns);
 
+declare global {
+  namespace Rango {
+    interface RegisteredRoutes extends typeof router.routeMap {}
+  }
+}
+```
+
+With that in place, look up the response type by URL pattern (ambient, no import):
+
+```typescript
 // After include("/api", apiPatterns) in main urls
-type Health = PathResponse<"/api/health">;
-// = ResponseEnvelope<{ status: string; timestamp: number }>
+type Health = Rango.PathResponse<"/api/health">;
+// = { status: string; timestamp: number }
+
+// RSC routes (no JSON payload) return never
+type Home = Rango.PathResponse<"/">;
+// = never
+```
 
-// RSC routes return ResponseEnvelope<never>
-type Home = PathResponse<"/">;
-// = ResponseEnvelope<never>
+`Rango.PathResponse` also accepts a **concrete path**, so it types a `fetch`
+wrapper whose response is inferred from the path you pass:
+
+```typescript
+import { href } from "@rangojs/router/client";
+
+async function get<T extends Rango.Path>(
+  path: T,
+): Promise<Rango.PathResponse<T>> {
+  return fetch(href(path)).then((r) => r.json());
+}
+
+const product = await get("/api/products/42"); // Product (bare value)
 ```
 
+Pattern keys (`/:id`) match exactly; a concrete path under a _nested_ dynamic
+route can match several patterns and union their responses.
+
+`Rango.PathResponse` reports the JSON **wire** shape, not the handler's raw
+return: `path.json()` serializes with `JSON.stringify`, so a handler returning
+`{ createdAt: Date }` resolves to the bare `{ createdAt: string }`. This
+runs through the ambient `Rango.JsonSerialize<T>` transform (`Date -> string`,
+honors `toJSON()`, drops functions/`undefined`, `bigint -> never`). The
+`RouteResponse` surface below applies the same `Rango.JsonSerialize` transform, so
+both response lookups report the identical wire shape.
+
+For local/scoped response typing without global augmentation, prefer
+`RouteResponse<typeof patterns, "routeName">` (see the section above) — it reads
+the response payload straight from the `urls()` patterns and needs no
+`RegisteredRoutes` wiring.
+
 ### ParamsFor with Response Routes
 
 ```typescript
@@ -361,15 +422,17 @@ export const urlpatterns = urls(({ path, include }) => [
 
 ```typescript
 import type { RouteResponse } from "@rangojs/router";
-import type { PathResponse, ParamsFor } from "@rangojs/router/client";
+import type { ParamsFor } from "@rangojs/router/client";
 
-// Scoped (before mount) -- use the module directly
+// Scoped (before mount) -- use the module directly, no global wiring needed
 type Stats = RouteResponse<typeof blogApiPatterns, "stats">;
-// = ResponseEnvelope<{ views: number; visitors: number }>
+// = { views: number; visitors: number }
 
-// After mounting -- names get prefixed
-type BlogStats = PathResponse<"/blog/api/stats">;
-// = ResponseEnvelope<{ views: number; visitors: number }>
+// After mounting -- names get prefixed.
+// Rango.PathResponse needs `RegisteredRoutes extends typeof router.routeMap` (see above),
+// otherwise it resolves to never.
+type BlogStats = Rango.PathResponse<"/blog/api/stats">;
+// = { views: number; visitors: number }
 
 // Params work through nested includes
 type LikesParams = ParamsFor<"blog.api.likes">;
@@ -413,7 +476,11 @@ best-effort basis.
 1. `path.json()` tags the route at the trie level with a MIME type
 2. `coreRequestHandler()` checks the tag before the RSC pipeline
 3. Tagged routes short-circuit: handler runs, Response is returned directly
-4. JSON routes auto-wrap return values in `{ data }` / `{ error }` envelope
+4. JSON routes serialize the return value verbatim (bare) on success; a thrown error becomes an RFC 9457 `problem+json` body (`application/problem+json`)
 5. Client-side navigation to response routes gets `X-RSC-Reload` header, triggering hard navigation
 6. Response types flow through `_responses` phantom type on `UrlPatterns`, propagated by `include()`
 7. When multiple routes share a URL pattern, the trie merges them for content negotiation (see `/mime-routes`)
+
+## Consuming response routes
+
+To call your own response-route JSON APIs from first-party TypeScript with a typed client (typed params, typed payloads inferred from the handler, no `.data`, typed `ProblemDetails` errors), see `/api-client` — a copy-paste recipe over `RouteResponse` + `ExtractParams` + a client-safe path builder. External/third-party consumers use the plain wire directly: bare JSON on success, `application/problem+json` on error.

package/skills/route/SKILL.md

@@ -234,14 +234,22 @@ Cacheable vars (the default) can be read freely inside cache scopes.
 
 ### Revalidation Contracts for Handler Data
 
+> **Scope: `revalidate()` is a partial-render concern, not a cache concern.**
+> It decides whether this segment re-runs and streams to the client on a
+> navigation or action — never whether a cached value is stale. The cache
+> decides hit/miss/ttl/swr independently and never reads `revalidate()`. See
+> `/cache-guide` → "Two axes" and `/rango` → "The shape of rango".
+
 Handler-first guarantees apply within a single full render pass. For partial
 action revalidation, define named revalidation contracts and reuse them on both
 the producer route and the consumer child segments.
 
 ```typescript
 // revalidation-contracts.ts
+// Defer (|| undefined), not ?? false: a hard `false` short-circuits the chain,
+// so when the same segment composes multiple contracts the later ones never run.
 export const revalidateCheckoutData = ({ actionId }) =>
-  actionId?.includes("src/actions/checkout.ts#") ?? false;
+  actionId?.includes("src/actions/checkout.ts#") || undefined;
 
 path("/checkout", CheckoutPage, { name: "checkout" }, () => [
   revalidate(revalidateCheckoutData), // producer (route handler) reruns
@@ -270,9 +278,6 @@ path("/checkout", CheckoutPage, { name: "checkout" }, () => [
 ]);
 ```
 
-For scope/revalidation guarantees and non-guarantees, see:
-[docs/execution-model.md](../../docs/internal/execution-model.md)
-
 ## Redirects
 
 ### Basic redirect

package/skills/router-setup/SKILL.md

@@ -71,7 +71,7 @@ urls(
 ## Router Options
 
 ```typescript
-interface RSCRouterOptions<TEnv> {
+interface RangoOptions<TEnv> {
   // URL patterns from urls() function
   urls: UrlPatterns;
 
@@ -405,7 +405,7 @@ interface AppBindings {
   KV: KVNamespace;
 }
 
-// Variables declared via module augmentation
+// Variables declared via global namespace augmentation
 interface AppVariables {
   user?: { id: string; name: string };
 }
@@ -417,7 +417,7 @@ const router = createRouter<AppBindings>({
 
 // Register types globally for implicit typing
 declare global {
-  namespace RSCRouter {
+  namespace Rango {
     interface Env extends AppBindings {}
     interface Vars extends AppVariables {}
   }

package/skills/server-actions/SKILL.md

@@ -32,35 +32,37 @@ Actions mutate state; route handlers and loaders read the latest state. After
 an action finishes, Rango performs a server-side revalidation render for the
 matched route so the UI receives fresh segment output and loader data.
 
-The main control point is `revalidate(({ actionId }) => ...)` on the segment
-that owns the data. This applies to `path()` handlers, `layout()` handlers,
-`parallel()` slots, `intercept()` routes, and loader registrations:
+The main control point is `revalidate((ctx) => ...)` on the segment that owns
+the data. Match specific actions by imported reference with `ctx.isAction()`;
+use raw `actionId` only when you intentionally need path or directory matching.
+This applies to `path()` handlers, `layout()` handlers, `parallel()` slots,
+`intercept()` routes, and loader registrations:
 
 ```typescript
 // urls.tsx — path/layout/parallel/intercept/loader/revalidate are passed in by urls()
 import { urls } from "@rangojs/router";
+import * as CartActions from "./actions/cart";
 
 export const urlpatterns = urls(({ path, loader, revalidate }) => [
   // The loader belongs to the route that consumes its data — nest it inside
   // the owning path() so the segment owns its data dependency.
   path("/cart", CartPage, { name: "cart" }, () => [
-    revalidate(
-      ({ actionId }) => actionId?.startsWith("src/actions/cart.ts#") ?? false,
-    ),
+    revalidate((ctx) => ctx.isAction(CartActions) || undefined),
     loader(CartLoader, () => [
-      revalidate(
-        ({ actionId }) => actionId?.startsWith("src/actions/cart.ts#") ?? false,
-      ),
+      revalidate((ctx) => ctx.isAction(CartActions) || undefined),
     ]),
   ]),
 ]);
 ```
 
-For module-level `"use server"` files, the `actionId` passed to every
+`ctx.isAction()` resolves the imported action reference the same way the router
+derives `actionId`, so it matches in both dev and production and survives action
+renames/moves as type errors instead of silent substring drift.
+
+For module-level `"use server"` files, the raw `actionId` passed to every
 server-side `revalidate()` predicate is path-bearing in the server/RSC
-environment in both dev and production: `src/actions/cart.ts#addToCart`. This
-is intentional so path, layout, parallel, intercept, and loader revalidation
-predicates can filter by action file, directory, or export name.
+environment in both dev and production: `src/actions/cart.ts#addToCart`. This is
+the escape hatch for broad filters by action file, directory, or export name.
 
 Actions and the follow-up revalidation render share one request context.
 Values written in the action with `ctx.set(MyVar, value)` or `ctx.set("key",
@@ -91,15 +93,18 @@ export async function switchTenant(tenantId: string) {
 ```typescript
 // urls.tsx
 import { urls } from "@rangojs/router";
+import * as TenantActions from "./actions/tenant";
 import { ChangedTenant } from "./context";
 
 export const urlpatterns = urls(({ path, revalidate }) => [
   path("/dashboard/:tenantId", DashboardPage, { name: "dashboard" }, () => [
-    revalidate(
-      ({ actionId, context }) =>
-        actionId?.startsWith("src/actions/tenant.ts#") &&
-        context.get(ChangedTenant) === context.params.tenantId,
-    ),
+    revalidate((ctx) => {
+      if (!ctx.isAction(TenantActions)) return undefined;
+      return (
+        ctx.context.get(ChangedTenant) === ctx.context.params.tenantId ||
+        undefined
+      );
+    }),
   ]),
 ]);
 ```
@@ -380,13 +385,18 @@ re-render so the UI updates. Rango runs the action, then evaluates
 `revalidate()` on matched segments and loaders. Each path, layout, parallel,
 intercept, or loader rule decides whether that piece re-renders/re-resolves.
 
-The `actionId` arrives as part of the revalidation context — match it to
-scope re-runs to specific actions.
+Use `ctx.isAction()` for specific actions or modules. It accepts one action,
+several actions, or a namespace import (`import * as CartActions`). Pair it with
+`|| undefined` for "revalidate on match, otherwise defer to defaults/downstream
+rules."
 
 ```typescript
 // urls.tsx — inside the urls() callback. Nest each loader inside the path(),
 // layout(), or parallel() that owns its data so the route tree mirrors the
 // data dependencies.
+import * as AccountActions from "./actions/account";
+import * as CartActions from "./actions/cart";
+
 urls(({ path, loader, revalidate }) => [
   path("/", HomePage, { name: "home" }, () => [
     // Loader data re-runs by default after any action. Opt out with revalidate(() => false).
@@ -395,36 +405,37 @@ urls(({ path, loader, revalidate }) => [
 
   // Re-render the cart page handler AND re-resolve its loader after cart actions
   path("/cart", CartPage, { name: "cart" }, () => [
-    revalidate(
-      ({ actionId }) => actionId?.startsWith("src/actions/cart.ts#") ?? false,
-    ),
+    revalidate((ctx) => ctx.isAction(CartActions) || undefined),
     loader(CartLoader, () => [
-      revalidate(
-        ({ actionId }) => actionId?.startsWith("src/actions/cart.ts#") ?? false,
-      ),
+      revalidate((ctx) => ctx.isAction(CartActions) || undefined),
     ]),
   ]),
 
-  // Re-run after any action under src/actions/account/
+  // Re-run after any action exported by the account actions module
   path("/account", AccountPage, { name: "account" }, () => [
     loader(AccountLoader, () => [
-      revalidate(
-        ({ actionId }) => actionId?.startsWith("src/actions/account/") ?? false,
-      ),
+      revalidate((ctx) => ctx.isAction(AccountActions) || undefined),
     ]),
   ]),
 ]);
 ```
 
-`actionId` is stable per action. For actions exported from a module-level
-`"use server"` file, the ID is prefixed with the source file path
-(`src/actions/cart.ts#addToCart`), so substring matching by file path is the
-recommended scope. **Inline `"use server"` actions** (declared inside an RSC
-component) intentionally keep their hashed IDs — file paths are withheld
-from the client for security. If you need file-path-based revalidation
-predicates, define the action in a module-level `"use server"` file rather
-than inline. See `/loader` for the full revalidation contract (deferred
-returns, soft suggestions).
+The raw `actionId` string stays available for broad path filters:
+
+```typescript
+// Match any action under src/actions/account/, including modules not imported here.
+revalidate(
+  ({ actionId }) => actionId?.startsWith("src/actions/account/") || undefined,
+);
+```
+
+For actions exported from a module-level `"use server"` file, the ID is prefixed
+with the source file path (`src/actions/cart.ts#addToCart`). **Inline `"use
+server"` actions** (declared inside an RSC component) intentionally keep their
+hashed IDs — file paths are withheld from the client for security. If you need
+file-path-based revalidation predicates, define the action in a module-level
+`"use server"` file rather than inline. See `/loader` for the full revalidation
+contract (deferred returns, soft suggestions).
 
 ### Cross-segment dependencies
 
@@ -434,8 +445,9 @@ stale context. Share the same `revalidate` predicate on both producer and
 consumer:
 
 ```typescript
-const revalidateCart = ({ actionId }) =>
-  actionId?.startsWith("src/actions/cart.ts#") ?? false;
+import * as CartActions from "./actions/cart";
+
+const revalidateCart = (ctx) => ctx.isAction(CartActions) || undefined;
 
 urls(({ path, layout, loader, revalidate }) => [
   layout(CartLayout, () => [

package/skills/testing/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: testing
+description: Test @rangojs/router apps — unit (loaders/middleware/reverse/components), integration (dispatch/Flight), and e2e (dev+prod parity, progressive enhancement)
+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`        |
+| 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 handle's `collect`/accumulator, or a seeded handle read                                                 | unit         | [`collectHandle` / seeded `handles`](./handles.md)                             | `@rangojs/router/testing[/dom]`  |
+| 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** / Flight serialization shape                                            | RSC unit     | [`renderToFlightString` + `toMatchFlight`](./flight.md)                        | `@rangojs/router/testing/flight` |
+| a client island's **typed props** / the **server-rendered** host content                                  | RSC unit     | [`renderServerTree` + `findClientBoundaries`/`findElements`](./server-tree.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` / 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.