@rangojs/router 0.19.1 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.19.1",
+  "version": "0.21.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -217,7 +217,6 @@
     "@playwright/test": "^1.49.1",
     "@testing-library/react": ">=16",
     "@vercel/functions": "^3.0.0",
-    "@vitejs/plugin-rsc": "^0.5.35",
     "react": ">=19.2.8 <20",
     "react-dom": ">=19.2.8 <20",
     "vite": "^8.0.16",

package/skills/bundle-analysis/SKILL.md

@@ -15,7 +15,7 @@ Your app builds in three Vite environments — `client`, `ssr`, and `rsc` — an
 1. **Server code leaking into the client.** A file that imports `node:fs`, calls a database, or contains action logic ends up in the client bundle because a client component pulled it in transitively. Symptom: your client bundle is much larger than expected, sometimes with imports that fail at runtime.
 2. **Both dev and prod React in the SSR/RSC bundle.** When `process.env.NODE_ENV` isn't folded at build time, React's CJS files ship both `.development.js` _and_ `.production.js` variants — doubling React's footprint. The Cloudflare Vite plugin and rango's `vercel` preset fold NODE_ENV automatically; on the default `node` preset, `vite build` does it for the client but not always for SSR/RSC, so add the `define` from Step 2.
 3. **An oversized routes-manifest in your RSC worker.** The `virtual:rsc-router/routes-manifest/<routerId>` chunk holds your route trie and precomputed entries — large only in proportion to your route count. If it's surprisingly big, you may have unintentionally generated routes (e.g., parametrized fixtures) that bloated the trie.
-4. **Poor client-chunk grouping.** `rango({ clientChunks })` decides how `"use client"` modules are grouped into browser chunks. The default groups them by route directory (`routes/<id>/**` → `app-<id>`), with flat folders like `src/components/` in one shared chunk; `clientChunks: false` ships one client chunk per router. A route that pulls in unrelated routes' client code, or one oversized shared chunk, points at the grouping.
+4. **Poor client-chunk grouping.** `rango({ clientChunks })` decides how `"use client"` modules are grouped into browser chunks. The default groups them by route directory (`routes/<id>/**` → `app-<id>`), with flat folders like `src/components/` in one shared chunk; `clientChunks: false` ships one client chunk per router. A group is the loading unit: rendering any one member downloads the whole group's chunk. A route that pulls in unrelated routes' client code, or one oversized shared chunk, points at the grouping; `DEBUG=rango:chunks vite build` logs each group's size at build end.
 
 Tree-shaking does _not_ catch generated data inlined as string literals, or data-dependent conditionals like React's `NODE_ENV` branches. You need a visualizer.
 

package/skills/cache-guide/SKILL.md

@@ -166,24 +166,87 @@ exemption there). The route then serves uncached; see `/ppr`.
 
 ### Cross-deploy safety: version-segmented store keys
 
-`CFCacheStore` prefixes every **physical** store key (the CF Cache API URL and
-the KV key) with the build version — auto-generated from the
-`@rangojs/router:version` virtual module, overridable via the store's `version`
-option. A new deploy reads under a new prefix, so it can **never** read a
-previous build's entries: no cross-deploy shape drift, and no dead client-chunk
-references baked into cached RSC.
-
-The tradeoff to know: **loader/data caches use the same store**, so they're
-version-segmented too. Every deploy is therefore a _cold data cache_ — SWR can't
-soften it, because no stale entry exists under the new key. For high-traffic,
-frequently-deploying, data-bound apps that's a deploy-time origin warm-up. Decide
-deliberately: accept it (correctness over hit-rate), or split the policy — let
-the render/edge cache auto-version while a separate data store gets a stable
-`version` so its entries survive deploys. (Per-process stores like
-`MemorySegmentCacheStore` are cold on every restart anyway; this matters for
-persistent stores.) `VercelCacheStore` does not version automatically: pass a
-per-deploy `getCache({ namespace })` or its `version` option (see `/vercel`).
-See `/caching` for store setup.
+`CFCacheStore` and `VercelCacheStore` prefix every **physical** store key with a
+version, so a build only reads entries that code like its own wrote. The version
+is a hash of the code, computed per `createRouter()` by `vite build`, not the
+build time. Each router has two:
+
+- The **data version** (a hash of the router's server code) keys cached RSC
+  data: segment entries from `cache()`, `"use cache"` values, loader data.
+- The **document version** (the data version plus the SSR output, the client
+  asset file names, `base`, and the router's `Prerender` payloads) keys stored
+  HTML (PPR shells, document-cache responses). It is also sent to the browser,
+  and a mismatch with the tab's `_rsc_v` reloads the tab.
+
+Same code builds to the same versions, so a rebuild or redeploy of unchanged
+code keeps the cache, and a deploy that changes app A keeps app B's cache.
+
+| Deploy                                | Cached data         | Stored HTML           | Open tabs               |
+| ------------------------------------- | ------------------- | --------------------- | ----------------------- |
+| Rebuild, no code change               | kept                | kept                  | untouched               |
+| Server code of app A changes          | cleared for A only  | cleared for A only    | A's tabs reload         |
+| Client code of any app changes        | kept for every app  | cleared for every app | every app's tabs reload |
+| Server code shared by A and B changes | cleared for A and B | cleared for A and B   | A's and B's tabs reload |
+
+"Server code" is everything the app's server can run: its own modules, the
+dependencies it imports (bundled, or on the node preset left external and
+resolved from `node_modules`), and a stylesheet its server code links
+(`import "./x.css"` in a server component, or `import href from "./x.css?url"`
+for a document `<link>`): the stylesheet's hashed URL is in what the server
+renders, so a change to the compiled CSS clears that app's cached data. A
+`clientUrls()` module is client code that also tells the server what to run:
+changing which loaders a route declares, its `loading` or its transition
+counts as a server change; changing the components it renders does not. Under
+a host router, apps are independent when the host mounts them lazily
+(`.lazy(() => import(...))`); routers one module imports statically share
+that module's code.
+
+The key families: `CFCacheStore` keys segment entries and `fn:` items with the
+data version and `doc:` responses and `shell2:` shells with the document
+version. `VercelCacheStore` does the same by default (families `s`, `i` data;
+`r`, `h` document). `MemorySegmentCacheStore` has no version; the process is its
+scope.
+
+Tag invalidation markers are stored without a version, so `updateTag()` and
+`revalidateTag()` apply to entries of every version, including a version that
+comes back in a rollback.
+
+- **Force a clear:** change `version` (`createRouter({ version })`,
+  `createRSCHandler({ version })`, `new CFCacheStore({ version })` or
+  `new VercelCacheStore({ version })` all use that exact value for both
+  versions), or invalidate tags.
+- **Keep the old "every deploy clears the cache" behavior:** set `version` to a
+  per-deploy value (a build id), or on Vercel keep a deployment-scoped
+  `getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID })`.
+- **Separate environments:** two deployments built from the same code have the
+  same versions. If they share a store (the same KV namespace), they share
+  entries. Give each environment its own KV namespace or cache namespace, or its
+  own `version`.
+
+Two things give a router a new version on every build, and with it a cold
+cache on every deploy:
+
+- **No stable encryption key.** The key that encrypts inline server-action
+  bound arguments is part of the version of every router whose code encrypts
+  with it. Pass `rango({ encryptionKey: process.env.RANGO_ENCRYPTION_KEY })`
+  (see `/use-cache`); the build prints a note when a router needs it.
+- **A `Prerender` or `Static()` handler whose output differs per build**: a
+  timestamp, a random id, or an inline action with bound arguments rendered at
+  build time (its arguments are encrypted with a random IV, stable key or not).
+- **An import the server build leaves external and cannot read**: a package
+  that is not in `node_modules` at build time, a path that does not resolve, a
+  URL. The build names it.
+
+Every build prints each router's versions and writes what they were computed
+from to `node_modules/.rangojs-router-build/cache-versions.json`. Diff that
+file between two builds to see which chunk or payload moved a version; its
+`unownedFiles` lists the server files in no router's version (the host entry
+of lazily mounted apps), where a change keeps every app's cache.
+
+A custom persistent store keys the same way with `getCacheVersions()` from
+`@rangojs/router/cache`, called per operation inside the request: `data` for
+segment entries and items, `document` for responses and shells, no version on
+its tag-invalidation records. See `/caching` for store setup.
 
 ### Client cache: forward/back is mutation-aware
 
@@ -226,8 +289,9 @@ recompute for a merely-aging entry.
   `/document-cache`. A platform CDN may independently consume the same header
   and bypass the function on hits; see `/deployment-caching`.
 
-SWR softens normal TTL expiry, **not** a cross-deploy cold cache — a new build
-has no stale entry to serve (see version-segmented store keys above).
+SWR softens normal TTL expiry, **not** a version change — a deploy that changes
+a router's code reads under a new version and has no stale entry to serve (see
+version-segmented store keys above).
 
 Store support is layer-specific. `CFCacheStore` and `VercelCacheStore` support
 SWR for segment, document/response, item (`"use cache"` and cached loaders), and

package/skills/caching/SKILL.md

@@ -564,9 +564,13 @@ const router = createRouter<AppBindings>({
 });
 ```
 
-`CFCacheStore` prefixes every key with the build version, so a deploy never
-reads the previous build's entries (override with `version`). See `/cache-guide`
-→ "Cross-deploy safety" and `/cloudflare` for bindings.
+`CFCacheStore` prefixes every key with a version computed per `createRouter()`
+from that router's built code: segment entries and `fn:` items with the data
+version, `doc:` responses and `shell2:` shells with the document version. A
+deploy that changes a router's code reads under a new version; a deploy that does
+not keeps the entries. Tag invalidation markers carry no version, so `updateTag()`
+reaches entries of every version. `version` replaces both versions with one
+value. See `/cache-guide` → "Cross-deploy safety" and `/cloudflare` for bindings.
 
 ### With KV L2 Persistence
 
@@ -755,10 +759,11 @@ the store adds SWR, tag invalidation, and the family split on top of it.
 import { getCache, waitUntil } from "@vercel/functions";
 import { VercelCacheStore } from "@rangojs/router/cache";
 
-// A per-deploy namespace: Vercel does not reconcile entries across deploys.
+// No deployment id in the namespace: the store versions its keys itself, so a
+// deploy that does not change a router keeps that router's entries.
 // One handle per process: the store keeps its PPR shell and tag-marker
 // memos per handle.
-const runtimeCache = getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID });
+const runtimeCache = getCache();
 
 const router = createRouter({
   document: Document,
@@ -794,6 +799,12 @@ beyond the per-item cap are dropped with a warning. The official client swallows
 `expireTag` failures, so treat `updateTag()` on Vercel as best-effort. See
 `/vercel` for the preset and the remaining options (`version`, `name`, `debug`).
 
+`VercelCacheStore` versions its keys by default: families `s` and `i` take the
+router's data version, `r` and `h` its document version, and tag markers
+(`rg:tm:{tag}`) take none. `version` replaces both. To clear the cache on every
+deploy, set `version` to a per-deploy value or keep a deployment-scoped
+`getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID })`.
+
 ## Cache purity & tainted objects
 
 A `cache()` boundary caches everything except loaders, so anything read inside a

package/skills/client-urls/SKILL.md

@@ -376,6 +376,22 @@ a hard load of the target URL renders the full route.
   throwers in the client `ErrorBoundary`; `useFetchLoader` works unchanged
   (route-independent lane; `revalidate()` deliberately not consulted).
   Pinned in the router repo's client-urls hook-probe e2e.
+- **Location state follows the same split as the route hooks.** Inside the
+  optimistic branch (the destination and the group's client layouts)
+  `useLocationState` reads the state the navigation carries (`<Link state>`,
+  `router.push(url, { state })`) from the first optimistic render, before the
+  server answers: a product page can show the name its link carried while
+  its loader streams. Chrome outside the group, and content a navigation
+  keeps on screen (a same-route navigation, a destination that suspends with
+  no boundary), keep the committed entry's state until the canonical commit.
+  State a redirect carries arrives with that commit (an action's
+  `setLocationState` without a redirect is applied when its response
+  arrives), and a navigation that is superseded or cancelled leaves none
+  behind. A `flash` slot read in the branch is cleared from history once the
+  navigation commits, not before. In the branch the value is the object the
+  navigation passed; from the commit on it is the entry's copy (a structured
+  clone), so an object-valued slot is a new, equal object at that point.
+  Do not key an effect on its identity across the two.
 - **Editing the module in dev:** projections refresh via HMR discovery; if a
   route-shape edit ever serves stale routes, restart dev — and if you are
   developing the router itself, rebuild the router dist before `pnpm dev`

package/skills/cloudflare/SKILL.md

@@ -48,7 +48,8 @@ export default defineConfig({
 Worker runs the RSC entry and loads SSR inside the same isolate.
 
 `buildEnv: "auto"` gives `Prerender` and `Static` handlers a real `ctx.env` at
-build time through Wrangler's `getPlatformProxy()` (local bindings). Omit it
+build time through Wrangler's `getPlatformProxy()` (local bindings), reading
+the wrangler config from the Vite root whatever the working directory. Omit it
 (default `false`) when build-time rendering must not touch bindings; `ctx.env`
 then throws during build rendering. See `/prerender`.
 

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

@@ -57,7 +57,7 @@ and multi-region composition without replacing its routing or data model.
 | Middleware              | Global + segment-scoped subtree                                                                            | Single root Proxy (matcher filters paths); no subtree scope                    | Request/server-function middleware                                                 | [Hono middleware + handler interceptors](https://waku.gg/#interceptors) |
 | Observability           | Built-in CF + Vercel OTel phase spans, `Server-Timing`, perf waterfall                                     | Built-in OTel spans; no equivalent router-phase waterfall                      | Client/data devtools                                                               | No equivalent built-in phase model                                      |
 | Deploy targets          | Node, Cloudflare, Vercel — all with presets                                                                | Node/Vercel first; other platforms through adapters                            | Broad Vite/Rsbuild runtime support                                                 | Node plus adapters                                                      |
-| Deployment skew         | Automatic build-version handshake for navigation, prefetch, and actions; safe reload on mismatch           | `deploymentId` mismatch reload; Vercel can pin clients to an immutable deploy  | Application/platform policy                                                        | Build-id mismatch reload (v1.0-beta)                                    |
+| Deployment skew         | Automatic version handshake for navigation, prefetch, and actions; safe reload on mismatch                 | `deploymentId` mismatch reload; Vercel can pin clients to an immutable deploy  | Application/platform policy                                                        | Build-id mismatch reload (v1.0-beta)                                    |
 | Multi-tenant            | `createHostRouter()` built-in                                                                              | Roll your own                                                                  | Roll your own                                                                      | Roll your own                                                           |
 | Testing primitives      | Ships `@rangojs/router/testing` (handlers/loaders/mw/Flight/e2e)                                           | No comparable handler/Flight primitives                                        | Documented patterns; no shipped utils                                              | No comparable handler/Flight primitives                                 |
 | Client runtime          | ~50 KB Rango + ~115 KB React/RSC, per-route chunks                                                         | Configuration-dependent                                                        | Configuration-dependent                                                            | Deliberately light                                                      |
@@ -336,8 +336,9 @@ first-class primitive.
 
 ### Deployment skew is detected before stale code executes
 
-The Vite plugin generates a build version and injects it into the RSC handler and
-initial payload. The browser returns that version on every partial navigation,
+`vite build` computes a document version per `createRouter()` from that router's
+built code (the server code, the SSR output, the client asset file names, `base`,
+and its Prerender payloads) and ships it in the initial payload metadata. The browser returns that version on every partial navigation,
 prefetch, and Server Action. If an old tab reaches a newer server, request
 classification detects the mismatch before resolving the route or executing the
 action and responds with `X-RSC-Reload`. The browser then performs a clean document
@@ -348,13 +349,16 @@ falling through to a misleading 404.
 The protection covers fresh, completed-prefetch, and in-flight-prefetch responses.
 For action requests, the reload returns to the same-origin referrer rather than the
 internal action URL. The cache side follows the same correctness rule:
-`CFCacheStore` automatically versions its physical Cache API and KV keys, so a new
-build cannot replay Flight containing an old component shape or dead client-chunk
-reference. `VercelCacheStore` exposes the same version segmentation, but — unlike
-`CFCacheStore` — does not default `version` to the build version: skew safety is
-opt-in via the `version` option or the recommended deployment-specific Runtime
-Cache namespace. The browser's Rango state also includes
-the build version, rotating HTTP and in-memory prefetch cache identity on boot.
+`CFCacheStore` and `VercelCacheStore` automatically version their physical keys
+(Cache API and KV keys on Cloudflare): cached RSC data (segment entries, `"use
+cache"` values, loader data) by a data version, a hash of the router's server
+code, and stored HTML (PPR shells, document-cache responses) by the document
+version. A build whose router code changed cannot replay Flight containing an old
+component shape or dead client-chunk reference, and a rebuild of unchanged code
+keeps its cache. Tag invalidation markers carry no version, so `updateTag()`
+reaches entries of every version. The `version` option replaces both versions.
+The browser's Rango state also includes the document version, rotating HTTP and
+in-memory prefetch cache identity on boot.
 
 Next.js deserves explicit credit here: its
 [`deploymentId`](https://nextjs.org/docs/app/api-reference/config/next-config-js/deploymentId)
@@ -587,10 +591,10 @@ dropped rather than warmed. `useLinkStatus()` exposes `{ pending }` for the owni
 link.
 
 **Rango State ties prefetch and client-cache invalidation together.** It is a
-session-cookie value shaped as `{buildVersion}:{invalidationTimestamp}`. Navigation
+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 changes the version; a mutation rotates the timestamp. Old
+identity. A deployment that changes the router's code or client assets changes the version; a mutation rotates the timestamp. Old
 responses become unreachable under the retired identity instead of requiring every
 cache layer to delete the same entries successfully.
 

package/skills/hooks/SKILL.md

@@ -68,6 +68,9 @@ the one for your case.
 - [`./state.md`](./state.md) — `useLocationState` (persistent + flash state,
   `.read()`/`.read(location)`/`.write()`/`.delete()`, typed `state` on `router.push()` /
   `router.replace()`, serializability errors that name the failing field),
+  state from another deploy (dropped by the router, no version to manage), the
+  `createLocationState` options (`flash`; `clearOnReload` for state that must
+  not come back after a refresh, such as a "load more" list),
   `invalidateClientCache()`.
 - [`./outlets.md`](./outlets.md) — `Outlet`, `ParallelOutlet`, `useOutlet`.
 - [`./urls.md`](./urls.md) — `useParams`, `usePathname`, `useSearchParams`,

package/skills/hooks/handle-and-actions.md

@@ -39,6 +39,12 @@ the capture, so its pushes always apply client-side; with `ssr: false` they
 bake into the shell. See `/loader` → "Writing Handles from Loaders". `useHandle`
 re-renders on every handle update, late loader pushes included.
 
+On a document load `useHandle` hydrates with the handle data its HTML was
+rendered from, then takes whatever arrived since. That holds wherever the
+reader sits: a reader inside a `<Suspense>` or `loading()` boundary, which
+hydrates after the rest of the page, does not see a late loader push during
+its hydration render, so it cannot mismatch its server HTML.
+
 Handles can be passed as props from server to client components:
 
 ```tsx

package/skills/hooks/navigation.md

@@ -27,6 +27,34 @@ function IsLoading() {
 }
 ```
 
+#### Pending UI, Back/Forward included
+
+A link click, `router.push()` and a Back/Forward that has to fetch its entry
+report a pending navigation the same way. While the page being left is still
+on screen:
+
+| What you want to show                          | Read                                                                                |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------- |
+| a request is out, nothing has arrived          | `state === "loading"`; `pendingUrl` is the URL being fetched                        |
+| the page has not fully arrived yet             | `isStreaming`: true from the start of the request until the stream ends             |
+| which page is on screen while the request runs | `location`, or `usePathname()` / `useSearchParams()` (see [`./urls.md`](./urls.md)) |
+
+`state` and `pendingUrl` cover the network wait. Once the response has
+arrived a loader may still be streaming, and React keeps the page being left
+on screen where a navigation holds its content (a same-route change, a
+`transition()` route); `isStreaming` covers that part too, so use it for a
+progress indicator that should last until the new page is complete.
+
+On Back/Forward the address bar changes at once, before any of this: during
+the wait `window.location` is the entry being fetched, the same URL as
+`pendingUrl`, and `location` is the page on screen. A Back/Forward served
+from the client's history cache restores its page in one commit and reports
+no pending state.
+
+`location` moves when the response arrives. Where React then holds the page
+being left, it is ahead of the screen for that last part of the wait, and so
+is a URL hook in a component that first mounts then (issue #1046).
+
 ### useRouter()
 
 Access stable router actions. The returned object never changes identity, so

package/skills/hooks/state.md

@@ -84,6 +84,59 @@ definition:
 const state = useLocationState<{ from?: string }>(); // { from?: string } | undefined
 ```
 
+### When a reader sees an entry's state
+
+A reader sees a history entry's location state together with that entry's
+page, never before it. The router keeps the state of the entry on screen next
+to the page it renders and changes both in one React commit. While a
+navigation is pending (its loader still streaming, a `transition()` holding
+the page) what is on screen keeps the state of the entry being left. That
+holds for every reader in it, including one that mounts during the wait: it
+reads the entry on screen, not the one `history.state` already holds.
+Back/forward and state the server sets on a navigation
+(`ctx.setLocationState()`, `redirect(url, { state })`) follow the same rule.
+
+| What changes the state                                       | A reader gets it                                                 |
+| ------------------------------------------------------------ | ---------------------------------------------------------------- |
+| `<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                         |
+| 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   |
+| `Def.write()` / `Def.delete()`                               | when the entry is next restored: back/forward to it, or a reload |
+
+Three consequences:
+
+- A value keeps its identity until the entry's state changes it. A navigation
+  that carries no state re-renders no reader. One that does re-renders each
+  reader once, in the commit that already renders the page; a reader of a
+  slot the navigation carried forward unchanged (the value it got from the
+  hook, passed back) or of a slot a server action did not touch gets the same
+  object again, so its effects and memoized children do not run. Any other
+  object is a new value, equal content included: a link clicked twice
+  announces its state twice. A value is always a copy of what was passed.
+- `Def.write()` and `Def.delete()` change the history entry and nothing a
+  reader shows, whether it is mounted or mounts later. `Def.read()` returns
+  the written value at once.
+- Outside the router's provider (a second React root, a component rendered
+  bare in a test) a reader has no entry and returns `undefined`. Test with
+  `renderRoute` (see `/testing`).
+
+A reader that mounts with the destination reads the destination's state on
+its first render. Inside an optimistically rendered `clientUrls()` destination
+that is the state the navigation carries, before the server has answered (see
+`/client-urls`, "Pitfalls").
+
+The URL hooks follow the same rule for a component that is mounted across the
+navigation: on back/forward too, `usePathname()` and `useSearchParams()`
+change with the page, not at the `popstate` event (see
+[`./urls.md`](./urls.md), "When the URL hooks change"). One difference
+remains (issue #1046): a component that first mounts in the page being left,
+after the response arrived and while React still holds the destination, reads
+its own entry's location state from `useLocationState` and the destination's
+URL and params from `usePathname()`, `useSearchParams()` and `useParams()`.
+
 ### State on router.push() / router.replace()
 
 The same `state` option exists on `router.push()` / `router.replace()` (see
@@ -201,9 +254,11 @@ Flash behavior is determined by the definition (`{ flash: true }`), not by which
 hook reads it. `useLocationState` reads the value during render (on the
 hydration render it returns `undefined` and reads in a post-mount effect, so
 SSR and hydration agree), then clears it from `history.state` via
-`replaceState` in a `useEffect`. Multiple components reading the same flash
-definition all see the value. Pressing back/forward will not re-show the flash
-since it was cleared.
+`replaceState` in a `useEffect`. Every component reading the same flash
+definition sees the value, whenever it mounts, until the next navigation or
+back/forward commits its entry's state: an entry that carries no flash shows
+none. A server action's state does not end it. Pressing back/forward will not
+re-show the flash since it was cleared.
 
 Set flash state from the server via `redirect()` with state (from a handler,
 middleware, or server action). Import the definition from the shared module so
@@ -221,7 +276,9 @@ import { FlashMessage } from "../location-states";
 };
 ```
 
-Or via `ctx.setLocationState()` on any response (handlers and middleware):
+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):
 
 ```tsx
 (ctx) => {
@@ -230,6 +287,148 @@ Or via `ctx.setLocationState()` on any response (handlers and middleware):
 };
 ```
 
+### State from another deploy
+
+History entries survive reloads and back/forward, so a tab left open across a
+release still holds the state the older build wrote. The router drops it for
+you: every entry records the app version its location state was written under,
+and a read under any other version returns `undefined`, for typed slots and
+for plain state alike. You do not manage a version and there is none to read;
+the app version is the one the router already uses to reload a client that is
+behind the server. It is computed from the app's built code (its server code
+and the client assets), so it changes with a build that changes the app and
+stays the same across a rebuild or redeploy of unchanged code.
+
+| An entry's location state, read by                               | Result      |
+| ---------------------------------------------------------------- | ----------- |
+| the version that wrote it: navigation, back/forward, refresh     | the value   |
+| the same code rebuilt or redeployed                              | the value   |
+| a changed build, after a refresh or a restored tab               | `undefined` |
+| a changed build, on back/forward to an entry the older one wrote | `undefined` |
+| any build, when the entry predates this behavior                 | `undefined` |
+
+So location state is for the current session of the current version of the
+app: a filter carried on a link, a flash message, a scroll target. State that
+has to outlive a deploy that changes the app belongs in the URL, a cookie or
+storage. In development a
+server-module edit (HMR) changes the version too; the running page keeps its
+state, and the next document load drops it.
+
+### createLocationState options
+
+```ts
+createLocationState<TState>({
+  flash?: boolean, // read once, cleared after paint (above)
+  clearOnReload?: boolean, // drop the state on a document load (below)
+});
+```
+
+The value is always stored as-is. `clearOnReload` changes the slot's KEY in
+`history.state` instead, by a suffix on the key the Vite plugin injects
+(`<key>` below, `__rsc_ls_<file>#<ExportName>`):
+
+| Options         | Key in `history.state` | Reads `undefined` when                          |
+| --------------- | ---------------------- | ----------------------------------------------- |
+| none, `flash`   | `<key>`                | the slot is empty (`flash`: once read)          |
+| `clearOnReload` | `<key>~r`              | the entry's document was loaded since the write |
+
+`Def.__rsc_ls_key` is that key, suffix included. `~` cannot appear in an export
+name, so no other definition can end up with a suffixed key.
+
+`flash` with `clearOnReload` is rejected: `createLocationState` throws in
+development.
+
+### clearOnReload: state the server did not render with
+
+Location state lives in the browser, so the server renders a document without
+it. `useLocationState` therefore hydrates as `undefined` and applies the stored
+value right after. For most state that is invisible. For state that decides
+how much content is on the page, it is a layout shift on every refresh.
+
+The case this option exists for is a "load more" list. `?page=6` loads that
+page's 50 products through a loader, and the 250 already on screen ride along
+as location state on the link, so the next page shows them at once and
+streams the new ones:
+
+```ts
+// location-states.ts
+import { createLocationState } from "@rangojs/router";
+
+export const CarriedProducts = createLocationState<Product[]>({
+  clearOnReload: true,
+});
+```
+
+```tsx
+"use client";
+import { Link, useLoader, useLocationState } from "@rangojs/router/client";
+import { ProductsLoader } from "./loaders"; // the page named by ?page
+import { CarriedProducts } from "./location-states";
+
+export function ProductList() {
+  const { data } = useLoader(ProductsLoader);
+  const carried = useLocationState(CarriedProducts) ?? [];
+  const products = [...carried, ...data.products];
+
+  return (
+    <>
+      <ul>
+        {products.map((product) => (
+          <li key={product.id}>{product.name}</li>
+        ))}
+      </ul>
+      <Link
+        to={`/products?page=${data.page + 1}`}
+        state={[CarriedProducts(products)]}
+        scroll={false}
+      >
+        Load more
+      </Link>
+    </>
+  );
+}
+```
+
+The list is a plain concatenation. After "Load more" the next page's loader
+streams while the current page stays on screen, and `carried` stays the
+current entry's until that page lands: the carried products and the loader's
+page change in one commit, so no product is ever listed twice.
+
+Without the option, a refresh of `?page=6` renders 50 products on the server
+and then inserts the stored 250 above them. With it, the refreshed page stays
+as the server rendered it:
+
+| What happens to the entry                                                 | A `clearOnReload` slot                                               |
+| ------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| The reader mounts during a client navigation (`<Link>`, `router.push`)    | applied, as without the option                                       |
+| back/forward inside the running app (popstate), a server action's state   | applied, as without the option                                       |
+| A document load: refresh, or a back/forward that loads the document       | not applied, and removed from `history.state`                        |
+| Later on that page: a reader mounts, or a navigation returns to the entry | still `undefined`; the next write (the next "Load more") stores anew |
+| The page is restored from the browser's back/forward cache                | untouched: nothing is loaded or hydrated                             |
+
+- The rule is any document load of the entry, not only the Reload button:
+  restoring a closed tab or duplicating a tab loads the document too.
+- Only the entry being loaded is cleared. Going back from it to an earlier
+  entry inside the running app is a client navigation and applies that
+  entry's state.
+- The router removes every `~r` key when the client starts, before hydration.
+  It goes by the key alone, so it does not matter whether a reader is mounted,
+  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.
+- `.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
+  stored before, under the plain key, is no longer read (and is not removed).
+  Removing the option moves it back to the plain key; what was stored under
+  `~r` is removed at the next document load.
+- It cannot be combined with `flash`: flash state is removed at its first
+  read, so the pair could only drop a message nobody has seen yet.
+
 ### .read() (non-hook access)
 
 Read current location state outside React components (client-side only):
@@ -264,9 +463,11 @@ Static counterparts to `.read()`. Both mutate the current history entry's
 bookkeeping, other location state slots). Both are client-only; they throw
 when called on the server.
 
-Neither dispatches an event, so components reading via `useLocationState`
-will NOT re-render until the next navigation/popstate. Pair with `.read()`
-(or a fresh mount via back/forward/reload) instead.
+Neither changes what a `useLocationState` reader shows, mounted or mounting
+later: readers get the entry's state as it was committed (see "When a reader
+sees an entry's state"). The written value is there for `.read()` at once,
+and for readers when the entry is next restored (back/forward to it, or a
+reload).
 
 ```tsx
 "use client";
@@ -275,7 +476,7 @@ import { ProductState } from "./state";
 // Persisted across hard refresh and back/forward of this entry.
 ProductState.write({ name: "Widget", price: 9.99 });
 
-// Read later (or on next mount).
+// Read later.
 const current = ProductState.read();
 
 // Manually clear the slot. Idempotent if it isn't set.