@rangojs/router 0.31.0 → 0.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -259,7 +259,7 @@
     "node": ">=24.0.0"
   },
   "scripts": {
-    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js && mkdir -p dist/bin/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/bin/plugins/cloudflare-protocol-loader-hook.mjs",
+    "build": "pnpm run build:types && pnpm exec esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm exec esbuild src/testing/vitest.ts --bundle --format=esm --outfile=dist/testing/vitest.js --platform=node --packages=external && rm -rf dist/bin && pnpm exec esbuild src/bin/rango.ts --bundle --format=esm --splitting --outdir=dist/bin --platform=node --packages=external && chmod +x dist/bin/rango.js && mkdir -p dist/bin/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/bin/plugins/cloudflare-protocol-loader-hook.mjs",
     "build:types": "rm -rf dist/types && pnpm exec tsc -p tsconfig.types.json",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
     "test": "playwright test",

package/skills/app-structure/SKILL.md

@@ -112,6 +112,14 @@ here for the rules they share.
    keeps the visitor's URL. A loader, handler or server action
    cannot rewrite, and a loop answers 508. Redirect when the new URL should
    show (`/middleware`, "Rewrite").
+9. **Keep prefetches shared.** One prefetch of a page serves every page
+   that links to it. A `revalidate()` that reads the page being left and
+   keeps its segment shares those prefetches only between the pages with
+   equal values of what it read (`currentParams.locale`: the pages of one
+   locale); one that reads `currentUrl` makes them page-only. Read params
+   by name, keep page-specific blocks in their route, and write such a rule
+   for chrome that shows a param's data
+   ([Prefetches are shared](#prefetches-are-shared)).
 
 ## A small app: one module
 
@@ -217,6 +225,72 @@ name a route alike. One unnamed level in the root module is fine.
 For where boundaries and `revalidate()` rules go inside that chrome so
 navigations stay smooth, see the `ux-architecture` skill.
 
+## Prefetches are shared
+
+In production every visible `<Link>` prefetches its page, and one prefetch
+of a page serves every page that links to it: a product prefetched on the
+home page is not fetched again on the search page or on page 2 of a list
+(`/links` → "Shared prefetches and `prefetchKey`"). A structure keeps that
+sharing as long as no segment's answer depends on the page being left.
+
+The default rules keep it: a standalone layout is held from every page that
+shows it, and a route re-renders when its params or search change. A
+`revalidate()` that reads the page being left and keeps its segment narrows
+it to what the rule read. A rule that reads `currentParams` or
+`fromRouteName` shares the answer between the pages with equal values of
+those reads (the params a rule reads by name, every param when it spreads
+`currentParams`, the route name for `fromRouteName`; the page's set of params
+always counts). A rule that reads `currentUrl` makes it page-only: the server
+stores the answer for the exact page that sent it, query string and hash
+included, and each page prefetches those links again. The answer stays
+correct; what is lost is the sharing.
+
+| What you are placing                                                                                                                               | Put it in                                                                    | Prefetches                                                                                                                                          |
+| -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A block that belongs to one page (a category's hero, a product's breadcrumb)                                                                       | that page's route: its handler, or a layout inside its `path()` (below)      | Shared. It re-renders with its route on a param or search change. In a layout other pages share it would need a rule that reads the page being left |
+| Links that follow a mount param (`:locale`, `:accountId`, `:projectId`)                                                                            | a client component with `useReverse(routes)` (rule 7)                        | Shared. The links follow `useParams()`, and the layout stays held with no rule                                                                      |
+| Chrome that shows a param's data (the locale's messages, a project's name)                                                                         | the layout, with a `revalidate()` comparing `currentParams` and `nextParams` | Shared between the pages with the same value of that param where the rule keeps the layout (the pages of one locale or one project)                 |
+| A page whose answer depends on the page that sent it through something the server cannot see (`context` in a `revalidate()`, the `Referer` header) | `prefetchKey=":source"` on the links to it                                   | Page-only, for those links                                                                                                                          |
+
+The third row is the one to weigh: write that rule for chrome that must
+follow the param, read the param by name, and keep everything else that
+varies by page out of the layout.
+
+Chrome that one kind of page has (a category's hero and breadcrumbs, a
+product's gallery frame) can be a layout of its own route instead of a
+template shared with other pages. A layout declared inside a `path()` belongs
+to that route (`/layout`, "Orphan Layout"):
+
+```tsx
+urls(({ path, layout }) => [
+  path("/c/:category", CategoryPage, { name: "category" }, () => [
+    layout(CategoryLayout), // the hero: re-renders with the category
+  ]),
+  path("/p/:slug", ProductPage, { name: "product" }, () => [
+    layout(ProductLayout),
+  ]),
+]);
+```
+
+- **No rule, shared prefetches.** It re-renders on its route's param or
+  search change by default, so nothing reads the page being left.
+- **It cannot leak.** The category's layout is not in the product page's
+  tree, so no navigation can keep it above a product page or the cart.
+- **What it costs.** Its handler runs on every param or search change of its
+  route, `?page=2` included; cache an expensive read with `"use cache"`. Without
+  a `transition()` in its chain (the route, this layout or a layout above) it
+  remounts on a param change, like the route. A navigation to another route
+  mounts that route's layout: nothing is held between them.
+- **In a `clientUrls()` group** a `path()` takes no `layout()`, only
+  `loader()`, `loading()` and `transition()` (`/client-urls`). A group
+  layout has no `revalidate()` of its own: it is a client component, so the
+  params it reads with `useParams()` are always the current page's. Its
+  loaders are held on navigation like a server layout's, though, so hero
+  data from a layout loader needs a rule that reads the page being left.
+  Put the block in the route component and its data in a loader on the
+  `path()`: that loader re-runs when the params or search change, with no
+  rule.
+
 ## Growing an app
 
 1. **Start with one `urls()` module** ([A small app](#a-small-app-one-module)).

package/skills/app-structure/e-commerce.md

@@ -424,12 +424,13 @@ without JavaScript too (`/server-actions` → "Progressive Enhancement").
 
 ## Why
 
-| Choice                                        | Why                                                                        |
-| --------------------------------------------- | -------------------------------------------------------------------------- |
-| `ppr` on category and product pages           | The shared part is HTML from the shell; only the holes render per request  |
-| `"use cache"` + `cacheTag()` for product data | One read for every visitor, and the tag reaches the shells that baked it   |
-| Live loaders for price, stock, cart           | Fresh on every request, shell HITs included                                |
-| `CartLoader` on the store layout              | One badge on every page; held on navigations; narrowed to cart actions     |
-| `TRACKING_SEARCH_PARAMS` excluded             | Campaign links do not multiply shells                                      |
-| `prefetch: false` on reviews                  | Every product card prefetches its page; few shoppers scroll to the reviews |
-| Checkout without `ppr` or `cache()`           | Nothing on it is shared                                                    |
+| Choice                                                  | Why                                                                                                                                                                                                                                                                                                                               |
+| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ppr` on category and product pages                     | The shared part is HTML from the shell; only the holes render per request                                                                                                                                                                                                                                                         |
+| `"use cache"` + `cacheTag()` for product data           | One read for every visitor, and the tag reaches the shells that baked it                                                                                                                                                                                                                                                          |
+| Live loaders for price, stock, cart                     | Fresh on every request, shell HITs included                                                                                                                                                                                                                                                                                       |
+| `CartLoader` on the store layout                        | One badge on every page; held on navigations; narrowed to cart actions                                                                                                                                                                                                                                                            |
+| `TRACKING_SEARCH_PARAMS` excluded                       | Campaign links do not multiply shells                                                                                                                                                                                                                                                                                             |
+| `prefetch: false` on reviews                            | Every product card prefetches its page; few shoppers scroll to the reviews                                                                                                                                                                                                                                                        |
+| Category content in `CategoryPage`, not a shared layout | A category hero belongs there too, or in a layout inside the category `path()`. In a layout shared with product pages it needs a `revalidate()` that reads the page being left, and every prefetch under that layout is shared only between the pages of one category ([Prefetches are shared](./SKILL.md#prefetches-are-shared)) |
+| Checkout without `ppr` or `cache()`                     | Nothing on it is shared                                                                                                                                                                                                                                                                                                           |

package/skills/app-structure/large-app.md

@@ -710,6 +710,10 @@ Rules of thumb:
   keeps the page being left on screen until the fill answers.
 - A same-route click (`/app/projects/1` to `/app/projects/2`) prefetches a
   flagged loader as usual: only data the page does not have yet is deferred.
+- One prefetch of a page serves every page that links to it. A `revalidate()`
+  that reads the page being left and keeps its segment shares it only between
+  the pages with equal values of what it read
+  ([Prefetches are shared](./SKILL.md#prefetches-are-shared)).
 
 Details: `/loader` → "`prefetch: false`", `/client-urls` → "`prefetch: false`".
 
@@ -802,11 +806,14 @@ reverse(".issues", { projectId: "api" }); // /acme/api/issues
 
 - A link into another module (the project nav's "Account settings") is built
   on the server and passed as a prop or loader data. `useReverse(accountRoutes)`
-  in a project component gives a wrong URL with no error (dc-t57).
+  in a project component gives a wrong URL with no error.
 - A server layout stays held when `:projectId` changes (partial rendering by
   design), so links it rendered keep the old project. Render the project
   switcher and nav in a client component with `useReverse(routes)`, or give
-  the layout a `revalidate()` comparing `projectId`.
+  the layout a `revalidate()` comparing `projectId`. Prefer the client
+  component: the rule reads the page being left, so a prefetch it keeps the
+  layout for is shared only between the pages of one project
+  ([Prefetches are shared](./SKILL.md#prefetches-are-shared)).
 - The account layout's `ctx.reverse(".settings")` resolves in the account
   module on every page below it, the project's pages included: it links to
   `/acme/settings`, not the project's settings route.
@@ -854,6 +861,12 @@ export function ProjectNav() {
 }
 ```
 
+`ProjectNavLoader`'s rule has the same cost: it reads `currentParams`, so a
+prefetch from `/acme/web/issues` to `/acme/web/settings` is shared only by
+the pages of the `web` project with the same set of params. Use it for links that need the server; links that
+stay inside the project module can come from `useReverse(routes)` in
+`ProjectNav`, with no rule.
+
 ## Why each piece sits where it does
 
 | Piece                                      | Where                                                          | Why                                                                                                                                                   |

package/skills/caching/SKILL.md

@@ -1121,7 +1121,7 @@ results first, outermost first:
 | deeper nesting                                | Composes the same way; the innermost boundary adds its default key without a `key` of its own, its request kind with one                                     |
 | under a `cache({ store })` on another store   | Also that store's `keyGenerator` result, one part per store: empty for a store that returns the default key while another's differs, none when all return it |
 | `cache(false)`                                | No caching, as before; a `cache()` re-enabled below it stays in the partition                                                                                |
-| no `key` anywhere                             | The default key, or the store's `keyGenerator` result, as before                                                                                             |
+| no `key` anywhere                             | The default key, or the store's `keyGenerator` result, then the request kind when that result does not start with it                                         |
 
 - No `key()` result, whatever it returns, equals a default key or a
   composed key, and no two composed keys are equal: a namespaced result
@@ -1150,10 +1150,15 @@ results first, outermost first:
   empty result there fails key resolution, so the request renders uncached,
   and the router warns once naming the store. On the same store the inner
   boundary's own default key already carries it (or its own `key()`
-  overrides it). Keep the default key in the result
-  (`` `${locale}:${defaultKey}` ``): its prefix is the request kind, and a
-  result without it gives a document request, a navigation and each
-  intercept navigation one record.
+  overrides it). A `keyGenerator` result keeps the request kind: the
+  default key starts with it (`doc:`, `partial:`, `intercept:<intercept>:`),
+  and a result that does not gets it as a last part (`items` is stored as
+  `items|doc` for a document request), so a document request, a navigation
+  and each intercept navigation keep their own record whatever it returns.
+  Build on the default key (`` `${defaultKey}|${locale}` ``) and the result
+  is the key, byte for byte. A prefix before it
+  (`` `${locale}:${defaultKey}` ``) keeps the kind too, but no longer starts
+  with it, so the kind is appended (`en%3Adoc%3A…|doc`).
 - A response route's entry (`path.json()` and the other response routes) is
   keyed the same way, behind a `response:` prefix. A `ppr` route's shell is
   partitioned by the chain's `key()` results, namespaced the same way, since

package/skills/client-urls/SKILL.md

@@ -278,7 +278,11 @@ the arguments and type of a `urls()` loader's (`ShouldRevalidateFn` from
 `actionUrl`, `actionResult`, `formData`, `method`,
 `routeName`/`fromRouteName`/`toRouteName`, and `stale`. Nothing runs in the
 browser before the request goes out; there is no client-computed decision and
-no hybrid.
+no hybrid. A predicate that reads `currentParams` or `fromRouteName` and
+keeps its segment shares a prefetch of that answer only between the pages
+with equal values of what it read, and one that reads `currentUrl` makes it
+page-only, as in `urls()` (`/links` → "Shared prefetches and
+`prefetchKey`").
 
 You still write the predicate in the `"use client"` module, or in a
 component's `.use`. The rango Vite plugin hoists each `revalidate()` argument
@@ -400,7 +404,7 @@ Everything after that is decided on the server, while it handles that request:
   the action's `actionResult` and `formData` (above). A loader that holds keeps
   the data the page shows.
 - **The browser's caches.** When the response arrives the browser marks its
-  history cache stale and drops its prefetches, unless the action called
+  history cache and its prefetches stale, unless the action called
   `keepClientCache()` (`/server-actions` → "Client Cache After an Action").
 - **A loader that fails on its rerun** reaches your `onError` on the server,
   and in the browser it throws at its read, below.
@@ -619,21 +623,23 @@ shell, such as a `useActionState` form (React suspends it once to encode its
 action), is in the first flush too: the router gives React up to three more
 turns before it, and none when the document is already complete.
 
-## `prefetch: false` — keep a loader out of prefetches
+## `prefetch: false` — keep a loader out of speculative prefetches
 
 A `<Link>` prefetch of a group route runs its loaders. Flag the expensive one
-and the prefetch skips it:
+and a viewport or render prefetch skips it. A hover prefetch, and
+`useRouter().prefetch()`, is intent to click: it runs the loader, and the
+click sends no fill (`/loader` → "`prefetch: false`").
 
 ```tsx
 path("/product/:slug", ProductPage, { name: "product" }, () => [
   loader(PriceLoader),
-  loader(ReviewsLoader, { prefetch: false }), // kept out of prefetches
+  loader(ReviewsLoader, { prefetch: false }), // kept out of viewport prefetches
   loading(<ProductSkeleton />),
 ]),
 ```
 
-A click inside the group still shows the destination at once. With the
-prefetch received, the URL and the other loaders' data move with the click
+A click inside the group still shows the destination at once. With a
+viewport or render prefetch received, the URL and the other loaders' data move with the click
 too, `useOutlet().pending` ends with that commit, and one follow-up request
 (the fill) runs only the flagged loaders. Read the flagged loader inside its
 own `<Suspense>` to show the page and that fallback at once; with no boundary
@@ -654,10 +660,11 @@ rest of the destination; otherwise it is held. A same-route click
 - `loading()` in `clientUrls()` takes no options, and a flagged `loading()`
   on a server layout above the group defers nothing for the group's routes.
 - On an `intercept()` loader the flag works as in `urls()`: an in-group
-  prefetch of the intercept's target defers it, and the click opens the modal
-  at once with one fill for it.
-- With `ssr: false` on a `ppr` group route the flag is ignored (the bake
-  lane), as on a server route.
+  viewport or render prefetch of the intercept's target defers it, and the
+  click opens the modal at once with one fill for it; a hover's runs it.
+- With `ssr: false` on a `ppr` group route the flag works as on a server
+  route: deferred unless the prefetch serves the loader from a pin of a
+  document-captured shell (`/ppr` → "`prefetch: false` on a `ppr` route").
 - Test it with `serveShellRequest` in the Flight project: mount the module
   itself, and `rangoUseClientTransform()` installs the group's projection
   (`/testing` → `serve-shell-request.md`, "`clientUrls()` routes"). It also

package/skills/comparison/references/framework-comparison.md

@@ -558,8 +558,9 @@ analog but operates on loader/query reload, not RSC-segment render.
 
 `<Link prefetch="hover|viewport|render|adaptive|none">` (default: the router's
 `defaultPrefetch`, `"none"` in development and `"viewport"` in production), plus
-`prefetchKey` (`":source"` scopes a prefetch to the originating page for routes
-whose response branches on `currentUrl`). Intercepted plain `<a href>` elements
+`prefetchKey` (`":source"` scopes a prefetch to the originating page; the
+router does so itself for an intercept target and for a `revalidate()` that
+read the source page and kept a segment). Intercepted plain `<a href>` elements
 inside the router basename follow the same default; common static-resource
 extensions are excluded unless `data-prefetch="true"` identifies an application
 route, and `data-prefetch="false"` or `"none"` opts out unsafe GET links. A
@@ -582,9 +583,11 @@ the bounded cache uses a configurable TTL. `Save-Data`,
 `prefers-reduced-data`, or `prefetchCacheTTL: false` disable speculation.
 
 Correctness is part of the prefetch contract. Keys include Rango state, destination
-URL, and the mounted segment set used to compute the diff. Server actions rotate
-state and abort stale speculative work; a generation check prevents a late result
-from repopulating an invalidated cache. Routes an intercept targets are automatically
+URL, and the mounted segment set used to compute the diff. Server actions mark
+every prefetch stale without aborting it: a click on a stale one shows it at once,
+then revalidates the page in the background. `invalidateClientCache()` rotates
+state and aborts speculative work; a generation check prevents a late result from
+repopulating a flushed cache. Routes an intercept targets are automatically
 source-scoped, matched or not,
 and malformed, cross-origin, foreign-router, redirect, and reload responses are
 dropped rather than warmed. `useLinkStatus()` exposes `{ pending }` for the owning
@@ -594,7 +597,7 @@ link.
 session-cookie value shaped as `{documentVersion}:{invalidationTimestamp}`. Navigation
 and prefetch requests send it as `X-Rango-State`, and RSC responses vary on that
 header, so the browser HTTP cache and Rango's decoded prefetch map share one cache
-identity. A deployment that changes the router's code or client assets changes the version; a mutation rotates the timestamp. Old
+identity. A deployment that changes the router's code or client assets changes the version; `invalidateClientCache()` rotates the timestamp. Old
 responses become unreachable under the retired identity instead of requiring every
 cache layer to delete the same entries successfully.
 
@@ -608,10 +611,13 @@ cookie. Across those two seats, it covers mutations initiated outside the action
 bridge: REST calls, client-observed WebSocket events, authentication changes, or
 middleware/loader decisions.
 
-Server Actions invalidate automatically after a response reaches the browser. If
-an action knows it changed nothing that any route renders, `keepClientCache()` is
-the explicit per-response escape hatch: it suppresses that automatic state
-rotation, prefetch flush, broadcast, and revalidation fetch. Together,
+Server Actions mark the history and prefetch caches stale automatically after a
+response reaches the browser, without rotating the state: the response bumps
+only its write part, so the browser HTTP cache misses on responses from before
+the write while the in-memory caches go stale. If an action knows it
+changed nothing that any route renders, `keepClientCache()` is the explicit
+per-response escape hatch: it suppresses that stale-marking, the broadcast, and
+the revalidation fetch. Together,
 `invalidateClientCache()` and `keepClientCache()` give application code control in
 both directions — force a miss for mutations the router cannot observe, or preserve
 the current state for a known no-op.

package/skills/document-cache/SKILL.md

@@ -217,6 +217,14 @@ suffixes are still appended.
   request that holds no segments (`router.refresh()`, a cross-tab refresh).
   Each renders at the origin and is not stored, because its data may predate
   a write and the cache cannot tell.
+- A client navigation whose answer depends on the page it came from: a
+  `revalidate()` rule that read `currentParams`, `currentUrl` or
+  `fromRouteName` kept a segment, or an intercept targets the route. The key
+  names the segments the client holds, not its page, so `/c/tv` would get the
+  answer `/c/audio` got for `/c/audio?sort=x` and keep its own hero. It is sent
+  `private, no-cache` over the route's `Cache-Control` and is not stored. One
+  whose rule re-rendered the segment is right from every page and is stored as
+  usual.
 - Non-GET requests
 - Responses without an `s-maxage` `Cache-Control` directive
 - Responses whose `Cache-Control` also contains `private`, `no-store`, or an
@@ -228,6 +236,11 @@ suffixes are still appended.
   (`rango-state-fresh` by default), so it is not stored. A stale entry's
   background re-run sets no fresh-reads cookie (no visitor made that
   invalidation), so its invalidation does not keep the refreshed page out.
+- A document that carries location state (`ctx.setLocationState()`, or the
+  one-shot cookie a document redirect left for it): it is the visitor's, so it
+  is not stored, leaves `private, no-store`, and a request that arrives with
+  that cookie, or whose earlier middleware set state, is not answered from a
+  stored entry (see `/hooks` `state.md`, "State on a document response")
 - Non-200 responses
 - A 200 whose render reported an error: a component that threw after the
   response started streaming, such as an async server component whose fetch

package/skills/hooks/navigation.md

@@ -160,14 +160,14 @@ function NavigationControls() {
 }
 ```
 
-| Method                   | Behaviour                                                                                                       |
-| ------------------------ | --------------------------------------------------------------------------------------------------------------- |
-| `push(url, options?)`    | Navigate and add a history entry. Returns a promise.                                                            |
-| `replace(url, options?)` | Navigate and replace the current history entry. Returns a promise.                                              |
-| `refresh()`              | Re-fetch the current route's server data, keeping client state. Returns a promise.                              |
-| `prefetch(url, opts?)`   | Prefetch a target. `{ key: ":source" }` scopes the entry to the source page (parity with `<Link prefetchKey>`). |
-| `back()`                 | `history.back()`; on the first entry of the session it replaces to the app root instead of leaving the app.     |
-| `forward()`              | `history.forward()`.                                                                                            |
+| Method                   | Behaviour                                                                                                                     |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| `push(url, options?)`    | Navigate and add a history entry. Returns a promise.                                                                          |
+| `replace(url, options?)` | Navigate and replace the current history entry. Returns a promise.                                                            |
+| `refresh()`              | Re-fetch the current route's server data, keeping client state. Returns a promise.                                            |
+| `prefetch(url, opts?)`   | Prefetch a target. `{ key: ":source" }` scopes the entry to the source page (parity with `<Link prefetchKey>`, see `/links`). |
+| `back()`                 | `history.back()`; on the first entry of the session it replaces to the app root instead of leaving the app.                   |
+| `forward()`              | `history.forward()`.                                                                                                          |
 
 `push` / `replace` options: `scroll` (`false` keeps the current scroll
 position), `revalidate` (default `true`, see below), `transition` (`false`

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,121 @@ 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. A HIT sends exactly the state set before its
+  render: its headers leave before its tail runs, so they decide then
+  whether the response is private.
+- **Not from a loader.** A loader has no `setLocationState`, and calling
+  `getRequestContext().setLocationState()` from one is not supported: the
+  payload takes the request's state before loaders settle, so a loader's
+  write may arrive (a `ppr` MISS then renders in full) or be dropped, and a
+  shell HIT never sends it. Set state from middleware, the handler or an
+  action.
+- **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. A `ppr`
+  shell HIT that read the cookie and then cannot finish its tail reloads the
+  page into a full render; its headers already cleared the cookie, so its
+  reload script sets it again first (from script, so without `HttpOnly`,
+  for the moment the reload takes), and the reload shows the state.
+- **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 +535,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
@@ -503,9 +619,12 @@ from module-level callbacks too. Imported from the root entry `@rangojs/router`,
 it is selected by export conditions:
 
 - **Client** (client component or module): marks the history cache stale,
-  flushes the prefetch cache, rotates the router state, and notifies other tabs
-  — the same thing a completed server action does. During SSR of a client
-  component it is a no-op (dev warning).
+  flushes the prefetch cache, rotates the router state, and notifies other
+  tabs, which adopt the new state and flush theirs. That is more than a
+  completed server action does: an action marks history and prefetches stale
+  and rotates nothing (its response bumps only the state's write part, so the
+  browser HTTP cache misses on responses from before the write). During SSR
+  of a client component it is a no-op (dev warning).
 - **Server** (handler, server component, middleware, loader, or action): writes
   a rotated state `Set-Cookie` for the responding client, which marks its
   caches stale when it next reads them. Idempotent within a request; throws
@@ -514,9 +633,10 @@ it is selected by export conditions:
   from handler code writes the cookie only on the renders that run it (a
   MISS); call it from middleware, which runs on every request, HITs included.
 
-Server actions already invalidate automatically; to suppress that for a no-op
-action, call `keepClientCache()` inside it (see `/server-actions` → "Client
-Cache After an Action").
+Server actions already mark the caches stale automatically; to suppress that
+for a no-op action, call `keepClientCache()` inside it, and for the full flush
+and rotation, call `invalidateClientCache()` inside it (see `/server-actions` →
+"Client Cache After an Action").
 
 ```tsx
 "use client";