@rangojs/router 0.0.0-experimental.9c9afef3 → 0.0.0-experimental.a014d2b7

package/src/browser/react/NavigationProvider.tsx

@@ -28,6 +28,60 @@ import { NonceContext } from "./nonce-context.js";
 import type { ResolvedThemeConfig, Theme } from "../../theme/types.js";
 import { cancelAllPrefetches } from "../prefetch/queue.js";
 import { handleNavigationEnd } from "../scroll-restoration.js";
+import { createAppShellRef, type AppShellRef } from "../app-shell.js";
+import { startConnectionWarmup } from "../connection-warmup.js";
+import { debugLog } from "../logging.js";
+import { cloneHandleData } from "../navigation-store.js";
+import { collectHandleData } from "../../handle.js";
+import { Meta } from "../../handles/meta.js";
+import type { MetaDescriptor } from "../../router/types.js";
+import {
+  HEAD_RESOLVE_HANDLE_NAMES,
+  hasDeferredHandleValue,
+  resolveDeferredHandleValues,
+} from "./deferred-handle-resolution.js";
+
+/** Meta handle-name key. Meta is the only head-placed handle whose consumer
+ *  use()s a deferred value above the route <Suspense>, so it must be resolved in
+ *  the store before apply; every other handle keeps the promise contract. */
+const META = "__rsc_router_meta__";
+
+/**
+ * Carry the previous page's COLLECTED Meta forward so the title is kept (no
+ * blank) while a deferred Meta resolves on a soft navigation.
+ *
+ * Why a carry-forward and not just preserving the previous Meta data: handle
+ * collection (useHandle/MetaTags) is driven by the event controller's
+ * `segmentOrder`, which becomes the NEW route's order so the synchronous
+ * breadcrumbs render immediately. The previous route's title lives under a
+ * segment that is NOT in the new order, so it would stop being collected — the
+ * title would fall back to the layout default. Re-keying the previous COLLECTED
+ * descriptors under a segment that IS in the new order keeps them visible.
+ *
+ * Title descriptors are wrapped as `{ title: { absolute } }` so re-collection
+ * under a (possibly template-bearing) new layout does not re-apply a title
+ * template to an already-final title. Promise and default (charSet/viewport)
+ * descriptors are dropped: Promise ones would suspend MetaTags, and the defaults
+ * are re-added by collectMeta.
+ */
+function carriedPreviousMeta(prev: MetaDescriptor[]): MetaDescriptor[] {
+  const out: MetaDescriptor[] = [];
+  for (const d of prev) {
+    if (d && typeof (d as { then?: unknown }).then === "function") continue;
+    const base = d as Exclude<MetaDescriptor, Promise<unknown>>;
+    if ("charSet" in base) continue;
+    if ("name" in base && (base as { name?: unknown }).name === "viewport") {
+      continue;
+    }
+    if ("title" in base) {
+      const t = (base as { title: unknown }).title;
+      out.push({ title: { absolute: typeof t === "string" ? t : String(t) } });
+      continue;
+    }
+    out.push(base);
+  }
+  return out;
+}
 
 /**
  * Process handles from an async generator, updating the event controller
@@ -46,10 +100,35 @@ async function processHandles(
     store: NavigationStore;
     matched?: string[];
     isPartial?: boolean;
+    /** Server's `resolvedIds`: every segment re-resolved this request,
+     *  including null-component ones excluded from `diff`/`segments`.
+     *  Drives cleanup of stale handle buckets when a re-resolved segment
+     *  pushed nothing. */
+    resolvedIds?: string[];
     historyKey: string;
   },
 ): Promise<void> {
-  const { eventController, store, matched, isPartial, historyKey } = opts;
+  const {
+    eventController,
+    store,
+    matched,
+    isPartial,
+    resolvedIds,
+    historyKey,
+  } = opts;
+
+  // This nav's instance token, captured before any await — processHandles runs
+  // right after its own commit, so this is that commit's token. generateHistoryKey
+  // is URL-only, so an A->B->A revisit reuses the key; the token lets a late
+  // resolution tell its own visit apart from a newer same-URL visit, so a stale
+  // nav can never clobber a fresher one's live state or cache (P1).
+  const myInstance = store.getNavInstance();
+
+  // True while this nav still owns the live page: same history key AND the most
+  // recent commit is still ours (no newer nav has committed since).
+  const stillLive = (): boolean =>
+    historyKey === store.getHistoryKey() &&
+    myInstance === store.getNavInstance();
 
   let yieldCount = 0;
   for await (const handleData of handlesGenerator) {
@@ -57,14 +136,139 @@ async function processHandles(
     // This prevents handle data from cancelled navigations polluting
     // the current route's breadcrumbs (e.g., quick popstate after clicking a link).
     if (historyKey !== store.getHistoryKey()) {
-      console.log(
+      debugLog(
         "[NavigationProvider] Stopping handle processing - user navigated away",
       );
       return;
     }
 
     yieldCount++;
-    eventController.setHandleData(handleData, matched, isPartial);
+
+    // Resolve ONLY Meta in the store before applying. Meta is the sole
+    // head-placed handle whose consumer use()s a deferred value above the route
+    // <Suspense>; an uncontained suspension there would revert the just-committed
+    // route and hide its loading fallback. Every other handle (Breadcrumbs,
+    // custom handles) keeps the DeferredHandleEntry contract: its deferred values
+    // reach the consumer AS A PROMISE and are narrowed via isThenable(). So sync
+    // handles AND non-Meta deferred promises apply/stream through immediately —
+    // only Meta is held back and swapped in once resolved.
+    const metaDeferred = hasDeferredHandleValue(
+      handleData,
+      HEAD_RESOLVE_HANDLE_NAMES,
+    );
+
+    // Apply now. The non-deferred-Meta case applies the whole snapshot in one
+    // call (Meta included). When Meta IS deferred, replace the deferred Meta with
+    // the previous page's COLLECTED Meta (stale-while-revalidate — never a blank
+    // title) keyed under one of the NEW route's Meta segments, so it stays
+    // collected under the new segment order while the synchronous and non-Meta
+    // deferred handles update with normal cleanup. The resolved Meta is swapped
+    // in by the partial merge below.
+    if (metaDeferred) {
+      const immediate: HandleData = { ...handleData };
+      const metaSegments = handleData[META] ?? {};
+      // Anchor: the last new Meta segment in matched order (collected after the
+      // shared layout, so its carried title wins). Falls back to any new Meta
+      // segment if matched ordering does not surface one.
+      const metaSegmentIds = Object.keys(metaSegments);
+      const ordered = (matched ?? []).filter((id) =>
+        metaSegmentIds.includes(id),
+      );
+      const anchor = ordered.at(-1) ?? metaSegmentIds.at(-1);
+
+      const prevState = eventController.getHandleState();
+      const prevCollected = collectHandleData(
+        Meta,
+        prevState.data,
+        prevState.segmentOrder,
+      ) as MetaDescriptor[];
+      const carried = carriedPreviousMeta(prevCollected);
+
+      if (anchor && carried.length > 0) {
+        immediate[META] = { [anchor]: carried };
+      } else {
+        // No previous Meta to carry and/or no anchor: leave Meta unset until it
+        // resolves (the documented no-previous-Meta behavior).
+        delete immediate[META];
+      }
+      eventController.setHandleData(immediate, matched, isPartial, resolvedIds);
+    } else {
+      eventController.setHandleData(
+        handleData,
+        matched,
+        isPartial,
+        resolvedIds,
+      );
+    }
+
+    // Snapshot of the nav's full applied handle state (sync handles, non-Meta
+    // deferred promises, and — when Meta is deferred — the carried previous Meta).
+    // Captured AFTER applying so it reflects what is actually on screen now.
+    const baseSnapshot = cloneHandleData(eventController.getHandleState().data);
+
+    if (!metaDeferred) {
+      // Non-deferred: the applied snapshot is final. Keep the cache in sync and
+      // fresh. The token guard stops a stale same-URL nav writing a newer entry.
+      if (store.getCacheEntryInstance(historyKey) === myInstance) {
+        store.updateCacheHandleData(historyKey, baseSnapshot, false);
+      }
+      continue;
+    }
+
+    // Meta is deferred-pending. The applied snapshot carries the PREVIOUS page's
+    // Meta (or none), not this route's final title, so the cache entry must NOT
+    // be served as fresh on a popstate return. Mark it STALE and handlesPending
+    // (token-guarded). This is the P1 fix: the deferred Meta is a SERVER-side
+    // promise streamed via Flight, so a navigate-away ABORTS the stream and the
+    // client's deferred-Meta promise never resolves — the .then below never
+    // fires. stale makes a popstate return revalidate; handlesPending makes that
+    // revalidation a FULL re-render (no client segment IDs) so the server
+    // re-streams the handles. A diff-only revalidation would omit the unchanged
+    // segments' handles and the deferred Meta would never land — see the
+    // segmentIds branch in navigation-bridge.ts.
+    if (store.getCacheEntryInstance(historyKey) === myInstance) {
+      store.updateCacheHandleData(historyKey, baseSnapshot, true, true);
+    }
+
+    // Resolve Meta late, then swap it in. The swap is a PARTIAL merge with
+    // resolvedIds=undefined so the stale-clear loop (which scans all handle
+    // names under resolvedIds) cannot wipe the non-Meta buckets we already
+    // applied. When the deferred Meta DOES resolve while this nav still owns the
+    // entry (no navigate-away abort), write the resolved handle data and clear
+    // stale + handlesPending — the entry is now complete, so a popstate return
+    // serves it without revalidating.
+    //
+    // Order-safety: each stream yield is a full cumulative snapshot and a
+    // segment's handle array is atomic, so concurrent Meta resolutions of
+    // different yields write identical per-segment arrays or touch disjoint
+    // segments — neither can clobber the other.
+    void resolveDeferredHandleValues(
+      handleData,
+      HEAD_RESOLVE_HANDLE_NAMES,
+    ).then((resolved) => {
+      const cacheValue = { ...baseSnapshot, [META]: resolved[META] };
+      if (stillLive()) {
+        // Still on the live page: swap Meta in and refresh the cache as fresh.
+        eventController.setHandleData(
+          { [META]: resolved[META] },
+          matched,
+          true,
+          undefined,
+        );
+        store.updateCacheHandleData(
+          historyKey,
+          eventController.getHandleState().data,
+          false,
+          false,
+        );
+      } else if (store.getCacheEntryInstance(historyKey) === myInstance) {
+        // Navigated away, but THIS nav still owns the target cache entry: write
+        // the resolved data and clear stale + handlesPending so a popstate return
+        // is fresh.
+        store.updateCacheHandleData(historyKey, cacheValue, false, false);
+      }
+      // else: a newer nav to the same URL superseded us — do nothing.
+    });
   }
 
   // Check again before final updates
@@ -72,19 +276,19 @@ async function processHandles(
     return;
   }
 
-  // For partial updates where the generator yielded nothing (cached handlers),
-  // we still need to update the segment order to clean up stale handle data.
-  // This happens when navigating away from a route - the handlers for the new
-  // route might not push any breadcrumbs, but we still need to remove the old ones.
+  // For partial updates where the generator yielded nothing (every
+  // re-resolved handler pushed nothing), still call setHandleData so the
+  // cleanup pass can clear out stale buckets for those segments.
   if (yieldCount === 0 && matched) {
-    eventController.setHandleData({}, matched, true);
+    eventController.setHandleData({}, matched, true, resolvedIds);
   }
 
   // After handles processing completes, update the cache's handleData.
   // This fixes a race condition where commit() caches stale handleData before
   // the async handles processing completes.
-  // Only update if we're still on the same page (historyKey matches).
-  if (historyKey === store.getHistoryKey()) {
+  // Only update if we're still on the same page AND this is still the live nav
+  // (the token guard stops a stale same-URL nav writing a newer nav's state).
+  if (stillLive()) {
     const finalHandleData = eventController.getHandleState().data;
     store.updateCacheHandleData(historyKey, finalHandleData);
   }
@@ -133,10 +337,33 @@ export interface NavigationProviderProps {
   warmupEnabled?: boolean;
 
   /**
-   * App version from server payload (stable, immutable).
-   * Forwarded to prefetch requests for version mismatch detection.
+   * App version from server payload.
+   * Used only as a fallback when `appShellRef` is not supplied.
    */
   version?: string;
+
+  /**
+   * URL prefix for all routes (from createRouter({ basename })).
+   * Used only as a fallback when `appShellRef` is not supplied.
+   */
+  basename?: string;
+
+  /**
+   * App-shell ref. When provided, the context's `basename` and `version` are
+   * read through it (live getters) so they don't close over a stale snapshot or
+   * invalidate the memoized context value. The shell is set once at init and is
+   * not swapped within a session — a cross-app navigation is a full document
+   * load (X-RSC-Reload), so the target app establishes its own shell on load.
+   */
+  appShellRef?: AppShellRef;
+
+  /**
+   * CSP nonce to expose via NonceContext. Production leaves this undefined — the
+   * browser has no nonce (it is a server-side HTML concern), and SSR provides the
+   * nonce through its own NonceContext.Provider. Test harnesses (renderRoute) set
+   * it to seed a nonce so components calling useNonce() can be exercised.
+   */
+  nonce?: string;
 }
 
 /**
@@ -169,6 +396,9 @@ export function NavigationProvider({
   initialTheme,
   warmupEnabled,
   version,
+  basename,
+  appShellRef,
+  nonce,
 }: NavigationProviderProps): ReactNode {
   // Track current payload for rendering (this triggers re-renders)
   const [payload, setPayload] = useState(initialPayload);
@@ -190,103 +420,43 @@ export function NavigationProvider({
     await bridge.refresh();
   }, []);
 
-  // Context value is stable (store, eventController, navigate, refresh never change)
-  const contextValue = useMemo<NavigationStoreContextValue>(
-    () => ({
+  // basename/version are always read through a shell ref so the context value
+  // has a single shape. Both are set once: a supplied appShellRef is seeded
+  // from the init payload (a cross-app navigation reloads, so it is not swapped
+  // in-session), and the standalone fallback wraps the mount-time props.
+  const fallbackShellRef = useRef<AppShellRef | null>(null);
+  if (!fallbackShellRef.current) {
+    fallbackShellRef.current = createAppShellRef({ basename, version });
+  }
+  const shellRef = appShellRef ?? fallbackShellRef.current;
+
+  const contextValue = useMemo<NavigationStoreContextValue>(() => {
+    const value = {
       store,
       eventController,
       navigate,
       refresh,
-      version,
-    }),
-    [],
-  );
+    } as NavigationStoreContextValue;
+    Object.defineProperty(value, "basename", {
+      configurable: true,
+      enumerable: true,
+      get: () => shellRef.get().basename,
+    });
+    Object.defineProperty(value, "version", {
+      configurable: true,
+      enumerable: true,
+      get: () => shellRef.get().version,
+    });
+    return value;
+  }, []);
 
-  // Connection warmup: keep TLS alive after idle periods.
-  // After 60s of no user interaction, marks connection as "cold".
-  // On next interaction or visibility change, sends a HEAD request to warm TLS
-  // before the user actually clicks a link.
+  // Connection warmup: keep TLS alive after idle periods. After 60s of no
+  // interaction the connection is marked cold; the next pointer/touch
+  // interaction or visibility change warms TLS via a HEAD request before the
+  // user clicks a link. State machine lives in connection-warmup.ts.
   useEffect(() => {
     if (!warmupEnabled) return;
-
-    const IDLE_TIMEOUT = 60_000;
-    const DEBOUNCE_DELAY = 150;
-
-    let idleTimer: ReturnType<typeof setTimeout> | undefined;
-    let debounceTimer: ReturnType<typeof setTimeout> | undefined;
-    let isCold = false;
-    let warmupListenersAttached = false;
-
-    function sendWarmup() {
-      isCold = false;
-      fetch("/?_rsc_warmup", { method: "HEAD" }).catch(() => {});
-    }
-
-    function triggerWarmup() {
-      if (!isCold) return;
-      clearTimeout(debounceTimer);
-      debounceTimer = setTimeout(() => {
-        sendWarmup();
-        detachWarmupListeners();
-        resetIdleTimer();
-      }, DEBOUNCE_DELAY);
-    }
-
-    function onVisibilityChange() {
-      if (document.visibilityState === "visible" && isCold) {
-        triggerWarmup();
-      }
-    }
-
-    function attachWarmupListeners() {
-      if (warmupListenersAttached) return;
-      warmupListenersAttached = true;
-      document.addEventListener("visibilitychange", onVisibilityChange);
-      document.addEventListener("mousemove", triggerWarmup, { once: true });
-      document.addEventListener("touchstart", triggerWarmup, { once: true });
-    }
-
-    function detachWarmupListeners() {
-      warmupListenersAttached = false;
-      document.removeEventListener("visibilitychange", onVisibilityChange);
-      document.removeEventListener("mousemove", triggerWarmup);
-      document.removeEventListener("touchstart", triggerWarmup);
-    }
-
-    function markCold() {
-      isCold = true;
-      attachWarmupListeners();
-    }
-
-    function resetIdleTimer() {
-      clearTimeout(idleTimer);
-      isCold = false;
-      idleTimer = setTimeout(markCold, IDLE_TIMEOUT);
-    }
-
-    // Activity events that reset the idle timer
-    const activityEvents = [
-      "mousemove",
-      "keydown",
-      "touchstart",
-      "scroll",
-    ] as const;
-    const activityOptions: AddEventListenerOptions = { passive: true };
-
-    for (const event of activityEvents) {
-      document.addEventListener(event, resetIdleTimer, activityOptions);
-    }
-
-    resetIdleTimer();
-
-    return () => {
-      clearTimeout(idleTimer);
-      clearTimeout(debounceTimer);
-      detachWarmupListeners();
-      for (const event of activityEvents) {
-        document.removeEventListener(event, resetIdleTimer);
-      }
-    };
+    return startConnectionWarmup();
   }, [warmupEnabled]);
 
   // Cancel non-matching prefetches when navigation starts.
@@ -338,8 +508,12 @@ export function NavigationProvider({
         metadata: update.metadata,
       });
 
-      // Update route params
-      eventController.setParams(update.metadata.params ?? {});
+      // Update route params. Only reset when the server actually sends a params
+      // map — an absent `params` field means "no change" (e.g., legacy action
+      // responses that omitted params). Explicit `{}` still clears correctly.
+      if (update.metadata.params !== undefined) {
+        eventController.setParams(update.metadata.params);
+      }
 
       // Update handle data progressively as it streams in
       if (update.metadata.handles) {
@@ -352,24 +526,20 @@ export function NavigationProvider({
           store,
           matched: update.metadata.matched,
           isPartial: update.metadata.isPartial,
+          resolvedIds: update.metadata.resolvedIds,
           historyKey,
         }).catch((err) =>
           console.error("[NavigationProvider] Error consuming handles:", err),
         );
-      } else if (update.metadata.cachedHandleData) {
-        // For back/forward navigation from cache, restore the cached handleData
-        // This restores breadcrumbs to the exact state they were when the page was cached
-        eventController.setHandleData(
-          update.metadata.cachedHandleData,
-          update.metadata.matched,
-          false, // full replace - restore entire cached state
-        );
       } else if (update.metadata.matched) {
-        // For cached navigations without handleData, update segmentOrder to clean up stale data
+        // cachedHandleData present -> full restore (back/forward); absent ->
+        // partial cleanup of segments no longer matched.
+        const cached = update.metadata.cachedHandleData;
         eventController.setHandleData(
-          {}, // Empty data - all existing data not in matched will be cleaned up
+          cached ?? {},
           update.metadata.matched,
-          true, // partial update - will clean up segments not in matched
+          cached === undefined,
+          cached === undefined ? update.metadata.resolvedIds : undefined,
         );
       }
     });
@@ -382,7 +552,8 @@ export function NavigationProvider({
     payload.root instanceof Promise ? use(payload.root) : payload.root;
 
   // Wrap content in RootErrorBoundary to catch:
-  // 1. Errors from NetworkErrorThrower (rendered during network failures)
+  // 1. Errors from RenderErrorThrower (network failures and unprocessable
+  //    navigation responses, routed here by the navigation bridge)
   // 2. Client component errors that occur before/outside the segment tree's error boundary
   // 3. Errors during promise resolution or navigation state updates
   // This acts as a safety net - the segment tree has its own RootErrorBoundary that
@@ -391,7 +562,11 @@ export function NavigationProvider({
   // Build the content tree
   let content = <RootErrorBoundary>{root}</RootErrorBoundary>;
 
-  // Wrap with ThemeProvider when theme is enabled
+  // Wrap with ThemeProvider when theme is enabled. The ThemeProvider is
+  // document-lifetime: its config comes from the initial load and persists for
+  // the session. It sits above the segment tree and is not remounted in-session;
+  // a cross-app navigation is a full document load (X-RSC-Reload), so the target
+  // app's theme config takes effect on its own load.
   if (themeConfig) {
     content = (
       <ThemeProvider config={themeConfig} initialTheme={initialTheme}>
@@ -402,9 +577,10 @@ export function NavigationProvider({
 
   // Match SSR tree shape: NonceContext.Provider is always present so
   // hydration sees the same component tree. Value is undefined on the
-  // client — CSP nonces are a server-side HTML concern.
+  // client — CSP nonces are a server-side HTML concern — unless a test
+  // harness seeded one via the `nonce` prop.
   content = (
-    <NonceContext.Provider value={undefined}>{content}</NonceContext.Provider>
+    <NonceContext.Provider value={nonce}>{content}</NonceContext.Provider>
   );
 
   return (

package/src/browser/react/ScrollRestoration.tsx

@@ -14,17 +14,21 @@ export interface ScrollRestorationProps {
    * Return location.pathname to restore scroll based on path
    * (useful for keeping scroll position on the same page).
    *
+   * Provide a stable reference: a module-level function or one wrapped in
+   * useCallback. The init effect re-runs when getKey's identity changes, and
+   * teardown clears in-memory scroll positions — a fresh inline arrow on every
+   * parent render would discard unpersisted positions mid-session.
+   *
    * @example
    * ```tsx
+   * // Stable module-level getKey (recommended)
+   * const byPathname = (location) => location.pathname;
+   *
    * // Restore based on pathname (same URL = same scroll)
-   * <ScrollRestoration
-   *   getKey={(location) => location.pathname}
-   * />
+   * <ScrollRestoration getKey={byPathname} />
    *
    * // Restore based on unique history entry (default)
-   * <ScrollRestoration
-   *   getKey={(location) => location.key}
-   * />
+   * // <ScrollRestoration /> — omit getKey to use location.key
    * ```
    */
   getKey?: (location: {

package/src/browser/react/context.ts

@@ -43,10 +43,15 @@ export interface NavigationStoreContextValue {
   refresh: () => Promise<void>;
 
   /**
-   * App version from server payload (stable, immutable).
-   * Used in prefetch requests for version mismatch detection.
+   * App version from the initial server payload.
    */
   version: string | undefined;
+
+  /**
+   * URL prefix for all routes (from createRouter({ basename })).
+   * Used by Link and useRouter() to auto-prefix app-local paths.
+   */
+  basename: string | undefined;
 }
 
 /**

package/src/browser/react/deferred-handle-resolution.ts

@@ -0,0 +1,75 @@
+import type { HandleData } from "../types.js";
+import { isThenable } from "../../handles/is-thenable.js";
+
+/**
+ * The set of handle names whose deferred (Promise) values MUST be resolved in
+ * the store BEFORE the snapshot is applied during client navigation.
+ *
+ * The boundary: a handle belongs here only if its consumer `use()`s a promise in
+ * <head>, above the route's <Suspense>. Suspending there would revert the
+ * just-committed route and hide its loading fallback. Today that is Meta alone
+ * (MetaTags lives in <head> and use()s deferred descriptors). Every OTHER handle
+ * keeps the public DeferredHandleEntry contract: its deferred value reaches the
+ * consumer AS A PROMISE during soft navigation, narrowed via isThenable().
+ *
+ * If a future head-placed handle starts use()-ing promises, add its name here.
+ */
+export const HEAD_RESOLVE_HANDLE_NAMES: readonly string[] = [
+  "__rsc_router_meta__",
+];
+
+/**
+ * True when a handle value in this snapshot is a deferred (Promise) value.
+ *
+ * When `onlyHandleNames` is given, only those handle buckets are considered;
+ * deferred values under any other handle are ignored (they pass through to the
+ * consumer as promises, by contract).
+ */
+export function hasDeferredHandleValue(
+  data: HandleData,
+  onlyHandleNames?: readonly string[],
+): boolean {
+  const scope = onlyHandleNames ? new Set(onlyHandleNames) : null;
+  for (const [handleName, segments] of Object.entries(data)) {
+    if (scope && !scope.has(handleName)) continue;
+    for (const values of Object.values(segments)) {
+      if (values.some(isThenable)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Snapshot with deferred (Promise) values awaited; a rejected deferred is
+ * dropped (it contributes nothing), mirroring the render-side REJECTED_META.
+ * Promise.allSettled treats non-promise values as already-fulfilled, so plain
+ * values pass through unchanged.
+ *
+ * When `onlyHandleNames` is given, ONLY those handle buckets are resolved; every
+ * other bucket is copied through by reference (its deferred values keep their
+ * promise identity so the consumer can narrow them).
+ */
+export async function resolveDeferredHandleValues(
+  data: HandleData,
+  onlyHandleNames?: readonly string[],
+): Promise<HandleData> {
+  const scope = onlyHandleNames ? new Set(onlyHandleNames) : null;
+  const out: HandleData = {};
+  await Promise.all(
+    Object.entries(data).flatMap(([handleName, segments]) => {
+      // Out-of-scope buckets pass through untouched (promise identity kept).
+      if (scope && !scope.has(handleName)) {
+        out[handleName] = segments;
+        return [];
+      }
+      out[handleName] = {};
+      return Object.entries(segments).map(async ([segmentId, values]) => {
+        const settled = await Promise.allSettled(values);
+        out[handleName][segmentId] = settled
+          .filter((r) => r.status === "fulfilled")
+          .map((r) => (r as PromiseFulfilledResult<unknown>).value);
+      });
+    }),
+  );
+  return out;
+}