@rangojs/router 0.0.0-experimental.e9c0b2f2 → 0.0.0-experimental.ea9f40f2

package/src/browser/partial-update.ts

@@ -20,7 +20,11 @@ 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,
+  IS_BROWSER_DEBUG,
+} from "./logging.js";
 import {
   validateRedirectOrigin,
   validateExternalRedirect,
@@ -147,9 +151,11 @@ export function createPartialUpdater(
         currentCached.filter(isInterceptSegment).map((s) => s.id),
       );
       segments = currentSegments.filter((id) => !interceptIds.has(id));
-      debugLog(
-        `[Browser] Leaving intercept - filtered segments: ${segments.join(", ")}`,
-      );
+      if (IS_BROWSER_DEBUG) {
+        debugLog(
+          `[Browser] Leaving intercept - filtered segments: ${segments.join(", ")}`,
+        );
+      }
     } else {
       segments = segmentIds ?? segmentState.currentSegmentIds;
     }
@@ -159,12 +165,14 @@ export function createPartialUpdater(
         ? segmentState.currentUrl || tx.currentUrl
         : interceptSourceUrl || tx.currentUrl || segmentState.currentUrl;
 
-    debugLog(`\n[Browser] >>> NAVIGATION`);
-    debugLog(`[Browser] From: ${previousUrl}`);
-    debugLog(`[Browser] To: ${url}`);
-    debugLog(`[Browser] Segments to send: ${segments.join(", ")}`);
-    if (interceptSourceUrl) {
-      debugLog(`[Browser] Intercept context from: ${interceptSourceUrl}`);
+    if (IS_BROWSER_DEBUG) {
+      debugLog(`\n[Browser] >>> NAVIGATION`);
+      debugLog(`[Browser] From: ${previousUrl}`);
+      debugLog(`[Browser] To: ${url}`);
+      debugLog(`[Browser] Segments to send: ${segments.join(", ")}`);
+      if (interceptSourceUrl) {
+        debugLog(`[Browser] Intercept context from: ${interceptSourceUrl}`);
+      }
     }
 
     const targetCache =
@@ -173,9 +181,11 @@ export function createPartialUpdater(
         : undefined;
     const cachedSegs = targetCache ?? getCurrentCachedSegments();
     const cachedSegsSource = targetCache ? "history-cache" : "current-page";
-    debugLog(
-      `[Browser] cachedSegs source: ${cachedSegsSource} (${cachedSegs.length} segments: ${cachedSegs.map((s) => s.id).join(", ")})`,
-    );
+    if (IS_BROWSER_DEBUG) {
+      debugLog(
+        `[Browser] cachedSegs source: ${cachedSegsSource} (${cachedSegs.length} segments: ${cachedSegs.map((s) => s.id).join(", ")})`,
+      );
+    }
 
     let fetchResult: Awaited<ReturnType<NavigationClient["fetchPartial"]>>;
     fetchResult = await client.fetchPartial({
@@ -188,7 +198,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.
@@ -254,8 +268,10 @@ export function createPartialUpdater(
         return;
       }
 
-      debugLog(`[Browser] Partial update - matched: ${matched?.join(", ")}`);
-      debugLog(`[Browser] Diff: ${diff?.join(", ")}`);
+      if (IS_BROWSER_DEBUG) {
+        debugLog(`[Browser] Partial update - matched: ${matched?.join(", ")}`);
+        debugLog(`[Browser] Diff: ${diff?.join(", ")}`);
+      }
 
       if (!diff || diff.length === 0) {
         const matchedIds = matched || [];
@@ -379,6 +395,13 @@ export function createPartialUpdater(
           return;
         }
         if (mode.type === "action") {
+          // An action refetch that lands on missing segments (navigated away /
+          // consolidation / HMR) drops rather than refetch-all: the action flow
+          // is storeOnly / skipLoadingState, so a full refetch here would fight
+          // it. Keep the stale-but-consistent tree; log so the drop is visible.
+          debugLog(
+            `[Browser] Action refetch: ${missingCount} segments missing; dropping (stale-but-consistent tree kept).`,
+          );
           return;
         }
         console.warn(
@@ -395,7 +418,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 +510,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 +550,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,17 +65,36 @@ 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;
 
+// Max stored entries before FIFO eviction. Mirrors DEFAULT_PREFETCH_CACHE_SIZE
+// (router/prefetch-limits.ts); kept as a local literal so the client bundle
+// doesn't pull in router-layer code, matching the cacheTTL default above.
+// Overridden at startup by initPrefetchCache from server metadata.
+let maxPrefetchCacheSize = 100;
+
 /**
- * Initialize the prefetch cache with the configured TTL.
- * Called once at app startup with the value from server metadata.
- * A TTL of 0 disables the in-memory cache and all prefetching.
+ * Initialize the prefetch cache with the configured TTL and max size.
+ * Called once at app startup with the values from server metadata. Each
+ * argument is applied only when provided, so a caller can set just the TTL.
+ * A TTL of 0 disables the in-memory cache and all prefetching. A size below 1
+ * is ignored (the default is kept) — disabling prefetch is the TTL's job.
  */
-export function initPrefetchCache(ttlMs: number): void {
-  cacheTTL = ttlMs;
+export function initPrefetchCache(ttlMs?: number, maxSize?: number): void {
+  if (ttlMs !== undefined) cacheTTL = ttlMs;
+  if (maxSize !== undefined && Number.isFinite(maxSize) && maxSize >= 1) {
+    maxPrefetchCacheSize = Math.floor(maxSize);
+  }
 }
 
 /**
@@ -85,7 +104,6 @@ export function initPrefetchCache(ttlMs: number): void {
 export function isPrefetchCacheDisabled(): boolean {
   return cacheTTL <= 0;
 }
-const MAX_PREFETCH_CACHE_SIZE = 50;
 
 interface PrefetchCacheEntry {
   entry: DecodedPrefetch;
@@ -95,6 +113,16 @@ interface PrefetchCacheEntry {
 const cache = new Map<string, PrefetchCacheEntry>();
 const inflight = new Set<string>();
 
+// Watermark: the smallest entry timestamp currently in `cache`, i.e. a lower
+// bound on when the oldest entry expires (timestamp + cacheTTL). storePrefetch's
+// eager expiry sweep is skipped while `now - earliestTimestamp <= cacheTTL` — the
+// oldest entry cannot be expired yet, so nothing would be evicted. Deletions
+// (consume/has/remove) may leave it stale-LOW, which only forces a harmless extra
+// sweep that recomputes it exactly; it is never stale-high, so a skipped sweep
+// can never retain an expired entry. consume/has still TTL-check lazily, so a
+// skipped sweep never serves a stale entry. Infinity when the cache is empty.
+let earliestTimestamp = Infinity;
+
 const inflightPromises = new Map<string, Promise<DecodedPrefetch | null>>();
 
 const inflightAliases = new Map<string, string[]>();
@@ -251,21 +279,32 @@ export function storePrefetch(
     return;
   }
 
-  // Evict expired entries
+  // Evict expired entries — but only when the watermark says the oldest entry
+  // could have expired, so a burst of stores no longer walks the whole map each
+  // time. The sweep recomputes the exact watermark from the survivors.
   const now = Date.now();
-  for (const [k, cached] of cache) {
-    if (now - cached.timestamp > cacheTTL) {
-      cache.delete(k);
+  if (now - earliestTimestamp > cacheTTL) {
+    let min = Infinity;
+    for (const [k, cached] of cache) {
+      if (now - cached.timestamp > cacheTTL) {
+        cache.delete(k);
+      } else if (cached.timestamp < min) {
+        min = cached.timestamp;
+      }
     }
+    earliestTimestamp = min;
   }
 
   // FIFO eviction if at capacity
-  if (cache.size >= MAX_PREFETCH_CACHE_SIZE) {
+  if (cache.size >= maxPrefetchCacheSize) {
     const oldest = cache.keys().next().value;
     if (oldest) cache.delete(oldest);
   }
 
   cache.set(key, { entry, timestamp: now });
+  // The new entry is the newest, so it only moves the watermark when the cache
+  // was empty (Infinity); otherwise the older watermark stands.
+  if (now < earliestTimestamp) earliestTimestamp = now;
 }
 
 /**
@@ -336,6 +375,7 @@ export function clearPrefetchCache(): void {
   inflightAliases.clear();
   adoptedKeys.clear();
   cache.clear();
+  earliestTimestamp = Infinity;
   abortAllPrefetches();
   invalidateRangoState();
 }

package/src/browser/prefetch/fetch.ts

@@ -31,7 +31,7 @@ import { getRangoState } from "../rango-state.js";
 import { isActionFenceActive } from "../action-fence.js";
 import { enqueuePrefetch } from "./queue.js";
 import { shouldPrefetch } from "./policy.js";
-import { debugLog } from "../logging.js";
+import { debugLog, IS_BROWSER_DEBUG } from "../logging.js";
 import { teeWithCompletion, isForeignRouterId } from "../response-adapter.js";
 import type { RscPayload } from "../types.js";
 
@@ -154,6 +154,8 @@ function executePrefetchFetch(
   sourceKey: string,
   fetchUrl: string,
   forceSourceScope: boolean,
+  /** Rango state captured once by the caller (keys + header share one read). */
+  rangoState: string,
   expectedRouterId?: string,
   signal?: AbortSignal,
 ): Promise<DecodedPrefetch | null> {
@@ -214,7 +216,7 @@ function executePrefetchFetch(
     ...(isActionFenceActive() && { cache: "no-store" as RequestCache }),
     signal: effectiveSignal,
     headers: {
-      "X-Rango-State": getRangoState(),
+      "X-Rango-State": rangoState,
       "X-RSC-Router-Client-Path": window.location.href,
       "X-Rango-Prefetch": "1",
     },
@@ -244,14 +246,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 +273,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 +286,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)
@@ -343,26 +373,31 @@ export function prefetchDirect(
   const wildcardKey = buildPrefetchKey(rangoState, targetUrl);
   const sourceKey = buildSourceKey(rangoState, sourceHref, targetUrl);
   if (hasPrefetchHit(forceSourceScope, wildcardKey, sourceKey)) {
-    debugLog("[prefetch] direct dedup (key already exists)", {
+    if (IS_BROWSER_DEBUG) {
+      debugLog("[prefetch] direct dedup (key already exists)", {
+        url,
+        wildcardKey,
+        sourceKey,
+        forceSourceScope,
+      });
+    }
+    return;
+  }
+  if (IS_BROWSER_DEBUG) {
+    debugLog("[prefetch] direct fetch", {
       url,
       wildcardKey,
       sourceKey,
+      source: sourceHref,
       forceSourceScope,
     });
-    return;
   }
-  debugLog("[prefetch] direct fetch", {
-    url,
-    wildcardKey,
-    sourceKey,
-    source: sourceHref,
-    forceSourceScope,
-  });
   executePrefetchFetch(
     wildcardKey,
     sourceKey,
     targetUrl.toString(),
     forceSourceScope,
+    rangoState,
     routerId,
   );
 }
@@ -393,12 +428,14 @@ export function prefetchQueued(
   const sourceKey = buildSourceKey(rangoState, sourceHref, targetUrl);
   const queueKey = forceSourceScope ? sourceKey : wildcardKey;
   if (hasPrefetchHit(forceSourceScope, wildcardKey, sourceKey)) {
-    debugLog("[prefetch] queued dedup (key already exists)", {
-      url,
-      wildcardKey,
-      sourceKey,
-      forceSourceScope,
-    });
+    if (IS_BROWSER_DEBUG) {
+      debugLog("[prefetch] queued dedup (key already exists)", {
+        url,
+        wildcardKey,
+        sourceKey,
+        forceSourceScope,
+      });
+    }
     return queueKey;
   }
   const fetchUrlStr = targetUrl.toString();
@@ -416,6 +453,7 @@ export function prefetchQueued(
       sourceKey,
       fetchUrlStr,
       forceSourceScope,
+      rangoState,
       routerId,
       signal,
     ).then(() => {});

package/src/browser/prefetch/queue.ts

@@ -16,9 +16,24 @@
 
 import { wait, waitForIdle, waitForViewportImages } from "./resource-ready.js";
 
-const MAX_CONCURRENT = 2;
+// Max prefetches executing at once. Mirrors DEFAULT_PREFETCH_CONCURRENCY
+// (router/prefetch-limits.ts); kept as a local literal so the client bundle
+// doesn't pull in router-layer code. Overridden at startup by
+// setPrefetchConcurrency from server metadata.
+let maxConcurrent = 2;
 const IMAGE_WAIT_TIMEOUT = 2000;
 
+/**
+ * Set the max number of concurrently-executing speculative prefetches.
+ * Called once at app startup with the value from server metadata. A value
+ * below 1 (or non-finite) is ignored, keeping the default.
+ */
+export function setPrefetchConcurrency(n: number): void {
+  if (Number.isFinite(n) && n >= 1) {
+    maxConcurrent = Math.floor(n);
+  }
+}
+
 let active = 0;
 const queue: Array<{
   key: string;
@@ -42,7 +57,7 @@ function startExecution(
     abortControllers.delete(key);
     // Only decrement if this key wasn't already cleared by cancelAllPrefetches.
     // Without this guard, cancelled tasks' .finally() would underflow active
-    // below zero, breaking the MAX_CONCURRENT guarantee.
+    // below zero, breaking the maxConcurrent guarantee.
     if (executing.delete(key)) {
       active--;
     }
@@ -63,7 +78,7 @@ function startExecution(
  */
 function scheduleDrain(): void {
   if (drainScheduled) return;
-  if (active >= MAX_CONCURRENT || queue.length === 0) return;
+  if (active >= maxConcurrent || queue.length === 0) return;
   drainScheduled = true;
   const gen = drainGeneration;
   waitForIdle()
@@ -83,7 +98,7 @@ function scheduleDrain(): void {
 }
 
 function drain(): void {
-  while (active < MAX_CONCURRENT && queue.length > 0) {
+  while (active < maxConcurrent && queue.length > 0) {
     const item = queue.shift()!;
     queued.delete(item.key);
     startExecution(item.key, item.execute);

package/src/browser/react/Link.tsx

@@ -39,9 +39,16 @@ import {
   unobserveForPrefetch,
 } from "../prefetch/observer.js";
 
+// The (hover: none) MediaQueryList, created lazily on first client read and
+// reused across every Link render. matchMedia allocates and registers a live
+// query object; a fresh one per render (Link renders can be very frequent) is
+// wasteful when the same object's `.matches` is already live. Left null on the
+// server (no window).
+let hoverNoneQuery: MediaQueryList | null = null;
+
 /**
- * Read current touch/no-hover capability. Evaluated at the point of use (per
- * render) rather than once at module load, so `prefetch="adaptive"` reacts to
+ * Read current touch/no-hover capability from the cached MediaQueryList. The
+ * `.matches` read is live, so `prefetch="adaptive"` still reacts to
  * input-capability changes on hybrid devices (touch laptops, tablets gaining or
  * losing a pointer) and after SSR -> hydrate. The SSR guard returns a stable
  * `false` (pointer/hover default) so the resolved strategy doesn't drift on the
@@ -49,7 +56,10 @@ import {
  */
 function isTouchDevice(): boolean {
   if (typeof window === "undefined") return false;
-  return window.matchMedia("(hover: none)").matches;
+  if (!hoverNoneQuery) {
+    hoverNoneQuery = window.matchMedia("(hover: none)");
+  }
+  return hoverNoneQuery.matches;
 }
 
 /**

package/src/browser/react/NavigationProvider.tsx

@@ -31,6 +31,11 @@ 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 {
+  deferredHandleNames,
+  resolveDeferredHandleValues,
+} from "../../handles/deferred-resolution.js";
 
 /**
  * Process handles from an async generator, updating the event controller
@@ -66,6 +71,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 +97,91 @@ async function processHandles(
     }
 
     yieldCount++;
-    eventController.setHandleData(handleData, matched, isPartial, resolvedIds);
+
+    // Resolve-by-default: hold the previous resolved value until this yield's
+    // deferred (Promise) handle values settle, then apply the fully-resolved
+    // snapshot. The hold needs NO extra state — we simply do not touch the store
+    // until the values resolve, so useHandle keeps reading (and showing) the
+    // previous data. A yield with no deferred value applies synchronously.
+    const hasDeferred = deferredHandleNames(handleData).size > 0;
+
+    if (!hasDeferred) {
+      eventController.setHandleData(
+        handleData,
+        matched,
+        isPartial,
+        resolvedIds,
+      );
+      // Keep the cache fresh. The token guard stops a stale same-URL nav writing
+      // a newer entry; the owned-write folds probe + write into one scan.
+      store.updateCacheHandleDataIfOwned(
+        historyKey,
+        eventController.getHandleState().data,
+        myInstance,
+        false,
+      );
+      continue;
+    }
+
+    // The PREVIOUS (held) snapshot — captured before the await so the cache and
+    // the navigate-away merge below reflect what useHandle is still showing.
+    const previousSnapshot = cloneHandleData(
+      eventController.getHandleState().data,
+    );
+
+    // The route HAS changed even though the handle data is held, so update
+    // `routeSegmentIds` (what useSegments reads) now. This leaves `data` /
+    // `segmentOrder` (what useHandle collects over) untouched, so useHandle keeps
+    // holding its previous value while useSegments reflects the new route.
+    eventController.setRouteSegmentIds(matched ?? []);
+
+    // Deferred-pending: the new values are not applied yet (the previous value is
+    // held), so the cache entry must NOT be served as fresh on a popstate return.
+    // Mark it STALE + handlesPending (token-guarded), storing the PREVIOUS (held)
+    // snapshot. P1 fix: a deferred value is a SERVER-side promise streamed via
+    // Flight, so a navigate-away ABORTS the stream and the resolve below never
+    // settles. 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 value would never land (see the
+    // segmentIds branch in navigation-bridge.ts).
+    store.updateCacheHandleDataIfOwned(
+      historyKey,
+      previousSnapshot,
+      myInstance,
+      true,
+      true,
+    );
+
+    // Resolve every deferred value (allSettled; rejected + nullish dropped, sync
+    // values pass through). Each stream yield is a full cumulative snapshot.
+    const resolved = await resolveDeferredHandleValues(handleData);
+
+    if (!stillLive()) {
+      // Navigated away (or a same-URL nav superseded us) while resolving. We do
+      // NOT write `resolved` into the entry. It is THIS yield's snapshot only (on a
+      // partial nav, just the re-resolved segments' buckets), and a correct write
+      // needs setHandleData's nested per-segment merge + matched/resolvedIds
+      // cleanup: HandleData is handleName -> segmentId -> entries[], so a
+      // handle-name-level spread would drop a shared layout bucket (e.g. a
+      // Breadcrumbs layout crumb under L0 when the route pushed under R0) and would
+      // mark stale previous-route buckets fresh. We cannot run that merge here
+      // without touching the now-different live page. Instead leave the entry as it
+      // was marked before the await — stale + handlesPending — so a popstate return
+      // revalidates with a full re-render and re-streams the handles. A newer nav
+      // owning the entry has already overwritten it; nothing to do either way.
+      continue;
+    }
+
+    // Still live: apply the fully-resolved snapshot and refresh the cache fresh.
+    eventController.setHandleData(resolved, matched, isPartial, resolvedIds);
+    store.updateCacheHandleDataIfOwned(
+      historyKey,
+      eventController.getHandleState().data,
+      myInstance,
+      false,
+      false,
+    );
   }
 
   // Check again before final updates
@@ -97,8 +199,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 +465,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