@rangojs/router 0.17.0 → 0.19.0

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

@@ -373,15 +373,17 @@ old-deployment request pinning.
 The `@rangojs/router/testing/*` entry points give you `runLoader`,
 `runMiddleware`, `runInRequestContext` (server actions), `dispatch` (base
 `./testing`), `renderHandler` and real Flight rendering (`renderServerTree`,
-`findClientBoundaries`, `findElements`) from `./testing/flight`, `renderRoute`
-from `./testing/dom`, a vitest preset from `./testing/vitest`, and a Playwright
-e2e harness with dev/prod parity helpers (`parityDescribe`, `expectParity`) from
-`./testing/e2e`. You can unit-test a loader, a middleware, an action, or an RSC
-handler in isolation. Next.js and Waku ship no official primitives for testing
-server components/handlers; TanStack documents testing patterns (build your own
-harness from `createRouter`/`createMemoryHistory`) but ships no testing package,
-and nothing at the RSC-handler level. See the [testing skill](../../testing/SKILL.md)
-and [testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md).
+`findClientBoundaries`, `findElements`) plus a real PPR shell capture and HIT
+(`serveShellRequest`, `resetShellTestState`) from `./testing/flight`,
+`renderRoute` from `./testing/dom`, a vitest preset from `./testing/vitest`, and
+a Playwright e2e harness with dev/prod parity helpers (`parityDescribe`,
+`expectParity`) from `./testing/e2e`. You can unit-test a loader, a middleware,
+an action, or an RSC handler in isolation. Next.js and Waku ship no official
+primitives for testing server components/handlers; TanStack documents testing
+patterns (build your own harness from `createRouter`/`createMemoryHistory`) but
+ships no testing package, and nothing at the RSC-handler level. See the
+[testing skill](../../testing/SKILL.md) and
+[testing.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/testing.md).
 
 ### Bundle discipline
 
@@ -487,7 +489,7 @@ layout(<ShopLayout />, () => [
     "@modal",
     "product.detail",
     ProductQuickView,
-    { when: ({ from }) => from.pathname === "/products" },
+    { when: ({ from }) => from.url.pathname === "/products" },
     () => [
       loader(ProductLoader),
       loading(<QuickViewSkeleton />),
@@ -506,8 +508,10 @@ middleware, layout, loaders, loading state, and loader-level caching and
 `intercept()`) can choose by navigation source.
 
 This is integrated with the rest of the runtime rather than implemented as URL
-masking plus local component state. Intercepts get source-scoped prefetch entries
-so a modal Flight payload cannot leak into direct navigation. A prerendered target
+masking plus local component state. A route an intercept targets gets
+source-scoped prefetch entries whether or not the intercept applied, so neither a
+modal Flight payload nor a full page prefetched from another page is reused where
+the intercept decides differently. A prerendered target
 can store a separate intercept variant while its loaders still run live at
 request time. An action can revalidate the open intercept without remounting its
 subtree or forcing the preserved background to render. See the
@@ -534,10 +538,13 @@ There are two distinct things named "revalidate", and the split is deliberate:
    tabs, and pagination. See
    [shallow-navigation.md](https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/design/shallow-navigation.md).
 
-Both are separate from `revalidateTag()`/`updateTag()`, which hard-purge tagged
-cache entries. `updateTag()` is awaitable for read-your-own-writes;
-`revalidateTag()` schedules the same invalidation in the background. Neither API
-selects a client segment to render. Next.js offers `router.refresh()` (and
+Both are separate from `revalidateTag()`/`updateTag()`, which evict tagged
+cache entries; the request that calls either reads its own writes.
+`updateTag()` also awaits the durable write; `revalidateTag()` schedules it in
+the background. The mutating user's next requests skip the stores' per-isolate
+PPR shell memos via a fresh-reads cookie, and other users converge within the
+memo window and the platform's own propagation. Neither API selects a client
+segment to render. Next.js offers `router.refresh()` (and
 `refresh()` from `next/cache`) plus path/tag cache invalidation, but no per-segment
 render predicate and no typed action discrimination — and its invalidations clear
 the whole client cache rather than selecting a segment. TanStack's `shouldReload`/`router.invalidate()` is the nearest
@@ -573,7 +580,8 @@ the bounded cache uses a configurable TTL. `Save-Data`,
 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. Intercepts are automatically source-scoped,
+from repopulating an invalidated 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
 link.
@@ -620,18 +628,22 @@ this resource-aware policy layer.
 
 `createLoader(fn)` / `loader()` define **live-by-default** data units: they are
 excluded from an enclosing segment cache and resolve on every request unless the
-loader itself explicitly opts into `cache()`. They may safely read `cookies()`,
-`headers()`, request context, and `env` because loader execution is outside the
-cached shell. Loaders run in parallel, stream independently under `loading()`
-boundaries, compose server-side via `ctx.use(OtherLoader)`, and carry
-route-level authority: they can throw `notFound()`/`redirect()`, WRITE handles
-(`ctx.use(Meta)({ title })` — data-derived page metadata pushed from the data's
-producer), read handle data after the render settles (`ctx.get(handle)` behind
-`await ctx.rendered()`), and opt into `loader(Def, { ssr: false })`
-so a document render awaits them before first flush (deterministic SSR'd data,
-meta, and 404 status). Reads happen through `useLoader` in a client component
-(including its SSR pass) or `useFetchLoader` for standalone client fetches. "Fetchable" loaders are callable
-endpoints with their own middleware and GET/POST/PUT/PATCH/DELETE bodies.
+loader itself explicitly opts into `cache()`. A loader without `ssr: false` may
+safely read `cookies()`, `headers()`, request context, and `env` because its
+execution is outside the cached shell; a loader with its own `cache()` must put
+those reads in its `key()`, or its miss fails and stores nothing. On a `ppr`
+route an `ssr: false` loader bakes into the shell, so an identity read there
+refuses the capture. Loaders run in parallel, stream independently under
+`loading()` boundaries, compose server-side via `ctx.use(OtherLoader)`, and
+carry route-level authority: they can throw `notFound()`/`redirect()`, WRITE
+handles (`ctx.use(Meta)({ title })` — data-derived page metadata pushed from the
+data's producer), read handle data after the render settles (`ctx.get(handle)`
+behind `await ctx.rendered()`), and opt into `loader(Def, { ssr: false })` so a
+document render awaits them before first flush (deterministic SSR'd data, meta,
+and 404 status). Reads happen through `useLoader` in a client component
+(including its SSR pass) or `useFetchLoader` for standalone client fetches.
+"Fetchable" loaders are callable endpoints with their own middleware and
+GET/POST/PUT/PATCH/DELETE bodies.
 
 One sharp edge is worth stating because the distinction matters: a cached handler
 can call `await ctx.use(Loader)`, but if it renders that result inline, it bakes the
@@ -681,7 +693,7 @@ a fully prerendered route. Caching loader data is a separate, explicit opt-in on
 that loader.
 
 The mechanism is concrete: a prerendered route serves its baked Flight shell from
-the store, then `resolveLoadersOnly()` resolves the loaders through their own
+the store, then the router resolves the loaders through their own
 freshness policy at request time and merges their segments into that replayed
 shell. With the default policy you get a cached/prerendered shell plus live data,
 automatically, with no per-route static-vs-dynamic decision. The loader is the
@@ -692,7 +704,8 @@ designated live data slot in a cache-first RSC tree.** Several properties follow
 that no loader-before-render has:
 
 - it is the **cache-safety escape hatch** — the only place request-coupled reads
-  are allowed inside a cache scope, because it is the part guaranteed to re-run;
+  are allowed inside a cache scope, because it is the part guaranteed to re-run
+  (a loader without `ssr: false` and without its own unkeyed `cache()`);
 - it is **standalone and composable**, not route-coupled — one `createLoader()`
   read by many segments, composed via `ctx.use`, or exposed as a fetchable endpoint;
 - it **streams as a hole, not a gate** — concurrent, Suspense-resolved under
@@ -744,7 +757,7 @@ from two hosts, route scopes, param sets, or query variants therefore does not
 collapse into one entry just because both calls received a `ctx` object.
 
 The same boundary guards operations whose meaning cannot survive a hit. Direct
-`cookies()`/`headers()` reads and request/response mutations such as `ctx.set()`,
+`cookies()`/`headers()`/`ctx.request.headers` reads and request/response mutations such as `ctx.set()`,
 `ctx.header()`, status, theme, and location-state writes throw inside
 `"use cache"`. If a cached function pushes typed handles through
 `ctx.use(Breadcrumbs)` or `ctx.use(Meta)`, Rango captures those pushes on a miss and
@@ -773,11 +786,13 @@ safe rule remains simple: read request-specific context at the live point of use
 normally a loader, rather than deriving it outside and carrying it into a cached
 shell.
 
-This is where the taint and loader designs meet. Loaders are the sanctioned dynamic
-holes: they run outside the enclosing segment cache and may read the current
-request, while the shared shell remains protected. Next.js also isolates runtime
-APIs from ordinary `"use cache"`, and React's optional taint APIs protect values at
-the server-to-client serialization boundary. Those are useful but different
+This is where the taint and loader designs meet. Loaders are the sanctioned
+dynamic holes: they run outside the enclosing segment cache and may read the
+current request (except, on a `ppr` route, an `ssr: false` loader or a loader a
+handler awaits, which the capture runs and refuses on such a read), while the
+shared shell remains protected. Next.js also isolates runtime APIs from ordinary
+`"use cache"`, and React's optional taint APIs protect values at the
+server-to-client serialization boundary. Those are useful but different
 contracts; they do not provide Rango's route-aware tainted-argument keying,
 non-cacheable typed context variables, handle capture/replay, and loader escape
 path as one system. TanStack Start and Waku leave this boundary primarily to

package/skills/defer-hydration/SKILL.md

@@ -15,7 +15,7 @@ storefront homepage (shell HIT, production build, M-series laptop): a single
 was dead for ~11s. Fast paint, frozen page.
 
 The obvious fix — wrap the heavy subtree in `<Suspense>` so it hydrates later —
-trades the paint away: under shell capture that boundary postpones, and the
+can trade the paint away: when that boundary postpones under shell capture, the
 frozen prelude ships an empty `<main>`. This recipe gets both: the full body
 HTML in the prelude AND its hydration off the initial task, released on first
 idle at retry-lane priority.
@@ -28,7 +28,9 @@ idle at retry-lane priority.
 | interactive (menu click works)   | ~3.5s    | ~1.6s                            | ~1.6s                     |
 
 Measure your own page before and after — the win depends on how much of the
-hydration cost lives under the boundary (see "Verifying and measuring").
+hydration cost lives under the boundary (see "Verifying and measuring"). These
+numbers were measured before PPR captures baked handler output; see the next
+section for what that changed.
 
 ## The recipe
 
@@ -102,23 +104,39 @@ inside hydrates after first idle.
 
 ## Why `fallback={children}` is load-bearing
 
-This is not a style choice; it is the half of the recipe that makes it
-PPR-compatible.
-
-Shell capture aborts on flight byte-quiet (`src/rsc/shell-capture.ts`,
-`FLIGHT_QUIET_HOPS`): once the Flight source has been byte-silent for the
-quiet window, the fizz render freezes. A big HTML subtree under _any_
-`<Suspense>` boundary cannot finish inside that window, so the boundary always
-postpones — boundary placement cannot fix it. Verified both ways: wrapping the
-client island from outside AND placing the boundary inside the island both
-baked `<!--$?--><template id="B:…">` into `<main>`, i.e. an empty body in the
-frozen prelude.
-
-With the content as the fallback, the unavoidable postpone _becomes the
-delivery mechanism_: the shell bakes the fallback, and the fallback IS the
-body. In `/ppr` hole-doctrine terms, this is the PHYSICS class exploited
-deliberately — you cannot stop the boundary from becoming a hole, so you make
-the hole's baked fallback carry the real markup.
+This is not a style choice. The recipe was built when the shell capture
+postponed any big `<Suspense>` subtree: the capture froze on Flight byte-quiet
+(`FLIGHT_QUIET_HOPS` in `src/rsc/shell-capture.ts`) while the handler output
+was still rendering, so a boundary over the page body became a hole no matter
+where it sat. Verified both ways at the time: wrapping the client island from
+outside AND placing the boundary inside the island both baked
+`<!--$?--><template id="B:…">` into `<main>`, i.e. an empty body in the frozen
+prelude. With the content as the fallback, the postpone became the delivery
+mechanism: the shell baked the fallback, and the fallback was the body.
+
+PPR captures now wait for the whole handler layer before freezing anything:
+the capture records the page's segments first (async server components
+rendered, every promise in the handler output settled) and renders its Flight
+payload from that record (`settleCaptureRecord` in `src/rsc/shell-capture.ts`).
+A boundary whose content is only handler output is therefore expected to bake
+its content as a completed boundary instead of postponing. What still
+postpones at capture is a boundary over live data: a loader without
+`ssr: false` read with `useLoader` under `loading()` or an inline
+`<Suspense>`, or a promise nested in an `ssr: false` loader's value. Run the
+prelude check in "Verifying and measuring" on your page rather than assuming
+either shape.
+
+`fallback={children}` stays the safe choice either way:
+
+- If the boundary still postpones (live data inside it), the fallback is what
+  the prelude shows, so it must be the content.
+- The sync-update trap below: a client render of the boundary shows the
+  fallback. With `fallback={children}` that is a visual no-op; with
+  `fallback={null}` it blanks the page.
+
+The hydration deferral does not depend on which shape you get: `HydrationGate`
+suspends during hydration, and React keeps the server DOM of the boundary in
+place until the gate releases.
 
 ## Why the client gate is free
 
@@ -164,13 +182,14 @@ release on interaction instead (see Variations).
 
 ## Known cost: the body rides twice (measure it, don't guess)
 
-On a shell HIT the gated subtree's HTML is in the response twice — once as the
-baked fallback in the prelude, once as the resumed hole content (the resume
-re-renders and re-ships it; there is no bake-through). Homepage measurement:
-234KB → 302KB gzipped (+68KB, +29%; raw +1.05MB). It is post-paint bandwidth,
-not render-blocking — the visible prelude streams first — but it is real bytes
-on every document GET. Weigh it per page; on a small body the recipe may not
-pay for itself.
+When the boundary postpones at capture, a shell HIT carries the gated
+subtree's HTML twice — once as the baked fallback in the prelude, once as the
+resumed hole content (the resume re-renders and re-ships it; there is no
+bake-through). Homepage measurement (postponing boundary): 234KB → 302KB
+gzipped (+68KB, +29%; raw +1.05MB). It is post-paint bandwidth, not
+render-blocking — the visible prelude streams first — but it is real bytes on
+every document GET. Weigh it per page; on a small body the recipe may not pay
+for itself. A boundary that bakes its content ships it once.
 
 ## Verifying and measuring
 
@@ -230,7 +249,8 @@ this exact space. The recipe survives that future; a primitive might not.
 
 ## Related
 
-- `/ppr` — the shell/hole mechanics this recipe rides on (hole doctrine:
-  PHYSICS class), and why the capture postpones any big Suspense subtree
-- `src/rsc/shell-capture.ts` — the byte-quiet capture window
-  (`FLIGHT_QUIET_HOPS`) that makes `fallback={children}` mandatory
+- `/ppr` — the shell/hole mechanics this recipe rides on: what bakes into the
+  shell, and which boundaries stay holes
+- `src/rsc/shell-capture.ts` — the record-first capture (`settleCaptureRecord`)
+  and the byte-quiet window (`FLIGHT_QUIET_HOPS`) that decide what the prelude
+  holds

package/skills/deployment-caching/SKILL.md

@@ -56,8 +56,11 @@ There are two shell producers:
 Both producers feed the same in-function serve path. Build-time shells are
 content-hashed modules in the server bundle, not CDN-served HTML files.
 
-`ppr.ttl`, `ppr.swr`, and `ppr.tags` govern that shell entry. They do **not**
-emit HTTP `Cache-Control` and do not configure a platform CDN.
+`ppr.ttl` and `ppr.swr` set the shell entry's lifetime, capped by the route
+`cache()` entry it was captured from (the shorter wins). Its tags are
+`ppr.tags` plus the tags its content recorded. A route `cache({ key })` or a
+store `keyGenerator` stores one shell per partition value. None of this emits
+HTTP `Cache-Control` or configures a platform CDN.
 
 ## Platform deployment shapes
 

package/skills/document-cache/SKILL.md

@@ -205,7 +205,10 @@ the variant suffixes are still appended.
 - Responses whose `Cache-Control` also contains `private`, `no-store`, or an
   unqualified `no-cache` (those win over `s-maxage` in a shared cache)
 - Responses carrying `Set-Cookie` (a per-client value must not be replayed to
-  everyone)
+  everyone). That includes a response whose request called
+  `updateTag()`/`revalidateTag()` on a store that keeps per-isolate memos
+  (`CFCacheStore`, `VercelCacheStore`): it carries the fresh-reads cookie
+  (`rango-state-fresh` by default), so it is not stored.
 - 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
@@ -216,6 +219,30 @@ the variant suffixes are still appended.
   error during the render. The current request still gets the errored render,
   the next request renders fresh, and on a stale refresh the stale entry keeps
   serving.
+- A page rendered with a visitor's stored theme other than `defaultTheme`.
+  That happens only when `Cache-Control` was set after the render (see
+  "Theme" below).
+
+## Theme
+
+With `theme` enabled, the page payload carries the theme `useTheme()` starts
+at (`initialTheme`). A page whose response opted in to this cache before
+`next()` starts it at the no-cookie default (`defaultTheme`), whoever rendered
+it (#978), so a visitor with no stored theme never inherits the theme of the
+visitor who warmed the entry. A visitor with a stored theme sees theirs after
+hydration, and the `<html>` class is right before paint either way (the theme
+script reads the cookie). Any other render, a 404 included, starts at the
+visitor's own theme.
+
+The render decides from the `Cache-Control` the handler or middleware set
+before `await next()`. A header set after `next()` (or in `onResponse`) arrives
+once the page is rendered, so the cache stores that response only when it was
+rendered with the default theme. Set `Cache-Control` in the handler or before
+`next()` so every visitor's miss can fill the entry.
+
+A handler that reads `ctx.theme` on a stored route is not guarded: the stored
+document shows that visitor's theme to everyone. Read the theme with
+`useTheme()` instead (see `/theme`).
 
 ## Invalidation
 
@@ -224,7 +251,10 @@ with the request's tag set, so `updateTag()`/`revalidateTag()` evict them:
 
 - a render-callable `cacheTag("...")` in any server component on the page;
 - tags of `cache()` segments, cached loaders, and `"use cache"` functions the
-  render read.
+  render read. A `cache()` segment HIT contributes the tags its content
+  recorded when it was written (render-callable calls and `"use cache"` reads
+  inside it), so a document stored over the HIT stays evictable by them. A
+  cached loader's HIT likewise contributes the tags its body recorded.
 
 Tags are snapshotted after the response body has fully streamed, so tags from
 Suspense-streamed content are included. A `Prerender()` route's build-time

package/skills/handler-use/SKILL.md

@@ -184,6 +184,8 @@ parallel({
 });
 ```
 
+On a `ppr` route, a slot's `loading()` over handler output does not make a hole. A slot handler that awaits `ctx.use(CartLoader)` is handler output: it runs at capture, its value is baked into the shared shell, and every HIT replays it without running the handler. A `cookies()`/`headers()` read in that loader refuses the capture, so the route stays on MISS. For a per-request slot, read the loader with `useLoader()` in a `"use client"` component under the slot's `loading()` (see `/ppr` → "The layout-with-loaders playbook").
+
 ### Two scopes for explicit `use` at the mount site: shared (broadcast) and slot-local
 
 `parallel()` accepts an explicit `use()` callback that **broadcasts** to every slot in the call ([dsl-helpers.ts](../../src/route-definition/dsl-helpers.ts)). That's the right behavior for the items the parallel allow-list permits and that accumulate (`loader`, `revalidate`, `errorBoundary`, `notFoundBoundary`, `transition`) — every slot gets them. (Note: `middleware` is not allowed inside `parallel()`; see the allowed-types table above.)

package/skills/hooks/SKILL.md

@@ -66,7 +66,9 @@ the one for your case.
   Rango-specific hook for tracking actions called outside a
   `<form action={...}>` flow.
 - [`./state.md`](./state.md) — `useLocationState` (persistent + flash state,
-  `.read()`/`.write()`/`.delete()`), `invalidateClientCache()`.
+  `.read()`/`.read(location)`/`.write()`/`.delete()`, typed `state` on `router.push()` /
+  `router.replace()`, serializability errors that name the failing field),
+  `invalidateClientCache()`.
 - [`./outlets.md`](./outlets.md) — `Outlet`, `ParallelOutlet`, `useOutlet`.
 - [`./urls.md`](./urls.md) — `useParams`, `usePathname`, `useSearchParams`,
   `useHref`, `useMount`, `useReverse`.

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

@@ -34,7 +34,9 @@ Writers: handlers AND loader bodies — `ctx.use(Handle)` returns the push
 function in each (middleware has no handle APIs). Loader pushes follow a delivery race (settle before
 the handler barrier → in the SSR'd document; later → applied client-side), and
 `loader(Def, { ssr: false })` makes them deterministic in the
-document. See `/loader` → "Writing Handles from Loaders". `useHandle`
+document. On a `ppr` shell HIT, a loader without `ssr: false` never ran during
+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.
 
 Handles can be passed as props from server to client components:

package/skills/hooks/navigation.md

@@ -67,8 +67,10 @@ function NavigationControls() {
 | `forward()`              | `history.forward()`.                                                                                            |
 
 `push` / `replace` options: `scroll` (`false` keeps the current scroll
-position), `revalidate` (default `true`, see below), and `state` (location
-state, see [`./state.md`](./state.md)).
+position), `revalidate` (default `true`, see below), `transition` (`false`
+skips the route's `transition()` for this navigation, see below), and `state`
+(location state: `[MyState(value)]` for typed entries, or plain
+structured-clone-safe data; see [`./state.md`](./state.md)).
 
 Target resolution: a path starting with `/` is app-absolute and gets the
 router `basename` prefixed. A relative path (`"cart"`, `"./cart"`) resolves
@@ -95,6 +97,25 @@ If the pathname changes, `revalidate: false` is silently ignored and a full navi
 
 Plain `<a>` tags can opt in via `data-revalidate="false"`.
 
+#### Skipping the transition
+
+Pass `transition: false` to present one navigation without the route's
+`transition()`: the commit is urgent (the `loading()` skeleton streams) and no
+view transition runs, the same result as a `transition({ when })` predicate
+returning `false`. No predicate is called. Back/forward, actions and
+revalidation are unaffected.
+
+```tsx
+router.push("/photos/2", { transition: false });
+
+<Link to="/photos/2" transition={false}>
+  Next
+</Link>;
+```
+
+Plain `<a>` tags can opt in via `data-transition="false"`. See
+`/view-transitions` → "Conditional transitions".
+
 ### useSegments()
 
 Access current URL path and matched route segments:

package/skills/hooks/state.md

@@ -12,6 +12,9 @@ import { useLocationState, createLocationState } from "@rangojs/router/client";
 
 // Define typed state (all export patterns supported)
 // Keys are auto-injected by the Vite plugin -- no manual key needed.
+// In a unit test (no plugin), key it with withLocationStateKey(ProductState,
+// "ProductState") from @rangojs/router/testing: outside production, an
+// unkeyed definition throws on first use.
 export const ProductState = createLocationState<{
   name: string;
   price: number;
@@ -81,8 +84,87 @@ definition:
 const state = useLocationState<{ from?: string }>(); // { from?: string } | undefined
 ```
 
+### State on router.push() / router.replace()
+
 The same `state` option exists on `router.push()` / `router.replace()` (see
-[`./navigation.md`](./navigation.md)).
+[`./navigation.md`](./navigation.md)), with the same type as `<Link state>`
+(minus the click-time getter): `HistoryState`, which is
+`readonly LocationStateEntry[]` (typed entries) or `PlainHistoryState` (plain,
+structured-clone-safe data). Both types are exported from
+`@rangojs/router/client`.
+
+```tsx
+"use client";
+import { useLocationState, useRouter } from "@rangojs/router/client";
+import { GridState } from "./state"; // createLocationState<{ count: number }>()
+
+function LoadMore() {
+  const router = useRouter();
+  const grid = useLocationState(GridState);
+  const count = grid?.count ?? 20;
+  return (
+    <button
+      onClick={() =>
+        router.replace("?page=2", { state: [GridState({ count: count + 20 })] })
+      }
+    >
+      Load more
+    </button>
+  );
+}
+```
+
+Typed entries always go in an array, with nothing else in it. Three mistakes
+are compile errors:
+
+```tsx
+router.push(url, { state: GridState({ count: 3 }) }); // entry without the array
+router.push(url, { state: [GridState] }); // definition, not called
+router.push(url, { state: [GridState({ count: 3 }), { from: "list" }] }); // mixed
+```
+
+Without the array, the entry's own `__rsc_ls_*` fields would land on
+`history.state` and `useLocationState(GridState)` would read `undefined`; an
+uncalled definition throws `DataCloneError` in `history.pushState`; in a mixed
+array only the first element picks the format, so the rest are lost. For
+untyped (JS) callers, development builds throw an error for each that names
+the definition's key (or the offending index) and the fix.
+
+Plain state is checked at the top level only. It rejects functions, symbols,
+`Promise`, `WeakMap`, `WeakSet`, and values typed `unknown` (narrow an
+`unknown` value, or annotate it as `PlainHistoryState`). Array, `Map`, and
+`Set` elements are checked the same way, but plain object members are not.
+These still compile and still throw `DataCloneError` at `history.pushState`:
+
+- a function, symbol, or React element inside a plain object
+  (`{ onClose: () => {} }`);
+- a top-level `ReactElement` or DOM node (`HTMLElement`), which look like
+  plain objects to the type.
+
+Store plain data and rebuild the rest on arrival, or use a typed
+`createLocationState<T>()` definition, whose `T` is checked all the way down.
+
+### When a type fails the serializability check
+
+`createLocationState<T>()` rejects values that cannot survive
+`history.state`'s structured clone: functions, class constructors, symbols,
+React/RSC content, and fields typed `unknown`. The compile error names the
+failing field and the reason:
+
+```
+Argument of type '{ items: never[]; cursor: string; }' is not assignable to
+parameter of type '... & LocationStateUnsafe<"`unknown` cannot be verified as
+serializable; give it a concrete type", "items[].info.values">'.
+```
+
+The path uses `.` for fields, `[string]` / `[number]` for index signatures
+(`Record<string, T>`), `[]` for array and `Set` elements, `[0]` for tuple
+elements, `<key>` / `<value>` for `Map` keys and values, and `<root>` when the
+value itself is unsafe. A field typed `any` is never reported. When several fields fail, the error lists one `LocationStateUnsafe` per
+path. An object's own unsafe fields are reported before anything nested
+deeper, so a class instance or DOM node stops at its methods
+(`row.el.click`); fix those and the next compile names the rest. The walk
+stops 8 levels deep, reporting the deepest path it reached.
 
 ### Flash State (read-once)
 
@@ -160,6 +242,15 @@ const flash = FlashMessage.read();
 const product = ProductState.read();
 ```
 
+`.read(location)` reads this definition's slot from any `{ state }` snapshot
+instead of the current entry, such as the `from` / `to` of a
+`transition({ when })` context. It works without `window` and never clears
+flash state:
+
+```tsx
+transition({ when: ({ to }) => ProductState.read(to) !== undefined });
+```
+
 > **Hydration:** `.read()` returns `undefined` on the server but may return
 > a real value on the first client render (history state survives reload).
 > Do not call `.read()` directly during the initial render of a component;
@@ -191,11 +282,12 @@ const current = ProductState.read();
 ProductState.delete();
 ```
 
-| Method      | Updates `history.state` | Fires `useLocationState` rerender | SSR behavior        |
-| ----------- | ----------------------- | --------------------------------- | ------------------- |
-| `.read()`   | no                      | n/a (returns snapshot)            | returns `undefined` |
-| `.write()`  | yes (replace this slot) | no                                | throws              |
-| `.delete()` | yes (remove this slot)  | no                                | throws              |
+| Method            | Updates `history.state` | Fires `useLocationState` rerender | SSR behavior        |
+| ----------------- | ----------------------- | --------------------------------- | ------------------- |
+| `.read()`         | no                      | n/a (returns snapshot)            | returns `undefined` |
+| `.read(location)` | no                      | n/a (reads the given snapshot)    | reads the snapshot  |
+| `.write()`        | yes (replace this slot) | no                                | throws              |
+| `.delete()`       | yes (remove this slot)  | no                                | throws              |
 
 ## Cache Control
 
@@ -214,7 +306,9 @@ it is selected by export conditions:
   a rotated state `Set-Cookie` for the responding client, which marks its
   caches stale when it next reads them. Idempotent within a request; throws
   inside a `cache()` / `"use cache"` boundary; a no-op with a dev warning
-  outside a request.
+  outside a request. On a `ppr` route a shell HIT runs no handler, so a call
+  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