@rangojs/router 0.18.0 → 0.19.1

package/src/router/prerender-match.ts

@@ -223,6 +223,8 @@ export async function matchForPrerender<TEnv = any>(
       res: stubRes,
       cookie: () => undefined,
       cookies: () => ({}),
+      _readCookie: () => undefined,
+      _readCookies: () => ({}),
       setCookie: () => {},
       deleteCookie: () => {},
       header: () => {},
@@ -526,6 +528,8 @@ export async function renderStaticSegment<TEnv = any>(
     res: stubRes,
     cookie: () => undefined,
     cookies: () => ({}),
+    _readCookie: () => undefined,
+    _readCookies: () => ({}),
     setCookie: () => {},
     deleteCookie: () => {},
     header: () => {},

package/src/router/request-classification.ts

@@ -15,6 +15,7 @@
  * Builds on RouteSnapshot from route-snapshot.ts.
  */
 
+import { requestHeaders } from "../server/request-headers.js";
 import { RouteNotFoundError } from "../errors.js";
 import type { EntryData } from "../server/context.js";
 import type { CollectedMiddleware } from "./middleware-types.js";
@@ -149,10 +150,11 @@ export async function classifyRequest<TEnv = any>(
 ): Promise<RequestPlan<TEnv>> {
   const pathname = url.pathname;
   const isAction =
-    request.headers.has("rsc-action") || url.searchParams.has("_rsc_action");
+    requestHeaders(request).has("rsc-action") ||
+    url.searchParams.has("_rsc_action");
   const isLoaderFetch = url.searchParams.has("_rsc_loader");
   const isPartialReq = url.searchParams.has("_rsc_partial");
-  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");
@@ -176,7 +178,7 @@ export async function classifyRequest<TEnv = any>(
   ) {
     let reloadUrl = stripInternalParams(url).toString();
     if (isAction) {
-      const referer = request.headers.get("referer");
+      const referer = requestHeaders(request).get("referer");
       if (referer) {
         try {
           const refererUrl = new URL(referer);
@@ -248,7 +250,8 @@ export async function classifyRequest<TEnv = any>(
   }
 
   const actionId =
-    request.headers.get("rsc-action") || url.searchParams.get("_rsc_action");
+    requestHeaders(request).get("rsc-action") ||
+    url.searchParams.get("_rsc_action");
 
   const hasVariants =
     snapshot.matched.negotiateVariants &&

package/src/router/router-options.ts

@@ -518,7 +518,10 @@ export interface RangoOptions<TEnv = any> {
    *
    * Controls how long prefetch responses are kept in the client-side
    * in-memory cache and sets `Cache-Control: private, max-age=<ttl>`
-   * on server responses for CDN/edge caching.
+   * on prefetch responses, so the browser's HTTP cache may reuse them
+   * (`private`: shared caches such as a CDN do not store them). A route an
+   * intercept targets gets no prefetch `Cache-Control`: whether its
+   * response is the modal or the full page depends on the source page.
    *
    * The cache is automatically invalidated on server actions regardless
    * of TTL, so this is primarily a staleness safety net.

package/src/router/segment-resolution/fresh.ts

@@ -324,7 +324,6 @@ export async function resolveSegment<TEnv>(
       transition: applyViewTransitionDefault(
         entry.transition,
         deps.viewTransitionDefault,
-        entry.shortCode,
       ),
       params,
       belongsToRoute: false,
@@ -474,7 +473,6 @@ export async function resolveSegment<TEnv>(
       transition: applyViewTransitionDefault(
         entry.transition,
         deps.viewTransitionDefault,
-        entry.shortCode,
       ),
       params,
       belongsToRoute: true,
@@ -563,7 +561,6 @@ export async function resolveOrphanLayout<TEnv>(
     transition: applyViewTransitionDefault(
       orphan.transition,
       deps.viewTransitionDefault,
-      orphan.shortCode,
     ),
     ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
   });
@@ -723,7 +720,6 @@ export async function resolveParallelEntry<TEnv>(
       transition: applyViewTransitionDefault(
         parallelEntry.transition,
         deps.viewTransitionDefault,
-        `${parentShortCode}.${slot}`,
       ),
       params,
       slot,

package/src/router/segment-resolution/loader-cache.ts

@@ -6,7 +6,8 @@
  * getItem()/setItem() methods on SegmentCacheStore.
  *
  * Cache key resolution (3-tier, matching CacheScope.resolveKey):
- *   1. options.key(requestCtx) — full override
+ *   1. options.key(requestCtx) — full override, stored namespaced as
+ *      loader:{loaderId}:key:{encodeURIComponent(result)} (#1009)
  *   2. store.keyGenerator(requestCtx, defaultKey) — store-level modification
  *   3. loader:{loaderId}:{host}{pathname}:{sortedParams} — default
  *
@@ -57,13 +58,17 @@ import {
 } from "../../cache/handle-capture.js";
 import { encodeHandles, decodeHandles } from "../../cache/handle-snapshot.js";
 import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
+import { runIdentityExempt } from "../../cache/cache-exec-scope.js";
 import {
   getRequestContext,
   _getRequestContext,
   runWithRequestContext,
 } from "../../server/request-context.js";
 import { observePhase, PHASES } from "../instrument.js";
-import { sortedRouteParams } from "../../cache/cache-key-utils.js";
+import {
+  KEY_PART_PREFIX,
+  sortedRouteParams,
+} from "../../cache/cache-key-utils.js";
 import {
   resolveTtl,
   resolveSwrWindow,
@@ -73,19 +78,25 @@ import {
   DEFAULT_ROUTE_TTL,
 } from "../../cache/cache-policy.js";
 import { readThroughItem } from "../../cache/read-through-swr.js";
+import {
+  executionStart,
+  predatesInvalidation,
+} from "../../cache/tag-invalidation.js";
 import {
   maskNestedContainerThenables,
   overlayLoaderContainer,
 } from "./loader-snapshot.js";
 import {
   SHELL_BAKE_TAG_OWNER,
-  armLoaderTagSets,
   captureRecordedTags,
+  earliestRecordedStart,
   flattenRecordedTags,
   linkLoaderTags,
   linkLoaderTagsTo,
   linkRecordedTags,
   markIdentityRead,
+  markTagSetStart,
+  readStartedLoaderValue,
   readValueTags,
   recordedIdentityRead,
   recordLoaderTags,
@@ -128,6 +139,28 @@ function getDefaultLoaderCacheKey(
   return `loader:${loaderId}:${host}${base}`;
 }
 
+/**
+ * A loader's own `key()` result as its entry key (#1009). The result is
+ * often request input, and the item family (`getItem`/`setItem`) has no
+ * other discriminator, so stored raw it could name another loader's entry
+ * or a `"use cache"` entry (`use-cache:<id>:...`, cache-runtime.ts), which
+ * shares that family; route records use `get`/`set`. Namespaced, it can't:
+ * - it starts with `loader:`, which no `"use cache"` key does;
+ * - an encoded result holds no `:`, so the key reads unambiguously from
+ *   the right (result, `key:`, loader id), and two namespaced keys are
+ *   equal only for the same loader and result;
+ * - a default key `loader:<id>:<host><pathname>...` holds a `/` past its
+ *   id, and an encoded result holds none, so the two are equal only if one
+ *   loader's id is literally `<other id>:<host>/<path>...`. Loader ids can
+ *   hold `:` (a dev id is a root-relative path, absolute `D:/...` on
+ *   Windows), so this is the guarantee, not "ids hold no `:`".
+ * A store keyGenerator result stays the store's own namespace, as on routes
+ * (composeCacheKeys).
+ */
+function loaderKeyFromResult(loaderId: string, result: string): string {
+  return `loader:${loaderId}:${KEY_PART_PREFIX}${encodeURIComponent(result)}`;
+}
+
 /**
  * Resolve cache key using the shared 3-tier priority. `declared`: a key() or
  * store keyGenerator produced it, so it can carry request identity (#972).
@@ -148,9 +181,14 @@ async function resolveLoaderKey(
   const host = getRequestContext()?.url?.host ?? "localhost";
   const defaultKey = getDefaultLoaderCacheKey(loaderId, host, pathname, params);
   if (options === false) return { key: defaultKey, declared: false };
+  const keyFn = options.key;
   return {
-    key: await resolveCacheKey(options.key, store, defaultKey, "LoaderCache"),
-    declared: Boolean(options.key || store.keyGenerator),
+    key: await resolveCacheKey(
+      keyFn && (async (ctx) => loaderKeyFromResult(loaderId, await keyFn(ctx))),
+      store,
+      defaultKey,
+    ),
+    declared: Boolean(keyFn || store.keyGenerator),
   };
 }
 
@@ -199,6 +237,64 @@ export function bindsLoaderCache(entries: readonly EntryData[]): boolean {
   return entries.some(entryBindsLoaderCache);
 }
 
+const chainLoaderEntriesMemo = new WeakMap<EntryData, readonly LoaderEntry[]>();
+
+// The loaders an entry registers, its orphan layouts' and its parallel
+// slots' included.
+function chainLoaderEntries(entry: EntryData): readonly LoaderEntry[] {
+  let loaders = chainLoaderEntriesMemo.get(entry);
+  if (loaders === undefined) {
+    loaders = [
+      ...(entry.loader ?? []),
+      ...(entry.layout ?? []).flatMap(chainLoaderEntries),
+      ...Object.values(entry.parallel ?? {}).flatMap((p) =>
+        p ? chainLoaderEntries(p) : [],
+      ),
+    ];
+    chainLoaderEntriesMemo.set(entry, loaders);
+  }
+  return loaders;
+}
+
+/**
+ * The ids of the loaders a request over the matched chain `entries` runs on
+ * the live lane (no `ssr: false`), on a chain entry, its orphan layouts or
+ * its parallel slots. A document HIT tail restores the record's pushes of
+ * every other owner as authoritative (withCacheLookup, HandleStore
+ * pushRestored); a live-lane loader is a hole, so its live run replaces its
+ * recorded pushes instead. Memoized per entry.
+ */
+export function liveLaneLoaderIds(
+  entries: readonly EntryData[],
+): ReadonlySet<string> {
+  const ids = new Set<string>();
+  for (const entry of entries) {
+    for (const l of chainLoaderEntries(entry)) {
+      if (!l.bake) ids.add(l.loader.$$id);
+    }
+  }
+  return ids;
+}
+
+/**
+ * The lane of each loader the matched chain `entries` registers: "live" (no
+ * `ssr: false`) or "bake". A loader registered on both is "live". A PPR
+ * capture credits a push to the first registered loader around it when that
+ * one is live (shell-capture.ts deriveShellCaptureContext).
+ */
+export function routeLoaderLanes(
+  entries: readonly EntryData[],
+): ReadonlyMap<string, "live" | "bake"> {
+  const lanes = new Map<string, "live" | "bake">();
+  for (const entry of entries) {
+    for (const l of chainLoaderEntries(entry)) {
+      if (!l.bake) lanes.set(l.loader.$$id, "live");
+      else if (!lanes.has(l.loader.$$id)) lanes.set(l.loader.$$id, "bake");
+    }
+  }
+  return lanes;
+}
+
 function getLoaderStore(
   loaderEntry: LoaderEntry,
 ): import("../../cache/types.js").SegmentCacheStore | null {
@@ -228,31 +324,47 @@ function getLoaderStore(
  * replayed one.
  * A PPR shell capture records the replayed pushes under this loader (its
  * push funnel reads the pushReplayed owner, shell-capture.ts), so a shell
- * HIT restores them owned: the claim above then skips this replay when the
- * loader runs on that HIT, and its live pushes replace the restored ones.
+ * HIT restores them owned (HandleStore.pushRestored). This replay still
+ * runs on that HIT: the store drops its settled values, which the record
+ * already restored, and keeps the thenable ones the record could not keep
+ * (a deferred push, the reason the loader's record carries `runs`).
  */
 async function replayLoaderHandles(
-  encoded: string,
+  encoded: string | undefined,
   handleStore: HandleStore,
   segmentId: string,
+  cachedLoaderId: string,
   claim: ((loaderId: string) => boolean) | undefined,
 ): Promise<void> {
-  const recorded = await decodeHandles(encoded);
+  const recorded = encoded ? await decodeHandles(encoded) : {};
   if (!recorded) return;
   const delivers = new Map<string, boolean>();
-  for (const key in recorded) {
-    const owner = key.slice(key.indexOf(":") + 1);
+  const claims = (owner: string): boolean => {
     let deliver = delivers.get(owner);
     if (deliver === undefined) {
       deliver = claim ? claim(owner) : true;
       delivers.set(owner, deliver);
     }
-    if (!deliver) continue;
-    for (const [handleName, values] of Object.entries(recorded[key])) {
-      for (const value of values) {
-        handleStore.pushReplayed(handleName, segmentId, value, owner);
+    return deliver;
+  };
+  const replay = (): void => {
+    for (const key in recorded) {
+      const owner = key.slice(key.indexOf(":") + 1);
+      if (!claims(owner)) continue;
+      for (const [handleName, values] of Object.entries(recorded[key])) {
+        for (const value of values) {
+          handleStore.pushReplayed(handleName, segmentId, value, owner);
+        }
       }
     }
+  };
+  // A hole's entry, pushes or none, takes the place of the shell copies of
+  // its pushes (HandleStore.redeliverReplays). Not once the hole delivered
+  // in this request: a run a reader started first replaces them itself.
+  if (claims(cachedLoaderId)) {
+    handleStore.redeliverReplays(cachedLoaderId, replay);
+  } else {
+    replay();
   }
 }
 
@@ -449,9 +561,10 @@ function executeLoaderData<TEnv>(
 
   // Evaluate runtime condition if provided
   const options = cacheConfig.options;
-  if (options.condition) {
+  const condition = options.condition;
+  if (condition) {
     const requestCtx = getRequestContext();
-    if (requestCtx && !options.condition(requestCtx)) {
+    if (requestCtx && !runIdentityExempt(() => condition(requestCtx))) {
       return ctx.use(loaderEntry.loader);
     }
   }
@@ -479,7 +592,7 @@ function executeLoaderData<TEnv>(
         // useLoader.
         linkLoaderTags(item.$$id);
         readValueTags(cached);
-        return cached;
+        return readStartedLoaderValue(cached, item.$$id);
       }
       return originalUse(item);
     }) as typeof ctx.use;
@@ -508,11 +621,8 @@ function executeLoaderData<TEnv>(
   const swr = swrWindow || undefined;
   const tags = resolveTags(loaderEntry);
   recordLoaderTags(loaderId, tags);
-  // Production arms at match, before any loader runs (match-api.ts,
-  // bindsLoaderCache); no production path relies on this. It only keeps a
-  // resolveLoaders call outside a match from running unarmed after this
-  // point (loaders it started earlier stay unrecorded).
-  armLoaderTagSets();
+  // The per-execution loader tag sets were armed before any loader ran: by
+  // the match (match-api.ts, bindsLoaderCache), or by runLoader.
   // An execution of this loader outside the binding (a reader started it
   // first, a stale refresh) answers for the cache() tags too.
   if (tags && tags.length > 0) {
@@ -530,8 +640,10 @@ function executeLoaderData<TEnv>(
   const isOwnBodyPush = () => isInsideLoaderBody(loaderId);
   // What a reader of this value takes on (tagLoaderValue below,
   // readValueTags): the cache() tags, plus the entry's tags on a HIT or the
-  // execution's on a MISS.
+  // execution's on a MISS. A HIT's value is as old as its lookup: a cached
+  // reader gates its own write from here at the latest (#977).
   const valueTags = new Set(tags);
+  markTagSetStart(valueTags, executionStart());
 
   const dataPromise = (async () => {
     const codec = await getCodec();
@@ -560,7 +672,9 @@ function executeLoaderData<TEnv>(
     const bodyTags = new Set(tags);
     let revalidating = false;
     let hitHandles: string | undefined;
+    let cachedRead = false;
     const onCachedRead = (label: string, cached: CacheItemResult) => {
+      cachedRead = true;
       hitHandles = cached.handles;
       const { read } = unmarkIdentity(cached.value);
       if (read) markIdentityRead(valueTags, read);
@@ -634,6 +748,15 @@ function executeLoaderData<TEnv>(
           // After the handle encode: it settles pending pushes, which can read.
           const read = identityRead();
           const entryTags = [...flattenRecordedTags(bodyTags)];
+          // One of the entry's tags was invalidated after the value's oldest
+          // part started (#977): this execution, or the run of this loader or
+          // of a dependency another reader started earlier. Written now, a
+          // value that may predate it would outlive it. Skip the write; the
+          // next read runs the body.
+          const start = earliestRecordedStart(bodyTags);
+          if (start && (await predatesInvalidation(store, entryTags, start))) {
+            return;
+          }
           await store.setItem!(k, markIdentity(v, read), {
             ...o,
             tags: entryTags.length > 0 ? entryTags : undefined,
@@ -642,6 +765,7 @@ function executeLoaderData<TEnv>(
         }),
       key,
       execute: async () => {
+        markTagSetStart(bodyTags, executionStart());
         const value = await captureRecordedTags(bodyTags, runBody);
         identityRead();
         return value;
@@ -675,12 +799,14 @@ function executeLoaderData<TEnv>(
       host: requestCtxForExecute,
     });
 
-    // An entry written before handles were recorded has none: no replay.
-    if (hitHandles && handleStore && owningSegmentId) {
+    // An entry without handles (none recorded, or dropped by an encode
+    // timeout) replays none, and still stands for a hole's shell copies.
+    if (cachedRead && handleStore && owningSegmentId) {
       await replayLoaderHandles(
         hitHandles,
         handleStore,
         owningSegmentId,
+        loaderId,
         internal._claimLoaderPushes,
       );
     }

package/src/router/segment-resolution/loader-mask.ts

@@ -8,10 +8,9 @@
  * fresh into it.
  *
  * Capture mode is signalled by `requestCtx._shellCaptureRun`, set to true ONLY on
- * the derived request context of the background capture task (shell-capture.ts) —
- * NOT by the foreground render, whose `_shellCapture` descriptor merely means "a
- * capture is wanted" and must not change behavior. This module is the single home
- * for the mask so every loader execution site gates the same way (loader-cache.ts
+ * the derived request context of the background capture task (shell-capture.ts);
+ * the foreground render never sets it. This module is the single home for the
+ * mask so every loader execution site gates the same way (loader-cache.ts
  * `resolveLoaderData`, fresh.ts `resolveLoaders`).
  */
 

package/src/router/segment-resolution/loader-snapshot.ts

@@ -10,24 +10,18 @@
  * server-component element holding a promise, which is a hole as a whole (see
  * elideLoaderContainer):
  *
- *   - elide:   deep-walk the settled container; a PENDING nested promise is a
- *              hole, replaced by {@link LOADER_HOLE_KEY} — and since
- *              loader-cache masks every nested thenable at capture
- *              ({@link maskNestedContainerThenables}), nested promises are
- *              ALWAYS pending here for new captures. The SETTLED-marker branch
- *              below is legacy: it fires only if a settled thenable reaches
- *              elide anyway, and the overlay keeps decoding SETTLED markers
- *              from pre-mask snapshots. The result is promise-free and
- *              Flight-serializable.
+ *   - elide:   deep-walk the settled container; a nested promise is a hole,
+ *              replaced by {@link LOADER_HOLE_KEY}. loader-cache masks every
+ *              nested thenable at capture ({@link maskNestedContainerThenables},
+ *              a never-settling promise), so the promise shape alone decides:
+ *              a value that settled in time does not bake (#692). The result
+ *              is promise-free and Flight-serializable.
  *   - overlay: on a HIT the loader runs fresh (only the loader body can mint
  *              the live nested promises), then the recorded container is laid
  *              over it: recorded paths win (they are what the prelude froze),
  *              hole-marker paths take the fresh run's value (the live hole),
- *              SETTLED-marker paths become Promise.resolve(pinned) — consumers
- *              wrote use(data.x) against a promise-shaped container, and
- *              handing them the raw value throws React #438 on every HIT (the
- *              storefront PDP regression) — and fresh-only paths pass through
- *              (they cannot contradict prelude bytes that never rendered them).
+ *              and fresh-only paths pass through (they cannot contradict
+ *              prelude bytes that never rendered them).
  */
 
 import { isValidElement, type ReactElement } from "react";
@@ -64,37 +58,6 @@ export function isLoaderHoleMarker(value: unknown): value is LoaderHoleMarker {
   );
 }
 
-/**
- * Marker wrapping the inlined value of a NESTED promise that settled during
- * capture. The value baked (physics), but the container key was a promise —
- * the overlay must hand consumers a Promise.resolve(value), not the raw value,
- * or an unconditional use(data.x) throws React #438 on every HIT. The ROOT
- * container is never wrapped: loader-cache overlays against the awaited fresh
- * container value.
- */
-export const LOADER_SETTLED_KEY = "$rangoLoaderSettled" as const;
-
-export interface LoaderSettledMarker {
-  [LOADER_SETTLED_KEY]: 1;
-  value: unknown;
-  /**
-   * Present when the pinned subtree contains hole markers. Computed once at
-   * capture (elide already visits every node) so the per-HIT overlay never
-   * rescans the pinned structure to pick its rehydration path.
-   */
-  holes?: 1;
-}
-
-export function isLoaderSettledMarker(
-  value: unknown,
-): value is LoaderSettledMarker {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    (value as Record<string, unknown>)[LOADER_SETTLED_KEY] === 1
-  );
-}
-
 /**
  * Probe whether a promise is already settled without waiting for it: races it
  * against an immediately-resolved sentinel across two microtask hops (then
@@ -128,12 +91,12 @@ export type ElideResult =
   | { state: "rejected" };
 
 /**
- * Deep-elide a settled bake-lane container for recording. Settled nested
- * promises pin their value behind a settled marker (they baked, but consumers
- * hold a promise-shaped key); pending ones become hole markers; a REJECTED
- * nested promise poisons the record (error UI must never bake into a shared
- * shell) — the caller refuses the capture. Plain data objects, arrays and the
- * props of host, Suspense/Fragment and client-reference elements are
+ * Deep-elide a settled bake-lane container for recording. Nested promises
+ * become hole markers: the capture masked each of them (never settles), so
+ * it postponed as a hole. A REJECTED container poisons the record (error UI
+ * must never bake into a shared shell) — the caller refuses the capture.
+ * Plain data objects, arrays and the props of host, Suspense/Fragment and
+ * client-reference elements are
  * traversed copy-on-write (an element through cloneElementWithProps); a shared
  * subtree or a cycle resolves to the same elided result. An element Flight
  * renders by calling user code (see rendersOnServer) is a leaf, or ONE hole
@@ -165,17 +128,7 @@ async function elideNested(
   seen: Map<object, ElideResult>,
 ): Promise<ElideResult> {
   if (isThenable(value)) {
-    const probed = await probeSettled(value);
-    if (probed.state === "pending") {
-      return { state: "ok", value: { [LOADER_HOLE_KEY]: 1 }, hasHole: true };
-    }
-    if (probed.state === "rejected") return { state: "rejected" };
-    const inner = await elideNested(probed.value, seen);
-    if (inner.state === "rejected") return inner;
-    const marker: LoaderSettledMarker = inner.hasHole
-      ? { [LOADER_SETTLED_KEY]: 1, value: inner.value, holes: 1 }
-      : { [LOADER_SETTLED_KEY]: 1, value: inner.value };
-    return { state: "ok", value: marker, hasHole: inner.hasHole };
+    return { state: "ok", value: { [LOADER_HOLE_KEY]: 1 }, hasHole: true };
   }
   if (typeof value !== "object" || value === null) {
     return { state: "ok", value, hasHole: false };
@@ -324,22 +277,6 @@ export function overlayLoaderContainer(
 ): unknown {
   if (isLoaderHoleMarker(recorded)) return fresh;
 
-  if (isLoaderSettledMarker(recorded)) {
-    const pinned = recorded.value;
-    // Deep holes inside a settled container (capture-computed `holes` bit)
-    // need the fresh promise's resolved value to fill them; a fully-pinned
-    // container resolves immediately (the prelude already shows it — never
-    // gate it on fresh latency). A rejecting fresh run degrades holes to
-    // undefined instead of poisoning the pin.
-    if (recorded.holes === 1) {
-      return Promise.resolve(fresh).then(
-        (freshValue) => overlayLoaderContainer(freshValue, pinned),
-        () => overlayLoaderContainer(undefined, pinned),
-      );
-    }
-    return Promise.resolve(overlayLoaderContainer(undefined, pinned));
-  }
-
   if (Array.isArray(recorded)) {
     const freshArr = Array.isArray(fresh) ? fresh : [];
     let out: unknown[] | undefined;

package/src/router/segment-resolution/mask-nested.ts

@@ -81,30 +81,55 @@ export function cloneElementWithProps(
  */
 export function settleNestedThenables(value: unknown): Promise<void> {
   const pending: Promise<void>[] = [];
-  const seen = new Set<object>();
-  const walk = (v: unknown): void => {
-    if (isThenable(v)) {
-      pending.push(
-        Promise.resolve(v).then(settleNestedThenables, () => undefined),
-      );
-      return;
-    }
-    if (isValidElement<Record<string, unknown>>(v)) {
-      walk(v.props);
-      return;
-    }
-    if (Array.isArray(v) || isPlainDataObject(v)) {
-      if (seen.has(v)) return;
-      seen.add(v);
-      for (const item of Array.isArray(v) ? v : Object.values(v)) walk(item);
-    }
-  };
-  walk(value);
+  someNestedThenable(value, (thenable) => {
+    pending.push(
+      Promise.resolve(thenable).then(settleNestedThenables, () => undefined),
+    );
+    return false;
+  });
   return pending.length === 0
     ? Promise.resolve()
     : Promise.all(pending).then(() => undefined);
 }
 
+/**
+ * The walk settleNestedThenables and holdsThenable share: visit each thenable
+ * reachable from `value` through plain data objects, arrays and React element
+ * props (never an element's owner or type), the shapes
+ * maskNestedContainerThenables masks; every other object is a leaf. Stops at
+ * the first visit that returns true and reports whether one did.
+ */
+function someNestedThenable(
+  value: unknown,
+  visit: (thenable: PromiseLike<unknown>) => boolean,
+): boolean {
+  let seen: Set<object> | undefined;
+  const walk = (v: unknown): boolean => {
+    if (isThenable(v)) return visit(v);
+    if (typeof v !== "object" || v === null) return false;
+    if (isValidElement<Record<string, unknown>>(v)) return walk(v.props);
+    if (!Array.isArray(v) && !isPlainDataObject(v)) return false;
+    seen ??= new Set();
+    if (seen.has(v)) return false;
+    seen.add(v);
+    // Own enumerable values, as maskNestedContainerThenables walks
+    // Object.keys: an array's non-index properties are walked too.
+    return Object.values(v).some(walk);
+  };
+  return walk(value);
+}
+
+/**
+ * True when `value` is a thenable or holds one where the capture's loader
+ * push funnel masks it (maskNestedContainerThenables): through plain data
+ * objects, arrays and React element props. Such a push stays out of a shell's
+ * record and reaches a HIT only from a run of its loader there, so a HIT
+ * keeps it; a push without one is the record's (HandleStore.pushRestored).
+ */
+export function holdsThenable(value: unknown): boolean {
+  return someNestedThenable(value, () => true);
+}
+
 /**
  * Optional single-walk report for maskNestedContainerThenables: `thenable`
  * flips true when the walk masked at least one thenable. The capture push
@@ -139,9 +164,9 @@ export interface MaskReport {
  * nodes included, are leaves. Copy-on-write: a subtree without a thenable
  * comes back by identity, so an element is rebuilt only when its props hold
  * one, and then through cloneElementWithProps, which keeps its type, key,
- * owner, dev fields and key validation. The INPUT IS NEVER MUTATED — handler-side loader consumption (the
- * consumption-lane rule, semantic-matrix PPR3) shares the raw container and
- * must keep real values. Cycles are preserved as cycles in the copy.
+ * owner, dev fields and key validation. The INPUT IS NEVER MUTATED: a handler
+ * that reads the loader (`ctx.use`) reads the raw container and must keep
+ * real values. Cycles are preserved as cycles in the copy.
  */
 export function maskNestedContainerThenables(
   value: unknown,