@rangojs/router 0.19.1 → 0.21.0

package/src/router/router-options.ts

@@ -502,13 +502,23 @@ export interface RangoOptions<TEnv = any> {
   nonce?: NonceProvider<TEnv>;
 
   /**
-   * RSC version string included in metadata.
-   * The browser sends this back on partial requests to detect version mismatches.
-   *
-   * Defaults to the auto-generated VERSION from `@rangojs/router:version` virtual module.
-   * Only set this if you need a custom versioning strategy.
-   *
-   * @default VERSION from @rangojs/router:version
+   * 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;
 

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

@@ -50,19 +50,29 @@ import {
   type LoaderIdentityRead,
 } from "../../server/context.js";
 import type { HandlerContext, InternalHandlerContext } from "../../types.js";
-import type { HandleStore } from "../../server/handle-store.js";
+import type {
+  HandleStore,
+  RecordAuthority,
+} from "../../server/handle-store.js";
 import type { CacheItemResult } from "../../cache/types.js";
 import {
   startHandleCapture,
   type HandleCapture,
 } from "../../cache/handle-capture.js";
-import { encodeHandles, decodeHandles } from "../../cache/handle-snapshot.js";
+import {
+  appendHandles,
+  encodeHandles,
+  decodeHandles,
+  type OwnedPushDelivery,
+} from "../../cache/handle-snapshot.js";
+import type { ShellLoaderSeedEntry } from "../../cache/shell-snapshot.js";
 import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
 import { runIdentityExempt } from "../../cache/cache-exec-scope.js";
 import {
   getRequestContext,
   _getRequestContext,
   runWithRequestContext,
+  type RequestContext,
 } from "../../server/request-context.js";
 import { observePhase, PHASES } from "../instrument.js";
 import {
@@ -256,26 +266,6 @@ function chainLoaderEntries(entry: EntryData): readonly LoaderEntry[] {
   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
@@ -295,6 +285,75 @@ export function routeLoaderLanes(
   return lanes;
 }
 
+/**
+ * The pins this request serves loaders from, by loader id: the seed a
+ * document HIT tail (serveShellHit) or a navigation replay whose doc record
+ * hit (matchPartialWithPprReplay) armed from the shell entry's loader
+ * records. A capture serves none: its bake-lane loaders execute.
+ *
+ * The one answer to "is this loader served from the shell record on this
+ * request", for its value (resolveLoaderData) and for the record's copies of
+ * its handle pushes (loaderPins): both look the loader up here and nowhere
+ * else. A condition that makes pins, or one loader's pin, not apply belongs
+ * here or in the seed's decode (shell-snapshot.ts buildShellLoaderSeed),
+ * never after a lookup, or the two disagree: issues #1001 and #1003 were the
+ * pushes decided from the request's type while the value was decided from
+ * the pin.
+ */
+function servedPins(
+  reqCtx: RequestContext<any> | undefined,
+): ReadonlyMap<string, ShellLoaderSeedEntry> | undefined {
+  return isShellCaptureActive(reqCtx) ? undefined : reqCtx?._shellLoaderSeed;
+}
+
+/**
+ * What a record restored on a request over the matched chain `entries` is to
+ * each loader's handle pushes (HandleStore RecordAuthority), from the pins
+ * the request serves (servedPins). Call it when the record hits: the pins are
+ * read here, once, because a navigation replay arms its seed for the match
+ * only and the store asks while loader bodies run.
+ *
+ * Each side applies its own lane to the pin. The value is per registration
+ * (resolveLoaderData: an `ssr: false` registration is served its pin). The
+ * pushes are per loader: one the route also registers without `ssr: false`
+ * is a hole whatever its other registration's pin says, because the capture
+ * credited its pushes to the live registration's run (routeLoaderLanes).
+ *
+ * A dependency the route does not register has no pin of its own, and the
+ * record does not name the loader that ran it at capture: its copies stand
+ * only while every `ssr: false` loader is pinned (exact when the pins are
+ * all there or all gone).
+ */
+export function loaderPins(
+  entries: readonly EntryData[],
+  reqCtx: RequestContext<any> | undefined,
+): OwnedPushDelivery {
+  const pins = servedPins(reqCtx);
+  let lanes: ReadonlyMap<string, "live" | "bake"> | undefined;
+  let dependency: RecordAuthority | undefined;
+  return (loaderId) => {
+    lanes ??= routeLoaderLanes(entries);
+    const lane = lanes.get(loaderId);
+    if (lane === "live") return "hole";
+    if (lane === "bake") {
+      const pin = pins?.get(loaderId);
+      return pin ? (pin.complete ? "pin" : "copies") : "hole";
+    }
+    if (dependency === undefined) {
+      let bakeLane = 0;
+      let pinned = 0;
+      for (const [id, registered] of lanes) {
+        if (registered !== "bake") continue;
+        bakeLane++;
+        if (pins?.has(id)) pinned++;
+      }
+      dependency =
+        bakeLane > 0 && pinned === bakeLane ? "copies" : "placeholders";
+    }
+    return dependency;
+  };
+}
+
 function getLoaderStore(
   loaderEntry: LoaderEntry,
 ): import("../../cache/types.js").SegmentCacheStore | null {
@@ -323,11 +382,12 @@ function getLoaderStore(
  * replay; and the store reads the body scope to tell a live push from a
  * 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 (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`).
+ * 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`).
  */
 async function replayLoaderHandles(
   encoded: string | undefined,
@@ -338,34 +398,7 @@ async function replayLoaderHandles(
 ): Promise<void> {
   const recorded = encoded ? await decodeHandles(encoded) : {};
   if (!recorded) return;
-  const delivers = new Map<string, boolean>();
-  const claims = (owner: string): boolean => {
-    let deliver = delivers.get(owner);
-    if (deliver === undefined) {
-      deliver = claim ? claim(owner) : true;
-      delivers.set(owner, deliver);
-    }
-    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();
-  }
+  appendHandles(recorded, handleStore, segmentId, claim, cachedLoaderId);
 }
 
 /**
@@ -492,10 +525,11 @@ export function resolveLoaderData<TEnv>(
     return createMaskedLoaderPromise();
   }
 
-  if (bakeSegmentKey) {
-    const seed = reqCtx?._shellLoaderSeed;
-    if (seed && seed.has(bakeSegmentKey)) {
-      const recorded = seed.get(bakeSegmentKey)!;
+  // `bake`: the pin is the `ssr: false` registration's. The caller's key is
+  // passed for an unflagged loader of an entry without loading() too.
+  if (bakeSegmentKey && loaderEntry.bake) {
+    const recorded = servedPins(reqCtx)?.get(loaderEntry.loader.$$id);
+    if (recorded) {
       if (!recorded.holes) {
         // Pin-first (hole-free record): the pinned container is what the
         // payload serves (recorded paths win wholesale), resolved
@@ -800,7 +834,8 @@ function executeLoaderData<TEnv>(
     });
 
     // An entry without handles (none recorded, or dropped by an encode
-    // timeout) replays none, and still stands for a hole's shell copies.
+    // timeout) replays none, and still takes the place of the loader's
+    // placeholders (appendHandles): a claimed entry is the loader's source.
     if (cachedRead && handleStore && owningSegmentId) {
       await replayLoaderHandles(
         hitHandles,

package/src/router-versions.ts

@@ -0,0 +1,60 @@
+/**
+ * Per-router cache versions: the shapes shared by the build (which computes
+ * them, vite/discovery/build-versions.ts) and the runtime (which reads them,
+ * server/build-version-table.ts). No imports, so the Vite plugin bundle can
+ * use it without resolving the `@rangojs/router:version` virtual module.
+ *
+ * Design: docs/design/per-app-cache-version.md.
+ */
+
+/**
+ * The two versions one `createRouter()` serves with.
+ *
+ * - `data` keys cached RSC data: segment entries, `"use cache"` values and
+ *   loader data. It follows the router's server code only.
+ * - `document` keys stored HTML (PPR shells, document-cache responses), is the
+ *   value the browser echoes as `_rsc_v`, and stamps `ShellCacheEntry.buildVersion`.
+ *   It follows the server code and the client asset URLs.
+ */
+export interface RouterVersions {
+  readonly data: string;
+  readonly document: string;
+}
+
+/**
+ * The build's table as the `@rangojs/router:version` module exports it:
+ * router id to `[data, document]`. {@link DEFAULT_ROUTER_VERSIONS_KEY} holds
+ * the whole-build pair, used for a router the build could not attribute.
+ */
+export type RouterVersionsTable = Readonly<
+  Record<string, readonly [data: string, document: string]>
+>;
+
+/** 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. */
+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 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)
+      ? table[routerId]
+      : undefined) ?? table[DEFAULT_ROUTER_VERSIONS_KEY];
+  return pair ? { data: pair[0], document: pair[1] } : undefined;
+}

package/src/rsc/full-payload.ts

@@ -52,8 +52,12 @@ export function buildFullPayload(
       rootLayout: ctx.router.rootLayout,
       // Full render: resolve deferred handle values server-side so SSR markup and
       // the first sync useHandle read see resolved values. Partial payloads
-      // (rsc-rendering.ts) keep streaming (handleStore.stream()).
-      handles: resolvedHandleStream(handleStore),
+      // (rsc-rendering.ts) keep streaming (handleStore.stream()). A shell
+      // capture renders from what its record keeps (resolvedHandleStream).
+      handles: resolvedHandleStream(
+        handleStore,
+        reqCtx._shellCaptureRun === true,
+      ),
       // Post-handler-barrier pushes (streaming loader ctx.handle() writes)
       // stream here; the client applies them after hydration. Instantly
       // complete when the loader lane is idle — including PPR shell capture,

package/src/rsc/handler-context.ts

@@ -14,6 +14,11 @@ import type { SSRStreamMode } from "../router/router-options.js";
 
 export interface HandlerContext<TEnv = unknown> {
   router: RangoInternal<TEnv, any>;
+  /**
+   * The router's DOCUMENT version (router-versions.ts): payload metadata, the
+   * `_rsc_v` reload check, and PPR shell stamping and gating. The data version
+   * is not here; cache stores read it from the request context.
+   */
   version: string;
   devDiscoveryEpoch?: number;
   renderToReadableStream: RSCDependencies["renderToReadableStream"];

package/src/rsc/handler.ts

@@ -1,5 +1,4 @@
 /// <reference types="@vitejs/plugin-rsc/types" />
-/// <reference path="../vite/plugins/version.d.ts" />
 /**
  * RSC Request Handler
  *
@@ -47,7 +46,7 @@ import {
   type ResponseRouteMatch,
 } from "./response-route-handler.js";
 import { nonce as nonceToken, resolveProviderNonce } from "./nonce.js";
-import { VERSION } from "@rangojs/router:version";
+import { resolveRouterVersions } from "../server/build-version-table.js";
 import type { ErrorPhase } from "../types.js";
 import type { RouterRequestInput } from "../router/router-interfaces.js";
 import {
@@ -169,7 +168,18 @@ export function createRSCHandler<
   TEnv = unknown,
   TRoutes extends Record<string, string> = Record<string, string>,
 >(options: CreateRSCHandlerOptions<TEnv, TRoutes>) {
-  const { router, version = VERSION, nonce: nonceProvider } = options;
+  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,
+  );
+  // 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
+  // a cache-key prefix, read by the stores from the request context.
+  const version = versions.document;
 
   // Handler-owned registry of explicit per-scope stores from cache({ store }).
   // Lives in the closure so it is scoped per handler (multi-router deployments
@@ -572,7 +582,7 @@ export function createRSCHandler<
       executionContext: executionCtx,
       themeConfig: router.themeConfig,
       stateCookieName: router.resolvedStateCookieName,
-      version,
+      versions,
     });
     if (unmarkedRequest) requestContext._shellForcedMiss = true;
     // Gate on the SAME enabled-semantics withTimeout uses (isTimeoutEnabled):

package/src/rsc/rsc-rendering.ts

@@ -1336,7 +1336,7 @@ async function matchPartialWithPprReplay<TEnv>(
   // null and the seeded record could not have been consulted, which used to
   // read as a misleading `snapshot-miss` AFTER two wasted getShell reads.
   // Same predicate as resolveNavigation, decided before any store I/O.
-  if (!getNavigationContextHeader(request)) {
+  if (!getNavigationContextHeader(request, url.origin)) {
     return runMatch({ outcome: "BYPASS", reason: "no-navigation-context" });
   }
   // Fragment passthrough (#700), extended to partial replay. Navigation
@@ -1745,6 +1745,17 @@ function serveShellHit(
     // close over that same context or a streaming tail inherits the base
     // context's premature non-streaming handle snapshot.
     wireRenderBarrier(tailCtx, handleStore);
+    // The tail's render barrier resolves once its record is replayed and
+    // before a loader runs (cache-lookup.ts withCacheLookup, yieldFromStore).
+    // The store then holds what the prelude was rendered from, so that is
+    // the snapshot the document hydrates with; what this request's loaders
+    // do to it afterwards reaches the client after hydration
+    // (HandleStore.freezeDocumentSnapshot, issue #1035).
+    const resolveRenderBarrier = tailCtx._resolveRenderBarrier;
+    tailCtx._resolveRenderBarrier = (segments) => {
+      handleStore.freezeDocumentSnapshot();
+      resolveRenderBarrier(segments);
+    };
     return tailCtx;
   };
 

package/src/rsc/shell-build-manifest.ts

@@ -11,8 +11,9 @@
  * served through the same serveShellHit as a captured one.
  *
  * Lifecycle:
- * - No expiry until the next deploy — the buildVersion gate retires entries
- *   the moment a new build ships (a new manifest replaces them anyway).
+ * - No expiry until the next deploy: every build ships its own manifest, and
+ *   its entries carry that build's document version for the router, which is
+ *   what the buildVersion gate compares.
  * - `ppr.ttl` drives STALENESS ONLY: past createdAt + ttl the entry still
  *   serves, but a runtime recapture is scheduled — SWR is the UPGRADE path
  *   from build entry to fresher runtime entry, not the bootstrap path. The
@@ -90,9 +91,10 @@ function loadManifest(): Promise<ShellManifestModule | null> {
  * Only the per-request gates (tag markers, staleness) stay outside the memo;
  * the document HIT decodes the prelude once per serve (openShellDocument),
  * partial replay never does. `null` memoizes a failed verdict —
- * deterministically invalid. Spec-only keying is sound because buildVersion is
- * process-constant on the manifest path (folded into the shipped worker; dev
- * never loads a manifest).
+ * deterministically invalid. Keyed by the asking router's document version as
+ * well as the spec: the manifest key is pathname-only (shell-manifest-key.ts),
+ * so under a host router two routers with different versions can ask about one
+ * record.
  */
 const validatedSpecs = new Map<string, ValidatedBuildShellEntry | null>();
 
@@ -110,7 +112,8 @@ async function validatedManifestRecord(
   spec: string,
   buildVersion: string,
 ): Promise<ValidatedBuildShellEntry | undefined> {
-  let verdict = validatedSpecs.get(spec);
+  const memoKey = `${buildVersion}\u0000${spec}`;
+  let verdict = validatedSpecs.get(memoKey);
   if (verdict === undefined) {
     const record = (await mod.loadShellAsset(spec)).default;
     verdict =
@@ -118,7 +121,7 @@ async function validatedManifestRecord(
       hasIntactShellPayload(record.entry)
         ? (record as ValidatedBuildShellEntry)
         : null;
-    validatedSpecs.set(spec, verdict);
+    validatedSpecs.set(memoKey, verdict);
   }
   return verdict ?? undefined;
 }

package/src/rsc/shell-capture.ts

@@ -1961,8 +1961,8 @@ export function deriveShellCaptureContext(
   //    (settleCaptureRecord) can wait for its promises, top-level and nested,
   //    before the doc record encodes the handles a HIT replays. A route
   //    cache() record's restore (handle-snapshot.ts restoreHandles) lands
-  //    here too: a value it restores through pushReplayed keeps that loader
-  //    as owner, so a HIT restores it as that loader's (pushRestored).
+  //    here too: a value it restores as a placeholder keeps that loader as
+  //    owner, so a HIT restores it as that loader's (pushRestored).
   //  - DSL-LOADER pushes. Only bake-lane { ssr: false } loaders and the
   //    loaders they await via ctx.use execute at capture (live loaders are
   //    masked), their pushes are in the captured HTML (<head> title/meta,
@@ -1970,28 +1970,33 @@ export function deriveShellCaptureContext(
   //    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
-  //    (CachedEntryData.handleOwners), and the HIT restores it through
-  //    pushRestored. Those copies stand: a promise-carrying bake-lane loader
-  //    that runs on the HIT 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 route also runs on the live lane is a hole: its
-  //    live run replaces its copies (pushReplayed, #936), those of the
+  //    (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; only the
-  //    captureHandles cache-write call site excludes tagged pushes, and the
-  //    loader records then carry `runs: 1` so a HIT runs those bodies for
-  //    them.
+  //    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>[] = [];
   // 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, which calls push() outside any
-  // loader body: name that loader for the funnel so the record keeps them
-  // under it too.
+  // recorded values through pushReplayed or pushPlaceholder, which call
+  // push() outside any loader body: name that loader for the funnel so the
+  // record keeps them under it too.
   let replayOwner: string | undefined;
   // The live-lane loader whose body a push is made in, at any depth, unless
   // a bake-lane loader's body is nearer (createMatchContextForFull sets the
@@ -2011,15 +2016,17 @@ export function deriveShellCaptureContext(
         : undefined)
     );
   };
-  const rawPushReplayed = freshHandleStore.pushReplayed.bind(freshHandleStore);
-  freshHandleStore.pushReplayed = (handleName, segmentId, value, loaderId) => {
-    replayOwner = loaderId;
-    try {
-      rawPushReplayed(handleName, segmentId, value, loaderId);
-    } finally {
-      replayOwner = undefined;
-    }
-  };
+  for (const copy of ["pushReplayed", "pushPlaceholder"] as const) {
+    const raw = freshHandleStore[copy].bind(freshHandleStore);
+    freshHandleStore[copy] = (handleName, segmentId, value, loaderId) => {
+      replayOwner = loaderId;
+      try {
+        raw(handleName, segmentId, value, loaderId);
+      } finally {
+        replayOwner = undefined;
+      }
+    };
+  }
   const rawCapturePush = freshHandleStore.push.bind(freshHandleStore);
   freshHandleStore.push = (
     handleName: string,
@@ -2043,8 +2050,11 @@ export function deriveShellCaptureContext(
     let owner: string | undefined;
     if (isThenable(value)) {
       // Deferred (thenable) loader pushes always keep the tag — the
-      // carve-out below is for settled values only.
-      masked = value.then(mask);
+      // 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 {
       masked = mask(value);
       if (!maskedNestedThenable) {

package/src/rsc/types.ts

@@ -357,13 +357,11 @@ export interface CreateRSCHandlerOptions<
   cache?: HandlerCacheConfig | ((env: TEnv) => HandlerCacheConfig);
 
   /**
-   * RSC version string included in metadata.
-   * The browser sends this back on partial requests to detect version mismatches.
+   * 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.
    *
-   * Defaults to the auto-generated VERSION from `rsc-router:version` virtual module.
-   * Only set this if you need a custom versioning strategy.
-   *
-   * @default VERSION from rsc-router:version
+   * @default createRouter({ version }), else the router's build versions
    */
   version?: string;