@rangojs/router 0.17.0 → 0.18.0

package/skills/caching/SKILL.md

@@ -58,7 +58,8 @@ cache({ ttl: 60, swr: 300 }, () => [
 not stored: it renders on every request, hits included, with its parallels and
 loaders, so a per-request shell or a header it writes stays live. On a `ppr`
 route the whole chain bakes into the shell, so there `cache()` covers the whole
-chain.
+chain, and a shell never outlives the route `cache()` entry it was captured
+from (it is fresh and served no longer than that entry; `/ppr`).
 
 ```typescript
 layout(AccountShell, () => [
@@ -89,8 +90,11 @@ path, not only ProductChrome.
 
 The consumer rule: **want it cached? render it inline. Want it live? put it in a
 loader and read it with `useLoader()` in a client component.** Anything read
-with `cookies()`, `headers()`, or a non-cacheable variable belongs in a loader
-(loaders always run fresh). Reading it directly in a cached handler throws;
+with `cookies()`, `headers()`, or a non-cacheable variable belongs in a loader:
+a route `cache()` does not store loader values, so a loader runs on every
+request. A loader bound with its own `cache()` is stored, so without a `key()`
+its miss fails; any `key()` switches that check off, so it must include the
+value (see `/loader` → "Cache Key"). Reading it directly in a cached handler throws;
 awaiting a loader with `ctx.use()` and rendering the result in a cached handler
 silently bakes per-request data into the shared entry (see "Cache purity &
 tainted objects" below).
@@ -163,7 +167,12 @@ cache(
   — document requests, client navigations, and intercept navigations are cached
   separately. The search part honors `cache.searchParams` (below).
 - **`key`** is a full override: it bypasses the default key, the store's
-  `keyGenerator`, and the search-param filter.
+  `keyGenerator`, and the search-param filter. A nested `cache()` keys its
+  records within that partition (see "Keys nest" under "Nested Cache
+  Boundaries"). On a `ppr` route the same key
+  (or, without one, the store's `keyGenerator`) partitions the PPR shell: each
+  partition captures and serves its own shell (`/ppr`, "Request-partitioned
+  shells").
 - **`condition`** returning `false` skips both the cache read and write for that
   request (the boundary renders live).
 - `cache(() => [...])` with no options uses the store defaults.
@@ -221,15 +230,25 @@ function CampaignBanner() {
 
 Each tag attaches to one entry, so know which entry you are tagging:
 
-- Forms 1 and 2 tag the `cache()` segment entry. They are the only way to tag
-  it: tags recorded by a `"use cache"` function (form 3) stay on that
-  function's entry and do not attach to an enclosing `cache()` segment entry.
+- Forms 1 and 2 tag the `cache()` segment entry.
 - Form 3 tags the `"use cache"` entry (plus any profile `tags`).
 - Form 4 tags the request's `ppr` shell entry (`/ppr`) or `/document-cache`
-  entry, with no `"use cache"` needed. Called inside a `cache()` segment it
-  still tags the document/shell, not the segment entry. On a route that is
-  neither `ppr` nor document-cached, nothing reads the tag — a silent no-op, so
-  do not expect a bare `cacheTag()` to tag an ordinary uncached page.
+  entry, with no `"use cache"` needed. On a route that is neither `ppr` nor
+  document-cached and has no `cache()`, nothing reads the tag — a silent
+  no-op, so do not expect a bare `cacheTag()` to tag an ordinary uncached page.
+- A route `cache()` entry also carries the tags its own content recorded when
+  it was written: form 4 calls and form 3 reads in the handlers and server
+  components it covers. `updateTag()` of such a tag drops the entry, and a HIT
+  re-records the tags, so a ppr shell or document built from the HIT stays
+  evictable. `loading()` subtrees count too: a HIT replays their output. A
+  loader's tags reach the entry only when a handler consumes its value
+  (`await ctx.use(Loader)`); a loader nobody reads on the server runs per
+  request and stays off.
+- A loader with its own `cache()` stores the tags its body recorded (form 4
+  calls and form 3 reads, including those of the loaders it reads with
+  `ctx.use()`) next to its `cache({ tags })`. They invalidate the loader's
+  entry, and a HIT records them again, so a route `cache()` entry, ppr shell
+  or document built over the HIT carries them.
 
 Invalidate with one of two server-only verbs (both variadic, imported from
 `@rangojs/router`):
@@ -258,6 +277,25 @@ function onProductsChanged() {
 | `updateTag(...tags)`     | awaitable (`Promise<void>`) | server actions            | immediate; next read is fresh                         |
 | `revalidateTag(...tags)` | background (`void`)         | route handlers / webhooks | background (non-blocking); next read re-renders fresh |
 
+The request that calls either verb reads its own writes. Before the call
+returns, each built-in store marks the tags as invalidated for the rest of that
+request, so an action that calls `revalidateTag()` and then renders gets fresh
+`"use cache"` and `cache()` reads, as with `await updateTag()`. What
+`revalidateTag()` does not wait for is the durable write (the KV marker, the
+tag purge, Vercel's `expireTag`): other requests see the invalidation once it
+lands. A `"use cache"` call that this request started before the
+invalidation, and that carries one of the invalidated tags, is not reused
+after it and does not store its value; neither does a stale entry's
+background refresh. The tags are the call's own (its `cacheTag()` calls and
+profile `tags`): a nested `"use cache"` function's tags do not reach the
+enclosing entry, so invalidating one of them neither evicts the outer entry
+nor stops an outer call already running
+([#980](https://github.com/rangojs/rango/issues/980)). Not covered
+([#977](https://github.com/rangojs/rango/issues/977)): such a call started
+by another request, or a loader's own `cache()` that started before the
+invalidation, still stores its value when it finishes, and reads after that
+can get it.
+
 Both must run inside a request (action, handler, middleware, response route).
 Called from a queue consumer or cron job, there is no request context, so they
 warn and invalidate nothing. `updateTag()` rejects when a store's durable write
@@ -383,8 +421,17 @@ defaults (ttl 60 when the store sets none); it does **not** inherit the options
 of an enclosing `cache()` boundary. Inside `loader()` only the direct form
 `cache({...})` is valid — the wrapper form `cache(opts, () => [...])` throws.
 Handle pushes from the loader body (`Meta`, `Breadcrumbs`) are stored with the
-value and replayed on every hit, stale included. See `/loader` for the full
-loader reference.
+value and replayed on every hit, stale included. The tags the body records
+(`cacheTag()`, `"use cache"` reads, and those of the loaders it reads) are
+stored with it too: `updateTag()` of one drops the entry, as `cache({ tags })`
+does. See `/loader` for the full loader reference.
+
+The entry's default key is the loader, host, path and params. It does not
+inherit an enclosing `cache()` boundary's `key()` either, so it is shared
+across users: a body that reads `cookies()`, `headers()` or a non-cacheable
+variable fails on a miss unless the loader `cache()` has a `key()` or its store
+a `keyGenerator`. Either one switches the check off, so it must itself include
+the value (`/loader` → "Cache Key").
 
 ## Global Cache Configuration
 
@@ -537,8 +584,9 @@ const router = createRouter<AppBindings>({
 | Cold colo    | MISS           | HIT     | Serve from KV, promote to L1  |
 | First render | MISS           | MISS    | Render, write to both L1 + KV |
 
-KV entries require `expirationTtl >= 60s`. Short-lived entries (< 60s total TTL)
-are only cached in L1.
+KV entries require `expirationTtl >= 60s`. Short-lived data entries (< 60s total
+TTL) are only cached in L1. A PPR shell is always written to KV, a short one
+with the 60 s minimum; its reads still expire it at its own deadline.
 
 ### Resilience & latency budgets
 
@@ -558,6 +606,74 @@ read. A non-finite value (e.g. `Number(env.UNSET)`) falls back to the default.
 The tag-invalidation marker reads inherit these same budgets and **fail open** on
 a KV timeout — the entry is served rather than wrongly treated as invalidated.
 
+A PPR shell HIT reads its entry prelude-first: the body budget (or the KV budget
+on a KV read, counted from opening the value) covers only the entry's head and
+prelude, the tag-marker read runs alongside the prelude read, and the capture
+snapshot behind them is read off the commit path, bounded by `kvReadTimeoutMs`
+(at least 1 s: the tail cannot render without it). A HIT whose snapshot read
+times out, or whose snapshot is truncated or corrupt (also evicted), cannot
+replay the captured segment record, so it degrades: the entry is replaced and
+recaptured and the page reloads once into a cache-miss render (`/ppr`). The
+snapshot holds only what a HIT reads: every HIT replays the handler layer from
+the captured segment record, so the `"use cache"` items only handler code read
+are not stored.
+
+**Shell memo.** After a shell read, the same isolate serves that key's next
+HITs from memory for `memo.shellMs` (default 2000; `{ shellMs: 0 }` turns it
+off), with no Cache API or KV read. The tag-marker check still runs on every
+HIT, and the isolate that runs `updateTag()`/`revalidateTag()` drops its own
+copies, so that request and later ones on the same isolate never get the
+invalidated shell. What another isolate can serve for up to one window: the
+previous capture of a key another isolate just recaptured, and, without KV in
+purge mode, a purged shell (the purge reaches the stored entry, not other
+isolates' memos). `memo.shellMaxBytes` (default 16 MiB, shared by every
+`CFCacheStore` in the isolate) caps what it holds; only fresh shells are kept.
+
+**Tag-marker memo.** With KV, PPR shell reads check their tag markers through
+a per-isolate memo, stale-while-revalidate: a marker read within
+`memo.markerFreshMs` (default 1000) is used as is, one within
+`memo.markerMaxStaleMs` (default 10000) is used while a background read
+refreshes it, an older one waits for KV. The isolate also remembers each
+shell's tag names and starts those marker reads with the Cache API match
+(`ppr.tags` are known up front). `cache()`, `"use cache"` and response entries
+keep reading their markers. `{ markerFreshMs: 0 }` turns the value memo off.
+
+**The fresh-reads cookie.** A response whose request ran `updateTag()` or
+`revalidateTag()` sets `<state cookie prefix>-fresh` (`rango-state-fresh` by
+default, shared by every router on the host with that prefix; `HttpOnly`,
+`SameSite=Lax`, `Path=/`, `Secure` on https, `Max-Age` 11 s with KV and 3 s
+without at the defaults: the longest memo staleness plus 1 s). It is strictly
+functional: its value is `1`, it identifies no one, and it only sends that
+browser's reads past the memos. The same user's requests that carry it skip
+both memos on every isolate, so a mutating user never sees a memoized shell or
+marker from before their write. What they read past the memos is the store's
+own consistency. `VercelCacheStore`: `expireTag` is global (about 300 ms), so
+they read fresh in any region. `CFCacheStore` with KV: the shell's tag check
+reads that colo's marker (its Cache API copy when `tagCacheTtl` is set, then
+KV), so in the colo that ran the mutation they read fresh, while a request
+another colo serves can still get the old shell until KV propagates the
+marker there (up to about 60 s) and that colo's cached marker (`tagCacheTtl`)
+expires. `CFCacheStore` without KV in purge mode (`tagPurge`) has no markers:
+the purge is what removes the shell, and they see it once it has reached the
+colo serving them. Other users can see a memoized shell or marker for up to
+`markerMaxStaleMs` (with KV) or the shell window (`VercelCacheStore` in
+another region, `CFCacheStore` in KV-less purge mode, where another isolate's
+memo can keep serving the purged shell). Set `{ shellMs: 0, markerFreshMs: 0 }` where every user's next
+request must see an invalidation (with KV, `{ shellMs: 0 }` alone still leaves
+the marker memo); that also means no cookie. The cookie is not set when the
+invalidation runs after the response headers were sent (a streaming loader or
+render; dev warns): invalidate in a server action, route handler or
+middleware. Any client can send it, which only makes its own requests read
+the store.
+
+```typescript
+new CFCacheStore({
+  ctx,
+  kv: env.CACHE_KV,
+  memo: { shellMs: 5000, markerFreshMs: 500 },
+});
+```
+
 ```typescript
 new CFCacheStore({
   ctx,
@@ -623,13 +739,17 @@ 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.
+// 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 router = createRouter({
   document: Document,
   urls: urlpatterns,
   cache: () => ({
     store: new VercelCacheStore({
-      // A per-deploy namespace: Vercel does not reconcile entries across deploys
-      cache: getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID }),
+      cache: runtimeCache,
       waitUntil,
       defaults: { ttl: 60, swr: 300 },
     }),
@@ -637,6 +757,22 @@ const router = createRouter({
 });
 ```
 
+The store keeps the same PPR shell memo as `CFCacheStore` (`memo.shellMs`,
+default 2000; `memo.shellMaxBytes`, default 16 MiB) and the same tag-marker
+memo (`memo.markerFreshMs`, default 300; `memo.markerMaxStaleMs`, default
+2000), one per `cache` handle: create the handle once, as above, or the memos
+never hit. The request that runs `updateTag()`/`revalidateTag()` misses on
+the entries carrying those tags before `expireTag` lands. A shell read's
+marker check sees the invalidation in the process that ran it once its
+markers are written, and in the rest of the region once their marker memo
+refreshes. The tag markers are a regional `cache.set` (only
+`expireTag` is global), so another region serves a shell it memoized before
+the invalidation until its window passes, where without the memo `expireTag`
+removes it within about 300 ms; a platform `expireTag` issued outside rango is
+likewise seen when the window passes. The fresh-reads cookie (`Max-Age` 3 s)
+sends the mutating user's next requests past both memos, and `expireTag` is
+global, so they read fresh in any region.
+
 Writes over 2 MB (the platform limit, `maxItemBytes`) are skipped, and tags
 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
@@ -654,6 +790,7 @@ another, request-scoped APIs are guarded inside a cache scope:
 | `cookies()` / `headers()` (read or write)                                          | **throws** — request-scoped, would poison the entry |
 | Response writes: `ctx.headers.set()`, `setCookie()`, `setStatus()`, `onResponse()` | **throws** — response side effects lost on a hit    |
 | `ctx.get(var)` where the var is `{ cache: false }`                                 | **throws** on read                                  |
+| `ctx.theme`, `getRequestContext().theme`                                           | **throws** — the theme is the visitor's cookie      |
 | `ctx.set(var, value)` for a cacheable var                                          | allowed (children are cached too)                   |
 | Any of the above **inside a registered loader** (`loader(...)`)                    | **allowed** — loaders always run fresh              |
 
@@ -661,6 +798,12 @@ A loader body invoked from a handler with `await ctx.use(Loader)` may read
 `cookies()`/`headers()`, but its response writes still throw: on a hit the
 handler is skipped, so that loader never runs.
 
+A loader bound with its **own** `cache()` (`loader(Def, () => [cache({...})])`)
+stores its value, and its key does not inherit the route's. A miss whose body
+read `cookies()`, `headers()` or a non-cacheable `ctx.get()` fails unless the
+binding has a `key()` or its store a `keyGenerator`, which must then include
+the value (`/loader` → "Cache Key").
+
 **Tainted objects.** Request-scoped objects (`ctx`, `env`, `request`) carry an
 internal taint symbol so they are excluded from `"use cache"` cache keys. The
 `cache()` scope is tracked in async-local state and deliberately ends inside
@@ -680,10 +823,12 @@ is **not** guarded. `ctx.use()` is a server-side escape hatch for non-rendered
 uses (set a ctx var, make a routing decision); never render its result inside a
 cached handler.
 
-This is the **consumption-lane rule**, and it holds identically for every
-shared artifact — `cache()`, `"use cache"`, and the PPR shell (`/ppr`):
-handler consumption = baked copy with identity reads permitted; client-side
-`useLoader` = live. It is stated once in `/rango` → Invariants.
+This is the **consumption-lane rule**, and it holds for every shared
+artifact — `cache()`, `"use cache"`, and the PPR shell (`/ppr`): handler
+consumption = baked copy; client-side `useLoader` = live. The tiers differ on
+identity reads inside a handler-consumed loader: `cache()` and `"use cache"`
+permit them (the leak above), while a PPR shell capture refuses them and the
+route stays uncached. It is stated once in `/rango` → Invariants.
 
 ```typescript
 // WRONG — throws: cookies() read directly in a cached handler
@@ -729,8 +874,9 @@ See `/cache-guide` for the full decision guide and the `cache()` vs `"use cache"
 
 ## Nested Cache Boundaries
 
-An inner boundary overrides the settings of the outer one for its subtree;
-`cache(false)` turns caching off for a subtree:
+An inner boundary overrides the settings of the outer one for its subtree
+(`key` composes instead, see below); `cache(false)` turns caching off for a
+subtree:
 
 ```typescript
 cache({ ttl: 300 }, () => [
@@ -746,6 +892,80 @@ cache({ ttl: 300 }, () => [
 ]);
 ```
 
+On a `ppr` route the opt-out also means no shell: `cache(false)`, or a
+`condition()` that returns false, renders that route (or that request) like a
+cache miss, with no shell served and none captured. A `ppr` route under a
+layout's `cache()` therefore cannot opt out of that `cache()` and still get a
+shell (`/ppr`).
+
+### Keys nest: a partition covers the whole subtree
+
+A `key()` partitions every record under its `cache()`. A nested `cache()`
+keys its records within that partition, so a request in one partition never
+HITs another partition's inner record:
+
+```typescript
+const tier = (ctx) =>
+  ctx.request.headers.get("x-tier") === "gold" ? "gold" : "silver";
+
+cache({ ttl: 300, key: (ctx) => `tier:${tier(ctx)}` }, () => [
+  layout(TierLayout, () => [
+    // No key() of its own: the outer key() result, then this boundary's own
+    // default key ("tier%3Agold|doc%3Aexample.com%2Fpricing"), so /pricing
+    // and /faq keep their own records
+    cache({ ttl: 60 }, () => [
+      path("/pricing", PricingPage, { name: "pricing" }),
+      path("/faq", FaqPage, { name: "faq" }),
+    ]),
+
+    // Its own key() composes with the outer one ("tier%3Agold|v%3Ab")
+    cache(
+      { ttl: 60, key: (ctx) => `v:${ctx.searchParams.get("v") ?? "a"}` },
+      () => [path("/plans", PlansPage, { name: "plans" })],
+    ),
+  ]),
+]);
+```
+
+The parts are joined by `|`, outermost first, each URI-encoded:
+
+| Boundary the route sits in                     | Record key                                                                                                              |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `cache({ ttl })`, no `key`, under a keyed one  | The chain's `key()` results, then this boundary's default key (its store's `keyGenerator` result, else the default key) |
+| `cache({ key })` under a keyed one             | The chain's `key()` results                                                                                             |
+| deeper nesting                                 | Composes the same way; only the innermost boundary's missing `key` adds its default key                                 |
+| `cache(false)`                                 | No caching, as before; a `cache()` re-enabled below it stays in the partition                                           |
+| a single keyed `cache()`, or no `key` anywhere | Its raw `key()` result, or the default key, as before                                                                   |
+
+- The encoding is unambiguous among composed keys: an encoded part holds no
+  `|`, so no two partitions, and no two inner keys, compose to the same
+  record key.
+- A single keyed `cache()` stores its `key()` result as is, so a raw result
+  can equal a composed key: a header value `gold|doc%3Aexample.com%2Fpricing`
+  returned raw names the record gold's pricing page keeps under the inner
+  `cache()` in the example above. Never return raw
+  request input from `key()`: normalize it to the values you serve, prefix
+  it (`tier:${value}`), or encode it. A composed key holds no `:` (every
+  part is URI-encoded), so a prefixed result never equals one.
+- An inner boundary without `key` keeps everything its default key tells
+  apart (path, params, search, document vs navigation), so its routes never
+  share a record, even when the outer `key()` names no route.
+- A boundary with its own `key()` skips the store's `keyGenerator`, as a
+  single `key()` does.
+- Each `key()` runs once per request, however many boundaries and lookups use
+  it.
+- A response route's entry (`path.json()` and the other response routes) is
+  keyed the same way. A `ppr` route's shell is partitioned by the chain's
+  `key()` results alone, since the shell key already carries the URL (plus the
+  store `keyGenerator`'s result for an inner boundary without `key`).
+- To share an inner cache across partitions, move it outside the keyed
+  `cache()`.
+
+Before issue #970, the innermost boundary alone decided the key: an inner
+`cache()` without `key` wrote under the default key and an inner `key()`
+dropped the outer partition, so a silver visitor could HIT what a gold
+visitor's request had cached.
+
 ## Custom Cache Store
 
 Create a dedicated store for specific routes:
@@ -765,6 +985,16 @@ A per-boundary store becomes reachable by `updateTag()`/`revalidateTag()` only
 once that boundary has been matched in the current process. For data you
 invalidate by tag, prefer the app-level store.
 
+If you implement `SegmentCacheStore` yourself, `invalidateTags(tags)` is called
+synchronously inside the invalidating request, and `revalidateTag()` does not
+await it. For that request to read its own writes, record the tags and the
+time as invalidated in request-scoped state your reads check (a `WeakMap`
+keyed by the object `getRequestContext()` returns) before the first `await`,
+then start the durable write. Only let that state turn hits into misses, and
+only for entries written at or before that time. A store that skips this
+still works, but the request that ran `revalidateTag()` can read invalidated
+entries until the durable write lands.
+
 ## Complete Example
 
 ```typescript

package/skills/catalog.json

@@ -251,7 +251,7 @@
     },
     {
       "name": "testing",
-      "description": "Test @rangojs/router apps — unit (loaders, middleware, server actions, handles, transition/clientUrls predicates), client components (renderRoute), RSC/Flight (renderServerTree, renderHandler), integration (dispatch), and e2e (dev+prod parity, progressive enhancement). Use when writing a unit test for a loader, middleware, action, or handler, setting up vitest for a Rango app, or testing a route end-to-end in dev and production.",
+      "description": "Test @rangojs/router apps — unit (loaders, middleware, server actions, handles, transition/clientUrls predicates), client components (renderRoute), RSC/Flight (renderServerTree, renderHandler, serveShellRequest for PPR shells), integration (dispatch), and e2e (dev+prod parity, progressive enhancement). Use when writing a unit test for a loader, middleware, action, or handler, setting up vitest for a Rango app, or testing a route end-to-end in dev and production.",
       "argumentHint": "[layer]",
       "path": "skills/testing/SKILL.md"
     },

package/skills/client-urls/SKILL.md

@@ -268,8 +268,9 @@ handler parity — `ctx.use(Meta)({ title })` pushes exactly like a handler
 push. Reads moved to `ctx.get(handle)`, gated behind `await ctx.rendered()`.
 Delivery follows the race model: pushes that settle before the handler barrier
 ride the SSR handle snapshot; later ones stream and apply post-hydration
-(document loads) or progressively (navigations). See `/loader` for the full
-contract.
+(document loads) or progressively (navigations). On a `ppr` shell HIT a loader
+without `ssr: false` never ran during the capture, so its pushes are never in
+the shell and always apply client-side. See `/loader` for the full contract.
 
 ## `ssr: false` — the SSR-completeness opt-in
 
@@ -309,10 +310,14 @@ Constraints:
 - Under a `ppr` group route the flag is the bake lane, exactly as on a server
   route (`/ppr` → The loader lane rule).
 
-Every document load pays the flagged loader's latency before first byte —
-that is the point, but it is a real cost. Keep flagged loaders fast (existence
-checks before expensive fetches) and flag the loaders that need it, not the
-route.
+Every document render that is not a `ppr` shell HIT pays the flagged
+loader's latency before first byte — that is the point, but it is a real cost.
+On a shell HIT the shell flushes first: a flagged loader whose value has no
+promises is served from the shell and does not run (unless the capture marked
+it to run: see `/ppr` → On a shell HIT), and one whose value
+carries promises runs on every HIT to fill its holes. Keep flagged loaders
+fast (existence checks before expensive fetches) and flag the loaders that
+need it, not the route.
 
 Pinned end to end by dev + production e2e in the router repository.
 

package/skills/cloudflare/SKILL.md

@@ -168,6 +168,21 @@ family runs L1-only (each colo captures and serves its own shell). A tagged
 shell with neither `kv` nor `tagPurge` logs a warning once and expires only by
 ttl+swr. See `/caching` and `/ppr`.
 
+Shell reads are stale-while-revalidate through per-isolate memos: a warm
+isolate serves a shell it read within `memo.shellMs` (default 2000) from
+memory, and with `kv` it checks tag markers through a memo that is used as is
+for `memo.markerFreshMs` (default 1000) and while it refreshes in the
+background up to `memo.markerMaxStaleMs` (default 10000). After
+`updateTag()`/`revalidateTag()` the response sets the fresh-reads cookie
+(`rango-state-fresh` by default), so the mutating user's next requests skip
+the memos. That makes them fresh in the colo that ran the mutation; other
+colos converge once KV propagates the marker and their cached marker
+(`tagCacheTtl`) expires. In purge mode without `kv`, another isolate's memo
+keeps serving a purged shell until `memo.shellMs` passes. Set
+`memo: { shellMs: 0, markerFreshMs: 0 }` to remove the memo delay for every
+user's next request; cross-colo KV propagation (and `tagCacheTtl`) still
+applies. Details: `/caching` → "The fresh-reads cookie".
+
 ## Tracing on Workers
 
 `createCloudflareTracing()` from `@rangojs/router/cloudflare` emits the

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
 
@@ -534,10 +536,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
@@ -620,18 +625,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 +690,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 +701,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
@@ -773,11 +783,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