@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.80daa23e

package/src/browser/event-controller.ts

@@ -8,7 +8,13 @@ import type {
   ResolvedSegment,
   RscMetadata,
   HandleData,
+  StreamingToken,
 } from "./types.js";
+import {
+  filterSegmentOrder,
+  filterRouteSegmentIds,
+} from "./react/filter-segment-order.js";
+import { notifyListeners } from "./notify-listeners.js";
 
 // Polyfill Symbol.dispose for Safari and older browsers
 if (typeof Symbol.dispose === "undefined") {
@@ -40,7 +46,7 @@ export interface NavigationEntry {
   abort: AbortController;
   phase: NavigationPhase;
   startedAt: number;
-  options?: NavigateOptions;
+  options?: NavigateOptions & { skipLoadingState?: boolean };
 }
 
 /**
@@ -77,6 +83,8 @@ export interface DerivedNavigationState {
   state: "idle" | "loading";
   /** Whether any operation is streaming */
   isStreaming: boolean;
+  /** Whether a navigation is active (fetching or streaming, before commit) */
+  isNavigating: boolean;
   /** Current committed location */
   location: NavigationLocation;
   /** URL being navigated to (null if idle) */
@@ -109,20 +117,24 @@ export type ActionStateListener = (state: TrackedActionState) => void;
 export type HandleListener = () => void;
 
 /**
- * Internal handle state stored in controller
+ * Internal handle state stored in controller.
+ *
+ * Two segment lists are exposed because they serve different consumers:
+ *
+ * - `segmentOrder` drives handle collection (collectHandleData). Includes
+ *   parallel slot ids and reorders them after their parent so later-wins
+ *   collect functions (e.g. Meta) get the right precedence.
+ * - `routeSegmentIds` is the layouts-and-routes-only list documented by
+ *   `useSegments().segmentIds`. Parallels and loader sub-ids are stripped;
+ *   raw matched order is preserved.
+ *
+ * Both are derived from the same `matched` input on each setHandleData call
+ * so they stay in sync.
  */
 export interface HandleState {
   data: HandleData;
   segmentOrder: string[];
-}
-
-/**
- * Token for tracking an active stream
- * Call end() when the stream completes
- */
-export interface StreamingToken {
-  /** End this streaming operation */
-  end(): void;
+  routeSegmentIds: string[];
 }
 
 /**
@@ -157,6 +169,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 */
@@ -165,8 +193,8 @@ export interface ActionHandle extends Disposable {
   readonly settled: boolean;
   /** Check if any concurrent actions were started */
   hadConcurrentActions: boolean;
-  /** Get segments to consolidate (only valid when this is the last action) */
-  getConsolidationSegments(): string[] | null;
+  /** Get raw set of segments revalidated by concurrent actions */
+  getRevalidatedSegments(): Set<string>;
   /** Clear consolidation tracking */
   clearConsolidation(): void;
 }
@@ -176,16 +204,25 @@ export interface ActionHandle extends Disposable {
  */
 export interface EventController {
   // Navigation operations
-  startNavigation(url: string, options?: NavigateOptions): NavigationHandle;
+  startNavigation(
+    url: string,
+    options?: NavigateOptions & { skipLoadingState?: boolean },
+  ): NavigationHandle;
   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
   getState(): DerivedNavigationState;
   getActionState(actionId: string): TrackedActionState;
+  getLocation(): NavigationLocation;
 
   // Location updates (for popstate where navigation doesn't go through startNavigation)
   setLocation(location: NavigationLocation): void;
@@ -194,26 +231,115 @@ export interface EventController {
   subscribe(listener: StateListener): () => void;
   subscribeToAction(
     actionId: string,
-    listener: ActionStateListener
+    listener: ActionStateListener,
   ): () => void;
   subscribeToHandles(listener: HandleListener): () => void;
+  /**
+   * Deliver queued location, params, navigation, and handle notifications now.
+   * NavigationProvider calls this inside the payload update so React assigns
+   * every route-state hook update to the same normal or transition lane.
+   */
+  flushRouteState(): void;
 
   // Handle operations
   setHandleData(
     data: HandleData,
     matched?: string[],
-    isPartial?: boolean
+    isPartial?: boolean,
+    /**
+     * Segment ids that were re-resolved on the server this request (the
+     * partial response's `diff`). On a partial update, any existing bucket
+     * keyed under one of these ids that has no incoming entry is treated as
+     * stale and cleared. Without this, a parallel slot that revalidates but
+     * pushes nothing leaves its previous bucket in place forever.
+     */
+    resolvedIds?: string[],
   ): void;
   getHandleState(): HandleState;
+  /**
+   * Update ONLY `routeSegmentIds` (what `useSegments` reads) from `matched`,
+   * leaving `data` and `segmentOrder` (what `useHandle` collects over) untouched.
+   * Used while a deferred handle is resolving: the route has changed (so
+   * `useSegments` must reflect the new segment ids) but `useHandle` still holds
+   * its previous value until the deferred snapshot is applied.
+   */
+  setRouteSegmentIds(matched: string[]): void;
+
+  // Params operations
+  setParams(params: Record<string, string>): void;
+  getParams(): Record<string, string>;
 
   // Direct state access for advanced use
   getCurrentNavigation(): NavigationEntry | null;
   getInflightActions(): Map<string, ActionEntry>;
+  /** Whether any concurrent actions have occurred (shared across all handles) */
+  hadAnyConcurrentActions(): boolean;
 }
 
-// ============================================================================
-// Default States
-// ============================================================================
+type LocationChangeController = Pick<EventController, "getState" | "subscribe">;
+
+interface LocationChangeSubscription {
+  registrations: Map<
+    symbol,
+    { href: string; listener: (href: string) => void }
+  >;
+  notificationVersion: number;
+  unsubscribe: () => void;
+}
+
+const locationChangeSubscriptions = new WeakMap<
+  LocationChangeController,
+  LocationChangeSubscription
+>();
+
+/** Share one controller subscription across all location-change consumers. */
+export function subscribeToLocationChange(
+  eventController: LocationChangeController,
+  listener: (href: string) => void,
+): () => void {
+  let subscription = locationChangeSubscriptions.get(eventController);
+  if (!subscription) {
+    subscription = {
+      registrations: new Map(),
+      notificationVersion: 0,
+      unsubscribe: () => {},
+    };
+    locationChangeSubscriptions.set(eventController, subscription);
+    const currentSubscription = subscription;
+    subscription.unsubscribe = eventController.subscribe(() => {
+      const notificationVersion = ++currentSubscription.notificationVersion;
+      const nextHref = eventController.getState().location.href;
+      notifyListeners(
+        [...currentSubscription.registrations],
+        ([, registration]) => {
+          if (registration.href === nextHref) return;
+          registration.href = nextHref;
+          registration.listener(nextHref);
+        },
+        ([token, registration]) =>
+          currentSubscription.registrations.get(token) === registration,
+        () => notificationVersion === currentSubscription.notificationVersion,
+      );
+    });
+  }
+
+  const token = Symbol();
+  subscription.registrations.set(token, {
+    href: eventController.getState().location.href,
+    listener,
+  });
+  let active = true;
+  return () => {
+    if (!active) return;
+    active = false;
+    subscription!.registrations.delete(token);
+    if (subscription!.registrations.size > 0) return;
+    if (locationChangeSubscriptions.get(eventController) === subscription) {
+      locationChangeSubscriptions.delete(eventController);
+    }
+    subscription!.unsubscribe();
+  };
+}
 
 const DEFAULT_ACTION_STATE: TrackedActionState = {
   state: "idle",
@@ -223,6 +349,13 @@ const DEFAULT_ACTION_STATE: TrackedActionState = {
   result: null,
 };
 
+// Shared empty inflight-actions list. getState() hands back this exact reference
+// whenever no action is inflight (the overwhelmingly common case), so the derived
+// snapshot's `inflightActions` is referentially stable across notifies instead of
+// a fresh [] each call. Read-only by contract (consumers only read length/spread),
+// same as the shared DEFAULT_ACTION_STATE.
+const EMPTY_INFLIGHT_ACTIONS: InflightAction[] = [];
+
 /**
  * Check if a subscription ID matches an action's full ID.
  *
@@ -230,22 +363,45 @@ const DEFAULT_ACTION_STATE: TrackedActionState = {
  * When subscriptionId has no '#', it's just an action name and matches by suffix.
  * This allows useAction("addToCart") to match "hash#addToCart" or "src/file.ts#addToCart".
  */
-function matchesActionId(subscriptionId: string, entryActionId: string): boolean {
+function matchesActionId(
+  subscriptionId: string,
+  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}`);
 }
 
-// ============================================================================
-// Implementation
-// ============================================================================
+interface DebouncedNotifier {
+  schedule(): void;
+  flush(): void;
+}
+
+// Batch rapid notifications into one task to prevent render storms. The
+// explicit flush lets a React update owner preserve its scheduling lane.
+function makeDebouncedNotifier(listeners: Set<() => void>): DebouncedNotifier {
+  let timeout: ReturnType<typeof setTimeout> | null = null;
+  const flush = () => {
+    if (timeout === null) return;
+    clearTimeout(timeout);
+    timeout = null;
+    notifyListeners(
+      [...listeners],
+      (listener) => listener(),
+      (listener) => listeners.has(listener),
+    );
+  };
+
+  return {
+    schedule() {
+      if (timeout !== null) clearTimeout(timeout);
+      timeout = setTimeout(flush, 0);
+    },
+    flush,
+  };
+}
 
-/**
- * Configuration for creating an event controller
- */
 export interface EventControllerConfig {
   initialLocation?: NavigationLocation;
 }
@@ -261,62 +417,105 @@ export interface EventControllerConfig {
  * Actions use mergeMap semantics (all run concurrently, consolidate at end).
  */
 export function createEventController(
-  config?: EventControllerConfig
+  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[] = [];
 
-  // ========================================================================
-  // Listeners
-  // ========================================================================
+  let routeParams: Record<string, string> = {};
 
   const stateListeners = new Set<StateListener>();
   const actionListeners = new Map<string, Set<ActionStateListener>>();
   const handleListeners = new Set<HandleListener>();
 
-  // Debounce state notifications to batch rapid updates
-  let notifyTimeout: ReturnType<typeof setTimeout> | null = null;
+  const notifyStateListeners = makeDebouncedNotifier(stateListeners);
 
-  function notify() {
-    if (notifyTimeout !== null) {
-      clearTimeout(notifyTimeout);
-    }
-    notifyTimeout = setTimeout(() => {
-      notifyTimeout = null;
-      stateListeners.forEach((listener) => listener());
-    }, 0);
+  // Memoized derived snapshot. Every state mutation already funnels through
+  // notify(), so invalidating here (synchronously, before the debounced fire)
+  // means a getState() call between two mutations reuses the same object — an
+  // unchanged state returns the SAME reference — while any real change recomputes
+  // on the next read. Kept null when dirty.
+  let cachedDerivedState: DerivedNavigationState | null = null;
+
+  function notify(): void {
+    cachedDerivedState = null;
+    notifyStateListeners.schedule();
   }
 
-  // Debounce per-action notifications
   const actionNotifyTimeouts = new Map<string, ReturnType<typeof setTimeout>>();
 
+  function notifyActionListenerSets(
+    subscriptions: Iterable<[string, Set<ActionStateListener>]>,
+  ): void {
+    const subscriptionSnapshots = [...subscriptions].map(
+      ([subscriptionId, listeners]) => ({
+        listenerSnapshot: [...listeners],
+        listeners,
+        subscriptionId,
+      }),
+    );
+    function* notifications(): Generator<{
+      listener: ActionStateListener;
+      listeners: Set<ActionStateListener>;
+      state: TrackedActionState;
+    }> {
+      for (const {
+        listenerSnapshot,
+        listeners,
+        subscriptionId,
+      } of subscriptionSnapshots) {
+        const state = getActionState(subscriptionId);
+        for (const listener of listenerSnapshot) {
+          yield { listener, listeners, state };
+        }
+      }
+    }
+    notifyListeners(
+      notifications(),
+      ({ listener, state }) => listener(state),
+      ({ listener, listeners }) => listeners.has(listener),
+    );
+  }
+
   function notifyAction(actionId: string) {
     const existing = actionNotifyTimeouts.get(actionId);
     if (existing !== undefined) {
@@ -326,83 +525,85 @@ 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);
-            listeners.forEach((listener) => listener(state));
-          }
-        }
-      }, 0)
+        notifyActionListenerSets(
+          [...actionListeners].filter(([subscriptionId]) =>
+            matchesActionId(subscriptionId, actionId),
+          ),
+        );
+      }, 0),
     );
   }
 
-  // Debounce handle notifications
-  let handleNotifyTimeout: ReturnType<typeof setTimeout> | null = null;
+  const notifyHandles = makeDebouncedNotifier(handleListeners);
 
-  function notifyHandles() {
-    if (handleNotifyTimeout !== null) {
-      clearTimeout(handleNotifyTimeout);
-    }
-    handleNotifyTimeout = setTimeout(() => {
-      handleNotifyTimeout = null;
-      handleListeners.forEach((listener) => listener());
-    }, 0);
+  function flushRouteState(): void {
+    notifyStateListeners.flush();
+    notifyHandles.flush();
   }
 
-  // ========================================================================
-  // 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) => ({
-        id: a.id,
-        actionId: a.actionId,
-        payload: a.payload,
-        startedAt: a.startedAt,
-      }));
-
-    // State: loading if navigation OR actions are in progress
+    if (cachedDerivedState) return cachedDerivedState;
+
+    // Skip the spread/filter/map entirely when idle — the common case — and hand
+    // back the shared frozen empty list for referential stability.
+    const inflightActionsList: InflightAction[] =
+      inflightActions.size === 0
+        ? EMPTY_INFLIGHT_ACTIONS
+        : [...inflightActions.values()]
+            .filter((a) => a.phase !== "settling")
+            .map((a) => ({
+              id: a.id,
+              actionId: a.actionId,
+              payload: a.payload,
+              startedAt: a.startedAt,
+            }));
+
     const hasActiveActions = inflightActionsList.length > 0;
-    const state =
-      currentNavigation !== null || hasActiveActions ? "loading" : "idle";
+    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 {
+    cachedDerivedState = {
       state,
       isStreaming,
+      // True when a navigation is active (fetching or streaming, before
+      // commit). Broader than pendingUrl which clears during streaming.
+      isNavigating: currentNavigation !== null,
       location,
-      // pendingUrl only during fetching phase - once streaming starts (URL changed), not pending
-      pendingUrl: currentNavigation?.phase === "fetching" ? currentNavigation.url : null,
+      // pendingUrl only during fetching phase - once streaming starts (URL changed), not pending.
+      // Background revalidations (skipLoadingState) don't expose a pending URL.
+      pendingUrl:
+        currentNavigation?.phase === "fetching" &&
+        !currentNavigation.options?.skipLoadingState
+          ? currentNavigation.url
+          : null,
       inflightActions: inflightActionsList,
     };
+    return cachedDerivedState;
   }
 
   function getActionState(actionId: string): TrackedActionState {
-    // Find the most recent action with this ID that's not settling
-    // Uses suffix matching when actionId is just a name (no #)
-    const activeEntry = [...inflightActions.values()]
-      .filter((a) => matchesActionId(actionId, a.actionId) && a.phase !== "settling")
-      .sort((a, b) => b.startedAt - a.startedAt)[0];
-
-    // Also check for settling entries to get result/error
-    const settlingEntry = [...inflightActions.values()]
-      .filter((a) => matchesActionId(actionId, a.actionId) && a.phase === "settling")
-      .sort((a, b) => b.startedAt - a.startedAt)[0];
-
-    const entry = activeEntry || settlingEntry;
+    // Nothing inflight — skip building/scanning the list and return the shared
+    // idle snapshot (the same reference use-action falls back to).
+    if (inflightActions.size === 0) return DEFAULT_ACTION_STATE;
+
+    const entry = [...inflightActions.values()]
+      .filter((a) => matchesActionId(actionId, a.actionId))
+      .reduce<ActionEntry | undefined>((best, a) => {
+        if (!best) return a;
+        const aActive = a.phase !== "settling";
+        const bActive = best.phase !== "settling";
+        if (aActive !== bActive) return aActive ? a : best;
+        return a.startedAt > best.startedAt ? a : best;
+      }, undefined);
 
     if (!entry) {
       return { ...DEFAULT_ACTION_STATE };
     }
 
-    // Derive state from phase
     let state: ActionLifecycleState;
     switch (entry.phase) {
       case "fetching":
@@ -431,7 +632,7 @@ export function createEventController(
 
   function startNavigation(
     url: string,
-    options?: NavigateOptions
+    options?: NavigateOptions & { skipLoadingState?: boolean },
   ): NavigationHandle {
     // Cancel existing navigation (switchMap semantics)
     if (currentNavigation) {
@@ -463,6 +664,7 @@ export function createEventController(
 
       startStreaming(): StreamingToken {
         let ended = false;
+        entry.phase = "streaming";
         activeStreamCount++;
         notify();
 
@@ -516,12 +718,45 @@ 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();
 
-    // Track if this action started while others were pending (concurrent)
-    const hadConcurrent = inflightActions.size > 0;
+    // 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 another was genuinely in-flight.
+    // Completed entries don't count: complete()/fail() ran, so the prior
+    // action's response was fully processed and applied — a request dispatched
+    // after that point is strictly ordered behind the prior action's server
+    // execution, and there is no skipped render or order uncertainty for
+    // consolidation to repair. Completed entries still linger in the map for
+    // the 100ms doSettle window (useAction reads) and, on a slow connection,
+    // while the Flight stream drains its EOF after complete(). Counting them
+    // latched hadAnyConcurrentActions for back-to-back sequential actions,
+    // which made the LAST action classify as consolidation-needed; the
+    // consolidation refetch omits every concurrently-revalidated segment id
+    // from _rsc_segments, so the server re-ran gated loaders as "new-segment"
+    // — bypassing revalidate(({ isAction }) => ...) on a plain GET (#675).
+    const hadConcurrent = [...inflightActions.values()].some(
+      (a) => !a.completed,
+    );
     if (hadConcurrent) {
       hadAnyConcurrentActions = true;
     }
@@ -543,11 +778,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;
@@ -555,6 +807,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
@@ -583,6 +838,19 @@ export function createEventController(
       doSettle();
     }
 
+    // streamingEnded is forced here for the "streaming never started" case so
+    // tryFinalize can run; otherwise the streaming token's end() finalizes.
+    function settleWith(result: NonNullable<typeof pendingResult>) {
+      if (!inflightActions.has(id) || settled) return;
+      actionCompleted = true;
+      entry.completed = true;
+      pendingResult = result;
+      if (entry.phase === "fetching" || streamingEnded) {
+        streamingEnded = true;
+        tryFinalize();
+      }
+    }
+
     return {
       id,
       abort,
@@ -618,56 +886,36 @@ export function createEventController(
         segmentIds.forEach((id) => concurrentRevalidatedSegments.add(id));
       },
 
-      complete(result?: unknown) {
-        if (!inflightActions.has(id) || settled) return;
-
-        actionCompleted = true;
-        entry.completed = true;
-        pendingResult = { type: "success", value: result };
-
-        // If streaming never started or already ended, finalize immediately
-        // Otherwise wait for streaming to end
-        if (entry.phase === "fetching" || streamingEnded) {
-          streamingEnded = true; // Mark as ended if never started
-          tryFinalize();
+      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];
+          }
         }
-        // If streaming is in progress, tryFinalize() will be called when streaming ends
+        return winning;
       },
 
-      fail(error: unknown) {
-        if (!inflightActions.has(id) || settled) return;
-
-        actionCompleted = true;
-        entry.completed = true;
-        pendingResult = { type: "error", value: error };
-
-        // If streaming never started or already ended, finalize immediately
-        // Otherwise wait for streaming to end
-        if (entry.phase === "fetching" || streamingEnded) {
-          streamingEnded = true; // Mark as ended if never started
-          tryFinalize();
-        }
-        // If streaming is in progress, tryFinalize() will be called when streaming ends
+      complete(result?: unknown) {
+        settleWith({ type: "success", value: result });
       },
 
-      getConsolidationSegments(): string[] | null {
-        // Only consolidate if all actions have at least received their response
-        // We don't need to wait for streaming to complete since we're refetching anyway
-        // Count actions that are still fetching (waiting for server response)
-        const stillFetchingCount = [...inflightActions.values()].filter(
-          (a) => a.phase === "fetching"
-        ).length;
+      fail(error: unknown) {
+        settleWith({ type: "error", value: error });
+      },
 
-        if (stillFetchingCount > 0) {
-          return null; // Some actions still waiting for server response
-        }
-        if (!hadAnyConcurrentActions) {
-          return null; // No concurrent actions occurred
-        }
-        if (concurrentRevalidatedSegments.size === 0) {
-          return null; // No segments to consolidate
-        }
-        return Array.from(concurrentRevalidatedSegments);
+      getRevalidatedSegments(): Set<string> {
+        return concurrentRevalidatedSegments;
       },
 
       clearConsolidation() {
@@ -679,6 +927,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);
@@ -702,41 +954,42 @@ export function createEventController(
   }
 
   function abortAllActions() {
-    for (const entry of inflightActions.values()) {
+    for (const [id, entry] of inflightActions) {
+      // Preserve settling entries — they have already been handled by
+      // fail()/complete() and will self-cleanup via the settlement timeout.
+      // Clearing them here would prevent debounced notifications from
+      // delivering the error/result state to subscribers.
+      if (entry.phase === "settling") continue;
       entry.abort.abort();
+      inflightActions.delete(id);
     }
-    inflightActions.clear();
     hadAnyConcurrentActions = false;
     concurrentRevalidatedSegments.clear();
+    cohortArbitration.clear();
     notify();
-    // Notify all action listeners
-    for (const actionId of actionListeners.keys()) {
-      notifyAction(actionId);
-    }
+    // Notify all action listeners directly by subscription ID.
+    // actionListeners keys are subscription IDs (possibly short names like
+    // "addToCart"), not full entry actionIds. Passing them to notifyAction
+    // would fail the suffix matcher — instead, notify each subscriber with
+    // its own state.
+    notifyActionListenerSets(actionListeners);
   }
 
   // ========================================================================
   // Handle Operations
   // ========================================================================
 
-  /**
-   * Filter segment IDs to only include routes and layouts.
-   * Excludes parallels (contain .@) and loaders (contain D followed by digit).
-   */
-  function filterSegmentOrder(matched: string[]): string[] {
-    return matched.filter((id) => {
-      if (id.includes(".@")) return false;
-      if (/D\d+\./.test(id)) return false;
-      return true;
-    });
-  }
-
   function setHandleData(
     data: HandleData,
     matched?: string[],
-    isPartial?: boolean
+    isPartial?: boolean,
+    resolvedIds?: string[],
   ): void {
-    const newSegmentOrder = filterSegmentOrder(matched ?? []);
+    const rawMatched = matched ?? [];
+    const newSegmentOrder = filterSegmentOrder(rawMatched);
+    // Separate list for useSegments(): "layouts and routes only" — strip
+    // parallels (".@") and loader sub-ids (D digit) without reordering.
+    const newRouteSegmentIds = filterRouteSegmentIds(rawMatched);
 
     if (isPartial && newSegmentOrder.length > 0) {
       // Partial update: merge new data with existing
@@ -748,10 +1001,19 @@ export function createEventController(
           handleData[handleName][segmentId] = data[handleName][segmentId];
         }
       }
-      // Clean up data from segments no longer in the matched list
+      const resolvedIdSet =
+        resolvedIds && resolvedIds.length > 0 ? new Set(resolvedIds) : null;
+      // Cleanup pass:
+      //   a) segment dropped from the match list — delete its bucket.
+      //   b) segment was re-resolved this request but pushed nothing for
+      //      this handle — its previous bucket is stale.
+      // (a) is the existing behavior; (b) requires resolvedIds.
       for (const handleName of Object.keys(handleData)) {
         for (const segmentId of Object.keys(handleData[handleName])) {
-          if (!newSegmentOrder.includes(segmentId)) {
+          const droppedFromMatch = !newSegmentOrder.includes(segmentId);
+          const reresolvedWithoutPush =
+            resolvedIdSet?.has(segmentId) && !data[handleName]?.[segmentId];
+          if (droppedFromMatch || reresolvedWithoutPush) {
             delete handleData[handleName][segmentId];
           }
         }
@@ -761,17 +1023,31 @@ export function createEventController(
       handleData = data;
     }
     handleSegmentOrder = newSegmentOrder;
+    routeSegmentIds = newRouteSegmentIds;
 
-    notifyHandles();
+    notifyHandles.schedule();
   }
 
   function getHandleState(): HandleState {
     return {
       data: handleData,
       segmentOrder: handleSegmentOrder,
+      routeSegmentIds,
     };
   }
 
+  function setRouteSegmentIds(matched: string[]): void {
+    const next = filterRouteSegmentIds(matched);
+    if (
+      next.length === routeSegmentIds.length &&
+      next.every((id, i) => id === routeSegmentIds[i])
+    ) {
+      return;
+    }
+    routeSegmentIds = next;
+    notifyHandles.schedule();
+  }
+
   // ========================================================================
   // Subscriptions
   // ========================================================================
@@ -783,7 +1059,7 @@ export function createEventController(
 
   function subscribeToAction(
     actionId: string,
-    listener: ActionStateListener
+    listener: ActionStateListener,
   ): () => void {
     let listeners = actionListeners.get(actionId);
     if (!listeners) {
@@ -805,6 +1081,19 @@ export function createEventController(
     return () => handleListeners.delete(listener);
   }
 
+  // ========================================================================
+  // Params Operations
+  // ========================================================================
+
+  function setParams(params: Record<string, string>): void {
+    routeParams = params;
+    notify();
+  }
+
+  function getParams(): Record<string, string> {
+    return routeParams;
+  }
+
   // ========================================================================
   // Return Controller
   // ========================================================================
@@ -821,56 +1110,27 @@ export function createEventController(
     // State
     getState,
     getActionState,
+    getLocation: () => location,
     setLocation,
 
     // Handles
     setHandleData,
     getHandleState,
+    setRouteSegmentIds,
+
+    // Params
+    setParams,
+    getParams,
 
     // Subscriptions
     subscribe,
     subscribeToAction,
     subscribeToHandles,
+    flushRouteState,
 
     // Direct access
     getCurrentNavigation: () => currentNavigation,
     getInflightActions: () => inflightActions,
+    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;
-}