@rangojs/router 0.0.0-experimental.9c9afef3 → 0.0.0-experimental.a014d2b7

package/src/browser/navigation-client.ts

@@ -12,16 +12,20 @@ import {
   startBrowserTransaction,
 } from "./logging.js";
 import { getRangoState } from "./rango-state.js";
-import { createClientDebugChannel, DEBUG_ID_HEADER } from "./debug-channel.js";
+import { isActionFenceActive } from "./action-fence.js";
 import {
   extractRscHeaderUrl,
   emptyResponse,
+  handleReloadHeader,
   teeWithCompletion,
+  isForeignRouterId,
 } from "./response-adapter.js";
 import {
   buildPrefetchKey,
+  buildSourceKey,
   consumeInflightPrefetch,
   consumePrefetch,
+  type DecodedPrefetch,
 } from "./prefetch/cache.js";
 
 /**
@@ -31,8 +35,10 @@ import {
  * 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.
+ * 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
@@ -62,6 +68,7 @@ export function createNavigationClient(
         staleRevalidation,
         interceptSourceUrl,
         version,
+        routerId,
         hmr,
       } = options;
 
@@ -89,32 +96,115 @@ export function createNavigationClient(
       if (version) {
         fetchUrl.searchParams.set("_rsc_v", version);
       }
+      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.
+      // 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 cacheKey = buildPrefetchKey(previousUrl, fetchUrl);
-      const cachedResponse = canUsePrefetch ? consumePrefetch(cacheKey) : null;
-      const inflightResponsePromise = canUsePrefetch
-        ? consumeInflightPrefetch(cacheKey)
-        : null;
+      // Suspend prefetch consumption while an action is in flight: a queued
+      // prefetch holds pre-mutation data and must not be served until the
+      // action's response decides whether anything changed.
+      const canUsePrefetch =
+        !staleRevalidation &&
+        !hmr &&
+        !interceptSourceUrl &&
+        !isActionFenceActive();
+      const rangoState = getRangoState();
+      const wildcardKey = buildPrefetchKey(rangoState, fetchUrl);
+      const cacheKey = buildSourceKey(rangoState, previousUrl, fetchUrl);
+
+      let cachedEntry: DecodedPrefetch | null = null;
+      let hitKey: string | null = null;
+      if (canUsePrefetch) {
+        cachedEntry = consumePrefetch(cacheKey);
+        if (cachedEntry) {
+          hitKey = cacheKey;
+        } else {
+          cachedEntry = consumePrefetch(wildcardKey);
+          if (cachedEntry) hitKey = wildcardKey;
+        }
+      }
+
+      let inflightEntryPromise: Promise<DecodedPrefetch | null> | null = null;
+      if (canUsePrefetch && !cachedEntry) {
+        inflightEntryPromise = consumeInflightPrefetch(cacheKey);
+        if (inflightEntryPromise) {
+          hitKey = cacheKey;
+        } else {
+          inflightEntryPromise = consumeInflightPrefetch(wildcardKey);
+          if (inflightEntryPromise) hitKey = wildcardKey;
+        }
+      }
       // Track when the stream completes
       let resolveStreamComplete: () => void;
       const streamComplete = new Promise<void>((resolve) => {
         resolveStreamComplete = resolve;
       });
 
-      // Dev-only: create debug channel for React Performance Tracks
-      const debugId = (import.meta as any).hot
-        ? crypto.randomUUID()
-        : undefined;
-      const debugChannel = debugId
-        ? createClientDebugChannel(debugId)
-        : undefined;
+      /**
+       * 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 reloadResult = handleReloadHeader(response, {
+          onBlocked: resolveStreamComplete,
+          onReload: (url) => {
+            if (tx) {
+              browserDebugLog(tx, `version mismatch, reloading (${source})`, {
+                reloadUrl: url,
+              });
+            }
+          },
+        });
+        if (reloadResult) return reloadResult;
+
+        // 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 (${source})`, {
+              redirectUrl: redirect.url,
+            });
+          }
+          resolveStreamComplete();
+          throw new ServerRedirect(redirect.url, undefined);
+        }
+
+        // Integrity check (pre-decode): refuse a foreign app's content response
+        // before createFromFetch imports its chunks. Ordered AFTER the reload
+        // and redirect handlers — control responses are never stamped with
+        // X-RSC-Router-Id, so they are steered first and never reach here.
+        if (isForeignRouterId(response, routerId)) {
+          if (tx) {
+            browserDebugLog(tx, `router id mismatch, reloading (${source})`);
+          }
+          resolveStreamComplete();
+          window.location.href = targetUrl;
+          return new Promise<Response>(() => {});
+        }
+
+        return response;
+      };
 
       /** Start a fresh navigation fetch (no cache / inflight hit). */
       const doFreshFetch = (): Promise<Response> => {
@@ -125,6 +215,11 @@ export function createNavigationClient(
         }
 
         return fetch(fetchUrl, {
+          // During an action's flight the state is not rotated, so the old
+          // X-Rango-State still matches the Vary-keyed HTTP-cache entry; bypass
+          // it so a genuine mid-action navigation fetches fresh instead of being
+          // served the stale prefetched bytes.
+          ...(isActionFenceActive() && { cache: "no-store" as RequestCache }),
           headers: {
             "X-RSC-Router-Client-Path": previousUrl,
             "X-Rango-State": getRangoState(),
@@ -133,47 +228,14 @@ export function createNavigationClient(
               "X-RSC-Router-Intercept-Source": interceptSourceUrl,
             }),
             ...(hmr && { "X-RSC-HMR": "1" }),
-            ...(debugId && { [DEBUG_ID_HEADER]: debugId }),
           },
           signal,
         }).then((response) => {
-          // Check for version mismatch - server wants us to reload
-          const reload = extractRscHeaderUrl(response, "X-RSC-Reload");
-          if (reload === "blocked") {
-            resolveStreamComplete();
-            return emptyResponse();
-          }
-          if (reload) {
-            if (tx) {
-              browserDebugLog(tx, "version mismatch, reloading", {
-                reloadUrl: reload.url,
-              });
-            }
-            window.location.href = reload.url;
-            return new Promise<Response>(() => {});
-          }
-
-          // Server-side redirect without state: the server returned 204 with
-          // X-RSC-Redirect instead of a 3xx (which fetch would auto-follow
-          // to a URL rendering full HTML). Throw ServerRedirect so the
-          // navigation bridge catches it and re-navigates with _skipCache.
-          const redirect = extractRscHeaderUrl(response, "X-RSC-Redirect");
-          if (redirect === "blocked") {
-            resolveStreamComplete();
-            return emptyResponse();
-          }
-          if (redirect) {
-            if (tx) {
-              browserDebugLog(tx, "server redirect", {
-                redirectUrl: redirect.url,
-              });
-            }
-            resolveStreamComplete();
-            throw new ServerRedirect(redirect.url, undefined);
-          }
+          const validated = validateRscHeaders(response, "fetch");
+          if (validated instanceof Promise) return validated;
 
           return teeWithCompletion(
-            response,
+            validated,
             () => {
               if (tx) browserDebugLog(tx, "stream complete");
               resolveStreamComplete();
@@ -183,59 +245,79 @@ export function createNavigationClient(
         });
       };
 
-      let responsePromise: Promise<Response>;
+      // A warm prefetch hit returns its eagerly-decoded payload directly: the
+      // route's chunks were imported during the prefetch, so this click runs
+      // no decode and no network. Only the fresh path runs createFromFetch and
+      // resolves the local streamComplete (via doFreshFetch's teeWithCompletion
+      // and the control-header short-circuits in validateRscHeaders).
+      const freshResult = (): {
+        payload: Promise<RscPayload>;
+        streamComplete: Promise<void>;
+      } => ({
+        payload: deps.createFromFetch<RscPayload>(doFreshFetch()),
+        streamComplete,
+      });
+
+      let payloadPromise: Promise<RscPayload>;
+      let streamCompletePromise: Promise<void>;
+      // True only for a prefetch-cache hit whose stream had already fully drained
+      // (complete === true). A still-streaming hit and the fresh path stay false,
+      // so only a fully-warmed prefetch commits in a transition (no fallback flash).
+      let fullyPrefetched = false;
 
-      if (cachedResponse) {
+      if (cachedEntry) {
         if (tx) {
-          browserDebugLog(tx, "prefetch cache hit", { key: cacheKey });
+          browserDebugLog(tx, "prefetch cache hit (warm)", {
+            key: hitKey,
+            wildcard: hitKey === wildcardKey,
+          });
         }
-        // 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) {
+        payloadPromise = cachedEntry.payload;
+        streamCompletePromise = cachedEntry.streamComplete;
+        // Only a hit whose stream already fully drained is "fully prefetched";
+        // a still-streaming hit must keep streaming its fallbacks like a cold load.
+        fullyPrefetched = cachedEntry.complete;
+      } else if (inflightEntryPromise) {
         if (tx) {
-          browserDebugLog(tx, "reusing inflight prefetch", { key: cacheKey });
+          browserDebugLog(tx, "reusing inflight prefetch", {
+            key: hitKey,
+            wildcard: hitKey === wildcardKey,
+          });
         }
-        responsePromise = inflightResponsePromise.then(async (response) => {
-          if (!response) {
-            if (tx) {
-              browserDebugLog(tx, "inflight prefetch unavailable, refetching");
-            }
-            return doFreshFetch();
+        const adoptedViaWildcard = hitKey === wildcardKey;
+        const entry = await inflightEntryPromise;
+        if (!entry) {
+          if (tx) {
+            browserDebugLog(tx, "inflight prefetch unavailable, refetching");
           }
-
-          return teeWithCompletion(
-            response,
-            () => {
-              if (tx) {
-                browserDebugLog(tx, "stream complete (from inflight prefetch)");
-              }
-              resolveStreamComplete();
-            },
-            signal,
-          );
-        });
+          ({ payload: payloadPromise, streamComplete: streamCompletePromise } =
+            freshResult());
+        } else if (adoptedViaWildcard && entry.scope === "source") {
+          // A wildcard-adopted inflight that turned out source-scoped was
+          // built for a different source page. Discard and refetch.
+          if (tx) {
+            browserDebugLog(
+              tx,
+              "wildcard inflight turned out source-scoped, refetching",
+            );
+          }
+          ({ payload: payloadPromise, streamComplete: streamCompletePromise } =
+            freshResult());
+        } else {
+          payloadPromise = entry.payload;
+          streamCompletePromise = entry.streamComplete;
+          // Adopted inflight is normally still streaming (false), but read the
+          // flag in case it completed between publish and adoption.
+          fullyPrefetched = entry.complete;
+        }
       } else {
-        responsePromise = doFreshFetch();
+        ({ payload: payloadPromise, streamComplete: streamCompletePromise } =
+          freshResult());
       }
 
       try {
-        // Deserialize RSC payload
-        const payload = await deps.createFromFetch<RscPayload>(
-          responsePromise,
-          {
-            ...(debugChannel && { debugChannel }),
-          },
-        );
+        const payload = await payloadPromise;
+
         if (tx) {
           browserDebugLog(tx, "response received", {
             isPartial: payload.metadata?.isPartial,
@@ -243,7 +325,11 @@ export function createNavigationClient(
             diffCount: payload.metadata?.diff?.length ?? 0,
           });
         }
-        return { payload, streamComplete };
+        return {
+          payload,
+          streamComplete: streamCompletePromise,
+          fullyPrefetched,
+        };
       } catch (error) {
         // Convert network-level errors to NetworkError for proper handling
         if (isNetworkError(error)) {

package/src/browser/navigation-store-handle.ts

@@ -0,0 +1,38 @@
+/**
+ * A module-level handle to the active navigation store.
+ *
+ * The boot path (`rsc-router.tsx`) calls `createNavigationStore()` directly;
+ * there is no global store singleton. This handle is the live reference for
+ * code that needs the store but does not
+ * receive it by argument: the jar-divergence observer (below) and the client
+ * seat of `invalidateClientCache()` (added later).
+ *
+ * Dependency-light on purpose: it imports only `setRangoStateObserver` and the
+ * store type, so pulling it into the default root entry does not drag the
+ * navigation store into bundles that previously lacked it.
+ */
+
+import { setRangoStateObserver } from "./rango-state.js";
+import type { NavigationStore } from "./types.js";
+
+let registeredStore: NavigationStore | null = null;
+
+/**
+ * Register the active navigation store at boot, and wire the jar-divergence
+ * observer: when a per-request cookie read detects an EXTERNAL rotation (a
+ * sibling tab, a server `Set-Cookie`, or a cookie clear), mark this tab's
+ * history cache stale. The history cache is not state-keyed, so the value
+ * rotation alone does not reach it. No broadcast, no prefetch clear, no
+ * re-rotation — the value already changed externally.
+ */
+export function registerNavigationStore(store: NavigationStore): void {
+  registeredStore = store;
+  setRangoStateObserver(() => {
+    registeredStore?.markHistoryCacheStale();
+  });
+}
+
+/** The active navigation store, or null before boot has registered it. */
+export function getRegisteredStore(): NavigationStore | null {
+  return registeredStore;
+}