@rangojs/router 0.0.0-experimental.2a0dea97 → 0.0.0-experimental.2c0cb8a1

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 {
@@ -496,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) {
@@ -623,6 +675,55 @@ export function createNavigationBridge(
         this.handlePopstate();
       };
 
+      // React's experimental ViewTransition integration deliberately skips
+      // animations for commits originating from a popstate event handler —
+      // popstate must finish synchronously to preserve scroll/form
+      // restoration, which conflicts with running a transition. The
+      // Navigation API's `navigate` event runs in an async-safe context
+      // (`event.intercept({ handler })` lets us await), so commits made
+      // inside the intercept handler are NOT popstate-originated from
+      // React's perspective and the VT walker fires normally for
+      // back-/forward-navigations. Falls back to popstate on browsers
+      // without Navigation API support (Firefox today); on those browsers
+      // back-nav view transitions won't fire — matching the React
+      // limitation and current behavior.
+      // See https://react.dev/reference/react/ViewTransition.
+      const navigationApi: any = (window as any).navigation;
+      const supportsNavigationApi =
+        !!navigationApi && typeof navigationApi.addEventListener === "function";
+
+      const handleNavigateEvent = (event: any): void => {
+        // Only handle browser history traversal (back/forward).
+        // Push/replace are still driven by setupLinkInterception →
+        // this.navigate(...) (which calls history.pushState/replaceState).
+        if (event.navigationType !== "traverse") return;
+        if (!event.canIntercept) return;
+        // canIntercept doesn't exclude every cross-document case (e.g., back
+        // to a previous same-origin non-Rango document, or a doc-level
+        // history.go() target). Without this guard, event.intercept() would
+        // forcibly turn that into a same-document navigation and route it
+        // through handlePopstate — silently breaking the destination page.
+        if (!event.destination?.sameDocument) return;
+        if (event.hashChange || event.downloadRequest) return;
+        // Known limitation: Chromium's Navigation API replaces the entry's
+        // history.state with `null` when an intercepted traverse commits,
+        // which clobbers the scroll-restoration `key` that rango stamps
+        // onto each history entry. Attempts to write the state back from
+        // the handler, finally, or event.finished all run after React's
+        // commit-phase useLayoutEffect has already read history.state, so
+        // none of them help. Consumers who rely on per-entry scroll
+        // restoration should use a URL-based scroll key today
+        // (useScrollRestoration({ getKey: ({ pathname }) => pathname }) or
+        // similar). Tracked as follow-up to switch scroll-restoration to
+        // navigation.currentEntry.id (or rango-store-backed keys) so it
+        // survives the intercept commit.
+        event.intercept({
+          handler: async () => {
+            await this.handlePopstate();
+          },
+        });
+      };
+
       // When the browser restores a page from bfcache (back-forward cache),
       // any in-flight navigation state is stale. This happens when:
       // 1. A navigation triggers X-RSC-Reload (e.g., response route hit via SPA)
@@ -648,13 +749,22 @@ export function createNavigationBridge(
         this.refresh();
       });
 
-      window.addEventListener("popstate", handlePopstate);
+      if (supportsNavigationApi) {
+        navigationApi.addEventListener("navigate", handleNavigateEvent);
+        debugLog("[Browser] Navigation bridge ready (Navigation API)");
+      } else {
+        window.addEventListener("popstate", handlePopstate);
+        debugLog("[Browser] Navigation bridge ready (popstate fallback)");
+      }
       window.addEventListener("pageshow", handlePageShow);
-      debugLog("[Browser] Navigation bridge ready");
 
       return () => {
         cleanupLinks();
-        window.removeEventListener("popstate", handlePopstate);
+        if (supportsNavigationApi) {
+          navigationApi.removeEventListener("navigate", handleNavigateEvent);
+        } else {
+          window.removeEventListener("popstate", handlePopstate);
+        }
         window.removeEventListener("pageshow", handlePageShow);
       };
     },
@@ -664,6 +774,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,17 +96,19 @@ 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);
-      // Wildcard key matches prefetch entries stored with a custom prefetchKey
-      // (Link's prefetchKey prop stores under "*" instead of the source URL).
-      const wildcardKey = "*\0" + fetchUrl.pathname + fetchUrl.search;
+      const rangoState = getRangoState();
+      const wildcardKey = buildPrefetchKey(rangoState, fetchUrl);
+      const cacheKey = buildSourceKey(rangoState, previousUrl, fetchUrl);
 
       let cachedResponse: Response | null = null;
       let hitKey: string | null = null;
@@ -244,6 +249,7 @@ export function createNavigationClient(
             wildcard: hitKey === wildcardKey,
           });
         }
+        const adoptedViaWildcard = hitKey === wildcardKey;
         responsePromise = inflightResponsePromise.then(async (response) => {
           if (!response) {
             if (tx) {
@@ -252,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;
 
   /**
@@ -228,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) {
@@ -236,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);
     }
@@ -319,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");
@@ -508,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") {
@@ -570,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,29 +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 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);
+  }
 }
 
 /**
@@ -120,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;
 }
 
@@ -193,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);
+  });
 }
 
 /**
@@ -210,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();
+}