@rangojs/router 0.0.0-experimental.77 → 0.0.0-experimental.77ed8945

package/src/browser/navigation-transaction.ts

@@ -11,7 +11,7 @@ import {
 } from "./scroll-restoration.js";
 import type { EventController, NavigationHandle } from "./event-controller.js";
 import { debugLog } from "./logging.js";
-import { buildHistoryState } from "./history-state.js";
+import { buildHistoryState, pushHistoryWithIdx } from "./history-state.js";
 
 // Re-export for consumers that import from navigation-transaction
 export { resolveNavigationState } from "./history-state.js";
@@ -186,12 +186,8 @@ export function createNavigationTransaction(
     // Used to detect when location state is being cleared.
     const oldState = window.history.state;
 
-    // Update browser URL
-    if (replace) {
-      window.history.replaceState(historyState, "", url);
-    } else {
-      window.history.pushState(historyState, "", url);
-    }
+    // Update browser URL (stamps history.state.idx for back() first-entry detection)
+    pushHistoryWithIdx(historyState, url, replace ?? false);
     // Ensure new history entry has a scroll restoration key
     ensureHistoryKey();
 
@@ -240,30 +236,16 @@ export function createNavigationTransaction(
           segments: ResolvedSegment[],
           overrides?: BoundCommitOverrides,
         ) => {
-          // Allow overrides to disable scroll (e.g., for intercepts)
-          const finalScroll =
-            overrides?.scroll !== undefined ? overrides.scroll : opts.scroll;
-          // Allow overrides to force replace (e.g., for intercepts)
-          const finalReplace =
-            overrides?.replace !== undefined ? overrides.replace : opts.replace;
-          // Intercept info: overrides take precedence, fallback to opts
-          const intercept =
-            overrides?.intercept !== undefined
-              ? overrides.intercept
-              : opts.intercept;
+          const finalScroll = overrides?.scroll ?? opts.scroll;
+          const finalReplace = overrides?.replace ?? opts.replace;
+          const intercept = overrides?.intercept ?? opts.intercept;
           const interceptSourceUrl =
-            overrides?.interceptSourceUrl !== undefined
-              ? overrides.interceptSourceUrl
-              : opts.interceptSourceUrl;
-          // Cache-only mode: overrides take precedence, fallback to opts
-          const cacheOnly =
-            overrides?.cacheOnly !== undefined
-              ? overrides.cacheOnly
-              : opts.cacheOnly;
-          // User state: overrides take precedence, fallback to opts
+            overrides?.interceptSourceUrl ?? opts.interceptSourceUrl;
+          const cacheOnly = overrides?.cacheOnly ?? opts.cacheOnly;
+          // state is `unknown` (null is meaningful) so `??` would wrongly drop a
+          // null override; serverState always comes from overrides, never opts.
           const state =
             overrides?.state !== undefined ? overrides.state : opts.state;
-          // Server-set location state: only from overrides (set by partial-update)
           const serverState = overrides?.serverState;
           return commit({
             ...opts,

package/src/browser/partial-update.ts

@@ -14,7 +14,10 @@ const addTransitionType: ((type: string) => void) | undefined =
 import type { RenderSegmentsOptions } from "../segment-system.js";
 import { reconcileSegments } from "./segment-reconciler.js";
 import type { ReconcileActor } from "./segment-reconciler.js";
-import { hasActiveIntercept as hasActiveInterceptSlots } from "./intercept-utils.js";
+import {
+  hasActiveIntercept as hasActiveInterceptSlots,
+  isInterceptSegment,
+} from "./intercept-utils.js";
 import type { BoundTransaction } from "./navigation-transaction.js";
 import { ServerRedirect } from "../errors.js";
 import { debugLog } from "./logging.js";
@@ -28,6 +31,23 @@ function toScrollPayload(
   return { enabled: scroll !== false ? scroll : false };
 }
 
+/**
+ * Whether to wrap an update in startViewTransition.
+ *
+ * Intercept-driven updates only mutate the parallel slot — the main outlet
+ * shows the same content — so transitions on the underlying main segments
+ * shouldn't fire (otherwise their elements get hoisted above the modal).
+ */
+function shouldStartViewTransition(segments: ResolvedSegment[]): boolean {
+  let hasIntercept = false;
+  let hasTransition = false;
+  for (const s of segments) {
+    if (isInterceptSegment(s)) hasIntercept = true;
+    else if (s.transition) hasTransition = true;
+  }
+  return !hasIntercept && hasTransition;
+}
+
 /**
  * Configuration for creating a partial updater
  */
@@ -76,7 +96,7 @@ export type UpdateMode =
       /** Source URL for intercept restore (popstate cache miss) */
       interceptSourceUrl?: string;
     }
-  | { type: "leave-intercept" }
+  | { type: "leave-intercept"; interceptSourceUrl?: string }
   | { type: "stale-revalidation"; interceptSourceUrl?: string }
   | { type: "action"; interceptSourceUrl?: string };
 
@@ -141,13 +161,7 @@ export function createPartialUpdater(
     // Capture history key at start for stale revalidation consistency check
     const historyKeyAtStart = store.getHistoryKey();
 
-    // Derive interceptSourceUrl from modes that carry it
-    const interceptSourceUrl =
-      mode.type === "stale-revalidation" ||
-      mode.type === "action" ||
-      mode.type === "navigate"
-        ? mode.interceptSourceUrl
-        : undefined;
+    const interceptSourceUrl = mode.interceptSourceUrl;
 
     // When leaving intercept, filter out intercept-specific segments
     let segments: string[];
@@ -167,9 +181,16 @@ export function createPartialUpdater(
       segments = segmentIds ?? segmentState.currentSegmentIds;
     }
 
-    // For intercept revalidation, use the intercept source URL as previousUrl
+    // For intercept revalidation, use the intercept source URL as previousUrl.
+    // For leave-intercept, tx.currentUrl captures window.location.href at tx
+    // creation, which on popstate is already the destination URL and would
+    // tell the server "from == to". segmentState.currentUrl still points at
+    // the URL the cached segments render (the intercept URL), which is the
+    // correct "from" for the server's diff computation.
     const previousUrl =
-      interceptSourceUrl || tx.currentUrl || segmentState.currentUrl;
+      mode.type === "leave-intercept"
+        ? segmentState.currentUrl || tx.currentUrl
+        : interceptSourceUrl || tx.currentUrl || segmentState.currentUrl;
 
     debugLog(`\n[Browser] >>> NAVIGATION`);
     debugLog(`[Browser] From: ${previousUrl}`);
@@ -183,13 +204,11 @@ export function createPartialUpdater(
     // When navigating with targetCacheSegments, use those for consistency.
     // Otherwise fall back to current page's segments (for same-route revalidation).
     const targetCache =
-      mode.type === "navigate" ? mode.targetCacheSegments : undefined;
-    const cachedSegs =
-      targetCache && targetCache.length > 0
-        ? targetCache
-        : getCurrentCachedSegments();
-    const cachedSegsSource =
-      targetCache && targetCache.length > 0 ? "history-cache" : "current-page";
+      mode.type === "navigate" && mode.targetCacheSegments?.length
+        ? mode.targetCacheSegments
+        : undefined;
+    const cachedSegs = targetCache ?? getCurrentCachedSegments();
+    const cachedSegsSource = targetCache ? "history-cache" : "current-page";
     debugLog(
       `[Browser] cachedSegs source: ${cachedSegsSource} (${cachedSegs.length} segments: ${cachedSegs.map((s) => s.id).join(", ")})`,
     );
@@ -218,19 +237,25 @@ export function createPartialUpdater(
       streamingToken.end();
     });
 
-    // Detect app switch: if routerId changed, the navigation crossed into
-    // a different router (e.g., via host router path mount). Downgrade
-    // partial to full so the entire tree is replaced without reconciliation
-    // against stale segments from the previous app.
-    if (payload.metadata?.routerId) {
-      const prevRouterId = store.getRouterId?.();
-      if (prevRouterId && prevRouterId !== payload.metadata.routerId) {
-        debugLog(
-          `[Browser] App switch detected (${prevRouterId} → ${payload.metadata.routerId}), forcing full update`,
-        );
-        payload.metadata.isPartial = false;
-      }
-      store.setRouterId?.(payload.metadata.routerId);
+    // Integrity guard (defense in depth). The server redirects on a cross-app
+    // routerId mismatch (X-RSC-Reload), so a partial payload's routerId must
+    // match this client's. If it doesn't — a stale/edge cache keyed without the
+    // routerId, a proxy mixing app responses, or a server classification bug —
+    // do NOT splice a foreign app's segments and client references into this
+    // document. Force a full reload so the server re-establishes the
+    // authoritative document for this URL.
+    const currentRouterId = store.getRouterId?.();
+    if (
+      payload.metadata?.routerId &&
+      currentRouterId &&
+      payload.metadata.routerId !== currentRouterId
+    ) {
+      console.error(
+        `[rango] Partial response router id "${payload.metadata.routerId}" does not ` +
+          `match this client ("${currentRouterId}"); discarding it and reloading to re-sync.`,
+      );
+      window.location.href = url;
+      return;
     }
 
     // Handle server-side redirect with state
@@ -272,7 +297,7 @@ export function createPartialUpdater(
           .filter(Boolean) as ResolvedSegment[];
 
         // When navigating with cached segments to a different route, render them.
-        if (mode.type === "navigate" && targetCache && targetCache.length > 0) {
+        if (mode.type === "navigate" && targetCache) {
           debugLog(
             "[Browser] No diff but navigating with cached segments - rendering target route",
           );
@@ -312,10 +337,7 @@ export function createPartialUpdater(
             scroll: toScrollPayload(commitScroll),
           };
 
-          const cachedHasTransition = existingSegments.some(
-            (s) => s.transition,
-          );
-          if (cachedHasTransition) {
+          if (shouldStartViewTransition(existingSegments)) {
             startTransition(() => {
               if (addTransitionType) {
                 addTransitionType("navigation");
@@ -501,7 +523,7 @@ export function createPartialUpdater(
 
       // Emit update to trigger React render.
       // Scroll info is included so NavigationProvider applies it after React commits.
-      const hasTransition = reconciled.mainSegments.some((s) => s.transition);
+      const hasTransition = shouldStartViewTransition(reconciled.segments);
       const scrollPayload = toScrollPayload(navScroll);
 
       if (mode.type === "action" || mode.type === "stale-revalidation") {
@@ -563,9 +585,7 @@ export function createPartialUpdater(
           })
         : tx.commit(segmentIds, segments);
 
-      const fullHasTransition = segments.some(
-        (s: ResolvedSegment) => s.transition,
-      );
+      const fullHasTransition = shouldStartViewTransition(segments);
       const fullScrollPayload = toScrollPayload(fullScroll);
 
       if (mode.type === "stale-revalidation") {

package/src/browser/prefetch/cache.ts

@@ -1,14 +1,33 @@
 /**
  * Prefetch Cache
  *
- * In-memory cache storing prefetched Response objects for instant cache hits
- * on subsequent navigation. Cache key is source-dependent (includes the
- * current page URL) because the server's diff-based response depends on
- * where the user navigates from.
+ * In-memory cache storing eagerly-decoded prefetch payloads for instant,
+ * already-warm cache hits on subsequent navigation. A prefetch fetches the
+ * RSC partial AND decodes it (createFromFetch) up front — decoding the Flight
+ * 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:
+ * - Wildcard (default): built by `buildPrefetchKey(rangoState, target)` —
+ *   shape `rangoState\0/target?...`. Shared across all source pages and
+ *   invalidated automatically when Rango state bumps (deploy or
+ *   server-action invalidation).
+ * - Source-scoped: built by `buildSourceKey(rangoState, sourceHref, target)`
+ *   — shape `rangoState\0sourceHref\0/target?...`. Embeds the Rango state
+ *   (so rotation invalidates source-scoped entries too) plus the source
+ *   href (so each originating page gets its own slot). Populated when the
+ *   server tags a response with `X-RSC-Prefetch-Scope: source` (intercept
+ *   modals etc.), OR when a Link opts in with `prefetchKey=":source"` — in
+ *   both cases so source-sensitive responses cannot bleed into navigations
+ *   from other pages.
  *
  * Also tracks in-flight prefetch promises. Each promise resolves to the
- * navigation branch of a tee'd Response, allowing navigation to adopt a
- * still-downloading prefetch without reparsing or buffering the body.
+ * decoded prefetch entry (or null), letting navigation adopt a
+ * still-downloading prefetch without issuing a duplicate request. A
+ * single promise can be registered under multiple alias keys (see
+ * `setInflightPromiseWithAliases`) so same-source navigations adopt via
+ * their source key while cross-source ones fall through to the wildcard
+ * alias — with consume/clear atomically removing every alias.
  *
  * Replaces the previous browser HTTP cache approach which was unreliable
  * due to response draining race conditions and browser inconsistencies.
@@ -16,6 +35,31 @@
 
 import { abortAllPrefetches } from "./queue.js";
 import { invalidateRangoState } from "../rango-state.js";
+import type { RscPayload } from "../types.js";
+
+/**
+ * A prefetch that has been fetched AND eagerly decoded. Storing the decoded
+ * payload (not the raw Response) is what makes a prefetched navigation "warm":
+ * decoding the Flight stream during prefetch pulls the route's client chunks,
+ * so the click reuses ready elements and loads no new JS.
+ */
+export interface DecodedPrefetch {
+  /** The eagerly-decoded RSC payload. Reused verbatim by navigation. */
+  payload: Promise<RscPayload>;
+  /**
+   * Resolves when the underlying RSC stream finishes draining. Navigation
+   * forwards this as its streamComplete so scroll/revalidation gating is
+   * unchanged from the fresh-fetch path.
+   */
+  streamComplete: Promise<void>;
+  /**
+   * 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.
+   */
+  scope: "source" | "wildcard";
+}
 
 // Default TTL: 5 minutes. Overridden by initPrefetchCache() with
 // the server-configured prefetchCacheTTL from router options.
@@ -41,7 +85,7 @@ export function isPrefetchCacheDisabled(): boolean {
 const MAX_PREFETCH_CACHE_SIZE = 50;
 
 interface PrefetchCacheEntry {
-  response: Response;
+  entry: DecodedPrefetch;
   timestamp: number;
 }
 
@@ -49,11 +93,36 @@ const cache = new Map<string, PrefetchCacheEntry>();
 const inflight = new Set<string>();
 
 /**
- * In-flight promise map. When a prefetch fetch is in progress, its
- * Promise<Response | null> is stored here so navigation can await
- * it instead of starting a duplicate request.
+ * In-flight promise map. When a prefetch fetch+decode is in progress, its
+ * Promise<DecodedPrefetch | null> is stored here so navigation can await it
+ * instead of starting a duplicate request. Resolves to null when the prefetch
+ * failed, was aborted, or carried a control header (reload/redirect) that the
+ * navigation must re-fetch to act on.
+ */
+const inflightPromises = new Map<string, Promise<DecodedPrefetch | null>>();
+
+/**
+ * Alias map for in-flight promises registered under multiple keys (see
+ * dual inflight in prefetch/fetch.ts). Records each key's sibling set so
+ * that consuming or clearing any one key atomically removes every alias —
+ * guaranteeing a single consumer for the shared decode.
  */
-const inflightPromises = new Map<string, Promise<Response | null>>();
+const inflightAliases = new Map<string, string[]>();
+
+/**
+ * Keys whose in-flight prefetch promise was adopted by a navigation (via
+ * `consumeInflightPrefetch`). A `DecodedPrefetch` carries a single-use
+ * `metadata.handles` async generator; the adopter drains it. The same entry is
+ * also published to the `cache` map by `storePrefetch` when the fetch resolves
+ * — which runs AFTER adoption (adoption only succeeds while the fetch is still
+ * in flight, so the entry is not yet cached). Without this guard the adopted,
+ * now-drained entry would be left in the cache and served to a later navigation
+ * whose handle generator yields nothing, silently dropping that route's
+ * breadcrumbs. Recording the adopted keys lets `storePrefetch` skip publishing
+ * them, keeping the existing one-time-consumption contract (a consumed prefetch
+ * is gone; the next navigation re-fetches).
+ */
+const adoptedKeys = new Set<string>();
 
 // Generation counter incremented on each clearPrefetchCache(). Fetches that
 // started before a clear carry a stale generation and must not store their
@@ -61,23 +130,57 @@ const inflightPromises = new Map<string, Promise<Response | null>>();
 let generation = 0;
 
 /**
- * Build a cache key for prefetched responses.
+ * Build a cache key by combining a scope prefix with the target URL.
+ *
+ * Low-level primitive — callers that want a specific scope should use
+ * 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).
+ *   Key shape: `rangoState\0/target?...`.
+ * - Source-scoped: use `buildSourceKey()`. Key shape:
+ *   `rangoState\0sourceHref\0/target?...` — embeds the Rango state so
+ *   rotation invalidates source-scoped entries alongside wildcard ones,
+ *   plus the source page href so the key is unique per originating page.
+ *   Populated either when the server tags a response with
+ *   `X-RSC-Prefetch-Scope: source` (intercept modals, etc.) or when a
+ *   Link opts in via `prefetchKey=":source"`.
  *
- * By default the key includes the source page href so the same target
- * prefetched from different pages gets separate entries (the server's
- * diff response depends on the source page context).
+ * The `_rsc_segments` query param that travels in the target URL means
+ * clients with different mounted segment trees naturally get different
+ * keys — so segment-level diffs remain consistent across both scopes.
+ */
+export function buildPrefetchKey(prefix: string, targetUrl: URL): string {
+  return prefix + "\0" + targetUrl.pathname + targetUrl.search;
+}
+
+/**
+ * Build a source-scoped cache key. Key shape:
+ * `rangoState\0sourceHref\0/target?...`.
  *
- * When `prefetchKey` is provided, the source portion is replaced with
- * a `*` sentinel so all custom-keyed entries share one cache slot per
- * target — enabling source-agnostic cache reuse.
+ * - `rangoState` is included so state rotation invalidates source-scoped
+ *   entries alongside wildcard ones.
+ * - `sourceHref` makes the key unique per originating page.
  */
-export function buildPrefetchKey(
+export function buildSourceKey(
+  rangoState: string,
   sourceHref: string,
   targetUrl: URL,
-  prefetchKey?: string | ((from: string) => string),
 ): string {
-  const source = prefetchKey != null ? "*" : sourceHref;
-  return source + "\0" + targetUrl.pathname + targetUrl.search;
+  return buildPrefetchKey(rangoState + "\0" + sourceHref, targetUrl);
+}
+
+/**
+ * Walk an inflight key plus any sibling aliases registered via
+ * `setInflightPromiseWithAliases`, invoking `fn` for each.
+ */
+function forEachAlias(key: string, fn: (k: string) => void): void {
+  const aliases = inflightAliases.get(key);
+  if (aliases) {
+    for (const k of aliases) fn(k);
+  } else {
+    fn(key);
+  }
 }
 
 /**
@@ -96,14 +199,14 @@ export function hasPrefetch(key: string): boolean {
 }
 
 /**
- * Consume a cached prefetch response. Returns null if not found or expired.
- * One-time consumption: the entry is deleted after retrieval.
+ * Consume a cached, eagerly-decoded prefetch. Returns null if not found or
+ * expired. One-time consumption: the entry is deleted after retrieval.
  * Returns null when caching is disabled (TTL <= 0).
  *
  * Does NOT check in-flight prefetches — use consumeInflightPrefetch()
- * for that (returns a Promise instead of a Response).
+ * for that (returns a Promise instead of a resolved entry).
  */
-export function consumePrefetch(key: string): Response | null {
+export function consumePrefetch(key: string): DecodedPrefetch | null {
   if (cacheTTL <= 0) return null;
   const entry = cache.get(key);
   if (!entry) return null;
@@ -112,52 +215,72 @@ export function consumePrefetch(key: string): Response | null {
     return null;
   }
   cache.delete(key);
-  return entry.response;
+  return entry.entry;
 }
 
 /**
  * Consume an in-flight prefetch promise. Returns null if no prefetch is
- * in-flight for this key. The returned Promise resolves to the buffered
- * Response (or null if the fetch failed/was aborted).
+ * in-flight for this key. The returned Promise resolves to the decoded
+ * prefetch entry (or null if the fetch failed/was aborted, or carried a
+ * control header the navigation must re-fetch to honor).
  *
- * One-time consumption: the promise entry is removed so a second call
- * returns null. The `inflight` set entry is intentionally kept so that
- * hasPrefetch() continues to return true while the underlying fetch is
- * still downloading — this prevents prefetchDirect() or other callers
- * from starting a duplicate request during the handoff window. The
- * inflight flag is cleaned up naturally by clearPrefetchInflight() in
- * the fetch's .finally().
+ * One-time consumption: the promise entry is removed (along with any
+ * sibling aliases registered via `setInflightPromiseWithAliases`) so a
+ * second call on any alias returns null — only one caller can adopt the
+ * shared Response stream. The `inflight` set entry is intentionally
+ * kept so that `hasPrefetch()` continues to return true while the
+ * underlying fetch is still downloading — this prevents
+ * `prefetchDirect()` or other callers from starting a duplicate request
+ * during the handoff window. The inflight flag is cleaned up naturally
+ * by `clearPrefetchInflight()` in the fetch's `.finally()`.
  */
 export function consumeInflightPrefetch(
   key: string,
-): Promise<Response | null> | null {
+): Promise<DecodedPrefetch | null> | null {
   const promise = inflightPromises.get(key);
   if (!promise) return null;
-  // Remove the promise (one-time consumption) but keep the inflight flag.
-  inflightPromises.delete(key);
+  // Remove the promise under every alias so a second consumer cannot
+  // adopt the same stream and race on the body, and mark every alias as
+  // adopted so the pending `storePrefetch` (which resolves later, after this
+  // adoption) does not leave the now-owned, single-use entry in the cache map.
+  // `inflightAliases` is intentionally preserved — `clearPrefetchInflight()` in
+  // the fetch's `.finally()` still needs it to clear every inflight flag and
+  // adopted marker; deleting here would strand the sibling's flag forever.
+  forEachAlias(key, (k) => {
+    inflightPromises.delete(k);
+    adoptedKeys.add(k);
+  });
   return promise;
 }
 
 /**
- * Store a prefetch response in the in-memory cache.
- * The response should be a clone() of the original so the caller can
- * still consume the body. The clone's body streams independently.
+ * 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).
  */
 export function storePrefetch(
   key: string,
-  response: Response,
+  entry: DecodedPrefetch,
   fetchGeneration: number,
 ): void {
   if (cacheTTL <= 0) return;
   if (fetchGeneration !== generation) return;
 
+  // If a navigation already adopted this prefetch's in-flight promise, it owns
+  // the single-use entry (and has drained its handle generator). Do NOT also
+  // 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));
+    return;
+  }
+
   // Evict expired entries
   const now = Date.now();
-  for (const [k, entry] of cache) {
-    if (now - entry.timestamp > cacheTTL) {
+  for (const [k, cached] of cache) {
+    if (now - cached.timestamp > cacheTTL) {
       cache.delete(k);
     }
   }
@@ -168,7 +291,7 @@ export function storePrefetch(
     if (oldest) cache.delete(oldest);
   }
 
-  cache.set(key, { response, timestamp: now });
+  cache.set(key, { entry, timestamp: now });
 }
 
 /**
@@ -188,14 +311,36 @@ export function markPrefetchInflight(key: string): void {
  */
 export function setInflightPromise(
   key: string,
-  promise: Promise<Response | null>,
+  promise: Promise<DecodedPrefetch | null>,
 ): void {
   inflightPromises.set(key, promise);
 }
 
+/**
+ * Store the same in-flight Promise under multiple keys, recording them
+ * as sibling aliases. Consuming or clearing any one alias atomically
+ * removes every entry, guaranteeing the shared Response stream has a
+ * single consumer even when navigation looks up either key.
+ */
+export function setInflightPromiseWithAliases(
+  keys: string[],
+  promise: Promise<DecodedPrefetch | null>,
+): void {
+  for (const k of keys) {
+    inflightPromises.set(k, promise);
+    inflightAliases.set(k, keys);
+  }
+}
+
 export function clearPrefetchInflight(key: string): void {
-  inflight.delete(key);
-  inflightPromises.delete(key);
+  forEachAlias(key, (k) => {
+    inflight.delete(k);
+    inflightPromises.delete(k);
+    inflightAliases.delete(k);
+    // Clear any adopted marker too, so a fetch that failed before storePrefetch
+    // (the marker's normal consumer) does not strand it across the next prefetch.
+    adoptedKeys.delete(k);
+  });
 }
 
 /**
@@ -210,6 +355,8 @@ export function clearPrefetchCache(): void {
   generation++;
   inflight.clear();
   inflightPromises.clear();
+  inflightAliases.clear();
+  adoptedKeys.clear();
   cache.clear();
   abortAllPrefetches();
   invalidateRangoState();