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

package/src/browser/navigation-store.ts

@@ -28,14 +28,28 @@ const DEFAULT_ACTION_STATE: TrackedActionState = {
 // Maximum number of history entries to cache (URLs visited)
 const HISTORY_CACHE_SIZE = 20;
 
-// Cache entry: [url-key, segments, stale, handleData?, routerId?]
-// stale=true means the data may be outdated and should be revalidated on access
+// Cache entry:
+//   [url-key, segments, stale, handleData?, routerId?, navInstance?, handlesPending?]
+// stale=true means the data may be outdated and should be revalidated on access.
+// navInstance is the monotonic nav-instance token (see navInstance below): it
+// identifies the per-commit visit that owns this entry. generateHistoryKey is
+// URL-only, so A->B->A reuses the same key; the token lets a late async
+// resolution tell its own visit's entry apart from a newer same-URL visit's, so
+// a stale nav can never clobber a fresher one.
+// handlesPending=true means the entry's handle data is INCOMPLETE (a deferred
+// Meta was still pending when the user navigated away, so it never streamed). A
+// popstate return must REVALIDATE WITH A FULL RE-RENDER (no client segment IDs)
+// to re-stream the handles — a diff-only revalidation omits unchanged segments'
+// handles, so the deferred Meta would never land. Cleared once the deferred Meta
+// resolves while the entry is still owned.
 type HistoryCacheEntry = [
   string,
   ResolvedSegment[],
   boolean,
   HandleData?,
   string?,
+  number?,
+  boolean?,
 ];
 
 /**
@@ -44,7 +58,7 @@ type HistoryCacheEntry = [
  * since mutations happen at the array level, not on individual data objects.
  * This preserves any non-serializable types (React elements, functions, etc.)
  */
-function cloneHandleData(handleData: HandleData): HandleData {
+export function cloneHandleData(handleData: HandleData): HandleData {
   const cloned: HandleData = {};
   for (const [handleKey, segmentMap] of Object.entries(handleData)) {
     cloned[handleKey] = {};
@@ -239,6 +253,14 @@ export function createNavigationStore(
   // Oldest entries (at front) are removed when over cacheSize limit
   const historyCache: HistoryCacheEntry[] = [];
 
+  // Monotonic nav-instance token. Bumped each time a cache entry is created or
+  // replaced in cacheSegmentsForHistory (i.e. once per commit). Because
+  // generateHistoryKey is URL-only, two visits to the same URL share a key; this
+  // token gives each visit a distinct identity so a late async handle resolution
+  // can tell whether it still owns the live page / the target cache entry, and
+  // never overwrite a newer same-URL visit's state.
+  let navInstance = 0;
+
   // Current history key (set on navigation, stored in history.state)
   let currentHistoryKey = config?.initialHistoryKey || generateHistoryKey();
 
@@ -248,6 +270,10 @@ export function createNavigationStore(
       config.initialHistoryKey,
       config.initialSegments,
       false,
+      undefined,
+      undefined,
+      ++navInstance,
+      false,
     ]);
   }
 
@@ -565,6 +591,29 @@ export function createNavigationStore(
       currentHistoryKey = key;
     },
 
+    /**
+     * Current nav-instance token: the instance of the most recently committed
+     * navigation (the value last written by cacheSegmentsForHistory). A late
+     * async handle resolution captures this at the start of its own nav and
+     * compares it back here to detect whether a NEWER navigation has since
+     * committed (token advanced), guarding against a stale nav writing a fresher
+     * nav's live state.
+     */
+    getNavInstance(): number {
+      return navInstance;
+    },
+
+    /**
+     * The nav-instance token recorded on a specific cache entry, or undefined if
+     * no entry exists for that key. Because the history key is URL-only, this is
+     * how a late resolution tells "the entry I seeded is still mine" from "a
+     * newer same-URL visit replaced my entry".
+     */
+    getCacheEntryInstance(historyKey: string): number | undefined {
+      const entry = historyCache.find(([key]) => key === historyKey);
+      return entry ? entry[5] : undefined;
+    },
+
     /**
      * Store segments for a history entry
      * Updates existing entry if key exists, otherwise adds new entry
@@ -583,6 +632,11 @@ export function createNavigationStore(
         ? cloneHandleData(handleData)
         : undefined;
 
+      // Each commit (create or replace) is a new nav instance. The bump happens
+      // here, exactly once per cacheSegmentsForHistory call, so getNavInstance()
+      // reflects the visit whose entry this is.
+      const instance = ++navInstance;
+
       // Check if entry already exists and update it
       const existingIndex = historyCache.findIndex(
         ([key]) => key === historyKey,
@@ -594,6 +648,8 @@ export function createNavigationStore(
           false,
           clonedHandleData,
           currentRouterId,
+          instance,
+          false, // fresh commit: handles complete unless a deferred apply marks it
         ];
       } else {
         // Add new entry at the end (not stale)
@@ -603,6 +659,8 @@ export function createNavigationStore(
           false,
           clonedHandleData,
           currentRouterId,
+          instance,
+          false,
         ]);
         // Remove oldest entries if over limit
         while (historyCache.length > cacheSize) {
@@ -621,6 +679,7 @@ export function createNavigationStore(
           stale: boolean;
           handleData?: HandleData;
           routerId?: string;
+          handlesPending?: boolean;
         }
       | undefined {
       const entry = historyCache.find(([key]) => key === historyKey);
@@ -630,6 +689,7 @@ export function createNavigationStore(
         stale: entry[2],
         handleData: entry[3],
         routerId: entry[4],
+        handlesPending: entry[6],
       };
     },
 
@@ -641,11 +701,23 @@ export function createNavigationStore(
     },
 
     /**
-     * Update only the handleData for an existing cache entry
-     * Does nothing if the cache entry doesn't exist
-     * This is used to fix stale handleData after async handles processing
+     * Update only the handleData (and optionally the stale flag) for an existing
+     * cache entry. Does nothing if the cache entry doesn't exist.
+     *
+     * Used to fix stale handleData after async handles processing AND to flip an
+     * entry's stale / handlesPending bits for the deferred-Meta
+     * invalidate+revalidate path: while a nav's Meta is deferred-pending its
+     * entry is marked stale + handlesPending (a popstate return then revalidates
+     * with a full re-render instead of serving the carry/seed as fresh), and once
+     * the deferred Meta resolves both are cleared. When a flag is omitted the
+     * entry's current value is preserved.
      */
-    updateCacheHandleData(historyKey: string, handleData: HandleData): void {
+    updateCacheHandleData(
+      historyKey: string,
+      handleData: HandleData,
+      stale?: boolean,
+      handlesPending?: boolean,
+    ): void {
       const existingIndex = historyCache.findIndex(
         ([key]) => key === historyKey,
       );
@@ -656,9 +728,11 @@ export function createNavigationStore(
         historyCache[existingIndex] = [
           entry[0],
           entry[1],
-          entry[2],
+          stale ?? entry[2], // set stale when provided, else preserve current
           clonedHandleData,
           entry[4], // preserve routerId
+          entry[5], // preserve navInstance (entry ownership identity)
+          handlesPending ?? entry[6], // set when provided, else preserve current
         ];
       }
     },

package/src/browser/network-error-handler.ts

@@ -1,5 +1,5 @@
 import { NetworkError, isNetworkError } from "../errors.js";
-import { NetworkErrorThrower } from "../network-error-thrower.js";
+import { RenderErrorThrower } from "../render-error-thrower.js";
 import type { UpdateSubscriber } from "./types.js";
 import { createElement, startTransition } from "react";
 
@@ -24,18 +24,18 @@ export function toNetworkError(
 }
 
 /**
- * Emit a NetworkError to the UI via the onUpdate subscriber.
- * Wraps in startTransition and renders a NetworkErrorThrower component
- * that throws during render to trigger the nearest error boundary.
+ * Render an error into the segment tree via the onUpdate subscriber so the
+ * nearest error boundary catches it. Wrapped in startTransition; RenderErrorThrower
+ * throws during render (async rejections do not reach boundaries on their own).
  */
-export function emitNetworkError(
+function emitErrorToBoundary(
   onUpdate: UpdateSubscriber,
-  error: NetworkError,
+  error: unknown,
   pathname: string,
 ): void {
   startTransition(() => {
     onUpdate({
-      root: createElement(NetworkErrorThrower, { error }),
+      root: createElement(RenderErrorThrower, { error }),
       metadata: {
         pathname,
         segments: [],
@@ -45,6 +45,33 @@ export function emitNetworkError(
   });
 }
 
+/**
+ * Emit a NetworkError to the nearest error boundary (offline, failed fetch).
+ */
+export function emitNetworkError(
+  onUpdate: UpdateSubscriber,
+  error: NetworkError,
+  pathname: string,
+): void {
+  emitErrorToBoundary(onUpdate, error, pathname);
+}
+
+/**
+ * Emit a navigation processing error to the nearest error boundary. Used when a
+ * navigation response cannot be processed (an undecodable Flight body, or any
+ * unanticipated failure while building the response) -- for both fresh and
+ * prefetched responses, since both funnel through the navigation catch. Without
+ * this, such a failure becomes an uncaught rejection that silently aborts the
+ * navigation instead of surfacing the route's error boundary.
+ */
+export function emitNavigationError(
+  onUpdate: UpdateSubscriber,
+  error: unknown,
+  pathname: string,
+): void {
+  emitErrorToBoundary(onUpdate, error, pathname);
+}
+
 /**
  * Check if an error is safe to suppress in background operations.
  *

package/src/browser/partial-update.ts

@@ -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
@@ -505,6 +516,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