@rangojs/router 0.0.0-experimental.31 → 0.0.0-experimental.3232cd17

package/skills/testing/loader.md

@@ -0,0 +1,128 @@
+# 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.use(SomeHandle)` returns — the ACCUMULATED handle data read after `await ctx.rendered()`. Matched by handle reference.                                                                     |
+
+### 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` (by `createVar()` handle or string key).                                                                           |
+| `use`              | `(dep) => ...`                                                                            | Resolve `ctx.use(OtherLoader)`/`ctx.use(SomeHandle)`: handle seeds first, then loader seeds, then the `use` resolver, then the real context `use()`. |
+| `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, or a
+`throw redirect(...)` (the auth-loader pattern) — use the sibling
+**`runLoaderResult(loader, opts)`** instead. Same options, but it returns an
+envelope: `{ result, thrown, response, cookies, headers, locationState, stateCookieName }`
+(parity with `runInRequestContext`; `result` is the loader's data). `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 `ctx.use(SomeHandle)`. `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: middleware runs BEFORE the render barrier, so it has no post-barrier `ctx.use(Handle)` access in production. Read handle data in a loader/handler and test it with `runLoader` (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"

package/skills/testing/render-handler.md

@@ -0,0 +1,121 @@
+# Testing a route handler — renderHandler
+
+**Layer:** RSC unit (react-server project) · **Import:** `@rangojs/router/testing/flight` · **DSL it tests:** a route handler `(ctx) => rsc` (see `/route`)
+
+A Rango route handler is a pure function `(ctx) => rsc` — the function you pass to `path("/p/:slug", ProductPage)`, NOT a component. `renderHandler` runs it with the REAL `HandlerContext` the router builds at runtime (so `ctx.params`, `ctx.use(Loader)`, `ctx.use(Meta)`, `ctx.reverse`, `ctx.get`, response headers via `ctx.headers`, and the standalone `cookies()` all work), serializes the returned RSC, and deserializes it to an inspectable tree. The render and effects are real; loaders are SEEDED (no real loader runs — same model as `runLoader`).
+
+## API
+
+### Options — `RenderHandlerOptions`
+
+| Field              | Type                                                   | Meaning                                                                                                                                                                                                                                                                                                                                                                              |
+| ------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `params`           | `Record<string, string>`                               | Route params surfaced as `ctx.params`.                                                                                                                                                                                                                                                                                                                                               |
+| `env`              | `TEnv`                                                 | Environment bindings surfaced as `ctx.env`.                                                                                                                                                                                                                                                                                                                                          |
+| `request`          | `Request \| string`                                    | Backing Request (string or `Request`); defaults to a localhost GET.                                                                                                                                                                                                                                                                                                                  |
+| `headers`          | `HeadersInit`                                          | Request headers (e.g. `Cookie`) the handler reads via `cookies()`.                                                                                                                                                                                                                                                                                                                   |
+| `vars`             | `VarsInit` (object or `[[Var, value]]` tuples)         | Variables a prior middleware set, read via `ctx.get(...)`.                                                                                                                                                                                                                                                                                                                           |
+| `routeName`        | `string`                                               | Matched route name (drives `ctx.routeName` and scoped reverse).                                                                                                                                                                                                                                                                                                                      |
+| `routeMap`         | `Record<string, string>`                               | Route name -> pattern map enabling `ctx.reverse()`.                                                                                                                                                                                                                                                                                                                                  |
+| `loaders`          | `ReadonlyArray<readonly [LoaderDefinition, unknown]>`  | Seed the data `ctx.use(SomeLoader)` returns. Matched by loader reference; NO real loader runs.                                                                                                                                                                                                                                                                                       |
+| `clientComponents` | `Record<string, unknown>`                              | `"use client"` components in the handler's RSC, so they serialize as real boundaries when `rangoUseClientTransform()` is not wired. Keyed by name.                                                                                                                                                                                                                                   |
+| `stateCookie`      | `StateCookieSeed` (`{ prefix?, routerId?, version? }`) | Customize the rango state cookie a handler calling `invalidateClientCache()` rotates. The name is ALWAYS seeded (default `rango-state_router_0`) so the rotation `Set-Cookie` fires like production rather than no-opping; override `prefix`/`routerId` to match your `createRouter({ stateCookiePrefix, id })`, or `version` (the value is `{version}:{timestamp}`, default `"0"`). |
+| `cacheStore`       | `SegmentCacheStore`                                    | Segment cache store backing a `"use cache"` function the handler invokes (e.g. `new MemorySegmentCacheStore()`). WITHOUT it, `registerCachedFunction` takes the uncached bypass and the cached path is NOT exercised (the runtime emits a one-time warning under the test runner). Pair with `cacheProfiles`.                                                                        |
+| `cacheProfiles`    | `Record<string, CacheProfile>`                         | Cache profiles in the `createRouter({ cacheProfiles })` shape, required for `"use cache: profileName"` resolution once a `cacheStore` is wired.                                                                                                                                                                                                                                      |
+
+### Context — `HandlerContext` (what your handler receives)
+
+| Field              | Type                                 | Meaning                                                                                        |
+| ------------------ | ------------------------------------ | ---------------------------------------------------------------------------------------------- |
+| `params`           | `Record<string, string>`             | The seeded route params.                                                                       |
+| `env`              | `TEnv`                               | The seeded environment bindings.                                                               |
+| `request`          | `Request`                            | The backing request.                                                                           |
+| `searchParams`     | `URLSearchParams`                    | Parsed query of `request.url`.                                                                 |
+| `pathname`         | `string`                             | Pathname of `request.url`.                                                                     |
+| `url`              | `URL`                                | Parsed `request.url`.                                                                          |
+| `routeName`        | `string \| undefined`                | The matched route name (from `routeName`).                                                     |
+| `use`              | `(loaderOrHandle) => data \| pushFn` | A loader returns its seeded data; a handle returns a push fn that RECORDS to `result.handles`. |
+| `reverse`          | `(name, params?) => string`          | Build a URL from `routeMap`.                                                                   |
+| `get`              | `(Var) => value`                     | Read a seeded `vars` variable.                                                                 |
+| `headers`          | `Headers`                            | Response headers; set via `ctx.headers.set(...)` (merged into `result.response`).              |
+| `setLocationState` | `(entries) => void`                  | Set location state (surfaced on `result.locationState`).                                       |
+| `waitUntil`        | `(promise) => void`                  | Register background work.                                                                      |
+
+### Returns — `RenderHandlerResult`
+
+| Field             | Type                      | Meaning                                                                                                                                                             |
+| ----------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tree`            | `unknown`                 | Deserialized RSC the handler returned; `undefined` when it returned/threw a `Response`. Inspect with `findClientBoundaries`.                                        |
+| `flight`          | `string \| undefined`     | Raw Flight wire string; `undefined` on a `Response`.                                                                                                                |
+| `thrown`          | `unknown`                 | The value the handler THREW (a `redirect()`/`notFound()` Response), captured not re-thrown.                                                                         |
+| `response`        | `Response`                | Merged Response (status + headers + Set-Cookie), folding a thrown/returned redirect with accumulated effects.                                                       |
+| `cookies`         | `Record<string, string>`  | Effective cookie view after the handler ran.                                                                                                                        |
+| `headers`         | `Record<string, string>`  | Response headers (excludes set-cookie; includes a redirect `Location`). The `keepClientCache()` directive shows here as `x-rango-keep-cache: "1"`.                  |
+| `stateCookieName` | `string`                  | The resolved rango state cookie name this run seeded (default `rango-state_router_0`). Assert an `invalidateClientCache()` rotation against it without recomputing. |
+| `locationState`   | `Record<string, unknown>` | Location state the handler set (`ctx.setLocationState`/`redirect({ state })`).                                                                                      |
+| `handles`         | `Map<Handle, unknown[]>`  | What the handler pushed via `ctx.use(Handle)(...)` (e.g. `Meta`, `Breadcrumbs`), keyed by handle.                                                                   |
+
+## Recipe
+
+```tsx
+import {
+  renderHandler,
+  findClientBoundaries,
+} from "@rangojs/router/testing/flight";
+import { ProductPage } from "../src/pages/product"; // the real handler: (ctx) => rsc
+import { ProductLoader } from "../src/loaders/product";
+import { Tenant } from "../src/middleware/tenant";
+import { Meta } from "../src/handles";
+
+it("renders the product page for a tenant", async () => {
+  const { tree, handles } = await renderHandler(ProductPage, {
+    params: { slug: "wine" },
+    loaders: [[ProductLoader, { name: "Wine", price: 9 }]], // seeds ctx.use(ProductLoader)
+    vars: [[Tenant, { name: "Acme" }]], // seeds ctx.get(Tenant)
+    routeMap: { product: "/p/:slug" }, // enables ctx.reverse
+  });
+
+  expect(JSON.stringify(tree)).toContain("Wine");
+  const [counter] = findClientBoundaries(tree, "Counter"); // islands inspectable too
+  expect(handles.get(Meta)).toEqual([{ title: "Wine - Shop" }]); // ctx.use(Meta) pushes
+});
+
+it("captures a guarded redirect", async () => {
+  const { thrown, response } = await renderHandler(ProductPage, {
+    params: { slug: "missing" },
+    loaders: [[ProductLoader, null]],
+  });
+
+  expect(thrown).toBeInstanceOf(Response); // throw redirect() is captured, not re-thrown
+  expect(response.status).toBe(302);
+});
+
+it("asserts the client-cache directives", async () => {
+  // invalidateClientCache() rotates the state cookie -> a Set-Cookie on response.
+  const { response, stateCookieName } = await renderHandler(LogoutPage);
+  expect(
+    response.headers
+      .getSetCookie()
+      .some((c) => c.startsWith(stateCookieName + "=")),
+  ).toBe(true);
+
+  // keepClientCache() sets the suppression directive header (no cookie).
+  const { headers } = await renderHandler(QuietPage);
+  expect(headers["x-rango-keep-cache"]).toBe("1");
+});
+```
+
+## Caveats
+
+- An unseeded `ctx.use(loader)` REJECTS with a setup error — seed every dependency via `{ loaders: [[OtherLoader, data]] }`, matched by reference. Loaders are SEEDED, not executed (same as `runLoader`).
+- Same alias requirement as flight tests: without the `@rangojs/router -> index.rsc.ts` alias (see [`./setup.md`](./setup.md)), a handler reading `getRequestContext()`/`cookies()` hits the throwing out-of-react-server stub. Symptom: `tree: undefined` with the stub error on `thrown`.
+- A `throw redirect()` is captured on `thrown` (with `tree` undefined, since it produced a `Response`) — assert on `thrown`/`response`, no try/catch needed.
+- No hydration and no interaction — for clicks, forms, and navigation use e2e.
+- `renderHandler` runs a handler FUNCTION `(ctx) => rsc`; for a plain ELEMENT `<Page/>` use `renderServerTree` (see [`./server-tree.md`](./server-tree.md)).
+- A handler that calls a `"use cache"` function runs UNCACHED unless you seed `cacheStore` (and `cacheProfiles` for a named profile). With nothing seeded the runtime bypasses to the live body and warns once under the test runner — assert real cache behavior by passing `{ cacheStore: new MemorySegmentCacheStore(), cacheProfiles: { default: { ttl: 60 } } }`.
+
+## See also
+
+- `/route` — the DSL this tests
+- Siblings: [`./server-tree.md`](./server-tree.md), [`./server-actions.md`](./server-actions.md), [`./setup.md`](./setup.md), [`./loader.md`](./loader.md)
+- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "renderHandler — run a real route handler and assert its RSC"

package/skills/testing/response-routes.md

@@ -0,0 +1,95 @@
+# Testing a response route / redirect — dispatch
+
+**Layer:** integration (node) · **Import:** `@rangojs/router/testing` · **DSL it tests:** response routes (json/text/html/xml/md), redirects, 404 (see `/response-routes`, `/mime-routes`)
+
+`dispatch` runs the router's REAL matching (reusing `previewMatch`) and the real global + route-level middleware chain, with no RSC render — so redirects, 404s, response routes, content negotiation, and middleware short-circuits behave exactly as in production. You SEED the request and `env`; everything else (matching, middleware, header/cookie merge) is real machinery.
+
+## API
+
+### Options — `DispatchOptions<TEnv>`
+
+| Field                | Type                | Meaning                                                                            |
+| -------------------- | ------------------- | ---------------------------------------------------------------------------------- |
+| `request` (required) | `Request \| string` | The request to dispatch: a `Request`, or a URL string (absolute or path).          |
+| `env`                | `TEnv`              | Environment bindings forwarded to matching and middleware (surfaced as `ctx.env`). |
+
+### Context — response-handler `ctx` (what your code receives)
+
+The lightweight context a RESPONSE-route handler reads (mirrors the production `handleResponseRoute` shape). Notable fields:
+
+| Field                 | Type                     | Meaning                                                                                                     |
+| --------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------- |
+| `request`             | `Request`                | The dispatched request.                                                                                     |
+| `params`              | `Record<string, string>` | URL params from the matched route.                                                                          |
+| `env`                 | `TEnv`                   | Bindings from `opts.env`.                                                                                   |
+| `searchParams`        | `URLSearchParams`        | Query params with internal `_rsc*` params stripped.                                                         |
+| `url`                 | `URL`                    | Cleaned request URL (internal `_rsc*` params removed).                                                      |
+| `pathname`            | `string`                 | Matched pathname.                                                                                           |
+| `reverse`             | `ReverseFunction`        | URL-from-name. Map-only (NO auto-fill from current params), matching the production response-route handler. |
+| `get`                 | fn                       | Read context vars set by prior middleware.                                                                  |
+| `header(name, value)` | fn                       | Set a response header; surfaces on the returned `Response`.                                                 |
+| `waitUntil`           | fn                       | Register a deferred task (no-op fidelity in tests).                                                         |
+
+### Returns — `dispatch(router, opts) -> Promise<Response>`
+
+```ts
+function dispatch<TEnv = any>(
+  router: Rango<TEnv, any>,
+  opts: DispatchOptions<TEnv>,
+): Promise<Response>;
+```
+
+A real `Response`: response-route body, a 308 redirect (`Location`), a 404, or a middleware short-circuit. A `path.json` handler that returns a bare value is serialized verbatim (no envelope); a returned `Response` passes through unchanged; cookies and `ctx.header(...)` surface on the `Response`. `dispatch` accepts your public router type directly (no cast).
+
+## Recipe
+
+```ts
+import { describe, it, expect } from "vitest";
+import { dispatch } from "@rangojs/router/testing";
+import { createRouter } from "@rangojs/router";
+import { apiPatterns } from "../src/api/urls"; // path.json(...) routes, no Prerender
+
+const router = createRouter().routes(apiPatterns);
+
+describe("api routes via dispatch", () => {
+  it("serializes a JSON response route as the bare handler value", async () => {
+    const res = await dispatch(router, { request: "/health" });
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toBe(
+      "application/json;charset=utf-8",
+    );
+    expect(await res.json()).toEqual({ status: "ok" });
+  });
+
+  it("maps a thrown RouterError to its status + RFC 9457 problem+json", async () => {
+    const res = await dispatch(router, { request: "/products/999" }); // handler throws RouterError 404
+    expect(res.status).toBe(404);
+    expect(res.headers.get("content-type")).toBe(
+      "application/problem+json;charset=utf-8",
+    );
+    expect((await res.json()).code).toBe("NOT_FOUND"); // { title, status, detail, code }
+  });
+
+  it("returns 404 for an unmatched path", async () => {
+    expect((await dispatch(router, { request: "/nope" })).status).toBe(404);
+  });
+});
+```
+
+`dispatch` also covers trailing-slash/redirect targets (`findMatch`) — a redirected path returns a 308 with the `Location` (query preserved). Pass `env` via `{ env }`.
+
+## Caveats
+
+- Hitting a COMPONENT (RSC) route throws a clear directive error: `dispatch` is for response routes + redirects + 404 + content negotiation, plus the global + route-level middleware guard stack on RESPONSE routes — it never renders React. Use Flight primitives or e2e to exercise component rendering.
+- A COMPONENT route's guard stack cannot run here. Assert it at e2e, or extract the middleware fn and unit-test it with `runMiddleware` (see `./middleware.md`).
+- JSON serialization is bare, applied in `response-route-handler.ts`: a `path.json` handler that returns a value is serialized verbatim (`JSON.stringify(value)`, status 200, `application/json`) — no envelope. Returning a `Response` (e.g. `Response.json(x)`) passes through unchanged. A thrown error yields an RFC 9457 problem+json body `{ title, status, detail, code }` (`application/problem+json`) with the error's status (`RouterError.status`, else 500, or the effective `ctx.setStatus()` override); `code` is the `RouterError.code`, else `"INTERNAL"`. The `type` member is omitted this phase. Assert the shape matching what your handler returns.
+- Setup: needs the preset (alias + virtual stubs) or a Vite-RSC env (see `./setup.md`); a bare router import throws on Vite virtuals.
+- A router using `Prerender()`/`createLoader()`/`Static()` now constructs in a bare test (each assigns a runtime fallback `$$id`). Importing the whole router _file_ may still need the plugin (its page modules pull app deps / `virtual:` modules) — build from a focused include (your API routes) for whole-router dispatch.
+- A `_rsc_partial` request to a response route runs global middleware first (an auth gate can still 401/redirect), then returns `X-RSC-Reload` — route-level middleware is skipped, exactly like production.
+- `dispatch` does NOT execute server actions (`?_rsc_action`), but it DOES run the global middleware chain on an action request — middleware can still 401/redirect it, and any 3xx redirect on a partial OR action request becomes a `204` + `X-RSC-Redirect` (fetch-safe interception), the raw `Location` dropped.
+
+## See also
+
+- `/response-routes`, `/mime-routes` — the DSL this tests
+- Siblings: `./middleware.md`, `./setup.md`, `./cache-prerender.md`
+- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "dispatch — request to Response" (the `rangoTestConfig` preset stubs `@vitejs/plugin-rsc/rsc`, so no per-file `vi.mock` is needed)

package/skills/testing/reverse-and-types.md

@@ -0,0 +1,84 @@
+# Testing reverse/href and type-level contracts
+
+**Layer:** unit (node) + typecheck · **Import:** `@rangojs/router/client` (useReverse), `@rangojs/router/testing` (assertGeneratedRoutesMatch) · **DSL it tests:** `reverse`/`href`/`useReverse` (see `/typesafety`, `/links`)
+
+The reverse/href/params/env types are a real contract: a wrong route name, a missing param, or an unknown env binding should be a COMPILE error, not a runtime surprise. The type-test recipes have no runtime API — `tsc --noEmit` IS the assertion. `assertGeneratedRoutesMatch` is the one runtime helper here: it runs the router's real matching to expand lazy includes, then diffs the live `routeMap` against the generated named-routes map you seed.
+
+## API
+
+### Options — `assertGeneratedRoutesMatch(router, generatedMap?)`
+
+| Field          | Type                                 | Meaning                                                                                                                                                    |
+| -------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `router`       | `{ routeMap; findMatch? }`           | Your router (real impl). `routeMap` is the live name→pattern map; `findMatch` (when present) is called to force-expand lazy `include()`d routes.           |
+| `generatedMap` | `Record<string, unknown>` (optional) | The imported `*.named-routes.gen.ts` map (name→pattern, or `{ path }` objects). Omit to diff against the global route map (`getGlobalRouteMap()`) instead. |
+
+### Context — `GeneratedRoutesDiff` (what `diffGeneratedRoutes` returns)
+
+| Field      | Type                           | Meaning                                                                                                                                     |
+| ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `missing`  | `string[]`                     | Names in the generated map but absent at runtime (stale generated entry).                                                                   |
+| `extra`    | `string[]`                     | Names at runtime but absent from the generated map (ungenerated route). Auto-generated internal names (`$path_*`/`$prefix_*`) are excluded. |
+| `mismatch` | `[name, generated, runtime][]` | Names in both whose patterns differ.                                                                                                        |
+| `ok`       | `boolean`                      | True when `missing`, `extra`, and `mismatch` are all empty.                                                                                 |
+
+### Returns — `assertGeneratedRoutesMatch`
+
+`void` on match. On drift, throws an `Error` listing every missing, extra, and mismatched route plus a "regenerate the `*.named-routes.gen.ts` file" hint. (`diffGeneratedRoutes` returns the `GeneratedRoutesDiff` above without throwing.)
+
+## Recipe
+
+```ts
+// 1. Negative assertions inline with @ts-expect-error — the directive ERRORS if
+//    the line below it ever starts compiling (i.e. if the type guard regresses).
+//    Validated by `tsc --noEmit`; a runtime test cannot assert this.
+import { useReverse } from "@rangojs/router/client";
+
+const reverse = useReverse({ post: "/blog/:slug" });
+reverse("post", { slug: "hi" }); // ok
+// @ts-expect-error - missing required :slug param
+reverse("post", {});
+// @ts-expect-error - "comment" is not a route in this map
+reverse("comment", { id: "1" });
+```
+
+```ts
+// 2. Positive assertions with vitest's expectTypeOf — pin an INFERRED type
+//    (loader return, parsed search schema, RouteParams) inside a normal *.test.ts.
+import { expectTypeOf } from "vitest";
+import type { RouteParams } from "@rangojs/router";
+
+// RouteParams takes a route NAME and a route map (defaulting to the global map).
+// Pass an explicit map to keep the type test self-contained.
+expectTypeOf<
+  RouteParams<"blogPost", { blogPost: "/blog/:slug" }>
+>().toEqualTypeOf<{ slug: string }>();
+```
+
+```ts
+// 3. assertGeneratedRoutesMatch — a one-liner whole-app drift test. Real
+//    matching expands lazy include()d routes before the diff.
+import { it } from "vitest";
+import { assertGeneratedRoutesMatch } from "@rangojs/router/testing";
+import { router } from "../src/router";
+import generated from "../src/router.named-routes.gen";
+
+it("generated named-routes map is in sync with the router", () => {
+  assertGeneratedRoutesMatch(router, generated);
+});
+```
+
+For a large type-only suite, collect recipe-1/2 assertions in `*.test-d.ts` files and add a `tsconfig.types.json` that `extends` your base config and `include`s only those files, then run `tsc -p tsconfig.types.json --noEmit` in CI. This is how the repo pins its own augmentation contracts. Recipe 1 is enough for most apps; reach for the dedicated tsconfig only when inline assertions clutter runtime tests.
+
+## Caveats
+
+- Type tests run at TYPECHECK time (`tsc --noEmit`), NOT in the vitest runner. They are their own layer — wire them into CI as a real step (`pnpm run typecheck`). A type test nobody runs is just a comment.
+- `@ts-expect-error` ERRORS if the line below it ever starts compiling, so a regressed guard fails the typecheck. A runtime test cannot assert "this should not type-check".
+- `assertGeneratedRoutesMatch` force-expands lazy `include()`d routes (calls `findMatch` on a concrete path derived from each generated pattern) before diffing — otherwise every included route reads as a false `missing`. This makes the whole-app drift check work in a plain unit test. Routers without `findMatch` (a bare `{ routeMap }`) are left as-is.
+- MULTI-APP route-map isolation. `href()`/`reverse()` typing is GLOBAL — each app's generated file augments the one `Rango.GeneratedRouteMap` interface. A `renderRoute` suite that imports a client component from app B (which calls `href("/b-route")`) won't typecheck if the same tsconfig program also carries app A's augmentation: A's route union rejects B's name. `renderRoute` is app-agnostic at RUNTIME; the collision is purely the global `href` typing. Keep a `renderRoute` suite single-app, or give each app its OWN tsconfig program (see `/typesafety`); a quick sidestep is to probe `useMount`/`useHref` inline instead of importing the cross-app component.
+
+## See also
+
+- `/typesafety`, `/links` — the DSL this tests
+- Siblings: `./client-components.md`, `./loader.md`
+- Long-form prose: [docs/testing.md](https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/testing.md) — section "Type-level tests — make misuse fail to compile"