@rangojs/router 0.18.0 → 0.19.0

package/package.json

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

package/skills/cache-guide/SKILL.md

@@ -123,7 +123,9 @@ 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**
@@ -131,19 +133,33 @@ else they allow:
   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
+  `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.
 
-The `ppr` shell capture has its own, stricter guard: `cookies()`, `headers()`, a
-theme read, a `{ cache: false }` variable read, and `ctx.dynamic()` refuse the
+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`.
@@ -222,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**          | Inner TTLs override; `key()` partitions compose       | 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
 
@@ -245,14 +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. It runs once per request and may read `cookies()`. A nested `cache()`
+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"). 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).
+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
 
@@ -302,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.
@@ -432,7 +453,8 @@ 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
@@ -469,26 +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.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 |
+| 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
@@ -528,14 +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. A loader with its own `cache()` does not: its value is stored,
-so it falls under the loader `cache()` guard above.
+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
 
@@ -657,7 +684,7 @@ 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. A body that reads
-`cookies()`, `headers()` or a non-cacheable variable needs a `key()`, which
+`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

package/skills/caching/SKILL.md

@@ -90,7 +90,8 @@ 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:
+with `cookies()`, `headers()`, `ctx.request.headers`, or a non-cacheable
+variable belongs in a loader:
 a route `cache()` does not store loader values, so a loader runs on every
 request. A loader bound with its own `cache()` is stored, so without a `key()`
 its miss fails; any `key()` switches that check off, so it must include the
@@ -167,14 +168,20 @@ cache(
   — document requests, client navigations, and intercept navigations are cached
   separately. The search part honors `cache.searchParams` (below).
 - **`key`** is a full override: it bypasses the default key, the store's
-  `keyGenerator`, and the search-param filter. A nested `cache()` keys its
-  records within that partition (see "Keys nest" under "Nested Cache
-  Boundaries"). On a `ppr` route the same key
-  (or, without one, the store's `keyGenerator`) partitions the PPR shell: each
-  partition captures and serves its own shell (`/ppr`, "Request-partitioned
-  shells").
+  `keyGenerator`, and the search-param filter. The result is stored
+  namespaced (`key:` plus its URI encoding), so whatever it returns, request
+  input included, never names another route's default-keyed record or a
+  nested partition's. A nested `cache()` keys its records within that
+  partition (see "Keys nest" under "Nested Cache Boundaries"). On a `ppr`
+  route the same key (or, without one, the store's `keyGenerator`)
+  partitions the PPR shell: each partition captures and serves its own shell
+  (`/ppr`, "Request-partitioned shells").
 - **`condition`** returning `false` skips both the cache read and write for that
-  request (the boundary renders live).
+  request (the boundary renders live). It gates every `cache()` nested under
+  it too: an inner boundary caches only when every enclosing `condition()`
+  allows it.
+- **`tags`** tag this boundary's records and those of every `cache()` nested
+  under it, so `updateTag()` of an outer tag evicts the inner records too.
 - `cache(() => [...])` with no options uses the store defaults.
 - `cache(false, () => [...])` disables caching for a subtree (see "Nested Cache
   Boundaries").
@@ -230,8 +237,11 @@ function CampaignBanner() {
 
 Each tag attaches to one entry, so know which entry you are tagging:
 
-- Forms 1 and 2 tag the `cache()` segment entry.
-- Form 3 tags the `"use cache"` entry (plus any profile `tags`).
+- Forms 1 and 2 tag the `cache()` segment entry, and the entries of every
+  `cache()` nested under it (see "Conditions and tags inherit").
+- Form 3 tags the `"use cache"` entry (plus any profile `tags`), and every
+  `"use cache"` entry that calls that function: the outer entry bakes the
+  inner value, so it carries the inner tags.
 - Form 4 tags the request's `ppr` shell entry (`/ppr`) or `/document-cache`
   entry, with no `"use cache"` needed. On a route that is neither `ppr` nor
   document-cached and has no `cache()`, nothing reads the tag — a silent
@@ -283,18 +293,21 @@ request, so an action that calls `revalidateTag()` and then renders gets fresh
 `"use cache"` and `cache()` reads, as with `await updateTag()`. What
 `revalidateTag()` does not wait for is the durable write (the KV marker, the
 tag purge, Vercel's `expireTag`): other requests see the invalidation once it
-lands. A `"use cache"` call that this request started before the
-invalidation, and that carries one of the invalidated tags, is not reused
-after it and does not store its value; neither does a stale entry's
-background refresh. The tags are the call's own (its `cacheTag()` calls and
-profile `tags`): a nested `"use cache"` function's tags do not reach the
-enclosing entry, so invalidating one of them neither evicts the outer entry
-nor stops an outer call already running
-([#980](https://github.com/rangojs/rango/issues/980)). Not covered
-([#977](https://github.com/rangojs/rango/issues/977)): such a call started
-by another request, or a loader's own `cache()` that started before the
-invalidation, still stores its value when it finishes, and reads after that
-can get it.
+lands.
+
+Work that started before the invalidation, in this request or another one,
+is not stored after it. A `"use cache"` call, a stale entry's background
+refresh, a loader's own `cache()`, a route `cache()` render or a
+document-cache render that read its data before one of its tags was
+invalidated still returns what it read, but its store write is skipped:
+every store stamps an entry when it is written, so the old value would be
+served as newer than the invalidation. The next read runs it again. A
+`"use cache"` call already running when one of its tags is invalidated is
+not joined by later calls either. Its tags include those of the
+`"use cache"` functions it calls. Another isolate's invalidation is caught
+through the store's markers (`CFCacheStore` with KV, `VercelCacheStore`); on
+a KV-less `CFCacheStore` only this isolate's invalidations are, and ttl+swr
+bounds the rest.
 
 Both must run inside a request (action, handler, middleware, response route).
 Called from a queue consumer or cron job, there is no request context, so they
@@ -428,8 +441,9 @@ does. See `/loader` for the full loader reference.
 
 The entry's default key is the loader, host, path and params. It does not
 inherit an enclosing `cache()` boundary's `key()` either, so it is shared
-across users: a body that reads `cookies()`, `headers()` or a non-cacheable
-variable fails on a miss unless the loader `cache()` has a `key()` or its store
+across users: a body that reads `cookies()`, `headers()`, `ctx.request.headers`
+or a non-cacheable variable fails on a miss unless the loader `cache()` has a
+`key()` or its store
 a `keyGenerator`. Either one switches the check off, so it must itself include
 the value (`/loader` → "Cache Key").
 
@@ -615,8 +629,10 @@ times out, or whose snapshot is truncated or corrupt (also evicted), cannot
 replay the captured segment record, so it degrades: the entry is replaced and
 recaptured and the page reloads once into a cache-miss render (`/ppr`). The
 snapshot holds only what a HIT reads: every HIT replays the handler layer from
-the captured segment record, so the `"use cache"` items only handler code read
-are not stored.
+the captured segment record and serves an `ssr: false` loader's baked
+container, so no `"use cache"` or loader `cache()` item is stored in it. A
+live hole, and any loader that runs on the HIT, reads those from the store
+under their own ttl/swr and tags.
 
 **Shell memo.** After a shell read, the same isolate serves that key's next
 HITs from memory for `memo.shellMs` (default 2000; `{ shellMs: 0 }` turns it
@@ -785,22 +801,49 @@ cached handler is **frozen into the shared cache entry** and served to every
 subsequent visitor. To stop one user's request-scoped data from leaking to
 another, request-scoped APIs are guarded inside a cache scope:
 
-| Inside a `cache()` boundary                                                        | Behavior                                            |
-| ---------------------------------------------------------------------------------- | --------------------------------------------------- |
-| `cookies()` / `headers()` (read or write)                                          | **throws** — request-scoped, would poison the entry |
-| Response writes: `ctx.headers.set()`, `setCookie()`, `setStatus()`, `onResponse()` | **throws** — response side effects lost on a hit    |
-| `ctx.get(var)` where the var is `{ cache: false }`                                 | **throws** on read                                  |
-| `ctx.theme`, `getRequestContext().theme`                                           | **throws** — the theme is the visitor's cookie      |
-| `ctx.set(var, value)` for a cacheable var                                          | allowed (children are cached too)                   |
-| Any of the above **inside a registered loader** (`loader(...)`)                    | **allowed** — loaders always run fresh              |
+| Inside a `cache()` boundary                                                        | Behavior                                                   |
+| ---------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `cookies()` / `headers()` (read or write)                                          | **throws** — request-scoped, would poison the entry        |
+| `ctx.request.headers`, `getRequestContext().cookie()` / `.cookies()`               | **throws** on read, like `headers()` / `cookies()`         |
+| Response writes: `ctx.headers.set()`, `setCookie()`, `setStatus()`, `onResponse()` | **throws** — response side effects lost on a hit           |
+| `ctx.get(var)` where the var is `{ cache: false }`                                 | **throws** on read                                         |
+| `ctx.theme`, `getRequestContext().theme`                                           | **throws** — the theme is the visitor's cookie             |
+| `ctx.set(var, value)` for a cacheable var                                          | allowed (children are cached too)                          |
+| Any of the above **inside a registered loader** (`loader(...)`)                    | **allowed** — loaders always run fresh                     |
+| Any read in the boundary's own `key()`, `keyGenerator`, `condition()` or `tags()`  | **allowed** — it picks or labels the entry, never rendered |
 
 A loader body invoked from a handler with `await ctx.use(Loader)` may read
-`cookies()`/`headers()`, but its response writes still throw: on a hit the
+`cookies()`/`headers()`/`ctx.request.headers`, but its response writes still throw: on a hit the
 handler is skipped, so that loader never runs.
 
+`ctx.request.clone()` is guarded the same way. `fetch(ctx.request)` and
+`new Request(ctx.request)` don't throw, but the guard can't see through them:
+a fetch forwards the visitor's `Cookie` and `Authorization`, so its response
+is per visitor and must not be rendered inside the boundary. A handler that
+must render a header its `key()` partitions by reads a copy middleware set:
+
+```tsx
+const Tier = createVar<string>();
+const tierOf = (ctx: { request: Request }) =>
+  ctx.request.headers.get("x-tier") === "gold" ? "gold" : "silver";
+
+middleware(
+  async (ctx, next) => {
+    ctx.set(Tier, tierOf(ctx)); // middleware runs outside the boundary
+    return next();
+  },
+  () => [
+    cache({ ttl: 300, key: (ctx) => `tier:${tierOf(ctx)}` }, () => [
+      path("/pricing", (ctx) => <Pricing tier={ctx.get(Tier)} />),
+    ]),
+  ],
+);
+```
+
 A loader bound with its **own** `cache()` (`loader(Def, () => [cache({...})])`)
 stores its value, and its key does not inherit the route's. A miss whose body
-read `cookies()`, `headers()` or a non-cacheable `ctx.get()` fails unless the
+read `cookies()`, `headers()`, `ctx.request.headers` or a non-cacheable
+`ctx.get()` fails unless the
 binding has a `key()` or its store a `keyGenerator`, which must then include
 the value (`/loader` → "Cache Key").
 
@@ -826,9 +869,12 @@ cached handler.
 This is the **consumption-lane rule**, and it holds for every shared
 artifact — `cache()`, `"use cache"`, and the PPR shell (`/ppr`): handler
 consumption = baked copy; client-side `useLoader` = live. The tiers differ on
-identity reads inside a handler-consumed loader: `cache()` and `"use cache"`
-permit them (the leak above), while a PPR shell capture refuses them and the
-route stays uncached. It is stated once in `/rango` → Invariants.
+identity reads inside a handler-consumed loader: `cache()` permits them (the
+leak above); `"use cache"` throws when the cached function is the first to
+read the loader in the request, because the loader body then runs inside it
+and its value is part of the result (a loader already started elsewhere
+returns its value unchecked, and that value is stored); a PPR shell capture
+refuses them and the route stays uncached. It is stated once in `/rango` → Invariants.
 
 ```typescript
 // WRONG — throws: cookies() read directly in a cached handler
@@ -874,9 +920,11 @@ See `/cache-guide` for the full decision guide and the `cache()` vs `"use cache"
 
 ## Nested Cache Boundaries
 
-An inner boundary overrides the settings of the outer one for its subtree
-(`key` composes instead, see below); `cache(false)` turns caching off for a
-subtree:
+An inner boundary overrides `ttl`, `swr` and `store` for its subtree;
+`cache(false)` turns caching off for a subtree. The options that decide
+whether and where a record may be shared build up instead: `key` composes
+(see below), every enclosing `condition()` must allow the inner boundary, and
+the inner records carry the enclosing `tags` too:
 
 ```typescript
 cache({ ttl: 300 }, () => [
@@ -898,6 +946,39 @@ cache miss, with no shell served and none captured. A `ppr` route under a
 layout's `cache()` therefore cannot opt out of that `cache()` and still get a
 shell (`/ppr`).
 
+### Conditions and tags inherit
+
+```typescript
+cache(
+  {
+    condition: (ctx) => !ctx.request.headers.has("x-preview"),
+    tags: ["catalog"],
+  },
+  () => [
+    cache({ ttl: 60, tags: ["prices"] }, () => [
+      path("/prices", PricesPage, { name: "prices" }),
+    ]),
+  ],
+);
+```
+
+- A preview request renders the prices page live: the outer `condition()` bypasses
+  the inner record's read and write, and a `ppr` route's shell. Conditions
+  combine with AND, through a `cache(false)` with a `cache()` re-enabled
+  below it too.
+- The prices record carries `catalog` and `prices` (static and function
+  `tags` alike), so `updateTag("catalog")` evicts it, and the `ppr` shells
+  and documents built from it.
+- `cache(false)` is unchanged: it caches nothing below it until a `cache()`
+  re-enables caching.
+- A loader's own `cache()` and `"use cache"` are separate layers: they take
+  neither the route's `condition()` nor its `tags`, nor its `key()`
+  partition.
+
+Before issue #974, only the innermost boundary's `condition` and `tags`
+applied: a request an outer `condition()` refused still read and wrote the
+inner record, and `updateTag()` of an outer tag left it in place.
+
 ### Keys nest: a partition covers the whole subtree
 
 A `key()` partitions every record under its `cache()`. A nested `cache()`
@@ -911,14 +992,14 @@ const tier = (ctx) =>
 cache({ ttl: 300, key: (ctx) => `tier:${tier(ctx)}` }, () => [
   layout(TierLayout, () => [
     // No key() of its own: the outer key() result, then this boundary's own
-    // default key ("tier%3Agold|doc%3Aexample.com%2Fpricing"), so /pricing
-    // and /faq keep their own records
+    // default key ("key:tier%3Agold|doc%3Aexample.com%2Fpricing"), so
+    // /pricing and /faq keep their own records
     cache({ ttl: 60 }, () => [
       path("/pricing", PricingPage, { name: "pricing" }),
       path("/faq", FaqPage, { name: "faq" }),
     ]),
 
-    // Its own key() composes with the outer one ("tier%3Agold|v%3Ab")
+    // Its own key() composes with the outer one ("key:tier%3Agold|key:v%3Ab")
     cache(
       { ttl: 60, key: (ctx) => `v:${ctx.searchParams.get("v") ?? "a"}` },
       () => [path("/plans", PlansPage, { name: "plans" })],
@@ -927,26 +1008,29 @@ cache({ ttl: 300, key: (ctx) => `tier:${tier(ctx)}` }, () => [
 ]);
 ```
 
-The parts are joined by `|`, outermost first, each URI-encoded:
-
-| Boundary the route sits in                     | Record key                                                                                                              |
-| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `cache({ ttl })`, no `key`, under a keyed one  | The chain's `key()` results, then this boundary's default key (its store's `keyGenerator` result, else the default key) |
-| `cache({ key })` under a keyed one             | The chain's `key()` results                                                                                             |
-| deeper nesting                                 | Composes the same way; only the innermost boundary's missing `key` adds its default key                                 |
-| `cache(false)`                                 | No caching, as before; a `cache()` re-enabled below it stays in the partition                                           |
-| a single keyed `cache()`, or no `key` anywhere | Its raw `key()` result, or the default key, as before                                                                   |
-
-- The encoding is unambiguous among composed keys: an encoded part holds no
-  `|`, so no two partitions, and no two inner keys, compose to the same
-  record key.
-- A single keyed `cache()` stores its `key()` result as is, so a raw result
-  can equal a composed key: a header value `gold|doc%3Aexample.com%2Fpricing`
-  returned raw names the record gold's pricing page keeps under the inner
-  `cache()` in the example above. Never return raw
-  request input from `key()`: normalize it to the values you serve, prefix
-  it (`tier:${value}`), or encode it. A composed key holds no `:` (every
-  part is URI-encoded), so a prefixed result never equals one.
+Every `key()` result is stored as `key:` plus its URI encoding; a default
+key in a composed key is URI-encoded. The parts are joined by `|`, `key()`
+results first, outermost first:
+
+| Boundary the route sits in                    | Record key                                                                                                                                                   |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| a single keyed `cache()`                      | Its `key()` result, namespaced (`tier:gold` is stored as `key:tier%3Agold`)                                                                                  |
+| `cache({ ttl })`, no `key`, under a keyed one | The chain's `key()` results, then this boundary's default key (its store's `keyGenerator` result, else the default key), encoded                             |
+| `cache({ key })` under a keyed one            | The chain's `key()` results                                                                                                                                  |
+| deeper nesting                                | Composes the same way; only the innermost boundary's missing `key` adds its default key                                                                      |
+| under a `cache({ store })` on another store   | Also that store's `keyGenerator` result, one part per store: empty for a store that returns the default key while another's differs, none when all return it |
+| `cache(false)`                                | No caching, as before; a `cache()` re-enabled below it stays in the partition                                                                                |
+| no `key` anywhere                             | The default key, or the store's `keyGenerator` result, as before                                                                                             |
+
+- No `key()` result, whatever it returns, equals a default key or a
+  composed key, and no two composed keys are equal: a namespaced result
+  starts with `key:` and holds no `|`, a default key never starts with
+  `key:`, and each part of a composed key is encoded, so the parts and their
+  kinds are recoverable. Returning request input from `key()` cannot name
+  another route's record (before issue #975 a header value
+  `doc:example.com/pricing` returned raw named the pricing page's default-keyed
+  record). A prefix (`tier:${value}`) is still worth it for readable keys,
+  and normalizing to the values you serve keeps the partition count bounded.
 - An inner boundary without `key` keeps everything its default key tells
   apart (path, params, search, document vs navigation), so its routes never
   share a record, even when the outer `key()` names no route.
@@ -954,17 +1038,31 @@ The parts are joined by `|`, outermost first, each URI-encoded:
   single `key()` does.
 - Each `key()` runs once per request, however many boundaries and lookups use
   it.
+- A store's `keyGenerator` partitions the records of a `cache()` on that
+  store without a `key()` of its own. A `cache({ store })` on another store
+  nested under it keys its records by that `keyGenerator` result too, so a
+  locale-partitioned outer boundary never shares an inner record across
+  locales. With several such stores each keeps its position: one that
+  returns the default key for a request adds an empty part while another's
+  differs, and when all return it the key is unchanged. A `keyGenerator` must
+  return the default key, not `""`, to leave a request unpartitioned: an
+  empty result there fails key resolution, so the request renders uncached,
+  and the router warns once naming the store. On the same store the inner
+  boundary's own default key already carries it (or its own `key()`
+  overrides it).
 - A response route's entry (`path.json()` and the other response routes) is
-  keyed the same way. A `ppr` route's shell is partitioned by the chain's
-  `key()` results alone, since the shell key already carries the URL (plus the
-  store `keyGenerator`'s result for an inner boundary without `key`).
+  keyed the same way, behind a `response:` prefix. A `ppr` route's shell is
+  partitioned by the chain's `key()` results, namespaced the same way, since
+  the shell key already carries the URL (plus the `keyGenerator` results
+  above, and the store's for an inner boundary without `key`).
 - To share an inner cache across partitions, move it outside the keyed
   `cache()`.
 
 Before issue #970, the innermost boundary alone decided the key: an inner
 `cache()` without `key` wrote under the default key and an inner `key()`
 dropped the outer partition, so a silver visitor could HIT what a gold
-visitor's request had cached.
+visitor's request had cached. Before issue #974 an outer `cache({ store })`'s
+`keyGenerator` did not reach an inner boundary on another store.
 
 ## Custom Cache Store
 

package/skills/client-urls/SKILL.md

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