@rangojs/router 0.16.0 → 0.18.0

package/skills/caching/SKILL.md

@@ -1,62 +1,122 @@
 ---
 name: caching
-description: Configure route/segment-subtree caching with memory, Cloudflare KV, or Vercel cache stores in @rangojs/router. Use when responses should be cached or revalidated, data is stale or not updating after code changes, or you are wiring up a cache store.
+description: Configure segment caching with the cache() DSL in @rangojs/router — TTL/SWR, tags and updateTag/revalidateTag, loader-level caching, and the Memory, Cloudflare (Cache API + optional KV), and Vercel Runtime Cache stores. Use when responses should be cached or revalidated, data is stale or not updating after changes, or you are wiring up a cache store.
 argument-hint: "[setup]"
 ---
 
 # Caching
 
-@rangojs/router supports segment-level caching with stale-while-revalidate (SWR) for optimal performance.
+This skill covers the route-level `cache()` DSL (segment caching), loader-level
+caching, tag invalidation, and the built-in cache stores. `cache()` stores the
+rendered segments of a route subtree and serves them with a TTL and an optional
+stale-while-revalidate (SWR) window; loaders keep running on every request.
 
-> SWR support is store-specific. `CFCacheStore` revalidates segment, response,
-> and `"use cache"` entries in the background. `MemorySegmentCacheStore`
-> supports SWR for response and `"use cache"` item entries, but its
-> route-segment entries expire at TTL with no background revalidation — use
-> `CFCacheStore` for real segment SWR. See `/cache-guide`.
+> SWR support is store-specific. `CFCacheStore` and `VercelCacheStore` serve a
+> stale entry and revalidate it in the background for every entry family
+> (segments, responses, loader and `"use cache"` items, PPR shells).
+> `MemorySegmentCacheStore` does this for responses, items, and shells, but its
+> route-segment entries expire at `ttl` (the `swr` window is ignored) with no
+> background revalidation. Use `CFCacheStore` or `VercelCacheStore` to see
+> segment SWR. See `/cache-guide`.
 
 ## Not this skill if…
 
 - You want to cache ONE function or component's return value — that is
   `"use cache"`: see `/use-cache`.
-- You want the whole HTTP response frozen at the edge, loader output included —
-  see `/document-cache`.
-- You want the HTML shell cached while loaders stay live per request — see
-  `/ppr`.
+- You want the whole HTTP response frozen, loader output included — see
+  `/document-cache`.
+- You want the rendered HTML shell cached and only the live holes resumed per
+  request — that is the `ppr` path option: see `/ppr`.
+- You want segments rendered once at build time — see `/prerender`.
 - You are unsure which cache layer you need — start at `/cache-guide`.
 
-## cache() is Partial Prerendering (PPR)
+## What cache() caches: everything except loaders
 
 `cache()` caches **everything except loaders**. On a cache hit, the cached
 segments (layouts, route components, parallels — including any resolved
-Suspense) are served from the store, and **loaders re-run fresh on every
-request**, streaming their results into the same response. Loaders are the
-dynamic "holes" of an otherwise-cached tree.
+Suspense content) are served from the store, and **loaders re-run fresh on every
+request**, streaming their results into the same response. Loaders are the live
+holes of an otherwise-cached segment tree.
 
-This means a `cache()` boundary at the document root **is** whole-document
-Partial Prerendering: the static shell is cached and served instantly while
-per-request/per-user data stays live — in one streamed response, no extra round
-trip. The browser cannot tell the shell came from cache.
+A `cache()` boundary at the document root therefore gives you a cached shell
+with live loader holes, in one streamed response with no extra round trip. The
+browser cannot tell the segments came from cache. This is a Flight segment
+cache: HTML is still rendered on every request. The `ppr` path option is a
+separate layer that also caches the rendered HTML shell and resumes only the
+holes — see `/ppr`, and `/cache-guide` for how the layers stack.
 
 ```typescript
 cache({ ttl: 60, swr: 300 }, () => [
-  layout(<RootLayout />), // cached shell
+  layout(<RootLayout />), // cached
   path("/dashboard", Dashboard, { name: "dashboard" }, () => [
-    loader(StatsLoader), // DYNAMIC HOLE — re-runs every request
+    loader(StatsLoader), // live hole — re-runs every request
   ]),
 ]);
 ```
 
-The consumer rule: **want it cached? render it inline. want it dynamic? 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; awaiting it with `ctx.use()` and rendering the result in a cached
-handler silently bakes per-request data into the shared shell (see "Cache purity
-& tainted objects" below).
+`cache()` covers only its own subtree. A layout declared above the boundary is
+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, and a shell never outlives the route `cache()` entry it was captured
+from (it is fresh and served no longer than that entry; `/ppr`).
 
-Pre-rendering (`/prerender`) is the build-time twin: it caches the same shell at
-build time instead of on first request. Both feed the segment system
-identically, and loaders always run fresh at request time.
+```typescript
+layout(AccountShell, () => [
+  // live: runs on every request, cache hits included
+  cache({ ttl: 60 }, () => [
+    path("/products/:id", ProductPage, { name: "product" }), // cached
+  ]),
+]);
+```
+
+A `cache()` among a path's own children caches that one path: its handler and
+its own layouts and parallels. Every other item in the list still attaches to
+the path, and everything above the path stays live:
+
+```typescript
+layout(AccountShell, () => [
+  // live
+  path("/products/:id", ProductPage, { name: "product" }, () => [
+    cache({ ttl: 60 }), // caches ProductPage and ProductChrome
+    layout(ProductChrome),
+  ]),
+]);
+```
+
+A `cache()` inside a `layout()` or `middleware()` wrapper in the path does the
+same: `layout(ProductChrome, () => [cache({ ttl: 60 })])` caches the whole
+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:
+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).
+
+Handle pushes follow the same split. Handler pushes (`ctx.use(Meta)`,
+`ctx.use(Breadcrumbs)`, custom handles) are stored with the segments and
+replayed on a hit. Pushes from a `loader()` body are not stored: the loader
+re-runs on the hit and pushes again, so each value appears once. A loader that
+runs only because a cached handler awaited it with `ctx.use(Loader)` does not
+re-run on a hit, so its pushes are stored with the handler's.
+
+A component that throws while the entry is written is not cached. Writing
+re-renders the segments, so an async server component whose fetch fails there
+would otherwise be stored as an error and rendered on every hit. Instead the
+write is skipped and reported to `onError` (phase `"cache"`, category
+`cache-write`): the next request renders fresh, and a stale entry keeps serving.
+The same applies to a stored handle push whose value fails to encode, such as a
+rejected promise: the whole entry is skipped, not just its handles.
+
+Pre-rendering (`/prerender`) is the build-time counterpart: it stores the same
+kind of segment payload at build time instead of on first request. Both feed the
+segment system identically, and loaders always run fresh at request time.
 
 ## Route-Level Caching with cache()
 
@@ -66,7 +126,8 @@ Use the `cache()` DSL function to cache routes:
 import { urls } from "@rangojs/router";
 
 export const urlpatterns = urls(({ path, cache }) => [
-  // Cache these routes for 60 seconds, SWR for 5 minutes
+  // Fresh for 60 seconds, then served stale for up to 5 more minutes
+  // while it refreshes in the background
   cache({ ttl: 60, swr: 300 }, () => [
     path("/blog", BlogIndex, { name: "blog" }),
     path("/blog/:slug", BlogPost, { name: "blogPost" }),
@@ -77,13 +138,24 @@ export const urlpatterns = urls(({ path, cache }) => [
 ]);
 ```
 
+`cache()` needs a store — the app-level one (see "Global Cache Configuration")
+or a per-boundary `store` option. Without one, the boundary renders live.
+
 ## Cache Options
 
+Every option is optional. Omitted `ttl`/`swr` fall back to the store's
+`defaults`.
+
 ```typescript
 cache(
   {
-    ttl: 60, // Time-to-live in seconds (default: 60)
-    swr: 300, // Stale-while-revalidate window (default: 300)
+    ttl: 60, // seconds fresh. Default: store.defaults.ttl, else 60
+    swr: 300, // seconds a stale entry is served while it refreshes.
+    //           Default: store.defaults.swr, else no SWR window
+    tags: ["blog"], // or (ctx) => string[]; see "Tag-Based Invalidation"
+    key: (ctx) => `blog:${ctx.pathname}`, // replaces the default key entirely
+    condition: (ctx) => !ctx.request.headers.has("x-preview"), // false = bypass
+    store: blogStore, // per-boundary store; see "Custom Cache Store"
   },
   () => [
     // Cached routes
@@ -91,6 +163,22 @@ cache(
 );
 ```
 
+- **Default key**: `{doc|partial|intercept}:{host}{pathname}[:params][?search]`
+  — 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. 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.
+- `cache(false, () => [...])` disables caching for a subtree (see "Nested Cache
+  Boundaries").
+
 ## When cache() does not pay
 
 A cache hit is not free: it still runs middleware, the store read, and the
@@ -114,6 +202,8 @@ Caching") over caching the rendered segment.
 Tag cached entries, then invalidate them on demand. Tags can be attached four ways:
 
 ```typescript
+import { cacheTag } from "@rangojs/router";
+
 // 1. Static tags in the cache() DSL
 cache({ ttl: 300, tags: ["products"] }, () => [path("/products", List)]);
 
@@ -133,22 +223,39 @@ async function getProduct(id: string) {
 // 4. Render-callable — a plain server component (no "use cache" in its tree)
 //    records onto the request's document/shell artifact.
 function CampaignBanner() {
-  cacheTag("campaign:spring"); // rides ctx._requestTags → shell/document entry
+  cacheTag("campaign:spring"); // tags the ppr shell / document-cache entry
   return <aside>Spring sale</aside>;
 }
 ```
 
-Form 4 is how you make a PPR shell or a `/document-cache` page tag-invalidatable
-without wrapping anything in `"use cache"`: the tag rides the request's
-`_requestTags` onto the shell/document entry, and `revalidateTag` then evicts it.
-On a route that is neither PPR nor document-cached the tag records where nothing
-reads it — a silent no-op, so don't expect a bare `cacheTag()` to tag an ordinary
-uncached page.
+Each tag attaches to one entry, so know which entry you are tagging:
+
+- 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. 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`):
 
 ```typescript
+import { updateTag, revalidateTag } from "@rangojs/router";
+
 // Server Action — read-your-own-writes. Await it so the action's own re-render
 // (and the next navigation) sees fresh data.
 async function updateProduct(formData: FormData) {
@@ -157,10 +264,9 @@ async function updateProduct(formData: FormData) {
   await updateTag("products");
 }
 
-// Route handler / webhook — background, non-blocking (waitUntil). Hard-purge:
-// the next read re-renders fresh (NOT stale-while-revalidate).
-export async function POST() {
-  "use server";
+// Webhook or response-route handler — background, non-blocking (waitUntil).
+// Hard purge: the next read re-renders fresh (NOT stale-while-revalidate).
+function onProductsChanged() {
   revalidateTag("products");
   return new Response("ok");
 }
@@ -171,10 +277,38 @@ export async function POST() {
 | `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 |
 
-All three built-in stores support tags. For `CFCacheStore`, distributed (cross-colo)
-invalidation requires a `kv` namespace — the tag-invalidation markers live in
-that same namespace; there is **no** separate tag-invalidation store to wire.
-If no tag-capable store is configured, `updateTag`/`revalidateTag` warn and no-op.
+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
+fails, so you can retry; `revalidateTag()` reports the failure to `onError`
+(phase `"cache"`, category `cache-invalidate`) instead.
+
+All three built-in stores support tags. If no tag-capable store is configured,
+`updateTag`/`revalidateTag` warn and no-op.
+
+For `CFCacheStore`, cross-colo invalidation needs either a `kv` namespace
+(marker mode — the tag-invalidation markers live in that same namespace; there
+is **no** separate tag-invalidation store to wire) or `tagPurge` (purge mode,
+below). With neither, invalidation logs a warning and has no effect.
 
 By default `CFCacheStore` reads the KV marker on every tagged cache read
 (strongest invalidation latency). To cut KV reads on hot tagged routes, set
@@ -196,14 +330,37 @@ Purge-by-tag is available on all plans (since April 2025), subject to per-plan
 rate limits, so the batched single call matters. With a purge wired, `tagCacheTtl`
 becomes a pure read-cost reducer + fallback window.
 
+**Purge mode (`tagPurge`).** Instead of checking a KV marker on every L1 read,
+the store can evict tagged L1 entries with Cloudflare's purge-by-tag API:
+
+```typescript
+new CFCacheStore({
+  ctx,
+  kv: env.CACHE_KV,
+  tagPurge: { zoneId: env.CF_ZONE_ID, apiToken: env.CF_PURGE_TOKEN },
+});
+```
+
+The token needs the `Zone.Cache Purge` permission; keep it in a Worker secret.
+You can also pass a `(cacheTags) => Promise<void>` function (for a proxy or a
+test stub); `createCloudflareZonePurge({ zoneId, apiToken })` from
+`@rangojs/router/cache` builds the default one. In purge mode every tagged L1
+entry carries a namespaced `Cache-Tag`, `updateTag()`/`revalidateTag()` await one
+batched purge call, and L1 hits skip the marker lookup. The KV tier and PPR shell
+reads still use KV markers, so keep `kv` configured when you have it; without
+`kv`, purge mode is the only tag invalidation and the store runs L1-only. A
+failed purge makes `updateTag()` reject. Purge-by-tag clears only your zone:
+`workers.dev` previews have an inert Cache API.
+
 ## Named Cache Profiles
 
-Define named profiles in `createRouter({ cacheProfiles })` so the same TTL/SWR
-values can be shared across the DSL and `"use cache"` functions without repetition.
-Unknown names throw at boot time.
+Named profiles in `createRouter({ cacheProfiles })` are for the
+`"use cache: <name>"` directive only (see `/use-cache`). `default` is built in as
+`{ ttl: 900, swr: 1800 }` and can be overridden. An invalid profile name or
+ttl/swr value throws when the router is created; an unknown profile name throws
+on the first call of a function that uses it.
 
 ```typescript
-// Define profiles in router
 createRouter({
   cacheProfiles: {
     default: { ttl: 900, swr: 1800 },
@@ -213,7 +370,8 @@ createRouter({
 });
 ```
 
-In the DSL, pass the profile's options directly to `cache()`:
+The DSL `cache()` helper does NOT accept a profile name — pass the options
+object directly:
 
 ```typescript
 export const urlpatterns = urls(({ path, cache }) => [
@@ -221,23 +379,34 @@ export const urlpatterns = urls(({ path, cache }) => [
     path("/blog", BlogIndex, { name: "blog" }),
   ]),
 
-  // Orphan cache boundary (covers subsequent siblings)
+  // Orphan cache boundary: with no children callback it covers the
+  // siblings that follow it
   cache({ ttl: 60, swr: 120 }),
   path("/feed", FeedPage, { name: "feed" }),
 ]);
 ```
 
-The DSL `cache()` helper does NOT accept a string profile name — strings are only
-valid in the `"use cache: <name>"` directive inside server functions. See
-`/use-cache` for function-level caching with named profiles.
+In a layout's children, a `layout()` after the bare `cache()` wraps every
+route of that layout, as it would without the `cache()`. It is cached only with
+the routes after the `cache()`; on a route before it, it renders live:
+
+```typescript
+layout(<AppShell />, () => [
+  path("/a", PageA, { name: "a" }), // PromoBanner renders live
+  cache({ ttl: 60 }),
+  layout(<PromoBanner />),
+  path("/b", PageB, { name: "b" }), // PromoBanner cached with PageB
+]);
+```
 
 ## Loader-Level Caching
 
-Cache individual loaders:
+Loaders are never part of a segment entry. To cache a loader's DATA, give the
+loader its own `cache()`:
 
 ```typescript
 path("/product/:slug", ProductPage, { name: "product" }, () => [
-  // Cache this loader's results
+  // Cache this loader's results for 5 minutes
   loader(ProductLoader, () => [cache({ ttl: 300 })]),
 
   // This loader is not cached
@@ -245,15 +414,38 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 ]);
 ```
 
+A loader `cache()` takes the same options as the DSL (`ttl`, `swr`, `tags`,
+`key`, `condition`, `store`) and is stored in the store's item family, so SWR
+works on every built-in store. Without options, `cache()` uses the store's
+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. 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
 
-Configure a cache store in the router:
+Configure the app-level store on the router. `cache()` boundaries, cached
+loaders, `"use cache"`, `ppr` shells, and `createDocumentCacheMiddleware()` all
+use it.
 
 ```typescript
 import { createRouter } from "@rangojs/router";
 import { MemorySegmentCacheStore } from "@rangojs/router/cache";
 
 const store = new MemorySegmentCacheStore({
+  // On the memory store `swr` applies to loader, "use cache", response and
+  // shell entries; route segments expire at ttl.
   defaults: { ttl: 60, swr: 300 },
 });
 
@@ -262,11 +454,14 @@ const router = createRouter({
   urls: urlpatterns,
   cache: {
     store,
-    enabled: true,
+    enabled: true, // false = no app store for the request: every layer above is off
   },
 });
 ```
 
+`cache` may also be a function `(env, ctx) => ({ store, enabled?, searchParams? })`
+when the store needs runtime bindings (Cloudflare, Vercel).
+
 ### Search param key filtering (`cache.searchParams`)
 
 By default every non-reserved query param keys the cache, so
@@ -308,23 +503,32 @@ already expressible with `cache({ key })`.
 
 ## Cache Stores
 
+| Store                     | Import                  | Use for                                            |
+| ------------------------- | ----------------------- | -------------------------------------------------- |
+| `MemorySegmentCacheStore` | `@rangojs/router/cache` | dev, tests, single-process Node deployments        |
+| `CFCacheStore`            | `@rangojs/router/cache` | Cloudflare Workers (Cache API L1 + optional KV L2) |
+| `VercelCacheStore`        | `@rangojs/router/cache` | Vercel Functions (Vercel Runtime Cache)            |
+
 ### Memory Store
 
-For single-instance deployments:
+For development, tests, and single-instance deployments. Entries live in
+process memory, so each instance has its own cache and a restart empties it.
 
 ```typescript
 import { MemorySegmentCacheStore } from "@rangojs/router/cache";
 
 const store = new MemorySegmentCacheStore({
-  defaults: { ttl: 60, swr: 300 },
+  defaults: { ttl: 60 }, // segments ignore swr on this store
   maxEntries: 1000, // per-family FIFO cap (default 1000)
+  name: "app", // optional: keep entries across Vite HMR module reloads
 });
 ```
 
 Each internal family (segments, responses, `"use cache"` items, PPR shells) is
 capped at `maxEntries`; on insert past the cap the oldest entry is evicted FIFO
 and its tag-index entries are cleaned up, so a long-lived process cannot grow
-without bound. TTL expiry stays lazy on top of the cap.
+without bound. TTL expiry stays lazy on top of the cap. Two stores with the same
+`name` share their backing maps.
 
 ### Cloudflare Edge Cache Store
 
@@ -338,7 +542,7 @@ const router = createRouter<AppBindings>({
   urls: urlpatterns,
   cache: (env, ctx) => ({
     store: new CFCacheStore({
-      ctx,
+      ctx: ctx!, // ExecutionContext, required (non-blocking writes)
       defaults: { ttl: 60, swr: 300 },
     }),
     enabled: true,
@@ -346,6 +550,10 @@ const router = createRouter<AppBindings>({
 });
 ```
 
+`CFCacheStore` prefixes every key with the build version, so a deploy never
+reads the previous build's entries (override with `version`). See `/cache-guide`
+→ "Cross-deploy safety" and `/cloudflare` for bindings.
+
 ### With KV L2 Persistence
 
 Add a KV namespace for global cross-colo persistence. On Cache API miss, KV is
@@ -359,7 +567,7 @@ const router = createRouter<AppBindings>({
   urls: urlpatterns,
   cache: (env, ctx) => ({
     store: new CFCacheStore({
-      ctx,
+      ctx: ctx!,
       kv: env.CACHE_KV, // optional KV namespace binding
       defaults: { ttl: 60, swr: 300 },
     }),
@@ -376,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
 
@@ -397,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,
@@ -453,6 +730,54 @@ deployment KV keeps markers hot in its per-colo edge cache, so it stays a few
 milliseconds. `match-error` (a transient `cache.match` rejection that falls
 through to L2) is kept distinct from a plain `l1-miss`.
 
+### Vercel Runtime Cache Store
+
+For Vercel Functions. Pass the Runtime Cache handle from `@vercel/functions`;
+the store adds SWR, tag invalidation, and the family split on top of it.
+
+```typescript
+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({
+      cache: runtimeCache,
+      waitUntil,
+      defaults: { ttl: 60, swr: 300 },
+    }),
+  }),
+});
+```
+
+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
+`/vercel` for the preset and the remaining options (`version`, `name`, `debug`).
+
 ## Cache purity & tainted objects
 
 A `cache()` boundary caches everything except loaders, so anything read inside a
@@ -460,26 +785,35 @@ 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 |
-| `ctx.header()` / `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 loader**                            | **allowed** — loaders always run fresh              |
+| 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.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              |
+
+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, and
-the cache scope is tracked via async-local state. Two flags back the guards:
-`INSIDE_CACHE_EXEC` (set while a `"use cache"` function runs) and the `cache()`
-DSL scope (`isInsideCacheScope()`). `isInsideCacheScope()` deliberately returns
-`false` inside loaders — which is exactly why loaders are the dynamic holes:
-they may read `cookies()`/`headers()` and re-run on every request.
+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
+loaders — which is exactly why loaders are the live holes: they may read
+`cookies()`/`headers()` and re-run on every request.
 
 The fix for "I need request data in a cached route": register a `loader()` and
 **consume it with `useLoader()` in a client component**. The loader is the
-dynamic hole — its data rides the fresh (never-cached) loader segment and is
-rendered in the client component, so it never lands in the cached shell.
+live hole — its data rides the fresh (never-cached) loader segment and is
+rendered in the client component, so it never lands in the cached entry.
 
 This is NOT the same as awaiting the loader in the handler. A cached handler
 that does `await ctx.use(Loader)` and renders the result bakes that per-request
@@ -489,20 +823,21 @@ 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. Stated once in `/rango` → Invariants; pinned by
-semantic-matrix row PPR3 and the `e2e/cache.test.ts` "baked copy" case.
+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
 cache({ ttl: 60 }, () => [
-  path("/me", () => <Profile id={cookies().get("uid")?.value} />),
+  path("/me", () => <Profile id={cookies().get("uid")?.value} />, { name: "me" }),
 ]);
 
 // ALSO WRONG (unguarded, but leaks) — the awaited loader data is rendered into
-// the cached handler, so the user's data is frozen into the shared shell.
+// the cached handler, so the user's data is frozen into the shared entry.
 cache({ ttl: 60 }, () => [
   path(
     "/me",
@@ -522,10 +857,11 @@ cache({ ttl: 60 }, () => [
 // profile.tsx (client component)
 "use client";
 import { useLoader } from "@rangojs/router/client";
+import { MeLoader } from "./loaders";
 
 export function Profile() {
-  const { user } = useLoader(MeLoader); // fresh per request; never cached
-  return <span>{user.name}</span>;
+  const { data } = useLoader(MeLoader); // fresh per request; never cached
+  return <span>{data.user.name}</span>;
 }
 
 // urls — register the loader; MeLoader reads cookies() inside the loader (allowed)
@@ -538,20 +874,98 @@ See `/cache-guide` for the full decision guide and the `cache()` vs `"use cache"
 
 ## Nested Cache Boundaries
 
-Override cache settings for specific sections:
+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
-// Global cache
 cache({ ttl: 300 }, () => [
   path("/blog", BlogIndex, { name: "blog" }),
 
-  // Override: shorter TTL for dynamic content
+  // Override: shorter TTL for this section
   cache({ ttl: 30 }, () => [
     path("/blog/:slug", BlogPost, { name: "blogPost" }),
   ]),
+
+  // Opt out: always rendered live
+  cache(false, () => [path("/blog/drafts", Drafts, { name: "drafts" })]),
+]);
+```
+
+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:
@@ -567,6 +981,20 @@ cache({ store: checkoutCache }, () => [
 ]);
 ```
 
+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
@@ -591,7 +1019,8 @@ export const urlpatterns = urls(({ path, layout, cache, loader, revalidate }) =>
     layout(<BlogLayout />, () => [
       path("/blog", BlogIndex, { name: "blog" }),
       path("/blog/:slug", BlogPost, { name: "blogPost" }, () => [
-        loader(BlogPostLoader, () => [cache()]),  // Use boundary cache settings
+        // Uses the app store's defaults, not the enclosing boundary's options
+        loader(BlogPostLoader, () => [cache()]),
       ]),
     ]),
   ]),
@@ -601,7 +1030,10 @@ export const urlpatterns = urls(({ path, layout, cache, loader, revalidate }) =>
     path("/shop/product/:slug", ProductPage, { name: "product" }, () => [
       loader(ProductLoader, () => [cache({ ttl: 120 })]),
       loader(CartLoader, () => [
-        revalidate((ctx) => ctx.isAction(CartActions) || undefined),
+        // after an action, re-run only for cart actions; on navigation, keep the default
+        revalidate((ctx) =>
+          ctx.isAction() ? ctx.isAction(CartActions) : undefined,
+        ),
       ]),
     ]),
   ]),