@rangojs/router 0.0.0-experimental.ce770c9a → 0.0.0-experimental.d5d3070a

package/src/browser/navigation-store.ts

@@ -28,9 +28,15 @@ 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?]
+// Cache entry: [url-key, segments, stale, handleData?, routerId?]
 // stale=true means the data may be outdated and should be revalidated on access
-type HistoryCacheEntry = [string, ResolvedSegment[], boolean, HandleData?];
+type HistoryCacheEntry = [
+  string,
+  ResolvedSegment[],
+  boolean,
+  HandleData?,
+  string?,
+];
 
 /**
  * Shallow clone handleData to avoid reference sharing between cache entries.
@@ -124,14 +130,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;
@@ -258,6 +264,11 @@ export function createNavigationStore(
   // Used to maintain intercept context during action revalidation
   let interceptSourceUrl: string | null = null;
 
+  // Router identity - tracks which router is currently active.
+  // When this changes on a partial response, the client forces a full
+  // tree replacement instead of reconciling with stale segments.
+  let currentRouterId: string | undefined;
+
   // Action state tracking (for useAction hook)
   // Maps action function ID to its tracked state
   const actionStates = new Map<string, TrackedActionState>();
@@ -269,18 +280,17 @@ export function createNavigationStore(
   /**
    * Create a debounced function that batches rapid calls
    */
+  // A non-keyed notifier is the keyed one restricted to a single constant key;
+  // its own keyed instance means the "" key never collides with action keys.
   function createDebouncedNotifier<T extends (...args: any[]) => void>(
     fn: T,
     ms: number = 20,
   ): T {
-    let timeout: ReturnType<typeof setTimeout> | null = null;
-    return ((...args: Parameters<T>) => {
-      if (timeout !== null) clearTimeout(timeout);
-      timeout = setTimeout(() => {
-        timeout = null;
-        fn(...args);
-      }, ms);
-    }) as T;
+    const keyed = createKeyedDebouncedNotifier(
+      (_key: string, ...args: any[]) => fn(...args),
+      ms,
+    );
+    return ((...args: Parameters<T>) => keyed("", ...args)) as T;
   }
 
   /**
@@ -325,12 +335,24 @@ export function createNavigationStore(
   }
 
   /**
-   * Mark all cache entries as stale (internal - does not broadcast)
+   * 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 markCacheAsStaleInternal(): void {
+  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). Also
+   * clears the prefetch caches, which rotates the rango state.
+   */
+  function markCacheAsStaleInternal(): void {
+    markHistoryStale();
     clearPrefetchCache();
   }
 
@@ -571,10 +593,17 @@ export function createNavigationStore(
           segments,
           false,
           clonedHandleData,
+          currentRouterId,
         ];
       } else {
         // Add new entry at the end (not stale)
-        historyCache.push([historyKey, segments, false, clonedHandleData]);
+        historyCache.push([
+          historyKey,
+          segments,
+          false,
+          clonedHandleData,
+          currentRouterId,
+        ]);
         // Remove oldest entries if over limit
         while (historyCache.length > cacheSize) {
           historyCache.shift();
@@ -586,14 +615,22 @@ export function createNavigationStore(
      * Get cached segments for a history entry
      * Returns { segments, stale, handleData } or undefined if not cached
      */
-    getCachedSegments(
-      historyKey: string,
-    ):
-      | { segments: ResolvedSegment[]; stale: boolean; handleData?: HandleData }
+    getCachedSegments(historyKey: string):
+      | {
+          segments: ResolvedSegment[];
+          stale: boolean;
+          handleData?: HandleData;
+          routerId?: string;
+        }
       | undefined {
       const entry = historyCache.find(([key]) => key === historyKey);
       if (!entry) return undefined;
-      return { segments: entry[1], stale: entry[2], handleData: entry[3] };
+      return {
+        segments: entry[1],
+        stale: entry[2],
+        handleData: entry[3],
+        routerId: entry[4],
+      };
     },
 
     /**
@@ -621,6 +658,7 @@ export function createNavigationStore(
           entry[1],
           entry[2],
           clonedHandleData,
+          entry[4], // preserve routerId
         ];
       }
     },
@@ -633,6 +671,16 @@ export function createNavigationStore(
       markCacheAsStaleInternal();
     },
 
+    /**
+     * 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.
+     */
+    markHistoryCacheStale(): void {
+      markHistoryStale();
+    },
+
     /**
      * Clear the history cache and broadcast to other tabs
      * Use this for hard invalidation when data is definitely stale
@@ -649,14 +697,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
@@ -687,6 +727,14 @@ export function createNavigationStore(
       interceptSourceUrl = url;
     },
 
+    getRouterId(): string | undefined {
+      return currentRouterId;
+    },
+
+    setRouterId(id: string): void {
+      currentRouterId = id;
+    },
+
     // ========================================================================
     // UI Update Notifications
     // ========================================================================
@@ -765,42 +813,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

@@ -11,9 +11,8 @@ import {
 } from "./scroll-restoration.js";
 import type { EventController, NavigationHandle } from "./event-controller.js";
 import { debugLog } from "./logging.js";
-import { buildHistoryState } from "./history-state.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,76 +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
-    if (replace) {
-      window.history.replaceState(historyState, "", url);
-    } else {
-      window.history.pushState(historyState, "", url);
-    }
-    // Ensure new history entry has a scroll restoration key
+    pushHistoryWithIdx(historyState, url, replace ?? false);
     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,
@@ -221,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 {
@@ -240,30 +207,16 @@ export function createNavigationTransaction(
           segments: ResolvedSegment[],
           overrides?: BoundCommitOverrides,
         ) => {
-          // Allow overrides to disable scroll (e.g., for intercepts)
-          const finalScroll =
-            overrides?.scroll !== undefined ? overrides.scroll : opts.scroll;
-          // Allow overrides to force replace (e.g., for intercepts)
-          const finalReplace =
-            overrides?.replace !== undefined ? overrides.replace : opts.replace;
-          // Intercept info: overrides take precedence, fallback to opts
-          const intercept =
-            overrides?.intercept !== undefined
-              ? overrides.intercept
-              : opts.intercept;
+          const finalScroll = overrides?.scroll ?? opts.scroll;
+          const finalReplace = overrides?.replace ?? opts.replace;
+          const intercept = overrides?.intercept ?? opts.intercept;
           const interceptSourceUrl =
-            overrides?.interceptSourceUrl !== undefined
-              ? overrides.interceptSourceUrl
-              : opts.interceptSourceUrl;
-          // Cache-only mode: overrides take precedence, fallback to opts
-          const cacheOnly =
-            overrides?.cacheOnly !== undefined
-              ? overrides.cacheOnly
-              : opts.cacheOnly;
-          // User state: overrides take precedence, fallback to opts
+            overrides?.interceptSourceUrl ?? opts.interceptSourceUrl;
+          const cacheOnly = overrides?.cacheOnly ?? opts.cacheOnly;
+          // state is `unknown` (null is meaningful) so `??` would wrongly drop a
+          // null override; serverState always comes from overrides, never opts.
           const state =
             overrides?.state !== undefined ? overrides.state : opts.state;
-          // Server-set location state: only from overrides (set by partial-update)
           const serverState = overrides?.serverState;
           return commit({
             ...opts,
@@ -282,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.
  *