@rangojs/router 0.20.0 → 0.22.0

package/src/segment-loader-promise.ts

@@ -2,36 +2,30 @@ import type { ResolvedSegment } from "./types.js";
 import { INTERNAL_RANGO_DEBUG } from "./internal-debug.js";
 
 /**
- * Cache of aggregate Promise.all results keyed on the first loader's
- * `loaderData` reference. Each entry holds the source refs it was built from
- * plus the resulting Promise/array; lookup scans entries for the matching
- * source array (typically a single entry, since distinct loader groups rarely
- * share a first source). Object first-refs live in a WeakMap (auto-GC);
- * primitive first-refs (strings/numbers/booleans/null) live in a Map so
- * loaders that resolve to primitive data are memoized too. The per-key array
- * is capped (MAX_ENTRIES_PER_KEY, oldest evicted) so a long session under a
- * stable first-ref does not grow it without bound.
+ * Browser: a boundary is handed the settled value. React treats a promise as
+ * fulfilled only after it has read it, and a boundary on screen handed a
+ * promise it has not read, in a render that cannot wait, shows its fallback.
+ * So a cache entry records its array once the aggregate fulfils and later
+ * calls return that same array; until then (and when it rejects) they return
+ * the promise. A boundary with no loaders gets one shared empty array.
  *
- * Keying externally means reconciliation's fresh segment objects no longer
- * drop memoization — the cache survives as long as the underlying loader
- * segments do, and GC collects entries when those loaders are released
- * (object keys only).
+ * Server: a fresh promise per call, so Suspense emits the fallback in the
+ * streamed HTML. A shared resolved promise would carry React's `.status`
+ * across requests and skip it.
  *
- * Browser-only. On the server each SSR render needs a fresh Promise so
- * Suspense can actually suspend and emit the loading fallback HTML before
- * content streams. A shared already-resolved promise has `.status` attached
- * by React on first `use()`; subsequent observations return synchronously
- * and skip the fallback. The zero-loader case is especially prone because
- * every empty-loader site would otherwise share one promise across requests.
+ * Entries are keyed on the first loader's `loaderData` reference (object refs
+ * in a WeakMap, primitives in a Map), so reconciliation's fresh segment
+ * objects keep hitting them. Each key's entry list is capped (see
+ * MAX_ENTRIES_PER_KEY).
  */
 const IS_BROWSER = typeof window !== "undefined";
 
 interface LoaderCacheEntry {
   sources: any[];
-  // buildLoaderPromise always returns a Promise, so the cached value is never a
-  // bare array. The public getMemoizedLoaderPromise return type stays broader
-  // (Promise<any[]> | any[]) to mirror its siblings.
+  // Resolves to the same array it records in `value`; a rejection passes
+  // through untouched.
   promise: Promise<any[]>;
+  value?: any[];
 }
 
 // Cap the per-key entries array. A stable first-ref (e.g. a layout loader whose
@@ -51,12 +45,8 @@ const primitiveLoaderCache = IS_BROWSER
   ? new Map<unknown, LoaderCacheEntry[]>()
   : null;
 
-// In the browser, a single shared empty aggregate is safe (and desirable) —
-// reusing the same resolved promise keeps React's `use()` in a known-fulfilled
-// state across renders. On the server it would leak `.status = "fulfilled"`
-// across requests and skip the Suspense fallback, so we rebuild on each call.
-const SHARED_EMPTY_LOADER_PROMISE: Promise<any[]> | null = IS_BROWSER
-  ? Promise.resolve([])
+const SHARED_EMPTY_LOADERS: any[] | null = IS_BROWSER
+  ? (Object.freeze([]) as unknown as any[])
   : null;
 
 function hasSameReferences(a: any[], b: any[]): boolean {
@@ -117,12 +107,8 @@ function isObjectLike(value: unknown): value is object {
 }
 
 /**
- * Memoize an aggregate Promise.all for a set of loader segments. Reusing the
- * same aggregate across renders — invalidated only when any underlying
- * loader.loaderData ref changes — keeps React's `use()` in "known fulfilled"
- * state and prevents a fresh Promise.all from suspending (and briefly
- * committing the Suspense fallback) on every partial update that doesn't
- * actually change loader data.
+ * The aggregate for a set of loader segments, memoized on their `loaderData`
+ * refs: the settled array once it has fulfilled, the promise before that.
  *
  * @internal
  */
@@ -130,7 +116,7 @@ export function getMemoizedLoaderPromise(
   loaders: ResolvedSegment[],
 ): Promise<any[]> | any[] {
   if (loaders.length === 0) {
-    return SHARED_EMPTY_LOADER_PROMISE ?? buildLoaderPromise(loaders);
+    return SHARED_EMPTY_LOADERS ?? buildLoaderPromise(loaders);
   }
   if (!objectLoaderCache || !primitiveLoaderCache) {
     return buildLoaderPromise(loaders);
@@ -145,13 +131,17 @@ export function getMemoizedLoaderPromise(
   if (entries) {
     for (const entry of entries) {
       if (hasSameReferences(entry.sources, sources)) {
-        return entry.promise;
+        return entry.value ?? entry.promise;
       }
     }
   }
 
-  const promise = buildLoaderPromise(loaders);
-  const newEntry: LoaderCacheEntry = { sources, promise };
+  const newEntry = { sources } as LoaderCacheEntry;
+  const promise = buildLoaderPromise(loaders).then((values) => {
+    newEntry.value = values;
+    return values;
+  });
+  newEntry.promise = promise;
   if (entries) {
     // Bound the array: drop the oldest entry before appending when at the cap.
     if (entries.length >= MAX_ENTRIES_PER_KEY) {

package/src/segment-system.tsx

@@ -5,7 +5,7 @@ import {
   type ComponentType,
   isValidElement,
 } from "react";
-import { OutletProvider } from "./outlet-provider.js";
+import { AuditedOutletProvider, OutletProvider } from "./outlet-provider.js";
 import { withOptimisticCommitNone } from "./browser/optimistic-commit.js";
 import { MountContextProvider } from "./browser/react/mount-context.js";
 import type { ResolvedSegment, RootLayoutProps } from "./types.js";
@@ -13,17 +13,25 @@ import { decodeLoaderResults } from "./decode-loader-results.js";
 import { LoaderRedirect } from "./loader-redirect.js";
 import { invariant } from "./errors.js";
 import {
+  AuditedLoaderBoundary,
+  AuditedRouteContent,
   RouteContentWrapper,
   LoaderBoundary,
   StreamedLoaderErrorBoundary,
 } from "./route-content-wrapper.js";
 import { RootErrorBoundary } from "./root-error-boundary.js";
 import { INTERNAL_RANGO_DEBUG } from "./internal-debug.js";
-import { getMemoizedContentPromise } from "./segment-content-promise.js";
+import { INTERNAL_RANGO_SUSPENSE_AUDIT } from "./internal-suspense-audit.js";
+import { getBoundaryContent } from "./segment-boundary-content.js";
 import {
   buildLoaderPromise,
   getMemoizedLoaderPromise,
 } from "./segment-loader-promise.js";
+import {
+  auditSegmentElement,
+  finishTreeAudit,
+  startTreeAudit,
+} from "./suspense-audit.js";
 
 /**
  * Debug log for the segment tree build, gated on the baked flag. Runs on BOTH
@@ -212,13 +220,25 @@ function wrapDefaultOutletContent(
     } as any);
   }
 
-  if (content.type === OutletProvider && props.segment?.type === "layout") {
+  if (
+    content.type ===
+      (process.env.NODE_ENV !== "production" && INTERNAL_RANGO_SUSPENSE_AUDIT
+        ? AuditedOutletProvider
+        : OutletProvider) &&
+    props.segment?.type === "layout"
+  ) {
     return React.cloneElement(content, {
       content: wrapDefaultOutletContent(props.content, transition),
     } as any);
   }
 
-  if (content.type === LoaderBoundary && props.segment?.type === "layout") {
+  if (
+    content.type ===
+      (process.env.NODE_ENV !== "production" && INTERNAL_RANGO_SUSPENSE_AUDIT
+        ? AuditedLoaderBoundary
+        : LoaderBoundary) &&
+    props.segment?.type === "layout"
+  ) {
     return React.cloneElement(content, {
       outletContent: wrapDefaultOutletContent(props.outletContent, transition),
     } as any);
@@ -376,6 +396,10 @@ export async function renderSegments(
   }
   // Separate segments by type, passing intercept segments for explicit injection
   const tree = segmentTreeWalk(normalizedSegments, normalizedInterceptSegments);
+  // Dev only: the wrapper chain per segment, compared with the previous
+  // tree's (suspense-audit.ts, I5).
+  const treeAudit =
+    process.env.NODE_ENV !== "production" ? startTreeAudit() : undefined;
 
   // A route is "in a transition scope" when its own segment OR any layout in
   // its matched chain declares transition(). Both transition() forms land here:
@@ -473,34 +497,33 @@ export async function renderSegments(
 
     let nodeContent: ReactNode = null;
     if (!clientGroup && isRenderableLoading(loading)) {
-      // forceAwait (popstate, stale-revalidation, fully-prefetched nav) renders a
-      // loading() route with the route content ALREADY resolved, so its
-      // RouteContentWrapper Suspender does not suspend for a microtask and flash
-      // the loading() fallback on a NORMAL (non-transition) commit. The router
-      // data is known-ready on these paths, so awaiting the content here is free.
-      // The wrapper tree is unchanged (RouteContentWrapper is still created with
-      // the same key/fallback) — only the `content` prop is a resolved node
-      // instead of a pending promise, which Suspender renders synchronously. This
-      // mirrors the forceAwait loaderData unwrap above; a CLIENT component that
-      // suspends on mount inside the content still reveals a fallback (it is not
-      // pre-resolved).
-      const contentPromise = getMemoizedContentPromise(resolvedComponent);
-      let loadingContent: Promise<ReactNode> | ReactNode = contentPromise;
+      // The wrapper tree is the same on every path; only `content` differs. A
+      // settled component is handed over as the node (getBoundaryContent), a
+      // pending one as its promise, so only pending work shows the loading()
+      // fallback. forceAwait also awaits a pending component here. A CLIENT
+      // component that suspends on mount inside the content still reveals a
+      // fallback.
+      let loadingContent: ReactNode = getBoundaryContent(resolvedComponent);
       if (forceAwait) {
         const contentAwaitStart = segDebug ? performance.now() : 0;
-        loadingContent = await contentPromise;
+        loadingContent = await loadingContent;
         if (segDebug) {
           segDebugLog(`segment ${id}: content awaited (forceAwait)`, {
             ms: Math.round(performance.now() - contentAwaitStart),
           });
         }
       }
-      nodeContent = createElement(RouteContentWrapper, {
-        key: `suspense-loading-${id}`,
-        content: loadingContent,
-        fallback: loading,
-        segmentId: id,
-      });
+      nodeContent = createElement(
+        process.env.NODE_ENV !== "production" && INTERNAL_RANGO_SUSPENSE_AUDIT
+          ? AuditedRouteContent
+          : RouteContentWrapper,
+        {
+          key: `suspense-loading-${id}`,
+          content: loadingContent,
+          fallback: loading,
+          segmentId: id,
+        },
+      );
     } else {
       // [VT-DIAG] Gated behind INTERNAL_RANGO_DEBUG. A segment in the no-loading()
       // branch whose component decodes as a Promise/lazy gets registered into
@@ -593,7 +616,10 @@ export async function renderSegments(
       let boundaryAwaitedLoaderIds: string[] | undefined;
       if (forceAwait || isAction) {
         const awaitStart = segDebug ? performance.now() : 0;
-        boundaryLoaderData = await loaderDataPromise;
+        boundaryLoaderData =
+          loaderDataPromise instanceof Promise
+            ? await loaderDataPromise
+            : loaderDataPromise;
         if (segDebug) {
           segDebugLog(`segment ${id}: loaders awaited (forceAwait/action)`, {
             loaderIds,
@@ -621,28 +647,38 @@ export async function renderSegments(
           );
         }
       }
-      content = createElement(LoaderBoundary, {
-        key: `loader-boundary-${key}`,
-        loaderDataPromise: boundaryLoaderData,
-        loaderIds,
-        loaderStreams: boundaryLoaderStreams,
-        awaitedLoaderIds: boundaryAwaitedLoaderIds,
-        fallback: loading,
-        outletKey: key,
-        outletContent,
-        segment: node.segment,
-        parallel: node.parallel,
-        children: nodeContent,
-      });
+      content = createElement(
+        process.env.NODE_ENV !== "production" && INTERNAL_RANGO_SUSPENSE_AUDIT
+          ? AuditedLoaderBoundary
+          : LoaderBoundary,
+        {
+          key: `loader-boundary-${key}`,
+          loaderDataPromise: boundaryLoaderData,
+          loaderIds,
+          loaderStreams: boundaryLoaderStreams,
+          awaitedLoaderIds: boundaryAwaitedLoaderIds,
+          fallback: loading,
+          outletKey: key,
+          outletContent,
+          segment: node.segment,
+          parallel: node.parallel,
+          children: nodeContent,
+        },
+      );
     } else if (loaderEntries.length === 0) {
-      content = createElement(OutletProvider, {
-        key,
-        content: outletContent,
-        segment: node.segment,
-        parallel: node.parallel,
-        pending: outletPending,
-        children: nodeContent,
-      });
+      content = createElement(
+        process.env.NODE_ENV !== "production" && INTERNAL_RANGO_SUSPENSE_AUDIT
+          ? AuditedOutletProvider
+          : OutletProvider,
+        {
+          key,
+          content: outletContent,
+          segment: node.segment,
+          parallel: node.parallel,
+          pending: outletPending,
+          children: nodeContent,
+        },
+      );
     } else {
       const layoutLoaders = loaderEntries.filter((l) => !l.parallelLoading);
       const parallelOwnedLoaders = loaderEntries.filter(
@@ -776,17 +812,23 @@ export async function renderSegments(
         }
       }
 
-      content = createElement(OutletProvider, {
-        key,
-        content: outletContent,
-        segment: node.segment,
-        parallel: node.parallel,
-        loaderData: Object.keys(loaderData).length > 0 ? loaderData : undefined,
-        loaderStreams,
-        awaitedLoaderIds,
-        pending: outletPending,
-        children: errorFallback ?? nodeContent,
-      });
+      content = createElement(
+        process.env.NODE_ENV !== "production" && INTERNAL_RANGO_SUSPENSE_AUDIT
+          ? AuditedOutletProvider
+          : OutletProvider,
+        {
+          key,
+          content: outletContent,
+          segment: node.segment,
+          parallel: node.parallel,
+          loaderData:
+            Object.keys(loaderData).length > 0 ? loaderData : undefined,
+          loaderStreams,
+          awaitedLoaderIds,
+          pending: outletPending,
+          children: errorFallback ?? nodeContent,
+        },
+      );
     }
 
     // Wrap with MountContextProvider for include() scoped components.
@@ -800,6 +842,22 @@ export async function renderSegments(
       });
     }
 
+    if (process.env.NODE_ENV !== "production") {
+      auditSegmentElement(
+        treeAudit,
+        id,
+        node.segment.type,
+        key,
+        content,
+        node.segment.type === "layout" &&
+          !!ReactViewTransition &&
+          !!transition &&
+          transition.viewTransition !== false,
+        node.parallel.map((p) => p.id),
+        [node.segment, ...node.parallel, ...node.loaders],
+      );
+    }
+
     if (segDebug) {
       segDebugLog(`segment ${id} built`, {
         type: node.segment.type,
@@ -849,6 +907,8 @@ export async function renderSegments(
     });
   }
 
+  if (process.env.NODE_ENV !== "production") finishTreeAudit(treeAudit, result);
+
   return result;
 }
 

package/src/server/build-version-table.ts

@@ -0,0 +1,130 @@
+/// <reference path="../vite/plugins/version.d.ts" />
+/**
+ * Runtime side of the per-router cache versions: binds the
+ * `@rangojs/router:version` virtual module and answers "which versions does
+ * this router, or this request, use".
+ *
+ * Design: docs/design/per-app-cache-version.md.
+ */
+import { ROUTER_VERSIONS, VERSION } from "@rangojs/router:version";
+import {
+  resolveVersionsFrom,
+  uniformVersions,
+  type RouterVersions,
+  type RouterVersionsTable,
+} from "../router-versions.js";
+import { _getRequestContext } from "./request-context.js";
+
+/**
+ * The build's table. Module state only so the testing primitive
+ * (testing/build-versions.ts) can install one where the build's is absent;
+ * production never reassigns it.
+ */
+let table: RouterVersionsTable | undefined = ROUTER_VERSIONS;
+
+/**
+ * The versions a router serves with, in order:
+ *
+ * 1. `override`, a consumer-set `version` (createRouter or createRSCHandler):
+ *    that exact value for both.
+ * 2. The router's entry in the build table, else the whole-build entry.
+ * 3. `VERSION` for both: the dev stamp, bumped on every RSC module edit.
+ */
+export function resolveRouterVersions(
+  routerId: string | undefined,
+  override?: string,
+): RouterVersions {
+  return (
+    resolveVersionsFrom(table, routerId, override) ?? uniformVersions(VERSION)
+  );
+}
+
+/**
+ * The version an on-demand prerender overlay key carries: the router's data
+ * version, because the overlay stores segment data, as the segment cache does
+ * (a client-only deploy keeps both). The write side (`router.prerender`,
+ * router.ts) and the read side (rsc/handler.ts) both call this with
+ * `createRouter({ version })`, the only override the trigger can see, so they
+ * cannot disagree; a `createRSCHandler({ version })` does not move it.
+ */
+export function resolvePrerenderVersion(
+  routerId: string | undefined,
+  routerVersion: string | undefined,
+): string {
+  return resolveRouterVersions(routerId, routerVersion).data;
+}
+
+/** The table gives some router a pair of its own. */
+function hasRouterVersions(): boolean {
+  if (!table) return false;
+  const pairs = new Set(
+    Object.values(table).map(([data, document]) => `${data}\0${document}`),
+  );
+  return pairs.size > 1;
+}
+
+let warnedOutsideRequest = false;
+
+/**
+ * The versions of the router serving the current request, for a cache store
+ * building a key. A store operation with no request context (a detached task
+ * that lost the ALS) gets the whole-build versions: it misses the request's
+ * entries instead of reading another version's. When routers have versions of
+ * their own that is a write no router reads back, so it is logged, once per
+ * process: `ctx.waitUntil()` re-enters the request context for every task it
+ * runs (server/request-context.ts), and this line in a production log means
+ * some other path lost it.
+ *
+ * Public from `@rangojs/router/cache`, for a custom persistent store to key
+ * the way the built-in ones do. Prefix cached RSC data (segment entries, items) with
+ * `data` and stored HTML or responses (shells, document responses) with
+ * `document`, and leave tag-invalidation records unversioned; an empty string
+ * means "no version" (tests). Call it per operation, inside the request, not
+ * in the store's constructor: the cache factory runs before the request
+ * context exists.
+ */
+export function getCacheVersions(): RouterVersions {
+  const versions = _getRequestContext()?._versions;
+  if (versions) return versions;
+  if (!warnedOutsideRequest && hasRouterVersions()) {
+    warnedOutsideRequest = true;
+    console.warn(
+      "[rango] A cache key was built outside a request, so it carries the whole-build cache " +
+        "version instead of a router's. This build has per-router versions: an entry written " +
+        "under that key is not read by a router with its own version, and an entry that router " +
+        "wrote is not found from here. A store operation ran in a task that lost the request's " +
+        "async context. Logged once per process.",
+    );
+  }
+  return resolveRouterVersions(undefined);
+}
+
+/** Which of the serving router's versions a store key carries; `null`: none. */
+export type KeyVersion = keyof RouterVersions | null;
+
+/**
+ * The `v/{version}/` prefix of a persistent store key, or "" for an
+ * unversioned one. A store-level `version` is used for every versioned kind;
+ * otherwise the version is the serving router's, read per operation because
+ * the cache factory builds the store before the request context exists.
+ */
+export function versionKeyPrefix(
+  storeVersion: string | undefined,
+  kind: KeyVersion,
+): string {
+  if (kind === null) return "";
+  const version = storeVersion ?? getCacheVersions()[kind];
+  return version ? `v/${version}/` : "";
+}
+
+/**
+ * @internal Install a table, or restore the build's with `undefined`. A
+ * request handler resolves its router's versions once, when it is created, so
+ * a test that swaps the table (a "deploy") needs new handlers.
+ */
+export function installRouterVersionsTable(
+  next: RouterVersionsTable | undefined,
+): void {
+  table = next ?? ROUTER_VERSIONS;
+  warnedOutsideRequest = false;
+}

package/src/server/context.ts

@@ -15,6 +15,10 @@ 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 {
+  noteWarmIdentityRead,
+  type WarmContext,
+} from "../prerender/warm-request.js";
 import {
   endIdentityExempt,
   isInsideCacheExecScope,
@@ -261,8 +265,13 @@ export type EntryData =
       /** Original PrerenderHandlerDefinition (for build-time getParams access) */
       prerenderDef?: {
         getParams?: (ctx: any) => Promise<any[]> | any[];
-        options?: { concurrency?: number };
+        options?: {
+          concurrency?: number;
+          onDemand?: import("../prerender/on-demand.js").OnDemandOption;
+        };
       };
+      /** Set when the route opted into on-demand prerender (Prerender(..., { onDemand })) */
+      isOnDemand?: true;
       /** Set when route is wrapped with Passthrough() — has a separate live handler */
       isPassthrough?: true;
       /** Live handler for runtime fallback (only set on Passthrough routes) */
@@ -428,6 +437,7 @@ export const getContext = (): {
   getStore: () => HelperContext;
   getParent: () => EntryData | null;
   getOrCreateStore: (forRoute?: string) => HelperContext;
+  runIsolated: <T>(forRoute: string, callback: () => T) => T;
   getNextIndex: (
     type: (string & {}) | "layout" | "parallel" | "middleware" | "revalidate",
   ) => string;
@@ -447,26 +457,29 @@ export const getContext = (): {
   ) => T;
 } => {
   const context = RangoContext;
+  const createStore = (forRoute?: string): HelperContext => ({
+    manifest: new Map<string, EntryData>(),
+    namespace: "",
+    parent: null,
+    forRoute,
+    counters: {},
+    patterns: new Map<string, string>(),
+    patternsByPrefix: new Map<string, Map<string, string>>(),
+    trailingSlash: new Map<string, "never" | "always" | "ignore">(),
+    searchSchemas: new Map<string, Record<string, string>>(),
+  });
 
   return {
     context,
     getOrCreateStore: (forRoute?: string): HelperContext => {
       let store = RangoContext.getStore();
       if (!store) {
-        store = {
-          manifest: new Map<string, EntryData>(),
-          namespace: "",
-          parent: null,
-          forRoute,
-          counters: {},
-          patterns: new Map<string, string>(),
-          patternsByPrefix: new Map<string, Map<string, string>>(),
-          trailingSlash: new Map<string, "never" | "always" | "ignore">(),
-          searchSchemas: new Map<string, Record<string, string>>(),
-        } satisfies HelperContext;
+        store = createStore(forRoute);
       }
       return store;
     },
+    runIsolated: <T>(forRoute: string, callback: () => T): T =>
+      context.run(createStore(forRoute), callback),
     getStore: (): HelperContext => {
       const store = context.getStore();
       if (!store) {
@@ -959,19 +972,20 @@ export interface IdentityReadWording {
  * nothing and are not captured reads: they take refuseInCacheScope alone.
  */
 export function guardIdentityRead(
-  ctx: unknown,
+  ctx: WarmContext | null | undefined,
   surface: string,
   wording: IdentityReadWording,
 ): void {
   if (isInsideIdentityExempt()) return;
   const { verb, fix } = wording;
   if (tripShellCaptureGuard(ctx, surface, fix.warning)) {
+    noteWarmIdentityRead(ctx, surface);
     throw new Error(
       `${surface} cannot be ${verb} while capturing a shared shell ` +
         `(ppr shell capture). ${fix.capture}`,
     );
   }
-  refuseInCacheScope(surface, wording);
+  refuseInCacheScope(surface, wording, ctx);
   if (wording.record !== false) recordLoaderIdentityRead(surface, verb);
 }
 
@@ -982,13 +996,16 @@ export function guardIdentityRead(
 export function refuseInCacheScope(
   surface: string,
   { verb, fix }: IdentityReadWording,
+  ctx?: WarmContext | null,
 ): void {
   if (isInsideCacheExecScope()) {
+    noteWarmIdentityRead(ctx, surface);
     throw new Error(
       `${surface} cannot be ${verb} inside a "use cache" function. ${fix.useCache}`,
     );
   }
   if (isInsideCacheScope()) {
+    noteWarmIdentityRead(ctx, surface);
     throw new Error(
       `${surface} cannot be ${verb} inside a cache() boundary. ${fix.cacheScope}`,
     );
@@ -1074,7 +1091,7 @@ const NON_CACHEABLE_READ: IdentityReadWording = {
  */
 export function assertNonCacheableReadAllowed(
   keyOrVar: string | ContextVar<unknown>,
-  requestCtx?: unknown,
+  requestCtx?: WarmContext | null,
 ): void {
   const name = typeof keyOrVar === "string" ? ` "${keyOrVar}"` : "";
   guardIdentityRead(
@@ -1276,7 +1293,10 @@ export function isInsideAnyLoaderScope(): boolean {
 
 /**
  * The one ppr opt-in predicate: a page route entry that DECLARED `ppr`
- * (`false` and undefined mean plain axis 1). Shared by the serve path
+ * (`false`, undefined, and on-demand routes mean plain axis 1). A writable
+ * prerender refresh cannot atomically replace the separate document shell, so
+ * combining those lanes would pair a fresh tail with a stale prelude. Shared by
+ * the serve path
  * (rsc/shell-serve.ts resolvePprConfig) and the header-write latch below so
  * the two layers can never drift on what counts as a ppr route.
  */
@@ -1285,7 +1305,10 @@ export function isPprEntry(entry: EntryData): entry is EntryData & {
   ppr: true | import("../urls/pattern-types.js").PartialPrerenderProps;
 } {
   return (
-    entry.type === "route" && entry.ppr !== undefined && entry.ppr !== false
+    entry.type === "route" &&
+    entry.isOnDemand !== true &&
+    entry.ppr !== undefined &&
+    entry.ppr !== false
   );
 }