@rangojs/router 0.0.0-experimental.d20dd405 → 0.0.0-experimental.d5d3070a

package/src/browser/navigation-bridge.ts

@@ -5,15 +5,15 @@ import type {
   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 { isActionFenceActive } from "./action-fence.js";
+import { getRangoState } from "./rango-state.js";
 import * as React from "react";
 import { startTransition } from "react";
 import {
   createNavigationTransaction,
   resolveNavigationState,
 } from "./navigation-transaction.js";
-import { buildHistoryState } from "./history-state.js";
+import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
 import {
   handleNavigationStart,
   handleNavigationEnd,
@@ -32,6 +32,7 @@ import { isInterceptOnlyCache } from "./intercept-utils.js";
 import {
   toNetworkError,
   emitNetworkError,
+  emitNavigationError,
   isBackgroundSuppressible,
 } from "./network-error-handler.js";
 import { debugLog } from "./logging.js";
@@ -50,13 +51,8 @@ export { createNavigationTransaction };
  */
 export interface NavigationBridgeConfigWithController extends NavigationBridgeConfig {
   eventController: EventController;
-  /** RSC version from initial payload metadata (fallback when appShellRef is not provided) */
+  /** RSC version from initial payload metadata. */
   version?: string;
-  /**
-   * Live app-shell ref. When supplied, the bridge reads version/basename
-   * from this ref so cross-app navigations propagate correctly.
-   */
-  appShellRef?: AppShellRef;
 }
 
 /**
@@ -75,46 +71,9 @@ export interface NavigationBridgeConfigWithController extends NavigationBridgeCo
 export function createNavigationBridge(
   config: NavigationBridgeConfigWithController,
 ): NavigationBridge {
-  const {
-    store,
-    client,
-    eventController,
-    onUpdate,
-    renderSegments,
-    appShellRef,
-  } = config;
+  const { store, client, eventController, onUpdate, renderSegments } = 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({
     store,
@@ -122,7 +81,6 @@ export function createNavigationBridge(
     onUpdate,
     renderSegments,
     getVersion: () => version,
-    applyAppShell,
   });
 
   return {
@@ -204,11 +162,7 @@ export function createNavigationBridge(
           },
           {},
         );
-        if (options.replace) {
-          window.history.replaceState(historyState, "", url);
-        } else {
-          window.history.pushState(historyState, "", url);
-        }
+        pushHistoryWithIdx(historyState, url, options?.replace ?? false);
 
         // Ensure new history entry has a scroll restoration key
         ensureHistoryKey();
@@ -372,8 +326,15 @@ export function createNavigationBridge(
           } as NavigateOptionsInternal);
         }
 
-        if (error instanceof DOMException && error.name === "AbortError") {
-          debugLog("[Browser] Navigation aborted by newer navigation");
+        // Aborted, or superseded by a newer navigation. A superseded nav may
+        // reject with a non-AbortError (e.g. a Flight decode that fails after its
+        // signal was aborted), so check the signal too -- otherwise we would
+        // render a boundary that clobbers the newer navigation's content.
+        if (
+          (error instanceof DOMException && error.name === "AbortError") ||
+          tx.handle.signal.aborted
+        ) {
+          debugLog("[Browser] Navigation aborted or superseded");
           return;
         }
 
@@ -390,7 +351,13 @@ export function createNavigationBridge(
           return;
         }
 
-        throw error;
+        // A response we could not process (undecodable Flight body, or an
+        // unanticipated failure building the response). Surface the route's
+        // error boundary rather than let the rejection abort the navigation
+        // silently. Prefetched responses funnel here too: a failed warm-prefetch
+        // payload rejects on consumption and propagates to this catch.
+        console.error("[Browser] Unprocessable navigation response:", error);
+        emitNavigationError(onUpdate, error, url);
       } finally {
         tx[Symbol.dispose]();
       }
@@ -419,6 +386,14 @@ export function createNavigationBridge(
           tx.with({ url: window.location.href, replace: true, scroll: false }),
         );
       } catch (error) {
+        // Aborted or superseded: bail without rendering a boundary (see navigate()).
+        if (
+          (error instanceof DOMException && error.name === "AbortError") ||
+          tx.handle.signal.aborted
+        ) {
+          return;
+        }
+
         const networkError = toNetworkError(error, {
           url: window.location.href,
           operation: "revalidation",
@@ -431,7 +406,12 @@ export function createNavigationBridge(
           emitNetworkError(onUpdate, networkError, window.location.href);
           return;
         }
-        throw error;
+
+        // refresh() shares the fetchPartialUpdate chokepoint with navigate()/
+        // popstate, so an unprocessable response must surface the error boundary
+        // here too rather than become an uncaught rejection.
+        console.error("[Browser] Unprocessable refresh response:", error);
+        emitNavigationError(onUpdate, error, window.location.href);
       } finally {
         tx[Symbol.dispose]();
       }
@@ -495,11 +475,22 @@ export function createNavigationBridge(
       // Helper to check if streaming is in progress
       const isStreaming = () => eventController.getState().isStreaming;
 
+      // Surface any external rotation of the rango state cookie (a server
+      // Set-Cookie, a sibling tab, a cookie clear) BEFORE reading the stale bit.
+      // The divergence observer only runs inside getRangoState() — fetch-time —
+      // so a popstate-first interaction would otherwise serve a pre-mutation
+      // page as fresh and never fetch to trigger the observer. Reading here lets
+      // the observer mark the history cache stale so getCachedSegments sees it.
+      getRangoState();
+
       // Check if we can restore from history cache
       const cached = store.getCachedSegments(historyKey);
       const cachedSegments = cached?.segments;
       const cachedHandleData = cached?.handleData;
-      const isStale = cached?.stale ?? false;
+      // While an action is in flight the fence persists no stale flag, so OR it
+      // in here: a popstate during the flight serves the cached entry AND
+      // revalidates (SWR) instead of serving it as fresh.
+      const isStale = (cached?.stale ?? false) || isActionFenceActive();
 
       if (cachedSegments && cachedSegments.length > 0) {
         // Update store to point to this history entry
@@ -638,8 +629,13 @@ export function createNavigationBridge(
         // Restore scroll position after fetch completes
         handleNavigationEnd({ restore: true, isStreaming });
       } catch (error) {
-        if (error instanceof DOMException && error.name === "AbortError") {
-          debugLog("[Browser] Popstate navigation aborted");
+        // Aborted or superseded by a newer navigation: bail without clobbering
+        // content with a boundary (see navigate()).
+        if (
+          (error instanceof DOMException && error.name === "AbortError") ||
+          tx.handle.signal.aborted
+        ) {
+          debugLog("[Browser] Popstate navigation aborted or superseded");
           return;
         }
 
@@ -656,7 +652,10 @@ export function createNavigationBridge(
           return;
         }
 
-        throw error;
+        // Unprocessable response on a back/forward navigation: surface the
+        // error boundary instead of an uncaught rejection (see navigate()).
+        console.error("[Browser] Unprocessable popstate response:", error);
+        emitNavigationError(onUpdate, error, url);
       } finally {
         tx[Symbol.dispose]();
       }
@@ -675,55 +674,6 @@ export function createNavigationBridge(
         this.handlePopstate();
       };
 
-      // React's experimental ViewTransition integration deliberately skips
-      // animations for commits originating from a popstate event handler —
-      // popstate must finish synchronously to preserve scroll/form
-      // restoration, which conflicts with running a transition. The
-      // Navigation API's `navigate` event runs in an async-safe context
-      // (`event.intercept({ handler })` lets us await), so commits made
-      // inside the intercept handler are NOT popstate-originated from
-      // React's perspective and the VT walker fires normally for
-      // back-/forward-navigations. Falls back to popstate on browsers
-      // without Navigation API support (Firefox today); on those browsers
-      // back-nav view transitions won't fire — matching the React
-      // limitation and current behavior.
-      // See https://react.dev/reference/react/ViewTransition.
-      const navigationApi: any = (window as any).navigation;
-      const supportsNavigationApi =
-        !!navigationApi && typeof navigationApi.addEventListener === "function";
-
-      const handleNavigateEvent = (event: any): void => {
-        // Only handle browser history traversal (back/forward).
-        // Push/replace are still driven by setupLinkInterception →
-        // this.navigate(...) (which calls history.pushState/replaceState).
-        if (event.navigationType !== "traverse") return;
-        if (!event.canIntercept) return;
-        // canIntercept doesn't exclude every cross-document case (e.g., back
-        // to a previous same-origin non-Rango document, or a doc-level
-        // history.go() target). Without this guard, event.intercept() would
-        // forcibly turn that into a same-document navigation and route it
-        // through handlePopstate — silently breaking the destination page.
-        if (!event.destination?.sameDocument) return;
-        if (event.hashChange || event.downloadRequest) return;
-        // Known limitation: Chromium's Navigation API replaces the entry's
-        // history.state with `null` when an intercepted traverse commits,
-        // which clobbers the scroll-restoration `key` that rango stamps
-        // onto each history entry. Attempts to write the state back from
-        // the handler, finally, or event.finished all run after React's
-        // commit-phase useLayoutEffect has already read history.state, so
-        // none of them help. Consumers who rely on per-entry scroll
-        // restoration should use a URL-based scroll key today
-        // (useScrollRestoration({ getKey: ({ pathname }) => pathname }) or
-        // similar). Tracked as follow-up to switch scroll-restoration to
-        // navigation.currentEntry.id (or rango-store-backed keys) so it
-        // survives the intercept commit.
-        event.intercept({
-          handler: async () => {
-            await this.handlePopstate();
-          },
-        });
-      };
-
       // When the browser restores a page from bfcache (back-forward cache),
       // any in-flight navigation state is stale. This happens when:
       // 1. A navigation triggers X-RSC-Reload (e.g., response route hit via SPA)
@@ -749,35 +699,26 @@ export function createNavigationBridge(
         this.refresh();
       });
 
-      if (supportsNavigationApi) {
-        navigationApi.addEventListener("navigate", handleNavigateEvent);
-        debugLog("[Browser] Navigation bridge ready (Navigation API)");
-      } else {
-        window.addEventListener("popstate", handlePopstate);
-        debugLog("[Browser] Navigation bridge ready (popstate fallback)");
-      }
+      window.addEventListener("popstate", handlePopstate);
       window.addEventListener("pageshow", handlePageShow);
+      debugLog("[Browser] Navigation bridge ready");
 
       return () => {
         cleanupLinks();
-        if (supportsNavigationApi) {
-          navigationApi.removeEventListener("navigate", handleNavigateEvent);
-        } else {
-          window.removeEventListener("popstate", handlePopstate);
-        }
+        window.removeEventListener("popstate", handlePopstate);
         window.removeEventListener("pageshow", handlePageShow);
       };
     },
 
+    getVersion(): string | undefined {
+      return version;
+    },
+
     updateVersion(newVersion: string): void {
       version = newVersion;
       setAppVersion(newVersion);
       store.clearHistoryCache();
     },
-
-    updateAppShell(next: AppShell): void {
-      applyAppShell(next);
-    },
   };
 }
 

package/src/browser/navigation-client.ts

@@ -12,16 +12,20 @@ import {
   startBrowserTransaction,
 } from "./logging.js";
 import { getRangoState } from "./rango-state.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";
 
 /**
@@ -105,31 +109,38 @@ export function createNavigationClient(
       // 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;
+      // 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 cachedResponse: Response | null = null;
+      let cachedEntry: DecodedPrefetch | null = null;
       let hitKey: string | null = null;
       if (canUsePrefetch) {
-        cachedResponse = consumePrefetch(cacheKey);
-        if (cachedResponse) {
+        cachedEntry = consumePrefetch(cacheKey);
+        if (cachedEntry) {
           hitKey = cacheKey;
         } else {
-          cachedResponse = consumePrefetch(wildcardKey);
-          if (cachedResponse) hitKey = wildcardKey;
+          cachedEntry = consumePrefetch(wildcardKey);
+          if (cachedEntry) hitKey = wildcardKey;
         }
       }
 
-      let inflightResponsePromise: Promise<Response | null> | null = null;
-      if (canUsePrefetch && !cachedResponse) {
-        inflightResponsePromise = consumeInflightPrefetch(cacheKey);
-        if (inflightResponsePromise) {
+      let inflightEntryPromise: Promise<DecodedPrefetch | null> | null = null;
+      if (canUsePrefetch && !cachedEntry) {
+        inflightEntryPromise = consumeInflightPrefetch(cacheKey);
+        if (inflightEntryPromise) {
           hitKey = cacheKey;
         } else {
-          inflightResponsePromise = consumeInflightPrefetch(wildcardKey);
-          if (inflightResponsePromise) hitKey = wildcardKey;
+          inflightEntryPromise = consumeInflightPrefetch(wildcardKey);
+          if (inflightEntryPromise) hitKey = wildcardKey;
         }
       }
       // Track when the stream completes
@@ -148,21 +159,17 @@ export function createNavigationClient(
         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 (${source})`, {
-              reloadUrl: reload.url,
-            });
-          }
-          window.location.href = reload.url;
-          // Block further processing — page is reloading
-          return new Promise<Response>(() => {});
-        }
+        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
@@ -183,6 +190,19 @@ export function createNavigationClient(
           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;
       };
 
@@ -195,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(),
@@ -220,29 +245,39 @@ 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", {
+          browserDebugLog(tx, "prefetch cache hit (warm)", {
             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) {
+        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: hitKey,
@@ -250,51 +285,38 @@ export function createNavigationClient(
           });
         }
         const adoptedViaWildcard = hitKey === wildcardKey;
-        responsePromise = inflightResponsePromise.then(async (response) => {
-          if (!response) {
-            if (tx) {
-              browserDebugLog(tx, "inflight prefetch unavailable, refetching");
-            }
-            return doFreshFetch();
+        const entry = await inflightEntryPromise;
+        if (!entry) {
+          if (tx) {
+            browserDebugLog(tx, "inflight prefetch unavailable, refetching");
           }
-
-          // 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();
+          ({ 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",
+            );
           }
-
-          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,
-          );
-        });
+          ({ 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 {
-        const payload = await deps.createFromFetch<RscPayload>(responsePromise);
+        const payload = await payloadPromise;
 
         if (tx) {
           browserDebugLog(tx, "response received", {
@@ -303,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;
+}