@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.140

package/src/browser/navigation-bridge.ts

@@ -1,442 +1,49 @@
 import type {
   NavigationBridge,
   NavigationBridgeConfig,
-  NavigateOptions,
-  NavigationStore,
+  NavigateOptionsInternal,
   ResolvedSegment,
 } from "./types.js";
+import { setAppVersion } from "./app-version.js";
+import { isActionFenceActive } from "./action-fence.js";
+import { getRangoState } from "./rango-state.js";
+import * as React from "react";
+import { startTransition } from "react";
 import {
-  isLocationStateEntry,
-  resolveLocationStateEntries,
-} from "./react/location-state-shared.js";
+  createNavigationTransaction,
+  resolveNavigationState,
+} from "./navigation-transaction.js";
+import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
+import {
+  handleNavigationStart,
+  handleNavigationEnd,
+  ensureHistoryKey,
+} from "./scroll-restoration.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_"));
-}
+// addTransitionType is only available in React experimental
+const addTransitionType: ((type: string) => void) | undefined =
+  "addTransitionType" in React ? (React as any).addTransitionType : undefined;
 
-/**
- * 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;
-    }
-  }
-
-  // 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;
-    }
-  }
-
-  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,
+  emitNavigationError,
+  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,7 +51,7 @@ export { createNavigationTransaction };
  */
 export interface NavigationBridgeConfigWithController extends NavigationBridgeConfig {
   eventController: EventController;
-  /** RSC version from initial payload metadata */
+  /** RSC version from initial payload metadata. */
   version?: string;
 }
 
@@ -462,9 +69,10 @@ 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 } = config;
+  let version = config.version;
 
   // Create shared partial updater
   const fetchPartialUpdate = createPartialUpdater({
@@ -472,25 +80,123 @@ export function createNavigationBridge(
     client,
     onUpdate,
     renderSegments,
-    version,
+    getVersion: () => version,
   });
 
   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();
       }
@@ -503,22 +209,27 @@ export function createNavigationBridge(
       const isLeavingIntercept = isCurrentlyIntercept && isSamePathNavigation;
 
       if (isLeavingIntercept) {
-        console.log(`[Browser] Leaving intercept - same URL navigation from intercept`);
+        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.
+      // 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. Use updateCacheHandleData (not cacheSegmentsForHistory):
+      // the source page's segments are unchanged, so this is a handleData refresh,
+      // not a commit. Critically it PRESERVES the entry's stale flag — when the
+      // source page has a deferred Meta still pending, its entry was marked stale
+      // (invalidate-on-pending) so a popstate return revalidates; re-committing it
+      // here would reset stale to false and serve the carried (pre-resolution)
+      // title as fresh. It also leaves the nav-instance token intact.
       const sourceHistoryKey = store.getHistoryKey();
       const sourceCached = store.getCachedSegments(sourceHistoryKey);
       if (sourceCached?.segments && sourceCached.segments.length > 0) {
         const currentHandleData = eventController.getHandleState().data;
-        store.cacheSegmentsForHistory(
-          sourceHistoryKey,
-          sourceCached.segments,
-          currentHandleData
-        );
+        store.updateCacheHandleData(sourceHistoryKey, currentHandleData);
       }
 
       // Check if we have cached segments for target URL
@@ -532,7 +243,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);
@@ -547,28 +258,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 &&
-        !isLeavingIntercept;
-
-      using tx = createNavigationTransaction(store, eventController, url, {
+        !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({
@@ -577,55 +300,69 @@ 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.
-          // When leaving intercept, pass the flag so fetchPartialUpdate knows to filter segments.
           hasUsableCache
-            ? { targetCacheSegments: cachedSegments, targetCacheHandleData: cachedHandleData }
+            ? {
+                type: "navigate" as const,
+                targetCacheSegments: cachedSegments,
+                targetCacheHandleData: cachedHandleData,
+              }
             : isLeavingIntercept
-              ? { leavingIntercept: true }
-              : undefined
+              ? { type: "leave-intercept" as const }
+              : undefined,
         );
       } catch (error) {
-        // Ignore AbortError - navigation was cancelled by a newer navigation
-        if (error instanceof DOMException && error.name === "AbortError") {
-          console.log("[Browser] Navigation aborted by newer navigation");
-          return;
+        // 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);
         }
 
-        // 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" }
-                );
+        // Aborted, or superseded by a newer navigation. A superseded nav may
+        // reject with a non-AbortError (e.g. a Flight decode that fails after its
+        // signal was aborted), so check the signal too -- otherwise we would
+        // render a boundary that clobbers the newer navigation's content.
+        if (
+          (error instanceof DOMException && error.name === "AbortError") ||
+          tx.handle.signal.aborted
+        ) {
+          debugLog("[Browser] Navigation aborted or superseded");
+          return;
+        }
 
+        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;
+        // A response we could not process (undecodable Flight body, or an
+        // unanticipated failure building the response). Surface the route's
+        // error boundary rather than let the rejection abort the navigation
+        // silently. Prefetched responses funnel here too: a failed warm-prefetch
+        // payload rejects on consumption and propagates to this catch.
+        console.error("[Browser] Unprocessable navigation response:", error);
+        emitNavigationError(onUpdate, error, url);
+      } finally {
+        tx[Symbol.dispose]();
       }
     },
 
@@ -635,11 +372,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 {
@@ -649,41 +386,37 @@ 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",
-                  }
-                );
+        // Aborted or superseded: bail without rendering a boundary (see navigate()).
+        if (
+          (error instanceof DOMException && error.name === "AbortError") ||
+          tx.handle.signal.aborted
+        ) {
+          return;
+        }
 
+        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;
+
+        // refresh() shares the fetchPartialUpdate chokepoint with navigate()/
+        // popstate, so an unprocessable response must surface the error boundary
+        // here too rather than become an uncaught rejection.
+        console.error("[Browser] Unprocessable refresh response:", error);
+        emitNavigationError(onUpdate, error, window.location.href);
+      } finally {
+        tx[Symbol.dispose]();
       }
     },
 
@@ -707,20 +440,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
@@ -736,11 +478,22 @@ export function createNavigationBridge(
       // Helper to check if streaming is in progress
       const isStreaming = () => eventController.getState().isStreaming;
 
+      // Surface any external rotation of the rango state cookie (a server
+      // Set-Cookie, a sibling tab, a cookie clear) BEFORE reading the stale bit.
+      // The divergence observer only runs inside getRangoState() — fetch-time —
+      // so a popstate-first interaction would otherwise serve a pre-mutation
+      // page as fresh and never fetch to trigger the observer. Reading here lets
+      // the observer mark the history cache stale so getCachedSegments sees it.
+      getRangoState();
+
       // Check if we can restore from history cache
       const cached = store.getCachedSegments(historyKey);
       const cachedSegments = cached?.segments;
       const cachedHandleData = cached?.handleData;
-      const isStale = cached?.stale ?? false;
+      // While an action is in flight the fence persists no stale flag, so OR it
+      // in here: a popstate during the flight serves the cached entry AND
+      // revalidates (SWR) instead of serving it as fresh.
+      const isStale = (cached?.stale ?? false) || isActionFenceActive();
 
       if (cachedSegments && cachedSegments.length > 0) {
         // Update store to point to this history entry
@@ -749,12 +502,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,
@@ -763,23 +531,51 @@ 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...");
-            // Background revalidation - don't await, just fire and forget
-            const segmentIds = cachedSegments.map((s) => s.id);
-
-            using tx = createNavigationTransaction(
+            debugLog("[Browser] Cache is stale, background revalidating...");
+            // Background revalidation - don't await, just fire and forget.
+            // When the entry's handles are incomplete (a deferred Meta was still
+            // pending when the user navigated away — see handlesPending), send NO
+            // segment IDs so the server returns a FULL re-render with the handle
+            // stream. A normal stale revalidation sends the cached IDs and the
+            // server returns a diff-only payload that omits unchanged segments'
+            // handles, so a deferred Meta would never re-stream and the title
+            // would stay the pre-resolution carry. handlesPending is set only for
+            // the deferred-Meta-aborted case, so action/cross-tab SWR keeps the
+            // cheap diff path.
+            const segmentIds = cached?.handlesPending
+              ? []
+              : cachedSegments.map((s) => s.id);
+
+            const tx = createNavigationTransaction(
               store,
               eventController,
               url,
-              { skipLoadingState: true, replace: true }
+              { skipLoadingState: true, replace: true },
             );
 
             fetchPartialUpdate(
@@ -795,41 +591,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,
       });
 
@@ -839,45 +627,51 @@ 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");
+        // Aborted or superseded by a newer navigation: bail without clobbering
+        // content with a boundary (see navigate()).
+        if (
+          (error instanceof DOMException && error.name === "AbortError") ||
+          tx.handle.signal.aborted
+        ) {
+          debugLog("[Browser] Popstate navigation aborted or superseded");
           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;
+        // Unprocessable response on a back/forward navigation: surface the
+        // error boundary instead of an uncaught rejection (see navigate()).
+        console.error("[Browser] Unprocessable popstate response:", error);
+        emitNavigationError(onUpdate, error, url);
+      } finally {
+        tx[Symbol.dispose]();
       }
     },
 
@@ -904,8 +698,13 @@ export function createNavigationBridge(
       // Abort the stale navigation to reset state to idle.
       const handlePageShow = (event: PageTransitionEvent) => {
         if (event.persisted) {
-          console.log("[Browser] Page restored from bfcache, resetting navigation state");
+          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";
         }
       };
 
@@ -916,7 +715,7 @@ export function createNavigationBridge(
 
       window.addEventListener("popstate", handlePopstate);
       window.addEventListener("pageshow", handlePageShow);
-      console.log("[Browser] Navigation bridge ready");
+      debugLog("[Browser] Navigation bridge ready");
 
       return () => {
         cleanupLinks();
@@ -924,6 +723,16 @@ export function createNavigationBridge(
         window.removeEventListener("pageshow", handlePageShow);
       };
     },
+
+    getVersion(): string | undefined {
+      return version;
+    },
+
+    updateVersion(newVersion: string): void {
+      version = newVersion;
+      setAppVersion(newVersion);
+      store.clearHistoryCache();
+    },
   };
 }