@rangojs/router 0.21.0 → 0.22.0

package/src/rsc/shell-capture.ts

@@ -41,7 +41,9 @@ import {
   SHELL_CAPTURE_TASK_HARD_CAP_MS,
   resetShellWarningsForTests,
   warnOnce,
+  type ShellCaptureRefusal,
 } from "./shell-capture-constants.js";
+import { noteWarmWrite } from "../prerender/warm-request.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import type { TraceSpan } from "../router/tracing.js";
@@ -75,6 +77,7 @@ import type {
   CachedEntryData,
   ShellCacheEntry,
   SegmentCacheStore,
+  ShellSnapshotHandlesValue,
   ShellSnapshotRecord,
 } from "../cache/types.js";
 import {
@@ -83,6 +86,7 @@ import {
 } from "../router/segment-resolution/loader-snapshot.js";
 import {
   RecordingShellStore,
+  SHELL_HANDLES_RECORD_KEY,
   SnapshotOnlySegmentStore,
   countSnapshotFamilies,
   estimateShellEntryBytes,
@@ -90,10 +94,17 @@ import {
   hasDocRecord,
   pruneShellSnapshot,
 } from "../cache/shell-snapshot.js";
+import {
+  captureOwnedHandles,
+  encodeHandles,
+} from "../cache/handle-snapshot.js";
 import type { HandlerContext } from "./handler-context.js";
 import type { SSRModule } from "./types.js";
 import { buildFullPayload, payloadInitialTheme } from "./full-payload.js";
-import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
+import {
+  recordedHandleData,
+  resolveDeferredHandleValues,
+} from "../handles/deferred-resolution.js";
 import { renderRscFlightStage } from "./render-pipeline.js";
 import { stripInternalParams } from "../router/handler-context.js";
 
@@ -482,6 +493,20 @@ function refuseOnCaptureGuard(
   return true;
 }
 
+/** The refusal a tripped capture guard stands for (refuseOnCaptureGuard). */
+function guardRefusal(derivedCtx: RequestContext<any>): ShellCaptureRefusal {
+  return derivedCtx._dynamic ? "dynamic" : "identity";
+}
+
+/** A refused attempt; the reason rides its event (ShellCaptureDebugEvent.refusal). */
+function refuse(
+  stats: Pick<ShellCaptureDebugEvent, "refusal">,
+  refusal: ShellCaptureRefusal,
+): "refused" {
+  stats.refusal = refusal;
+  return "refused";
+}
+
 /** The no-shell cause for handler output that missed the capture deadline. */
 const HANDLER_OUTPUT_TIMEOUT_REASON: string =
   "the handler output (a promise it passes or pushes, or an async server " +
@@ -658,6 +683,8 @@ export interface ShellCaptureDebugEvent {
   untaggedBake?: true;
   /** Outcome reported by a store that supports shell-write acknowledgements. */
   storeWrite?: "stored" | "invalidated" | "uncacheable";
+  /** Why a `refused` attempt refused. */
+  refusal?: ShellCaptureRefusal;
   /** Consecutive failure count in the key's backoff entry, when one exists. */
   backoffFailures?: number;
   /** Ms remaining in the key's backoff window, when one exists. */
@@ -719,6 +746,7 @@ export function describeShellCaptureEvent(
   if (event.storeWrite !== undefined) {
     parts.push(`store-write=${event.storeWrite}`);
   }
+  if (event.refusal !== undefined) parts.push(`refusal=${event.refusal}`);
   if (event.backoffFailures !== undefined) {
     parts.push(`backoff-failures=${event.backoffFailures}`);
   }
@@ -1042,6 +1070,15 @@ export interface ShellCaptureDescriptor {
    * re-render the page and drop the isolate's memo of the shell just stored.
    */
   storedSeqAtRead?: number;
+  /**
+   * A `router.prerender()` warm's capture (rsc-rendering.ts shellServePlan):
+   * one explicit call that must store, so the guards that shed a herd of
+   * visitors do not apply to it. scheduleShellCapture skips the in-flight
+   * dedup and the refused-capture backoff, and attemptCapture waits longer on
+   * the write barrier. Every correctness guard, the inert-store skip and the
+   * queue limits still decide.
+   */
+  force?: true;
 }
 
 /** Per key, the sequence number of its latest stored capture (bounded). */
@@ -1086,7 +1123,10 @@ export function scheduleShellCapture(
   descriptor: ShellCaptureDescriptor,
 ): void {
   const key = descriptor.key;
-  const inFlight = inFlightCaptures.get(key);
+  // A forced capture installs its own token below: a visitor's capture that
+  // started before the warm may have read data from before the change the
+  // warm publishes, and the queue runs it first, so the warm stores last.
+  const inFlight = descriptor.force ? undefined : inFlightCaptures.get(key);
   if (inFlight) {
     if (Date.now() - inFlight.startedAt <= SHELL_CAPTURE_TASK_HARD_CAP_MS) {
       publishCaptureDebugEvent(descriptor, { key, outcome: "skip-in-flight" });
@@ -1107,7 +1147,7 @@ export function scheduleShellCapture(
   }
   // Refused/failed within the window → skip the doomed re-render (one probe per
   // key per window per isolate). Expired entries self-evict inside the check.
-  if (isCaptureBackedOff(key)) {
+  if (!descriptor.force && isCaptureBackedOff(key)) {
     publishCaptureDebugEvent(descriptor, {
       key,
       outcome: "skip-backoff",
@@ -1436,6 +1476,7 @@ type CaptureAttemptStats = Pick<
   | "snapshotSkipped"
   | "untaggedBake"
   | "storeWrite"
+  | "refusal"
   | "recordSettleMs"
   | "entryBytes"
 > & {
@@ -1597,7 +1638,7 @@ async function runShellCapture(
 export type CaptureRecordOutcome =
   | { kind: "record" | "prerender"; match: MatchResult }
   | { kind: "timeout"; reason: string }
-  | { kind: "refused" };
+  | { kind: "refused"; refusal: ShellCaptureRefusal };
 
 /**
  * Record-first capture: the doc record is both the settle signal and the
@@ -1643,7 +1684,13 @@ export async function settleCaptureRecord(
   const loaderRecords = derivedCtx._shellCaptureLoaderRecords;
   const settled = await raceDeadline(
     Promise.all([
-      freshHandleStore.getData().then(resolveDeferredHandleValues),
+      freshHandleStore
+        .getData()
+        .then((data) =>
+          resolveDeferredHandleValues(
+            recordedHandleData(freshHandleStore, data),
+          ),
+        ),
       derivation.handlerPushesSettled(),
       loaderRecords && loaderRecords.size > 0
         ? Promise.allSettled([...loaderRecords.values()])
@@ -1655,7 +1702,7 @@ export async function settleCaptureRecord(
   // write starts (no encode for a capture that already failed).
   if (!settled.done) {
     if (refuseOnCaptureGuard(capture.key, derivedCtx))
-      return { kind: "refused" };
+      return { kind: "refused", refusal: guardRefusal(derivedCtx) };
     return { kind: "timeout", reason: HANDLER_OUTPUT_TIMEOUT_REASON };
   }
 
@@ -1676,7 +1723,9 @@ export async function settleCaptureRecord(
 
   // Capture guards first: a tripped guard usually also fails the record,
   // and its own message names the cause.
-  if (refuseOnCaptureGuard(capture.key, derivedCtx)) return { kind: "refused" };
+  if (refuseOnCaptureGuard(capture.key, derivedCtx)) {
+    return { kind: "refused", refusal: guardRefusal(derivedCtx) };
+  }
 
   const docKey = derivedCtx._shellImplicitCache?.docKey;
   const record =
@@ -1694,7 +1743,7 @@ export async function settleCaptureRecord(
       return { kind: "timeout", reason: HANDLER_OUTPUT_TIMEOUT_REASON };
     }
     warnCaptureRefusedOnce(capture.key, NO_DOC_RECORD_REASON);
-    return { kind: "refused" };
+    return { kind: "refused", refusal: "no-record" };
   }
 
   // A handle encode that timed out stores "" (handle-snapshot.ts
@@ -1708,7 +1757,7 @@ export async function settleCaptureRecord(
         "record. A promise inside a Map, Set, or class instance is not awaited " +
         "before the encode; push plain objects and arrays.",
     );
-    return { kind: "refused" };
+    return { kind: "refused", refusal: "handles" };
   }
 
   const { fragmentSegments } = await import("../cache/segment-codec.js");
@@ -1805,8 +1854,21 @@ async function attemptCapture(
   // skipped, cache-store middleware's write path gated off by state.cacheHit), so
   // prelude, snapshot, and ring-3 agree on the foreground's generation. Runs per
   // attempt (the retry re-checks; already-settled promises are free).
+  //
+  // A forced capture (a warm) is not latency-bound and must not bake an entry
+  // its own foreground is still replacing, so it waits for as long as the task
+  // hard cap leaves after the capture budget.
   const barrierStart = performance.now();
-  await settleTrackedBackgroundTasks(reqCtx, SHELL_CAPTURE_WRITE_BARRIER_MS);
+  await settleTrackedBackgroundTasks(
+    reqCtx,
+    descriptor.force
+      ? Math.max(
+          SHELL_CAPTURE_WRITE_BARRIER_MS,
+          SHELL_CAPTURE_TASK_HARD_CAP_MS -
+            (descriptor.captureTimeout ?? SHELL_CAPTURE_MAX_WAIT_MS),
+        )
+      : SHELL_CAPTURE_WRITE_BARRIER_MS,
+  );
   stats.barrierWaitMs = Math.round(performance.now() - barrierStart);
 
   const derivation = deriveShellCaptureContext(
@@ -1863,7 +1925,7 @@ async function attemptCapture(
         stats.recordSettleMs,
       );
     }
-    if (settled.kind === "refused") return "refused";
+    if (settled.kind === "refused") return refuse(stats, settled.refusal);
     if (settled.kind === "timeout") {
       stats.noShellCause = settled.reason;
       return "no-shell";
@@ -2122,6 +2184,7 @@ export function deriveShellCaptureContext(
   // Own list: the capture's render errors refuse the capture only, and the
   // foreground's never reach it.
   derivedCtx._renderErrors = [];
+  derivedCtx._recoveredHandlerErrors = undefined;
   derivedCtx._shellCaptureRun = true;
   // Own dynamic() latch. The inherited method writes the FOREGROUND context
   // (its closure), which already served, and nothing read it for a runtime
@@ -2240,7 +2303,9 @@ async function captureAndStoreShell(
   // (boundary-less segment — lands in the catch) or is swallowed into
   // per-loader error UI (the render completes — caught after the try).
   const refuseOnGuardTrip = (): "refused" | undefined =>
-    refuseOnCaptureGuard(capture.key, reqCtx) ? "refused" : undefined;
+    refuseOnCaptureGuard(capture.key, reqCtx)
+      ? refuse(stats, guardRefusal(reqCtx))
+      : undefined;
 
   // Dev diagnostics for a no-shell attempt (warnNullCaptureOnce): the stacks of
   // the tasks React reports as still pending at the capture's abort. React's
@@ -2356,7 +2421,7 @@ async function captureAndStoreShell(
               "Fix the loader, or drop its ssr: false to move it to the live lane.",
             PPR_LANE_HINT,
           );
-          return "refused";
+          return refuse(stats, "loader");
         }
         // The container itself never settled: it is a hole (under an ancestor
         // boundary) or the trivial-prelude gate already fired. Omit — no pin.
@@ -2373,7 +2438,7 @@ async function captureAndStoreShell(
               "Drop its ssr: false to move it to the live lane, or move the decision into middleware.",
             PPR_LANE_HINT,
           );
-          return "refused";
+          return refuse(stats, "loader");
         }
         // Past the hole check: this container settled with real material that
         // bakes into the shell prelude (independent of the snapshot pin below).
@@ -2413,6 +2478,21 @@ async function captureAndStoreShell(
       }
     }
 
+    // Built before the render-error check below so its encode errors refuse
+    // the capture (ShellSnapshotHandlesValue).
+    const docKey = reqCtx._shellImplicitCache?.docKey;
+    let prerenderHandles: ShellSnapshotHandlesValue | undefined;
+    if (!capture.navigationOnly && !hasDocRecord(snapshot, docKey)) {
+      // The store is sealed (settleCaptureRecord) and settled (quiesce).
+      const { handles, owners } = captureOwnedHandles(reqCtx._handleStore);
+      prerenderHandles = {
+        handles: await encodeHandles(handles, (error) => {
+          reqCtx._renderErrors?.push(error);
+        }),
+        handleOwners: owners,
+      };
+    }
+
     // A shell component that threw inside a Suspense boundary does not reject
     // the capture: Flight and Fizz report it through onError and the prelude
     // carries the errored boundary, which every HIT would serve (issue #915).
@@ -2426,7 +2506,6 @@ async function captureAndStoreShell(
     // Store only what a HIT reads (issue #941): the doc record and, for a
     // document entry, the bake-lane loader pins. Before the size guards, so
     // they measure what is stored.
-    const docKey = reqCtx._shellImplicitCache?.docKey;
     let prunedRecords: string | undefined;
     const { kept, pruned } = pruneShellSnapshot(
       snapshot,
@@ -2464,6 +2543,15 @@ async function captureAndStoreShell(
         stats.snapshotSkipped = true;
       }
     }
+    // Exempt from maxSnapshotBytes: the HIT needs it for its HTML and
+    // hydration data to match.
+    if (prerenderHandles) {
+      snapshot.push({
+        family: "handles",
+        key: SHELL_HANDLES_RECORD_KEY,
+        value: prerenderHandles,
+      });
+    }
 
     // settleCaptureRecord refused every capture without a doc record except a
     // prerender-served one (the prerender store supplies its handler layer on
@@ -2525,7 +2613,7 @@ async function captureAndStoreShell(
           "Shrink the page the shell bakes, or move large regions under a live " +
           "loader's boundary.",
       );
-      return "refused";
+      return refuse(stats, "size");
     }
 
     // Missing tags are valid: the shell follows TTL/SWR-only invalidation. Expose
@@ -2597,7 +2685,7 @@ async function captureAndStoreShell(
                 record,
                 `${sinceWriteMs} ms after this capture wrote it`,
               );
-              return "refused";
+              return refuse(stats, "record-expired");
             }
             stats.expired = {
               route,
@@ -2623,7 +2711,7 @@ async function captureAndStoreShell(
               "If capture code deterministically calls updateTag() on its own shell tag, move that mutation out of the render; " +
               "otherwise every generation is invalidated before it can be served.",
           );
-          return "refused";
+          return refuse(stats, "invalidated");
         }
         if (storeWrite === "uncacheable") {
           // The store declared the entry unstorable under its current
@@ -2638,8 +2726,9 @@ async function captureAndStoreShell(
               "the write as permanently refusable, so the key is backed off. See the cache store's " +
               "own warning for the specific limit and remedy.",
           );
-          return "refused";
+          return refuse(stats, "uncacheable");
         }
+        noteWarmWrite(reqCtx, "shell");
       } catch (error) {
         // Best-effort: a failed put must never throw out of the background task.
         reportCacheError(

package/src/rsc/shell-serve.ts

@@ -35,6 +35,7 @@ import {
   resetShellWarningsForTests,
   warnOnce,
 } from "./shell-capture-constants.js";
+import { routerKeyPrefix } from "../cache/cache-key-utils.js";
 
 export {
   PPR_REPLAY_STATUS_HEADER,
@@ -529,8 +530,9 @@ export function warnPprWindowCappedOnce(
 
 /**
  * Paths a partitioned request found without a build shell. Build shells are
- * per path (a param route prerenders some of its paths), so a negative is
- * kept per path, not per route; cleared when full, so it stays bounded.
+ * per router and path (a param route prerenders some of its paths), so a
+ * negative is kept per router and path, not per route; cleared when full, so
+ * it stays bounded.
  */
 const pathsWithoutBuildShell = new Set<string>();
 const PATHS_WITHOUT_BUILD_SHELL_MAX = 1_000;
@@ -540,12 +542,14 @@ const PATHS_WITHOUT_BUILD_SHELL_MAX = 1_000;
  * already warned, or its path was already found without one.
  */
 export function partitionBuildShellCheckDone(
+  routerId: string,
   pathname: string,
   routeName: string | undefined,
 ): boolean {
+  const router = routerKeyPrefix(routerId);
   return (
-    hasWarnedOnce("partition-build-shell", routeName ?? pathname) ||
-    pathsWithoutBuildShell.has(pathname)
+    hasWarnedOnce("partition-build-shell", router + (routeName ?? pathname)) ||
+    pathsWithoutBuildShell.has(router + pathname)
   );
 }
 
@@ -560,21 +564,23 @@ export function partitionBuildShellCheckDone(
  * with no build shell stays silent.
  */
 export function notePartitionBuildShellCheck(
+  routerId: string,
   pathname: string,
   routeName: string | undefined,
   found: boolean,
 ): void {
+  const router = routerKeyPrefix(routerId);
   if (!found) {
     if (pathsWithoutBuildShell.size >= PATHS_WITHOUT_BUILD_SHELL_MAX) {
       pathsWithoutBuildShell.clear();
     }
-    pathsWithoutBuildShell.add(pathname);
+    pathsWithoutBuildShell.add(router + pathname);
     return;
   }
   // Concurrent first requests can both probe; one of them warns.
   warnOnce(
     "partition-build-shell",
-    routeName ?? pathname,
+    router + (routeName ?? pathname),
     () =>
       `[rango] Route ${routeName ? `"${routeName}" ` : ""}("${pathname}") has a ` +
       "build-time shell, but its request partition (a cache({ key }) enclosing the route, " +

package/src/rsc/ssr-module-loader.ts

@@ -0,0 +1,26 @@
+/**
+ * The SSR module loader a handler created without `loadSSRModule` falls back
+ * to in tests (`router.fetch` creates its handler that way). A leaf with no
+ * runtime imports: testing/serve-shell-request.ts installs its stub here when
+ * it loads, without importing rsc/handler.ts (which binds build-only virtual
+ * modules a flight-only test config does not alias).
+ */
+
+import type { LoadSSRModule } from "./types.js";
+
+let testLoader: LoadSSRModule | undefined;
+
+/**
+ * @internal Tests only: `router.prerender()` warms through `router.fetch`,
+ * and the rsc Vitest project cannot run `import.meta.viteRsc.loadModule`.
+ */
+export function setDefaultSSRModuleLoaderForTests(
+  loader: LoadSSRModule | undefined,
+): void {
+  testLoader = loader;
+}
+
+/** @internal Undefined everywhere but in tests. */
+export function defaultSSRModuleLoaderForTests(): LoadSSRModule | undefined {
+  return testLoader;
+}

package/src/rsc/types.ts

@@ -97,6 +97,14 @@ export interface RscPayload {
     locationState?: Record<string, unknown>;
   };
   returnValue?: { ok: boolean; data: unknown };
+  /**
+   * useActionState form state of a progressive-enhancement POST re-render
+   * (the value the SSR render received). Present only on that document; the
+   * browser entry passes it to hydrateRoot so the hydrated hook matches the
+   * server HTML instead of resetting to its initial state. A promise so a
+   * state Flight cannot serialize rejects this slot alone.
+   */
+  formState?: Promise<ReactFormState>;
 }
 
 /**

package/src/segment-boundary-content.ts

@@ -0,0 +1,25 @@
+import type { ReactNode } from "react";
+
+const IS_BROWSER = typeof window !== "undefined";
+
+/**
+ * What a RouteContentWrapper receives as `content`.
+ *
+ * Browser: hand over 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. A component that
+ * is already a promise (a Flight-streamed segment) is returned as is, since
+ * it can really be pending.
+ *
+ * Server: a fresh `Promise.resolve(component)` 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.
+ *
+ * @internal
+ */
+export function getBoundaryContent(component: ReactNode): ReactNode {
+  if (component instanceof Promise || IS_BROWSER) {
+    return component;
+  }
+  return Promise.resolve(component);
+}

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) {