@rangojs/router 0.0.0-experimental.3 → 0.0.0-experimental.30

package/src/browser/action-coordinator.ts

@@ -0,0 +1,97 @@
+import {
+  classifyActionResponse,
+  type ActionScenario,
+} from "./action-response-classifier.js";
+import type { ActionEntry } from "./event-controller.js";
+
+/**
+ * Plain data inputs for classifying a post-reconciliation action outcome.
+ * No browser objects or controller references — all values are snapshots.
+ */
+export interface ActionOutcomeInput {
+  /** This action's unique instance ID */
+  handleId: string;
+  /** All in-flight action entries (snapshot from event controller) */
+  inflightActions: Map<string, ActionEntry>;
+  /** Whether any concurrent actions occurred (controller-level shared flag) */
+  hadAnyConcurrentActions: boolean;
+  /** Segments revalidated by concurrent actions (from tracking set) */
+  revalidatedSegments: Set<string>;
+  /** window.location.pathname captured at action start */
+  actionStartPathname: string;
+  /** window.location.pathname at classification time */
+  currentPathname: string;
+  /** window.history.state?.key captured at action start */
+  actionStartLocationKey: string | undefined;
+  /** window.history.state?.key at classification time */
+  currentLocationKey: string | undefined;
+  /** Number of segments after reconciliation */
+  reconciledSegmentCount: number;
+  /** Number of matched segment IDs from server */
+  matchedCount: number;
+  /** Current intercept source URL (null when not on intercept route) */
+  currentInterceptSource: string | null;
+}
+
+/**
+ * Compute consolidation segments from concurrent action state.
+ *
+ * Returns segment IDs that need re-fetching when concurrent actions
+ * have each revalidated different parts of the tree, or null if
+ * consolidation is not needed.
+ */
+function computeConsolidationSegments(
+  input: ActionOutcomeInput,
+): string[] | null {
+  if (!input.hadAnyConcurrentActions) return null;
+  if (input.revalidatedSegments.size === 0) return null;
+
+  // Can't consolidate while any action is still waiting for a server response
+  const stillFetchingCount = [...input.inflightActions.values()].filter(
+    (a) => a.phase === "fetching",
+  ).length;
+  if (stillFetchingCount > 0) return null;
+
+  return Array.from(input.revalidatedSegments);
+}
+
+/**
+ * Count other actions still in "fetching" phase (excluding this handle).
+ */
+function countOtherFetchingActions(input: ActionOutcomeInput): number {
+  let count = 0;
+  for (const [, a] of input.inflightActions) {
+    if (a.phase === "fetching" && a.id !== input.handleId) {
+      count++;
+    }
+  }
+  return count;
+}
+
+/**
+ * Classify a post-reconciliation action outcome into one of 5 scenarios.
+ *
+ * This is the single entry point for post-action decision logic.
+ * It gathers consolidation and concurrency data from the plain inputs,
+ * then delegates to the pure classifyActionResponse function.
+ *
+ * The server-action-bridge calls this after reconciliation to decide
+ * whether to render, skip, consolidate, or refetch.
+ */
+export function classifyActionOutcome(
+  input: ActionOutcomeInput,
+): ActionScenario {
+  return classifyActionResponse({
+    actionStartPathname: input.actionStartPathname,
+    currentPathname: input.currentPathname,
+    actionStartLocationKey: input.actionStartLocationKey,
+    currentLocationKey: input.currentLocationKey,
+    reconciledSegmentCount: input.reconciledSegmentCount,
+    matchedCount: input.matchedCount,
+    currentInterceptSource: input.currentInterceptSource,
+    consolidationSegments: computeConsolidationSegments(input),
+    otherFetchingActionCount: countOtherFetchingActions(input),
+  });
+}
+
+export type { ActionScenario };

package/src/browser/action-response-classifier.ts

@@ -0,0 +1,99 @@
+/**
+ * Discriminated union of post-reconciliation action response scenarios.
+ *
+ * Error and full-update-unsupported are handled inline in the bridge
+ * before reconciliation. This classifier only runs for partial responses
+ * that have been successfully reconciled.
+ */
+export type ActionScenario =
+  | {
+      type: "navigated-away";
+      historyKeyChanged: boolean;
+      onInterceptRoute: boolean;
+    }
+  | { type: "hmr-missing" }
+  | { type: "consolidation-needed"; segmentIds: string[] }
+  | { type: "concurrent-skip"; otherFetchingCount: number }
+  | { type: "normal" };
+
+/**
+ * Pure data inputs for classifying a partial action response.
+ * All values come from the bridge but no browser APIs or side effects.
+ */
+export interface ClassifierInput {
+  /** window.location.pathname captured at action start */
+  actionStartPathname: string;
+  /** window.location.pathname at classification time */
+  currentPathname: string;
+  /** window.history.state?.key captured at action start */
+  actionStartLocationKey: string | undefined;
+  /** window.history.state?.key at classification time */
+  currentLocationKey: string | undefined;
+  /** Number of segments after reconciliation */
+  reconciledSegmentCount: number;
+  /** Number of matched segment IDs from server */
+  matchedCount: number;
+  /** Segment IDs needing consolidation (from concurrent action tracking) */
+  consolidationSegments: string[] | null;
+  /** Number of other actions still in "fetching" phase */
+  otherFetchingActionCount: number;
+  /** Current intercept source URL (null when not on intercept route) */
+  currentInterceptSource: string | null;
+}
+
+/**
+ * Classify a partial action response into one of 5 post-reconciliation
+ * scenarios.
+ *
+ * Called after error and full-update cases are handled inline by the bridge.
+ * The classification order matches the priority chain:
+ * 1. User navigated away during action
+ * 2. HMR missing segments (fewer reconciled than matched)
+ * 3. Consolidation needed (concurrent actions finished)
+ * 4. Concurrent skip (other actions still fetching)
+ * 5. Normal (single action, no issues)
+ *
+ * This is a pure function with no side effects - the bridge handles
+ * all UI updates, store mutations, and network requests based on the
+ * returned scenario.
+ */
+export function classifyActionResponse(input: ClassifierInput): ActionScenario {
+  // Check if user navigated away during the action
+  const userNavigatedAway =
+    input.currentPathname !== input.actionStartPathname ||
+    input.currentLocationKey !== input.actionStartLocationKey;
+
+  if (userNavigatedAway) {
+    const historyKeyChanged =
+      input.currentLocationKey !== input.actionStartLocationKey;
+    return {
+      type: "navigated-away",
+      historyKeyChanged,
+      onInterceptRoute: input.currentInterceptSource !== null,
+    };
+  }
+
+  // HMR resilience: segments missing after reconciliation
+  if (input.reconciledSegmentCount < input.matchedCount) {
+    return { type: "hmr-missing" };
+  }
+
+  // Consolidation needed for concurrent actions
+  if (input.consolidationSegments && input.consolidationSegments.length > 0) {
+    return {
+      type: "consolidation-needed",
+      segmentIds: input.consolidationSegments,
+    };
+  }
+
+  // Other actions still fetching - skip UI update
+  if (input.otherFetchingActionCount > 0) {
+    return {
+      type: "concurrent-skip",
+      otherFetchingCount: input.otherFetchingActionCount,
+    };
+  }
+
+  // Normal single-action completion
+  return { type: "normal" };
+}

package/src/browser/event-controller.ts

@@ -8,7 +8,9 @@ import type {
   ResolvedSegment,
   RscMetadata,
   HandleData,
+  StreamingToken,
 } from "./types.js";
+import { filterSegmentOrder } from "./react/filter-segment-order.js";
 
 // Polyfill Symbol.dispose for Safari and older browsers
 if (typeof Symbol.dispose === "undefined") {
@@ -40,7 +42,7 @@ export interface NavigationEntry {
   abort: AbortController;
   phase: NavigationPhase;
   startedAt: number;
-  options?: NavigateOptions;
+  options?: NavigateOptions & { skipLoadingState?: boolean };
 }
 
 /**
@@ -116,15 +118,6 @@ export interface HandleState {
   segmentOrder: string[];
 }
 
-/**
- * Token for tracking an active stream
- * Call end() when the stream completes
- */
-export interface StreamingToken {
-  /** End this streaming operation */
-  end(): void;
-}
-
 /**
  * Result from starting a navigation
  * Implements Disposable for use with `using` keyword
@@ -165,8 +158,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,7 +169,10 @@ 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
@@ -186,6 +182,7 @@ export interface EventController {
   // 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,7 +191,7 @@ export interface EventController {
   subscribe(listener: StateListener): () => void;
   subscribeToAction(
     actionId: string,
-    listener: ActionStateListener
+    listener: ActionStateListener,
   ): () => void;
   subscribeToHandles(listener: HandleListener): () => void;
 
@@ -202,13 +199,19 @@ export interface EventController {
   setHandleData(
     data: HandleData,
     matched?: string[],
-    isPartial?: boolean
+    isPartial?: boolean,
   ): void;
   getHandleState(): HandleState;
 
+  // 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;
 }
 
 // ============================================================================
@@ -230,7 +233,10 @@ 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;
@@ -261,7 +267,7 @@ export interface EventControllerConfig {
  * Actions use mergeMap semantics (all run concurrently, consolidate at end).
  */
 export function createEventController(
-  config?: EventControllerConfig
+  config?: EventControllerConfig,
 ): EventController {
   // ========================================================================
   // Source of Truth
@@ -293,6 +299,9 @@ export function createEventController(
   let handleData: HandleData = {};
   let handleSegmentOrder: string[] = [];
 
+  // Merged route params from current match
+  let routeParams: Record<string, string> = {};
+
   // ========================================================================
   // Listeners
   // ========================================================================
@@ -334,7 +343,7 @@ export function createEventController(
             listeners.forEach((listener) => listener(state));
           }
         }
-      }, 0)
+      }, 0),
     );
   }
 
@@ -367,9 +376,12 @@ export function createEventController(
       }));
 
     // State: loading if navigation OR actions are in progress
+    // Background revalidations (skipLoadingState) don't affect visible state
     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";
@@ -378,8 +390,13 @@ export function createEventController(
       state,
       isStreaming,
       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,
     };
   }
@@ -388,12 +405,16 @@ export function createEventController(
     // 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")
+      .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")
+      .filter(
+        (a) => matchesActionId(actionId, a.actionId) && a.phase === "settling",
+      )
       .sort((a, b) => b.startedAt - a.startedAt)[0];
 
     const entry = activeEntry || settlingEntry;
@@ -431,7 +452,7 @@ export function createEventController(
 
   function startNavigation(
     url: string,
-    options?: NavigateOptions
+    options?: NavigateOptions & { skipLoadingState?: boolean },
   ): NavigationHandle {
     // Cancel existing navigation (switchMap semantics)
     if (currentNavigation) {
@@ -463,6 +484,7 @@ export function createEventController(
 
       startStreaming(): StreamingToken {
         let ended = false;
+        entry.phase = "streaming";
         activeStreamCount++;
         notify();
 
@@ -650,24 +672,8 @@ export function createEventController(
         // If streaming is in progress, tryFinalize() will be called when streaming ends
       },
 
-      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;
-
-        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() {
@@ -702,16 +708,26 @@ 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();
     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.
+    for (const [subscriptionId, listeners] of actionListeners) {
+      const state = getActionState(subscriptionId);
+      listeners.forEach((listener) => listener(state));
     }
   }
 
@@ -719,22 +735,10 @@ export function createEventController(
   // 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,
   ): void {
     const newSegmentOrder = filterSegmentOrder(matched ?? []);
 
@@ -783,7 +787,7 @@ export function createEventController(
 
   function subscribeToAction(
     actionId: string,
-    listener: ActionStateListener
+    listener: ActionStateListener,
   ): () => void {
     let listeners = actionListeners.get(actionId);
     if (!listeners) {
@@ -805,6 +809,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,12 +838,17 @@ export function createEventController(
     // State
     getState,
     getActionState,
+    getLocation: () => location,
     setLocation,
 
     // Handles
     setHandleData,
     getHandleState,
 
+    // Params
+    setParams,
+    getParams,
+
     // Subscriptions
     subscribe,
     subscribeToAction,
@@ -835,6 +857,7 @@ export function createEventController(
     // Direct access
     getCurrentNavigation: () => currentNavigation,
     getInflightActions: () => inflightActions,
+    hadAnyConcurrentActions: () => hadAnyConcurrentActions,
   };
 }
 
@@ -848,7 +871,7 @@ let controllerInstance: EventController | null = null;
  * Initialize the global event controller
  */
 export function initEventController(
-  config?: EventControllerConfig
+  config?: EventControllerConfig,
 ): EventController {
   if (!controllerInstance) {
     controllerInstance = createEventController(config);
@@ -862,7 +885,7 @@ export function initEventController(
 export function getEventController(): EventController {
   if (!controllerInstance) {
     throw new Error(
-      "Event controller not initialized. Call initEventController first."
+      "Event controller not initialized. Call initEventController first.",
     );
   }
   return controllerInstance;

package/src/browser/history-state.ts

@@ -0,0 +1,80 @@
+import {
+  isLocationStateEntry,
+  resolveLocationStateEntries,
+} from "./react/location-state-shared.js";
+
+/**
+ * Check if state is from typed LocationStateEntry[] (has __rsc_ls_ keys)
+ */
+function isTypedLocationState(
+  state: unknown,
+): state is Record<string, unknown> {
+  if (state === null || typeof state !== "object") return false;
+  return Object.keys(state).some((key) => key.startsWith("__rsc_ls_"));
+}
+
+/**
+ * Resolve navigation state - handles both LocationStateEntry[] and plain formats
+ */
+export function resolveNavigationState(state: unknown): unknown {
+  if (
+    Array.isArray(state) &&
+    state.length > 0 &&
+    isLocationStateEntry(state[0])
+  ) {
+    return resolveLocationStateEntries(state);
+  }
+  return state;
+}
+
+/**
+ * Build history state object from user state
+ * - Typed state: spread directly into history.state
+ * - Plain state: store in history.state.state
+ */
+export function buildHistoryState(
+  userState: unknown,
+  routerState?: { intercept?: boolean; sourceUrl?: string },
+  serverState?: Record<string, unknown>,
+): Record<string, unknown> | null {
+  const result: Record<string, unknown> = {};
+
+  if (routerState?.intercept) {
+    result.intercept = true;
+    if (routerState.sourceUrl) {
+      result.sourceUrl = routerState.sourceUrl;
+    }
+  }
+
+  if (userState !== undefined) {
+    if (isTypedLocationState(userState)) {
+      Object.assign(result, userState);
+    } else {
+      result.state = userState;
+    }
+  }
+
+  if (serverState) {
+    Object.assign(result, serverState);
+  }
+
+  return Object.keys(result).length > 0 ? result : null;
+}
+
+/**
+ * Merge server-set location state into the current history entry.
+ * Replaces the current history state and dispatches notification event
+ * so useLocationState hooks re-read from history.state.
+ */
+export function mergeLocationState(
+  locationState: Record<string, unknown>,
+): void {
+  const merged = {
+    ...window.history.state,
+    ...locationState,
+  };
+  window.history.replaceState(merged, "", window.location.href);
+  if (Object.keys(locationState).some((k) => k.startsWith("__rsc_ls_"))) {
+    window.dispatchEvent(new Event("__rsc_locationstate"));
+  }
+}

package/src/browser/intercept-utils.ts

@@ -0,0 +1,52 @@
+import type { ResolvedSegment } from "./types.js";
+import type { SlotState } from "../types.js";
+
+/**
+ * Check if a segment is an intercept segment.
+ * Intercept segments have namespace starting with "intercept:" — both the
+ * parallel container (@modal) and its content children receive this namespace
+ * from intercept-resolution.ts. Regular parallel segments like @sidebar do not.
+ */
+export function isInterceptSegment(s: ResolvedSegment): boolean {
+  return s.namespace?.startsWith("intercept:") === true;
+}
+
+/**
+ * Split an array of segments into main and intercept groups.
+ * Intercept segments are separated for explicit injection into the render tree
+ * via the interceptSegments render option.
+ */
+export function splitInterceptSegments(segments: ResolvedSegment[]): {
+  main: ResolvedSegment[];
+  intercept: ResolvedSegment[];
+} {
+  const main: ResolvedSegment[] = [];
+  const intercept: ResolvedSegment[] = [];
+  for (const s of segments) {
+    if (isInterceptSegment(s)) {
+      intercept.push(s);
+    } else {
+      main.push(s);
+    }
+  }
+  return { main, intercept };
+}
+
+/**
+ * Check if any slot is currently active (has content to render).
+ * Active slots indicate an intercept response where a parallel segment
+ * (e.g., @modal) has matched and should be rendered.
+ */
+export function hasActiveIntercept(slots?: Record<string, SlotState>): boolean {
+  if (!slots) return false;
+  return Object.values(slots).some((slot) => slot.active);
+}
+
+/**
+ * Check if cached segments contain any intercept segments.
+ * Intercept caches shouldn't be used for cached SWR rendering since
+ * whether interception happens depends on the current page context.
+ */
+export function isInterceptOnlyCache(segments: ResolvedSegment[]): boolean {
+  return segments.some(isInterceptSegment);
+}