@rangojs/router 0.16.0 → 0.17.0

package/skills/testing/client-components.md

@@ -2,7 +2,7 @@
 
 **Layer:** unit (DOM) · **Import:** `@rangojs/router/testing/dom` · **DSL it tests:** a client component reading router context (see `/hooks`)
 
-RTL-style stub (peer of React Router's `createRoutesStub` / Expo's `renderRouter`). It mounts the router's REAL `NavigationProvider` plus a synthetic segment tree built from the `routes` you pass, so client hooks resolve against production context — no server, no Vite build, no Flight round-trip. Loader data, location state, and handle output are SEEDED into client context; nothing is executed.
+`renderRoute(routes, options?)` is an RTL-style stub (peer of React Router's `createRoutesStub` / Expo's `renderRouter`), and it is async — `await` it. It mounts the router's REAL `NavigationProvider` plus a synthetic segment tree built from the `routes` you pass, so client hooks resolve against production context — no server, no Vite build, no Flight round-trip. Loader data, location state, and handle output are SEEDED into client context; nothing is executed.
 
 ## API
 
@@ -25,7 +25,7 @@ RTL-style stub (peer of React Router's `createRoutesStub` / Expo's `renderRouter
 | `nonce`           | `string`                                                               | CSP nonce to seed via `NonceContext`, so a component calling `useNonce()` (e.g. an analytics/GTM head script) sees it — mirroring SSR. Defaults to `undefined` (the browser default).                                                         |
 | `defaultPrefetch` | `PrefetchStrategy`                                                     | Router default for `<Link>` and eligible plain anchors. `data-prefetch="false"`/`"none"` opts out one anchor; ancestor `data-prefetch-scope="false"`/`"none"` hard-disables the subtree; `"true"` permits routed resource suffixes elsewhere. |
 
-`RenderRouteSpec = { path, Component, layout?, loaderIds?, name? }` — one node of the route definition. The array is the layout chain root-to-leaf; the LAST entry is the leaf route (its pattern is matched against `request` to extract params; layout patterns are informational). `loaderIds` attaches seeded loaders to THIS node's segment; `layout` on the leaf wraps it; `name` is informational.
+`RenderRouteSpec = { path, Component, layout?, loaderIds?, name?, transition? }` — one node of the route definition. The array is the layout chain root-to-leaf; the LAST entry is the leaf route (its pattern is matched against `request` to extract params; layout patterns are informational). `loaderIds` attaches seeded loaders to THIS node's segment; `layout` on the leaf wraps it; `name` is informational. `transition` is the `transition()` config this node declares (`{}` for a bare `transition()`), attached to its segment exactly as the DSL does — see [Held navigation](#held-navigation).
 
 ### Context — client hooks it makes resolve (what your code receives)
 
@@ -40,7 +40,7 @@ RTL-style stub (peer of React Router's `createRoutesStub` / Expo's `renderRouter
 | `usePathname`                  | Current committed pathname.                                                                   |
 | `useSearchParams`              | Search params from the `request` URL.                                                         |
 | `useNonce`                     | SEEDED CSP nonce (`options.nonce`), else `undefined` (the browser default).                   |
-| `useLoader` / `useFetchLoader` | SEEDED loader data (read path, not run path).                                                 |
+| `useLoader` / `useFetchLoader` | SEEDED loader data (read path, not run path). Held-navigation `isLoading` is modeled (below). |
 | `useLocationState`             | SEEDED `history.state` value.                                                                 |
 | `useHandle`                    | SEEDED handle output (globally accumulated).                                                  |
 | `Outlet`                       | Renders the next segment in the chain (layout nesting).                                       |
@@ -54,7 +54,13 @@ Extends RTL's `RenderResult` (`getByTestId`, `getByText`, `getByRole`, `containe
 ```ts
 type RenderRouteResult = RenderResult & {
   router: {
-    navigate(url: string): Promise<void>; // client-only nav, re-resolves the same routes
+    // client-only nav, re-resolves the same routes; `loaders` seeds THIS nav
+    navigate(
+      url: string,
+      options?: {
+        loaders?: ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>;
+      },
+    ): Promise<void>;
     pathname(): string;
     params(): Record<string, string>;
     store: NavigationStore; // advanced
@@ -108,17 +114,64 @@ it("resolves params + reverse + Outlet through the layout chain", async () => {
 });
 ```
 
+## Held navigation
+
+A stale indicator driven by `useLoader().isLoading` (see `/hooks` data.md, "A held navigation flags the data it keeps on screen") IS unit-testable. Put `transition` on the spec that declares `transition()` in your `urls()`, and pass the next navigation's loader data to `router.navigate(url, { loaders })` as a PENDING Promise. navigate() then commits through production's `commitInTransition` (browser/partial-update.ts), which calls `loaderStore.announcePendingStreams` inside the `startTransition`. The harness does not fake the flag: React holds the reader on screen and the real `useLoader` pin reports `isLoading: true` until the promise settles.
+
+```tsx
+import { act } from "@testing-library/react";
+import { useLoader } from "@rangojs/router/client";
+import { ProductLoader } from "../loaders/product"; // path("/products/:id", ..., () => [loader(ProductLoader), transition()])
+
+function ProductPrice() {
+  const { data, isLoading } = useLoader(ProductLoader);
+  return (
+    <p data-testid="price" aria-busy={isLoading}>
+      {data.price}
+    </p>
+  );
+}
+
+it("dims the held price while the next product streams", async () => {
+  const { getByTestId, router } = await renderRoute(
+    [{ path: "/products/:id", Component: ProductPrice, transition: {} }],
+    { request: "/products/1", loaders: [[ProductLoader, { price: 10 }]] },
+  );
+
+  let resolve!: (value: { price: number }) => void;
+  const next = new Promise<{ price: number }>((r) => (resolve = r));
+  await router.navigate("/products/2", { loaders: [[ProductLoader, next]] });
+  expect(getByTestId("price").getAttribute("aria-busy")).toBe("true"); // old price, stale
+
+  await act(async () => resolve({ price: 12 })); // settle INSIDE act to flush the commit
+  expect(getByTestId("price").getAttribute("aria-busy")).toBe("false");
+  expect(getByTestId("price").textContent).toBe("12");
+});
+```
+
+| Pending state                                                                                  | Under `renderRoute`                                                                                                                                            |
+| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useLoader().isLoading` on the reader a `transition` navigate() holds, pending seed            | Modeled: `true` on the OLD data until the promise settles, then `false` with the new data in the same commit.                                                  |
+| `transition` navigate(), settled seed (a plain value)                                          | `false`; the data swaps in the commit.                                                                                                                         |
+| navigate() without `transition`, pending seed                                                  | Urgent commit (production's cold-navigation lane): the read suspends to the nearest `<Suspense>` fallback (with none, React keeps the previous tree). No flag. |
+| Production's other hold lanes (same-structure search/filter nav, fully-prefetched, optimistic) | NOT modeled — without `transition` navigate() stays urgent. Assert those at e2e.                                                                               |
+| `useNavigation().state`, `useLinkStatus().pending`, `useAction().state`                        | Stay `idle` — navigate() never starts the navigation lifecycle. e2e.                                                                                           |
+
+- Per-navigation seeds merge over the render-time `loaders`/`loaderData` for THAT navigation only; a later `navigate()` without `loaders` falls back to the render-time data.
+- Pass settled data as a plain value, not `Promise.resolve(value)`: React has not observed a plain promise yet, so it counts as pending and renders one `stale` frame. (A Flight chunk that has already settled carries its status and is skipped, which a plain value mirrors.)
+- `loading()` is not a spec field: a `<Suspense>` in your layout component stands in for it.
+
 ## Caveats
 
 - Client tree ONLY. Does NOT catch server/client boundary reference-identity remount bugs, real Flight serialization errors, loader execution, middleware, or handler ordering — those are `renderServerTree` / `renderHandler` / e2e territory. Loader data is SEEDED, never run.
-- `router.navigate()` bypasses the navigation lifecycle, so the controller never leaves `idle`. `useNavigation()` / `useLinkStatus()` / `useAction()` non-idle states (loading/streaming/pending, action result/error) are NOT reachable — test those at e2e.
+- `router.navigate()` bypasses the navigation lifecycle, so the controller never leaves `idle`. `useNavigation()` / `useLinkStatus()` / `useAction()` non-idle states (loading/streaming/pending, action result/error) are NOT reachable — test those at e2e. The one modeled pending state is held-navigation `useLoader().isLoading` ([Held navigation](#held-navigation)).
 - `outletPending` seeds only the production-shaped outlet context. It is useful
   for the two settled render states of a layout that reads `useOutlet()`, but it
   does not prove the hydrated `clientUrls()` transition that toggles the value;
   keep that transition in dev + production e2e.
 - CATCH — streaming `use(promise)` Suspense content (e.g. an async breadcrumb `content: Promise<ReactNode>`): a plain `Promise.resolve(node)` does NOT flush its Suspense retry in RTL/happy-dom, so the DOM stays on the fallback. Assert the PENDING fallback with `new Promise(() => {})`; for the ARRIVED state pass an already-settled promise so `use()` reads it synchronously: `const p = Promise.resolve(node) as any; p.status = "fulfilled"; p.value = node;`. The real pending->resolved transition is an e2e concern.
 - ARIA gotcha — an explicit `role` on a `<Link>` (e.g. `<Link role="tab">` in a tablist) OVERRIDES the implicit `link` role, so `getByRole("link")` finds nothing. Query the explicit role (`getByRole("tab")`) or fall back to `getByText` / `getByTestId` and assert `getAttribute("href")`.
-- `ctx.theme` is undefined unless `theme` is passed; the typed `ctx.search` defaults to `{}` (seed `searchData` on `runLoader`, not here).
+- `useTheme()` throws unless `theme` is passed (it needs the `ThemeProvider` that option mounts). Search state comes only from the `request` URL — there is no typed-search seed here (that is `runLoader`'s `searchData`).
 - Use `mount` only for an `include()` prefix. An OPTIONAL param in the matched pattern (`/:locale?/c/:group` at `/en/c/wine`) auto-fills `locale` from the match — production parity, `useReverse` merges `useParams()` — so no `mount` is needed; a locale "dropping" from a reversed URL is usually a missing `mount` seed, not an auto-fill gap.
 - Needs a DOM env (`// @vitest-environment happy-dom`, or jsdom) and `@testing-library/react` (optional peers).
 - Don't hand-roll a `NavigationProvider`/router-context mock to test a client component — `renderRoute` mounts the REAL provider, so a hand-mock both duplicates effort and drifts from the production context shape.

package/skills/testing/e2e-parity.md

@@ -16,7 +16,7 @@ This is full-stack: the harness builds and serves your real app (`pnpm dev` or `
 | `expect`      | `Expect`   | Your Playwright `expect` (used by helpers + matchers).                   |
 | `defaultRoot` | `string?`  | Fallback app root for `parityDescribe` when a call omits `options.root`. |
 
-### Fixture options — `FixtureOptions` (`useFixture` / `parityDescribe` 3rd arg)
+### Fixture options — `FixtureOptions` (`useFixture`; `parityDescribe`'s 3rd arg takes the same fields minus `mode`)
 
 | Field            | Type               | Meaning                                                                        |
 | ---------------- | ------------------ | ------------------------------------------------------------------------------ |
@@ -54,7 +54,17 @@ This is full-stack: the harness builds and serves your real app (`pnpm dev` or `
 - `expectParity(page, intent, opts) => Promise<void>` — runs `intent` over the JS page and a fresh no-JS context, asserts observed testids' text + pathname/search/hash + `document.cookie` are equal. `opts` is the required `observe` plus optional `baseURL`, `waitFor`, and `ignoreCookies` (the rango state cookie is excluded automatically).
 - `rangoMatchers` — `{ toHaveRangoPathname }` only (pass to `expect.extend`).
 - `testNoJs` — a `test` variant with JavaScript disabled.
-- Page helpers: `waitForHydration`, `expectNoReload`, `expectNoPageError`, `testId`, `waitForNavigation`, `waitForElement`, `goBack`/`goForward`, `getHistoryState`, `waitForTextChange`/`waitForNumericChange`, timing helpers.
+- Page helpers:
+  - navigation/state: `waitForHydration(page)`, `waitForNavigation(page, url)`, `goBack(page)` / `goForward(page)`, `getHistoryState(page)`;
+  - elements: `testId(page, id)`, `waitForElement`, `isVisibleInViewport`, `parseNumber(text)`, `getNumericContent(locator)`;
+  - assertions bound to your `expect`: `expectNoReload(page)` (use with `await using`), `expectNoPageError(page)` (use with `using`), `waitForTextChange`, `waitForNumericChange`;
+  - timing: `createStopwatch()`, `measureTime(fn)`, `expectTiming`, `expectMinTiming`, `expectMaxTiming`.
+
+The entry also exports standalone functions that are NOT on the factory result:
+
+- Prefetch control: `isPrefetchRequest(req)` (true for requests carrying `X-Rango-Prefetch`), `blockPrefetch(page)` / `unblockPrefetch(page)` (abort speculative prefetches — install before `page.goto` when a test needs the click's own navigation fetch, since a warmed Link adopts its prefetch and issues none).
+- The building blocks `createRangoE2E` composes: `createUseFixture(test)`, `createParity({ test, expect, useFixture, defaultRoot? })`, `createPageHelpers(expect)`, `createRangoMatchers(expect)`.
+- The cache/shell status helpers (`assertCacheStatus`, `assertShellStatus`, ... — see `./cache-prerender.md`), re-exported so a plain Playwright runner can use them.
 
 ## Recipe
 

package/skills/testing/flight.md

@@ -4,21 +4,24 @@
 
 > **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.
+`renderToFlightString(element, opts?)` 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, route map, vars, theme, and cache store 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]]`).                                                                                                                               |
+| 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]]`).                                                                                                                               |
+| `theme`         | `ThemeConfig \| true`          | Theme config (`createRouter({ theme })` shape). Without it `getRequestContext().theme` is `undefined` and `setTheme` is inert.                                                                                                                                               |
+| `cacheStore`    | `SegmentCacheStore`            | Store backing a `"use cache"` function the tree calls. Without it the cached path is bypassed (the function runs uncached).                                                                                                                                                  |
+| `cacheProfiles` | `Record<string, CacheProfile>` | Profiles for `"use cache: name"`, the `createRouter({ cacheProfiles })` shape. Pair with `cacheStore`.                                                                                                                                                                       |
 
 ### Context — `RequestContext` (what your component receives)
 
@@ -42,7 +45,12 @@ expect(await renderToFlightString(<C />)).toMatchFlight("substring"); // contain
 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`).
+`toMatchFlight(substring)` is containment (not equality) on the normalized payload; `toMatchFlightSnapshot()` snapshots the normalized payload. Both matchers live at `@rangojs/router/testing/flight-matchers`, which imports `vitest` but not the Flight serializer — so it also loads under the plain node condition (a shared `setupFiles` can `expect.extend(flightMatchers)` for both projects). The Flight strings they assert still come from `renderToFlightString`, which runs only under the react-server project (see `./setup.md`). Importing the entry also adds the matcher types to vitest's `Assertion`.
+
+### Helpers
+
+- `normalizeFlight(flight)` — the normalization both matchers apply: strips the dev-only leading `:N<timestamp>` row and rewrites absolute `file://` paths to `file://<path>`. Use it when asserting on the raw string yourself.
+- `assertFlightRuntimeAvailable()` — throws a descriptive error when the vendored react-server-dom serializer is missing (for example after a `@vitejs/plugin-rsc` upgrade moved it). Call it in a `beforeAll` to fail fast with a clear message.
 
 ## Recipe
 

package/skills/testing/handles.md

@@ -61,10 +61,10 @@ it("runs a custom 'last wins' collect", () => {
 ```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 { runLoader, type TestLoaderContext } from "@rangojs/router/testing";
 import { RenderedProducts } from "../src/handles"; // a createHandle(...)
 
-const livePricesBody = async (ctx) => {
+const livePricesBody = async (ctx: TestLoaderContext) => {
   await ctx.rendered(); // barrier: handle data is now readable
   const ids = ctx.get(RenderedProducts) as string[];
   return ids.map((id) => ({ id, price: 9.99 }));
@@ -85,10 +85,13 @@ it("reads the accumulated handle value (seed the OUTPUT, mock the barrier)", asy
 ```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";
+import {
+  runLoaderResult,
+  type TestLoaderContext,
+} from "@rangojs/router/testing";
+import { Meta } from "@rangojs/router";
 
-const productBody = async (ctx) => {
+const productBody = async (ctx: TestLoaderContext) => {
   const product = { name: "Widget", slug: "widget" };
   ctx.use(Meta)({ title: `${product.name} — Shop` });
   return product;

package/skills/testing/loader.md

@@ -2,7 +2,7 @@
 
 **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) => ...`.
+`runLoader(loader, opts?)` 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()` definition (its fn is recovered from the registry) or the raw async body `(ctx) => ...`; type a raw body's argument as `TestLoaderContext` (exported from `@rangojs/router/testing`).
 
 ## API
 
@@ -51,7 +51,7 @@
 | `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).                                                                                                                                                                                               |
+| `waitUntil`        | `(fn: () => Promise<void>) => void`                                                       | Register background work; takes a function, not a promise (no-op accounting in tests).                                                                                                                                                              |
 | `executionContext` | `ExecutionContext \| undefined`                                                           | Platform execution context from the backing request; pairs with `waitUntil`.                                                                                                                                                                        |
 
 ### Returns — `Promise<T>`
@@ -70,8 +70,10 @@ order). `runLoader` discards those effects.
 ## Recipe
 
 ```ts
+import { it, expect } from "vitest";
 import { runLoader, runLoaderResult } from "@rangojs/router/testing";
 import { createLoader, createVar } from "@rangojs/router";
+import { AuthLoader } from "../src/loaders/auth"; // sets a `session` cookie, then throw redirect("/")
 
 const User = createVar<{ name: string }>();
 // The registered loader — no separate body export needed for testability:
@@ -100,7 +102,6 @@ it("builds a self link via reverse", async () => {
 });
 
 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"),
   });
@@ -115,12 +116,14 @@ it("asserts a loader's set-cookie + redirect (runLoaderResult)", async () => {
 ## 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.
+- `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.
+- A loader has no `isAction()`: whether it re-runs after an action is decided by `revalidate()` on its registration, not inside the loader body. Assert post-action re-runs 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).
+- A `createLoader()` definition 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`.
+- A `"use cache"` hit needs real Flight, which loads only under the react-server condition. In the react-server project (a `*.rsc-test.ts` file, see [`./setup.md`](./setup.md)) with `cacheStore` seeded, the body runs once across `runLoader` calls and the value round-trips. The write is a background (`waitUntil`) task `runLoader` does not await: a call before it lands joins the still-running execution, a call after it reads the store (wait with `vi.waitFor` on a `cacheStore.setItem` spy). In the node project a call looks up the store but never writes, so every call runs the body. A function written with the directive needs `rangoUseCacheTransform()` in the project's `plugins` (see [`./render-handler.md`](./render-handler.md#a-use-cache-hit)).
 - Platform bindings are yours to double via `env` (see `./bindings.md`).
 
 ## See also

package/skills/testing/middleware.md

@@ -2,14 +2,17 @@
 
 **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.
+`runMiddleware(mw | mw[], opts)` 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>`
 
+`opts` is a required argument (unlike `runLoader`); pass `{}` when you need no seeds.
+
 | Field           | Type                                                   | Meaning                                                                                                                                                                                                                                                                               |
 | --------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `build`         | `boolean`                                              | Seed `ctx.build` (default `false`) to test a middleware that branches on the build-time PPR shell-capture pass (e.g. `if (ctx.build) ctx.dynamic()`). With `true`, `ctx.waitUntil()` is inert, as at build time. Assert the opt-out via `result.dynamic`.                             |
 | `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`.                                                                                                                                                                                                                                                |
@@ -33,10 +36,11 @@ The `ctx` your middleware reads. Notable fields:
 | `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`.                          |
+| `reverse`                   | `GlobalReverseFunction` | Global names only: no auto-fill, `.name` is a type error. 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`).                                        |
+| `build` / `dynamic()`       | `boolean` / fn          | Build-pass flag (from `opts.build`) and the PPR shell opt-out (`result.dynamic`).  |
 
 ### Returns — `RunMiddlewareResult<TEnv>`
 
@@ -45,6 +49,7 @@ The `ctx` your middleware reads. Notable fields:
 | `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.                                                                                                                                                                                   |
+| `dynamic`         | `boolean`                 | Whether the chain called `ctx.dynamic()` (the PPR shell opt-out).                                                                                                                                                                                            |
 | `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).                                                                                                                                                          |
@@ -88,7 +93,7 @@ Pass an array to run several in order. Cookies set inside middleware via the sta
 
 - 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).
+- Middleware-phase `ctx.reverse` is map-only (global names 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, and `MiddlewareContext["reverse"]` rejects `.name` at compile time).
 - `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`).
 

package/skills/testing/predicates.md

@@ -0,0 +1,120 @@
+# Testing navigation predicates — runTransitionWhen, runClientRevalidate
+
+**Layer:** unit (node) · **Import:** `@rangojs/router/testing` · **DSL it tests:** `transition({ when })` (see `/view-transitions`) and `clientUrls()` `revalidate()` (see `/client-urls`)
+
+Both primitives are synchronous and run the router's own evaluation code on arguments you seed, so a predicate sees the same fields it sees at runtime. Neither renders anything: they answer "would this gate keep the transition?" and "would this `clientUrls()` loader re-run?".
+
+## runTransitionWhen(config, opts?)
+
+Runs a `transition()` config through the production gate (`gateTransitions`, plus the PPR pre-handler evaluator when `ppr: true`) and reports whether the transition survives this request.
+
+### Options — `RunTransitionWhenOptions<TEnv>`
+
+Every field is optional. Omitted navigation fields model "source unavailable" (an initial document load); omitted `action*` fields model a plain navigation.
+
+| Field           | Type                     | Meaning                                                                                           |
+| --------------- | ------------------------ | ------------------------------------------------------------------------------------------------- |
+| `request`       | `Request \| string`      | Navigation TARGET (drives `nextUrl`). Defaults to `http://localhost/`.                            |
+| `params`        | `Record<string, string>` | Target params (`nextParams`).                                                                     |
+| `toRouteName`   | `string`                 | Target route name (`toRouteName`).                                                                |
+| `currentUrl`    | `string \| URL`          | Navigation SOURCE (`currentUrl`).                                                                 |
+| `currentParams` | `Record<string, string>` | Source params (`currentParams`).                                                                  |
+| `fromRouteName` | `string`                 | Source route name (`fromRouteName`).                                                              |
+| `actionId`      | `string`                 | Id of the action that triggered the render.                                                       |
+| `actionUrl`     | `string \| URL`          | URL the action was submitted from.                                                                |
+| `actionResult`  | `unknown`                | The action's return value.                                                                        |
+| `formData`      | `FormData`               | Form data from a form action.                                                                     |
+| `env`           | `TEnv`                   | Bindings surfaced as `env`.                                                                       |
+| `vars`          | `VarsInit`               | Values the predicate reads through `get()`. With `ppr`, these model pre-handler middleware state. |
+| `onError`       | `OnErrorCallback`        | Receives an error the predicate throws (the gate reports it with phase `"rendering"`).            |
+| `ppr`           | `boolean`                | Model a `ppr` route, where the predicate runs before route handlers and the cache lookup.         |
+
+### Returns — `RunTransitionWhenResult<TEnv>`
+
+| Field         | Type                                 | Meaning                                                                                         |
+| ------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `kept`        | `boolean`                            | True when the transition applies (the predicate did not return `false`, or there is no `when`). |
+| `dropped`     | `boolean`                            | `!kept`.                                                                                        |
+| `whenContext` | `TransitionWhenContext \| undefined` | The context the predicate received; `undefined` when the config has no `when`.                  |
+| `ctx`         | `RequestContext<TEnv>`               | The underlying request context, for extra assertions.                                           |
+
+### Recipe
+
+```ts
+import { it, expect } from "vitest";
+import { runTransitionWhen } from "@rangojs/router/testing";
+import type { TransitionConfig } from "@rangojs/router";
+
+const slide: TransitionConfig = {
+  when: (c) => c.fromRouteName === "products",
+};
+
+it("animates only when coming from the product list", () => {
+  expect(
+    runTransitionWhen(slide, {
+      request: "/products/1",
+      fromRouteName: "products",
+    }).kept,
+  ).toBe(true);
+  expect(runTransitionWhen(slide, { request: "/products/1" }).dropped).toBe(
+    true,
+  );
+});
+```
+
+## runClientRevalidate(fn | fn[], opts?)
+
+Evaluates one `clientUrls()` loader `revalidate()` predicate, or a chain in declaration order, through the production chain evaluator: the locked default, boolean short-circuit, soft verdicts (`{ defaultShouldRevalidate }`), and a throwing predicate deferring to the default all behave as in the browser. Returns the final `boolean` (the locked default when every predicate defers or throws).
+
+### Options — `RunClientRevalidateOptions`
+
+Defaults model a same-URL navigation with no action.
+
+| Field           | Type                             | Meaning                                                                                                                                                                                         |
+| --------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `currentUrl`    | `string \| URL`                  | Source URL. Defaults to `http://localhost/`.                                                                                                                                                    |
+| `nextUrl`       | `string \| URL`                  | Target URL. Defaults to `currentUrl`.                                                                                                                                                           |
+| `currentParams` | `Record<string, string>`         | Source params. Defaults to `{}`.                                                                                                                                                                |
+| `nextParams`    | `Record<string, string>`         | Target params. Defaults to `currentParams`.                                                                                                                                                     |
+| `stale`         | `boolean`                        | The `stale` arg. Defaults to `false`.                                                                                                                                                           |
+| `action`        | `(...args) => unknown \| string` | The triggering action: one imported server action (its id is read from the build-injected `$id`/`$$id`) or a raw action id string. A namespace object is rejected. Omit for a plain navigation. |
+| `actionRequest` | `boolean`                        | Model the action-triggered refetch GET: `isAction()` stays true but the locked default is the navigation default. Defaults to treating `action` as the action POST itself.                      |
+
+Outside a built app, an imported action carries no id, so pass the id string your predicate matches (for example `"src/actions/cart.ts#addToCart"`); `runClientRevalidate` throws a clear error otherwise.
+
+### Recipe
+
+```ts
+import { it, expect } from "vitest";
+import { runClientRevalidate } from "@rangojs/router/testing";
+import type { ClientRevalidateFn } from "@rangojs/router/client";
+
+const onlyOnTabChange: ClientRevalidateFn = ({ currentUrl, nextUrl }) =>
+  currentUrl.searchParams.get("tab") !== nextUrl.searchParams.get("tab");
+
+it("revalidates only when the tab changes", () => {
+  expect(
+    runClientRevalidate(onlyOnTabChange, {
+      currentUrl: "/settings?tab=profile",
+      nextUrl: "/settings?tab=billing",
+    }),
+  ).toBe(true);
+  expect(
+    runClientRevalidate(onlyOnTabChange, {
+      currentUrl: "/settings?tab=profile",
+      nextUrl: "/settings?tab=profile&sort=asc",
+    }),
+  ).toBe(false);
+});
+```
+
+## Caveats
+
+- Server-tree `revalidate()` predicates have no dedicated primitive: they are plain functions, so call them with a hand-built args object, or assert the post-action result at e2e.
+- `runTransitionWhen` proves the GATE decision only. Whether the browser actually runs a view transition is e2e territory (see `./e2e-parity.md`).
+- Both are synchronous; a predicate returning a Promise is a bug in the predicate, not something to await here.
+
+## See also
+
+- `/view-transitions`, `/client-urls` — the DSL these test
+- Siblings: `./client-components.md`, `./e2e-parity.md`