@rangojs/router 0.22.1 → 0.24.0

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

@@ -1,12 +1,16 @@
 import type { ResolvedSegment } from "./types.js";
 import { debugLog, IS_BROWSER_DEBUG } from "./logging.js";
+import { settledValue } from "../thenable-status.js";
 
 /**
  * Merge partial loader data from server with cached loader data.
  *
  * During partial revalidation (stale or action), the server may return only
- * some loaders that pass the revalidation check. The component still needs
- * all loader data, so we merge fresh data with cached data.
+ * some loaders that pass the revalidation check, none when every one is held.
+ * The component still needs all loader data, so we merge fresh data with
+ * cached data. Two settled aggregates merge into the array itself: a fresh
+ * Promise.all over settled parts is a promise React has not read, and content
+ * on screen handed one suspends (docs/internal/suspense-contract.md, rule 2).
  *
  * @param fromServer - Segment returned from server with partial loaders
  * @param fromCache - Cached segment with full loader data
@@ -25,24 +29,33 @@ export function mergeSegmentLoaders(
     );
   }
 
+  // Fresh data for the loaders the server re-ran, cached data for the rest.
+  const merge = (newData: any[], cachedData: any[]): any[] =>
+    cachedLoaderIds.map((id: string, i: number) => {
+      const newIndex = serverLoaderIds.indexOf(id);
+      return newIndex !== -1 ? newData[newIndex] : cachedData[i];
+    });
+  const settledNew = settledValue(fromServer.loaderDataPromise!);
+  const settledCached = settledValue(fromCache.loaderDataPromise!);
+
   return {
     ...fromCache,
-    // Keep cached component (server's might be a fresh Promise that needs the loaders)
-    component: fromCache.component,
-    // Merge loader data - await both and combine
-    loaderDataPromise: Promise.all([
-      fromServer.loaderDataPromise!,
-      fromCache.loaderDataPromise!,
-    ]).then(([newData, cachedData]) => {
-      // Build merged array: use new data for updated loaders, cached for rest
-      return cachedLoaderIds.map((id: string, i: number) => {
-        const newIndex = serverLoaderIds.indexOf(id);
-        if (newIndex !== -1) {
-          return (newData as any[])[newIndex]; // Use fresh data
-        }
-        return (cachedData as any[])[i]; // Use cached data
-      });
-    }),
+    // The server re-ran the slot's handler and layout: their render applies,
+    // as it does when every loader re-runs. Only the loaders it held keep
+    // their cached data.
+    component: fromServer.component,
+    layout: fromServer.layout,
+    // Every loader held: the cached aggregate itself, so a boundary still
+    // waiting on it keeps its one thenable (suspense-contract.md, rule 1).
+    loaderDataPromise:
+      serverLoaderIds.length === 0
+        ? fromCache.loaderDataPromise
+        : settledNew && settledCached
+          ? merge(settledNew, settledCached)
+          : Promise.all([
+              fromServer.loaderDataPromise!,
+              fromCache.loaderDataPromise!,
+            ]).then(([newData, cachedData]) => merge(newData, cachedData)),
     // Keep all loader IDs from cache
     loaderIds: fromCache.loaderIds,
     // The rebuilt aggregate is the source of truth. Cached per-loader

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,13 @@ 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 { withSegmentHandles } from "../handles/pushed-by.js";
 import {
   handleNavigationStart,
   handleNavigationEnd,
@@ -120,6 +127,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 +176,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 +231,7 @@ export function createNavigationBridge(
     });
   }
 
-  return {
+  const bridge: NavigationBridge = {
     /**
      * Navigate to a URL
      * Uses cached segments for SWR revalidation when available
@@ -247,7 +283,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) {
@@ -349,15 +387,21 @@ export function createNavigationBridge(
       // since it may have fresher data after an action revalidation.
       // This avoids unnecessary server round-trips for shared layout loaders.
       let cachedSegments = cached?.segments;
-      const cachedHandleData = cached?.handleData;
+      // The segments taken from the page on screen: their pushes come from
+      // it too (targetCacheHandleData below).
+      const fromSource = new Set<string>();
       if (cachedSegments && sourceCached?.segments) {
         const sourceSegmentMap = new Map(
           sourceCached.segments.map((s) => [s.id, s]),
         );
         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.
+          if (!sourceSeg || isPlaceholder(sourceSeg)) return targetSeg;
+          fromSource.add(targetSeg.id);
+          return sourceSeg;
         });
       }
 
@@ -374,8 +418,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 &&
@@ -460,10 +503,23 @@ export function createNavigationBridge(
                 ...(hasUsableCache
                   ? {
                       targetCacheSegments: cachedSegments,
-                      targetCacheHandleData: cachedHandleData,
+                      // Read at commit: a push the page on screen gets while
+                      // the request is in flight is in it.
+                      targetCacheHandleData: () =>
+                        withSegmentHandles(
+                          cached?.handleData ?? {},
+                          liveHandleDataForCache(
+                            eventController,
+                            store,
+                            sourceHistoryKey,
+                          ),
+                          fromSource,
+                        ),
                     }
                   : {}),
-                optimisticPresented: clientUrlPresentation !== null,
+                ...(clientUrlPresentation && {
+                  presentation: clientUrlPresentation,
+                }),
               },
         );
       } catch (error) {
@@ -580,7 +636,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 +706,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 +876,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 +950,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 +998,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 {