@rangojs/router 0.16.0 → 0.18.0

package/src/server/context.ts

@@ -12,6 +12,12 @@ import type {
 } from "../types";
 import { invariant, DslContextError } from "../errors";
 import type { DefaultRouteName } from "../types/global-namespace.js";
+import type { ContextVar } from "../context-var.js";
+import { PPR_LANE_HINT } from "../rsc/shell-capture-constants.js";
+import {
+  getCacheExecScope,
+  type CacheExecScope,
+} from "../cache/cache-exec-scope.js";
 
 // ============================================================================
 //  Performance Metrics Types
@@ -65,6 +71,17 @@ export type EntryPropCommon = {
   id: string;
   shortCode: string; // Short identifier for network efficiency (e.g., "L0", "P1", "R2")
   parent: EntryData | null;
+  /**
+   * Orphan siblings only (attachOrphanSibling in
+   * route-definition/dsl-helpers.ts): the entry whose `layout[]` holds this
+   * one. `parent` stays null on an orphan (matchError's matched-id stack in
+   * router/match-api.ts starts at the boundary-holding entry, possibly an
+   * orphan, and must stop there), so the boundary walkers in
+   * router/error-handling.ts follow this instead. A lookup that starts at an
+   * orphan (its loaders, an intercept it declares) then reaches the owner's
+   * boundaries and the owner's ancestors.
+   */
+  orphanOwner?: EntryData;
   /** Cache configuration for this entry (set by cache() DSL) */
   cache?: EntryCacheConfig;
   /** URL prefix from include() scope, used for MountContext on client */
@@ -118,6 +135,15 @@ export type LoaderEntry = {
    * appears on navigation-lane entries.
    */
   awaitBeforeFlush?: true;
+  /**
+   * loader(Def, { ssr: false }) on every DSL evaluation, document and
+   * navigation: the loader's PPR bake lane (loader-cache.ts
+   * resolveLoaderData). The bake/seed key rides on it, so a client
+   * navigation's shell replay pins exactly the loaders a document HIT pins,
+   * whatever the entry's loading(). awaitBeforeFlush cannot carry that: a
+   * navigation evaluation never has it.
+   */
+  bake?: true;
 };
 
 /**
@@ -187,9 +213,6 @@ export type InterceptEntry = {
   routeName: string; // e.g., "card"
   handler: ReactNode | Handler<any, any, any>;
   middleware: MiddlewareFn<any, any>[];
-  revalidate: ShouldRevalidateFn<any, any>[];
-  errorBoundary: (ReactNode | ErrorBoundaryHandler)[];
-  notFoundBoundary: (ReactNode | NotFoundBoundaryHandler)[];
   loader: LoaderEntry[];
   loading?: ReactNode | false;
   transition?: TransitionConfig;
@@ -833,27 +856,30 @@ const loaderScopeALS: AsyncLocalStorage<{ active: true }> = ((
 // Purity-only scope: marks that a loader FUNCTION BODY is executing, regardless
 // of how the loader was invoked (DSL via runInsideLoaderScope, or handler-
 // invoked via ctx.use). Consulted by isInsideCacheScope() to exempt
-// request-scoped reads, by getCurrentLoaderBodyId() for guard-warning
-// attribution, and by isInsideHandlerInvokedLoaderBody() for the
-// consumption-lane rule (the shell-capture guard exemption). It deliberately
-// does NOT affect isInsideLoaderScope(), so rendered()/barrier/deadlock
-// gating (which must distinguish DSL from handler-invoked loaders) is
-// unchanged.
-const LOADER_BODY_SCOPE_KEY = Symbol.for("rangojs-router:loader-body-scope");
-const loaderBodyScopeALS: AsyncLocalStorage<{
-  active: true;
-  loaderId?: string;
-  handlerInvoked?: boolean;
-}> = ((globalThis as any)[LOADER_BODY_SCOPE_KEY] ??= new AsyncLocalStorage<{
+// request-scoped reads, and by getCurrentLoaderBodyId() for guard-warning
+// attribution. It deliberately does NOT affect isInsideLoaderScope(), so
+// rendered()/barrier/deadlock gating (which must distinguish DSL from
+// handler-invoked loaders) is unchanged.
+interface LoaderBodyScope {
   active: true;
   loaderId?: string;
-  handlerInvoked?: boolean;
-}>());
+  /** The body scope this one was entered from (a ctx.use(Loader) chain). */
+  parent?: LoaderBodyScope;
+  /** The "use cache" scope the body was entered in (assertNonCacheableReadAllowed). */
+  execScope?: CacheExecScope;
+  /** The tags this execution records (#964, cache-tag.ts "Recorded-tag sets"). */
+  tags?: Set<string>;
+}
+const LOADER_BODY_SCOPE_KEY = Symbol.for("rangojs-router:loader-body-scope");
+const loaderBodyScopeALS: AsyncLocalStorage<LoaderBodyScope> = ((
+  globalThis as any
+)[LOADER_BODY_SCOPE_KEY] ??= new AsyncLocalStorage<LoaderBodyScope>());
 
 /**
  * Check if the current execution is inside a cache() DSL boundary.
- * Returns false inside loader execution — loaders are always fresh
- * (never cached), so non-cacheable reads are safe.
+ * Returns false inside loader execution: a route cache() does not store
+ * loader values, so non-cacheable reads are safe. A loader bound with its own
+ * cache() stores its value; recordLoaderIdentityRead guards that.
  */
 export function isInsideCacheScope(): boolean {
   if (RangoContext.getStore()?.insideCacheScope !== true) return false;
@@ -869,6 +895,234 @@ export function isInsideCacheScope(): boolean {
   return true;
 }
 
+/**
+ * Throw if called during the ACTIVE background shell-capture render
+ * (`_shellCaptureRun` true on the derived request context built by
+ * shell-capture.ts). The captured shell is shared across every user hitting
+ * the URL, so a request-scoped read here would bake one user's cookies,
+ * headers, or per-request variables into markup served to others — same
+ * hazard as the cache scopes above, at the document tier. DSL segment loaders
+ * need no exemption: the live lane is masked (never executed) during capture,
+ * and the bake lane is exactly what this guard exists for.
+ *
+ * It covers everything the capture waits for, not only synchronous handler
+ * code: a promise the handler passes or pushes, an async server component,
+ * and a loader the handler awaits (`await ctx.use(Loader)`) all run under the
+ * capture context and all bake. The last one used to be exempt (the
+ * consumption-lane rule, #672/#674): while a HIT re-ran handlers, a slot
+ * handler's `ctx.use` of an identity loader rendered per visitor on the HIT.
+ * Now every HIT replays the capture's copy, so the exemption would bake the
+ * capturing request's identity into every visitor's page. The cache()
+ * guards above keep it (a cache() HIT is a separate tier).
+ *
+ * Keys off `_shellCaptureRun`, NOT the `_shellCapture` descriptor: the descriptor
+ * is also present during the FOREGROUND render (it means "a capture is wanted"),
+ * and the foreground must read cookies/headers normally to serve the real user.
+ * Only the derived capture context sets `_shellCaptureRun`.
+ *
+ * Applies only to the READ surfaces (cookies(), headers(), a { cache: false }
+ * variable, and the theme reads through tripShellCaptureGuard) whose values
+ * become markup. Response directives
+ * (invalidateClientCache(), keepClientCache()) stay callable: during capture
+ * they are header effects on a discarded response, and on the live HIT path
+ * the full pipeline runs so their headers flow to the client normally.
+ *
+ * The throw can be caught by the code that made the read, so the guard also
+ * flags the capture context; the capture refuses on the flag
+ * (shell-capture.ts refuseOnCaptureGuard), nothing is stored, and every
+ * request keeps getting the normal axis-1 render.
+ */
+export function assertNotInsideShellCapture(
+  ctx: unknown,
+  fnName: string,
+): void {
+  if (!tripShellCaptureGuard(ctx, `${fnName}()`, REQUEST_READ_CAPTURE_FIX)) {
+    return;
+  }
+  const what =
+    fnName === "cookies"
+      ? "cookies"
+      : fnName === "headers"
+        ? "headers"
+        : "per-request variables";
+  throw new Error(
+    `${fnName}() cannot be called while capturing a shared shell ` +
+      `(ppr shell capture). The captured shell is served to every user ` +
+      `of this URL, so request-scoped data read here would leak one user's ` +
+      `${what} to others. Read it ` +
+      `inside a loader without ssr: false and consume it with useLoader, e.g. ` +
+      `createLoader(async () => getUser(cookies().get("session")?.value)). ` +
+      PPR_LANE_HINT,
+  );
+}
+
+/**
+ * The fix the capture refusal warning (shell-capture.ts refuseOnCaptureGuard)
+ * gives for a cookies()/headers()/{ cache: false } variable read. Recorded
+ * with the trip (tripShellCaptureGuard), so each guarded read carries its own
+ * fix; the theme reads (cookie-store.ts assertThemeReadAllowed) record theirs.
+ */
+const REQUEST_READ_CAPTURE_FIX: string =
+  "Read it in a loader without ssr: false and consume it with useLoader under " +
+  "loading() or an inline <Suspense> (a live hole). A promise the handler passes " +
+  "or pushes does not help: the capture waits for it.";
+
+/**
+ * True when `ctx` is the active capture render (assertNotInsideShellCapture
+ * above). On true the capture context is flagged with the read (`surface`,
+ * e.g. "cookies()", "ctx.theme") and the fix the refusal warning gives, plus
+ * the loader body (if any) that made the read, and the caller throws.
+ */
+export function tripShellCaptureGuard(
+  ctx: unknown,
+  surface: string,
+  fix: string,
+): boolean {
+  if (
+    ctx === null ||
+    typeof ctx !== "object" ||
+    (ctx as { _shellCaptureRun?: unknown })._shellCaptureRun !== true
+  ) {
+    return false;
+  }
+  // Record WHICH loader body (if any) made the read, so the refusal warning
+  // can name the real source instead of hardcoding a lane (issue #672).
+  const flagged = ctx as {
+    _shellCaptureGuardTripped?: { surface: string; fix: string };
+    _shellCaptureGuardTrippedLoaderId?: string;
+  };
+  flagged._shellCaptureGuardTripped = { surface, fix };
+  flagged._shellCaptureGuardTrippedLoaderId = getCurrentLoaderBodyId();
+  return true;
+}
+
+/**
+ * Read guard for a non-cacheable variable (`createVar({ cache: false })` or a
+ * `ctx.set(..., { cache: false })` write). Callers check isNonCacheable() first
+ * so ordinary reads never reach the scope lookups.
+ *
+ * Throws during a PPR shell capture (`requestCtx` is the ambient request
+ * context; assertNotInsideShellCapture): the shell is shared per host+URL.
+ *
+ * Throws inside a "use cache" body: the key does not include the value, so the
+ * first caller's value would be stored and served to later callers (#925). A
+ * loader body entered INSIDE the cached function is exempt, the same baked-copy
+ * trade isInsideCacheScope() makes for cache(). A cached function called FROM a
+ * loader is not: the loader re-runs, the cached body does not. The body scope
+ * records the exec scope it was entered in, so the exemption holds only while
+ * that is still the innermost one.
+ */
+export function assertNonCacheableReadAllowed(
+  keyOrVar: string | ContextVar<unknown>,
+  requestCtx?: unknown,
+): void {
+  // A shell capture bakes what it reads into a page every visitor gets.
+  assertNotInsideShellCapture(requestCtx, "ctx.get");
+  const execScope = getCacheExecScope();
+  const variable = ` for a non-cacheable variable${typeof keyOrVar === "string" ? ` "${keyOrVar}"` : ""}`;
+  if (
+    execScope !== undefined &&
+    loaderBodyScopeALS.getStore()?.execScope !== execScope
+  ) {
+    throw new Error(
+      `ctx.get()${variable} cannot be called inside a "use cache" function. ` +
+        `The variable was created with { cache: false } or set with { cache: false }, ` +
+        `and the cache key does not include its value, so the first caller's value ` +
+        `would be served to later callers. Read it before calling the cached function ` +
+        `and pass the value in as an argument so it becomes part of the cache key.`,
+    );
+  }
+  if (isInsideCacheScope()) {
+    throw new Error(
+      `ctx.get() for a non-cacheable variable cannot be called inside a cache() boundary. ` +
+        `The variable was created with { cache: false } or set with { cache: false }, ` +
+        `and its value would be stale on cache hit. Move the read outside the cached scope.`,
+    );
+  }
+  recordLoaderIdentityRead(`ctx.get()${variable}`);
+}
+
+/** How the identity error words a read: a function call or a property read. */
+export type LoaderIdentityReadVerb = "called" | "read";
+
+/** A request-identity read a loader execution made (recordLoaderIdentityRead). */
+export interface LoaderIdentityRead {
+  /**
+   * The read as the error names it: "cookies()", "headers()",
+   * `ctx.get() for a non-cacheable variable "x"`, "ctx.theme" or
+   * "getRequestContext().theme".
+   */
+  surface: string;
+  /** "called" for a function, "read" for a property (the theme getters). */
+  verb: LoaderIdentityReadVerb;
+  /** The loader body that made the read. */
+  bodyId: string | undefined;
+  /**
+   * The cached loader whose value carries a read another loader made
+   * (loader-cache.ts identity mark): its readers read it through `via`.
+   */
+  via?: string;
+}
+
+/**
+ * Where cache-tag.ts installs its recorder at module init (same key there):
+ * it owns the per-execution recorded sets, and importing it here would be a
+ * cycle.
+ */
+const IDENTITY_READ_RECORDER_KEY = Symbol.for(
+  "rangojs-router:identity-read-recorder",
+);
+
+/**
+ * Record a request-identity read (cookies(), headers(), a non-cacheable
+ * ctx.get()) on the current loader execution (#972).
+ *
+ * isInsideCacheScope() exempts loader bodies because a route cache() never
+ * stores their values. A loader bound with its own cache() does: with no key()
+ * and no store keyGenerator its entry is keyed by loader, host, path and
+ * params only, and an enclosing route cache() key does not partition it
+ * (#974). A cookies() read there stored the first visitor's session and served
+ * it to everyone for the TTL. The read is recorded on the execution, not
+ * thrown at the call: a reader that starts the loader before its binding does
+ * runs it outside any fill, and the binding's MISS then reuses that run. The
+ * fill checks what its execution recorded, through the same links as its tags
+ * (cache-tag.ts recordedIdentityRead), so both orders fail the same way.
+ * Response directives do not record: a key cannot make a skipped body's side
+ * effect reach a HIT.
+ */
+export function recordLoaderIdentityRead(
+  surface: string,
+  verb: LoaderIdentityReadVerb = "called",
+): void {
+  const recorder = (globalThis as Record<symbol, unknown>)[
+    IDENTITY_READ_RECORDER_KEY
+  ] as ((surface: string, verb: LoaderIdentityReadVerb) => void) | undefined;
+  recorder?.(surface, verb);
+}
+
+/** The error a loader cache() fill with no declared key fails with (#972). */
+export function loaderCacheIdentityError(
+  read: LoaderIdentityRead,
+  cachedLoaderId: string,
+): Error {
+  const filling = `while filling its own cache() entry with no key()`;
+  const where =
+    read.via !== undefined && read.via !== cachedLoaderId
+      ? `inside loader "${read.bodyId}", which loader "${cachedLoaderId}" reads through another loader ("${read.via}") ${filling}`
+      : read.bodyId !== undefined && read.bodyId !== cachedLoaderId
+        ? `inside loader "${read.bodyId}", which loader "${cachedLoaderId}" reads ${filling}`
+        : `inside loader "${cachedLoaderId}", whose own cache() has no key()`;
+  return new Error(
+    `${read.surface} cannot be ${read.verb} ${where}. ` +
+      `The entry is keyed by loader, host, path and params only, so it is ` +
+      `shared across users: request-scoped data (cookies, headers, ` +
+      `non-cacheable variables) read here would be stored from one request ` +
+      `and served to everyone. Add a key that includes the value, or drop ` +
+      `the loader's cache():\n\n` +
+      `  cache({ ttl: 60, key: (ctx) => \`session:\${cookies().get("session")?.value}\` })`,
+  );
+}
+
 /**
  * Check if the current execution is inside a DSL loader scope
  * (wrapped by runInsideLoaderScope). Used by rendered() barrier
@@ -897,7 +1151,7 @@ export function latchCachedHeaderScope(
 /** True inside ANY loader execution — DSL loader scope or a loader body
  *  (however invoked). The "loaders always re-run fresh" exemptions key off
  *  this. */
-function isInsideAnyLoaderScope(): boolean {
+export function isInsideAnyLoaderScope(): boolean {
   return (
     loaderScopeALS.getStore()?.active === true ||
     loaderBodyScopeALS.getStore()?.active === true
@@ -1050,15 +1304,29 @@ export function runInsideLoaderScope<T>(fn: () => T): T {
 export function runInsideLoaderBodyScope<T>(
   fn: () => T,
   loaderId?: string,
-  handlerInvoked?: boolean,
+  tags?: Set<string>,
 ): T {
-  return loaderBodyScopeALS.run({ active: true, loaderId, handlerInvoked }, fn);
+  return loaderBodyScopeALS.run(
+    {
+      active: true,
+      loaderId,
+      parent: loaderBodyScopeALS.getStore(),
+      execScope: getCacheExecScope(),
+      tags,
+    },
+    fn,
+  );
+}
+
+/** The innermost loader body's execution tag set (runInsideLoaderBodyScope). */
+export function getLoaderBodyTags(): Set<string> | undefined {
+  return loaderBodyScopeALS.getStore()?.tags;
 }
 
 /**
  * The $$id of the loader whose body is currently executing, or undefined
  * outside any loader body. Used by the shell-capture identity guard
- * (cookie-store.ts) so its refusal warning can name the loader that read
+ * (assertNotInsideShellCapture) so its refusal warning can name the loader that read
  * cookies()/headers() instead of blaming a lane it cannot see — the old
  * hardcoded "bake-lane loader" text misled a live-lane debugging session
  * (issue #672, secondary).
@@ -1068,16 +1336,16 @@ export function getCurrentLoaderBodyId(): string | undefined {
 }
 
 /**
- * True while a HANDLER-invoked loader body (`await ctx.use(Loader)` from a
- * handler, not the DSL segment funnel) is executing. The consumption-lane
- * rule keys off this: handler consumption yields a BAKED copy in every shared
- * artifact — cache(), "use cache", and the PPR shell — so the shell-capture
- * identity guard (cookie-store.ts) permits cookies()/headers() here, exactly
- * like the cache-purity guards do. DSL segment loaders (live lane masked at
- * capture, bake lane guarded) never set the flag.
+ * True while `loaderId`'s body, or a loader it awaits via ctx.use at any
+ * depth, is executing. The loader-level cache records these pushes
+ * (loader-cache.ts): a HIT skips the cached body, so a dep that no other
+ * reader runs in that request only reaches the page through the replay.
  */
-export function isInsideHandlerInvokedLoaderBody(): boolean {
-  return loaderBodyScopeALS.getStore()?.handlerInvoked === true;
+export function isInsideLoaderBody(loaderId: string): boolean {
+  for (let s = loaderBodyScopeALS.getStore(); s; s = s.parent) {
+    if (s.loaderId === loaderId) return true;
+  }
+  return false;
 }
 
 // Scope for handle PUSH CALLBACKS (push(() => ...), including async ones).

package/src/server/cookie-store.ts

@@ -11,8 +11,9 @@ import type { CookieOptions } from "../router/middleware-types.js";
 import { getRequestContext, _getRequestContext } from "./request-context.js";
 import {
   isInsideCacheScope,
-  getCurrentLoaderBodyId,
-  isInsideHandlerInvokedLoaderBody,
+  assertNotInsideShellCapture,
+  tripShellCaptureGuard,
+  recordLoaderIdentityRead,
 } from "./context.js";
 import { isInsideCacheExecScope } from "../cache/cache-exec-scope.js";
 
@@ -112,9 +113,13 @@ type HeadersIterator<T> = IterableIterator<T>;
  * (Scar: the previous INSIDE_CACHE_EXEC stamp on the shared RequestContext
  * made exactly that parallel read throw for the cached fetch's whole
  * execution window — see cache-exec-scope.ts.)
+ *
+ * The loader cache() identity reads (#972) are recorded by the read methods
+ * instead (createCookieStore, the headers() view), so a write alone is not one.
  */
 function assertNotInsideCacheContext(fnName: string): void {
-  if (isInsideCacheExecScope()) {
+  const scope = refusingCacheScope();
+  if (scope === "use cache") {
     throw new Error(
       `${fnName}() cannot be called inside a "use cache" function. ` +
         `Request-scoped data (cookies, headers) varies per request but is not ` +
@@ -125,7 +130,7 @@ function assertNotInsideCacheContext(fnName: string): void {
         `  const data = await getCachedData(locale); // locale is now in the cache key`,
     );
   }
-  if (isInsideCacheScope()) {
+  if (scope === "cache()") {
     throw new Error(
       `${fnName}() cannot be called inside a cache() boundary. ` +
         `A cache() scope caches everything except loaders, so request-scoped ` +
@@ -138,72 +143,89 @@ function assertNotInsideCacheContext(fnName: string): void {
 }
 
 /**
- * Throw if called during the ACTIVE background shell-capture render
- * (`_shellCaptureRun` true on the derived request context built by
- * shell-capture.ts). The captured shell prelude is shared across every user
- * hitting the URL, so a request-scoped read here would bake one user's
- * cookies/headers into markup served to others — same hazard as the cache
- * scopes above, at the document tier. DSL segment loaders need no exemption:
- * the live lane is masked (never executed) during capture, and the bake lane
- * is exactly what this guard exists for.
- *
- * HANDLER-INVOKED loader bodies (`await ctx.use(Loader)` from a handler) are
- * EXEMPT — the consumption-lane rule: handler consumption yields a BAKED
- * shared copy in every artifact tier, and the cache-purity guards above
- * already permit identity reads there (cache()/"use cache" bake the same
- * reads today). Guarding only the PPR tier made the same code legal under
- * cache() but capture-refusing under ppr (issue #672 / #674). The trade is
- * documented: an identity read in a handler-consumed loader bakes the CAPTURE
- * request's value into the shared shell; client-side consumption (useLoader)
- * is the live lane.
- *
- * Keys off `_shellCaptureRun`, NOT the `_shellCapture` descriptor: the descriptor
- * is also present during the FOREGROUND render (it means "a capture is wanted"),
- * and the foreground must read cookies/headers normally to serve the real user.
- * Only the derived capture context sets `_shellCaptureRun`.
+ * The cache scope that refuses a request-scoped read here, or undefined. One
+ * owner of the predicates and their order (assertNotInsideCacheContext above),
+ * so cookies()/headers() and the theme reads refuse in the same places.
+ */
+function refusingCacheScope(): "use cache" | "cache()" | undefined {
+  if (isInsideCacheExecScope()) return "use cache";
+  if (isInsideCacheScope()) return "cache()";
+  return undefined;
+}
+
+/** The fix for a theme read that a cache() boundary or a ppr capture refuses. */
+const THEME_READ_FIX =
+  "On ppr and cache() routes, read the theme with useTheme() in a client " +
+  "component, or in a live loader (no ssr: false) with cookies().get(<storageKey>). " +
+  "The <html> theme class needs neither: the theme script sets it before paint. " +
+  "See the /theme skill (node_modules/@rangojs/router/skills/theme/SKILL.md).";
+
+/** The public reads of the visitor's theme cookie that assertThemeReadAllowed guards. */
+export type ThemeReadSurface = "ctx.theme" | "getRequestContext().theme";
+
+/**
+ * Guard for a read of the visitor's theme: the handler and middleware
+ * `ctx.theme` (handler-context.ts, middleware.ts) and `getRequestContext().theme`
+ * (request-context.ts). The theme is the visitor's theme cookie, so it is an
+ * identity read like cookies(): it refuses in the same scopes, in the same
+ * order (refusingCacheScope, then tripShellCaptureGuard in context.ts), with
+ * the same exemption (a loader body under cache(); at capture there is none).
+ * Before #971 each read was a plain cookie read, so a ppr shell, a cache()
+ * entry or a "use cache" entry stored the first visitor's theme and served it
+ * to every later visitor.
  *
- * Applies only to the READ surfaces (cookies(), headers()) whose values
- * become markup. Response directives (invalidateClientCache(),
- * keepClientCache()) stay callable: during capture they are header effects on
- * a discarded response, and on the live HIT path the full pipeline runs so their
- * headers flow to the client normally.
+ * A read the guards allow is recorded on the current loader execution, as a
+ * cookies() read method records it (#972, recordLoaderIdentityRead).
  *
- * The throw makes such a route PPR-ineligible by construction: the capture
- * render errors, nothing is stored, and every request keeps getting the
- * normal axis-1 render.
+ * `ctx` is the request context at read time, as cookies() reads it. The
+ * router's own payload read (payloadInitialTheme, rsc/full-payload.ts) goes
+ * through the unguarded `_readTheme()`.
  */
-function assertNotInsideShellCapture(ctx: unknown, fnName: string): void {
-  if (
-    ctx !== null &&
-    typeof ctx === "object" &&
-    (ctx as { _shellCaptureRun?: unknown })._shellCaptureRun === true
-  ) {
-    if (isInsideHandlerInvokedLoaderBody()) return;
-    // Flag the capture context BEFORE throwing: inside an executing bake-lane
-    // loader this throw is swallowed by wrapLoaderPromise into per-loader error
-    // UI, which would bake silently into the shared shell. The capture checks
-    // the flag after the render and refuses (shell-capture.ts). Also record
-    // WHICH loader body (if any) made the read, so the refusal warning can
-    // name the real source instead of hardcoding a lane — the read may come
-    // from a bake-lane loader OR from handler/render code (issue #672).
-    (ctx as { _shellCaptureGuardTripped?: string })._shellCaptureGuardTripped =
-      fnName;
-    (
-      ctx as { _shellCaptureGuardTrippedLoaderId?: string }
-    )._shellCaptureGuardTrippedLoaderId = getCurrentLoaderBodyId();
+export function assertThemeReadAllowed(
+  ctx: unknown,
+  surface: ThemeReadSurface,
+): void {
+  const scope = refusingCacheScope();
+  if (scope === "use cache") {
     throw new Error(
-      `${fnName}() cannot be called while capturing a shared shell ` +
-        `(shell-cache middleware). The captured shell is served to every user ` +
-        `of this URL, so request-scoped data read here would leak one user's ` +
-        `${fnName === "cookies" ? "cookies" : "headers"} to others. Read it ` +
-        `inside a loader instead — loaders are never captured and always run ` +
-        `fresh per request:\n\n` +
-        `  loader("user", () => getUser(cookies().get("session")?.value));`,
+      `${surface} cannot be read inside a "use cache" function. The theme ` +
+        `comes from the visitor's cookie and is not in the cache key, so the ` +
+        `first caller's theme would be served to later callers. Read it ` +
+        `before the cached function and pass it in as an argument.`,
+    );
+  }
+  if (scope === "cache()") {
+    throw new Error(
+      `${surface} cannot be read inside a cache() boundary. The theme comes ` +
+        `from the visitor's cookie, so the first visitor's theme would be ` +
+        `stored in the shared entry and served to everyone. ${THEME_READ_FIX}`,
+    );
+  }
+  if (tripShellCaptureGuard(ctx, surface, THEME_READ_FIX)) {
+    throw new Error(
+      `${surface} cannot be read while capturing a shared shell (ppr shell ` +
+        `capture). The captured shell is served to every visitor of this URL, ` +
+        `so the capturing visitor's theme would reach everyone. ${THEME_READ_FIX}`,
     );
   }
+  // An identity read like a cookies() read method: a loader cache() fill with
+  // no key() refuses an execution that made one (#972).
+  recordLoaderIdentityRead(surface, "read");
 }
 
 const HEADERS_MUTATION_METHODS = new Set(["set", "append", "delete"]);
+// Reading one records the read (#972), like the cookies() read methods: a
+// headers() view taken outside a loader and read inside one still counts.
+const HEADERS_READ_PROPS = new Set<string | symbol>([
+  "get",
+  "has",
+  "entries",
+  "keys",
+  "values",
+  "forEach",
+  "getSetCookie",
+  Symbol.iterator,
+]);
 
 /**
  * Get the original request headers (read-only).
@@ -226,6 +248,7 @@ export function headers(): ReadonlyHeaders {
   assertNotInsideShellCapture(ctx, "headers");
   return new Proxy(ctx.request.headers, {
     get(target, prop, receiver) {
+      if (HEADERS_READ_PROPS.has(prop)) recordLoaderIdentityRead("headers()");
       if (typeof prop === "string" && HEADERS_MUTATION_METHODS.has(prop)) {
         return () => {
           throw new Error(
@@ -306,11 +329,13 @@ function createCookieStore(ctx: {
 }): CookieStore {
   return {
     get(name: string): Cookie | undefined {
+      recordLoaderIdentityRead("cookies()");
       const value = ctx.cookie(name);
       return value !== undefined ? { name, value } : undefined;
     },
 
     getAll(name?: string): Cookie[] {
+      recordLoaderIdentityRead("cookies()");
       const all = ctx.cookies();
       if (name !== undefined) {
         const value = all[name];
@@ -320,6 +345,7 @@ function createCookieStore(ctx: {
     },
 
     has(name: string): boolean {
+      recordLoaderIdentityRead("cookies()");
       return ctx.cookie(name) !== undefined;
     },