@rangojs/router 0.17.0 → 0.19.0

package/skills/testing/cache-prerender.md

@@ -119,17 +119,17 @@ expect(decision.segments?.[0].shouldRevalidate).toBe(true);
 
 ## PPR shell and navigation replay
 
-**DSL:** `ppr: true | PartialPrerenderProps` on a page route (see `/ppr`). **Not** the same header as `X-Rango-Cache` — shell is a second render axis.
-
-| Helper                                    | Import                               | Role                                                                                                                                                                                                                            |
-| ----------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `assertShellStatus(res, "HIT" \| "MISS")` | `@rangojs/router/testing` or `…/e2e` | Assert `x-rango-shell` on a **real document** Response                                                                                                                                                                          |
-| `parseShellStatus(res)`                   | same                                 | `"HIT" \| "MISS" \| null` (null = header absent / unrecognized)                                                                                                                                                                 |
-| `shellCacheKey(url, searchParams?)`       | same                                 | Production shell store key (`host+pathname+sorted search+:shell`) for `store.getShell` / custom stores. Pass your router's `cache.searchParams` config as the second argument when it sets one — the production key applies it. |
-| `SHELL_STATUS_HEADER`                     | same                                 | `"x-rango-shell"` constant                                                                                                                                                                                                      |
-| `assertPprReplayStatus(res, expected)`    | same                                 | Assert fresh/stale replay or a bounded bypass decision                                                                                                                                                                          |
-| `parsePprReplayStatus(res)`               | same                                 | Structured replay/bypass status, or null for an absent/unrecognized header                                                                                                                                                      |
-| `PPR_REPLAY_STATUS_HEADER`                | same                                 | `"x-rango-ppr-replay"` constant                                                                                                                                                                                                 |
+**DSL:** `ppr: true | PartialPrerenderProps` on a page route (see `/ppr`). **Not** the same header as `X-Rango-Cache` — the shell is cached separately from the segments.
+
+| Helper                                          | Import                               | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ----------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `assertShellStatus(res, "HIT" \| "MISS")`       | `@rangojs/router/testing` or `…/e2e` | Assert `x-rango-shell` on a **real document** Response                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `parseShellStatus(res)`                         | same                                 | `"HIT" \| "MISS" \| null` (null = header absent / unrecognized)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `shellCacheKey(url, searchParams?, partition?)` | same                                 | Production shell store key (`host+pathname+sorted search+:shell`, then `\|partition`) for `store.getShell` / custom stores. Pass your router's `cache.searchParams` config as the second argument when it sets one — the production key applies it. For a route whose `cache({ key })` partitions its record, pass that function's result for the request as `partition`: the shell is partitioned the same way, the result namespaced as production stores it (`key:` plus its URI encoding). Under nested keyed `cache()` boundaries, pass their `key()` results as an array, outermost first. For a store `keyGenerator` that partitions it, pass `{ keys, generated }` (`ShellCachePartition`): `generated` lists the `keyGenerator` results one per store, outermost first: leave them out when every one returns the default key, else keep each position and pass `""` for one that returns it. |
+| `SHELL_STATUS_HEADER`                           | same                                 | `"x-rango-shell"` constant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `assertPprReplayStatus(res, expected)`          | same                                 | Assert fresh/stale replay or a bounded bypass decision                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `parsePprReplayStatus(res)`                     | same                                 | Structured replay/bypass status, or null for an absent/unrecognized header                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `PPR_REPLAY_STATUS_HEADER`                      | same                                 | `"x-rango-ppr-replay"` constant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 
 ### What unit can prove vs e2e
 
@@ -137,10 +137,11 @@ expect(decision.segments?.[0].shouldRevalidate).toBe(true);
 | -------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | **Unit** | store family + key identity | `MemorySegmentCacheStore` + `shellCacheKey(url)` + `putShell`/`getShell` / tag eviction — dogfood in `e2e/mini/test/shell-store-family.test.ts` and `src/testing/__tests__/shell-status.test.ts` |
 | **Unit** | header helper contract      | `assertShellStatus` on a Response that already carries the header (characterizes the helper; **never** invent a HIT to claim capture worked)                                                     |
+| **Unit** | real capture → HIT, replay  | `serveShellRequest(router, url, { cacheStore })` (react-server project); only the HTML step is stubbed — [`./serve-shell-request.md`](./serve-shell-request.md)                                  |
 | **E2E**  | live MISS → capture → HIT   | document GET, poll until `x-rango-shell: HIT` (background capture) — `e2e/shell-cache.test.ts`                                                                                                   |
 | **E2E**  | partial replay decision     | soft navigation to a warmed shell and `assertPprReplayStatus(response, { outcome: "HIT", freshness: "fresh" })`                                                                                  |
 
-`dispatch` is RSC-free: it never runs shell serve/capture. `renderHandler` only surfaces `ctx.dynamic()` opt-out, not bake/serve.
+`dispatch` is RSC-free: it never runs shell serve/capture. `renderHandler` only surfaces `ctx.dynamic()` opt-out, not bake/serve. The HIT contract — no handler runs, the handler output is the capture's copy, live loaders re-run — is asserted through `serveShellRequest`: count your handler's runs and a live loader's across a MISS and the HITs after it, and check that only the loader's moves ([`./serve-shell-request.md`](./serve-shell-request.md)). A route partitioned by `cache({ key })` or a store `keyGenerator` has a shell per partition: `serveShellRequest` reports the key the serve path resolved (`result.key`), and `shellCacheKey` takes the partition as its third argument.
 
 ### Recipe (e2e)
 
@@ -185,7 +186,7 @@ it("stores the shell under the production key", async () => {
 ## Caveats
 
 - The `X-Rango-Cache` header is emitted ONLY when the gate is on: `createRouter({ debugCacheSignal: true })` or `process.env.RANGO_TEST_SIGNALS === "1"`. Off by default — zero production surface. With the gate off, `assertCacheStatus` throws a clear "header missing" error.
-- `x-rango-shell` is always set on document GETs the serve path considered for a ppr route (no debug gate). Absent header = axis-1 fall-open or non-ppr.
+- `x-rango-shell` is always set on document GETs the serve path considered for a ppr route (no debug gate). Absent header = a normal render (no shell): the request fell open, or the route has no `ppr`.
 - v1 is COARSE: route-level, keyed by the route NAME (e.g. `product.detail`), NOT the URL pattern (`/products/:id`); not per-individual-segment. The signal is built from `ctx.routeKey`, so a pattern-shaped key never matches. (`parseCacheHeader` exposes the raw `{ routeKey: status }` map if you need it.)
 - Prerender is indistinguishable from a cache hit by design — no static `.html`/`.rsc` files, the worker handles every request and looks up a stored Flight payload; the browser cannot tell. Do not assert "prerendered" from the DOM. Assert via the signal (`assertCacheStatus(res, seg, "prerendered")`) and run prerender assertions in PRODUCTION mode (the build-time artifacts only exist after `pnpm build`).
 - In a Playwright e2e import the cache-status / shell-status helpers from the `/e2e` entry — the `@rangojs/router/testing` barrel is Vitest-only (it pulls a build-only virtual that does not resolve in a plain Playwright runner). Zero-prod-surface alternative for segment cache: the telemetry sink (`createCacheSink`/`filterCacheDecisions`), no header at all. Note: the non-RSC `dispatch()` primitive never emits either header — get the Response from the router's real RSC fetch path.
@@ -194,5 +195,5 @@ it("stores the shell under the production key", async () => {
 ## See also
 
 - `/caching`, `/prerender`, `/use-cache`, `/ppr` — the DSL this tests
-- Siblings: [`./e2e-parity.md`](./e2e-parity.md), [`./response-routes.md`](./response-routes.md)
+- Siblings: [`./e2e-parity.md`](./e2e-parity.md), [`./response-routes.md`](./response-routes.md), [`./serve-shell-request.md`](./serve-shell-request.md)
 - Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "Cache, SWR, and prerender"

package/skills/testing/client-components.md

@@ -15,7 +15,7 @@
 | `outletPending`   | `boolean`                                                              | Seed `useOutlet().pending` through each synthetic segment's production `OutletProvider`. Defaults to `false`; this is context seeding, not a simulated navigation/Suspense/action lifecycle.                                                  |
 | `loaders`         | `ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>`             | Seed by REFERENCE: `[loader, data]` pairs. Robust for real `createLoader()` handles whose `$$id` is empty in a bare test. Prefer over `loaderData`.                                                                                           |
 | `params`          | `Record<string, string>`                                               | Explicit params, merged over (and overriding) params extracted from the `request` URL.                                                                                                                                                        |
-| `locationState`   | `ReadonlyArray<readonly [LocationStateDefinition<any, any>, unknown]>` | Seed `useLocationState(def)` by REFERENCE: `[def, value]` pairs; written to `history.state`.                                                                                                                                                  |
+| `locationState`   | `ReadonlyArray<readonly [LocationStateDefinition<any, any>, unknown]>` | Seed `useLocationState(def)` by REFERENCE: `[def, value]` pairs; keys an unkeyed `def` (like `withLocationStateKey(def)`) and writes to `history.state`. See [Location state](#location-state).                                               |
 | `handles`         | `ReadonlyArray<readonly [Handle<any, any>, unknown[]]>`                | Seed `useHandle(handle)` by REFERENCE: `[handle, pushedValues[]]`. Accumulated GLOBALLY (not segment-scoped).                                                                                                                                 |
 | `handle`          | `HandleDataSeed`                                                       | Advanced: raw wire format `{ [handleId]: { [segmentId]: pushedValues[] } }`. Prefer `handles`. Merged with it.                                                                                                                                |
 | `routeMap`        | `Record<string, string>`                                               | Name -> pattern map (informational; client `useReverse` takes its map as an argument, so this is not consumed).                                                                                                                               |
@@ -41,7 +41,7 @@
 | `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). Held-navigation `isLoading` is modeled (below). |
-| `useLocationState`             | SEEDED `history.state` value.                                                                 |
+| `useLocationState`             | SEEDED `history.state` value, or the `state` a push/replace/`<Link>` wrote (below).           |
 | `useHandle`                    | SEEDED handle output (globally accumulated).                                                  |
 | `Outlet`                       | Renders the next segment in the chain (layout nesting).                                       |
 | `useOutlet`                    | Next-segment `content` plus SEEDED `options.outletPending`.                                   |
@@ -54,13 +54,19 @@ Extends RTL's `RenderResult` (`getByTestId`, `getByText`, `getByRole`, `containe
 ```ts
 type RenderRouteResult = RenderResult & {
   router: {
-    // client-only nav, re-resolves the same routes; `loaders` seeds THIS nav
+    // client-only nav, re-resolves the same routes; `loaders` seeds THIS nav.
+    // A spec's transition({ when }) decides it as kind "push";
+    // `transition: false` commits urgently and calls no predicate.
     navigate(
       url: string,
       options?: {
         loaders?: ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>;
+        transition?: boolean;
       },
     ): Promise<void>;
+    // re-render the current location, as router.refresh() does:
+    // a spec's when gets kind "revalidate" (`to` is `from`)
+    refresh(): Promise<void>;
     pathname(): string;
     params(): Record<string, string>;
     store: NavigationStore; // advanced
@@ -114,6 +120,41 @@ it("resolves params + reverse + Outlet through the layout chain", async () => {
 });
 ```
 
+## Location state
+
+A `createLocationState()` definition gets its key from the rango Vite plugin, which a bare Vitest project does not run. Outside production an unkeyed definition throws on first use (`Def(value)`, `useLocationState(Def)`, `.read()`), with a message that points here. Key it with `withLocationStateKey` from `@rangojs/router/testing`:
+
+- `withLocationStateKey(GridState, "GridState")` sets `__rsc_ls_GridState` (stable across runs).
+- `withLocationStateKey(GridState)` keeps a key that is already set, else assigns a synthetic `__rsc_ls_test_<n>` that stays the same for that definition.
+- The `locationState` seed option keys an unkeyed definition the same way, so a seeded definition needs no call. Key every definition a component reads WITHOUT a seed.
+
+A `useRouter().push/replace(url, { state })` or `<Link state>` navigation writes its history entry through production's path (`resolveNavigationState` -> `buildHistoryState` -> `pushHistoryWithIdx`, then the `__rsc_locationstate` event), so `useLocationState(Def)` re-reads after the click. The dev check for a bare entry or an uncalled definition runs too, and, as in production, a push or `<Link>` without `state` starts an entry with no location state. The URL in `window.location` does not change (renderRoute tracks location on its event controller), and `router.navigate()` from the test leaves `history.state` alone. The click starts an async navigation, so wait for the result with RTL's `waitFor`:
+
+```tsx
+// @vitest-environment happy-dom
+import { afterEach, expect, it } from "vitest";
+import { cleanup, fireEvent, waitFor } from "@testing-library/react";
+import { withLocationStateKey } from "@rangojs/router/testing";
+import { renderRoute } from "@rangojs/router/testing/dom";
+import { LoadMore } from "../src/components/LoadMore"; // router.replace(url, { state: [GridState(...)] })
+import { GridState } from "../src/location-states";
+
+afterEach(cleanup);
+withLocationStateKey(GridState, "GridState");
+
+it("shows the count it pushed", async () => {
+  const { getByTestId } = await renderRoute(
+    [{ path: "/grid", Component: LoadMore }],
+    { request: "/grid" },
+  );
+  fireEvent.click(getByTestId("load-more"));
+  await waitFor(() => expect(getByTestId("count").textContent).toBe("40"));
+  expect(window.history.state).toMatchObject({
+    __rsc_ls_GridState: { count: 40 },
+  });
+});
+```
+
 ## 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.
@@ -154,6 +195,7 @@ it("dims the held price while the next product streams", async () => {
 | `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. |
+| `transition: { when }` returning false, or `navigate(url, { transition: false })`              | Same as without `transition`: urgent, with production's decision (`kind: "push"`; `refresh()` is `"revalidate"`). `transition: false` calls no predicate.      |
 | 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.                                                                                           |
 

package/skills/testing/loader.md

@@ -27,6 +27,7 @@
 | `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.                                                                                                                                                               |
+| `cache`         | `PartialCacheOptions`                                           | Run the loader through the `cache()` a route binds it with (`loader(Loader, () => [cache({...})])` takes the same options), against `cache.store`, else `cacheStore`. See the caveat below.                                |
 | `stateCookie`   | `StateCookieSeed` (`{ prefix?, routerId?, version? }`)          | Customize the rango state cookie a loader calling `invalidateClientCache()` rotates (the name is always seeded — default `rango-state_router_0`).                                                                          |
 | `rendered`      | `boolean \| (() => void \| Promise<void>)`                      | Mock the `ctx.rendered()` render barrier so a loader that `await ctx.rendered()`s can be unit-tested. By default `ctx.rendered()` throws. `true` resolves immediately; a function controls timing/side effects.            |
 | `handles`       | `ReadonlyArray<readonly [Handle<any, any>, unknown]>`           | Seed the values `ctx.get(SomeHandle)` returns — the ACCUMULATED handle data read after `await ctx.rendered()`. Matched by handle reference. (Loader handle WRITES need no seed — see `runLoaderResult(...).handlePushes`.) |
@@ -120,10 +121,27 @@ it("asserts a loader's set-cookie + redirect (runLoaderResult)", async () => {
 - 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 `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).
+- Location state needs a key: a `createLocationState()` definition gets it from the Vite plugin, which a test project does not run. In the node project (`NODE_ENV` is not `production`) an unkeyed `Flash(value)` throws, so a loader's `throw redirect(url, { state: [Flash(value)] })` surfaces on `runLoaderResult`'s `thrown` as that missing-key error, not the redirect; in the react-server project (`NODE_ENV=production`) the value lands on `locationState["undefined"]`. Call `withLocationStateKey(Flash, "Flash")` from `@rangojs/router/testing` once per definition and assert `locationState` as `{ __rsc_ls_Flash: value }` (the helper adds the `__rsc_ls_` prefix).
 - 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`.
+- `ctx.theme`/`ctx.setTheme` are NOT on the loader context — they are handler/middleware-only. The `theme` option seeds the request context's theme config, so a loader body reads the visitor's theme with `getRequestContext().theme` (seed the cookie through `request`). That read is guarded like `cookies()` (#971): allowed in a loader body, but it throws inside a `"use cache"` function. `ctx.request.headers` is guarded the same way. `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)).
+- The `cache` option runs the loader through the production loader-cache read-through, so it needs the react-server project for the same reason. A HIT returns the stored value without running the body and records the tags the body recorded when the entry was written, so `updateTag()` of one (inside `runInRequestContext(fn, { cacheStore })`) drops the entry. There is no in-flight join here: wait for the write before the next call, or that call misses too. A raw body is keyed by its function reference. With no `key()`, a fill whose body read request identity (`cookies()`, `headers()`, `ctx.request.headers`, a `{ cache: false }` variable) fails with the identity error and stores nothing; add a `key()` that includes the value. `runLoaderResult(...).handlePushes` lists the body's pushes, so a HIT reports none (the replay into the page's handle store is not modeled).
+
+  ```ts
+  const load = () =>
+    runLoader(productLoader, {
+      params: { id: "1" },
+      cacheStore,
+      cache: { ttl: 300 },
+    });
+  await load(); // MISS: the body runs and calls cacheTag("product:1")
+  await vi.waitFor(() => expect(setItem).toHaveBeenCalledTimes(1));
+  await load(); // HIT: the body does not run
+  await runInRequestContext(() => updateTag("product:1"), { cacheStore });
+  await load(); // MISS again
+  ```
+
 - Platform bindings are yours to double via `env` (see `./bindings.md`).
 
 ## See also

package/skills/testing/middleware.md

@@ -95,6 +95,7 @@ Pass an array to run several in order. Cookies set inside middleware via the sta
 - 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 (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.
+- Location state needs a key: a `createLocationState()` definition gets it from the Vite plugin, which a test project does not run, and outside production an unkeyed `Flash(value)` throws inside the middleware (before `redirect()` or `ctx.setLocationState()` runs). Call `withLocationStateKey(Flash, "Flash")` from `@rangojs/router/testing` once per definition and assert `locationState` as `{ __rsc_ls_Flash: value }` (the helper adds the `__rsc_ls_` prefix).
 - Platform bindings are yours to double via `env` (see `./bindings.md`).
 
 ## See also

package/skills/testing/predicates.md

@@ -2,66 +2,66 @@
 
 **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.                                           |
+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 navigation hold?" and "would this `clientUrls()` loader re-run?". Both predicates run in the browser at runtime.
+
+## runTransitionWhen(when | config, opts?)
+
+Builds the `TransitionWhenContext` the browser builds and evaluates the predicate through the router's own browser code (`browser/transition-when.ts`): a throw counts as `false` and is logged with `console.error`, exactly as at navigation time. Accepts the predicate or a whole `transition()` config (a config without `when` always applies).
+
+### Options — `RunTransitionWhenOptions`
+
+Every field is optional. A location (`from` / `to`) is a URL string, a `URL`, or a partial `RouteLocation`: `{ url?, params?, routeName?, state? }`. A `state` given as location-state entries (`[Def(value)]`, what `Link` and `router.push` take) is stored the way a push stores it, so `Def.read(ctx.to)` reads it back; any other value is used as the raw `history.state`.
+
+| Field    | Type                                                              | Meaning                                                                                                                                                                       |
+| -------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `kind`   | `"push" \| "replace" \| "pop" \| "action" \| "revalidate"`        | Defaults to `"action"` when `action` is given, `"push"` otherwise.                                                                                                            |
+| `from`   | location                                                          | The committed location being left. Defaults to `http://localhost/`.                                                                                                           |
+| `to`     | location                                                          | The destination. Defaults to `from`; always `from` for `"action"` and `"revalidate"`.                                                                                         |
+| `action` | imported action \| `string` \| `{ ref, formData, result, error }` | The triggering action (`isAction()` matches it; `action.id` is its id). Like `runClientRevalidate`, an imported action outside a built app needs its id passed as the string. |
+
+### Returns — `RunTransitionWhenResult`
+
+| Field      | Type                    | Meaning                                                                                                               |
+| ---------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `applied`  | `boolean`               | True when the navigation holds: the predicate returned anything but `false` and did not throw, or there is no `when`. |
+| `gatedOff` | `boolean`               | `!applied`: the navigation commits urgently with no view transition.                                                  |
+| `context`  | `TransitionWhenContext` | The context the predicate received.                                                                                   |
 
 ### Recipe
 
 ```ts
 import { it, expect } from "vitest";
-import { runTransitionWhen } from "@rangojs/router/testing";
-import type { TransitionConfig } from "@rangojs/router";
+import {
+  runTransitionWhen,
+  withLocationStateKey,
+} from "@rangojs/router/testing";
+import { slideWhen } from "../src/transitions.js"; // a "use client" module
+import { Slide } from "../src/location-states.js";
 
-const slide: TransitionConfig = {
-  when: (c) => c.fromRouteName === "products",
-};
+withLocationStateKey(Slide, "Slide");
 
-it("animates only when coming from the product list", () => {
+it("animates unless the Link pushed { animate: false }", () => {
   expect(
-    runTransitionWhen(slide, {
-      request: "/products/1",
-      fromRouteName: "products",
-    }).kept,
+    runTransitionWhen(slideWhen, {
+      from: { url: "/photos/1", params: { id: "1" }, routeName: "photo" },
+      to: { url: "/photos/2", params: { id: "2" }, routeName: "photo" },
+    }).applied,
   ).toBe(true);
-  expect(runTransitionWhen(slide, { request: "/products/1" }).dropped).toBe(
-    true,
-  );
+
+  const { gatedOff, context } = runTransitionWhen(slideWhen, {
+    from: "/photos/1",
+    to: { url: "/photos/2", state: [Slide({ animate: false })] },
+  });
+  expect(Slide.read(context.to)).toEqual({ animate: false });
+  expect(gatedOff).toBe(true);
 });
 ```
 
+### Known limits (Vitest)
+
+- A Vitest project runs neither the Vite plugin's hoist nor its validation. An inline `when` in a `urls()` file stays a plain function there, and a `"use client"` import is the plain function outside the RSC graph, so a server function is not told apart and is accepted. The loud error for an invalid `when` belongs to dev startup, the build and HMR.
+- `renderRoute` decides each commit with production's decision code: `router.navigate()` (and `useRouter().push/replace`, `<Link>`) as `kind: "push"` / `"replace"`, `router.refresh()` as `kind: "revalidate"`, and `navigate(url, { transition: false })` without calling the predicate. Pop, action and `clientUrls()` optimistic-swap decisions are e2e territory.
+
 ## 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).
@@ -111,7 +111,7 @@ it("revalidates only when the tab changes", () => {
 ## 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`).
+- `runTransitionWhen` proves the 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

package/skills/testing/render-handler.md

@@ -159,6 +159,7 @@ Without the plugin, wrap a function yourself with the call the transform emits,
 - 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. `renderHandler` detects this and REJECTS with a setup error naming `rangoTestAliases` (it is not captured 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.
+- Location state needs a key: a `createLocationState()` definition gets it from the Vite plugin, which a test project does not run. This react-server project runs with `NODE_ENV=production`, so an unkeyed `ctx.setLocationState(Flash(value))` does not throw; the value lands on `locationState["undefined"]`. Call `withLocationStateKey(Flash, "Flash")` from `@rangojs/router/testing` once per definition and assert `{ __rsc_ls_Flash: value }` (the helper adds the `__rsc_ls_` prefix; `{ [Flash.__rsc_ls_key]: value }` works for any key).
 - 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. With a store seeded, the body runs once across renders and a render after the background write reads the store — see [A `"use cache"` hit](#a-use-cache-hit), including `rangoUseCacheTransform()`, without which Vitest leaves the directive unwrapped.

package/skills/testing/serve-shell-request.md

@@ -0,0 +1,202 @@
+# Testing a PPR shell — serveShellRequest
+
+**Layer:** RSC unit (react-server project) · **Import:** `@rangojs/router/testing/flight` · **DSL it tests:** the `ppr` path option (see `/ppr`)
+
+`serveShellRequest(router, url, options?)` serves one GET through your router's production request handler — built as `router.fetch` builds it, with the router's `nonce`, `version`, `cache` config and middleware — and settles every background task the request scheduled before it resolves. So the first request for a `ppr` route is a MISS whose real capture has stored its shell (`putShell` landed), and the next request with the same store is a real HIT: shell read, version gates, the tail replaying the handler output the capture baked (no handler runs), live loaders. A `partial` request is a real client navigation with its `x-rango-ppr-replay` decision. Flight is real.
+
+The one stub is the HTML step (the SSR module), because `react-dom/server` does not load under the react-server condition:
+
+| SSR step           | Under `serveShellRequest`                                                                              |
+| ------------------ | ------------------------------------------------------------------------------------------------------ |
+| `renderHTML`       | passes the Flight stream through: a document body is its Flight payload                                |
+| `captureShellHTML` | stores, as the prelude, the Flight text the capture rendered before it went quiet; `postponed` is null |
+| `resumeShellHTML`  | passes the tail's Flight through: a HIT body is the stored prelude, then the tail's Flight payload     |
+
+So `prelude` is the shell as captured (Flight text, not HTML): a value the shell froze appears there, and a hole (a live loader under `loading()`) does not.
+
+## API
+
+### Options — `ServeShellRequestOptions`
+
+| Field        | Type                                             | Meaning                                                                                                                                                                                                    |
+| ------------ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cacheStore` | `SegmentCacheStore`                              | The store for this request, in place of the store your `createRouter({ cache })` config returns. The rest of that config (`enabled`, `searchParams`) still applies. Omit it to use the router's own store. |
+| `env`        | `TEnv`                                           | Bindings, as `router.fetch(request, { env })` passes them. A function `cache` config receives them.                                                                                                        |
+| `headers`    | `HeadersInit`                                    | Request headers (e.g. `cookie`). A document request defaults `accept` to `text/html`.                                                                                                                      |
+| `partial`    | `true \| { from?: string; segments?: string[] }` | Serve the navigation request the browser sends instead of a document GET: from `from` (default the site root) with `segments` mounted (default none).                                                      |
+
+### Returns — `ServeShellRequestResult`
+
+| Field          | Type                                     | Meaning                                                                                                                                                                             |
+| -------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `shellStatus`  | `"HIT" \| "MISS" \| null`                | `x-rango-shell`; null when the serve path did not consider the request (not a `ppr` route, a nonce'd request, a partial request).                                                   |
+| `replayStatus` | `PprReplayStatus \| null`                | `x-rango-ppr-replay` on a partial request: `{ outcome: "HIT", freshness }` or `{ outcome: "BYPASS", reason }`.                                                                      |
+| `prelude`      | `string \| undefined`                    | The prelude a HIT served (the capture's Flight text). `undefined` unless `shellStatus` is `"HIT"`.                                                                                  |
+| `flight`       | `string \| undefined`                    | The Flight payload this request rendered: a HIT's tail, a document render, or a partial response. `undefined` when no Flight rendered (a redirect, a middleware response).          |
+| `key`          | `string`                                 | The shell key the serve path resolved for a document it read (MISS or HIT), request partition included. Otherwise (no `ppr`, a partial request) the URL's key without a partition.  |
+| `readEntry`    | `() => Promise<ShellCacheEntry \| null>` | Reads the document entry under `key` from the request's store (a passive `getShell`). A read: on a store with a shell memo it warms the memo, so call it after the reads you count. |
+| `response`     | `Response`                               | Status and headers. Its body is already read.                                                                                                                                       |
+| `body`         | `string`                                 | The body text.                                                                                                                                                                      |
+
+### `resetShellTestState(): Promise<void>`
+
+A worker keeps some PPR state across requests, and so does the test process across tests: the capture's stampede guard and backoff (a refused capture backs its URL off for later tests too), the capture's and the serve path's once-per-key warnings, the build-shell manifest memo, and `CFCacheStore`'s isolate memos (shells, tag markers, tag hints), which every `CFCacheStore` shares by namespace and URL — a later test's first request can be a HIT from an earlier test's shell. `resetShellTestState()` clears all of it. Call it in `beforeEach`, never while a request is in flight. `VercelCacheStore`'s memos live on the `cache` handle you pass it: a new handle per test starts empty.
+
+## Recipe
+
+```ts
+// test/product-shell.rsc-test.tsx — in the react-server project (./setup.md)
+import { beforeEach, expect, it } from "vitest";
+import { createRouter, updateTag, urls } from "@rangojs/router";
+import { MemorySegmentCacheStore } from "@rangojs/router/cache";
+import { runInRequestContext } from "@rangojs/router/testing";
+import {
+  resetShellTestState,
+  serveShellRequest,
+} from "@rangojs/router/testing/flight";
+import { ProductPage } from "../src/pages/product"; // renders the product name
+import { StockLoader } from "../src/loaders/stock"; // live stock count
+
+const router = createRouter().routes(
+  urls(({ path, loader, loading }) => [
+    path("/product/:id", ProductPage, { name: "product", ppr: { tags: ["catalog"] } }, () => [
+      loader(StockLoader),
+      loading(<p>Checking stock…</p>),
+    ]),
+  ]),
+);
+
+beforeEach(() => resetShellTestState());
+
+it("serves the captured shell and fills the stock hole live", async () => {
+  const cacheStore = new MemorySegmentCacheStore();
+
+  const miss = await serveShellRequest(router, "/product/1", { cacheStore });
+  expect(miss.shellStatus).toBe("MISS"); // a normal render; the capture stored the shell
+
+  const hit = await serveShellRequest(router, "/product/1", { cacheStore });
+  expect(hit.shellStatus).toBe("HIT");
+  expect(hit.prelude).toContain("Widget"); // frozen at capture
+  expect(hit.prelude).not.toContain("in stock"); // the hole
+  expect(hit.flight).toContain("in stock"); // rendered by this request
+
+  await runInRequestContext(() => updateTag("catalog"), { cacheStore });
+  const recapture = await serveShellRequest(router, "/product/1", { cacheStore });
+  expect(recapture.shellStatus).toBe("MISS");
+});
+
+it("replays the captured segments on a client navigation", async () => {
+  const cacheStore = new MemorySegmentCacheStore();
+  await serveShellRequest(router, "/product/2", { cacheStore });
+
+  const nav = await serveShellRequest(router, "/product/2", {
+    cacheStore,
+    partial: { from: "/" },
+  });
+  expect(nav.replayStatus).toEqual({ outcome: "HIT", freshness: "fresh" });
+});
+```
+
+A store built per request from a function `cache` config gets the request's execution context (`ctx`), so its own `waitUntil` writes (`CFCacheStore({ ctx })`) settle with the call. A store built outside the request with its own `waitUntil` (`VercelCacheStore`'s option) is not settled by the call. For `CFCacheStore`, stub the `caches` global and pass a KV double in `env`; for `VercelCacheStore`, pass a `cache` double. A store's shell memo then behaves as in production (count your double's reads across two HITs).
+
+## A HIT runs no handler
+
+A HIT replays what the capture's handlers produced — their elements, the promises they passed or pushed, their handle values — and runs only middleware and loaders. Count runs to pin it:
+
+```ts
+let pageRuns = 0;
+// the page handler does `pageRuns += 1` and renders `page-run-${pageRuns}`
+
+it("a HIT runs no handler", async () => {
+  const cacheStore = new MemorySegmentCacheStore();
+  await serveShellRequest(router, "/product/3", { cacheStore }); // MISS + capture
+  const baked = pageRuns; // the capture's run
+
+  const hit = await serveShellRequest(router, "/product/3", { cacheStore });
+  expect(hit.shellStatus).toBe("HIT");
+  expect(pageRuns).toBe(baked);
+  expect(hit.flight).toContain(`page-run-${baked}`);
+});
+```
+
+## Request-partitioned shells
+
+A route whose `cache()` record is partitioned by the request (`cache({ key })`, or the store's `keyGenerator`) has a shell per partition. Serve each partition with the request headers or cookies its key reads; the result's `key` is the key the serve path resolved, partition included, and `readEntry()` reads it:
+
+```ts
+// cache({ ttl: 300, key: (ctx) => `tier:${ctx.request.headers.get("x-tier")}` }, () => [
+//   path("/pricing", PricingPage, { ppr: true }),
+// ])
+const tier = (name: string) => ({ cacheStore, headers: { "x-tier": name } });
+
+await serveShellRequest(router, "/pricing", tier("gold")); // MISS + capture
+const silver = await serveShellRequest(router, "/pricing", tier("silver"));
+expect(silver.shellStatus).toBe("MISS"); // its own capture, never gold's shell
+const gold = await serveShellRequest(router, "/pricing", tier("gold"));
+expect(gold.shellStatus).toBe("HIT");
+expect(gold.key).toBe(shellCacheKey("/pricing", undefined, "tier:gold"));
+// "localhost/pricing:shell|key%3Atier%253Agold": the key() result is
+// namespaced as production stores it (issue #975).
+expect(await gold.readEntry()).not.toBeNull();
+```
+
+Under nested keyed `cache()` boundaries the partition is their `key()` results composed, outermost first (see `/caching`, "Keys nest"). Pass them to `shellCacheKey` as an array and it composes them the same way:
+
+```ts
+// cache({ key: tierKey }, () => [
+//   layout(TierLayout, () => [
+//     cache({ key: (ctx) => `v:${variantOf(ctx)}` }, () => [path("/plans", PlansPage, { ppr: true })]),
+//   ]),
+// ])
+expect(result.key).toBe(
+  shellCacheKey("/plans", undefined, ["tier:gold", "v:a"]),
+);
+```
+
+A store `keyGenerator` result that partitions the record partitions the shell too, an enclosing `cache({ store })` on another store included (issue #974). Pass those results as `generated`, with any `key()` results as `keys`:
+
+```ts
+// createRouter({ cache: { store: localeStore } }), where localeStore's
+// keyGenerator returns `${defaultKey}|${locale}`
+expect(result.key).toBe(
+  shellCacheKey("/pricing", undefined, {
+    generated: ["doc:localhost/pricing|de"],
+  }),
+);
+```
+
+A partial request has no HTML step, so its `key` is the URL's key without a partition: read a partitioned route's entry from a document request's result.
+
+## Handles and loader data
+
+The result carries no structured `handles` map (unlike `renderHandler`): a handle value and loader data ride the payload, so you assert them as text in `prelude` and `flight`. A value the handler pushed is in the prelude and in every HIT's tail; a live loader's data is only in the tail. No public helper decodes a payload string into values: `normalizeFlight` and the `flightMatchers` (`toMatchFlight`) work on the text too.
+
+```ts
+// The handler pushed ctx.use(Meta)({ title: "Widget - Shop" })
+expect(hit.prelude).toContain('"title":"Widget - Shop"');
+expect(hit.flight).toContain('"title":"Widget - Shop"');
+```
+
+## Caveats
+
+What the HTML stub cannot reproduce, so keep it in e2e:
+
+- The prelude's `<body` sanity gate. A route whose production capture refuses for a root postpone (a live loader read with no `loading()` or `<Suspense>` above it) stores a shell here.
+- The capture deadline. `ppr.captureTimeout` (default 15s) bounds the whole capture: the match, the handler output, then the shell render. A capture that runs out of it stores nothing and is not retried in place, here as in production, so the call waits one deadline: give such a route a short `captureTimeout` in a test (Vitest's default test timeout is 5s). One difference: when the handler output settled but the shell render does not go quiet in what is left, the stub returns no shell, while production goes on to its abort and can still store the prelude rendered by then.
+- SSR render errors. In production a fizz render error during the capture refuses it (#915). The stub renders no HTML and reports none, so a shell whose client component throws during SSR is stored here. A server component that throws still refuses the capture, as in production.
+- Fizz resume of the holes, bootstrap scripts, nonce injection, and browser resume.
+
+Other caveats:
+
+- A HIT's tail carries replayed segments as Flight fragments inside JSON strings, so their quotes are escaped (`\"`). Match plain text, or unescape before matching JSON-shaped text.
+- Call `resetShellTestState()` in `beforeEach` (see above). Without it, a URL a previous test left backed off, or a shell memoized by another `CFCacheStore`, changes what the next test sees.
+- `readEntry()` reads the document entry under `key`. A partial request that finds no entry captures a navigation-only entry, which is stored apart from it.
+- `updateTag()` needs a request context with the store: call it through `runInRequestContext(fn, { cacheStore })` or your app's own endpoint (`dispatch`). A store refuses a capture that starts in the invalidation's millisecond (the invalidation wins) and backs the key off; `serveShellRequest` starts each request in a later millisecond than the call, so an invalidation made before the call cannot collide with it.
+- GET only. Server actions are not served; test their effects with `runInRequestContext`.
+- Same setup as every Flight test: the react-server condition and `rangoTestAliases()` (see [`./setup.md`](./setup.md)).
+
+## See also
+
+- `/ppr` — the DSL this tests; `/caching` — stores and tags
+- Siblings: [`./cache-prerender.md`](./cache-prerender.md) (the shell-status helpers and the e2e recipe), [`./render-handler.md`](./render-handler.md)
+- Long-form prose: [docs/testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md) — section "serveShellRequest — a real PPR capture and HIT"