@rangojs/router 0.31.0 → 0.33.0

package/src/bin/rango.ts

@@ -1,4 +1,5 @@
-import { resolve, dirname } from "node:path";
+#!/usr/bin/env node
+import { resolve, dirname, basename } from "node:path";
 import { readFileSync, statSync, existsSync } from "node:fs";
 import {
   findTsFiles,
@@ -8,6 +9,7 @@ import {
   detectUnresolvableIncludesForUrlsFile,
   findNestedRouterConflict,
   formatNestedRouterConflictError,
+  isRoutableSourceFile,
   type UnresolvableInclude,
 } from "../build/generate-route-types.ts";
 
@@ -93,6 +95,19 @@ Examples:
   );
 }
 
+/**
+ * A createRouter() file that is not a test: a test builds its own router (a
+ * Flight test's `*.rsc-test.tsx` usually mounts an inline urls() tree), and a
+ * named-routes.gen.ts beside it would merge its routes into the app's global
+ * GeneratedRouteMap. The same rule findRouterFiles() applies in Vite.
+ */
+function isRouterFile(filePath: string, source: string): boolean {
+  return (
+    isRoutableSourceFile(basename(filePath)) &&
+    /\bcreateRouter\s*[<(]/.test(source)
+  );
+}
+
 /**
  * Walk up from a file path to find the project root (directory containing
  * package.json or vite.config.ts).
@@ -141,7 +156,7 @@ function runStaticGeneration(args: string[], mode: "default" | "static") {
   for (const filePath of files) {
     try {
       const source = readFileSync(filePath, "utf-8");
-      if (/\bcreateRouter\s*[<(]/.test(source)) {
+      if (isRouterFile(filePath, source)) {
         routerFiles.push(filePath);
       }
       // Both spellings, matching the writer's own gate: "clientUrls(" does
@@ -181,7 +196,8 @@ function runStaticGeneration(args: string[], mode: "default" | "static") {
   // Deduplicate diagnostics (router and urls detection may find the same issue)
   const seen = new Set<string>();
   const uniqueDiagnostics = allDiagnostics.filter((d) => {
-    const key = `${d.sourceFile}:${d.pathPrefix}:${d.reason}`;
+    // Every unreadable routes mount has pathPrefix "/": its detail names it.
+    const key = `${d.sourceFile}:${d.pathPrefix}:${d.reason}${d.reason === "unresolvable-routes" ? `:${d.detail}` : ""}`;
     if (seen.has(key)) return false;
     seen.add(key);
     return true;
@@ -192,10 +208,11 @@ function runStaticGeneration(args: string[], mode: "default" | "static") {
     console.error("\n[rango] Unresolvable routes detected:\n");
     formatDiagnostics(uniqueDiagnostics);
     console.error(
-      "\nThe static parser cannot resolve these includes or basename because " +
-        "they use factory functions or dynamic expressions. A basename must be " +
-        "a string literal or a top-level const (in the router file or imported " +
-        "from a relative module).\n\n" +
+      "\nThe static parser cannot resolve these includes, routes or basename " +
+        "because they use factory functions or dynamic expressions. A router's " +
+        "routes must be a urls() call, a builder function or a variable holding " +
+        "urls(); a basename must be a string literal or a top-level const (in " +
+        "the router file or imported from a relative module).\n\n" +
         "Options:\n" +
         "  rango generate <path> --runtime   Use Vite-based discovery (requires vite)\n" +
         "  rango generate <path> --static    Accept partial output (missing routes or basename prefix above)\n",
@@ -255,7 +272,7 @@ async function runRuntimeDiscovery(args: string[], configFile?: string) {
   for (const filePath of files) {
     try {
       const source = readFileSync(filePath, "utf-8");
-      if (/\bcreateRouter\s*[<(]/.test(source)) {
+      if (isRouterFile(filePath, source)) {
         routerEntries.push(filePath);
       }
       // Also generate per-module types for urls files. Both spellings — a
@@ -281,6 +298,10 @@ async function runRuntimeDiscovery(args: string[], configFile?: string) {
     process.exit(1);
   }
 
+  // Loads from its own chunk only because the bin is built with esbuild
+  // --splitting (package.json "build"). A single-file bundle folds this module
+  // in and hoists its Vite imports to the top, so every command, --help
+  // included, failed without vite installed.
   let discoverAndWriteRouteTypes: typeof import("../build/runtime-discovery.ts").discoverAndWriteRouteTypes;
   try {
     const mod = await import("../build/runtime-discovery.ts");
@@ -290,9 +311,12 @@ async function runRuntimeDiscovery(args: string[], configFile?: string) {
       err.code === "ERR_MODULE_NOT_FOUND" ||
       err.code === "MODULE_NOT_FOUND"
     ) {
+      // runtime-discovery checks vite and @vitejs/plugin-rsc itself and names
+      // what to install, so reaching here means a bundled chunk file is
+      // missing: the installed package is incomplete.
       console.error(
-        "[rango] Runtime discovery requires 'vite' and '@vitejs/plugin-rsc'.\n" +
-          "Install them with: pnpm add -D vite @vitejs/plugin-rsc",
+        `[rango] Failed to load runtime discovery: ${err.message}\n` +
+          "The installed @rangojs/router looks broken (a CLI chunk is missing). Reinstall it.",
       );
     } else {
       console.error(`[rango] Failed to load runtime discovery: ${err.message}`);
@@ -320,9 +344,11 @@ function formatDiagnostics(
     const prefix =
       d.reason === "unresolvable-basename"
         ? "createRouter basename"
-        : d.namePrefix
-          ? `${d.namePrefix}.*`
-          : `${d.pathPrefix}*`;
+        : d.reason === "unresolvable-routes"
+          ? "createRouter routes"
+          : d.namePrefix
+            ? `${d.namePrefix}.*`
+            : `${d.pathPrefix}*`;
     console.error(`  ${prefix}`);
     console.error(`    Reason:  ${d.reason} -- ${d.detail}`);
     console.error(`    Source:  ${d.sourceFile}`);

package/src/browser/action-fence.ts

@@ -38,12 +38,82 @@
 
 let fenceCount = 0;
 
+/**
+ * Whether a cookie read saw the state rotate externally while the fence was
+ * up and no action's landing took it yet (navigation-store-handle.ts reports
+ * it). Almost always an action's own server-seat `invalidateClientCache()`
+ * `Set-Cookie`; a sibling tab's rotation in that window reads the same and
+ * costs one full flush, today's behavior. navigation-store.ts takes it when
+ * an action lands, so one rotation makes one landing flush, not every later
+ * landing of the batch.
+ */
+let rotatedInFence = false;
+
+/**
+ * Whether a cookie read saw a write-only change of the state (a server
+ * action's response, this tab's or another's) while the fence was up and no
+ * action's landing took it yet. A landing marks every cache stale, so it
+ * takes this; when the fence drops with it still set (the actions that
+ * landed called keepClientCache(), failed before they were sent, or reloaded
+ * on a version mismatch), the drop hands it to `unlandedWriteHandler`.
+ */
+let wroteInFence = false;
+
+let unlandedWriteHandler: (() => void) | null = null;
+
+/**
+ * Register what runs when the fence drops holding a write no landing took:
+ * the navigation store's markCachesStaleAfterWrite (navigation-store-handle.ts).
+ */
+export function setUnlandedWriteHandler(handler: (() => void) | null): void {
+  unlandedWriteHandler = handler;
+}
+
 export function enterActionFence(): void {
+  if (fenceCount === 0) {
+    rotatedInFence = false;
+    wroteInFence = false;
+  }
   fenceCount++;
 }
 
 export function exitActionFence(): void {
   if (fenceCount > 0) fenceCount--;
+  if (fenceCount === 0 && wroteInFence) {
+    wroteInFence = false;
+    unlandedWriteHandler?.();
+  }
+}
+
+/** A cookie read saw an external state rotation (rango-state.ts observer). */
+export function noteStateRotation(): void {
+  if (fenceCount > 0) rotatedInFence = true;
+}
+
+/**
+ * A cookie read saw a write-only change (rango-state.ts write observer).
+ * Returns whether the fence is up and took it; with the fence down the
+ * caller marks the caches stale itself.
+ */
+export function noteStateWrite(): boolean {
+  if (fenceCount === 0) return false;
+  wroteInFence = true;
+  return true;
+}
+
+/** A landing marked every cache stale: a write seen so far is covered. */
+export function takeStateWriteInActionFence(): void {
+  wroteInFence = false;
+}
+
+/**
+ * Whether the state rotated externally since the fence went up or the last
+ * landing took it, and clear it. False with the fence down.
+ */
+export function takeStateRotationInActionFence(): boolean {
+  const rotated = fenceCount > 0 && rotatedInFence;
+  rotatedInFence = false;
+  return rotated;
 }
 
 export function isActionFenceActive(): boolean {
@@ -53,4 +123,6 @@ export function isActionFenceActive(): boolean {
 /** Test-only: reset the refcount between cases. */
 export function __resetActionFence(): void {
   fenceCount = 0;
+  rotatedInFence = false;
+  wroteInFence = false;
 }

package/src/browser/cookie-name.ts

@@ -91,31 +91,48 @@ export function getRawCookieValue(
 }
 
 /**
- * Encode a state value for the wire: `encodeURIComponent(version):timestamp`.
- * Only the build-derived version is encoded (it is arbitrary); the `:`
- * separator and numeric timestamp stay raw, so the `{version}:{timestamp}`
- * shape survives and `:` is a legal cookie-value octet.
+ * Encode a state value for the wire: `encodeURIComponent(version):timestamp`,
+ * plus `:write` when the write part is not 0. Only the build-derived version
+ * is encoded (it is arbitrary); the `:` separators and the numeric parts stay
+ * raw, so the shape survives and `:` is a legal cookie-value octet. A value no
+ * server action has bumped keeps the two-part shape it had before the write
+ * part existed.
  */
-export function encodeStateValue(version: string, timestamp: number): string {
-  return `${encodeURIComponent(version)}:${timestamp}`;
+export function encodeStateValue(
+  version: string,
+  timestamp: number,
+  write = 0,
+): string {
+  const base = `${encodeURIComponent(version)}:${timestamp}`;
+  return write === 0 ? base : `${base}:${write}`;
 }
 
-/** Parsed state value. `version` is decoded; `timestamp` is the raw integer. */
+/**
+ * Parsed state value. `version` is decoded; `timestamp` (the invalidation
+ * part) and `write` are the raw integers. `write` is 0 for a two-part value.
+ */
 export interface StateValue {
   version: string;
   timestamp: number;
+  write: number;
 }
 
 /**
- * Decode a wire value back into `{version, timestamp}`. Returns null for a
- * malformed value (no `:`, empty version, or non-numeric timestamp) so callers
- * mint fresh instead of trusting garbage.
+ * Decode a wire value back into `{version, timestamp, write}`. Accepts the
+ * two-part `{version}:{timestamp}` (a value no action bumped, or one an open
+ * tab wrote before the write part existed) and the three-part
+ * `{version}:{timestamp}:{write}`. Returns null for a malformed value (no `:`,
+ * empty version, a non-numeric part, or more parts) so callers mint fresh
+ * instead of trusting garbage.
  */
 export function decodeStateValue(raw: string): StateValue | null {
   const colon = raw.indexOf(":");
   if (colon <= 0) return null;
-  const timestamp = Number(raw.slice(colon + 1));
-  if (!Number.isFinite(timestamp)) return null;
+  const parts = raw.slice(colon + 1).split(":");
+  if (parts.length > 2) return null;
+  const timestamp = parseStatePart(parts[0]!);
+  const write = parts.length === 2 ? parseStatePart(parts[1]!) : 0;
+  if (timestamp === null || write === null) return null;
   let version: string;
   try {
     version = decodeURIComponent(raw.slice(0, colon));
@@ -124,7 +141,31 @@ export function decodeStateValue(raw: string): StateValue | null {
     // a thrown URIError here would 500 the server seat or fail client boot.
     return null;
   }
-  return { version, timestamp };
+  return { version, timestamp, write };
+}
+
+function parseStatePart(part: string): number | null {
+  if (part === "") return null;
+  const value = Number(part);
+  return Number.isFinite(value) ? value : null;
+}
+
+/**
+ * The `{version}:{timestamp}` part of a wire value: what every in-memory
+ * comparison on the client reads (the prefetch cache keys, the action
+ * fence's rotation check, the external-rotation observer). A change to it is
+ * a hard invalidation (a deploy, or invalidateClientCache() on either seat);
+ * a change to the write part alone is a server action's write, which marks
+ * caches stale and flushes nothing. The full value, write part included, is
+ * what requests send as `X-Rango-State`, so the browser HTTP cache (Vary)
+ * misses after every write. A raw cut, no decode: the version is
+ * percent-encoded, so the second `:` is always the write separator.
+ */
+export function stateEpoch(raw: string): string {
+  const first = raw.indexOf(":");
+  if (first < 0) return raw;
+  const second = raw.indexOf(":", first + 1);
+  return second < 0 ? raw : raw.slice(0, second);
 }
 
 /**
@@ -132,7 +173,9 @@ export function decodeStateValue(raw: string): StateValue | null {
  * one, so a re-mint inside the same millisecond (or a backward clock step) still
  * differs from the current value. `prevRaw` is the current wire value (the
  * client's in-memory mirror, or the server's inbound header/cookie) or null; its
- * timestamp is the floor. Shared by both seats so the monotonic guard lives once.
+ * timestamp is the floor. The write part starts over (left out): the new
+ * timestamp alone makes the value one no response was cached under. Shared by
+ * both seats so the monotonic guard lives once.
  */
 export function mintStateValue(
   version: string,
@@ -143,6 +186,31 @@ export function mintStateValue(
   return encodeStateValue(version, ts);
 }
 
+/**
+ * Bump the write part of `prevRaw`, keeping its version and timestamp: what
+ * the response of a server action without a directive sets. Keeping the
+ * version keeps the bump soft for a client still on another build (a form
+ * posted from a document served before a deploy); its own boot handles the
+ * deploy. Returns null when `prevRaw` is absent or malformed: a client with
+ * no state value sends no `X-Rango-State` and has nothing in the HTTP cache
+ * keyed by one.
+ *
+ * The new write part must be one no response was cached under. It is
+ * strictly greater than the previous one, and it is the current time in
+ * microseconds with random low digits: two actions that start from the same
+ * value (two tabs, or two in flight in one tab) can run in the same server
+ * millisecond (a Worker's clock does not move between I/O), and the second
+ * response must not set the value the first one set, under which a prefetch
+ * between them may have been cached with the second write missing.
+ */
+export function bumpStateWrite(prevRaw: string | null): string | null {
+  const prev = prevRaw ? decodeStateValue(prevRaw) : null;
+  if (!prev) return null;
+  const fresh = Date.now() * 1000 + Math.floor(Math.random() * 1000);
+  const write = Math.max(fresh, prev.write + 1);
+  return encodeStateValue(prev.version, prev.timestamp, write);
+}
+
 /**
  * Attribute string for the state cookie. Session cookie (no Max-Age/Expires),
  * Path=/ (whole app), SameSite=Lax (sent on top-level navigations), and Secure

package/src/browser/history-state.ts

@@ -158,8 +158,9 @@ export function stripShellMissMarker(): void {
  * the server rendered this document without them. One pass before hydration
  * (initBrowserApp; renderRoute's `hydrate` mode), so no reader needs to know
  * the page began as a document load, and a slot nobody reads is removed too.
- * No server-set state exists yet to lose: a document response carries none
- * (rsc-rendering.ts attaches it to partial payloads only).
+ * Server-set state is not lost to it: the state a document response carries
+ * is merged after this pass (applyDocumentLocationState), so a `~r` slot the
+ * server set for this load survives this load and no later one.
  *
  * A slot is recognised by its key alone (the `~r` suffix): at start-up the
  * module that defines it may not be loaded.
@@ -185,6 +186,27 @@ export function clearLocationStateOnDocumentLoad(): void {
   if (next) window.history.replaceState(next, "");
 }
 
+/**
+ * Merge the location state a document response carried (its bootstrap
+ * payload's `metadata.locationState`, server/document-location-state.ts)
+ * into the entry the document loaded on. Start-up runs it after
+ * clearLocationStateOnDocumentLoad and the version is set, before the entry
+ * is committed for readers (initBrowserApp; renderRoute's `hydrate` mode),
+ * so readers get it once they have hydrated, as stored state. Only typed
+ * slots are taken.
+ */
+export function applyDocumentLocationState(
+  locationState: Record<string, unknown> | undefined,
+): void {
+  if (!locationState) return;
+  let slots: Record<string, unknown> | undefined;
+  for (const key of Object.keys(locationState)) {
+    if (!isLocationStateKey(key)) continue;
+    (slots ??= {})[key] = locationState[key];
+  }
+  if (slots) mergeLocationState(slots);
+}
+
 /**
  * Merge server-set location state into the current history entry and return
  * the entry state written. Readers see it when the caller commits it

package/src/browser/invalidate-client-cache.ts

@@ -1,12 +1,14 @@
 /**
  * Client seat of `invalidateClientCache()` (the `default` export condition).
  *
- * Makes the current client behave as if a server action had just completed:
- * the history cache is marked stale (SWR), the prefetch map is flushed, the
- * state rotates, and sibling tabs are broadcast to — the same
- * `markCacheAsStaleAndBroadcast()` path the server-action bridge uses. This is
- * the gentler mark-stale (not hard-clear) behavior, so Back renders the cached
- * entry instantly and revalidates.
+ * The full client invalidation, more than a server action without a
+ * directive does: the history cache is marked stale (SWR), the prefetch map
+ * is flushed (in-flight prefetches aborted, visible links prefetch again), the
+ * state rotates, and sibling tabs are broadcast to, which adopt the new state
+ * and flush too (`invalidateCacheAndBroadcast()`). A directive-free action
+ * only marks history and prefetches stale and rotates nothing
+ * (`markCacheAsStaleAndBroadcast()`). History is marked stale, not cleared, so
+ * Back renders the cached entry instantly and revalidates.
  */
 
 import { getRegisteredStore } from "./navigation-store-handle.js";
@@ -27,7 +29,7 @@ export function invalidateClientCache(): void {
 
   const store = getRegisteredStore();
   if (store) {
-    store.markCacheAsStaleAndBroadcast();
+    store.invalidateCacheAndBroadcast();
     return;
   }
 

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