@rangojs/router 0.17.0 → 0.19.0

package/src/server/request-context.ts

@@ -17,6 +17,7 @@ import type { CookieOptions } from "../router/middleware.js";
 import {
   KEEP_CACHE_HEADER,
   getRawCookieValue,
+  freshReadsCookieName,
   mintStateValue,
   serializeStateCookie,
 } from "../browser/cookie-name.js";
@@ -48,7 +49,7 @@ import { getFetchableLoader } from "./fetchable-loader-store.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
 import type { ExecutionContext, RequestScope } from "../types/request-scope.js";
-import type { TransitionWhenFn } from "../types/segments.js";
+import type { TransitionWhenRecord } from "../router/transition-when.js";
 import type { ResolvedTracing } from "../router/tracing.js";
 import type { RenderMode, RenderPhase } from "../router/timeout.js";
 import {
@@ -64,6 +65,12 @@ import {
   assertNonCacheableReadAllowed,
   clearPprHeaderScope,
 } from "./context.js";
+import {
+  guardRawCookieRead,
+  guardRequestHeaders,
+  readGuardedTheme,
+} from "./cookie-store.js";
+import { requestHeaders } from "./request-headers.js";
 import {
   createReverseFunction,
   stripInternalParams,
@@ -74,6 +81,10 @@ import {
   getSearchSchema,
 } from "../route-map-builder.js";
 import { parseSearchParams } from "../search-params.js";
+import {
+  executionStart,
+  type ExecutionStart,
+} from "../cache/invalidation-order.js";
 import { invariant } from "../errors.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 
@@ -144,10 +155,24 @@ export interface RequestContext<
   /** @internal Request-local PPR opt-out marker set by ctx.dynamic(). */
   _dynamic?: boolean;
 
-  /** @internal Get a cookie value (effective: request + response mutations). Use cookies().get() instead. */
+  /**
+   * @internal Get a cookie value (effective: request + response mutations).
+   * Use cookies().get() instead. Guarded like cookies() (#976).
+   */
   cookie(name: string): string | undefined;
-  /** @internal Get all cookies (effective merged view). Use cookies().getAll() instead. */
+  /**
+   * @internal Get all cookies (effective merged view). Use
+   * cookies().getAll() instead. Guarded like cookies() (#976).
+   */
   cookies(): Record<string, string>;
+  /**
+   * @internal `cookie()` without the identity guard: the read behind the
+   * cookies() store, which guards at its own call and records per read
+   * method. Non-enumerable, like `_readTheme`.
+   */
+  _readCookie(name: string): string | undefined;
+  /** @internal `cookies()` without the identity guard (see `_readCookie`). */
+  _readCookies(): Record<string, string>;
   /** @internal Set a cookie on the response. Use cookies().set() instead. */
   setCookie(name: string, value: string, options?: CookieOptions): void;
   /** @internal Delete a cookie. Use cookies().delete() instead. */
@@ -165,6 +190,39 @@ export interface RequestContext<
   _rotateStateCookie(): void;
   /** @internal Set the keepClientCache() directive header on the response. */
   _setKeepCacheDirective(): void;
+  /**
+   * @internal This request carries the fresh-reads cookie: it follows an
+   * updateTag()/revalidateTag() by the same user, so the stores read tag
+   * markers and shells from the store, not from an isolate memo.
+   */
+  _freshReads?: boolean;
+  /**
+   * @internal Set the fresh-reads cookie on this response for `maxAgeMs`
+   * (rounded up to whole seconds; the longest stays). Called by
+   * updateTag()/revalidateTag().
+   */
+  _setFreshReadsCookie(maxAgeMs: number): void;
+  /**
+   * @internal The context createRequestContext() returned. A context derived
+   * from it with Object.create (a PPR HIT tail, a shell capture, a background
+   * revalidation render) inherits it, so per-request invalidation state (the
+   * stores' masks) is keyed by the request, not by whichever derived object
+   * called or read (#973).
+   */
+  _requestRoot?: RequestContext<any, any>;
+  /**
+   * @internal Where the request started in the isolate's invalidation order
+   * (cache/invalidation-order.ts), taken when createRequestContext() ran. The
+   * document cache gates its write on it (#977): a middleware ahead of the
+   * document cache can read tagged data the document bakes.
+   */
+  _requestStart?: ExecutionStart;
+  /**
+   * @internal The handler has handed the response to the host (rsc/handler.ts
+   * `rango.response`): header and cookie writes after this are lost, as from
+   * a streaming loader or render.
+   */
+  _responseSent?: boolean;
 
   /**
    * Access loader data or push handle data.
@@ -206,16 +264,13 @@ export interface RequestContext<
   readonly _handleStore: HandleStore;
 
   /**
-   * @internal transition({ when }) predicates for segments matched this request,
-   * keyed by segment id. Collected during resolution (the function is stripped
-   * from the serialized segment config), then evaluated post-handler in
-   * rsc-rendering — outside any cache scope — to drop the transition of any
-   * segment whose predicate returns false.
+   * @internal transition({ when }) client references of the matched entry
+   * chain, keyed by segment id. Recorded at match time from the static route
+   * definition (router/transition-when.ts) and attached to the payload's
+   * segments right before Flight (rsc/attach-transition-when.ts). The server
+   * never calls them, and no cache or snapshot stores them.
    */
-  _transitionWhen?: Array<{ id: string; when: TransitionWhenFn }>;
-
-  /** @internal PPR transition decisions evaluated before cache lookup/handlers. */
-  _pprTransitionDecisions?: Map<string, boolean>;
+  _transitionWhenRefs?: ReadonlyMap<string, TransitionWhenRecord>;
 
   /**
    * @internal Post-match serve-source truth for the PPR replay reporter.
@@ -243,8 +298,8 @@ export interface RequestContext<
    * capture task's derived request context (built by shell-capture.ts). This is
    * the switch every capture-specific behavior reads: loader masking
    * (loader-mask.ts isShellCaptureActive / fresh.ts emitStreaming) and the
-   * cookies()/headers() capture guard (cookie-store.ts
-   * assertNotInsideShellCapture). The foreground render never sets it, so the
+   * identity-read capture guard (server/context.ts guardIdentityRead). The
+   * foreground render never sets it, so the
    * served response is byte-identical to axis 1. The capture descriptor itself
    * (key/ttl/swr/tags/store) is NOT threaded through the request context — the
    * integrated PPR serve path (rsc/shell-serve.ts + rsc-rendering.ts) builds it
@@ -264,6 +319,59 @@ export interface RequestContext<
    */
   _shellCaptureLoaderRecords?: Map<string, Promise<unknown>>;
 
+  /**
+   * @internal Set on a capture's derived context when a loader pushed a
+   * value the record cannot keep (a deferred push, masked nested promises,
+   * or a push outside a loader body): the loader records then carry
+   * `runs: 1`, so a HIT still runs their bodies for those pushes.
+   */
+  _shellCaptureUnrecordedLoaderPush?: true;
+
+  /**
+   * @internal The lane of each loader the capture's matched route registers
+   * (loader-cache.ts routeLoaderLanes), set by createMatchContextForFull
+   * before any loader runs. The capture's push funnel credits a push made
+   * under a live-lane loader's body, at any depth, to that loader
+   * (shell-capture.ts deriveShellCaptureContext). Own property of the
+   * capture's derived context only.
+   */
+  _shellCaptureLoaderLanes?: ReadonlyMap<string, "live" | "bake">;
+
+  /**
+   * @internal Record keys resolved for this request (CacheScope
+   * resolveKeyFrom): by the scope's `key()` (one result) or its store's
+   * keyGenerator (one per default key). A shell capture's derived context
+   * reads it through the prototype chain, so the capture reuses the
+   * partition its request resolved instead of running `key()` again.
+   */
+  _resolvedCacheKeys?: Map<unknown, Map<string, Promise<string>>>;
+
+  /**
+   * @internal The shell store key the PPR serve path resolved for this
+   * document request (rsc-rendering.ts shellServePlan), request partition
+   * included. Read by the testing helper serveShellRequest.
+   */
+  _shellKey?: string;
+
+  /**
+   * @internal The request carried the forced-MISS reload marker
+   * (shell-serve.ts SHELL_MISS_PARAM). The handler strips the marker from the
+   * request on entry and sets this; the shell gate renders the request like a
+   * cache miss.
+   */
+  _shellForcedMiss?: true;
+
+  /**
+   * @internal The freshness window of the route cache() records this
+   * request read or wrote (cache-scope.ts noteRouteRecordWindow), as ms
+   * timestamps: `freshUntil` is the record's `expiresAt`, `staleUntil` adds
+   * its scope's swr. The narrowest record wins. A shell capture caps its
+   * entry's ttl and ttl+swr to it (shell-capture.ts capShellWindow), so a
+   * shell is never fresher, or served longer, than the route cache() entry
+   * it replayed or wrote.
+   */
+  _routeRecordWindow?: RouteRecordWindow;
+
   /**
    * @internal Loader-family snapshot seed for a shell HIT's tail render:
    * segment-key -> the capture's elided container (already Flight-deserialized
@@ -271,8 +379,10 @@ export interface RequestContext<
    * overlays it onto the fresh run's container (recorded paths pinned,
    * hole-marker paths keep the fresh nested promises) so the payload's baked
    * bytes match the frozen prelude; a hole-free entry resolves pin-first
-   * without gating on the fresh run. Own property of the HIT tail's derived
-   * context only.
+   * and does not run the loader. Two owners: serveShellHit sets it on the
+   * HIT tail's derived context, and matchPartialWithPprReplay sets it on the
+   * request context of a PPR partial replay once its doc record hits, and
+   * restores the previous value after the match.
    */
   _shellLoaderSeed?: Map<
     string,
@@ -280,16 +390,17 @@ export interface RequestContext<
   >;
 
   /**
-   * @internal Shell fast-path marker: makes the next eligible match treat the
-   * whole matched route as an implicit doc-level cache() boundary (see
+   * @internal The doc record marker: makes the next match treat the whole
+   * matched route as an implicit doc-level cache() boundary (see
    * resolveShellImplicitCacheScope in cache/cache-scope.ts). Set ONLY on
    * (a) the capture's derived context — with a record-only store so the
    * capture's cacheRoute write lands in the snapshot, never the real store —
-   * (b) a HIT tail's seeded context, and (c) an eligible normal-route partial
-   * replay, where `store` is a request-local segment overlay. Handler-live holes
-   * and conditional transitions decline replay.
-   * Routes with their own cache() config are never overridden — their scope's
-   * store/key/ttl/swr/condition semantics stay authoritative. On the
+   * (b) a document HIT tail's seeded context (`docTail`), and (c) an eligible
+   * normal-route partial replay, where `store` is a request-local segment
+   * overlay.
+   * A document HIT tail replays the record even for a route with its own
+   * cache() config (the gate before the commit already evaluated that
+   * scope's opt-outs). Elsewhere the route's scope stays authoritative. On the
    * navigation-replay serve path (`onExplicitHit` set) the marker COMPOSES with
    * such a scope instead of being ignored: the seeded doc record supplies the match
    * only when the explicit tier misses (withCacheLookup). cache(false) and a
@@ -306,12 +417,17 @@ export interface RequestContext<
      * segment record even when the triggering request is partial.
      */
     keyPrefix?: "doc";
-    /** @internal Called only after the implicit cache hit decodes successfully. */
-    onHit?: () => void;
+    /**
+     * @internal Called only after the implicit cache hit decodes
+     * successfully; the lookup awaits it before returning the hit, so work
+     * it starts lands before the route's loaders resolve.
+     */
+    onHit?: () => void | Promise<void>;
     /**
      * @internal Called when the seeded document record fails server-side
      * deserialization. Partial replay uses it to replace the enclosing shell
-     * snapshot after serving the fresh fallback.
+     * snapshot after serving the fresh fallback. A document HIT tail does not
+     * set it: withCacheLookup throws ShellRecordUnavailableError instead.
      */
     onCorrupt?: () => void;
     /**
@@ -322,6 +438,23 @@ export interface RequestContext<
      * require the exact consumable record instead of "any segment record".
      */
     docKey?: string;
+    /**
+     * @internal Set on a document HIT tail (serveShellHit). The implicit doc
+     * scope replaces any route-derived cache() scope for the tail's match
+     * (resolveShellImplicitCacheScope), and a lookup that does not hit throws
+     * ShellRecordUnavailableError instead of resolving segments
+     * (withCacheLookup): a HIT never runs a handler. The record's
+     * loader-owned handle pushes restore as authoritative
+     * (HandleStore.pushRestored): the prelude rendered them.
+     */
+    docTail?: true;
+    /**
+     * @internal The key a document HIT tail looks the doc record up by: the
+     * entry's own `docKey`. Recomputing it could name another key (a store
+     * keyGenerator folding request data, a build-time capture's synthetic
+     * host) and miss the record.
+     */
+    fixedDocKey?: string;
     /**
      * @internal Set ONLY by matchPartialWithPprReplay on the navigation-replay
      * serve path. Its presence arms the explicit-scope composition in
@@ -365,31 +498,17 @@ export interface RequestContext<
   _shellFragmentPayload?: boolean;
 
   /**
-   * @internal Handler-layer liveness observed DURING a shell capture, from
-   * three sources: (a) the capture handle-store push wrapper (shell-capture.ts)
-   * when a push made OUTSIDE a DSL loader scope carries a nested thenable
-   * (masked to a never-filling hole); (b) still-pending top-level handler
-   * pushes (liveness unknowable at the barrier); (c) a handler-invoked loader
-   * executing during the capture (loader-resolution.ts — its consumption-lane
-   * value would freeze on a handler-free HIT). captureAndStoreShell folds it
-   * into ShellCacheEntry.handlerLiveHoles at the putShell barrier. Own
-   * property of the capture's derived context only.
-   */
-  _shellCaptureHandleLiveness?: {
-    holes: boolean;
-    pendingPushes: number;
-    handlerInvokedLoader: boolean;
-  };
-
-  /**
-   * @internal Set (to the offending fn name) by the cookies()/headers()
-   * capture guard when it throws DURING a capture render. Load-bearing for the
+   * @internal Set by the capture guard (server/context.ts
+   * guardIdentityRead) when it throws DURING a capture render: the read
+   * ("cookies()", "headers()", `ctx.get() for a non-cacheable variable`,
+   * "ctx.theme") and the fix the
+   * refusal warning gives for it. Load-bearing for the
    * bake lane: a guard throw inside an executing loader is swallowed by
    * wrapLoaderPromise into per-loader error UI, which would otherwise bake
    * silently into the shared shell — the capture checks this flag after the
    * render and refuses instead. Deterministic, so the capture does not retry.
    */
-  _shellCaptureGuardTripped?: string;
+  _shellCaptureGuardTripped?: { surface: string; fix: string };
 
   /**
    * @internal The loader $$id whose BODY was executing when the capture guard
@@ -420,6 +539,23 @@ export interface RequestContext<
    */
   _requestTags: Set<string>;
 
+  /**
+   * @internal This request can write a route cache() record: its match
+   * resolved a cache scope (match-api.ts). Arms the record tag owners
+   * (cache-tag.ts armRecordTagOwners); off, the segment scopes, loader links
+   * and owned tag sets are skipped entirely. A capture's or background
+   * re-render's derived context (Object.create) inherits it.
+   */
+  _recordTagOwners?: true;
+
+  /**
+   * @internal This request resolves a loader bound with its own cache()
+   * (match-api.ts, or the binding's funnel). Arms the per-execution loader
+   * tag sets (cache-tag.ts armLoaderTagSets); off, a loader execution
+   * allocates no set and a read links nothing. Derived contexts inherit it.
+   */
+  _recordLoaderTags?: true;
+
   /** @internal Cache profiles for "use cache" profile resolution (per-router) */
   _cacheProfiles?: Record<
     string,
@@ -467,6 +603,11 @@ export interface RequestContext<
    * Returns the theme value from the cookie, or the default theme if not set.
    * This is the user's preference ("light", "dark", or "system"), not the resolved value.
    *
+   * The visitor's cookie, so it is guarded like `cookies()`: reading it
+   * refuses a ppr shell capture and throws inside a `cache()` boundary or a
+   * `"use cache"` function (#971). A non-enumerable getter: a spread or
+   * `Object.assign` copy of the context does not carry it.
+   *
    * @example
    * ```typescript
    * route("settings", (ctx) => {
@@ -475,7 +616,7 @@ export interface RequestContext<
    * });
    * ```
    */
-  theme?: Theme;
+  readonly theme?: Theme;
 
   /**
    * Set the theme (only available when theme is enabled in router config)
@@ -499,6 +640,30 @@ export interface RequestContext<
   /** @internal Theme configuration (null if theme not enabled) */
   _themeConfig?: ResolvedThemeConfig | null;
 
+  /**
+   * @internal The theme cookie (or the default) read with no identity guard.
+   * The guarded reads (`theme` here, the handler and middleware `ctx.theme`)
+   * call it after guardIdentityRead (readGuardedTheme); the router's own payload read goes
+   * through payloadInitialTheme (rsc/full-payload.ts), except the unmatched
+   * route's 404 (rsc/handler.ts), which is never stored. Undefined without
+   * theme config.
+   */
+  _readTheme(): Theme | undefined;
+
+  /**
+   * @internal Set by the document-cache middleware (cache/document-cache.ts)
+   * before it runs a render whose response it may store: the MISS and the
+   * stale refresh. payloadInitialTheme reads it (#978).
+   */
+  _documentCacheRender?: boolean;
+
+  /**
+   * @internal Set by payloadInitialTheme when the document payload carries
+   * the visitor's theme and it differs from the no-cookie default. The
+   * document cache does not store that response (#978).
+   */
+  _payloadVisitorTheme?: boolean;
+
   /**
    * Attach location state entries to the current response.
    *
@@ -542,20 +707,6 @@ export interface RequestContext<
   /** @internal Previous route key (from the navigation source), used for revalidation */
   _prevRouteKey?: string;
 
-  /**
-   * @internal Navigation/action source data the transition({ when }) gate reads
-   * to build its ShouldRevalidateFn-shaped predicate context. currentUrl/Params
-   * come from the navigation snapshot (set at match time); action* are stashed
-   * at the action-bearing gate call sites. All undefined when there is no source
-   * (initial full load) or no action (plain navigation).
-   */
-  _gateCurrentUrl?: URL;
-  _gateCurrentParams?: Record<string, string>;
-  _gateActionId?: string;
-  _gateActionUrl?: URL;
-  _gateActionResult?: unknown;
-  _gateFormData?: FormData;
-
   /**
    * @internal True while the post-action revalidation render is running (set by
    * revalidateAfterAction). The "use cache" runtime reads this to prefer
@@ -726,6 +877,21 @@ export interface RequestContext<
   _cacheSignal?: import("../router/telemetry.js").CacheSegmentSignal[];
 }
 
+/**
+ * @internal The freshness window of a route cache() record, as ms
+ * timestamps: fresh until `freshUntil` (its `expiresAt`), stale until
+ * `staleUntil` (plus its scope's swr). `ttl`, `swr` and `written` describe
+ * the record that sets `staleUntil`: its cache() config, and whether this
+ * request wrote it (cacheRoute) rather than read it.
+ */
+export interface RouteRecordWindow {
+  freshUntil: number;
+  staleUntil: number;
+  ttl: number;
+  swr: number;
+  written: boolean;
+}
+
 /**
  * Public view of RequestContext, without internal methods and fields.
  *
@@ -739,11 +905,12 @@ export type PublicRequestContext<
   RequestContext<TEnv, TParams>,
   | "cookie"
   | "cookies"
+  | "_readCookie"
+  | "_readCookies"
   | "setCookie"
   | "deleteCookie"
   | "_handleStore"
-  | "_transitionWhen"
-  | "_pprTransitionDecisions"
+  | "_transitionWhenRefs"
   | "_pprReplayPostMatchReason"
   | "_cacheStore"
   | "_searchParamsFilter"
@@ -751,25 +918,29 @@ export type PublicRequestContext<
   | "_shellImplicitCache"
   | "_shellLoaderSeed"
   | "_shellCaptureLoaderRecords"
-  | "_shellCaptureHandleLiveness"
+  | "_shellCaptureUnrecordedLoaderPush"
+  | "_shellCaptureLoaderLanes"
+  | "_resolvedCacheKeys"
+  | "_shellKey"
+  | "_shellForcedMiss"
+  | "_routeRecordWindow"
   | "_shellFragmentPayload"
   | "_shellCaptureGuardTripped"
   | "_shellCaptureGuardTrippedLoaderId"
   | "_explicitTaggedStores"
   | "_requestTags"
+  | "_recordTagOwners"
+  | "_recordLoaderTags"
   | "_cacheProfiles"
   | "_onResponseCallbacks"
   | "_pendingBackgroundTasks"
   | "_themeConfig"
+  | "_readTheme"
+  | "_documentCacheRender"
+  | "_payloadVisitorTheme"
   | "_locationState"
   | "_routeName"
   | "_prevRouteKey"
-  | "_gateCurrentUrl"
-  | "_gateCurrentParams"
-  | "_gateActionId"
-  | "_gateActionUrl"
-  | "_gateActionResult"
-  | "_gateFormData"
   | "_inActionRevalidation"
   | "_reportedErrors"
   | "_renderErrors"
@@ -795,6 +966,11 @@ export type PublicRequestContext<
   | "_setStatus"
   | "_rotateStateCookie"
   | "_setKeepCacheDirective"
+  | "_freshReads"
+  | "_setFreshReadsCookie"
+  | "_requestRoot"
+  | "_requestStart"
+  | "_responseSent"
   | "_variables"
   | "_classifiedRoute"
   | "_requestMode"
@@ -897,17 +1073,10 @@ export function setRequestContextParams(
  */
 export function setRequestContextPrevRouteKey(
   prevRouteKey: string | undefined,
-  currentUrl?: URL,
-  currentParams?: Record<string, string>,
 ): void {
   const ctx = requestContextStorage.getStore();
   if (!ctx) return;
   if (prevRouteKey !== undefined) ctx._prevRouteKey = prevRouteKey;
-  // Source URL/params for the transition({ when }) gate (effectiveFromUrl /
-  // effectiveFromMatch.params from the navigation snapshot). Same write point as
-  // _prevRouteKey, which doubles as fromRouteName.
-  if (currentUrl !== undefined) ctx._gateCurrentUrl = currentUrl;
-  if (currentParams !== undefined) ctx._gateCurrentParams = currentParams;
 }
 
 /**
@@ -989,8 +1158,15 @@ export function createRequestContext<TEnv>(
     stateCookieName,
     version: stateVersion,
   } = options;
-  const cookieHeader = request.headers.get("Cookie");
+  // ctx.request.headers is guarded like headers() (#976); every router read
+  // of this request's headers goes through requestHeaders().
+  guardRequestHeaders(request);
+  const cookieHeader = requestHeaders(request).get("Cookie");
   let rangoStateRotated = false;
+  const freshCookie = stateCookieName
+    ? freshReadsCookieName(stateCookieName)
+    : undefined;
+  let freshCookieMaxAge = 0;
   let parsedCookies: Record<string, string> | null = null;
 
   let stubResponse = initialResponse
@@ -1084,6 +1260,26 @@ export function createRequestContext<TEnv>(
     return getParsedCookies()[name];
   };
 
+  // The effective jar: request cookies minus deletions plus same-request writes.
+  const effectiveCookies = (): Record<string, string> => {
+    const parsed = getParsedCookies();
+    const mutations = getResponseCookies();
+    if (mutations.size === 0) return { ...parsed };
+    // Build result without delete (avoids V8 dictionary-mode de-opt)
+    const deleted = new Set<string>();
+    for (const [k, v] of mutations) {
+      if (v === null) deleted.add(k);
+    }
+    const result: Record<string, string> = {};
+    for (const key of Object.keys(parsed)) {
+      if (!deleted.has(key)) result[key] = parsed[key];
+    }
+    for (const [k, v] of mutations) {
+      if (v !== null) result[k] = v;
+    }
+    return result;
+  };
+
   const getTheme = (): Theme | undefined => {
     if (!themeConfig) return undefined;
 
@@ -1144,7 +1340,7 @@ export function createRequestContext<TEnv>(
     _dynamic: false,
     get: ((keyOrVar: any) => {
       if (isNonCacheable(variables, keyOrVar)) {
-        assertNonCacheableReadAllowed(keyOrVar);
+        assertNonCacheableReadAllowed(keyOrVar, _getRequestContext());
       }
       return contextGet(variables, keyOrVar);
     }) as RequestContext<TEnv>["get"],
@@ -1163,29 +1359,23 @@ export function createRequestContext<TEnv>(
       );
     },
 
+    // The visitor's cookies, guarded like cookies() (#976): before, a plain
+    // read that a ppr shell, a cache() entry or a "use cache" entry stored
+    // for every visitor.
     cookie(name: string): string | undefined {
+      guardRawCookieRead(ctx, "getRequestContext().cookie()");
       return effectiveCookie(name);
     },
 
     cookies(): Record<string, string> {
-      const parsed = getParsedCookies();
-      const mutations = getResponseCookies();
-      if (mutations.size === 0) return { ...parsed };
-      // Build result without delete (avoids V8 dictionary-mode de-opt)
-      const deleted = new Set<string>();
-      for (const [k, v] of mutations) {
-        if (v === null) deleted.add(k);
-      }
-      const result: Record<string, string> = {};
-      for (const key of Object.keys(parsed)) {
-        if (!deleted.has(key)) result[key] = parsed[key];
-      }
-      for (const [k, v] of mutations) {
-        if (v !== null) result[k] = v;
-      }
-      return result;
+      guardRawCookieRead(ctx, "getRequestContext().cookies()");
+      return effectiveCookies();
     },
 
+    // Non-enumerable, defined after this literal.
+    _readCookie: effectiveCookie,
+    _readCookies: effectiveCookies,
+
     setCookie(name: string, value: string, options?: CookieOptions): void {
       assertNotInsideCacheExec(ctx, "setCookie");
       stubResponse.headers.append(
@@ -1234,7 +1424,7 @@ export function createRequestContext<TEnv>(
       // decodeStateValue decodes exactly once) AND is the same parser the client
       // mirror uses, so both seats read the same jar entry.
       const prevRaw =
-        (request.headers.get("x-rango-state") || null) ??
+        (requestHeaders(request).get("x-rango-state") || null) ??
         getRawCookieValue(cookieHeader, stateCookieName);
       const value = mintStateValue(stateVersion ?? "0", prevRaw);
       // rawStubHeaders: guard-exempt internal writer — invalidateClientCache()
@@ -1254,6 +1444,48 @@ export function createRequestContext<TEnv>(
       rawStubHeaders.set(KEEP_CACHE_HEADER, "1");
     },
 
+    // The fresh-reads cookie (browser/cookie-name.ts): one Set-Cookie per
+    // response, the longest Max-Age any invalidation asked for. HttpOnly (the
+    // client never reads it), SameSite=Lax, Path=/. rawStubHeaders: an
+    // internal writer, allowed wherever updateTag()/revalidateTag() are. A
+    // shared cache never stores it (Set-Cookie is a per-client signal).
+    _setFreshReadsCookie(maxAgeMs: number): void {
+      if (!freshCookie) return;
+      const maxAge = Math.ceil(maxAgeMs / 1000);
+      // Already set for at least this long (an earlier invalidation in this
+      // request): nothing to add, sent or not.
+      if (maxAge <= freshCookieMaxAge) return;
+      if (ctx._responseSent) {
+        // A streaming loader or render: the headers already left. The
+        // invalidation itself still ran; only the mutating user's bypass of
+        // the stores' isolate memos is lost.
+        if (process.env.NODE_ENV !== "production") {
+          console.warn(
+            `[rango] updateTag()/revalidateTag() ran after the response ` +
+              `headers were sent (from a streaming loader or render), so the ` +
+              `${freshCookie} cookie was not set: this user's next requests ` +
+              `can be served from a store's isolate memo for a few seconds. ` +
+              `Invalidate in a server action, a route handler, or middleware.`,
+          );
+        }
+        return;
+      }
+      const serialized = (age: number) =>
+        `${freshCookie}=1; Max-Age=${age}; Path=/; HttpOnly; SameSite=Lax` +
+        (url.protocol === "https:" ? "; Secure" : "");
+      if (freshCookieMaxAge > 0) {
+        const prior = serialized(freshCookieMaxAge);
+        const kept = rawStubHeaders
+          .getSetCookie()
+          .filter((cookie) => cookie !== prior);
+        rawStubHeaders.delete("Set-Cookie");
+        for (const cookie of kept) rawStubHeaders.append("Set-Cookie", cookie);
+      }
+      freshCookieMaxAge = maxAge;
+      rawStubHeaders.append("Set-Cookie", serialized(maxAge));
+      invalidateResponseCookieCache();
+    },
+
     setStatus(status: number): void {
       assertNotInsideCacheExec(ctx, "setStatus");
       assertResponseWriteAllowed("setStatus");
@@ -1269,12 +1501,14 @@ export function createRequestContext<TEnv>(
     method: request.method,
 
     _handleStore: handleStore,
-    _transitionWhen: [],
     _cacheStore: cacheStore,
     _searchParamsFilter: searchParamsFilter,
     _explicitTaggedStores: explicitTaggedStores,
     _requestTags: new Set<string>(),
     _cacheProfiles: cacheProfiles,
+    _freshReads:
+      freshCookie !== undefined &&
+      getRawCookieValue(cookieHeader, freshCookie) !== null,
 
     waitUntil(fn: () => Promise<void>): void {
       if (ctx.build) return;
@@ -1316,9 +1550,8 @@ export function createRequestContext<TEnv>(
       this._onResponseCallbacks.push(callback);
     },
 
-    get theme() {
-      return themeConfig ? getTheme() : undefined;
-    },
+    // theme: a guarded, non-enumerable getter defined after this literal.
+    _readTheme: getTheme,
     setTheme: themeConfig
       ? (theme: Theme) => {
           assertNotInsideCacheExec(ctx, "setTheme");
@@ -1359,7 +1592,38 @@ export function createRequestContext<TEnv>(
     getContext: () => ctx,
   });
 
+  // getRequestContext().theme is the visitor's cookie, guarded like cookies()
+  // (#971); before it was a plain read that a ppr shell, a cache() entry or a
+  // "use cache" entry stored for every visitor. Non-enumerable like the
+  // handler ctx.theme (handler-context.ts THEME_DESCRIPTOR): serializing the
+  // context (React dev debug info) must not count as a read. The guard reads
+  // the ambient context, as cookies() does, and falls back to the receiver.
+  // _readTheme is the unguarded read: non-enumerable too, so a spread copy of
+  // the context (the fetchable-loader ctx, loader-fetch.ts) cannot carry it.
+  // The same holds for the unguarded cookie reads (#976).
+  Object.defineProperties(ctx, {
+    theme: {
+      get(this: RequestContext<TEnv>): Theme | undefined {
+        return readGuardedTheme(this, "getRequestContext().theme");
+      },
+      enumerable: false,
+      configurable: true,
+    },
+    _readTheme: { enumerable: false },
+    _readCookie: { enumerable: false },
+    _readCookies: { enumerable: false },
+  });
+
   (ctx as any)[NOCACHE_SYMBOL] = true;
+  // Non-enumerable: a self-reference would make the context circular for
+  // JSON.stringify, spreads and React's dev debug-info serialization of props.
+  Object.defineProperty(ctx, "_requestRoot", {
+    value: ctx,
+    enumerable: false,
+    configurable: true,
+    writable: true,
+  });
+  ctx._requestStart = executionStart();
   return ctx;
 }