@rangojs/router 0.31.0 → 0.33.0

package/skills/testing/client-components.md

@@ -8,25 +8,26 @@
 
 ### Options — `RenderRouteOptions`
 
-| Field             | Type                                                                   | Meaning                                                                                                                                                                                                                                       |
-| ----------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `request`         | `Request \| string`                                                    | Initial location. Only the URL is read (client render — headers/method ignored). Defaults to the leaf spec's static prefix or `"/"`.                                                                                                          |
-| `loaderData`      | `Record<string, unknown>`                                              | Loader data keyed by loader `$$id`. `useLoader(L)` reads `loaderData[L.$$id]`.                                                                                                                                                                |
-| `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 `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.                          |
-| `mount`           | `string`                                                               | `include()` mount prefix. Wraps the segment chain in a `MountContext` so `useMount()` returns the prefix. Normalized like a path prefix. Defaults to `"/"`.                                                                                   |
-| `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`, `recoverableErrors` and `shellError`. See [Hydration](#hydration).            |
-| `rewrite`         | `string`                                                               | The path middleware rewrote `request` to (`throw rewrite()`): the leaf is matched against it for params, while the location (`usePathname`, `useSearchParams`) stays `request`, as a rewritten document renders and hydrates.                 |
+| Field                   | Type                                                                   | Meaning                                                                                                                                                                                                                                                                                                      |
+| ----------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `request`               | `Request \| string`                                                    | Initial location. Only the URL is read (client render — headers/method ignored). Defaults to the leaf spec's static prefix or `"/"`.                                                                                                                                                                         |
+| `loaderData`            | `Record<string, unknown>`                                              | Loader data keyed by loader `$$id`. `useLoader(L)` reads `loaderData[L.$$id]`.                                                                                                                                                                                                                               |
+| `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 `value` to `history.state` under `def.__rsc_ls_key`. See [Location state](#location-state).                                                                             |
+| `documentLocationState` | `ReadonlyArray<readonly [LocationStateDefinition<any, any>, unknown]>` | The location state the document response carried (a handler, middleware or no-JS form action set it, or a document redirect's cookie brought it), as `[def, value]` pairs. Merged at start-up after `locationState` and the `clearOnReload` pass. See [State a document carried](#state-a-document-carried). |
+| `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.                                                                                         |
+| `mount`                 | `string`                                                               | `include()` mount prefix. Wraps the segment chain in a `MountContext` so `useMount()` returns the prefix. Normalized like a path prefix. Defaults to `"/"`.                                                                                                                                                  |
+| `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`, `recoverableErrors` and `shellError`. See [Hydration](#hydration).                                                                           |
+| `rewrite`               | `string`                                                               | The path middleware rewrote `request` to (`throw rewrite()`): the leaf is matched against it for params, while the location (`usePathname`, `useSearchParams`) stays `request`, as a rewritten document renders and hydrates.                                                                                |
 
 `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).
 
@@ -78,6 +79,21 @@ type RenderRouteResult = RenderResult & {
     // re-render the current location, as router.refresh() does:
     // a spec's when gets kind "revalidate" (`to` is `from`)
     refresh(): Promise<void>;
+    // keep `url` as a prefetch made now carries it (the seeds then, `loaders`
+    // over them); a later navigate(url) without `loaders` commits that data
+    prefetch(
+      url: string,
+      options?: {
+        loaders?: ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>;
+      },
+    ): void;
+    // land a server action's response: `loaders` are the post-write values,
+    // the page on screen re-renders with them, and (without keepClientCache)
+    // every history entry and prefetch is marked stale
+    action(options?: {
+      loaders?: ReadonlyArray<readonly [LoaderDefinition<any>, unknown]>;
+      keepClientCache?: boolean;
+    }): Promise<void>;
     pathname(): string;
     params(): Record<string, string>;
     store: NavigationStore; // advanced
@@ -265,6 +281,30 @@ it("drops them on a refresh and carries again on the next navigation", async ()
 });
 ```
 
+### State a document carried
+
+A page load, a no-JS form post that renders a page, and the target of a document redirect carry the location state the server set for them (see `/hooks`, state.md, "State on a document response"). Start-up merges it into the entry after the `clearOnReload` pass, so a reader gets it once the root has hydrated, `clearOnReload` slots included. Seed it with `documentLocationState`, not `locationState`: `locationState` is the entry's stored state, which `hydrate: true` passes through the `clearOnReload` pass first.
+
+| To test                                                    | Do                                                                                                                |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| a flash a document carried, as the page hydrates           | `renderRoute(routes, { hydrate: true, documentLocationState })`                                                   |
+| a document's `clearOnReload` state replacing a stale entry | `hydrate: true` with the stale value in `locationState`, the new one in `documentLocationState`                   |
+| what the server put in the document                        | `serveShellRequest(router, url).readLocationState()` (see [`./serve-shell-request.md`](./serve-shell-request.md)) |
+
+```tsx
+it("shows the flash the declined-payment redirect carried", async () => {
+  const { serverHtml, getByRole } = await renderRoute(
+    [{ path: "/checkout", Component: FlashBanner }],
+    {
+      hydrate: true,
+      documentLocationState: [[FlashMessage, { text: "Payment declined" }]],
+    },
+  );
+  expect(serverHtml).not.toContain("Payment declined"); // useLocationState is undefined until hydration
+  expect(getByRole("alert")).toHaveTextContent("Payment declined");
+});
+```
+
 ## 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.
@@ -395,19 +435,20 @@ it("dims the held price while the next product streams", async () => {
 });
 ```
 
-| Pending state                                                                                  | Under `renderRoute`                                                                                                                                                                                                  |
-| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `useLoader().isLoading` on the reader a `transition` navigate() holds, pending seed            | Modeled: `true` on the OLD data until the promise settles, then `false` with the new data in the same commit.                                                                                                        |
-| `transition` navigate(), settled seed (a plain value)                                          | `false`; the data swaps in the commit.                                                                                                                                                                               |
-| navigate() without `transition`, pending seed                                                  | Urgent commit (production's cold-navigation lane): the read suspends to the nearest `<Suspense>` fallback (with none, React keeps the previous tree). No flag.                                                       |
-| `transition: { when }` returning false, or `navigate(url, { transition: false })`              | Same as without `transition`: urgent, with production's decision (`kind: "push"`; `refresh()` is `"revalidate"`). `transition: false` calls no predicate.                                                            |
-| Production's other hold lanes (same-structure search/filter nav, fully-prefetched, optimistic) | NOT modeled — without `transition` navigate() stays urgent. Assert those at e2e.                                                                                                                                     |
-| `useNavigation().state`, `useLinkStatus().pending`                                             | Modeled: navigate() starts the navigation as a click does. `loading` from the call, `idle` in the commit, held with it; `pending` true for the destination's link until that commit, held with it too.               |
-| `useAction().state`                                                                            | Stays `idle`: navigate() runs no action. e2e.                                                                                                                                                                        |
-| `useHandle()` on a held navigation, `navigate(url, { handles, loaders })`                      | Modeled: `handles` arrive on the response's handle stream, so readers keep the page being left's values while React holds the page and take the new ones with its commit.                                            |
-| `useNavigation().isStreaming` past the commit, `navigate(url, { streamUntil })`                | Modeled: the stream opens a task after the call (`pendingUrl` clears) and ends when the promise settles or a newer navigation aborts it; settle it inside `await act(async () => ...)`.                              |
-| A navigation started while React holds a page (a newer click, a `transition: false` commit)    | `await router.navigate(...)` shows its page, with or without `act()`. A `<Link>` click goes inside `await act(async () => { ... })`: `fireEvent`'s synchronous `act()` drops React's retry of the held page.         |
-| A back/forward restored from the history cache (`pop`)                                         | Modeled for the mounted entry and one a navigate() wrote: the page and its handle values come back, decided by `transition({ when })` as kind `"pop"`. A stale entry's revalidation and a restore that fetches: e2e. |
+| Pending state                                                                                        | Under `renderRoute`                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useLoader().isLoading` on the reader a `transition` navigate() holds, pending seed                  | Modeled: `true` on the OLD data until the promise settles, then `false` with the new data in the same commit.                                                                                                                                                                                                                                                                                                                             |
+| `transition` navigate(), settled seed (a plain value)                                                | `false`; the data swaps in the commit.                                                                                                                                                                                                                                                                                                                                                                                                    |
+| navigate() without `transition`, pending seed                                                        | Urgent commit (production's cold-navigation lane): the read suspends to the nearest `<Suspense>` fallback (with none, React keeps the previous tree). No flag.                                                                                                                                                                                                                                                                            |
+| `transition: { when }` returning false, or `navigate(url, { transition: false })`                    | Same as without `transition`: urgent, with production's decision (`kind: "push"`; `refresh()` is `"revalidate"`). `transition: false` calls no predicate.                                                                                                                                                                                                                                                                                 |
+| Production's other hold lanes (same-structure search/filter nav, fully-prefetched, optimistic)       | NOT modeled — without `transition` navigate() stays urgent. Assert those at e2e.                                                                                                                                                                                                                                                                                                                                                          |
+| `useNavigation().state`, `useLinkStatus().pending`                                                   | Modeled: navigate() starts the navigation as a click does. `loading` from the call, `idle` in the commit, held with it; `pending` true for the destination's link until that commit, held with it too.                                                                                                                                                                                                                                    |
+| `useAction().state`                                                                                  | Stays `idle`: navigate() runs no action. e2e.                                                                                                                                                                                                                                                                                                                                                                                             |
+| `useHandle()` on a held navigation, `navigate(url, { handles, loaders })`                            | Modeled: `handles` arrive on the response's handle stream, so readers keep the page being left's values while React holds the page and take the new ones with its commit.                                                                                                                                                                                                                                                                 |
+| `useNavigation().isStreaming` past the commit, `navigate(url, { streamUntil })`                      | Modeled: the stream opens a task after the call (`pendingUrl` clears) and ends when the promise settles or a newer navigation aborts it; settle it inside `await act(async () => ...)`.                                                                                                                                                                                                                                                   |
+| A navigation started while React holds a page (a newer click, a `transition: false` commit)          | `await router.navigate(...)` shows its page, with or without `act()`. A `<Link>` click goes inside `await act(async () => { ... })`: `fireEvent`'s synchronous `act()` drops React's retry of the held page.                                                                                                                                                                                                                              |
+| A back/forward restored from the history cache (`pop`)                                               | Modeled for the mounted entry and one a navigate() wrote: the page and its handle values come back, decided by `transition({ when })` as kind `"pop"`. A stale entry's revalidation and a restore that fetches: e2e.                                                                                                                                                                                                                      |
+| A click on a prefetch made before an action, `prefetch(url)`, `action({ loaders })`, `navigate(url)` | Modeled: the click commits the prefetch's data at once; once it settled, the page revalidates in Back's lane with the post-write data (`useNavigation().state` stays `idle`, nothing remounts). `router.revalidations()` lists each revalidation request (its URL and held segment ids), decided by production's guards. `action({ keepClientCache: true })` keeps the prefetch fresh: no revalidation. The prefetch request itself: e2e. |
 
 - Per-navigation seeds merge over the render-time `loaders`/`loaderData` for THAT navigation only; a later `navigate()` without `loaders` falls back to the render-time data.
 - Pass settled data as a plain value, not `Promise.resolve(value)`: React has not observed a plain promise yet, so it counts as pending and renders one `stale` frame. (A Flight chunk that has already settled carries its status and is skipped, which a plain value mirrors.)

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

@@ -20,29 +20,30 @@ A `Prerender` route is served as in production: from the artifact `router.matchF
 
 ### Options — `ServeShellRequestOptions`
 
-| Field        | Type                                                                                                                                                                       | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cacheStore` | `SegmentCacheStore`                                                                                                                                                        | The store for this request, in place of the store your `createRouter({ cache })` config returns. The rest of that config (`enabled`, `searchParams`) still applies. Omit it to use the router's own store.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `env`        | `TEnv`                                                                                                                                                                     | Bindings, as `router.fetch(request, { env })` passes them. A function `cache` config receives them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `headers`    | `HeadersInit`                                                                                                                                                              | Request headers (e.g. `cookie`). A document request defaults `accept` to `text/html`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `partial`    | `true \| { from?: string; rewriteTarget?: string; segments?: string[]; prefetch?: boolean; fill?: boolean; interceptSource?: string; stale?: boolean; boundary?: string }` | Serve the navigation request the browser sends instead of a document GET: from `from` (default the site root) with `segments` mounted (default none). `prefetch: true` sends it as a `<Link>` prefetch (`X-Rango-Prefetch`), so `prefetch: false` work is deferred. `fill: true` sends the follow-up request (`_rsc_fill=1`) the browser makes after adopting a prefetch; pass the prefetch's delivered ids, without the deferred ones, as `segments`, and the same URL as `from`. `interceptSource` sends the intercept source (`X-RSC-Router-Intercept-Source`) the browser sends with the fill of an intercept, whose `from` is that source too. `rewriteTarget` sends what the page at `from` carried as its payload's `metadata.rewriteTarget` when middleware rewrote it (`_rsc_rt`), as the browser does, so the server diffs against the route that rendered that page. `stale: true` sends a stale request (`_rsc_stale`), as the browser sends it: every `revalidate()` sees `stale: true` (see `revalidate()`'s `stale`), segments take an action's revalidation defaults, and it renders live, as an action does: neither the route cache (`cache()`) nor the document cache serves or stores it, and a `ppr` route's `replayStatus` is `{ outcome: "BYPASS", reason: "stale" }`. `boundary` names the error segment of a thrown action's boundary the page at `from` shows (`_rsc_boundary`), as the background revalidation an earlier action owes that page sends it, with `stale: true` and no `segments`: the response renders every segment above the boundary and nothing at or below it, claims the boundary in `matched` and sends no segment for it. The server reads it only beside `stale`. |
-| `action`     | `{ ref: Function; id: string; args?: unknown[]; segments?: string[]; rewriteTarget?: string }`                                                                             | Send the request a JS server action call makes from the page at `url`: a POST of `args` (encoded as the browser encodes them) with `?_rsc_action`, the `rsc-action` header, `X-RSC-Router-Client-Path` and `_rsc_segments` (the page's mounted segment ids, default none), plus the page's `rewriteTarget` as for `partial`. Registers `ref` under `id` (`<module id>#<export name>`). Not with `partial` or `form`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| Field        | Type                                                                                                                                                                       | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cacheStore` | `SegmentCacheStore`                                                                                                                                                        | The store for this request, in place of the store your `createRouter({ cache })` config returns. The rest of that config (`enabled`, `searchParams`) still applies. Omit it to use the router's own store.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `env`        | `TEnv`                                                                                                                                                                     | Bindings, as `router.fetch(request, { env })` passes them. A function `cache` config receives them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `headers`    | `HeadersInit`                                                                                                                                                              | Request headers (e.g. `cookie`). A document request defaults `accept` to `text/html`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `partial`    | `true \| { from?: string; rewriteTarget?: string; segments?: string[]; prefetch?: boolean; fill?: boolean; interceptSource?: string; stale?: boolean; boundary?: string }` | Serve the navigation request the browser sends instead of a document GET: from `from` (default the site root) with `segments` mounted (default none). `prefetch: true` sends the speculative kind a viewport or render `<Link>` prefetch sends (`X-Rango-Prefetch: 1`), so `prefetch: false` work is deferred; add `headers: { "X-Rango-Prefetch": "intent" }` to send a hover's or `prefetch()`'s intent prefetch instead, which defers nothing. `fill: true` sends the follow-up request (`_rsc_fill=1`) the browser makes after adopting a prefetch; pass the prefetch's delivered ids, without the deferred ones, as `segments`, and the same URL as `from`. `interceptSource` sends the intercept source (`X-RSC-Router-Intercept-Source`) the browser sends with the fill of an intercept, whose `from` is that source too. `rewriteTarget` sends what the page at `from` carried as its payload's `metadata.rewriteTarget` when middleware rewrote it (`_rsc_rt`), as the browser does, so the server diffs against the route that rendered that page. `stale: true` sends a stale request (`_rsc_stale`), as the browser sends it: every `revalidate()` sees `stale: true` (see `revalidate()`'s `stale`), segments take an action's revalidation defaults, and it renders live, as an action does: neither the route cache (`cache()`) nor the document cache serves or stores it, and a `ppr` route's `replayStatus` is `{ outcome: "BYPASS", reason: "stale" }`. `boundary` names the error segment of a thrown action's boundary the page at `from` shows (`_rsc_boundary`), as the background revalidation an earlier action owes that page sends it, with `stale: true` and no `segments`: the response renders every segment above the boundary and nothing at or below it, claims the boundary in `matched` and sends no segment for it. The server reads it only beside `stale`. |
+| `action`     | `{ ref: Function; id: string; args?: unknown[]; segments?: string[]; rewriteTarget?: string }`                                                                             | Send the request a JS server action call makes from the page at `url`: a POST of `args` (encoded as the browser encodes them) with `?_rsc_action`, the `rsc-action` header, `X-RSC-Router-Client-Path` and `_rsc_segments` (the page's mounted segment ids, default none), plus the page's `rewriteTarget` as for `partial`. Registers `ref` under `id` (`<module id>#<export name>`). Not with `partial` or `form`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 
 ### 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.                                                |
-| `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.                                                                            |
-| `readDeferred` | `() => Promise<string[] \| undefined>`            | The ids of the segments the payload marks deferred (a prefetch skipped them; the fill renders them), in payload order. `[]` when nothing was deferred, `undefined` when no Flight rendered.                                        |
-| `readAction`   | `() => Promise<ShellRequestAction \| undefined>`  | For an `action` request, the call's answer as the browser reads it: `{ ok, result, revalidationError }` (see "A server action called from the page"). `undefined` when no Flight rendered or the payload carries no action result. |
-| `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.                                                                            |
+| `readDeferred`      | `() => Promise<string[] \| undefined>`                | The ids of the segments the payload marks deferred (a prefetch skipped them; the fill renders them), in payload order. `[]` when nothing was deferred, `undefined` when no Flight rendered.                                        |
+| `readAction`        | `() => Promise<ShellRequestAction \| undefined>`      | For an `action` request, the call's answer as the browser reads it: `{ ok, result, revalidationError }` (see "A server action called from the page"). `undefined` when no Flight rendered or the payload carries no action result. |
+| `readLocationState` | `() => Promise<Record<string, unknown> \| undefined>` | The payload's location state as the browser reads it: `{ [Def.__rsc_ls_key]: value }` (see "Location state on a document"). `undefined` when it carries none or no Flight rendered.                                                |
+| `response`          | `Response`                                            | Status and headers. Its body is already read.                                                                                                                                                                                      |
+| `body`              | `string`                                              | The body text.                                                                                                                                                                                                                     |
 
 ### `resetShellTestState(): Promise<void>`
 
@@ -415,6 +416,30 @@ expect(await result.readPayloadFormState()).toEqual(result.formState);
 - 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.
 
+## Location state on a document
+
+A document carries the location state its handler, middleware or no-JS form action set, in its bootstrap payload; `readLocationState()` reads it as the browser does. A document request that redirects carries its state to the target in a one-shot cookie instead (`Set-Cookie`, `<stateCookieName>-ls`, `__Host-` on https): pass that cookie on the target's request, as the browser does when it follows the redirect, and read what the target's payload carries.
+
+```tsx
+const redirected = await serveShellRequest(router, "/payment/callback");
+const setCookie = redirected.response.headers
+  .getSetCookie()
+  .find((c) => /-ls=/.test(c.split(";")[0]!))!;
+
+const target = await serveShellRequest(router, "/checkout", {
+  headers: { cookie: setCookie.split(";")[0]!, "sec-fetch-dest": "document" },
+});
+expect(await target.readLocationState()).toEqual({
+  [FlashMessage.__rsc_ls_key]: { text: "Payment declined" },
+});
+expect(target.response.headers.get("cache-control")).toBe("private, no-store");
+```
+
+- Only a GET document request of the target's pathname reads the cookie, and clears it (`Max-Age=0` on its response). Where the request sends `Sec-Fetch-Dest`, it must be `document`, `iframe` or `frame`: a prefetch or `fetch()` (`empty`) leaves the cookie to the navigation. Without the header the request counts as a navigation.
+- A document that carries state, and the redirect carrying it on, leave `Cache-Control: private, no-store`; the document cache neither stores nor serves them. On a `ppr` route, state set before its handler ran, by middleware or a redirect's cookie, rides the live payload: the request is still a `MISS` that captures or a `HIT`, and `prelude` holds none of it. State its handler sets keeps the route from being stored as a shell (`readEntry()` is null).
+- For a `form` request, the re-rendered document carries what the action set; a redirecting action carries it in the cookie, as above.
+- What a reader shows is client-side: seed it with `renderRoute({ hydrate: true, documentLocationState })` (see [`./client-components.md`](./client-components.md)).
+
 ## A server action called from the page
 
 `serveShellRequest(router, url, { action: { ref, id, args, segments } })` sends the request a JS server action call makes from the page at `url`, as `browser/server-action-bridge.ts` sends it: a POST of `args` with `?_rsc_action`, the `rsc-action` header, `X-RSC-Router-Client-Path` and `_rsc_segments`. `ref` is registered under `id` (`<module id>#<export name>`, any unique string of that shape in a test) so the handler loads it by id. The response is the action's Flight payload: its return value and the segments it re-rendered, `flight` as for any other request. Pass the segment ids the page holds as `segments`, so the request has segments to revalidate; without them the server holds none. Read them from the `metadata.matched` of a `partial` request's payload (`flight`), as in "Testing `prefetch: false`" above.

package/skills/testing/server-actions.md

@@ -53,6 +53,14 @@
 | `stateCookieName` | `string`                  | The resolved rango state cookie name this run seeded (default `rango-state_router_0`). Assert an `invalidateClientCache()` rotation against it without recomputing.                               |
 | `locationState`   | `Record<string, unknown>` | The flash set via `ctx.setLocationState()` / `redirect({ state })`, as the flat `{ key: value }` the client reads.                                                                                |
 
+`runInRequestContext` runs your function, not the router's action handling,
+so its `response` carries no write bump: the router sets that around every
+action it runs (the state cookie's `{version}:{timestamp}:{write}`, write part
+bumped unless the action called `keepClientCache()`). To assert it, send the
+action through the router with `serveShellRequest(router, url, { action })`
+(or `{ form }` with `createActionForm` for a post before hydration) and read
+the state `Set-Cookie` on `result.response`.
+
 Low-level building blocks (all from `@rangojs/router/testing`):
 
 - `createTestRequestContext(opts)` builds the context WITHOUT entering it and returns `{ ctx, request, url, variables, stateCookieName }`. Its `ctx.reverse` accepts any name from your `routeMap`.

package/skills/ux-architecture/SKILL.md

@@ -249,6 +249,13 @@ them right:
   server").
 - A prefetch runs the predicates too, so a loader that holds costs nothing in
   the prefetch of a tab switch.
+- A predicate that reads `currentParams` or `fromRouteName` and keeps its
+  segment shares that prefetch only between the pages with equal values of
+  what it read; one that reads `currentUrl` makes it page-only (2.6).
+  `bySlug` keeps only on an unchanged slug, so a product's tabs share their
+  prefetches; `bySearch` reads the URL, so the cost is the links between one
+  query's tabs. A layout rule comparing a param most pages share (a locale,
+  an account) groups by that param and keeps the sharing.
 - Unit-test them with `runRevalidate` (`/testing`).
 
 ### 2.5 loading() or an inline Suspense
@@ -279,8 +286,14 @@ A prefetch is a navigation sent early: the server renders the destination's
 handlers and loaders for it, from the page you are on (`/links`, "What a
 prefetch renders"). A click that adopts a complete prefetch commits with no
 request. Entries live 300 s by default (`prefetchCacheTTL`) in the router's
-memory only (prefetch responses carry no `Cache-Control`), and an action
-drops them unless it calls `keepClientCache()`. A prefetch whose page failed
+memory. An action marks them stale unless it calls `keepClientCache()`: a
+click on one shows it at once, then revalidates the page in the background
+(`/server-actions`, "Client Cache After an Action"). The browser HTTP cache
+keeps a prefetch for as long only when nothing in it is live: a document cache
+HIT, or an answer whose every sent segment came from a `cache()` record or a
+Prerender entry and that runs no loader
+(`Cache-Control: private, max-age=<prefetchCacheTTL>`). Any other prefetch
+carries no `Cache-Control` of the router's. A prefetch whose page failed
 is never used: a 500 or 404, and a 200 whose render reported an error (a
 loader that threw, a `loading()` handler that fell back to its
 `errorBoundary()`, an async component that threw). The click sends its own
@@ -301,11 +314,16 @@ The rule: **prefetch broadly, and flag what is expensive.**
   already on screen whose `revalidate()` re-runs it for the destination is
   prefetched with it, so the click does not wait on a fill for data the page
   is already showing.
-- The trade-off, measured on a `clientUrls()` tab in a consumer app (dev, a
-  loaded machine): with the tab's loader flagged, a hover then a click 150 ms
+- `prefetch: false` applies to speculative prefetches: viewport and render.
+  A hover, or `useRouter().prefetch()`, is intent to click and runs the
+  loader, so its click needs no fill. A hover over a link a viewport prefetch
+  already answered sends nothing, and that click still fills.
+- The trade-off of a deferring prefetch, measured on a `clientUrls()` tab in
+  a consumer app (dev, a loaded machine), before a hover's prefetch ran
+  flagged loaders: with the tab's loader flagged, a hover then a click 150 ms
   later showed the content in 843 to 918 ms; with the tab prefetched whole, in
   77 to 157 ms. The flagged click pays the fill request and then React's
-  300 ms on the tab's fallback.
+  300 ms on the tab's fallback. A viewport-prefetched link still pays it.
 - A click that adopts a prefetch with a flagged loader shows the page at once
   and sends one fill request for the flagged loaders. Read a flagged loader
   under its own `<Suspense>`: with no boundary, React keeps the page being
@@ -313,9 +331,33 @@ The rule: **prefetch broadly, and flag what is expensive.**
 - On a server route, `loading(fallback, { prefetch: false })` keeps the whole
   entry behind that fallback out of the prefetch (`/route`, "`loading()`
   options"). A group's `loading()` takes no options.
-- When the target's `revalidate()` reads `currentUrl` or `currentParams`, give
-  the Link `prefetchKey=":source"`: the default prefetch entry is shared by
-  every source page (`src/browser/react/Link.tsx`, `prefetchKey`).
+- One prefetch of a page serves every page that links to it, so a paginated list
+  or a grid does not prefetch each link again after every navigation. The server
+  makes an answer page-only (`x-rsc-prefetch-scope: source`) when sharing it
+  would be wrong: an intercept targets the route or the page sending it, the
+  answer defers a `prefetch: false` unit the page does not show yet, a
+  `revalidate()` on the target read `currentUrl` and kept its segment, a rule
+  on the route (or inside its `path()`) read the page being left and kept the
+  segment through the route's default, or a kept answer sends no segment at
+  all. Only a click from that exact URL, query
+  and hash included, uses a page-only answer, so every page prefetches it
+  again (`/links`, "Shared prefetches and `prefetchKey`").
+- A `revalidate()` that read `currentParams` or `fromRouteName` and kept its
+  segment, or a prerendered target reached from a page with the same route
+  params, groups the answer (`x-rsc-prefetch-scope: params; <label>`): the
+  pages with equal values of what was read share it. A layout rule comparing
+  `currentParams.locale` shares each prefetch between the pages of one locale.
+  Spreading `currentParams` reads every param; read the ones the rule needs by
+  name. A page's own block (a category hero) still goes in its route or in a
+  layout inside its `path()`, and links that follow a mount param come from
+  `useReverse`; neither needs a rule (`/app-structure`, "Prefetches are
+  shared").
+- `prefetchKey=":source"` on a Link, or
+  `router.prefetch(url, { key: ":source" })`, makes that link's prefetches
+  page-only. Use it when the target's answer depends on the page through
+  something the server does not track: `context` in a `revalidate()`, or a
+  `Referer` read. It costs the same requests, so set it per link, not
+  app-wide.
 
 ### 2.7 transition() and view transitions
 
@@ -372,16 +414,16 @@ The rule: **prefetch broadly, and flag what is expensive.**
   the error to the nearest error boundary, which replaces the page and its
   form (`/client-urls`, "A loader that fails on its rerun").
 - `keepClientCache()` in an action that changed nothing keeps the prefetches
-  and the history cache.
+  and the history cache fresh: no revalidation after a click or on Back.
 - `useOptimistic` gives feedback before the action answers.
 
 ### 2.10 Updates you did not make: three channels
 
-| The change                                         | The tool                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Your own mutation                                  | A server action plus `revalidate()` rules (`isAction(ref)`, `actionResult`). The server re-runs what the action touched in the same response; nothing else to call.                                                                                                                                                                                                                                                                                                                           |
-| Out of band: a push, polling, a REST call, a login | `useLoader(L).load()` (also `refetch`): a plain `load()` of a route-registered loader updates every reader of it. `refreshGroup` on reads plus `useRefreshLoaders()` refreshes several loaders at once. Both need a fetchable loader, `createLoader(fn, true)`; a plain one answers 403. `router.refresh()` re-renders the current route's server data and keeps client state. `invalidateClientCache()` marks the history cache stale and drops prefetches when the change makes them wrong. |
-| Shared server caches (other users' data)           | Tags: `cache({ tags })` or `cacheTag()`, then `updateTag()` in the action (awaitable, the action's response reads fresh) or `revalidateTag()` from a webhook. `revalidate()` is not cache invalidation (`/cache-guide`).                                                                                                                                                                                                                                                                      |
+| The change                                         | The tool                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Your own mutation                                  | A server action plus `revalidate()` rules (`isAction(ref)`, `actionResult`). The server re-runs what the action touched in the same response; nothing else to call.                                                                                                                                                                                                                                                                                                                                              |
+| Out of band: a push, polling, a REST call, a login | `useLoader(L).load()` (also `refetch`): a plain `load()` of a route-registered loader updates every reader of it. `refreshGroup` on reads plus `useRefreshLoaders()` refreshes several loaders at once. Both need a fetchable loader, `createLoader(fn, true)`; a plain one answers 403. `router.refresh()` re-renders the current route's server data and keeps client state. `invalidateClientCache()` marks the history cache stale, drops prefetches and rotates the state when the change makes them wrong. |
+| Shared server caches (other users' data)           | Tags: `cache({ tags })` or `cacheTag()`, then `updateTag()` in the action (awaitable, the action's response reads fresh) or `revalidateTag()` from a webhook. `revalidate()` is not cache invalidation (`/cache-guide`).                                                                                                                                                                                                                                                                                         |
 
 ### 2.11 Handles: titles and breadcrumbs
 
@@ -445,7 +487,7 @@ ctx.reverse(".product", { slug: "b", locale: "de" }); // switch language
   take unchecked path strings: prefer the typed `useReverse` map.
 - `useReverse` with another module's map, or `useReverse(NamedRoutes)` under
   a mount, gives a wrong URL with no error. Build cross-module links on the
-  server and pass them as props or loader data (dc-t57).
+  server and pass them as props or loader data.
 - A server layout stays held across navigations, its own `:projectId`
   changing included: partial rendering by design. Links it rendered keep the
   old params. Put param-dependent nav links in a client component with
@@ -926,6 +968,16 @@ Each entry: what the user sees, why, the fix.
 15. **An effect keyed on a location-state object.** In a group the object is
     the one the navigation passed until the commit, then the history entry's
     copy: the effect runs twice. Fix: key it on a primitive field.
+16. **A page's own block in a shared layout, kept by a rule that reads the
+    page being left** (a category hero in a template over the product pages,
+    re-rendered when `currentParams.category` changes). Nothing looks wrong,
+    but every prefetch under that layout is shared only between the pages of
+    one category (or with the same params, off the category routes): the
+    other pages prefetch their links again and the server renders them
+    again. Fix: put
+    the block in its route, or in a layout inside its `path()`; it
+    re-renders on its own params with no rule (`/app-structure`, "Prefetches
+    are shared").
 
 ## 5. Known gaps