@rangojs/router 0.0.0-experimental.28 → 0.0.0-experimental.29-prefetch-cache.29972e92

package/dist/vite/index.js

@@ -1745,7 +1745,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.28",
+  version: "0.0.0-experimental.29-prefetch-cache.29972e92",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.28",
+  "version": "0.0.0-experimental.29-prefetch-cache.29972e92",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

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,111 @@
 /**
- * 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";
 
+const PREFETCH_CACHE_TTL = 30_000; // 30 seconds
+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;
+  const entry = cache.get(key);
+  if (!entry) return false;
+  if (Date.now() - entry.timestamp > PREFETCH_CACHE_TTL) {
+    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.
  */
-export function currentGeneration(): number {
-  return generation;
+export function consumePrefetch(key: string): Response | null {
+  const entry = cache.get(key);
+  if (!entry) return null;
+  if (Date.now() - entry.timestamp > PREFETCH_CACHE_TTL) {
+    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 (fetchGeneration !== generation) return;
+
+  // Evict expired entries
+  const now = Date.now();
+  for (const [k, entry] of cache) {
+    if (now - entry.timestamp > PREFETCH_CACHE_TTL) {
+      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 +117,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) =>