@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.1878aa49

package/src/browser/navigation-store.ts

@@ -12,7 +12,7 @@ import type {
   ActionStateListener,
   HandleData,
 } from "./types.js";
-import { clearPrefetchCache } from "./prefetch-cache.js";
+import { clearPrefetchCache } from "./prefetch/cache.js";
 
 /**
  * Default action state (idle with no payload)
@@ -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.
@@ -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>();
@@ -338,7 +349,6 @@ export function createNavigationStore(
    * Clear the history cache and broadcast to other tabs
    */
   function clearCacheAndBroadcast(): void {
-    console.log("[Browser] Clearing cache and broadcasting to other tabs");
     clearCacheInternal();
     broadcastInvalidation();
   }
@@ -347,9 +357,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();
   }
@@ -372,14 +379,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");
     }
   }
 
@@ -404,34 +403,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?.();
                 }
               };
@@ -596,10 +582,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();
@@ -611,14 +604,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],
+      };
     },
 
     /**
@@ -646,6 +647,7 @@ export function createNavigationStore(
           entry[1],
           entry[2],
           clonedHandleData,
+          entry[4], // preserve routerId
         ];
       }
     },
@@ -656,11 +658,6 @@ export function createNavigationStore(
      */
     markCacheAsStale(): void {
       markCacheAsStaleInternal();
-      console.log(
-        "[Browser] Marked",
-        historyCache.length,
-        "cache entries as stale",
-      );
     },
 
     /**
@@ -717,6 +714,14 @@ export function createNavigationStore(
       interceptSourceUrl = url;
     },
 
+    getRouterId(): string | undefined {
+      return currentRouterId;
+    },
+
+    setRouterId(id: string): void {
+      currentRouterId = id;
+    },
+
     // ========================================================================
     // UI Update Notifications
     // ========================================================================

package/src/browser/navigation-transaction.ts

@@ -4,82 +4,25 @@ import type {
   ResolvedSegment,
   StreamingToken,
 } from "./types.js";
-import {
-  isLocationStateEntry,
-  resolveLocationStateEntries,
-} from "./react/location-state-shared.js";
 import { generateHistoryKey } from "./navigation-store.js";
 import {
   handleNavigationStart,
-  handleNavigationEnd,
   ensureHistoryKey,
 } from "./scroll-restoration.js";
 import type { EventController, NavigationHandle } from "./event-controller.js";
 import { debugLog } from "./logging.js";
-
-/**
- * Check if state is from typed LocationStateEntry[] (has __rsc_ls_ keys)
- */
-function isTypedLocationState(
-  state: unknown,
-): state is Record<string, unknown> {
-  if (state === null || typeof state !== "object") return false;
-  return Object.keys(state).some((key) => key.startsWith("__rsc_ls_"));
-}
-
-/**
- * Resolve navigation state - handles both LocationStateEntry[] and plain formats
- */
-export function resolveNavigationState(state: unknown): unknown {
-  // Check if it's an array of LocationStateEntry
-  if (
-    Array.isArray(state) &&
-    state.length > 0 &&
-    isLocationStateEntry(state[0])
-  ) {
-    return resolveLocationStateEntries(state);
-  }
-  // Return as-is for plain state formats
-  return state;
-}
-
-/**
- * Build history state object from user state
- * - Typed state: spread directly into history.state
- * - Plain state: store in history.state.state
- */
-function buildHistoryState(
-  userState: unknown,
-  routerState?: { intercept?: boolean; sourceUrl?: string },
-  serverState?: Record<string, unknown>,
-): Record<string, unknown> | null {
-  const result: Record<string, unknown> = {};
-
-  // Add router internal state
-  if (routerState?.intercept) {
-    result.intercept = true;
-    if (routerState.sourceUrl) {
-      result.sourceUrl = routerState.sourceUrl;
-    }
-  }
-
-  // Add user state
-  if (userState !== undefined) {
-    if (isTypedLocationState(userState)) {
-      // Typed state: spread directly
-      Object.assign(result, userState);
-    } else {
-      // Plain state: store in .state
-      result.state = userState;
-    }
-  }
-
-  // Merge server-set location state (from ctx.setLocationState on non-redirect responses)
-  if (serverState) {
-    Object.assign(result, serverState);
-  }
-
-  return Object.keys(result).length > 0 ? result : null;
+import { buildHistoryState } 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. */
+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_"))
+  );
 }
 
 // Polyfill Symbol.dispose for Safari and older browsers
@@ -87,11 +30,6 @@ if (typeof Symbol.dispose === "undefined") {
   (Symbol as any).dispose = Symbol("Symbol.dispose");
 }
 
-// Monotonic counter for tagging early-pushed history entries.
-// Used by disposal to verify ownership without URL comparison,
-// which breaks when two navigations target the same URL.
-let navStamp = 0;
-
 /**
  * Options for committing a navigation transaction
  */
@@ -142,11 +80,12 @@ 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,
-  ): void;
+  ): { scroll?: boolean };
 }
 
 /**
@@ -154,10 +93,7 @@ export interface BoundTransaction {
  * Uses the event controller handle for lifecycle management
  */
 interface NavigationTransaction extends Disposable {
-  /** Optimistically commit from cache - instant render before revalidation */
-  optimisticCommit(options: CommitOptions): void;
-  /** Final commit with server data (or reconciliation after optimistic) */
-  commit(options: CommitOptions): void;
+  commit(options: CommitOptions): { scroll?: boolean };
   with(
     options: Omit<CommitOptions, "segmentIds" | "segments">,
   ): BoundTransaction;
@@ -168,9 +104,6 @@ interface NavigationTransaction extends Disposable {
 /**
  * Creates a navigation transaction that coordinates with the event controller.
  * Handles loading state transitions and cleanup on completion/abort.
- *
- * Supports optimistic navigation: render from cache immediately,
- * then revalidate in background and reconcile if data changed.
  */
 export function createNavigationTransaction(
   store: NavigationStore,
@@ -179,102 +112,29 @@ export function createNavigationTransaction(
   options?: NavigateOptions & { skipLoadingState?: boolean },
 ): NavigationTransaction {
   let committed = false;
-  let optimisticallyCommitted = false;
-  let earlyStatePushed = false;
-  let earlyStateStamp: number | null = null;
   const currentUrl = window.location.href;
-  const currentHistoryState = window.history.state;
 
   // Start navigation in event controller (this sets loading state)
   const handle = eventController.startNavigation(url, options);
 
-  // If state is provided, push it to history immediately so loading UI can access it
-  // This enables "optimistic state" - showing product names in skeletons etc.
-  if (options?.state !== undefined && !options?.replace) {
-    earlyStateStamp = ++navStamp;
-    const earlyHistoryState = buildHistoryState(options.state);
-    if (earlyHistoryState) {
-      (earlyHistoryState as any).__navStamp = earlyStateStamp;
-    }
-    window.history.pushState(
-      earlyHistoryState ?? { __navStamp: earlyStateStamp },
-      "",
-      url,
-    );
-    earlyStatePushed = true;
-  }
-
-  /**
-   * Optimistically commit from cache - renders immediately before revalidation
-   * Sets optimisticallyCommitted flag so final commit() knows to reconcile
-   */
-  function optimisticCommit(opts: CommitOptions): void {
-    optimisticallyCommitted = true;
-
-    const { url, segmentIds, segments, replace, scroll } = opts;
-    const parsedUrl = new URL(url, window.location.origin);
-
-    // Save current scroll position before navigating
-    handleNavigationStart();
-
-    // Update segment state
-    store.setSegmentIds(segmentIds);
-    store.setCurrentUrl(url);
-    store.setPath(parsedUrl.pathname);
-
-    // Generate history key from URL
-    const historyKey = generateHistoryKey(url);
-    store.setHistoryKey(historyKey);
-
-    // Cache segments with current handleData (will be overwritten by fresh data on final commit)
-    const currentHandleData = eventController.getHandleState().data;
-    store.cacheSegmentsForHistory(historyKey, segments, currentHandleData);
-
-    // Build history state with user state if provided
-    const historyState = buildHistoryState(opts.state);
-
-    // Update browser URL
-    // Use replaceState if we already pushed early (for optimistic state access)
-    if (replace || earlyStatePushed) {
-      window.history.replaceState(historyState, "", url);
-    } else {
-      window.history.pushState(historyState, "", url);
-    }
-
-    // Ensure new history entry has a scroll restoration key
-    ensureHistoryKey();
-
-    // Complete the navigation in event controller (sets idle state)
-    handle.complete(parsedUrl);
-
-    // Handle scroll after navigation
-    handleNavigationEnd({ scroll });
-
-    debugLog("[Browser] Optimistic commit from cache, historyKey:", historyKey);
-  }
-
   /**
    * Commit the navigation - updates store and URL atomically
-   * If optimisticCommit was called, this becomes a reconciliation
    */
-  function commit(opts: CommitOptions): void {
+  function commit(opts: CommitOptions): { scroll?: boolean } {
     committed = true;
 
-    // If optimistic commit already done, adjust options for reconciliation
-    const isReconciliation = optimisticallyCommitted;
     const {
       url,
       segmentIds,
       segments,
+      replace,
+      scroll,
       storeOnly,
       intercept,
       interceptSourceUrl,
       cacheOnly,
       serverState,
     } = opts;
-    // For reconciliation: always replace (URL already pushed), no scroll
-    const replace = isReconciliation ? true : opts.replace;
-    const scroll = isReconciliation ? false : opts.scroll;
 
     const parsedUrl = new URL(url, window.location.origin);
 
@@ -286,14 +146,15 @@ export function createNavigationTransaction(
     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;
+      return { scroll: false };
     }
 
-    // Save current scroll position before navigating (only for non-reconciliation)
-    if (!isReconciliation) {
-      handleNavigationStart();
-    }
+    // Save current scroll position before navigating
+    handleNavigationStart();
 
     // Update segment state atomically
     store.setSegmentIds(segmentIds);
@@ -302,7 +163,7 @@ export function createNavigationTransaction(
 
     store.setHistoryKey(historyKey);
 
-    // Cache segments with current handleData for this history entry (fresh data overwrites optimistic)
+    // Cache segments with current handleData for this history entry
     const currentHandleData = eventController.getHandleState().data;
     store.cacheSegmentsForHistory(historyKey, segments, currentHandleData);
 
@@ -311,7 +172,7 @@ export function createNavigationTransaction(
       debugLog("[Browser] Store updated (action)");
       // Complete navigation to clear loading state
       handle.complete(parsedUrl);
-      return;
+      return { scroll: false };
     }
 
     // Build history state - include user state, intercept info, and server-set state
@@ -321,50 +182,43 @@ export function createNavigationTransaction(
       serverState,
     );
 
-    // Update browser URL (skip if reconciliation - already done in optimisticCommit)
-    if (!isReconciliation) {
-      // Use replaceState if we already pushed early (for optimistic state access) or replace requested
-      if (replace || earlyStatePushed) {
-        window.history.replaceState(historyState, "", url);
-      } else {
-        window.history.pushState(historyState, "", url);
-      }
-      // Ensure new history entry has a scroll restoration key
-      ensureHistoryKey();
+    // Snapshot old state before pushState/replaceState overwrites it.
+    // Used to detect when location state is being cleared.
+    const oldState = window.history.state;
 
-      // Notify location state hooks when history state includes typed entries.
-      // Needed for same-page redirects where components don't remount and
-      // useState initializers don't re-run, even though history.state was updated.
-      if (
-        historyState &&
-        Object.keys(historyState).some((k) => k.startsWith("__rsc_ls_"))
-      ) {
-        window.dispatchEvent(new Event("__rsc_locationstate"));
-      }
+    // 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
+    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);
 
-    // Handle scroll after navigation (skip if reconciliation)
-    if (!isReconciliation) {
-      handleNavigationEnd({ scroll });
-    }
+    // NOTE: Scroll is NOT handled here. The caller (partial-update.ts) handles
+    // scroll AFTER onUpdate() so React has the new content before we scroll.
 
-    if (isReconciliation) {
-      debugLog("[Browser] Reconciliation commit, historyKey:", historyKey);
-    } else {
-      debugLog(
-        "[Browser] Navigation committed, historyKey:",
-        historyKey,
-        intercept ? "(intercept)" : "",
-      );
-    }
+    debugLog(
+      "[Browser] Navigation committed, historyKey:",
+      historyKey,
+      intercept ? "(intercept)" : "",
+    );
+
+    return { scroll };
   }
 
   return {
     handle,
-    optimisticCommit,
     commit,
 
     /**
@@ -411,7 +265,7 @@ export function createNavigationTransaction(
             overrides?.state !== undefined ? overrides.state : opts.state;
           // Server-set location state: only from overrides (set by partial-update)
           const serverState = overrides?.serverState;
-          commit({
+          return commit({
             ...opts,
             segmentIds,
             segments,
@@ -428,27 +282,14 @@ export function createNavigationTransaction(
     },
 
     [Symbol.dispose]() {
-      // Superseded: another navigation took over. Roll back our early push
-      // so the new navigation starts from a clean history position.
-      // Guard: only rollback if our early-pushed state is still the current
-      // history entry. Compare by stamp (monotonic counter embedded in state)
-      // so that a newer navigation targeting the same URL is not clobbered.
+      // Superseded: another navigation took over.
       if (handle.signal.aborted) {
-        if (
-          earlyStatePushed &&
-          !committed &&
-          !optimisticallyCommitted &&
-          earlyStateStamp !== null &&
-          window.history.state?.__navStamp === earlyStateStamp
-        ) {
-          window.history.replaceState(currentHistoryState, "", currentUrl);
-        }
         return;
       }
 
       // Failed (not committed): keep the target URL -- the error UI owns it.
       // Just reset the event controller to idle.
-      if (!committed && !optimisticallyCommitted) {
+      if (!committed) {
         handle[Symbol.dispose]();
       }
     },