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

package/src/browser/navigation-store.ts

@@ -12,10 +12,7 @@ import type {
   ActionStateListener,
   HandleData,
 } from "./types.js";
-import {
-  clearPrefetchCache,
-  clearPrefetchCacheLocal,
-} from "./prefetch/cache.js";
+import { clearPrefetchCache } from "./prefetch/cache.js";
 
 /**
  * Default action state (idle with no payload)
@@ -133,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;
@@ -283,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;
   }
 
   /**
@@ -339,24 +335,24 @@ export function createNavigationStore(
   }
 
   /**
-   * Drop this tab's navigation + prefetch caches without broadcasting or
-   * rotating shared state. Used when the local session changes in a way that
-   * doesn't affect other tabs — e.g. this tab crosses into a different app
-   * via a cross-router navigation. Other tabs in the old app keep their
-   * caches and their X-Rango-State token.
+   * 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 clearCacheInternalLocal(): void {
-    historyCache.length = 0;
-    clearPrefetchCacheLocal();
+  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)
+   * Mark all cache entries as stale (internal - does not broadcast). Also
+   * clears the prefetch caches, which rotates the rango state.
    */
   function markCacheAsStaleInternal(): void {
-    for (let i = 0; i < historyCache.length; i++) {
-      historyCache[i][2] = true;
-    }
+    markHistoryStale();
     clearPrefetchCache();
   }
 
@@ -676,20 +672,21 @@ export function createNavigationStore(
     },
 
     /**
-     * Clear the history cache and broadcast to other tabs
-     * Use this for hard invalidation when data is definitely stale
+     * 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.
      */
-    clearHistoryCache(): void {
-      clearCacheAndBroadcast();
+    markHistoryCacheStale(): void {
+      markHistoryStale();
     },
 
     /**
-     * Drop this tab's navigation + prefetch caches locally without
-     * broadcasting or rotating shared state. Intended for cross-app
-     * transitions where the session state diverges for this tab only.
+     * Clear the history cache and broadcast to other tabs
+     * Use this for hard invalidation when data is definitely stale
      */
-    clearHistoryCacheLocal(): void {
-      clearCacheInternalLocal();
+    clearHistoryCache(): void {
+      clearCacheAndBroadcast();
     },
 
     /**
@@ -700,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
@@ -824,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.
  *