@rangojs/router 0.20.0 → 0.22.0

package/skills/loader/SKILL.md

@@ -612,6 +612,10 @@ included. A handler's `ctx.use(Loader)` read never caches by itself (see
 body, gets the binding's value: one value per loader per request, a HIT
 included. A reader that runs before the binding starts (a layout's loader
 reading a route's cached loader) gets the value of its own run, as before.
+This is by design: that loader runs live while the binding serves its entry,
+so its data and its handle push can come from different runs on that request.
+To keep them together, declare the cached loader first or read it from the
+handler.
 
 The loader's data is cached independently from the route's segment cache,
 using the same `SegmentCacheStore` (app-level or per-loader override).
@@ -648,11 +652,21 @@ rejects) skips the whole entry, as above. Entries written
 before handles were recorded replay none until they are rewritten (expiry or
 SWR revalidation).
 
+On a `ppr` route the shell keeps a copy of an `ssr: false` loader's settled
+pushes too. The two never disagree on the page: where a replay of the shell
+serves the loader's data from the shell, the shell's copy is the one shown
+and the entry only adds the deferred push the shell could not keep; where it
+does not (the loader runs or reads its entry), the entry's pushes take the
+shell copy's place, none if the entry recorded none. See `/ppr` → "On a shell
+HIT".
+
 ### Cache Key
 
-The default cache key is `loader:{loaderId}:{host}{pathname}:{sortedParams}`
-(the host keeps multi-tenant hosts from sharing entries). This can be customized
-at two levels:
+The default cache key is
+`loader:{loaderId}:{routerId}@{host}{pathname}:{sortedParams}`: the host keeps
+multi-tenant hosts from sharing entries, and the router id keeps two routers
+that mount the loader on one store apart (see `/host-router`, "Shared cache
+store"). This can be customized at two levels:
 
 ```typescript
 import { cookies } from "@rangojs/router";
@@ -676,7 +690,7 @@ Resolution priority (same order as route-level `cache()`):
    `loader:{loaderId}:key:` plus the result's URI encoding
 2. `store.keyGenerator(ctx, defaultKey)` — store-level modification, stored
    as returned
-3. Default key — `loader:{loaderId}:{host}{pathname}:{sortedParams}`
+3. Default key — `loader:{loaderId}:{routerId}@{host}{pathname}:{sortedParams}`
 
 Because the `key()` result is namespaced by the loader id, no value it
 returns, request input included, can name another loader's entry or a
@@ -993,7 +1007,13 @@ on document loads (`metadata.handlesLate`) or progressively on navigations.
 A push before your slow fetch usually beats the barrier; a push derived from
 the fetched data usually does not. When it MUST be in the document, use
 `ssr: false` below. A loader with its own `cache()` keeps its pushes on a hit —
-they are replayed from the entry (see "Opting a Loader into Caching").
+they are replayed from the entry (see "Opting a Loader into Caching"). On a
+`ppr` route the race does not apply to a document served from its shell:
+there every push a loader makes on that request applies post-hydration (see
+`/ppr`, "Handles on a shell HIT"). A `useHandle` reader inside this loader's
+`loading()` or `<Suspense>` hydrates with the data its HTML was rendered
+from and shows a later push right after, so a push after an `await` causes
+no hydration mismatch there.
 
 Under `cache()`, loader pushes are not stored with the cached segments: the
 loader re-runs on every hit and its live push is the only copy. (`ppr` keeps

package/skills/middleware/SKILL.md

@@ -426,6 +426,8 @@ export const requireAuthMiddleware: Middleware = async (ctx, next) => {
 
 Read the flash on the target page with `useLocationState(FlashMessage)`. The `{ flash: true }` option makes it auto-clear after first render. See `/hooks`.
 
+A redirect is followed on a link click, `router.push()`, and Back/Forward to an entry the client has to fetch. On Back/Forward the redirect replaces the history entry it was triggered from: Back from the target lands on the entry before the redirecting one, not on the redirecting one again. The client follows at most 20 redirects in one navigation; a loop (two pages redirecting to each other) stops there with the error boundary and a `[rango] Server redirect loop` console error.
+
 ## Authentication Middleware
 
 ```typescript

package/skills/migrate-nextjs/SKILL.md

@@ -416,13 +416,82 @@ default) or serves an open-ended param space. See `/prerender` for full API.
 
 Next.js route segment config maps onto Rango's explicit primitives:
 
-| Next.js segment config                              | Rango                                                        |
-| --------------------------------------------------- | ------------------------------------------------------------ |
-| `dynamic = "force-static"` + `generateStaticParams` | `Static()` / `Prerender()` (see `/prerender`)                |
-| `revalidate = 60` (ISR)                             | `cache({ ttl: 60, swr: ... })` on the route (see `/caching`) |
-| `dynamic = "force-dynamic"`                         | the default — routes are dynamic unless you cache them       |
-| `dynamicParams = true`                              | `Passthrough()` (above)                                      |
-| `experimental_ppr = true`                           | the `ppr` path option (below, and `/ppr`)                    |
+| Next.js segment config                              | Rango                                                                                                                     |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `dynamic = "force-static"` + `generateStaticParams` | `Static()` / `Prerender()` (see `/prerender`)                                                                             |
+| `revalidate = 60` (ISR)                             | `cache({ ttl: 60, swr: ... })` on the route (see `/caching`), or on-demand prerender with `onDemand: { ttl: 60 }` (below) |
+| `dynamic = "force-dynamic"`                         | the default — routes are dynamic unless you cache them                                                                    |
+| `dynamicParams = true`                              | `Passthrough()` (above)                                                                                                   |
+| `experimental_ppr = true`                           | the `ppr` path option (below, and `/ppr`)                                                                                 |
+
+### On-demand ISR → `Prerender(..., { onDemand })` + `router.prerender()`
+
+A Next.js page with `generateStaticParams` refreshed by `revalidatePath()` or
+`revalidateTag()` from a CMS webhook maps to an on-demand prerender route. The
+route opts in, a store holds refreshed payloads, and the webhook re-renders the
+page instead of invalidating it:
+
+```typescript
+// Next.js:
+export const revalidate = 3600;
+export async function generateStaticParams() {
+  return (await getFeatured()).map((p) => ({ id: p.id }));
+}
+// app/api/revalidate/route.ts
+revalidatePath(`/products/${id}`);
+revalidateTag(`product:${id}`);
+
+// Rango:
+export const ProductPage = Prerender<{ id: string }>(
+  async () => (await getFeatured()).map((p) => ({ id: p.id })),
+  async (ctx) => <Product data={await getProduct(ctx.params.id)} />,
+  { onDemand: { ttl: 3600, tags: ({ params }) => [`product:${params.id}`] } },
+);
+
+// router: createRouter({ prerender: { store, ttl, onRevalidate? } })
+// webhook (route handler, cron or queue):
+const prerender = router.prerender({ env, ctx });
+await prerender(`/products/${id}`); // revalidatePath
+await prerender.markStale([`product:${id}`]); // revalidateTag
+```
+
+| Next.js                               | Rango                                                                                               |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `revalidatePath(path)` on an ISR page | `await router.prerender({ env, ctx })(path)`: renders now, serves the new payload next request      |
+| `revalidateTag(tag)` on ISR pages     | `router.prerender({ env, ctx }).markStale([tag])`: marks only; a stale hit schedules `onRevalidate` |
+| `revalidate = N` (time-based ISR)     | `onDemand: { ttl: N }` + `onRevalidate`; `ttl` is soft, entries never expire                        |
+| `dynamicParams = false`               | plain on-demand `Prerender`: an unknown param 404s until something refreshes it                     |
+| `dynamicParams = true`                | wrap it in `Passthrough()`: unknown params render live until refreshed                              |
+
+A page whose item was deleted. In the Pages Router, `getStaticProps` returns
+`{ notFound: true }` on a revalidation: "With `notFound: true`, the page will
+return a `404` even if there was a successfully generated page before. This is
+meant to support use cases like user-generated content getting removed by its
+author. Note, `notFound` follows the same `revalidate` behavior described
+here." In Rango a `notFound()` anywhere in the on-demand render (the route
+handler, a layout or slot handler, any server component) does the same on the
+next `prerender(path)`: the result is `{ ok: true, status: "removed" }`, the
+page answers 404 instead of the page or its build-time entry, and the removal
+is rechecked per the route's `ttl`, as Next's is per `revalidate`. When the
+data source may be failing, throw anything else: that keeps the page.
+`prerender.remove(path)` removes without rendering, for a webhook that already
+knows the item is gone, and is permanent until a `prerender(path)` renders the
+page again. See `/prerender` → "Remove a page".
+
+Three differences to plan for:
+
+- Prerender tags are their own namespace. `updateTag()` / `revalidateTag()`
+  from `@rangojs/router` purge the runtime cache and never reach on-demand
+  entries; `markStale()` never reaches the runtime cache.
+- A refresh is requestless: `cookies()` / `headers()` in the page make it
+  return `skipped-personalized`, and `ctx.env` is the live env you pass.
+- `markStale()` does not re-render: without `onRevalidate` or a cron calling
+  `prerender(target, { onlyIfStale: true })` (the runner from
+  `router.prerender({ env, ctx })`), a marked page keeps
+  serving its old payload.
+
+See `/prerender` → "On-demand refresh (ISR)" for the store options, the serve
+table and the rules.
 
 ### Partial prerendering → the `ppr` path option
 
@@ -552,7 +621,9 @@ cookie (`rango-state-fresh`); other users, and other locations on
 propagates (`/caching` → "The fresh-reads cookie").
 Built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`, `VercelCacheStore`)
 index by tag. Next's
-`revalidatePath` has no path-based equivalent — tag the relevant entries instead.
+`revalidatePath` has no path-based equivalent for runtime-cached data — tag the
+relevant entries instead. For a prerendered ISR page it is
+`router.prerender({ env, ctx })(path)` (see "On-demand ISR" above).
 
 **2. Partial-render selection (which segments re-run after an action).** This is
 NOT cache invalidation — it is `revalidate()`, controlling which segments
@@ -594,7 +665,9 @@ When migrating:
 
 - `revalidateTag(tag)` → `await updateTag(tag)` (in a server action) or
   `revalidateTag(tag)` (in a route handler / webhook). Effectively 1:1.
-- `revalidatePath(path)` → no path-based equivalent; tag the entries on that
+- `revalidatePath(path)` on an ISR page → `router.prerender({ env, ctx })(path)`
+  (on-demand prerender, §3); on runtime-cached data, no path-based
+  equivalent; tag the entries on that
   route (`cache({ tags })` / `cacheTag(...)`) and invalidate by tag.
 - To also force specific segments to re-render after the action (independent of
   cache busting), attach a `revalidate()` rule at those segment boundaries.

package/skills/ppr/SKILL.md

@@ -53,7 +53,8 @@ implements the shell family (`getShell`/`putShell`): `MemorySegmentCacheStore`
 `VercelCacheStore` (Vercel Runtime Cache). A ppr route on a store without the
 family renders normally (no shell) with a once-per-key warning. A custom store
 returns each `ShellCacheEntry` field as `putShell` received it, including
-`buildVersion` and `snapshot` (both required; the snapshot can be empty).
+`buildVersion` (the router's document version) and `snapshot` (both required;
+the snapshot can be empty).
 
 ```typescript
 import { createRouter, urls } from "@rangojs/router";
@@ -169,7 +170,7 @@ The partition follows nested scopes (issue #970): a `ppr` route under a
 inner boundary has none, and by both composed (outermost first, joined by
 `|`) when it has its own. Each `key()` result is namespaced as `key:` plus
 its URI encoding (issue #975), exactly as in the record key, so the shell of
-`key: () => "tier:gold"` is `<host><path>:shell|key%3Atier%253Agold`. The
+`key: () => "tier:gold"` is `<router>@<host><path>:shell|key%3Atier%253Agold`. The
 route's record adds the inner boundary's own default key when it has no
 `key`; the shell partition does not, since the shell key already carries the
 URL (a store `keyGenerator`'s result is kept when it adds anything, an
@@ -219,10 +220,10 @@ does not render from: otherwise the first variant captured is served for every
 value of it.
 
 In tests, `serveShellRequest` reports the key the serve path resolved
-(`result.key`, partition included); `shellCacheKey(url, searchParams,
+(`result.key`, partition included); `shellCacheKey(router, url, searchParams,
 partition)` builds the same key from the `key()` result, namespacing it as
 production does. Under nested keyed scopes, pass the `key()` results as an
-array, outermost first (`shellCacheKey(url, undefined, ["tier:gold",
+array, outermost first (`shellCacheKey(router, url, undefined, ["tier:gold",
 "v:a"])`); for a store `keyGenerator` partition pass
 `{ keys, generated }` (`/testing`, `cache-prerender.md`).
 
@@ -250,7 +251,9 @@ under `cache()` and under the shell alike.
 
 Invalidation crosses layers: `updateTag()`/`revalidateTag()` reach segment,
 shell, loader, and item entries in the same store, and shell entries
-additionally self-invalidate on `React.version` change.
+additionally self-invalidate on `React.version` change and when the router's
+document version changes (server code, SSR output, client asset names, `base`
+or Prerender payloads changed), not on every deploy.
 
 ## The serve pipeline: commit after ALL middleware
 
@@ -261,7 +264,7 @@ On a document GET to a ppr route the router runs:
    DSL `middleware()`; both are guards, and the COMMIT POINT is after all of
    them: any rejection/redirect/401 wins before a single shell byte, on MISS
    and on a warmed HIT alike;
-3. **shell lookup** — `getShell(key)` on the app store (key =
+3. **shell lookup** — `getShell(key)` on the app store (key = router id +
    host+pathname+sorted search). `CFCacheStore` stores the entry prelude-first
    and the serve path reads only its head and prelude here, with the tag-marker
    read running alongside; the capture snapshot is read off the commit path.
@@ -383,10 +386,12 @@ encountered by the shell capture.
 Two more decisions are made before any shell-store read, so probes and
 prerendered routes never spend passive `getShell` I/O:
 
-- A partial request carrying neither `X-RSC-Router-Client-Path` nor `Referer`
-  (a curl probe, a synthetic monitor) can never produce a partial match; it
-  reports `BYPASS; reason=no-navigation-context`. Alert on replay hit-rate
-  with this in mind — such probes are not cache misses.
+- A partial request carrying neither `X-RSC-Router-Client-Path` nor a
+  same-origin `Referer` (a curl probe, a synthetic monitor) can never produce
+  a partial match; it reports `BYPASS; reason=no-navigation-context`. A
+  `Referer` on another origin counts as absent: only its pathname would be
+  matched, as if it were a route of this app. Alert on replay hit-rate with
+  this in mind — such probes are not cache misses.
 - A `Prerender()` route's partial is served from the build-time prerender
   store inside matching (a better-than-HIT outcome); it reports
   `BYPASS; reason=prerender-store`. Its captures never record the page's
@@ -436,7 +441,7 @@ The bounded bypass tokens, grouped by when they are decided:
 | Token                                                                         | Decided           | Meaning                                                                                                                                                                                                              |
 | ----------------------------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `method`, `dynamic`, `nonce`, `store-unavailable`, `passive-read-unsupported` | pre-read          | request/route/store ineligible for replay                                                                                                                                                                            |
-| `no-navigation-context`                                                       | pre-read          | no `X-RSC-Router-Client-Path`/`Referer`; a partial match is impossible                                                                                                                                               |
+| `no-navigation-context`                                                       | pre-read          | no `X-RSC-Router-Client-Path` and no same-origin `Referer`; a partial match is impossible                                                                                                                            |
 | `prerender-store`                                                             | pre-read or match | `Prerender()` route served by its baked artifact (pre-read probe of the normal variant; reclassified post-match when the store actually served, either variant)                                                      |
 | `intercept`                                                                   | match             | the navigation resolved to an intercept — replay is never armed for intercepts (they keep their normal cache path); no heal capture                                                                                  |
 | `cache-disabled`                                                              | pre-read or match | `cache(false)` (pre-read, static) or `condition()` false (decided at the lookup); consumer opt-out is absolute                                                                                                       |
@@ -556,6 +561,19 @@ curl -s -D - -o /dev/null https://app.example.com/products/1 | grep -i x-rango-s
   writes, and marker rejection, with `cf-ray`/colo and read timings. The flag is baked at
   build time; setting only a Worker runtime variable is too late.
 
+### Capturing a shell before the first visitor
+
+A shell is captured by the first document MISS for its key, so the first
+visitor after a deploy or an `updateTag()` renders without one. To capture it
+ahead of them, warm the URL: `router.prerender({ env, ctx })(url)` renders it
+through the handler, schedules the capture and waits for it, so the next
+document request is a HIT. A warm replaces a stored shell in place (the old
+one serves until the new one is written) and reports the capture's outcome
+(`result.caches.shell`, with `refusal` when the capture refused). It is not
+subject to the per-key in-flight dedup or the refused-capture backoff, which
+exist to stop a herd of visitors repeating work; every correctness guard on
+this page still decides. See `/prerender` → "Warm any route before traffic".
+
 ### Unit / integration testing (public primitives)
 
 Import from `@rangojs/router/testing` (Vitest) or `@rangojs/router/testing/e2e`
@@ -566,17 +584,18 @@ Import from `@rangojs/router/testing` (Vitest) or `@rangojs/router/testing/e2e`
 | `assertShellStatus(res, "HIT" \| "MISS")`         | Document Response from a real RSC serve / e2e `page.request` |
 | `assertPprReplayStatus(res, expected)`            | Partial response fresh/stale replay or bounded bypass        |
 | `parsePprReplayStatus(res)`                       | Read structured replay/bypass status or null                 |
-| `shellCacheKey(url)`                              | Production store key for `store.getShell` / custom stores    |
+| `shellCacheKey(router, url)`                      | Production store key for `store.getShell` / custom stores    |
 | `MemorySegmentCacheStore` + `getShell`/`putShell` | Custom store contract / tag eviction (no faked HIT)          |
 | `serveShellRequest(router, url, opts)`            | A real MISS → capture → HIT (react-server Vitest)            |
 
 ```ts
 import { MemorySegmentCacheStore } from "@rangojs/router/cache";
 import { assertShellStatus, shellCacheKey } from "@rangojs/router/testing";
+import { router } from "./router";
 
 // Unit: store + key (after a real putShell / capture flush in e2e)
 const store = new MemorySegmentCacheStore();
-const key = shellCacheKey("http://localhost/products/1");
+const key = shellCacheKey(router, "http://localhost/products/1");
 // ... after production putShell ...
 expect(await store.getShell(key)).not.toBeNull();
 
@@ -783,6 +802,9 @@ identifiers — served to anonymous visitors.)
 - `ctx.use(H)(promise)` from a handler — a TOP-LEVEL pushed promise is awaited
   at capture and BAKED into the shell (bounded by `ppr.captureTimeout`, 15s by
   default).
+- A promise pushed from a LOADER is never in the shell and the capture does not
+  wait for it: however slow it is (or if it never settles), the shell is still
+  stored, and the HIT's own loader run delivers the value after hydration.
 - `ctx.use(H)({ x: promise })` from a HANDLER — also baked. The capture waits
   for every promise nested in a handler's push, at any depth of plain objects,
   arrays and JSX props, before it records the handles every HIT replays. Keep
@@ -896,31 +918,109 @@ value once it refreshes, while the baked container keeps the capture's. If a
 hole needs a stable value, give it its own cache (`"use cache"` with a
 profile, or a loader `cache()`); the shell never provides one.
 
-**Handle pushes from a bake-lane loader appear once.** The capture records
-the settled, thenable-free handle pushes of every loader body it runs (the
+**Handle pushes from a bake-lane loader appear once, and they match its
+data.** A loader's title, meta or breadcrumb describes the data next to it,
+so both come from the same run on every way a shell can be replayed: a
+document HIT, a client navigation, a prefetch. The capture records the
+settled, thenable-free handle pushes of every loader body it runs (the
 prelude rendered them): the `ssr: false` loader's own, those of the loaders
-it awaits with `ctx.use()`, and those its own `cache()` entry replays. Every
-HIT restores them with the handler layer, and they stand: a bake-lane loader
-that does run on the HIT (a hole-carrying one) reads the store, so its settled
-pushes, and those a `"use cache"` hit inside its body replays, are dropped
-instead of replacing the restored ones. Any handle, deduping or not, shows
-each value once, and it is the value the prelude rendered. A loader the route
-also registers on the live lane is a hole: its live run replaces its restored
-pushes, and those of the loaders it awaits, so they show its live value, even
-when a bake-lane loader running on the HIT awaits it. A run that throws or
-makes no push shows none of the capture's once its run ends; a hole slower
-than the handler barrier shows the shell's copy in the first snapshot until
-then. A hole with its own loader `cache()` that hits shows the pushes that
-entry recorded, none if it recorded none, matching its data. A dependency the route does not
-register, which an `ssr: false` loader awaited at capture outside any live
-loader, is on neither lane: its settled pushes stay as the prelude rendered
-them, even where a live loader also awaits it, while its data is fresh. To
-keep its pushes live, declare it as its own `loader()` on the route. A push the capture cannot record (a
-deferred push, or one holding a promise) marks every loader record of the
-page to run: those bodies then still run on each HIT, in the background, and
-that push reaches the page (from the loader's own `cache()` entry when it
-hits) with the run's value; a push that lands after the document's handle snapshot
-reaches the client after hydration.
+it awaits with `ctx.use()`, and those its own `cache()` entry replays. What
+a replay does with a loader's recorded pushes follows what it does with that
+loader's data:
+
+| The replay serves the loader's data from                                    | Its settled pushes are                                                                                                                                                                      |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| the shell (its pinned container)                                            | the shell's: restored with the handler layer, and they stand. A loader that does run on the replay (a hole-carrying one) reads the store, and the settled pushes that run makes are dropped |
+| a run on this request (a live-lane loader, or one the shell has no pin for) | that run's: they replace the shell's copies in place; a run that throws or makes no push shows none                                                                                         |
+| the loader's own `cache()` entry                                            | that entry's: the pushes it recorded, none if it recorded none                                                                                                                              |
+
+So any handle, deduping or not, shows each value once. A pinned loader's
+pushes are the values the prelude rendered, also for the pushes a `"use
+cache"` hit inside its body replays. A loader the route also registers on
+the live lane is a hole: its live run replaces its restored pushes, and those
+of the loaders it awaits, so they show its live value, even when a bake-lane
+loader running on the replay awaits it. On a document HIT the page hydrates
+with the shell's copy and the hole's value takes its place after hydration
+("Handles on a shell HIT" below). An
+`ssr: false` loader is served from the shell only while the entry holds its
+pin: a snapshot captured by a navigation alone carries none, and a shell over
+`ppr.maxSnapshotBytes` drops them. There the loader runs fresh, and its
+pushes are that run's, like its data.
+
+A `Prerender` + `ppr` page follows the same table. Its handler layer comes
+from the prerendered payload, which never holds a loader push (loaders do not
+run at build), so the shell entry records the loader pushes its HTML rendered
+on its own, and a HIT restores them as above (#1057).
+
+A dependency the route does not register, which an `ssr: false` loader
+awaited at capture outside any live loader, is on neither lane: its settled
+pushes stay as the prelude rendered them, even where a live loader also
+awaits it, while its data is fresh. (They follow the run instead once the
+entry has lost a pin, because the loader that awaits it then runs.) To keep
+its pushes live, declare it as its own `loader()` on the route. A push the
+capture cannot record (a deferred push, or one holding a promise) marks every
+loader record of the page to run: those bodies then still run on each replay,
+in the background, and that push reaches the page (from the loader's own
+`cache()` entry when it hits) with the run's value, on a document HIT and on
+a client navigation alike. On a document HIT it arrives after hydration.
+
+**Handles on a shell HIT.** A promise pushed from a loader is live and is
+never in a shell. To have a value in the shell's HTML, push it settled
+(await it) from the `ssr: false` loader, or push it from the handler.
+
+Three things follow, in this order of scope:
+
+1. **What is in a shell's HTML** changes only for promise pushes of
+   `ssr: false` loaders and of the loaders they await: `push(promise)`, or a
+   pushed value that holds a promise. Those run at capture, and the shell
+   renders no element for such a push. A loader without `ssr: false` never
+   ran at capture, so nothing of it was ever in the shell.
+2. **On a shell HIT every loader push made during the request arrives after
+   hydration**, a live-lane loader's included. The document hydrates with
+   exactly the handle data the shell's HTML was rendered from (the handlers'
+   pushes and the settled pushes of the loaders that ran at capture), and
+   the request's own pushes follow as a normal `useHandle` update.
+3. **`useHandle` on every document, `ppr` or not:** a reader that React is
+   hydrating reads the handle data its HTML was rendered from, wherever its
+   boundary hydrates, and takes the newer data right after. So a reader
+   inside the `loading()` or `<Suspense>` of a loader that pushes after an
+   `await` hydrates clean.
+
+| On the HIT's request                                                        | In the HIT's HTML      | The client                                        |
+| --------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------- |
+| a handler's push, a pinned `ssr: false` loader's settled push               | yes (the shell has it) | hydrates with it                                  |
+| a deferred push (`push(promise)`), or a push holding a promise, by a loader | no                     | gets it right after hydration                     |
+| a live-lane loader's push                                                   | no                     | gets it right after hydration                     |
+| the run of an `ssr: false` loader the shell has no pin for                  | the capture's push     | hydrates with the capture's, then shows the run's |
+
+A value a loader pushes as a promise is therefore in the HTML of a document
+MISS (the render awaits it) and of a route without `ppr`, and not in the
+HTML of a shell HIT. When a crawler or the first paint needs it, change one
+line:
+
+```ts
+ctx.use(Notes)(db.stockNote(id)); // a promise: live, after hydration on a HIT
+ctx.use(Notes)(await db.stockNote(id)); // settled: baked into the shell
+```
+
+The settled push bakes with the shell and is invalidated with it (its TTL,
+its tags). A promise is not baked, whenever it settles: it is the shape that
+says "per request", the same as a promise in the loader's data.
+
+A pinned loader's pushes are exactly the ones its capture made. If its body
+pushes a settled value only on some runs (behind a condition), a replay that
+runs it shows the capture's answer, a push or none, never a later run's next
+to the pinned data. A deferred push is the exception by design: it is
+delivered on every replay.
+
+One arrangement mixes sources by design. A loader that reads a
+`cache()`-bound loader with `ctx.use()` before that binding starts (a loader
+declared ahead of it, a parent layout) runs it live while the binding serves
+its entry, so the cached loader's data and its handle push can come from
+different runs on that request. To keep them together, declare the cached
+loader first, or read it from the handler: a handler's `ctx.use()` is where a
+loader read is baked. An entry such a request writes holds no pushes, and a
+later HIT of it then shows none for that loader.
 
 Four hard edges (each e2e/unit-pinned):
 
@@ -1187,8 +1287,9 @@ eligible captured segment snapshot, per-request CSP nonce, `streamMode:
 request the route's own `cache()` scope refuses (`cache(false)`, or a
 `condition()` returning false for it), and any store without the shell family.
 A stored shell is invalidated when
-`React.version` changes (postponed state is build-coupled), so deploys
-self-heal via recapture.
+`React.version` changes (postponed state is build-coupled) or when the router's
+document version changes, so a deploy that changes the router self-heals via
+recapture, and a deploy that does not keeps its shells.
 
 The per-request CSP nonce guarantee covers BOTH ways a nonce arrives — the
 `createRouter({ nonce })` provider AND a direct `ctx.set(nonce, value)` token
@@ -1234,13 +1335,13 @@ path(
 );
 ```
 
-| Field              | Default | Notes                                                                                                                                                                                                                                                                                                      |
-| ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ttl`              | `300`   | shell freshness window in seconds (`ppr: true` uses the default)                                                                                                                                                                                                                                           |
-| `swr`              | —       | stale window: serve the stale shell + background recapture                                                                                                                                                                                                                                                 |
-| `tags`             | —       | operational tags UNIONED with the tags the capture collects — see "Invalidation" below                                                                                                                                                                                                                     |
-| `maxSnapshotBytes` | 8 MiB   | cap on the loader pins in the entry's snapshot (the bake-lane loader records). The recorded handler layer is exempt. Over the cap the pins are dropped and the shell is stored with its handler layer (warned once per key); bake-lane loaders then read the live store, and drift is repaired client-side |
-| `captureTimeout`   | 15000ms | ONE capture deadline: the handler layer settling (promises it passes or pushes, async server components, loaders it awaits), bake-lane loaders, and the prerender; a capture that misses it stores nothing rather than a partial shell                                                                     |
+| Field              | Default | Notes                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ttl`              | `300`   | shell freshness window in seconds (`ppr: true` uses the default)                                                                                                                                                                                                                                                                                                                                            |
+| `swr`              | —       | stale window: serve the stale shell + background recapture                                                                                                                                                                                                                                                                                                                                                  |
+| `tags`             | —       | operational tags UNIONED with the tags the capture collects — see "Invalidation" below                                                                                                                                                                                                                                                                                                                      |
+| `maxSnapshotBytes` | 8 MiB   | cap on the loader pins in the entry's snapshot (the bake-lane loader records). The recorded handler layer is exempt. Over the cap the pins are dropped and the shell is stored with its handler layer (warned once per key); bake-lane loaders then run on every replay and read the live store, their handle pushes come from that run like their data, and drift from the prelude is repaired client-side |
+| `captureTimeout`   | 15000ms | ONE capture deadline: the handler layer settling (promises it passes or pushes, async server components, loaders it awaits), bake-lane loaders, and the prerender; a capture that misses it stores nothing rather than a partial shell                                                                                                                                                                      |
 
 A shell never outlives the route `cache()` entry it was captured from: under
 a route `cache()`, the shell is fresh no longer than that entry is (at most
@@ -1268,8 +1369,9 @@ shrink what the shell bakes or move large regions under a live loader's
 boundary.
 
 The shell store is always the app-level `createRouter({ cache })` store; the
-default key is `${host}${pathname}${sortedSearch}:shell` (host-scoped so
-multi-tenant shells never collide).
+default key is `${routerId}@${host}${pathname}${sortedSearch}:shell`: host-scoped
+so multi-tenant shells never collide, and router-scoped so two routers on one
+store keep their own (see `/host-router`, "Shared cache store").
 
 These options control the in-function shell entry only. They do not emit HTTP
 `Cache-Control`. Adding `s-maxage` separately allows a platform CDN to cache the