@rangojs/router 0.31.0 → 0.33.0

package/src/browser/prefetch/fetch.ts

@@ -16,28 +16,39 @@
  */
 
 import {
+  buildParamsKey,
   buildPrefetchKey,
   buildSourceKey,
   hasPrefetch,
+  paramsCandidateKeys,
+  rememberParamsShape,
   markPrefetchInflight,
   setInflightPromiseWithAliases,
   storePrefetch,
   removePrefetch,
   clearPrefetchInflight,
   currentGeneration,
+  currentPrefetchEpoch,
   isFragmentPassthroughEnabled,
+  isPrefetchStale,
   type DecodedPrefetch,
+  type PrefetchScope,
 } from "./cache.js";
+import { paramsScopeLabel } from "../../prefetch-source-scope.js";
 import { getRangoState } from "../rango-state.js";
+import { stateEpoch } from "../cookie-name.js";
 import { isActionFenceActive } from "../action-fence.js";
 import { enqueuePrefetch } from "./queue.js";
 import { shouldPrefetch } from "./policy.js";
 import { debugLog, IS_BROWSER_DEBUG } from "../logging.js";
 import { teeWithCompletion, isForeignRouterId } from "../response-adapter.js";
 import { SEGMENT_FRAGMENT_CAPABILITY_HEADER } from "../../segment-fragments.js";
-import { PREFETCH_HEADER } from "../../prefetch-markers.js";
+import { PREFETCH_HEADER, PREFETCH_INTENT } from "../../prefetch-markers.js";
 import type { RscPayload } from "../types.js";
-import { getRegisteredStore } from "../navigation-store-handle.js";
+import {
+  getCommittedPage,
+  getRegisteredStore,
+} from "../navigation-store-handle.js";
 import { writePartialParams } from "../wire-protocol.js";
 
 /**
@@ -87,7 +98,8 @@ export function setPrefetchDecoder(fn: PrefetchDecoder): void {
 function makeRespawn(
   storageKey: string,
   reserve: ReadableStream<Uint8Array>,
-  scope: "source" | "wildcard",
+  slot: PrefetchSlot,
+  epoch: number,
 ): () => DecodedPrefetch {
   return () => {
     const [body, nextReserve] = reserve.tee();
@@ -98,7 +110,9 @@ function makeRespawn(
     const entry: DecodedPrefetch = {
       payload,
       streamComplete: Promise.resolve(),
-      scope,
+      scope: slot.scope,
+      paramsLabel: slot.paramsLabel,
+      epoch,
       complete: true,
       dispose: () => {
         // Rejects (caught) instead of throwing if the branch is already
@@ -107,7 +121,7 @@ function makeRespawn(
         nextReserve.cancel().catch(() => {});
       },
     };
-    entry.respawn = makeRespawn(storageKey, nextReserve, scope);
+    entry.respawn = makeRespawn(storageKey, nextReserve, slot, epoch);
     // Parity with the original path: a rejected decode must not stay
     // consumable. Clean bytes should never fail to decode, but if they do,
     // evict (identity-guarded) so navigation refetches instead.
@@ -117,17 +131,36 @@ function makeRespawn(
 }
 
 /**
- * Check if a URL resolves to the current page (same pathname + search).
+ * The page a prefetch is sent from: the URL the router store committed, the
+ * page whose segment ids every caller sends. Not window.location: a popstate
+ * moves it to the popped entry before that entry's fetch commits, and a
+ * prefetch sent from there with the page on screen's ids was judged against
+ * the wrong page, so a layout kept for one page showed the other's copy.
+ * Absolute, as navigation-client.ts makes the URL navigation sends
+ * (partial-update.ts previousUrl), so the source keys agree.
+ */
+function committedHref(): string {
+  const committed = getRegisteredStore()?.getSegmentState().currentUrl;
+  return committed
+    ? new URL(committed, window.location.origin).href
+    : window.location.href;
+}
+
+function withoutHash(href: string): string {
+  const hash = href.indexOf("#");
+  return hash === -1 ? href : href.slice(0, hash);
+}
+
+/**
+ * Check if a URL resolves to the committed page (same pathname + search).
  * Used to prevent same-page prefetching, which produces a trivial diff
  * that would corrupt the (default wildcard) prefetch cache entry.
  */
-function isSamePage(url: string): boolean {
+function isSamePage(url: string, sourceHref: string): boolean {
   try {
     const target = new URL(url, window.location.origin);
-    return (
-      target.pathname + target.search ===
-      window.location.pathname + window.location.search
-    );
+    const source = new URL(sourceHref, window.location.origin);
+    return target.pathname + target.search === source.pathname + source.search;
   } catch {
     return false;
   }
@@ -165,6 +198,41 @@ function buildPrefetchUrl(
   });
 }
 
+/** Where a completed prefetch is stored, and the label of a params scope. */
+export interface PrefetchSlot {
+  scope: PrefetchScope;
+  key: string;
+  paramsLabel?: string;
+}
+
+/**
+ * Where a completed prefetch is stored: under the source key when the Link
+ * forced it or the response says `X-RSC-Prefetch-Scope: source`; under the
+ * label's key when it says `params; <label>`, for the pages with equal values
+ * of what a revalidate() rule read; else under the key every source page
+ * shares (#1331). `stateKey` is the state's epoch the other keys were built
+ * with (cookie-name.ts stateEpoch).
+ */
+export function prefetchStorageSlot(
+  forceSourceScope: boolean,
+  scopeHeader: string | null,
+  sourceKey: string,
+  wildcardKey: string,
+  stateKey: string,
+  targetUrl: URL,
+): PrefetchSlot {
+  if (forceSourceScope || scopeHeader === "source") {
+    return { scope: "source", key: sourceKey };
+  }
+  const label = paramsScopeLabel(scopeHeader);
+  if (label === undefined) return { scope: "wildcard", key: wildcardKey };
+  return {
+    scope: "params",
+    key: buildParamsKey(stateKey, label, targetUrl),
+    paramsLabel: label,
+  };
+}
+
 /**
  * Core prefetch fetch logic. Fetches the response, eagerly decodes it, and
  * stores the decoded payload in the in-memory cache. The returned Promise
@@ -191,21 +259,38 @@ function buildPrefetchUrl(
  *   `sourceKey` so same-source navigations adopt directly via their own
  *   source key. Storage key is chosen at response time from the
  *   `X-RSC-Prefetch-Scope` header — `"source"` → `sourceKey` (a route an
- *   intercept targets), anything else → `wildcardKey`. The entry records its scope
- *   so cross-source navigations that adopted via `wildcardKey` can bail out
- *   in `navigation-client.ts` when the adopted entry turns out source-scoped.
+ *   intercept targets), `"params; <label>"` → the label's key, anything else
+ *   → `wildcardKey`. The entry records its scope (and label) so cross-source
+ *   navigations that adopted via `wildcardKey` can bail out in
+ *   `navigation-client.ts` when the adopted entry turns out source-scoped,
+ *   or params-scoped to a group their page is not in.
  */
 function executePrefetchFetch(
   wildcardKey: string,
   sourceKey: string,
-  fetchUrl: string,
+  /** The committed page sent as the source, the one `sourceKey` names. */
+  sourceHref: string,
+  targetUrl: URL,
   forceSourceScope: boolean,
-  /** Rango state captured once by the caller (keys + header share one read). */
+  /**
+   * Rango state captured once by the caller (keys + header share one read).
+   * The header sends it whole; the keys hold its epoch.
+   */
   rangoState: string,
+  /**
+   * An intent prefetch (prefetchDirect: hover, `prefetch()`): sent as
+   * PREFETCH_INTENT so the server defers nothing, as in the navigation it
+   * starts early. A speculative one (prefetchQueued) sends `1` and lets the
+   * server defer `prefetch: false` work (docs/design/prefetch-false.md, R16).
+   */
+  intent: boolean,
   expectedRouterId?: string,
   signal?: AbortSignal,
 ): Promise<DecodedPrefetch | null> {
   const gen = currentGeneration();
+  // An action that lands while this fetch is out marks it stale without
+  // aborting it: it finishes and is stored stale (cache.ts isPrefetchStale).
+  const epoch = currentPrefetchEpoch();
   const inflightKeys = forceSourceScope
     ? [sourceKey]
     : [wildcardKey, sourceKey];
@@ -253,7 +338,7 @@ function executePrefetchFetch(
       });
   }
 
-  const promise: Promise<DecodedPrefetch | null> = fetch(fetchUrl, {
+  const promise: Promise<DecodedPrefetch | null> = fetch(targetUrl.toString(), {
     priority: "low" as RequestPriority,
     // 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
@@ -264,8 +349,8 @@ function executePrefetchFetch(
     signal: effectiveSignal,
     headers: {
       "X-Rango-State": rangoState,
-      "X-RSC-Router-Client-Path": window.location.href,
-      [PREFETCH_HEADER]: "1",
+      "X-RSC-Router-Client-Path": sourceHref,
+      [PREFETCH_HEADER]: intent ? PREFETCH_INTENT : "1",
       ...(isFragmentPassthroughEnabled() && {
         [SEGMENT_FRAGMENT_CAPABILITY_HEADER]: "1",
       }),
@@ -288,12 +373,18 @@ function executePrefetchFetch(
         return null;
       }
 
-      const scope: "source" | "wildcard" =
-        forceSourceScope ||
-        response.headers.get("x-rsc-prefetch-scope") === "source"
-          ? "source"
-          : "wildcard";
-      const storageKey = scope === "source" ? sourceKey : wildcardKey;
+      // The one place the storage key is decided: from the header, with the
+      // values the server read. A key computed when the fetch was scheduled
+      // and written again later would undo it (vercel/next.js#91488).
+      const slot = prefetchStorageSlot(
+        forceSourceScope,
+        response.headers.get("x-rsc-prefetch-scope"),
+        sourceKey,
+        wildcardKey,
+        stateEpoch(rangoState),
+        targetUrl,
+      );
+      const storageKey = slot.key;
 
       // Track stream completion off a tee so navigation's scroll/revalidation
       // gating matches the fresh-fetch path; decode the other branch. The
@@ -340,7 +431,9 @@ function executePrefetchFetch(
       const entry: DecodedPrefetch = {
         payload,
         streamComplete,
-        scope,
+        scope: slot.scope,
+        paramsLabel: slot.paramsLabel,
+        epoch,
         complete: false,
         stallTimer: timeoutId,
         ...(reserve && {
@@ -349,7 +442,10 @@ function executePrefetchFetch(
           },
         }),
       };
-      storePrefetch(storageKey, entry, gen);
+      storePrefetch(storageKey, entry, gen, inflightKeys[0]);
+      if (slot.paramsLabel !== undefined) {
+        rememberParamsShape(targetUrl, slot.paramsLabel);
+      }
       // The stall timeout now owns the body stream: arm eviction (publishedKey)
       // and clear the timer once the stream completes. The tee's finally resolves
       // streamComplete on normal completion AND on abort, so a healthy body pays
@@ -375,7 +471,7 @@ function executePrefetchFetch(
         if (decode.status === "fulfilled" && endedCleanly) {
           entry.complete = true;
           if (reserve) {
-            entry.respawn = makeRespawn(storageKey, reserve, scope);
+            entry.respawn = makeRespawn(storageKey, reserve, slot, epoch);
             // Refill after an early adoption. A click that lands before this
             // point adopts the entry with respawn unarmed and leaves the slot
             // empty — via either path: pre-headers inflight adoption makes
@@ -386,7 +482,11 @@ function executePrefetchFetch(
             // live again (our own un-adopted entry, a fresh entry, or a new
             // in-flight prefetch), and storePrefetch's generation check drops
             // the sibling if the cache was invalidated since the fetch began.
-            if (!hasPrefetch(storageKey)) {
+            // A stale entry is served at most once (cache.ts consumePrefetch),
+            // so an adopted stale one is not refilled: the next click fetches
+            // fresh. The isPrefetchStale check also keeps hasPrefetch from
+            // dropping (and disposing) our own un-adopted entry once stale.
+            if (!isPrefetchStale(entry) && !hasPrefetch(storageKey)) {
               storePrefetch(storageKey, entry.respawn(), gen);
             }
           }
@@ -409,7 +509,8 @@ function executePrefetchFetch(
 }
 
 /**
- * Dedup check for prefetch entry presence.
+ * Dedup check for prefetch entry presence: the wildcard key, the source key,
+ * or a params-scoped answer whose group the page on screen is in.
  *
  * Forced `:source` must NOT dedupe against a pre-existing wildcard entry —
  * otherwise the source slot would stay unpopulated and navigation from
@@ -420,15 +521,29 @@ function hasPrefetchHit(
   forceSourceScope: boolean,
   wildcardKey: string,
   sourceKey: string,
+  stateKey: string,
+  targetUrl: URL,
 ): boolean {
-  return forceSourceScope
-    ? hasPrefetch(sourceKey)
-    : hasPrefetch(wildcardKey) || hasPrefetch(sourceKey);
+  if (forceSourceScope) return hasPrefetch(sourceKey);
+  return (
+    hasPrefetch(wildcardKey) ||
+    hasPrefetch(sourceKey) ||
+    paramsCandidateKeys(stateKey, targetUrl, getCommittedPage()).some(
+      hasPrefetch,
+    )
+  );
 }
 
 /**
  * Prefetch (direct): fetch with low priority and store in in-memory cache.
- * Used by hover strategy -- fires immediately without queueing.
+ * Used by hover (on hover and viewport links, and delegated anchors) and
+ * useRouter().prefetch() -- fires immediately without queueing.
+ *
+ * An intent prefetch: the visitor is about to click, so it asks for the full
+ * response the navigation would get, `prefetch: false` loaders and flagged
+ * `loading()` work included. It runs only on a miss: a cached prefetch or one
+ * in flight, even a speculative one that deferred work, is used as it is,
+ * and its click sends the fill as before (docs/design/prefetch-false.md, R16).
  *
  * By default the wildcard key (Rango-state-keyed) is used for inflight
  * dedup and for responses that are not source-sensitive; source-scoped
@@ -450,18 +565,27 @@ export function prefetchDirect(
   const targetUrl = buildPrefetchUrl(url, segmentIds, version, routerId);
   if (!targetUrl) return;
   const forceSourceScope = prefetchKey === ":source";
+  const sourceHref = committedHref();
   // Skip same-page prefetch — a same-page diff is trivial and would corrupt
   // the wildcard cache entry used for cross-page navigation.
   // When `:source` is forced the entry is source-scoped (single-aliased to
   // itself), so it cannot poison any shared slot — allow it.
-  if (!forceSourceScope && isSamePage(url)) {
+  if (!forceSourceScope && isSamePage(url, sourceHref)) {
     return;
   }
-  const sourceHref = window.location.href;
   const rangoState = getRangoState();
-  const wildcardKey = buildPrefetchKey(rangoState, targetUrl);
-  const sourceKey = buildSourceKey(rangoState, sourceHref, targetUrl);
-  if (hasPrefetchHit(forceSourceScope, wildcardKey, sourceKey)) {
+  const stateKey = stateEpoch(rangoState);
+  const wildcardKey = buildPrefetchKey(stateKey, targetUrl);
+  const sourceKey = buildSourceKey(stateKey, sourceHref, targetUrl);
+  if (
+    hasPrefetchHit(
+      forceSourceScope,
+      wildcardKey,
+      sourceKey,
+      stateKey,
+      targetUrl,
+    )
+  ) {
     if (IS_BROWSER_DEBUG) {
       debugLog("[prefetch] direct dedup (key already exists)", {
         url,
@@ -484,16 +608,19 @@ export function prefetchDirect(
   executePrefetchFetch(
     wildcardKey,
     sourceKey,
-    targetUrl.toString(),
+    sourceHref,
+    targetUrl,
     forceSourceScope,
     rangoState,
+    true,
     routerId,
   );
 }
 
 /**
  * Prefetch (queued): goes through the concurrency-limited queue.
- * Used by viewport/render strategies to avoid flooding the server.
+ * Used by viewport/render strategies to avoid flooding the server. A
+ * speculative prefetch: the server defers `prefetch: false` work in it.
  * Returns the inflight key (wildcard by default, source-scoped when
  * `prefetchKey=":source"` is passed).
  */
@@ -508,15 +635,24 @@ export function prefetchQueued(
   const targetUrl = buildPrefetchUrl(url, segmentIds, version, routerId);
   if (!targetUrl) return "";
   const forceSourceScope = prefetchKey === ":source";
-  if (!forceSourceScope && isSamePage(url)) {
+  const sourceHref = committedHref();
+  if (!forceSourceScope && isSamePage(url, sourceHref)) {
     return "";
   }
-  const sourceHref = window.location.href;
   const rangoState = getRangoState();
-  const wildcardKey = buildPrefetchKey(rangoState, targetUrl);
-  const sourceKey = buildSourceKey(rangoState, sourceHref, targetUrl);
+  const stateKey = stateEpoch(rangoState);
+  const wildcardKey = buildPrefetchKey(stateKey, targetUrl);
+  const sourceKey = buildSourceKey(stateKey, sourceHref, targetUrl);
   const queueKey = forceSourceScope ? sourceKey : wildcardKey;
-  if (hasPrefetchHit(forceSourceScope, wildcardKey, sourceKey)) {
+  if (
+    hasPrefetchHit(
+      forceSourceScope,
+      wildcardKey,
+      sourceKey,
+      stateKey,
+      targetUrl,
+    )
+  ) {
     if (IS_BROWSER_DEBUG) {
       debugLog("[prefetch] queued dedup (key already exists)", {
         url,
@@ -527,22 +663,46 @@ export function prefetchQueued(
     }
     return queueKey;
   }
-  const fetchUrlStr = targetUrl.toString();
   enqueuePrefetch(queueKey, (signal) => {
+    // The header sends the state as it is now: a server action that landed
+    // while this sat in the queue bumped the write part, and the value read
+    // when it was queued would be answered by the browser HTTP cache with
+    // pre-write bytes. A rotation since then made the keys obsolete. Read
+    // before the re-check below: a read that sees another tab's write marks
+    // the entries from before it stale, so they no longer count as a hit.
+    const liveState = getRangoState();
+    if (stateEpoch(liveState) !== stateKey) return Promise.resolve();
     // Re-check at execution time: a hover-triggered prefetchDirect may
     // have started or completed this key while the item sat in the queue.
-    if (hasPrefetchHit(forceSourceScope, wildcardKey, sourceKey)) {
+    if (
+      hasPrefetchHit(
+        forceSourceScope,
+        wildcardKey,
+        sourceKey,
+        stateKey,
+        targetUrl,
+      )
+    ) {
       return Promise.resolve();
     }
-    if (!forceSourceScope && isSamePage(url)) {
+    // The segment ids and the source were read when it was queued: once the
+    // committed page has moved, they name a page no longer on screen.
+    // A hash-only change commits the same page, so the hash is not compared.
+    const committed = committedHref();
+    if (
+      withoutHash(committed) !== withoutHash(sourceHref) ||
+      (!forceSourceScope && isSamePage(url, committed))
+    ) {
       return Promise.resolve();
     }
     return executePrefetchFetch(
       wildcardKey,
       sourceKey,
-      fetchUrlStr,
+      sourceHref,
+      targetUrl,
       forceSourceScope,
-      rangoState,
+      liveState,
+      false,
       routerId,
       signal,
     ).then(() => {});

package/src/browser/prefetch/queue.ts

@@ -188,8 +188,9 @@ export function cancelAllPrefetches(keepUrl?: string | null): void {
 
 /**
  * Hard-cancel everything including in-flight prefetches.
- * Used by clearPrefetchCache (server action invalidation) where
- * in-flight responses would be stale.
+ * Used by clearPrefetchCache (invalidateClientCache(), a deploy) where
+ * in-flight responses would be stale. A server action never calls it: it
+ * marks prefetches stale and lets in-flight ones finish (cache.ts).
  */
 export function abortAllPrefetches(): void {
   for (const ac of abortControllers.values()) {

package/src/browser/rango-state.ts

@@ -6,11 +6,25 @@
  * requests; the server responds with `Vary: X-Rango-State`, so the browser HTTP
  * cache keys responses by (URL, X-Rango-State value).
  *
- * Value format: `{buildVersion}:{invalidationTimestamp}`
+ * Value format: `{buildVersion}:{invalidationTimestamp}[:{write}]`
  * - Build version: the router's document version. It changes when a deploy
  *   changes the router's server code or the client assets, busting all cached
  *   prefetches at boot; a deploy that changes neither keeps them.
- * - Timestamp rotates on invalidation (server action, invalidateClientCache).
+ * - Timestamp rotates on invalidation (invalidateClientCache, either seat).
+ * - Write: bumped by the response of a server action without a directive (its
+ *   `Set-Cookie`, server side, so a no-JS action bumps it too); left out while
+ *   0. It changes the `X-Rango-State` every tab and every reload sends, so
+ *   responses the browser HTTP cache holds from before the write miss.
+ *
+ * The client's in-memory comparisons read only `{buildVersion}:{timestamp}`
+ * (`stateEpoch`): the prefetch cache keys, the action fence's rotation check,
+ * the external-rotation observer below and the cross-tab adopt. A write-only
+ * change is soft: prefetches and history entries are marked stale and nothing
+ * is flushed. The tab that ran the action marks its own when it lands
+ * (navigation-store.ts markStaleSoftAndBroadcast) and tells the tabs that
+ * share a segment with it. Any other tab marks its own when a read sees the
+ * write part change (the write observer below), so a tab that ignores the
+ * broadcast or has crossTabSync off does not serve a pre-write prefetch fresh.
  *
  * Storage is a session cookie named by the server-resolved name passed to
  * initRangoState (`{prefix}_{routerId}`, default prefix `rango-state`). The
@@ -32,6 +46,7 @@ import {
   getRawCookieValue,
   mintStateValue,
   serializeStateCookie,
+  stateEpoch,
 } from "./cookie-name.js";
 
 let cookieName: string = DEFAULT_STATE_COOKIE_PREFIX;
@@ -42,10 +57,13 @@ let mirror: string | null = null;
 let cookieBacked = false;
 
 let externalRotationObserver: ((value: string) => void) | null = null;
+let externalWriteObserver: (() => void) | null = null;
 
 /**
  * Register the observer invoked when a read detects an EXTERNAL rotation (a
- * sibling tab, a server `Set-Cookie`, or a cookie clear). Self-rotations
+ * sibling tab, a server `Set-Cookie`, or a cookie clear) of the
+ * `{version}:{timestamp}` part. A change to the write part alone (a server
+ * action's write) goes to the write observer instead. Self-rotations
  * (invalidateRangoState) update the mirror synchronously and never fire it.
  */
 export function setRangoStateObserver(
@@ -54,6 +72,19 @@ export function setRangoStateObserver(
   externalRotationObserver = observer;
 }
 
+/**
+ * Register the observer invoked when a read sees the write part change while
+ * the `{version}:{timestamp}` part stays: a server action's response, in this
+ * tab or another, bumped it in the shared jar since the last read. Every read
+ * updates the mirror, and a prefetch reads the state before it starts, so a
+ * prefetch sent with the new value is never one this observer sees as old.
+ */
+export function setRangoStateWriteObserver(
+  observer: (() => void) | null,
+): void {
+  externalWriteObserver = observer;
+}
+
 /** Return the resolved cookie name used to namespace cross-tab messages. */
 export function getRangoStateCookieName(): string {
   return cookieName;
@@ -146,11 +177,17 @@ export function getRangoState(): string {
 
   if (read.value !== null) {
     if (read.value !== mirror) {
-      // External rotation (sibling tab / server Set-Cookie): adopt it. The
-      // mirror update makes this idempotent across a burst of reads.
+      // External change (sibling tab / server Set-Cookie): adopt it. The
+      // mirror update makes this idempotent across a burst of reads. A
+      // rotation notifies the rotation observer; a write-only bump (a server
+      // action's response, or a sibling tab's) keeps the caches the epoch
+      // keys and notifies the write observer, which marks them stale.
+      const rotated =
+        mirror === null || stateEpoch(mirror) !== stateEpoch(read.value);
       mirror = read.value;
       cookieBacked = true;
-      notifyExternalRotation(read.value);
+      if (rotated) notifyExternalRotation(read.value);
+      else externalWriteObserver?.();
     } else {
       cookieBacked = true;
     }
@@ -176,7 +213,7 @@ export function getRangoState(): string {
 
 /**
  * Invalidate the Rango state (self-rotation). Called when the client clears its
- * prefetch caches (e.g. via the server-action bridge). Rotates the timestamp,
+ * prefetch caches (e.g. invalidateClientCache()). Rotates the timestamp,
  * keeps the version, writes the cookie, and updates the mirror synchronously so
  * the external-rotation observer is NOT triggered by our own write.
  */
@@ -186,7 +223,12 @@ export function invalidateRangoState(): void {
   writeCookie(cookieName, mirror);
 }
 
-/** Adopt the state carried by a same-origin cache-invalidation broadcast. */
+/**
+ * Adopt the state carried by a same-origin cache-invalidation broadcast when
+ * its timestamp is newer (a rotation). The write part is not compared: a soft
+ * broadcast's newer write is already in the shared jar, and a value that
+ * differs only there is no rotation to adopt.
+ */
 export function adoptRangoState(value: string): boolean {
   const incoming = decodeStateValue(value);
   if (!incoming || incoming.version !== currentVersion) return false;

package/src/browser/react/Link.tsx

@@ -110,23 +110,29 @@ export interface LinkProps extends Omit<
    * keyed on Rango state + target URL. This is correct for routes whose
    * response shape doesn't depend on where the user navigates from.
    *
-   * Set `":source"` when this Link's response would legitimately differ
-   * based on the source page — typically when the target route (or one
-   * of its layouts) uses a custom `revalidate()` handler that reads
-   * `currentUrl` / `currentParams`, and the wildcard entry would
-   * therefore serve the wrong diff to a navigation from a different
-   * source.
+   * Set `":source"` to scope every prefetch of this Link to the page that
+   * sent it, when its response would differ by source page in a way the
+   * server cannot see.
    *
-   * A route an intercept targets is scoped to the source automatically
-   * (server-side `x-rsc-prefetch-scope: source`), whether or not the
-   * intercept applies from this page: the modal and the full page are
-   * both source-specific. Every other route stays shared, so `":source"`
-   * is only needed for custom revalidation logic.
+   * The server scopes a prefetch to its source automatically
+   * (`x-rsc-prefetch-scope: source`) when an intercept targets the route or
+   * the source page, whether or not it applies (the modal and the full page
+   * are both source-specific), when the answer defers a `prefetch: false`
+   * unit the source does not hold, when a `revalidate()` of the target read
+   * `currentUrl` and kept the segment, and when a kept answer sends no
+   * segment. A `revalidate()` that read `currentParams` or `fromRouteName`
+   * and kept the segment, or a prerendered target that keeps segments on
+   * equal params (`storedEntrySends`), shares the answer between the pages
+   * with equal values of what was read (`x-rsc-prefetch-scope: params`,
+   * #1331). Every other response stays shared. Use the key
+   * for what the server does not track: `context` in a `revalidate()`, or
+   * a `Referer` read.
+   *
+   * A source-scoped entry is keyed by the source page's full URL, query
+   * and hash included, so every page prefetches the link again.
    *
    * @example
    * ```tsx
-   * // Route uses a `revalidate()` that branches on currentUrl — opt in
-   * // so prefetches don't bleed across source pages.
    * <Link to="/dashboard" prefetch="hover" prefetchKey=":source" />
    * ```
    */
@@ -364,9 +370,11 @@ export const Link: ForwardRefExoticComponent<
         (!isHashOnlyNavigation(element) && !isPrefetchScopeDisabled(element)))
     ) {
       // For "hover", this is the primary prefetch trigger.
-      // For "viewport", this upgrades/prioritizes a potentially queued
-      // prefetch — prefetchDirect bypasses the queue, and hasPrefetch
-      // deduplicates if the viewport prefetch already completed.
+      // For "viewport", this prioritizes a potentially queued prefetch:
+      // prefetchDirect bypasses the queue, and its dedupe skips it when the
+      // viewport prefetch is cached or in flight. Either way it is an intent
+      // prefetch, which defers no `prefetch: false` work
+      // (docs/design/prefetch-false.md, R16).
       const segmentState = ctx.store.getSegmentState();
       prefetchDirect(
         resolvedTo,

package/src/browser/react/location-state-shared.ts

@@ -462,6 +462,12 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
  * The key is auto-injected by the Vite exposeInternalIds plugin as a property
  * based on file path and export name. No manual key required.
  *
+ * One definition is one slot in `history.state`. Entries of different
+ * definitions accumulate, but for the same definition the last write wins:
+ * two `ctx.setLocationState(Def(...))` calls in one response, or
+ * `redirect(url, { state: [Def(a), Def(b)] })`, deliver only the later
+ * value. To combine writes, make the state an array and write it once.
+ *
  * @param options Optional configuration
  * @returns A typed state definition for use with Link and useLocationState
  *
@@ -675,7 +681,8 @@ export function isLocationStateEntry(
 }
 
 /**
- * Resolve state entries into a flat object for history.state
+ * Resolve state entries into a flat object for history.state. One slot per
+ * definition: a later entry of the same definition replaces an earlier one.
  */
 export function resolveLocationStateEntries(
   entries: LocationStateEntry[],