@rangojs/router 0.31.0 → 0.33.0

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;
+}

package/src/browser/navigation-store.ts

@@ -10,7 +10,11 @@ import type {
   ShownEntry,
 } from "./types.js";
 import type { EventController } from "./event-controller.js";
-import { clearPrefetchCache } from "./prefetch/cache.js";
+import { clearPrefetchCache, markPrefetchesStale } from "./prefetch/cache.js";
+import {
+  takeStateRotationInActionFence,
+  takeStateWriteInActionFence,
+} from "./action-fence.js";
 import { LoaderStore } from "../loader-store.js";
 import {
   adoptRangoState,
@@ -172,8 +176,8 @@ export interface NavigationStoreConfig {
 
   /**
    * Enable cross-tab cache invalidation via BroadcastChannel (default: true)
-   * When cache is cleared (via server actions or invalidateClientCache()),
-   * other tabs will also clear their cache
+   * After a server action other tabs that share a segment mark their caches
+   * stale; after invalidateClientCache() they adopt its state and flush
    */
   crossTabSync?: boolean;
 
@@ -332,22 +336,57 @@ export function createNavigationStore(
    */
   function clearCacheAndBroadcast(): void {
     clearCacheInternal();
-    broadcastInvalidation();
+    broadcastInvalidation(false);
   }
 
   /**
-   * Mark cache as stale and broadcast to other tabs
+   * Mark cache as stale, flush the prefetch caches (rotating the state), and
+   * broadcast to other tabs: the client seat of `invalidateClientCache()`.
    */
   function markStaleAndBroadcast(): void {
     markCacheAsStaleInternal();
-    broadcastInvalidation();
+    broadcastInvalidation(false);
+  }
+
+  /**
+   * What a server action without a directive does once its response arrived
+   * (server-action-bridge.ts finalizeAction). History entries and prefetches
+   * are marked stale, nothing is flushed or rotated, and other tabs get a
+   * `soft` broadcast: they mark theirs stale and refresh.
+   *
+   * When the state rotated during the action (the action called the server
+   * seat of `invalidateClientCache()`, whose `Set-Cookie` reached the jar),
+   * it does what every action did before #1329: flush the prefetch map,
+   * rotate the state once more and send the full broadcast. The second
+   * rotation is what lets other tabs adopt: one that already read the
+   * server's value from the shared jar would refuse an equal one and rotate
+   * on its own, stranding this tab's new prefetches.
+   */
+  function markStaleSoftAndBroadcast(): void {
+    markHistoryStale();
+    // The read reports an external rotation or write the jar holds to the
+    // fence. Either branch below marks every cache stale, so it covers a
+    // write seen so far.
+    const rangoState = getRangoState();
+    takeStateWriteInActionFence();
+    if (takeStateRotationInActionFence()) {
+      clearPrefetchCache();
+      broadcastInvalidation(false);
+      return;
+    }
+    markPrefetchesStale();
+    broadcastInvalidation(true, rangoState);
   }
 
   /**
-   * Broadcast cache invalidation to other tabs without clearing local cache
-   * Used after consolidation fetch where local cache has fresh data
+   * Broadcast cache invalidation to other tabs. `soft` marks a server action
+   * that rotated nothing: a receiver that cannot adopt a newer state marks its
+   * caches stale instead of flushing them and rotating.
    */
-  function broadcastInvalidation(): void {
+  function broadcastInvalidation(
+    soft: boolean,
+    rangoState: string = getRangoState(),
+  ): void {
     // Only broadcast if cross-tab sync is enabled
     if (!crossTabSync) return;
 
@@ -360,8 +399,9 @@ export function createNavigationStore(
         type: "invalidate",
         path: currentPath,
         segmentIds: currentSegmentIds,
-        rangoState: getRangoState(),
+        rangoState,
         stateCookieName: getRangoStateCookieName(),
+        ...(soft && { soft: true }),
       });
     }
   }
@@ -394,12 +434,20 @@ export function createNavigationStore(
             typeof stateCookieName === "string"
           ) {
             if (stateCookieName !== getRangoStateCookieName()) return;
-            // The sender already rotated the same-origin cookie. Adopt that
-            // value before clearing locally so tabs cannot ping-pong rotations
-            // and obsolete each other's post-invalidation prefetches.
-            const adopted = adoptRangoState(rangoState);
             markHistoryStale();
-            clearPrefetchCache(!adopted);
+            if (adoptRangoState(rangoState)) {
+              // The sender carries a newer state (it rotated the shared
+              // cookie: invalidateClientCache() on either seat). Adopt it
+              // before flushing locally, whether or not the message is soft,
+              // so tabs cannot ping-pong rotations and obsolete each other's
+              // post-invalidation prefetches.
+              clearPrefetchCache(false);
+            } else if (event.data.soft === true) {
+              // A server action that rotated nothing: mark, never flush.
+              markPrefetchesStale();
+            } else {
+              clearPrefetchCache(true);
+            }
           } else {
             // Compatibility with an already-open tab running an older sender.
             markCacheAsStaleInternal();
@@ -679,6 +727,18 @@ export function createNavigationStore(
       markHistoryStale();
     },
 
+    /**
+     * Mark history entries and prefetches stale, telling no other tab: a
+     * cookie read saw a server action's write part change (rango-state.ts
+     * write observer). What a soft broadcast's receiver does, for a tab the
+     * broadcast does not reach: one whose page shares no segment with the
+     * acting page, or one with crossTabSync off.
+     */
+    markCachesStaleAfterWrite(): void {
+      markHistoryStale();
+      markPrefetchesStale();
+    },
+
     /**
      * Clear the history cache and broadcast to other tabs
      * Use this for hard invalidation when data is definitely stale
@@ -688,10 +748,19 @@ export function createNavigationStore(
     },
 
     /**
-     * Mark cache as stale and broadcast to other tabs
-     * Called after server actions - allows SWR pattern for popstate
+     * Mark history entries and prefetches stale and tell other tabs. Called
+     * after a server action without a directive: Back and a click on a
+     * prefetch made before it show the cached page and revalidate it.
      */
     markCacheAsStaleAndBroadcast(): void {
+      markStaleSoftAndBroadcast();
+    },
+
+    /**
+     * Mark history stale, flush the prefetch caches, rotate the state and
+     * tell other tabs: the client seat of invalidateClientCache().
+     */
+    invalidateCacheAndBroadcast(): void {
       markStaleAndBroadcast();
     },
 

package/src/browser/navigation-transaction.ts

@@ -114,7 +114,6 @@ export interface CommitResult {
  * Bound transaction with pre-configured commit options (without segmentIds/segments)
  */
 export interface BoundTransaction {
-  readonly currentUrl: string;
   /** Bound `replace` option (history replace instead of push). */
   readonly replace?: boolean;
   /** Bound `traversal` option: a back/forward navigation. */
@@ -156,8 +155,6 @@ export function createNavigationTransaction(
   url: string,
   options?: NavigateOptionsInternal & { skipLoadingState?: boolean },
 ): NavigationTransaction {
-  const currentUrl = window.location.href;
-
   const handle = eventController.startNavigation(url, options);
 
   /**
@@ -260,9 +257,6 @@ export function createNavigationTransaction(
       opts: Omit<CommitOptions, "segmentIds" | "segments">,
     ): BoundTransaction {
       return {
-        get currentUrl() {
-          return currentUrl;
-        },
         replace: opts.replace,
         traversal: opts.traversal,
         state: opts.state,

package/src/browser/partial-update.ts

@@ -238,6 +238,19 @@ export type UpdateMode =
       refresh?: boolean;
       /** The cross-tab refresh's held boundary (see `action`). */
       boundary?: string;
+      /**
+       * A click's: told of each response this navigation fetches, true when
+       * it is a prefetch a server action marked stale
+       * (FetchPartialResult.stalePrefetch), false otherwise, so a fresh
+       * refetch after it (a fill's start-over, an HMR retry) clears it. Its
+       * presence is what lets a stale prefetch answer
+       * (FetchPartialOptions.acceptStalePrefetch): only a navigation that
+       * revalidates afterwards takes one. The click commits it as it commits
+       * any prefetch; the bridge revalidates the page once the navigation
+       * settled (navigation-bridge.ts navigate). Nothing here changes how or
+       * when this commit lands.
+       */
+      onStalePrefetch?: (stale: boolean) => void;
     }
   | { type: "leave-intercept"; interceptSourceUrl?: string; boundary?: never }
   | {
@@ -601,16 +614,18 @@ export function createPartialUpdater(
       segments = segmentIds ?? segmentState.currentSegmentIds;
     }
 
-    // The page the client is on, which the server diffs the target against.
-    // tx.currentUrl is window.location when the transaction was created: on
-    // a back/forward the popstate event had already moved it to the target,
-    // and a server told the target is also the source revalidates nothing on
-    // the same route, so the page being left stayed on screen (#1030). The
-    // store's URL is the committed entry's until tx.commit().
+    // The page the client is on, which the server diffs the target against:
+    // the committed entry (the store's URL until tx.commit()), whose segment
+    // ids are sent above, or the intercept's source. Never window.location:
+    // a popstate has already moved it to the popped entry before that
+    // entry's fetch commits. Sent from there, a back/forward was told the
+    // target is also the source and kept the page being left (#1030), and a
+    // click during a back/forward that missed the history cache was judged
+    // against the popped entry while holding the page on screen's copies, so
+    // a layout kept for one page showed the other's.
     const previousUrl =
-      mode.type === "leave-intercept" || (tx.traversal && !interceptSourceUrl)
-        ? segmentState.currentUrl || tx.currentUrl
-        : interceptSourceUrl || tx.currentUrl || segmentState.currentUrl;
+      (mode.type !== "leave-intercept" && interceptSourceUrl) ||
+      segmentState.currentUrl;
 
     if (IS_BROWSER_DEBUG) {
       debugLog(`\n[Browser] >>> NAVIGATION`);
@@ -625,8 +640,7 @@ export function createPartialUpdater(
     // transition({ when }). Every decision below runs before tx.commit()
     // moves the store, so `from` is still the location being left:
     // segmentState.currentUrl is the committed URL even on a popstate cache
-    // miss, where tx.currentUrl and window.location already point at the
-    // target.
+    // miss, where window.location already points at the target.
     const whenKind: TransitionWhenKind =
       mode.type === "action"
         ? "action"
@@ -707,6 +721,8 @@ export function createPartialUpdater(
       boundary,
       version: getVersion(),
       routerId: store.getRouterId?.(),
+      acceptStalePrefetch:
+        mode.type === "navigate" && mode.onStalePrefetch !== undefined,
     });
     const streamingToken = tx.startStreaming();
     const {
@@ -714,6 +730,9 @@ export function createPartialUpdater(
       streamComplete: rawStreamComplete,
       fullyPrefetched,
     } = fetchResult;
+    if (mode.type === "navigate") {
+      mode.onStalePrefetch?.(fetchResult.stalePrefetch === true);
+    }
     debugLog("payload.metadata", payload.metadata);
 
     // Side effect only: end the streaming token once the stream settles.
@@ -1093,7 +1112,7 @@ export function createPartialUpdater(
 
       // A background refresh keeps the stale page on screen when a loader it
       // re-ran threw (its entries settled in the build): nothing is committed,
-      // and navigation-bridge logs the rejection (dc-t65). Every other lane
+      // and navigation-bridge logs the rejection. Every other lane
       // throws it at the read. Before the abort check: the await yields.
       if (mode.type === "stale-revalidation") {
         const failed = await revalidationErrorOf(serverSegments);