@rangojs/router 0.0.0-experimental.f2d1a2f1 → 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,19 +1,20 @@
 import type {
   NavigationBridge,
   NavigationBridgeConfig,
+  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 { 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,
@@ -24,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";
@@ -32,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") {
@@ -50,13 +62,50 @@ export { createNavigationTransaction };
  */
 export interface NavigationBridgeConfigWithController extends NavigationBridgeConfig {
   eventController: EventController;
-  /** RSC version from initial payload metadata (fallback when appShellRef is not provided) */
+  /** RSC version from initial payload metadata. */
   version?: string;
-  /**
-   * Live app-shell ref. When supplied, the bridge reads version/basename
-   * from this ref so cross-app navigations propagate correctly.
-   */
-  appShellRef?: AppShellRef;
+  /** 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 },
+  );
 }
 
 /**
@@ -81,40 +130,11 @@ export function createNavigationBridge(
     eventController,
     onUpdate,
     renderSegments,
-    appShellRef,
+    defaultPrefetch,
+    basename,
   } = 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({
     store,
@@ -122,7 +142,6 @@ export function createNavigationBridge(
     onUpdate,
     renderSegments,
     getVersion: () => version,
-    applyAppShell,
   });
 
   return {
@@ -204,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();
@@ -262,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
@@ -325,6 +343,10 @@ export function createNavigationBridge(
         state: resolvedState,
         skipLoadingState: false,
       });
+      const clientUrlPresentation = beginClientUrlNavigation(
+        targetUrl,
+        tx.handle.signal,
+      );
 
       // REVALIDATE: Fetch fresh data from server
       try {
@@ -372,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;
         }
 
@@ -390,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]();
       }
     },
@@ -419,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",
@@ -431,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]();
       }
@@ -495,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
@@ -541,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) {
@@ -556,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,
@@ -631,8 +709,13 @@ export function createNavigationBridge(
         // 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;
         }
 
@@ -649,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]();
       }
@@ -704,15 +790,24 @@ export function createNavigationBridge(
       };
     },
 
+    registerDelegatedPrefetch(): () => void {
+      return setupNavigationBridgeDelegatedPrefetch(
+        store,
+        eventController,
+        () => version,
+        { defaultPrefetch, basename },
+      );
+    },
+
+    getVersion(): string | undefined {
+      return version;
+    },
+
     updateVersion(newVersion: string): void {
       version = newVersion;
       setAppVersion(newVersion);
       store.clearHistoryCache();
     },
-
-    updateAppShell(next: AppShell): void {
-      applyAppShell(next);
-    },
   };
 }