@rangojs/router 0.16.0 → 0.18.0

package/skills/cache-guide/SKILL.md

@@ -1,42 +1,98 @@
 ---
 name: cache-guide
-description: When to use cache() DSL vs "use cache" directive — key differences and decision guide. Use when unsure which caching mechanism fits a given problem, comparing route/segment caching, function-level caching, and document-level caching, or asking "which cache API should I use".
+description: Decision guide for Rango's cache layers — "use cache", loader cache(), segment cache(), Prerender/Static, the ppr HTML shell, and document/CDN caching — with the cache() vs "use cache" comparison (keys, guards, SWR, nesting). Use when unsure which caching mechanism fits a problem, comparing layers, or asking "which cache API should I use".
 argument-hint:
 ---
 
-# cache() vs "use cache" — When to Use Which
-
-Both mechanisms share the same backing store and cache profiles, and both accept
-an optional `tags` field (honored by the built-in stores — invalidate with
-`updateTag`/`revalidateTag`; see "Two axes" below). They differ in scope, cache
-key, execution model, and runtime control.
+# Choosing a cache layer
+
+Start here when you are not sure which cache to use. The first section maps
+every layer; the rest of the page compares the two you will reach for most,
+the `cache()` DSL and the `"use cache"` directive.
+
+## The layers at a glance
+
+Each layer stores a more "cooked" artifact than the one above it, and keeps less
+of the request live on a hit. The runtime layers share the app-level store
+(`createRouter({ cache })`) and one tag system (`cacheTag` / `updateTag` /
+`revalidateTag`); `Prerender()`/`Static()` output is built into the server
+bundle instead.
+
+| Layer                | Declared with                                  | Stores                                                   | Still runs on a hit                                    | Skill                 |
+| -------------------- | ---------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------ | --------------------- |
+| Function / component | `"use cache"`                                  | one function's return value                              | everything around the call                             | `/use-cache`          |
+| Loader data          | `loader(L, () => [cache({...})])`              | one loader's result                                      | other loaders, handlers, rendering                     | `/caching`, `/loader` |
+| Segments, runtime    | `cache({...}, () => [...])`                    | rendered Flight segments of a subtree                    | middleware, segments above it, loaders, HTML render    | `/caching`            |
+| Segments, build time | `Prerender()` / `Static()`                     | Flight segments rendered at build                        | middleware, loaders, HTML render                       | `/prerender`          |
+| HTML shell           | `ppr` path option                              | HTML prelude + React postponed state + the handler layer | middleware and live loaders (no handler); holes resume | `/ppr`                |
+| Whole response (app) | `createDocumentCacheMiddleware()` + `s-maxage` | final response in the app store                          | middleware above it; nothing below                     | `/document-cache`     |
+| Whole response (CDN) | `Cache-Control: s-maxage` read by the platform | final response outside the app                           | nothing — the app is not invoked                       | `/deployment-caching` |
+
+Quick rules:
+
+- Expensive **data** used in several places → `"use cache"` on the fetch.
+- Expensive **rendering** of a route subtree → `cache()`.
+- Content fixed at **build time** (known params, files on disk) → `Prerender()`.
+- **Instant first byte** of HTML while parts stay per-request → `ppr`.
+- **Whole response** public and identical for everyone → `/document-cache` or
+  CDN caching (`/deployment-caching`).
+- A value that must be fresh on **every** request → a loader (never cached
+  unless you opt in), read with `useLoader()`; on a `ppr` route, keep it off
+  `ssr: false`. A handler inside a `cache()` or `ppr` boundary that awaits
+  `ctx.use(Loader)` renders the value it got on the miss, and every hit
+  replays that output.
+
+The layers compose: `"use cache"` inside a `cache()` subtree, a cached loader
+under a `cache()` boundary, `cache()` segments replayed inside a `ppr` shell
+capture, or `Prerender()` + `ppr` for a shell baked at build time.
+
+## cache() vs "use cache"
+
+Both mechanisms use the same app-level store, and both can be tagged
+(`cache({ tags })`; profile `tags` or runtime `cacheTag()` for `"use cache"`) and
+invalidated with `updateTag`/`revalidateTag` — see "Two axes" below. Named
+cache profiles apply to `"use cache"` only. They differ in scope, cache key,
+execution model, and runtime control.
 
 ## Two axes — do not conflate
 
-Everything on this page is **axis 1: stored-value freshness** — _is a cached
-value still good?_ There is a second, orthogonal axis it is easy to mistake for
+Everything on this page is **stored-value freshness** — _is a cached value
+still good?_ There is a second, orthogonal concern it is easy to mistake for
 caching:
 
-1. **Stored-value freshness** — _is a cached value still good?_
-   → `"use cache"` (fn/component), `cache()` (segment), loader `cache()` (loader data).
-   Entries expire by **TTL/SWR** and can be tagged (`cache({ tags })` or runtime
-   `cacheTag(...tags)` — inside `"use cache"` it tags that entry; called during a
-   request render outside `"use cache"` it tags the document/shell artifact).
-   Built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`)
-   index by tag; invalidate on demand with `updateTag(...tags)` (awaitable,
-   read-your-own-writes) or `revalidateTag(...tags)` (background, non-blocking).
-   Both hard-purge; the difference is awaitability, not stale-serving.
+1. **Stored-value freshness** — _is a cached value still good?_ → `"use cache"`
+   (fn/component), `cache()` (segment), loader `cache()` (loader data). Entries
+   expire by **TTL/SWR** and can be tagged (`cache({ tags })` or runtime
+   `cacheTag(...tags)` — inside `"use cache"` it tags that entry; called during
+   a request render outside `"use cache"` it tags what the render stores: the
+   enclosing route `cache()` entry, a cached loader's own entry when called in
+   its body, and the `ppr` shell or document-cache entry built from them; on a
+   `ppr` route it tags the shell only when shell material calls it). All
+   built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`,
+   `VercelCacheStore`) index by tag; invalidate on demand with
+   `updateTag(...tags)` (awaitable) or `revalidateTag(...tags)` (background,
+   non-blocking). Both evict rather than mark stale, and the request that calls
+   either reads its own writes; `updateTag()` also waits for the durable write,
+   `revalidateTag()` leaves it in the background. `CFCacheStore` and
+   `VercelCacheStore` serve PPR shell reads through per-isolate memos: the
+   invalidating user skips them via the fresh-reads cookie, other users see the
+   invalidation once the memo refreshes and, on `CFCacheStore` with KV, once KV
+   propagates the marker to their colo (`/caching` → "Tag-Based Invalidation"
+   and "The fresh-reads cookie").
 2. **Client-update selection** — _should this segment re-run and stream to the
    client on this navigation/action?_
    → `revalidate()`. Covered in `/loader` and `/route`, **not here**.
 
 They are orthogonal and compose: a segment selected by `revalidate()` still
-consults its cache (hit → no recompute); a cache bust does **not** force a client
+consults its cache (hit → no recompute), except that a server action's
+revalidation render skips the route `cache()` lookup and re-renders those
+segments fresh (a loader's own `cache()` and `"use cache"` are still read); a
+cache bust does **not** force a client
 update, and `revalidate()` never reads, writes, or expires a cached value. If you
 know React Router, `revalidate()` is `shouldRevalidate`, not `Cache-Control`. See
 `/rango` → "Coming from another framework" for the cross-framework mapping.
 
-## Fast choice
+## Fast choice: cache() or "use cache"
 
 Read this first; use the rest of the page when the choice has edge cases.
 
@@ -62,20 +118,35 @@ protection the framework already gives you (or assume one it deliberately
 doesn't).
 
 There are two guard models to keep separate. Both block response side effects
-(`ctx.header()`, cookie writes) that would be lost on a hit; they differ in what
+(`ctx.headers.set()`, cookie writes) that would be lost on a hit; they differ in what
 else they allow:
 
 - **`cache()` boundary guard** (route-level) — fires while the handler runs on a
   miss. `cookies()` and `headers()` throw (request-scoped data would be baked into
   the shared cached shell), `ctx.get(nonCacheableVar)` throws (a tainted value
-  would be baked in), and response side effects (`ctx.header()`, `ctx.setCookie()`,
-  `ctx.setStatus()`, `ctx.onResponse()`) throw. `ctx.set()` of a cacheable var is
+  would be baked in), and response side effects (`ctx.headers.set()`,
+  `setCookie()`, `setStatus()`, `onResponse()`) throw. `ctx.set()` of a cacheable var is
   **allowed** — children are cached too and can read it. **Loaders are exempt**
-  (they always run fresh) — read request data inside a loader.
+  (a route `cache()` does not store their values) — read request data inside a
+  loader.
+- **Loader `cache()` guard** (a loader bound with its own `cache()`) — its value
+  is stored under a key that names no user, so a miss whose body read
+  `cookies()`, `headers()`, the theme or a non-cacheable `ctx.get()` fails
+  unless the binding has a `key()` or its store a `keyGenerator`. Either one
+  switches the check off, so put what the body reads in it (`/loader` →
+  "Cache Key").
 - **`"use cache"` exec-guard** (function-level) — the same request-scoped APIs
   throw inside the cached function (`cookies()`, `headers()`, `ctx.set()`,
-  `ctx.header()`); additionally, tainted `ctx`/`env`/`req` args are excluded from
-  the cache key.
+  `ctx.headers.set()` and other response writes); additionally, tainted
+  `ctx`/`env`/`req` args are excluded from the cache key. The guard runs only on
+  the cached path: with no item-capable store configured the function runs
+  uncached and nothing throws.
+
+The `ppr` shell capture has its own, stricter guard: `cookies()`, `headers()`, a
+theme read, a `{ cache: false }` variable read, and `ctx.dynamic()` refuse the
+capture anywhere it waits — handlers, promises they pass or push, async server
+components, `ssr: false` loaders, and loaders a handler awaits (no loader
+exemption there). The route then serves uncached; see `/ppr`.
 
 ### Cross-deploy safety: version-segmented store keys
 
@@ -94,7 +165,9 @@ deliberately: accept it (correctness over hit-rate), or split the policy — let
 the render/edge cache auto-version while a separate data store gets a stable
 `version` so its entries survive deploys. (Per-process stores like
 `MemorySegmentCacheStore` are cold on every restart anyway; this matters for
-persistent stores.) See `/caching` for store setup.
+persistent stores.) `VercelCacheStore` does not version automatically: pass a
+per-deploy `getCache({ namespace })` or its `version` option (see `/vercel`).
+See `/caching` for store setup.
 
 ### Client cache: forward/back is mutation-aware
 
@@ -110,9 +183,10 @@ solved on the partial-render axis.
 
 `createVar({ cache: false })` (or a `ctx.set(var, v, { cache: false })` write)
 taints a value as request-scoped; reading it **directly** with `ctx.get()` inside
-a `cache()` boundary throws — the guard against the catastrophic "serve user A's
-data to user B" bug. The guarantee is precise and intentionally narrow — see
-"Context Variable Cache Safety" below for exactly what it does and does not catch.
+a `cache()` boundary or a `"use cache"` function throws — the guard against the
+catastrophic "serve user A's data to user B" bug. The guarantee is precise and
+intentionally narrow — see "Context Variable Cache Safety" below for exactly
+what it does and does not catch.
 
 ## Stale-while-revalidate
 
@@ -139,40 +213,58 @@ recompute for a merely-aging entry.
 SWR softens normal TTL expiry, **not** a cross-deploy cold cache — a new build
 has no stale entry to serve (see version-segmented store keys above).
 
-Store support is layer-specific. `CFCacheStore` supports SWR for segment,
-document/response, and `"use cache"` item entries. `MemorySegmentCacheStore`
-supports SWR for response and `"use cache"` item entries, but its route-segment
-entries expire at TTL and never background-revalidate. Use the memory store for
+Store support is layer-specific. `CFCacheStore` and `VercelCacheStore` support
+SWR for segment, document/response, item (`"use cache"` and cached loaders), and
+PPR shell entries. `MemorySegmentCacheStore` supports SWR for response, item,
+and shell entries, but its route-segment entries expire at `ttl` (the `swr`
+window is dropped) and never background-revalidate. Use the memory store for
 local/dev behavior, not as proof that segment SWR is active.
 
 ## Key Differences
 
-|                      | `cache()` DSL                                         | `"use cache"` directive                            |
-| -------------------- | ----------------------------------------------------- | -------------------------------------------------- |
-| **Scope**            | Route segment tree (handler + children + parallels)   | Single function return value                       |
-| **Defined at**       | Route definition site (`urls.ts`)                     | Inside function body or at file top                |
-| **Cache key**        | Request type + pathname + params (+ optional custom)  | Function identity + serialized non-tainted args    |
-| **Execution on hit** | All-or-nothing: entire handler skipped                | Partial: function body skipped, calling code runs  |
-| **Runtime control**  | `condition` to disable, custom `key` function         | None — if the directive is present, it caches      |
-| **Side effects**     | Response side effects throw inside the boundary       | `ctx.header()`, `ctx.set()`, etc. throw at runtime |
-| **Handle data**      | Captured and replayed                                 | Captured and replayed                              |
-| **Loaders**          | Always fresh — excluded from cache, opt-in per loader | Can be used inside loaders                         |
-| **Nesting**          | Nest `cache()` boundaries with different TTLs         | Compose by calling cached functions from uncached  |
+|                      | `cache()` DSL                                         | `"use cache"` directive                           |
+| -------------------- | ----------------------------------------------------- | ------------------------------------------------- |
+| **Scope**            | Route segment tree (handler + children + parallels)   | Single function return value                      |
+| **Defined at**       | Route definition site (`urls.ts`)                     | Inside function body or at file top               |
+| **Cache key**        | Request type + host + pathname + params + search      | Function identity + serialized non-tainted args   |
+| **Execution on hit** | All-or-nothing: entire handler skipped                | Partial: function body skipped, calling code runs |
+| **Runtime control**  | `condition` to disable, custom `key` function         | None — if the directive is present, it caches     |
+| **Side effects**     | Response side effects throw inside the boundary       | `ctx.headers.set()`, `ctx.set()`, etc. throw      |
+| **Handle data**      | Handler pushes replayed; loader pushes re-run live    | Captured and replayed when it receives `ctx`      |
+| **Loaders**          | Always fresh — excluded from cache, opt-in per loader | Can be used inside loaders                        |
+| **Nesting**          | Inner TTLs override; `key()` partitions compose       | Compose by calling cached functions from uncached |
 
 ### cache() Cache Key
 
-The key is `{requestType}:{pathname}:{params}` where requestType is one of
-`doc:`, `partial:`, or `intercept:`. This means the same URL cached separately
-for full document loads, client navigations, and intercept navigations.
-
-Custom `key` functions can segment the cache further (e.g., by user role or locale).
-`condition` can disable caching entirely at runtime (e.g., skip for authenticated users).
+The default key is `{requestType}:{host}{pathname}[:params][?search]`, where
+requestType is `doc`, `partial`, or `intercept`. The same URL is therefore cached
+separately for full document loads, client navigations, and intercept
+navigations. The host keeps tenants apart when one deployment serves several
+domains; the search part is sorted, excludes the router's internal params, and
+honors `createRouter({ cache: { searchParams } })`.
+
+A custom `key` function replaces the whole default key (e.g., to key by user role
+or locale); it also bypasses the store's `keyGenerator` and the search-param
+filter. It runs once per request and may read `cookies()`. A nested `cache()`
+keys its records within the enclosing `key()` partition (`/caching` → "Keys
+nest"). Never return raw request input from `key()`: normalize it to the
+values you serve or prefix it. On a `ppr` route, `key()` (and a store
+`keyGenerator` that returns a non-default key) also partitions the shell: one
+shell per value, and a partitioned request never reads a build-time shell.
+Keep the values to a small set. `condition` can disable caching entirely at
+runtime (e.g., skip for authenticated users).
 
 ### "use cache" Cache Key
 
 The key is `use-cache:{functionId}:{serializedArgs}` where functionId is a stable
-ID from the Vite transform (module path + export name) and args are serialized via
-RSC `encodeReply()`. Tainted arguments (ctx, env, req) are excluded.
+ID from the Vite transform (module path + export name) and args are serialized
+(stable JSON when every arg is JSON-safe, RSC `encodeReply()` otherwise).
+Request-scoped arguments are excluded: route fields read off `ctx` (handler,
+loader or middleware: host, route name, pathname, params, search) and a
+`Request`'s URL are folded in, and `env`
+is left out. React element slots stay out of the key; any other argument that
+cannot be serialized (a function, a class instance) runs the call uncached. See
+`/use-cache`.
 
 ## Execution Model
 
@@ -180,17 +272,22 @@ This is the most important distinction.
 
 ### cache() — all-or-nothing
 
-On cache hit, the cache-lookup middleware short-circuits the entire pipeline.
-No handler code runs. On miss, all handlers execute normally and segments are
-stored.
+On cache hit, the cache-lookup middleware short-circuits segment resolution for
+the boundary: no handler inside it runs. Segments above the boundary are not in
+the entry and resolve as on an uncached render. On miss, all handlers execute
+normally and the boundary's segments are stored.
 
 ```
-HIT  → cached segments served, loaders resolved fresh, no handler runs
-MISS → all handlers run, segments cached, response built normally
+HIT  → segments above the boundary resolved, cached segments served, loaders resolved fresh, no handler in the boundary runs
+MISS → all handlers run, the boundary's segments cached, response built normally
 ```
 
-Headers, cookies, and ctx.set() calls inside handlers naturally don't execute on
-hit. There is no partial execution, so no runtime guards are needed.
+`ctx.set()` calls are safe: every handler that could read the value is inside the
+same cached unit, so a hit replays a consistent subtree. Response side effects
+and request-scoped reads are not safe — a write would reach only MISS responses
+and a `cookies()` read would be baked into the shared entry — so the boundary
+guard throws on them even on a miss (see "Correctness & invalidation" above and
+"Headers and Cookies" below).
 
 ### "use cache" — partial execution
 
@@ -203,11 +300,13 @@ HIT  → function body skipped, calling code runs, handle data replayed
 MISS → function body runs, return value + handle data cached
 ```
 
-Runtime guards throw if you call cookies(), headers(), ctx.header(), ctx.set(),
-ctx.onResponse(), ctx.setTheme(), or ctx.setLocationState() inside a "use cache"
-function. cookies() and headers() are blocked because per-request data is not in the
-cache key. Side-effect methods are blocked because their effects are lost on hit.
-Use ctx.use(Handle) instead for data — handle data is captured and replayed.
+Runtime guards throw if you call `cookies()`, `headers()`, `ctx.set()`,
+`ctx.headers.set()` (or any response write: cookie writes, `setStatus()`,
+`onResponse()`), `ctx.setTheme()`, or `ctx.setLocationState()` inside a
+`"use cache"` function. `cookies()` and `headers()` are blocked because
+per-request data is not in the cache key. Side-effect methods are blocked because
+their effects are lost on hit. Use `ctx.use(Handle)` instead for data — handle
+data is captured and replayed.
 
 ## When to Use cache()
 
@@ -230,6 +329,11 @@ export const urlpatterns = urls(({ path, cache }) => [
 ]);
 ```
 
+On a `ppr` route, `cache(false)` or a `condition()` that returns false also
+means no shell: that route (or that request) renders like a cache miss, with
+no shell served or captured. A `ppr` route cannot opt out of a layout's
+`cache()` and still get a shell.
+
 ## When to Use "use cache"
 
 Use the `"use cache"` directive when:
@@ -250,10 +354,11 @@ async function getProductData(slug: string) {
   return await db.query("SELECT * FROM products WHERE slug = ?", [slug]);
 }
 
-// Handler calls cached function, sets headers outside
+// Handler calls cached function, sets headers outside it
+// (this route is not inside a cache() boundary or a ppr route)
 async function ProductPage(ctx) {
   const data = await getProductData(ctx.params.slug);
-  ctx.header("X-Product", data.id);
+  ctx.headers.set("X-Product", data.id);
   return <Product data={data} />;
 }
 ```
@@ -299,21 +404,39 @@ does **not** keep a value fresher than its parent:
 So `"use cache: short"` (60s) inside `cache({ ttl: 600 })` yields ~600s freshness
 on hits, **not** 60s. This is not a bug: setting `cache({ ttl: 600 })` declares
 "this subtree may be ~600s stale." **If a value must be fresher than its
-enclosing segment, put it in a loader** (always live). `debugPerformance` prints
-cache hits per layer, so the actual per-request behavior is observable.
+enclosing segment, put it in a loader** read with `useLoader()` (without
+`ssr: false` on a `ppr` route). `debugPerformance` prints cache hits per
+layer, so the actual per-request behavior is observable.
+
+Keys and tags cross the nesting too:
+
+- An inner `cache()` without `key` keys its records within the outer `key()`
+  partition; one with its own `key` composes both (`/caching` → "Keys nest").
+- Tags that `cacheTag()` calls and `"use cache"` reads record inside a
+  `cache()` subtree are stored on that `cache()` entry, so `updateTag()` of one
+  of them evicts it (and a `ppr` shell or document built from it) instead of
+  waiting for it to expire.
+- A `ppr` shell never outlives the route `cache()` entry it was captured
+  from: its ttl and ttl + swr are capped to what that entry has left.
 
 ## Headers and Cookies
 
 Neither mechanism caches response headers or cookies.
 
 - **cache()**: Response-level side effects throw inside the cache boundary even
-  on a miss: `ctx.header()`, `ctx.setCookie()`, `ctx.deleteCookie()`,
-  `ctx.setStatus()`, `ctx.onResponse()`, and direct `ctx.headers` mutation. On a
-  hit the handler would be skipped, so allowing the write on a miss would produce
-  inconsistent responses. If you need headers or cookies on every response, set
-  them in middleware or a live segment outside the cache boundary.
-- **"use cache"**: cookies() and headers() throw inside the cached function
-  (both reads and writes). ctx.header() also throws. Move them outside.
+  on a miss: `ctx.headers` mutation (`ctx.headers.set()` etc.), `cookies()`
+  (read or write), and the request-context writers `header()`, `setCookie()`,
+  `deleteCookie()`, `setStatus()`, `onResponse()`. On a hit the handler would be
+  skipped, so allowing the write on a miss would produce inconsistent responses.
+  Registered loaders are exempt (they run on every request, hits included). If
+  you need headers or cookies on every response, set them in middleware, a live
+  segment outside the cache boundary, or a loader.
+- **"use cache"**: `cookies()` and `headers()` throw inside the cached function
+  (both reads and writes), and so do `ctx.headers` mutations. Move them outside.
+- **`ctx.theme`** (handler and middleware) and **`getRequestContext().theme`**
+  are the visitor's theme cookie, so a read throws in both scopes, like
+  `cookies()`. Read it with `useTheme()` in a client component, or in a
+  loader (see the `/theme` skill).
 
 ```typescript
 // Set headers that must appear on every response in middleware
@@ -327,8 +450,9 @@ middleware(async (ctx, next) => {
 
 Context variables created with `createVar()` are cacheable by default and can
 be read freely inside cached scopes. A non-cacheable var throws when read
-**directly** with `ctx.get()` inside a `cache()` boundary — where the value would
-otherwise be serialized into the stored segment.
+**directly** with `ctx.get()` inside a `cache()` boundary or a `"use cache"`
+function — where the value would otherwise be serialized into the stored
+segment or entry without being part of its key.
 
 There are two ways to mark a value as non-cacheable:
 
@@ -345,30 +469,36 @@ specifies `cache: false`, the value is non-cacheable.
 
 **Behavior inside a `cache()` boundary:**
 
-| Operation                                 | Inside a `cache()` boundary                            |
-| ----------------------------------------- | ------------------------------------------------------ |
-| `cookies()` / `headers()` (read or write) | Throws (request-scoped, would poison the shared entry) |
-| `ctx.get(cacheableVar)`                   | Allowed                                                |
-| `ctx.get(nonCacheableVar)`                | Throws (would be baked in)                             |
-| `ctx.set(var, value)` (cacheable)         | Allowed                                                |
-| `ctx.header()` / cookie writes            | Throws (response side effect would be lost on hit)     |
-| Any of the above **inside a loader**      | Allowed (loaders always run fresh)                     |
+| Operation                                          | Inside a `cache()` boundary                                                        |
+| -------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `cookies()` / `headers()` (read or write)          | Throws (request-scoped, would poison the shared entry)                             |
+| `ctx.theme`, `getRequestContext().theme`           | Throws, like `cookies()` (#971)                                                    |
+| `ctx.get(cacheableVar)`                            | Allowed                                                                            |
+| `ctx.get(nonCacheableVar)`                         | Throws (would be baked in)                                                         |
+| `ctx.set(var, value)` (cacheable)                  | Allowed                                                                            |
+| `ctx.headers.set()` / cookie writes                | Throws (response side effect would be lost on hit)                                 |
+| Any of the above **inside a loader**               | Allowed (loaders always run fresh)                                                 |
+| The reads above in a loader with its own `cache()` | The miss fails without a `key()`; any `key()` allows them, so it must include them |
 
 (Both scopes block the same request-scoped APIs — `cookies()`, `headers()`,
 response side effects, and non-cacheable `ctx.get()` — because each would leak
 per-request data into a shared cache entry. The `cache()` boundary tracks the
 scope via `isInsideCacheScope()`; `"use cache"` uses the exec guard and also
 excludes tainted `ctx`/`env`/`req` args from the cache key. Loaders are exempt in
-both — see "Headers and Cookies" and the precise guarantee below.)
+both — see "Headers and Cookies" and the precise guarantee below. Under `"use
+cache"` the exemption covers a loader body the cached function consumes
+(`await ctx.use(Loader)`), not a cached function a loader calls: the loader
+re-runs on every request, the cached body does not.)
 
 Write is dumb — `ctx.set()` stores the cache metadata but does not enforce.
 Enforcement happens at read time (`ctx.get()`), where ALS detects the cache
 scope and rejects non-cacheable reads.
 
-### The guarantee is precise — a direct read inside `cache()`, not propagating
+### The guarantee is precise — a direct read inside a cache scope, not propagating
 
 The guard fires on a **direct** `ctx.get(taintedVar)` **inside a `cache()`
-boundary** (the scope `isInsideCacheScope` detects). The taint lives on the
+boundary** (the scope `isInsideCacheScope` detects) **or a `"use cache"`
+function body**. The taint lives on the
 variable; a value **derived** from it and read **outside** the boundary is not
 tracked:
 
@@ -396,35 +526,47 @@ layout((ctx) => {
 So do **not** read this as "you can't cache user data" — that overstates it and
 breeds the false confidence that makes the derived leak _more_ likely. The guard
 is deliberately non-propagating (propagation would cost a wrapper per derivation
-on the hot path), and it is scoped to the `cache()` segment boundary. `"use
-cache"` functions block the same request-scoped reads (`cookies()` / `headers()`
-throw inside them) and additionally exclude tainted `ctx`/`env`/`req` args from
-the cache key. The pattern that stays safe is also the natural one:
+on the hot path), and it is scoped to the `cache()` segment boundary and the
+`"use cache"` body. `"use cache"` functions block the same request-scoped reads
+(`cookies()` / `headers()` and non-cacheable `ctx.get()` throw inside them) and
+additionally exclude tainted `ctx`/`env`/`req` args from the cache key — pass a
+non-cacheable value in as an argument so it becomes part of the key. The pattern that stays safe is also the natural one:
 **read tainted context at the point of use, in the path that needs it (a loader or
 live segment) — never extract user data into a plain value and cache that.**
 Loaders are exempt because they run outside the cache scope and resolve fresh
-every request.
+every request. A loader with its own `cache()` does not: its value is stored,
+so it falls under the loader `cache()` guard above.
 
 ## Loaders Are Always Fresh
 
-Loaders are **never cached** by route-level `cache()`. Even on a full cache hit
-where all UI segments are served from cache, loaders are re-resolved fresh on
-every request. This is enforced at two levels:
-
-1. **Storage**: `cacheRoute()` filters out loader segments before serialization
-   (`segments.filter(s => s.type !== "loader")`).
-2. **Retrieval**: On cache hit, `resolveLoadersOnly()` runs after yielding cached
-   UI segments, ensuring fresh data regardless of cache state.
-
-This means `cache()` gives you cached UI + fresh data by default. To also cache
-a loader's data, explicitly opt in with `loader(Fn, () => [cache({...})])`.
+Loaders are **never cached** by route-level `cache()`. Even on a cache hit
+where the boundary's UI segments are served from cache, loaders are re-resolved
+fresh on every request. This is enforced at two levels:
+
+1. **Storage**: `cacheRoute()` filters out loader segments before serialization.
+2. **Retrieval**: On cache hit, `resolveLoadersOnly()` runs the boundary's
+   loaders after yielding its cached UI segments (the loaders above the boundary
+   run with their live segments), ensuring fresh data regardless of cache state.
+
+This means `cache()` gives you cached UI + fresh data by default, where the
+data is read outside the cached output: `useLoader()` in a client component.
+A handler inside the boundary that awaits `ctx.use(Loader)` renders the value
+it got on the miss, and every hit replays that output. On a `ppr` route an
+`ssr: false` loader is the other exception: it bakes into the shell (`/ppr`).
+To also cache a loader's data, explicitly opt in with
+`loader(Fn, () => [cache({...})])`.
+That entry is keyed by loader, host, path and params, not by the route's
+`key()`, so give it a `key()` that includes any request data its body reads;
+without one the miss fails.
 
 ## cache() Placement Patterns
 
-### Wrapping children of a path
+### cache() among a path's children
 
-An orphan `cache()` inside a path's children becomes the parent for all
-subsequent siblings. Everything below the cache boundary is cached as one unit:
+A `cache()` among a path's children caches that path. The path's handler and
+its own layouts and parallels are one cached unit, wherever the `cache()` sits
+in the list. Every other item still attaches to the path, and the segments
+above the path stay live:
 
 ```typescript
 path("/dashboard", DashboardPage, { name: "dashboard" }, () => [
@@ -433,34 +575,66 @@ path("/dashboard", DashboardPage, { name: "dashboard" }, () => [
     parallel("@stats", StatsPanel),
     parallel("@activity", ActivityFeed),
   ]),
+  loader(DashboardLoader),
 ]),
 ```
 
 On hit: DashboardPage, DashboardSidebar, StatsPanel, and ActivityFeed are all
-served from cache. On miss: all handlers run, all segments cached together.
+served from cache, and DashboardLoader runs fresh. On miss: all handlers run and
+the path's segments are cached together. DashboardPage runs inside the boundary,
+so the guards apply to it: a header write there throws. The wrapper form
+`cache({ ttl: 300 }, () => [layout(DashboardSidebar)])` inside a path does the
+same, and `cache(false)` there opts the path out of an enclosing `cache()` (on a
+`ppr` route, out of the shell too). The same form caches a response route:
+`path.json("/api/feed", handler, { name: "feed" }, () => [cache({ ttl: 60 })])`.
+A `cache()` inside a `layout()` or `middleware()` wrapper in the path caches the
+path too: `layout(DashboardSidebar, () => [cache({ ttl: 300 })])` is the same
+unit as the example above, not the sidebar alone.
+
+### Bare cache() among a layout's children
+
+A `cache()` with no children callback covers the routes after it. The
+`layout()`, `parallel()`, `loader()` and `middleware()` items after it still
+wrap every route of the layout, including the routes before the `cache()`;
+they are cached only with the routes after it:
+
+```typescript
+layout(<AppShell />, () => [
+  path("/a", PageA, { name: "a" }), // PromoBanner renders live on /a
+  cache({ ttl: 60 }),
+  layout(<PromoBanner />),
+  path("/b", PageB, { name: "b" }), // PromoBanner cached with /b
+]),
+```
+
+With no route after the `cache()`, nothing is cached. To cache
+`<PromoBanner />` with PageA too, put the `cache()` before PageA's `path()`.
+A `cache()` among PageA's own children does not cover it: the banner belongs
+to the layout, above that path's boundary.
 
 ### Uncached layout with cached children
 
 The cache boundary only covers what's inside it. Parent segments above the
-boundary are not cached and always re-render:
+boundary are not cached and always re-render, cache hits included:
 
 ```typescript
 layout(RootLayout, () => [
   // RootLayout is NOT cached — runs every request
-  path("/products/:slug", ProductPage, { name: "product" }, () => [
-    cache({ ttl: 300 }),
-    layout(ProductSidebar),
-    parallel("@reviews", ReviewsPanel),
-    parallel("@related", RelatedProducts),
+  cache({ ttl: 300 }, () => [
+    path("/products/:slug", ProductPage, { name: "product" }, () => [
+      parallel("@reviews", ReviewsPanel),
+      parallel("@related", RelatedProducts),
+    ]),
   ]),
 ]),
 ```
 
-RootLayout renders fresh every request. ProductPage, ProductSidebar,
-ReviewsPanel, and RelatedProducts are all inside the cache boundary and
-served from cache on hit. This is useful when the root layout depends on
-request-specific data (user session, theme) but the product content is
-cacheable.
+RootLayout renders fresh every request, and a header it writes lands on every
+response. ProductPage, ReviewsPanel, and RelatedProducts are inside the cache
+boundary and served from cache on hit. This is useful when the root layout
+depends on request-specific data (user session, theme) but the product content
+is cacheable. On a `ppr` route the shell bakes RootLayout too: a shell HIT runs
+no layout, and the shell expires no later than this `cache()` entry.
 
 ### Loader-level caching
 
@@ -479,14 +653,22 @@ path("/product/:slug", ProductPage, { name: "product" }, () => [
 ```
 
 This attaches the cache config directly to the loader entry. The loader's
-data is cached independently from the route's segment cache. Loader caching
+data is cached independently from the route's segment cache, together with
+the handle pushes its body made (replayed on every hit). Loader caching
 supports custom keys, tags, SWR, conditional bypass, and per-loader store
-overrides — see `/loader` for the full reference.
+overrides — see `/loader` for the full reference. A body that reads
+`cookies()`, `headers()` or a non-cacheable variable needs a `key()`, which
+must include the value: without one the miss fails, and any `key()` switches
+that check off. The entry also carries the tags its body recorded
+(`cacheTag()` calls, `"use cache"` reads, and those of the loaders it reads
+with `ctx.use()`), so `updateTag()` of any of them drops it.
 
 ## See Also
 
-- `/caching` — cache() DSL setup, stores, nested boundaries
+- `/caching` — cache() DSL setup, stores, tags, nested boundaries
 - `/use-cache` — "use cache" directive details, profiles, transforms, guards
+- `/loader` — loader-level caching and the loader context
+- `/prerender` — build-time segments with `Prerender()`/`Static()`
+- `/ppr` — PPR shell caching: cached HTML shell + live holes (different layer)
 - `/document-cache` — store-backed complete-response middleware
 - `/deployment-caching` — in-function versus external CDN cache boundaries
-- `/ppr` — PPR shell caching: cached HTML shell + live loader holes (different layer)