@rangojs/router 0.0.0-experimental.133 → 0.0.0-experimental.135

package/src/browser/partial-update.ts

@@ -20,7 +20,7 @@ import {
 } from "./intercept-utils.js";
 import type { BoundTransaction } from "./navigation-transaction.js";
 import { ServerRedirect } from "../errors.js";
-import { debugLog } from "./logging.js";
+import { debugLog, isBrowserDebugEnabled } from "./logging.js";
 import {
   validateRedirectOrigin,
   validateExternalRedirect,
@@ -188,7 +188,11 @@ export function createPartialUpdater(
       routerId: store.getRouterId?.(),
     });
     const streamingToken = tx.startStreaming();
-    const { payload, streamComplete: rawStreamComplete } = fetchResult;
+    const {
+      payload,
+      streamComplete: rawStreamComplete,
+      fullyPrefetched,
+    } = fetchResult;
     debugLog("payload.metadata", payload.metadata);
 
     // Side effect only: end the streaming token once the stream settles.
@@ -395,7 +399,14 @@ export function createPartialUpdater(
 
       const renderOptions = {
         isAction: mode.type === "action",
-        forceAwait: mode.type === "stale-revalidation",
+        // forceAwait unwraps the ROUTER loader promises during render so they
+        // land without a loading()/fallback frame. A fully-prefetched nav has
+        // its router data already resolved (the prefetch stream drained), so
+        // awaiting it here is free and lets us commit NORMALLY (not in a
+        // transition) below — a normal commit still shows fallbacks for any
+        // CLIENT component that suspends on mount, which a transition would
+        // wrongly suppress by holding the old UI until that suspense settles.
+        forceAwait: mode.type === "stale-revalidation" || fullyPrefetched,
         interceptSegments:
           reconciled.interceptSegments.length > 0
             ? reconciled.interceptSegments
@@ -480,6 +491,21 @@ export function createPartialUpdater(
       debugLog("[partial-update] updating document");
 
       const hasTransition = shouldStartViewTransition(reconciled.segments);
+      // [VT-DIAG] Gated behind INTERNAL_RANGO_DEBUG. Reports which reconciled
+      // segment still carries a transition after the server-side when-gate, and
+      // whether the commit will be held in a startTransition. If `withTransition`
+      // lists an ancestor (layout/root) id rather than the gated leaf, an ungated
+      // ancestor transition is holding the subtree (missing loading() fallback).
+      if (isBrowserDebugEnabled()) {
+        debugLog("[VT-DIAG] commit", {
+          mode: mode.type,
+          hasTransition,
+          withTransition: reconciled.segments
+            .filter((s) => s.transition)
+            .map((s) => s.id),
+          all: reconciled.segments.map((s) => s.id),
+        });
+      }
       const scrollPayload = toScrollPayload(navScroll);
 
       if (mode.type === "action" || mode.type === "stale-revalidation") {
@@ -505,6 +531,20 @@ export function createPartialUpdater(
           });
         });
       } else {
+        // Normal commit (cold/partial nav AND fully-prefetched nav). For a
+        // fully-prefetched nav, renderOptions.forceAwait (above) unwrapped the
+        // already-resolved ROUTER loader data AND route content during render, so
+        // the new tree carries it inline with no loading()/fallback frame — yet we
+        // still commit NORMALLY here rather than in a transition. A transition
+        // holds the OLD UI until ALL suspense in the new tree settles, including a
+        // CLIENT component that starts its own data request only when mounted
+        // (post-commit) under a persistent boundary; that would retain the
+        // previous page indefinitely with no feedback. A normal commit lets such
+        // client-initiated suspense reveal a fallback (correct) while the router
+        // data — genuinely ready — never flashes. Cold/partial navs
+        // (fullyPrefetched=false) do not forceAwait, so they stream their
+        // fallbacks. Explicit transition() routes keep the broader content-hold
+        // via the hasTransition branch above (the documented opt-in).
         onUpdate({
           root: newTree,
           metadata: payload.metadata!,

package/src/browser/prefetch/cache.ts

@@ -65,6 +65,14 @@ export interface DecodedPrefetch {
    * when it adopted an inflight entry through the wildcard key.
    */
   scope: "source" | "wildcard";
+  /**
+   * Synchronously-readable flag, flipped to true when `streamComplete` resolves
+   * (the entire RSC stream has drained). Navigation reads this at click time to
+   * tell a FULLY warmed prefetch (payload commits without suspending → safe to
+   * commit in a startTransition, no fallback flash) from a partially-warmed one
+   * (still streaming → stream its fallbacks like a cold load). Starts false.
+   */
+  complete: boolean;
 }
 
 let cacheTTL = 300_000;

package/src/browser/prefetch/fetch.ts

@@ -244,14 +244,21 @@ function executePrefetchFetch(
       const storageKey = scope === "source" ? sourceKey : wildcardKey;
 
       // Track stream completion off a tee so navigation's scroll/revalidation
-      // gating matches the fresh-fetch path; decode the other branch.
+      // gating matches the fresh-fetch path; decode the other branch. The
+      // completion callback reports whether the stream ended on a clean EOF
+      // (true) or was aborted/errored (false) — only a clean end can mark the
+      // entry complete (see below).
       let resolveStreamComplete!: () => void;
+      let endedCleanly = false;
       const streamComplete = new Promise<void>((resolve) => {
         resolveStreamComplete = resolve;
       });
       const tracked = teeWithCompletion(
         response,
-        () => resolveStreamComplete(),
+        (clean) => {
+          endedCleanly = clean;
+          resolveStreamComplete();
+        },
         effectiveSignal,
         // Speculative prefetch: a never-consumed/aborted stream error is benign.
         true,
@@ -264,7 +271,12 @@ function executePrefetchFetch(
       // error is still surfaced to navigation if it consumes the entry.
       payload.catch(() => {});
 
-      const entry: DecodedPrefetch = { payload, streamComplete, scope };
+      const entry: DecodedPrefetch = {
+        payload,
+        streamComplete,
+        scope,
+        complete: false,
+      };
       storePrefetch(storageKey, entry, gen);
       // The stall timeout now owns the body stream: arm eviction (publishedKey)
       // and clear the timer once the stream completes. The tee's finally resolves
@@ -272,7 +284,23 @@ function executePrefetchFetch(
       // no lingering timer while a stalled one is evicted when the timer fires.
       publishedKey = storageKey;
       publishedEntry = entry;
-      streamComplete.then(() => clearTimeout(timeoutId));
+      // Evict a broken prefetch IMMEDIATELY on the earliest failure signal — do not
+      // wait for both branches to settle. A decode that rejects while the tracking
+      // stream is still draining (or hung) would otherwise leave the rejected payload
+      // consumable (navigation reads entry.payload regardless of `complete`) until EOF
+      // or the stall timeout. removePrefetch is identity-guarded, so a fresh entry
+      // republished under the same key is never dropped, and a double call is a no-op.
+      payload.catch(() => removePrefetch(storageKey, entry));
+      streamComplete.then(() => {
+        if (!endedCleanly) removePrefetch(storageKey, entry);
+      });
+      // Mark complete ONLY on a fully-healthy prefetch (decode resolved AND clean EOF).
+      Promise.allSettled([payload, streamComplete]).then(([decode]) => {
+        if (decode.status === "fulfilled" && endedCleanly) {
+          entry.complete = true;
+        }
+        clearTimeout(timeoutId);
+      });
       return entry;
     })
     .catch(() => null)

package/src/browser/react/NavigationProvider.tsx

@@ -31,6 +31,57 @@ 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
@@ -66,6 +117,19 @@ async function processHandles(
     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) {
     // Check if user navigated away before each update.
@@ -79,7 +143,132 @@ async function processHandles(
     }
 
     yieldCount++;
-    eventController.setHandleData(handleData, matched, isPartial, resolvedIds);
+
+    // 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
@@ -97,8 +286,9 @@ async function processHandles(
   // 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);
   }
@@ -362,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

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

package/src/browser/response-adapter.ts

@@ -2,6 +2,16 @@ import { validateRedirectOrigin } from "./validate-redirect-origin.js";
 
 type HeaderResult = { url: string } | "blocked" | null;
 
+/**
+ * Null-body statuses: the Fetch spec forbids pairing these with a body, so
+ * `new Response(body, { status })` throws ("Response with null body status
+ * cannot have body"). fetch() can still surface one WITH a body straight from
+ * the network layer (never the JS constructor): a 304 stale-while-revalidate
+ * prefetch revalidated to Not Modified (body from cache), or a 204 soft
+ * redirect. teeWithCompletion must not re-run those through `new Response`.
+ */
+const NULL_BODY_STATUS = new Set([101, 204, 205, 304]);
+
 /**
  * Extract and validate an RSC response header URL (X-RSC-Reload, X-RSC-Redirect).
  * Returns { url } if valid, "blocked" if present but invalid origin, null if absent.
@@ -74,7 +84,13 @@ export function handleReloadHeader(
  * Returns a new Response with one branch; the other is consumed to detect
  * end-of-stream, calling onComplete when done.
  *
- * If the response has no body, onComplete fires synchronously.
+ * `onComplete` receives `endedCleanly`: true only on a normal EOF drain, false
+ * on a read error or an abort (the signal cancelled the reader). Callers that
+ * gate a "fully complete" fast path (e.g. prefetch's `entry.complete`) must
+ * treat a non-clean end as incomplete — a broken stream is not complete data.
+ *
+ * If the response has no body, onComplete fires synchronously with `true`
+ * (an empty body is a clean, complete stream).
  * If signal is provided, an abort cancels the tracking reader.
  *
  * `silent` suppresses the stream-error log. Prefetch passes it: a speculative,
@@ -84,7 +100,7 @@ export function handleReloadHeader(
  */
 export function teeWithCompletion(
   response: Response,
-  onComplete: () => void,
+  onComplete: (endedCleanly: boolean) => void,
   signal?: AbortSignal,
   silent = false,
 ): Response {
@@ -92,15 +108,18 @@ export function teeWithCompletion(
   // rejection's .catch, so onComplete must be settled exactly once across all
   // paths (no-body early return, finally, catch).
   let settled = false;
-  const settle = () => {
+  const settle = (endedCleanly: boolean) => {
     if (!settled) {
       settled = true;
-      onComplete();
+      onComplete(endedCleanly);
     }
   };
 
-  if (!response.body) {
-    settle();
+  // Empty body, or a null-body status fetch() paired with a body: either way the
+  // body can't be re-attached via `new Response` below. Settle and pass the
+  // original response through; its body (when present) stays readable downstream.
+  if (!response.body || NULL_BODY_STATUS.has(response.status)) {
+    settle(true);
     return response;
   }
 
@@ -110,21 +129,31 @@ export function teeWithCompletion(
     const reader = trackingStream.getReader();
     const onAbort = signal ? reader.cancel.bind(reader) : undefined;
     if (onAbort) signal!.addEventListener("abort", onAbort, { once: true });
+    // Only a loop that reaches `done` is a clean EOF. A read error rejects out
+    // of the try and still runs the finally, so the finally must NOT assume
+    // clean — it gates on this flag (false on error) AND on signal.aborted
+    // (an abort cancels the reader so read() resolves { done: true } and the
+    // loop breaks here normally, NOT in the .catch — re-check the signal to
+    // catch that case).
+    let cleanEof = false;
     try {
       while (true) {
         const { done } = await reader.read();
-        if (done) break;
+        if (done) {
+          cleanEof = true;
+          break;
+        }
       }
     } finally {
       if (onAbort) signal!.removeEventListener("abort", onAbort);
       reader.releaseLock();
-      settle();
+      settle(cleanEof && !signal?.aborted);
     }
   })().catch((error) => {
     if (!silent && !signal?.aborted) {
       console.error("[Browser] Error reading tracking stream:", error);
     }
-    settle();
+    settle(false);
   });
 
   return new Response(rscStream, {

package/src/browser/types.ts

@@ -447,6 +447,10 @@ export interface NavigationStore {
   // History-based segment cache (for back/forward navigation and partial merging)
   getHistoryKey(): string;
   setHistoryKey(key: string): void;
+  /** Monotonic token of the most recently committed navigation. */
+  getNavInstance(): number;
+  /** Nav-instance token recorded on a cache entry (undefined if absent). */
+  getCacheEntryInstance(historyKey: string): number | undefined;
   cacheSegmentsForHistory(
     historyKey: string,
     segments: ResolvedSegment[],
@@ -458,10 +462,28 @@ export interface NavigationStore {
         stale: boolean;
         handleData?: HandleData;
         routerId?: string;
+        /**
+         * True when the entry's handle data is incomplete (a deferred Meta was
+         * still pending at navigate-away). A popstate return must revalidate with
+         * a FULL re-render so the server re-streams handles.
+         */
+        handlesPending?: boolean;
       }
     | undefined;
   hasHistoryCache(historyKey: string): boolean;
-  updateCacheHandleData(historyKey: string, handleData: HandleData): void;
+  /**
+   * Update only the handleData (and optionally the stale / handlesPending flags)
+   * of an existing cache entry. When a flag is omitted the entry's current value
+   * is preserved. `stale=true` marks a single entry stale so a popstate return
+   * revalidates it; `handlesPending=true` additionally forces that revalidation
+   * to be a full re-render (so a deferred Meta re-streams).
+   */
+  updateCacheHandleData(
+    historyKey: string,
+    handleData: HandleData,
+    stale?: boolean,
+    handlesPending?: boolean,
+  ): void;
   markCacheAsStale(): void;
   markHistoryCacheStale(): void;
   markCacheAsStaleAndBroadcast(): void;
@@ -521,6 +543,15 @@ export interface FetchPartialResult {
   payload: RscPayload;
   /** Promise that resolves when the response stream is fully consumed */
   streamComplete: Promise<void>;
+  /**
+   * True only when this payload came from a prefetch-cache hit whose stream had
+   * ALREADY fully drained at fetch time (the route was fully prefetched). The
+   * commit then runs in a startTransition so loading()/Suspense content — already
+   * resolved — swaps in directly without flashing a fallback. A partially-warmed
+   * (still-streaming) prefetch hit and a cold fetch leave this false so their
+   * fallbacks stream as usual.
+   */
+  fullyPrefetched?: boolean;
 }
 
 /**