@rangojs/router 0.31.0 → 0.32.0

package/skills/hooks/state.md

@@ -101,6 +101,7 @@ Back/forward and state the server sets on a navigation
 | `<Link state>`, `router.push()` / `router.replace()`         | in the commit that shows the destination                         |
 | back/forward                                                 | in the commit that restores the entry (cached or refetched)      |
 | the server, on a navigation (`setLocationState`, a redirect) | in the commit that shows the destination                         |
+| the server, on a document load (a page load, a no-JS post)   | once the page has hydrated, as stored state                      |
 | a navigation the server answers with nothing to re-render    | with the new location: the page on screen is the entry's         |
 | `router.push(url, { revalidate: false })` (no server fetch)  | with the new location: the page does not change                  |
 | a server action's `setLocationState` (no navigation)         | when the action's response arrives, added to what readers show   |
@@ -279,8 +280,8 @@ import { FlashMessage } from "../location-states";
 ```
 
 Or via `ctx.setLocationState()` from a handler or middleware. It is delivered
-with a client navigation's or an action's response; a document response
-carries no location state (there is no history entry to write it to yet):
+with a client navigation's or an action's response, and with a document
+response too (see "State on a document response" below):
 
 ```tsx
 (ctx) => {
@@ -289,6 +290,109 @@ carries no location state (there is no history entry to write it to yet):
 };
 ```
 
+### Several writes to one definition
+
+Entries accumulate across definitions, but one definition is one slot in
+`history.state`: for the same definition the last write wins. Two
+`ctx.setLocationState(Toasts(...))` calls in one response, or
+`redirect(url, { state: [Toasts(a), Toasts(b)] })`, deliver only the later
+value, without a warning. A server action, a handler and the middleware
+around them all write to the same response, so a shared helper that writes a
+definition replaces what an earlier call wrote.
+
+To combine several messages, make the state an array and write it once, for
+example by collecting them in a request variable and writing the definition
+at the end of the action:
+
+```ts
+export const Toasts = createLocationState<ToastMessage[]>({ flash: true });
+
+// One write per response, with every toast in it.
+getRequestContext().setLocationState(Toasts([...savedToasts, loginToast]));
+```
+
+### State on a document response
+
+A document request has no history entry yet, so the router carries what the
+server set to the client and writes it there when the client starts. This
+covers the mutations that most need a flash message: a `<form action={fn}>`
+posted before hydration or without JS, a payment provider redirecting the
+shopper back, a link from an email.
+
+| The document request                                                         | Where the state travels                                          |
+| ---------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| renders a page (`setLocationState` in a handler, middleware or no-JS action) | the document's bootstrap payload                                 |
+| redirects (`redirect(url, { state })`, or `setLocationState` and a redirect) | a one-shot cookie the target's document request reads and clears |
+| redirects with `{ external: true }` or off-origin                            | nowhere: the cookie would not reach the target                   |
+
+```tsx
+// A payment provider sends the shopper back to /checkout/callback.
+path("/checkout/callback", async (ctx) => {
+  const ok = await completeOrder(ctx.searchParams.get("token"));
+  return ok
+    ? redirect("/orders/confirmed", { state: [Flash({ text: "Paid" })] })
+    : redirect("/checkout", { state: [Flash({ text: "Payment declined" })] });
+});
+```
+
+- **When a reader gets it.** `useLocationState` returns `undefined` while the
+  document streams and hydrates, then the value, at the moment it would get
+  state stored in the entry. A flash message shows just after hydration.
+- **Without JS, no flash.** The state rides to the client, and only the
+  client writes it into the entry and hands it to readers. A visitor with JS
+  disabled gets the page as the server rendered it, where every reader of the
+  state shows `undefined`: the post and its redirect work, but the message
+  never shows. If such visitors must see it, render it from the server, for
+  example from a search param or a cookie your handler reads.
+- **Flash and refresh.** Flash state is cleared once read, as always. The
+  cookie is cleared by the response that read it, so a refresh of the target
+  renders without it. A page whose handler sets state on every request
+  delivers it again on a refresh, because the handler ran again. A no-JS post
+  answered with a page (no redirect) is re-posted by the browser on refresh;
+  redirect after the post (`redirect(url, { status: 303, state })`) to avoid
+  that.
+- **Caching.** A document that carries state, and the redirect carrying it
+  on, are sent `Cache-Control: private, no-store`, after every middleware.
+  The document cache neither stores such a document nor answers a request
+  that arrives with the cookie from a stored one. A shared PPR shell never
+  holds state: on a `ppr` route, state set before the render (by middleware,
+  or the cookie) rides the live payload of a shell HIT or MISS, and the shell
+  is still served and captured; state a handler sets keeps that route from
+  being captured, so it renders in full. `no-store` also keeps the
+  page out of the browser's back/forward cache (Chrome's bfcache), so Back to
+  it loads it again. That costs little for a one-off flash; a handler that
+  sets state on every request pays it on every page view.
+- **`ppr` and cached routes.** A shell HIT and a `cache()` hit run no
+  handler, so a handler there cannot set state on that request. Set it from
+  middleware, which runs on every request; the HIT still serves, with the
+  state in its live payload.
+- **The cookie.** It is named after the router's state cookie
+  (`<stateCookieName>-ls`, `__Host-` prefixed on https), `HttpOnly`,
+  `SameSite=Lax`, `Path=/`, and lives 60 seconds. Only the next GET document
+  request of the redirect's target pathname that navigates reads it: where
+  the browser sends `Sec-Fetch-Dest`, it must be `document`, `iframe` or
+  `frame`, so a `<link rel=prefetch>` or a `fetch()` of that path leaves it
+  to the navigation. A form POST to it, a client navigation and a Flight
+  fetch leave it too, as does a request of another path. A
+  target that redirects again carries the state on to the next target. There
+  is one such cookie per router: two document redirects within a moment (two
+  tabs) keep only the later one's state. Without https there is no `__Host-`
+  prefix, so a sibling subdomain could set the cookie: treat state that
+  arrives this way as a message to show, not as a fact to act on.
+- **Known limit: a redirect from one router to another.** The cookie is
+  named after the redirecting router's state cookie, which holds its router
+  id (`<stateCookiePrefix>_<routerId>`), and a router reads only its own. On
+  one origin served by several routers (a host router, or several
+  `createRouter()` apps behind one worker), a document redirect from one
+  router to a path another serves loses its state, without a warning. Carry
+  such a message another way, such as a search param.
+- **JSON only across a redirect.** The cookie holds JSON: a `Date` arrives as
+  a string, a `Map` or `Set` as `{}`, `undefined` is dropped. Development
+  warns, naming the slot. A value JSON cannot encode (a `bigint`), or state
+  over the cookie's 4000-byte limit, is dropped from the redirect with a
+  `console.warn`. Carry an id and load the rest on the target page.
+  Navigation and action payloads are not limited this way.
+
 ### State from another deploy
 
 History entries survive reloads and back/forward, so a tab left open across a
@@ -419,10 +523,10 @@ as the server rendered it:
   where it sits (a `<Suspense>` boundary that hydrates late included), or
   whether the definition's module is loaded at all. Other slots on the entry
   are left alone.
-- State the server sets is never dropped by this: a document response carries
-  no location state, and `ctx.setLocationState()` / `redirect(url, { state })`
-  reach `history.state` only through navigations and actions in the running
-  app, after start-up.
+- State the server sets is never dropped by this: the state a document
+  response carries is written after the `~r` keys are removed, so a
+  `clearOnReload` slot the server set for this load is applied on this load
+  (and removed by the next one). Navigations and actions write after start-up.
 - `.write()` stores under the same key, so it does not survive a refresh
   either.
 - Adding the option to an existing definition moves it to the `~r` key: state

package/skills/intercept/SKILL.md

@@ -316,7 +316,8 @@ or not the intercept applies from that page (`rsc-rendering.ts`
 `x-rsc-prefetch-scope: source`, set from `MatchResult.interceptTargeted`). A
 full page prefetched from a page where `when` is false never serves a click
 from a page where it is true. Routes no intercept targets keep one shared
-prefetch entry.
+prefetch entry, unless a `revalidate()` that read the source page kept a
+segment (`MatchResult.sourceHeld`, same header).
 
 ```typescript
 // Intercept only when opened from the shop index

package/skills/ppr/SKILL.md

@@ -500,6 +500,18 @@ Rango warns with the shell key and backs capture off instead of rendering the
 same doomed generation on every request. Move a deterministic self-invalidation
 out of render code if you want the shell to persist.
 
+### Location state on a ppr route
+
+A shared shell never holds location state: the capture builds its own
+payload, without it. State set before the render (from middleware, or the
+one-shot cookie a document redirect left for this request) rides the live
+payload: a HIT serves the shell with the state in its tail's payload, a MISS
+carries it and still captures. Either response leaves `private, no-store`.
+State a handler sets skips the capture of that MISS, so that route renders in
+full: a HIT runs no handler, so a handler's `ctx.setLocationState()` does not
+happen on a HIT. Set it from middleware (see `/hooks` `state.md`, "State on a
+document response").
+
 ### Opting out per request with `ctx.dynamic()`
 
 Middleware and handlers can call `ctx.dynamic()` to force this request onto a

package/skills/server-actions/SKILL.md

@@ -645,6 +645,14 @@ Redirects from actions render the **target** route tree's matched segments
 source page's — the target is what the user sees next. See `/hooks
 useLocationState` for reading flash state on the target page.
 
+The same holds for a form posted without JS (or before hydration): an action
+that redirects with `state` carries it to the target in a one-shot cookie,
+and one that sets it with `getRequestContext().setLocationState()` and does
+not redirect carries it in the re-rendered page. Either way the target reads
+it with `useLocationState` once it has hydrated. Prefer a `303` redirect, so a
+refresh does not post the form again. State that crosses a no-JS redirect
+travels as JSON (see `/hooks` `state.md`, "State on a document response").
+
 Build the target by name rather than a literal path:
 `throw redirect(getRequestContext().reverse("account.settings"))`. It fills
 mount params (`:accountId`, `:locale`) from the page URL the action was called

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).
 
@@ -265,6 +266,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.

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

@@ -30,19 +30,20 @@ A `Prerender` route is served as in production: from the artifact `router.matchF
 
 ### 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/ux-architecture/SKILL.md

@@ -313,9 +313,12 @@ 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`).
+- The default prefetch entry is shared by every source page. When the
+  target's `revalidate()` reads `currentParams`, `currentUrl` or
+  `fromRouteName` and keeps the segment, the router scopes that prefetch to
+  the page that sent it (`x-rsc-prefetch-scope: source`): another page
+  prefetches its own. `prefetchKey=":source"` on the Link scopes every
+  prefetch of it (`src/browser/react/Link.tsx`, `prefetchKey`).
 
 ### 2.7 transition() and view transitions
 

package/src/browser/history-state.ts

@@ -158,8 +158,9 @@ export function stripShellMissMarker(): void {
  * the server rendered this document without them. One pass before hydration
  * (initBrowserApp; renderRoute's `hydrate` mode), so no reader needs to know
  * the page began as a document load, and a slot nobody reads is removed too.
- * No server-set state exists yet to lose: a document response carries none
- * (rsc-rendering.ts attaches it to partial payloads only).
+ * Server-set state is not lost to it: the state a document response carries
+ * is merged after this pass (applyDocumentLocationState), so a `~r` slot the
+ * server set for this load survives this load and no later one.
  *
  * A slot is recognised by its key alone (the `~r` suffix): at start-up the
  * module that defines it may not be loaded.
@@ -185,6 +186,27 @@ export function clearLocationStateOnDocumentLoad(): void {
   if (next) window.history.replaceState(next, "");
 }
 
+/**
+ * Merge the location state a document response carried (its bootstrap
+ * payload's `metadata.locationState`, server/document-location-state.ts)
+ * into the entry the document loaded on. Start-up runs it after
+ * clearLocationStateOnDocumentLoad and the version is set, before the entry
+ * is committed for readers (initBrowserApp; renderRoute's `hydrate` mode),
+ * so readers get it once they have hydrated, as stored state. Only typed
+ * slots are taken.
+ */
+export function applyDocumentLocationState(
+  locationState: Record<string, unknown> | undefined,
+): void {
+  if (!locationState) return;
+  let slots: Record<string, unknown> | undefined;
+  for (const key of Object.keys(locationState)) {
+    if (!isLocationStateKey(key)) continue;
+    (slots ??= {})[key] = locationState[key];
+  }
+  if (slots) mergeLocationState(slots);
+}
+
 /**
  * Merge server-set location state into the current history entry and return
  * the entry state written. Readers see it when the caller commits it

package/src/browser/react/Link.tsx

@@ -110,23 +110,20 @@ export interface LinkProps extends Omit<
    * keyed on Rango state + target URL. This is correct for routes whose
    * response shape doesn't depend on where the user navigates from.
    *
-   * Set `":source"` when this Link's response would legitimately differ
-   * based on the source page — typically when the target route (or one
-   * of its layouts) uses a custom `revalidate()` handler that reads
-   * `currentUrl` / `currentParams`, and the wildcard entry would
-   * therefore serve the wrong diff to a navigation from a different
-   * source.
+   * Set `":source"` to scope every prefetch of this Link to the page that
+   * sent it, when its response would differ by source page in a way the
+   * server cannot see.
    *
-   * A route an intercept targets is scoped to the source automatically
-   * (server-side `x-rsc-prefetch-scope: source`), whether or not the
-   * intercept applies from this page: the modal and the full page are
-   * both source-specific. Every other route stays shared, so `":source"`
-   * is only needed for custom revalidation logic.
+   * The server scopes a prefetch to its source automatically
+   * (`x-rsc-prefetch-scope: source`) when an intercept targets the route,
+   * whether or not it applies from this page (the modal and the full page
+   * are both source-specific), and when a `revalidate()` of the target
+   * read `currentParams`, `currentUrl` or `fromRouteName` and kept the
+   * segment: that diff is the source page's (#1331). Every other response
+   * stays shared.
    *
    * @example
    * ```tsx
-   * // Route uses a `revalidate()` that branches on currentUrl — opt in
-   * // so prefetches don't bleed across source pages.
    * <Link to="/dashboard" prefetch="hover" prefetchKey=":source" />
    * ```
    */

package/src/browser/react/location-state-shared.ts

@@ -462,6 +462,12 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
  * The key is auto-injected by the Vite exposeInternalIds plugin as a property
  * based on file path and export name. No manual key required.
  *
+ * One definition is one slot in `history.state`. Entries of different
+ * definitions accumulate, but for the same definition the last write wins:
+ * two `ctx.setLocationState(Def(...))` calls in one response, or
+ * `redirect(url, { state: [Def(a), Def(b)] })`, deliver only the later
+ * value. To combine writes, make the state an array and write it once.
+ *
  * @param options Optional configuration
  * @returns A typed state definition for use with Link and useLocationState
  *
@@ -675,7 +681,8 @@ export function isLocationStateEntry(
 }
 
 /**
- * Resolve state entries into a flat object for history.state
+ * Resolve state entries into a flat object for history.state. One slot per
+ * definition: a later entry of the same definition replaces an earlier one.
  */
 export function resolveLocationStateEntries(
   entries: LocationStateEntry[],

package/src/browser/rsc-router.tsx

@@ -47,6 +47,7 @@ import {
 import { createAppShellRef } from "./app-shell.js";
 import { bootLog, IS_BROWSER_DEBUG } from "./logging.js";
 import {
+  applyDocumentLocationState,
   clearLocationStateOnDocumentLoad,
   stripShellMissMarker,
 } from "./history-state.js";
@@ -274,8 +275,10 @@ export async function initBrowserApp(
     setSuspenseAuditStreamProbe(() => eventController.getState().isStreaming);
   }
 
-  // The document's entry, after the clearOnReload pass and under the version
-  // set above: what readers get once they have hydrated.
+  // The state the document response carried, after the clearOnReload pass
+  // and under the version set above.
+  applyDocumentLocationState(initialPayload.metadata?.locationState);
+  // The document's entry: what readers get once they have hydrated.
   eventController.commitLocationState(window.history.state);
 
   // Initialize event controller with segment order (even without handles)

package/src/build/runtime-discovery.ts

@@ -37,10 +37,12 @@ export async function discoverAndWriteRouteTypes(
   outputFiles: string[];
 }> {
   let loadConfigFromFile: typeof import("vite").loadConfigFromFile;
+  let resolveConfig: typeof import("vite").resolveConfig;
 
   try {
     const vite = await import("vite");
     loadConfigFromFile = vite.loadConfigFromFile;
+    resolveConfig = vite.resolveConfig;
   } catch {
     throw new Error(
       "Runtime discovery requires 'vite'. Install it with: pnpm add -D vite",
@@ -59,14 +61,19 @@ export async function discoverAndWriteRouteTypes(
   const { createDiscoveryState } = await import("../vite/discovery/state.js");
   const { discoverClientUrlProjections } =
     await import("../vite/discovery/client-urls-projection.js");
-  const { pickForwardedRunnerConfig, selectForwardableResolvePlugins } =
-    await import("../vite/utils/forward-user-plugins.js");
+  const {
+    isFrameworkPlugin,
+    pickForwardedRunnerConfig,
+    selectForwardableResolvePlugins,
+  } = await import("../vite/utils/forward-user-plugins.js");
 
   // The discovery temp server of `vite dev/build` (expose-internal-ids, the
   // cloudflare:* stubs, the user's resolver plugins and resolve/define/oxc).
-  // The config stays unresolved: resolving it would run rango()'s
-  // configResolved, which writes the static gen files. Forwarded resolvers
-  // therefore run without their own config/configResolved hooks.
+  // Resolver plugins are forwarded from a resolved config, as `vite dev` does:
+  // vite-tsconfig-paths and the like build their matchers in config /
+  // configResolved, and resolving drops `apply: "build"` plugins. The
+  // framework plugins are left out of that resolve: rango()'s configResolved
+  // writes the static gen files.
   const entryPath = resolve(opts.entry);
   const state = createDiscoveryState(entryPath, undefined);
   state.projectRoot = opts.root;
@@ -80,9 +87,40 @@ export async function discoverAndWriteRouteTypes(
       );
       if (loaded) {
         state.userRunnerConfig = pickForwardedRunnerConfig(loaded.config);
-        state.userResolvePlugins = selectForwardableResolvePlugins(
-          await flattenPluginOptions(loaded.config.plugins),
-        );
+        const userPlugins = (
+          await flattenPluginOptions(loaded.config.plugins)
+        ).filter((p) => !isFrameworkPlugin(p.name ?? ""));
+        try {
+          // The temp server's root, so a resolver's root-relative state
+          // matches the server it runs in.
+          const resolved = await resolveConfig(
+            {
+              ...loaded.config,
+              root: opts.root,
+              configFile: false,
+              plugins: userPlugins,
+            },
+            "serve",
+            "development",
+          );
+          state.userResolvePlugins = selectForwardableResolvePlugins(
+            resolved.plugins,
+          );
+        } catch (err: any) {
+          console.warn(
+            `[rango] Could not resolve the Vite config (${err?.message ?? err}); forwarding its resolver plugins without their config hooks. rango() and rsc() are left out of that resolve, so a plugin that needs the rsc environment fails there`,
+          );
+          // The resolve would have applied `apply`; do the same for the serve
+          // pass, including the function form.
+          const serveEnv = { command: "serve", mode: "development" } as const;
+          state.userResolvePlugins = selectForwardableResolvePlugins(
+            userPlugins.filter((p) =>
+              typeof p.apply === "function"
+                ? p.apply(loaded.config, serveEnv)
+                : p.apply !== "build",
+            ),
+          );
+        }
       }
     } catch (err: any) {
       // Discovery without the app's resolvers fails later on an unrelated