@rangojs/router 0.17.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/breadcrumbs/SKILL.md

@@ -103,13 +103,16 @@ Delivery follows the loader race model: a push that beats the handler barrier
 is in the SSR'd document; a push after a slow fetch streams and applies
 client-side (`useHandle` re-renders when it lands). To guarantee document
 delivery, register the loader as `loader(Def, { ssr: false })` —
-see `/loader` → "Writing Handles from Loaders". Under `cache()` loader crumbs
-are not stored with the cached segments; the loader re-pushes them on every
-hit, so they appear once even without an `href`. A loader with its own
-`cache()` keeps its crumbs on its own hits too: they are replayed from the
-loader's cache entry. A crumb from a loader it awaits appears once even when
-a sibling loader or the handler reads that loader too; that live run's crumb
-replaces the cached one in the trail.
+see `/loader` → "Writing Handles from Loaders". On a `ppr` route the race is
+decided at capture: a loader without `ssr: false` never runs there, so its
+crumb is not in the shell and applies client-side on every HIT; with
+`ssr: false` the crumb bakes into the shell (`/ppr` → "On a shell HIT").
+Under `cache()` loader crumbs are not stored with the cached segments; the
+loader re-pushes them on every hit, so they appear once even without an `href`.
+A loader with its own `cache()` keeps its crumbs on its own hits too: they are
+replayed from the loader's cache entry. A crumb from a loader it awaits appears
+once even when a sibling loader or the handler reads that loader too; that live
+run's crumb replaces the cached one in the trail.
 
 ## Async Content
 
@@ -134,6 +137,13 @@ path("/product/:id", async (ctx) => {
 Async content is a `Promise<ReactNode>`. Resolve it in your component
 with React's `use()` hook wrapped in `<Suspense>`.
 
+A crumb the HANDLER pushes is handler output. In a route `cache()` entry and
+in a `ppr` shell it is stored resolved: the cache write, or the shell capture
+(within `ppr.captureTimeout`), waits for a `content` promise and for a
+`.defer()` slot (below), and every HIT replays the crumb as it was resolved
+then, without running the handler. For per-request crumb content, push it
+from a loader without `ssr: false` (see "Pushing from Loaders").
+
 ### Deferred content (decide now, resolve from a deep component)
 
 When the handler should DECIDE to push a crumb early but the value is produced

package/skills/cache-guide/SKILL.md

@@ -18,15 +18,15 @@ of the request live on a hit. The runtime layers share the app-level store
 `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  | middleware, handlers, loaders; only the 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` |
+| 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:
 
@@ -37,7 +37,10 @@ Quick rules:
 - **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).
+  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
@@ -53,25 +56,38 @@ 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).
-   All built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`,
-   `VercelCacheStore`) 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.
@@ -107,18 +123,47 @@ 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
+  the shared cached shell), and so do the raw reads `ctx.request.headers` and
+  `getRequestContext().cookie()` / `.cookies()` (#976);
+  `ctx.get(nonCacheableVar)` throws (a tainted value
   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()`, `ctx.request.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.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
+  throw inside the cached function (`cookies()`, `headers()`,
+  `ctx.request.headers`, `ctx.set()`, `ctx.headers.set()` and other response
+  writes); additionally, tainted `ctx`/`env`/`req` args are excluded from the
+  cache key (a `Request` argument keys by its URL only). The guard runs only
+  on the cached path: with no item-capable store configured the function runs
   uncached and nothing throws.
 
+All three guards leave a cache's own callbacks alone: a `key()`, a store
+`keyGenerator`, a `condition()` and a `tags()` function may read `cookies()`,
+`headers()` or `ctx.request.headers`, because the value picks or labels the
+entry rather than being rendered into it. So does `onError`, which only
+observes. A `"use cache"` function or loader they call is guarded as usual.
+
+`ctx.request.clone()` is guarded like `ctx.request.headers`. The remaining gap:
+`fetch(ctx.request)` and `new Request(ctx.request)` don't throw and aren't
+guarded. A fetch forwards the visitor's `Cookie` and `Authorization`, so its
+response is per visitor; don't make one in a cached body.
+
+The `ppr` shell capture has its own, stricter guard: `cookies()`, `headers()`,
+`ctx.request.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
 
 `CFCacheStore` prefixes every **physical** store key (the CF Cache API URL and
@@ -193,17 +238,17 @@ 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 + 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**          | 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; inner tags reach the outer entry |
 
 ### cache() Cache Key
 
@@ -216,8 +261,18 @@ 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. `condition` can disable caching entirely at runtime (e.g., skip for
-authenticated users).
+filter. It runs once per request and may read `cookies()`. Its result is
+stored namespaced (`key:` plus its URI encoding), so no value it returns, raw
+request input included, names another route's record. A nested `cache()`
+keys its records within the enclosing `key()` partition (`/caching` → "Keys
+nest"). Normalize the result to the values you serve: each distinct value is
+a record. 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), for every `cache()` nested under it too, and an
+outer `cache()`'s `tags` tag the nested records (`/caching` → "Conditions
+and tags inherit").
 
 ### "use cache" Cache Key
 
@@ -267,8 +322,9 @@ MISS → function body runs, return value + handle data cached
 
 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
+`onResponse()`), `ctx.setTheme()`, or `ctx.setLocationState()`, or read
+`ctx.request.headers`, inside a `"use cache"` function. `cookies()`,
+`headers()` and `ctx.request.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.
@@ -294,6 +350,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:
@@ -364,8 +425,20 @@ 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
 
@@ -380,7 +453,12 @@ Neither mechanism caches response headers or cookies.
   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.
+  (both reads and writes), and so do `ctx.request.headers` reads and
+  `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
@@ -413,24 +491,27 @@ 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.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)                     |
+| Operation                                                            | Inside a `cache()` boundary                                                        |
+| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `cookies()` / `headers()` (read or write)                            | Throws (request-scoped, would poison the shared entry)                             |
+| `ctx.request.headers`, `getRequestContext().cookie()` / `.cookies()` | Throws, like `headers()` / `cookies()` (#976)                                      |
+| `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. 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.)
+excludes tainted `ctx`/`env`/`req` args from the cache key. Loaders are exempt
+under `cache()` — see "Headers and Cookies" and the precise guarantee below.
+Under `"use cache"` nothing is exempt: a loader body the cached function
+consumes (`await ctx.use(Loader)`) is part of the cached result, and a cached
+function a loader calls does not re-run with the loader.)
 
 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
@@ -470,13 +551,18 @@ 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 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
+(`cookies()` / `headers()`, `ctx.request.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.
+Loaders are exempt from the `cache()` guard because they run outside the cache
+scope and resolve fresh every request. A loader with its own `cache()` does not:
+its value is stored, so it falls under the loader `cache()` guard above. Nor
+does a loader awaited inside a `"use cache"` body: its value is part of what the
+function returns, so the same reads throw there when the cached function is
+the first to read it in the request (an already-started loader's value is
+stored unchecked).
 
 ## Loaders Are Always Fresh
 
@@ -489,8 +575,16 @@ fresh on every request. This is enforced at two levels:
    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. To also cache
-a loader's data, explicitly opt in with `loader(Fn, () => [cache({...})])`.
+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
 
@@ -513,16 +607,16 @@ path("/dashboard", DashboardPage, { name: "dashboard" }, () => [
 ```
 
 On hit: DashboardPage, DashboardSidebar, StatsPanel, and ActivityFeed are all
-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()`. The same form caches a response route:
+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.
+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
 
@@ -566,8 +660,8 @@ 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 whole chain bakes into the shell, so there
-`cache()` covers RootLayout too.
+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
 
@@ -589,7 +683,12 @@ This attaches the cache config directly to the loader entry. The loader's
 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()`, `ctx.request.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