@rangojs/router 0.0.0-experimental.e16b7c00 → 0.0.0-experimental.e9c0b2f2

package/src/browser/event-controller.ts

@@ -10,7 +10,10 @@ import type {
   HandleData,
   StreamingToken,
 } from "./types.js";
-import { filterSegmentOrder } from "./react/filter-segment-order.js";
+import {
+  filterSegmentOrder,
+  filterRouteSegmentIds,
+} from "./react/filter-segment-order.js";
 
 // Polyfill Symbol.dispose for Safari and older browsers
 if (typeof Symbol.dispose === "undefined") {
@@ -165,6 +168,22 @@ export interface ActionHandle extends Disposable {
   startStreaming(): StreamingToken;
   /** Record segments that were revalidated */
   recordRevalidatedSegments(segmentIds: string[]): void;
+  /**
+   * Claim the subset of a location-state payload this action may write. A key
+   * is claimed only if no later-initiated action in the SAME cohort has already
+   * claimed it, so same-key concurrent writes resolve to the last-initiated
+   * action while distinct keys from every action survive. Recording the claim
+   * stops a later-settling earlier action from overwriting it. Arbitration is
+   * scoped to the action's cohort (its originating history entry, captured at
+   * startAction), so an action on one entry cannot suppress an action on
+   * another that happens to write the same slot.
+   *
+   * Contract: this guarantees the FINAL value is the last-initiated action's,
+   * not that the loser is never momentarily visible. When an earlier-initiated
+   * action settles first, its value is merged and observable until the
+   * later-initiated winner's response lands and overwrites it.
+   */
+  claimLocationState(state: Record<string, unknown>): Record<string, unknown>;
   /** Complete the action with result */
   complete(result?: unknown): void;
   /** Fail the action with error */
@@ -191,7 +210,12 @@ export interface EventController {
   abortNavigation(): void;
 
   // Action operations
-  startAction(actionId: string, args: unknown[]): ActionHandle;
+  startAction(
+    actionId: string,
+    args: unknown[],
+    /** Originating history entry key; scopes location-state arbitration. */
+    cohort?: string,
+  ): ActionHandle;
   abortAllActions(): void;
 
   // State access
@@ -237,10 +261,6 @@ export interface EventController {
   hadAnyConcurrentActions(): boolean;
 }
 
-// ============================================================================
-// Default States
-// ============================================================================
-
 const DEFAULT_ACTION_STATE: TrackedActionState = {
   state: "idle",
   actionId: null,
@@ -261,16 +281,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 +298,6 @@ function makeDebouncedNotifier(listeners: Set<() => void>): () => void {
   };
 }
 
-// ============================================================================
-// Implementation
-// ============================================================================
-
-/**
- * Configuration for creating an event controller
- */
 export interface EventControllerConfig {
   initialLocation?: NavigationLocation;
 }
@@ -306,51 +315,56 @@ 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)
+  // Monotonic dispatch counter: every startAction() takes the next value
+  // (private), so a larger sequence means the action was initiated later.
+  let actionDispatchSeq = 0;
+
+  // Concurrent location-state arbitration, scoped PER COHORT (history entry).
+  // Each cohort owns a slotKey->winningDispatchSeq map plus a refcount of its
+  // inflight actions; claimLocationState() consults its own cohort's map so
+  // same-key writes within one entry resolve to the last-initiated action
+  // regardless of settle order, while actions on different entries never
+  // compete. A cohort's map is freed once its LAST action's cleanup runs — the
+  // same brief post-settle grace (doSettle's 100ms timer) as other action
+  // teardown, not when every action everywhere settles — so a long-running
+  // action in one cohort can never retain arbitration keys from other cohorts
+  // that have since drained. It is never cleared in clearConsolidation, which
+  // fires
+  // per-action on divert/error and would let a later-settling earlier action
+  // wrongly reclaim a key a sibling already won.
+  const cohortArbitration = new Map<
+    string,
+    { keySeq: Map<string, number>; inflight: number }
+  >();
+
   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 +376,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 +388,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 +398,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 +425,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 +439,6 @@ export function createEventController(
       return { ...DEFAULT_ACTION_STATE };
     }
 
-    // Derive state from phase
     let state: ActionLifecycleState;
     switch (entry.phase) {
       case "fetching":
@@ -552,10 +553,29 @@ export function createEventController(
   // Action Operations
   // ========================================================================
 
-  function startAction(actionId: string, args: unknown[]): ActionHandle {
+  function startAction(
+    actionId: string,
+    args: unknown[],
+    cohort?: string,
+  ): ActionHandle {
     const id = `${actionId}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+    // Private to this handle: never exposed on the returned ActionHandle.
+    const dispatchSeq = actionDispatchSeq++;
     const abort = new AbortController();
 
+    // Register this action under its cohort (originating history entry). The
+    // cohort's arbitration is created on first use and freed when its last
+    // action settles (see doSettle). Keyless entries share the "" cohort.
+    const cohortId = cohort ?? "";
+    let arb = cohortArbitration.get(cohortId);
+    if (!arb) {
+      arb = { keySeq: new Map<string, number>(), inflight: 0 };
+      cohortArbitration.set(cohortId, arb);
+    }
+    // const so the captured reference stays non-undefined inside doSettle.
+    const arbitration = arb;
+    arbitration.inflight++;
+
     // Track if this action started while others were pending (concurrent)
     const hadConcurrent = inflightActions.size > 0;
     if (hadConcurrent) {
@@ -579,11 +599,28 @@ export function createEventController(
     let settled = false;
     let streamingEnded = false;
     let actionCompleted = false;
+    let cohortReleased = false;
     let pendingResult:
       | { type: "success"; value?: unknown }
       | { type: "error"; value: unknown }
       | null = null;
 
+    // Release this action's hold on its cohort arbitration exactly once: drop
+    // the refcount and, only if the map still points at THIS arbitration object,
+    // delete it. A newer generation may have replaced it (e.g. abortAllActions
+    // cleared the map and a fresh action recreated the same cohort id), so a
+    // stale settlement must never delete the newer one by id.
+    function releaseCohort() {
+      if (cohortReleased) return;
+      cohortReleased = true;
+      if (
+        --arbitration.inflight <= 0 &&
+        cohortArbitration.get(cohortId) === arbitration
+      ) {
+        cohortArbitration.delete(cohortId);
+      }
+    }
+
     function doSettle() {
       if (settled) return;
       settled = true;
@@ -591,6 +628,9 @@ export function createEventController(
       // Cleanup after brief delay (allow useAction to read result)
       setTimeout(() => {
         inflightActions.delete(id);
+        // Free this cohort's arbitration once its last action has settled, so
+        // a long-running action elsewhere cannot pin keys from a drained entry.
+        releaseCohort();
         // Check for consolidation
         if (inflightActions.size === 0) {
           // All actions done - reset tracking
@@ -667,6 +707,26 @@ export function createEventController(
         segmentIds.forEach((id) => concurrentRevalidatedSegments.add(id));
       },
 
+      claimLocationState(state: Record<string, unknown>) {
+        const winning: Record<string, unknown> = {};
+        // Arbitrate against this action's OWN captured arbitration object, not a
+        // live map lookup: a concurrent map clear/replace (abortAllActions, a
+        // stale settlement) must not make this action silently stop recording
+        // and accept every key.
+        const keySeq = arbitration.keySeq;
+        for (const key of Object.keys(state)) {
+          const prevSeq = keySeq.get(key);
+          // Strictly-greater: a later-initiated action wins a key over an
+          // earlier one in the same cohort regardless of arrival order. Equal
+          // cannot happen (dispatchSeq is unique per action).
+          if (prevSeq === undefined || dispatchSeq > prevSeq) {
+            keySeq.set(key, dispatchSeq);
+            winning[key] = state[key];
+          }
+        }
+        return winning;
+      },
+
       complete(result?: unknown) {
         settleWith({ type: "success", value: result });
       },
@@ -688,6 +748,10 @@ export function createEventController(
       [Symbol.dispose]() {
         // If aborted, another navigation/error took over - don't touch state
         if (abort.signal.aborted) {
+          // Aborted actions skip doSettle, so release the cohort hold here to
+          // keep the per-cohort refcount balanced (no leak when an action is
+          // aborted individually rather than via abortAllActions).
+          releaseCohort();
           inflightActions.delete(id);
           notify();
           notifyAction(actionId);
@@ -722,6 +786,7 @@ export function createEventController(
     }
     hadAnyConcurrentActions = false;
     concurrentRevalidatedSegments.clear();
+    cohortArbitration.clear();
     notify();
     // Notify all action listeners directly by subscription ID.
     // actionListeners keys are subscription IDs (possibly short names like
@@ -748,9 +813,7 @@ export function createEventController(
     const newSegmentOrder = filterSegmentOrder(rawMatched);
     // Separate list for useSegments(): "layouts and routes only" — strip
     // parallels (".@") and loader sub-ids (D digit) without reordering.
-    const newRouteSegmentIds = rawMatched.filter(
-      (id) => !id.includes(".@") && !/D\d+\./.test(id),
-    );
+    const newRouteSegmentIds = filterRouteSegmentIds(rawMatched);
 
     if (isPartial && newSegmentOrder.length > 0) {
       // Partial update: merge new data with existing
@@ -881,40 +944,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,8 +5,8 @@ import type {
   ResolvedSegment,
 } from "./types.js";
 import { setAppVersion } from "./app-version.js";
-import { setRangoStateLocal } from "./rango-state.js";
-import type { AppShell, AppShellRef } from "./app-shell.js";
+import { isActionFenceActive } from "./action-fence.js";
+import { getRangoState } from "./rango-state.js";
 import * as React from "react";
 import { startTransition } from "react";
 import {
@@ -50,13 +50,8 @@ export { createNavigationTransaction };
  */
 export interface NavigationBridgeConfigWithController extends NavigationBridgeConfig {
   eventController: EventController;
-  /** RSC version from initial payload metadata (fallback when appShellRef is not provided) */
+  /** RSC version from initial payload metadata. */
   version?: string;
-  /**
-   * Live app-shell ref. When supplied, the bridge reads version/basename
-   * from this ref so cross-app navigations propagate correctly.
-   */
-  appShellRef?: AppShellRef;
 }
 
 /**
@@ -75,46 +70,9 @@ export interface NavigationBridgeConfigWithController extends NavigationBridgeCo
 export function createNavigationBridge(
   config: NavigationBridgeConfigWithController,
 ): NavigationBridge {
-  const {
-    store,
-    client,
-    eventController,
-    onUpdate,
-    renderSegments,
-    appShellRef,
-  } = config;
+  const { store, client, eventController, onUpdate, renderSegments } = config;
   let version = config.version;
 
-  /**
-   * Replace the active app-shell snapshot atomically. Called by the partial
-   * updater when a response's routerId indicates the navigation crossed
-   * into a different app. Runs the local-only side-effects tied to
-   * app-shell fields (app version, rango-state namespace) so the new app
-   * owns them after the swap. Theme, warmup, and prefetch TTL are
-   * document-lifetime and are NOT touched here.
-   */
-  function applyAppShell(next: AppShell): void {
-    if (appShellRef) {
-      appShellRef.update(next);
-    }
-    if (next.version !== undefined) {
-      version = next.version;
-      setAppVersion(next.version);
-      // Use the local-only setter — initRangoState writes the shared
-      // localStorage key and fires a storage event in other tabs still in
-      // the old app. setRangoStateLocal only mutates this tab's in-memory
-      // cache and rebinds it to the target app's routerId-scoped key,
-      // preserving the "local-only, no broadcast/rotation" contract for
-      // smooth app-switch transitions.
-      setRangoStateLocal(next.version, next.routerId);
-    }
-    // Cross-app: prior cache entries belong to a different app's segments.
-    // Drop them locally only — do NOT broadcast invalidation or rotate the
-    // shared X-Rango-State token, since other tabs still in the old app are
-    // unaffected by this tab's transition.
-    store.clearHistoryCacheLocal();
-  }
-
   // Create shared partial updater
   const fetchPartialUpdate = createPartialUpdater({
     store,
@@ -122,7 +80,6 @@ export function createNavigationBridge(
     onUpdate,
     renderSegments,
     getVersion: () => version,
-    applyAppShell,
   });
 
   return {
@@ -491,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
@@ -716,10 +684,6 @@ export function createNavigationBridge(
       setAppVersion(newVersion);
       store.clearHistoryCache();
     },
-
-    updateAppShell(next: AppShell): void {
-      applyAppShell(next);
-    },
   };
 }