@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.135c6902

package/src/browser/navigation-client.ts

@@ -5,12 +5,23 @@ import type {
   RscPayload,
   RscBrowserDependencies,
 } from "./types.js";
-import { NetworkError, isNetworkError } from "../errors.js";
+import { NetworkError, ServerRedirect, isNetworkError } from "../errors.js";
 import {
   browserDebugLog,
   isBrowserDebugEnabled,
   startBrowserTransaction,
 } from "./logging.js";
+import { getRangoState } from "./rango-state.js";
+import {
+  extractRscHeaderUrl,
+  emptyResponse,
+  teeWithCompletion,
+} from "./response-adapter.js";
+import {
+  buildPrefetchKey,
+  consumeInflightPrefetch,
+  consumePrefetch,
+} from "./prefetch/cache.js";
 
 /**
  * Create a navigation client for fetching RSC payloads
@@ -18,32 +29,23 @@ 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">,
 ): NavigationClient {
-
   return {
     /**
      * 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
@@ -75,7 +77,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(","));
@@ -86,80 +89,134 @@ export function createNavigationClient(
         fetchUrl.searchParams.set("_rsc_v", version);
       }
 
-      if (tx) {
-        browserDebugLog(tx, "fetching", {
-          path: `${fetchUrl.pathname}${fetchUrl.search}`,
-        });
-      }
-
+      // Check completed 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 canUsePrefetch = !staleRevalidation && !hmr && !interceptSourceUrl;
+      const cacheKey = buildPrefetchKey(previousUrl, fetchUrl);
+      const cachedResponse = canUsePrefetch ? consumePrefetch(cacheKey) : null;
+      const inflightResponsePromise = canUsePrefetch
+        ? consumeInflightPrefetch(cacheKey)
+        : null;
       // Track when the stream completes
       let resolveStreamComplete: () => void;
       const streamComplete = new Promise<void>((resolve) => {
         resolveStreamComplete = resolve;
       });
 
-      // Create a response promise that tracks stream completion
-      const responsePromise = fetch(fetchUrl, {
-        headers: {
-          "X-RSC-Router-Client-Path": previousUrl,
-          ...(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 reloadUrl = response.headers.get("X-RSC-Reload");
-        if (reloadUrl) {
-          if (tx) {
-            browserDebugLog(tx, "version mismatch, reloading", { reloadUrl });
-          }
-          window.location.href = reloadUrl;
-          // Return a never-resolving promise to prevent further processing
-          return new Promise<Response>(() => {});
+      /** Start a fresh navigation fetch (no cache / inflight hit). */
+      const doFreshFetch = (): Promise<Response> => {
+        if (tx) {
+          browserDebugLog(tx, "fetching", {
+            path: `${fetchUrl.pathname}${fetchUrl.search}`,
+          });
         }
 
-        if (!response.body) {
-          // No body means stream is already complete
-          resolveStreamComplete();
-          return response;
-        }
+        return 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>(() => {});
+          }
 
-        // Tee the stream: one for RSC runtime, one for tracking completion
-        const [rscStream, trackingStream] = response.body.tee();
+          // 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);
+          }
 
-        // Consume the tracking stream to detect when it closes
-        (async () => {
-          const reader = trackingStream.getReader();
+          return teeWithCompletion(
+            response,
+            () => {
+              if (tx) browserDebugLog(tx, "stream complete");
+              resolveStreamComplete();
+            },
+            signal,
+          );
+        });
+      };
 
-          // Cancel tracking if navigation is aborted
-          const onAbort = reader.cancel.bind(reader);
-          signal?.addEventListener("abort", onAbort, { once: true });
+      let responsePromise: Promise<Response>;
 
-          try {
-            while (true) {
-              const { done } = await reader.read();
-              if (done) break;
-            }
-          } finally {
-            signal?.removeEventListener("abort", onAbort);
-            reader.releaseLock();
+      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 (inflightResponsePromise) {
+        if (tx) {
+          browserDebugLog(tx, "reusing inflight prefetch", { key: cacheKey });
+        }
+        responsePromise = inflightResponsePromise.then(async (response) => {
+          if (!response) {
             if (tx) {
-              browserDebugLog(tx, "stream complete");
+              browserDebugLog(tx, "inflight prefetch unavailable, refetching");
             }
-            resolveStreamComplete();
+            return doFreshFetch();
           }
-        })();
 
-        // Return response with the RSC stream
-        return new Response(rscStream, {
-          headers: response.headers,
-          status: response.status,
-          statusText: response.statusText,
+          return teeWithCompletion(
+            response,
+            () => {
+              if (tx) {
+                browserDebugLog(tx, "stream complete (from inflight prefetch)");
+              }
+              resolveStreamComplete();
+            },
+            signal,
+          );
         });
-      });
+      } else {
+        responsePromise = doFreshFetch();
+      }
 
       try {
         // Deserialize RSC payload

package/src/browser/navigation-store.ts

@@ -12,6 +12,7 @@ import type {
   ActionStateListener,
   HandleData,
 } from "./types.js";
+import { clearPrefetchCache } from "./prefetch/cache.js";
 
 /**
  * Default action state (idle with no payload)
@@ -88,7 +89,7 @@ export interface HistoryKeyOptions {
  */
 export function generateHistoryKey(
   url?: string,
-  options?: HistoryKeyOptions
+  options?: HistoryKeyOptions,
 ): string {
   if (!url) {
     url = typeof window !== "undefined" ? window.location.href : "/";
@@ -182,7 +183,7 @@ function createLocation(loc: { href: string }): NavigationLocation {
  * ```
  */
 export function createNavigationStore(
-  config?: NavigationStoreConfig
+  config?: NavigationStoreConfig,
 ): NavigationStore {
   // Default location from window or config
   const defaultLocation: NavigationLocation =
@@ -270,7 +271,7 @@ export function createNavigationStore(
    */
   function createDebouncedNotifier<T extends (...args: any[]) => void>(
     fn: T,
-    ms: number = 20
+    ms: number = 20,
   ): T {
     let timeout: ReturnType<typeof setTimeout> | null = null;
     return ((...args: Parameters<T>) => {
@@ -297,7 +298,7 @@ export function createNavigationStore(
         setTimeout(() => {
           timeouts.delete(key);
           fn(key, ...args);
-        }, ms)
+        }, ms),
       );
     }) as T;
   }
@@ -312,7 +313,7 @@ export function createNavigationStore(
       if (listeners) {
         listeners.forEach((listener) => listener(state));
       }
-    }
+    },
   );
 
   /**
@@ -320,6 +321,7 @@ export function createNavigationStore(
    */
   function clearCacheInternal(): void {
     historyCache.length = 0;
+    clearPrefetchCache();
   }
 
   /**
@@ -329,13 +331,13 @@ export function createNavigationStore(
     for (let i = 0; i < historyCache.length; i++) {
       historyCache[i][2] = true;
     }
+    clearPrefetchCache();
   }
 
   /**
    * Clear the history cache and broadcast to other tabs
    */
   function clearCacheAndBroadcast(): void {
-    console.log("[Browser] Clearing cache and broadcasting to other tabs");
     clearCacheInternal();
     broadcastInvalidation();
   }
@@ -344,9 +346,6 @@ export function createNavigationStore(
    * Mark cache as stale and broadcast to other tabs
    */
   function markStaleAndBroadcast(): void {
-    console.log(
-      "[Browser] Marking cache as stale and broadcasting to other tabs"
-    );
     markCacheAsStaleInternal();
     broadcastInvalidation();
   }
@@ -369,14 +368,6 @@ export function createNavigationStore(
         path: currentPath,
         segmentIds: currentSegmentIds,
       });
-      console.log(
-        "[Browser] Broadcast sent for path:",
-        currentPath,
-        "segments:",
-        currentSegmentIds.join(", ")
-      );
-    } else {
-      console.warn("[Browser] No BroadcastChannel available");
     }
   }
 
@@ -393,7 +384,7 @@ export function createNavigationStore(
           // Check for shared segments between tabs
           // Routes sharing any segment (layout, loader, etc.) should invalidate together
           const hasSharedSegment = mutatedSegmentIds.some((id) =>
-            currentSegmentIds.includes(id)
+            currentSegmentIds.includes(id),
           );
 
           if (!hasSharedSegment) {
@@ -401,34 +392,21 @@ export function createNavigationStore(
             return;
           }
 
-          console.log(
-            "[Browser] Cache marked stale by another tab, shared segments:",
-            mutatedSegmentIds
-              .filter((id) => currentSegmentIds.includes(id))
-              .join(", ")
-          );
           markCacheAsStaleInternal();
 
           // Auto-refresh if enabled and callback is registered
           if (crossTabAutoRefresh && crossTabRefreshCallback) {
             // If idle, refresh immediately. If loading, wait for idle then refresh.
             if (navState.state === "idle") {
-              console.log("[Browser] Cross-tab refresh triggered (idle)");
               crossTabRefreshCallback();
             } else if (!pendingCrossTabRefresh) {
               // Only queue one refresh, ignore subsequent events while loading
               pendingCrossTabRefresh = true;
-              console.log(
-                "[Browser] Navigation in progress, deferring cross-tab refresh"
-              );
               // Subscribe to state changes, refresh when idle
               const listener: StateListener = () => {
                 if (navState.state === "idle") {
                   stateListeners.delete(listener);
                   pendingCrossTabRefresh = false;
-                  console.log(
-                    "[Browser] Cross-tab refresh triggered (deferred)"
-                  );
                   crossTabRefreshCallback?.();
                 }
               };
@@ -574,7 +552,7 @@ export function createNavigationStore(
     cacheSegmentsForHistory(
       historyKey: string,
       segments: ResolvedSegment[],
-      handleData?: HandleData
+      handleData?: HandleData,
     ): void {
       // Shallow clone handleData arrays to avoid reference sharing between cache entries
       // We only clone the structure (objects and arrays), not the data items themselves,
@@ -585,10 +563,15 @@ export function createNavigationStore(
 
       // Check if entry already exists and update it
       const existingIndex = historyCache.findIndex(
-        ([key]) => key === historyKey
+        ([key]) => key === historyKey,
       );
       if (existingIndex !== -1) {
-        historyCache[existingIndex] = [historyKey, segments, false, clonedHandleData];
+        historyCache[existingIndex] = [
+          historyKey,
+          segments,
+          false,
+          clonedHandleData,
+        ];
       } else {
         // Add new entry at the end (not stale)
         historyCache.push([historyKey, segments, false, clonedHandleData]);
@@ -604,8 +587,10 @@ export function createNavigationStore(
      * Returns { segments, stale, handleData } or undefined if not cached
      */
     getCachedSegments(
-      historyKey: string
-    ): { segments: ResolvedSegment[]; stale: boolean; handleData?: HandleData } | undefined {
+      historyKey: string,
+    ):
+      | { segments: ResolvedSegment[]; stale: boolean; handleData?: HandleData }
+      | undefined {
       const entry = historyCache.find(([key]) => key === historyKey);
       if (!entry) return undefined;
       return { segments: entry[1], stale: entry[2], handleData: entry[3] };
@@ -625,13 +610,18 @@ export function createNavigationStore(
      */
     updateCacheHandleData(historyKey: string, handleData: HandleData): void {
       const existingIndex = historyCache.findIndex(
-        ([key]) => key === historyKey
+        ([key]) => key === historyKey,
       );
       if (existingIndex !== -1) {
         const entry = historyCache[existingIndex];
         // Shallow clone handleData arrays to avoid reference sharing
         const clonedHandleData = cloneHandleData(handleData);
-        historyCache[existingIndex] = [entry[0], entry[1], entry[2], clonedHandleData];
+        historyCache[existingIndex] = [
+          entry[0],
+          entry[1],
+          entry[2],
+          clonedHandleData,
+        ];
       }
     },
 
@@ -640,14 +630,7 @@ export function createNavigationStore(
      * Called after server actions to indicate data may be outdated
      */
     markCacheAsStale(): void {
-      for (let i = 0; i < historyCache.length; i++) {
-        historyCache[i][2] = true;
-      }
-      console.log(
-        "[Browser] Marked",
-        historyCache.length,
-        "cache entries as stale"
-      );
+      markCacheAsStaleInternal();
     },
 
     /**
@@ -745,7 +728,7 @@ export function createNavigationStore(
      */
     setActionState(
       actionId: string,
-      partial: Partial<TrackedActionState>
+      partial: Partial<TrackedActionState>,
     ): void {
       const current = actionStates.get(actionId) ?? { ...DEFAULT_ACTION_STATE };
       const updated: TrackedActionState = {
@@ -763,7 +746,7 @@ export function createNavigationStore(
      */
     subscribeToAction(
       actionId: string,
-      listener: ActionStateListener
+      listener: ActionStateListener,
     ): () => void {
       let listeners = actionListeners.get(actionId);
       if (!listeners) {
@@ -793,7 +776,7 @@ let storeInstance: NavigationStore | null = null;
  * Subsequent calls return the existing instance.
  */
 export function initNavigationStore(
-  config?: NavigationStoreConfig
+  config?: NavigationStoreConfig,
 ): NavigationStore {
   if (!storeInstance) {
     storeInstance = createNavigationStore(config);
@@ -809,7 +792,7 @@ export function initNavigationStore(
 export function getNavigationStore(): NavigationStore {
   if (!storeInstance) {
     throw new Error(
-      "Navigation store not initialized. Call initNavigationStore first."
+      "Navigation store not initialized. Call initNavigationStore first.",
     );
   }
   return storeInstance;