@rangojs/router 0.0.0-experimental.a62282ba → 0.0.0-experimental.c65e9248

package/src/browser/navigation-client.ts

@@ -17,7 +17,11 @@ import {
   emptyResponse,
   teeWithCompletion,
 } from "./response-adapter.js";
-import { buildPrefetchKey, consumePrefetch } from "./prefetch/cache.js";
+import {
+  buildPrefetchKey,
+  consumePrefetch,
+  consumeInflightPrefetch,
+} from "./prefetch/cache.js";
 
 /**
  * Create a navigation client for fetching RSC payloads
@@ -90,10 +94,15 @@ export function createNavigationClient(
       // server's diff response depends on the source page context.
       // Skip cache for stale revalidation (needs fresh data), HMR (needs
       // fresh modules), and intercept contexts (source-dependent responses).
+      const canUsePrefetch = !staleRevalidation && !hmr && !interceptSourceUrl;
       const cacheKey = buildPrefetchKey(previousUrl, fetchUrl);
-      const cachedResponse =
-        !staleRevalidation && !hmr && !interceptSourceUrl
-          ? consumePrefetch(cacheKey)
+      const cachedResponse = canUsePrefetch ? consumePrefetch(cacheKey) : null;
+      // If no completed cache entry, check for in-flight prefetch.
+      // This reuses a prefetch that is still downloading rather than
+      // starting a duplicate request from scratch.
+      const inflightPrefetch =
+        !cachedResponse && canUsePrefetch
+          ? consumeInflightPrefetch(cacheKey)
           : null;
 
       // Track when the stream completes
@@ -102,32 +111,15 @@ export function createNavigationClient(
         resolveStreamComplete = resolve;
       });
 
-      let responsePromise: Promise<Response>;
-
-      if (cachedResponse) {
-        if (tx) {
-          browserDebugLog(tx, "prefetch cache hit", { key: cacheKey });
-        }
-        // Cached response body is already fully buffered (arrayBuffer),
-        // so stream completion is immediate.
-        responsePromise = Promise.resolve(cachedResponse).then((response) => {
-          return teeWithCompletion(
-            response,
-            () => {
-              if (tx) browserDebugLog(tx, "stream complete (from cache)");
-              resolveStreamComplete();
-            },
-            signal,
-          );
-        });
-      } else {
+      /** Start a fresh navigation fetch (no cache / inflight hit). */
+      const doFreshFetch = (): Promise<Response> => {
         if (tx) {
           browserDebugLog(tx, "fetching", {
             path: `${fetchUrl.pathname}${fetchUrl.search}`,
           });
         }
 
-        responsePromise = fetch(fetchUrl, {
+        return fetch(fetchUrl, {
           headers: {
             "X-RSC-Router-Client-Path": previousUrl,
             "X-Rango-State": getRangoState(),
@@ -183,6 +175,60 @@ export function createNavigationClient(
             signal,
           );
         });
+      };
+
+      let responsePromise: Promise<Response>;
+
+      if (cachedResponse) {
+        if (tx) {
+          browserDebugLog(tx, "prefetch cache hit", { key: cacheKey });
+        }
+        // Cached response body is already fully buffered (arrayBuffer),
+        // so stream completion is immediate.
+        responsePromise = Promise.resolve(cachedResponse).then((response) => {
+          return teeWithCompletion(
+            response,
+            () => {
+              if (tx) browserDebugLog(tx, "stream complete (from cache)");
+              resolveStreamComplete();
+            },
+            signal,
+          );
+        });
+      } else if (inflightPrefetch) {
+        if (tx) {
+          browserDebugLog(tx, "reusing inflight prefetch", { key: cacheKey });
+        }
+        // Await the in-flight prefetch. If it resolves with a Response,
+        // use it like a cache hit. If it fails (null), fall back to
+        // a fresh navigation fetch.
+        responsePromise = inflightPrefetch.then((prefetchResponse) => {
+          if (!prefetchResponse) {
+            if (tx) {
+              browserDebugLog(
+                tx,
+                "inflight prefetch failed, falling back to fetch",
+              );
+            }
+            return doFreshFetch();
+          }
+          if (tx) {
+            browserDebugLog(tx, "inflight prefetch resolved", {
+              key: cacheKey,
+            });
+          }
+          return teeWithCompletion(
+            prefetchResponse,
+            () => {
+              if (tx)
+                browserDebugLog(tx, "stream complete (from inflight prefetch)");
+              resolveStreamComplete();
+            },
+            signal,
+          );
+        });
+      } else {
+        responsePromise = doFreshFetch();
       }
 
       try {

package/src/browser/navigation-transaction.ts

@@ -7,7 +7,6 @@ import type {
 import { generateHistoryKey } from "./navigation-store.js";
 import {
   handleNavigationStart,
-  handleNavigationEnd,
   ensureHistoryKey,
 } from "./scroll-restoration.js";
 import type { EventController, NavigationHandle } from "./event-controller.js";
@@ -81,11 +80,12 @@ export interface BoundTransaction {
   readonly currentUrl: string;
   /** 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(
     segmentIds: string[],
     segments: ResolvedSegment[],
     overrides?: BoundCommitOverrides,
-  ): void;
+  ): { scroll?: boolean };
 }
 
 /**
@@ -93,7 +93,7 @@ export interface BoundTransaction {
  * Uses the event controller handle for lifecycle management
  */
 interface NavigationTransaction extends Disposable {
-  commit(options: CommitOptions): void;
+  commit(options: CommitOptions): { scroll?: boolean };
   with(
     options: Omit<CommitOptions, "segmentIds" | "segments">,
   ): BoundTransaction;
@@ -120,7 +120,7 @@ export function createNavigationTransaction(
   /**
    * Commit the navigation - updates store and URL atomically
    */
-  function commit(opts: CommitOptions): void {
+  function commit(opts: CommitOptions): { scroll?: boolean } {
     committed = true;
 
     const {
@@ -150,7 +150,7 @@ export function createNavigationTransaction(
       // Without this, the entry lingers and weakens state-machine invariants.
       handle.complete(parsedUrl);
       debugLog("[Browser] Cache-only commit, historyKey:", historyKey);
-      return;
+      return { scroll: false };
     }
 
     // Save current scroll position before navigating
@@ -172,7 +172,7 @@ export function createNavigationTransaction(
       debugLog("[Browser] Store updated (action)");
       // Complete navigation to clear loading state
       handle.complete(parsedUrl);
-      return;
+      return { scroll: false };
     }
 
     // Build history state - include user state, intercept info, and server-set state
@@ -205,14 +205,16 @@ export function createNavigationTransaction(
     // Complete the navigation in event controller (sets idle state, updates location)
     handle.complete(parsedUrl);
 
-    // Handle scroll after navigation
-    handleNavigationEnd({ scroll });
+    // NOTE: Scroll is NOT handled here. The caller (partial-update.ts) handles
+    // scroll AFTER onUpdate() so React has the new content before we scroll.
 
     debugLog(
       "[Browser] Navigation committed, historyKey:",
       historyKey,
       intercept ? "(intercept)" : "",
     );
+
+    return { scroll };
   }
 
   return {
@@ -263,7 +265,7 @@ export function createNavigationTransaction(
             overrides?.state !== undefined ? overrides.state : opts.state;
           // Server-set location state: only from overrides (set by partial-update)
           const serverState = overrides?.serverState;
-          commit({
+          return commit({
             ...opts,
             segmentIds,
             segments,

package/src/browser/partial-update.ts

@@ -19,6 +19,14 @@ import type { BoundTransaction } from "./navigation-transaction.js";
 import { ServerRedirect } from "../errors.js";
 import { debugLog } from "./logging.js";
 import { validateRedirectOrigin } from "./validate-redirect-origin.js";
+import type { NavigationUpdate } from "./types.js";
+
+/** Build a scroll payload from the commit's scroll option */
+function toScrollPayload(
+  scroll: boolean | undefined,
+): NonNullable<NavigationUpdate["scroll"]> {
+  return { enabled: scroll !== false ? scroll : false };
+}
 
 /**
  * Configuration for creating a partial updater
@@ -246,7 +254,10 @@ export function createPartialUpdater(
             forceAwait: true,
           });
 
-          tx.commit(matchedIds, existingSegments);
+          const { scroll: commitScroll } = tx.commit(
+            matchedIds,
+            existingSegments,
+          );
 
           // Include cachedHandleData in metadata so NavigationProvider can restore
           // breadcrumbs and other handle data from cache.
@@ -260,6 +271,7 @@ export function createPartialUpdater(
               ...metadataWithoutHandles,
               cachedHandleData: mode.targetCacheHandleData,
             },
+            scroll: toScrollPayload(commitScroll),
           };
 
           const cachedHasTransition = existingSegments.some(
@@ -290,11 +302,15 @@ export function createPartialUpdater(
             forceAwait: true,
           });
 
-          tx.commit(matchedIds, existingSegments);
+          const { scroll: leaveScroll } = tx.commit(
+            matchedIds,
+            existingSegments,
+          );
 
           onUpdate({
             root: newTree,
             metadata: payload.metadata,
+            scroll: toScrollPayload(leaveScroll),
           });
 
           debugLog("[Browser] Navigation complete (left intercept)");
@@ -426,7 +442,11 @@ export function createPartialUpdater(
         : serverLocationState
           ? { serverState: serverLocationState }
           : undefined;
-      tx.commit(allSegmentIds, reconciled.segments, overrides);
+      const { scroll: navScroll } = tx.commit(
+        allSegmentIds,
+        reconciled.segments,
+        overrides,
+      );
 
       // For stale revalidation: verify history key hasn't changed before updating UI
       if (mode.type === "stale-revalidation") {
@@ -441,8 +461,10 @@ export function createPartialUpdater(
 
       debugLog("[partial-update] updating document");
 
-      // Emit update to trigger React render
+      // Emit update to trigger React render.
+      // Scroll info is included so NavigationProvider applies it after React commits.
       const hasTransition = reconciled.mainSegments.some((s) => s.transition);
+      const scrollPayload = toScrollPayload(navScroll);
 
       if (mode.type === "action" || mode.type === "stale-revalidation") {
         startTransition(() => {
@@ -452,6 +474,7 @@ export function createPartialUpdater(
           onUpdate({
             root: newTree,
             metadata: payload.metadata!,
+            scroll: scrollPayload,
           });
         });
       } else if (hasTransition) {
@@ -462,12 +485,14 @@ export function createPartialUpdater(
           onUpdate({
             root: newTree,
             metadata: payload.metadata!,
+            scroll: scrollPayload,
           });
         });
       } else {
         onUpdate({
           root: newTree,
           metadata: payload.metadata!,
+          scroll: scrollPayload,
         });
       }
 
@@ -494,15 +519,16 @@ export function createPartialUpdater(
       }
 
       const fullUpdateServerState = payload.metadata?.locationState;
-      if (fullUpdateServerState) {
-        tx.commit(segmentIds, segments, { serverState: fullUpdateServerState });
-      } else {
-        tx.commit(segmentIds, segments);
-      }
+      const { scroll: fullScroll } = fullUpdateServerState
+        ? tx.commit(segmentIds, segments, {
+            serverState: fullUpdateServerState,
+          })
+        : tx.commit(segmentIds, segments);
 
       const fullHasTransition = segments.some(
         (s: ResolvedSegment) => s.transition,
       );
+      const fullScrollPayload = toScrollPayload(fullScroll);
 
       if (mode.type === "stale-revalidation") {
         await rawStreamComplete;
@@ -513,6 +539,7 @@ export function createPartialUpdater(
           onUpdate({
             root: newTree,
             metadata: payload.metadata!,
+            scroll: fullScrollPayload,
           });
         });
       } else if (mode.type === "action") {
@@ -523,6 +550,7 @@ export function createPartialUpdater(
           onUpdate({
             root: newTree,
             metadata: payload.metadata!,
+            scroll: fullScrollPayload,
           });
         });
       } else if (fullHasTransition) {
@@ -533,12 +561,14 @@ export function createPartialUpdater(
           onUpdate({
             root: newTree,
             metadata: payload.metadata!,
+            scroll: fullScrollPayload,
           });
         });
       } else {
         onUpdate({
           root: newTree,
           metadata: payload.metadata!,
+          scroll: fullScrollPayload,
         });
       }
 

package/src/browser/prefetch/cache.ts

@@ -6,11 +6,15 @@
  * current page URL) because the server's diff-based response depends on
  * where the user navigates from.
  *
+ * Also tracks in-flight prefetch promises so navigation can reuse a
+ * prefetch that is still downloading rather than starting a duplicate
+ * request. See consumeInflightPrefetch().
+ *
  * Replaces the previous browser HTTP cache approach which was unreliable
  * due to response draining race conditions and browser inconsistencies.
  */
 
-import { cancelAllPrefetches } from "./queue.js";
+import { abortAllPrefetches } from "./queue.js";
 import { invalidateRangoState } from "../rango-state.js";
 
 // Default TTL: 5 minutes. Overridden by initPrefetchCache() with
@@ -44,6 +48,13 @@ interface PrefetchCacheEntry {
 const cache = new Map<string, PrefetchCacheEntry>();
 const inflight = new Set<string>();
 
+/**
+ * In-flight promise map. When a prefetch fetch is in progress, its
+ * Promise<Response | null> is stored here so navigation can await
+ * it instead of starting a duplicate request.
+ */
+const inflightPromises = new Map<string, Promise<Response | null>>();
+
 // Generation counter incremented on each clearPrefetchCache(). Fetches that
 // started before a clear carry a stale generation and must not store their
 // response (the data may be stale due to a server action invalidation).
@@ -78,6 +89,9 @@ export function hasPrefetch(key: string): boolean {
  * Consume a cached prefetch response. Returns null if not found or expired.
  * One-time consumption: the entry is deleted after retrieval.
  * Returns null when caching is disabled (TTL <= 0).
+ *
+ * Does NOT check in-flight prefetches — use consumeInflightPrefetch()
+ * for that (returns a Promise instead of a Response).
  */
 export function consumePrefetch(key: string): Response | null {
   if (cacheTTL <= 0) return null;
@@ -91,6 +105,29 @@ export function consumePrefetch(key: string): Response | null {
   return entry.response;
 }
 
+/**
+ * Consume an in-flight prefetch promise. Returns null if no prefetch is
+ * in-flight for this key. The returned Promise resolves to the buffered
+ * Response (or null if the fetch failed/was aborted).
+ *
+ * One-time consumption: the promise entry is removed so a second call
+ * returns null. The `inflight` set entry is intentionally kept so that
+ * hasPrefetch() continues to return true while the underlying fetch is
+ * still downloading — this prevents prefetchDirect() or other callers
+ * from starting a duplicate request during the handoff window. The
+ * inflight flag is cleaned up naturally by clearPrefetchInflight() in
+ * the fetch's .finally().
+ */
+export function consumeInflightPrefetch(
+  key: string,
+): Promise<Response | null> | null {
+  const promise = inflightPromises.get(key);
+  if (!promise) return null;
+  // Remove the promise (one-time consumption) but keep the inflight flag.
+  inflightPromises.delete(key);
+  return promise;
+}
+
 /**
  * Store a prefetch response in the in-memory cache.
  * The response body must be fully buffered (e.g. via arrayBuffer()) before
@@ -136,19 +173,34 @@ export function markPrefetchInflight(key: string): void {
   inflight.add(key);
 }
 
+/**
+ * Store the in-flight Promise for a prefetch so navigation can reuse it.
+ */
+export function setInflightPromise(
+  key: string,
+  promise: Promise<Response | null>,
+): void {
+  inflightPromises.set(key, promise);
+}
+
 export function clearPrefetchInflight(key: string): void {
   inflight.delete(key);
+  inflightPromises.delete(key);
 }
 
 /**
  * Invalidate all prefetch state. Called when server actions mutate data.
  * Clears the in-memory cache, cancels in-flight prefetches, and rotates
  * the Rango state key so CDN-cached responses are also invalidated.
+ *
+ * Uses abortAllPrefetches (hard cancel) because in-flight responses
+ * may contain stale data after a mutation.
  */
 export function clearPrefetchCache(): void {
   generation++;
   inflight.clear();
+  inflightPromises.clear();
   cache.clear();
-  cancelAllPrefetches();
+  abortAllPrefetches();
   invalidateRangoState();
 }

package/src/browser/prefetch/fetch.ts

@@ -6,12 +6,16 @@
  * real navigation so the server returns a proper diff. The Response is fully
  * buffered and stored in an in-memory cache for instant consumption on
  * subsequent navigation.
+ *
+ * In-flight promises are tracked in the cache so that navigation can reuse
+ * a prefetch that is still downloading instead of starting a duplicate request.
  */
 
 import {
   buildPrefetchKey,
   hasPrefetch,
   markPrefetchInflight,
+  setInflightPromise,
   storePrefetch,
   clearPrefetchInflight,
   currentGeneration,
@@ -52,18 +56,19 @@ function buildPrefetchUrl(
 
 /**
  * Core prefetch fetch logic. Fetches the response, fully buffers the body,
- * and stores it in the in-memory cache. Returns a Promise and accepts an
- * optional AbortSignal for cancellation by the prefetch queue.
+ * and stores it in the in-memory cache. The returned Promise resolves to
+ * the buffered Response (or null on failure) so navigation can reuse
+ * in-flight prefetches via consumeInflightPrefetch().
  */
 function executePrefetchFetch(
   key: string,
   fetchUrl: string,
   signal?: AbortSignal,
-): Promise<void> {
+): Promise<Response | null> {
   const gen = currentGeneration();
   markPrefetchInflight(key);
 
-  return fetch(fetchUrl, {
+  const promise: Promise<Response | null> = fetch(fetchUrl, {
     priority: "low" as RequestPriority,
     signal,
     headers: {
@@ -73,7 +78,7 @@ function executePrefetchFetch(
     },
   })
     .then(async (response) => {
-      if (!response.ok) return;
+      if (!response.ok) return null;
       // Fully buffer the response body so the cached Response is
       // self-contained and doesn't depend on the network connection.
       // This eliminates the race condition where the user clicks before
@@ -84,14 +89,16 @@ function executePrefetchFetch(
         status: response.status,
         statusText: response.statusText,
       });
-      storePrefetch(key, cachedResponse, gen);
-    })
-    .catch(() => {
-      // Silently ignore prefetch failures (including abort)
+      storePrefetch(key, cachedResponse.clone(), gen);
+      return cachedResponse;
     })
+    .catch(() => null)
     .finally(() => {
       clearPrefetchInflight(key);
     });
+
+  setInflightPromise(key, promise);
+  return promise;
 }
 
 /**
@@ -128,8 +135,11 @@ export function prefetchQueued(
   const key = buildPrefetchKey(window.location.href, targetUrl);
   if (hasPrefetch(key)) return key;
   const fetchUrlStr = targetUrl.toString();
-  enqueuePrefetch(key, (signal) =>
-    executePrefetchFetch(key, fetchUrlStr, signal),
-  );
+  enqueuePrefetch(key, (signal) => {
+    // Re-check at execution time: a hover-triggered prefetchDirect may
+    // have started or completed this key while the item sat in the queue.
+    if (hasPrefetch(key)) return Promise.resolve();
+    return executePrefetchFetch(key, fetchUrlStr, signal).then(() => {});
+  });
   return key;
 }

package/src/browser/prefetch/queue.ts

@@ -5,12 +5,22 @@
  * Hover prefetches bypass this queue — they fire directly for immediate response
  * to user intent.
  *
- * All queued/executing prefetches share a single AbortController so they can
- * be cancelled in bulk when a navigation starts.
+ * Draining is deferred to the next animation frame so prefetch network activity
+ * never blocks paint. This applies to both the initial batch and subsequent
+ * batches — every drain cycle yields to the browser first.
+ *
+ * When a navigation starts, queued prefetches are cancelled but executing ones
+ * are left running. Navigation can reuse their in-flight responses via the
+ * prefetch cache's inflight promise map, avoiding duplicate requests.
  */
 
 const MAX_CONCURRENT = 2;
 
+const deferToNextPaint: (fn: () => void) => void =
+  typeof requestAnimationFrame === "function"
+    ? requestAnimationFrame
+    : (fn) => setTimeout(fn, 0);
+
 let active = 0;
 const queue: Array<{
   key: string;
@@ -19,6 +29,7 @@ const queue: Array<{
 const queued = new Set<string>();
 const executing = new Set<string>();
 let abortController: AbortController | null = null;
+let drainScheduled = false;
 
 function startExecution(
   key: string,
@@ -34,6 +45,21 @@ function startExecution(
     if (executing.delete(key)) {
       active--;
     }
+    scheduleDrain();
+  });
+}
+
+/**
+ * Schedule a drain on the next animation frame.
+ * Coalesces multiple drain requests into a single rAF callback so
+ * batch completion doesn't schedule redundant frames.
+ */
+function scheduleDrain(): void {
+  if (drainScheduled) return;
+  if (active >= MAX_CONCURRENT || queue.length === 0) return;
+  drainScheduled = true;
+  deferToNextPaint(() => {
+    drainScheduled = false;
     drain();
   });
 }
@@ -48,8 +74,8 @@ function drain(): void {
 
 /**
  * Enqueue a prefetch for concurrency-limited execution.
- * If below the concurrency limit, executes immediately.
- * Otherwise queues for later execution.
+ * Execution is always deferred to the next animation frame to avoid
+ * blocking paint, even when below the concurrency limit.
  * Deduplicates by key — items already queued or executing are skipped.
  *
  * The executor receives an AbortSignal that is aborted when
@@ -61,20 +87,33 @@ export function enqueuePrefetch(
 ): void {
   if (queued.has(key) || executing.has(key)) return;
 
-  if (active < MAX_CONCURRENT) {
-    startExecution(key, execute);
-  } else {
-    queued.add(key);
-    queue.push({ key, execute });
-  }
+  queued.add(key);
+  queue.push({ key, execute });
+  scheduleDrain();
 }
 
 /**
- * Cancel all in-flight and queued prefetches.
- * Called when a navigation starts — speculative prefetches should not
- * compete with navigation fetches for connection slots.
+ * Cancel queued prefetches. Executing prefetches are left running so
+ * navigation can reuse their in-flight responses (checked via
+ * consumeInflightPrefetch in the prefetch cache). With MAX_CONCURRENT=2
+ * and priority: "low", in-flight prefetches don't meaningfully compete
+ * with navigation fetches under HTTP/2 multiplexing.
+ *
+ * Called when a navigation starts via the NavigationProvider's
+ * event controller subscription.
  */
 export function cancelAllPrefetches(): void {
+  queue.length = 0;
+  queued.clear();
+  drainScheduled = false;
+}
+
+/**
+ * Hard-cancel everything including in-flight prefetches.
+ * Used by clearPrefetchCache (server action invalidation) where
+ * in-flight responses would be stale.
+ */
+export function abortAllPrefetches(): void {
   abortController?.abort();
   abortController = null;
 
@@ -85,4 +124,5 @@ export function cancelAllPrefetches(): void {
   // so active settles at 0 without underflow.
   executing.clear();
   active = 0;
+  drainScheduled = false;
 }

package/src/browser/react/Link.tsx

@@ -279,7 +279,15 @@ export const Link: ForwardRefExoticComponent<
   );
 
   const handleMouseEnter = useCallback(() => {
-    if (resolvedStrategy === "hover" && !isExternal && ctx?.store) {
+    if (
+      (resolvedStrategy === "hover" || resolvedStrategy === "viewport") &&
+      !isExternal &&
+      ctx?.store
+    ) {
+      // For "hover", this is the primary prefetch trigger.
+      // For "viewport", this upgrades/prioritizes a potentially queued
+      // prefetch — prefetchDirect bypasses the queue, and hasPrefetch
+      // deduplicates if the viewport prefetch already completed.
       const segmentState = ctx.store.getSegmentState();
       prefetchDirect(to, segmentState.currentSegmentIds, ctx.version);
     }