@rangojs/router 0.0.0-experimental.35 → 0.0.0-experimental.358c376d

package/skills/breadcrumbs/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: breadcrumbs
-description: Built-in Breadcrumbs handle for accumulating breadcrumb navigation across route segments
-argument-hint: [setup]
+description: Built-in Breadcrumbs handle for accumulating breadcrumb navigation across route segments. Use when building a breadcrumb trail for nested routes, or asking how to show the current navigation path in a layout.
+argument-hint: "[setup]"
 ---
 
 # Breadcrumbs
 
 Built-in handle for accumulating breadcrumb items across route segments.
-Each layout/route pushes items via `ctx.use(Breadcrumbs)`, and they are
-collected in parent-to-child order with automatic deduplication by `href`.
+Handlers and loader bodies push items via `ctx.use(Breadcrumbs)`, and they
+are collected in parent-to-child order with automatic deduplication by
+`href`.
 
 ## BreadcrumbItem Type
 
@@ -58,6 +59,32 @@ export const urlpatterns = urls(({ path, layout }) => [
 
 On `/blog/my-post`, breadcrumbs accumulate: `Home > Blog > my-post`.
 
+## Pushing from Loaders
+
+A data-derived crumb belongs where the data lives — the loader body pushes
+with the same API (handler parity), so routes without handlers (`useLoader`
+consumption, `clientUrls()` groups) still build trails:
+
+```typescript
+export const ProductLoader = createLoader(async (ctx) => {
+  "use server";
+  const product = await getProduct(ctx.params.slug);
+
+  const pushCrumb = ctx.use(Breadcrumbs);
+  pushCrumb({ label: "Shop", href: "/shop" });
+  pushCrumb({ label: product.name, href: `/shop/product/${product.slug}` });
+
+  return product;
+});
+```
+
+Two pushes from one segment accumulate in push order (`Shop › product`).
+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, { stream: "navigation" })` —
+see `/loader` → "Writing Handles from Loaders".
+
 ## Async Content
 
 The `content` field supports `Promise<ReactNode>` for streaming:
@@ -81,6 +108,73 @@ path("/product/:id", async (ctx) => {
 Async content is a `Promise<ReactNode>`. Resolve it in your component
 with React's `use()` hook wrapped in `<Suspense>`.
 
+### Deferred content (decide now, resolve from a deep component)
+
+When the handler should DECIDE to push a crumb early but the value is produced
+far away — by a deep async component, not the handler — call `.defer()` on the
+push function. (If the value comes from a LOADER, skip `.defer()` entirely and
+push from the loader body — see "Pushing from Loaders" above.)
+`ctx.use(Handle)` returns the push function; `.defer(options)` reserves the crumb's
+slot synchronously and returns a **resolver that is push-equal** — you call it
+later, anywhere in the render, with the same argument you'd have passed to the
+push (a value, a `Promise`, or a thunk). The only added behavior is a timeout, so a
+forgotten resolve can't hang the render (and the HTTP response): resolve-by-default
+awaits the reserved slot before any consumer reads it, and the timeout guarantees it
+settles to `else` instead of blocking forever.
+
+Reserve the slot in the handler, then resolve it from a nested async component
+that closes over the resolver — no extra wiring (the resolver is a plain closure,
+not outlet context):
+
+```tsx
+import { Breadcrumbs } from "@rangojs/router";
+import { Outlet } from "@rangojs/router/client";
+import { Suspense } from "react";
+
+function DocsLayout(ctx) {
+  const breadcrumb = ctx.use(Breadcrumbs);
+  // Decide now (the slot is reserved before the stream seals); resolve later.
+  const resolveCrumb = breadcrumb.defer({ timeoutMs: 5000, else: null });
+
+  // Deep, async, far from the handler — closes over the resolver, never touches ctx.
+  // Same call shape as breadcrumb({ ... }), just deferred:
+  async function LiveCrumb() {
+    const n = await countOpenIssues();
+    resolveCrumb({ label: "Docs", href: "/docs", content: <span>{n}</span> });
+    return null;
+  }
+
+  return (
+    <>
+      <Suspense>
+        <LiveCrumb />
+      </Suspense>
+      <Outlet />
+    </>
+  );
+}
+```
+
+If the resolver is never called, the slot auto-resolves to `else` after
+`timeoutMs` (default 10s) and warns in dev — graceful degradation instead of a
+hung request. `timeoutMs: 0` or `Infinity` disable the timeout intentionally; any
+other non-finite or negative value falls back to the default rather than silently
+disabling the safety net.
+
+**Consumer note (resolve-by-default):** a deferred crumb is RESOLVED before any
+consumer sees it — `useHandle(Breadcrumbs)` returns the resolved item, never a
+`Promise`, so you read it like any sync crumb (no `use()`, no thenable narrowing).
+On a full/SSR load the value is resolved server-side; on a soft navigation the
+breadcrumbs HOLD the previous resolved value until the deferred value lands, then
+swap in — no blank, no pending entry. If the slot times out to `else: null`/
+undefined, the entry is simply dropped. Use `.defer()` only when even
+`label`/`href` are unknown at handler time AND the producer is a component,
+not a loader — a loader-produced crumb pushes directly from the loader body
+(add `{ stream: "navigation" }` if it must be in the SSR'd document), and if
+you know `label`/`href` and only the `content` is async, push a concrete item
+with a `Promise` `content` field instead (the `content` field is a nested
+promise you resolve with `use()` in your component; no `.defer()` needed).
+
 ## Consuming Breadcrumbs (Client)
 
 Use `useHandle(Breadcrumbs)` in a client component to read the accumulated items:
@@ -141,10 +235,12 @@ path("/dashboard", (ctx) => {
   breadcrumb({ label: "Dashboard", href: "/dashboard" });
   return <DashboardNav handle={Breadcrumbs} />;
 });
+```
 
+```tsx
 // Client component
-("use client");
-import { useHandle, type Breadcrumbs } from "@rangojs/router/client";
+"use client";
+import { useHandle, Breadcrumbs } from "@rangojs/router/client";
 
 function DashboardNav({ handle }: { handle: typeof Breadcrumbs }) {
   const crumbs = useHandle(handle);
@@ -212,15 +308,28 @@ Create your own handle with `createHandle()`:
 ```typescript
 import { createHandle } from "@rangojs/router";
 
-// Default: flatten into array
+// Custom collect: last value wins.
 export const PageTitle = createHandle<string, string>(
   (segments) => segments.flat().at(-1) ?? "Default Title",
 );
 
-// No collect function: default flattens into T[]
+// No collect: the DEFAULT is the identity (lossless) — `collect` receives the
+// per-segment data (TData[][], one array per segment that pushed, in segment
+// order) and passes it through as-is. `useHandle(Warnings)` is `string[][]`, so a
+// consumer can tell which/how-many segments contributed.
 export const Warnings = createHandle<string>();
+
+// Want a single flat list instead? Opt in:
+export const FlatWarnings = createHandle<string, string[]>((segments) =>
+  segments.flat(),
+);
 ```
 
+A handle whose module is never imported (so `createHandle()` never ran to register
+its collect) falls back to this same identity default and **warns in dev** — a
+handle with a custom collect that failed to register would otherwise return the
+wrong shape silently, and the runtime can't tell it from one that wanted the default.
+
 The Vite `exposeInternalIds` plugin auto-injects a stable `$$id` based on
 file path and export name. No manual naming required for project-local code.
 

package/skills/bundle-analysis/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: bundle-analysis
+description: Audit a Rango app's production bundle for server-side code leaking into the client, dev/prod React duplication, oversized chunks, and inefficient client-reference grouping. Use when investigating bundle size growth, before a production deploy, or when the client/SSR/RSC output suddenly balloons.
+argument-hint: "<app-dir>"
+---
+
+# Bundle Analysis
+
+Use this when you want **proof** that your Rango app is shipping the bundles you expect: small client, no server leaks, no doubled React, reasonable RSC worker size.
+
+## What this checks
+
+Your app builds in three Vite environments — `client`, `ssr`, and `rsc` — and each ships its own bundle. The most common bundle bugs in a Rango app are:
+
+1. **Server code leaking into the client.** A file that imports `node:fs`, calls a database, or contains action logic ends up in the client bundle because a client component pulled it in transitively. Symptom: your client bundle is much larger than expected, sometimes with imports that fail at runtime.
+2. **Both dev and prod React in the SSR/RSC bundle.** When `process.env.NODE_ENV` isn't folded at build time, React's CJS files ship both `.development.js` _and_ `.production.js` variants — doubling React's footprint. The Cloudflare vite plugin folds NODE_ENV automatically; vanilla `vite build` does it for client but not always for SSR/RSC.
+3. **An oversized routes-manifest in your RSC worker.** The `virtual:rsc-router/routes-manifest/<routerId>` chunk holds your route trie and precomputed entries — large only in proportion to your route count. If it's surprisingly big, you may have unintentionally generated routes (e.g., parametrized fixtures) that bloated the trie.
+4. **Inefficient client-reference grouping.** Each `"use client"` boundary becomes a chunk. Too many small client components = many tiny chunks; one giant client component = one giant chunk that defeats code-splitting.
+
+Tree-shaking does _not_ catch (1) generated data inlined as string literals or (2) data-dependent conditionals like React's. You need a visualizer.
+
+## Step 1: Install the visualizer
+
+In your app's directory:
+
+```bash
+pnpm add -D rollup-plugin-visualizer
+# or: npm install --save-dev rollup-plugin-visualizer
+# or: yarn add -D rollup-plugin-visualizer
+```
+
+## Step 2: Wire it into your `vite.config.ts`
+
+Add a small helper that registers one visualizer instance **per Vite environment** (not just one global). The plugin caches its options after the first call, so a single instance can't handle multi-environment builds — you'll get a report for one environment and silence for the others.
+
+```ts
+// vite.config.ts
+import { defineConfig, type PluginOption, type Plugin } from "vite";
+import { visualizer } from "rollup-plugin-visualizer";
+import { join } from "node:path";
+// ... your other imports ...
+
+function analyze(): PluginOption[] {
+  if (!process.env.RANGO_ANALYZE) return [];
+  return (["client", "ssr", "rsc"] as const).map((envName) => {
+    const inner = visualizer({
+      filename: join("bundle-stats", `${envName}.html`),
+      template: "treemap",
+      gzipSize: true,
+      brotliSize: true,
+    }) as Plugin;
+    return {
+      ...inner,
+      name: `analyze-${envName}`,
+      applyToEnvironment(env) {
+        return env.name === envName;
+      },
+    } as Plugin;
+  });
+}
+
+export default defineConfig(({ command }) => ({
+  plugins: [
+    // your existing plugins...
+    ...analyze(),
+  ],
+  // For non-Cloudflare apps, fold NODE_ENV explicitly so React's CJS files
+  // emit only the .production.js variants in SSR/RSC. Skip if your build
+  // setup already does this (the Cloudflare vite plugin does).
+  define:
+    command === "build"
+      ? { "process.env.NODE_ENV": JSON.stringify("production") }
+      : undefined,
+}));
+```
+
+Add `bundle-stats/` to your `.gitignore`.
+
+## Step 3: Build with the analyzer enabled
+
+```bash
+RANGO_ANALYZE=1 pnpm exec vite build
+```
+
+You'll get three HTML reports in `bundle-stats/`:
+
+- `bundle-stats/client.html` — what runs in the browser
+- `bundle-stats/ssr.html` — what runs during HTML stream
+- `bundle-stats/rsc.html` — what runs in your RSC server (Worker / Node)
+
+Open them with a quick local server (file:// has CORS issues with the embedded scripts):
+
+```bash
+pnpm dlx serve -l 5050 .
+# then visit http://localhost:5050/bundle-stats/client.html
+```
+
+## Step 4: Triage the reports
+
+### Open `client.html` first
+
+The treemap shows nested boxes; box area = uncompressed size. Hover for gzip/brotli numbers.
+
+**Look for:**
+
+- **Your server code.** Any of your own files that contain database queries, secret keys, server actions implementation (not the action _reference_), or `node:` imports. If they appear in the client treemap with non-zero bytes, they leaked. Common causes:
+  - A shared module that mixes client and server code without a `"use client"` or `"use server"` directive.
+  - A barrel file (`index.ts`) that re-exports both client and server symbols. Tree-shaking should help, but `JSON.parse('{...}')` data and side-effecting top-level statements survive.
+  - Client component imports a server-only utility through an indirect path (e.g., shared types file that pulls server modules).
+- **Multiple copies of the same package.** Look for two boxes with the same package name but different version paths. Usually means a transitive dep pinned a different version.
+- **The `@rangojs/router` chunk** should be roughly **50 KB gzip** (74 files). If significantly larger, you might be importing client-incompatible APIs from the wrong subpath.
+- **Per-route client-reference chunks** (named like `chunk-<hash>.js`). Each `"use client"` boundary can become its own chunk. If you have hundreds of tiny chunks, you may have over-split (every leaf component as a client component); if you have one massive 200 KB chunk, you've under-split (a wide client tree behind one boundary).
+
+### Now check `ssr.html`
+
+**Look for:**
+
+- **`react-dom-server.edge.development-*.js`** (or any `*.development*.js` chunk). This is the dev/prod React doubling. Fix: add `define: { "process.env.NODE_ENV": '"production"' }` to your vite config (see Step 2).
+- **Your client components** appearing in SSR. They're _expected_ here — SSR hydration needs to produce HTML for them. The same components show up in `client.html` too because the browser hydrates them. This is not a leak.
+- **Total SSR size**: a reasonable Rango SSR is ~140 KB gzip plus your app code. If it's >300 KB, almost always (1) dev/prod React duplication or (2) a giant data structure being inlined.
+
+### Now check `rsc.html`
+
+**Look for:**
+
+- **`virtual:rsc-router/routes-manifest`** should be **tiny** (< 1 KB). If it's > 100 KB, you're on an old version of `@rangojs/router` that inlined the trie eagerly — upgrade to a release that includes commit `d10a2470`.
+- **`virtual:rsc-router/routes-manifest/<hash>`** is the lazy per-router chunk. Its size is proportional to your route count. For a typical app: 5–50 KB gzip. For a stress-test app with thousands of routes: hundreds of KB. If yours is unexpectedly huge, check whether you're generating routes you don't need.
+- **`<your-router>.named-routes.gen.ts`** — generated route map. Should match your route count.
+- **Your action and loader implementations** — these run server-side. Expected to be here, not in client.
+- **Worker-incompatible code** (Node-only imports like `node:fs` that Cloudflare doesn't support). The build will usually fail before the analyzer runs, but if you're seeing runtime errors at the edge, the RSC treemap shows what made it in.
+
+## Step 5: Fix what you find
+
+| Finding                                                  | Fix                                                                                                                                                                         |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Your server code in `client.html` (non-zero bytes)       | Audit the import chain. Add `"use server"` to server-only files. Move shared data out of barrel files. Use the `@rangojs/router/server` subpath for explicitly server APIs. |
+| Your server code in `client.html` listed but 0 bytes     | Tree-shaking already eliminated it. Cosmetic. Leave it.                                                                                                                     |
+| `react-dom-server.edge.development-*.js` in SSR or RSC   | Add the `define` block from Step 2 to your vite config.                                                                                                                     |
+| Routes-manifest > 100 KB gzip in RSC eager chunk         | Update `@rangojs/router` to a release that includes the lazy-only manifest fix.                                                                                             |
+| Same package version present twice                       | Run `pnpm dedupe` (or `npm dedupe`). If the duplication persists, a transitive dep pins an incompatible version — open a PR upstream or pin the resolution.                 |
+| Client chunk > 500 KB gzip with a single dominant module | That module is your largest client component. Consider lazy-loading via dynamic `import()` or moving non-interactive parts to server components.                            |
+| Hundreds of tiny client chunks                           | You've sprinkled `"use client"` too liberally. Hoist directives to higher boundaries so React groups them.                                                                  |
+
+## When to re-run
+
+- Before every production deploy, especially after adding new dependencies.
+- After upgrading `@rangojs/router`, React, or `@vitejs/plugin-rsc`.
+- After adding routes that scale with data (e.g., one route per item from a content directory) — the manifest may have grown.
+- When CI starts reporting larger artifact sizes.
+
+## Reporting Rango regressions
+
+If a finding looks like a `@rangojs/router` regression (the framework is shipping more than it should, not your app), open an issue at the [@rangojs/router GitHub](https://github.com/ivogt/vite-rsc/issues) and include:
+
+- The output of `client.html` / `rsc.html` (screenshots or the JSON `data = {...}` block from the HTML).
+- The `@rangojs/router` version (`pnpm why @rangojs/router`).
+- Your `vite.config.ts`.
+
+The framework maintainers run a similar audit internally — the methodology in this skill mirrors what they use to validate every release.

package/skills/cache-guide/SKILL.md

@@ -1,13 +1,149 @@
 ---
 name: cache-guide
-description: When to use cache() DSL vs "use cache" directive — key differences and decision guide
+description: When to use cache() DSL vs "use cache" directive — key differences and decision guide. Use when unsure which caching mechanism fits a given problem, comparing route/segment caching, function-level caching, and document-level caching, or asking "which cache API should I use".
 argument-hint:
 ---
 
 # cache() vs "use cache" — When to Use Which
 
-Both mechanisms share the same backing store, cache profiles, and tag-based
-invalidation. They differ in scope, cache key, execution model, and runtime control.
+Both mechanisms share the same backing store and cache profiles, and both accept
+an optional `tags` field (honored by the built-in stores — invalidate with
+`updateTag`/`revalidateTag`; see "Two axes" below). They differ in scope, cache
+key, execution model, and runtime control.
+
+## 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
+caching:
+
+1. **Stored-value freshness** — _is a cached value still good?_
+   → `"use cache"` (fn/component), `cache()` (segment), loader `cache()` (loader data).
+   Entries expire by **TTL/SWR** and can be tagged (`cache({ tags })` or runtime
+   `cacheTag(...tags)` — inside `"use cache"` it tags that entry; called during a
+   request render outside `"use cache"` it tags the document/shell artifact).
+   Built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`)
+   index by tag; invalidate on demand with `updateTag(...tags)` (awaitable,
+   read-your-own-writes) or `revalidateTag(...tags)` (background, non-blocking).
+   Both hard-purge; the difference is awaitability, not stale-serving.
+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
+update, and `revalidate()` never reads, writes, or expires a cached value. If you
+know React Router, `revalidate()` is `shouldRevalidate`, not `Cache-Control`. See
+`/rango` → "Coming from another framework" for the cross-framework mapping.
+
+## Fast choice
+
+Read this first; use the rest of the page when the choice has edge cases.
+
+1. Do you want to cache an entire route or group of routes?
+   **Yes** -> `cache()`
+2. Do you need runtime conditions, such as skip for authed users or key by
+   locale?
+   **Yes** -> `cache()` with `condition` / `key`
+3. Do you want to cache a data fetch or helper shared across routes?
+   **Yes** -> `"use cache"`
+4. Do you need different cache entries for different function arguments?
+   **Yes** -> `"use cache"` (keyed by args)
+5. Is the expensive part rendering a subtree?
+   **Yes** -> `cache()` (caches rendered segments)
+6. Is the expensive part one query inside a larger live handler?
+   **Yes** -> `"use cache"` on the query function
+
+## Correctness & invalidation
+
+rango's caches are built so a hit can't serve wrong or stale-shaped data. These
+guarantees are mostly automatic — worth knowing so you don't reimplement
+protection the framework already gives you (or assume one it deliberately
+doesn't).
+
+There are two guard models to keep separate. Both block response side effects
+(`ctx.header()`, cookie writes) that would be lost on a hit; they differ in what
+else they allow:
+
+- **`cache()` boundary guard** (route-level) — fires while the handler runs on a
+  miss. `cookies()` and `headers()` throw (request-scoped data would be baked into
+  the shared cached shell), `ctx.get(nonCacheableVar)` throws (a tainted value
+  would be baked in), and response side effects (`ctx.header()`, `ctx.setCookie()`,
+  `ctx.setStatus()`, `ctx.onResponse()`) throw. `ctx.set()` of a cacheable var is
+  **allowed** — children are cached too and can read it. **Loaders are exempt**
+  (they always run fresh) — read request data inside a loader.
+- **`"use cache"` exec-guard** (function-level) — the same request-scoped APIs
+  throw inside the cached function (`cookies()`, `headers()`, `ctx.set()`,
+  `ctx.header()`); additionally, tainted `ctx`/`env`/`req` args are excluded from
+  the cache key.
+
+### Cross-deploy safety: version-segmented store keys
+
+`CFCacheStore` prefixes every **physical** store key (the CF Cache API URL and
+the KV key) with the build version — auto-generated from the
+`@rangojs/router:version` virtual module, overridable via the store's `version`
+option. A new deploy reads under a new prefix, so it can **never** read a
+previous build's entries: no cross-deploy shape drift, and no dead client-chunk
+references baked into cached RSC.
+
+The tradeoff to know: **loader/data caches use the same store**, so they're
+version-segmented too. Every deploy is therefore a _cold data cache_ — SWR can't
+soften it, because no stale entry exists under the new key. For high-traffic,
+frequently-deploying, data-bound apps that's a deploy-time origin warm-up. Decide
+deliberately: accept it (correctness over hit-rate), or split the policy — let
+the render/edge cache auto-version while a separate data store gets a stable
+`version` so its entries survive deploys. (Per-process stores like
+`MemorySegmentCacheStore` are cold on every restart anyway; this matters for
+persistent stores.) See `/caching` for store setup.
+
+### Client cache: forward/back is mutation-aware
+
+The browser keeps a history (forward/back) cache of rendered segments. Any
+client-side mutation (a server action) marks those entries **stale** and
+broadcasts it to other tabs. On back/forward (popstate) the router looks up the
+entry, sees it's stale, and revalidates — so your `revalidate()` predicates re-run
+and the segment refreshes (SWR: the stale view paints instantly, fresh data
+streams in). It's the client-side analog of the server-cache correctness problem,
+solved on the partial-render axis.
+
+### Request-scoped data: the `cache: false` taint
+
+`createVar({ cache: false })` (or a `ctx.set(var, v, { cache: false })` write)
+taints a value as request-scoped; reading it **directly** with `ctx.get()` inside
+a `cache()` boundary throws — the guard against the catastrophic "serve user A's
+data to user B" bug. The guarantee is precise and intentionally narrow — see
+"Context Variable Cache Safety" below for exactly what it does and does not catch.
+
+## Stale-while-revalidate
+
+SWR is a first-class cache behavior when the backing store supports it: while an
+entry is within its SWR window the cache serves the **stale value instantly** and
+refreshes it in the **background** (`waitUntil`), so users never wait on a
+recompute for a merely-aging entry.
+
+- **`"use cache"`** resolves to the `default` profile `{ ttl: 900, swr: 1800 }`,
+  so function/component caching gets a 30-minute SWR window **out of the box**.
+  Tune or add profiles via `createRouter({ cacheProfiles: { … } })`
+  (`"use cache: short"` → the `short` profile).
+- **`cache()` DSL and loader caches** take an explicit `swr` in seconds (or
+  inherit `store.defaults.swr`): `cache({ ttl: 60, swr: 300 })` → fresh ≤60s,
+  stale-served 60–360s, miss after 360s in stores that implement SWR for that
+  layer.
+- **Client forward/back** is SWR after a mutation — see "Correctness &
+  invalidation" → Client cache.
+- **Store-backed document layer** uses the HTTP `stale-while-revalidate`
+  directive as policy for `createDocumentCacheMiddleware`; see
+  `/document-cache`. A platform CDN may independently consume the same header
+  and bypass the function on hits; see `/deployment-caching`.
+
+SWR softens normal TTL expiry, **not** a cross-deploy cold cache — a new build
+has no stale entry to serve (see version-segmented store keys above).
+
+Store support is layer-specific. `CFCacheStore` supports SWR for segment,
+document/response, and `"use cache"` item entries. `MemorySegmentCacheStore`
+supports SWR for response and `"use cache"` item entries, but its route-segment
+entries expire at TTL and never background-revalidate. Use the memory store for
+local/dev behavior, not as proof that segment SWR is active.
 
 ## Key Differences
 
@@ -18,7 +154,7 @@ invalidation. They differ in scope, cache key, execution model, and runtime cont
 | **Cache key**        | Request type + pathname + params (+ optional custom)  | Function identity + serialized non-tainted args    |
 | **Execution on hit** | All-or-nothing: entire handler skipped                | Partial: function body skipped, calling code runs  |
 | **Runtime control**  | `condition` to disable, custom `key` function         | None — if the directive is present, it caches      |
-| **Side effects**     | No guards needed — handler doesn't run on hit         | `ctx.header()`, `ctx.set()`, etc. throw at runtime |
+| **Side effects**     | Response side effects throw inside the boundary       | `ctx.header()`, `ctx.set()`, etc. throw at runtime |
 | **Handle data**      | Captured and replayed                                 | Captured and replayed                              |
 | **Loaders**          | Always fresh — excluded from cache, opt-in per loader | Can be used inside loaders                         |
 | **Nesting**          | Nest `cache()` boundaries with different TTLs         | Compose by calling cached functions from uncached  |
@@ -144,13 +280,38 @@ On cache hit for the route, the handler doesn't run and `getProductData` is neve
 called. On cache miss, the handler runs and `getProductData` may itself return a
 cached value from a previous call with the same slug.
 
+### Nesting rule: the outer window bounds the inner
+
+A cache's window bounds everything rendered inside it (loaders excepted). An
+inner shorter TTL only takes effect when the **enclosing** cache recomputes — it
+does **not** keep a value fresher than its parent:
+
+- Outer `cache()` **fresh hit** → the subtree is served from stored RSC, so inner
+  `"use cache"` functions are **not consulted** (frozen at the outer's age — no
+  code inside the boundary runs on a hit).
+- Outer **miss / SWR revalidation** → inner caches are consulted, each per its own
+  ttl/swr. With SWR on the outer, a stale subtree serves instantly and refreshes
+  in the background, so under traffic it keeps refreshing rather than rotting to
+  the worst case.
+- **Loaders are the exception** — excluded from the segment cache, re-resolved
+  live even on an outer hit.
+
+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.
+
 ## Headers and Cookies
 
 Neither mechanism caches response headers or cookies.
 
-- **cache()**: Headers set by handlers are naturally absent on hit because no
-  handler runs. If you need headers on every response, set them in middleware
-  (which runs before cache lookup).
+- **cache()**: Response-level side effects throw inside the cache boundary even
+  on a miss: `ctx.header()`, `ctx.setCookie()`, `ctx.deleteCookie()`,
+  `ctx.setStatus()`, `ctx.onResponse()`, and direct `ctx.headers` mutation. On a
+  hit the handler would be skipped, so allowing the write on a miss would produce
+  inconsistent responses. If you need headers or cookies on every response, set
+  them in middleware or a live segment outside the cache boundary.
 - **"use cache"**: cookies() and headers() throw inside the cached function
   (both reads and writes). ctx.header() also throws. Move them outside.
 
@@ -162,6 +323,88 @@ middleware(async (ctx, next) => {
 });
 ```
 
+## Context Variable Cache Safety
+
+Context variables created with `createVar()` are cacheable by default and can
+be read freely inside cached scopes. A non-cacheable var throws when read
+**directly** with `ctx.get()` inside a `cache()` boundary — where the value would
+otherwise be serialized into the stored segment.
+
+There are two ways to mark a value as non-cacheable:
+
+```typescript
+// Var-level policy — inherently request-specific data
+const Session = createVar<SessionData>({ cache: false });
+
+// Write-level escalation — this specific write is non-cacheable
+ctx.set(Theme, derivedTheme, { cache: false });
+```
+
+"Least cacheable wins": if either the var definition or the `ctx.set()` call
+specifies `cache: false`, the value is non-cacheable.
+
+**Behavior inside a `cache()` boundary:**
+
+| Operation                                 | Inside a `cache()` boundary                            |
+| ----------------------------------------- | ------------------------------------------------------ |
+| `cookies()` / `headers()` (read or write) | Throws (request-scoped, would poison the shared entry) |
+| `ctx.get(cacheableVar)`                   | Allowed                                                |
+| `ctx.get(nonCacheableVar)`                | Throws (would be baked in)                             |
+| `ctx.set(var, value)` (cacheable)         | Allowed                                                |
+| `ctx.header()` / cookie writes            | Throws (response side effect would be lost on hit)     |
+| Any of the above **inside a loader**      | Allowed (loaders always run fresh)                     |
+
+(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.)
+
+Write is dumb — `ctx.set()` stores the cache metadata but does not enforce.
+Enforcement happens at read time (`ctx.get()`), where ALS detects the cache
+scope and rejects non-cacheable reads.
+
+### The guarantee is precise — a direct read inside `cache()`, not propagating
+
+The guard fires on a **direct** `ctx.get(taintedVar)` **inside a `cache()`
+boundary** (the scope `isInsideCacheScope` detects). The taint lives on the
+variable; a value **derived** from it and read **outside** the boundary is not
+tracked:
+
+```typescript
+// CAUGHT — direct read of a tainted var inside a cache() boundary
+cache({ ttl: 60 }, () => [
+  path("/dashboard", (ctx) => {
+    const user = ctx.get(User); // throws: non-cacheable read inside cache()
+    return <Dashboard user={user} />;
+  }, { name: "dashboard" }),
+]);
+
+// NOT CAUGHT — read outside the boundary, derived value cached
+layout((ctx) => {
+  const name = ctx.get(User).name; // allowed — this layout is not cached
+  ctx.set(UserName, name); // now a plain (cacheable) string
+  return <Outlet />;
+}, () => [
+  cache({ ttl: 60 }, () => [
+    // a child reads ctx.get(UserName) and silently caches user-derived data
+  ]),
+]);
+```
+
+So do **not** read this as "you can't cache user data" — that overstates it and
+breeds the false confidence that makes the derived leak _more_ likely. The guard
+is deliberately non-propagating (propagation would cost a wrapper per derivation
+on the hot path), and it is scoped to the `cache()` segment boundary. `"use
+cache"` functions block the same request-scoped reads (`cookies()` / `headers()`
+throw inside them) and additionally exclude tainted `ctx`/`env`/`req` args from
+the cache key. The pattern that stays safe is also the natural one:
+**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 Always Fresh
 
 Loaders are **never cached** by route-level `cache()`. Even on a full cache hit
@@ -185,7 +428,7 @@ subsequent siblings. Everything below the cache boundary is cached as one unit:
 
 ```typescript
 path("/dashboard", DashboardPage, { name: "dashboard" }, () => [
-  cache("long"),
+  cache({ ttl: 300 }),
   layout(DashboardSidebar, () => [
     parallel("@stats", StatsPanel),
     parallel("@activity", ActivityFeed),
@@ -205,7 +448,7 @@ boundary are not cached and always re-render:
 layout(RootLayout, () => [
   // RootLayout is NOT cached — runs every request
   path("/products/:slug", ProductPage, { name: "product" }, () => [
-    cache("long"),
+    cache({ ttl: 300 }),
     layout(ProductSidebar),
     parallel("@reviews", ReviewsPanel),
     parallel("@related", RelatedProducts),
@@ -240,23 +483,10 @@ data is cached independently from the route's segment cache. Loader caching
 supports custom keys, tags, SWR, conditional bypass, and per-loader store
 overrides — see `/loader` for the full reference.
 
-## Decision Flowchart
-
-1. Do you want to cache an entire route or group of routes?
-   **Yes** -> `cache()`
-2. Do you need runtime conditions (skip for auth users, key by locale)?
-   **Yes** -> `cache()` with `condition` / `key`
-3. Do you want to cache a data fetch shared across routes?
-   **Yes** -> `"use cache"`
-4. Do you need different cache entries for different arguments?
-   **Yes** -> `"use cache"` (keyed by args)
-5. Is the expensive part rendering, not data fetching?
-   **Yes** -> `cache()` (caches rendered segments)
-6. Is the expensive part a single query inside a larger handler?
-   **Yes** -> `"use cache"` on the query function
-
 ## See Also
 
 - `/caching` — cache() DSL setup, stores, nested boundaries
 - `/use-cache` — "use cache" directive details, profiles, transforms, guards
-- `/document-cache` — Edge caching with Cache-Control headers (different layer)
+- `/document-cache` — store-backed complete-response middleware
+- `/deployment-caching` — in-function versus external CDN cache boundaries
+- `/ppr` — PPR shell caching: cached HTML shell + live loader holes (different layer)