@rangojs/router 0.0.0-experimental.12 → 0.0.0-experimental.121

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 : "/";
@@ -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,6 +331,7 @@ export function createNavigationStore(
    */
   function clearCacheInternal(): void {
     historyCache.length = 0;
+    clearPrefetchCache();
   }
 
   /**
@@ -329,13 +341,13 @@ export function createNavigationStore(
     for (let i = 0; i < historyCache.length; i++) {
       historyCache[i][2] = true;
     }
+    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 +356,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 +378,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 +394,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 +402,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 +562,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 +573,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 +603,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 +635,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 +656,7 @@ 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();
     },
 
     /**
@@ -704,6 +713,14 @@ export function createNavigationStore(
       interceptSourceUrl = url;
     },
 
+    getRouterId(): string | undefined {
+      return currentRouterId;
+    },
+
+    setRouterId(id: string): void {
+      currentRouterId = id;
+    },
+
     // ========================================================================
     // UI Update Notifications
     // ========================================================================
@@ -745,7 +762,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 +780,7 @@ export function createNavigationStore(
      */
     subscribeToAction(
       actionId: string,
-      listener: ActionStateListener
+      listener: ActionStateListener,
     ): () => void {
       let listeners = actionListeners.get(actionId);
       if (!listeners) {
@@ -793,7 +810,7 @@ let storeInstance: NavigationStore | null = null;
  * Subsequent calls return the existing instance.
  */
 export function initNavigationStore(
-  config?: NavigationStoreConfig
+  config?: NavigationStoreConfig,
 ): NavigationStore {
   if (!storeInstance) {
     storeInstance = createNavigationStore(config);
@@ -809,7 +826,7 @@ export function initNavigationStore(
 export function getNavigationStore(): NavigationStore {
   if (!storeInstance) {
     throw new Error(
-      "Navigation store not initialized. Call initNavigationStore first."
+      "Navigation store not initialized. Call initNavigationStore first.",
     );
   }
   return storeInstance;

package/src/browser/navigation-transaction.ts

@@ -0,0 +1,279 @@
+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";
+
+// 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
+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;
+
+  // Start navigation in event controller (this sets loading state)
+  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);
+
+    // 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,
+      intercept ? "(intercept)" : "",
+    );
+
+    return { scroll };
+  }
+
+  return {
+    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 {
+      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]() {
+      // 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

@@ -0,0 +1,61 @@
+import { NetworkError, isNetworkError } from "../errors.js";
+import { NetworkErrorThrower } from "../network-error-thrower.js";
+import type { UpdateSubscriber } from "./types.js";
+import { createElement, startTransition } from "react";
+
+/**
+ * Convert an unknown error to a NetworkError, or return null if not network-related.
+ *
+ * Pure function: extracts the "is this a network error?" decision from
+ * navigation-bridge and server-action-bridge so it can be unit tested.
+ */
+export function toNetworkError(
+  error: unknown,
+  context: { url: string; operation: "action" | "navigation" | "revalidation" },
+): NetworkError | null {
+  if (error instanceof NetworkError) return error;
+  if (isNetworkError(error)) {
+    return new NetworkError(
+      "Unable to connect to server. Please check your connection.",
+      { cause: error, url: context.url, operation: context.operation },
+    );
+  }
+  return null;
+}
+
+/**
+ * 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.
+ */
+export function emitNetworkError(
+  onUpdate: UpdateSubscriber,
+  error: NetworkError,
+  pathname: string,
+): void {
+  startTransition(() => {
+    onUpdate({
+      root: createElement(NetworkErrorThrower, { error }),
+      metadata: {
+        pathname,
+        segments: [],
+        isError: true,
+      },
+    });
+  });
+}
+
+/**
+ * Check if an error is safe to suppress in background operations.
+ *
+ * Background revalidation (SWR, navigated-away refetch) should silently
+ * swallow AbortErrors and network errors since the user has already moved
+ * on and showing an error would be disruptive.
+ *
+ * Pure function, easily unit tested.
+ */
+export function isBackgroundSuppressible(error: unknown): boolean {
+  if (error instanceof DOMException && error.name === "AbortError") return true;
+  if (error instanceof NetworkError || isNetworkError(error)) return true;
+  return false;
+}