@rangojs/router 0.18.0 → 0.19.0

package/skills/testing/cache-prerender.md

@@ -121,15 +121,15 @@ expect(decision.segments?.[0].shouldRevalidate).toBe(true);
 
 **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 })` or store `keyGenerator` partitions its record, pass what that function returns for the request as `partition`: the shell is partitioned the same way. Under nested keyed `cache()` boundaries, pass their `key()` results as an array, outermost first. |
-| `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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| 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
 

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

@@ -121,11 +121,12 @@ 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 — 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. `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. `runLoaderResult(...).handlePushes` lists the body's pushes, so a HIT reports none (the replay into the page's handle store is not modeled).
+- 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 = () =>

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

@@ -135,6 +135,8 @@ 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();
 ```
 
@@ -151,6 +153,18 @@ expect(result.key).toBe(
 );
 ```
 
+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

package/skills/testing/server-actions.md

@@ -64,11 +64,16 @@ Low-level building blocks (all from `@rangojs/router/testing`):
 
 ```ts
 import { it, expect } from "vitest";
-import { runInRequestContext } from "@rangojs/router/testing";
-import { loginAction } from "../src/actions/login"; // sets a session cookie + flash, then throw redirect("/app")
+import {
+  runInRequestContext,
+  withLocationStateKey,
+} from "@rangojs/router/testing";
+import { loginAction } from "../src/actions/login"; // sets a session cookie, then throw redirect("/app", { state: [Flash({ text: "Welcome back" })] })
 import { logoutAction, dismissBannerAction } from "../src/actions/session"; // invalidateClientCache() / keepClientCache()
+import { Flash } from "../src/location-states"; // createLocationState<{ text: string }>({ flash: true })
 
 const env = { DB: fakeDb }; // your binding double (see ./bindings.md)
+withLocationStateKey(Flash, "Flash"); // no Vite plugin here: key -> "__rsc_ls_Flash"
 
 it("sets the session cookie + flash and redirects", async () => {
   const { thrown, cookies, locationState } = await runInRequestContext(
@@ -82,7 +87,7 @@ it("sets the session cookie + flash and redirects", async () => {
   );
   expect((thrown as Response).headers.get("Location")).toBe("/app"); // redirected
   expect(cookies.session).toBeDefined(); // cookie set before the throw, no @internal cast
-  expect(locationState).toEqual({ flash: { text: "Welcome back" } });
+  expect(locationState).toEqual({ __rsc_ls_Flash: { text: "Welcome back" } });
 });
 
 it("asserts the client-cache directives an action issued", async () => {
@@ -105,6 +110,7 @@ it("asserts the client-cache directives an action issued", async () => {
 ## Caveats
 
 - The snapshot fires whether `fn` RETURNS or THROWS. A `throw redirect("/app")` on the success path is captured on `thrown` (NOT re-thrown), so no try/catch is needed; assert on `thrown` for a throwing action.
+- Location state needs a key. A `createLocationState()` definition gets it from the Vite plugin, which a unit-test project does not run, and outside production an unkeyed `Flash(value)` throws before `redirect()` runs: `thrown` is that missing-key error, not the redirect. Call `withLocationStateKey(Flash, "Flash")` once per definition; `locationState` then holds `{ __rsc_ls_Flash: value }` (the helper adds the `__rsc_ls_` prefix; `{ [Flash.__rsc_ls_key]: value }` works for any key).
 - There is no cookies / headers option. Seed a request cookie by passing a full `Request` with the `Cookie` header (as in the recipe).
 - An action has no loader context, so `runLoader` is the wrong shape for it even when the action reads cookies or vars; use `runInRequestContext`.
 - Platform bindings are yours to double via `env` (see `./bindings.md`).

package/skills/theme/SKILL.md

@@ -123,6 +123,7 @@ and `getRequestContext().theme` are guarded like `cookies()`:
 | middleware `ctx.set()` of the theme, read by a handler     | Not guarded: the first visitor's theme bakes into the shell or `cache()` entry, like a session object |
 | a route with no `ppr` or `cache()` above it, or middleware | Allowed: rendered per request                                                                         |
 | a loader with its own `cache()` and no `key()`             | The miss fails and stores nothing (#972), like a `cookies()` read there; key the theme                |
+| a handler on a document-cached route (`s-maxage`)          | Not guarded: the stored document shows that visitor's theme to everyone                               |
 
 The theme getters are read-only and non-enumerable: `{ ...ctx }` and
 `Object.assign({}, ctx)` do not carry `theme`, and assigning it throws.
@@ -133,10 +134,13 @@ write there; call it from middleware.
 Read the theme where it is per request instead:
 
 - `useTheme()` in a client component. The `<html>` class is right before
-  paint (the theme script sets it). On a `ppr` HIT the shell carries the
-  no-cookie default (`defaultTheme`), whoever captured it: a visitor with no
-  stored theme sees the default, and one with a stored theme sees it after
-  hydration.
+  paint (the theme script sets it). A render that other visitors may be
+  served starts `useTheme()` at the no-cookie default (`defaultTheme`),
+  whoever rendered it: a `ppr` shell, and a page whose response opted in to
+  the document cache before `next()` (#978, see `/document-cache`). A
+  visitor with no stored theme sees the default, and one with a stored theme
+  sees it after hydration. Any other render, a 404 included, starts at the
+  visitor's own theme.
 - A live loader (no `ssr: false`). Loaders do not get `ctx.theme` or
   `ctx.setTheme`; read the cookie directly. A live loader runs on every
   request, HITs included, and on a `ppr` route needs `loading()` or an inline

package/skills/typesafety/env-and-bindings.md

@@ -339,3 +339,11 @@ the value at click time; `ctx.setLocationState(entry)` attaches state from a
 handler; `redirect(url, { state })` carries it through a redirect; and
 `ProductPreview.read()` / `.write(value)` / `.delete()` access the current
 history entry outside React (client-only, non-reactive).
+`ProductPreview.read(location)` reads the slot from any `{ state }` snapshot,
+such as a `transition({ when })` context's `from` / `to`, and works without
+`window`.
+
+The `state` option on `<Link>`, `router.push()` and `router.replace()` is typed
+`HistoryState`: an array of called entries (`[ProductPreview({ ... })]`) or
+plain structured-clone data. A bare entry (`state: ProductPreview({ ... })`) or
+an uncalled definition (`state: [ProductPreview]`) is a compile error.

package/skills/use-cache/SKILL.md

@@ -229,13 +229,32 @@ export const ProductLoader = createLoader(async (ctx) => getProduct(ctx));
 per-request values (cookies, headers) are not reflected in the cache key. Without
 this guard, one user's data would be served to another.
 
+The raw reads throw the same way: `ctx.request.headers` on any `ctx` passed in
+(handler, loader, middleware; it is one `Request` object, also
+`getRequestContext().request`), and `getRequestContext().cookie()` /
+`.cookies()`. A `ctx` or a `Request` argument keys the entry by its route and
+URL only, never by its headers.
+
 Extract the value before the cached function and pass it as an argument:
 
 ```typescript
 const locale = cookies().get("locale")?.value ?? "en";
 const data = await getCachedData(locale); // locale is now in the cache key
+
+// the same for a header
+const language = ctx.request.headers.get("accept-language") ?? "en";
+const greeting = await getGreeting(language);
 ```
 
+Building the key from a `Request` argument reads only its URL.
+`ctx.request.clone()` is guarded like `ctx.request.headers`. One gap remains:
+`fetch(ctx.request)` and `new Request(ctx.request)` don't throw, and the guard
+can't see through them. The fetch forwards the visitor's `Cookie` and
+`Authorization`, so its response is per visitor, and the copy's headers are
+the visitor's; either one stored in the entry serves one visitor's data to
+the next. Don't make them in a cached body: fetch outside and pass the
+result in, or pass in the values the fetch depends on.
+
 `ctx.get()` of a **non-cacheable variable** (`createVar({ cache: false })`, or
 a value written with `ctx.set(key, value, { cache: false })`) throws the same
 way, whether it goes through `getRequestContext().get()` or a `ctx` passed in
@@ -259,17 +278,20 @@ Ordinary (cacheable) variables stay readable. Calling the cached function from
 a loader does not exempt it: the loader re-runs on every request, but the
 cached body does not.
 
-The non-cacheable variable guard does not reach into LOADER bodies consumed
-inside the cached function (`await ctx.use(loader)`): loaders always run
-fresh, so their variable reads are exempt — but the CONSUMED VALUE is captured
-into the shared cache entry like any other computed data. (`cookies()` and
-`headers()` still throw there: that guard follows the cached body's whole
-async chain, loaders included.) Same rule across `cache()` and the PPR shell:
-handler/cached-scope consumption = baked copy, client-side `useLoader` = live
-(the consumption-lane rule, `/rango` → Invariants). The PPR shell is stricter
-about the loader's own reads: during a capture, `cookies()`, `headers()`, and a
-`{ cache: false }` variable read inside a handler-consumed loader refuse the
-capture.
+A LOADER body consumed inside the cached function (`await ctx.use(loader)`)
+is part of that body: its value is captured into the shared cache entry like
+any other computed data, so a `{ cache: false }` variable read there throws,
+exactly as `cookies()`, `headers()`, `ctx.request.headers` and a theme read do
+(one guard follows the
+cached body's whole async chain, loaders included). The check runs only when
+the loader body starts inside the cached function: a loader something else in
+the request already started (a handler's `ctx.use()`, a route `loader()`)
+returns its memoized value without it, and that value is still stored in the
+entry. Read the value outside and pass it in as an argument. Handler/cached-scope consumption = baked copy,
+client-side `useLoader` = live (the consumption-lane rule, `/rango` →
+Invariants). Under a route `cache()` a loader body's reads stay allowed (the
+route entry never stores a loader's value); during a PPR capture they refuse
+the capture, a handler-consumed loader's included.
 
 ### Side-Effect Guards
 
@@ -532,11 +554,35 @@ on a navigation or action), not a cache bust.
 A route `cache()` entry stores the tags of the `"use cache"` reads inside it,
 so `updateTag()` of one evicts the enclosing entry and any `ppr` shell or
 document built from it. A loader's own `cache()` entry does the same for the
-reads in its body. The exception is a `"use cache"` function called inside
-another `"use cache"` function: its tags do not reach the enclosing entry, so
-invalidating one of them neither evicts the outer entry nor keeps this request
-from joining or storing an outer call that started before the invalidation
-([#980](https://github.com/rangojs/rango/issues/980)).
+reads in its body, and a `"use cache"` function for the `"use cache"`
+functions it calls: the outer entry bakes the inner value, so it carries the
+inner tags, whether the inner call ran, was a hit, or joined another call's execution. That includes calls made
+by the server components a cached component returns, which render when the
+value is stored.
+
+```typescript
+async function getStock(sku: string) {
+  "use cache";
+  cacheTag("stock");
+  return db.stock(sku);
+}
+
+async function getProductCard(sku: string) {
+  "use cache";
+  return { sku, stock: await getStock(sku) };
+}
+
+// getProductCard's entry is tagged "stock": updateTag("stock") evicts both.
+```
+
+A call that started before `updateTag()`/`revalidateTag()` of one of its tags
+returns what it read but does not store it, in any request: written after the
+invalidation, the old value would be served as newer than it. The next call
+runs the function again. The same holds for a stale entry's background
+refresh, a loader's own `cache()`, route `cache()` entries and the document
+cache. Another isolate's invalidation is caught through the store's markers:
+`CFCacheStore` with KV, `VercelCacheStore`. On a KV-less `CFCacheStore` only
+this isolate's invalidations are caught; ttl+swr bounds the rest.
 
 ## Interaction with Other Caching
 
@@ -552,9 +598,8 @@ from joining or storing an outer call that started before the invalidation
 Inside a `ppr` shell, a `"use cache"` value that renders as shell material is
 pinned at capture time for the life of that shell (see `/ppr` → Pitfalls). A
 hole's own read (in a loader without `ssr: false` under `loading()` or an
-inline `<Suspense>`) returns the current entry, not the shell's copy, unless a
-loader the capture ran (an `ssr: false` loader, or one a handler awaits) read
-the same entry.
+inline `<Suspense>`) always returns the store's current entry, never the
+shell's copy, even when a loader the capture ran read the same entry.
 
 ## Dev Mode and tests