@rangojs/router 0.17.0 → 0.18.0

package/dist/types/urls/pattern-types.d.ts

@@ -53,30 +53,34 @@ export interface PartialPrerenderProps {
     /**
      * Operational tags attached to the captured shell entry for
      * `updateTag()`/`revalidateTag()`-driven eviction. UNIONED with the tags the
-     * capture render auto-collects (the shell's own non-loader request tags).
+     * capture collects: its doc record's tags (what the handler layer and the
+     * server components it rendered recorded) and its bake-lane loaders'.
      */
     tags?: string[];
     /**
-     * Upper bound (serialized UTF-8 bytes) on the capture data snapshot riding
-     * inside the shell entry. The snapshot duplicates every cache-store value
-     * the capture pinned, so a page over a large cache() segment can push the
-     * entry toward store value limits (Cloudflare KV caps a value at 25 MiB).
-     * Over the cap the snapshot is skipped: the shell is still stored and
-     * served, but pinned reads fall back to the live store, so drifted cached
-     * content can hydration-mismatch and be repaired client-side (the
-     * pre-snapshot behavior). Reported once per key. Defaults to 8 MiB.
+     * Upper bound (serialized UTF-8 bytes) on the loader pins in the capture
+     * data snapshot: the loader records and the cache values loaders read,
+     * duplicated into the shell entry. The doc record (the handler layer every
+     * HIT replays) is exempt. Over the cap the pins are dropped: the shell is
+     * still stored and every HIT still replays the handler layer, but the
+     * pinned loaders read the live store, so drifted cached content can
+     * hydration-mismatch and be repaired client-side. Reported once per key.
+     * Defaults to 8 MiB. The whole entry is bounded separately by the store's
+     * value limit (Cloudflare KV: 25 MiB); an entry over it is refused.
      */
     maxSnapshotBytes?: number;
     /**
-     * Capture settle budget in MILLISECONDS (default 15000). Bounds the whole
-     * background capture: the wait for deferred shell material — top-level
-     * pushed handle promises (`ctx.use(Meta)(promise.then(...))` and friends)
-     * are AWAITED and their settled values baked into the stored shell — AND
-     * the fizz prerender deadline. Declare it to tighten the budget below the
-     * default or when a route's shell material takes longer than 15s to
-     * settle. A budget that expires with pushes still pending REFUSES the
-     * capture (the route stays MISS with the once-per-key warning) — a shell
-     * with missing head material is never stored. Capture is background work
+     * Capture settle budget in MILLISECONDS (default 15000). One deadline for
+     * the whole background capture: the match (the handlers, and the loaders
+     * they await), the wait for handler output (handle pushes and the promises
+     * nested in them, bake-lane loaders, and the doc record's encode, which
+     * awaits handler promises and async server components), AND the fizz
+     * prerender. Everything a handler produces is
+     * awaited and baked into the stored shell. Declare it to tighten the
+     * budget below the default or when a route's shell material takes longer
+     * than 15s to settle. A budget that expires before the doc record is
+     * written REFUSES the capture (the route stays MISS with the once-per-key
+     * warning): a shell with missing handler output is never stored. Capture is background work
      * (waitUntil), so a longer budget costs latency-to-HIT only, never a served
      * response; the platform waitUntil lifetime (workerd: ~30s past response
      * completion) is the physical ceiling — the default's derivation lives in

package/dist/types/vite/router-discovery.d.ts

@@ -5,9 +5,36 @@
  * environment. Delegates to extracted modules for discovery, route types
  * generation, virtual module codegen, and bundle post-processing.
  */
-import type { Plugin } from "vite";
-import { VIRTUAL_ROUTES_MANIFEST_ID, type PluginOptions } from "./discovery/state.js";
+import type { Plugin, ViteDevServer } from "vite";
+import { VIRTUAL_ROUTES_MANIFEST_ID, type DiscoveryState, type PluginOptions } from "./discovery/state.js";
 export { VIRTUAL_ROUTES_MANIFEST_ID };
+/**
+ * Create a minimal Vite server for router discovery.
+ *
+ * Both dev-mode prerender and build-mode discovery need a temp RSC server
+ * to import user router files via module runner. This factory centralizes
+ * the shared config and the mode-specific differences:
+ * - Dev: path-based IDs (no forceBuild), separate cacheDir
+ * - Build: hashed IDs (forceBuild), hashClientRefs for production bundles
+ *
+ * Returns the ViteDevServer instance. Callers access .environments.rsc as needed.
+ * @internal Exported for tests.
+ */
+export declare function createTempRscServer(state: DiscoveryState, options?: {
+    forceBuild?: boolean;
+    cacheDir?: string;
+    /**
+     * Serve the REAL rango SSR entry (getVirtualEntrySSR) for
+     * "virtual:entry-ssr" instead of the discovery stub, so the dev
+     * /__rsc_shell endpoint can drive captureShellHTML in this server's SSR
+     * realm. Dev-correct by construction: the entry's bootstrap resolves to
+     * plugin-rsc's stable virtual browser-entry URL, which the MAIN dev
+     * server serves to the browser. Loaded lazily — discovery never imports
+     * the SSR entry, so the temp server stays as light as before until a
+     * shell capture actually runs.
+     */
+    realSsrEntry?: boolean;
+}): Promise<ViteDevServer>;
 /**
  * Plugin that discovers router instances at dev/build time via the RSC environment.
  *

package/dist/vite/index.js

@@ -3802,7 +3802,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.17.0",
+  version: "0.18.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -6147,6 +6147,9 @@ import React from "react";
 // src/server/context.ts
 import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
 
+// src/rsc/shell-capture-constants.ts
+var SHELL_CAPTURE_MAX_WAIT_MS = 15e3;
+
 // src/cache/cache-exec-scope.ts
 import { AsyncLocalStorage } from "node:async_hooks";
 
@@ -6170,19 +6173,23 @@ var LOADER_SCOPE_KEY = /* @__PURE__ */ Symbol.for("rangojs-router:loader-scope")
 var loaderScopeALS = globalThis[LOADER_SCOPE_KEY] ??= new AsyncLocalStorage2();
 var LOADER_BODY_SCOPE_KEY = /* @__PURE__ */ Symbol.for("rangojs-router:loader-body-scope");
 var loaderBodyScopeALS = globalThis[LOADER_BODY_SCOPE_KEY] ??= new AsyncLocalStorage2();
+function getLoaderBodyTags() {
+  return loaderBodyScopeALS.getStore()?.tags;
+}
+function getCurrentLoaderBodyId() {
+  return loaderBodyScopeALS.getStore()?.loaderId;
+}
 var PUSH_CALLBACK_SCOPE_KEY = /* @__PURE__ */ Symbol.for(
   "rangojs-router:push-callback-scope"
 );
 var pushCallbackScopeALS = globalThis[PUSH_CALLBACK_SCOPE_KEY] ??= new AsyncLocalStorage2();
 
-// src/rsc/shell-capture-constants.ts
-var SHELL_CAPTURE_MAX_WAIT_MS = 15e3;
-
 // src/rsc/shell-serve.ts
 var DEV_SHELL_PROBE_TIMEOUT_MS = 1e4;
 function normalizeCaptureTimeout(value) {
   return typeof value === "number" && Number.isFinite(value) && value >= 1 ? Math.min(value, SHELL_CAPTURE_MAX_WAIT_MS) : void 0;
 }
+var SHELL_PRELUDE_CHUNK_BYTES = 32 * 1024;
 
 // src/vite/inject-client-debug.ts
 function isRouterInternalDebugId(id) {
@@ -9133,18 +9140,36 @@ var ALL_USE_ITEM_TYPES = new Set(
 );
 
 // src/server/request-context.ts
-import { AsyncLocalStorage as AsyncLocalStorage4 } from "node:async_hooks";
+import { AsyncLocalStorage as AsyncLocalStorage5 } from "node:async_hooks";
 init_cookie_name();
 
 // src/server/handle-store.ts
 var LOADER_SLOT = Object.freeze({ loader: true });
 
+// src/cache/cache-tag.ts
+import { AsyncLocalStorage as AsyncLocalStorage3 } from "node:async_hooks";
+var cacheTagStorage = new AsyncLocalStorage3();
+var segmentOwnerStorage = new AsyncLocalStorage3();
+var recordedTagCapture = globalThis[/* @__PURE__ */ Symbol.for("rangojs-router:recorded-tag-capture")] ??= new AsyncLocalStorage3();
+var identityReads = globalThis[/* @__PURE__ */ Symbol.for("rangojs-router:identity-reads")] ??= /* @__PURE__ */ new WeakMap();
+function activeTagSet() {
+  const capture = recordedTagCapture.getStore();
+  const body = getLoaderBodyTags();
+  if (capture && capture.outer === body) return capture.into;
+  return body ?? capture?.into;
+}
+globalThis[/* @__PURE__ */ Symbol.for("rangojs-router:identity-read-recorder")] = (surface, verb) => {
+  const set = activeTagSet();
+  if (set === void 0 || identityReads.has(set)) return;
+  identityReads.set(set, { surface, verb, bodyId: getCurrentLoaderBodyId() });
+};
+
 // src/router/router-context.ts
-import { AsyncLocalStorage as AsyncLocalStorage3 } from "async_hooks";
-var routerContext = new AsyncLocalStorage3();
+import { AsyncLocalStorage as AsyncLocalStorage4 } from "async_hooks";
+var routerContext = new AsyncLocalStorage4();
 
 // src/server/request-context.ts
-var requestContextStorage = new AsyncLocalStorage4();
+var requestContextStorage = new AsyncLocalStorage5();
 
 // src/route-definition/redirect.ts
 init_redirect_origin();
@@ -9727,6 +9752,8 @@ async function runShellPrerenderPhase(s, builder) {
   const candidates = s.shellCandidates;
   const startTotal = performance.now();
   console.log(`[rango] Shell-prerendering ${candidates.length} URL(s)...`);
+  const keepAlive = setInterval(() => {
+  }, 6e4);
   let restoreClientRequire;
   try {
     const rscEnv = tempServer.environments?.rsc;
@@ -9934,6 +9961,7 @@ async function runShellPrerenderPhase(s, builder) {
   } finally {
     delete globalThis.__loadPrerenderManifestModule;
     restoreClientRequire?.();
+    clearInterval(keepAlive);
   }
 }
 function writeShellManifest(s, rscOutDir, staged) {
@@ -10603,7 +10631,16 @@ async function createTempRscServer(state, options = {}) {
   return createViteServer({
     root: state.projectRoot,
     configFile: false,
-    server: { middlewareMode: true },
+    server: {
+      middlewareMode: true,
+      // Build mode: no file watching. buildStart installs the per-router tries
+      // into this realm and runShellPrerenderPhase reuses it after the bundles
+      // are written. A watched write in between (writeRouteTypesFiles' own
+      // <router>.named-routes.gen.ts, which every router file imports) can
+      // make Vite full-reload the RSC runner; the shell phase then matches in
+      // a fresh realm with no tries and a root path("/*") wins (#947).
+      ...options.forceBuild ? { watch: null } : {}
+    },
     appType: "custom",
     logLevel: "silent",
     resolve: resolveConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.17.0",
+  "version": "0.18.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.
@@ -111,7 +127,14 @@ else they allow:
   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.headers.set()` and other response writes); additionally, tainted
@@ -119,6 +142,12 @@ else they allow:
   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
 
 `CFCacheStore` prefixes every **physical** store key (the CF Cache API URL and
@@ -203,7 +232,7 @@ local/dev behavior, not as proof that segment SWR is active.
 | **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 |
+| **Nesting**          | Inner TTLs override; `key()` partitions compose       | Compose by calling cached functions from uncached |
 
 ### cache() Cache Key
 
@@ -216,8 +245,14 @@ 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()`. 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
 
@@ -294,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:
@@ -364,8 +404,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
 
@@ -381,6 +433,10 @@ Neither mechanism caches response headers or cookies.
   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
@@ -413,14 +469,16 @@ 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.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
@@ -476,7 +534,8 @@ non-cacheable value in as an argument so it becomes part of the key. The pattern
 **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
 
@@ -489,8 +548,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 +580,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 +633,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 +656,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()` 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