@rangojs/router 0.0.0-experimental.80 → 0.0.0-experimental.80daa23e

package/skills/testing/flight.md

@@ -0,0 +1,91 @@
+# Pinning the Flight wire payload — renderToFlightString
+
+**Layer:** RSC unit (react-server project) · **Import:** `@rangojs/router/testing/flight` + `@rangojs/router/testing/flight-matchers` · **DSL it tests:** an async Server Component / Flight output (see `/route`)
+
+> **Prefer `renderServerTree` (see [`./server-tree.md`](./server-tree.md)) for assertions on a Flight render** — it deserializes to a traversable tree with TYPED boundary props (a `Date` is a `Date`, not the opaque `$D...` encoding). Reach for `renderToFlightString` + the wire matchers (`toMatchFlight`/`toMatchFlightSnapshot`) only to pin the raw wire payload SHAPE — a `toMatchFlightSnapshot` drift snapshot. That is the niche/escape-hatch case; for "testing an async Server Component (assert what it rendered)" start at `./server-tree.md`.
+
+`renderToFlightString` runs the REAL react-server-dom serializer the router uses at runtime — your async Server Component genuinely renders to its Flight wire string in plain node, with a request context active for the render. What you SEED is the request, headers, env, params, routeName, and vars that context exposes.
+
+## API
+
+### Options — `RenderToFlightStringOptions`
+
+| Field       | Type                     | Meaning                                                                                                                                                                                                                                                                      |
+| ----------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `request`   | `Request \| string`      | The request the render runs under: a `Request`, or a URL string (absolute or path). Defaults to `http://localhost/`. A component reading `getRequestContext()` sees this request's url/cookies. When a `Request` is passed, its headers are used and `headers` is ignored.   |
+| `headers`   | `HeadersInit`            | Request headers (e.g. Cookie) visible to the server tree, used only when `request` is a string.                                                                                                                                                                              |
+| `env`       | `unknown`                | Env / bindings exposed as `ctx.env`. Defaults to `{}`.                                                                                                                                                                                                                       |
+| `params`    | `Record<string, string>` | Route params exposed via `ctx.params` and loader contexts.                                                                                                                                                                                                                   |
+| `routeName` | `string`                 | Matched route name (drives `ctx.routeName` and scoped reverse).                                                                                                                                                                                                              |
+| `routeMap`  | `Record<string, string>` | Route name -> pattern map scoping `ctx.reverse()` (like `renderHandler`). Without it, a component that reverses resolves against the GLOBAL route map and is order-dependent on whatever router registered last. Pass the router-under-test's map for deterministic reverse. |
+| `vars`      | `VarsInit`               | Variables a prior middleware would have set, visible via `ctx.get(...)`. Object form (`{ user }`) or `[key, value]` tuples (`[[userVar, u]]`).                                                                                                                               |
+
+### Context — `RequestContext` (what your component receives)
+
+A request context is active for the whole render, so an async Server Component can read it via `getRequestContext()` / the router's server APIs. The notable surfaces seeded from the options above:
+
+| Field       | Type                                                                       | Meaning                                                               |
+| ----------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `request`   | `Request`                                                                  | The backing request (from `request`/`headers`).                       |
+| `url`       | `URL`                                                                      | The request URL.                                                      |
+| `env`       | `unknown`                                                                  | Env / bindings (from `env`).                                          |
+| `params`    | `Record<string, string>`                                                   | Route params (from `params`).                                         |
+| `routeName` | `string \| undefined`                                                      | Matched route name (from `routeName`).                                |
+| `get`       | `<T>(v: ContextVar<T>) => T \| undefined; <K extends string>(key: K): any` | Read a var seeded via `vars` (by `createVar()` handle or string key). |
+
+### Returns — `Promise<string>`
+
+The Flight wire string for the rendered tree. Assert on it with the matchers (register via `expect.extend(flightMatchers)`):
+
+```ts
+expect(await renderToFlightString(<C />)).toMatchFlight("substring"); // containment
+expect(await renderToFlightString(<C />)).toMatchFlightSnapshot();     // normalized snapshot
+```
+
+`toMatchFlight(substring)` is containment (not equality) on the normalized payload; `toMatchFlightSnapshot()` snapshots the normalized payload. Both matchers live at `@rangojs/router/testing/flight-matchers` and run ONLY under the react-server vitest project (see `./setup.md`).
+
+## Recipe
+
+Name the file `*.rsc-test.{ts,tsx}` and run `pnpm test:unit:rsc`:
+
+```tsx
+import { it, expect } from "vitest";
+import { renderToFlightString } from "@rangojs/router/testing/flight";
+import { flightMatchers } from "@rangojs/router/testing/flight-matchers";
+expect.extend(flightMatchers);
+
+// Pure leaf server components: data comes in as props, not getRequestContext.
+async function Greeting({ name }: { name: string }) {
+  const who = await Promise.resolve(name);
+  return <h1>Hello {who}</h1>;
+}
+
+async function ItemView({ id }: { id: string }) {
+  const item = await Promise.resolve({ id, label: `Item ${id}` });
+  return <article>{item.label}</article>;
+}
+
+it("renders an async server component to Flight", async () => {
+  const flight = await renderToFlightString(<Greeting name="Ada" />);
+  expect(flight).toMatchFlight("Ada");
+});
+
+it("snapshots the normalized payload", async () => {
+  const flight = await renderToFlightString(<ItemView id="7" />);
+  expect(flight).toMatchFlightSnapshot();
+});
+```
+
+## Caveats
+
+- Leaf / server-only: a client island in the tree emits an un-hydratable `I[...]` import row against the empty client manifest. Keep Flight tests to leaf server components; test full pages at e2e.
+- Requires the react-server vitest project (see `./setup.md`): `resolve.conditions` includes `react-server`, the `@rangojs/router -> index.rsc.ts` alias, `NODE_ENV=production`, and the worker `execArgv`. Name files `*.rsc-test.{ts,tsx}` and run `pnpm test:unit:rsc`. The main vitest project must NOT set `react-server` (it would flip React to the no-hooks server build).
+- A component that imports a server API (`getRequestContext`, `cookies`) from the bare `@rangojs/router` barrel works ONLY with the `index.rsc.ts` alias wired (see `./setup.md`); without it the bare import resolves to the throwing out-of-react-server stub. `renderToFlightString` / `renderServerTree` self-diagnose this exact misconfiguration — they reject with an actionable message naming `rangoTestAliases`, rather than surfacing the opaque stub error. Pure-leaf components that take all data as props need no barrel import and are the simplest case.
+- `toMatchFlight` is containment (substring), not equality — the row framing (prefixes/quoting) is an internal serializer detail, so pin the rendered text/shape, not the framing. `toMatchFlightSnapshot()` snapshots the normalized payload; run under `NODE_ENV=production` for the cleanest, most stable bytes.
+- No hydration / no interaction here — that is the e2e tier. For typed assertions on a client boundary's props (a `Date` back as a `Date`), or to confirm an island actually crossed the boundary, use `renderServerTree` (see `./server-tree.md`).
+
+## See also
+
+- `/route` — the DSL this tests
+- Siblings: `./setup.md`, `./server-tree.md`, `./render-handler.md`
+- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "renderToFlightString — real async Server Components"

package/skills/testing/handles.md

@@ -0,0 +1,153 @@
+# Testing a handle — collectHandle, plus the loader read/write and client read paths
+
+**Layer:** unit (node + DOM) · **Import:** `@rangojs/router/testing` (collectHandle), `@rangojs/router/testing/dom` (renderRoute) · **DSL it tests:** a handle e.g. Breadcrumbs/Meta (see `/handler-use`, `/breadcrumbs`)
+
+A handle's `collect`/accumulator (the `createHandle(collect)` argument that maps per-segment pushed values into one accumulated result) is otherwise unreachable — `createHandle` keeps it in a private registry keyed by `$$id`. These primitives test it from different angles: `collectHandle` runs the REAL registered collect on per-segment values you SEED; `runLoader` seeds the POST-collect accumulated value a loader READS (`ctx.get(handle)` after the barrier); `runLoaderResult(...).handlePushes` records what a loader WRITES (`ctx.use(SomeHandle)({...})`, in push order); `renderRoute` seeds the RAW pushed values for a client component reading `useHandle`. None of them run the real push -> accumulate -> barrier wiring (that stays e2e).
+
+## API
+
+### `collectHandle(handle, segments)` — `src/testing/collect-handle.ts`
+
+| Param      | Type                                  | Meaning                                                                                                                                                                                                                                              |
+| ---------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `handle`   | `Handle<TData, TAccumulated>`         | The handle whose registered collect to run.                                                                                                                                                                                                          |
+| `segments` | `ReadonlyArray<ReadonlyArray<TData>>` | Per-segment pushed values, one inner array per route segment, in **parent -> child** order. Empty inner arrays are filtered before the collect runs (matching production `collectHandleData` — a segment that pushed nothing is not passed through). |
+
+**Returns** `TAccumulated` — exactly what the handle's collect produces (the default identity collect's per-segment `TData[][]`, or a custom accumulator's value). If the handle's module was never imported (collect unregistered), it falls back to that same identity default and **warns** — a handle with a custom collect that failed to register would otherwise return the wrong shape silently.
+
+### runLoader option — `handles` — `src/testing/run-loader.ts`
+
+| Field      | Type                                        | Meaning                                                                                                                                                                                                                                                                  |
+| ---------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `handles`  | `ReadonlyArray<readonly [Handle, unknown]>` | Seeds the value `ctx.get(SomeHandle)` returns — the POST-collect **ACCUMULATED** value (singular `unknown`), what a loader reads after `await ctx.rendered()`. Matched by handle reference. Pair with `rendered`.                                                        |
+| `rendered` | `boolean \| (() => void \| Promise<void>)`  | Mocks the `ctx.rendered()` barrier (throws by default). `true` resolves it immediately; a function controls timing/side effects. A `ctx.get(handle)` read before the barrier settles throws, exactly as in production. (`ctx.use(handle)` — the WRITE — is never gated.) |
+
+### renderRoute option — `handles` — `src/testing/render-route.tsx`
+
+| Field     | Type                                          | Meaning                                                                                                                                                                                                                                                                   |
+| --------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `handles` | `ReadonlyArray<readonly [Handle, unknown[]]>` | Seeds the CLIENT read path for `useHandle(handle)` — the RAW **pushed values array** (`unknown[]`), the values a route's handlers would have pushed. Attached to the leaf route segment under the handle's `$$id`, so `useHandle` runs the handle's REAL collect on them. |
+
+**Shape contrast:** `renderRoute` feeds the barrier INPUT (the pushes, `unknown[]`); `runLoader` feeds its OUTPUT (the single accumulated value, `unknown`).
+
+**Across navigation:** seeded `handles` are applied once at the initial render and PERSIST across `router.navigate()` within the same test (like `loaderData`) — unlike a real navigation, which re-runs handlers. A layout/page reading `useHandle` still resolves the seeded values after `navigate()`.
+
+## Recipe
+
+```ts
+// collectHandle.test.ts — the pure collect, no route match
+import { describe, it, expect } from "vitest";
+import { collectHandle } from "@rangojs/router/testing";
+import { createHandle } from "@rangojs/router";
+
+// Opt into a flat list; the default collect groups per segment (TData[][]).
+type Crumb = { label: string; href: string };
+const Breadcrumbs = createHandle<Crumb, Crumb[]>((segments) => segments.flat());
+
+it("flattens per-segment crumbs in parent->child order", () => {
+  const home = { label: "Home", href: "/" };
+  const post = { label: "P", href: "/p" };
+  expect(collectHandle(Breadcrumbs, [[home], [post]])).toEqual([home, post]);
+});
+
+it("runs a custom 'last wins' collect", () => {
+  const PageTitle = createHandle<string, string>((s) => s.flat().at(-1) ?? "");
+  expect(collectHandle(PageTitle, [["Home"], ["Products"], ["Shoes"]])).toBe(
+    "Shoes",
+  );
+});
+```
+
+```ts
+// loader-reads-handle.test.ts — a loader reading accumulated handle data after the barrier
+import { it, expect } from "vitest";
+import { runLoader } from "@rangojs/router/testing";
+import { RenderedProducts } from "../src/handles"; // a createHandle(...)
+
+const livePricesBody = async (ctx) => {
+  await ctx.rendered(); // barrier: handle data is now readable
+  const ids = ctx.get(RenderedProducts) as string[];
+  return ids.map((id) => ({ id, price: 9.99 }));
+};
+
+it("reads the accumulated handle value (seed the OUTPUT, mock the barrier)", async () => {
+  const data = await runLoader(livePricesBody, {
+    rendered: true,
+    handles: [[RenderedProducts, ["widget-a", "widget-b"]]], // singular accumulated value
+  });
+  expect(data).toEqual([
+    { id: "widget-a", price: 9.99 },
+    { id: "widget-b", price: 9.99 },
+  ]);
+});
+```
+
+```ts
+// loader-writes-handle.test.ts — a loader PUSHING meta/breadcrumbs (handler parity)
+import { it, expect } from "vitest";
+import { runLoaderResult } from "@rangojs/router/testing";
+import { Meta } from "../src/handles";
+
+const productBody = async (ctx) => {
+  const product = { name: "Widget", slug: "widget" };
+  ctx.use(Meta)({ title: `${product.name} — Shop` });
+  return product;
+};
+
+it("records loader handle writes in push order", async () => {
+  const { result, handlePushes } = await runLoaderResult(productBody);
+  expect(result?.name).toBe("Widget");
+  expect(handlePushes).toEqual([
+    { handle: Meta, value: { title: "Widget — Shop" } },
+  ]);
+});
+```
+
+```tsx
+// breadcrumb-trail.test.tsx — a client component reading useHandle
+// @vitest-environment happy-dom
+import { it, expect, afterEach } from "vitest";
+import { cleanup } from "@testing-library/react";
+import { renderRoute } from "@rangojs/router/testing/dom";
+import { useHandle } from "@rangojs/router/client";
+import { Breadcrumbs } from "../src/handles";
+
+afterEach(cleanup);
+
+function BreadcrumbTrail() {
+  const crumbs = useHandle(Breadcrumbs); // accumulated client-side via the real collect
+  return <nav>{crumbs.map((c) => c.label).join(" / ")}</nav>;
+}
+
+it("renders the seeded trail (seed the INPUT pushes, the collect runs)", async () => {
+  const { getByText } = await renderRoute(
+    [{ path: "/p", Component: BreadcrumbTrail }],
+    {
+      handles: [
+        [
+          Breadcrumbs,
+          [
+            { label: "Home", href: "/" },
+            { label: "P", href: "/p" },
+          ],
+        ],
+      ], // raw pushes array
+    },
+  );
+  expect(getByText("Home / P")).toBeTruthy();
+});
+```
+
+## Caveats
+
+- `collectHandle` tests the pure collect/accumulator in ISOLATION (parent -> child segment order, empty arrays filtered to match production). It does NOT run the real push -> accumulate -> barrier wiring — that stays e2e.
+- renderRoute `handles` seeds the CLIENT read path with the RAW pushed values array (`unknown[]`), attached to the leaf segment. Handle data accumulates GLOBALLY (not segment-scoped like loaders), so a LAYOUT reading the same handle sees the seeded values too, not just the leaf route.
+- runLoader `handles` seeds the POST-collect ACCUMULATED value (singular `unknown`) a loader reads via `ctx.get(handle)` after `await ctx.rendered()`; pair with `{ rendered: true }`. Shape contrast: renderRoute feeds the barrier INPUT (pushes[]), runLoader feeds its OUTPUT (the accumulated value).
+- Loader WRITES are the other direction: `ctx.use(SomeHandle)({...})` records into `runLoaderResult(...).handlePushes` (push order; a `.defer()` resolver's value is recorded when the resolver runs). Nothing to seed — assert the envelope.
+- The renderRoute path is the CLIENT tree only: it does NOT catch server/client boundary remount bugs, real Flight serialization errors, or loader execution.
+
+## See also
+
+- `/handler-use`, `/breadcrumbs` — the DSL this tests
+- Siblings: `./loader.md`, `./client-components.md`, `./render-handler.md`
+- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Testing a handle's collect/accumulator"

package/skills/testing/loader.md

@@ -0,0 +1,130 @@
+# Testing a loader — runLoader
+
+**Layer:** unit (node) · **Import:** `@rangojs/router/testing` · **DSL it tests:** `loader()` (see `/loader`)
+
+`runLoader` runs a loader against a real `RequestContext` (cookies, headers, `ctx.get`, `ctx.reverse` all resolve) in plain node — that machinery is REAL; what you SEED is the params, env, vars, search, route map, and any `ctx.use` dependency data. Pass a registered `createLoader()` handle (its fn is recovered from the registry) or the raw async body `(ctx) => ...`.
+
+## API
+
+### Options — `RunLoaderOptions<TEnv>`
+
+| Field           | Type                                                            | Meaning                                                                                                                                                                                                                    |
+| --------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `params`        | `Record<string, string>`                                        | Route params; surfaced as `ctx.params` and `ctx.routeParams`.                                                                                                                                                              |
+| `search`        | `Record<string, string>`                                        | Search params; merged into the request URL so `ctx.searchParams` reflects them.                                                                                                                                            |
+| `searchData`    | `Record<string, unknown>`                                       | The TYPED `ctx.search` object a route's search schema would produce. Distinct from `search` (which sets the raw `ctx.searchParams`).                                                                                       |
+| `basename`      | `string`                                                        | Router basename surfaced on the context; drives `redirect()` prefixing.                                                                                                                                                    |
+| `theme`         | `ThemeConfig \| true`                                           | Theme config in the `createRouter({ theme })` shape (e.g. `true` or `{ themes: [...] }`). Without it `ctx.theme`/`ctx.setTheme` are inert.                                                                                 |
+| `env`           | `TEnv`                                                          | Environment bindings surfaced as `ctx.env`.                                                                                                                                                                                |
+| `request`       | `Request \| string`                                             | Override the backing Request. Defaults to a localhost GET.                                                                                                                                                                 |
+| `vars`          | `VarsInit`                                                      | Variables a prior middleware would have set (object `{ key: value }`, or `[key, value]` tuples where the key may be a `createVar()` handle).                                                                               |
+| `routeMap`      | `Record<string, string>`                                        | Route name -> pattern map enabling `ctx.reverse()`.                                                                                                                                                                        |
+| `routeName`     | `string`                                                        | Matched route name for scoped `.name` reverse resolution.                                                                                                                                                                  |
+| `method`        | `string`                                                        | HTTP method surfaced as `ctx.method`. Defaults to `"GET"`.                                                                                                                                                                 |
+| `body`          | `unknown`                                                       | Request body surfaced as `ctx.body`.                                                                                                                                                                                       |
+| `formData`      | `FormData`                                                      | Form data surfaced as `ctx.formData` (exposed verbatim; no multipart parsing).                                                                                                                                             |
+| `loaders`       | `ReadonlyArray<readonly [LoaderDefinition<any, any>, unknown]>` | Seed `ctx.use(OtherLoader)` by REFERENCE as `[[OtherLoader, data]]` tuples (same shape as `renderHandler`/`renderRoute`). Checked before `use`.                                                                            |
+| `use`           | `UseResolver`                                                   | Dynamic resolver for `ctx.use(OtherLoader)` composition. `loaders` wins when both match.                                                                                                                                   |
+| `cacheStore`    | `SegmentCacheStore`                                             | Cache store backing `use cache` functions. Without one, a cached function bypasses and runs uncached (its taint/profile guards never fire).                                                                                |
+| `cacheProfiles` | `Record<string, CacheProfile>`                                  | Cache profiles, the `createRouter({ cacheProfiles })` shape.                                                                                                                                                               |
+| `stateCookie`   | `StateCookieSeed` (`{ prefix?, routerId?, version? }`)          | Customize the rango state cookie a loader calling `invalidateClientCache()` rotates (the name is always seeded — default `rango-state_router_0`).                                                                          |
+| `rendered`      | `boolean \| (() => void \| Promise<void>)`                      | Mock the `ctx.rendered()` render barrier so a loader that `await ctx.rendered()`s can be unit-tested. By default `ctx.rendered()` throws. `true` resolves immediately; a function controls timing/side effects.            |
+| `handles`       | `ReadonlyArray<readonly [Handle<any, any>, unknown]>`           | Seed the values `ctx.get(SomeHandle)` returns — the ACCUMULATED handle data read after `await ctx.rendered()`. Matched by handle reference. (Loader handle WRITES need no seed — see `runLoaderResult(...).handlePushes`.) |
+
+### Context — `TestLoaderContext<TEnv>` (what your loader receives)
+
+| Field              | Type                                                                                      | Meaning                                                                                                                                                                                                                                             |
+| ------------------ | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `params`           | `Record<string, string>`                                                                  | Route params (from `opts.params`).                                                                                                                                                                                                                  |
+| `routeParams`      | `Record<string, string>`                                                                  | Same values as `params`.                                                                                                                                                                                                                            |
+| `request`          | `Request`                                                                                 | The backing request.                                                                                                                                                                                                                                |
+| `searchParams`     | `URLSearchParams`                                                                         | Raw search params (from `opts.search` baked into the URL).                                                                                                                                                                                          |
+| `search`           | `Record<string, unknown>`                                                                 | The TYPED search object (from `opts.searchData`); defaults to `{}`.                                                                                                                                                                                 |
+| `pathname`         | `string`                                                                                  | Request pathname.                                                                                                                                                                                                                                   |
+| `url`              | `URL`                                                                                     | Request URL.                                                                                                                                                                                                                                        |
+| `originalUrl`      | `URL`                                                                                     | Pre-basename-rewrite URL.                                                                                                                                                                                                                           |
+| `env`              | `TEnv`                                                                                    | Environment bindings (from `opts.env`).                                                                                                                                                                                                             |
+| `get`              | `<T>(contextVar: ContextVar<T>) => T \| undefined` / `<T>(key: string) => T \| undefined` | Read a var seeded via `opts.vars` — or READ a handle: `ctx.get(handle)` is rendered-gated (throws before the barrier) and returns the `opts.handles` seed.                                                                                          |
+| `use`              | `(dep) => ...`                                                                            | Resolve `ctx.use(OtherLoader)` (loader seeds, then the `use` resolver, then the real context `use()`) — or WRITE a handle: `ctx.use(SomeHandle)` returns the push function (withDefer-wrapped), recording into `runLoaderResult(...).handlePushes`. |
+| `method`           | `string`                                                                                  | HTTP method (from `opts.method`, default `"GET"`).                                                                                                                                                                                                  |
+| `body`             | `unknown`                                                                                 | Request body (from `opts.body`).                                                                                                                                                                                                                    |
+| `formData`         | `FormData \| undefined`                                                                   | Form data (from `opts.formData`).                                                                                                                                                                                                                   |
+| `reverse`          | `(name, params?, search?) => string`                                                      | Build a URL; throws unless `opts.routeMap` was passed.                                                                                                                                                                                              |
+| `rendered`         | `() => Promise<void>`                                                                     | The render barrier; throws by default, mocked via `opts.rendered`.                                                                                                                                                                                  |
+| `waitUntil`        | `(p: Promise<unknown>) => void`                                                           | Register background work (no-op accounting in tests).                                                                                                                                                                                               |
+| `executionContext` | `ExecutionContext \| undefined`                                                           | Platform execution context from the backing request; pairs with `waitUntil`.                                                                                                                                                                        |
+
+### Returns — `Promise<T>`
+
+The loader data DIRECTLY (no envelope). `T` is the loader's return type.
+
+To assert a loader's EFFECTS — a `Set-Cookie`, a response header, a
+`throw redirect(...)` or `notFound()` (loader authority signals), or handle
+writes — use the sibling **`runLoaderResult(loader, opts)`** instead. Same
+options, but it returns an envelope:
+`{ result, thrown, response, cookies, headers, locationState, stateCookieName, handlePushes }`
+(parity with `runInRequestContext`; `result` is the loader's data;
+`handlePushes` records every `ctx.use(SomeHandle)({...})` write in push
+order). `runLoader` discards those effects.
+
+## Recipe
+
+```ts
+import { runLoader, runLoaderResult } from "@rangojs/router/testing";
+import { createLoader, createVar } from "@rangojs/router";
+
+const User = createVar<{ name: string }>();
+// The registered loader — no separate body export needed for testability:
+const ProductLoader = createLoader(async (ctx) => ({
+  id: ctx.params.id,
+  region: ctx.env.REGION,
+  user: ctx.get(User),
+}));
+
+it("reads params, env, and seeded vars", async () => {
+  const data = await runLoader(ProductLoader, {
+    params: { id: "42" },
+    env: { REGION: "eu" },
+    vars: [[User, { name: "Ada" }]],
+  });
+  expect(data).toEqual({ id: "42", region: "eu", user: { name: "Ada" } });
+});
+
+it("builds a self link via reverse", async () => {
+  // runLoader(async (ctx) => ({ ... }), opts) — the bare body — works identically.
+  const data = await runLoader(
+    async (ctx) => ({ self: ctx.reverse("product", { id: ctx.params.id }) }),
+    { params: { id: "42" }, routeMap: { product: "/products/:id" } },
+  );
+  expect(data.self).toBe("/products/42");
+});
+
+it("asserts a loader's set-cookie + redirect (runLoaderResult)", async () => {
+  // AuthLoader validates, sets a `session` cookie, then `throw redirect("/")`.
+  const { thrown, response, cookies } = await runLoaderResult(AuthLoader, {
+    request: new Request("https://app.test/login?token=ok"),
+  });
+  expect((thrown as Response).headers.get("Location")).toBe("/");
+  expect(cookies.session).toBeDefined();
+  expect(
+    response.headers.getSetCookie().some((c) => c.startsWith("session=")),
+  ).toBe(true);
+});
+```
+
+## Caveats
+
+- `ctx.reverse(...)` throws unless you pass `routeMap` (and `routeName` for scoped `.name` resolution). It does NOT fall back to the global route map.
+- `ctx.rendered()` throws by default (the render barrier only exists in a full match); pass `{ rendered: true }` to mock it for post-barrier logic, and `{ handles: [[SomeHandle, data]] }` to seed the `ctx.get(SomeHandle)` read. `ctx.isAction(...)` is unavailable — cover those at e2e.
+- Seeded `loaders` (by-reference tuples) are NOT executed — `ctx.use(OtherLoader)` returns the seeded value. The dynamic `use` resolver, by contrast, IS executed (it is a function called to compute the value). Either way the REAL loader body is not run; real loader execution and side-effects are e2e-only. `loaders` is checked before the `use` resolver.
+- A handle imported through the CLIENT build has its body dropped — `runLoader` throws a clear error pointing to the `rangoTestConfig()` preset or the raw body. A router using `Prerender()`/`createLoader()`/`Static()` now constructs in a bare test (each assigns a runtime fallback `$$id`); only the whole router _file_ may still need the plugin (its page modules pull app deps / `virtual:` modules).
+- No `cookies`/`headers` option: seed a cookie by passing a full Request with a Cookie header — `{ request: new Request(url, { headers: { Cookie: "sid=abc" } }) }`. (`search`/`method` are baked onto this request for you.)
+- `ctx.search` (typed) defaults to `{}`; `opts.search` only sets the raw `ctx.searchParams`. Seed the typed object with `searchData`. (The harness seeds `searchData` verbatim — it does NOT run a typed-search SCHEMA, so schema parsing/validation is e2e.)
+- `ctx.theme`/`ctx.setTheme` are NOT on the loader context — theme accessors are handler-only. (The `theme` option seeds the underlying request context for `use cache` theme resolution, but a loader body cannot read theme.) `redirect()` does no basename prefixing unless you seed `basename`.
+- Platform bindings are yours to double via `env` (see `./bindings.md`).
+
+## See also
+
+- `/loader` — the DSL this tests
+- Siblings: `./handles.md`, `./reverse-and-types.md`, `./bindings.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 "Loaders — the raw body or a registered createLoader"

package/skills/testing/middleware.md

@@ -0,0 +1,99 @@
+# Testing middleware — runMiddleware
+
+**Layer:** unit (node) · **Import:** `@rangojs/router/testing` · **DSL it tests:** `middleware()` (see `/middleware`)
+
+`runMiddleware` executes your chain through the router's REAL `executeLoaderMiddleware`, so `next()`, return-Response and throw-Response short-circuits, double-next guards, and header/cookie merge are production-identical. You SEED the request and any prior-middleware state (`vars`, `params`, `env`, `routeMap`); everything else (cookie/header merge, request-context resolution) is real machinery.
+
+## API
+
+### Options — `RunMiddlewareOptions<TEnv>`
+
+| Field           | Type                                                   | Meaning                                                                                                                                                                                                                                                                               |
+| --------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `request`       | `Request \| string`                                    | The request the chain runs under: a `Request`, or a URL string (absolute or path). Optional — defaults to `http://localhost/`; pass it for path-, header-, or cookie-driven middleware.                                                                                               |
+| `env`           | `TEnv`                                                 | Environment bindings surfaced as `ctx.env`. Your seam for doubling platform bindings (see `./bindings.md`).                                                                                                                                                                           |
+| `params`        | `Record<string, string>`                               | Route params surfaced as `ctx.params`.                                                                                                                                                                                                                                                |
+| `vars`          | `VarsInit`                                             | Variables a prior middleware would have set (object form, or `[key, value]` tuples where `key` may be a `createVar()` handle).                                                                                                                                                        |
+| `routeMap`      | `Record<string, string>`                               | Route name -> pattern map enabling `ctx.reverse()`.                                                                                                                                                                                                                                   |
+| `routeName`     | `string`                                               | Matched route name surfaced as `ctx.routeName`. Does NOT enable scoped `.name` reverse: the chain's `reverse` is deliberately map-only, matching production app/response middleware.                                                                                                  |
+| `basename`      | `string`                                               | Router basename surfaced on the context (drives `redirect()` prefixing).                                                                                                                                                                                                              |
+| `theme`         | `ThemeConfig \| true`                                  | Theme config in the `createRouter({ theme })` shape; enables `ctx.theme`.                                                                                                                                                                                                             |
+| `next`          | `() => Promise<Response>`                              | Terminal handler invoked when the chain calls `next()` all the way through. Defaults to a 200 empty Response. Use it to model the downstream route/handler response.                                                                                                                  |
+| `cacheStore`    | `SegmentCacheStore`                                    | Cache store backing any `use cache` function a middleware invokes. Without it, `registerCachedFunction` bypasses, so the cached fn runs uncached and its taint/profile guards never fire.                                                                                             |
+| `cacheProfiles` | `Record<string, CacheProfile>`                         | Cache profiles in the `createRouter({ cacheProfiles })` shape.                                                                                                                                                                                                                        |
+| `stateCookie`   | `StateCookieSeed` (`{ prefix?, routerId?, version? }`) | Customize the rango state cookie a middleware calling `invalidateClientCache()` rotates (the name is always seeded — default `rango-state_router_0`). Assert via the `Set-Cookie` on `result.response` / `result.cookies`, or against `result.stateCookieName` (without recomputing). |
+
+### Context — `MiddlewareContext` (what your code receives)
+
+The `ctx` your middleware reads. Notable fields:
+
+| Field                       | Type                    | Meaning                                                                            |
+| --------------------------- | ----------------------- | ---------------------------------------------------------------------------------- |
+| `params`                    | `TParams`               | URL params from `opts.params`.                                                     |
+| `env`                       | `TEnv`                  | Bindings from `opts.env`.                                                          |
+| `get` / `set`               | fns                     | Read/write context vars (shared with handlers); `get` resolves what `vars` seeded. |
+| `header(name, value)`       | fn                      | Queue a response header before `next()`, or set it directly after.                 |
+| `reverse`                   | `ScopedReverseFunction` | URL-from-name. Map-only (no auto-fill); needs `routeMap`.                          |
+| `setLocationState(entries)` | fn                      | Attach flash/location state to the response.                                       |
+| `theme` / `setTheme`        | `Theme` / fn            | Current theme; `undefined` unless `theme` is passed.                               |
+| `routeName`                 | `string`                | Matched route name (from `opts.routeName`).                                        |
+
+### Returns — `RunMiddlewareResult<TEnv>`
+
+| Field             | Type                      | Meaning                                                                                                                                                                                                                                                      |
+| ----------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `response`        | `Response`                | The final Response: the downstream response, or a middleware short-circuit.                                                                                                                                                                                  |
+| `ctx`             | `RequestContext<TEnv>`    | The underlying RequestContext (NOT a per-middleware `MiddlewareContext`). Use `ctx.get(...)` for anything the envelope above doesn't surface.                                                                                                                |
+| `nextCalled`      | `number`                  | Times the terminal handler ran: `0` on short-circuit, `1` on pass-through.                                                                                                                                                                                   |
+| `cookies`         | `Record<string, string>`  | Effective cookie view: request cookies merged with chain sets/deletes (last-write-wins), as `{ name: value }`.                                                                                                                                               |
+| `headers`         | `Record<string, string>`  | Final response headers as `{ name: value }`, lowercased, EXCLUDING `set-cookie` (use `cookies`).                                                                                                                                                             |
+| `locationState`   | `Record<string, unknown>` | Flat `{ key: value }` state set via `setLocationState()` / `redirect({ state })` (empty when none).                                                                                                                                                          |
+| `stateCookieName` | `string`                  | The resolved rango state cookie name seeded for the run (default `rango-state_router_0`). Assert a middleware's `invalidateClientCache()` rotation against it without recomputing — parity with `runInRequestContext` / `runLoaderResult` / `renderHandler`. |
+
+## Recipe
+
+```ts
+import { describe, it, expect } from "vitest";
+import { runMiddleware } from "@rangojs/router/testing";
+import type { Middleware } from "@rangojs/router";
+
+const requireUser: Middleware = async (ctx, next) => {
+  if (!ctx.get("user")) return new Response(null, { status: 401 });
+  return next();
+};
+
+describe("requireUser", () => {
+  it("passes through when the user is present", async () => {
+    const { response, nextCalled } = await runMiddleware(requireUser, {
+      request: "/dashboard",
+      vars: { user: { id: 1 } }, // object form; or [[key, value]] tuples (key may be a createVar())
+    });
+    expect(nextCalled).toBe(1);
+    expect(response.status).toBe(200);
+  });
+
+  it("short-circuits (return OR throw Response) when unauthenticated", async () => {
+    const { response, nextCalled } = await runMiddleware(requireUser, {
+      request: "/dashboard",
+    });
+    expect(nextCalled).toBe(0);
+    expect(response.status).toBe(401);
+  });
+});
+```
+
+Pass an array to run several in order. Cookies set inside middleware via the standalone `cookies().set(...)` (imported from `@rangojs/router`, NOT a `ctx` method) surface on the result's `cookies` and on the merged response `Set-Cookie`.
+
+## Caveats
+
+- No `handles`/`rendered` option by design: the middleware context has no handle APIs in production — no push (`ctx.use(Handle)` is a handler/loader API) and no post-barrier read (`ctx.get(handle)` is loader-only, and middleware runs BEFORE the render barrier anyway). Read handle data in a loader and test it with `runLoader`; assert loader pushes via `runLoaderResult(...).handlePushes` (see `./handles.md`).
+- A COMPONENT route's guard stack cannot be exercised through `dispatch` (it throws on component routes), and `renderToFlightString`/`renderRoute` don't run route middleware. Extract the middleware fn and unit-test it here, or assert the guard stack at e2e.
+- Middleware-phase `ctx.reverse` is map-only (no auto-fill from current params), matching production — enable it with `routeMap`. `routeName` only feeds `ctx.routeName`; it does NOT scope `.name` reverse (the chain reverse stays map-only by design).
+- `ctx.theme` is `undefined` unless `theme` is passed; `redirect()` does no basename prefixing unless `basename` is seeded.
+- Platform bindings are yours to double via `env` (see `./bindings.md`).
+
+## See also
+
+- `/middleware` — the DSL this tests
+- Siblings: `./response-routes.md`, `./server-actions.md`, `./loader.md`, `./bindings.md`
+- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Middleware"