@rangojs/router 0.17.0 → 0.19.0

package/src/rsc/full-payload.ts

@@ -13,7 +13,10 @@ import type { RscPayload } from "./types.js";
 import type { HandlerContext } from "./handler-context.js";
 import type { RequestContext } from "../server/request-context.js";
 import type { HandleStore } from "../server/handle-store.js";
-import { gateTransitions } from "./transition-gate.js";
+import type { Theme } from "../theme/types.js";
+import { documentCacheStoresRender } from "../cache/document-cache.js";
+import { attachTransitionWhen } from "./attach-transition-when.js";
+import { publicRouteName } from "../route-name.js";
 import { resolvedHandleStream } from "../handles/deferred-resolution.js";
 
 /**
@@ -38,11 +41,12 @@ export function buildFullPayload(
       pathname: url.pathname,
       routerId: ctx.router.id,
       basename: ctx.router.basename,
-      segments: gateTransitions(m.segments, reqCtx, ctx.router.onError),
+      segments: attachTransitionWhen(m.segments, reqCtx),
       matched: m.matched,
       diff: m.diff,
       resolvedIds: m.resolvedIds,
       params: m.params,
+      routeName: publicRouteName(m.routeName),
       isPartial: false,
       interceptTargets: m.interceptTargets,
       rootLayout: ctx.router.rootLayout,
@@ -71,7 +75,47 @@ export function buildFullPayload(
       // entry knows whether to wrap hydration in React.StrictMode. Partial
       // (navigation) payloads omit it by design; StrictMode is decided once.
       strictMode: ctx.router.strictMode,
-      initialTheme: reqCtx.theme,
+      initialTheme: payloadInitialTheme(reqCtx),
     },
   };
 }
+
+/**
+ * The theme a document payload carries as `metadata.initialTheme` (the
+ * ThemeProvider's first state), read with no identity guard: it is the
+ * router's own read, not handler code (#971).
+ *
+ * A render other visitors may be served carries the no-cookie default, not
+ * the rendering visitor's theme: a shell capture, and a render the document
+ * cache runs whose response opted in before next() (documentCacheStoresRender,
+ * #978). The shell, its ShellCacheEntry.initialTheme and the stored document
+ * serve every visitor, and ThemeProvider re-syncs only from an explicitly
+ * stored theme, so a visitor with none kept the first visitor's
+ * `useTheme().theme` for the page's lifetime. A visitor with a stored theme
+ * gets it pre-paint (theme script) and in the provider after mount.
+ *
+ * Any other render carries the visitor's theme (the unmatched-route 404 reads
+ * it without this function, rsc/handler.ts); when that differs from the
+ * default it marks `_payloadVisitorTheme`, and the document cache does not
+ * store the response.
+ */
+export function payloadInitialTheme(
+  reqCtx: Pick<
+    RequestContext<any>,
+    | "_themeConfig"
+    | "_shellCaptureRun"
+    | "_readTheme"
+    | "_documentCacheRender"
+    | "_payloadVisitorTheme"
+    | "res"
+  >,
+): Theme | undefined {
+  const config = reqCtx._themeConfig;
+  if (!config) return undefined;
+  if (reqCtx._shellCaptureRun || documentCacheStoresRender(reqCtx)) {
+    return config.defaultTheme;
+  }
+  const theme = reqCtx._readTheme();
+  if (theme !== config.defaultTheme) reqCtx._payloadVisitorTheme = true;
+  return theme;
+}

package/src/rsc/handler.ts

@@ -7,6 +7,7 @@
  * and progressive enhancement (no-JS form submissions).
  */
 
+import { requestHeaders } from "../server/request-headers.js";
 import { isRouteNotFoundError } from "../errors.js";
 import { matchMiddleware, executeMiddleware } from "../router/middleware.js";
 import {
@@ -85,6 +86,7 @@ import {
   ORIGIN_CHECK_PHASE_BY_MODE,
 } from "./origin-guard.js";
 import { handleRscRendering } from "./rsc-rendering.js";
+import { withoutShellMissMarker } from "./shell-serve.js";
 import {
   withTimeout,
   isTimeoutEnabled,
@@ -436,10 +438,16 @@ export function createRSCHandler<
   };
 
   return async function handler(
-    request: Request,
+    incomingRequest: Request,
     input: RouterRequestInput<TEnv> = {},
   ): Promise<Response> {
     const handlerStart = performance.now();
+    // A degraded PPR HIT's reload carries the forced-MISS marker: keep only
+    // the flag (set on the request context below) and drop the marker before
+    // anything reads the request, so middleware, handlers, loaders, cache
+    // keys and the SSR search seed see the URL the visitor asked for.
+    const unmarkedRequest = withoutShellMissMarker(incomingRequest);
+    const request = unmarkedRequest ?? incomingRequest;
     // Create the metrics store at handler start so handler:total has startTime=0
     // and all metrics are relative to the request entry point.
     const earlyMetricsStore = router.debugPerformance
@@ -566,6 +574,7 @@ export function createRSCHandler<
       stateCookieName: router.resolvedStateCookieName,
       version,
     });
+    if (unmarkedRequest) requestContext._shellForcedMiss = true;
     // Gate on the SAME enabled-semantics withTimeout uses (isTimeoutEnabled):
     // a `renderStartMs: 0` / negative opt-out disables the timeout, so the
     // driver's cursor bookkeeping (which only the timeout reads) must be off too.
@@ -662,6 +671,9 @@ export function createRSCHandler<
         // the host; it never reads or wraps response.body. A downstream throw
         // skips it entirely (no response exists to hand off).
         return observePhase(PHASES.response, (responseSpan) => {
+          // Header and cookie writes from here on (a streaming loader or
+          // render) no longer reach the response.
+          requestContext._responseSent = true;
           let response: Response;
           if (hasMiddleware) {
             if (
@@ -913,8 +925,10 @@ export function createRSCHandler<
         originPhase,
       );
       if (originResult) {
+        const origin = requestHeaders(request).get("origin");
+        const host = requestHeaders(request).get("host");
         const originError = new Error(
-          `Origin check rejected: ${request.headers.get("origin") ?? "none"} vs ${request.headers.get("host") ?? "none"}`,
+          `Origin check rejected: ${origin ?? "none"} vs ${host ?? "none"}`,
         );
         originError.name = "OriginCheckError";
 
@@ -923,11 +937,7 @@ export function createRSCHandler<
           url,
           env,
           handledByBoundary: false,
-          metadata: {
-            phase: originPhase,
-            origin: request.headers.get("origin"),
-            host: request.headers.get("host"),
-          },
+          metadata: { phase: originPhase, origin, host },
         });
 
         if (router.telemetry) {
@@ -938,8 +948,8 @@ export function createRSCHandler<
             method: request.method,
             pathname: url.pathname,
             phase: originPhase,
-            origin: request.headers.get("origin"),
-            host: request.headers.get("host"),
+            origin,
+            host,
           });
         }
 
@@ -1355,7 +1365,11 @@ export function createRSCHandler<
               themeConfig: router.themeConfig,
               warmupEnabled: router.warmupEnabled,
               strictMode: router.strictMode,
-              initialTheme: getRequestContext().theme,
+              // The visitor's theme, not payloadInitialTheme (full-payload.ts):
+              // that picks the default when middleware opted the URL into the
+              // document cache before next(), but a 404 is never stored or
+              // captured (#978).
+              initialTheme: getRequestContext()._readTheme(),
             },
           };
 

package/src/rsc/loader-fetch.ts

@@ -11,6 +11,7 @@
  * has already extracted params from it.
  */
 
+import { requestHeaders } from "../server/request-headers.js";
 import { getLoaderLazy } from "../server/loader-registry.js";
 import { isDataNotFoundError } from "../errors.js";
 import { executeLoaderMiddleware } from "../router/middleware.js";
@@ -144,7 +145,7 @@ export async function handleLoaderFetch<TEnv>(
 
   if (isBodyMethod) {
     try {
-      const contentType = request.headers.get("content-type") || "";
+      const contentType = requestHeaders(request).get("content-type") || "";
       if (contentType.includes("multipart/form-data")) {
         // FormData body — sent by load() when body is a FormData instance.
         // Preserves File objects and binary data.

package/src/rsc/manifest-init.ts

@@ -14,6 +14,7 @@ import {
   setRouterPrecomputedEntries,
 } from "../route-map-builder.js";
 import { mergeFullManifests } from "../build/merge-full-manifests.js";
+import { isTransitionWhenValidationEnabled } from "../transition-when-ref.js";
 
 /**
  * Build a fresh route trie from the router's URL-pattern mounts and store it in
@@ -49,6 +50,9 @@ export async function buildRouterTrieFromUrlpatterns(
       await generateManifestFull(mount.patterns, mount.mountIndex, {
         routerId: router.id,
         ...(router.basename ? { urlPrefix: router.basename } : {}),
+        // Under the Vite plugin the realm validates like discovery does, so
+        // a Cloudflare dev rebuild fails on an invalid when too.
+        validateTransitionWhen: isTransitionWhenValidationEnabled(),
       }),
     );
   }

package/src/rsc/origin-guard.ts

@@ -9,6 +9,7 @@
  * navigations, bookmarks, and non-browser clients don't send Origin.
  */
 
+import { requestHeaders } from "../server/request-headers.js";
 import type { RequestPlan } from "../router/request-classification.js";
 
 /**
@@ -69,10 +70,11 @@ export type OriginCheckConfig<TEnv = any> =
  * Returns true to allow, false to reject.
  */
 export function defaultOriginCheck(request: Request, url: URL): boolean {
-  let requestOrigin = request.headers.get("origin");
+  const headers = requestHeaders(request);
+  let requestOrigin = headers.get("origin");
 
   if (!requestOrigin) {
-    const referer = request.headers.get("referer");
+    const referer = headers.get("referer");
     if (referer) {
       try {
         requestOrigin = new URL(referer).origin;
@@ -92,7 +94,7 @@ export function defaultOriginCheck(request: Request, url: URL): boolean {
   // :authority), so a missing Host here is anomalous. Fail closed rather than
   // fall back to url.host (derived from the request line) when the trusted Host
   // cannot be established.
-  const expectedHost = request.headers.get("host");
+  const expectedHost = headers.get("host");
   if (!expectedHost) return false;
 
   const expectedOrigin = `${url.protocol}//${expectedHost}`;
@@ -102,11 +104,12 @@ export function defaultOriginCheck(request: Request, url: URL): boolean {
 
 function createForbiddenResponse(request: Request): Response {
   const isDev = process.env.NODE_ENV !== "production";
+  const headers = requestHeaders(request);
   const body = isDev
     ? "Forbidden: Origin mismatch. The request origin does not match the server host. " +
       `Set originCheck: false in createRouter() to disable this check. ` +
-      `(Origin: ${request.headers.get("origin") ?? "none"}, ` +
-      `Host: ${request.headers.get("host") ?? "none"})`
+      `(Origin: ${headers.get("origin") ?? "none"}, ` +
+      `Host: ${headers.get("host") ?? "none"})`
     : "Forbidden";
 
   return new Response(body, {

package/src/rsc/progressive-enhancement.ts

@@ -6,6 +6,7 @@
  * reference. We detect these and return HTML instead of RSC stream.
  */
 
+import { requestHeaders } from "../server/request-headers.js";
 import {
   getRequestContext,
   setRequestContextParams,
@@ -14,7 +15,8 @@ import { createSsrHtmlStage } from "./ssr-setup.js";
 import type { MiddlewareFn } from "../router/middleware.js";
 import { executeMiddleware } from "../router/middleware.js";
 import { observePhase, PHASES } from "../router/instrument.js";
-import { gateTransitions } from "./transition-gate.js";
+import { attachTransitionWhen } from "./attach-transition-when.js";
+import { payloadInitialTheme } from "./full-payload.js";
 import { resolvedHandleStream } from "../handles/deferred-resolution.js";
 import type { RscPayload, ReactFormState } from "./types.js";
 import {
@@ -63,7 +65,7 @@ export async function handleProgressiveEnhancement<TEnv>(
   nonce: string | undefined,
   routeMwInfo?: PeRouteMiddlewareInfo,
 ): Promise<Response | null> {
-  const contentType = request.headers.get("content-type") || "";
+  const contentType = requestHeaders(request).get("content-type") || "";
   const isFormSubmission =
     contentType.includes("multipart/form-data") ||
     contentType.includes("application/x-www-form-urlencoded");
@@ -311,7 +313,7 @@ async function handleProgressiveEnhancementInner<TEnv>(
     // custom headers) so loaders that read request headers/cookies behave
     // identically under PE and the JS action path. Drop body-framing headers
     // from the bodyless GET and force the HTML accept.
-    const headers = new Headers(request.headers);
+    const headers = new Headers(requestHeaders(request));
     headers.delete("content-type");
     headers.delete("content-length");
     headers.delete("content-encoding");
@@ -325,15 +327,9 @@ async function handleProgressiveEnhancementInner<TEnv>(
     // JS/PE parity: this is an action's revalidation render, so mark it BEFORE
     // matching — a stale `foregroundOnAction` cache entry must re-execute in the
     // foreground during the re-render, exactly as the JS path's
-    // revalidateAfterAction does. PPR transition({ when }) runs during match,
-    // while foregroundOnAction reads _inActionRevalidation there too, so all
-    // action metadata must be available before matching.
+    // revalidateAfterAction does.
     const peReqCtx = getRequestContext();
     peReqCtx._inActionRevalidation = true;
-    peReqCtx._gateActionId = directActionId ?? undefined;
-    peReqCtx._gateActionUrl = new URL(url);
-    peReqCtx._gateActionResult = actionResult;
-    peReqCtx._gateFormData = formData;
 
     return runRoutine(
       peRenderPlan({
@@ -426,11 +422,7 @@ function renderPeResponse<TEnv>(
       pathname: url.pathname,
       routerId: ctx.router.id,
       basename: ctx.router.basename,
-      segments: gateTransitions(
-        match.segments,
-        getRequestContext(),
-        ctx.router.onError,
-      ),
+      segments: attachTransitionWhen(match.segments, getRequestContext()),
       matched: match.matched,
       diff: match.diff,
       resolvedIds: match.resolvedIds,
@@ -444,7 +436,7 @@ function renderPeResponse<TEnv>(
       themeConfig: ctx.router.themeConfig,
       warmupEnabled: ctx.router.warmupEnabled,
       strictMode: ctx.router.strictMode,
-      initialTheme: getRequestContext().theme,
+      initialTheme: payloadInitialTheme(getRequestContext()),
     },
   };
 
@@ -602,16 +594,6 @@ async function matchPeErrorBoundary<TEnv>(
 
   setRequestContextParams(errorResult.params, errorResult.routeName);
 
-  // Only the failing action id + URL are in scope here (no formData/actionResult
-  // thread into this helper). Expose the URL only when the action id is known:
-  // this helper also handles malformed form bodies before action detection, and
-  // those should not look like action-triggered renders to transition({ when }).
-  if (actionId != null) {
-    const peErrCtx = getRequestContext();
-    peErrCtx._gateActionId = actionId;
-    peErrCtx._gateActionUrl = new URL(url);
-  }
-
   return errorResult;
 }
 
@@ -627,11 +609,7 @@ function renderPeErrorResponse<TEnv>(
       pathname: url.pathname,
       routerId: ctx.router.id,
       basename: ctx.router.basename,
-      segments: gateTransitions(
-        errorResult.segments,
-        getRequestContext(),
-        ctx.router.onError,
-      ),
+      segments: attachTransitionWhen(errorResult.segments, getRequestContext()),
       matched: errorResult.matched,
       diff: errorResult.diff,
       resolvedIds: errorResult.resolvedIds,
@@ -646,7 +624,7 @@ function renderPeErrorResponse<TEnv>(
       themeConfig: ctx.router.themeConfig,
       warmupEnabled: ctx.router.warmupEnabled,
       strictMode: ctx.router.strictMode,
-      initialTheme: getRequestContext().theme,
+      initialTheme: payloadInitialTheme(getRequestContext()),
     },
   };
 

package/src/rsc/response-cache-serve.ts

@@ -3,24 +3,27 @@
  *
  * Owns the single response-cache contract — cache-scope resolution from the
  * matched entry tree, condition eval, key resolution (route key() > store
- * keyGenerator > default), tag resolution, pre-handler-callback timing, and the
- * fresh-hit / SWR-revalidate / miss-write branches — for BOTH the production
+ * keyGenerator > default, CacheScope.resolveKeyFrom), tag resolution,
+ * pre-handler-callback timing, and the fresh-hit / SWR-revalidate /
+ * miss-write branches — for BOTH the production
  * response-route handler (rsc/response-route-handler.ts) and the dispatch testing
  * primitive (testing/dispatch.ts), so the two can never drift.
  *
  * Plugin-rsc hazard: cache-scope.ts pulls @vitejs/plugin-rsc (via segment-codec),
  * which the non-Vite unit-test runner cannot resolve, and this module is on the
- * testing barrel's EAGER graph (dispatch imports it). So `createCacheScope` and
- * `resolveCacheTags` are NOT imported here at runtime — they are INJECTED by the
- * caller (production imports them statically; dispatch lazy-imports them only once
- * a response route matches). The only runtime imports here are plugin-rsc-free
+ * testing barrel's EAGER graph (dispatch imports it). So `createCacheScope` is
+ * NOT imported here at runtime — it is INJECTED by the caller (production
+ * imports it statically; dispatch lazy-imports it only once a response route
+ * matches). The only runtime imports here are plugin-rsc-free
  * (helpers' isCacheableStatus/finalizeResponse, traverseBack); cache-scope is a
  * type-only import (erased at build).
  */
 
 import type { CacheScope } from "../cache/cache-scope.js";
-import type { PartialCacheOptions } from "../types.js";
-import type { RequestContext } from "../server/request-context.js";
+import {
+  _getRequestContext,
+  type RequestContext,
+} from "../server/request-context.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { EntryCacheConfig, EntryData } from "../server/context.js";
 import { traverseBack } from "../router/pattern-matching.js";
@@ -31,18 +34,19 @@ import {
 } from "./helpers.js";
 import { reportCacheError } from "../cache/cache-error.js";
 import { cacheKeyBase } from "../cache/cache-key-utils.js";
+import {
+  executionStart,
+  predatesInvalidation,
+  type ExecutionStart,
+} from "../cache/tag-invalidation.js";
 import { hasPerClientSignal } from "../browser/cookie-name.js";
 
-/** Injected cache-scope builders (kept off this module's runtime import graph). */
+/** Injected cache-scope builder (kept off this module's runtime import graph). */
 export interface CacheScopeDeps {
   createCacheScope: (
     config: EntryCacheConfig | undefined,
     parent?: CacheScope | null,
   ) => CacheScope | null;
-  resolveCacheTags: (
-    config: PartialCacheOptions | false,
-    ctx: RequestContext | undefined,
-  ) => string[] | undefined;
 }
 
 export interface ServeResponseRouteWithCacheArgs {
@@ -60,8 +64,12 @@ export interface ServeResponseRouteWithCacheArgs {
  * applies (no scope, disabled, condition false, or store lacks get/putResponse)
  * so the caller falls through to a plain `executeHandler()` run.
  *
- * Must run inside runWithRequestContext (reads the ambient request context via
- * the helpers and reqCtx.waitUntil for background writes).
+ * Must run inside runWithRequestContext for `reqCtx` (reads the ambient
+ * request context via the helpers and reqCtx.waitUntil for background writes).
+ * Outside it, the route runs uncached: the scope resolves `key()`, a store
+ * keyGenerator and `condition()` against the ambient context, and without
+ * it a keyGenerator was skipped and the entry landed on the broad default
+ * key.
  */
 export async function serveResponseRouteWithCache(
   args: ServeResponseRouteWithCacheArgs,
@@ -75,6 +83,7 @@ export async function serveResponseRouteWithCache(
   if (method !== "GET" && method !== "HEAD") {
     return undefined;
   }
+  if (_getRequestContext() !== reqCtx) return undefined;
 
   let cacheScope: CacheScope | null = null;
   for (const entry of traverseBack(manifestEntry)) {
@@ -83,20 +92,12 @@ export async function serveResponseRouteWithCache(
     }
   }
 
-  if (!cacheScope?.enabled) return undefined;
-
-  // Evaluate condition — skip the response cache when condition returns false.
-  let conditionPassed = true;
-  if (cacheScope.config !== false && cacheScope.config.condition) {
-    try {
-      conditionPassed = !!cacheScope.config.condition(reqCtx);
-    } catch {
-      conditionPassed = false;
-    }
-  }
+  // Skip the response cache when a condition() of the scope, or of any
+  // cache() enclosing it (#974), refuses this request.
+  if (!cacheScope?.allowsCache("read")) return undefined;
 
   const store = cacheScope.getStore() ?? reqCtx._cacheStore;
-  if (!conditionPassed || !store?.getResponse || !store?.putResponse) {
+  if (!store?.getResponse || !store?.putResponse) {
     return undefined;
   }
 
@@ -105,8 +106,12 @@ export async function serveResponseRouteWithCache(
   // the host-namespacing and search-normalization rules cannot drift.
   let cacheKey = `response:${responseType}:${cacheKeyBase(url.host, url.pathname, url.searchParams, undefined, reqCtx._searchParamsFilter)}`;
 
-  // Priority 1: route-level key() (full override). Priority 2: store-level
-  // keyGenerator (modifies the default key).
+  // Keyed like the segment record (CacheScope.resolveKeyFrom): with key()
+  // results on the cache() chain (a full override, namespaced, #975) or an
+  // enclosing scope on another store whose keyGenerator partitions (#974),
+  // `response:` plus the composed key, so a nested cache() never shares an
+  // entry across the enclosing partitions (#970); otherwise the store's
+  // keyGenerator result (it modifies the default key), else the default key.
   //
   // A CONFIGURED key()/keyGenerator that THROWS must DEGRADE TO A MISS, not fall
   // back to the broad default key. The default key is intentionally broad; if the
@@ -114,46 +119,27 @@ export async function serveResponseRouteWithCache(
   // would cache PERSONALIZED output under it and serve it cross-user (cache
   // poisoning). Mirrors the segment-cache behavior (cache-scope.ts lookupRoute):
   // a throwing key degrades to a cache miss, never a collision onto the default
-  // slot. The no-key default path is left untouched (the broad key is correct
-  // when no key is configured).
-  let keyResolutionFailed = false;
-  if (cacheScope.config !== false && cacheScope.config.key) {
-    try {
-      const customKey = await cacheScope.config.key(reqCtx);
-      cacheKey = `response:${customKey}`;
-    } catch (error) {
-      keyResolutionFailed = true;
-      reportCacheError(
-        error,
-        "cache-read",
-        "[ResponseCache] Key resolution failed",
-        reqCtx,
-      );
-    }
-  } else if (store.keyGenerator) {
-    try {
-      cacheKey = await store.keyGenerator(reqCtx, cacheKey);
-    } catch (error) {
-      keyResolutionFailed = true;
-      reportCacheError(
-        error,
-        "cache-read",
-        "[ResponseCache] keyGenerator failed",
-        reqCtx,
-      );
-    }
-  }
-
-  // Degrade to a MISS: return undefined so the caller runs the route UNCACHED.
-  // This early-returns BEFORE _onResponseCallbacks is saved/cleared below, so the
-  // pre-handler onResponse callbacks are still intact for the uncached run.
-  if (keyResolutionFailed) {
+  // slot, and so does a key() with no ambient request context to run in
+  // (resolveKeyFrom rejects).
+  try {
+    cacheKey = await cacheScope.resolveKeyFrom(cacheKey, "response:");
+  } catch (error) {
+    reportCacheError(
+      error,
+      "cache-read",
+      "[ResponseCache] Key resolution failed",
+      reqCtx,
+    );
+    // Degrade to a MISS: the caller runs the route UNCACHED. This returns
+    // BEFORE _onResponseCallbacks is saved/cleared below, so the pre-handler
+    // onResponse callbacks are still intact for the uncached run.
     return undefined;
   }
 
-  // Resolve cache tags for this document entry (static or dynamic) while the
-  // request context is available, so the stored entry is tag-invalidatable.
-  const responseTags = deps.resolveCacheTags(cacheScope.config, reqCtx);
+  // Resolve cache tags for this entry (static or dynamic, the enclosing
+  // scopes' included, #974) while the request context is available, so the
+  // stored entry is tag-invalidatable.
+  const responseTags = cacheScope.resolveTags(reqCtx);
 
   // Pre-handler callbacks (registered by app-level middleware before the cache
   // block) are saved and the live array is cleared:
@@ -180,17 +166,26 @@ export async function serveResponseRouteWithCache(
   const canServeCached = (response: Response): boolean =>
     isCacheableStatus(response.status) && !hasPerClientSignal(response.headers);
 
-  const putFresh = (
+  // A handler run that started before one of the entry's tags was
+  // invalidated is not written (#977, predatesInvalidation).
+  const putFresh = async (
     store2: SegmentCacheStore,
     fresh: Response,
-  ): Promise<void> =>
-    store2.putResponse!(
+    start: ExecutionStart,
+  ): Promise<void> => {
+    if (await predatesInvalidation(store2, responseTags, start)) {
+      // Nothing reads the copy now: release it (a tee branch buffers).
+      await fresh.body?.cancel();
+      return;
+    }
+    await store2.putResponse!(
       cacheKey,
-      fresh.clone(),
+      fresh,
       cacheScope!.ttl,
       cacheScope!.swr,
       responseTags,
     );
+  };
 
   try {
     const cached = await store.getResponse(cacheKey);
@@ -201,8 +196,9 @@ export async function serveResponseRouteWithCache(
       // Stale hit (SWR): return cached, revalidate in background.
       reqCtx.waitUntil(async () => {
         try {
+          const start = executionStart();
           const fresh = finalizeResponse(await executeHandler());
-          if (canStore(fresh)) await putFresh(store, fresh);
+          if (canStore(fresh)) await putFresh(store, fresh, start);
         } catch (error) {
           reportCacheError(
             error,
@@ -224,6 +220,7 @@ export async function serveResponseRouteWithCache(
   }
 
   // Cache miss: execute the handler and cache the result when storeable.
+  const start = executionStart();
   const response = finalizeResponse(await executeHandler());
   if (canStore(response)) {
     // Clone SYNCHRONOUSLY here, before returning. The original `response` is
@@ -238,13 +235,7 @@ export async function serveResponseRouteWithCache(
     const toCache = response.clone();
     reqCtx.waitUntil(async () => {
       try {
-        await store.putResponse!(
-          cacheKey,
-          toCache,
-          cacheScope!.ttl,
-          cacheScope!.swr,
-          responseTags,
-        );
+        await putFresh(store, toCache, start);
       } catch (error) {
         reportCacheError(
           error,

package/src/rsc/response-route-handler.ts

@@ -11,7 +11,7 @@ import { getRequestContext } from "../server/request-context.js";
 import { contextGet, isNonCacheable } from "../context-var.js";
 import { NOCACHE_SYMBOL } from "../cache/taint.js";
 import { RESPONSE_TYPE_MIME } from "../router/content-negotiation.js";
-import { createCacheScope, resolveCacheTags } from "../cache/cache-scope.js";
+import { createCacheScope } from "../cache/cache-scope.js";
 import { serveResponseRouteWithCache } from "./response-cache-serve.js";
 import { executeMiddleware } from "../router/middleware.js";
 import {
@@ -220,7 +220,7 @@ export async function handleResponseRoute<TEnv>(
       responseType: preview.responseType,
       url,
       executeHandler,
-      deps: { createCacheScope, resolveCacheTags },
+      deps: { createCacheScope },
     });
     if (cached !== undefined) return cached;
   }