@rangojs/router 0.17.0 → 0.19.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,12 @@ 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()`, `ctx.request.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,9 +168,20 @@ 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. The result is stored
+  namespaced (`key:` plus its URI encoding), so whatever it returns, request
+  input included, never names another route's default-keyed record or a
+  nested partition's. 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).
+  request (the boundary renders live). It gates every `cache()` nested under
+  it too: an inner boundary caches only when every enclosing `condition()`
+  allows it.
+- **`tags`** tag this boundary's records and those of every `cache()` nested
+  under it, so `updateTag()` of an outer tag evicts the inner records too.
 - `cache(() => [...])` with no options uses the store defaults.
 - `cache(false, () => [...])` disables caching for a subtree (see "Nested Cache
   Boundaries").
@@ -221,15 +237,28 @@ 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.
-- Form 3 tags the `"use cache"` entry (plus any profile `tags`).
+- Forms 1 and 2 tag the `cache()` segment entry, and the entries of every
+  `cache()` nested under it (see "Conditions and tags inherit").
+- Form 3 tags the `"use cache"` entry (plus any profile `tags`), and every
+  `"use cache"` entry that calls that function: the outer entry bakes the
+  inner value, so it carries the inner 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 +287,28 @@ 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.
+
+Work that started before the invalidation, in this request or another one,
+is not stored after it. A `"use cache"` call, a stale entry's background
+refresh, a loader's own `cache()`, a route `cache()` render or a
+document-cache render that read its data before one of its tags was
+invalidated still returns what it read, but its store write is skipped:
+every store stamps an entry when it is written, so the old value would be
+served as newer than the invalidation. The next read runs it again. A
+`"use cache"` call already running when one of its tags is invalidated is
+not joined by later calls either. Its tags include those of the
+`"use cache"` functions it calls. Another isolate's invalidation is caught
+through the store's markers (`CFCacheStore` with KV, `VercelCacheStore`); on
+a KV-less `CFCacheStore` only this isolate's invalidations are, and ttl+swr
+bounds the rest.
+
 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 +434,18 @@ 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()`, `ctx.request.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 +598,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 +620,76 @@ 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 and serves an `ssr: false` loader's baked
+container, so no `"use cache"` or loader `cache()` item is stored in it. A
+live hole, and any loader that runs on the HIT, reads those from the store
+under their own ttl/swr and tags.
+
+**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 +755,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 +773,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
@@ -649,18 +801,52 @@ cached handler is **frozen into the shared cache entry** and served to every
 subsequent visitor. To stop one user's request-scoped data from leaking to
 another, request-scoped APIs are guarded inside a cache scope:
 
-| Inside a `cache()` boundary                                                        | Behavior                                            |
-| ---------------------------------------------------------------------------------- | --------------------------------------------------- |
-| `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.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              |
+| Inside a `cache()` boundary                                                        | Behavior                                                   |
+| ---------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `cookies()` / `headers()` (read or write)                                          | **throws** — request-scoped, would poison the entry        |
+| `ctx.request.headers`, `getRequestContext().cookie()` / `.cookies()`               | **throws** on read, like `headers()` / `cookies()`         |
+| 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                     |
+| Any read in the boundary's own `key()`, `keyGenerator`, `condition()` or `tags()`  | **allowed** — it picks or labels the entry, never rendered |
 
 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
+`cookies()`/`headers()`/`ctx.request.headers`, but its response writes still throw: on a hit the
 handler is skipped, so that loader never runs.
 
+`ctx.request.clone()` is guarded the same way. `fetch(ctx.request)` and
+`new Request(ctx.request)` don't throw, but the guard can't see through them:
+a fetch forwards the visitor's `Cookie` and `Authorization`, so its response
+is per visitor and must not be rendered inside the boundary. A handler that
+must render a header its `key()` partitions by reads a copy middleware set:
+
+```tsx
+const Tier = createVar<string>();
+const tierOf = (ctx: { request: Request }) =>
+  ctx.request.headers.get("x-tier") === "gold" ? "gold" : "silver";
+
+middleware(
+  async (ctx, next) => {
+    ctx.set(Tier, tierOf(ctx)); // middleware runs outside the boundary
+    return next();
+  },
+  () => [
+    cache({ ttl: 300, key: (ctx) => `tier:${tierOf(ctx)}` }, () => [
+      path("/pricing", (ctx) => <Pricing tier={ctx.get(Tier)} />),
+    ]),
+  ],
+);
+```
+
+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()`, `ctx.request.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 +866,15 @@ 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()` permits them (the
+leak above); `"use cache"` throws when the cached function is the first to
+read the loader in the request, because the loader body then runs inside it
+and its value is part of the result (a loader already started elsewhere
+returns its value unchecked, and that value is stored); 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 +920,11 @@ 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 `ttl`, `swr` and `store` for its subtree;
+`cache(false)` turns caching off for a subtree. The options that decide
+whether and where a record may be shared build up instead: `key` composes
+(see below), every enclosing `condition()` must allow the inner boundary, and
+the inner records carry the enclosing `tags` too:
 
 ```typescript
 cache({ ttl: 300 }, () => [
@@ -746,6 +940,130 @@ 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`).
+
+### Conditions and tags inherit
+
+```typescript
+cache(
+  {
+    condition: (ctx) => !ctx.request.headers.has("x-preview"),
+    tags: ["catalog"],
+  },
+  () => [
+    cache({ ttl: 60, tags: ["prices"] }, () => [
+      path("/prices", PricesPage, { name: "prices" }),
+    ]),
+  ],
+);
+```
+
+- A preview request renders the prices page live: the outer `condition()` bypasses
+  the inner record's read and write, and a `ppr` route's shell. Conditions
+  combine with AND, through a `cache(false)` with a `cache()` re-enabled
+  below it too.
+- The prices record carries `catalog` and `prices` (static and function
+  `tags` alike), so `updateTag("catalog")` evicts it, and the `ppr` shells
+  and documents built from it.
+- `cache(false)` is unchanged: it caches nothing below it until a `cache()`
+  re-enables caching.
+- A loader's own `cache()` and `"use cache"` are separate layers: they take
+  neither the route's `condition()` nor its `tags`, nor its `key()`
+  partition.
+
+Before issue #974, only the innermost boundary's `condition` and `tags`
+applied: a request an outer `condition()` refused still read and wrote the
+inner record, and `updateTag()` of an outer tag left it in place.
+
+### 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 ("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 ("key:tier%3Agold|key:v%3Ab")
+    cache(
+      { ttl: 60, key: (ctx) => `v:${ctx.searchParams.get("v") ?? "a"}` },
+      () => [path("/plans", PlansPage, { name: "plans" })],
+    ),
+  ]),
+]);
+```
+
+Every `key()` result is stored as `key:` plus its URI encoding; a default
+key in a composed key is URI-encoded. The parts are joined by `|`, `key()`
+results first, outermost first:
+
+| Boundary the route sits in                    | Record key                                                                                                                                                   |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| a single keyed `cache()`                      | Its `key()` result, namespaced (`tier:gold` is stored as `key:tier%3Agold`)                                                                                  |
+| `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), encoded                             |
+| `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                                                                      |
+| under a `cache({ store })` on another store   | Also that store's `keyGenerator` result, one part per store: empty for a store that returns the default key while another's differs, none when all return it |
+| `cache(false)`                                | No caching, as before; a `cache()` re-enabled below it stays in the partition                                                                                |
+| no `key` anywhere                             | The default key, or the store's `keyGenerator` result, as before                                                                                             |
+
+- No `key()` result, whatever it returns, equals a default key or a
+  composed key, and no two composed keys are equal: a namespaced result
+  starts with `key:` and holds no `|`, a default key never starts with
+  `key:`, and each part of a composed key is encoded, so the parts and their
+  kinds are recoverable. Returning request input from `key()` cannot name
+  another route's record (before issue #975 a header value
+  `doc:example.com/pricing` returned raw named the pricing page's default-keyed
+  record). A prefix (`tier:${value}`) is still worth it for readable keys,
+  and normalizing to the values you serve keeps the partition count bounded.
+- 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 store's `keyGenerator` partitions the records of a `cache()` on that
+  store without a `key()` of its own. A `cache({ store })` on another store
+  nested under it keys its records by that `keyGenerator` result too, so a
+  locale-partitioned outer boundary never shares an inner record across
+  locales. With several such stores each keeps its position: one that
+  returns the default key for a request adds an empty part while another's
+  differs, and when all return it the key is unchanged. A `keyGenerator` must
+  return the default key, not `""`, to leave a request unpartitioned: an
+  empty result there fails key resolution, so the request renders uncached,
+  and the router warns once naming the store. On the same store the inner
+  boundary's own default key already carries it (or its own `key()`
+  overrides it).
+- A response route's entry (`path.json()` and the other response routes) is
+  keyed the same way, behind a `response:` prefix. A `ppr` route's shell is
+  partitioned by the chain's `key()` results, namespaced the same way, since
+  the shell key already carries the URL (plus the `keyGenerator` results
+  above, and the store's 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. Before issue #974 an outer `cache({ store })`'s
+`keyGenerator` did not reach an inner boundary on another store.
+
 ## Custom Cache Store
 
 Create a dedicated store for specific routes:
@@ -765,6 +1083,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

@@ -134,7 +134,7 @@ flow into the generated route map, so `href()`, `ctx.reverse()` and
 | `loader()`     | `loader(Def, use?)` or `loader(Def, { ssr: false }, use?)` — see below                                                                                                                           |
 | `loading()`    | Route-level boundary around the optimistic render; inline `<Suspense>` at read sites keeps the destination's chrome visible while only the reads wait                                            |
 | `revalidate()` | Valid **inside a loader() use callback only**; runs in the browser                                                                                                                               |
-| `transition()` | Inside a `path()` use callback only (at most one). Data-only ViewTransition config — no `when`; same-route navs in a group already hold previous content without it                              |
+| `transition()` | Inside a `path()` use callback only (at most one). ViewTransition config plus a browser-run `when` predicate (see `/view-transitions`); same-route navs in a group already hold without it       |
 | `intercept()`  | Dot-local named target in the SAME definition; use may contain `loader()`/`loading()`                                                                                                            |
 
 At the top level of the builder only `path()`, `layout()` and `intercept()`
@@ -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