@rangojs/router 0.0.0-experimental.c65e9248 → 0.0.0-experimental.c7e2ee4c

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
  */
@@ -39,8 +59,15 @@ export interface PartialUpdateConfig {
     segments: ResolvedSegment[],
     options?: RenderSegmentsOptions,
   ) => Promise<ReactNode> | ReactNode;
-  /** RSC version received from server (from initial payload metadata) */
-  version?: string;
+  /** 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;
 }
 
 /**
@@ -104,7 +131,14 @@ export type PartialUpdater = (
 export function createPartialUpdater(
   config: PartialUpdateConfig,
 ): PartialUpdater {
-  const { store, client, onUpdate, renderSegments, version } = config;
+  const {
+    store,
+    client,
+    onUpdate,
+    renderSegments,
+    getVersion = () => undefined,
+    applyAppShell,
+  } = config;
 
   /**
    * Get current page's cached segments as an array
@@ -161,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}`);
@@ -182,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"]>>;
@@ -193,7 +239,8 @@ export function createPartialUpdater(
       // (action redirect sends empty segments for a fresh render).
       staleRevalidation:
         mode.type === "stale-revalidation" || segments.length === 0,
-      version,
+      version: getVersion(),
+      routerId: store.getRouterId?.(),
     });
     // Mark navigation as streaming (response received, now parsing RSC).
     // Called after fetchPartial so pendingUrl stays set during the network wait,
@@ -206,6 +253,32 @@ 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, 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) {
+        debugLog(
+          `[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);
+    }
+
     // Handle server-side redirect with state
     if (payload.metadata?.redirect) {
       if (signal?.aborted) {
@@ -259,6 +332,17 @@ export function createPartialUpdater(
             existingSegments,
           );
 
+          // tx.commit() cached the source page's handleData because
+          // eventController hasn't been updated yet. Overwrite with the
+          // correct cached handleData to prevent cache corruption on
+          // subsequent navigations to this same URL.
+          if (mode.targetCacheHandleData) {
+            store.updateCacheHandleData(
+              store.getHistoryKey(),
+              mode.targetCacheHandleData,
+            );
+          }
+
           // Include cachedHandleData in metadata so NavigationProvider can restore
           // breadcrumbs and other handle data from cache.
           // Remove `handles` from metadata to prevent NavigationProvider from
@@ -274,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");
@@ -463,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") {

package/src/browser/prefetch/cache.ts

@@ -1,14 +1,28 @@
 /**
  * Prefetch Cache
  *
- * In-memory cache storing prefetch 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 prefetched Response objects for instant cache hits
+ * 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 so navigation can reuse a
- * prefetch that is still downloading rather than starting a duplicate
- * request. See consumeInflightPrefetch().
+ * 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. 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,28 +176,34 @@ 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;
 }
 
 /**
  * Store a prefetch response in the in-memory cache.
- * The response body must be fully buffered (e.g. via arrayBuffer()) before
- * storing, so the cached Response is self-contained and network-independent.
+ * The response should be a clone() of the original so the caller can
+ * still consume the body. The clone's body streams independently.
  *
  * Skips storage if the generation has changed since the fetch started
  * (a server action invalidated the cache mid-flight).
@@ -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();
+}

package/src/browser/prefetch/fetch.ts

@@ -13,9 +13,10 @@
 
 import {
   buildPrefetchKey,
+  buildSourceKey,
   hasPrefetch,
   markPrefetchInflight,
-  setInflightPromise,
+  setInflightPromiseWithAliases,
   storePrefetch,
   clearPrefetchInflight,
   currentGeneration,
@@ -23,6 +24,24 @@ import {
 import { getRangoState } from "../rango-state.js";
 import { enqueuePrefetch } from "./queue.js";
 import { shouldPrefetch } from "./policy.js";
+import { debugLog } from "../logging.js";
+
+/**
+ * Check if a URL resolves to the current page (same pathname + search).
+ * Used to prevent same-page prefetching, which produces a trivial diff
+ * that would corrupt the (default wildcard) prefetch cache entry.
+ */
+function isSamePage(url: string): boolean {
+  try {
+    const target = new URL(url, window.location.origin);
+    return (
+      target.pathname + target.search ===
+      window.location.pathname + window.location.search
+    );
+  } catch {
+    return false;
+  }
+}
 
 /**
  * Build an RSC partial URL for prefetching.
@@ -34,6 +53,7 @@ function buildPrefetchUrl(
   url: string,
   segmentIds: string[],
   version?: string,
+  routerId?: string,
 ): URL | null {
   let targetUrl: URL;
   try {
@@ -51,22 +71,44 @@ function buildPrefetchUrl(
   if (version) {
     targetUrl.searchParams.set("_rsc_v", version);
   }
+  if (routerId) {
+    targetUrl.searchParams.set("_rsc_rid", routerId);
+  }
   return targetUrl;
 }
 
 /**
- * Core prefetch fetch logic. Fetches the response, fully buffers the body,
- * and stores it in the in-memory cache. The returned Promise resolves to
- * the buffered Response (or null on failure) so navigation can reuse
- * in-flight prefetches via consumeInflightPrefetch().
+ * Core prefetch fetch logic. Fetches the response, tees the body, and stores
+ * one branch in the in-memory cache. The returned Promise resolves to the
+ * sibling navigation branch (or null on failure) so navigation can safely
+ * reuse an in-flight prefetch via consumeInflightPrefetch().
+ *
+ * Inflight + storage key selection:
+ *
+ * - `forceSourceScope` (Link opted in with `prefetchKey=":source"`): single
+ *   inflight registration under `sourceKey`; response stored under
+ *   `sourceKey`. No wildcard leak is possible.
+ *
+ * - Otherwise: dual inflight registration under both `wildcardKey` and
+ *   `sourceKey` so same-source navigations adopt directly via their own
+ *   source key. Storage key is chosen at response time from the
+ *   `X-RSC-Prefetch-Scope` header — `"source"` → `sourceKey` (intercept
+ *   modals etc.), anything else → `wildcardKey`. Cross-source navigations
+ *   that adopted via `wildcardKey` must bail out in `navigation-client.ts`
+ *   if the adopted response turns out to be source-scoped.
  */
 function executePrefetchFetch(
-  key: string,
+  wildcardKey: string,
+  sourceKey: string,
   fetchUrl: string,
+  forceSourceScope: boolean,
   signal?: AbortSignal,
 ): Promise<Response | null> {
   const gen = currentGeneration();
-  markPrefetchInflight(key);
+  const inflightKeys = forceSourceScope
+    ? [sourceKey]
+    : [wildcardKey, sourceKey];
+  for (const k of inflightKeys) markPrefetchInflight(k);
 
   const promise: Promise<Response | null> = fetch(fetchUrl, {
     priority: "low" as RequestPriority,
@@ -77,69 +119,164 @@ function executePrefetchFetch(
       "X-Rango-Prefetch": "1",
     },
   })
-    .then(async (response) => {
+    .then((response) => {
       if (!response.ok) return null;
-      // Fully buffer the response body so the cached Response is
-      // self-contained and doesn't depend on the network connection.
-      // This eliminates the race condition where the user clicks before
-      // the response body has been fully downloaded.
-      const buffer = await response.arrayBuffer();
-      const cachedResponse = new Response(buffer, {
+      // Don't buffer with arrayBuffer() — that blocks until the entire
+      // body downloads, defeating streaming for slow loaders.
+      // Tee the body: one branch for navigation, one for cache storage.
+      const [navStream, cacheStream] = response.body!.tee();
+      const responseInit = {
         headers: response.headers,
         status: response.status,
         statusText: response.statusText,
-      });
-      storePrefetch(key, cachedResponse.clone(), gen);
-      return cachedResponse;
+      };
+      let storageKey: string;
+      if (forceSourceScope) {
+        storageKey = sourceKey;
+      } else {
+        const scope = response.headers.get("x-rsc-prefetch-scope");
+        storageKey = scope === "source" ? sourceKey : wildcardKey;
+      }
+      storePrefetch(storageKey, new Response(cacheStream, responseInit), gen);
+      return new Response(navStream, responseInit);
     })
     .catch(() => null)
     .finally(() => {
-      clearPrefetchInflight(key);
+      clearPrefetchInflight(inflightKeys[0]!);
     });
 
-  setInflightPromise(key, promise);
+  setInflightPromiseWithAliases(inflightKeys, promise);
   return promise;
 }
 
+/**
+ * Dedup check for prefetch entry presence.
+ *
+ * Forced `:source` must NOT dedupe against a pre-existing wildcard entry —
+ * otherwise the source slot would stay unpopulated and navigation from
+ * this source would fall through to the (potentially wrong) wildcard
+ * response, defeating the opt-out.
+ */
+function hasPrefetchHit(
+  forceSourceScope: boolean,
+  wildcardKey: string,
+  sourceKey: string,
+): boolean {
+  return forceSourceScope
+    ? hasPrefetch(sourceKey)
+    : hasPrefetch(wildcardKey) || hasPrefetch(sourceKey);
+}
+
 /**
  * Prefetch (direct): fetch with low priority and store in in-memory cache.
  * Used by hover strategy -- fires immediately without queueing.
+ *
+ * By default the wildcard key (Rango-state-keyed) is used for inflight
+ * dedup and for responses that are not source-sensitive; source-scoped
+ * storage is automatic when the server emits `X-RSC-Prefetch-Scope: source`.
+ *
+ * Pass `prefetchKey=":source"` to force source-scoped inflight + storage
+ * (e.g. when the target uses a custom `revalidate()` that reads
+ * `currentUrl` and the wildcard slot would serve the wrong diff).
  */
 export function prefetchDirect(
   url: string,
   segmentIds: string[],
   version?: string,
+  routerId?: string,
+  prefetchKey?: ":source",
 ): void {
   if (!shouldPrefetch()) return;
 
-  const targetUrl = buildPrefetchUrl(url, segmentIds, version);
+  const targetUrl = buildPrefetchUrl(url, segmentIds, version, routerId);
   if (!targetUrl) return;
-  const key = buildPrefetchKey(window.location.href, targetUrl);
-  if (hasPrefetch(key)) return;
-  executePrefetchFetch(key, targetUrl.toString());
+  const forceSourceScope = prefetchKey === ":source";
+  // Skip same-page prefetch — a same-page diff is trivial and would corrupt
+  // the wildcard cache entry used for cross-page navigation.
+  // When `:source` is forced the entry is source-scoped (single-aliased to
+  // itself), so it cannot poison any shared slot — allow it.
+  if (!forceSourceScope && isSamePage(url)) {
+    return;
+  }
+  const sourceHref = window.location.href;
+  const rangoState = getRangoState();
+  const wildcardKey = buildPrefetchKey(rangoState, targetUrl);
+  const sourceKey = buildSourceKey(rangoState, sourceHref, targetUrl);
+  if (hasPrefetchHit(forceSourceScope, wildcardKey, sourceKey)) {
+    debugLog("[prefetch] direct dedup (key already exists)", {
+      url,
+      wildcardKey,
+      sourceKey,
+      forceSourceScope,
+    });
+    return;
+  }
+  debugLog("[prefetch] direct fetch", {
+    url,
+    wildcardKey,
+    sourceKey,
+    source: sourceHref,
+    forceSourceScope,
+  });
+  executePrefetchFetch(
+    wildcardKey,
+    sourceKey,
+    targetUrl.toString(),
+    forceSourceScope,
+  );
 }
 
 /**
  * Prefetch (queued): goes through the concurrency-limited queue.
  * Used by viewport/render strategies to avoid flooding the server.
- * Returns the cache key for use in cleanup.
+ * Returns the inflight key (wildcard by default, source-scoped when
+ * `prefetchKey=":source"` is passed).
  */
 export function prefetchQueued(
   url: string,
   segmentIds: string[],
   version?: string,
+  routerId?: string,
+  prefetchKey?: ":source",
 ): string {
   if (!shouldPrefetch()) return "";
-  const targetUrl = buildPrefetchUrl(url, segmentIds, version);
+  const targetUrl = buildPrefetchUrl(url, segmentIds, version, routerId);
   if (!targetUrl) return "";
-  const key = buildPrefetchKey(window.location.href, targetUrl);
-  if (hasPrefetch(key)) return key;
+  const forceSourceScope = prefetchKey === ":source";
+  if (!forceSourceScope && isSamePage(url)) {
+    return "";
+  }
+  const sourceHref = window.location.href;
+  const rangoState = getRangoState();
+  const wildcardKey = buildPrefetchKey(rangoState, targetUrl);
+  const sourceKey = buildSourceKey(rangoState, sourceHref, targetUrl);
+  const queueKey = forceSourceScope ? sourceKey : wildcardKey;
+  if (hasPrefetchHit(forceSourceScope, wildcardKey, sourceKey)) {
+    debugLog("[prefetch] queued dedup (key already exists)", {
+      url,
+      wildcardKey,
+      sourceKey,
+      forceSourceScope,
+    });
+    return queueKey;
+  }
   const fetchUrlStr = targetUrl.toString();
-  enqueuePrefetch(key, (signal) => {
+  enqueuePrefetch(queueKey, (signal) => {
     // Re-check at execution time: a hover-triggered prefetchDirect may
     // have started or completed this key while the item sat in the queue.
-    if (hasPrefetch(key)) return Promise.resolve();
-    return executePrefetchFetch(key, fetchUrlStr, signal).then(() => {});
+    if (hasPrefetchHit(forceSourceScope, wildcardKey, sourceKey)) {
+      return Promise.resolve();
+    }
+    if (!forceSourceScope && isSamePage(url)) {
+      return Promise.resolve();
+    }
+    return executePrefetchFetch(
+      wildcardKey,
+      sourceKey,
+      fetchUrlStr,
+      forceSourceScope,
+      signal,
+    ).then(() => {});
   });
-  return key;
+  return queueKey;
 }