@rangojs/router 0.16.0 → 0.17.0

package/skills/caching/SKILL.md

@@ -1,62 +1,118 @@
 ---
 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.
 
-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
+(loaders always run fresh). 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 +122,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 +134,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 +159,17 @@ 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.
+- **`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 +193,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 +214,29 @@ 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. 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`).
+- 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.
 
 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 +245,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 +258,19 @@ 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.
+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 +292,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 +332,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 +341,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 +376,29 @@ 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. See `/loader` for the full
+loader reference.
+
 ## 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 +407,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 +456,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 +495,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 +503,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 +520,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 },
     }),
@@ -453,6 +614,34 @@ 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";
+
+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 }),
+      waitUntil,
+      defaults: { ttl: 60, swr: 300 },
+    }),
+  }),
+});
+```
+
+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 +649,28 @@ 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.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.
 
 **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
@@ -492,17 +683,16 @@ 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.
+`useLoader` = live. 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 +712,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,17 +729,20 @@ 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;
+`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" })]),
 ]);
 ```
 
@@ -567,6 +761,10 @@ 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.
+
 ## Complete Example
 
 ```typescript
@@ -591,7 +789,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 +800,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,
+        ),
       ]),
     ]),
   ]),