@rangojs/router 0.0.0-experimental.69 → 0.0.0-experimental.6c70a2ab

package/src/browser/navigation-bridge.ts

@@ -5,6 +5,8 @@ import type {
   ResolvedSegment,
 } from "./types.js";
 import { setAppVersion } from "./app-version.js";
+import { setRangoStateLocal } from "./rango-state.js";
+import type { AppShell, AppShellRef } from "./app-shell.js";
 import * as React from "react";
 import { startTransition } from "react";
 import {
@@ -48,8 +50,13 @@ export { createNavigationTransaction };
  */
 export interface NavigationBridgeConfigWithController extends NavigationBridgeConfig {
   eventController: EventController;
-  /** RSC version from initial payload metadata */
+  /** RSC version from initial payload metadata (fallback when appShellRef is not provided) */
   version?: string;
+  /**
+   * Live app-shell ref. When supplied, the bridge reads version/basename
+   * from this ref so cross-app navigations propagate correctly.
+   */
+  appShellRef?: AppShellRef;
 }
 
 /**
@@ -68,9 +75,46 @@ export interface NavigationBridgeConfigWithController extends NavigationBridgeCo
 export function createNavigationBridge(
   config: NavigationBridgeConfigWithController,
 ): NavigationBridge {
-  const { store, client, eventController, onUpdate, renderSegments } = config;
+  const {
+    store,
+    client,
+    eventController,
+    onUpdate,
+    renderSegments,
+    appShellRef,
+  } = config;
   let version = config.version;
 
+  /**
+   * Replace the active app-shell snapshot atomically. Called by the partial
+   * updater when a response's routerId indicates the navigation crossed
+   * into a different app. Runs the local-only side-effects tied to
+   * app-shell fields (app version, rango-state namespace) so the new app
+   * owns them after the swap. Theme, warmup, and prefetch TTL are
+   * document-lifetime and are NOT touched here.
+   */
+  function applyAppShell(next: AppShell): void {
+    if (appShellRef) {
+      appShellRef.update(next);
+    }
+    if (next.version !== undefined) {
+      version = next.version;
+      setAppVersion(next.version);
+      // Use the local-only setter — initRangoState writes the shared
+      // localStorage key and fires a storage event in other tabs still in
+      // the old app. setRangoStateLocal only mutates this tab's in-memory
+      // cache and rebinds it to the target app's routerId-scoped key,
+      // preserving the "local-only, no broadcast/rotation" contract for
+      // smooth app-switch transitions.
+      setRangoStateLocal(next.version, next.routerId);
+    }
+    // Cross-app: prior cache entries belong to a different app's segments.
+    // Drop them locally only — do NOT broadcast invalidation or rotate the
+    // shared X-Rango-State token, since other tabs still in the old app are
+    // unaffected by this tab's transition.
+    store.clearHistoryCacheLocal();
+  }
+
   // Create shared partial updater
   const fetchPartialUpdate = createPartialUpdater({
     store,
@@ -78,6 +122,7 @@ export function createNavigationBridge(
     onUpdate,
     renderSegments,
     getVersion: () => version,
+    applyAppShell,
   });
 
   return {
@@ -261,18 +306,24 @@ export function createNavigationBridge(
       // 2. routes that CAN be intercepted - we don't know if this navigation will intercept
       // 3. when leaving intercept - we need fresh non-intercept segments from server
       // 4. redirect-with-state - force re-render so hooks read fresh state
+      // 5. stale cache - server action invalidated it, need fresh data with loading state
       const hasUsableCache =
         cachedSegments &&
         cachedSegments.length > 0 &&
         !isInterceptOnlyCache(cachedSegments) &&
         !hasInterceptCache &&
         !isLeavingIntercept &&
+        !cached?.stale &&
         !options?._skipCache;
 
+      // Forward navigations always await fetchPartialUpdate before rendering,
+      // so useNavigation should always report "loading". skipLoadingState is
+      // only used for popstate background revalidation (line ~526) where
+      // cached content renders instantly without a network wait.
       const tx = createNavigationTransaction(store, eventController, url, {
         ...options,
         state: resolvedState,
-        skipLoadingState: hasUsableCache,
+        skipLoadingState: false,
       });
 
       // REVALIDATE: Fetch fresh data from server
@@ -412,6 +463,15 @@ export function createNavigationBridge(
         eventController.abortAllActions();
       }
 
+      // Popstate that exits an intercept to a non-intercept destination. The
+      // fallback fetch path below needs `leave-intercept` mode so it filters
+      // the cached @modal segment from the request and forces a re-render —
+      // otherwise a cache-miss popstate whose server response has an empty
+      // diff hits the "no changes" branch in partial-update and the modal
+      // stays on screen.
+      const isLeavingIntercept =
+        !isIntercept && currentInterceptSource !== null;
+
       // Compute history key from URL (with intercept suffix if applicable)
       const historyKey = generateHistoryKey(url, { intercept: isIntercept });
 
@@ -481,7 +541,14 @@ export function createNavigationBridge(
             },
             scroll: { restore: true, isStreaming },
           };
-          const hasTransition = cachedSegments.some((s) => s.transition);
+          // Intercept-driven popstate (entering OR leaving an intercept) only
+          // mutates the parallel slot; the main outlet shows the same content.
+          // Skip startViewTransition in those cases — same rationale as the
+          // intercept guard in partial-update.ts's hasTransition computation.
+          const hasTransition =
+            !isIntercept &&
+            !isLeavingIntercept &&
+            cachedSegments.some((s) => s.transition);
           if (hasTransition) {
             startTransition(() => {
               if (addTransitionType) {
@@ -562,7 +629,11 @@ export function createNavigationBridge(
             intercept: isIntercept,
             interceptSourceUrl,
           }),
-          isIntercept ? { type: "navigate", interceptSourceUrl } : undefined,
+          isIntercept
+            ? { type: "navigate", interceptSourceUrl }
+            : isLeavingIntercept
+              ? { type: "leave-intercept" }
+              : undefined,
         );
         // Restore scroll position after fetch completes
         handleNavigationEnd({ restore: true, isStreaming });
@@ -645,6 +716,10 @@ export function createNavigationBridge(
       setAppVersion(newVersion);
       store.clearHistoryCache();
     },
+
+    updateAppShell(next: AppShell): void {
+      applyAppShell(next);
+    },
   };
 }
 

package/src/browser/navigation-client.ts

@@ -19,6 +19,7 @@ import {
 } from "./response-adapter.js";
 import {
   buildPrefetchKey,
+  buildSourceKey,
   consumeInflightPrefetch,
   consumePrefetch,
 } from "./prefetch/cache.js";
@@ -30,8 +31,10 @@ import {
  * deserializing the response using the RSC runtime.
  *
  * Checks the in-memory prefetch cache before making a network request.
- * The cache key is source-dependent (includes the previous URL) so
- * prefetch responses match the exact diff the server would produce.
+ * Tries the source-scoped key first (populated when the server tagged
+ * the response as source-sensitive via `X-RSC-Prefetch-Scope: source`)
+ * and falls back to the Rango-state-keyed wildcard slot used for the
+ * common source-agnostic case.
  *
  * @param deps - RSC browser dependencies (createFromFetch)
  * @returns NavigationClient instance
@@ -93,18 +96,42 @@ export function createNavigationClient(
         fetchUrl.searchParams.set("_rsc_rid", routerId);
       }
 
-      // Check completed in-memory prefetch cache before making a network request.
-      // The cache key includes the source URL (previousUrl) because the
-      // server's diff response depends on the source page context.
+      // Check completed in-memory prefetch cache before making a network
+      // request. Try the source-scoped key first (populated when the server
+      // tagged the prefetch response as source-sensitive, e.g. intercepts,
+      // or when a Link opted in with `prefetchKey=":source"`), then fall
+      // back to the wildcard slot shared across source pages.
+      // Both keys embed the Rango state, so state rotation (deploy or
+      // server-action invalidation) auto-invalidates both scopes.
       // Skip cache for stale revalidation (needs fresh data), HMR (needs
       // fresh modules), and intercept contexts (source-dependent responses).
-      //
       const canUsePrefetch = !staleRevalidation && !hmr && !interceptSourceUrl;
-      const cacheKey = buildPrefetchKey(previousUrl, fetchUrl);
-      const cachedResponse = canUsePrefetch ? consumePrefetch(cacheKey) : null;
-      const inflightResponsePromise = canUsePrefetch
-        ? consumeInflightPrefetch(cacheKey)
-        : null;
+      const rangoState = getRangoState();
+      const wildcardKey = buildPrefetchKey(rangoState, fetchUrl);
+      const cacheKey = buildSourceKey(rangoState, previousUrl, fetchUrl);
+
+      let cachedResponse: Response | null = null;
+      let hitKey: string | null = null;
+      if (canUsePrefetch) {
+        cachedResponse = consumePrefetch(cacheKey);
+        if (cachedResponse) {
+          hitKey = cacheKey;
+        } else {
+          cachedResponse = consumePrefetch(wildcardKey);
+          if (cachedResponse) hitKey = wildcardKey;
+        }
+      }
+
+      let inflightResponsePromise: Promise<Response | null> | null = null;
+      if (canUsePrefetch && !cachedResponse) {
+        inflightResponsePromise = consumeInflightPrefetch(cacheKey);
+        if (inflightResponsePromise) {
+          hitKey = cacheKey;
+        } else {
+          inflightResponsePromise = consumeInflightPrefetch(wildcardKey);
+          if (inflightResponsePromise) hitKey = wildcardKey;
+        }
+      }
       // Track when the stream completes
       let resolveStreamComplete: () => void;
       const streamComplete = new Promise<void>((resolve) => {
@@ -197,7 +224,10 @@ export function createNavigationClient(
 
       if (cachedResponse) {
         if (tx) {
-          browserDebugLog(tx, "prefetch cache hit", { key: cacheKey });
+          browserDebugLog(tx, "prefetch cache hit", {
+            key: hitKey,
+            wildcard: hitKey === wildcardKey,
+          });
         }
         responsePromise = Promise.resolve(cachedResponse).then((response) => {
           const validated = validateRscHeaders(response, "prefetch cache");
@@ -214,8 +244,12 @@ export function createNavigationClient(
         });
       } else if (inflightResponsePromise) {
         if (tx) {
-          browserDebugLog(tx, "reusing inflight prefetch", { key: cacheKey });
+          browserDebugLog(tx, "reusing inflight prefetch", {
+            key: hitKey,
+            wildcard: hitKey === wildcardKey,
+          });
         }
+        const adoptedViaWildcard = hitKey === wildcardKey;
         responsePromise = inflightResponsePromise.then(async (response) => {
           if (!response) {
             if (tx) {
@@ -224,6 +258,23 @@ export function createNavigationClient(
             return doFreshFetch();
           }
 
+          // Cross-source safety: an inflight promise adopted via the
+          // wildcard key may turn out to be source-scoped (server emitted
+          // `X-RSC-Prefetch-Scope: source`), which means it was built for
+          // a different source page. Discard and refetch.
+          if (
+            adoptedViaWildcard &&
+            response.headers.get("x-rsc-prefetch-scope") === "source"
+          ) {
+            if (tx) {
+              browserDebugLog(
+                tx,
+                "wildcard inflight turned out source-scoped, refetching",
+              );
+            }
+            return doFreshFetch();
+          }
+
           const validated = validateRscHeaders(response, "inflight prefetch");
           if (validated instanceof Promise) return validated;
 

package/src/browser/navigation-store.ts

@@ -12,7 +12,10 @@ import type {
   ActionStateListener,
   HandleData,
 } from "./types.js";
-import { clearPrefetchCache } from "./prefetch/cache.js";
+import {
+  clearPrefetchCache,
+  clearPrefetchCacheLocal,
+} from "./prefetch/cache.js";
 
 /**
  * Default action state (idle with no payload)
@@ -335,6 +338,18 @@ export function createNavigationStore(
     clearPrefetchCache();
   }
 
+  /**
+   * Drop this tab's navigation + prefetch caches without broadcasting or
+   * rotating shared state. Used when the local session changes in a way that
+   * doesn't affect other tabs — e.g. this tab crosses into a different app
+   * via a cross-router navigation. Other tabs in the old app keep their
+   * caches and their X-Rango-State token.
+   */
+  function clearCacheInternalLocal(): void {
+    historyCache.length = 0;
+    clearPrefetchCacheLocal();
+  }
+
   /**
    * Mark all cache entries as stale (internal - does not broadcast)
    */
@@ -668,6 +683,15 @@ export function createNavigationStore(
       clearCacheAndBroadcast();
     },
 
+    /**
+     * Drop this tab's navigation + prefetch caches locally without
+     * broadcasting or rotating shared state. Intended for cross-app
+     * transitions where the session state diverges for this tab only.
+     */
+    clearHistoryCacheLocal(): void {
+      clearCacheInternalLocal();
+    },
+
     /**
      * Mark cache as stale and broadcast to other tabs
      * Called after server actions - allows SWR pattern for popstate

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
  */
@@ -41,6 +61,13 @@ export interface PartialUpdateConfig {
   ) => Promise<ReactNode> | ReactNode;
   /** RSC version getter — returns the current version (may change after HMR) */
   getVersion?: () => string | undefined;
+  /**
+   * Replace the active app-shell when a cross-app navigation is detected.
+   * Called before the full-update tree replacement renders, so the new
+   * payload's rootLayout, basename, and version are picked up. Theme,
+   * warmup, and prefetch TTL are not part of the shell — see AppShell.
+   */
+  applyAppShell?: (next: import("./app-shell.js").AppShell) => void;
 }
 
 /**
@@ -110,6 +137,7 @@ export function createPartialUpdater(
     onUpdate,
     renderSegments,
     getVersion = () => undefined,
+    applyAppShell,
   } = config;
 
   /**
@@ -167,9 +195,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}`);
@@ -188,6 +223,11 @@ export function createPartialUpdater(
       targetCache && targetCache.length > 0
         ? targetCache
         : getCurrentCachedSegments();
+    const cachedSegsSource =
+      targetCache && targetCache.length > 0 ? "history-cache" : "current-page";
+    debugLog(
+      `[Browser] cachedSegs source: ${cachedSegsSource} (${cachedSegs.length} segments: ${cachedSegs.map((s) => s.id).join(", ")})`,
+    );
 
     // Fetch partial payload (no abort signal - RSC doesn't support it well)
     let fetchResult: Awaited<ReturnType<NavigationClient["fetchPartial"]>>;
@@ -216,7 +256,12 @@ export function createPartialUpdater(
     // 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.
+    // against stale segments from the previous app, and replace the app
+    // shell (rootLayout, basename, version) so the target app's document
+    // and router config take effect instead of remaining captured from the
+    // initial load. Theme, warmup, and prefetch TTL are intentionally
+    // document-lifetime (see AppShell doc); a new document navigation
+    // applies them.
     if (payload.metadata?.routerId) {
       const prevRouterId = store.getRouterId?.();
       if (prevRouterId && prevRouterId !== payload.metadata.routerId) {
@@ -224,6 +269,12 @@ export function createPartialUpdater(
           `[Browser] App switch detected (${prevRouterId} → ${payload.metadata.routerId}), forcing full update`,
         );
         payload.metadata.isPartial = false;
+        applyAppShell?.({
+          routerId: payload.metadata.routerId,
+          rootLayout: payload.metadata.rootLayout,
+          basename: payload.metadata.basename,
+          version: payload.metadata.version,
+        });
       }
       store.setRouterId?.(payload.metadata.routerId);
     }
@@ -307,10 +358,7 @@ export function createPartialUpdater(
             scroll: toScrollPayload(commitScroll),
           };
 
-          const cachedHasTransition = existingSegments.some(
-            (s) => s.transition,
-          );
-          if (cachedHasTransition) {
+          if (shouldStartViewTransition(existingSegments)) {
             startTransition(() => {
               if (addTransitionType) {
                 addTransitionType("navigation");
@@ -496,7 +544,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") {
@@ -558,9 +606,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

@@ -2,13 +2,27 @@
  * 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.
+ * on subsequent navigation. 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.
+ * still-downloading prefetch without reparsing or buffering the body. 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.
@@ -55,19 +69,71 @@ const inflight = new Set<string>();
  */
 const inflightPromises = new Map<string, Promise<Response | 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 Response stream.
+ */
+const inflightAliases = new Map<string, string[]>();
+
 // Generation counter incremented on each clearPrefetchCache(). Fetches that
 // started before a clear carry a stale generation and must not store their
 // response (the data may be stale due to a server action invalidation).
 let generation = 0;
 
 /**
- * Build a source-dependent cache key.
- * Includes the source page href so the same target prefetched from
- * different pages gets separate entries — the server response varies
- * based on the source page context (diff-based rendering).
+ * 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"`.
+ *
+ * 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?...`.
+ *
+ * - `rangoState` is included so state rotation invalidates source-scoped
+ *   entries alongside wildcard ones.
+ * - `sourceHref` makes the key unique per originating page.
+ */
+export function buildSourceKey(
+  rangoState: string,
+  sourceHref: string,
+  targetUrl: URL,
+): string {
+  return buildPrefetchKey(rangoState + "\0" + sourceHref, targetUrl);
+}
+
+/**
+ * Walk an inflight key plus any sibling aliases registered via
+ * `setInflightPromiseWithAliases`, invoking `fn` for each.
  */
-export function buildPrefetchKey(sourceHref: string, targetUrl: URL): string {
-  return sourceHref + "\0" + targetUrl.pathname + targetUrl.search;
+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);
+  }
 }
 
 /**
@@ -110,21 +176,27 @@ export function consumePrefetch(key: string): Response | null {
  * in-flight for this key. The returned Promise resolves to the buffered
  * Response (or null if the fetch failed/was aborted).
  *
- * 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 {
   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. `inflightAliases` is
+  // intentionally preserved — `clearPrefetchInflight()` in the fetch's
+  // `.finally()` still needs it to clear every inflight flag; deleting
+  // here would strand the sibling's flag forever.
+  forEachAlias(key, (k) => inflightPromises.delete(k));
   return promise;
 }
 
@@ -183,9 +255,28 @@ export function setInflightPromise(
   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<Response | 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);
+  });
 }
 
 /**
@@ -200,7 +291,24 @@ export function clearPrefetchCache(): void {
   generation++;
   inflight.clear();
   inflightPromises.clear();
+  inflightAliases.clear();
   cache.clear();
   abortAllPrefetches();
   invalidateRangoState();
 }
+
+/**
+ * Drop all in-memory prefetch state for this tab without rotating rango-state.
+ *
+ * Use for local-only invalidations (e.g. app switch in this tab) where
+ * other tabs should NOT observe a state rotation. Unlike clearPrefetchCache,
+ * does not call invalidateRangoState, so the shared X-Rango-State token
+ * stays intact and siblings in the old app keep their prefetches.
+ */
+export function clearPrefetchCacheLocal(): void {
+  generation++;
+  inflight.clear();
+  inflightPromises.clear();
+  cache.clear();
+  abortAllPrefetches();
+}