@rangojs/router 0.0.0-experimental.122 → 0.0.0-experimental.124

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.122",
+  "version": "0.0.0-experimental.124",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -126,57 +126,97 @@
     "./host/testing": {
       "types": "./src/host/testing.ts",
       "default": "./src/host/testing.ts"
+    },
+    "./testing": {
+      "types": "./src/testing/index.ts",
+      "default": "./src/testing/index.ts"
+    },
+    "./testing/vitest": {
+      "types": "./src/testing/vitest.ts",
+      "default": "./dist/testing/vitest.js"
+    },
+    "./testing/dom": {
+      "types": "./src/testing/dom.entry.ts",
+      "default": "./src/testing/dom.entry.ts"
+    },
+    "./testing/e2e": {
+      "types": "./src/testing/e2e/index.ts",
+      "default": "./src/testing/e2e/index.ts"
+    },
+    "./testing/flight": {
+      "types": "./src/testing/flight.entry.ts",
+      "react-server": "./src/testing/flight.entry.ts",
+      "default": "./src/testing/flight.entry.ts"
+    },
+    "./testing/flight-matchers": {
+      "types": "./src/testing/flight-matchers.ts",
+      "default": "./src/testing/flight-matchers.ts"
     }
   },
   "publishConfig": {
     "access": "public",
     "tag": "experimental"
   },
-  "scripts": {
-    "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
-    "prepublishOnly": "pnpm build",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
-    "test": "playwright test",
-    "test:ui": "playwright test --ui",
-    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-routes --project=hmr-basename --project=hmr-prerender --no-deps --workers=1",
-    "test:unit": "vitest run",
-    "test:unit:watch": "vitest"
-  },
   "dependencies": {
     "@types/debug": "^4.1.12",
     "@vitejs/plugin-rsc": "^0.5.26",
     "debug": "^4.4.1",
     "magic-string": "^0.30.17",
     "picomatch": "^4.0.3",
-    "rsc-html-stream": "^0.0.7"
+    "rsc-html-stream": "^0.0.7",
+    "tinyexec": "^0.3.2"
   },
   "devDependencies": {
     "@playwright/test": "^1.49.1",
-    "@shared/e2e": "workspace:*",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@types/node": "^24.10.1",
-    "@types/react": "catalog:",
-    "@types/react-dom": "catalog:",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
     "esbuild": "^0.27.0",
+    "happy-dom": "^20.10.1",
     "jiti": "^2.6.1",
-    "react": "catalog:",
-    "react-dom": "catalog:",
-    "tinyexec": "^0.3.2",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
     "typescript": "^5.3.0",
-    "vitest": "^4.0.0"
+    "vitest": "^4.0.0",
+    "@shared/e2e": "0.0.1"
   },
   "peerDependencies": {
     "@cloudflare/vite-plugin": "^1.38.0",
+    "@playwright/test": "^1.49.1",
+    "@testing-library/react": ">=16",
     "@vitejs/plugin-rsc": "^0.5.26",
     "react": ">=19.2.6 <20",
     "react-dom": ">=19.2.6 <20",
-    "vite": "^8.0.0"
+    "vite": "^8.0.0",
+    "vitest": ">=3"
   },
   "peerDependenciesMeta": {
     "@cloudflare/vite-plugin": {
       "optional": true
     },
+    "@playwright/test": {
+      "optional": true
+    },
+    "@testing-library/react": {
+      "optional": true
+    },
     "vite": {
       "optional": true
+    },
+    "vitest": {
+      "optional": true
     }
+  },
+  "scripts": {
+    "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm dlx esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
+    "test": "playwright test",
+    "test:ui": "playwright test --ui",
+    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-routes --project=hmr-basename --project=hmr-prerender --no-deps --workers=1",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest",
+    "test:unit:rsc": "vitest run --config vitest.rsc.config.ts"
   }
-}
+}

package/skills/caching/SKILL.md

@@ -471,6 +471,7 @@ cache({ store: checkoutCache }, () => [
 ```typescript
 import { urls } from "@rangojs/router";
 import { MemorySegmentCacheStore } from "@rangojs/router/cache";
+import * as CartActions from "./actions/cart";
 
 // Custom store for checkout (short TTL)
 const checkoutCache = new MemorySegmentCacheStore({
@@ -499,7 +500,7 @@ export const urlpatterns = urls(({ path, layout, cache, loader, revalidate }) =>
     path("/shop/product/:slug", ProductPage, { name: "product" }, () => [
       loader(ProductLoader, () => [cache({ ttl: 120 })]),
       loader(CartLoader, () => [
-        revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
+        revalidate((ctx) => ctx.isAction(CartActions) || undefined),
       ]),
     ]),
   ]),

package/skills/hooks/SKILL.md

@@ -683,33 +683,44 @@ ProductState.delete();
 | `.write()`  | yes (replace this slot) | no                                | throws              |
 | `.delete()` | yes (remove this slot)  | no                                | throws              |
 
-## Cache Hooks
+## Cache Control
 
-### useClientCache()
+### invalidateClientCache()
 
-Manually control client-side navigation cache:
+Force the client's caches to miss after a mutation the router can't see (a REST
+call, a WebSocket push, a login). It is a plain function, not a hook, so it works
+from module-level callbacks too. Imported from the root entry `@rangojs/router`,
+it is selected by export conditions: in a client component it marks the caches
+stale immediately; from a handler/server component it writes a rotated
+`Set-Cookie` for the responding client.
 
 ```tsx
 "use client";
-import { useClientCache } from "@rangojs/router/client";
+import { invalidateClientCache } from "@rangojs/router";
 
 function SaveButton() {
-  const { clear } = useClientCache();
-
   const handleSave = async () => {
     await fetch("/api/data", {
       method: "POST",
       body: JSON.stringify(data),
     });
 
-    // Invalidate cache after mutation
-    clear();
+    // Invalidate the client's caches after the mutation
+    invalidateClientCache();
   };
 
   return <button onClick={handleSave}>Save</button>;
 }
 ```
 
+A module-level subscription works the same way (no component needed):
+
+```ts
+import { invalidateClientCache } from "@rangojs/router";
+
+socket.on("catalog-updated", () => invalidateClientCache());
+```
+
 **Use cases**: REST API mutations, WebSocket updates, non-RSC data changes.
 
 ## Outlet Components
@@ -892,22 +903,22 @@ See `/links` for the full URL generation guide. `ctx.reverse()` is server-only;
 
 ## Hook Summary
 
-| Hook                  | Purpose                           | Returns                                                            |
-| --------------------- | --------------------------------- | ------------------------------------------------------------------ |
-| `useParams()`         | Route params                      | `Readonly<T>` (default `Record<string, string>`) or selected value |
-| `usePathname()`       | Current pathname                  | `string`                                                           |
-| `useSearchParams()`   | URL search params                 | `ReadonlyURLSearchParams`                                          |
-| `useHref()`           | Mount-aware href                  | `(path) => string`                                                 |
-| `useMount()`          | Current include() mount path      | `string`                                                           |
-| `useReverse()`        | Local reverse for imported routes | `(name, params?, search?) => string`                               |
-| `useNavigation()`     | Reactive navigation state         | state, location, isStreaming                                       |
-| `useRouter()`         | Stable router actions             | push, replace, refresh, prefetch, back, forward                    |
-| `useSegments()`       | URL path & segment IDs            | path, segmentIds, location                                         |
-| `useLinkStatus()`     | Link pending state                | { pending }                                                        |
-| `useLoader()`         | Loader data (strict)              | data, isLoading, error                                             |
-| `useFetchLoader()`    | Loader with on-demand fetch       | data, load, isLoading                                              |
-| `useRefreshLoaders()` | Refresh cross-loader group(s)     | `() => (groups: string \| string[]) => Promise<void>`              |
-| `useHandle()`         | Accumulated handle data           | T (handle type)                                                    |
-| `useAction()`         | Server action state               | state, error, result                                               |
-| `useLocationState()`  | History state (persists or flash) | T \| undefined                                                     |
-| `useClientCache()`    | Cache control                     | { clear }                                                          |
+| Hook                      | Purpose                                                        | Returns                                                            |
+| ------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `useParams()`             | Route params                                                   | `Readonly<T>` (default `Record<string, string>`) or selected value |
+| `usePathname()`           | Current pathname                                               | `string`                                                           |
+| `useSearchParams()`       | URL search params                                              | `ReadonlyURLSearchParams`                                          |
+| `useHref()`               | Mount-aware href                                               | `(path) => string`                                                 |
+| `useMount()`              | Current include() mount path                                   | `string`                                                           |
+| `useReverse()`            | Local reverse for imported routes                              | `(name, params?, search?) => string`                               |
+| `useNavigation()`         | Reactive navigation state                                      | state, location, isStreaming                                       |
+| `useRouter()`             | Stable router actions                                          | push, replace, refresh, prefetch, back, forward                    |
+| `useSegments()`           | URL path & segment IDs                                         | path, segmentIds, location                                         |
+| `useLinkStatus()`         | Link pending state                                             | { pending }                                                        |
+| `useLoader()`             | Loader data (strict)                                           | data, isLoading, error                                             |
+| `useFetchLoader()`        | Loader with on-demand fetch                                    | data, load, isLoading                                              |
+| `useRefreshLoaders()`     | Refresh cross-loader group(s)                                  | `() => (groups: string \| string[]) => Promise<void>`              |
+| `useHandle()`             | Accumulated handle data                                        | T (handle type)                                                    |
+| `useAction()`             | Server action state                                            | state, error, result                                               |
+| `useLocationState()`      | History state (persists or flash)                              | T \| undefined                                                     |
+| `invalidateClientCache()` | Force client caches to miss (function, not a hook; root entry) | `void`                                                             |

package/skills/host-router/SKILL.md

@@ -189,12 +189,26 @@ Logs pattern matching, route registration, and cookie override decisions to cons
 ## Testing
 
 ```typescript
-import { createTestRequest, testPattern } from "@rangojs/router/host/testing";
+import {
+  createTestRequest,
+  testPattern,
+  matchesHost,
+} from "@rangojs/router/host/testing";
 
-// Test pattern matching
+// Test pattern matching (host-only)
 testPattern("admin.*", "admin.example.com"); // true
 testPattern([".", "www.*"], "example.com"); // true
 
+// Path-based patterns need the third pathname arg (defaults to "/", so a
+// host-only pattern still works with two args):
+testPattern("**.workers.dev/admin", "foo.workers.dev", "/admin"); // true
+
+// Or match a pattern against a real Request (hostname + pathname from the URL):
+matchesHost(
+  "**.workers.dev/admin",
+  new Request("https://foo.workers.dev/admin"),
+); // true
+
 // Create requests for integration tests
 const request = createTestRequest({
   host: "admin.example.com",

package/skills/intercept/SKILL.md

@@ -107,8 +107,10 @@ Use named revalidation contracts on both the outer producer and the intercept
 consumer when they share `ctx.set()` data:
 
 ```typescript
-export const revalidateProductShell = ({ actionId }) =>
-  actionId?.includes("src/actions/product.ts#") || undefined;
+import * as ProductActions from "./actions/product";
+
+export const revalidateProductShell = (ctx) =>
+  ctx.isAction(ProductActions) || undefined;
 
 layout(ProductLayout, () => [
   revalidate(revalidateProductShell), // producer reruns

package/skills/layout/SKILL.md

@@ -202,8 +202,10 @@ layout(<ShopLayout />, () => [
 ])
 
 // Or revalidate based on conditions
+import * as CartActions from "./actions/cart";
+
 layout(<CartLayout />, () => [
-  revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
+  revalidate((ctx) => ctx.isAction(CartActions) || undefined),
 
   path("/cart", CartPage, { name: "cart" }),
 ])
@@ -221,8 +223,9 @@ them on both producer and consumer segments:
 
 ```typescript
 // revalidation-contracts.ts
-export const revalidateCartData = ({ actionId }) =>
-  actionId?.includes("src/actions/cart.ts#addToCart") || undefined;
+import { addToCart } from "./actions/cart";
+
+export const revalidateCartData = (ctx) => ctx.isAction(addToCart) || undefined;
 ```
 
 ```typescript
@@ -242,9 +245,10 @@ You can also package them as importable handoff helpers:
 ```typescript
 // revalidation-contracts.ts
 import { revalidate } from "@rangojs/router";
+import * as AuthActions from "./actions/auth";
 
-export const revalidateAuthData = ({ actionId }) =>
-  actionId?.includes("src/actions/auth.ts#") || undefined;
+export const revalidateAuthData = (ctx) =>
+  ctx.isAction(AuthActions) || undefined;
 export const revalidateAuth = () => [revalidate(revalidateAuthData)];
 ```
 
@@ -262,6 +266,7 @@ layout(<ShellLayout />, () => [
 ```typescript
 import { urls } from "@rangojs/router";
 import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+import * as CartActions from "./actions/cart";
 
 function ShopLayout() {
   return (
@@ -291,7 +296,7 @@ export const shopPatterns = urls(({ path, layout, parallel, loader, revalidate }
   }, () => [
     // Layout loaders
     loader(CartLoader, () => [
-      revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
+      revalidate((ctx) => ctx.isAction(CartActions) || undefined),
     ]),
 
     // Parallel routes

package/skills/loader/SKILL.md

@@ -249,6 +249,8 @@ export const OrderLoader = createLoader(async (ctx) => {
 Add caching or revalidation to specific loaders:
 
 ```typescript
+import * as CartActions from "./actions/cart";
+
 path("/product/:slug", ProductPage, { name: "product" }, () => [
   // Cached loader
   loader(ProductLoader, () => [cache({ ttl: 300 })]),
@@ -261,7 +263,7 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
   // Loader that revalidates after cart actions (defer otherwise — keeps the
   // permissive loader defaults for navigation and other actions intact)
   loader(CartLoader, () => [
-    revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
+    revalidate((ctx) => ctx.isAction(CartActions) || undefined),
   ]),
 ]);
 ```
@@ -781,10 +783,12 @@ export const CartLoader = createLoader(async (ctx) => {
 });
 
 // urls.tsx — register loaders in the DSL
+import * as CartActions from "./actions/cart";
+
 export const urlpatterns = urls(({ path, layout, loader, loading, cache, revalidate }) => [
   layout(<ShopLayout />, () => [
     loader(CartLoader, () => [
-      revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
+      revalidate((ctx) => ctx.isAction(CartActions) || undefined),
     ]),
 
     path("/shop/product/:slug", ProductPage, { name: "product" }, () => [

package/skills/middleware/SKILL.md

@@ -67,8 +67,10 @@ For shared segment data, use named revalidation contracts on both the producer
 and consumer segments, even when middleware is present in the chain.
 
 ```typescript
-export const revalidateCartData = ({ actionId }) =>
-  actionId?.includes("src/actions/cart.ts#") || undefined;
+import * as CartActions from "./actions/cart";
+
+export const revalidateCartData = (ctx) =>
+  ctx.isAction(CartActions) || undefined;
 
 layout(CartLayout, () => [
   middleware(cartRenderMiddleware),

package/skills/migrate-nextjs/SKILL.md

@@ -317,9 +317,11 @@ NOT cache invalidation — it is `revalidate()`, controlling which segments
 re-rendering:
 
 ```typescript
+import { updateBlog } from "./actions/blog";
+
 // Re-run this layout when a blog action fires
 layout(BlogLayout, () => [
-  revalidate(({ actionId }) => actionId?.includes("updateBlog") || undefined),
+  revalidate((ctx) => ctx.isAction(updateBlog) || undefined),
   path("/blog/:slug", BlogPost, { name: "blogPost" }),
 ]);
 

package/skills/parallel/SKILL.md

@@ -330,6 +330,8 @@ parallel({
 Control when parallel routes revalidate:
 
 ```typescript
+import * as CartActions from "./actions/cart";
+
 parallel(
   {
     "@cart": () => <CartSummary />,
@@ -337,7 +339,7 @@ parallel(
   () => [
     loader(CartLoader),
     // Revalidate when cart actions occur
-    revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
+    revalidate((ctx) => ctx.isAction(CartActions) || undefined),
   ]
 )
 ```
@@ -360,8 +362,10 @@ the parallel consumer:
 
 ```typescript
 // revalidation-contracts.ts
-export const revalidateCartData = ({ actionId }) =>
-  actionId?.includes("src/actions/cart.ts#") || undefined;
+import * as CartActions from "./actions/cart";
+
+export const revalidateCartData = (ctx) =>
+  ctx.isAction(CartActions) || undefined;
 
 layout(CartLayout, () => [
   revalidate(revalidateCartData), // producer reruns
@@ -429,6 +433,7 @@ function MyLayout() {
 ```typescript
 import { urls } from "@rangojs/router";
 import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+import * as CartActions from "./actions/cart";
 
 function ShopLayout() {
   return (
@@ -479,7 +484,7 @@ export const shopPatterns = urls(({
       () => [
         loader(CartLoader),
         loading(<CartSkeleton />),
-        revalidate(({ actionId }) => actionId?.includes("Cart") || undefined),
+        revalidate((ctx) => ctx.isAction(CartActions) || undefined),
       ]
     ),
 

package/skills/rango/SKILL.md

@@ -154,6 +154,12 @@ returned, for outcome-conditional revalidation. The arg also exposes `actionId`
 (raw `path#export`), `actionUrl`, `formData`, `method`, and `stale` (cross-tab
 `_rsc_stale` signal). All are `undefined` on plain navigation (no action).
 
+Two idioms, picked by what an _unrelated_ action should do. `ctx.isAction()`
+returns a raw boolean, so combine it with `|| undefined` to **defer** ("mine,
+else let the default decide": `ctx.isAction(CartActions) || undefined`) or leave
+it bare to **suppress** ("mine only": `ctx.isAction(CartActions)`). Prefer the
+defer form unless a sibling segment must own the unrelated-action decision.
+
 ```ts
 // re-render only when checkout actually succeeded; defer otherwise
 revalidate((ctx) => (ctx.isAction(checkout) && ctx.actionResult?.ok) || undefined),
@@ -232,6 +238,12 @@ Grouped by concern — read when you need to…
 | `/bundle-analysis` | Audit your app's production bundle for server leaks and oversized chunks |
 | `/debug-manifest`  | Inspect route manifest structure                                         |
 
+**Testing**:
+
+| Skill      | Description                                                                                                                     |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `/testing` | Unit (loaders/middleware/reverse/components), integration (dispatch/Flight), and e2e (dev+prod parity, progressive enhancement) |
+
 **Setup, types & migration**:
 
 | Skill                   | Description                                     |

package/skills/route/SKILL.md

@@ -246,10 +246,12 @@ the producer route and the consumer child segments.
 
 ```typescript
 // revalidation-contracts.ts
+import * as CheckoutActions from "./actions/checkout";
+
 // 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#") || undefined;
+export const revalidateCheckoutData = (ctx) =>
+  ctx.isAction(CheckoutActions) || undefined;
 
 path("/checkout", CheckoutPage, { name: "checkout" }, () => [
   revalidate(revalidateCheckoutData), // producer (route handler) reruns

package/skills/testing/SKILL.md

@@ -0,0 +1,129 @@
+---
+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`        |
+| 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 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.