@rangojs/router 0.23.0 → 0.24.0

package/src/browser/partial-update.ts

@@ -32,7 +32,7 @@ import {
   IS_BROWSER_DEBUG,
 } from "./logging.js";
 import { validatePayloadRedirect } from "./validate-redirect-origin.js";
-import type { NavigationUpdate, RscMetadata } from "./types.js";
+import type { HandleData, NavigationUpdate, RscMetadata } from "./types.js";
 import { OPTIMISTIC_COMMIT_TRANSITION_TYPE } from "./optimistic-commit.js";
 import type { LoaderStore } from "../loader-store.js";
 import { setActiveInterceptTargets } from "../client-urls/navigation.js";
@@ -200,9 +200,11 @@ export type UpdateMode =
        * when we send cached segment IDs to the server - if the server returns empty diff,
        * we use the same segments we told the server we have. */
       targetCacheSegments?: ResolvedSegment[];
-      /** Cached handle data for the target URL. When server returns empty diff and we're
-       * rendering from cache, this is passed to the UI to restore breadcrumbs etc. */
-      targetCacheHandleData?: Record<string, Record<string, unknown[]>>;
+      /** The handle state of `targetCacheSegments`: the entry's pushes, and
+       * the live pushes of the page on screen for each segment taken from it.
+       * Read at commit; the page starts from it and the response's handles,
+       * when it has any, merge onto it (NavigationProvider). */
+      targetCacheHandleData?: () => HandleData;
       /** Source URL for intercept restore (popstate cache miss) */
       interceptSourceUrl?: string;
       /**
@@ -643,6 +645,16 @@ export function createPartialUpdater(
         : undefined;
     const cachedSegs = targetCache ?? getCurrentCachedSegments();
     const cachedSegsSource = targetCache ? "history-cache" : "current-page";
+    // Rendered from the history cache, the page starts from the entry's
+    // pushes whether or not the response re-renders. Read before tx.commit():
+    // it records the controller's handle state (the document snapshot during
+    // the hydration window) in the entry it commits, which for a link to the
+    // page on screen's own URL is the entry this reads. Written over that
+    // record after it.
+    const readCachedHandleData =
+      targetCache && mode.type === "navigate"
+        ? mode.targetCacheHandleData
+        : undefined;
     if (IS_BROWSER_DEBUG) {
       debugLog(
         `[Browser] cachedSegs source: ${cachedSegsSource} (${cachedSegs.length} segments: ${cachedSegs.map((s) => s.id).join(", ")})`,
@@ -739,16 +751,16 @@ export function createPartialUpdater(
           });
           if (signal?.aborted) return;
 
+          const cachedHandleData = readCachedHandleData?.();
           const { scroll: commitScroll } = tx.commit(
             matchedIds,
             existingSegments,
             { routeName: payload.metadata.routeName },
           );
-
-          if (mode.targetCacheHandleData) {
+          if (cachedHandleData) {
             store.updateCacheHandleData(
               store.getHistoryKey(),
-              mode.targetCacheHandleData,
+              cachedHandleData,
             );
           }
 
@@ -756,10 +768,7 @@ export function createPartialUpdater(
             payload.metadata!;
           const cachedUpdate = {
             root: newTree,
-            metadata: {
-              ...metadataWithoutHandles,
-              cachedHandleData: mode.targetCacheHandleData,
-            },
+            metadata: { ...metadataWithoutHandles, cachedHandleData },
             ...(commitScroll && { scroll: commitScroll }),
           };
 
@@ -1064,11 +1073,15 @@ export function createPartialUpdater(
         }),
         ...(serverLocationState && { serverState: serverLocationState }),
       };
+      const cachedHandleData = readCachedHandleData?.();
       const { scroll: navScroll } = tx.commit(
         heldIds,
         reconciled.segments,
         overrides,
       );
+      if (cachedHandleData) {
+        store.updateCacheHandleData(store.getHistoryKey(), cachedHandleData);
+      }
       const hasTransition = shouldStartViewTransition(
         reconciled.segments,
         gatedOff,
@@ -1118,7 +1131,9 @@ export function createPartialUpdater(
       // navigation-transaction.ts CommitResult.
       const update: NavigationUpdate = {
         root: newTree,
-        metadata: payload.metadata!,
+        metadata: cachedHandleData
+          ? { ...payload.metadata, cachedHandleData }
+          : payload.metadata!,
         ...(navScroll && { scroll: navScroll }),
       };
       if (process.env.NODE_ENV !== "production") {

package/src/browser/react/Link.tsx

@@ -42,6 +42,7 @@ import {
   subscribeToAdaptiveStrategyChange,
 } from "../prefetch/default-strategy.js";
 import { getAppVersion } from "../app-version.js";
+import { prefixBasename } from "../../router/basename.js";
 import type { PrefetchStrategy } from "../../router/prefetch-default.js";
 
 // The PrefetchStrategy union is defined in router/prefetch-default.ts (both
@@ -244,15 +245,12 @@ export const Link: ForwardRefExoticComponent<
   // store and no origin: links stay internal.
   const isExternal = isExternalUrl(to, ctx?.origin);
 
-  // Auto-prefix with basename for app-local paths.
-  // Skip if external, already prefixed, or not a root-relative path.
-  const resolvedTo = useMemo(() => {
-    if (isExternal) return to;
-    const bn = ctx?.basename;
-    if (!bn || !to.startsWith("/") || to.startsWith(bn + "/") || to === bn)
-      return to;
-    return to === "/" ? bn : bn + to;
-  }, [to, isExternal, ctx?.basename]);
+  // Auto-prefix with basename for app-local paths (prefixBasename: not when
+  // external, already prefixed, or not root-relative).
+  const resolvedTo = useMemo(
+    () => (isExternal ? to : prefixBasename(to, ctx?.basename)),
+    [to, isExternal, ctx?.basename],
+  );
 
   // No explicit `prefetch` prop: fall back to the router-wide default from
   // the router store. Adaptive is resolved against the input capability when a

package/src/browser/react/NavigationProvider.tsx

@@ -311,13 +311,17 @@ export interface NavigationProviderProps {
    * The document this provider hydrates (initBrowserApp; renderRoute with
    * `hydrate: true`), whose store EventController.lockHydration locked.
    * `settled` resolves once the stream has ended and React has revealed every
-   * boundary. Until then location state is `undefined`, as SSR rendered it;
-   * then one transition gives the entry's state and changes
-   * HydrationBarrierContext, and the store is released after that commit
-   * (handle data lands in that release notification). A navigation committed
-   * earlier releases the store before its update, for the whole hold when the
-   * navigation is held: an old-page boundary hydrating meanwhile reads
-   * the destination's values and can mismatch.
+   * boundary. Then a transition changes HydrationBarrierContext alone, and
+   * React commits it once every boundary has hydrated, one still suspended on
+   * the client (a lazy chunk, a deferred-hydration gate) included. Until that
+   * commit location state is `undefined`, as SSR rendered it, through any
+   * commit no payload follows (a shallow navigation), and the store is
+   * locked; after it the entry's state lands in a transition of its own
+   * and the store is released (handle data lands in that release
+   * notification). A navigation committed earlier releases the store before
+   * its update, for the whole hold when the navigation is held: an old-page
+   * boundary hydrating meanwhile reads the destination's values and can
+   * mismatch.
    * Absent for a provider mounted on the client.
    */
   hydration?: { settled: Promise<void> };
@@ -432,18 +436,18 @@ export function NavigationProvider({
     return startConnectionWarmup();
   }, [warmupEnabled]);
 
-  // The document has been revealed: one transition gives the entry's location
-  // state and moves the barrier, so React hydrates every boundary still
-  // dehydrated before it commits.
+  // The document has been revealed. The barrier must be the only update in
+  // its transition lane: then React holds the commit until every boundary
+  // still dehydrated beneath it has hydrated. Any other update in the lane
+  // (location state in its own startTransition here included) can let React
+  // commit around a boundary still suspended on the client. Why:
+  // docs/internal/execution-model.md, "The reveal barrier is alone in its lane".
   useEffect(() => {
     if (!hydration) return;
     let cancelled = false;
     void hydration.settled.then(() => {
       if (cancelled || !hydrationOpen.current) return;
-      startTransition(() => {
-        setLocationState(eventController.getLocationState());
-        setHydrationBarrier((n) => n + 1);
-      });
+      startTransition(() => setHydrationBarrier((n) => n + 1));
     });
     return () => {
       cancelled = true;
@@ -451,20 +455,31 @@ export function NavigationProvider({
   }, []);
 
   // After the barrier's commit no boundary under this provider is dehydrated:
-  // release the store, and its handle writes reach their readers.
+  // the entry's location state lands in a transition of its own, and the
+  // store is released so its handle writes reach their readers. A navigation
+  // that committed first has done both (store onUpdate below).
   useEffect(() => {
-    if (hydrationBarrier === 0) return;
+    if (hydrationBarrier === 0 || !hydrationOpen.current) return;
     hydrationOpen.current = false;
+    startTransition(() => setLocationState(eventController.getLocationState()));
     eventController.releaseHydrationLock();
   }, [hydrationBarrier]);
 
   // A commit no payload follows (a shallow navigation, a commit that keeps
   // every segment, merged server-set state): the tree on screen is already
-  // the entry's, so its state is taken with the commit's notification.
+  // the entry's, so its state is taken with the commit's notification. Not
+  // while the hydration window is open: a boundary of the document may still
+  // be dehydrated, an update a reader outside it takes commits around it, and
+  // it then hydrates against the new state. The barrier's effect gives the
+  // controller's state, this commit's included. The window stays open: this
+  // commit mounts nothing that must read the live store.
   useEffect(
     () =>
       eventController.subscribe(() => {
-        if (eventController.takeTreelessLocationState()) {
+        if (
+          eventController.takeTreelessLocationState() &&
+          !hydrationOpen.current
+        ) {
           setLocationState(eventController.getLocationState());
         }
       }),
@@ -541,18 +556,23 @@ export function NavigationProvider({
         eventController.setParams(update.metadata.params);
       }
 
+      // A page rendered from a history-cache entry (back/forward, or a link
+      // to it) starts from the entry's pushes, and its response's handles
+      // merge onto them: the page on screen's pushes are not its segments'.
+      const { matched, cachedHandleData } = update.metadata;
+      if (matched && cachedHandleData) {
+        eventController.setHandleData(cachedHandleData, matched);
+      }
       // Update handle data progressively as it streams in
       if (update.metadata.handles) {
         consumeHandles(update.metadata, eventController, store);
-      } else if (update.metadata.matched) {
-        // cachedHandleData present -> full restore (back/forward); absent ->
-        // partial cleanup of segments no longer matched.
-        const cached = update.metadata.cachedHandleData;
+      } else if (matched && !cachedHandleData) {
+        // Partial cleanup of segments no longer matched.
         eventController.setHandleData(
-          cached ?? {},
-          update.metadata.matched,
-          cached === undefined,
-          cached === undefined ? update.metadata.resolvedIds : undefined,
+          {},
+          matched,
+          true,
+          update.metadata.resolvedIds,
         );
       }
 

package/src/browser/react/context.ts

@@ -91,8 +91,9 @@ export const LocationStateContext: Context<LocationStateSnapshot> =
  * Read by no component. NavigationProvider changes its value in a transition so
  * that React hydrates every boundary still dehydrated beneath it before that
  * commit: React hydrates a dehydrated boundary first when a provider above it
- * changes, and nothing re-renders for a value nobody reads. See
- * NavigationProviderProps.hydration.
+ * changes, and nothing re-renders for a value nobody reads. It must stay
+ * unread and alone in its lane (docs/internal/execution-model.md, "The reveal
+ * barrier is alone in its lane"). See NavigationProviderProps.hydration.
  */
 export const HydrationBarrierContext: Context<number> =
   createContext<number>(0);

package/src/browser/react/use-router.ts

@@ -5,6 +5,7 @@ import { NavigationStoreContext } from "./context.js";
 import { useMount } from "./use-mount.js";
 import { prefetchDirect } from "../prefetch/loader.js";
 import { getAppVersion } from "../app-version.js";
+import { prefixBasename } from "../../router/basename.js";
 import type { RouterInstance, RouterNavigateOptions } from "../types.js";
 
 /**
@@ -51,10 +52,7 @@ export function useRouter(): RouterInstance {
   return useMemo<RouterInstance>(() => {
     /** Prefix a root-relative path with basename if not already prefixed. */
     function withBasename(url: string): string {
-      const bn = ctx!.basename;
-      if (!bn || !url.startsWith("/") || url.startsWith(bn + "/") || url === bn)
-        return url;
-      return url === "/" ? bn : bn + url;
+      return prefixBasename(url, ctx!.basename);
     }
 
     /**

package/src/browser/server-action-bridge.ts

@@ -906,6 +906,12 @@ export function createServerActionBridge(
 
       handle.complete(returnData);
       return returnData;
+    } catch (error) {
+      // What the call rejects with (a revalidation render that threw, a
+      // failed decode) is the action's error, for useAction as for the
+      // caller. A no-op for an aborted or already-settled action.
+      handle.fail(error);
+      throw error;
     } finally {
       // The single deferred invalidation + fence release for this action. Runs
       // for every terminal that settles (normal, navigated-away, error, abort,

package/src/browser/types.ts

@@ -85,7 +85,11 @@ export interface RscMetadata {
    * positions and must complete at the handler barrier.
    */
   handlesLate?: AsyncGenerator<HandleData, void, unknown>;
-  /** Cached handle data (for back/forward navigation from cache) */
+  /**
+   * Handle data of the history-cache entry the update renders from (a
+   * back/forward restore, or a link to a cached page). It replaces the handle
+   * state, and `handles`, when present, merge onto it.
+   */
   cachedHandleData?: HandleData;
   /**
    * RSC version string from the server.

package/src/build/route-types/scan-filter.ts

@@ -75,9 +75,18 @@ export function isInSkippedScanDir(
   return dirs.some(isUniversallySkippedScanDir);
 }
 
+/**
+ * Directory names the source-file scans skip: findTsFiles() and the build
+ * loader pre-scan (expose-internal-ids.ts). The isUniversallySkippedScanDir()
+ * set plus `build`, which the router scans still enter.
+ */
+export function isSkippedSourceScanDir(name: string): boolean {
+  return isUniversallySkippedScanDir(name) || name === "build";
+}
+
 /**
  * Recursively find .ts/.tsx files under a directory, skipping the directories
- * isUniversallySkippedScanDir() names, `build`, and .gen. files.
+ * isSkippedSourceScanDir() names and .gen. files.
  */
 export function findTsFiles(dir: string, filter?: ScanFilter): string[] {
   const results: string[] = [];
@@ -93,9 +102,7 @@ export function findTsFiles(dir: string, filter?: ScanFilter): string[] {
   for (const entry of entries) {
     const fullPath = join(dir, entry.name);
     if (entry.isDirectory()) {
-      if (isUniversallySkippedScanDir(entry.name) || entry.name === "build") {
-        continue;
-      }
+      if (isSkippedSourceScanDir(entry.name)) continue;
       results.push(...findTsFiles(fullPath, filter));
     } else if (
       (entry.name.endsWith(".ts") ||

package/src/cache/document-cache-policy.ts

@@ -0,0 +1,131 @@
+/**
+ * Document cache storage policy: which responses the document cache stores.
+ * A leaf (types and the per-client signal only), so request-scoped code can
+ * ask whether a render will be stored (documentCacheStoresRender) without
+ * importing the cache middleware.
+ */
+
+import { hasPerClientSignal } from "../browser/cookie-name.js";
+import type { RequestContext } from "../server/request-context.js";
+
+export interface CacheDirectives {
+  sMaxAge?: number;
+  staleWhileRevalidate?: number;
+}
+
+/**
+ * Parse Cache-Control header for s-maxage and stale-while-revalidate directives
+ */
+function parseCacheControl(header: string | null): CacheDirectives | null {
+  if (!header) return null;
+
+  // RFC 7234: in a SHARED cache, `private` and `no-store` forbid storage and
+  // MUST win over `s-maxage` even though `private, s-maxage` is contradictory.
+  // The document cache is a shared app store, so refuse both regardless of any
+  // s-maxage / stale-while-revalidate also present. Match standalone directive
+  // tokens (start/end, whitespace, comma, semicolon, or `=` bounded), not a
+  // substring, so a value containing "private" cannot false-veto.
+  if (/(^|[\s,;])(private|no-store)(?=$|[\s,;=])/i.test(header)) {
+    return null;
+  }
+
+  // RFC 7234 §5.2.2.2: a shared cache MUST NOT serve a stored `no-cache`
+  // response without successful origin validation. This store's hit path has no
+  // validation step, so serving a stored no-cache response within s-maxage
+  // would hand the client content the origin marked must-revalidate. Refuse to
+  // store it. Only UNqualified `no-cache` (no `=`) vetoes — the field-name-
+  // scoped `no-cache="set-cookie"` form IS storable per the RFC, so the `=`
+  // boundary is excluded from the lookahead (unlike private/no-store above).
+  if (/(^|[\s,;])no-cache(?=$|[\s,;])/i.test(header)) {
+    return null;
+  }
+
+  const directives: CacheDirectives = {};
+
+  // Parse s-maxage
+  const sMaxAgeMatch = header.match(/s-maxage\s*=\s*(\d+)/i);
+  if (sMaxAgeMatch) {
+    directives.sMaxAge = parseInt(sMaxAgeMatch[1], 10);
+  }
+
+  // Parse stale-while-revalidate
+  const swrMatch = header.match(/stale-while-revalidate\s*=\s*(\d+)/i);
+  if (swrMatch) {
+    directives.staleWhileRevalidate = parseInt(swrMatch[1], 10);
+  }
+
+  // Only return if we have at least s-maxage (required for document caching)
+  if (directives.sMaxAge !== undefined) {
+    return directives;
+  }
+
+  return null;
+}
+
+/**
+ * Check if response should be cached based on Cache-Control headers
+ */
+export function shouldCacheResponse(
+  response: Response,
+  requestCtx?: Pick<
+    RequestContext,
+    "_payloadVisitorTheme" | "_payloadDeferred" | "_payloadVisitorLocation"
+  >,
+): CacheDirectives | null {
+  // Only cache successful responses
+  if (response.status !== 200) {
+    return null;
+  }
+
+  // Never cache a per-client signal into a SHARED response store. A Set-Cookie
+  // (e.g. a rango state rotation from invalidateClientCache(), or any cookie a
+  // loader set) would be replayed to every client on a hit — pinning them to
+  // one value and even rolling a rotated client back to a prior one. The
+  // x-rango-keep-cache directive header is the mirror image: a replayed "keep"
+  // would suppress invalidation for every replayed client. Refuse both.
+  if (hasPerClientSignal(response.headers)) {
+    return null;
+  }
+
+  // The payload carries the visitor's theme (#978): the render ran before the
+  // response opted in (a Cache-Control written after next()), so
+  // payloadInitialTheme could not render the default.
+  if (requestCtx?._payloadVisitorTheme) {
+    return null;
+  }
+
+  // A rewritten request's render shows the visitor's URL (renderedLocation,
+  // full-payload.ts); this entry is keyed by the rewrite target.
+  if (requestCtx?._payloadVisitorLocation) {
+    return null;
+  }
+
+  // prefetch: false. The payload carries deferred units: it answers one
+  // page's prefetch and nothing else. parseCacheControl refuses the
+  // Cache-Control it is sent with (rsc-rendering.ts NOT_REUSED), but a
+  // middleware can replace that after next(), and a navigation answered
+  // with this body would show a fallback no fill ever replaces.
+  if (requestCtx?._payloadDeferred) {
+    return null;
+  }
+
+  const cacheControl = response.headers.get("Cache-Control");
+  return parseCacheControl(cacheControl);
+}
+
+/**
+ * Whether this cache will store the response the current render produces, as
+ * far as the render can tell: the middleware runs it (a MISS or a stale
+ * refresh) and the response stub already opts in. payloadInitialTheme
+ * (rsc/full-payload.ts) then renders the no-cookie default theme (#978). A
+ * Cache-Control written after next() is not on the stub yet; for that render
+ * shouldCacheResponse refuses a payload marked `_payloadVisitorTheme`.
+ */
+export function documentCacheStoresRender(
+  reqCtx: Pick<RequestContext, "_documentCacheRender" | "res">,
+): boolean {
+  return (
+    reqCtx._documentCacheRender === true &&
+    shouldCacheResponse(reqCtx.res) !== null
+  );
+}

package/src/cache/document-cache.ts

@@ -16,7 +16,10 @@
 import { requestHeaders } from "../server/request-headers.js";
 import { FILL_PARAM } from "../prefetch-markers.js";
 import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
-import { hasPerClientSignal } from "../browser/cookie-name.js";
+import {
+  documentCacheStoresRender,
+  shouldCacheResponse,
+} from "./document-cache-policy.js";
 import {
   getRequestContext,
   runWithRequestContext,
@@ -37,11 +40,14 @@ import {
   predatesInvalidation,
 } from "./tag-invalidation.js";
 import { observePhase, PHASES } from "../router/instrument.js";
+import { isRewrite } from "../route-definition/rewrite.js";
 import {
   SEGMENT_FRAGMENT_CAPABILITY_HEADER,
   SEGMENT_FRAGMENT_RECOVERY_HEADER,
 } from "../segment-fragments.js";
 
+export { documentCacheStoresRender };
+
 const CACHE_STATUS_HEADER = "x-document-cache-status";
 
 function collectRequestTags(
@@ -62,124 +68,6 @@ function hashSegmentIds(segmentIds: string): string {
   return Math.abs(hash).toString(36);
 }
 
-// ============================================================================
-
-interface CacheDirectives {
-  sMaxAge?: number;
-  staleWhileRevalidate?: number;
-}
-
-/**
- * Parse Cache-Control header for s-maxage and stale-while-revalidate directives
- */
-function parseCacheControl(header: string | null): CacheDirectives | null {
-  if (!header) return null;
-
-  // RFC 7234: in a SHARED cache, `private` and `no-store` forbid storage and
-  // MUST win over `s-maxage` even though `private, s-maxage` is contradictory.
-  // The document cache is a shared app store, so refuse both regardless of any
-  // s-maxage / stale-while-revalidate also present. Match standalone directive
-  // tokens (start/end, whitespace, comma, semicolon, or `=` bounded), not a
-  // substring, so a value containing "private" cannot false-veto.
-  if (/(^|[\s,;])(private|no-store)(?=$|[\s,;=])/i.test(header)) {
-    return null;
-  }
-
-  // RFC 7234 §5.2.2.2: a shared cache MUST NOT serve a stored `no-cache`
-  // response without successful origin validation. This store's hit path has no
-  // validation step, so serving a stored no-cache response within s-maxage
-  // would hand the client content the origin marked must-revalidate. Refuse to
-  // store it. Only UNqualified `no-cache` (no `=`) vetoes — the field-name-
-  // scoped `no-cache="set-cookie"` form IS storable per the RFC, so the `=`
-  // boundary is excluded from the lookahead (unlike private/no-store above).
-  if (/(^|[\s,;])no-cache(?=$|[\s,;])/i.test(header)) {
-    return null;
-  }
-
-  const directives: CacheDirectives = {};
-
-  // Parse s-maxage
-  const sMaxAgeMatch = header.match(/s-maxage\s*=\s*(\d+)/i);
-  if (sMaxAgeMatch) {
-    directives.sMaxAge = parseInt(sMaxAgeMatch[1], 10);
-  }
-
-  // Parse stale-while-revalidate
-  const swrMatch = header.match(/stale-while-revalidate\s*=\s*(\d+)/i);
-  if (swrMatch) {
-    directives.staleWhileRevalidate = parseInt(swrMatch[1], 10);
-  }
-
-  // Only return if we have at least s-maxage (required for document caching)
-  if (directives.sMaxAge !== undefined) {
-    return directives;
-  }
-
-  return null;
-}
-
-/**
- * Check if response should be cached based on Cache-Control headers
- */
-function shouldCacheResponse(
-  response: Response,
-  requestCtx?: Pick<
-    RequestContext,
-    "_payloadVisitorTheme" | "_payloadDeferred"
-  >,
-): CacheDirectives | null {
-  // Only cache successful responses
-  if (response.status !== 200) {
-    return null;
-  }
-
-  // Never cache a per-client signal into a SHARED response store. A Set-Cookie
-  // (e.g. a rango state rotation from invalidateClientCache(), or any cookie a
-  // loader set) would be replayed to every client on a hit — pinning them to
-  // one value and even rolling a rotated client back to a prior one. The
-  // x-rango-keep-cache directive header is the mirror image: a replayed "keep"
-  // would suppress invalidation for every replayed client. Refuse both.
-  if (hasPerClientSignal(response.headers)) {
-    return null;
-  }
-
-  // The payload carries the visitor's theme (#978): the render ran before the
-  // response opted in (a Cache-Control written after next()), so
-  // payloadInitialTheme could not render the default.
-  if (requestCtx?._payloadVisitorTheme) {
-    return null;
-  }
-
-  // prefetch: false. The payload carries deferred units: it answers one
-  // page's prefetch and nothing else. parseCacheControl refuses the
-  // Cache-Control it is sent with (rsc-rendering.ts NOT_REUSED), but a
-  // middleware can replace that after next(), and a navigation answered
-  // with this body would show a fallback no fill ever replaces.
-  if (requestCtx?._payloadDeferred) {
-    return null;
-  }
-
-  const cacheControl = response.headers.get("Cache-Control");
-  return parseCacheControl(cacheControl);
-}
-
-/**
- * Whether this cache will store the response the current render produces, as
- * far as the render can tell: the middleware runs it (a MISS or a stale
- * refresh) and the response stub already opts in. payloadInitialTheme
- * (rsc/full-payload.ts) then renders the no-cookie default theme (#978). A
- * Cache-Control written after next() is not on the stub yet; for that render
- * shouldCacheResponse refuses a payload marked `_payloadVisitorTheme`.
- */
-export function documentCacheStoresRender(
-  reqCtx: Pick<RequestContext, "_documentCacheRender" | "res">,
-): boolean {
-  return (
-    reqCtx._documentCacheRender === true &&
-    shouldCacheResponse(reqCtx.res) !== null
-  );
-}
-
 /**
  * Throw the first error the drained render reported through Flight or Fizz
  * onError. A component that throws after the 200 committed does not fail the
@@ -513,6 +401,9 @@ export function createDocumentCacheMiddleware<TEnv = any>(
               ),
             );
           } catch (error) {
+            // The route now rewrites (route middleware): nothing to refresh
+            // this entry with.
+            if (isRewrite(error)) return;
             // Pass requestCtx explicitly: this runs in a detached waitUntil task
             // where the ALS context is gone, so onError only fires if we hand it
             // the captured context (reportCacheError falls back to _getRequestContext
@@ -600,6 +491,8 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       noteWarmDocument(requestCtx, "not-cacheable");
       return originalResponse;
     } catch (error) {
+      // A rewrite() thrown downstream re-dispatches the request.
+      if (isRewrite(error)) throw error;
       reportCacheError(error, "cache-read", "[DocumentCache] middleware");
       if (handlerCalled) {
         // Post-handler failure (e.g. body.tee()): do not call next() again