@rangojs/router 0.0.0-experimental.1b930379 → 0.0.0-experimental.1fa245e2

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
@@ -31,8 +39,8 @@ export interface PartialUpdateConfig {
     segments: ResolvedSegment[],
     options?: RenderSegmentsOptions,
   ) => Promise<ReactNode> | ReactNode;
-  /** RSC version received from server (from initial payload metadata) */
-  version?: string;
+  /** RSC version getter — returns the current version (may change after HMR) */
+  getVersion?: () => string | undefined;
 }
 
 /**
@@ -96,7 +104,13 @@ export type PartialUpdater = (
 export function createPartialUpdater(
   config: PartialUpdateConfig,
 ): PartialUpdater {
-  const { store, client, onUpdate, renderSegments, version } = config;
+  const {
+    store,
+    client,
+    onUpdate,
+    renderSegments,
+    getVersion = () => undefined,
+  } = config;
 
   /**
    * Get current page's cached segments as an array
@@ -185,7 +199,8 @@ export function createPartialUpdater(
       // (action redirect sends empty segments for a fresh render).
       staleRevalidation:
         mode.type === "stale-revalidation" || segments.length === 0,
-      version,
+      version: getVersion(),
+      routerId: store.getRouterId?.(),
     });
     // Mark navigation as streaming (response received, now parsing RSC).
     // Called after fetchPartial so pendingUrl stays set during the network wait,
@@ -198,6 +213,21 @@ export function createPartialUpdater(
       streamingToken.end();
     });
 
+    // Detect app switch: if routerId changed, the navigation crossed into
+    // a different router (e.g., via host router path mount). Downgrade
+    // partial to full so the entire tree is replaced without reconciliation
+    // against stale segments from the previous app.
+    if (payload.metadata?.routerId) {
+      const prevRouterId = store.getRouterId?.();
+      if (prevRouterId && prevRouterId !== payload.metadata.routerId) {
+        debugLog(
+          `[Browser] App switch detected (${prevRouterId} → ${payload.metadata.routerId}), forcing full update`,
+        );
+        payload.metadata.isPartial = false;
+      }
+      store.setRouterId?.(payload.metadata.routerId);
+    }
+
     // Handle server-side redirect with state
     if (payload.metadata?.redirect) {
       if (signal?.aborted) {
@@ -246,7 +276,21 @@ export function createPartialUpdater(
             forceAwait: true,
           });
 
-          tx.commit(matchedIds, existingSegments);
+          const { scroll: commitScroll } = tx.commit(
+            matchedIds,
+            existingSegments,
+          );
+
+          // tx.commit() cached the source page's handleData because
+          // eventController hasn't been updated yet. Overwrite with the
+          // correct cached handleData to prevent cache corruption on
+          // subsequent navigations to this same URL.
+          if (mode.targetCacheHandleData) {
+            store.updateCacheHandleData(
+              store.getHistoryKey(),
+              mode.targetCacheHandleData,
+            );
+          }
 
           // Include cachedHandleData in metadata so NavigationProvider can restore
           // breadcrumbs and other handle data from cache.
@@ -260,6 +304,7 @@ export function createPartialUpdater(
               ...metadataWithoutHandles,
               cachedHandleData: mode.targetCacheHandleData,
             },
+            scroll: toScrollPayload(commitScroll),
           };
 
           const cachedHasTransition = existingSegments.some(
@@ -290,11 +335,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)");
@@ -411,8 +460,10 @@ export function createPartialUpdater(
         }
       }
 
-      // Commit navigation - transaction handles all store mutations atomically
-      const allSegmentIds = reconciled.segments.map((s) => s.id);
+      // Commit navigation - use server's matched as the authoritative segment ID list.
+      // reconciled.segments may be missing IDs (e.g., loader segments not in diff or cache)
+      // but the server's matched always includes all expected segment IDs.
+      const allSegmentIds = matchedIds;
       const serverLocationState = payload.metadata?.locationState;
       const overrides: CommitOverrides | undefined = isInterceptResponse
         ? {
@@ -424,7 +475,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") {
@@ -439,8 +494,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(() => {
@@ -450,6 +507,7 @@ export function createPartialUpdater(
           onUpdate({
             root: newTree,
             metadata: payload.metadata!,
+            scroll: scrollPayload,
           });
         });
       } else if (hasTransition) {
@@ -460,12 +518,14 @@ export function createPartialUpdater(
           onUpdate({
             root: newTree,
             metadata: payload.metadata!,
+            scroll: scrollPayload,
           });
         });
       } else {
         onUpdate({
           root: newTree,
           metadata: payload.metadata!,
+          scroll: scrollPayload,
         });
       }
 
@@ -492,15 +552,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;
@@ -511,6 +572,7 @@ export function createPartialUpdater(
           onUpdate({
             root: newTree,
             metadata: payload.metadata!,
+            scroll: fullScrollPayload,
           });
         });
       } else if (mode.type === "action") {
@@ -521,6 +583,7 @@ export function createPartialUpdater(
           onUpdate({
             root: newTree,
             metadata: payload.metadata!,
+            scroll: fullScrollPayload,
           });
         });
       } else if (fullHasTransition) {
@@ -531,12 +594,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

@@ -1,16 +1,20 @@
 /**
  * Prefetch Cache
  *
- * In-memory cache storing prefetch Response objects for instant cache hits
+ * In-memory cache storing prefetched Response objects for instant cache hits
  * on subsequent navigation. Cache key is source-dependent (includes the
  * current page URL) because the server's diff-based response depends on
  * where the user navigates from.
  *
+ * Also tracks in-flight prefetch promises. Each promise resolves to the
+ * navigation branch of a tee'd Response, allowing navigation to adopt a
+ * still-downloading prefetch without reparsing or buffering the body.
+ *
  * 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,10 +105,33 @@ 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
- * storing, so the cached Response is self-contained and network-independent.
+ * The response should be a clone() of the original so the caller can
+ * still consume the body. The clone's body streams independently.
  *
  * Skips storage if the generation has changed since the fetch started
  * (a server action invalidated the cache mid-flight).
@@ -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,
@@ -30,6 +34,7 @@ function buildPrefetchUrl(
   url: string,
   segmentIds: string[],
   version?: string,
+  routerId?: string,
 ): URL | null {
   let targetUrl: URL;
   try {
@@ -47,23 +52,27 @@ function buildPrefetchUrl(
   if (version) {
     targetUrl.searchParams.set("_rsc_v", version);
   }
+  if (routerId) {
+    targetUrl.searchParams.set("_rsc_rid", routerId);
+  }
   return targetUrl;
 }
 
 /**
- * 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.
+ * Core prefetch fetch logic. Fetches the response, tees the body, and stores
+ * one branch in the in-memory cache. The returned Promise resolves to the
+ * sibling navigation branch (or null on failure) so navigation can safely
+ * reuse an in-flight prefetch 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: {
@@ -72,26 +81,27 @@ function executePrefetchFetch(
       "X-Rango-Prefetch": "1",
     },
   })
-    .then(async (response) => {
-      if (!response.ok) return;
-      // 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
-      // the response body has been fully downloaded.
-      const buffer = await response.arrayBuffer();
-      const cachedResponse = new Response(buffer, {
+    .then((response) => {
+      if (!response.ok) return null;
+      // Don't buffer with arrayBuffer() — that blocks until the entire
+      // body downloads, defeating streaming for slow loaders.
+      // Tee the body: one branch for navigation, one for cache storage.
+      const [navStream, cacheStream] = response.body!.tee();
+      const responseInit = {
         headers: response.headers,
         status: response.status,
         statusText: response.statusText,
-      });
-      storePrefetch(key, cachedResponse, gen);
-    })
-    .catch(() => {
-      // Silently ignore prefetch failures (including abort)
+      };
+      storePrefetch(key, new Response(cacheStream, responseInit), gen);
+      return new Response(navStream, responseInit);
     })
+    .catch(() => null)
     .finally(() => {
       clearPrefetchInflight(key);
     });
+
+  setInflightPromise(key, promise);
+  return promise;
 }
 
 /**
@@ -102,10 +112,11 @@ export function prefetchDirect(
   url: string,
   segmentIds: string[],
   version?: string,
+  routerId?: string,
 ): void {
   if (!shouldPrefetch()) return;
 
-  const targetUrl = buildPrefetchUrl(url, segmentIds, version);
+  const targetUrl = buildPrefetchUrl(url, segmentIds, version, routerId);
   if (!targetUrl) return;
   const key = buildPrefetchKey(window.location.href, targetUrl);
   if (hasPrefetch(key)) return;
@@ -121,15 +132,19 @@ export function prefetchQueued(
   url: string,
   segmentIds: string[],
   version?: string,
+  routerId?: string,
 ): string {
   if (!shouldPrefetch()) return "";
-  const targetUrl = buildPrefetchUrl(url, segmentIds, version);
+  const targetUrl = buildPrefetchUrl(url, segmentIds, version, routerId);
   if (!targetUrl) return "";
   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,11 +5,19 @@
  * 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 waits for an idle main-thread moment and for viewport images to
+ * finish loading, so prefetch fetch() calls never compete with critical
+ * resources for the browser's connection pool.
+ *
+ * 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.
  */
 
+import { wait, waitForIdle, waitForViewportImages } from "./resource-ready.js";
+
 const MAX_CONCURRENT = 2;
+const IMAGE_WAIT_TIMEOUT = 2000;
 
 let active = 0;
 const queue: Array<{
@@ -18,7 +26,9 @@ const queue: Array<{
 }> = [];
 const queued = new Set<string>();
 const executing = new Set<string>();
-let abortController: AbortController | null = null;
+const abortControllers = new Map<string, AbortController>();
+let drainScheduled = false;
+let drainGeneration = 0;
 
 function startExecution(
   key: string,
@@ -26,18 +36,49 @@ function startExecution(
 ): void {
   active++;
   executing.add(key);
-  abortController ??= new AbortController();
-  execute(abortController.signal).finally(() => {
+  const ac = new AbortController();
+  abortControllers.set(key, ac);
+  execute(ac.signal).finally(() => {
+    abortControllers.delete(key);
     // Only decrement if this key wasn't already cleared by cancelAllPrefetches.
     // Without this guard, cancelled tasks' .finally() would underflow active
     // below zero, breaking the MAX_CONCURRENT guarantee.
     if (executing.delete(key)) {
       active--;
     }
-    drain();
+    scheduleDrain();
   });
 }
 
+/**
+ * Schedule a drain after the browser is idle and viewport images are loaded.
+ * Coalesces multiple drain requests into a single deferred callback so
+ * batch completion doesn't schedule redundant waits.
+ *
+ * The two-step wait ensures prefetch fetch() calls don't compete with
+ * images for the browser's connection pool:
+ * 1. waitForIdle — yield until the main thread has a quiet moment
+ * 2. waitForViewportImages OR 2s timeout — yield until visible images
+ *    finish loading, but don't let slow/broken images block indefinitely
+ */
+function scheduleDrain(): void {
+  if (drainScheduled) return;
+  if (active >= MAX_CONCURRENT || queue.length === 0) return;
+  drainScheduled = true;
+  const gen = drainGeneration;
+  waitForIdle()
+    .then(() =>
+      Promise.race([waitForViewportImages(), wait(IMAGE_WAIT_TIMEOUT)]),
+    )
+    .then(() => {
+      drainScheduled = false;
+      // Stale drain: a cancel/abort happened while we were waiting.
+      // A fresh scheduleDrain will be called by whatever enqueues next.
+      if (gen !== drainGeneration) return;
+      if (queue.length > 0) drain();
+    });
+}
+
 function drain(): void {
   while (active < MAX_CONCURRENT && queue.length > 0) {
     const item = queue.shift()!;
@@ -48,9 +89,10 @@ function drain(): void {
 
 /**
  * Enqueue a prefetch for concurrency-limited execution.
- * If below the concurrency limit, executes immediately.
- * Otherwise queues for later execution.
- * Deduplicates by key — items already queued or executing are skipped.
+ * Execution is deferred until the browser is idle and viewport images
+ * have finished loading, so prefetches never compete with critical
+ * resources. Deduplicates by key — items already queued or executing
+ * are skipped.
  *
  * The executor receives an AbortSignal that is aborted when
  * cancelAllPrefetches() is called (e.g. on navigation start).
@@ -61,22 +103,50 @@ 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 queued prefetches and abort in-flight ones that don't match
+ * the current navigation target. If `keepUrl` is provided, the
+ * executing prefetch whose key contains that URL is kept alive so
+ * navigation can reuse its response via consumeInflightPrefetch.
+ *
+ * Called when a navigation starts via the NavigationProvider's
+ * event controller subscription.
+ */
+export function cancelAllPrefetches(keepUrl?: string | null): void {
+  queue.length = 0;
+  queued.clear();
+  drainScheduled = false;
+  drainGeneration++;
+
+  // Abort in-flight prefetches that aren't for the navigation target.
+  // Keys use format "sourceHref\0targetPathname+search" — match the
+  // target portion (after \0) against keepUrl.
+  for (const [key, ac] of abortControllers) {
+    const target = key.split("\0")[1];
+    if (keepUrl && target && keepUrl.startsWith(target)) continue;
+    ac.abort();
+    abortControllers.delete(key);
+    if (executing.delete(key)) {
+      active--;
+    }
   }
 }
 
 /**
- * Cancel all in-flight and queued prefetches.
- * Called when a navigation starts — speculative prefetches should not
- * compete with navigation fetches for connection slots.
+ * Hard-cancel everything including in-flight prefetches.
+ * Used by clearPrefetchCache (server action invalidation) where
+ * in-flight responses would be stale.
  */
-export function cancelAllPrefetches(): void {
-  abortController?.abort();
-  abortController = null;
+export function abortAllPrefetches(): void {
+  for (const ac of abortControllers.values()) {
+    ac.abort();
+  }
+  abortControllers.clear();
 
   queue.length = 0;
   queued.clear();
@@ -85,4 +155,6 @@ export function cancelAllPrefetches(): void {
   // so active settles at 0 without underflow.
   executing.clear();
   active = 0;
+  drainScheduled = false;
+  drainGeneration++;
 }