@rangojs/router 0.0.0-experimental.122 → 0.0.0-experimental.125

package/src/browser/event-controller.ts

@@ -237,10 +237,6 @@ export interface EventController {
   hadAnyConcurrentActions(): boolean;
 }
 
-// ============================================================================
-// Default States
-// ============================================================================
-
 const DEFAULT_ACTION_STATE: TrackedActionState = {
   state: "idle",
   actionId: null,
@@ -261,16 +257,12 @@ function matchesActionId(
   entryActionId: string,
 ): boolean {
   if (subscriptionId.includes("#")) {
-    // Full ID: exact match
     return subscriptionId === entryActionId;
   }
-  // Action name only: suffix match (matches "anything#actionName")
   return entryActionId.endsWith(`#${subscriptionId}`);
 }
 
-// Coalesce rapid notifications into one microtask-deferred fan-out; the
-// setTimeout(0) batching prevents render storms. Each notifier owns its timer
-// so listener kinds coalesce independently.
+// Batch rapid notifications into one microtask to prevent render storms
 function makeDebouncedNotifier(listeners: Set<() => void>): () => void {
   let timeout: ReturnType<typeof setTimeout> | null = null;
   return () => {
@@ -282,13 +274,6 @@ function makeDebouncedNotifier(listeners: Set<() => void>): () => void {
   };
 }
 
-// ============================================================================
-// Implementation
-// ============================================================================
-
-/**
- * Configuration for creating an event controller
- */
 export interface EventControllerConfig {
   initialLocation?: NavigationLocation;
 }
@@ -306,51 +291,34 @@ export interface EventControllerConfig {
 export function createEventController(
   config?: EventControllerConfig,
 ): EventController {
-  // ========================================================================
-  // Source of Truth
-  // ========================================================================
-
-  // Current navigation in progress (null = idle)
   let currentNavigation: NavigationEntry | null = null;
 
-  // All in-flight actions (keyed by unique instance ID)
   const inflightActions = new Map<string, ActionEntry>();
 
-  // Committed location (updated when navigation completes)
   let location: NavigationLocation =
     config?.initialLocation ??
     (typeof window !== "undefined"
       ? new URL(window.location.href)
       : new URL("/", "http://localhost"));
 
-  // Track if any concurrent actions occurred (for consolidation)
   let hadAnyConcurrentActions = false;
 
-  // Track segments revalidated by concurrent actions
   const concurrentRevalidatedSegments = new Set<string>();
 
-  // Active streaming count (independent of navigation/action lifecycle)
   let activeStreamCount = 0;
 
-  // Handle data from RSC payload
   let handleData: HandleData = {};
   let handleSegmentOrder: string[] = [];
   let routeSegmentIds: string[] = [];
 
-  // Merged route params from current match
   let routeParams: Record<string, string> = {};
 
-  // ========================================================================
-  // Listeners
-  // ========================================================================
-
   const stateListeners = new Set<StateListener>();
   const actionListeners = new Map<string, Set<ActionStateListener>>();
   const handleListeners = new Set<HandleListener>();
 
   const notify = makeDebouncedNotifier(stateListeners);
 
-  // Debounce per-action notifications
   const actionNotifyTimeouts = new Map<string, ReturnType<typeof setTimeout>>();
 
   function notifyAction(actionId: string) {
@@ -362,8 +330,6 @@ export function createEventController(
       actionId,
       setTimeout(() => {
         actionNotifyTimeouts.delete(actionId);
-        // Notify all listeners whose subscription ID matches this action
-        // This includes exact matches and suffix matches (e.g., "addToCart" matches "hash#addToCart")
         for (const [subscriptionId, listeners] of actionListeners) {
           if (matchesActionId(subscriptionId, actionId)) {
             const state = getActionState(subscriptionId);
@@ -376,12 +342,7 @@ export function createEventController(
 
   const notifyHandles = makeDebouncedNotifier(handleListeners);
 
-  // ========================================================================
-  // Derived State
-  // ========================================================================
-
   function getState(): DerivedNavigationState {
-    // Build inflight actions list (for compatibility with existing API)
     const inflightActionsList: InflightAction[] = [...inflightActions.values()]
       .filter((a) => a.phase !== "settling")
       .map((a) => ({
@@ -391,15 +352,12 @@ export function createEventController(
         startedAt: a.startedAt,
       }));
 
-    // State: loading if navigation OR actions are in progress
-    // Background revalidations (skipLoadingState) don't affect visible state
     const hasActiveActions = inflightActionsList.length > 0;
     const isVisibleNavigation =
       currentNavigation !== null &&
       !currentNavigation.options?.skipLoadingState;
     const state = isVisibleNavigation || hasActiveActions ? "loading" : "idle";
 
-    // Streaming: true if any active streams (navigation or action) or loading
     const isStreaming = activeStreamCount > 0 || state === "loading";
 
     return {
@@ -421,8 +379,6 @@ export function createEventController(
   }
 
   function getActionState(actionId: string): TrackedActionState {
-    // Prefer the most-recent non-settling entry; fall back to most-recent
-    // settling so a just-settled action's result/error stays readable.
     const entry = [...inflightActions.values()]
       .filter((a) => matchesActionId(actionId, a.actionId))
       .reduce<ActionEntry | undefined>((best, a) => {
@@ -437,7 +393,6 @@ export function createEventController(
       return { ...DEFAULT_ACTION_STATE };
     }
 
-    // Derive state from phase
     let state: ActionLifecycleState;
     switch (entry.phase) {
       case "fetching":
@@ -881,40 +836,3 @@ export function createEventController(
     hadAnyConcurrentActions: () => hadAnyConcurrentActions,
   };
 }
-
-// ============================================================================
-// Singleton
-// ============================================================================
-
-let controllerInstance: EventController | null = null;
-
-/**
- * Initialize the global event controller
- */
-export function initEventController(
-  config?: EventControllerConfig,
-): EventController {
-  if (!controllerInstance) {
-    controllerInstance = createEventController(config);
-  }
-  return controllerInstance;
-}
-
-/**
- * Get the global event controller
- */
-export function getEventController(): EventController {
-  if (!controllerInstance) {
-    throw new Error(
-      "Event controller not initialized. Call initEventController first.",
-    );
-  }
-  return controllerInstance;
-}
-
-/**
- * Reset the controller instance (for testing)
- */
-export function resetEventController(): void {
-  controllerInstance = null;
-}

package/src/browser/invalidate-client-cache.ts

@@ -0,0 +1,52 @@
+/**
+ * Client seat of `invalidateClientCache()` (the `default` export condition).
+ *
+ * Makes the current client behave as if a server action had just completed:
+ * the history cache is marked stale (SWR), the prefetch map is flushed, the
+ * state rotates, and sibling tabs are broadcast to — the same
+ * `markCacheAsStaleAndBroadcast()` path the server-action bridge uses. This is
+ * the gentler mark-stale (not hard-clear) behavior, so Back renders the cached
+ * entry instantly and revalidates.
+ */
+
+import { getRegisteredStore } from "./navigation-store-handle.js";
+import { clearPrefetchCache } from "./prefetch/cache.js";
+
+export function invalidateClientCache(): void {
+  if (typeof document === "undefined") {
+    // SSR pass of a client component also resolves the default condition. A
+    // render-time call must not take down the page; no-op with a dev warning.
+    if (process.env.NODE_ENV !== "production") {
+      console.warn(
+        "[rango] invalidateClientCache() was called during a server render; " +
+          "it is a no-op outside the browser.",
+      );
+    }
+    return;
+  }
+
+  const store = getRegisteredStore();
+  if (store) {
+    store.markCacheAsStaleAndBroadcast();
+    return;
+  }
+
+  // Pre-boot: no store registered yet. clearPrefetchCache() (which rotates the
+  // state) is complete at this point — there is no history cache to mark and no
+  // sibling state worth broadcasting.
+  clearPrefetchCache();
+}
+
+/**
+ * Client no-op for `keepClientCache()`. It is a server action directive (the
+ * `react-server` condition sets a response header the action bridge reads);
+ * there is nothing to suppress from the client side.
+ */
+export function keepClientCache(): void {
+  if (process.env.NODE_ENV !== "production") {
+    console.warn(
+      "[rango] keepClientCache() has no effect on the client; it is a server " +
+        "action directive. Call it from inside a server action.",
+    );
+  }
+}

package/src/browser/navigation-bridge.ts

@@ -5,6 +5,8 @@ import type {
   ResolvedSegment,
 } from "./types.js";
 import { setAppVersion } from "./app-version.js";
+import { isActionFenceActive } from "./action-fence.js";
+import { getRangoState } from "./rango-state.js";
 import * as React from "react";
 import { startTransition } from "react";
 import {
@@ -446,11 +448,22 @@ export function createNavigationBridge(
       // Helper to check if streaming is in progress
       const isStreaming = () => eventController.getState().isStreaming;
 
+      // Surface any external rotation of the rango state cookie (a server
+      // Set-Cookie, a sibling tab, a cookie clear) BEFORE reading the stale bit.
+      // The divergence observer only runs inside getRangoState() — fetch-time —
+      // so a popstate-first interaction would otherwise serve a pre-mutation
+      // page as fresh and never fetch to trigger the observer. Reading here lets
+      // the observer mark the history cache stale so getCachedSegments sees it.
+      getRangoState();
+
       // Check if we can restore from history cache
       const cached = store.getCachedSegments(historyKey);
       const cachedSegments = cached?.segments;
       const cachedHandleData = cached?.handleData;
-      const isStale = cached?.stale ?? false;
+      // While an action is in flight the fence persists no stale flag, so OR it
+      // in here: a popstate during the flight serves the cached entry AND
+      // revalidates (SWR) instead of serving it as fresh.
+      const isStale = (cached?.stale ?? false) || isActionFenceActive();
 
       if (cachedSegments && cachedSegments.length > 0) {
         // Update store to point to this history entry

package/src/browser/navigation-client.ts

@@ -12,6 +12,7 @@ import {
   startBrowserTransaction,
 } from "./logging.js";
 import { getRangoState } from "./rango-state.js";
+import { isActionFenceActive } from "./action-fence.js";
 import {
   extractRscHeaderUrl,
   emptyResponse,
@@ -108,7 +109,14 @@ export function createNavigationClient(
       // server-action invalidation) auto-invalidates both scopes.
       // Skip cache for stale revalidation (needs fresh data), HMR (needs
       // fresh modules), and intercept contexts (source-dependent responses).
-      const canUsePrefetch = !staleRevalidation && !hmr && !interceptSourceUrl;
+      // Suspend prefetch consumption while an action is in flight: a queued
+      // prefetch holds pre-mutation data and must not be served until the
+      // action's response decides whether anything changed.
+      const canUsePrefetch =
+        !staleRevalidation &&
+        !hmr &&
+        !interceptSourceUrl &&
+        !isActionFenceActive();
       const rangoState = getRangoState();
       const wildcardKey = buildPrefetchKey(rangoState, fetchUrl);
       const cacheKey = buildSourceKey(rangoState, previousUrl, fetchUrl);
@@ -207,6 +215,11 @@ export function createNavigationClient(
         }
 
         return fetch(fetchUrl, {
+          // During an action's flight the state is not rotated, so the old
+          // X-Rango-State still matches the Vary-keyed HTTP-cache entry; bypass
+          // it so a genuine mid-action navigation fetches fresh instead of being
+          // served the stale prefetched bytes.
+          ...(isActionFenceActive() && { cache: "no-store" as RequestCache }),
           headers: {
             "X-RSC-Router-Client-Path": previousUrl,
             "X-Rango-State": getRangoState(),

package/src/browser/navigation-store-handle.ts

@@ -0,0 +1,38 @@
+/**
+ * A module-level handle to the active navigation store.
+ *
+ * The boot path (`rsc-router.tsx`) calls `createNavigationStore()` directly;
+ * there is no global store singleton. This handle is the live reference for
+ * code that needs the store but does not
+ * receive it by argument: the jar-divergence observer (below) and the client
+ * seat of `invalidateClientCache()` (added later).
+ *
+ * Dependency-light on purpose: it imports only `setRangoStateObserver` and the
+ * store type, so pulling it into the default root entry does not drag the
+ * navigation store into bundles that previously lacked it.
+ */
+
+import { setRangoStateObserver } from "./rango-state.js";
+import type { NavigationStore } from "./types.js";
+
+let registeredStore: NavigationStore | null = null;
+
+/**
+ * Register the active navigation store at boot, and wire the jar-divergence
+ * observer: when a per-request cookie read detects an EXTERNAL rotation (a
+ * sibling tab, a server `Set-Cookie`, or a cookie clear), mark this tab's
+ * history cache stale. The history cache is not state-keyed, so the value
+ * rotation alone does not reach it. No broadcast, no prefetch clear, no
+ * re-rotation — the value already changed externally.
+ */
+export function registerNavigationStore(store: NavigationStore): void {
+  registeredStore = store;
+  setRangoStateObserver(() => {
+    registeredStore?.markHistoryCacheStale();
+  });
+}
+
+/** The active navigation store, or null before boot has registered it. */
+export function getRegisteredStore(): NavigationStore | null {
+  return registeredStore;
+}

package/src/browser/navigation-store.ts

@@ -130,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;
@@ -335,12 +335,24 @@ export function createNavigationStore(
   }
 
   /**
-   * 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();
   }
 
@@ -659,6 +671,16 @@ export function createNavigationStore(
       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();
+    },
+
     /**
      * Clear the history cache and broadcast to other tabs
      * Use this for hard invalidation when data is definitely stale
@@ -675,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
@@ -799,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

@@ -13,7 +13,6 @@ 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. */
@@ -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,72 +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 (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,
@@ -217,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 {
@@ -264,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]();
       }