@rangojs/router 0.0.0-experimental.f3c21dba → 0.0.0-experimental.f4a8e8de

package/src/browser/merge-segment-loaders.ts

@@ -1,5 +1,5 @@
 import type { ResolvedSegment } from "./types.js";
-import { debugLog } from "./logging.js";
+import { debugLog, IS_BROWSER_DEBUG } from "./logging.js";
 
 /**
  * Merge partial loader data from server with cached loader data.
@@ -19,9 +19,11 @@ export function mergeSegmentLoaders(
   const serverLoaderIds = fromServer.loaderIds || [];
   const cachedLoaderIds = fromCache.loaderIds || [];
 
-  debugLog(
-    `[Browser] Merging partial loaders: server has ${serverLoaderIds.join(", ")}, cache has ${cachedLoaderIds.join(", ")}`,
-  );
+  if (IS_BROWSER_DEBUG) {
+    debugLog(
+      `[Browser] Merging partial loaders: server has ${serverLoaderIds.join(", ")}, cache has ${cachedLoaderIds.join(", ")}`,
+    );
+  }
 
   return {
     ...fromCache,

package/src/browser/navigation-bridge.ts

@@ -1,16 +1,20 @@
 import type {
   NavigationBridge,
   NavigationBridgeConfig,
+  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 {
   createNavigationTransaction,
   resolveNavigationState,
 } from "./navigation-transaction.js";
-import { buildHistoryState } from "./history-state.js";
+import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
 import {
   handleNavigationStart,
   handleNavigationEnd,
@@ -21,7 +25,10 @@ import {
 const addTransitionType: ((type: string) => void) | undefined =
   "addTransitionType" in React ? (React as any).addTransitionType : undefined;
 
-import { setupLinkInterception } from "./link-interceptor.js";
+import {
+  setupDelegatedLinkPrefetch,
+  setupLinkInterception,
+} from "./link-interceptor.js";
 import { createPartialUpdater } from "./partial-update.js";
 import { generateHistoryKey } from "./navigation-store.js";
 import type { EventController } from "./event-controller.js";
@@ -29,11 +36,19 @@ import { isInterceptOnlyCache } from "./intercept-utils.js";
 import {
   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";
+import {
+  prefetchDirect,
+  prefetchQueued,
+  schedulePrefetchWhenRouterIdle,
+} from "./prefetch/loader.js";
+import type { PrefetchStrategy } from "../router/prefetch-default.js";
+import { beginClientUrlNavigation } from "../client-urls/navigation.js";
 
 // Polyfill Symbol.dispose for Safari and older browsers
 if (typeof Symbol.dispose === "undefined") {
@@ -47,8 +62,50 @@ export { createNavigationTransaction };
  */
 export interface NavigationBridgeConfigWithController extends NavigationBridgeConfig {
   eventController: EventController;
-  /** RSC version from initial payload metadata */
+  /** RSC version from initial payload metadata. */
   version?: string;
+  /** Server-resolved default used by both Links and delegated anchors. */
+  defaultPrefetch?: PrefetchStrategy;
+  /** Canonical router basename used to scope delegated anchor prefetch. */
+  basename?: string;
+}
+
+export interface NavigationBridgeDelegatedPrefetchOptions {
+  defaultPrefetch?: PrefetchStrategy;
+  root?: HTMLElement;
+  basename?: string;
+}
+
+/** Register delegated anchor prefetch with the production bridge wiring. */
+export function setupNavigationBridgeDelegatedPrefetch(
+  store: NavigationStore,
+  eventController: EventController,
+  getVersion: () => string | undefined,
+  options: NavigationBridgeDelegatedPrefetchOptions = {},
+): () => void {
+  return setupDelegatedLinkPrefetch(
+    (url, priority) => {
+      const trigger = () => {
+        const segmentState = store.getSegmentState();
+        const prefetch =
+          priority === "direct" ? prefetchDirect : prefetchQueued;
+        prefetch(
+          url,
+          segmentState.currentSegmentIds,
+          getVersion(),
+          store.getRouterId?.(),
+        );
+      };
+
+      if (priority === "direct") {
+        trigger();
+        return;
+      }
+
+      return schedulePrefetchWhenRouterIdle(eventController, trigger);
+    },
+    { eventController, ...options },
+  );
 }
 
 /**
@@ -67,8 +124,16 @@ 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,
+    defaultPrefetch,
+    basename,
+  } = config;
+  let version = config.version;
 
   // Create shared partial updater
   const fetchPartialUpdate = createPartialUpdater({
@@ -76,7 +141,7 @@ export function createNavigationBridge(
     client,
     onUpdate,
     renderSegments,
-    version,
+    getVersion: () => version,
   });
 
   return {
@@ -158,11 +223,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();
@@ -216,17 +277,20 @@ export function createNavigationBridge(
         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
@@ -260,19 +324,29 @@ 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,
       });
+      const clientUrlPresentation = beginClientUrlNavigation(
+        targetUrl,
+        tx.handle.signal,
+      );
 
       // REVALIDATE: Fetch fresh data from server
       try {
@@ -320,8 +394,15 @@ export function createNavigationBridge(
           } as NavigateOptionsInternal);
         }
 
-        if (error instanceof DOMException && error.name === "AbortError") {
-          debugLog("[Browser] Navigation aborted by newer 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;
         }
 
@@ -338,8 +419,15 @@ export function createNavigationBridge(
           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 {
+        clientUrlPresentation?.clear();
         tx[Symbol.dispose]();
       }
     },
@@ -367,6 +455,14 @@ export function createNavigationBridge(
           tx.with({ url: window.location.href, replace: true, scroll: false }),
         );
       } catch (error) {
+        // 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",
@@ -379,7 +475,12 @@ export function createNavigationBridge(
           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]();
       }
@@ -411,6 +512,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 });
 
@@ -434,11 +544,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
@@ -447,6 +568,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, {
@@ -474,7 +601,14 @@ export function createNavigationBridge(
             },
             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) {
@@ -489,8 +623,19 @@ export function createNavigationBridge(
           // SWR: If stale, trigger background revalidation
           if (isStale) {
             debugLog("[Browser] Cache is stale, background revalidating...");
-            // Background revalidation - don't await, just fire and forget
-            const segmentIds = cachedSegments.map((s) => s.id);
+            // 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,
@@ -555,13 +700,22 @@ 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 });
       } catch (error) {
-        if (error instanceof DOMException && error.name === "AbortError") {
-          debugLog("[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;
         }
 
@@ -578,7 +732,10 @@ export function createNavigationBridge(
           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]();
       }
@@ -632,6 +789,25 @@ export function createNavigationBridge(
         window.removeEventListener("pageshow", handlePageShow);
       };
     },
+
+    registerDelegatedPrefetch(): () => void {
+      return setupNavigationBridgeDelegatedPrefetch(
+        store,
+        eventController,
+        () => version,
+        { defaultPrefetch, basename },
+      );
+    },
+
+    getVersion(): string | undefined {
+      return version;
+    },
+
+    updateVersion(newVersion: string): void {
+      version = newVersion;
+      setAppVersion(newVersion);
+      store.clearHistoryCache();
+    },
   };
 }