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

package/src/browser/navigation-bridge.ts

@@ -10,6 +10,12 @@ import {
   createNavigationTransaction,
   resolveNavigationState,
 } from "./navigation-transaction.js";
+import { buildHistoryState } from "./history-state.js";
+import {
+  handleNavigationStart,
+  handleNavigationEnd,
+  ensureHistoryKey,
+} from "./scroll-restoration.js";
 
 // addTransitionType is only available in React experimental
 const addTransitionType: ((type: string) => void) | undefined =
@@ -18,7 +24,6 @@ const addTransitionType: ((type: string) => void) | undefined =
 import { setupLinkInterception } from "./link-interceptor.js";
 import { createPartialUpdater } from "./partial-update.js";
 import { generateHistoryKey } from "./navigation-store.js";
-import { handleNavigationEnd } from "./scroll-restoration.js";
 import type { EventController } from "./event-controller.js";
 import { isInterceptOnlyCache } from "./intercept-utils.js";
 import {
@@ -114,6 +119,85 @@ export function createNavigationBridge(
         return;
       }
 
+      // Shallow navigation: skip RSC fetch when revalidate is false
+      // and the pathname hasn't changed (search param / hash only change).
+      if (
+        options?.revalidate === false &&
+        targetUrl.pathname === new URL(window.location.href).pathname
+      ) {
+        // Preserve intercept context from the current history entry so that
+        // popstate uses the correct cache key (:intercept suffix) and restores
+        // the right full-page vs modal semantics.
+        const currentHistoryState = window.history.state;
+        const isIntercept = currentHistoryState?.intercept === true;
+        const interceptSourceUrl = isIntercept
+          ? currentHistoryState?.sourceUrl
+          : undefined;
+
+        const historyKey = generateHistoryKey(url, { intercept: isIntercept });
+
+        // Copy current segments to the new history key so back/forward restores instantly
+        const currentKey = store.getHistoryKey();
+        const currentCache = store.getCachedSegments(currentKey);
+        if (currentCache?.segments) {
+          const currentHandleData = eventController.getHandleState().data;
+          store.cacheSegmentsForHistory(
+            historyKey,
+            currentCache.segments,
+            currentHandleData,
+          );
+        }
+
+        // Save current scroll position before changing URL
+        handleNavigationStart();
+
+        // Snapshot old state before pushState/replaceState overwrites it
+        const oldState = window.history.state;
+
+        // Update browser URL (carry intercept context into history state)
+        const historyState = buildHistoryState(
+          resolvedState,
+          {
+            intercept: isIntercept || undefined,
+            sourceUrl: interceptSourceUrl,
+          },
+          {},
+        );
+        if (options.replace) {
+          window.history.replaceState(historyState, "", url);
+        } else {
+          window.history.pushState(historyState, "", url);
+        }
+
+        // Ensure new history entry has a scroll restoration key
+        ensureHistoryKey();
+
+        // Notify useLocationState() hooks when state changes
+        const hasOldState =
+          oldState &&
+          typeof oldState === "object" &&
+          ("state" in oldState ||
+            Object.keys(oldState).some((k) => k.startsWith("__rsc_ls_")));
+        const hasNewState =
+          historyState &&
+          ("state" in historyState ||
+            Object.keys(historyState).some((k) => k.startsWith("__rsc_ls_")));
+        if (hasOldState || hasNewState) {
+          window.dispatchEvent(new Event("__rsc_locationstate"));
+        }
+
+        // Update store history key so future navigations reference the right cache
+        store.setHistoryKey(historyKey);
+        store.setCurrentUrl(url);
+
+        // Notify hooks — location updates, state stays idle
+        eventController.setLocation(targetUrl);
+
+        // Handle post-navigation scroll
+        handleNavigationEnd({ scroll: options.scroll });
+        return;
+      }
+
       // Only abort pending requests when navigating to a different route
       // Same-route navigation (e.g., /todos -> /todos) should not cancel in-flight actions
       const currentPath = new URL(window.location.href).pathname;
@@ -189,7 +273,7 @@ export function createNavigationBridge(
         !isLeavingIntercept &&
         !options?._skipCache;
 
-      using tx = createNavigationTransaction(store, eventController, url, {
+      const tx = createNavigationTransaction(store, eventController, url, {
         ...options,
         state: resolvedState,
         skipLoadingState: hasUsableCache,
@@ -224,7 +308,7 @@ export function createNavigationBridge(
         );
       } catch (error) {
         // Server-side redirect with location state: the current transaction's
-        // `using` cleanup resets loading state. Re-navigate to the redirect
+        // cleanup resets loading state. Re-navigate to the redirect
         // target carrying the server-set state into history.pushState.
         if (error instanceof ServerRedirect) {
           const redirectUrl = validateRedirectOrigin(
@@ -260,6 +344,8 @@ export function createNavigationBridge(
         }
 
         throw error;
+      } finally {
+        tx[Symbol.dispose]();
       }
     },
 
@@ -269,7 +355,7 @@ export function createNavigationBridge(
     async refresh(): Promise<void> {
       eventController.abortNavigation();
 
-      using tx = createNavigationTransaction(
+      const tx = createNavigationTransaction(
         store,
         eventController,
         window.location.href,
@@ -299,6 +385,8 @@ export function createNavigationBridge(
           return;
         }
         throw error;
+      } finally {
+        tx[Symbol.dispose]();
       }
     },
 
@@ -457,7 +545,7 @@ export function createNavigationBridge(
       }
 
       // Fetch if not cached
-      using tx = createNavigationTransaction(store, eventController, url, {
+      const tx = createNavigationTransaction(store, eventController, url, {
         replace: true,
       });
 
@@ -498,6 +586,8 @@ export function createNavigationBridge(
         }
 
         throw error;
+      } finally {
+        tx[Symbol.dispose]();
       }
     },
 

package/src/browser/navigation-client.ts

@@ -17,6 +17,7 @@ import {
   emptyResponse,
   teeWithCompletion,
 } from "./response-adapter.js";
+import { buildPrefetchKey, consumePrefetch } from "./prefetch/cache.js";
 
 /**
  * Create a navigation client for fetching RSC payloads
@@ -24,21 +25,12 @@ import {
  * The client handles building URLs with RSC parameters and
  * deserializing the response using the RSC runtime.
  *
+ * Checks the in-memory prefetch cache before making a network request.
+ * The cache key is source-dependent (includes the previous URL) so
+ * prefetch responses match the exact diff the server would produce.
+ *
  * @param deps - RSC browser dependencies (createFromFetch)
  * @returns NavigationClient instance
- *
- * @example
- * ```typescript
- * import { createFromFetch } from "@vitejs/plugin-rsc/browser";
- *
- * const client = createNavigationClient({ createFromFetch });
- *
- * const payload = await client.fetchPartial({
- *   targetUrl: "/shop/products",
- *   segmentIds: ["root", "shop"],
- *   previousUrl: "/",
- * });
- * ```
  */
 export function createNavigationClient(
   deps: Pick<RscBrowserDependencies, "createFromFetch">,
@@ -47,8 +39,9 @@ export function createNavigationClient(
     /**
      * Fetch a partial RSC payload for navigation
      *
-     * Sends current segment IDs to the server so it can determine
-     * which segments need to be re-rendered (diff).
+     * First checks the in-memory prefetch cache for a matching entry.
+     * If found, uses the cached response instantly. Otherwise sends
+     * current segment IDs to the server for diff-based rendering.
      *
      * @param options - Fetch options
      * @returns RSC payload with segments and metadata, plus stream completion promise
@@ -80,7 +73,8 @@ export function createNavigationClient(
         });
       }
 
-      // Build fetch URL with partial rendering params
+      // Build fetch URL with partial rendering params (used for both
+      // cache key lookup and actual fetch if cache misses)
       const fetchUrl = new URL(targetUrl, window.location.origin);
       fetchUrl.searchParams.set("_rsc_partial", "true");
       fetchUrl.searchParams.set("_rsc_segments", segmentIds.join(","));
@@ -90,11 +84,17 @@ export function createNavigationClient(
       if (version) {
         fetchUrl.searchParams.set("_rsc_v", version);
       }
-      if (tx) {
-        browserDebugLog(tx, "fetching", {
-          path: `${fetchUrl.pathname}${fetchUrl.search}`,
-        });
-      }
+
+      // Check in-memory prefetch cache before making a network request.
+      // The cache key includes the source URL (previousUrl) because the
+      // 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 cacheKey = buildPrefetchKey(previousUrl, fetchUrl);
+      const cachedResponse =
+        !staleRevalidation && !hmr && !interceptSourceUrl
+          ? consumePrefetch(cacheKey)
+          : null;
 
       // Track when the stream completes
       let resolveStreamComplete: () => void;
@@ -102,63 +102,88 @@ export function createNavigationClient(
         resolveStreamComplete = resolve;
       });
 
-      // Create a response promise that tracks stream completion
-      const responsePromise = fetch(fetchUrl, {
-        headers: {
-          "X-RSC-Router-Client-Path": previousUrl,
-          "X-Rango-State": getRangoState(),
-          ...(tx && { "X-RSC-Router-Request-Id": tx.requestId }),
-          ...(interceptSourceUrl && {
-            "X-RSC-Router-Intercept-Source": interceptSourceUrl,
-          }),
-          ...(hmr && { "X-RSC-HMR": "1" }),
-        },
-        signal,
-      }).then((response) => {
-        // Check for version mismatch - server wants us to reload
-        const reload = extractRscHeaderUrl(response, "X-RSC-Reload");
-        if (reload === "blocked") {
-          resolveStreamComplete();
-          return emptyResponse();
-        }
-        if (reload) {
-          if (tx) {
-            browserDebugLog(tx, "version mismatch, reloading", {
-              reloadUrl: reload.url,
-            });
-          }
-          window.location.href = reload.url;
-          return new Promise<Response>(() => {});
-        }
+      let responsePromise: Promise<Response>;
 
-        // Server-side redirect without state: the server returned 204 with
-        // X-RSC-Redirect instead of a 3xx (which fetch would auto-follow
-        // to a URL rendering full HTML). Throw ServerRedirect so the
-        // navigation bridge catches it and re-navigates with _skipCache.
-        const redirect = extractRscHeaderUrl(response, "X-RSC-Redirect");
-        if (redirect === "blocked") {
-          resolveStreamComplete();
-          return emptyResponse();
+      if (cachedResponse) {
+        if (tx) {
+          browserDebugLog(tx, "prefetch cache hit", { key: cacheKey });
         }
-        if (redirect) {
-          if (tx) {
-            browserDebugLog(tx, "server redirect", {
-              redirectUrl: redirect.url,
-            });
-          }
-          resolveStreamComplete();
-          throw new ServerRedirect(redirect.url, undefined);
+        // 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 (tx) {
+          browserDebugLog(tx, "fetching", {
+            path: `${fetchUrl.pathname}${fetchUrl.search}`,
+          });
         }
 
-        return teeWithCompletion(
-          response,
-          () => {
-            if (tx) browserDebugLog(tx, "stream complete");
-            resolveStreamComplete();
+        responsePromise = fetch(fetchUrl, {
+          headers: {
+            "X-RSC-Router-Client-Path": previousUrl,
+            "X-Rango-State": getRangoState(),
+            ...(tx && { "X-RSC-Router-Request-Id": tx.requestId }),
+            ...(interceptSourceUrl && {
+              "X-RSC-Router-Intercept-Source": interceptSourceUrl,
+            }),
+            ...(hmr && { "X-RSC-HMR": "1" }),
           },
           signal,
-        );
-      });
+        }).then((response) => {
+          // Check for version mismatch - server wants us to reload
+          const reload = extractRscHeaderUrl(response, "X-RSC-Reload");
+          if (reload === "blocked") {
+            resolveStreamComplete();
+            return emptyResponse();
+          }
+          if (reload) {
+            if (tx) {
+              browserDebugLog(tx, "version mismatch, reloading", {
+                reloadUrl: reload.url,
+              });
+            }
+            window.location.href = reload.url;
+            return new Promise<Response>(() => {});
+          }
+
+          // Server-side redirect without state: the server returned 204 with
+          // X-RSC-Redirect instead of a 3xx (which fetch would auto-follow
+          // to a URL rendering full HTML). Throw ServerRedirect so the
+          // navigation bridge catches it and re-navigates with _skipCache.
+          const redirect = extractRscHeaderUrl(response, "X-RSC-Redirect");
+          if (redirect === "blocked") {
+            resolveStreamComplete();
+            return emptyResponse();
+          }
+          if (redirect) {
+            if (tx) {
+              browserDebugLog(tx, "server redirect", {
+                redirectUrl: redirect.url,
+              });
+            }
+            resolveStreamComplete();
+            throw new ServerRedirect(redirect.url, undefined);
+          }
+
+          return teeWithCompletion(
+            response,
+            () => {
+              if (tx) browserDebugLog(tx, "stream complete");
+              resolveStreamComplete();
+            },
+            signal,
+          );
+        });
+      }
 
       try {
         // Deserialize RSC payload

package/src/browser/prefetch/cache.ts

@@ -1,47 +1,135 @@
 /**
- * Prefetch Tracking
+ * Prefetch Cache
  *
- * Tracks in-flight and completed prefetches for deduplication.
- * The actual response caching is handled by the browser's HTTP cache
- * via Vary: X-Rango-State.
+ * In-memory cache storing prefetch 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.
+ *
+ * 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 { invalidateRangoState } from "../rango-state.js";
 
+// Default TTL: 5 minutes. Overridden by initPrefetchCache() with
+// the server-configured prefetchCacheTTL from router options.
+// 0 disables the in-memory cache entirely.
+let cacheTTL = 300_000;
+
+/**
+ * Initialize the prefetch cache with the configured TTL.
+ * Called once at app startup with the value from server metadata.
+ * A TTL of 0 disables the in-memory cache and all prefetching.
+ */
+export function initPrefetchCache(ttlMs: number): void {
+  cacheTTL = ttlMs;
+}
+
+/**
+ * Check if the prefetch cache is disabled (TTL <= 0).
+ * When disabled, no prefetch requests should be issued.
+ */
+export function isPrefetchCacheDisabled(): boolean {
+  return cacheTTL <= 0;
+}
+const MAX_PREFETCH_CACHE_SIZE = 50;
+
+interface PrefetchCacheEntry {
+  response: Response;
+  timestamp: number;
+}
+
+const cache = new Map<string, PrefetchCacheEntry>();
 const inflight = new Set<string>();
-const prefetched = new Set<string>();
 
 // Generation counter incremented on each clearPrefetchCache(). Fetches that
-// started before a clear carry a stale generation and must not re-add their
-// key to the prefetched set (the browser HTTP cache entry is already invalid
-// due to Rango-State rotation).
+// 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).
 let generation = 0;
 
 /**
- * Check if a prefetch is already in-flight or completed for the given key.
+ * Build a source-dependent cache key.
+ * Includes the source page href so the same target prefetched from
+ * different pages gets separate entries — the server response varies
+ * based on the source page context (diff-based rendering).
+ */
+export function buildPrefetchKey(sourceHref: string, targetUrl: URL): string {
+  return sourceHref + "\0" + targetUrl.pathname + targetUrl.search;
+}
+
+/**
+ * Check if a prefetch is already cached, in-flight, or queued for the given key.
  */
 export function hasPrefetch(key: string): boolean {
-  return prefetched.has(key) || inflight.has(key);
+  if (inflight.has(key)) return true;
+  if (cacheTTL <= 0) return false;
+  const entry = cache.get(key);
+  if (!entry) return false;
+  if (Date.now() - entry.timestamp > cacheTTL) {
+    cache.delete(key);
+    return false;
+  }
+  return true;
 }
 
 /**
- * Capture the current generation. The returned value is passed to
- * markPrefetched so it can detect stale completions.
+ * 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).
  */
-export function currentGeneration(): number {
-  return generation;
+export function consumePrefetch(key: string): Response | null {
+  if (cacheTTL <= 0) return null;
+  const entry = cache.get(key);
+  if (!entry) return null;
+  if (Date.now() - entry.timestamp > cacheTTL) {
+    cache.delete(key);
+    return null;
+  }
+  cache.delete(key);
+  return entry.response;
 }
 
 /**
- * Mark a key as successfully prefetched (response is in browser HTTP cache).
- * Skips if the generation has changed since the fetch started (cache was
- * invalidated mid-flight, so the response uses a stale X-Rango-State).
+ * 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.
+ *
+ * Skips storage if the generation has changed since the fetch started
+ * (a server action invalidated the cache mid-flight).
  */
-export function markPrefetched(key: string, fetchGeneration: number): void {
-  if (fetchGeneration === generation) {
-    prefetched.add(key);
+export function storePrefetch(
+  key: string,
+  response: Response,
+  fetchGeneration: number,
+): void {
+  if (cacheTTL <= 0) return;
+  if (fetchGeneration !== generation) return;
+
+  // Evict expired entries
+  const now = Date.now();
+  for (const [k, entry] of cache) {
+    if (now - entry.timestamp > cacheTTL) {
+      cache.delete(k);
+    }
+  }
+
+  // FIFO eviction if at capacity
+  if (cache.size >= MAX_PREFETCH_CACHE_SIZE) {
+    const oldest = cache.keys().next().value;
+    if (oldest) cache.delete(oldest);
   }
+
+  cache.set(key, { response, timestamp: now });
+}
+
+/**
+ * Capture the current generation. The returned value is passed to
+ * storePrefetch so it can detect stale completions.
+ */
+export function currentGeneration(): number {
+  return generation;
 }
 
 export function markPrefetchInflight(key: string): void {
@@ -53,15 +141,14 @@ export function clearPrefetchInflight(key: string): void {
 }
 
 /**
- * Invalidate prefetch state. Called when server actions mutate data.
- * Updates the localStorage state key so next fetch has a different
- * X-Rango-State value, causing Vary mismatch in browser HTTP cache.
- * Also cancels any in-flight or queued speculative prefetches.
+ * 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.
  */
 export function clearPrefetchCache(): void {
   generation++;
   inflight.clear();
-  prefetched.clear();
+  cache.clear();
   cancelAllPrefetches();
   invalidateRangoState();
 }

package/src/browser/prefetch/fetch.ts

@@ -2,15 +2,17 @@
  * Prefetch Fetch
  *
  * Fetch-based prefetch logic used by Link (hover/viewport/render strategies)
- * and useRouter().prefetch(). Sends low-priority fetch requests with
- * X-Rango-State and X-Rango-Prefetch headers so the browser HTTP cache
- * can serve the response on subsequent navigation.
+ * and useRouter().prefetch(). Sends the same headers and segment IDs as a
+ * 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.
  */
 
 import {
+  buildPrefetchKey,
   hasPrefetch,
   markPrefetchInflight,
-  markPrefetched,
+  storePrefetch,
   clearPrefetchInflight,
   currentGeneration,
 } from "./cache.js";
@@ -20,9 +22,9 @@ import { shouldPrefetch } from "./policy.js";
 
 /**
  * Build an RSC partial URL for prefetching.
- * Includes _rsc_v for version mismatch detection when available.
- * Returns null for malformed or cross-origin URLs to prevent
- * leaking router headers to external origins.
+ * Includes _rsc_segments so the server can diff against currently mounted
+ * segments, and _rsc_v for version mismatch detection.
+ * Returns null for malformed or cross-origin URLs.
  */
 function buildPrefetchUrl(
   url: string,
@@ -49,18 +51,9 @@ function buildPrefetchUrl(
 }
 
 /**
- * Build the dedup key for prefetch tracking.
- * Includes the source page pathname so the same target prefetched from
- * different pages gets separate entries — the server response varies on
- * X-RSC-Router-Client-Path (source page context).
- */
-function buildPrefetchKey(targetUrl: URL): string {
-  return window.location.href + "\0" + targetUrl.pathname + targetUrl.search;
-}
-
-/**
- * Core prefetch fetch logic. Returns a Promise and accepts an optional
- * AbortSignal for cancellation by the prefetch queue.
+ * 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.
  */
 function executePrefetchFetch(
   key: string,
@@ -79,14 +72,19 @@ function executePrefetchFetch(
       "X-Rango-Prefetch": "1",
     },
   })
-    .then((response) => {
-      // Drain body to ensure full download for browser HTTP cache.
-      // pipeTo avoids decoding the stream into a JS string (unlike .text()).
-      if (response.ok && response.body) {
-        return response.body
-          .pipeTo(new WritableStream())
-          .then(() => markPrefetched(key, gen));
-      }
+    .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, {
+        headers: response.headers,
+        status: response.status,
+        statusText: response.statusText,
+      });
+      storePrefetch(key, cachedResponse, gen);
     })
     .catch(() => {
       // Silently ignore prefetch failures (including abort)
@@ -97,7 +95,7 @@ function executePrefetchFetch(
 }
 
 /**
- * Prefetch (direct): fetch with low priority and store in browser HTTP cache.
+ * Prefetch (direct): fetch with low priority and store in in-memory cache.
  * Used by hover strategy -- fires immediately without queueing.
  */
 export function prefetchDirect(
@@ -109,7 +107,7 @@ export function prefetchDirect(
 
   const targetUrl = buildPrefetchUrl(url, segmentIds, version);
   if (!targetUrl) return;
-  const key = buildPrefetchKey(targetUrl);
+  const key = buildPrefetchKey(window.location.href, targetUrl);
   if (hasPrefetch(key)) return;
   executePrefetchFetch(key, targetUrl.toString());
 }
@@ -127,7 +125,7 @@ export function prefetchQueued(
   if (!shouldPrefetch()) return "";
   const targetUrl = buildPrefetchUrl(url, segmentIds, version);
   if (!targetUrl) return "";
-  const key = buildPrefetchKey(targetUrl);
+  const key = buildPrefetchKey(window.location.href, targetUrl);
   if (hasPrefetch(key)) return key;
   const fetchUrlStr = targetUrl.toString();
   enqueuePrefetch(key, (signal) =>