@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.204030a9

package/src/browser/navigation-bridge.ts

@@ -1,442 +1,48 @@
 import type {
   NavigationBridge,
   NavigationBridgeConfig,
-  NavigateOptions,
-  NavigationStore,
+  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 {
-  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 legacy formats
- */
-function resolveNavigationState(state: unknown): unknown {
-  // Check if it's an array of LocationStateEntry
-  if (
-    Array.isArray(state) &&
-    state.length > 0 &&
-    isLocationStateEntry(state[0])
-  ) {
-    return resolveLocationStateEntries(state);
-  }
-  // Return as-is for legacy formats
-  return state;
-}
-
-/**
- * Build history state object from user state
- * - Typed state: spread directly into history.state
- * - Legacy state: store in history.state.state
- */
-function buildHistoryState(
-  userState: unknown,
-  routerState?: { intercept?: boolean; sourceUrl?: string }
-): Record<string, unknown> | null {
-  const result: Record<string, unknown> = {};
-
-  // Add router internal state
-  if (routerState?.intercept) {
-    result.intercept = true;
-    if (routerState.sourceUrl) {
-      result.sourceUrl = routerState.sourceUrl;
-    }
-  }
+  createNavigationTransaction,
+  resolveNavigationState,
+} from "./navigation-transaction.js";
+import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
+import {
+  handleNavigationStart,
+  handleNavigationEnd,
+  ensureHistoryKey,
+} from "./scroll-restoration.js";
 
-  // Add user state
-  if (userState !== undefined) {
-    if (isTypedLocationState(userState)) {
-      // Typed state: spread directly
-      Object.assign(result, userState);
-    } else {
-      // Legacy state: store in .state
-      result.state = userState;
-    }
-  }
+// addTransitionType is only available in React experimental
+const addTransitionType: ((type: string) => void) | undefined =
+  "addTransitionType" in React ? (React as any).addTransitionType : undefined;
 
-  return Object.keys(result).length > 0 ? result : null;
-}
 import { setupLinkInterception } from "./link-interceptor.js";
 import { createPartialUpdater } from "./partial-update.js";
 import { generateHistoryKey } from "./navigation-store.js";
+import type { EventController } from "./event-controller.js";
+import { isInterceptOnlyCache } from "./intercept-utils.js";
 import {
-  handleNavigationStart,
-  handleNavigationEnd,
-  ensureHistoryKey,
-} from "./scroll-restoration.js";
-import type { EventController, NavigationHandle } from "./event-controller.js";
-import { NetworkError, isNetworkError } from "../errors.js";
-import { NetworkErrorThrower } from "../network-error-thrower.js";
-import { createElement, startTransition } from "react";
+  toNetworkError,
+  emitNetworkError,
+  isBackgroundSuppressible,
+} from "./network-error-handler.js";
+import { debugLog } from "./logging.js";
+import { ServerRedirect } from "../errors.js";
+import { validateRedirectOrigin } from "./validate-redirect-origin.js";
 
 // Polyfill Symbol.dispose for Safari and older browsers
 if (typeof Symbol.dispose === "undefined") {
   (Symbol as any).dispose = Symbol("Symbol.dispose");
 }
 
-/**
- * Check if a segment is an intercept segment
- * Intercept segments have namespace starting with "intercept:" or ID containing .@
- */
-function isInterceptSegment(s: ResolvedSegment): boolean {
-  return (
-    s.namespace?.startsWith("intercept:") ||
-    (s.type === "parallel" && s.id.includes(".@"))
-  );
-}
-
-/**
- * Check if cached segments are intercept-only (no main route segments)
- * Intercept responses shouldn't be used for optimistic rendering since
- * whether interception happens depends on the current page context
- */
-function isInterceptOnlyCache(segments: ResolvedSegment[]): boolean {
-  return segments.some(isInterceptSegment);
-}
-
-/**
- * Options for committing a navigation transaction
- */
-interface CommitOptions {
-  url: string;
-  segmentIds: string[];
-  segments: ResolvedSegment[];
-  replace?: boolean;
-  scroll?: boolean;
-  /** User-provided state to store in history.state */
-  state?: unknown;
-  /** If true, only update store without changing URL/history (for server actions) */
-  storeOnly?: boolean;
-  /** If true, this is an intercept route - store in history.state for popstate handling */
-  intercept?: boolean;
-  /** Source URL where the intercept was triggered from (stored in history.state) */
-  interceptSourceUrl?: string;
-  /** If true, only update cache without touching store or history (for background stale revalidation) */
-  cacheOnly?: boolean;
-}
-
-/**
- * Options that can override the pre-configured commit settings
- */
-interface BoundCommitOverrides {
-  /** Override scroll behavior (e.g., disable for intercepts) */
-  scroll?: boolean;
-  /** Override replace behavior (e.g., force replace for intercepts) */
-  replace?: boolean;
-  /** Override user-provided state */
-  state?: unknown;
-  /** Mark this as an intercept route */
-  intercept?: boolean;
-  /** Source URL where intercept was triggered from */
-  interceptSourceUrl?: string;
-  /** If true, only update cache (for stale revalidation) */
-  cacheOnly?: boolean;
-}
-
-/**
- * Token for tracking an active stream - call end() when stream completes
- */
-export interface StreamingToken {
-  end(): void;
-}
-
-/**
- * Bound transaction with pre-configured commit options (without segmentIds/segments)
- */
-export interface BoundTransaction {
-  readonly currentUrl: string;
-  /** Start streaming and get a token to end it when the stream completes */
-  startStreaming(): StreamingToken;
-  commit(
-    segmentIds: string[],
-    segments: ResolvedSegment[],
-    overrides?: BoundCommitOverrides
-  ): void;
-}
-
-/**
- * Navigation transaction for managing state during navigation
- * Uses the event controller handle for lifecycle management
- */
-interface NavigationTransaction extends Disposable {
-  /** Optimistically commit from cache - instant render before revalidation */
-  optimisticCommit(options: CommitOptions): void;
-  /** Final commit with server data (or reconciliation after optimistic) */
-  commit(options: CommitOptions): void;
-  with(
-    options: Omit<CommitOptions, "segmentIds" | "segments">
-  ): BoundTransaction;
-  /** The navigation handle from the event controller */
-  handle: NavigationHandle;
-}
-
-/**
- * Creates a navigation transaction that coordinates with the event controller.
- * Handles loading state transitions and cleanup on completion/abort.
- *
- * Supports optimistic navigation: render from cache immediately,
- * then revalidate in background and reconcile if data changed.
- */
-function createNavigationTransaction(
-  store: NavigationStore,
-  eventController: EventController,
-  url: string,
-  options?: NavigateOptions & { skipLoadingState?: boolean }
-): NavigationTransaction {
-  let committed = false;
-  let optimisticallyCommitted = false;
-  let earlyStatePushed = false;
-  const currentUrl = window.location.href;
-
-  // Start navigation in event controller (this sets loading state)
-  const handle = eventController.startNavigation(url, options);
-
-  // If state is provided, push it to history immediately so loading UI can access it
-  // This enables "optimistic state" - showing product names in skeletons etc.
-  if (options?.state !== undefined && !options?.replace) {
-    const earlyHistoryState = buildHistoryState(options.state);
-    window.history.pushState(earlyHistoryState, "", url);
-    earlyStatePushed = true;
-  }
-
-  /**
-   * Optimistically commit from cache - renders immediately before revalidation
-   * Sets optimisticallyCommitted flag so final commit() knows to reconcile
-   */
-  function optimisticCommit(opts: CommitOptions): void {
-    optimisticallyCommitted = true;
-
-    const { url, segmentIds, segments, replace, scroll } = opts;
-    const parsedUrl = new URL(url, window.location.origin);
-
-    // Save current scroll position before navigating
-    handleNavigationStart();
-
-    // Update segment state
-    store.setSegmentIds(segmentIds);
-    store.setCurrentUrl(url);
-    store.setPath(parsedUrl.pathname);
-
-    // Generate history key from URL
-    const historyKey = generateHistoryKey(url);
-    store.setHistoryKey(historyKey);
-
-    // Cache segments with current handleData (will be overwritten by fresh data on final commit)
-    const currentHandleData = eventController.getHandleState().data;
-    store.cacheSegmentsForHistory(historyKey, segments, currentHandleData);
-
-    // Build history state with user state if provided
-    const historyState = buildHistoryState(opts.state);
-
-    // Update browser URL
-    // Use replaceState if we already pushed early (for optimistic state access)
-    if (replace || earlyStatePushed) {
-      window.history.replaceState(historyState, "", url);
-    } else {
-      window.history.pushState(historyState, "", url);
-    }
-
-    // Ensure new history entry has a scroll restoration key
-    ensureHistoryKey();
-
-    // Complete the navigation in event controller (sets idle state)
-    handle.complete(parsedUrl);
-
-    // Handle scroll after navigation
-    handleNavigationEnd({ scroll });
-
-    console.log(
-      "[Browser] Optimistic commit from cache, historyKey:",
-      historyKey
-    );
-  }
-
-  /**
-   * Commit the navigation - updates store and URL atomically
-   * If optimisticCommit was called, this becomes a reconciliation
-   */
-  function commit(opts: CommitOptions): void {
-    committed = true;
-
-    // If optimistic commit already done, adjust options for reconciliation
-    const isReconciliation = optimisticallyCommitted;
-    const {
-      url,
-      segmentIds,
-      segments,
-      storeOnly,
-      intercept,
-      interceptSourceUrl,
-      cacheOnly,
-    } = opts;
-    // For reconciliation: always replace (URL already pushed), no scroll
-    const replace = isReconciliation ? true : opts.replace;
-    const scroll = isReconciliation ? false : opts.scroll;
-
-    const parsedUrl = new URL(url, window.location.origin);
-
-    // Generate history key from URL (with intercept suffix for separate caching)
-    const historyKey = generateHistoryKey(url, { intercept });
-
-    // For cache-only commits (stale revalidation), only update cache and return
-    // Don't touch store state or history - user may have navigated elsewhere
-    if (cacheOnly) {
-      const currentHandleData = eventController.getHandleState().data;
-      store.cacheSegmentsForHistory(historyKey, segments, currentHandleData);
-      console.log("[Browser] Cache-only commit, historyKey:", historyKey);
-      return;
-    }
-
-    // Save current scroll position before navigating (only for non-reconciliation)
-    if (!isReconciliation) {
-      handleNavigationStart();
-    }
-
-    // Update segment state atomically
-    store.setSegmentIds(segmentIds);
-    store.setCurrentUrl(url);
-    store.setPath(parsedUrl.pathname);
-
-    store.setHistoryKey(historyKey);
-
-    // Cache segments with current handleData for this history entry (fresh data overwrites optimistic)
-    const currentHandleData = eventController.getHandleState().data;
-    store.cacheSegmentsForHistory(historyKey, segments, currentHandleData);
-
-    // For server actions, skip URL/history updates but still complete navigation
-    if (storeOnly) {
-      console.log("[Browser] Store updated (action)");
-      // Complete navigation to clear loading state
-      handle.complete(parsedUrl);
-      return;
-    }
-
-    // Build history state - include user state and intercept info for popstate handling
-    const historyState = buildHistoryState(opts.state, {
-      intercept,
-      sourceUrl: interceptSourceUrl,
-    });
-
-    // Update browser URL (skip if reconciliation - already done in optimisticCommit)
-    if (!isReconciliation) {
-      // Use replaceState if we already pushed early (for optimistic state access) or replace requested
-      if (replace || earlyStatePushed) {
-        window.history.replaceState(historyState, "", url);
-      } else {
-        window.history.pushState(historyState, "", url);
-      }
-      // Ensure new history entry has a scroll restoration key
-      ensureHistoryKey();
-    }
-
-    // Complete the navigation in event controller (sets idle state, updates location)
-    handle.complete(parsedUrl);
-
-    // Handle scroll after navigation (skip if reconciliation)
-    if (!isReconciliation) {
-      handleNavigationEnd({ scroll });
-    }
-
-    if (isReconciliation) {
-      console.log("[Browser] Reconciliation commit, historyKey:", historyKey);
-    } else {
-      console.log(
-        "[Browser] Navigation committed, historyKey:",
-        historyKey,
-        intercept ? "(intercept)" : ""
-      );
-    }
-  }
-
-  return {
-    handle,
-    optimisticCommit,
-    commit,
-
-    /**
-     * Create a bound transaction with pre-configured URL options
-     * segmentIds and segments provided at commit time (after they're resolved)
-     */
-    with(
-      opts: Omit<CommitOptions, "segmentIds" | "segments">
-    ): BoundTransaction {
-      return {
-        get currentUrl() {
-          return currentUrl;
-        },
-        startStreaming() {
-          return handle.startStreaming();
-        },
-        commit: (
-          segmentIds: string[],
-          segments: ResolvedSegment[],
-          overrides?: BoundCommitOverrides
-        ) => {
-          // Allow overrides to disable scroll (e.g., for intercepts)
-          const finalScroll =
-            overrides?.scroll !== undefined ? overrides.scroll : opts.scroll;
-          // Allow overrides to force replace (e.g., for intercepts)
-          const finalReplace =
-            overrides?.replace !== undefined ? overrides.replace : opts.replace;
-          // Intercept info: overrides take precedence, fallback to opts
-          const intercept =
-            overrides?.intercept !== undefined
-              ? overrides.intercept
-              : opts.intercept;
-          const interceptSourceUrl =
-            overrides?.interceptSourceUrl !== undefined
-              ? overrides.interceptSourceUrl
-              : opts.interceptSourceUrl;
-          // Cache-only mode: overrides take precedence, fallback to opts
-          const cacheOnly =
-            overrides?.cacheOnly !== undefined
-              ? overrides.cacheOnly
-              : opts.cacheOnly;
-          // User state: overrides take precedence, fallback to opts
-          const state =
-            overrides?.state !== undefined ? overrides.state : opts.state;
-          commit({
-            ...opts,
-            segmentIds,
-            segments,
-            scroll: finalScroll,
-            replace: finalReplace,
-            state,
-            intercept,
-            interceptSourceUrl,
-            cacheOnly,
-          });
-        },
-      };
-    },
-
-    [Symbol.dispose]() {
-      // If aborted, another navigation took over - don't touch state
-      if (handle.signal.aborted) return;
-
-      // If not committed (and not optimistically committed), the handle's dispose
-      // will reset state to idle via the event controller
-      if (!committed && !optimisticallyCommitted) {
-        handle[Symbol.dispose]();
-        // The NavigationHandle's [Symbol.dispose] handles this
-      }
-    },
-  };
-}
-
-// Export for use by server-action-bridge
 export { createNavigationTransaction };
 
 /**
@@ -444,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;
 }
 
 /**
@@ -462,9 +73,47 @@ export interface NavigationBridgeConfigWithController extends NavigationBridgeCo
  * @returns NavigationBridge instance
  */
 export function createNavigationBridge(
-  config: NavigationBridgeConfigWithController
+  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({
@@ -472,29 +121,143 @@ export function createNavigationBridge(
     client,
     onUpdate,
     renderSegments,
-    version,
+    getVersion: () => version,
+    applyAppShell,
   });
 
   return {
     /**
      * Navigate to a URL
-     * Uses optimistic rendering from cache when available (SWR pattern)
+     * Uses cached segments for SWR revalidation when available
      */
-    async navigate(url: string, options?: NavigateOptions): Promise<void> {
+    async navigate(
+      url: string,
+      options?: NavigateOptionsInternal,
+    ): Promise<void> {
       // Resolve LocationStateEntry[] to flat object if needed
       const resolvedState =
         options?.state !== undefined
           ? resolveNavigationState(options.state)
           : undefined;
 
+      // Cross-origin URLs are not handled by SPA navigation.
+      // Fall back to a full browser navigation for http/https only.
+      let targetUrl: URL;
+      try {
+        targetUrl = new URL(url, window.location.origin);
+      } catch {
+        console.warn(`[rango] navigate() ignored: malformed URL "${url}"`);
+        return;
+      }
+      if (targetUrl.origin !== window.location.origin) {
+        if (targetUrl.protocol !== "http:" && targetUrl.protocol !== "https:") {
+          console.error(
+            `[rango] navigate() blocked: unsupported scheme "${targetUrl.protocol}"`,
+          );
+          return;
+        }
+        window.location.href = targetUrl.href;
+        return;
+      }
+
+      // Shallow navigation: skip RSC fetch when revalidate is false
+      // and the pathname hasn't changed (search param / hash only change).
+      if (
+        options?.revalidate === false &&
+        targetUrl.pathname === new URL(window.location.href).pathname
+      ) {
+        // Preserve intercept context from the current history entry so that
+        // popstate uses the correct cache key (:intercept suffix) and restores
+        // the right full-page vs modal semantics.
+        const currentHistoryState = window.history.state;
+        const isIntercept = currentHistoryState?.intercept === true;
+        const interceptSourceUrl = isIntercept
+          ? currentHistoryState?.sourceUrl
+          : undefined;
+
+        const historyKey = generateHistoryKey(url, { intercept: isIntercept });
+
+        // Copy current segments to the new history key so back/forward restores instantly
+        const currentKey = store.getHistoryKey();
+        const currentCache = store.getCachedSegments(currentKey);
+        if (currentCache?.segments) {
+          const currentHandleData = eventController.getHandleState().data;
+          store.cacheSegmentsForHistory(
+            historyKey,
+            currentCache.segments,
+            currentHandleData,
+          );
+        }
+
+        // Save current scroll position before changing URL
+        handleNavigationStart();
+
+        // Snapshot old state before pushState/replaceState overwrites it
+        const oldState = window.history.state;
+
+        // Update browser URL (carry intercept context into history state)
+        const historyState = buildHistoryState(
+          resolvedState,
+          {
+            intercept: isIntercept || undefined,
+            sourceUrl: interceptSourceUrl,
+          },
+          {},
+        );
+        pushHistoryWithIdx(historyState, url, options?.replace ?? false);
+
+        // Ensure new history entry has a scroll restoration key
+        ensureHistoryKey();
+
+        // Notify useLocationState() hooks when state changes
+        const hasOldState =
+          oldState &&
+          typeof oldState === "object" &&
+          ("state" in oldState ||
+            Object.keys(oldState).some((k) => k.startsWith("__rsc_ls_")));
+        const hasNewState =
+          historyState &&
+          ("state" in historyState ||
+            Object.keys(historyState).some((k) => k.startsWith("__rsc_ls_")));
+        if (hasOldState || hasNewState) {
+          window.dispatchEvent(new Event("__rsc_locationstate"));
+        }
+
+        // Update store history key so future navigations reference the right cache
+        store.setHistoryKey(historyKey);
+        store.setCurrentUrl(url);
+
+        // Notify hooks — location updates, state stays idle
+        eventController.setLocation(targetUrl);
+
+        // Handle post-navigation scroll
+        handleNavigationEnd({ scroll: options.scroll });
+        return;
+      }
+
       // Only abort pending requests when navigating to a different route
       // Same-route navigation (e.g., /todos -> /todos) should not cancel in-flight actions
       const currentPath = new URL(window.location.href).pathname;
-      const targetPath = new URL(url, window.location.origin).pathname;
+      const targetPath = targetUrl.pathname;
       if (currentPath !== targetPath) {
         eventController.abortNavigation();
       }
 
+      // Check if we're "leaving intercept" - navigating from intercept to same URL without intercept
+      // This happens when clicking "View Full Details" in an intercept modal
+      const currentHistoryState = window.history.state;
+      const isCurrentlyIntercept = currentHistoryState?.intercept === true;
+      const isSamePathNavigation = currentPath === targetPath;
+      const isLeavingIntercept = isCurrentlyIntercept && isSamePathNavigation;
+
+      if (isLeavingIntercept) {
+        debugLog(
+          "[Browser] Leaving intercept - same URL navigation from intercept",
+        );
+        // Clear intercept source URL to ensure server doesn't treat this as intercept
+        store.setInterceptSourceUrl(null);
+      }
+
       // Before navigating away, update the source page's cache with the latest handleData.
       // This ensures the cache has correct handleData even if handles were streaming.
       const sourceHistoryKey = store.getHistoryKey();
@@ -504,7 +267,7 @@ export function createNavigationBridge(
         store.cacheSegmentsForHistory(
           sourceHistoryKey,
           sourceCached.segments,
-          currentHandleData
+          currentHandleData,
         );
       }
 
@@ -519,7 +282,7 @@ export function createNavigationBridge(
       const cachedHandleData = cached?.handleData;
       if (cachedSegments && sourceCached?.segments) {
         const sourceSegmentMap = new Map(
-          sourceCached.segments.map((s) => [s.id, s])
+          sourceCached.segments.map((s) => [s.id, s]),
         );
         cachedSegments = cachedSegments.map((targetSeg) => {
           const sourceSeg = sourceSegmentMap.get(targetSeg.id);
@@ -534,26 +297,40 @@ export function createNavigationBridge(
       const interceptHistoryKey = generateHistoryKey(url, { intercept: true });
       const hasInterceptCache = store.hasHistoryCache(interceptHistoryKey);
 
-      // Skip optimistic rendering for:
+      // Skip cached SWR for:
       // 1. intercept caches - interception depends on source page context
       // 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;
-
-      using tx = createNavigationTransaction(store, eventController, url, {
+        !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
       try {
         await fetchPartialUpdate(
           url,
-          hasUsableCache ? cachedSegments!.map((s) => s.id) : undefined,
+          hasUsableCache
+            ? cachedSegments!.map((s) => s.id)
+            : options?._skipCache
+              ? [] // Action redirect: send no segments so server renders everything fresh
+              : undefined,
           false,
           tx.handle.signal,
           tx.with({
@@ -562,50 +339,56 @@ export function createNavigationBridge(
             scroll: options?.scroll,
             state: resolvedState,
           }),
-          // Pass cached segments (merged with current page's fresh segments for shared IDs)
-          // so the segment map is consistent with what we tell the server we have.
-          // Server decides what needs revalidation based on route matching and custom functions.
-          // No need for staleRevalidation flag - we're sending the freshest segments we have.
-          // Also pass cached handle data for restoring breadcrumbs when server returns empty diff.
-          hasUsableCache ? { targetCacheSegments: cachedSegments, targetCacheHandleData: cachedHandleData } : undefined
+          hasUsableCache
+            ? {
+                type: "navigate" as const,
+                targetCacheSegments: cachedSegments,
+                targetCacheHandleData: cachedHandleData,
+              }
+            : isLeavingIntercept
+              ? { type: "leave-intercept" as const }
+              : undefined,
         );
       } catch (error) {
-        // Ignore AbortError - navigation was cancelled by a newer navigation
+        // Server-side redirect with location state: the current transaction's
+        // cleanup resets loading state. Re-navigate to the redirect
+        // target carrying the server-set state into history.pushState.
+        if (error instanceof ServerRedirect) {
+          const redirectUrl = validateRedirectOrigin(
+            error.url,
+            window.location.origin,
+          );
+          if (!redirectUrl) {
+            return;
+          }
+          return this.navigate(redirectUrl, {
+            state: error.state,
+            replace: options?.replace,
+            _skipCache: true,
+          } as NavigateOptionsInternal);
+        }
+
         if (error instanceof DOMException && error.name === "AbortError") {
-          console.log("[Browser] Navigation aborted by newer navigation");
+          debugLog("[Browser] Navigation aborted by newer navigation");
           return;
         }
 
-        // Handle network errors by triggering root error boundary
-        if (error instanceof NetworkError || isNetworkError(error)) {
-          const networkError =
-            error instanceof NetworkError
-              ? error
-              : new NetworkError(
-                  "Unable to connect to server. Please check your connection.",
-                  { cause: error, url, operation: "navigation" }
-                );
-
+        const networkError = toNetworkError(error, {
+          url,
+          operation: "navigation",
+        });
+        if (networkError) {
           console.error(
             "[Browser] Network error during navigation:",
-            networkError
+            networkError,
           );
-
-          // Emit update with NetworkErrorThrower to trigger root error boundary
-          startTransition(() => {
-            onUpdate({
-              root: createElement(NetworkErrorThrower, { error: networkError }),
-              metadata: {
-                pathname: url,
-                segments: [],
-                isError: true,
-              },
-            });
-          });
+          emitNetworkError(onUpdate, networkError, url);
           return;
         }
 
         throw error;
+      } finally {
+        tx[Symbol.dispose]();
       }
     },
 
@@ -615,11 +398,11 @@ export function createNavigationBridge(
     async refresh(): Promise<void> {
       eventController.abortNavigation();
 
-      using tx = createNavigationTransaction(
+      const tx = createNavigationTransaction(
         store,
         eventController,
         window.location.href,
-        { replace: true }
+        { replace: true },
       );
 
       try {
@@ -629,41 +412,24 @@ export function createNavigationBridge(
           [],
           false,
           tx.handle.signal,
-          tx.with({ url: window.location.href, replace: true, scroll: false })
+          tx.with({ url: window.location.href, replace: true, scroll: false }),
         );
       } catch (error) {
-        // Handle network errors by triggering root error boundary
-        if (error instanceof NetworkError || isNetworkError(error)) {
-          const networkError =
-            error instanceof NetworkError
-              ? error
-              : new NetworkError(
-                  "Unable to connect to server. Please check your connection.",
-                  {
-                    cause: error,
-                    url: window.location.href,
-                    operation: "revalidation",
-                  }
-                );
-
+        const networkError = toNetworkError(error, {
+          url: window.location.href,
+          operation: "revalidation",
+        });
+        if (networkError) {
           console.error(
             "[Browser] Network error during refresh:",
-            networkError
+            networkError,
           );
-
-          startTransition(() => {
-            onUpdate({
-              root: createElement(NetworkErrorThrower, { error: networkError }),
-              metadata: {
-                pathname: window.location.href,
-                segments: [],
-                isError: true,
-              },
-            });
-          });
+          emitNetworkError(onUpdate, networkError, window.location.href);
           return;
         }
         throw error;
+      } finally {
+        tx[Symbol.dispose]();
       }
     },
 
@@ -687,20 +453,29 @@ export function createNavigationBridge(
       const currentInterceptSource = store.getInterceptSourceUrl();
       const newInterceptSource = interceptSourceUrl ?? null;
       if (currentInterceptSource !== newInterceptSource) {
-        console.log(
-          `[Browser] Intercept context changing (${currentInterceptSource} -> ${newInterceptSource}), aborting in-flight actions`
+        debugLog(
+          `[Browser] Intercept context changing (${currentInterceptSource} -> ${newInterceptSource}), aborting in-flight actions`,
         );
         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 });
 
-      console.log(
+      debugLog(
         "[Browser] Popstate -",
         isIntercept ? "intercept" : "normal",
         "key:",
-        historyKey
+        historyKey,
       );
 
       // Update location in event controller
@@ -729,12 +504,27 @@ 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 = renderSegments(cachedSegments, {
+          const root = await renderSegments(cachedSegments, {
             forceAwait: true,
           });
-          onUpdate({
+          // Merge params from cached segments for useParams restoration.
+          // Set params on event controller before onUpdate so both location
+          // and params are current when the debounced notify() fires.
+          const cachedParams: Record<string, string> = {};
+          for (const s of cachedSegments) {
+            if (s.params) Object.assign(cachedParams, s.params);
+          }
+          eventController.setParams(cachedParams);
+
+          const popstateUpdate = {
             root,
             metadata: {
               pathname: new URL(url).pathname,
@@ -743,23 +533,40 @@ export function createNavigationBridge(
               matched: cachedSegments.map((s) => s.id),
               diff: [],
               cachedHandleData,
+              params: cachedParams,
             },
-          });
-
-          // Restore scroll position for back/forward navigation
-          handleNavigationEnd({ restore: true, isStreaming });
+            scroll: { restore: true, isStreaming },
+          };
+          // 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) {
+                addTransitionType("navigation-back");
+              }
+              onUpdate(popstateUpdate);
+            });
+          } else {
+            onUpdate(popstateUpdate);
+          }
 
           // SWR: If stale, trigger background revalidation
           if (isStale) {
-            console.log("[Browser] Cache is stale, background revalidating...");
+            debugLog("[Browser] Cache is stale, background revalidating...");
             // Background revalidation - don't await, just fire and forget
             const segmentIds = cachedSegments.map((s) => s.id);
 
-            using tx = createNavigationTransaction(
+            const tx = createNavigationTransaction(
               store,
               eventController,
               url,
-              { skipLoadingState: true, replace: true }
+              { skipLoadingState: true, replace: true },
             );
 
             fetchPartialUpdate(
@@ -775,41 +582,33 @@ export function createNavigationBridge(
                 interceptSourceUrl,
                 cacheOnly: true,
               }),
-              { staleRevalidation: true, interceptSourceUrl }
-            ).catch((error) => {
-              if (
-                error instanceof DOMException &&
-                error.name === "AbortError"
-              ) {
-                console.log("[Browser] Background revalidation aborted");
-                return;
-              }
-              // For background revalidation, network errors are logged but don't trigger error boundary
-              // since the user is already seeing cached content
-              if (error instanceof NetworkError || isNetworkError(error)) {
-                console.warn(
-                  "[Browser] Background revalidation network error (cached content preserved):",
-                  error.message
+              { type: "stale-revalidation", interceptSourceUrl },
+            )
+              .catch((error) => {
+                if (isBackgroundSuppressible(error)) return;
+                console.error(
+                  "[Browser] Background revalidation failed:",
+                  error,
                 );
-                return;
-              }
-              console.error("[Browser] Background revalidation failed:", error);
-            });
+              })
+              .finally(() => {
+                tx[Symbol.dispose]();
+              });
           }
           return;
         } catch (error) {
           console.warn(
             "[Browser] Failed to render from cache, fetching:",
-            error
+            error,
           );
           // Fall through to fetch
         }
       } else {
-        console.log("[Browser] History cache miss for key:", historyKey);
+        debugLog("[Browser] History cache miss for key:", historyKey);
       }
 
       // Fetch if not cached
-      using tx = createNavigationTransaction(store, eventController, url, {
+      const tx = createNavigationTransaction(store, eventController, url, {
         replace: true,
       });
 
@@ -819,45 +618,43 @@ export function createNavigationBridge(
           undefined,
           false,
           tx.handle.signal,
-          tx.with({ url, replace: true, scroll: false })
+          tx.with({
+            url,
+            replace: true,
+            scroll: false,
+            intercept: isIntercept,
+            interceptSourceUrl,
+          }),
+          isIntercept
+            ? { type: "navigate", interceptSourceUrl }
+            : isLeavingIntercept
+              ? { type: "leave-intercept" }
+              : undefined,
         );
         // Restore scroll position after fetch completes
         handleNavigationEnd({ restore: true, isStreaming });
       } catch (error) {
         if (error instanceof DOMException && error.name === "AbortError") {
-          console.log("[Browser] Popstate navigation aborted");
+          debugLog("[Browser] Popstate navigation aborted");
           return;
         }
 
-        // Handle network errors by triggering root error boundary
-        if (error instanceof NetworkError || isNetworkError(error)) {
-          const networkError =
-            error instanceof NetworkError
-              ? error
-              : new NetworkError(
-                  "Unable to connect to server. Please check your connection.",
-                  { cause: error, url, operation: "navigation" }
-                );
-
+        const networkError = toNetworkError(error, {
+          url,
+          operation: "navigation",
+        });
+        if (networkError) {
           console.error(
-            "[Browser] Network error during popstate navigation:",
-            networkError
+            "[Browser] Network error during popstate:",
+            networkError,
           );
-
-          startTransition(() => {
-            onUpdate({
-              root: createElement(NetworkErrorThrower, { error: networkError }),
-              metadata: {
-                pathname: url,
-                segments: [],
-                isError: true,
-              },
-            });
-          });
+          emitNetworkError(onUpdate, networkError, url);
           return;
         }
 
         throw error;
+      } finally {
+        tx[Symbol.dispose]();
       }
     },
 
@@ -874,19 +671,55 @@ export function createNavigationBridge(
         this.handlePopstate();
       };
 
+      // When the browser restores a page from bfcache (back-forward cache),
+      // any in-flight navigation state is stale. This happens when:
+      // 1. A navigation triggers X-RSC-Reload (e.g., response route hit via SPA)
+      // 2. window.location.href does a hard navigation
+      // 3. The user presses back and the browser restores from bfcache
+      // At that point, currentNavigation is still set from step 1, so
+      // getState() returns "loading" and the progress bar shows.
+      // Abort the stale navigation to reset state to idle.
+      const handlePageShow = (event: PageTransitionEvent) => {
+        if (event.persisted) {
+          debugLog(
+            "[Browser] Page restored from bfcache, resetting navigation state",
+          );
+          eventController.abortNavigation();
+          // pagehide flips scrollRestoration to "auto" for bfcache compat;
+          // restore "manual" so the router controls scroll on SPA navigations.
+          window.history.scrollRestoration = "manual";
+        }
+      };
+
       // Register cross-tab refresh callback with the store
       store.setCrossTabRefreshCallback(() => {
         this.refresh();
       });
 
       window.addEventListener("popstate", handlePopstate);
-      console.log("[Browser] Navigation bridge ready");
+      window.addEventListener("pageshow", handlePageShow);
+      debugLog("[Browser] Navigation bridge ready");
 
       return () => {
         cleanupLinks();
         window.removeEventListener("popstate", handlePopstate);
+        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);
+    },
   };
 }