@rangojs/router 0.32.0 → 0.33.0

package/src/browser/navigation-bridge.ts

@@ -43,7 +43,7 @@ import {
   generateHistoryKey,
   liveHandleDataForCache,
 } from "./navigation-store.js";
-import type { EventController } from "./event-controller.js";
+import type { EventController, NavigationEntry } from "./event-controller.js";
 import { isInterceptOnlyCache } from "./intercept-utils.js";
 import { actionBoundaryAt, idsAboveBoundary } from "./segment-reconciler.js";
 import {
@@ -140,6 +140,82 @@ function isRestorable(
   );
 }
 
+/**
+ * The request a stale-prefetch revalidation makes (scheduleStalePrefetch-
+ * Revalidation): the ids it holds, and the intercept and action error
+ * boundary on screen.
+ */
+export interface StalePrefetchRevalidation {
+  segmentIds: string[];
+  intercept: { isIntercept: boolean; sourceUrl?: string };
+  boundary: string | undefined;
+}
+
+/**
+ * A click that adopted a prefetch a server action marked stale
+ * (prefetch/cache.ts isPrefetchStale) committed the pre-write payload, as any
+ * prefetched click commits. Once that navigation settled
+ * (NavigationEntry.settled: its commit, any `prefetch: false` fill and its
+ * stream, so this never supersedes the click nor cuts a response
+ * that arrived short), `revalidate` runs the page's request in
+ * Back's lane (the bridge's revalidateInBackground), with the ids on screen
+ * and the action error boundary it shows held, as Back onto a stale entry
+ * does.
+ *
+ * The entry is marked stale first, so a Back onto it revalidates when this
+ * one never ran or was left. Nothing runs when the click did not commit, or
+ * when the page moved since (a newer navigation aborts the click's entry, a
+ * shallow one moves the history key) or another navigation is open. An
+ * action in flight does not hold it back, as it does not hold Back's: its
+ * follow-up, when it owes one, starts a navigation that supersedes this one.
+ *
+ * Exported so renderRoute (testing/render-route.tsx) drives these guards and
+ * this plan rather than a copy of them.
+ */
+export function scheduleStalePrefetchRevalidation(
+  store: Pick<
+    NavigationStore,
+    "getCachedSegments" | "getHistoryKey" | "updateCacheHandleData"
+  >,
+  eventController: Pick<EventController, "getUnsettledNavigation">,
+  entry: Pick<NavigationEntry, "settled">,
+  historyKey: string,
+  revalidate: (request: StalePrefetchRevalidation) => void,
+): void {
+  void entry.settled.then((committed) => {
+    if (!committed) return;
+    const cached = store.getCachedSegments(historyKey);
+    if (!cached) return;
+    store.updateCacheHandleData(historyKey, cached.handleData ?? {}, true);
+    if (
+      store.getHistoryKey() !== historyKey ||
+      eventController.getUnsettledNavigation() ||
+      !isRestorable(cached.segments)
+    ) {
+      return;
+    }
+    const historyState = window.history.state;
+    const isIntercept = historyState?.intercept === true;
+    const boundaryAt = isIntercept ? -1 : actionBoundaryAt(cached.segments);
+    if (boundaryAt === 0) return;
+    const boundary = cached.segments[boundaryAt]?.id;
+    debugLog("[Browser] Stale prefetch committed, background revalidating");
+    // A deferred Meta still pending when its handles were cached: a whole
+    // render re-streams them (handlePopstate, handlesPending).
+    const segmentIds = cached.handlesPending
+      ? []
+      : idsAboveBoundary(
+          cached.segments.map((s) => s.id),
+          boundary,
+        );
+    revalidate({
+      segmentIds,
+      intercept: { isIntercept, sourceUrl: historyState?.sourceUrl },
+      boundary,
+    });
+  });
+}
+
 /**
  * Create a navigation bridge for handling client-side navigation
  *
@@ -236,6 +312,53 @@ export function createNavigationBridge(
     });
   }
 
+  /**
+   * Back's stale-revalidation lane: a background request for the page on
+   * screen (skipLoadingState: useNavigation() stays idle, useLinkStatus shows
+   * nothing) that holds `segmentIds` and an action error boundary on screen,
+   * re-caches the entry (cacheOnly) and commits as kind "revalidate". Used by
+   * a Back/Forward restore of a stale entry (handlePopstate) and after a click
+   * on a stale prefetch (scheduleStalePrefetchRevalidation).
+   */
+  function revalidateInBackground(
+    url: string,
+    segmentIds: string[],
+    intercept: { isIntercept: boolean; sourceUrl?: string },
+    boundary: string | undefined,
+  ): void {
+    const tx = createNavigationTransaction(store, eventController, url, {
+      skipLoadingState: true,
+      replace: true,
+    });
+
+    fetchPartialUpdate(
+      url,
+      segmentIds,
+      false,
+      tx.handle.signal,
+      tx.with({
+        url,
+        replace: true,
+        scroll: false,
+        intercept: intercept.isIntercept,
+        interceptSourceUrl: intercept.sourceUrl,
+        cacheOnly: true,
+      }),
+      {
+        type: "stale-revalidation",
+        interceptSourceUrl: intercept.sourceUrl,
+        boundary,
+      },
+    )
+      .catch((error) => {
+        if (isBackgroundSuppressible(error)) return;
+        console.error("[Browser] Background revalidation failed:", error);
+      })
+      .finally(() => {
+        tx[Symbol.dispose]();
+      });
+  }
+
   const bridge: NavigationBridge = {
     /**
      * Navigate to a URL
@@ -387,6 +510,17 @@ export function createNavigationBridge(
         store.updateCacheHandleData(sourceHistoryKey, currentHandleData);
       }
 
+      // Read the rango state BEFORE the target entry's stale bit, as
+      // handlePopstate does. Another tab's write reaches this tab only through
+      // a read (rango-state.ts write observer) when its broadcast does not:
+      // the pages share no segment, or crossTabSync is off. The first read
+      // otherwise comes from the navigation client, after the held ids below
+      // are chosen, and the server keeps what the client says it holds when
+      // the default allows (router/revalidation.ts: a route whose params and
+      // search are the entry's, a layout loader with no revalidate()), so the
+      // entry's pre-write copy would commit as fresh.
+      getRangoState();
+
       // Check if we have cached segments for target URL
       const historyKey = generateHistoryKey(url);
       const cached = store.getCachedSegments(historyKey);
@@ -441,6 +575,9 @@ export function createNavigationBridge(
         state: resolvedState,
         skipLoadingState: false,
       });
+      // This navigation's entry when its response was a prefetch an action
+      // marked stale (scheduleStalePrefetchRevalidation).
+      let stalePrefetchEntry: NavigationEntry | null = null;
       // A cross-route clientUrls() navigation presents its destination
       // optimistically at once: transition({ when }) decides THERE (the first
       // presentation), over the destination route's predicate and those of
@@ -520,8 +657,30 @@ export function createNavigationBridge(
                 ...(clientUrlPresentation && {
                   presentation: clientUrlPresentation,
                 }),
+                // The last response decides: a fresh refetch after a stale
+                // adoption (a fill's start-over) clears it.
+                onStalePrefetch: (stale: boolean) => {
+                  const entry = eventController.getUnsettledNavigation();
+                  stalePrefetchEntry =
+                    stale && entry?.abort === tx.handle.abort ? entry : null;
+                },
               },
         );
+        if (stalePrefetchEntry && !tx.handle.signal.aborted) {
+          scheduleStalePrefetchRevalidation(
+            store,
+            eventController,
+            stalePrefetchEntry,
+            store.getHistoryKey(),
+            ({ segmentIds, intercept, boundary }) =>
+              revalidateInBackground(
+                window.location.href,
+                segmentIds,
+                intercept,
+                boundary,
+              ),
+          );
+        }
       } catch (error) {
         // 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
@@ -846,39 +1005,12 @@ export function createNavigationBridge(
               // the deferred-Meta-aborted case, so action/cross-tab SWR keeps the
               // cheap diff path.
               const segmentIds = cached?.handlesPending ? [] : heldIds;
-
-              const tx = createNavigationTransaction(
-                store,
-                eventController,
-                url,
-                { skipLoadingState: true, replace: true },
-              );
-
-              fetchPartialUpdate(
+              revalidateInBackground(
                 url,
                 segmentIds,
-                false,
-                tx.handle.signal,
-                tx.with({
-                  url,
-                  replace: true,
-                  scroll: false,
-                  intercept: isIntercept,
-                  interceptSourceUrl,
-                  cacheOnly: true,
-                }),
-                { type: "stale-revalidation", interceptSourceUrl, boundary },
-              )
-                .catch((error) => {
-                  if (isBackgroundSuppressible(error)) return;
-                  console.error(
-                    "[Browser] Background revalidation failed:",
-                    error,
-                  );
-                })
-                .finally(() => {
-                  tx[Symbol.dispose]();
-                });
+                { isIntercept, sourceUrl: interceptSourceUrl },
+                boundary,
+              );
             }
           };
           // React commits a transition started while window.event is the

package/src/browser/navigation-client.ts

@@ -13,6 +13,7 @@ import {
   startBrowserTransaction,
 } from "./logging.js";
 import { getRangoState } from "./rango-state.js";
+import { stateEpoch } from "./cookie-name.js";
 import { isActionFenceActive } from "./action-fence.js";
 import {
   expandPayloadFragments,
@@ -35,11 +36,54 @@ import {
   consumePrefetch,
   disableFragmentPassthrough,
   isFragmentPassthroughEnabled,
+  isPrefetchStale,
+  pageMatchesParamsLabel,
+  paramsCandidateKeys,
   type DecodedPrefetch,
 } from "./prefetch/cache.js";
+import { getCommittedPage } from "./navigation-store-handle.js";
+import type { SourcePage } from "../prefetch-source-scope.js";
 import { cancelAllPrefetches } from "./prefetch/loader.js";
 import { writePartialParams } from "./wire-protocol.js";
 
+/**
+ * The completed prefetch a navigation adopts: the one stored under its
+ * source key, else one stored for a group of source pages the page is in
+ * (`paramsKeys`, paramsCandidateKeys), else the one every source page
+ * shares. None when the navigation cannot use a prefetch. A stale one only
+ * when `acceptStale` (FetchPartialOptions.acceptStalePrefetch).
+ */
+export function consumeStoredPrefetch(
+  canUsePrefetch: boolean,
+  sourceKey: string,
+  paramsKeys: readonly string[],
+  wildcardKey: string,
+  acceptStale = false,
+): { entry: DecodedPrefetch | null; hitKey: string | null } {
+  if (!canUsePrefetch) return { entry: null, hitKey: null };
+  for (const key of [sourceKey, ...paramsKeys, wildcardKey]) {
+    const entry = consumePrefetch(key, { acceptStale });
+    if (entry) return { entry, hitKey: key };
+  }
+  return { entry: null, hitKey: null };
+}
+
+/**
+ * Whether a navigation from `page` may serve an in-flight prefetch it
+ * adopted through the wildcard key: not one the server scoped to its own
+ * source page, nor one scoped to a group of source pages `page` is not in.
+ */
+export function wildcardAdoptionFits(
+  entry: DecodedPrefetch,
+  page: SourcePage | null,
+): boolean {
+  if (entry.scope === "source") return false;
+  if (entry.scope === "params") {
+    return pageMatchesParamsLabel(entry.paramsLabel ?? "", page);
+  }
+  return true;
+}
+
 /**
  * Create a navigation client for fetching RSC payloads
  *
@@ -88,8 +132,14 @@ export function createNavigationClient(
         routerId,
         hmr,
         fill,
+        acceptStalePrefetch = false,
       } = options;
 
+      // The page left, absolute: the router store keeps a committed URL as
+      // navigate() was given it, often a path. The header and the source
+      // prefetch key name it as prefetch/fetch.ts does, so they agree.
+      const sourceHref = new URL(previousUrl, window.location.origin).href;
+
       const debugEnabled = isBrowserDebugEnabled();
       const tx = debugEnabled
         ? startBrowserTransaction(staleRevalidation ? "revalidate" : "navigate")
@@ -135,8 +185,13 @@ export function createNavigationClient(
       // intercept targets, 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.
+      // Both keys embed the Rango state's epoch (`{version}:{timestamp}`,
+      // cookie-name.ts stateEpoch), so state rotation (deploy or
+      // invalidateClientCache()) auto-invalidates both scopes. A server
+      // action bumps only the write part, which the keys leave out: it marks
+      // entries stale instead, and one is still served to a click
+      // (acceptStalePrefetch), whose bridge revalidates its page after it
+      // settled (stalePrefetch); for any other caller it is a miss.
       // Skip cache for stale revalidation (needs fresh data), HMR (needs
       // fresh modules), and intercept contexts (source-dependent responses).
       // A prefetch served during an action's flight holds pre-write data:
@@ -144,20 +199,22 @@ export function createNavigationClient(
       const canUsePrefetch =
         !staleRevalidation && !hmr && !fill && !interceptSourceUrl;
       const rangoState = getRangoState();
-      const wildcardKey = buildPrefetchKey(rangoState, fetchUrl);
-      const cacheKey = buildSourceKey(rangoState, previousUrl, fetchUrl);
+      const stateKey = stateEpoch(rangoState);
+      const wildcardKey = buildPrefetchKey(stateKey, fetchUrl);
+      const cacheKey = buildSourceKey(stateKey, sourceHref, fetchUrl);
+      // The page being left, as the router store committed it: the group a
+      // params-scoped prefetch must have been answered for.
+      const sourcePage = canUsePrefetch ? getCommittedPage() : null;
 
-      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;
-        }
-      }
+      const stored = consumeStoredPrefetch(
+        canUsePrefetch,
+        cacheKey,
+        paramsCandidateKeys(stateKey, fetchUrl, sourcePage),
+        wildcardKey,
+        acceptStalePrefetch,
+      );
+      const cachedEntry = stored.entry;
+      let hitKey = stored.hitKey;
 
       let inflightEntryPromise: Promise<DecodedPrefetch | null> | null = null;
       if (canUsePrefetch && !cachedEntry) {
@@ -262,7 +319,7 @@ export function createNavigationClient(
               cache: "no-store" as RequestCache,
             }),
             headers: {
-              "X-RSC-Router-Client-Path": previousUrl,
+              "X-RSC-Router-Client-Path": sourceHref,
               // Reuse the single per-operation read (see rangoState above): the
               // cache-key lookup and this header must agree on one value, and the
               // cookie read has side effects (external-rotation notify) we do not
@@ -312,6 +369,9 @@ export function createNavigationClient(
       // (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;
+      // A prefetch an action marked stale after it was fetched: committed
+      // like any other, then revalidated (FetchPartialResult.stalePrefetch).
+      let stalePrefetch = false;
 
       // The prefetch entry this navigation serves.
       let adopted = cachedEntry;
@@ -335,15 +395,27 @@ export function createNavigationClient(
           if (tx) {
             browserDebugLog(tx, "inflight prefetch unavailable, refetching");
           }
-        } 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.
+        } else if (
+          adoptedViaWildcard &&
+          !wildcardAdoptionFits(entry, sourcePage)
+        ) {
+          // A wildcard-adopted inflight that turned out source-scoped, or
+          // params-scoped to a group this page is not in, was built for a
+          // different source page. Discard and refetch.
           if (tx) {
             browserDebugLog(
               tx,
-              "wildcard inflight turned out source-scoped, refetching",
+              `wildcard inflight turned out ${entry.scope}-scoped, refetching`,
             );
           }
+        } else if (!acceptStalePrefetch && isPrefetchStale(entry)) {
+          // An action marked it stale, and this navigation never revalidates
+          // (not a click): drop it and fetch fresh. Its reserve is released;
+          // the decode it started is never read.
+          entry.dispose?.();
+          if (tx) {
+            browserDebugLog(tx, "inflight prefetch is stale, refetching");
+          }
         } else {
           adopted = entry;
         }
@@ -357,6 +429,7 @@ export function createNavigationClient(
         // prefetched"; a still-streaming one keeps streaming its fallbacks like
         // a cold load.
         fullyPrefetched = adopted.complete;
+        stalePrefetch = isPrefetchStale(adopted);
       } else {
         ({ payload: payloadPromise, streamComplete: streamCompletePromise } =
           freshResult());
@@ -393,6 +466,7 @@ export function createNavigationClient(
           const recovery = freshResult(false, true);
           streamCompletePromise = recovery.streamComplete;
           fullyPrefetched = false;
+          stalePrefetch = false;
           payload = await recovery.payload;
           await expandPayloadFragments(payload, deps.createFromReadableStream);
         }
@@ -414,6 +488,7 @@ export function createNavigationClient(
           payload,
           streamComplete: streamCompletePromise,
           fullyPrefetched,
+          stalePrefetch,
         };
       } catch (error) {
         // Convert network-level errors to NetworkError for proper handling

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

@@ -7,13 +7,23 @@
  * 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.
+ * Dependency-light on purpose: it imports only the action fence, the
+ * rango-state observers 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 {
+  noteStateRotation,
+  noteStateWrite,
+  setUnlandedWriteHandler,
+} from "./action-fence.js";
+import {
+  setRangoStateObserver,
+  setRangoStateWriteObserver,
+} from "./rango-state.js";
 import type { NavigationStore } from "./types.js";
+import type { SourcePage } from "../prefetch-source-scope.js";
 
 let registeredStore: NavigationStore | null = null;
 
@@ -23,16 +33,68 @@ let registeredStore: NavigationStore | null = null;
  * 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.
+ * re-rotation — the value already changed externally. A rotation seen while
+ * an action is in flight is recorded on the fence: the action's landing then
+ * sends the full broadcast (navigation-store.ts markCacheAsStaleAndBroadcast).
+ *
+ * A read that sees only the write part change (a server action's response,
+ * in this tab or another) marks this tab's history entries and prefetches
+ * stale, as a soft broadcast's receiver does: a tab the broadcast does not
+ * reach would otherwise serve a prefetch made before the write as fresh.
+ * While an action is in flight the write is recorded on the fence instead:
+ * the action's landing marks every cache stale once (navigation-store.ts
+ * markStaleSoftAndBroadcast), and when no landing does, the fence's drop
+ * marks them.
  */
 export function registerNavigationStore(store: NavigationStore): void {
   registeredStore = store;
   setRangoStateObserver(() => {
+    noteStateRotation();
     registeredStore?.markHistoryCacheStale();
   });
+  const markCachesStale = () => registeredStore?.markCachesStaleAfterWrite();
+  setRangoStateWriteObserver(() => {
+    if (!noteStateWrite()) markCachesStale();
+  });
+  setUnlandedWriteHandler(markCachesStale);
 }
 
 /** The active navigation store, or null before boot has registered it. */
 export function getRegisteredStore(): NavigationStore | null {
   return registeredStore;
 }
+
+let readCommittedPage: (() => SourcePage) | null = null;
+
+/**
+ * Register the reader of the committed page's params and route name: the
+ * router store's own state, which useParams reads (the event controller's
+ * params, the displayed history entry's route name). Read by the prefetch
+ * cache outside render, at request time, to look up an answer shared by the
+ * pages with equal values of what a revalidate() rule read
+ * (prefetch-source-scope.ts). A reader, not a copy: there is no second
+ * source of truth for the params.
+ */
+export function registerCommittedPageReader(read: () => SourcePage): void {
+  readCommittedPage = read;
+}
+
+/**
+ * The boot reader (rsc-router.tsx): the event controller's params, which
+ * useParams reads and only a commit sets (an optimistic clientUrls() frame
+ * sets React context, not them), and the displayed entry's route name.
+ */
+export function committedPageOf(
+  controller: { getParams(): Record<string, string> },
+  store: Pick<NavigationStore, "getHistoryEntryMemory">,
+): () => SourcePage {
+  return () => ({
+    params: controller.getParams(),
+    routeName: store.getHistoryEntryMemory()?.routeName,
+  });
+}
+
+/** The committed page, or null before boot has registered its reader. */
+export function getCommittedPage(): SourcePage | null {
+  return readCommittedPage ? readCommittedPage() : null;
+}