@rangojs/router 0.0.0-experimental.b9cb8739 → 0.0.0-experimental.bd6e11bc

package/src/browser/app-shell.ts

@@ -0,0 +1,52 @@
+import type { ComponentType, ReactNode } from "react";
+
+/**
+ * App-shell metadata: the set of per-router fields that describe the
+ * "envelope" around the current app's segment tree. These fields are set
+ * from the initial RSC payload and must be replaced atomically when the
+ * client navigates into a different router (app switch).
+ *
+ * Intentionally NOT part of the shell (all document-lifetime):
+ * - themeConfig / initialTheme: ThemeProvider is mounted above the segment
+ *   tree and must not remount on smooth transitions.
+ * - warmupEnabled: attached to the NavigationProvider's lifetime effect;
+ *   toggling it mid-session would tear down and restart idle listeners.
+ *   Also not serialized on every full-render path (e.g. the not-found
+ *   fallback), so carrying it here would be unreliable.
+ * - prefetchCacheTTL: the not-found full-render payload does not serialize
+ *   it, so a cross-app nav into a 404 would silently erase the setting.
+ *   Mutable shell fields must be serialized on EVERY full-render path,
+ *   otherwise absent fields are indistinguishable from "new app has no
+ *   value" and the old app's value is dropped.
+ *
+ * A new document navigation (hard reload) applies these fields from the
+ * target app's initial payload.
+ */
+export interface AppShell {
+  /** Router identity. Used to namespace per-app client state (e.g. the
+   *  rango-state localStorage key) so sibling apps on the same origin
+   *  cannot observe each other's cache invalidations. */
+  routerId?: string;
+  rootLayout?: ComponentType<{ children: ReactNode }>;
+  basename?: string;
+  version?: string;
+}
+
+/**
+ * Mutable container for the active app shell. Read-through via `get()` so
+ * closures capture the ref, not the shell, and pick up updates at call time.
+ */
+export interface AppShellRef {
+  get(): AppShell;
+  update(next: AppShell): void;
+}
+
+export function createAppShellRef(initial: AppShell): AppShellRef {
+  let current = initial;
+  return {
+    get: () => current,
+    update: (next) => {
+      current = next;
+    },
+  };
+}

package/src/browser/app-version.ts

@@ -0,0 +1,14 @@
+/**
+ * Mutable app version — updated after HMR revalidation.
+ * Read by prefetch, navigation, and context code.
+ */
+
+let currentVersion: string | undefined;
+
+export function getAppVersion(): string | undefined {
+  return currentVersion;
+}
+
+export function setAppVersion(version: string | undefined): void {
+  currentVersion = version;
+}

package/src/browser/event-controller.ts

@@ -79,6 +79,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) */
@@ -111,11 +113,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[];
+  routeSegmentIds: string[];
 }
 
 /**
@@ -200,6 +215,14 @@ export interface EventController {
     data: HandleData,
     matched?: string[],
     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;
 
@@ -245,6 +268,20 @@ function matchesActionId(
   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.
+function makeDebouncedNotifier(listeners: Set<() => void>): () => void {
+  let timeout: ReturnType<typeof setTimeout> | null = null;
+  return () => {
+    if (timeout !== null) clearTimeout(timeout);
+    timeout = setTimeout(() => {
+      timeout = null;
+      listeners.forEach((listener) => listener());
+    }, 0);
+  };
+}
+
 // ============================================================================
 // Implementation
 // ============================================================================
@@ -298,6 +335,7 @@ export function createEventController(
   // 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> = {};
@@ -310,18 +348,7 @@ export function createEventController(
   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;
-
-  function notify() {
-    if (notifyTimeout !== null) {
-      clearTimeout(notifyTimeout);
-    }
-    notifyTimeout = setTimeout(() => {
-      notifyTimeout = null;
-      stateListeners.forEach((listener) => listener());
-    }, 0);
-  }
+  const notify = makeDebouncedNotifier(stateListeners);
 
   // Debounce per-action notifications
   const actionNotifyTimeouts = new Map<string, ReturnType<typeof setTimeout>>();
@@ -347,18 +374,7 @@ export function createEventController(
     );
   }
 
-  // Debounce handle notifications
-  let handleNotifyTimeout: ReturnType<typeof setTimeout> | null = null;
-
-  function notifyHandles() {
-    if (handleNotifyTimeout !== null) {
-      clearTimeout(handleNotifyTimeout);
-    }
-    handleNotifyTimeout = setTimeout(() => {
-      handleNotifyTimeout = null;
-      handleListeners.forEach((listener) => listener());
-    }, 0);
-  }
+  const notifyHandles = makeDebouncedNotifier(handleListeners);
 
   // ========================================================================
   // Derived State
@@ -389,6 +405,9 @@ export function createEventController(
     return {
       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.
       // Background revalidations (skipLoadingState) don't expose a pending URL.
@@ -402,22 +421,17 @@ export function createEventController(
   }
 
   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;
+    // 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) => {
+        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 };
@@ -605,6 +619,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,
@@ -641,35 +668,11 @@ export function createEventController(
       },
 
       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();
-        }
-        // If streaming is in progress, tryFinalize() will be called when streaming ends
+        settleWith({ type: "success", value: result });
       },
 
       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
+        settleWith({ type: "error", value: error });
       },
 
       getRevalidatedSegments(): Set<string> {
@@ -739,8 +742,15 @@ export function createEventController(
     data: HandleData,
     matched?: string[],
     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 = rawMatched.filter(
+      (id) => !id.includes(".@") && !/D\d+\./.test(id),
+    );
 
     if (isPartial && newSegmentOrder.length > 0) {
       // Partial update: merge new data with existing
@@ -752,10 +762,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];
           }
         }
@@ -765,6 +784,7 @@ export function createEventController(
       handleData = data;
     }
     handleSegmentOrder = newSegmentOrder;
+    routeSegmentIds = newRouteSegmentIds;
 
     notifyHandles();
   }
@@ -773,6 +793,7 @@ export function createEventController(
     return {
       data: handleData,
       segmentOrder: handleSegmentOrder,
+      routeSegmentIds,
     };
   }
 

package/src/browser/history-state.ts

@@ -61,6 +61,27 @@ export function buildHistoryState(
   return Object.keys(result).length > 0 ? result : null;
 }
 
+/**
+ * Stamp an `idx` on the next history entry's state and call push/replaceState.
+ * Push increments the current idx; replace keeps it. Initial entry idx is 0.
+ * Used by useRouter().back() to detect "first entry in this session" without
+ * relying on the Navigation API.
+ */
+export function pushHistoryWithIdx(
+  state: Record<string, unknown> | null,
+  url: string,
+  replace: boolean,
+): void {
+  const oldIdx = (window.history.state as { idx?: number } | null)?.idx ?? 0;
+  const newIdx = replace ? oldIdx : oldIdx + 1;
+  const finalState = { ...(state ?? {}), idx: newIdx };
+  if (replace) {
+    window.history.replaceState(finalState, "", url);
+  } else {
+    window.history.pushState(finalState, "", url);
+  }
+}
+
 /**
  * Merge server-set location state into the current history entry.
  * Replaces the current history state and dispatches notification event

package/src/browser/index.ts

@@ -1,9 +1,9 @@
 // ============================================================================
-// Browser Module - Browser entry point for RSC Router
+// Browser Module - Browser entry point for Rango
 // ============================================================================
 //
 // Usage:
-//   import { initBrowserApp, RSCRouter } from "rsc-router/browser";
+//   import { initBrowserApp, Rango } from "rsc-router/browser";
 //
 // For React components (Link, useNavigation, etc.):
 //   import { Link, useNavigation, useAction, href } from "rsc-router/client";
@@ -13,6 +13,6 @@
 // Browser app initialization
 export {
   initBrowserApp,
-  RSCRouter,
+  Rango,
   type InitBrowserAppOptions,
 } from "./rsc-router.js";

package/src/browser/navigation-bridge.ts

@@ -4,13 +4,16 @@ import type {
   NavigateOptionsInternal,
   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 * as React from "react";
 import { startTransition } from "react";
 import {
   createNavigationTransaction,
   resolveNavigationState,
 } from "./navigation-transaction.js";
-import { buildHistoryState } from "./history-state.js";
+import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
 import {
   handleNavigationStart,
   handleNavigationEnd,
@@ -47,8 +50,13 @@ export { createNavigationTransaction };
  */
 export interface NavigationBridgeConfigWithController extends NavigationBridgeConfig {
   eventController: EventController;
-  /** RSC version from initial payload metadata */
+  /** RSC version from initial payload metadata (fallback when appShellRef is not provided) */
   version?: string;
+  /**
+   * Live app-shell ref. When supplied, the bridge reads version/basename
+   * from this ref so cross-app navigations propagate correctly.
+   */
+  appShellRef?: AppShellRef;
 }
 
 /**
@@ -67,8 +75,45 @@ export interface NavigationBridgeConfigWithController extends NavigationBridgeCo
 export function createNavigationBridge(
   config: NavigationBridgeConfigWithController,
 ): NavigationBridge {
-  const { store, client, eventController, onUpdate, renderSegments, version } =
-    config;
+  const {
+    store,
+    client,
+    eventController,
+    onUpdate,
+    renderSegments,
+    appShellRef,
+  } = 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({
@@ -76,7 +121,8 @@ export function createNavigationBridge(
     client,
     onUpdate,
     renderSegments,
-    version,
+    getVersion: () => version,
+    applyAppShell,
   });
 
   return {
@@ -158,11 +204,7 @@ export function createNavigationBridge(
           },
           {},
         );
-        if (options.replace) {
-          window.history.replaceState(historyState, "", url);
-        } else {
-          window.history.pushState(historyState, "", url);
-        }
+        pushHistoryWithIdx(historyState, url, options?.replace ?? false);
 
         // Ensure new history entry has a scroll restoration key
         ensureHistoryKey();
@@ -260,18 +302,24 @@ export function createNavigationBridge(
       // 2. routes that CAN be intercepted - we don't know if this navigation will intercept
       // 3. when leaving intercept - we need fresh non-intercept segments from server
       // 4. redirect-with-state - force re-render so hooks read fresh state
+      // 5. stale cache - server action invalidated it, need fresh data with loading state
       const hasUsableCache =
         cachedSegments &&
         cachedSegments.length > 0 &&
         !isInterceptOnlyCache(cachedSegments) &&
         !hasInterceptCache &&
         !isLeavingIntercept &&
+        !cached?.stale &&
         !options?._skipCache;
 
+      // Forward navigations always await fetchPartialUpdate before rendering,
+      // so useNavigation should always report "loading". skipLoadingState is
+      // only used for popstate background revalidation (line ~526) where
+      // cached content renders instantly without a network wait.
       const tx = createNavigationTransaction(store, eventController, url, {
         ...options,
         state: resolvedState,
-        skipLoadingState: hasUsableCache,
+        skipLoadingState: false,
       });
 
       // REVALIDATE: Fetch fresh data from server
@@ -411,6 +459,15 @@ export function createNavigationBridge(
         eventController.abortAllActions();
       }
 
+      // Popstate that exits an intercept to a non-intercept destination. The
+      // fallback fetch path below needs `leave-intercept` mode so it filters
+      // the cached @modal segment from the request and forces a re-render —
+      // otherwise a cache-miss popstate whose server response has an empty
+      // diff hits the "no changes" branch in partial-update and the modal
+      // stays on screen.
+      const isLeavingIntercept =
+        !isIntercept && currentInterceptSource !== null;
+
       // Compute history key from URL (with intercept suffix if applicable)
       const historyKey = generateHistoryKey(url, { intercept: isIntercept });
 
@@ -447,6 +504,12 @@ export function createNavigationBridge(
         store.setCurrentUrl(url);
         store.setPath(new URL(url).pathname);
 
+        // Restore router identity from cache so subsequent navigations
+        // don't falsely detect an app switch.
+        if (cached?.routerId) {
+          store.setRouterId?.(cached.routerId);
+        }
+
         // Render from cache - force await to skip loading fallbacks
         try {
           const root = await renderSegments(cachedSegments, {
@@ -472,8 +535,16 @@ export function createNavigationBridge(
               cachedHandleData,
               params: cachedParams,
             },
+            scroll: { restore: true, isStreaming },
           };
-          const hasTransition = cachedSegments.some((s) => s.transition);
+          // Intercept-driven popstate (entering OR leaving an intercept) only
+          // mutates the parallel slot; the main outlet shows the same content.
+          // Skip startViewTransition in those cases — same rationale as the
+          // intercept guard in partial-update.ts's hasTransition computation.
+          const hasTransition =
+            !isIntercept &&
+            !isLeavingIntercept &&
+            cachedSegments.some((s) => s.transition);
           if (hasTransition) {
             startTransition(() => {
               if (addTransitionType) {
@@ -485,9 +556,6 @@ export function createNavigationBridge(
             onUpdate(popstateUpdate);
           }
 
-          // Restore scroll position for back/forward navigation
-          handleNavigationEnd({ restore: true, isStreaming });
-
           // SWR: If stale, trigger background revalidation
           if (isStale) {
             debugLog("[Browser] Cache is stale, background revalidating...");
@@ -557,7 +625,11 @@ export function createNavigationBridge(
             intercept: isIntercept,
             interceptSourceUrl,
           }),
-          isIntercept ? { type: "navigate", interceptSourceUrl } : undefined,
+          isIntercept
+            ? { type: "navigate", interceptSourceUrl }
+            : isLeavingIntercept
+              ? { type: "leave-intercept" }
+              : undefined,
         );
         // Restore scroll position after fetch completes
         handleNavigationEnd({ restore: true, isStreaming });
@@ -634,6 +706,20 @@ export function createNavigationBridge(
         window.removeEventListener("pageshow", handlePageShow);
       };
     },
+
+    getVersion(): string | undefined {
+      return version;
+    },
+
+    updateVersion(newVersion: string): void {
+      version = newVersion;
+      setAppVersion(newVersion);
+      store.clearHistoryCache();
+    },
+
+    updateAppShell(next: AppShell): void {
+      applyAppShell(next);
+    },
   };
 }