@rangojs/router 0.0.0-experimental.25 → 0.0.0-experimental.25dbaac3

package/src/browser/navigation-bridge.ts

@@ -4,12 +4,21 @@ import type {
   NavigateOptionsInternal,
   ResolvedSegment,
 } from "./types.js";
+import { setAppVersion } from "./app-version.js";
+import { setRangoStateLocal } from "./rango-state.js";
+import type { AppShell, AppShellRef } from "./app-shell.js";
 import * as React from "react";
 import { startTransition } from "react";
 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 +27,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 {
@@ -35,11 +43,6 @@ if (typeof Symbol.dispose === "undefined") {
   (Symbol as any).dispose = Symbol("Symbol.dispose");
 }
 
-/** Get IDs of non-loader segments (layouts, routes, parallels). */
-function getNonLoaderSegmentIds(segments: ResolvedSegment[]): string[] {
-  return segments.filter((s) => s.type !== "loader").map((s) => s.id);
-}
-
 export { createNavigationTransaction };
 
 /**
@@ -47,8 +50,13 @@ export { createNavigationTransaction };
  */
 export interface NavigationBridgeConfigWithController extends NavigationBridgeConfig {
   eventController: EventController;
-  /** RSC version from initial payload metadata */
+  /** RSC version from initial payload metadata (fallback when appShellRef is not provided) */
   version?: string;
+  /**
+   * Live app-shell ref. When supplied, the bridge reads version/basename
+   * from this ref so cross-app navigations propagate correctly.
+   */
+  appShellRef?: AppShellRef;
 }
 
 /**
@@ -67,8 +75,45 @@ export interface NavigationBridgeConfigWithController extends NavigationBridgeCo
 export function createNavigationBridge(
   config: NavigationBridgeConfigWithController,
 ): NavigationBridge {
-  const { store, client, eventController, onUpdate, renderSegments, version } =
-    config;
+  const {
+    store,
+    client,
+    eventController,
+    onUpdate,
+    renderSegments,
+    appShellRef,
+  } = config;
+  let version = config.version;
+
+  /**
+   * Replace the active app-shell snapshot atomically. Called by the partial
+   * updater when a response's routerId indicates the navigation crossed
+   * into a different app. Runs the local-only side-effects tied to
+   * app-shell fields (app version, rango-state namespace) so the new app
+   * owns them after the swap. Theme, warmup, and prefetch TTL are
+   * document-lifetime and are NOT touched here.
+   */
+  function applyAppShell(next: AppShell): void {
+    if (appShellRef) {
+      appShellRef.update(next);
+    }
+    if (next.version !== undefined) {
+      version = next.version;
+      setAppVersion(next.version);
+      // Use the local-only setter — initRangoState writes the shared
+      // localStorage key and fires a storage event in other tabs still in
+      // the old app. setRangoStateLocal only mutates this tab's in-memory
+      // cache and rebinds it to the target app's routerId-scoped key,
+      // preserving the "local-only, no broadcast/rotation" contract for
+      // smooth app-switch transitions.
+      setRangoStateLocal(next.version, next.routerId);
+    }
+    // Cross-app: prior cache entries belong to a different app's segments.
+    // Drop them locally only — do NOT broadcast invalidation or rotate the
+    // shared X-Rango-State token, since other tabs still in the old app are
+    // unaffected by this tab's transition.
+    store.clearHistoryCacheLocal();
+  }
 
   // Create shared partial updater
   const fetchPartialUpdate = createPartialUpdater({
@@ -76,7 +121,8 @@ export function createNavigationBridge(
     client,
     onUpdate,
     renderSegments,
-    version,
+    getVersion: () => version,
+    applyAppShell,
   });
 
   return {
@@ -114,6 +160,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;
@@ -181,18 +306,24 @@ export function createNavigationBridge(
       // 2. routes that CAN be intercepted - we don't know if this navigation will intercept
       // 3. when leaving intercept - we need fresh non-intercept segments from server
       // 4. redirect-with-state - force re-render so hooks read fresh state
+      // 5. stale cache - server action invalidated it, need fresh data with loading state
       const hasUsableCache =
         cachedSegments &&
         cachedSegments.length > 0 &&
         !isInterceptOnlyCache(cachedSegments) &&
         !hasInterceptCache &&
         !isLeavingIntercept &&
+        !cached?.stale &&
         !options?._skipCache;
 
+      // Forward navigations always await fetchPartialUpdate before rendering,
+      // so useNavigation should always report "loading". skipLoadingState is
+      // only used for popstate background revalidation (line ~526) where
+      // cached content renders instantly without a network wait.
       const tx = createNavigationTransaction(store, eventController, url, {
         ...options,
         state: resolvedState,
-        skipLoadingState: hasUsableCache,
+        skipLoadingState: false,
       });
 
       // REVALIDATE: Fetch fresh data from server
@@ -200,7 +331,7 @@ export function createNavigationBridge(
         await fetchPartialUpdate(
           url,
           hasUsableCache
-            ? getNonLoaderSegmentIds(cachedSegments!)
+            ? cachedSegments!.map((s) => s.id)
             : options?._skipCache
               ? [] // Action redirect: send no segments so server renders everything fresh
               : undefined,
@@ -332,6 +463,15 @@ export function createNavigationBridge(
         eventController.abortAllActions();
       }
 
+      // Popstate that exits an intercept to a non-intercept destination. The
+      // fallback fetch path below needs `leave-intercept` mode so it filters
+      // the cached @modal segment from the request and forces a re-render —
+      // otherwise a cache-miss popstate whose server response has an empty
+      // diff hits the "no changes" branch in partial-update and the modal
+      // stays on screen.
+      const isLeavingIntercept =
+        !isIntercept && currentInterceptSource !== null;
+
       // Compute history key from URL (with intercept suffix if applicable)
       const historyKey = generateHistoryKey(url, { intercept: isIntercept });
 
@@ -368,6 +508,12 @@ export function createNavigationBridge(
         store.setCurrentUrl(url);
         store.setPath(new URL(url).pathname);
 
+        // Restore router identity from cache so subsequent navigations
+        // don't falsely detect an app switch.
+        if (cached?.routerId) {
+          store.setRouterId?.(cached.routerId);
+        }
+
         // Render from cache - force await to skip loading fallbacks
         try {
           const root = await renderSegments(cachedSegments, {
@@ -393,6 +539,7 @@ export function createNavigationBridge(
               cachedHandleData,
               params: cachedParams,
             },
+            scroll: { restore: true, isStreaming },
           };
           const hasTransition = cachedSegments.some((s) => s.transition);
           if (hasTransition) {
@@ -406,14 +553,11 @@ export function createNavigationBridge(
             onUpdate(popstateUpdate);
           }
 
-          // Restore scroll position for back/forward navigation
-          handleNavigationEnd({ restore: true, isStreaming });
-
           // SWR: If stale, trigger background revalidation
           if (isStale) {
             debugLog("[Browser] Cache is stale, background revalidating...");
             // Background revalidation - don't await, just fire and forget
-            const segmentIds = getNonLoaderSegmentIds(cachedSegments);
+            const segmentIds = cachedSegments.map((s) => s.id);
 
             const tx = createNavigationTransaction(
               store,
@@ -478,7 +622,11 @@ export function createNavigationBridge(
             intercept: isIntercept,
             interceptSourceUrl,
           }),
-          isIntercept ? { type: "navigate", interceptSourceUrl } : undefined,
+          isIntercept
+            ? { type: "navigate", interceptSourceUrl }
+            : isLeavingIntercept
+              ? { type: "leave-intercept" }
+              : undefined,
         );
         // Restore scroll position after fetch completes
         handleNavigationEnd({ restore: true, isStreaming });
@@ -555,6 +703,16 @@ export function createNavigationBridge(
         window.removeEventListener("pageshow", handlePageShow);
       };
     },
+
+    updateVersion(newVersion: string): void {
+      version = newVersion;
+      setAppVersion(newVersion);
+      store.clearHistoryCache();
+    },
+
+    updateAppShell(next: AppShell): void {
+      applyAppShell(next);
+    },
   };
 }
 

package/src/browser/navigation-client.ts

@@ -17,6 +17,12 @@ import {
   emptyResponse,
   teeWithCompletion,
 } from "./response-adapter.js";
+import {
+  buildPrefetchKey,
+  buildSourceKey,
+  consumeInflightPrefetch,
+  consumePrefetch,
+} from "./prefetch/cache.js";
 
 /**
  * Create a navigation client for fetching RSC payloads
@@ -24,21 +30,14 @@ 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.
+ * Tries the source-scoped key first (populated when the server tagged
+ * the response as source-sensitive via `X-RSC-Prefetch-Scope: source`)
+ * and falls back to the Rango-state-keyed wildcard slot used for the
+ * common source-agnostic case.
+ *
  * @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 +46,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 +64,7 @@ export function createNavigationClient(
         staleRevalidation,
         interceptSourceUrl,
         version,
+        routerId,
         hmr,
       } = options;
 
@@ -80,7 +81,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 +92,62 @@ 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. Try the source-scoped key first (populated when the server
+      // tagged the prefetch response as source-sensitive, e.g. intercepts,
+      // or when a Link opted in with `prefetchKey=":source"`), then fall
+      // back to the wildcard slot shared across source pages.
+      // Both keys embed the Rango state, so state rotation (deploy or
+      // server-action invalidation) auto-invalidates both scopes.
+      // Skip cache for stale revalidation (needs fresh data), HMR (needs
+      // fresh modules), and intercept contexts (source-dependent responses).
+      const canUsePrefetch = !staleRevalidation && !hmr && !interceptSourceUrl;
+      const rangoState = getRangoState();
+      const wildcardKey = buildPrefetchKey(rangoState, fetchUrl);
+      const cacheKey = buildSourceKey(rangoState, previousUrl, fetchUrl);
+
+      let cachedResponse: Response | null = null;
+      let hitKey: string | null = null;
+      if (canUsePrefetch) {
+        cachedResponse = consumePrefetch(cacheKey);
+        if (cachedResponse) {
+          hitKey = cacheKey;
+        } else {
+          cachedResponse = consumePrefetch(wildcardKey);
+          if (cachedResponse) hitKey = wildcardKey;
+        }
       }
 
+      let inflightResponsePromise: Promise<Response | null> | null = null;
+      if (canUsePrefetch && !cachedResponse) {
+        inflightResponsePromise = consumeInflightPrefetch(cacheKey);
+        if (inflightResponsePromise) {
+          hitKey = cacheKey;
+        } else {
+          inflightResponsePromise = consumeInflightPrefetch(wildcardKey);
+          if (inflightResponsePromise) hitKey = wildcardKey;
+        }
+      }
       // 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 +155,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 +175,7 @@ export function createNavigationClient(
         }
         if (redirect) {
           if (tx) {
-            browserDebugLog(tx, "server redirect", {
+            browserDebugLog(tx, `server redirect (${source})`, {
               redirectUrl: redirect.url,
             });
           }
@@ -150,19 +183,119 @@ 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: hitKey,
+            wildcard: hitKey === wildcardKey,
+          });
+        }
+        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: hitKey,
+            wildcard: hitKey === wildcardKey,
+          });
+        }
+        const adoptedViaWildcard = hitKey === wildcardKey;
+        responsePromise = inflightResponsePromise.then(async (response) => {
+          if (!response) {
+            if (tx) {
+              browserDebugLog(tx, "inflight prefetch unavailable, refetching");
+            }
+            return doFreshFetch();
+          }
+
+          // Cross-source safety: an inflight promise adopted via the
+          // wildcard key may turn out to be source-scoped (server emitted
+          // `X-RSC-Prefetch-Scope: source`), which means it was built for
+          // a different source page. Discard and refetch.
+          if (
+            adoptedViaWildcard &&
+            response.headers.get("x-rsc-prefetch-scope") === "source"
+          ) {
+            if (tx) {
+              browserDebugLog(
+                tx,
+                "wildcard inflight turned out source-scoped, 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,