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

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

@@ -288,21 +288,40 @@ export const Product = Passthrough(ProductDef, async (ctx) => {
 Use `Passthrough()` whenever the Next.js route has `dynamicParams: true` (the
 default) or serves an open-ended param space. See `/prerender` for full API.
 
-### Revalidation: different model
+### Revalidation: two distinct axes
 
-Next.js uses path/tag-based cache invalidation (`revalidatePath`, `revalidateTag`)
-to bust cached responses. Rango does not currently have a direct equivalent.
+Next.js conflates two things under "revalidation." Rango separates them — and
+tag-based cache invalidation now maps directly.
 
-In Rango, separate these two concepts:
+**1. Cache invalidation (bust cached values) — direct equivalent.** Tag entries
+with `cache({ tags })` or, inside a `"use cache"` function, runtime
+`cacheTag(...tags)`. Then invalidate by tag:
 
-**Partial rendering revalidation** — `revalidate()` controls which segments
-(layouts, paths, loaders, parallels) should re-run during partial action
-re-rendering. This is about the segment tree, not cache invalidation:
+```typescript
+// Next.js                    Rango
+// revalidateTag("products")  →  await updateTag("products")  // in a server action: awaitable,
+//                                                            // read-your-own-writes (next render is fresh)
+//                            or  revalidateTag("products")    // in a route handler / webhook:
+//                                                            // background, non-blocking (hard-purge)
+```
+
+`updateTag` is awaitable and immediate; `revalidateTag` is fire-and-forget. Both
+hard-purge (the next read re-renders fresh); the only difference is awaitability —
+despite the Next.js name, `revalidateTag` here is NOT stale-while-revalidate.
+Built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`) index by tag. Next's
+`revalidatePath` has no path-based equivalent — tag the relevant entries instead.
+
+**2. Partial-render selection (which segments re-run after an action).** This is
+NOT cache invalidation — it is `revalidate()`, controlling which segments
+(layouts, paths, loaders, parallels) recompute during partial action
+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" }),
 ]);
 
@@ -323,15 +342,18 @@ cache({ ttl: 60, swr: 300 }, () => [
 ]);
 ```
 
-The key shift is:
+The two axes compose: `updateTag()` / `revalidateTag()` bust cached values;
+`revalidate()` selects which segments re-render and stream to the client after an
+action.
 
-- Next.js asks "which cached path or tag should I invalidate?"
-- Rango asks "which segments should re-run after this action?"
+When migrating:
 
-When migrating `revalidatePath()` / `revalidateTag()` usage, the Rango version
-usually is not a 1:1 API replacement. Instead, decide which layouts, routes,
-loaders, or parallels should recompute after an action and declare
-`revalidate()` at those segment boundaries.
+- `revalidateTag(tag)` → `await updateTag(tag)` (in a server action) or
+  `revalidateTag(tag)` (in a route handler / webhook). Effectively 1:1.
+- `revalidatePath(path)` → no path-based equivalent; tag the entries on that
+  route (`cache({ tags })` / `cacheTag(...)`) and invalidate by tag.
+- To also force specific segments to re-render after the action (independent of
+  cache busting), attach a `revalidate()` rule at those segment boundaries.
 
 ## 4. Middleware
 
@@ -463,7 +485,7 @@ Server actions work the same way — `"use server"` directive, `useActionState`,
 
 Key difference: in Rango, route middleware does NOT wrap action execution. Actions only see global middleware context. Use `getRequestContext()` in actions to access `ctx.set()`/`ctx.get()`.
 
-Next.js's `revalidatePath()` / `revalidateTag()` have no direct equivalent — Rango partially re-renders matched route segments (path/layout/parallel/intercept) and re-resolves their loaders, and you scope re-runs by attaching a `revalidate(({ actionId }) => ...)` rule to any segment or loader registration. See `/server-actions` for the full pattern (validation, error handling, file uploads) and `/loader` for revalidation rule semantics.
+Next.js's `revalidateTag()` maps directly: tag entries via `cache({ tags })` / `cacheTag(...)`, then invalidate. **In a server action use `await updateTag(tag)`** — it is read-your-own-writes, so the action's own re-render sees fresh data; `revalidateTag(tag)` is a background (non-blocking) hard-purge and is NOT read-your-own-writes, so reserve it for route handlers / webhooks (calling it from an action can leave that action's re-render stale). `revalidatePath()` has no path-based equivalent — tag the route's entries instead. Separately, to force specific matched segments (path/layout/parallel/intercept) and their loaders to re-render after an action, attach a `revalidate(({ actionId }) => ...)` rule to that segment or loader registration. See `/server-actions` for the full pattern (validation, error handling, file uploads), `/caching` for tag invalidation, and `/loader` for revalidation rule semantics.
 
 ## 8. Metadata / Head
 

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

@@ -28,10 +28,10 @@ with the shape, then pick a primitive.
   cache hit streams UI instantly while loaders resolve fresh alongside). Opt into
   caching explicitly. See `/loader` → "Parallel and streaming".
 - **One identity, one store** — loaders, handles, cached fns, and actions are all
-  `path#export`; all caches share one store. Entries expire by TTL/SWR; cache
-  entries accept an optional `tags` field, but built-in stores do not yet index
-  or invalidate by tag, so tag-based invalidation (`revalidateTag`) is a
-  forward-looking API requiring a custom store.
+  `path#export`; all caches share one store. Entries expire by TTL/SWR, and are
+  tagged via `cache({ tags })` or runtime `cacheTag(...tags)`; built-in stores
+  index by tag and invalidate via `updateTag(...tags)` (awaitable, read-your-own-writes)
+  or `revalidateTag(...tags)` (background, non-blocking).
 - **Type-safe end to end** — route names, params, search schemas, loader return
   types, context vars, and `href` / `reverse` are checked at compile time
   (`/typesafety`).
@@ -85,10 +85,10 @@ To decide where something can live: **does it define a URL? structure, stays in
   (`set`/`header`/`setTheme`/`onResponse`/`setLocationState`) throw; `ctx.use(Handle)`
   is captured on miss and replayed on hit. (The non-cacheable read guard is a
   separate `cache()`-boundary check — see the correctness bullet below.)
-- One identity `path#export` (`functionId`/`$$id`/`actionId`); one store. The
-  cross-cutting freshness mechanism today is TTL/SWR expiry; cache entries accept
-  an optional `tags` field, but built-in stores do not yet index or invalidate by
-  tag, so `revalidateTag` is forward-looking (requires a custom store).
+- One identity `path#export` (`functionId`/`$$id`/`actionId`); one store. Freshness
+  is TTL/SWR expiry plus tag-based invalidation: tag via `cache({ tags })` /
+  `cacheTag(...tags)`, then `updateTag(...tags)` (awaitable) or `revalidateTag(...tags)`
+  (background). Built-in stores index by tag.
 - `useLoader` / `useHandle` / `useFetchLoader` are client-only.
 - Caches are correctness-first: persistent store keys are version-segmented (no
   cross-deploy drift), the forward/back cache is mutation-aware, and
@@ -111,13 +111,13 @@ To decide where something can live: **does it define a URL? structure, stays in
 Same words, different jobs — this is the most common source of the
 `revalidate()`-is-caching misread.
 
-| You may know                               | Maps to Rango axis | Watch out                                                                                                                                                                                                                       |
-| ------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Next.js `export const revalidate = N`      | **Axis 1** (cache) | Same word, opposite meaning. Next's `revalidate` is time-based cache expiry; Rango's `revalidate()` is **axis 2**. Use `cache({ ttl })` for the Next behavior.                                                                  |
-| Next.js `revalidatePath` / `revalidateTag` | **Axis 1** (cache) | Cache busting. No shipped equivalent: entries accept `tags`, but built-in stores don't yet index/invalidate by tag, so `revalidateTag` is forward-looking (custom store); today entries expire by TTL/SWR. No `revalidatePath`. |
-| React Router / Remix `shouldRevalidate`    | **Axis 2**         | This is the correct mental model for Rango's `revalidate()`.                                                                                                                                                                    |
-| HTTP `Cache-Control` / ISR                 | **Axis 1**         | Edge/document layer — see `/document-cache`. Separate from both `cache()` and `revalidate()`.                                                                                                                                   |
-| Remix/RR `loader`                          | live data          | Like Rango loaders, fresh per request — but Rango loaders run in parallel and stream (latency overlaps first paint), and can opt into caching on demand.                                                                        |
+| You may know                            | Maps to Rango axis | Watch out                                                                                                                                                                                                                                                                               |
+| --------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Next.js `export const revalidate = N`   | **Axis 1** (cache) | Same word, opposite meaning. Next's `revalidate` is time-based cache expiry; Rango's `revalidate()` is **axis 2**. Use `cache({ ttl })` for the Next behavior.                                                                                                                          |
+| Next.js `revalidateTag` / `updateTag`   | **Axis 1** (cache) | Cache busting by tag. Tag via `cache({ tags })` / `cacheTag(...tags)`; invalidate with `updateTag(...tags)` (awaitable, read-your-own-writes) or `revalidateTag(...tags)` (background, non-blocking). Built-in stores index by tag. No `revalidatePath` (path-based busting); use tags. |
+| React Router / Remix `shouldRevalidate` | **Axis 2**         | This is the correct mental model for Rango's `revalidate()`.                                                                                                                                                                                                                            |
+| HTTP `Cache-Control` / ISR              | **Axis 1**         | Edge/document layer — see `/document-cache`. Separate from both `cache()` and `revalidate()`.                                                                                                                                                                                           |
+| Remix/RR `loader`                       | live data          | Like Rango loaders, fresh per request — but Rango loaders run in parallel and stream (latency overlaps first paint), and can opt into caching on demand.                                                                                                                                |
 
 See `/cache-guide` for the axis-1 decision guide, `/loader` and `/route` for
 `revalidate()` (axis 2), and `/document-cache` for the edge layer.
@@ -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.

package/skills/testing/bindings.md

@@ -0,0 +1,89 @@
+# Testing platform bindings — your double is the seam
+
+**Layer:** cross-cutting (unit/integration) · **Seam:** the `env` option every primitive takes
+
+The node primitives test the router's seams; the moment your loader/middleware/action calls a **platform binding** (`env.DB`, a Durable Object stub, `env.R2`), you have crossed out of rango and into your app's I/O. The router machinery is real — what you seed is the binding double behind it, injected through `env`.
+
+## Where it plugs in
+
+rango ships **no doubles** for platform bindings — they are app- and schema-specific. You build the double and inject it through the `env` option that every primitive already accepts:
+
+- `runLoader(body, { env })`
+- `runMiddleware(fn, { request, env })`
+- `runInRequestContext(fn, { request, env })`
+- `renderHandler(handler, { request, env })`
+- `dispatch(router, { request, env })`
+- `renderToFlightString(el, { env })`
+
+Inside the run, `getRequestContext().env` (and anything that reads it — `cache()`, your loaders, your middleware) sees the object you passed.
+
+## Driver contract
+
+The work here is matching the binding's **driver contract**, not its public API. A double that satisfies the public surface but not the driver's wire shape mounts green and proves nothing.
+
+- **Per-method shapes.** `drizzle-orm/d1` serves SELECTs through `.raw()` and writes (INSERT/UPDATE/DELETE) through `.run()`. The two return different shapes and hit different code paths in the decoder. Model **both**.
+- **`.raw()` (reads).** Must serve **positional row arrays in schema-column order**, with the driver-level encodings so the decoder round-trips `Date`/JSON. NOT `{ column: value }` objects.
+- **`.run()` (writes).** Returns `{ success, meta }` — no rows — and bypasses the row responder entirely.
+
+## Recipe
+
+```ts
+import { describe, it, expect } from "vitest";
+import {
+  runLoader,
+  runMiddleware,
+  runInRequestContext,
+} from "@rangojs/router/testing";
+import { bundleLoaderBody } from "../app/loaders";
+import { requireMembership } from "../app/middleware";
+import { authorizeAction } from "../app/actions";
+
+// A D1Database double satisfying drizzle-orm/d1's driver contract.
+const fakeD1 = makeFakeD1({
+  // .raw() serves positional rows in schema-column order, driver-encoded.
+  raw: () => [[1, "acme", "2026-01-01T00:00:00.000Z"]],
+  // .run() returns { success, meta }, no rows.
+  run: () => ({ success: true, meta: { changes: 1 } }),
+});
+
+describe("bindings seam", () => {
+  it("loader reads through env.DB", async () => {
+    const result = await runLoader(bundleLoaderBody, { env: { DB: fakeD1 } });
+    expect(result).toMatchObject({ slug: "acme" });
+  });
+
+  it("middleware reads through env.DB", async () => {
+    const { nextCalled, response } = await runMiddleware(requireMembership, {
+      request: "/t/acme/edit",
+      env: { DB: fakeD1 },
+    });
+    expect(nextCalled).toBe(1); // membership passed, chain continued
+    expect(response.status).toBe(200);
+  });
+
+  it("action reads through env.DB", async () => {
+    const { result } = await runInRequestContext(
+      () => authorizeAction({ id: 1 }),
+      {
+        env: { DB: fakeD1 },
+        request: "/t/acme/edit",
+      },
+    );
+    expect(result).toBe(true);
+  });
+});
+```
+
+## Caveats
+
+- rango ships **no doubles** for platform bindings (`env.DB`, Durable Objects, `env.R2`) by design — they are app- and schema-specific. Inject your own double through the `env` option every primitive takes.
+- This is usually the **single biggest effort** in a consumer unit suite, and the work is matching the **driver contract**, not the binding's public API.
+- `drizzle-orm/d1`: a `D1Database` double must serve **positional row arrays in schema-column order** for drizzle's `.raw()` path (with driver-level encodings so the decoder round-trips `Date`/JSON), NOT `{ column: value }` objects — an object-shaped double returns silently-wrong or empty rows.
+- The contract is **per-method**: SELECTs go through `.raw()` (positional rows); writes (INSERT/UPDATE/DELETE) go through `.run()`, which returns `{ success, meta }` (no rows) and bypasses the row responder entirely. Model **both** paths — a read-only `.raw()` double silently no-ops every write.
+- Keep the double at the **binding boundary**; never mock a rango primitive to dodge building it.
+
+## See also
+
+- (cross-cutting)
+- Siblings: `./loader.md`, `./middleware.md`, `./server-actions.md`
+- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "What these primitives deliberately don't cover (the platform-bindings paragraph)"