@rangojs/router 0.20.0 → 0.22.0

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

@@ -14,6 +14,8 @@ The one stub is the HTML step (the SSR module), because `react-dom/server` does
 
 So `prelude` is the shell as captured (Flight text, not HTML): a value the shell froze appears there, and a hole (a live loader under `loading()`) does not.
 
+A `Prerender` route is served as in production: from the artifact `router.matchForPrerender` bakes for the URL (on its first request, kept until `resetShellTestState()`), through the production prerender store, so its handler runs once, at the bake, and never on a request. Its first `ppr` request is a MISS with a runtime capture, as a URL without a build-time shell is in production. The shell `vite build` bakes (served first in production for a URL without a query string) is not reproduced: keep that in e2e. The `env` option doubles as the bake's `buildEnv`. An on-demand route (`Prerender(..., { onDemand })`) is baked only when it is wrapped in `Passthrough()` and its `getParams()` lists the param, as a build bakes it; a plain on-demand route is not baked here, so its pages come from the prerender store alone (`router.prerender()`), and "a removed page the build baked" is a case for a `Passthrough` route or for e2e.
+
 ## API
 
 ### Options — `ServeShellRequestOptions`
@@ -27,20 +29,21 @@ So `prelude` is the shell as captured (Flight text, not HTML): a value the shell
 
 ### Returns — `ServeShellRequestResult`
 
-| Field          | Type                                     | Meaning                                                                                                                                                                             |
-| -------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `shellStatus`  | `"HIT" \| "MISS" \| null`                | `x-rango-shell`; null when the serve path did not consider the request (not a `ppr` route, a nonce'd request, a partial request).                                                   |
-| `replayStatus` | `PprReplayStatus \| null`                | `x-rango-ppr-replay` on a partial request: `{ outcome: "HIT", freshness }` or `{ outcome: "BYPASS", reason }`.                                                                      |
-| `prelude`      | `string \| undefined`                    | The prelude a HIT served (the capture's Flight text). `undefined` unless `shellStatus` is `"HIT"`.                                                                                  |
-| `flight`       | `string \| undefined`                    | The Flight payload this request rendered: a HIT's tail, a document render, or a partial response. `undefined` when no Flight rendered (a redirect, a middleware response).          |
-| `key`          | `string`                                 | The shell key the serve path resolved for a document it read (MISS or HIT), request partition included. Otherwise (no `ppr`, a partial request) the URL's key without a partition.  |
-| `readEntry`    | `() => Promise<ShellCacheEntry \| null>` | Reads the document entry under `key` from the request's store (a passive `getShell`). A read: on a store with a shell memo it warms the memo, so call it after the reads you count. |
-| `response`     | `Response`                               | Status and headers. Its body is already read.                                                                                                                                       |
-| `body`         | `string`                                 | The body text.                                                                                                                                                                      |
+| Field          | Type                                              | Meaning                                                                                                                                                                             |
+| -------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `shellStatus`  | `"HIT" \| "MISS" \| null`                         | `x-rango-shell`; null when the serve path did not consider the request (not a `ppr` route, a nonce'd request, a partial request).                                                   |
+| `replayStatus` | `PprReplayStatus \| null`                         | `x-rango-ppr-replay` on a partial request: `{ outcome: "HIT", freshness }` or `{ outcome: "BYPASS", reason }`.                                                                      |
+| `prelude`      | `string \| undefined`                             | The prelude a HIT served (the capture's Flight text). `undefined` unless `shellStatus` is `"HIT"`.                                                                                  |
+| `flight`       | `string \| undefined`                             | The Flight payload this request rendered: a HIT's tail, a document render, or a partial response. `undefined` when no Flight rendered (a redirect, a middleware response).          |
+| `key`          | `string`                                          | The shell key the serve path resolved for a document it read (MISS or HIT), request partition included. Otherwise (no `ppr`, a partial request) the URL's key without a partition.  |
+| `readEntry`    | `() => Promise<ShellCacheEntry \| null>`          | Reads the document entry under `key` from the request's store (a passive `getShell`). A read: on a store with a shell memo it warms the memo, so call it after the reads you count. |
+| `readHandles`  | `() => Promise<ShellRequestHandles \| undefined>` | Decodes the response's handle data as the browser reads it: `{ hydration, late }` (see "Handles and loader data"). `undefined` when no Flight rendered.                             |
+| `response`     | `Response`                                        | Status and headers. Its body is already read.                                                                                                                                       |
+| `body`         | `string`                                          | The body text.                                                                                                                                                                      |
 
 ### `resetShellTestState(): Promise<void>`
 
-A worker keeps some PPR state across requests, and so does the test process across tests: the capture's stampede guard and backoff (a refused capture backs its URL off for later tests too), the capture's and the serve path's once-per-key warnings, the build-shell manifest memo, and `CFCacheStore`'s isolate memos (shells, tag markers, tag hints), which every `CFCacheStore` shares by namespace and URL — a later test's first request can be a HIT from an earlier test's shell. `resetShellTestState()` clears all of it. Call it in `beforeEach`, never while a request is in flight. `VercelCacheStore`'s memos live on the `cache` handle you pass it: a new handle per test starts empty.
+A worker keeps some PPR state across requests, and so does the test process across tests: the capture's stampede guard and backoff (a refused capture backs its URL off for later tests too), the capture's and the serve path's once-per-key warnings, the build-shell manifest memo, the `Prerender` artifacts baked so far, and `CFCacheStore`'s isolate memos (shells, tag markers, tag hints), which every `CFCacheStore` shares by namespace and URL — a later test's first request can be a HIT from an earlier test's shell. `resetShellTestState()` clears all of it. Call it in `beforeEach`, never while a request is in flight. `VercelCacheStore`'s memos live on the `cache` handle you pass it: a new handle per test starts empty.
 
 ## Recipe
 
@@ -99,6 +102,35 @@ it("replays the captured segments on a client navigation", async () => {
 
 A store built per request from a function `cache` config gets the request's execution context (`ctx`), so its own `waitUntil` writes (`CFCacheStore({ ctx })`) settle with the call. A store built outside the request with its own `waitUntil` (`VercelCacheStore`'s option) is not settled by the call. For `CFCacheStore`, stub the `caches` global and pass a KV double in `env`; for `VercelCacheStore`, pass a `cache` double. A store's shell memo then behaves as in production (count your double's reads across two HITs).
 
+## Simulating a deploy: setBuildVersions
+
+A stored shell is stamped with the router's document version and a HIT requires the stamp to match. In a build, `vite build` computes that version per `createRouter()`; under test there is no build, so the primitives run unversioned. `setBuildVersions` (from `@rangojs/router/testing`) installs the versions a build would ship, and calling it again with a different `document` is a deploy that changed the router:
+
+```ts
+import { setBuildVersions } from "@rangojs/router/testing";
+
+afterEach(() => setBuildVersions()); // remove the versions: unversioned again
+
+it("a deploy that changes the document version retires the shell", async () => {
+  const cacheStore = new MemorySegmentCacheStore();
+  setBuildVersions({ data: "d1", document: "h1" });
+
+  expect(
+    (await serveShellRequest(router, "/product/4", { cacheStore })).shellStatus,
+  ).toBe("MISS");
+  expect(
+    (await serveShellRequest(router, "/product/4", { cacheStore })).shellStatus,
+  ).toBe("HIT");
+
+  setBuildVersions({ data: "d1", document: "h2" }); // new SSR output or client assets
+  expect(
+    (await serveShellRequest(router, "/product/4", { cacheStore })).shellStatus,
+  ).toBe("MISS");
+});
+```
+
+`setBuildVersions({ data, document, routers?: { [routerId]: { data, document } } })` takes the whole-build pair and, optionally, a pair per router id (a router with no entry gets the whole-build pair). `setBuildVersions()` with no argument removes them. The types `BuildVersions` and `RouterVersions` are exported too. `dispatch` sees the same versions.
+
 ## A HIT runs no handler
 
 A HIT replays what the capture's handlers produced — their elements, the promises they passed or pushed, their handle values — and runs only middleware and loaders. Count runs to pin it:
@@ -134,9 +166,12 @@ const silver = await serveShellRequest(router, "/pricing", tier("silver"));
 expect(silver.shellStatus).toBe("MISS"); // its own capture, never gold's shell
 const gold = await serveShellRequest(router, "/pricing", tier("gold"));
 expect(gold.shellStatus).toBe("HIT");
-expect(gold.key).toBe(shellCacheKey("/pricing", undefined, "tier:gold"));
-// "localhost/pricing:shell|key%3Atier%253Agold": the key() result is
-// namespaced as production stores it (issue #975).
+expect(gold.key).toBe(
+  shellCacheKey(router, "/pricing", undefined, "tier:gold"),
+);
+// "{router.id}@localhost/pricing:shell|key%3Atier%253Agold": the router the
+// shell belongs to, then the key() result namespaced as production stores it
+// (issue #975).
 expect(await gold.readEntry()).not.toBeNull();
 ```
 
@@ -149,7 +184,7 @@ Under nested keyed `cache()` boundaries the partition is their `key()` results c
 //   ]),
 // ])
 expect(result.key).toBe(
-  shellCacheKey("/plans", undefined, ["tier:gold", "v:a"]),
+  shellCacheKey(router, "/plans", undefined, ["tier:gold", "v:a"]),
 );
 ```
 
@@ -159,24 +194,134 @@ A store `keyGenerator` result that partitions the record partitions the shell to
 // createRouter({ cache: { store: localeStore } }), where localeStore's
 // keyGenerator returns `${defaultKey}|${locale}`
 expect(result.key).toBe(
-  shellCacheKey("/pricing", undefined, {
-    generated: ["doc:localhost/pricing|de"],
+  shellCacheKey(router, "/pricing", undefined, {
+    generated: [`doc:${router.id}@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.
 
+## Two routers on one cache store
+
+A shell's key starts with its router's id (`shellCacheKey(router, url)`), so two routers that share a store and serve the same host and path each read and write their own (why and when: `/host-router`, "Shared cache store"). Serve both against one store to pin it:
+
+```ts
+const store = new MemorySegmentCacheStore();
+// appA and appB: createRouter({ id: "app-a" | "app-b", cache: { store } }),
+// each with path("/pricing", ..., { ppr: true })
+const url = "http://preview.dev/pricing";
+
+await serveShellRequest(appA, url); // MISS + capture
+const fromB = await serveShellRequest(appB, url);
+expect(fromB.shellStatus).toBe("MISS"); // never app A's shell
+expect((await serveShellRequest(appA, url)).shellStatus).toBe("HIT");
+expect((await serveShellRequest(appB, url)).shellStatus).toBe("HIT");
+```
+
+Vitest runs no Vite id transform, so give each router an explicit `id` when a test builds more than one, and do not reuse one `id` for routers with different routes in the same file: the route manifest is registered per id.
+
 ## Handles and loader data
 
-The result carries no structured `handles` map (unlike `renderHandler`): a handle value and loader data ride the payload, so you assert them as text in `prelude` and `flight`. A value the handler pushed is in the prelude and in every HIT's tail; a live loader's data is only in the tail. No public helper decodes a payload string into values: `normalizeFlight` and the `flightMatchers` (`toMatchFlight`) work on the text too.
+`readHandles()` decodes the handle data the response carries, the way the browser reads it, with deferred values resolved. Each field is the raw handle data (`{ [handleId]: { [segmentId]: values[] } }`):
+
+| Field       | What it is                                                                                                                                          |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hydration` | What the document hydrates with (`metadata.handles`, read to its end before hydration starts). For a `partial` request, the last state it streamed. |
+| `late`      | The states that arrived on the late channel (`metadata.handlesLate`), in order. Each replaces the client's handle data after hydration. Often `[]`. |
+
+On a HIT the client hydrates with exactly what the shell was rendered from, so `hydration` is also what the shell's HTML holds, and whatever this request's loaders push, replace or drop is in `late` (see `/ppr`, "Handles on a shell HIT"):
 
 ```ts
-// The handler pushed ctx.use(Meta)({ title: "Widget - Shop" })
-expect(hit.prelude).toContain('"title":"Widget - Shop"');
-expect(hit.flight).toContain('"title":"Widget - Shop"');
+// The handler pushed ctx.use(Notes)("from-handler"); a live loader pushes
+// ctx.use(Notes)("in stock").
+const values = (data) =>
+  Object.values(data ?? {}).flatMap((s) => Object.values(s).flat());
+
+const hit = await serveShellRequest(router, "/product/1", { cacheStore });
+const handles = await hit.readHandles();
+expect(values(handles.hydration)).toEqual(["from-handler"]); // the shell's HTML, hydrates clean
+expect(values(handles.late.at(-1))).toEqual(["from-handler", "in stock"]); // after hydration
 ```
 
+Loader data has no decoder: it rides the payload, so assert it as text in `prelude` and `flight`. `normalizeFlight` and the `flightMatchers` (`toMatchFlight`) work on the text too. A live loader's data is only in the tail.
+
+```ts
+expect(hit.flight).toContain('"stock":"in stock"');
+```
+
+## Warming a route: router.prerender()
+
+`router.prerender()` warms a route that is not `Prerender(..., { onDemand })`
+through `router.fetch` (`/prerender` → "Warm any route before traffic").
+Importing `serveShellRequest` gives that handler the same HTML stub, so the
+whole path runs here: warm, then serve the next visitor's request.
+
+```tsx
+class SharedMemoryStore extends MemorySegmentCacheStore {
+  // The shipped store is "local" and refused; a test store says it is shared.
+  readonly scope = "global" as const;
+}
+
+const router = createRouter({
+  cache: { store: new SharedMemoryStore() },
+}).routes(
+  urls(({ path }) => [path("/product/:id", ProductPage, { ppr: true })]),
+);
+
+const result = await router.prerender({ env: {} })(
+  "http://localhost/product/1",
+);
+expect(result).toMatchObject({ ok: true, path: "warm", status: "warmed" });
+
+// No visitor has requested the URL: its first document is a HIT.
+const hit = await serveShellRequest(router, "/product/1");
+expect(hit.shellStatus).toBe("HIT");
+```
+
+- Configure the store on the router. A warm writes to the store
+  `createRouter({ cache })` resolves, not to the `cacheStore` option of
+  `serveShellRequest`.
+- Give the target the origin `serveShellRequest` uses (`http://localhost`), as
+  a full URL or with `router.prerender({ env, origin })`: cache keys carry the
+  host. A path target with neither returns `skipped-no-origin`, unless the
+  runner is called from inside a served request (a route handler that calls
+  `router.prerender()`), where it takes that request's origin.
+- To assert a replace, count handler runs or render a per-run stamp: fill the
+  cache with one request, move the data, warm, then check the next request
+  shows the new value and ran no handler.
+- `router.fetch` binds its handler's document version once, as a production
+  isolate does, so `setBuildVersions()` between two warms does not move it.
+
+## A form submitted before hydration
+
+`serveShellRequest(router, url, { form })` POSTs a form the way a browser does before the page hydrates, through the production no-JS path: the action runs, the page re-renders, and for a `useActionState` form the document payload carries the form state. Build the body with `createActionForm(action, { id })` from the same entry; it writes React's hidden fields and registers `action` under `id` (`<module id>#<export name>`, any unique string of that shape in a test).
+
+```tsx
+import {
+  createActionForm,
+  serveShellRequest,
+} from "@rangojs/router/testing/flight";
+
+const form = createActionForm(makeToken, { id: "actions/token#makeToken" });
+const result = await serveShellRequest(router, "/token", { form });
+
+// What the SSR render received, and what the browser entry hands hydrateRoot:
+expect(result.formState).toEqual([
+  { token: "tok-1" },
+  "k0",
+  "actions/token#makeToken",
+  0,
+]);
+expect(await result.readPayloadFormState()).toEqual(result.formState);
+```
+
+- `useActionState: false` builds a plain `<form action={fn}>` POST (`$ACTION_ID_`): the action runs as `(formData)` and no form state is carried. Default true runs `(prevState, formData)` with the hook's initial `null`. `fields` are the form's own fields (`formData.get("name")`).
+- An action returning a state Flight cannot serialize (a class instance) still renders the document with status 200 and `formState` holds the raw value, but `readPayloadFormState()` rejects: the entry catches that and hydrates without it, as before the fix.
+- A GET, a plain-form POST and a redirecting action carry no form state: `formState` and `readPayloadFormState()` are undefined, a redirect has no `flight`.
+- Request headers come from `headers`. No `Origin` is sent by default, which the origin guard allows.
+- Not with `partial`. The hydration itself (`hydrateRoot` taking the state, the hook not resetting) is e2e.
+
 ## Caveats
 
 What the HTML stub cannot reproduce, so keep it in e2e:
@@ -192,7 +337,7 @@ Other caveats:
 - Call `resetShellTestState()` in `beforeEach` (see above). Without it, a URL a previous test left backed off, or a shell memoized by another `CFCacheStore`, changes what the next test sees.
 - `readEntry()` reads the document entry under `key`. A partial request that finds no entry captures a navigation-only entry, which is stored apart from it.
 - `updateTag()` needs a request context with the store: call it through `runInRequestContext(fn, { cacheStore })` or your app's own endpoint (`dispatch`). A store refuses a capture that starts in the invalidation's millisecond (the invalidation wins) and backs the key off; `serveShellRequest` starts each request in a later millisecond than the call, so an invalidation made before the call cannot collide with it.
-- GET only. Server actions are not served; test their effects with `runInRequestContext`.
+- GET, and one POST shape: a form submitted before hydration (see "A form submitted before hydration" above). Other server action requests are not served; test their effects with `runInRequestContext`.
 - Same setup as every Flight test: the react-server condition and `rangoTestAliases()` (see [`./setup.md`](./setup.md)).
 
 ## See also

package/skills/testing/server-actions.md

@@ -8,22 +8,22 @@
 
 ### Options — `CreateTestContextOptions<TEnv>`
 
-| Field           | Type                                                   | Meaning                                                                                                                                                                                                                                                                                                                                               |
-| --------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `env`           | `TEnv`                                                 | Platform bindings the action reads (`ctx.env`). Default `{}`. Double them yourself (see `./bindings.md`).                                                                                                                                                                                                                                             |
-| `request`       | `Request \| string`                                    | The request to run under. A `string` becomes `new Request(url)`; pass a full `Request` to seed a `Cookie` header. Default origin `http://localhost/`.                                                                                                                                                                                                 |
-| `requestInit`   | `RequestInit`                                          | Init merged when `request` is a string (e.g. `{ method, headers, body }`).                                                                                                                                                                                                                                                                            |
-| `variables`     | `Record<string, unknown>`                              | Raw backing store for `ctx.get()` / `ctx.set()`, pre-seeded from `vars`.                                                                                                                                                                                                                                                                              |
-| `vars`          | `VarsInit`                                             | Vars a prior middleware would have set (object or `[token, value]` list).                                                                                                                                                                                                                                                                             |
-| `routeMap`      | `Record<string, string>`                               | Route name -> pattern map enabling `ctx.reverse()` without global state.                                                                                                                                                                                                                                                                              |
-| `routeName`     | `string`                                               | Current route name (drives `ctx.reverse()` self-references).                                                                                                                                                                                                                                                                                          |
-| `params`        | `Record<string, string>`                               | Route params on `ctx.params`.                                                                                                                                                                                                                                                                                                                         |
-| `basename`      | `string`                                               | Router basename, normalized exactly like `createRouter({ basename })`; drives `redirect()` prefixing. Default `undefined`.                                                                                                                                                                                                                            |
-| `cacheStore`    | `SegmentCacheStore`                                    | Backing store for `use cache` functions (same shape as `createRouter({ cache })`). Without it, cached functions run uncached and their guards never fire.                                                                                                                                                                                             |
-| `cacheProfiles` | `Record<string, CacheProfile>`                         | Profiles for `use cache: "name"`, same shape as `createRouter({ cacheProfiles })`. An unknown profile throws.                                                                                                                                                                                                                                         |
-| `theme`         | `ThemeConfig \| true`                                  | Theme config (same shape as `createRouter({ theme })`). Without it `ctx.theme` / `ctx.setTheme` are inert.                                                                                                                                                                                                                                            |
-| `build`         | `boolean`                                              | Seed `ctx.build` (default `false`) for code that branches on the build-time PPR shell-capture pass. With `true`, `ctx.waitUntil()` is inert, as at build time.                                                                                                                                                                                        |
-| `stateCookie`   | `StateCookieSeed` (`{ prefix?, routerId?, version? }`) | Customize the rango state cookie an action calling `invalidateClientCache()` rotates. The name is ALWAYS seeded (default `rango-state_router_0`) so the rotation `Set-Cookie` fires like production; override `prefix`/`routerId` to match `createRouter({ stateCookiePrefix, id })`, or `version` (value is `{version}:{timestamp}`, default `"0"`). |
+| Field           | Type                                                   | Meaning                                                                                                                                                                                                                                                                                                                                                                                                               |
+| --------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `env`           | `TEnv`                                                 | Platform bindings the action reads (`ctx.env`). Default `{}`. Double them yourself (see `./bindings.md`).                                                                                                                                                                                                                                                                                                             |
+| `request`       | `Request \| string`                                    | The request to run under. A `string` becomes `new Request(url)`; pass a full `Request` to seed a `Cookie` header. Default origin `http://localhost/`.                                                                                                                                                                                                                                                                 |
+| `requestInit`   | `RequestInit`                                          | Init merged when `request` is a string (e.g. `{ method, headers, body }`).                                                                                                                                                                                                                                                                                                                                            |
+| `variables`     | `Record<string, unknown>`                              | Raw backing store for `ctx.get()` / `ctx.set()`, pre-seeded from `vars`.                                                                                                                                                                                                                                                                                                                                              |
+| `vars`          | `VarsInit`                                             | Vars a prior middleware would have set (object or `[token, value]` list).                                                                                                                                                                                                                                                                                                                                             |
+| `routeMap`      | `Record<string, string>`                               | Route name -> pattern map enabling `ctx.reverse()` without global state.                                                                                                                                                                                                                                                                                                                                              |
+| `routeName`     | `string`                                               | Current route name (drives `ctx.reverse()` self-references).                                                                                                                                                                                                                                                                                                                                                          |
+| `params`        | `Record<string, string>`                               | Route params on `ctx.params`.                                                                                                                                                                                                                                                                                                                                                                                         |
+| `basename`      | `string`                                               | Router basename, normalized exactly like `createRouter({ basename })`; drives `redirect()` prefixing. Default `undefined`.                                                                                                                                                                                                                                                                                            |
+| `cacheStore`    | `SegmentCacheStore`                                    | Backing store for `use cache` functions (same shape as `createRouter({ cache })`). Without it, cached functions run uncached and their guards never fire.                                                                                                                                                                                                                                                             |
+| `cacheProfiles` | `Record<string, CacheProfile>`                         | Profiles for `use cache: "name"`, same shape as `createRouter({ cacheProfiles })`. An unknown profile throws.                                                                                                                                                                                                                                                                                                         |
+| `theme`         | `ThemeConfig \| true`                                  | Theme config (same shape as `createRouter({ theme })`). Without it `ctx.theme` / `ctx.setTheme` are inert.                                                                                                                                                                                                                                                                                                            |
+| `build`         | `boolean`                                              | Seed `ctx.build` (default `false`) for code that branches on the build-time PPR shell-capture pass. With `true`, `ctx.waitUntil()` is inert, as at build time.                                                                                                                                                                                                                                                        |
+| `stateCookie`   | `StateCookieSeed` (`{ prefix?, routerId?, version? }`) | Customize the rango state cookie an action calling `invalidateClientCache()` rotates. The name is ALWAYS seeded (default `rango-state_router_0`) so the rotation `Set-Cookie` fires like production; override `prefix`/`routerId` to match `createRouter({ stateCookiePrefix, id })`, or `version` (the app's version, as `createRouter({ version })` would set it; value is `{version}:{timestamp}`, default `"0"`). |
 
 ### Context — `RequestContext<TEnv>` (what your code receives)
 
@@ -110,7 +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).
+- 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, including one that carries the `clearOnReload` suffix, `__rsc_ls_Flash~r`).
 - 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/testing/server-tree.md

@@ -128,7 +128,7 @@ it("asserts the server-rendered host content", async () => {
 - A client boundary's props come back as REAL JS values after deserialization (a `Date` is a `Date`, not a `$D...` encoding) — but there is NO hydration and NO interaction; boundaries are inert placeholders carrying props.
 - Server COMPONENTS do not survive Flight as identities (they are executed during serialization), so `findElements` matches the host elements they PRODUCED, not the component function. Client islands keep identity — use `findClientBoundaries` for those.
 - `findClientBoundaries` finds islands (`I` rows); `findElements` finds host elements. A `testId` on an island matches with `findClientBoundaries`; a `testId` on a host element matches with `findElements`. Use `textContent(node)` in place of `JSON.stringify(tree).toContain`.
-- A true interactive, clickable DOM `renderServer` is intentionally NOT shipped: in-process happy-dom hydration re-tests React more than your app and misses server/client divergence (the only hydration bug worth a dedicated test, which needs a real browser). Test interaction at e2e.
+- A true interactive, clickable DOM `renderServer` is intentionally NOT shipped: in-process happy-dom hydration of a Flight tree re-tests React more than your app and misses the divergence that needs the real document (streaming order, client-reference identity, the browser's HTML parser). Test interaction at e2e. A CLIENT component's own server/client divergence is unit-reachable: `renderRoute` with `hydrate: true` ([`./client-components.md`](./client-components.md#hydration)).
 
 ## See also
 

package/skills/typesafety/generated-files-and-cli.md

@@ -113,7 +113,7 @@ and client helpers.
 CLI flags: the default mode fails (and writes nothing) when an `include()` cannot
 be resolved statically (factory functions, dynamic expressions); `--static`
 accepts partial output with warnings; `--runtime` uses Vite-based discovery for
-full coverage (needs `vite` and `@vitejs/plugin-rsc`, optional
+full coverage (needs `vite`, optional
 `--config <path>`). Passing a directory scans it for router and `urls()` files.
 
 ### Named Routes, `$$routeNames`, And `router.routeMap`

package/skills/use-cache/SKILL.md

@@ -151,11 +151,15 @@ argument. The same holds for a loader's own `cache()` (`/loader` → "Cache Key"
 
 The tainted `ctx` object is excluded from arg serialization (see below), but
 route-identifying fields read off it are extracted into `serializedArgs`:
-`url.host`, route name (`_routeName`), `pathname`, `params`, response type
-(`_responseType`), and the user-facing sorted search params (internal `_rsc*`/`__`
-params excluded). The same cached function called with `ctx` on different routes,
-param combinations, hosts, response types, or query variants therefore produces
-distinct cache entries -- not one shared entry.
+the serving router's id and `url.host` (`{routerId}@{host}`), route name
+(`_routeName`), `pathname`, `params`, response type (`_responseType`), and the
+user-facing sorted search params (internal `_rsc*`/`__` params excluded). The
+same cached function called with `ctx` on different routes, param combinations,
+hosts, response types, or query variants therefore produces distinct cache
+entries -- not one shared entry. Two routers that call it on one host and path
+keep two entries as well: a `ctx` is one router's (`/host-router`, "Shared
+cache store"). A bare `Request` argument folds in its URL only, so it names no
+router.
 
 ## Request-Scoped Arguments (ctx, Request, env)
 
@@ -485,11 +489,22 @@ the current time and expect freshness -- those are frozen at cache-write. The
 `cookies()`/`headers()` read guard applies to the cached function body, NOT to an
 inline action's body.
 
-Deploy note: captured values are encrypted with a per-build key by default. If
-cache entries can outlive a deploy (a persistent store such as the Cloudflare
-cache store), set `RANGO_ENCRYPTION_KEY` (base64-encoded 32 bytes) in the build
-environment so actions embedded in entries written by a previous deploy still
-decrypt; without it they fail until the entry expires or revalidates.
+Deploy note: captured values are encrypted with a key that is generated per
+build by default. Set a stable one in the plugin options:
+
+```ts
+rango({ encryptionKey: process.env.RANGO_ENCRYPTION_KEY });
+```
+
+The value is base64-encoded 32 bytes (`openssl rand -base64 32`), never a
+literal, and is validated when `rango()` is called. `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 server-action bound arguments, so without a stable key those routers get a
+new version (and a cleared cache) on every build, and the build prints one note
+when that applies. With a stable key, actions embedded in entries written by a
+previous deploy still decrypt. A router that renders no inline action with bound
+arguments keeps its cache without a stable key. See `/cache-guide`.
 
 ## Vite Transform
 

package/skills/vercel/SKILL.md

@@ -98,9 +98,7 @@ const memoryStore = new MemorySegmentCacheStore({ defaults });
 // passes, since the tag markers are regional and only expireTag is global. A
 // platform expireTag issued outside rango writes no marker, so every memo
 // serves the shell until its window passes.
-const runtimeCache = process.env.VERCEL
-  ? getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID })
-  : undefined;
+const runtimeCache = process.env.VERCEL ? getCache() : undefined;
 
 function resolveCache() {
   if (runtimeCache) {
@@ -120,6 +118,10 @@ export const router = createRouter({ cache: resolveCache }).routes(/* ... */);
 
 The cache factory receives `(env, ctx)`: on Vercel `env` is `process.env` and `ctx` is `{ waitUntil }`; off-platform `ctx` is `undefined`. Cache semantics and tag invalidation: `/caching`, `/cache-guide`.
 
+`router.prerender()` can warm a route into this store before traffic (`/prerender` → "Warm any route before traffic"). The Runtime Cache is per region, so `VercelCacheStore` declares `scope: "regional"`: a warm fills the region the call runs in. That is all traffic when the project's functions run in one region (the default `iad1` for new projects, and every Hobby project); on a multi-region project it warms one region and the others fill on first use. The router does not detect the region count. The memory store used off-platform above is refused in production and allowed under the dev server.
+
+`getCache()` takes no deployment id: `VercelCacheStore` puts a version in front of every key itself (data version for families `s`, `i`; document version for `r`, `h`; none for tag markers), computed per `createRouter()` from its built code. A deploy that does not change a router keeps its entries; a deploy that changes it reads under new keys. `version` on the store (or on `createRouter`) replaces both versions. To clear the cache on every deploy, set `version` to a per-deploy value or keep a deployment-scoped `getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID })`. Two environments built from the same code share entries if they share a cache namespace; give each its own namespace or `version`.
+
 ## Host routers (multi-app)
 
 A multi-app host router deploys as a **single function** running `hostRouter.match()` for every request (mirrors the Cloudflare single-worker model). Two requirements:

package/skills/view-transitions/SKILL.md

@@ -359,10 +359,15 @@ interface TransitionWhenContext {
   the route or loses its state
   ([#995](https://github.com/rangojs/rango/issues/995)).
 - That holds for every kind, actions and revalidations included: a gated-off
-  action or revalidation commit is urgent too, so a segment it re-renders
-  streams its `loading()`. The router commits an action's result after the
-  response arrives, outside the transition React opens for a form action or
-  `useActionState` call, so React does not hold it either.
+  action or revalidation commit is urgent and unanimated too, and a segment it
+  re-renders shows its `loading()` only while something in it is still pending
+  (a gated-off navigation whose data is still streaming shows it; an action
+  whose response already carries the data does not in a production build,
+  while the dev server still shows it briefly because it resolves each
+  response's client components asynchronously). The router commits an
+  action's result after the response arrives, outside the transition React
+  opens for a form action or `useActionState` call, so React does not hold it
+  either.
 - A predicate that throws counts as `false` and is logged with
   `console.error` (the conservative default: no hold).
 - Intercept (modal) commits skip the evaluation, including a back/forward

package/src/bin/rango.ts

@@ -76,7 +76,7 @@ if (command === "generate") {
 Modes:
   (default)   Static parser with error on unresolvable includes
   --runtime   Vite-based runtime discovery (100% coverage)
-              Requires vite and @vitejs/plugin-rsc
+              Requires vite
   --static    Static parser, accept partial output with warnings
 
 Options: