@rangojs/router 0.0.0-experimental.112 → 0.0.0-experimental.114

package/dist/bin/rango.js

@@ -543,7 +543,7 @@ function writePerModuleRouteTypesForFile(filePath) {
     } else {
       routes = extractRoutesFromSource(source);
     }
-    const genPath = filePath.replace(/\.(tsx?)$/, ".gen.ts");
+    const genPath = filePath.replace(/\.(tsx?|jsx?)$/, ".gen.ts");
     if (routes.length === 0) {
       if (varNames.length > 0 && !existsSync2(genPath)) {
         writeFileSync(genPath, generatePerModuleTypesSource([]));
@@ -576,6 +576,75 @@ var init_per_module_writer = __esm({
   }
 });
 
+// src/build/route-types/source-scan.ts
+function isLineTerminator(ch) {
+  const c = ch.charCodeAt(0);
+  return c === 10 || c === 13 || c === 8232 || c === 8233;
+}
+function makeCodeClassifier(code) {
+  const n = code.length;
+  let i = 0;
+  let skipStart = -1;
+  let skipEnd = -1;
+  return (q) => {
+    if (q >= skipStart && q < skipEnd) return false;
+    while (i < n && i <= q) {
+      const c = code[i];
+      const d = i + 1 < n ? code[i + 1] : "";
+      let end = -1;
+      if (c === "/" && d === "/") {
+        let j = i + 2;
+        while (j < n && !isLineTerminator(code[j])) j++;
+        end = j;
+      } else if (c === "/" && d === "*") {
+        let j = i + 2;
+        while (j < n && !(code[j] === "*" && code[j + 1] === "/")) j++;
+        end = Math.min(n, j + 2);
+      } else if (c === '"' || c === "'" || c === "`") {
+        let j = i + 1;
+        while (j < n) {
+          if (code[j] === "\\") {
+            j += 2;
+            continue;
+          }
+          if (code[j] === c) {
+            j++;
+            break;
+          }
+          j++;
+        }
+        end = j;
+      }
+      if (end >= 0) {
+        if (q < end) {
+          skipStart = i;
+          skipEnd = end;
+          return false;
+        }
+        i = end;
+      } else {
+        i++;
+      }
+    }
+    return true;
+  };
+}
+function firstCodeMatchIndex(code, pattern) {
+  const inCode = makeCodeClassifier(code);
+  pattern.lastIndex = 0;
+  let m;
+  while ((m = pattern.exec(code)) !== null) {
+    if (inCode(m.index)) return m.index;
+    if (pattern.lastIndex <= m.index) pattern.lastIndex = m.index + 1;
+  }
+  return -1;
+}
+var init_source_scan = __esm({
+  "src/build/route-types/source-scan.ts"() {
+    "use strict";
+  }
+});
+
 // src/build/route-types/router-processing.ts
 import {
   readFileSync as readFileSync3,
@@ -630,7 +699,7 @@ function findRouterFilesRecursive(dir, filter, results) {
     if (filter && !filter(fullPath)) continue;
     try {
       const source = readFileSync3(fullPath, "utf-8");
-      if (ROUTER_CALL_PATTERN.test(source)) {
+      if (ROUTER_CALL_PATTERN.test(source) && firstCodeMatchIndex(source, ROUTER_CALL_PATTERN_G) >= 0) {
         routerFilesInDir.push(fullPath);
       }
     } catch {
@@ -971,15 +1040,17 @@ function writeCombinedRouteTypes(root, knownRouterFiles, opts) {
     }
   }
 }
-var ROUTER_CALL_PATTERN;
+var ROUTER_CALL_PATTERN, ROUTER_CALL_PATTERN_G;
 var init_router_processing = __esm({
   "src/build/route-types/router-processing.ts"() {
     "use strict";
     init_codegen();
+    init_source_scan();
     init_include_resolution();
     init_per_module_writer();
     init_route_name();
     ROUTER_CALL_PATTERN = /\bcreateRouter\s*[<(]/;
+    ROUTER_CALL_PATTERN_G = /\bcreateRouter\s*[<(]/g;
   }
 });
 

package/dist/vite/index.js

@@ -744,6 +744,83 @@ var STRICT_CREATE_CONFIGS = [
 
 // src/vite/plugins/expose-ids/export-analysis.ts
 import { parseAst } from "vite";
+
+// src/build/route-types/source-scan.ts
+function isLineTerminator(ch) {
+  const c = ch.charCodeAt(0);
+  return c === 10 || c === 13 || c === 8232 || c === 8233;
+}
+function makeCodeClassifier(code) {
+  const n = code.length;
+  let i = 0;
+  let skipStart = -1;
+  let skipEnd = -1;
+  return (q) => {
+    if (q >= skipStart && q < skipEnd) return false;
+    while (i < n && i <= q) {
+      const c = code[i];
+      const d = i + 1 < n ? code[i + 1] : "";
+      let end = -1;
+      if (c === "/" && d === "/") {
+        let j = i + 2;
+        while (j < n && !isLineTerminator(code[j])) j++;
+        end = j;
+      } else if (c === "/" && d === "*") {
+        let j = i + 2;
+        while (j < n && !(code[j] === "*" && code[j + 1] === "/")) j++;
+        end = Math.min(n, j + 2);
+      } else if (c === '"' || c === "'" || c === "`") {
+        let j = i + 1;
+        while (j < n) {
+          if (code[j] === "\\") {
+            j += 2;
+            continue;
+          }
+          if (code[j] === c) {
+            j++;
+            break;
+          }
+          j++;
+        }
+        end = j;
+      }
+      if (end >= 0) {
+        if (q < end) {
+          skipStart = i;
+          skipEnd = end;
+          return false;
+        }
+        i = end;
+      } else {
+        i++;
+      }
+    }
+    return true;
+  };
+}
+function firstCodeMatchIndex(code, pattern) {
+  const inCode = makeCodeClassifier(code);
+  pattern.lastIndex = 0;
+  let m;
+  while ((m = pattern.exec(code)) !== null) {
+    if (inCode(m.index)) return m.index;
+    if (pattern.lastIndex <= m.index) pattern.lastIndex = m.index + 1;
+  }
+  return -1;
+}
+function codeMatchIndices(code, pattern) {
+  const inCode = makeCodeClassifier(code);
+  const indices = [];
+  pattern.lastIndex = 0;
+  let m;
+  while ((m = pattern.exec(code)) !== null) {
+    if (inCode(m.index)) indices.push(m.index);
+    if (pattern.lastIndex <= m.index) pattern.lastIndex = m.index + 1;
+  }
+  return indices;
+}
+
+// src/vite/plugins/expose-ids/export-analysis.ts
 function isExportOnlyFile(code, bindings) {
   if (bindings.length === 0) return false;
   const knownLocals = /* @__PURE__ */ new Set();
@@ -772,12 +849,30 @@ function isExportOnlyFile(code, bindings) {
   }
   return true;
 }
-function countCreateCallsForNames(code, fnNames) {
-  const pattern = new RegExp(
+function createCallPattern(fnNames) {
+  return new RegExp(
     `\\b(?:${fnNames.map(escapeRegExp).join("|")})\\s*(?:<[^>]*>\\s*)?\\(`,
     "g"
   );
-  return (code.match(pattern) || []).length;
+}
+function countCreateCallsForNames(code, fnNames) {
+  return codeMatchIndices(code, createCallPattern(fnNames)).length;
+}
+function offsetToLineColumn(code, index) {
+  let line = 1;
+  let lineStart = 0;
+  const end = Math.min(index, code.length);
+  for (let i = 0; i < end; i++) {
+    if (code[i] === "\n") {
+      line++;
+      lineStart = i + 1;
+    }
+  }
+  return { line, column: index - lineStart + 1 };
+}
+function findUnsupportedCreateCallSites(code, fnNames, supportedBindings) {
+  const supported = new Set(supportedBindings.map((b) => b.callExprStart));
+  return codeMatchIndices(code, createCallPattern(fnNames)).filter((index) => !supported.has(index)).map((index) => offsetToLineColumn(code, index));
 }
 function getImportedFnNames(code, importedName) {
   const importPattern = /import\s*\{([^}]*)\}\s*from\s*["']@rangojs\/router(?:\/[^"']*)?["']/g;
@@ -936,9 +1031,20 @@ function collectCreateExportBindings(code, fnNames, program) {
   }
   return bindings;
 }
-function buildUnsupportedShapeWarning(filePath, fnName) {
-  return [
-    `[rango] Unsupported ${fnName} shape in "${filePath}".`,
+function buildUnsupportedShapeWarning(filePath, fnName, sites = []) {
+  const lines = [`[rango] Unsupported ${fnName} shape in "${filePath}".`];
+  if (sites.length === 1) {
+    const s = sites[0];
+    lines.push(
+      `The ${fnName}(...) call at ${filePath}:${s.line}:${s.column} has no stable $$id injected \u2014 it is not in a supported shape.`
+    );
+  } else if (sites.length > 1) {
+    lines.push(
+      `These ${fnName}(...) calls have no stable $$id injected \u2014 they are not in a supported shape:`
+    );
+    for (const s of sites) lines.push(`  - ${filePath}:${s.line}:${s.column}`);
+  }
+  lines.push(
     `Supported shapes are:`,
     `  - export const X = ${fnName}(...)`,
     `  - const X = ${fnName}(...); export { X }`,
@@ -946,7 +1052,8 @@ function buildUnsupportedShapeWarning(filePath, fnName) {
     `Potentially unsupported forms include:`,
     `  - export let/var X = ${fnName}(...)`,
     `  - inline ${fnName}(...) calls`
-  ].join("\n");
+  );
+  return lines.join("\n");
 }
 
 // src/vite/plugins/expose-ids/loader-transform.ts
@@ -1366,13 +1473,16 @@ ${lazyImports.join(",\n")}
           const hasCode = cfg.fnName === "createLoader" ? hasLoaderCode : cfg.fnName === "createHandle" ? hasHandleCode : hasLocationStateCode;
           if (!hasCode) continue;
           const fnNames = getFnNames(cfg.fnName);
-          const totalCalls = countCreateCallsForNames(code, fnNames);
-          const supportedBindings = getBindings(code, fnNames).length;
-          if (totalCalls <= supportedBindings) continue;
+          const sites = findUnsupportedCreateCallSites(
+            code,
+            fnNames,
+            getBindings(code, fnNames)
+          );
+          if (sites.length === 0) continue;
           const warnKey = `${id}::${cfg.fnName}`;
           if (unsupportedShapeWarnings.has(warnKey)) continue;
           unsupportedShapeWarnings.add(warnKey);
-          this.warn(buildUnsupportedShapeWarning(filePath, cfg.fnName));
+          this.warn(buildUnsupportedShapeWarning(filePath, cfg.fnName, sites));
         }
         if (hasLoaderCode && isRscEnv) {
           const fnNames = getFnNames("createLoader");
@@ -1658,6 +1768,7 @@ import MagicString4 from "magic-string";
 var debug4 = createRangoDebugger(NS.transform);
 var CACHE_RUNTIME_IMPORT = "@rangojs/router/cache-runtime";
 var LAYOUT_TEMPLATE_PATTERN = /\/(layout|template)\.(tsx?|jsx?)$/;
+var USE_CACHE_DIRECTIVE_RE = /^use cache(:\s*[\w-]+)?$/;
 function useCacheTransform() {
   let projectRoot = "";
   let isBuild = false;
@@ -1786,7 +1897,7 @@ function transformFileLevelUseCache(code, ast, filePath, sourceId, isBuild, isLa
 function transformFunctionLevelUseCache(code, ast, filePath, sourceId, isBuild, transformHoistInlineDirective) {
   try {
     const { output, names } = transformHoistInlineDirective(code, ast, {
-      directive: /^use cache(:\s*[\w-]+)?$/,
+      directive: USE_CACHE_DIRECTIVE_RE,
       runtime: (value, name, meta) => {
         const funcId = isBuild ? hashId(filePath, name) : `${filePath}#${name}`;
         const profileMatch = meta.directiveMatch[1];
@@ -1816,14 +1927,13 @@ function findFileLevelDirective(ast) {
   }
   return null;
 }
-var VALID_DIRECTIVE_RE = /^use cache(:\s*[\w-]+)?$/;
 var NEAR_MISS_RE = /^use cache:\s*.+$/;
 function warnOnNearMissDirectives(ast, fileId, warn) {
   const visit = (node) => {
     if (!node || typeof node !== "object") return;
     if (node.type === "ExpressionStatement" && node.expression?.type === "Literal" && typeof node.expression.value === "string") {
       const value = node.expression.value;
-      if (value.startsWith("use cache") && NEAR_MISS_RE.test(value) && !VALID_DIRECTIVE_RE.test(value)) {
+      if (value.startsWith("use cache") && NEAR_MISS_RE.test(value) && !USE_CACHE_DIRECTIVE_RE.test(value)) {
         const profilePart = value.slice("use cache:".length).trim();
         warn(
           `[rango:use-cache] "${value}" in ${fileId} has an invalid profile name "${profilePart}". Profile names must match [a-zA-Z0-9_-]+. This directive will be ignored.`
@@ -2019,7 +2129,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.112",
+  version: "0.0.0-experimental.114",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -2677,6 +2787,7 @@ function countPublicRouteEntries(source) {
   return count;
 }
 var ROUTER_CALL_PATTERN = /\bcreateRouter\s*[<(]/;
+var ROUTER_CALL_PATTERN_G = /\bcreateRouter\s*[<(]/g;
 function isRoutableSourceFile(name) {
   return (name.endsWith(".ts") || name.endsWith(".tsx") || name.endsWith(".js") || name.endsWith(".jsx")) && !name.includes(".gen.") && !name.includes(".test.") && !name.includes(".spec.");
 }
@@ -2704,7 +2815,7 @@ function findRouterFilesRecursive(dir, filter, results) {
     if (filter && !filter(fullPath)) continue;
     try {
       const source = readFileSync2(fullPath, "utf-8");
-      if (ROUTER_CALL_PATTERN.test(source)) {
+      if (ROUTER_CALL_PATTERN.test(source) && firstCodeMatchIndex(source, ROUTER_CALL_PATTERN_G) >= 0) {
         routerFilesInDir.push(fullPath);
       }
     } catch {
@@ -5946,8 +6057,12 @@ ${err.stack}`
             const trimmed = source.trimStart();
             const isUseClient = trimmed.startsWith('"use client"') || trimmed.startsWith("'use client'");
             if (!inRecoveryMode && isUseClient) return;
-            const hasUrls = source.includes("urls(");
-            const hasCreateRouter = /\bcreateRouter\s*[<(]/.test(source);
+            let hasUrls = source.includes("urls(");
+            let hasCreateRouter = /\bcreateRouter\s*[<(]/.test(source);
+            if (hasUrls) hasUrls = firstCodeMatchIndex(source, /urls\(/g) >= 0;
+            if (hasCreateRouter) {
+              hasCreateRouter = firstCodeMatchIndex(source, /\bcreateRouter\s*[<(]/g) >= 0;
+            }
             if (!inRecoveryMode && !hasUrls && !hasCreateRouter) return;
             if (inRecoveryMode) {
               debugDiscovery?.(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.112",
+  "version": "0.0.0-experimental.114",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/cache-guide/SKILL.md

@@ -6,8 +6,9 @@ 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 (not yet honored by the built-in stores — see "Two axes"
+below). They differ in scope, cache key, execution model, and runtime control.
 
 ## Two axes — do not conflate
 
@@ -17,7 +18,10 @@ caching:
 
 1. **Stored-value freshness** — _is a cached value still good?_
    → `"use cache"` (fn/component), `cache()` (segment), loader `cache()` (loader data).
-   Entries are coupled across the one store by **tags** (`revalidateTag`).
+   Entries expire by **TTL/SWR**. They accept an optional `tags` field, but the
+   built-in stores (`MemorySegmentCacheStore`, `CFCacheStore`) do not yet index or
+   invalidate by tag, so tag-based invalidation (`revalidateTag`) is a
+   forward-looking API requiring a custom store with secondary indices.
 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**.
@@ -58,12 +62,16 @@ There are two guard models to keep separate. Both block response side effects
 else they allow:
 
 - **`cache()` boundary guard** (route-level) — fires while the handler runs on a
-  miss. `ctx.get(nonCacheableVar)` throws (a tainted value would be baked into the
-  cached segment) and response side effects (`ctx.header()`, `ctx.setCookie()`,
+  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.
-- **`"use cache"` exec-guard** (function-level) — stricter: inside the cached
-  function `cookies()`, `headers()`, `ctx.set()`, and `ctx.header()` all throw.
+  **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
 
@@ -331,18 +339,21 @@ specifies `cache: false`, the value is non-cacheable.
 
 **Behavior inside a `cache()` boundary:**
 
-| Operation                         | Inside a `cache()` boundary                        |
-| --------------------------------- | -------------------------------------------------- |
-| `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) |
-
-(Inside a `"use cache"` function the scoping differs: `ctx.set`, `ctx.header()`,
-`cookies()`, and `headers()` **throw** via the cache-exec guard. Inside
-`cache()`, response side effects throw via the cache-boundary guard, while the
-`ctx.get(nonCacheableVar)` taint check above is tied to the `cache()` boundary —
-see "Headers and Cookies" and the precise guarantee below.)
+| 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
@@ -379,10 +390,10 @@ layout((ctx) => {
 So do **not** read this as "you can't cache user data" — that overstates it and
 breeds the false confidence that makes the derived leak _more_ likely. The guard
 is deliberately non-propagating (propagation would cost a wrapper per derivation
-on the hot path), and it is scoped to the `cache()` segment boundary — `"use
-cache"` functions guard request data differently (tainted `ctx`/`env`/`req` args
-are excluded from the cache key, and `cookies()` / `headers()` throw inside them;
-see "Headers and Cookies"). The pattern that stays safe is also the natural one:
+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

package/skills/caching/SKILL.md

@@ -8,6 +8,46 @@ argument-hint: [setup]
 
 @rangojs/router supports segment-level caching with stale-while-revalidate (SWR) for optimal performance.
 
+> SWR support is store-specific. `CFCacheStore` revalidates segment, response,
+> and `"use cache"` entries in the background. `MemorySegmentCacheStore`
+> supports SWR for response and `"use cache"` item entries, but its
+> route-segment entries expire at TTL with no background revalidation — use
+> `CFCacheStore` for real segment SWR. See `/cache-guide`.
+
+## cache() is Partial Prerendering (PPR)
+
+`cache()` caches **everything except loaders**. On a cache hit, the cached
+segments (layouts, route components, parallels — including any resolved
+Suspense) are served from the store, and **loaders re-run fresh on every
+request**, streaming their results into the same response. Loaders are the
+dynamic "holes" of an otherwise-cached tree.
+
+This means a `cache()` boundary at the document root **is** whole-document
+Partial Prerendering: the static shell is cached and served instantly while
+per-request/per-user data stays live — in one streamed response, no extra round
+trip. The browser cannot tell the shell came from cache.
+
+```typescript
+cache({ ttl: 60, swr: 300 }, () => [
+  layout(<RootLayout />), // cached shell
+  path("/dashboard", Dashboard, { name: "dashboard" }, () => [
+    loader(StatsLoader), // DYNAMIC HOLE — re-runs every request
+  ]),
+]);
+```
+
+The consumer rule: **want it cached? render it inline. want it dynamic? 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 (loaders always run fresh). Reading it directly in a cached handler
+throws; awaiting it with `ctx.use()` and rendering the result in a cached
+handler silently bakes per-request data into the shared shell (see "Cache purity
+& tainted objects" below).
+
+Pre-rendering (`/prerender`) is the build-time twin: it caches the same shell at
+build time instead of on first request. Both feed the segment system
+identically, and loaders always run fresh at request time.
+
 ## Route-Level Caching with cache()
 
 Use the `cache()` DSL function to cache routes:
@@ -116,7 +156,6 @@ import { MemorySegmentCacheStore } from "@rangojs/router/cache";
 
 const store = new MemorySegmentCacheStore({
   defaults: { ttl: 60, swr: 300 },
-  maxSize: 1000, // Max entries
 });
 ```
 
@@ -173,13 +212,82 @@ const router = createRouter<AppBindings>({
 KV entries require `expirationTtl >= 60s`. Short-lived entries (< 60s total TTL)
 are only cached in L1.
 
-## Context Variables Inside Cache Boundaries
+## Cache purity & tainted objects
+
+A `cache()` boundary caches everything except loaders, so anything read inside a
+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 |
+| `ctx.header()` / `setCookie()` / `setStatus()` / `onResponse()` | **throws** — response side effects lost on a hit    |
+| `ctx.get(var)` where the var is `{ cache: false }`              | **throws** on read                                  |
+| `ctx.set(var, value)` for a cacheable var                       | allowed (children are cached too)                   |
+| Any of the above **inside a loader**                            | **allowed** — loaders always run fresh              |
+
+**Tainted objects.** Request-scoped objects (`ctx`, `env`, `request`) carry an
+internal taint symbol so they are excluded from `"use cache"` cache keys, and
+the cache scope is tracked via async-local state. Two flags back the guards:
+`INSIDE_CACHE_EXEC` (set while a `"use cache"` function runs) and the `cache()`
+DSL scope (`isInsideCacheScope()`). `isInsideCacheScope()` deliberately returns
+`false` inside loaders — which is exactly why loaders are the dynamic holes:
+they may read `cookies()`/`headers()` and re-run on every request.
+
+The fix for "I need request data in a cached route": register a `loader()` and
+**consume it with `useLoader()` in a client component**. The loader is the
+dynamic hole — its data rides the fresh (never-cached) loader segment and is
+rendered in the client component, so it never lands in the cached shell.
+
+This is NOT the same as awaiting the loader in the handler. A cached handler
+that does `await ctx.use(Loader)` and renders the result bakes that per-request
+data straight into the shared cached segment — the loader running "fresh" does
+not help, because its output was inlined into the cached parent, and `ctx.use()`
+is **not** guarded. `ctx.use()` is a server-side escape hatch for non-rendered
+uses (set a ctx var, make a routing decision); never render its result inside a
+cached handler.
+
+```typescript
+// WRONG — throws: cookies() read directly in a cached handler
+cache({ ttl: 60 }, () => [
+  path("/me", () => <Profile id={cookies().get("uid")?.value} />),
+]);
+
+// ALSO WRONG (unguarded, but leaks) — the awaited loader data is rendered into
+// the cached handler, so the user's data is frozen into the shared shell.
+cache({ ttl: 60 }, () => [
+  path(
+    "/me",
+    async (ctx) => {
+      const { user } = await ctx.use(MeLoader); // runs fresh…
+      return <Profile user={user} />; // …but inlined into the CACHED segment → leak
+    },
+    { name: "me" },
+    () => [loader(MeLoader)],
+  ),
+]);
+
+// RIGHT — consume the loader in a CLIENT component via useLoader(). The cached
+// route segment holds only the <Profile/> reference; the user data rides the
+// fresh loader segment and renders client-side.
+
+// profile.tsx (client component)
+"use client";
+import { useLoader } from "@rangojs/router/client";
+
+export function Profile() {
+  const { user } = useLoader(MeLoader); // fresh per request; never cached
+  return <span>{user.name}</span>;
+}
+
+// urls — register the loader; MeLoader reads cookies() inside the loader (allowed)
+cache({ ttl: 60 }, () => [
+  path("/me", () => <Profile />, { name: "me" }, () => [loader(MeLoader)]),
+]);
+```
 
-Context variables (`createVar`) are cacheable by default and can be read and
-written inside `cache()` scopes. Variables marked with `{ cache: false }` (at
-the var level or write level) throw when read inside a cache scope. Response
-side effects (`ctx.header()`, `ctx.cookie()`) always throw inside cache
-boundaries. See `/cache-guide` for the full cache safety table.
+See `/cache-guide` for the full decision guide and the `cache()` vs `"use cache"` comparison.
 
 ## Nested Cache Boundaries