@rangojs/router 0.32.0 → 0.33.0

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);

package/src/browser/prefetch/cache.ts

@@ -7,11 +7,14 @@
  * stream resolves the route's client references, so the route's JS chunks are
  * imported during prefetch rather than on click. The decoded payload is reused
  * verbatim by navigation, so a prefetched click loads no new code. Two key
- * scopes are in play:
+ * scopes are in play. Wherever a key below says `rangoState`, callers pass the
+ * state's `{version}:{timestamp}` part (cookie-name.ts stateEpoch), not the
+ * whole value: a server action's write bump leaves the keys as they were.
  * - Wildcard (default): built by `buildPrefetchKey(rangoState, target)` —
  *   shape `rangoState\0/target?...`. Shared across all source pages and
  *   source segment trees; `_rsc_segments` is omitted from this key. Invalidated
- *   automatically when Rango state bumps (deploy or server-action invalidation).
+ *   automatically when Rango state bumps (deploy or invalidateClientCache()).
+ *   A server action marks entries stale instead (the stale epoch, below).
  * - Source-scoped: built by `buildSourceKey(rangoState, sourceHref, target)`
  *   — shape `rangoState\0sourceHref\0/target?...`. Embeds the Rango state
  *   (so rotation invalidates source-scoped entries too), the source href, and
@@ -20,6 +23,14 @@
  *   targets, matched or not), OR when a Link opts in with
  *   `prefetchKey=":source"` — in both cases so source-sensitive responses
  *   cannot bleed into navigations from other pages.
+ * - Params-scoped: built by `buildParamsKey(rangoState, label, target)` —
+ *   shape `rangoState\0p:<label>\0/target?...`. Populated when the server
+ *   tags a response with `X-RSC-Prefetch-Scope: params; <label>`: a
+ *   revalidate() rule read the source's params or route name and kept a
+ *   segment, so the answer is right for every page with equal values of
+ *   what it read (prefetch-source-scope.ts). `paramsShapes` remembers, per
+ *   target, what the stored labels read, so a lookup rebuilds the label of
+ *   the page on screen (paramsCandidateKeys).
  *
  * Also tracks in-flight prefetch promises. Each promise resolves to the
  * decoded prefetch entry (or null), letting navigation adopt a
@@ -44,6 +55,13 @@ import { notifyPrefetchCacheInvalidated } from "./invalidation.js";
 import { invalidateRangoState } from "../rango-state.js";
 import type { RscPayload } from "../types.js";
 import { WIRE } from "../../wire-params.js";
+import {
+  formatSourceLabel,
+  parseSourceShape,
+  sourceShapeId,
+  type SourcePage,
+  type SourceShape,
+} from "../../prefetch-source-scope.js";
 
 /**
  * A prefetch that has been fetched AND eagerly decoded. Storing the decoded
@@ -64,9 +82,23 @@ export interface DecodedPrefetch {
    * Prefetch scope as tagged by the server via `X-RSC-Prefetch-Scope`.
    * `"source"` means the response is source-page-sensitive and must not be
    * reused by a navigation from a different page — navigation enforces this
-   * when it adopted an inflight entry through the wildcard key.
+   * when it adopted an inflight entry through the wildcard key. `"params"`
+   * means it serves the pages whose label equals `paramsLabel`.
    */
-  scope: "source" | "wildcard";
+  scope: PrefetchScope;
+  /** The label of a `"params"` entry (prefetch-source-scope.ts). */
+  paramsLabel?: string;
+  /**
+   * The stale epoch (`currentPrefetchEpoch()`) the prefetch's fetch started
+   * under. A server action without a directive marks every prefetch stale
+   * (`markPrefetchesStale()` bumps the epoch) instead of flushing it: an entry
+   * from an older epoch is still served, and the navigation that adopts it
+   * revalidates its page once it settled (`isPrefetchStale`). A stale entry
+   * is served at most once, and only to a click (`consumePrefetch`'s
+   * `acceptStale`). A respawn keeps the original fetch's epoch, as it keeps
+   * its timestamp.
+   */
+  epoch: number;
   /**
    * Synchronously-readable flag, flipped to true when `streamComplete` resolves
    * (the entire RSC stream has drained). Navigation reads this at click time to
@@ -108,6 +140,9 @@ export interface DecodedPrefetch {
   dispose?: () => void;
 }
 
+/** Where a prefetch is stored: see the module comment. */
+export type PrefetchScope = "source" | "params" | "wildcard";
+
 let cacheTTL = 300_000;
 let fragmentPassthroughEnabled = true;
 
@@ -163,8 +198,25 @@ const inflightAliases = new Map<string, string[]>();
 
 const adoptedKeys = new Set<string>();
 
+/**
+ * What the stored params-scoped labels of a target read, by
+ * `buildPrefetchKey("", target)`: the shapes paramsCandidateKeys rebuilds
+ * labels from. Bounded like the cache; cleared with it.
+ */
+const paramsShapes = new Map<string, Map<string, SourceShape>>();
+
 let generation = 0;
 
+/**
+ * The stale epoch. `markPrefetchesStale()` bumps it; an entry whose fetch
+ * started under an older one is stale (`isPrefetchStale`). Separate from
+ * `generation`: a stale mark keeps every entry and every in-flight fetch,
+ * where a generation bump drops them. So a Flight response that has already
+ * arrived is never aborted by an action (aborting it mid-stream errors
+ * the stream): an in-flight prefetch finishes and lands stale.
+ */
+let staleEpoch = 0;
+
 /**
  * Build a cache key by combining a scope prefix with the target URL.
  *
@@ -172,7 +224,7 @@ let generation = 0;
  * one of:
  * - Wildcard (source-agnostic): prefix is the Rango state value from
  *   `getRangoState()`. Shared across all source pages. Invalidated
- *   automatically when Rango state bumps (deploy or server-action).
+ *   automatically when Rango state bumps (deploy or invalidateClientCache()).
  *   `_rsc_segments` is omitted so sibling payloads prefetched from one page
  *   remain reusable after another prefetched navigation commits. Key shape:
  *   `rangoState\0/target?...`.
@@ -218,6 +270,76 @@ export function buildSourceKey(
   );
 }
 
+/**
+ * Build a params-scoped cache key. Key shape:
+ * `rangoState\0p:<label>\0/target?...`, the target normalized like the
+ * wildcard key's: the answer serves every page with this label, whatever
+ * segments it holds, as a wildcard answer serves every page.
+ */
+export function buildParamsKey(
+  rangoState: string,
+  label: string,
+  targetUrl: URL,
+): string {
+  return buildPrefetchKey(rangoState + "\0p:" + label, targetUrl);
+}
+
+/**
+ * Remember that a params-scoped answer for `targetUrl` is stored under a
+ * label of this shape. Called where the response header is read, with the
+ * store (fetch.ts executePrefetchFetch).
+ */
+export function rememberParamsShape(targetUrl: URL, label: string): void {
+  const target = buildPrefetchKey("", targetUrl);
+  const shape = parseSourceShape(label);
+  let shapes = paramsShapes.get(target);
+  if (!shapes) {
+    if (paramsShapes.size >= maxPrefetchCacheSize) {
+      const oldest = paramsShapes.keys().next().value;
+      if (oldest !== undefined) paramsShapes.delete(oldest);
+    }
+    shapes = new Map();
+    paramsShapes.set(target, shapes);
+  }
+  shapes.set(sourceShapeId(shape), shape);
+}
+
+/**
+ * The params-scoped keys a request for `targetUrl` from `page` may adopt:
+ * the page's label under each shape stored for the target, the shapes that
+ * read the most first. Empty without a page (before boot).
+ */
+export function paramsCandidateKeys(
+  rangoState: string,
+  targetUrl: URL,
+  page: SourcePage | null,
+): string[] {
+  if (!page) return [];
+  const shapes = paramsShapes.get(buildPrefetchKey("", targetUrl));
+  if (!shapes) return [];
+  return [...shapes.values()]
+    .sort((a, b) => weightOf(b) - weightOf(a))
+    .map((shape) =>
+      buildParamsKey(rangoState, formatSourceLabel(shape, page), targetUrl),
+    );
+}
+
+const weightOf = (shape: SourceShape): number =>
+  shape.names.length + (shape.route ? 1 : 0) + (shape.keys ? 1 : 0);
+
+/**
+ * Whether `page` is in the group a params-scoped entry serves: its label
+ * under the entry's shape equals the entry's.
+ */
+export function pageMatchesParamsLabel(
+  label: string,
+  page: SourcePage | null,
+): boolean {
+  return (
+    page !== null && formatSourceLabel(parseSourceShape(label), page) === label
+  );
+}
+
 /**
  * Walk an inflight key plus any sibling aliases registered via
  * `setInflightPromiseWithAliases`, invoking `fn` for each.
@@ -233,13 +355,19 @@ function forEachAlias(key: string, fn: (k: string) => void): void {
 
 /**
  * Check if a prefetch is already cached, in-flight, or queued for the given key.
+ *
+ * A stale stored entry (`isPrefetchStale`) counts as absent and is dropped, so
+ * a new hover or viewport trigger replaces it with a fresh prefetch, and a
+ * click made while that one is in flight adopts it rather than the stale one.
+ * An in-flight fetch counts whatever its epoch: it is never aborted, and a
+ * duplicate request for its key would race it for the slot.
  */
 export function hasPrefetch(key: string): boolean {
   if (inflight.has(key)) return true;
   if (cacheTTL <= 0) return false;
   const entry = cache.get(key);
   if (!entry) return false;
-  if (Date.now() - entry.timestamp > cacheTTL) {
+  if (Date.now() - entry.timestamp > cacheTTL || isPrefetchStale(entry.entry)) {
     entry.entry.dispose?.();
     cache.delete(key);
     return false;
@@ -258,10 +386,20 @@ export function hasPrefetch(key: string): boolean {
  * TTL bounds the age of the data, not of the latest adoption. Without
  * `respawn` the entry is deleted (legacy one-shot behavior).
  *
+ * A stale entry (`isPrefetchStale`) is served only to a caller that passes
+ * `acceptStale` (a click, which revalidates its page once it settled,
+ * navigation-bridge.ts): for any other caller it is a miss and stays in its
+ * slot. It is served at most once: its slot is not re-armed, so a second
+ * click on the same link fetches fresh rather than showing pre-write data
+ * older than what the first click's revalidation showed.
+ *
  * Does NOT check in-flight prefetches — use consumeInflightPrefetch()
  * for that (returns a Promise instead of a resolved entry).
  */
-export function consumePrefetch(key: string): DecodedPrefetch | null {
+export function consumePrefetch(
+  key: string,
+  options?: { acceptStale?: boolean },
+): DecodedPrefetch | null {
   if (cacheTTL <= 0) return null;
   const cached = cache.get(key);
   if (!cached) return null;
@@ -271,10 +409,15 @@ export function consumePrefetch(key: string): DecodedPrefetch | null {
     return null;
   }
   const entry = cached.entry;
-  if (entry.respawn) {
+  const stale = isPrefetchStale(entry);
+  if (stale && !options?.acceptStale) return null;
+  if (entry.respawn && !stale) {
     cached.entry = entry.respawn();
   } else {
     cache.delete(key);
+    // The buffered reserve (fetch.ts) is never replayed: release it. It is a
+    // separate tee branch, so the payload the caller adopts keeps streaming.
+    if (stale) entry.dispose?.();
   }
   return entry;
 }
@@ -318,12 +461,18 @@ export function consumeInflightPrefetch(
  * Store an eagerly-decoded prefetch in the in-memory cache.
  *
  * Skips storage if the generation has changed since the fetch started
- * (a server action invalidated the cache mid-flight).
+ * (the cache was flushed mid-flight). An entry from an older stale epoch (an
+ * action marked prefetches stale mid-flight) is stored, and stays stale.
+ *
+ * `inflightKey` is the key the prefetch was in flight under, when the
+ * storage key is not one of its aliases (a params-scoped answer): a
+ * navigation that adopted it marked the aliases.
  */
 export function storePrefetch(
   key: string,
   entry: DecodedPrefetch,
   fetchGeneration: number,
+  inflightKey: string = key,
 ): void {
   if (cacheTTL <= 0) return;
   if (fetchGeneration !== generation) return;
@@ -333,8 +482,8 @@ export function storePrefetch(
   // publish it to the cache map, or a later navigation would be served the
   // exhausted entry and lose that route's handles. Clear the marker (under all
   // aliases) now that the decision is made.
-  if (adoptedKeys.has(key)) {
-    forEachAlias(key, (k) => adoptedKeys.delete(k));
+  if (adoptedKeys.has(inflightKey)) {
+    forEachAlias(inflightKey, (k) => adoptedKeys.delete(k));
     return;
   }
 
@@ -398,6 +547,33 @@ export function currentGeneration(): number {
   return generation;
 }
 
+/**
+ * Capture the current stale epoch. A prefetch fetch stamps its entry with the
+ * value read when it started (`DecodedPrefetch.epoch`).
+ */
+export function currentPrefetchEpoch(): number {
+  return staleEpoch;
+}
+
+/** Whether an action marked prefetches stale after this entry's fetch began. */
+export function isPrefetchStale(
+  entry: Pick<DecodedPrefetch, "epoch">,
+): boolean {
+  return entry.epoch < staleEpoch;
+}
+
+/**
+ * Mark every stored and in-flight prefetch stale: what a server action
+ * without a directive does (navigation-store.ts markCacheAsStaleAndBroadcast).
+ * Only bumps the epoch. Nothing is dropped, aborted or rotated, and visible
+ * links are not told (no `notifyPrefetchCacheInvalidated()`), so they do not
+ * prefetch again. A click on a stale entry commits it at once; the navigation
+ * then revalidates its page (navigation-bridge.ts navigate).
+ */
+export function markPrefetchesStale(): void {
+  staleEpoch++;
+}
+
 export function markPrefetchInflight(key: string): void {
   inflight.add(key);
 }
@@ -457,6 +633,7 @@ export function clearPrefetchCache(rotateRangoState = true): void {
   inflightPromises.clear();
   inflightAliases.clear();
   adoptedKeys.clear();
+  paramsShapes.clear();
   for (const cached of cache.values()) cached.entry.dispose?.();
   cache.clear();
   earliestTimestamp = Infinity;