@rangojs/router 0.20.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";
@@ -1961,8 +2023,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 +2032,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 +2078,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 +2112,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) {
@@ -2112,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
@@ -2230,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
@@ -2346,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.
@@ -2363,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).
@@ -2403,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).
@@ -2416,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,
@@ -2454,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
@@ -2515,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
@@ -2587,7 +2685,7 @@ async function captureAndStoreShell(
                 record,
                 `${sinceWriteMs} ms after this capture wrote it`,
               );
-              return "refused";
+              return refuse(stats, "record-expired");
             }
             stats.expired = {
               route,
@@ -2613,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
@@ -2628,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>;
 }
 
 /**
@@ -357,13 +365,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.
-   *
-   * Defaults to the auto-generated VERSION from `rsc-router:version` virtual module.
-   * Only set this if you need a custom versioning strategy.
+   * 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 VERSION from rsc-router:version
+   * @default createRouter({ version }), else the router's build versions
    */
   version?: string;
 

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);
+}