@rangojs/router 0.0.0-experimental.bd6e11bc → 0.0.0-experimental.bdaf10aa

package/src/browser/navigation-store.ts

@@ -12,10 +12,7 @@ import type {
   ActionStateListener,
   HandleData,
 } from "./types.js";
-import {
-  clearPrefetchCache,
-  clearPrefetchCacheLocal,
-} from "./prefetch/cache.js";
+import { clearPrefetchCache } from "./prefetch/cache.js";
 
 /**
  * Default action state (idle with no payload)
@@ -31,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;
 }
@@ -133,14 +150,14 @@ export interface NavigationStoreConfig {
 
   /**
    * Enable cross-tab cache invalidation via BroadcastChannel (default: true)
-   * When cache is cleared (via server actions or useClientCache().clear()),
+   * When cache is cleared (via server actions or invalidateClientCache()),
    * other tabs will also clear their cache
    */
   crossTabSync?: boolean;
 
   /**
    * Auto-refresh when another tab mutates data on the same path (default: true)
-   * Triggered when cache is cleared via server actions or useClientCache().clear()
+   * Triggered when cache is cleared via server actions or invalidateClientCache()
    * Requires crossTabSync to be enabled
    */
   crossTabAutoRefresh?: boolean;
@@ -242,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();
 
@@ -251,6 +276,10 @@ export function createNavigationStore(
       config.initialHistoryKey,
       config.initialSegments,
       false,
+      undefined,
+      undefined,
+      ++navInstance,
+      false,
     ]);
   }
 
@@ -338,24 +367,24 @@ export function createNavigationStore(
   }
 
   /**
-   * Drop this tab's navigation + prefetch caches without broadcasting or
-   * rotating shared state. Used when the local session changes in a way that
-   * doesn't affect other tabs — e.g. this tab crosses into a different app
-   * via a cross-router navigation. Other tabs in the old app keep their
-   * caches and their X-Rango-State token.
+   * Mark every history entry stale WITHOUT touching the prefetch caches or the
+   * rango state. Used by the jar-divergence observer: an external rotation has
+   * already changed the state value (so prefetch/HTTP entries strand under the
+   * retired key), and this tab must NOT re-rotate — only the history cache,
+   * which is not state-keyed, needs marking.
    */
-  function clearCacheInternalLocal(): void {
-    historyCache.length = 0;
-    clearPrefetchCacheLocal();
+  function markHistoryStale(): void {
+    for (let i = 0; i < historyCache.length; i++) {
+      historyCache[i][2] = true;
+    }
   }
 
   /**
-   * Mark all cache entries as stale (internal - does not broadcast)
+   * Mark all cache entries as stale (internal - does not broadcast). Also
+   * clears the prefetch caches, which rotates the rango state.
    */
   function markCacheAsStaleInternal(): void {
-    for (let i = 0; i < historyCache.length; i++) {
-      historyCache[i][2] = true;
-    }
+    markHistoryStale();
     clearPrefetchCache();
   }
 
@@ -568,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
@@ -586,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,
@@ -597,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)
@@ -606,6 +665,8 @@ export function createNavigationStore(
           false,
           clonedHandleData,
           currentRouterId,
+          instance,
+          false,
         ]);
         // Remove oldest entries if over limit
         while (historyCache.length > cacheSize) {
@@ -624,6 +685,7 @@ export function createNavigationStore(
           stale: boolean;
           handleData?: HandleData;
           routerId?: string;
+          handlesPending?: boolean;
         }
       | undefined {
       const entry = historyCache.find(([key]) => key === historyKey);
@@ -633,6 +695,7 @@ export function createNavigationStore(
         stale: entry[2],
         handleData: entry[3],
         routerId: entry[4],
+        handlesPending: entry[6],
       };
     },
 
@@ -644,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,
       );
@@ -659,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
@@ -675,20 +786,21 @@ export function createNavigationStore(
     },
 
     /**
-     * Clear the history cache and broadcast to other tabs
-     * Use this for hard invalidation when data is definitely stale
+     * Mark every history entry stale WITHOUT clearing the prefetch caches or
+     * rotating the rango state. The jar-divergence observer calls this after an
+     * external rotation has already changed the state value, so re-rotating
+     * here would ping-pong with the tab that rotated.
      */
-    clearHistoryCache(): void {
-      clearCacheAndBroadcast();
+    markHistoryCacheStale(): void {
+      markHistoryStale();
     },
 
     /**
-     * Drop this tab's navigation + prefetch caches locally without
-     * broadcasting or rotating shared state. Intended for cross-app
-     * transitions where the session state diverges for this tab only.
+     * Clear the history cache and broadcast to other tabs
+     * Use this for hard invalidation when data is definitely stale
      */
-    clearHistoryCacheLocal(): void {
-      clearCacheInternalLocal();
+    clearHistoryCache(): void {
+      clearCacheAndBroadcast();
     },
 
     /**
@@ -699,14 +811,6 @@ export function createNavigationStore(
       markStaleAndBroadcast();
     },
 
-    /**
-     * Broadcast cache invalidation to other tabs without clearing local cache
-     * Used after consolidation fetch where local cache has fresh data
-     */
-    broadcastCacheInvalidation(): void {
-      broadcastInvalidation();
-    },
-
     /**
      * Set the callback to invoke when cross-tab refresh is triggered
      * Called by navigation bridge during initialization
@@ -823,42 +927,3 @@ export function createNavigationStore(
     },
   };
 }
-
-// Singleton store instance
-let storeInstance: NavigationStore | null = null;
-
-/**
- * Initialize the global navigation store
- *
- * Should be called once during app initialization.
- * Subsequent calls return the existing instance.
- */
-export function initNavigationStore(
-  config?: NavigationStoreConfig,
-): NavigationStore {
-  if (!storeInstance) {
-    storeInstance = createNavigationStore(config);
-  }
-  return storeInstance;
-}
-
-/**
- * Get the global navigation store
- *
- * Throws if store hasn't been initialized.
- */
-export function getNavigationStore(): NavigationStore {
-  if (!storeInstance) {
-    throw new Error(
-      "Navigation store not initialized. Call initNavigationStore first.",
-    );
-  }
-  return storeInstance;
-}
-
-/**
- * Reset the store instance (for testing)
- */
-export function resetNavigationStore(): void {
-  storeInstance = null;
-}

package/src/browser/navigation-transaction.ts

@@ -13,7 +13,6 @@ import type { EventController, NavigationHandle } from "./event-controller.js";
 import { debugLog } from "./logging.js";
 import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
 
-// Re-export for consumers that import from navigation-transaction
 export { resolveNavigationState } from "./history-state.js";
 
 /** Check if a history state object contains location state keys. */
@@ -25,7 +24,6 @@ function hasLocationState(state: unknown): boolean {
   );
 }
 
-// Polyfill Symbol.dispose for Safari and older browsers
 if (typeof Symbol.dispose === "undefined") {
   (Symbol as any).dispose = Symbol("Symbol.dispose");
 }
@@ -114,7 +112,6 @@ export function createNavigationTransaction(
   let committed = false;
   const currentUrl = window.location.href;
 
-  // Start navigation in event controller (this sets loading state)
   const handle = eventController.startNavigation(url, options);
 
   /**
@@ -138,72 +135,50 @@ export function createNavigationTransaction(
 
     const parsedUrl = new URL(url, window.location.origin);
 
-    // Generate history key from URL (with intercept suffix for separate caching)
     const historyKey = generateHistoryKey(url, { intercept });
 
-    // For cache-only commits (stale revalidation), only update cache and return
-    // Don't touch store state or history - user may have navigated elsewhere
     if (cacheOnly) {
       const currentHandleData = eventController.getHandleState().data;
       store.cacheSegmentsForHistory(historyKey, segments, currentHandleData);
-      // Complete the navigation handle so currentNavigation is cleared.
-      // Without this, the entry lingers and weakens state-machine invariants.
       handle.complete(parsedUrl);
       debugLog("[Browser] Cache-only commit, historyKey:", historyKey);
       return { scroll: false };
     }
 
-    // Save current scroll position before navigating
     handleNavigationStart();
 
-    // Update segment state atomically
     store.setSegmentIds(segmentIds);
     store.setCurrentUrl(url);
     store.setPath(parsedUrl.pathname);
 
     store.setHistoryKey(historyKey);
 
-    // Cache segments with current handleData for this history entry
     const currentHandleData = eventController.getHandleState().data;
     store.cacheSegmentsForHistory(historyKey, segments, currentHandleData);
 
-    // For server actions, skip URL/history updates but still complete navigation
     if (storeOnly) {
       debugLog("[Browser] Store updated (action)");
-      // Complete navigation to clear loading state
       handle.complete(parsedUrl);
       return { scroll: false };
     }
 
-    // Build history state - include user state, intercept info, and server-set state
     const historyState = buildHistoryState(
       opts.state,
       { intercept, sourceUrl: interceptSourceUrl },
       serverState,
     );
 
-    // Snapshot old state before pushState/replaceState overwrites it.
-    // Used to detect when location state is being cleared.
     const oldState = window.history.state;
 
-    // Update browser URL (stamps history.state.idx for back() first-entry detection)
     pushHistoryWithIdx(historyState, url, replace ?? false);
-    // Ensure new history entry has a scroll restoration key
     ensureHistoryKey();
 
-    // Notify location state hooks when either old or new state carries
-    // location state. This covers both "set new state" and "clear old state"
-    // for same-page navigations where components don't remount.
     if (hasLocationState(oldState) || hasLocationState(historyState)) {
       window.dispatchEvent(new Event("__rsc_locationstate"));
     }
 
-    // Complete the navigation in event controller (sets idle state, updates location)
     handle.complete(parsedUrl);
 
-    // NOTE: Scroll is NOT handled here. The caller (partial-update.ts) handles
-    // scroll AFTER onUpdate() so React has the new content before we scroll.
-
     debugLog(
       "[Browser] Navigation committed, historyKey:",
       historyKey,
@@ -217,10 +192,6 @@ export function createNavigationTransaction(
     handle,
     commit,
 
-    /**
-     * Create a bound transaction with pre-configured URL options
-     * segmentIds and segments provided at commit time (after they're resolved)
-     */
     with(
       opts: Omit<CommitOptions, "segmentIds" | "segments">,
     ): BoundTransaction {
@@ -264,13 +235,10 @@ export function createNavigationTransaction(
     },
 
     [Symbol.dispose]() {
-      // Superseded: another navigation took over.
       if (handle.signal.aborted) {
         return;
       }
 
-      // Failed (not committed): keep the target URL -- the error UI owns it.
-      // Just reset the event controller to idle.
       if (!committed) {
         handle[Symbol.dispose]();
       }

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