@rangojs/router 0.20.0 → 0.21.0

package/skills/testing/client-components.md

@@ -2,7 +2,7 @@
 
 **Layer:** unit (DOM) · **Import:** `@rangojs/router/testing/dom` · **DSL it tests:** a client component reading router context (see `/hooks`)
 
-`renderRoute(routes, options?)` is an RTL-style stub (peer of React Router's `createRoutesStub` / Expo's `renderRouter`), and it is async — `await` it. It mounts the router's REAL `NavigationProvider` plus a synthetic segment tree built from the `routes` you pass, so client hooks resolve against production context — no server, no Vite build, no Flight round-trip. Loader data, location state, and handle output are SEEDED into client context; nothing is executed.
+`renderRoute(routes, options?)` is an RTL-style stub (peer of React Router's `createRoutesStub` / Expo's `renderRouter`), and it is async — `await` it. It mounts the router's REAL `NavigationProvider` plus a synthetic segment tree built from the `routes` you pass, so client hooks resolve against production context — no server, no Vite build, no Flight round-trip. Loader data, location state, and handle output are SEEDED into client context; nothing is executed. With `hydrate: true` it renders that same tree to HTML first and hydrates it ([Hydration](#hydration)).
 
 ## API
 
@@ -15,8 +15,9 @@
 | `outletPending`   | `boolean`                                                              | Seed `useOutlet().pending` through each synthetic segment's production `OutletProvider`. Defaults to `false`; this is context seeding, not a simulated navigation/Suspense/action lifecycle.                                                  |
 | `loaders`         | `ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>`             | Seed by REFERENCE: `[loader, data]` pairs. Robust for real `createLoader()` handles whose `$$id` is empty in a bare test. Prefer over `loaderData`.                                                                                           |
 | `params`          | `Record<string, string>`                                               | Explicit params, merged over (and overriding) params extracted from the `request` URL.                                                                                                                                                        |
-| `locationState`   | `ReadonlyArray<readonly [LocationStateDefinition<any, any>, unknown]>` | Seed `useLocationState(def)` by REFERENCE: `[def, value]` pairs; keys an unkeyed `def` (like `withLocationStateKey(def)`) and writes to `history.state`. See [Location state](#location-state).                                               |
+| `locationState`   | `ReadonlyArray<readonly [LocationStateDefinition<any, any>, unknown]>` | Seed `useLocationState(def)` by REFERENCE: `[def, value]` pairs; keys an unkeyed `def` (like `withLocationStateKey(def)`) and writes `value` to `history.state` under `def.__rsc_ls_key`. See [Location state](#location-state).              |
 | `handles`         | `ReadonlyArray<readonly [Handle<any, any>, unknown[]]>`                | Seed `useHandle(handle)` by REFERENCE: `[handle, pushedValues[]]`. Accumulated GLOBALLY (not segment-scoped).                                                                                                                                 |
+| `lateHandles`     | `ReadonlyArray<readonly [Handle<any, any>, unknown[]]>`                | Handle values that arrive AFTER hydration, as a late loader push does: `[handle, valuesAfterTheUpdate[]]` replaces that handle's `handles` seed once the root has hydrated (or mounted). See [Hydration](#hydration).                         |
 | `handle`          | `HandleDataSeed`                                                       | Advanced: raw wire format `{ [handleId]: { [segmentId]: pushedValues[] } }`. Prefer `handles`. Merged with it.                                                                                                                                |
 | `routeMap`        | `Record<string, string>`                                               | Name -> pattern map (informational; client `useReverse` takes its map as an argument, so this is not consumed).                                                                                                                               |
 | `basename`        | `string`                                                               | `createRouter({ basename })` value. Wired into `NavigationProvider` so `useRouter().basename`, `<Link>` prefixing, `useMount`/`useHref` resolve against the mount. Normalized like `createRouter`. Defaults to root.                          |
@@ -24,6 +25,7 @@
 | `theme`           | `ThemeConfig \| true`                                                  | Theme config (`createRouter({ theme })` shape) to wrap the tree in a `ThemeProvider`. Defaults to no provider. A component calling `useTheme()` REQUIRES one.                                                                                 |
 | `nonce`           | `string`                                                               | CSP nonce to seed via `NonceContext`, so a component calling `useNonce()` (e.g. an analytics/GTM head script) sees it — mirroring SSR. Defaults to `undefined` (the browser default).                                                         |
 | `defaultPrefetch` | `PrefetchStrategy`                                                     | Router default for `<Link>` and eligible plain anchors. `data-prefetch="false"`/`"none"` opts out one anchor; ancestor `data-prefetch-scope="false"`/`"none"` hard-disables the subtree; `"true"` permits routed resource suffixes elsewhere. |
+| `hydrate`         | `boolean`                                                              | Render the same tree to HTML first (`renderToString`, no `window`/`document`), then hydrate that HTML instead of mounting fresh. The result gains `serverHtml` and `recoverableErrors`. See [Hydration](#hydration).                          |
 
 `RenderRouteSpec = { path, Component, layout?, loaderIds?, name?, transition? }` — one node of the route definition. The array is the layout chain root-to-leaf; the LAST entry is the leaf route (its pattern is matched against `request` to extract params; layout patterns are informational). `loaderIds` attaches seeded loaders to THIS node's segment; `layout` on the leaf wraps it; `name` is informational. `transition` is the `transition()` config this node declares (`{}` for a bare `transition()`), attached to its segment exactly as the DSL does — see [Held navigation](#held-navigation).
 
@@ -41,7 +43,7 @@
 | `useSearchParams`              | Search params from the `request` URL.                                                         |
 | `useNonce`                     | SEEDED CSP nonce (`options.nonce`), else `undefined` (the browser default).                   |
 | `useLoader` / `useFetchLoader` | SEEDED loader data (read path, not run path). Held-navigation `isLoading` is modeled (below). |
-| `useLocationState`             | SEEDED `history.state` value, or the `state` a push/replace/`<Link>` wrote (below).           |
+| `useLocationState`             | SEEDED `history.state` value, or the `state` a navigation or a `popstate` brought (below).    |
 | `useHandle`                    | SEEDED handle output (globally accumulated).                                                  |
 | `Outlet`                       | Renders the next segment in the chain (layout nesting).                                       |
 | `useOutlet`                    | Next-segment `content` plus SEEDED `options.outletPending`.                                   |
@@ -55,12 +57,16 @@ Extends RTL's `RenderResult` (`getByTestId`, `getByText`, `getByRole`, `containe
 type RenderRouteResult = RenderResult & {
   router: {
     // client-only nav, re-resolves the same routes; `loaders` seeds THIS nav.
-    // A spec's transition({ when }) decides it as kind "push";
-    // `transition: false` commits urgently and calls no predicate.
+    // A spec's transition({ when }) decides it as kind "push" ("replace" with
+    // `replace`); `transition: false` commits urgently and calls no predicate.
+    // `state` / `replace` write the history entry as router.push(url, { state })
+    // / router.replace do; without either, history.state is left alone.
     navigate(
       url: string,
       options?: {
         loaders?: ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>;
+        state?: HistoryState;
+        replace?: boolean;
         transition?: boolean;
       },
     ): Promise<void>;
@@ -73,6 +79,12 @@ type RenderRouteResult = RenderResult & {
     eventController: EventController; // advanced
   };
 };
+
+// With `hydrate: true` (see Hydration):
+type RenderRouteHydrateResult = RenderRouteResult & {
+  serverHtml: string; // what the server pass rendered, as placed in the container
+  recoverableErrors: string[]; // messages React passed to onRecoverableError (live)
+};
 ```
 
 ## Recipe
@@ -128,7 +140,11 @@ A `createLocationState()` definition gets its key from the rango Vite plugin, wh
 - `withLocationStateKey(GridState)` keeps a key that is already set, else assigns a synthetic `__rsc_ls_test_<n>` that stays the same for that definition.
 - The `locationState` seed option keys an unkeyed definition the same way, so a seeded definition needs no call. Key every definition a component reads WITHOUT a seed.
 
-A `useRouter().push/replace(url, { state })` or `<Link state>` navigation writes its history entry through production's path (`resolveNavigationState` -> `buildHistoryState` -> `pushHistoryWithIdx`, then the `__rsc_locationstate` event), so `useLocationState(Def)` re-reads after the click. The dev check for a bare entry or an uncalled definition runs too, and, as in production, a push or `<Link>` without `state` starts an entry with no location state. The URL in `window.location` does not change (renderRoute tracks location on its event controller), and `router.navigate()` from the test leaves `history.state` alone. The click starts an async navigation, so wait for the result with RTL's `waitFor`:
+`useLocationState` reads the entry the router's provider has on screen, so a component that calls it is tested through `renderRoute`; rendered bare (RTL's `render`) it has no entry and reads `undefined`.
+
+A `useRouter().push/replace(url, { state })` or `<Link state>` navigation writes its history entry through production's path (`resolveNavigationState` -> `buildHistoryState` -> `pushHistoryWithIdx`, then the entry's state committed on the event controller), and the provider hands it to readers with the navigation's tree, so `useLocationState(Def)` shows the new value in the commit that shows the destination. The dev check for a bare entry or an uncalled definition runs too, and, as in production, a push or `<Link>` without `state` starts an entry with no location state. The URL in `window.location` does not change (renderRoute tracks location on its event controller).
+
+`router.navigate()` from the test writes a history entry only when asked: `state` pushes an entry carrying it, `replace: true` replaces the current entry (with `state`, or with none, which drops the entry's location state as a production replace does). With neither, history is left alone and readers keep what they show, so `navigate(url)` and `navigate(url, { replace: false })` are the same call. The click starts an async navigation, so wait for the result with RTL's `waitFor`:
 
 ```tsx
 // @vitest-environment happy-dom
@@ -155,6 +171,175 @@ it("shows the count it pushed", async () => {
 });
 ```
 
+### State while a navigation is pending
+
+A reader gets an entry's state in the commit that shows that entry (see `/hooks`, state.md, "When a reader sees an entry's state"). To test a component across a pending navigation, hold the navigation's loader: put `transition` on the spec (see [Held navigation](#held-navigation)) and pass `state` together with a PENDING loader seed to `router.navigate()`:
+
+```tsx
+it("lists no product twice while the next page loads", async () => {
+  const { getAllByRole, router } = await renderRoute(
+    [{ path: "/products", Component: ProductList, transition: {} }],
+    {
+      request: "/products?page=1",
+      loaders: [[ProductsLoader, { page: 1, products: [wine] }]],
+    },
+  );
+
+  let land!: (data: { page: number; products: Product[] }) => void;
+  const next = new Promise<{ page: number; products: Product[] }>(
+    (resolve) => (land = resolve),
+  );
+  await router.navigate("/products?page=2", {
+    state: [CarriedProducts([wine])], // what "Load more" carries
+    loaders: [[ProductsLoader, next]],
+  });
+  // History is on page 2's entry; the list is still page 1's.
+  expect(CarriedProducts.read()).toEqual([wine]);
+  expect(getAllByRole("listitem")).toHaveLength(1);
+
+  await act(async () => land({ page: 2, products: [beer] }));
+  expect(getAllByRole("listitem")).toHaveLength(2);
+});
+```
+
+| To bring state to a reader                          | Do                                                                                                                                                                                                                                           |
+| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| a push / replace, the component's own               | click its `<Link state>` or the control that calls `router.push(url, { state })`, then `waitFor`                                                                                                                                             |
+| a push / replace whose loader the test holds        | `router.navigate(url, { state, replace?, loaders: [[Loader, pendingPromise]] })` on a `transition` spec                                                                                                                                      |
+| back/forward onto an entry                          | `history.replaceState(entry, "")`, then `window.dispatchEvent(new Event("popstate"))` inside `act`. The tree has one location, so no page is restored: readers take the entry as history holds it (also how a `Def.write()` becomes visible) |
+| a reader that mounts while a navigation is pending  | hold the navigation as in the row above, then mount the reader inside `await act(async () => { ... })`: it reads the entry on screen                                                                                                         |
+| a server action's state, a redirect's, an intercept | e2e                                                                                                                                                                                                                                          |
+
+### Definitions with `clearOnReload`
+
+The option never changes the stored value. It changes the key: it appends `~r` to the name you key the definition with (`__rsc_ls_CarriedProducts~r`, see `/hooks`, state.md). So a seed is the plain value for every definition, and a stored-state assertion uses `[CarriedProducts.__rsc_ls_key]` instead of spelling the key.
+
+| To test                                         | Do                                                                                                                                                                                 |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `clearOnReload` state after a client navigation | plain `renderRoute(routes, { locationState })`: the tree mounts as during a navigation, the seed is applied                                                                        |
+| `clearOnReload` state after a refresh           | `renderRoute(routes, { hydrate: true, locationState })`: a document load of the seeded entry. The slot is removed before hydration, by the same function production start-up calls |
+
+In the browser the router also drops location state another app version wrote (see `/hooks`, state.md). A test has no app version, so there is nothing to set up: seeds read back on a mount and on a `hydrate: true` load, and nothing in `window.history.state` or in a server primitive's `locationState` names a version.
+
+A name passed to `withLocationStateKey` may not contain `~`; the definition appends its own suffix.
+
+```tsx
+// @vitest-environment happy-dom
+import { afterEach, expect, it } from "vitest";
+import { cleanup, fireEvent, waitFor } from "@testing-library/react";
+import { renderRoute } from "@rangojs/router/testing/dom";
+import { ProductList } from "../src/components/ProductList"; // the "load more" list of /hooks state.md: useLoader(ProductsLoader) + useLocationState(CarriedProducts)
+import { ProductsLoader } from "../src/loaders";
+import { CarriedProducts } from "../src/location-states"; // createLocationState<Product[]>({ clearOnReload: true })
+
+afterEach(cleanup);
+const routes = [{ path: "/products", Component: ProductList }];
+const carried = [{ id: "p1", name: "Wine" }];
+const loaders = [[ProductsLoader, { page: 6, products: [] }]] as const; // this page's own products: none, to count only carried ones
+
+it("shows the carried products after a client navigation", async () => {
+  const { getAllByRole } = await renderRoute(routes, {
+    loaders,
+    locationState: [[CarriedProducts, carried]],
+  });
+  expect(getAllByRole("listitem")).toHaveLength(1);
+});
+
+it("drops them on a refresh and carries again on the next navigation", async () => {
+  const { recoverableErrors, queryAllByRole, getByText } = await renderRoute(
+    routes,
+    { loaders, hydrate: true, locationState: [[CarriedProducts, carried]] },
+  );
+  expect(recoverableErrors).toEqual([]);
+  expect(queryAllByRole("listitem")).toHaveLength(0);
+  expect(CarriedProducts.read()).toBeUndefined(); // removed from history.state
+
+  fireEvent.click(getByText("Load more"));
+  await waitFor(() => expect(CarriedProducts.read()).toBeDefined());
+});
+```
+
+## Hydration
+
+A plain `renderRoute` mounts with `createRoot`, so a component never runs its hydration render: `useSyncExternalStore` skips `getServerSnapshot`, and nothing compares the first client render with server HTML. `hydrate: true` runs the document-load sequence instead. renderRoute renders the same element (same providers, seeds, and RTL `reactStrictMode`) to HTML with `react-dom/server`'s `renderToString`, puts that HTML in the container, and hydrates it through RTL (`render(ui, { hydrate: true, onRecoverableError })`), so `cleanup()` unmounts it like any other render. `serverHtml` is what the server pass produced; `recoverableErrors` holds the message of every error React recovered from, which is where a hydration mismatch arrives.
+
+```tsx
+// @vitest-environment happy-dom
+import { Suspense } from "react";
+import { afterEach, expect, it } from "vitest";
+import { cleanup } from "@testing-library/react";
+import { renderRoute } from "@rangojs/router/testing/dom";
+import { Grid } from "../src/components/Grid"; // <p data-testid="count">{useLocationState(GridState)?.count ?? 0}</p>
+import { GridState } from "../src/location-states";
+
+afterEach(cleanup);
+
+// A <Suspense> boundary hydrates after the root has marked the page hydrated,
+// as a streamed boundary does in production.
+function GridPage() {
+  return (
+    <Suspense fallback={null}>
+      <Grid />
+    </Suspense>
+  );
+}
+
+it("hydrates as the server rendered it, then shows the stored count", async () => {
+  const { serverHtml, recoverableErrors, getByTestId } = await renderRoute(
+    [{ path: "/grid", Component: GridPage }],
+    { hydrate: true, locationState: [[GridState, { count: 3 }]] },
+  );
+  expect(serverHtml).toContain('<p data-testid="count">0</p>'); // no history.state on the server
+  expect(recoverableErrors).toEqual([]); // the first client render matched it
+  expect(getByTestId("count").textContent).toBe("3"); // then the stored value
+});
+```
+
+| In your component                                                                     | Under `hydrate: true`                                                                                                                                                                                                                        |
+| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `typeof window` / `typeof document` in render                                         | `"undefined"` in the server pass: both globals are removed for it and restored before hydration. A branch renders its server side; if the client side differs, React reports the mismatch.                                                   |
+| An unguarded `window.x` / `document.x` in render                                      | Throws `ReferenceError` in the server pass, as in SSR. Inside a `<Suspense>` the boundary is client-rendered and reported; outside one `renderRoute` rejects.                                                                                |
+| `useSyncExternalStore`                                                                | The server pass and the hydration render read `getServerSnapshot`; the render after it reads `getSnapshot`.                                                                                                                                  |
+| A text or element mismatch                                                            | React re-renders that tree on the client and reports it: `recoverableErrors` gets `"Hydration failed because ..."` with the diff.                                                                                                            |
+| An attribute-only mismatch (`className`, `href`)                                      | NOT in `recoverableErrors`. React keeps the server attribute and logs `console.error` in development; assert it with `vi.spyOn(console, "error")`.                                                                                           |
+| `<Suspense>` whose content renders synchronously                                      | In `serverHtml`. It hydrates in a later pass than the tree above it, after that tree's effects, before `renderRoute` resolves.                                                                                                               |
+| Content that suspends in the server pass (`lazy`, a pending or plain `use()` promise) | NOT hydrated: `serverHtml` has the fallback, the client renders the content, and `recoverableErrors` reports the boundary. With no `<Suspense>` above it `renderRoute` rejects. A settled promise (Caveats, below) stays in the server HTML. |
+| Render counts and module state                                                        | Every component renders once in the server pass before its hydration render. Both passes share one module realm, so module state written while rendering is still there at hydration.                                                        |
+| `history`, `localStorage`, `navigator` read outside a server snapshot                 | FIDELITY LIMIT: still defined in the server pass (only `window` and `document` are removed), so the read renders the same in both passes here and can still mismatch in real SSR.                                                            |
+| `data-hydrated` on `<html>`                                                           | Set after hydration, as the production root sets it from its effect, and removed on unmount. A `<Suspense>` boundary therefore hydrates with it already set.                                                                                 |
+| `useHandle` with `lateHandles`                                                        | The `handles` values in the server pass and in every hydration render, a `<Suspense>` boundary's included; the `lateHandles` values on the render after.                                                                                     |
+| `useLocationState` of a seeded definition                                             | `undefined` in the server pass and the hydration render, the seeded value on the render after. A `clearOnReload` definition stays `undefined`: its seeded slot is removed from `history.state` before hydration, as on a real document load. |
+
+A handle value can reach the page after hydration: a loader push made after an `await`, or any loader push on a PPR shell HIT (`/ppr`, "Handles on a shell HIT"). `lateHandles` models it. The server HTML is rendered from `handles`; the update is applied once the root has hydrated, so a reader inside a `<Suspense>` hydrates after it arrived, as a streamed boundary does in production:
+
+```tsx
+function NotesPage() {
+  return (
+    <Suspense fallback={null}>
+      <NoteList /> {/* <li> per useHandle(Notes) value */}
+    </Suspense>
+  );
+}
+
+it("hydrates with the document's notes, then shows the late one", async () => {
+  const { serverHtml, recoverableErrors, getAllByRole } = await renderRoute(
+    [{ path: "/notes", Component: NotesPage }],
+    {
+      hydrate: true,
+      handles: [[Notes, ["from-handler"]]],
+      lateHandles: [[Notes, ["from-handler", "from-loader"]]],
+    },
+  );
+  expect(serverHtml).not.toContain("from-loader");
+  expect(recoverableErrors).toEqual([]); // useHandle hydrated with the document's data
+  expect(getAllByRole("listitem")).toHaveLength(2);
+});
+```
+
+- Needs `@testing-library/react` 16.2.0 or newer. 16.0 and 16.1 never pass `onRecoverableError` to `hydrateRoot`, so a mismatch would be invisible; `renderRoute` throws there instead.
+- `recoverableErrors` is live: React appends to it for as long as the root is mounted.
+- The server pass is the HTML render of the CLIENT tree. It runs no handler, loader, middleware, or Flight, and it is not the streamed document: streaming order, client-reference identity, and the browser's HTML parser stay at e2e.
+
 ## Held navigation
 
 A stale indicator driven by `useLoader().isLoading` (see `/hooks` data.md, "A held navigation flags the data it keeps on screen") IS unit-testable. Put `transition` on the spec that declares `transition()` in your `urls()`, and pass the next navigation's loader data to `router.navigate(url, { loaders })` as a PENDING Promise. navigate() then commits through production's `commitInTransition` (browser/partial-update.ts), which calls `loaderStore.announcePendingStreams` inside the `startTransition`. The harness does not fake the flag: React holds the reader on screen and the real `useLoader` pin reports `isLoading: true` until the promise settles.
@@ -205,7 +390,7 @@ it("dims the held price while the next product streams", async () => {
 
 ## Caveats
 
-- Client tree ONLY. Does NOT catch server/client boundary reference-identity remount bugs, real Flight serialization errors, loader execution, middleware, or handler ordering — those are `renderServerTree` / `renderHandler` / e2e territory. Loader data is SEEDED, never run.
+- Client tree ONLY. Does NOT catch server/client boundary reference-identity remount bugs, real Flight serialization errors, loader execution, middleware, or handler ordering — those are `renderServerTree` / `renderHandler` / e2e territory. Loader data is SEEDED, never run. `hydrate: true` adds an HTML pass of this same client tree ([Hydration](#hydration)), not a render of your routes on a server.
 - `router.navigate()` bypasses the navigation lifecycle, so the controller never leaves `idle`. `useNavigation()` / `useLinkStatus()` / `useAction()` non-idle states (loading/streaming/pending, action result/error) are NOT reachable — test those at e2e. The one modeled pending state is held-navigation `useLoader().isLoading` ([Held navigation](#held-navigation)).
 - `outletPending` seeds only the production-shaped outlet context. It is useful
   for the two settled render states of a layout that reads `useOutlet()`, but it
@@ -215,7 +400,7 @@ it("dims the held price while the next product streams", async () => {
 - ARIA gotcha — an explicit `role` on a `<Link>` (e.g. `<Link role="tab">` in a tablist) OVERRIDES the implicit `link` role, so `getByRole("link")` finds nothing. Query the explicit role (`getByRole("tab")`) or fall back to `getByText` / `getByTestId` and assert `getAttribute("href")`.
 - `useTheme()` throws unless `theme` is passed (it needs the `ThemeProvider` that option mounts). Search state comes only from the `request` URL — there is no typed-search seed here (that is `runLoader`'s `searchData`).
 - Use `mount` only for an `include()` prefix. An OPTIONAL param in the matched pattern (`/:locale?/c/:group` at `/en/c/wine`) auto-fills `locale` from the match — production parity, `useReverse` merges `useParams()` — so no `mount` is needed; a locale "dropping" from a reversed URL is usually a missing `mount` seed, not an auto-fill gap.
-- Needs a DOM env (`// @vitest-environment happy-dom`, or jsdom) and `@testing-library/react` (optional peers).
+- Needs a DOM env (`// @vitest-environment happy-dom`, or jsdom) and `@testing-library/react` (optional peers; `hydrate` needs 16.2.0 or newer).
 - Don't hand-roll a `NavigationProvider`/router-context mock to test a client component — `renderRoute` mounts the REAL provider, so a hand-mock both duplicates effort and drifts from the production context shape.
 - MULTI-APP `href` typing. When a `renderRoute` suite imports client components across apps, the global `Rango.GeneratedRouteMap` augmentations collide and `href()` stops typechecking (app A's route union rejects app B's name). Runtime is unaffected — it is purely the global `href` typing. Keep the suite single-app, or split tsconfig programs per app (see [`./reverse-and-types.md`](./reverse-and-types.md) and `/typesafety`).
 

package/skills/testing/handles.md

@@ -28,6 +28,8 @@ A handle's `collect`/accumulator (the `createHandle(collect)` argument that maps
 | --------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `handles` | `ReadonlyArray<readonly [Handle, unknown[]]>` | Seeds the CLIENT read path for `useHandle(handle)` — the RAW **pushed values array** (`unknown[]`), the values a route's handlers would have pushed. Attached to the leaf route segment under the handle's `$$id`, so `useHandle` runs the handle's REAL collect on them. |
 
+`lateHandles` takes the same pairs for values that arrive after hydration (a late loader push): each replaces that handle's `handles` seed once the root has hydrated or mounted. With `hydrate: true` it pins that a reader hydrates with the document's values; see [`./client-components.md`](./client-components.md), "Hydration".
+
 **Shape contrast:** `renderRoute` feeds the barrier INPUT (the pushes, `unknown[]`); `runLoader` feeds its OUTPUT (the single accumulated value, `unknown`).
 
 **Across navigation:** seeded `handles` are applied once at the initial render and PERSIST across `router.navigate()` within the same test (like `loaderData`) — unlike a real navigation, which re-runs handlers. A layout/page reading `useHandle` still resolves the seeded values after `navigate()`.

package/skills/testing/loader.md

@@ -121,7 +121,7 @@ it("asserts a loader's set-cookie + redirect (runLoaderResult)", async () => {
 - A loader has no `isAction()`: whether it re-runs after an action is decided by `revalidate()` on its registration, not inside the loader body. Assert post-action re-runs at e2e.
 - Seeded `loaders` (by-reference tuples) are NOT executed — `ctx.use(OtherLoader)` returns the seeded value. The dynamic `use` resolver, by contrast, IS executed (it is a function called to compute the value). Either way the REAL loader body is not run; real loader execution and side-effects are e2e-only. `loaders` is checked before the `use` resolver.
 - A `createLoader()` definition imported through the CLIENT build has its body dropped — `runLoader` throws a clear error pointing to the `rangoTestConfig()` preset or the raw body. A router using `Prerender()`/`createLoader()`/`Static()` now constructs in a bare test (each assigns a runtime fallback `$$id`); only the whole router _file_ may still need the plugin (its page modules pull app deps / `virtual:` modules).
-- Location state needs a key: a `createLocationState()` definition gets it from the Vite plugin, which a test project does not run. In the node project (`NODE_ENV` is not `production`) an unkeyed `Flash(value)` throws, so a loader's `throw redirect(url, { state: [Flash(value)] })` surfaces on `runLoaderResult`'s `thrown` as that missing-key error, not the redirect; in the react-server project (`NODE_ENV=production`) the value lands on `locationState["undefined"]`. Call `withLocationStateKey(Flash, "Flash")` from `@rangojs/router/testing` once per definition and assert `locationState` as `{ __rsc_ls_Flash: value }` (the helper adds the `__rsc_ls_` prefix).
+- Location state needs a key: a `createLocationState()` definition gets it from the Vite plugin, which a test project does not run. In the node project (`NODE_ENV` is not `production`) an unkeyed `Flash(value)` throws, so a loader's `throw redirect(url, { state: [Flash(value)] })` surfaces on `runLoaderResult`'s `thrown` as that missing-key error, not the redirect; in the react-server project (`NODE_ENV=production`) the value lands on `locationState["undefined"]`. Call `withLocationStateKey(Flash, "Flash")` from `@rangojs/router/testing` once per definition and assert `locationState` as `{ __rsc_ls_Flash: value }` (the helper adds the `__rsc_ls_` prefix). A definition with `clearOnReload` appends a suffix to its key (`__rsc_ls_Flash~r`), so `{ [Flash.__rsc_ls_key]: value }` is the form that holds for any definition.
 - No `cookies`/`headers` option: seed a cookie by passing a full Request with a Cookie header — `{ request: new Request(url, { headers: { Cookie: "sid=abc" } }) }`. (`search`/`method` are baked onto this request for you.)
 - `ctx.search` (typed) defaults to `{}`; `opts.search` only sets the raw `ctx.searchParams`. Seed the typed object with `searchData`. (The harness seeds `searchData` verbatim — it does NOT run a typed-search SCHEMA, so schema parsing/validation is e2e.)
 - `ctx.theme`/`ctx.setTheme` are NOT on the loader context — they are handler/middleware-only. The `theme` option seeds the request context's theme config, so a loader body reads the visitor's theme with `getRequestContext().theme` (seed the cookie through `request`). That read is guarded like `cookies()` (#971): allowed in a loader body, but it throws inside a `"use cache"` function. `ctx.request.headers` is guarded the same way. `redirect()` does no basename prefixing unless you seed `basename`.

package/skills/testing/middleware.md

@@ -95,7 +95,7 @@ Pass an array to run several in order. Cookies set inside middleware via the sta
 - A COMPONENT route's guard stack cannot be exercised through `dispatch` (it throws on component routes), and `renderToFlightString`/`renderRoute` don't run route middleware. Extract the middleware fn and unit-test it here, or assert the guard stack at e2e.
 - Middleware-phase `ctx.reverse` is map-only (global names only, no auto-fill from current params), matching production — enable it with `routeMap`. `routeName` only feeds `ctx.routeName`; it does NOT scope `.name` reverse (the chain reverse stays map-only by design, and `MiddlewareContext["reverse"]` rejects `.name` at compile time).
 - `ctx.theme` is `undefined` unless `theme` is passed; `redirect()` does no basename prefixing unless `basename` is seeded.
-- Location state needs a key: a `createLocationState()` definition gets it from the Vite plugin, which a test project does not run, and outside production an unkeyed `Flash(value)` throws inside the middleware (before `redirect()` or `ctx.setLocationState()` runs). Call `withLocationStateKey(Flash, "Flash")` from `@rangojs/router/testing` once per definition and assert `locationState` as `{ __rsc_ls_Flash: value }` (the helper adds the `__rsc_ls_` prefix).
+- Location state needs a key: a `createLocationState()` definition gets it from the Vite plugin, which a test project does not run, and outside production an unkeyed `Flash(value)` throws inside the middleware (before `redirect()` or `ctx.setLocationState()` runs). Call `withLocationStateKey(Flash, "Flash")` from `@rangojs/router/testing` once per definition and assert `locationState` as `{ __rsc_ls_Flash: value }` (the helper adds the `__rsc_ls_` prefix). A definition with `clearOnReload` appends a suffix to its key (`__rsc_ls_Flash~r`), so `{ [Flash.__rsc_ls_key]: value }` is the form that holds for any definition.
 - Platform bindings are yours to double via `env` (see `./bindings.md`).
 
 ## See also

package/skills/testing/render-handler.md

@@ -8,23 +8,23 @@ A Rango route handler is a pure function `(ctx) => rsc` — the function you pas
 
 ### Options — `RenderHandlerOptions`
 
-| Field                  | Type                                                   | Meaning                                                                                                                                                                                                                                                                                                                                                                              |
-| ---------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `params`               | `Record<string, string>`                               | Route params surfaced as `ctx.params`.                                                                                                                                                                                                                                                                                                                                               |
-| `env`                  | `TEnv`                                                 | Environment bindings surfaced as `ctx.env`.                                                                                                                                                                                                                                                                                                                                          |
-| `request`              | `Request \| string`                                    | Backing Request (string or `Request`); defaults to a localhost GET.                                                                                                                                                                                                                                                                                                                  |
-| `headers`              | `HeadersInit`                                          | Request headers (e.g. `Cookie`) the handler reads via `cookies()`. Used only when `request` is a string or omitted; a passed `Request` keeps its own headers.                                                                                                                                                                                                                        |
-| `build`                | `boolean`                                              | Seed `ctx.build` (default `false`) to test a handler that branches on the build-time pass, including calling `ctx.dynamic()` on a miss. Assert the opt-out via `result.dynamic`.                                                                                                                                                                                                     |
-| `theme`                | `ThemeConfig \| true`                                  | Theme config (`createRouter({ theme })` shape). Without it `ctx.theme`/`ctx.setTheme` are inert; pass one to test a handler that reads the theme or writes the theme cookie.                                                                                                                                                                                                         |
-| `vars`                 | `VarsInit` (object or `[[Var, value]]` tuples)         | Variables a prior middleware set, read via `ctx.get(...)`.                                                                                                                                                                                                                                                                                                                           |
-| `routeName`            | `string`                                               | Matched route name (drives `ctx.routeName` and scoped reverse).                                                                                                                                                                                                                                                                                                                      |
-| `routeMap`             | `Record<string, string>`                               | Route name -> pattern map enabling `ctx.reverse()`.                                                                                                                                                                                                                                                                                                                                  |
-| `loaders`              | `ReadonlyArray<readonly [LoaderDefinition, unknown]>`  | Seed the data `ctx.use(SomeLoader)` returns. Matched by loader reference; NO real loader runs.                                                                                                                                                                                                                                                                                       |
-| `clientComponents`     | `Record<string, unknown>`                              | `"use client"` components in the handler's RSC, so they serialize as real boundaries when `rangoUseClientTransform()` is not wired. Keyed by name.                                                                                                                                                                                                                                   |
-| `stateCookie`          | `StateCookieSeed` (`{ prefix?, routerId?, version? }`) | Customize the rango state cookie a handler calling `invalidateClientCache()` rotates. The name is ALWAYS seeded (default `rango-state_router_0`) so the rotation `Set-Cookie` fires like production rather than no-opping; override `prefix`/`routerId` to match your `createRouter({ stateCookiePrefix, id })`, or `version` (the value is `{version}:{timestamp}`, default `"0"`). |
-| `cacheStore`           | `SegmentCacheStore`                                    | Segment cache store backing a `"use cache"` function the handler invokes (e.g. `new MemorySegmentCacheStore()`). WITHOUT it, `registerCachedFunction` takes the uncached bypass and the cached path is NOT exercised (the runtime emits a one-time warning under the test runner). Pair with `cacheProfiles`.                                                                        |
-| `cacheProfiles`        | `Record<string, CacheProfile>`                         | Cache profiles in the `createRouter({ cacheProfiles })` shape, required for `"use cache: profileName"` resolution once a `cacheStore` is wired.                                                                                                                                                                                                                                      |
-| `inActionRevalidation` | `boolean`                                              | Render as if inside a server action's revalidation render (production sets this in `revalidateAfterAction`). A stale `"use cache"` entry whose profile sets `foregroundOnAction: true` then re-executes in the FOREGROUND (fresh result in this render) instead of SWR. Pair with `cacheStore` + `cacheProfiles` to exercise the opt-in.                                             |
+| Field                  | Type                                                   | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| ---------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `params`               | `Record<string, string>`                               | Route params surfaced as `ctx.params`.                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `env`                  | `TEnv`                                                 | Environment bindings surfaced as `ctx.env`.                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `request`              | `Request \| string`                                    | Backing Request (string or `Request`); defaults to a localhost GET.                                                                                                                                                                                                                                                                                                                                                                                  |
+| `headers`              | `HeadersInit`                                          | Request headers (e.g. `Cookie`) the handler reads via `cookies()`. Used only when `request` is a string or omitted; a passed `Request` keeps its own headers.                                                                                                                                                                                                                                                                                        |
+| `build`                | `boolean`                                              | Seed `ctx.build` (default `false`) to test a handler that branches on the build-time pass, including calling `ctx.dynamic()` on a miss. Assert the opt-out via `result.dynamic`.                                                                                                                                                                                                                                                                     |
+| `theme`                | `ThemeConfig \| true`                                  | Theme config (`createRouter({ theme })` shape). Without it `ctx.theme`/`ctx.setTheme` are inert; pass one to test a handler that reads the theme or writes the theme cookie.                                                                                                                                                                                                                                                                         |
+| `vars`                 | `VarsInit` (object or `[[Var, value]]` tuples)         | Variables a prior middleware set, read via `ctx.get(...)`.                                                                                                                                                                                                                                                                                                                                                                                           |
+| `routeName`            | `string`                                               | Matched route name (drives `ctx.routeName` and scoped reverse).                                                                                                                                                                                                                                                                                                                                                                                      |
+| `routeMap`             | `Record<string, string>`                               | Route name -> pattern map enabling `ctx.reverse()`.                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `loaders`              | `ReadonlyArray<readonly [LoaderDefinition, unknown]>`  | Seed the data `ctx.use(SomeLoader)` returns. Matched by loader reference; NO real loader runs.                                                                                                                                                                                                                                                                                                                                                       |
+| `clientComponents`     | `Record<string, unknown>`                              | `"use client"` components in the handler's RSC, so they serialize as real boundaries when `rangoUseClientTransform()` is not wired. Keyed by name.                                                                                                                                                                                                                                                                                                   |
+| `stateCookie`          | `StateCookieSeed` (`{ prefix?, routerId?, version? }`) | Customize the rango state cookie a handler calling `invalidateClientCache()` rotates. The name is ALWAYS seeded (default `rango-state_router_0`) so the rotation `Set-Cookie` fires like production rather than no-opping; override `prefix`/`routerId` to match your `createRouter({ stateCookiePrefix, id })`, or `version` (the app's version, as `createRouter({ version })` would set it; the value is `{version}:{timestamp}`, default `"0"`). |
+| `cacheStore`           | `SegmentCacheStore`                                    | Segment cache store backing a `"use cache"` function the handler invokes (e.g. `new MemorySegmentCacheStore()`). WITHOUT it, `registerCachedFunction` takes the uncached bypass and the cached path is NOT exercised (the runtime emits a one-time warning under the test runner). Pair with `cacheProfiles`.                                                                                                                                        |
+| `cacheProfiles`        | `Record<string, CacheProfile>`                         | Cache profiles in the `createRouter({ cacheProfiles })` shape, required for `"use cache: profileName"` resolution once a `cacheStore` is wired.                                                                                                                                                                                                                                                                                                      |
+| `inActionRevalidation` | `boolean`                                              | Render as if inside a server action's revalidation render (production sets this in `revalidateAfterAction`). A stale `"use cache"` entry whose profile sets `foregroundOnAction: true` then re-executes in the FOREGROUND (fresh result in this render) instead of SWR. Pair with `cacheStore` + `cacheProfiles` to exercise the opt-in.                                                                                                             |
 
 ### Context — `HandlerContext` (what your handler receives)
 
@@ -159,7 +159,7 @@ Without the plugin, wrap a function yourself with the call the transform emits,
 - An unseeded `ctx.use(loader)` REJECTS with a setup error — seed every dependency via `{ loaders: [[OtherLoader, data]] }`, matched by reference. Loaders are SEEDED, not executed (same as `runLoader`).
 - Same alias requirement as flight tests: without the `@rangojs/router -> index.rsc.ts` alias (see [`./setup.md`](./setup.md)), a handler reading `getRequestContext()`/`cookies()` hits the throwing out-of-react-server stub. `renderHandler` detects this and REJECTS with a setup error naming `rangoTestAliases` (it is not captured on `thrown`).
 - A `throw redirect()` is captured on `thrown` (with `tree` undefined, since it produced a `Response`) — assert on `thrown`/`response`, no try/catch needed.
-- Location state needs a key: a `createLocationState()` definition gets it from the Vite plugin, which a test project does not run. This react-server project runs with `NODE_ENV=production`, so an unkeyed `ctx.setLocationState(Flash(value))` does not throw; the value lands on `locationState["undefined"]`. Call `withLocationStateKey(Flash, "Flash")` from `@rangojs/router/testing` once per definition and assert `{ __rsc_ls_Flash: value }` (the helper adds the `__rsc_ls_` prefix; `{ [Flash.__rsc_ls_key]: value }` works for any key).
+- Location state needs a key: a `createLocationState()` definition gets it from the Vite plugin, which a test project does not run. This react-server project runs with `NODE_ENV=production`, so an unkeyed `ctx.setLocationState(Flash(value))` does not throw; the value lands on `locationState["undefined"]`. Call `withLocationStateKey(Flash, "Flash")` from `@rangojs/router/testing` once per definition and assert `{ __rsc_ls_Flash: value }` (the helper adds the `__rsc_ls_` prefix; `{ [Flash.__rsc_ls_key]: value }` works for any key, including one that carries the `clearOnReload` suffix, `__rsc_ls_Flash~r`).
 - No hydration and no interaction — for clicks, forms, and navigation use e2e.
 - `renderHandler` runs a handler FUNCTION `(ctx) => rsc`; for a plain ELEMENT `<Page/>` use `renderServerTree` (see [`./server-tree.md`](./server-tree.md)).
 - A handler that calls a `"use cache"` function runs UNCACHED unless you seed `cacheStore` (and `cacheProfiles` for a named profile). With nothing seeded the runtime bypasses to the live body and warns once under the test runner. With a store seeded, the body runs once across renders and a render after the background write reads the store — see [A `"use cache"` hit](#a-use-cache-hit), including `rangoUseCacheTransform()`, without which Vitest leaves the directive unwrapped.

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

@@ -27,16 +27,17 @@ 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>`
 
@@ -99,6 +100,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:
@@ -169,12 +199,31 @@ A partial request has no HTML step, so its `key` is the URL's key without a part
 
 ## 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(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
-// The handler pushed ctx.use(Meta)({ title: "Widget - Shop" })
-expect(hit.prelude).toContain('"title":"Widget - Shop"');
-expect(hit.flight).toContain('"title":"Widget - Shop"');
+expect(hit.flight).toContain('"stock":"in stock"');
 ```
 
 ## Caveats

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`).