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

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();
@@ -262,17 +216,20 @@ export function createNavigationBridge(
         store.setInterceptSourceUrl(null);
       }
 
-      // Before navigating away, update the source page's cache with the latest handleData.
-      // This ensures the cache has correct handleData even if handles were streaming.
+      // Before navigating away, update the source page's cache with the latest
+      // handleData. This ensures the cache has correct handleData even if handles
+      // were streaming. Use updateCacheHandleData (not cacheSegmentsForHistory):
+      // the source page's segments are unchanged, so this is a handleData refresh,
+      // not a commit. Critically it PRESERVES the entry's stale flag — when the
+      // source page has a deferred Meta still pending, its entry was marked stale
+      // (invalidate-on-pending) so a popstate return revalidates; re-committing it
+      // here would reset stale to false and serve the carried (pre-resolution)
+      // title as fresh. It also leaves the nav-instance token intact.
       const sourceHistoryKey = store.getHistoryKey();
       const sourceCached = store.getCachedSegments(sourceHistoryKey);
       if (sourceCached?.segments && sourceCached.segments.length > 0) {
         const currentHandleData = eventController.getHandleState().data;
-        store.cacheSegmentsForHistory(
-          sourceHistoryKey,
-          sourceCached.segments,
-          currentHandleData,
-        );
+        store.updateCacheHandleData(sourceHistoryKey, currentHandleData);
       }
 
       // Check if we have cached segments for target URL
@@ -372,8 +329,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 +354,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 +389,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 +409,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 +478,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
@@ -541,7 +535,14 @@ export function createNavigationBridge(
             },
             scroll: { restore: true, isStreaming },
           };
-          const hasTransition = cachedSegments.some((s) => s.transition);
+          // Intercept-driven popstate (entering OR leaving an intercept) only
+          // mutates the parallel slot; the main outlet shows the same content.
+          // Skip startViewTransition in those cases — same rationale as the
+          // intercept guard in partial-update.ts's hasTransition computation.
+          const hasTransition =
+            !isIntercept &&
+            !isLeavingIntercept &&
+            cachedSegments.some((s) => s.transition);
           if (hasTransition) {
             startTransition(() => {
               if (addTransitionType) {
@@ -556,8 +557,19 @@ export function createNavigationBridge(
           // 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 = cachedSegments.map((s) => s.id);
+            // Background revalidation - don't await, just fire and forget.
+            // When the entry's handles are incomplete (a deferred Meta was still
+            // pending when the user navigated away — see handlesPending), send NO
+            // segment IDs so the server returns a FULL re-render with the handle
+            // stream. A normal stale revalidation sends the cached IDs and the
+            // server returns a diff-only payload that omits unchanged segments'
+            // handles, so a deferred Meta would never re-stream and the title
+            // would stay the pre-resolution carry. handlesPending is set only for
+            // the deferred-Meta-aborted case, so action/cross-tab SWR keeps the
+            // cheap diff path.
+            const segmentIds = cached?.handlesPending
+              ? []
+              : cachedSegments.map((s) => s.id);
 
             const tx = createNavigationTransaction(
               store,
@@ -631,8 +643,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;
         }
 
@@ -649,7 +666,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]();
       }
@@ -704,15 +724,15 @@ export function createNavigationBridge(
       };
     },
 
+    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;
+}