@rangojs/router 0.21.0 → 0.22.1

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     |

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/testing/SKILL.md

@@ -115,6 +115,7 @@ Each primitive links to its sub-file (API + recipe + caveats).
 | 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)   |
@@ -158,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();
 });
 ```

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`
@@ -41,7 +43,7 @@ So `prelude` is the shell as captured (Flight text, not HTML): a value the shell
 
 ### `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
 
@@ -164,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();
 ```
 
@@ -179,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"]),
 );
 ```
 
@@ -189,14 +194,33 @@ 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
 
 `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[] } }`):
@@ -226,6 +250,78 @@ Loader data has no decoder: it rides the payload, so assert it as text in `prelu
 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:
@@ -241,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/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)
 

package/skills/vercel/SKILL.md

@@ -118,6 +118,8 @@ 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)

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/browser/event-controller.ts

@@ -142,6 +142,16 @@ export interface HandleState {
   routeSegmentIds: string[];
 }
 
+/**
+ * What the document's HTML was rendered with, kept for the hydration window
+ * (EventController.lockHydration).
+ */
+export interface HydrationSnapshot {
+  state: DerivedNavigationState;
+  params: Record<string, string>;
+  handles: HandleState;
+}
+
 /**
  * Result from starting a navigation
  * Implements Disposable for use with `using` keyword
@@ -263,22 +273,30 @@ export interface EventController {
   ): void;
   getHandleState(): HandleState;
   /**
-   * Keep the current handle state as the one the document's HTML was rendered
-   * with. initBrowserApp calls it before hydrateRoot, once the document's
-   * handle snapshot is applied.
+   * Open the hydration window. Until releaseHydrationLock(), getHandleState()
+   * returns the state the document's HTML was rendered with, and handle writes
+   * (setHandleData, setRouteSegmentIds) wait in order. initBrowserApp opens it
+   * before hydrateRoot, once the document's handle snapshot is applied: a hook
+   * reading the handle state when its boundary hydrates, however late, reads
+   * what SSR rendered (issue #1035).
    */
-  freezeHydrationHandleState(): void;
+  lockHydration(): void;
   /**
-   * The handle state the document's HTML was rendered with, once the live
-   * state has moved on from it; undefined while the live state is still that
-   * state (nothing changed since the freeze, or nothing was frozen: a tree
-   * that was mounted, an SSR pass). A render React is hydrating reads it
-   * (useHandle), whenever its boundary hydrates: the late handle channel
-   * (rsc-router.tsx) waits for the root to hydrate, not for a `<Suspense>`
-   * boundary that hydrates after it, and by then the live state can hold
-   * values that boundary's HTML does not (issue #1035).
+   * While the hydration window is open, the state the document's HTML was
+   * rendered with; undefined once it closes. A router hook's first render
+   * reads it: a component hydrating in a boundary that streamed in late
+   * renders what SSR rendered, even after a navigation or an action started.
+   * The hook's effect then catches up with the live state, and its
+   * subscription stays live, so pending UI is not held back.
    */
-  getHydrationHandleState(): HandleState | undefined;
+  getHydrationSnapshot(): HydrationSnapshot | undefined;
+  /**
+   * Close the hydration window: apply the writes that waited, in order, and
+   * notify handle subscribers. NavigationProvider calls it after the commit
+   * that made React hydrate every boundary still dehydrated (its barrier).
+   * Idempotent.
+   */
+  releaseHydrationLock(): void;
   /**
    * Update ONLY `routeSegmentIds` (what `useSegments` reads) from `matched`,
    * leaving `data` and `segmentOrder` (what `useHandle` collects over) untouched.
@@ -498,8 +516,10 @@ export function createEventController(
   let handleData: HandleData = {};
   let handleSegmentOrder: string[] = [];
   let routeSegmentIds: string[] = [];
-  // freezeHydrationHandleState: what the document's HTML was rendered with.
-  let hydrationHandleState: HandleState | undefined;
+  // The hydration window (lockHydration): what the document's HTML was
+  // rendered with, and the handle writes waiting for its release.
+  let hydrationSnapshot: HydrationSnapshot | undefined;
+  let writesAfterHydration: (() => void)[] = [];
 
   let routeParams: Record<string, string> = {};
 
@@ -1028,6 +1048,12 @@ export function createEventController(
     isPartial?: boolean,
     resolvedIds?: string[],
   ): void {
+    if (hydrationSnapshot) {
+      writesAfterHydration.push(() =>
+        setHandleData(data, matched, isPartial, resolvedIds),
+      );
+      return;
+    }
     const rawMatched = matched ?? [];
     const newSegmentOrder = filterSegmentOrder(rawMatched);
     // Separate list for useSegments(): "layouts and routes only" — strip
@@ -1036,9 +1062,8 @@ export function createEventController(
 
     if (isPartial && newSegmentOrder.length > 0) {
       // Partial update: merge new data with existing, into a copy of the
-      // containers. The object a reader was handed is never written to: the
-      // hydration snapshot (freezeHydrationHandleState) and a history entry
-      // restored from the store's cache can be that object.
+      // containers. The object a reader was handed is never written to: a
+      // history entry restored from the store's cache can be that object.
       handleData = cloneHandleData(handleData);
       for (const handleName of Object.keys(data)) {
         if (!handleData[handleName]) {
@@ -1076,6 +1101,7 @@ export function createEventController(
   }
 
   function getHandleState(): HandleState {
+    if (hydrationSnapshot) return hydrationSnapshot.handles;
     return {
       data: handleData,
       segmentOrder: handleSegmentOrder,
@@ -1083,7 +1109,29 @@ export function createEventController(
     };
   }
 
+  function lockHydration(): void {
+    if (hydrationSnapshot) return;
+    hydrationSnapshot = {
+      state: getState(),
+      params: routeParams,
+      handles: getHandleState(),
+    };
+  }
+
+  function releaseHydrationLock(): void {
+    if (!hydrationSnapshot) return;
+    hydrationSnapshot = undefined;
+    const writes = writesAfterHydration;
+    writesAfterHydration = [];
+    for (const write of writes) write();
+    notifyHandles.flush();
+  }
+
   function setRouteSegmentIds(matched: string[]): void {
+    if (hydrationSnapshot) {
+      writesAfterHydration.push(() => setRouteSegmentIds(matched));
+      return;
+    }
     const next = filterRouteSegmentIds(matched);
     if (
       next.length === routeSegmentIds.length &&
@@ -1177,13 +1225,9 @@ export function createEventController(
     // Handles
     setHandleData,
     getHandleState,
-    freezeHydrationHandleState: () => {
-      hydrationHandleState = getHandleState();
-    },
-    getHydrationHandleState: () =>
-      hydrationHandleState?.data === handleData
-        ? undefined
-        : hydrationHandleState,
+    lockHydration,
+    getHydrationSnapshot: () => hydrationSnapshot,
+    releaseHydrationLock,
     setRouteSegmentIds,
 
     // Params

package/src/browser/link-interceptor.ts

@@ -4,7 +4,7 @@ import {
   type EventController,
 } from "./event-controller.js";
 import {
-  getDefaultPrefetchStrategy,
+  ENVIRONMENT_DEFAULT_PREFETCH,
   resolveAdaptiveStrategy,
   subscribeToAdaptiveStrategyChange,
 } from "./prefetch/default-strategy.js";
@@ -383,7 +383,7 @@ export function setupDelegatedLinkPrefetch(
   options: DelegatedPrefetchOptions,
 ): () => void {
   const defaultStrategy =
-    options.defaultPrefetch ?? getDefaultPrefetchStrategy();
+    options.defaultPrefetch ?? ENVIRONMENT_DEFAULT_PREFETCH;
   if (defaultStrategy === "none") return () => {};
 
   const basename = canonicalizeBasenamePathname(options.basename);