@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.131

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,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.
@@ -88,7 +95,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 +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;
@@ -182,7 +189,7 @@ function createLocation(loc: { href: string }): NavigationLocation {
  * ```
  */
 export function createNavigationStore(
-  config?: NavigationStoreConfig
+  config?: NavigationStoreConfig,
 ): NavigationStore {
   // Default location from window or config
   const defaultLocation: NavigationLocation =
@@ -257,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>();
@@ -268,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
+    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 +308,7 @@ export function createNavigationStore(
         setTimeout(() => {
           timeouts.delete(key);
           fn(key, ...args);
-        }, ms)
+        }, ms),
       );
     }) as T;
   }
@@ -312,7 +323,7 @@ export function createNavigationStore(
       if (listeners) {
         listeners.forEach((listener) => listener(state));
       }
-    }
+    },
   );
 
   /**
@@ -320,22 +331,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 +368,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 +390,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 +406,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 +414,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?.();
                 }
               };
@@ -574,7 +574,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,
@@ -585,13 +585,25 @@ export function createNavigationStore(
 
       // 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,
+        ];
       } 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();
@@ -603,12 +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 } | undefined {
+    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],
+      };
     },
 
     /**
@@ -625,13 +647,19 @@ export function createNavigationStore(
      */
     updateCacheHandleData(historyKey: string, handleData: HandleData): 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],
+          entry[2],
+          clonedHandleData,
+          entry[4], // preserve routerId
+        ];
       }
     },
 
@@ -640,14 +668,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 +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
@@ -704,6 +727,14 @@ export function createNavigationStore(
       interceptSourceUrl = url;
     },
 
+    getRouterId(): string | undefined {
+      return currentRouterId;
+    },
+
+    setRouterId(id: string): void {
+      currentRouterId = id;
+    },
+
     // ========================================================================
     // UI Update Notifications
     // ========================================================================
@@ -745,7 +776,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 +794,7 @@ export function createNavigationStore(
      */
     subscribeToAction(
       actionId: string,
-      listener: ActionStateListener
+      listener: ActionStateListener,
     ): () => void {
       let listeners = actionListeners.get(actionId);
       if (!listeners) {
@@ -782,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

@@ -0,0 +1,247 @@
+import type {
+  NavigateOptions,
+  NavigationStore,
+  ResolvedSegment,
+  StreamingToken,
+} from "./types.js";
+import { generateHistoryKey } from "./navigation-store.js";
+import {
+  handleNavigationStart,
+  ensureHistoryKey,
+} from "./scroll-restoration.js";
+import type { EventController, NavigationHandle } from "./event-controller.js";
+import { debugLog } from "./logging.js";
+import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
+
+export { resolveNavigationState } from "./history-state.js";
+
+/** Check if a history state object contains location state keys. */
+function hasLocationState(state: unknown): boolean {
+  if (!state || typeof state !== "object") return false;
+  return (
+    "state" in state ||
+    Object.keys(state).some((k) => k.startsWith("__rsc_ls_"))
+  );
+}
+
+if (typeof Symbol.dispose === "undefined") {
+  (Symbol as any).dispose = Symbol("Symbol.dispose");
+}
+
+/**
+ * Options for committing a navigation transaction
+ */
+interface CommitOptions {
+  url: string;
+  segmentIds: string[];
+  segments: ResolvedSegment[];
+  replace?: boolean;
+  scroll?: boolean;
+  /** User-provided state to store in history.state */
+  state?: unknown;
+  /** If true, only update store without changing URL/history (for server actions) */
+  storeOnly?: boolean;
+  /** If true, this is an intercept route - store in history.state for popstate handling */
+  intercept?: boolean;
+  /** Source URL where the intercept was triggered from (stored in history.state) */
+  interceptSourceUrl?: string;
+  /** If true, only update cache without touching store or history (for background stale revalidation) */
+  cacheOnly?: boolean;
+  /** Server-set location state to merge into history.pushState */
+  serverState?: Record<string, unknown>;
+}
+
+/**
+ * Options that can override the pre-configured commit settings
+ */
+interface BoundCommitOverrides {
+  /** Override scroll behavior (e.g., disable for intercepts) */
+  scroll?: boolean;
+  /** Override replace behavior (e.g., force replace for intercepts) */
+  replace?: boolean;
+  /** Override user-provided state */
+  state?: unknown;
+  /** Mark this as an intercept route */
+  intercept?: boolean;
+  /** Source URL where intercept was triggered from */
+  interceptSourceUrl?: string;
+  /** If true, only update cache (for stale revalidation) */
+  cacheOnly?: boolean;
+  /** Server-set location state to merge into history.pushState */
+  serverState?: Record<string, unknown>;
+}
+
+/**
+ * Bound transaction with pre-configured commit options (without segmentIds/segments)
+ */
+export interface BoundTransaction {
+  readonly currentUrl: string;
+  /** Start streaming and get a token to end it when the stream completes */
+  startStreaming(): StreamingToken;
+  /** Commit the navigation. Returns the effective scroll option for the caller to handle. */
+  commit(
+    segmentIds: string[],
+    segments: ResolvedSegment[],
+    overrides?: BoundCommitOverrides,
+  ): { scroll?: boolean };
+}
+
+/**
+ * Navigation transaction for managing state during navigation
+ * Uses the event controller handle for lifecycle management
+ */
+interface NavigationTransaction extends Disposable {
+  commit(options: CommitOptions): { scroll?: boolean };
+  with(
+    options: Omit<CommitOptions, "segmentIds" | "segments">,
+  ): BoundTransaction;
+  /** The navigation handle from the event controller */
+  handle: NavigationHandle;
+}
+
+/**
+ * Creates a navigation transaction that coordinates with the event controller.
+ * Handles loading state transitions and cleanup on completion/abort.
+ */
+export function createNavigationTransaction(
+  store: NavigationStore,
+  eventController: EventController,
+  url: string,
+  options?: NavigateOptions & { skipLoadingState?: boolean },
+): NavigationTransaction {
+  let committed = false;
+  const currentUrl = window.location.href;
+
+  const handle = eventController.startNavigation(url, options);
+
+  /**
+   * Commit the navigation - updates store and URL atomically
+   */
+  function commit(opts: CommitOptions): { scroll?: boolean } {
+    committed = true;
+
+    const {
+      url,
+      segmentIds,
+      segments,
+      replace,
+      scroll,
+      storeOnly,
+      intercept,
+      interceptSourceUrl,
+      cacheOnly,
+      serverState,
+    } = opts;
+
+    const parsedUrl = new URL(url, window.location.origin);
+
+    const historyKey = generateHistoryKey(url, { intercept });
+
+    if (cacheOnly) {
+      const currentHandleData = eventController.getHandleState().data;
+      store.cacheSegmentsForHistory(historyKey, segments, currentHandleData);
+      handle.complete(parsedUrl);
+      debugLog("[Browser] Cache-only commit, historyKey:", historyKey);
+      return { scroll: false };
+    }
+
+    handleNavigationStart();
+
+    store.setSegmentIds(segmentIds);
+    store.setCurrentUrl(url);
+    store.setPath(parsedUrl.pathname);
+
+    store.setHistoryKey(historyKey);
+
+    const currentHandleData = eventController.getHandleState().data;
+    store.cacheSegmentsForHistory(historyKey, segments, currentHandleData);
+
+    if (storeOnly) {
+      debugLog("[Browser] Store updated (action)");
+      handle.complete(parsedUrl);
+      return { scroll: false };
+    }
+
+    const historyState = buildHistoryState(
+      opts.state,
+      { intercept, sourceUrl: interceptSourceUrl },
+      serverState,
+    );
+
+    const oldState = window.history.state;
+
+    pushHistoryWithIdx(historyState, url, replace ?? false);
+    ensureHistoryKey();
+
+    if (hasLocationState(oldState) || hasLocationState(historyState)) {
+      window.dispatchEvent(new Event("__rsc_locationstate"));
+    }
+
+    handle.complete(parsedUrl);
+
+    debugLog(
+      "[Browser] Navigation committed, historyKey:",
+      historyKey,
+      intercept ? "(intercept)" : "",
+    );
+
+    return { scroll };
+  }
+
+  return {
+    handle,
+    commit,
+
+    with(
+      opts: Omit<CommitOptions, "segmentIds" | "segments">,
+    ): BoundTransaction {
+      return {
+        get currentUrl() {
+          return currentUrl;
+        },
+        startStreaming() {
+          return handle.startStreaming();
+        },
+        commit: (
+          segmentIds: string[],
+          segments: ResolvedSegment[],
+          overrides?: BoundCommitOverrides,
+        ) => {
+          const finalScroll = overrides?.scroll ?? opts.scroll;
+          const finalReplace = overrides?.replace ?? opts.replace;
+          const intercept = overrides?.intercept ?? opts.intercept;
+          const interceptSourceUrl =
+            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;
+          const serverState = overrides?.serverState;
+          return commit({
+            ...opts,
+            segmentIds,
+            segments,
+            scroll: finalScroll,
+            replace: finalReplace,
+            state,
+            intercept,
+            interceptSourceUrl,
+            cacheOnly,
+            serverState,
+          });
+        },
+      };
+    },
+
+    [Symbol.dispose]() {
+      if (handle.signal.aborted) {
+        return;
+      }
+
+      if (!committed) {
+        handle[Symbol.dispose]();
+      }
+    },
+  };
+}