@rangojs/router 0.22.1 → 0.23.0

package/src/browser/navigation-bridge.ts

@@ -5,6 +5,7 @@ import type {
   NavigateOptionsInternal,
   ResolvedSegment,
 } from "./types.js";
+import { isPlaceholder } from "../types/segments.js";
 import { setAppVersion } from "./app-version.js";
 import { isActionFenceActive } from "./action-fence.js";
 import { getRangoState } from "./rango-state.js";
@@ -14,7 +15,12 @@ import {
   createNavigationTransaction,
   resolveNavigationState,
 } from "./navigation-transaction.js";
-import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
+import {
+  buildHistoryState,
+  mergeLocationState,
+  pushHistoryWithIdx,
+} from "./history-state.js";
+import { consumeHandles } from "./react/NavigationProvider.js";
 import {
   handleNavigationStart,
   handleNavigationEnd,
@@ -120,6 +126,21 @@ export function setupNavigationBridgeDelegatedPrefetch(
   );
 }
 
+/**
+ * A history entry's segments, when they can be shown. An entry left before
+ * its fill landed (`prefetch: false`) holds placeholders, not segments:
+ * restoring it would suspend on holes nobody resolves, so it is fetched.
+ */
+function isRestorable(
+  segments: ResolvedSegment[] | undefined,
+): segments is ResolvedSegment[] {
+  return (
+    segments !== undefined &&
+    segments.length > 0 &&
+    !segments.some(isPlaceholder)
+  );
+}
+
 /**
  * Create a navigation bridge for handling client-side navigation
  *
@@ -154,6 +175,20 @@ export function createNavigationBridge(
     onUpdate,
     renderSegments,
     getVersion: () => version,
+    fill: {
+      // A fill follows a redirect as a navigation (`bridge` is below).
+      redirect: (url, state) =>
+        void bridge.navigate(url, { state, replace: true, _skipCache: true }),
+      // No payload follows (`treeless`): the entry's readers are told now.
+      locationState: (state) => {
+        eventController.commitLocationState(mergeLocationState(state), true);
+        eventController.flushRouteState();
+      },
+      handles: (metadata) => {
+        if (metadata.handles) consumeHandles(metadata, eventController, store);
+      },
+      flush: eventController.flushRouteState,
+    },
   });
 
   /**
@@ -195,7 +230,7 @@ export function createNavigationBridge(
     });
   }
 
-  return {
+  const bridge: NavigationBridge = {
     /**
      * Navigate to a URL
      * Uses cached segments for SWR revalidation when available
@@ -247,7 +282,9 @@ export function createNavigationBridge(
 
         const historyKey = generateHistoryKey(url, { intercept: isIntercept });
 
-        // Copy current segments to the new history key so back/forward restores instantly
+        // Copy current segments to the new history key so back/forward restores instantly.
+        // The array itself, not a clone: getPageHistoryKeys reads a shared
+        // array as the same page (the document's late handle pushes).
         const currentKey = store.getHistoryKey();
         const currentCache = store.getCachedSegments(currentKey);
         if (currentCache?.segments) {
@@ -356,8 +393,10 @@ export function createNavigationBridge(
         );
         cachedSegments = cachedSegments.map((targetSeg) => {
           const sourceSeg = sourceSegmentMap.get(targetSeg.id);
-          // Use source (current page) version for shared segments - it's fresher
-          return sourceSeg || targetSeg;
+          // Use source (current page) version for shared segments - it's
+          // fresher. A placeholder waiting for its fill (prefetch: false) is
+          // not a copy of the segment: the target keeps its own.
+          return sourceSeg && !isPlaceholder(sourceSeg) ? sourceSeg : targetSeg;
         });
       }
 
@@ -374,8 +413,7 @@ export function createNavigationBridge(
       // 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 &&
+        isRestorable(cachedSegments) &&
         !isInterceptOnlyCache(cachedSegments) &&
         !hasInterceptCache &&
         !isLeavingIntercept &&
@@ -463,7 +501,9 @@ export function createNavigationBridge(
                       targetCacheHandleData: cachedHandleData,
                     }
                   : {}),
-                optimisticPresented: clientUrlPresentation !== null,
+                ...(clientUrlPresentation && {
+                  presentation: clientUrlPresentation,
+                }),
               },
         );
       } catch (error) {
@@ -580,7 +620,9 @@ export function createNavigationBridge(
      * Uses cached segments when available for instant restoration
      */
     async handlePopstate(): Promise<void> {
-      // Abort any pending navigation to prevent race conditions
+      // Abort any pending navigation to prevent race conditions, and the
+      // fill of the page being left (prefetch: false), which its committed
+      // navigation still owns.
       eventController.abortNavigation();
       handleTraversalStart();
 
@@ -648,7 +690,7 @@ export function createNavigationBridge(
       // revalidates (SWR) instead of serving it as fresh.
       const isStale = (cached?.stale ?? false) || isActionFenceActive();
 
-      if (cachedSegments && cachedSegments.length > 0) {
+      if (isRestorable(cachedSegments)) {
         // transition({ when }) decides the restore (kind "pop") against the
         // entry being left, so before the store moves to the restored entry.
         // The decision the entry was committed with is not reused: it was
@@ -818,8 +860,12 @@ export function createNavigationBridge(
               ? { type: "leave-intercept" }
               : undefined,
         );
-        // Restore scroll position after fetch completes
-        handleNavigationEnd({ restore: true, isStreaming });
+        // Restore scroll position after fetch completes. A traversal that
+        // was left returns here too, its response ignored: it restores
+        // nothing.
+        if (!tx.handle.signal.aborted) {
+          handleNavigationEnd({ restore: true, isStreaming });
+        }
       } catch (error) {
         // Aborted or superseded by a newer navigation: bail without clobbering
         // content with a boundary (see navigate()).
@@ -888,13 +934,16 @@ export function createNavigationBridge(
       // 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.
+      // Abort the stale navigation to reset state to idle. Only that one: the
+      // page restored is not being left, so a committed navigation's
+      // prefetch: false fill keeps its signal, and fails as a navigation if
+      // the browser dropped its request while the page was frozen.
       const handlePageShow = (event: PageTransitionEvent) => {
         if (event.persisted) {
           debugLog(
             "[Browser] Page restored from bfcache, resetting navigation state",
           );
-          eventController.abortNavigation();
+          eventController.abortNavigation(true);
         }
       };
 
@@ -933,6 +982,7 @@ export function createNavigationBridge(
       store.clearHistoryCache();
     },
   };
+  return bridge;
 }
 
 export { createNavigationBridge as default };

package/src/browser/navigation-client.ts

@@ -14,7 +14,6 @@ import {
 } from "./logging.js";
 import { getRangoState } from "./rango-state.js";
 import { isActionFenceActive } from "./action-fence.js";
-import { CLIENT_REVALIDATION_HEADER } from "../client-urls/revalidation-protocol.js";
 import {
   expandPayloadFragments,
   SEGMENT_FRAGMENT_CAPABILITY_HEADER,
@@ -22,6 +21,7 @@ import {
   SegmentFragmentDecodeError,
 } from "../segment-fragments.js";
 import {
+  abortUntilResponse,
   extractRscHeaderUrl,
   emptyResponse,
   handleReloadHeader,
@@ -38,6 +38,7 @@ import {
   type DecodedPrefetch,
 } from "./prefetch/cache.js";
 import { cancelAllPrefetches } from "./prefetch/loader.js";
+import { FILL_PARAM } from "../prefetch-markers.js";
 
 /**
  * Create a navigation client for fetching RSC payloads
@@ -80,11 +81,11 @@ export function createNavigationClient(
         previousUrl,
         signal,
         staleRevalidation,
-        clientRevalidation,
         interceptSourceUrl,
         version,
         routerId,
         hmr,
+        fill,
       } = options;
 
       const debugEnabled = isBrowserDebugEnabled();
@@ -114,11 +115,18 @@ export function createNavigationClient(
       if (routerId) {
         fetchUrl.searchParams.set("_rsc_rid", routerId);
       }
+      // A param, not a header: the document cache decides from the raw URL
+      // (cache/document-cache.ts), and it keeps the fill out of every
+      // prefetch key below.
+      if (fill) {
+        fetchUrl.searchParams.set(FILL_PARAM, "1");
+      }
 
       // If the lazy prefetch runtime has not loaded yet, prevent a deferred
       // speculative request from starting after this navigation misses the
-      // synchronous cache lookup and begins its own fetch.
-      cancelAllPrefetches(targetUrl);
+      // synchronous cache lookup and begins its own fetch. A fill is not a
+      // navigation: the links on the page it completes stay prefetched.
+      if (!fill) cancelAllPrefetches(targetUrl);
 
       // Check completed in-memory prefetch cache before making a network
       // request. Try the source-scoped key first (populated when the server
@@ -136,6 +144,7 @@ export function createNavigationClient(
       const canUsePrefetch =
         !staleRevalidation &&
         !hmr &&
+        !fill &&
         !interceptSourceUrl &&
         !isActionFenceActive();
       const rangoState = getRangoState();
@@ -242,39 +251,42 @@ export function createNavigationClient(
           });
         }
 
-        const responsePromise = fetch(fetchUrl, {
-          // During an action's flight the state is not rotated, so the old
-          // X-Rango-State still matches the Vary-keyed HTTP-cache entry; bypass
-          // it so a genuine mid-action navigation fetches fresh instead of being
-          // served the stale prefetched bytes. Fragment recovery also bypasses
-          // HTTP caches so it reaches the server's decode-and-evict path.
-          ...((isActionFenceActive() || fragmentRecovery) && {
-            cache: "no-store" as RequestCache,
-          }),
-          headers: {
-            "X-RSC-Router-Client-Path": previousUrl,
-            // Reuse the single per-operation read (see rangoState above): the
-            // cache-key lookup and this header must agree on one value, and the
-            // cookie read has side effects (external-rotation notify) we do not
-            // want to fire twice per navigation.
-            "X-Rango-State": rangoState,
-            ...(fragmentPassthrough && {
-              [SEGMENT_FRAGMENT_CAPABILITY_HEADER]: "1",
-            }),
-            ...(fragmentRecovery && {
-              [SEGMENT_FRAGMENT_RECOVERY_HEADER]: "1",
-            }),
-            ...(clientRevalidation && {
-              [CLIENT_REVALIDATION_HEADER]: clientRevalidation,
+        // `signal` cancels the request until its response arrives
+        // (abortUntilResponse). A prefetch: false fill passes its
+        // navigation's signal, which stays abortable after the commit
+        // (event-controller.ts streamingNavigation).
+        const responsePromise = abortUntilResponse(signal, (requestSignal) =>
+          fetch(fetchUrl, {
+            // During an action's flight the state is not rotated, so the old
+            // X-Rango-State still matches the Vary-keyed HTTP-cache entry; bypass
+            // it so a genuine mid-action navigation fetches fresh instead of being
+            // served the stale prefetched bytes. Fragment recovery also bypasses
+            // HTTP caches so it reaches the server's decode-and-evict path.
+            ...((isActionFenceActive() || fragmentRecovery || fill) && {
+              cache: "no-store" as RequestCache,
             }),
-            ...(tx && { "X-RSC-Router-Request-Id": tx.requestId }),
-            ...(interceptSourceUrl && {
-              "X-RSC-Router-Intercept-Source": interceptSourceUrl,
-            }),
-            ...(hmr && { "X-RSC-HMR": "1" }),
-          },
-          signal,
-        }).then((response) => {
+            headers: {
+              "X-RSC-Router-Client-Path": previousUrl,
+              // Reuse the single per-operation read (see rangoState above): the
+              // cache-key lookup and this header must agree on one value, and the
+              // cookie read has side effects (external-rotation notify) we do not
+              // want to fire twice per navigation.
+              "X-Rango-State": rangoState,
+              ...(fragmentPassthrough && {
+                [SEGMENT_FRAGMENT_CAPABILITY_HEADER]: "1",
+              }),
+              ...(fragmentRecovery && {
+                [SEGMENT_FRAGMENT_RECOVERY_HEADER]: "1",
+              }),
+              ...(tx && { "X-RSC-Router-Request-Id": tx.requestId }),
+              ...(interceptSourceUrl && {
+                "X-RSC-Router-Intercept-Source": interceptSourceUrl,
+              }),
+              ...(hmr && { "X-RSC-HMR": "1" }),
+            },
+            signal: requestSignal,
+          }),
+        ).then((response) => {
           const validated = validateRscHeaders(
             response,
             "fetch",

package/src/browser/navigation-store.ts

@@ -656,6 +656,19 @@ export function createNavigationStore(
       ];
     },
 
+    /**
+     * Entries that show the same page as `historyKey`'s. A shallow navigation
+     * (navigation-bridge.ts) caches the page's segments array under the new
+     * key; every other commit caches a new array, so identity is the page.
+     */
+    getPageHistoryKeys(historyKey: string): string[] {
+      const segments = historyCache.find(([key]) => key === historyKey)?.[1];
+      if (!segments) return [historyKey];
+      return historyCache
+        .filter((entry) => entry[1] === segments)
+        .map(([key]) => key);
+    },
+
     /**
      * Mark every history entry stale WITHOUT clearing the prefetch caches or
      * rotating the rango state. The jar-divergence observer calls this after an

package/src/browser/navigation-transaction.ts

@@ -92,6 +92,23 @@ interface BoundCommitOverrides {
   treeless?: boolean;
 }
 
+/**
+ * What a commit decided about scroll, in the shape the update that follows
+ * carries it (NavigationUpdate.scroll). A navigation always decides, and "do
+ * not scroll" is a decision (`<Link scroll={false}>`, an intercept): it
+ * replaces a pending one. A commit that is not a navigation decides nothing:
+ * an action refetch into the entry on screen (`storeOnly`) and a cache-only
+ * commit return no `scroll`, and their update leaves a pending decision alone
+ * (react/NavigationProvider.tsx).
+ *
+ * Scar tissue: those two used to answer `scroll: false`. An action refetch
+ * that landed before React committed a navigation then replaced the
+ * navigation's pending scroll with "do not scroll".
+ */
+export interface CommitResult {
+  scroll?: { enabled: boolean | undefined };
+}
+
 /**
  * Bound transaction with pre-configured commit options (without segmentIds/segments)
  */
@@ -107,12 +124,12 @@ export interface BoundTransaction {
   readonly transitionGatedOff?: boolean;
   /** Start streaming and get a token to end it when the stream completes */
   startStreaming(): StreamingToken;
-  /** Commit the navigation. Returns the effective scroll option for the caller to handle. */
+  /** Commit the navigation. Returns its scroll decision, for the update. */
   commit(
     segmentIds: string[],
     segments: ResolvedSegment[],
     overrides?: BoundCommitOverrides,
-  ): { scroll?: boolean };
+  ): CommitResult;
 }
 
 /**
@@ -120,7 +137,7 @@ export interface BoundTransaction {
  * Uses the event controller handle for lifecycle management
  */
 interface NavigationTransaction extends Disposable {
-  commit(options: CommitOptions): { scroll?: boolean };
+  commit(options: CommitOptions): CommitResult;
   with(
     options: Omit<CommitOptions, "segmentIds" | "segments">,
   ): BoundTransaction;
@@ -146,7 +163,7 @@ export function createNavigationTransaction(
   /**
    * Commit the navigation - updates store and URL atomically
    */
-  function commit(opts: CommitOptions): { scroll?: boolean } {
+  function commit(opts: CommitOptions): CommitResult {
     committed = true;
 
     const {
@@ -172,7 +189,7 @@ export function createNavigationTransaction(
       store.cacheSegmentsForHistory(historyKey, segments, currentHandleData);
       handle.complete(parsedUrl);
       debugLog("[Browser] Cache-only commit, historyKey:", historyKey);
-      return { scroll: false };
+      return {};
     }
 
     if (!traversal) handleNavigationStart();
@@ -196,7 +213,7 @@ export function createNavigationTransaction(
       store.rememberDisplayedEntry(opts.routeName);
       debugLog("[Browser] Store updated (action)");
       handle.complete(parsedUrl);
-      return { scroll: false };
+      return {};
     }
 
     if (traversal) {
@@ -209,7 +226,7 @@ export function createNavigationTransaction(
       eventController.commitLocationState(entryState, opts.treeless);
       handle.complete(parsedUrl);
       debugLog("[Browser] Traversal committed, historyKey:", historyKey);
-      return { scroll };
+      return { scroll: { enabled: scroll } };
     }
 
     const historyState = buildHistoryState(
@@ -231,7 +248,7 @@ export function createNavigationTransaction(
       intercept ? "(intercept)" : "",
     );
 
-    return { scroll };
+    return { scroll: { enabled: scroll } };
   }
 
   return {