@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.1878aa49

package/src/browser/navigation-bridge.ts

@@ -4,12 +4,19 @@ import type {
   NavigateOptionsInternal,
   ResolvedSegment,
 } from "./types.js";
+import { setAppVersion } from "./app-version.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 +25,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 {
@@ -28,17 +34,13 @@ import {
 } from "./network-error-handler.js";
 import { debugLog } from "./logging.js";
 import { ServerRedirect } from "../errors.js";
+import { validateRedirectOrigin } from "./validate-redirect-origin.js";
 
 // Polyfill Symbol.dispose for Safari and older browsers
 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 };
 
 /**
@@ -66,8 +68,8 @@ 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 } = config;
+  let version = config.version;
 
   // Create shared partial updater
   const fetchPartialUpdate = createPartialUpdater({
@@ -75,13 +77,13 @@ export function createNavigationBridge(
     client,
     onUpdate,
     renderSegments,
-    version,
+    getVersion: () => version,
   });
 
   return {
     /**
      * Navigate to a URL
-     * Uses optimistic rendering from cache when available (SWR pattern)
+     * Uses cached segments for SWR revalidation when available
      */
     async navigate(
       url: string,
@@ -93,10 +95,109 @@ export function createNavigationBridge(
           ? resolveNavigationState(options.state)
           : undefined;
 
+      // Cross-origin URLs are not handled by SPA navigation.
+      // Fall back to a full browser navigation for http/https only.
+      let targetUrl: URL;
+      try {
+        targetUrl = new URL(url, window.location.origin);
+      } catch {
+        console.warn(`[rango] navigate() ignored: malformed URL "${url}"`);
+        return;
+      }
+      if (targetUrl.origin !== window.location.origin) {
+        if (targetUrl.protocol !== "http:" && targetUrl.protocol !== "https:") {
+          console.error(
+            `[rango] navigate() blocked: unsupported scheme "${targetUrl.protocol}"`,
+          );
+          return;
+        }
+        window.location.href = targetUrl.href;
+        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;
-      const targetPath = new URL(url, window.location.origin).pathname;
+      const targetPath = targetUrl.pathname;
       if (currentPath !== targetPath) {
         eventController.abortNavigation();
       }
@@ -155,7 +256,7 @@ export function createNavigationBridge(
       const interceptHistoryKey = generateHistoryKey(url, { intercept: true });
       const hasInterceptCache = store.hasHistoryCache(interceptHistoryKey);
 
-      // Skip optimistic rendering for:
+      // Skip cached SWR for:
       // 1. intercept caches - interception depends on source page context
       // 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
@@ -168,7 +269,7 @@ export function createNavigationBridge(
         !isLeavingIntercept &&
         !options?._skipCache;
 
-      using tx = createNavigationTransaction(store, eventController, url, {
+      const tx = createNavigationTransaction(store, eventController, url, {
         ...options,
         state: resolvedState,
         skipLoadingState: hasUsableCache,
@@ -179,7 +280,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,
@@ -191,27 +292,29 @@ export function createNavigationBridge(
             scroll: options?.scroll,
             state: resolvedState,
           }),
-          // Pass cached segments (merged with current page's fresh segments for shared IDs)
-          // so the segment map is consistent with what we tell the server we have.
-          // Server decides what needs revalidation based on route matching and custom functions.
-          // No need for staleRevalidation flag - we're sending the freshest segments we have.
-          // Also pass cached handle data for restoring breadcrumbs when server returns empty diff.
-          // When leaving intercept, pass the flag so fetchPartialUpdate knows to filter segments.
           hasUsableCache
             ? {
+                type: "navigate" as const,
                 targetCacheSegments: cachedSegments,
                 targetCacheHandleData: cachedHandleData,
               }
             : isLeavingIntercept
-              ? { leavingIntercept: true }
+              ? { type: "leave-intercept" as const }
               : undefined,
         );
       } 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) {
-          return this.navigate(error.url, {
+          const redirectUrl = validateRedirectOrigin(
+            error.url,
+            window.location.origin,
+          );
+          if (!redirectUrl) {
+            return;
+          }
+          return this.navigate(redirectUrl, {
             state: error.state,
             replace: options?.replace,
             _skipCache: true,
@@ -237,6 +340,8 @@ export function createNavigationBridge(
         }
 
         throw error;
+      } finally {
+        tx[Symbol.dispose]();
       }
     },
 
@@ -246,7 +351,7 @@ export function createNavigationBridge(
     async refresh(): Promise<void> {
       eventController.abortNavigation();
 
-      using tx = createNavigationTransaction(
+      const tx = createNavigationTransaction(
         store,
         eventController,
         window.location.href,
@@ -276,6 +381,8 @@ export function createNavigationBridge(
           return;
         }
         throw error;
+      } finally {
+        tx[Symbol.dispose]();
       }
     },
 
@@ -341,6 +448,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, {
@@ -366,6 +479,7 @@ export function createNavigationBridge(
               cachedHandleData,
               params: cachedParams,
             },
+            scroll: { restore: true, isStreaming },
           };
           const hasTransition = cachedSegments.some((s) => s.transition);
           if (hasTransition) {
@@ -379,14 +493,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,
@@ -408,7 +519,7 @@ export function createNavigationBridge(
                 interceptSourceUrl,
                 cacheOnly: true,
               }),
-              { staleRevalidation: true, interceptSourceUrl },
+              { type: "stale-revalidation", interceptSourceUrl },
             )
               .catch((error) => {
                 if (isBackgroundSuppressible(error)) return;
@@ -434,7 +545,7 @@ export function createNavigationBridge(
       }
 
       // Fetch if not cached
-      using tx = createNavigationTransaction(store, eventController, url, {
+      const tx = createNavigationTransaction(store, eventController, url, {
         replace: true,
       });
 
@@ -444,7 +555,14 @@ export function createNavigationBridge(
           undefined,
           false,
           tx.handle.signal,
-          tx.with({ url, replace: true, scroll: false }),
+          tx.with({
+            url,
+            replace: true,
+            scroll: false,
+            intercept: isIntercept,
+            interceptSourceUrl,
+          }),
+          isIntercept ? { type: "navigate", interceptSourceUrl } : undefined,
         );
         // Restore scroll position after fetch completes
         handleNavigationEnd({ restore: true, isStreaming });
@@ -468,6 +586,8 @@ export function createNavigationBridge(
         }
 
         throw error;
+      } finally {
+        tx[Symbol.dispose]();
       }
     },
 
@@ -498,6 +618,9 @@ export function createNavigationBridge(
             "[Browser] Page restored from bfcache, resetting navigation state",
           );
           eventController.abortNavigation();
+          // pagehide flips scrollRestoration to "auto" for bfcache compat;
+          // restore "manual" so the router controls scroll on SPA navigations.
+          window.history.scrollRestoration = "manual";
         }
       };
 
@@ -516,6 +639,12 @@ export function createNavigationBridge(
         window.removeEventListener("pageshow", handlePageShow);
       };
     },
+
+    updateVersion(newVersion: string): void {
+      version = newVersion;
+      setAppVersion(newVersion);
+      store.clearHistoryCache();
+    },
   };
 }
 

package/src/browser/navigation-client.ts

@@ -12,6 +12,16 @@ import {
   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
@@ -19,21 +29,12 @@ import { getRangoState } from "./rango-state.js";
  * 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">,
@@ -42,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
@@ -59,6 +61,7 @@ export function createNavigationClient(
         staleRevalidation,
         interceptSourceUrl,
         version,
+        routerId,
         hmr,
       } = options;
 
@@ -75,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(","));
@@ -85,51 +89,51 @@ 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
-        const reloadUrl = response.headers.get("X-RSC-Reload");
-        if (reloadUrl) {
-          // Validate origin to prevent open redirect via crafted headers
-          try {
-            const target = new URL(reloadUrl, window.location.origin);
-            if (target.origin !== window.location.origin) {
-              throw new Error(
-                `X-RSC-Reload blocked: origin mismatch (${target.origin})`,
-              );
-            }
-          } catch (e) {
-            console.error("[rango]", e);
-            return response;
-          }
+      /**
+       * 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();
+          return emptyResponse();
+        }
+        if (reload) {
           if (tx) {
-            browserDebugLog(tx, "version mismatch, reloading", { reloadUrl });
+            browserDebugLog(tx, `version mismatch, reloading (${source})`, {
+              reloadUrl: reload.url,
+            });
           }
-          window.location.href = reloadUrl;
-          // Return a never-resolving promise to prevent further processing
+          window.location.href = reload.url;
+          // Block further processing — page is reloading
           return new Promise<Response>(() => {});
         }
 
@@ -137,61 +141,110 @@ export function createNavigationClient(
         // 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 redirectUrl = response.headers.get("X-RSC-Redirect");
-        if (redirectUrl) {
+        const redirect = extractRscHeaderUrl(response, "X-RSC-Redirect");
+        if (redirect === "blocked") {
+          resolveStreamComplete();
+          return emptyResponse();
+        }
+        if (redirect) {
           if (tx) {
-            browserDebugLog(tx, "server redirect", { redirectUrl });
+            browserDebugLog(tx, `server redirect (${source})`, {
+              redirectUrl: redirect.url,
+            });
           }
           resolveStreamComplete();
-          throw new ServerRedirect(redirectUrl, undefined);
+          throw new ServerRedirect(redirect.url, undefined);
         }
 
-        if (!response.body) {
-          // No body means stream is already complete
-          resolveStreamComplete();
-          return response;
+        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}`,
+          });
         }
 
-        // Tee the stream: one for RSC runtime, one for tracking completion
-        const [rscStream, trackingStream] = response.body.tee();
+        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;
 
-        // Consume the tracking stream to detect when it closes
-        (async () => {
-          const reader = trackingStream.getReader();
+          return teeWithCompletion(
+            validated,
+            () => {
+              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 });
+        }
+        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, "stream complete");
+              browserDebugLog(tx, "inflight prefetch unavailable, refetching");
             }
-            resolveStreamComplete();
+            return doFreshFetch();
           }
-        })().catch((error) => {
-          console.error("[Browser] Error reading tracking stream:", error);
-          resolveStreamComplete();
-        });
 
-        // Return response with the RSC stream
-        return new Response(rscStream, {
-          headers: response.headers,
-          status: response.status,
-          statusText: response.statusText,
+          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,