@rangojs/router 0.25.0 → 0.26.0

package/src/prerender/build-shell-capture.ts

@@ -106,8 +106,7 @@ export interface BuildShellCaptureOptions {
   /** Build-time env bindings (rango plugin buildEnv), if configured. */
   buildEnv?: unknown;
   /**
-   * The versions the SHIPPED build serves this router with (the build table,
-   * or the router's consumer-set version) — NOT the temp server's own
+   * The versions the SHIPPED build serves this router with (the build table) — NOT the temp server's own
    * version-plugin stamp. The serve-side isValidShellHit gate compares
    * entry.buildVersion against the running worker's ctx.version, which is the
    * document version; stamping the temp server's would make every build entry

package/src/prerender/writable-store.ts

@@ -22,9 +22,8 @@ import { paramsEqual } from "../router/params-util.js";
 export interface PrerenderKey {
   routerId: string;
   /**
-   * The owning router's cache version (its data version, or
-   * `createRouter({ version })`). Opaque: never set or read by app code; a
-   * store keys off it as given.
+   * The owning router's cache version (its data version). Opaque: never set
+   * or read by app code; a store keys off it as given.
    */
   version: string;
   routeName: string;

package/src/route-definition/dsl-helpers.ts

@@ -9,6 +9,8 @@ import type {
   TransitionConfig,
 } from "../types.js";
 import {
+  applyDocumentModeLoading,
+  documentModeLoader,
   getContext,
   getNamePrefix,
   getReverseScope,
@@ -928,17 +930,14 @@ const loader: RouteHelpers<any, any>["loader"] = (
 
   const name = `${ctx.namespace}.$${store.getNextIndex("loader")}`;
 
-  // Create loader entry with empty revalidate array. awaitBeforeFlush is
-  // resolved here, at DSL-evaluation time, for the same reason
-  // loading({ ssr: false }) is (below) — per-isSSR entry caching makes the
-  // flag request-mode-correct with no isSSR threading; see LoaderEntry.
-  // `bake` is the lane, the same on both evaluations.
+  // Create loader entry with empty revalidate array. `bake` is the lane, the
+  // same on both evaluations; a document evaluation adds awaitBeforeFlush at
+  // the push (documentModeLoader) — per-isSSR entry caching makes the flag
+  // request-mode-correct with no isSSR threading; see LoaderEntry.
   const loaderEntry: LoaderEntry = {
     loader: loaderDef,
     revalidate: [] as ShouldRevalidateFn<any, any>[],
     ...(optionsGiven?.ssr === false && { bake: true as const }),
-    ...(optionsGiven?.ssr === false &&
-      ctx.isSSR && { awaitBeforeFlush: true as const }),
     ...(optionsGiven?.prefetch === false && { prefetch: false as const }),
     // The declaring layout's / parallel's / cache()'s scope. A route's (and
     // an intercept's) loaders have none: they resolve from the route's name,
@@ -978,7 +977,9 @@ const loader: RouteHelpers<any, any>["loader"] = (
     validateUseItems(result, name, "loader", "use");
   }
 
-  ctx.parent.loader.push(loaderEntry);
+  ctx.parent.loader.push(
+    ctx.isSSR ? documentModeLoader(loaderEntry) : loaderEntry,
+  );
   return { name, type: "loader" } as LoaderItem;
 };
 
@@ -1006,12 +1007,11 @@ const loading: RouteHelpers<any, any>["loading"] = (component, options) => {
   const resolved =
     typeof component === "function" ? (component as () => any)() : component;
 
-  // If ssr: false and we're in SSR, set loading to false
-  if (options?.ssr === false && ctx.isSSR) {
-    parent.loading = false;
-  } else {
-    parent.loading = resolved;
-  }
+  // `loadingSsr` records ssr: false on both evaluations; a document drops
+  // the fallback (applyDocumentModeLoading).
+  parent.loading = resolved;
+  parent.loadingSsr = options?.ssr === false ? false : undefined;
+  if (ctx.isSSR) applyDocumentModeLoading(parent);
 
   // The flag means "what this fallback covers": without a fallback to show
   // there is nothing to defer behind. Recorded from `resolved`, not

package/src/router/manifest.ts

@@ -3,6 +3,7 @@ import { createRouteHelpers } from "../route-definition";
 import {
   getContext,
   runWithPrefixes,
+  getDocumentModeEntry,
   getIsolatedLazyParent,
   type EntryData,
   type MetricsStore,
@@ -120,12 +121,18 @@ export async function loadManifest(
       mountIndex !== undefined ? `#router.M${mountIndex}` : "#router";
 
     // For lazy entries, use the captured parent from include() context
-    // This ensures routes are registered under the correct layout hierarchy
+    // This ensures routes are registered under the correct layout hierarchy.
+    // The captured chain comes from an evaluation without isSSR: a document
+    // request takes its document-mode copy (getDocumentModeEntry, #1179).
     const lazyContext =
       entry.lazy && entry.lazyPatterns ? entry.lazyContext : null;
+    const capturedParent =
+      (lazyContext?.parent as EntryData | null | undefined) ?? Store.parent;
     const parentForContext = lazyContext
       ? getIsolatedLazyParent(
-          (lazyContext.parent as EntryData | null) ?? Store.parent,
+          isSSR && capturedParent
+            ? getDocumentModeEntry(capturedParent)
+            : capturedParent,
         )
       : Store.parent;
 

package/src/router/match-middleware/intercept-resolution.ts

@@ -232,8 +232,8 @@ async function handleCacheHitIntercept<TEnv>(
   const cachedSlot = segments.filter(isInterceptSegment);
   // A record stored before 0.25.0 carries the loaders' aggregate on the slot;
   // the loader segments below replace it. Build versions hash the router's
-  // code, so only a `version` pinned across the upgrade (createRouter's or
-  // the store's) still reads one.
+  // code, so an upgrade does not read one; a custom store that ignores
+  // versions can.
   for (const slot of cachedSlot) {
     delete slot.loaderDataPromise;
     delete slot.loaderIds;

package/src/router/router-interfaces.ts

@@ -479,12 +479,6 @@ export interface RangoInternal<
    */
   readonly nonce?: NonceProvider<TEnv>;
 
-  /**
-   * The consumer-set version (createRouter({ version })), used for both of the
-   * router's versions. Undefined when the router uses its build versions.
-   */
-  readonly version?: string;
-
   /**
    * URL patterns reference for build-time manifest generation
    */

package/src/router/router-options.ts

@@ -531,27 +531,6 @@ export interface RangoOptions<TEnv = any> {
    */
   nonce?: NonceProvider<TEnv>;
 
-  /**
-   * Version override. When set, this exact value is used for both of the
-   * router's versions: it keys the router's cached data (segments, `"use
-   * cache"` values, loader data) and its stored HTML (PPR shells,
-   * document-cache responses), is sent in payload metadata, and is what the
-   * browser's `_rsc_v` is compared with (a mismatch reloads the tab).
-   *
-   * Leave it unset for the default: rango computes two versions per router at
-   * build time, a data version from the router's server code and a document
-   * version that also covers the client assets. The same code builds to the
-   * same versions, so a deploy that does not change this router keeps its
-   * cache. In dev both are a stamp bumped on every RSC module edit.
-   *
-   * Set it to clear this router's cache on demand (change the value), or to
-   * tie the cache to your own release id (a per-deploy value clears the cache
-   * on every deploy).
-   *
-   * @default the router's build versions
-   */
-  version?: string;
-
   /**
    * TTL (in seconds) for the client-side in-memory prefetch cache.
    *

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

@@ -378,9 +378,10 @@ function getLoaderStore(
  * push funnel reads the pushReplayed owner, shell-capture.ts), so a replay
  * of that shell that serves this loader from its pin restores them owned
  * (HandleStore.pushRestored), on a document HIT and on a navigation alike.
- * This replay still runs there: 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 pin carries `runs`).
+ * This replay still runs there: the store drops its values that settle
+ * thenable-free, which the record already restored, and keeps the ones
+ * holding a promise the record could not keep (the reason the loader's pin
+ * carries `runs`).
  */
 async function replayLoaderHandles(
   encoded: string | undefined,

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

@@ -125,9 +125,11 @@ function someNestedThenable(
 /**
  * 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).
+ * objects, arrays and React element props. A settled push that holds one
+ * 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). A top-level thenable is judged by the value it
+ * settles to, on both sides (#1182).
  */
 export function holdsThenable(value: unknown): boolean {
   return someNestedThenable(value, () => true);

package/src/router-versions.ts

@@ -33,24 +33,24 @@ export type RouterVersionsTable = Readonly<
 /** Table key of the whole-build versions. Not a legal `$$id` (8 hex chars). */
 export const DEFAULT_ROUTER_VERSIONS_KEY = "*";
 
-/** One value for both versions: a consumer-set `version`, or the dev stamp. */
+/**
+ * One value for both versions: the dev stamp, the version a build-time shell
+ * capture is asked for, or a test's seed.
+ */
 export function uniformVersions(version: string): RouterVersions {
   return { data: version, document: version };
 }
 
 /**
- * The versions a router serves with under `table`: a consumer-set `version`
- * for both; else the router's own entry; else the whole-build pair, for a
- * router the table does not list. `undefined` when there is no table (dev,
- * tests) or it has neither entry. One function for the request handler and
+ * The versions a router serves with under `table`: the router's own entry,
+ * else the whole-build pair, for a router the table does not list.
+ * `undefined` when there is no table (dev, tests) or it has neither entry. One function for the request handler and
  * the build's shell capture, which must stamp what the handler will check.
  */
 export function resolveVersionsFrom(
   table: RouterVersionsTable | undefined,
   routerId: string | undefined,
-  override: string | undefined,
 ): RouterVersions | undefined {
-  if (override !== undefined) return uniformVersions(override);
   if (!table) return undefined;
   const pair =
     (routerId !== undefined && Object.hasOwn(table, routerId)

package/src/router.ts

@@ -170,7 +170,6 @@ export function createRouter<TEnv = any>(
     $$routeNames: staticRouteNames,
     $$sourceFile: injectedSourceFile,
     nonce,
-    version,
     prefetchCacheTTL: prefetchCacheTTLOption,
     prefetchCacheSize: prefetchCacheSizeOption,
     prefetchConcurrency: prefetchConcurrencyOption,
@@ -771,7 +770,7 @@ export function createRouter<TEnv = any>(
   // handler's overlay read makes (resolvePrerenderVersion), so the keys agree.
   const prerenderTrigger = createPrerenderTrigger<TEnv, {}>({
     routerId,
-    resolveVersion: () => resolvePrerenderVersion(routerId, version),
+    resolveVersion: () => resolvePrerenderVersion(routerId),
     isDev: isDevEnvironment,
     isViteDevServer,
     ensureManifest: () => ensureRouterManifest(routerId),
@@ -803,7 +802,7 @@ export function createRouter<TEnv = any>(
         {},
         {
           ...prerenderDeps,
-          versions: resolveRouterVersions(routerId, version),
+          versions: resolveRouterVersions(routerId),
         },
         undefined,
         isPassthrough,
@@ -812,7 +811,7 @@ export function createRouter<TEnv = any>(
         true,
       ),
     // A warm goes through router.fetch's handler: the one createRouter's own
-    // cache, nonce and version configure. An entry that passes them to
+    // cache and nonce configure. An entry that passes them to
     // createRSCHandler itself is not what a warm runs.
     resolveCacheConfig: (env, ctx) =>
       typeof cache === "function" ? cache(env, ctx) : cache,
@@ -1222,9 +1221,6 @@ export function createRouter<TEnv = any>(
     // Expose nonce provider for fetch
     nonce,
 
-    // Expose version for fetch
-    version,
-
     // Expose urlpatterns for runtime manifest generation
     get urlpatterns() {
       return storedUrlPatterns ?? undefined;
@@ -1292,7 +1288,6 @@ export function createRouter<TEnv = any>(
             router: router as any,
             cache,
             nonce,
-            version,
           }) as (
             request: Request,
             input: RouterRequestInput<TEnv>,

package/src/rsc/handler.ts

@@ -165,12 +165,8 @@ export function createRSCHandler<
   TRoutes extends Record<string, string> = Record<string, string>,
 >(options: CreateRSCHandlerOptions<TEnv, TRoutes>) {
   const { router, nonce: nonceProvider } = options;
-  // A consumer-set version (this option, else createRouter({ version })) is
-  // used for both; otherwise the router's own pair from the build.
-  const versions = resolveRouterVersions(
-    router.id,
-    options.version ?? router.version,
-  );
+  // The router's own pair from the build.
+  const versions = resolveRouterVersions(router.id);
   // Everything the handler itself versions is tied to the HTML a tab holds:
   // payload metadata (what the browser echoes as `_rsc_v`), the reload check,
   // shell stamping and gating, the rango state value. The data version is only
@@ -548,7 +544,7 @@ export function createRSCHandler<
         resolvedPrerender = {
           config: prerenderConfig,
           routerId: router.id,
-          version: resolvePrerenderVersion(router.id, router.version),
+          version: resolvePrerenderVersion(router.id),
         };
       }
     }

package/src/rsc/shell-capture-constants.ts

@@ -208,9 +208,10 @@ export const SHELL_CAPTURE_TASK_HARD_CAP_MS = 25_000;
  * (ShellCaptureDebugEvent.refusal, `caches.refusal` on a `router.prerender()`
  * result): `identity` (a request-scoped read: cookies(), headers(), the
  * theme, a `{ cache: false }` variable), `dynamic` (`ctx.dynamic()`),
- * `loader` (a `{ ssr: false }` loader rejected, or settled with
- * redirect()/notFound()), `no-record` (no doc record: the route's cache()
- * refused the write, or the handler output failed), `handles` (a pushed
+ * `loader` (a `{ ssr: false }` loader rejected, settled with
+ * redirect()/notFound(), or a promise it pushed rejected),
+ * `no-record` (no doc record: the route's cache() refused the write, or the
+ * handler output failed), `handles` (a pushed
  * handle value did not finish encoding), `size` (over the store's value
  * limit), `record-expired` (the route cache() record the capture wrote ran
  * out first), `invalidated` (a tag of the shell was invalidated after the

package/src/rsc/shell-capture.ts

@@ -508,6 +508,11 @@ function refuse(
   return "refused";
 }
 
+/** A bake-lane loader's promise push, as a refusal names it. */
+function describeLoaderPromisePush(push: LoaderPromisePush): string {
+  return `the promise the loader "${push.loaderId}" pushed to the handle "${push.handleName}"`;
+}
+
 /** 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 " +
@@ -1667,8 +1672,9 @@ export type CaptureRecordOutcome =
  * component showed one value in the prelude and another on every HIT.
  *
  * Order, all bounded by the one capture deadline (`ppr.captureTimeout`):
- * top-level handle promises, the handler pushes' nested promises, and the
- * bake-lane loader containers settle first (the record encodes the handles
+ * top-level handle promises (a bake-lane loader's pushed promises among
+ * them, #1182), the handler pushes' nested promises, and the bake-lane
+ * loader containers settle first (the record encodes the handles
  * a HIT restores, and its handle encode has its own 5s timeout that must
  * never be the one that fires); then the capture's onResponse callbacks fire
  * with a synthetic 200 (the implicit doc scope's cacheRoute, an explicit
@@ -1711,7 +1717,33 @@ export async function settleCaptureRecord(
   if (!settled.done) {
     if (refuseOnCaptureGuard(capture.key, derivedCtx))
       return { kind: "refused", refusal: guardRefusal(derivedCtx) };
-    return { kind: "timeout", reason: HANDLER_OUTPUT_TIMEOUT_REASON };
+    const pending = derivation.loaderPromisePushes.find(
+      (p) => p.state === "pending",
+    );
+    return {
+      kind: "timeout",
+      reason: pending
+        ? `${describeLoaderPromisePush(pending)} did not settle within ppr.captureTimeout`
+        : HANDLER_OUTPUT_TIMEOUT_REASON,
+    };
+  }
+  // A rejected value must not bake, and the record's encode would fail on
+  // it anyway: refuse before the write starts. A guard trip in that promise
+  // names the read instead.
+  const rejected = derivation.loaderPromisePushes.find(
+    (p) => p.state === "rejected",
+  );
+  if (rejected) {
+    if (refuseOnCaptureGuard(capture.key, derivedCtx))
+      return { kind: "refused", refusal: guardRefusal(derivedCtx) };
+    warnCaptureRefusedOnce(
+      capture.key,
+      `${describeLoaderPromisePush(rejected)} rejected during capture; a ` +
+        "failed value must not bake into the shared shell. Catch it and push " +
+        "a fallback, or push it from a loader without ssr: false.",
+      PPR_LANE_HINT,
+    );
+    return { kind: "refused", refusal: "loader" };
   }
 
   const callbacks = derivedCtx._onResponseCallbacks?.splice(0) ?? [];
@@ -2006,6 +2038,20 @@ export interface CaptureContextDerivation {
    * record encodes its handles, so that encode never races a pending value.
    */
   handlerPushesSettled: () => Promise<void>;
+  /**
+   * Every promise a bake-lane loader body pushed (#1182), in push order.
+   * The record-first step waits for them (they are in the recorded cut) and
+   * names the loader and the handle of one that rejects or misses the
+   * deadline.
+   */
+  loaderPromisePushes: readonly LoaderPromisePush[];
+}
+
+/** A promise a bake-lane loader pushed at capture, owned by that loader. */
+export interface LoaderPromisePush {
+  loaderId: string;
+  handleName: string;
+  state: "pending" | "fulfilled" | "rejected";
 }
 
 /**
@@ -2041,30 +2087,35 @@ export function deriveShellCaptureContext(
   //    masked), their pushes are in the captured HTML (<head> title/meta,
   //    useHandle echoes), and a HIT does not run a promise-free bake-lane
   //    loader (loader-cache.ts), so the stored record carries them: each
-  //    settled, thenable-free push from a loader body keeps that loader as
-  //    `owner` (HandleStore.push), the record stores it
+  //    push from a loader body whose value, once settled, is thenable-free
+  //    keeps that loader as `owner` (HandleStore.push), the record stores it
   //    (CachedEntryData.handleOwners), and a replay that serves the loader
-  //    from its pin restores it through pushRestored (restoreHandles). Those
-  //    copies stand: a promise-carrying bake-lane loader that runs on the
-  //    replay reads the store, so its settled pushes (and those replayed
-  //    inside its body) are dropped and only its thenable ones are added. A
-  //    loader the replay does not serve from a pin is a hole: one the route
-  //    also runs on the live lane, or one whose pin the entry lost. Its run
-  //    replaces its copies (pushPlaceholder, #936), those of the
-  //    dependencies it awaits included (they are credited to it). Nested
-  //    thenables stay masked (the promise shape is the liveness
-  //    declaration, mask-nested.ts). A deferred (thenable) push,
-  //    one with masked nested promises, or one outside a loader body (a
-  //    loader-cache replay names its loader: pushReplayed below) stays
-  //    tagged (HandleStore.push loaderPush) so the
-  //    handle encode cannot stall on a never-resolving mask. A tagged push
-  //    is out of the record (captureHandles) and out of the capture's own
-  //    render (resolvedHandleStream `recordedOnly`, issue #1035): the
-  //    prelude is rendered from what the record keeps, which is what a HIT
-  //    hydrates with. The loader records then carry `runs: 1` so a HIT runs
-  //    those bodies for them, and what they push reaches the client after
+  //    from its pin restores it through pushRestored (restoreHandles). A
+  //    pushed promise (push(promise), .defer()) is judged by its settled
+  //    value, as push(await promise) would be (#1182): the record-first step
+  //    waits for it under the capture deadline, and one that rejects or
+  //    misses the deadline refuses the capture. Those copies stand: a
+  //    promise-carrying bake-lane loader that runs on the replay reads the
+  //    store, so its pushes that settle thenable-free (and those replayed
+  //    inside its body) are dropped and only the ones holding a promise are
+  //    added. A loader the replay does not serve from a pin is a hole: one
+  //    the route also runs on the live lane, or one whose pin the entry
+  //    lost. Its run replaces its copies (pushPlaceholder, #936), those of
+  //    the dependencies it awaits included (they are credited to it). Nested
+  //    thenables stay masked (the promise shape is the liveness declaration,
+  //    mask-nested.ts). A push whose settled value holds a masked nested
+  //    promise, one credited to a live-lane body, or one no body or replay
+  //    names (a loader-cache replay names its loader: pushReplayed below)
+  //    stays tagged (HandleStore.push loaderPush) so the handle encode cannot
+  //    stall on a never-resolving mask. A tagged push is out of the record
+  //    (captureHandles) and out of the capture's own render
+  //    (resolvedHandleStream `recordedOnly`, issue #1035): the prelude is
+  //    rendered from what the record keeps, which is what a HIT hydrates
+  //    with. The loader records then carry `runs: 1` so a HIT runs those
+  //    bodies for them, and what they push reaches the client after
   //    hydration (HandleStore.freezeDocumentSnapshot).
   const handlerPushSettles: Promise<void>[] = [];
+  const loaderPromisePushes: LoaderPromisePush[] = [];
   // A replay (a loader-cache HIT, loader-cache.ts replayLoaderHandles, or a
   // route cache() record's owned values, restoreHandles) re-pushes a loader's
   // recorded values through pushReplayed or pushPlaceholder, which call
@@ -2118,39 +2169,62 @@ export function deriveShellCaptureContext(
       if (report.thenable) maskedNestedThenable = true;
       return masked;
     };
+    // The loader the push is credited to (see the funnel comment above). A
+    // push under a live-lane loader's body, at any depth, is that hole's
+    // output: its live run replaces it on a HIT and a navigation. Otherwise
+    // the first loader around the push that the route registers decides: a
+    // bake-lane one keeps the push under the innermost body, and a
+    // dependency on neither lane is walked past. A replay of a hole's push
+    // is that hole's, unless a live-lane body around it takes it first.
+    const live = liveLaneOwner();
+    const bodyLoaderId = live ?? getCurrentLoaderBodyId() ?? replayOwner;
     let masked: unknown;
-    let loaderPush = true;
     let owner: string | undefined;
-    if (isThenable(value)) {
-      // Deferred (thenable) loader pushes always keep the tag — the
-      // carve-out below is for settled values only. Promise.resolve first: a
-      // loader cache() entry replays a deferred push as the thenable Flight
-      // decoded it to, whose then() returns nothing, and the slot was
-      // `undefined` (the empty element of issue #1035).
-      masked = Promise.resolve(value).then(mask);
-    } else {
+    if (!isThenable(value)) {
       masked = mask(value);
-      if (!maskedNestedThenable) {
-        // A settled, thenable-free push from a loader body is shell
-        // material (see the funnel comment above): only bake-lane loaders
-        // and the loaders they await run at capture, and a HIT does not run
-        // a promise-free bake-lane loader (loader-cache.ts), so the record
-        // keeps the push under the loader that made it. A push under a
-        // live-lane loader's body, at any depth, is that hole's output: it
-        // is credited to the hole, whose live run replaces it on a HIT and
-        // a navigation. The first loader around the push that the route
-        // registers decides: a bake-lane one keeps the push under the
-        // innermost body, and a dependency on neither lane is walked past. A
-        // replay of a hole's push is that hole's, unless a live-lane body
-        // around it takes it first.
-        const bodyLoaderId =
-          liveLaneOwner() ?? getCurrentLoaderBodyId() ?? replayOwner;
-        loaderPush = bodyLoaderId === undefined;
-        if (!loaderPush) owner = bodyLoaderId;
-      }
+      if (!maskedNestedThenable) owner = bodyLoaderId;
+    } else if (live === undefined && bodyLoaderId !== undefined) {
+      // Owned now, judged by its settled value (funnel comment above).
+      // Promise.resolve first: a loader cache() entry replays a deferred
+      // push as the thenable Flight decoded it to, whose then() returns
+      // nothing (issue #1035). The retag runs inside the slot's own then(),
+      // so it lands before the wait on it (settleCaptureRecord) resumes and
+      // the record encodes. The state handler is attached now, which also
+      // marks a rejection as handled.
+      const slot: Promise<unknown> = Promise.resolve(value).then((settled) => {
+        const judged = mask(settled);
+        if (maskedNestedThenable) {
+          freshHandleStore.unrecordPush(handleName, segmentId, slot);
+          derivedCtx._shellCaptureUnrecordedLoaderPush = true;
+        }
+        return judged;
+      });
+      const push: LoaderPromisePush = {
+        loaderId: bodyLoaderId,
+        handleName,
+        state: "pending",
+      };
+      slot.then(
+        () => {
+          push.state = "fulfilled";
+        },
+        () => {
+          push.state = "rejected";
+        },
+      );
+      loaderPromisePushes.push(push);
+      masked = slot;
+      owner = bodyLoaderId;
+    } else {
+      // A hole's promise, or one no body or replay names: tagged. Nothing
+      // awaits the slot at capture, so its rejection is handled here.
+      const tagged = Promise.resolve(value).then(mask);
+      tagged.catch(() => {});
+      masked = tagged;
     }
     // A push the record cannot keep reaches a HIT only from a live run of
     // its loader, so the loader records ask for one (runs: 1).
+    const loaderPush = owner === undefined;
     if (loaderPush) derivedCtx._shellCaptureUnrecordedLoaderPush = true;
     rawCapturePush(handleName, segmentId, masked, loaderPush, owner);
   };
@@ -2271,6 +2345,7 @@ export function deriveShellCaptureContext(
     freshHandleStore,
     handlerPushesSettled: () =>
       Promise.all(handlerPushSettles).then(() => undefined),
+    loaderPromisePushes,
   };
 }
 

package/src/rsc/types.ts

@@ -369,15 +369,6 @@ export interface CreateRSCHandlerOptions<
    */
   cache?: HandlerCacheConfig | ((env: TEnv) => HandlerCacheConfig);
 
-  /**
-   * Version override for this handler. Same meaning as
-   * `createRouter({ version })`, which it takes precedence over: this exact
-   * value is used for both of the router's versions.
-   *
-   * @default createRouter({ version }), else the router's build versions
-   */
-  version?: string;
-
   /**
    * Nonce provider for Content Security Policy (CSP).
    *