@rangojs/router 0.0.0-experimental.21 → 0.0.0-experimental.21efdd86

package/src/browser/navigation-client.ts

@@ -17,6 +17,11 @@ import {
   emptyResponse,
   teeWithCompletion,
 } from "./response-adapter.js";
+import {
+  buildPrefetchKey,
+  consumeInflightPrefetch,
+  consumePrefetch,
+} from "./prefetch/cache.js";
 
 /**
  * Create a navigation client for fetching RSC payloads
@@ -24,21 +29,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 +43,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
@@ -64,6 +61,7 @@ export function createNavigationClient(
         staleRevalidation,
         interceptSourceUrl,
         version,
+        routerId,
         hmr,
       } = options;
 
@@ -80,7 +78,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,32 +89,38 @@ export function createNavigationClient(
       if (version) {
         fetchUrl.searchParams.set("_rsc_v", version);
       }
-      if (tx) {
-        browserDebugLog(tx, "fetching", {
-          path: `${fetchUrl.pathname}${fetchUrl.search}`,
-        });
+      if (routerId) {
+        fetchUrl.searchParams.set("_rsc_rid", routerId);
       }
 
+      // 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,
-          "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
+      /**
+       * Validate RSC control headers on any response (fresh, cached, or
+       * in-flight). Handles version-mismatch reloads and server redirects.
+       * Returns the response unchanged when no control header is present.
+       */
+      const validateRscHeaders = (
+        response: Response,
+        source: string,
+      ): Response | Promise<Response> => {
+        // Version mismatch — server wants a full page reload
         const reload = extractRscHeaderUrl(response, "X-RSC-Reload");
         if (reload === "blocked") {
           resolveStreamComplete();
@@ -123,11 +128,12 @@ export function createNavigationClient(
         }
         if (reload) {
           if (tx) {
-            browserDebugLog(tx, "version mismatch, reloading", {
+            browserDebugLog(tx, `version mismatch, reloading (${source})`, {
               reloadUrl: reload.url,
             });
           }
           window.location.href = reload.url;
+          // Block further processing — page is reloading
           return new Promise<Response>(() => {});
         }
 
@@ -142,7 +148,7 @@ export function createNavigationClient(
         }
         if (redirect) {
           if (tx) {
-            browserDebugLog(tx, "server redirect", {
+            browserDebugLog(tx, `server redirect (${source})`, {
               redirectUrl: redirect.url,
             });
           }
@@ -150,19 +156,95 @@ export function createNavigationClient(
           throw new ServerRedirect(redirect.url, undefined);
         }
 
-        return teeWithCompletion(
-          response,
-          () => {
-            if (tx) browserDebugLog(tx, "stream complete");
-            resolveStreamComplete();
+        return response;
+      };
+
+      /** Start a fresh navigation fetch (no cache / inflight hit). */
+      const doFreshFetch = (): Promise<Response> => {
+        if (tx) {
+          browserDebugLog(tx, "fetching", {
+            path: `${fetchUrl.pathname}${fetchUrl.search}`,
+          });
+        }
+
+        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) => {
+          const validated = validateRscHeaders(response, "fetch");
+          if (validated instanceof Promise) return validated;
+
+          return teeWithCompletion(
+            validated,
+            () => {
+              if (tx) browserDebugLog(tx, "stream complete");
+              resolveStreamComplete();
+            },
+            signal,
+          );
+        });
+      };
+
+      let responsePromise: Promise<Response>;
+
+      if (cachedResponse) {
+        if (tx) {
+          browserDebugLog(tx, "prefetch cache hit", { key: cacheKey });
+        }
+        responsePromise = Promise.resolve(cachedResponse).then((response) => {
+          const validated = validateRscHeaders(response, "prefetch cache");
+          if (validated instanceof Promise) return validated;
+
+          return teeWithCompletion(
+            validated,
+            () => {
+              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, "inflight prefetch unavailable, refetching");
+            }
+            return doFreshFetch();
+          }
+
+          const validated = validateRscHeaders(response, "inflight prefetch");
+          if (validated instanceof Promise) return validated;
+
+          return teeWithCompletion(
+            validated,
+            () => {
+              if (tx) {
+                browserDebugLog(tx, "stream complete (from inflight prefetch)");
+              }
+              resolveStreamComplete();
+            },
+            signal,
+          );
+        });
+      } else {
+        responsePromise = doFreshFetch();
+      }
 
       try {
-        // Deserialize RSC payload
         const payload = await deps.createFromFetch<RscPayload>(responsePromise);
+
         if (tx) {
           browserDebugLog(tx, "response received", {
             isPartial: payload.metadata?.isPartial,

package/src/browser/navigation-store.ts

@@ -28,9 +28,15 @@ const DEFAULT_ACTION_STATE: TrackedActionState = {
 // Maximum number of history entries to cache (URLs visited)
 const HISTORY_CACHE_SIZE = 20;
 
-// Cache entry: [url-key, segments, stale, handleData?]
+// Cache entry: [url-key, segments, stale, handleData?, routerId?]
 // stale=true means the data may be outdated and should be revalidated on access
-type HistoryCacheEntry = [string, ResolvedSegment[], boolean, HandleData?];
+type HistoryCacheEntry = [
+  string,
+  ResolvedSegment[],
+  boolean,
+  HandleData?,
+  string?,
+];
 
 /**
  * Shallow clone handleData to avoid reference sharing between cache entries.
@@ -258,6 +264,11 @@ export function createNavigationStore(
   // Used to maintain intercept context during action revalidation
   let interceptSourceUrl: string | null = null;
 
+  // Router identity - tracks which router is currently active.
+  // When this changes on a partial response, the client forces a full
+  // tree replacement instead of reconciling with stale segments.
+  let currentRouterId: string | undefined;
+
   // Action state tracking (for useAction hook)
   // Maps action function ID to its tracked state
   const actionStates = new Map<string, TrackedActionState>();
@@ -571,10 +582,17 @@ export function createNavigationStore(
           segments,
           false,
           clonedHandleData,
+          currentRouterId,
         ];
       } else {
         // Add new entry at the end (not stale)
-        historyCache.push([historyKey, segments, false, clonedHandleData]);
+        historyCache.push([
+          historyKey,
+          segments,
+          false,
+          clonedHandleData,
+          currentRouterId,
+        ]);
         // Remove oldest entries if over limit
         while (historyCache.length > cacheSize) {
           historyCache.shift();
@@ -586,14 +604,22 @@ export function createNavigationStore(
      * Get cached segments for a history entry
      * Returns { segments, stale, handleData } or undefined if not cached
      */
-    getCachedSegments(
-      historyKey: string,
-    ):
-      | { segments: ResolvedSegment[]; stale: boolean; handleData?: HandleData }
+    getCachedSegments(historyKey: string):
+      | {
+          segments: ResolvedSegment[];
+          stale: boolean;
+          handleData?: HandleData;
+          routerId?: string;
+        }
       | undefined {
       const entry = historyCache.find(([key]) => key === historyKey);
       if (!entry) return undefined;
-      return { segments: entry[1], stale: entry[2], handleData: entry[3] };
+      return {
+        segments: entry[1],
+        stale: entry[2],
+        handleData: entry[3],
+        routerId: entry[4],
+      };
     },
 
     /**
@@ -621,6 +647,7 @@ export function createNavigationStore(
           entry[1],
           entry[2],
           clonedHandleData,
+          entry[4], // preserve routerId
         ];
       }
     },
@@ -687,6 +714,14 @@ export function createNavigationStore(
       interceptSourceUrl = url;
     },
 
+    getRouterId(): string | undefined {
+      return currentRouterId;
+    },
+
+    setRouterId(id: string): void {
+      currentRouterId = id;
+    },
+
     // ========================================================================
     // UI Update Notifications
     // ========================================================================

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
@@ -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,
         });
       }