@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.141

package/src/browser/navigation-store.ts

@@ -12,6 +12,7 @@ import type {
   ActionStateListener,
   HandleData,
 } from "./types.js";
+import { clearPrefetchCache } from "./prefetch/cache.js";
 
 /**
  * Default action state (idle with no payload)
@@ -27,9 +28,29 @@ 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?]
-// stale=true means the data may be outdated and should be revalidated on access
-type HistoryCacheEntry = [string, ResolvedSegment[], boolean, HandleData?];
+// 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.
@@ -37,7 +58,7 @@ type HistoryCacheEntry = [string, ResolvedSegment[], boolean, HandleData?];
  * 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] = {};
@@ -88,7 +109,7 @@ export interface HistoryKeyOptions {
  */
 export function generateHistoryKey(
   url?: string,
-  options?: HistoryKeyOptions
+  options?: HistoryKeyOptions,
 ): string {
   if (!url) {
     url = typeof window !== "undefined" ? window.location.href : "/";
@@ -123,14 +144,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;
@@ -182,7 +203,7 @@ function createLocation(loc: { href: string }): NavigationLocation {
  * ```
  */
 export function createNavigationStore(
-  config?: NavigationStoreConfig
+  config?: NavigationStoreConfig,
 ): NavigationStore {
   // Default location from window or config
   const defaultLocation: NavigationLocation =
@@ -232,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();
 
@@ -241,6 +270,10 @@ export function createNavigationStore(
       config.initialHistoryKey,
       config.initialSegments,
       false,
+      undefined,
+      undefined,
+      ++navInstance,
+      false,
     ]);
   }
 
@@ -257,6 +290,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>();
@@ -268,18 +306,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
+    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;
   }
 
   /**
@@ -297,7 +334,7 @@ export function createNavigationStore(
         setTimeout(() => {
           timeouts.delete(key);
           fn(key, ...args);
-        }, ms)
+        }, ms),
       );
     }) as T;
   }
@@ -312,7 +349,7 @@ export function createNavigationStore(
       if (listeners) {
         listeners.forEach((listener) => listener(state));
       }
-    }
+    },
   );
 
   /**
@@ -320,22 +357,35 @@ export function createNavigationStore(
    */
   function clearCacheInternal(): void {
     historyCache.length = 0;
+    clearPrefetchCache();
   }
 
   /**
-   * 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();
+  }
+
   /**
    * Clear the history cache and broadcast to other tabs
    */
   function clearCacheAndBroadcast(): void {
-    console.log("[Browser] Clearing cache and broadcasting to other tabs");
     clearCacheInternal();
     broadcastInvalidation();
   }
@@ -344,9 +394,6 @@ export function createNavigationStore(
    * Mark cache as stale and broadcast to other tabs
    */
   function markStaleAndBroadcast(): void {
-    console.log(
-      "[Browser] Marking cache as stale and broadcasting to other tabs"
-    );
     markCacheAsStaleInternal();
     broadcastInvalidation();
   }
@@ -369,14 +416,6 @@ export function createNavigationStore(
         path: currentPath,
         segmentIds: currentSegmentIds,
       });
-      console.log(
-        "[Browser] Broadcast sent for path:",
-        currentPath,
-        "segments:",
-        currentSegmentIds.join(", ")
-      );
-    } else {
-      console.warn("[Browser] No BroadcastChannel available");
     }
   }
 
@@ -393,7 +432,7 @@ export function createNavigationStore(
           // Check for shared segments between tabs
           // Routes sharing any segment (layout, loader, etc.) should invalidate together
           const hasSharedSegment = mutatedSegmentIds.some((id) =>
-            currentSegmentIds.includes(id)
+            currentSegmentIds.includes(id),
           );
 
           if (!hasSharedSegment) {
@@ -401,34 +440,21 @@ export function createNavigationStore(
             return;
           }
 
-          console.log(
-            "[Browser] Cache marked stale by another tab, shared segments:",
-            mutatedSegmentIds
-              .filter((id) => currentSegmentIds.includes(id))
-              .join(", ")
-          );
           markCacheAsStaleInternal();
 
           // Auto-refresh if enabled and callback is registered
           if (crossTabAutoRefresh && crossTabRefreshCallback) {
             // If idle, refresh immediately. If loading, wait for idle then refresh.
             if (navState.state === "idle") {
-              console.log("[Browser] Cross-tab refresh triggered (idle)");
               crossTabRefreshCallback();
             } else if (!pendingCrossTabRefresh) {
               // Only queue one refresh, ignore subsequent events while loading
               pendingCrossTabRefresh = true;
-              console.log(
-                "[Browser] Navigation in progress, deferring cross-tab refresh"
-              );
               // Subscribe to state changes, refresh when idle
               const listener: StateListener = () => {
                 if (navState.state === "idle") {
                   stateListeners.delete(listener);
                   pendingCrossTabRefresh = false;
-                  console.log(
-                    "[Browser] Cross-tab refresh triggered (deferred)"
-                  );
                   crossTabRefreshCallback?.();
                 }
               };
@@ -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
@@ -574,7 +623,7 @@ export function createNavigationStore(
     cacheSegmentsForHistory(
       historyKey: string,
       segments: ResolvedSegment[],
-      handleData?: HandleData
+      handleData?: HandleData,
     ): void {
       // Shallow clone handleData arrays to avoid reference sharing between cache entries
       // We only clone the structure (objects and arrays), not the data items themselves,
@@ -583,15 +632,36 @@ 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
+        ([key]) => key === historyKey,
       );
       if (existingIndex !== -1) {
-        historyCache[existingIndex] = [historyKey, segments, false, clonedHandleData];
+        historyCache[existingIndex] = [
+          historyKey,
+          segments,
+          false,
+          clonedHandleData,
+          currentRouterId,
+          instance,
+          false, // fresh commit: handles complete unless a deferred apply marks it
+        ];
       } else {
         // Add new entry at the end (not stale)
-        historyCache.push([historyKey, segments, false, clonedHandleData]);
+        historyCache.push([
+          historyKey,
+          segments,
+          false,
+          clonedHandleData,
+          currentRouterId,
+          instance,
+          false,
+        ]);
         // Remove oldest entries if over limit
         while (historyCache.length > cacheSize) {
           historyCache.shift();
@@ -603,12 +673,24 @@ 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 } | undefined {
+    getCachedSegments(historyKey: string):
+      | {
+          segments: ResolvedSegment[];
+          stale: boolean;
+          handleData?: HandleData;
+          routerId?: string;
+          handlesPending?: boolean;
+        }
+      | 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],
+        handlesPending: entry[6],
+      };
     },
 
     /**
@@ -619,19 +701,39 @@ 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
+        ([key]) => key === historyKey,
       );
       if (existingIndex !== -1) {
         const entry = historyCache[existingIndex];
         // Shallow clone handleData arrays to avoid reference sharing
         const clonedHandleData = cloneHandleData(handleData);
-        historyCache[existingIndex] = [entry[0], entry[1], entry[2], clonedHandleData];
+        historyCache[existingIndex] = [
+          entry[0],
+          entry[1],
+          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
+        ];
       }
     },
 
@@ -640,14 +742,17 @@ export function createNavigationStore(
      * Called after server actions to indicate data may be outdated
      */
     markCacheAsStale(): void {
-      for (let i = 0; i < historyCache.length; i++) {
-        historyCache[i][2] = true;
-      }
-      console.log(
-        "[Browser] Marked",
-        historyCache.length,
-        "cache entries as stale"
-      );
+      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();
     },
 
     /**
@@ -666,14 +771,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
@@ -704,6 +801,14 @@ export function createNavigationStore(
       interceptSourceUrl = url;
     },
 
+    getRouterId(): string | undefined {
+      return currentRouterId;
+    },
+
+    setRouterId(id: string): void {
+      currentRouterId = id;
+    },
+
     // ========================================================================
     // UI Update Notifications
     // ========================================================================
@@ -745,7 +850,7 @@ export function createNavigationStore(
      */
     setActionState(
       actionId: string,
-      partial: Partial<TrackedActionState>
+      partial: Partial<TrackedActionState>,
     ): void {
       const current = actionStates.get(actionId) ?? { ...DEFAULT_ACTION_STATE };
       const updated: TrackedActionState = {
@@ -763,7 +868,7 @@ export function createNavigationStore(
      */
     subscribeToAction(
       actionId: string,
-      listener: ActionStateListener
+      listener: ActionStateListener,
     ): () => void {
       let listeners = actionListeners.get(actionId);
       if (!listeners) {
@@ -782,42 +887,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;
-}