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

package/src/browser/merge-segment-loaders.ts

@@ -1,5 +1,5 @@
 import type { ResolvedSegment } from "./types.js";
-import { debugLog } from "./logging.js";
+import { debugLog, IS_BROWSER_DEBUG } from "./logging.js";
 
 /**
  * Merge partial loader data from server with cached loader data.
@@ -19,9 +19,11 @@ export function mergeSegmentLoaders(
   const serverLoaderIds = fromServer.loaderIds || [];
   const cachedLoaderIds = fromCache.loaderIds || [];
 
-  debugLog(
-    `[Browser] Merging partial loaders: server has ${serverLoaderIds.join(", ")}, cache has ${cachedLoaderIds.join(", ")}`,
-  );
+  if (IS_BROWSER_DEBUG) {
+    debugLog(
+      `[Browser] Merging partial loaders: server has ${serverLoaderIds.join(", ")}, cache has ${cachedLoaderIds.join(", ")}`,
+    );
+  }
 
   return {
     ...fromCache,

package/src/browser/navigation-bridge.ts

@@ -32,6 +32,7 @@ import { isInterceptOnlyCache } from "./intercept-utils.js";
 import {
   toNetworkError,
   emitNetworkError,
+  emitNavigationError,
   isBackgroundSuppressible,
 } from "./network-error-handler.js";
 import { debugLog } from "./logging.js";
@@ -215,17 +216,20 @@ export function createNavigationBridge(
         store.setInterceptSourceUrl(null);
       }
 
-      // Before navigating away, update the source page's cache with the latest handleData.
-      // This ensures the cache has correct handleData even if handles were streaming.
+      // Before navigating away, update the source page's cache with the latest
+      // handleData. This ensures the cache has correct handleData even if handles
+      // were streaming. Use updateCacheHandleData (not cacheSegmentsForHistory):
+      // the source page's segments are unchanged, so this is a handleData refresh,
+      // not a commit. Critically it PRESERVES the entry's stale flag — when the
+      // source page has a deferred Meta still pending, its entry was marked stale
+      // (invalidate-on-pending) so a popstate return revalidates; re-committing it
+      // here would reset stale to false and serve the carried (pre-resolution)
+      // title as fresh. It also leaves the nav-instance token intact.
       const sourceHistoryKey = store.getHistoryKey();
       const sourceCached = store.getCachedSegments(sourceHistoryKey);
       if (sourceCached?.segments && sourceCached.segments.length > 0) {
         const currentHandleData = eventController.getHandleState().data;
-        store.cacheSegmentsForHistory(
-          sourceHistoryKey,
-          sourceCached.segments,
-          currentHandleData,
-        );
+        store.updateCacheHandleData(sourceHistoryKey, currentHandleData);
       }
 
       // Check if we have cached segments for target URL
@@ -325,8 +329,15 @@ export function createNavigationBridge(
           } as NavigateOptionsInternal);
         }
 
-        if (error instanceof DOMException && error.name === "AbortError") {
-          debugLog("[Browser] Navigation aborted by newer navigation");
+        // Aborted, or superseded by a newer navigation. A superseded nav may
+        // reject with a non-AbortError (e.g. a Flight decode that fails after its
+        // signal was aborted), so check the signal too -- otherwise we would
+        // render a boundary that clobbers the newer navigation's content.
+        if (
+          (error instanceof DOMException && error.name === "AbortError") ||
+          tx.handle.signal.aborted
+        ) {
+          debugLog("[Browser] Navigation aborted or superseded");
           return;
         }
 
@@ -343,7 +354,13 @@ export function createNavigationBridge(
           return;
         }
 
-        throw error;
+        // A response we could not process (undecodable Flight body, or an
+        // unanticipated failure building the response). Surface the route's
+        // error boundary rather than let the rejection abort the navigation
+        // silently. Prefetched responses funnel here too: a failed warm-prefetch
+        // payload rejects on consumption and propagates to this catch.
+        console.error("[Browser] Unprocessable navigation response:", error);
+        emitNavigationError(onUpdate, error, url);
       } finally {
         tx[Symbol.dispose]();
       }
@@ -372,6 +389,14 @@ export function createNavigationBridge(
           tx.with({ url: window.location.href, replace: true, scroll: false }),
         );
       } catch (error) {
+        // Aborted or superseded: bail without rendering a boundary (see navigate()).
+        if (
+          (error instanceof DOMException && error.name === "AbortError") ||
+          tx.handle.signal.aborted
+        ) {
+          return;
+        }
+
         const networkError = toNetworkError(error, {
           url: window.location.href,
           operation: "revalidation",
@@ -384,7 +409,12 @@ export function createNavigationBridge(
           emitNetworkError(onUpdate, networkError, window.location.href);
           return;
         }
-        throw error;
+
+        // refresh() shares the fetchPartialUpdate chokepoint with navigate()/
+        // popstate, so an unprocessable response must surface the error boundary
+        // here too rather than become an uncaught rejection.
+        console.error("[Browser] Unprocessable refresh response:", error);
+        emitNavigationError(onUpdate, error, window.location.href);
       } finally {
         tx[Symbol.dispose]();
       }
@@ -527,8 +557,19 @@ export function createNavigationBridge(
           // SWR: If stale, trigger background revalidation
           if (isStale) {
             debugLog("[Browser] Cache is stale, background revalidating...");
-            // Background revalidation - don't await, just fire and forget
-            const segmentIds = cachedSegments.map((s) => s.id);
+            // Background revalidation - don't await, just fire and forget.
+            // When the entry's handles are incomplete (a deferred Meta was still
+            // pending when the user navigated away — see handlesPending), send NO
+            // segment IDs so the server returns a FULL re-render with the handle
+            // stream. A normal stale revalidation sends the cached IDs and the
+            // server returns a diff-only payload that omits unchanged segments'
+            // handles, so a deferred Meta would never re-stream and the title
+            // would stay the pre-resolution carry. handlesPending is set only for
+            // the deferred-Meta-aborted case, so action/cross-tab SWR keeps the
+            // cheap diff path.
+            const segmentIds = cached?.handlesPending
+              ? []
+              : cachedSegments.map((s) => s.id);
 
             const tx = createNavigationTransaction(
               store,
@@ -602,8 +643,13 @@ export function createNavigationBridge(
         // Restore scroll position after fetch completes
         handleNavigationEnd({ restore: true, isStreaming });
       } catch (error) {
-        if (error instanceof DOMException && error.name === "AbortError") {
-          debugLog("[Browser] Popstate navigation aborted");
+        // Aborted or superseded by a newer navigation: bail without clobbering
+        // content with a boundary (see navigate()).
+        if (
+          (error instanceof DOMException && error.name === "AbortError") ||
+          tx.handle.signal.aborted
+        ) {
+          debugLog("[Browser] Popstate navigation aborted or superseded");
           return;
         }
 
@@ -620,7 +666,10 @@ export function createNavigationBridge(
           return;
         }
 
-        throw error;
+        // Unprocessable response on a back/forward navigation: surface the
+        // error boundary instead of an uncaught rejection (see navigate()).
+        console.error("[Browser] Unprocessable popstate response:", error);
+        emitNavigationError(onUpdate, error, url);
       } finally {
         tx[Symbol.dispose]();
       }

package/src/browser/navigation-client.ts

@@ -8,6 +8,7 @@ import type {
 import { NetworkError, ServerRedirect, isNetworkError } from "../errors.js";
 import {
   browserDebugLog,
+  debugLog,
   isBrowserDebugEnabled,
   startBrowserTransaction,
 } from "./logging.js";
@@ -222,7 +223,11 @@ export function createNavigationClient(
           ...(isActionFenceActive() && { cache: "no-store" as RequestCache }),
           headers: {
             "X-RSC-Router-Client-Path": previousUrl,
-            "X-Rango-State": getRangoState(),
+            // Reuse the single per-operation read (see rangoState above): the
+            // cache-key lookup and this header must agree on one value, and the
+            // cookie read has side effects (external-rotation notify) we do not
+            // want to fire twice per navigation.
+            "X-Rango-State": rangoState,
             ...(tx && { "X-RSC-Router-Request-Id": tx.requestId }),
             ...(interceptSourceUrl && {
               "X-RSC-Router-Intercept-Source": interceptSourceUrl,
@@ -260,6 +265,10 @@ export function createNavigationClient(
 
       let payloadPromise: Promise<RscPayload>;
       let streamCompletePromise: Promise<void>;
+      // True only for a prefetch-cache hit whose stream had already fully drained
+      // (complete === true). A still-streaming hit and the fresh path stay false,
+      // so only a fully-warmed prefetch commits in a transition (no fallback flash).
+      let fullyPrefetched = false;
 
       if (cachedEntry) {
         if (tx) {
@@ -270,6 +279,9 @@ export function createNavigationClient(
         }
         payloadPromise = cachedEntry.payload;
         streamCompletePromise = cachedEntry.streamComplete;
+        // Only a hit whose stream already fully drained is "fully prefetched";
+        // a still-streaming hit must keep streaming its fallbacks like a cold load.
+        fullyPrefetched = cachedEntry.complete;
       } else if (inflightEntryPromise) {
         if (tx) {
           browserDebugLog(tx, "reusing inflight prefetch", {
@@ -299,6 +311,9 @@ export function createNavigationClient(
         } else {
           payloadPromise = entry.payload;
           streamCompletePromise = entry.streamComplete;
+          // Adopted inflight is normally still streaming (false), but read the
+          // flag in case it completed between publish and adoption.
+          fullyPrefetched = entry.complete;
         }
       } else {
         ({ payload: payloadPromise, streamComplete: streamCompletePromise } =
@@ -306,7 +321,18 @@ export function createNavigationClient(
       }
 
       try {
+        // [VT-DIAG] Gated behind INTERNAL_RANGO_DEBUG. Times how long the RSC
+        // payload ROOT takes to resolve: ~full-stream duration means the root
+        // model is not flushed early (server/runtime buffering, e.g. wrangler
+        // dev gzip); fast means the block, if any, is downstream in render.
+        const vtDebugStart = isBrowserDebugEnabled() ? performance.now() : 0;
         const payload = await payloadPromise;
+        if (isBrowserDebugEnabled()) {
+          debugLog("[VT-DIAG] payloadResolved", {
+            ms: Math.round(performance.now() - vtDebugStart),
+            isPartial: payload.metadata?.isPartial,
+          });
+        }
 
         if (tx) {
           browserDebugLog(tx, "response received", {
@@ -315,7 +341,11 @@ export function createNavigationClient(
             diffCount: payload.metadata?.diff?.length ?? 0,
           });
         }
-        return { payload, streamComplete: streamCompletePromise };
+        return {
+          payload,
+          streamComplete: streamCompletePromise,
+          fullyPrefetched,
+        };
       } catch (error) {
         // Convert network-level errors to NetworkError for proper handling
         if (isNetworkError(error)) {

package/src/browser/navigation-store.ts

@@ -28,29 +28,49 @@ 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?,
 ];
 
 /**
- * Shallow clone handleData to avoid reference sharing between cache entries.
- * Only clones the structure (objects and arrays), not the data items themselves,
- * since mutations happen at the array level, not on individual data objects.
- * This preserves any non-serializable types (React elements, functions, etc.)
+ * Clone the handleData CONTAINERS (the handle-name map and each segment map) so
+ * a cache entry is decoupled from the live map that eventController mutates — it
+ * adds/deletes segment keys and REPLACES bucket arrays in place. The bucket
+ * arrays themselves are shared by reference, NOT copied: a bucket array is only
+ * ever replaced wholesale (eventController.setHandleData reassigns it,
+ * resolveDeferredHandleValues builds a fresh one) and collect functions read it
+ * without mutating, so sharing is safe and skips an O(elements) copy on every
+ * cache write — the per-yield streaming hot path. This also preserves any
+ * non-serializable bucket contents (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] = {};
+    const clonedMap: Record<string, unknown[]> = {};
     for (const [segmentId, dataArray] of Object.entries(segmentMap)) {
-      cloned[handleKey][segmentId] = [...dataArray];
+      clonedMap[segmentId] = dataArray;
     }
+    cloned[handleKey] = clonedMap;
   }
   return cloned;
 }
@@ -239,6 +259,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 +276,10 @@ export function createNavigationStore(
       config.initialHistoryKey,
       config.initialSegments,
       false,
+      undefined,
+      undefined,
+      ++navInstance,
+      false,
     ]);
   }
 
@@ -565,6 +597,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 +638,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 +654,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 +665,8 @@ export function createNavigationStore(
           false,
           clonedHandleData,
           currentRouterId,
+          instance,
+          false,
         ]);
         // Remove oldest entries if over limit
         while (historyCache.length > cacheSize) {
@@ -621,6 +685,7 @@ export function createNavigationStore(
           stale: boolean;
           handleData?: HandleData;
           routerId?: string;
+          handlesPending?: boolean;
         }
       | undefined {
       const entry = historyCache.find(([key]) => key === historyKey);
@@ -630,6 +695,7 @@ export function createNavigationStore(
         stale: entry[2],
         handleData: entry[3],
         routerId: entry[4],
+        handlesPending: entry[6],
       };
     },
 
@@ -641,11 +707,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,13 +734,49 @@ 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
         ];
       }
     },
 
+    /**
+     * Owner-guarded handle-data write: locate the entry, and write ONLY when it
+     * is still owned by `ownerInstance` (the nav-instance token that seeded it).
+     * Folds the streaming hot path's separate getCacheEntryInstance() ownership
+     * probe and updateCacheHandleData() write into a SINGLE historyCache scan
+     * (processHandles calls this per yield). Semantics otherwise match
+     * updateCacheHandleData: no-op on a missing entry, clone the handleData
+     * containers, and preserve stale / handlesPending when the flag is omitted.
+     */
+    updateCacheHandleDataIfOwned(
+      historyKey: string,
+      handleData: HandleData,
+      ownerInstance: number,
+      stale?: boolean,
+      handlesPending?: boolean,
+    ): void {
+      const existingIndex = historyCache.findIndex(
+        ([key]) => key === historyKey,
+      );
+      if (existingIndex === -1) return;
+      const entry = historyCache[existingIndex];
+      if (entry[5] !== ownerInstance) return;
+      const clonedHandleData = cloneHandleData(handleData);
+      historyCache[existingIndex] = [
+        entry[0],
+        entry[1],
+        stale ?? entry[2],
+        clonedHandleData,
+        entry[4],
+        entry[5],
+        handlesPending ?? entry[6],
+      ];
+    },
+
     /**
      * Mark all cache entries as stale
      * Called after server actions to indicate data may be outdated

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.
  *