@rangojs/router 0.20.0 → 0.22.0

package/skills/rango/SKILL.md

@@ -116,6 +116,7 @@ stated, greppable contract.
 | set meta/breadcrumbs from loader data   | `ctx.use(Handle)` in the loader    | /loader                 |
 | guarantee loader output in the SSR HTML | `loader(L, { ssr: false })`        | /loader                 |
 | pre-render a route at build time        | `Prerender(...)` wrapper           | /prerender              |
+| make a route ready before traffic       | `router.prerender({ env })(url)`   | /prerender              |
 | feed live loaders from a cached shell   | replayed handle + `ctx.rendered()` | /shell-manifest         |
 | cache HTML shell, live loaders as holes | `ppr` path option                  | /ppr                    |
 | choose in-function vs CDN caching       | deployment cache boundary          | /deployment-caching     |
@@ -157,8 +158,9 @@ stated, greppable contract.
   `cacheTag(...tags)`, then `updateTag(...tags)` (awaitable) or `revalidateTag(...tags)`
   (background). Built-in stores index by tag.
 - `useLoader` / `useHandle` / `useFetchLoader` are client-only.
-- Caches are correctness-first: persistent store keys are version-segmented (no
-  cross-deploy drift), the forward/back cache is mutation-aware, and
+- Caches are correctness-first: persistent store keys are version-segmented per
+  `createRouter()` by a hash of its built code (a deploy that does not change a
+  router keeps its cache; one that does reads under new keys), the forward/back cache is mutation-aware, and
   `createVar({ cache: false })` throws on a **direct** read inside a `cache()`
   boundary or a `"use cache"` function (a deliberately non-propagating guard). See `/cache-guide` →
   "Correctness & invalidation".
@@ -422,11 +424,11 @@ npx rango generate src/urls.tsx src/api/
 
 Three modes:
 
-| Flag        | Behavior                                                                                                                  |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------- |
-| (none)      | Static parser. Exits with an error, writing nothing, if an `include()` can't be resolved statically (factory or dynamic). |
-| `--static`  | Static parser, but writes partial output and prints the unresolvable includes as warnings.                                |
-| `--runtime` | Vite-based runtime discovery (full coverage; needs `vite` and `@vitejs/plugin-rsc`). `--config <path>` picks the config.  |
+| Flag        | Behavior                                                                                                                                    |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| (none)      | Static parser. Exits with an error, writing nothing, if an `include()` can't be resolved statically (factory or dynamic).                   |
+| `--static`  | Static parser, but writes partial output and prints the unresolvable includes as warnings.                                                  |
+| `--runtime` | Vite-based runtime discovery (full coverage; needs `vite`; `@vitejs/plugin-rsc` comes with the router). `--config <path>` picks the config. |
 
 ### Auto-detection
 

package/skills/response-routes/SKILL.md

@@ -422,11 +422,11 @@ path.json("/api/users", handler, { name: "users" }, () => [
 Response-route `cache()` stores whole `Response`s. The serve leaf
 (`serveResponseRouteWithCache`) applies the same safety gates as document cache:
 
-| Gate                   | Behavior                                                                                                                                                                                |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **GET/HEAD only**      | Non-GET/HEAD methods skip the cache (handler runs uncached).                                                                                                                            |
-| **Per-client signals** | A response with `Set-Cookie` or `x-rango-keep-cache` is returned live but **not** stored (MISS + SWR revalidation also skip put).                                                       |
-| **Default key**        | `response:{type}:{cacheKeyBase(host, path, searchParams)}` — sorted search, reserved `_rsc*` / allowlisted `__*` params excluded. Custom `key()` / store `keyGenerator` still override. |
+| Gate                   | Behavior                                                                                                                                                                                                 |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **GET/HEAD only**      | Non-GET/HEAD methods skip the cache (handler runs uncached).                                                                                                                                             |
+| **Per-client signals** | A response with `Set-Cookie` or `x-rango-keep-cache` is returned live but **not** stored (MISS + SWR revalidation also skip put).                                                                        |
+| **Default key**        | `response:{type}:{routerId}@{host}{path}[?search]` — the serving router's id, sorted search, reserved `_rsc*` / allowlisted `__*` params excluded. Custom `key()` / store `keyGenerator` still override. |
 
 ## CSRF
 

package/skills/route/SKILL.md

@@ -404,6 +404,35 @@ path("/checkout", CheckoutPage, { name: "checkout" }, () => [
 ]);
 ```
 
+## Errors in a streamed handler
+
+A handler under `loading()` (a route, or a parallel slot) streams: it settles
+after the response started. When it rejects, the nearest `errorBoundary()`
+renders in place of that segment; `notFound()` renders the nearest
+`notFoundBoundary()`. A slot finds boundaries declared on its owning layout or
+route. Layouts and nav stay, on the document load and on a client navigation.
+
+```typescript
+path("/product/:slug", ProductPage, { name: "product" }, () => [
+  loading(<ProductSkeleton />),
+  errorBoundary(({ error }) => <ProductError message={error.message} />),
+  notFoundBoundary(() => <ProductNotFound />),
+]);
+```
+
+- The HTTP status stays what the stream already sent (200), `notFound()`
+  included; a failure before the flush (no `loading()`, or
+  `loading(fallback, { ssr: false })` on a document load) still sets 500 / 404.
+  A loader's 404 is likewise only set when its rejection settles before the
+  response is built.
+- `onError` fires once per failure.
+- A failed render is never stored: `cache()` skips the write for the scope that
+  holds the failed segment, a `ppr` shell and the document cache refuse the
+  whole document, and a Prerender route still fails the build.
+- With no declared boundary the rejection reaches the client and
+  `RootErrorBoundary` replaces the page. A `redirect()` thrown from a streamed
+  handler is not recovered either (see "Redirects").
+
 ## Redirects
 
 `redirect(url, statusOrOptions?)` returns a `Response` (default status `302`).

package/skills/router-setup/SKILL.md

@@ -170,7 +170,7 @@ interface RangoOptions<TEnv> {
     request: Request,
     env: TEnv,
   ) => string | boolean | Promise<string | boolean>;
-  version?: string; // Client/server version string; defaults to the build VERSION
+  version?: string; // Cache version and client/server version; replaces both computed versions (data and document); defaults to the versions `vite build` computes per router
   originCheck?:
     | boolean
     | ((
@@ -215,6 +215,7 @@ rango({
   headScripts: "preinit", // "preinit" (executing head module scripts) | "preload" (modulepreload hints only)
   prerender: { onError: "fail" }, // "fail" | "warn" when a Prerender/Static render throws (/prerender)
   buildEnv: false, // Build-time ctx.env for Prerender/Static handlers (/prerender)
+  encryptionKey: process.env.RANGO_ENCRYPTION_KEY, // Stable server-action encryption key (see Notes)
 });
 ```
 
@@ -254,6 +255,19 @@ Notes:
   renders and PPR shell capture. Unset, documents whose route has a
   `loader(Def, { ssr: false })` raise it automatically so that content stays
   in place; see `/loader`.
+- `encryptionKey` is the key that encrypts inline server-action bound
+  arguments: base64-encoded 32 bytes (`openssl rand -base64 32`). Pass it as
+  `rango({ encryptionKey: process.env.RANGO_ENCRYPTION_KEY })`, never as a
+  literal. It is validated when `rango()` is called (invalid base64 or a wrong
+  size throws). `undefined` falls back to the `RANGO_ENCRYPTION_KEY`
+  environment variable, then to a key generated per build. The key is part of
+  the cache version of every router whose server code encrypts inline-action
+  bound arguments, so without a stable key those routers get a new version (and
+  a cleared cache) on every build; the build prints one note when that applies.
+  A router that renders no such action keeps its cache without one (`/use-cache`,
+  `/cache-guide`).
+- `createRouter({ version })` takes effect on every preset, including `node`
+  and `vercel`. It replaces both computed cache versions with that exact value.
 - `@rangojs/router/vite` also exports `poke()`, a dev-server plugin: type `e`
   then Enter (or Ctrl+R where the terminal passes it through) to full-reload
   the browser.

package/skills/testing/SKILL.md

@@ -89,32 +89,36 @@ The single rule that drives everything:
 
 Each primitive links to its sub-file (API + recipe + caveats).
 
-| The behavior is…                                                                                                                   | Layer        | Primitive                                                                                             | Import root                      |
-| ---------------------------------------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- | -------------------------------- |
-| a `reverse` / `href` / params / env TYPE contract (a wrong name or missing param must not compile)                                 | types (tsc)  | [`@ts-expect-error` / `expectTypeOf`](./reverse-and-types.md)                                         | `@rangojs/router/client` + `tsc` |
-| one loader's data logic                                                                                                            | unit (node)  | [`runLoader`](./loader.md)                                                                            | `@rangojs/router/testing`        |
-| a loader's cookie / header / thrown `redirect()`/`notFound()` / handle-push output                                                 | unit (node)  | [`runLoaderResult`](./loader.md)                                                                      | `@rangojs/router/testing`        |
-| one middleware's ordering / short-circuit / cookie+header merge                                                                    | unit (node)  | [`runMiddleware`](./middleware.md)                                                                    | `@rangojs/router/testing`        |
-| a `"use server"` action's cookie / header / flash output (even on `throw redirect()`)                                              | unit (node)  | [`runInRequestContext`](./server-actions.md)                                                          | `@rangojs/router/testing`        |
-| a `transition({ when })` browser predicate against `{ kind, from, to, action }`                                                    | unit (node)  | [`runTransitionWhen`](./predicates.md) (`{ applied, gatedOff, context }`)                             | `@rangojs/router/testing`        |
-| a `clientUrls()` `revalidate()` / `isAction(ref)` predicate                                                                        | unit (node)  | [`runClientRevalidate`](./predicates.md) (production chain evaluator + locked defaults)               | `@rangojs/router/testing`        |
-| a handle's `collect`/accumulator, a seeded handle read, or a loader handle write                                                   | unit         | [`collectHandle` / seeded `handles` / `handlePushes`](./handles.md)                                   | `@rangojs/router/testing`        |
-| a CLIENT component reading router context (`useParams`/`useReverse`/`Outlet`/`useNavigation`/`useLoader`)                          | unit (DOM)   | [`renderRoute`](./client-components.md)                                                               | `@rangojs/router/testing/dom`    |
-| a stale indicator from `useLoader().isLoading` while a `transition()` navigation re-runs the loader                                | unit (DOM)   | [`renderRoute` + `navigate(url, { loaders })`](./client-components.md#held-navigation)                | `@rangojs/router/testing/dom`    |
-| a component reading `useLocationState(Def)` after `router.push(url, { state: [Def(value)] })`                                      | unit (DOM)   | [`renderRoute` + `withLocationStateKey`](./client-components.md#location-state)                       | `@rangojs/router/testing[/dom]`  |
-| a redirect / status / headers / cookies / **response route** (json/text/html/xml/md), no Flight                                    | integration  | [`dispatch`](./response-routes.md)                                                                    | `@rangojs/router/testing`        |
-| a real async **Server Component** (assert what it rendered: typed boundary props, server-rendered host content, inlined-vs-island) | RSC unit     | [`renderServerTree` + `findClientBoundaries`/`findElements`](./server-tree.md)                        | `@rangojs/router/testing/flight` |
-| the exact Flight **wire payload** shape (a drift snapshot)                                                                         | RSC unit     | [`renderToFlightString` + `toMatchFlightSnapshot`](./flight.md)                                       | `@rangojs/router/testing/flight` |
-| a real route **handler** `(ctx) => rsc` (params/loaders/vars -> rendered RSC + effects)                                            | RSC unit     | [`renderHandler`](./render-handler.md)                                                                | `@rangojs/router/testing/flight` |
-| navigation, hydration, PE parity, view transitions, real SSR                                                                       | e2e          | [`createRangoE2E` -> `parityDescribe`/`expectParity`](./e2e-parity.md)                                | `@rangojs/router/testing/e2e`    |
-| a `"use cache"` hit in a handler (the body runs once across renders; the value round-trips)                                        | RSC unit     | [`renderHandler` + seeded `cacheStore`](./render-handler.md#a-use-cache-hit)                          | `@rangojs/router/testing/flight` |
-| a `"use cache"` hit in a loader (the same, in the react-server project)                                                            | RSC unit     | [`runLoader` + seeded `cacheStore`](./loader.md)                                                      | `@rangojs/router/testing`        |
-| a loader's own `cache()` (HIT, `updateTag()` of a tag its body recorded)                                                           | RSC unit     | [`runLoader` + `cache` + seeded `cacheStore`](./loader.md)                                            | `@rangojs/router/testing`        |
-| cache hit/miss/stale, prerender (= a cache hit by design)                                                                          | e2e + signal | [`assertCacheStatus` (header) / `assertCacheDecision` (telemetry sink)](./cache-prerender.md)         | `@rangojs/router/testing[/e2e]`  |
-| a `ppr` route's shell: MISS -> capture -> HIT, what the shell froze vs what a HIT renders live, tag eviction, navigation replay    | RSC unit     | [`serveShellRequest`](./serve-shell-request.md)                                                       | `@rangojs/router/testing/flight` |
-| PPR shell HIT/MISS in real HTML (`ppr` path option), shell store key / getShell after flush                                        | e2e + signal | [`assertShellStatus` / `shellCacheKey` + store](./cache-prerender.md#ppr-shell-and-navigation-replay) | `@rangojs/router/testing[/e2e]`  |
-| generated route map drift vs runtime                                                                                               | unit (node)  | [`assertGeneratedRoutesMatch`](./reverse-and-types.md)                                                | `@rangojs/router/testing`        |
-| a platform binding (`env.DB` / Durable Object / `env.R2`)                                                                          | unit/integr. | [your own double via `env`](./bindings.md)                                                            | (any primitive's `env` option)   |
+| The behavior is…                                                                                                                   | Layer        | Primitive                                                                                                             | Import root                      |
+| ---------------------------------------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| a `reverse` / `href` / params / env TYPE contract (a wrong name or missing param must not compile)                                 | types (tsc)  | [`@ts-expect-error` / `expectTypeOf`](./reverse-and-types.md)                                                         | `@rangojs/router/client` + `tsc` |
+| one loader's data logic                                                                                                            | unit (node)  | [`runLoader`](./loader.md)                                                                                            | `@rangojs/router/testing`        |
+| a loader's cookie / header / thrown `redirect()`/`notFound()` / handle-push output                                                 | unit (node)  | [`runLoaderResult`](./loader.md)                                                                                      | `@rangojs/router/testing`        |
+| one middleware's ordering / short-circuit / cookie+header merge                                                                    | unit (node)  | [`runMiddleware`](./middleware.md)                                                                                    | `@rangojs/router/testing`        |
+| a `"use server"` action's cookie / header / flash output (even on `throw redirect()`)                                              | unit (node)  | [`runInRequestContext`](./server-actions.md)                                                                          | `@rangojs/router/testing`        |
+| a `transition({ when })` browser predicate against `{ kind, from, to, action }`                                                    | unit (node)  | [`runTransitionWhen`](./predicates.md) (`{ applied, gatedOff, context }`)                                             | `@rangojs/router/testing`        |
+| a `clientUrls()` `revalidate()` / `isAction(ref)` predicate                                                                        | unit (node)  | [`runClientRevalidate`](./predicates.md) (production chain evaluator + locked defaults)                               | `@rangojs/router/testing`        |
+| a handle's `collect`/accumulator, a seeded handle read, or a loader handle write                                                   | unit         | [`collectHandle` / seeded `handles` / `handlePushes`](./handles.md)                                                   | `@rangojs/router/testing`        |
+| a CLIENT component reading router context (`useParams`/`useReverse`/`Outlet`/`useNavigation`/`useLoader`)                          | unit (DOM)   | [`renderRoute`](./client-components.md)                                                                               | `@rangojs/router/testing/dom`    |
+| a stale indicator from `useLoader().isLoading` while a `transition()` navigation re-runs the loader                                | unit (DOM)   | [`renderRoute` + `navigate(url, { loaders })`](./client-components.md#held-navigation)                                | `@rangojs/router/testing/dom`    |
+| a component reading `useLocationState(Def)` after `router.push(url, { state: [Def(value)] })`                                      | unit (DOM)   | [`renderRoute` + `withLocationStateKey`](./client-components.md#location-state)                                       | `@rangojs/router/testing[/dom]`  |
+| location state while a navigation is pending (a loader the test holds), or after a back/forward                                    | unit (DOM)   | [`navigate(url, { state, loaders })`, a `popstate` event](./client-components.md#state-while-a-navigation-is-pending) | `@rangojs/router/testing[/dom]`  |
+| a CLIENT component's hydration: its first client render against its own server HTML (`typeof window`, a late `<Suspense>`)         | unit (DOM)   | [`renderRoute` + `hydrate: true`](./client-components.md#hydration)                                                   | `@rangojs/router/testing/dom`    |
+| location state with `clearOnReload`: state after a refresh vs a client navigation                                                  | unit (DOM)   | [`renderRoute` seeds, with and without `hydrate: true`](./client-components.md#location-state)                        | `@rangojs/router/testing[/dom]`  |
+| a redirect / status / headers / cookies / **response route** (json/text/html/xml/md), no Flight                                    | integration  | [`dispatch`](./response-routes.md)                                                                                    | `@rangojs/router/testing`        |
+| a real async **Server Component** (assert what it rendered: typed boundary props, server-rendered host content, inlined-vs-island) | RSC unit     | [`renderServerTree` + `findClientBoundaries`/`findElements`](./server-tree.md)                                        | `@rangojs/router/testing/flight` |
+| the exact Flight **wire payload** shape (a drift snapshot)                                                                         | RSC unit     | [`renderToFlightString` + `toMatchFlightSnapshot`](./flight.md)                                                       | `@rangojs/router/testing/flight` |
+| a real route **handler** `(ctx) => rsc` (params/loaders/vars -> rendered RSC + effects)                                            | RSC unit     | [`renderHandler`](./render-handler.md)                                                                                | `@rangojs/router/testing/flight` |
+| navigation, hydration, PE parity, view transitions, real SSR                                                                       | e2e          | [`createRangoE2E` -> `parityDescribe`/`expectParity`](./e2e-parity.md)                                                | `@rangojs/router/testing/e2e`    |
+| a `"use cache"` hit in a handler (the body runs once across renders; the value round-trips)                                        | RSC unit     | [`renderHandler` + seeded `cacheStore`](./render-handler.md#a-use-cache-hit)                                          | `@rangojs/router/testing/flight` |
+| a `"use cache"` hit in a loader (the same, in the react-server project)                                                            | RSC unit     | [`runLoader` + seeded `cacheStore`](./loader.md)                                                                      | `@rangojs/router/testing`        |
+| a loader's own `cache()` (HIT, `updateTag()` of a tag its body recorded)                                                           | RSC unit     | [`runLoader` + `cache` + seeded `cacheStore`](./loader.md)                                                            | `@rangojs/router/testing`        |
+| cache hit/miss/stale, prerender (= a cache hit by design)                                                                          | e2e + signal | [`assertCacheStatus` (header) / `assertCacheDecision` (telemetry sink)](./cache-prerender.md)                         | `@rangojs/router/testing[/e2e]`  |
+| a `ppr` route's shell: MISS -> capture -> HIT, what the shell froze vs what a HIT renders live, tag eviction, navigation replay    | RSC unit     | [`serveShellRequest`](./serve-shell-request.md)                                                                       | `@rangojs/router/testing/flight` |
+| a form submitted before hydration: a `useActionState` result the no-JS POST renders, the form state its payload carries            | RSC unit     | [`createActionForm` + `serveShellRequest({ form })`](./serve-shell-request.md)                                        | `@rangojs/router/testing/flight` |
+| PPR shell HIT/MISS in real HTML (`ppr` path option), shell store key / getShell after flush                                        | e2e + signal | [`assertShellStatus` / `shellCacheKey` + store](./cache-prerender.md#ppr-shell-and-navigation-replay)                 | `@rangojs/router/testing[/e2e]`  |
+| generated route map drift vs runtime                                                                                               | unit (node)  | [`assertGeneratedRoutesMatch`](./reverse-and-types.md)                                                                | `@rangojs/router/testing`        |
+| a platform binding (`env.DB` / Durable Object / `env.R2`)                                                                          | unit/integr. | [your own double via `env`](./bindings.md)                                                                            | (any primitive's `env` option)   |
 
 Cross-references to the DSL skills: `/loader`, `/middleware`, `/server-actions`,
 `/handler-use`, `/hooks`, `/response-routes`, `/route`, `/caching`, `/prerender`,
@@ -147,6 +151,7 @@ beside their function):
 |                                           | `collectHandle`                                                                                                                                              | [`handles.md`](./handles.md)                         |
 |                                           | `withLocationStateKey`                                                                                                                                       | [`client-components.md`](./client-components.md)     |
 |                                           | `dispatch`                                                                                                                                                   | [`response-routes.md`](./response-routes.md)         |
+|                                           | `setBuildVersions`                                                                                                                                           | [`serve-shell-request.md`](./serve-shell-request.md) |
 |                                           | `assertCacheStatus`, `assertCacheDecision`, `parseCacheHeader`, `createCacheSink`, `filterCacheDecisions`                                                    | [`cache-prerender.md`](./cache-prerender.md)         |
 |                                           | `assertShellStatus`, `parseShellStatus`, `shellCacheKey`, `SHELL_STATUS_HEADER`, `assertPprReplayStatus`, `parsePprReplayStatus`, `PPR_REPLAY_STATUS_HEADER` | [`cache-prerender.md`](./cache-prerender.md)         |
 |                                           | `assertGeneratedRoutesMatch`, `diffGeneratedRoutes`                                                                                                          | [`reverse-and-types.md`](./reverse-and-types.md)     |
@@ -154,7 +159,7 @@ beside their function):
 | `@rangojs/router/testing/flight`          | `renderToFlightString`, `normalizeFlight`, `assertFlightRuntimeAvailable`                                                                                    | [`flight.md`](./flight.md)                           |
 |                                           | `renderServerTree`, `findClientBoundaries`, `findElements`, `textContent`, `assertFlightTreeRuntimeAvailable`                                                | [`server-tree.md`](./server-tree.md)                 |
 |                                           | `renderHandler`                                                                                                                                              | [`render-handler.md`](./render-handler.md)           |
-|                                           | `serveShellRequest`, `resetShellTestState`                                                                                                                   | [`serve-shell-request.md`](./serve-shell-request.md) |
+|                                           | `serveShellRequest`, `resetShellTestState`, `createActionForm`                                                                                               | [`serve-shell-request.md`](./serve-shell-request.md) |
 | `@rangojs/router/testing/flight-matchers` | `flightMatchers` (`toMatchFlight`, `toMatchFlightSnapshot`)                                                                                                  | [`flight.md`](./flight.md)                           |
 | `@rangojs/router/testing/vitest`          | `rangoTestConfig`, `rangoTestAliases`, `rangoInlineDeps`, `rangoUseClientTransform`, `rangoUseCacheTransform`                                                | [`setup.md`](./setup.md)                             |
 | `@rangojs/router/testing/e2e`             | `createRangoE2E` and its standalone helpers; the cache/shell status helpers above are re-exported here                                                       | [`e2e-parity.md`](./e2e-parity.md)                   |

package/skills/testing/cache-prerender.md

@@ -121,25 +121,25 @@ 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 })` 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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| 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(router, url, searchParams?, partition?)` | same                                 | Production shell store key (`routerId@host+pathname+sorted search+:shell`, then `\|partition`) for `store.getShell` / custom stores. `router` is the router that serves the URL, or `{ id }` where it cannot be imported (a Playwright test): a shell belongs to one router. 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
 
-| Layer    | What you assert             | How                                                                                                                                                                                              |
-| -------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **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" })`                                                                                  |
+| Layer    | What you assert             | How                                                                                                                                                                                                      |
+| -------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Unit** | store family + key identity | `MemorySegmentCacheStore` + `shellCacheKey(router, 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. 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.
 
@@ -175,10 +175,11 @@ parityDescribe("product shell", (f) => {
 // Unit (Vitest): the key the serve path uses, against your own store instance
 import { expect, it } from "vitest";
 import { shellCacheKey } from "@rangojs/router/testing";
+import { router } from "../src/router";
 
 it("stores the shell under the production key", async () => {
   // ...after your code under test captured a shell into `store`...
-  const key = shellCacheKey(new URL("http://localhost/products/1"));
+  const key = shellCacheKey(router, new URL("http://localhost/products/1"));
   expect(await store.getShell(key)).not.toBeNull();
 });
 ```