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

package/src/browser/prefetch/fetch.ts

@@ -3,32 +3,60 @@
  *
  * Fetch-based prefetch logic used by Link (hover/viewport/render strategies)
  * and useRouter().prefetch(). Sends the same headers and segment IDs as a
- * real navigation so the server returns a proper diff. The Response is fully
- * buffered and stored in an in-memory cache for instant consumption on
- * subsequent navigation.
+ * real navigation so the server returns a proper diff. The response is fetched
+ * AND eagerly decoded (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 stored in an
+ * in-memory cache and reused verbatim by navigation, so a prefetched click
+ * loads no new code.
  *
  * In-flight promises are tracked in the cache so that navigation can reuse
- * a prefetch that is still downloading instead of starting a duplicate request.
+ * a prefetch that is still downloading/decoding instead of starting a
+ * duplicate request.
  */
 
 import {
   buildPrefetchKey,
+  buildSourceKey,
   hasPrefetch,
   markPrefetchInflight,
-  setInflightPromise,
+  setInflightPromiseWithAliases,
   storePrefetch,
   clearPrefetchInflight,
   currentGeneration,
+  type DecodedPrefetch,
 } from "./cache.js";
 import { getRangoState } from "../rango-state.js";
 import { enqueuePrefetch } from "./queue.js";
 import { shouldPrefetch } from "./policy.js";
 import { debugLog } from "../logging.js";
+import { teeWithCompletion, isForeignRouterId } from "../response-adapter.js";
+import type { RscPayload } from "../types.js";
+
+/**
+ * Decoder injected at app startup (see setPrefetchDecoder). This is
+ * `deps.createFromFetch` — decoupled from the RSC runtime exactly like the
+ * navigation client. Prefetch decodes through it so the route's client chunks
+ * are pulled during the prefetch, not on click.
+ */
+type PrefetchDecoder = (response: Promise<Response>) => Promise<RscPayload>;
+
+let decoder: PrefetchDecoder | null = null;
+
+/**
+ * Wire the RSC decoder used to eagerly decode prefetched responses. Called
+ * once from initBrowserApp with the same createFromFetch the navigation client
+ * uses. Until set, prefetch warming is inert (prefetches are skipped) — the
+ * browser app always sets it before any Link can fire.
+ */
+export function setPrefetchDecoder(fn: PrefetchDecoder): void {
+  decoder = fn;
+}
 
 /**
  * Check if a URL resolves to the current page (same pathname + search).
- * Used to prevent same-page prefetching with prefetchKey, which would
- * produce a trivial diff that corrupts the wildcard cache.
+ * 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 {
@@ -77,20 +105,50 @@ function buildPrefetchUrl(
 }
 
 /**
- * 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().
+ * Core prefetch fetch logic. Fetches the response, eagerly decodes it, and
+ * stores the decoded payload in the in-memory cache. The returned Promise
+ * resolves to the decoded entry (or null on failure / control header) so
+ * navigation can safely reuse an in-flight prefetch via
+ * consumeInflightPrefetch().
+ *
+ * Eager decode is the warming step: createFromFetch parses the Flight stream,
+ * which resolves the route's client references and imports its JS chunks. The
+ * stored payload is reused as-is by navigation, so the click loads no new code.
+ *
+ * Control headers are NOT acted on here. A speculative prefetch must never
+ * reload the page or throw a redirect — if the response carries X-RSC-Reload
+ * or X-RSC-Redirect, we drop it (resolve null) and let the real navigation
+ * re-fetch and honor it.
+ *
+ * Inflight + storage key selection:
+ *
+ * - `forceSourceScope` (Link opted in with `prefetchKey=":source"`): single
+ *   inflight registration under `sourceKey`; entry 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`. The entry records its scope
+ *   so cross-source navigations that adopted via `wildcardKey` can bail out
+ *   in `navigation-client.ts` when the adopted entry turns out source-scoped.
  */
 function executePrefetchFetch(
-  key: string,
+  wildcardKey: string,
+  sourceKey: string,
   fetchUrl: string,
+  forceSourceScope: boolean,
+  expectedRouterId?: string,
   signal?: AbortSignal,
-): Promise<Response | null> {
+): Promise<DecodedPrefetch | 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, {
+  const promise: Promise<DecodedPrefetch | null> = fetch(fetchUrl, {
     priority: "low" as RequestPriority,
     signal,
     headers: {
@@ -100,107 +158,193 @@ function executePrefetchFetch(
     },
   })
     .then((response) => {
-      if (!response.ok) return null;
-      // 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, new Response(cacheStream, responseInit), gen);
-      return new Response(navStream, responseInit);
+      if (!response.ok || !decoder) return null;
+      // Control headers mean this response is stale (reload) or redirecting.
+      // Don't warm it — drop so navigation re-fetches and acts on the header.
+      if (
+        response.headers.has("X-RSC-Reload") ||
+        response.headers.has("X-RSC-Redirect")
+      ) {
+        return null;
+      }
+      // Integrity check: never warm (or decode/import the chunks of) a foreign
+      // app's payload. A speculative prefetch must never reload — just drop it;
+      // navigation re-fetches and the server steers it.
+      if (isForeignRouterId(response, expectedRouterId)) {
+        return null;
+      }
+
+      const scope: "source" | "wildcard" =
+        forceSourceScope ||
+        response.headers.get("x-rsc-prefetch-scope") === "source"
+          ? "source"
+          : "wildcard";
+      const storageKey = scope === "source" ? sourceKey : wildcardKey;
+
+      // Track stream completion off a tee so navigation's scroll/revalidation
+      // gating matches the fresh-fetch path; decode the other branch.
+      let resolveStreamComplete!: () => void;
+      const streamComplete = new Promise<void>((resolve) => {
+        resolveStreamComplete = resolve;
+      });
+      const tracked = teeWithCompletion(
+        response,
+        () => resolveStreamComplete(),
+        signal,
+        // Speculative prefetch: a never-consumed/aborted stream error is benign.
+        true,
+      );
+
+      // Eager decode: parsing the Flight stream imports the route's client
+      // chunks now, not on click.
+      const payload = decoder(Promise.resolve(tracked));
+      // Mark handled so an unconsumed prefetch decode error stays quiet; the
+      // error is still surfaced to navigation if it consumes the entry.
+      payload.catch(() => {});
+
+      const entry: DecodedPrefetch = { payload, streamComplete, scope };
+      storePrefetch(storageKey, entry, gen);
+      return entry;
     })
     .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?: string | ((from: string) => string),
+  prefetchKey?: ":source",
 ): void {
   if (!shouldPrefetch()) return;
 
   const targetUrl = buildPrefetchUrl(url, segmentIds, version, routerId);
   if (!targetUrl) return;
-  // Skip same-page prefetch with prefetchKey — a same-page diff is trivial
-  // and would corrupt the wildcard cache entry for cross-page navigation.
-  if (prefetchKey != null && isSamePage(url)) {
+  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 key = buildPrefetchKey(window.location.href, targetUrl, prefetchKey);
-  if (hasPrefetch(key)) {
+  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,
-      key,
-      prefetchKey: prefetchKey != null ? String(prefetchKey) : undefined,
+      wildcardKey,
+      sourceKey,
+      forceSourceScope,
     });
     return;
   }
   debugLog("[prefetch] direct fetch", {
     url,
-    key,
-    source: window.location.href,
-    prefetchKey: prefetchKey != null ? String(prefetchKey) : undefined,
+    wildcardKey,
+    sourceKey,
+    source: sourceHref,
+    forceSourceScope,
   });
-  executePrefetchFetch(key, targetUrl.toString());
+  executePrefetchFetch(
+    wildcardKey,
+    sourceKey,
+    targetUrl.toString(),
+    forceSourceScope,
+    routerId,
+  );
 }
 
 /**
  * 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?: string | ((from: string) => string),
+  prefetchKey?: ":source",
 ): string {
   if (!shouldPrefetch()) return "";
   const targetUrl = buildPrefetchUrl(url, segmentIds, version, routerId);
   if (!targetUrl) return "";
-  // Skip same-page prefetch with prefetchKey — a same-page diff is trivial
-  // and would corrupt the wildcard cache entry for cross-page navigation.
-  if (prefetchKey != null && isSamePage(url)) {
+  const forceSourceScope = prefetchKey === ":source";
+  if (!forceSourceScope && isSamePage(url)) {
     return "";
   }
-  const key = buildPrefetchKey(window.location.href, targetUrl, prefetchKey);
-  if (hasPrefetch(key)) {
+  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,
-      key,
-      prefetchKey: prefetchKey != null ? String(prefetchKey) : undefined,
+      wildcardKey,
+      sourceKey,
+      forceSourceScope,
     });
-    return key;
+    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();
-    // By execution time, the user may have navigated to the target page.
-    // A same-page prefetch produces a trivial diff that would overwrite
-    // the useful cross-page entry in the wildcard cache.
-    if (prefetchKey != null && isSamePage(url)) {
+    if (hasPrefetchHit(forceSourceScope, wildcardKey, sourceKey)) {
+      return Promise.resolve();
+    }
+    if (!forceSourceScope && isSamePage(url)) {
       return Promise.resolve();
     }
-    return executePrefetchFetch(key, fetchUrlStr, signal).then(() => {});
+    return executePrefetchFetch(
+      wildcardKey,
+      sourceKey,
+      fetchUrlStr,
+      forceSourceScope,
+      routerId,
+      signal,
+    ).then(() => {});
   });
-  return key;
+  return queueKey;
 }

package/src/browser/prefetch/queue.ts

@@ -108,10 +108,29 @@ export function enqueuePrefetch(
   scheduleDrain();
 }
 
+/**
+ * Normalize a URL-like string for keep-alive matching: parse against a
+ * placeholder origin and strip internal `_rsc_*` query params. Returns
+ * `pathname + search` so comparisons ignore hash and the internal params
+ * that prefetch appends to targets (`_rsc_partial`, `_rsc_segments`,
+ * `_rsc_v`, `_rsc_rid`, `_rsc_stale`).
+ */
+function normalizeForMatch(urlish: string): string {
+  try {
+    const u = new URL(urlish, "http://placeholder");
+    for (const k of [...u.searchParams.keys()]) {
+      if (k.startsWith("_rsc_")) u.searchParams.delete(k);
+    }
+    return u.pathname + u.search;
+  } catch {
+    return urlish;
+  }
+}
+
 /**
  * Cancel queued prefetches and abort in-flight ones that don't match
  * the current navigation target. If `keepUrl` is provided, the
- * executing prefetch whose key contains that URL is kept alive so
+ * executing prefetch whose key targets that URL is kept alive so
  * navigation can reuse its response via consumeInflightPrefetch.
  *
  * Called when a navigation starts via the NavigationProvider's
@@ -124,11 +143,23 @@ export function cancelAllPrefetches(keepUrl?: string | null): void {
   drainGeneration++;
 
   // Abort in-flight prefetches that aren't for the navigation target.
-  // Keys use format "sourceHref\0targetPathname+search" — match the
-  // target portion (after \0) against keepUrl.
+  // Key shapes (see prefetch/cache.ts buildPrefetchKey):
+  //   wildcard:      "rangoState\0/target?..."
+  //   source-scoped: "rangoState\0sourceHref\0/target?..."
+  // The target portion is always the final \0-delimited segment and
+  // includes internal `_rsc_*` params (from buildPrefetchUrl); keepUrl
+  // comes from NavigationProvider's pendingUrl which is the bare
+  // navigation target. Normalize both sides before comparing.
+  const normalizedKeep = keepUrl ? normalizeForMatch(keepUrl) : null;
   for (const [key, ac] of abortControllers) {
-    const target = key.split("\0")[1];
-    if (keepUrl && target && keepUrl.startsWith(target)) continue;
+    const lastNul = key.lastIndexOf("\0");
+    const target = lastNul >= 0 ? key.substring(lastNul + 1) : "";
+    if (
+      normalizedKeep &&
+      target &&
+      normalizeForMatch(target) === normalizedKeep
+    )
+      continue;
     ac.abort();
     abortControllers.delete(key);
     if (executing.delete(key)) {

package/src/browser/rango-state.ts

@@ -6,21 +6,36 @@
  * navigation requests. The server responds with `Vary: X-Rango-State`,
  * so the browser HTTP cache keys responses by (URL, X-Rango-State value).
  *
- * Format: `{buildVersion}:{invalidationTimestamp}`
+ * Value format: `{buildVersion}:{invalidationTimestamp}`
  * - Build version changes on deploy, busting all cached prefetches.
  * - Timestamp changes on server action invalidation.
  *
- * localStorage is cross-tab and survives page refresh, so:
- * - One tab's prefetch warms the cache for all tabs.
- * - Invalidation in one tab is picked up by other tabs on next fetch.
+ * Storage key is namespaced per routerId (`rango-state:{routerId}`) so
+ * tabs in different apps on the same origin do not collide. Two tabs in
+ * the same app share a key → one tab's invalidation is picked up by the
+ * other via the `storage` event. The key is bound once at document init; a
+ * cross-app navigation is a full document load (X-RSC-Reload), so the target
+ * app's document binds its own key on load (tabs in the old app keep theirs).
+ *
+ * If no routerId is supplied, falls back to a single legacy key for
+ * backward compatibility (single-app deployments unaffected).
  */
 
-const STORAGE_KEY = "rango-state";
+const LEGACY_STORAGE_KEY = "rango-state";
+
+function buildStorageKey(routerId: string | undefined): string {
+  return routerId ? `${LEGACY_STORAGE_KEY}:${routerId}` : LEGACY_STORAGE_KEY;
+}
 
 // Module-level cache avoids hitting localStorage on every getRangoState() call.
 // Initialized from localStorage on first access or by initRangoState().
 let cachedState: string | null = null;
 
+// The localStorage key this tab is currently bound to. Bound on
+// initRangoState (document boot). The storage listener filters cross-tab
+// events by this key so events from tabs in a different app are ignored.
+let currentStorageKey: string = LEGACY_STORAGE_KEY;
+
 // Cross-tab sync: the `storage` event fires in OTHER tabs when one tab writes
 // to localStorage, keeping cachedState fresh without polling.
 let storageListenerAttached = false;
@@ -28,7 +43,10 @@ let storageListenerAttached = false;
 function attachStorageListener(): void {
   if (storageListenerAttached || typeof window === "undefined") return;
   window.addEventListener("storage", (e) => {
-    if (e.key !== STORAGE_KEY) return;
+    // Only react to events for this tab's current app namespace. Events
+    // under other routerId-scoped keys belong to other apps and must not
+    // clobber this tab's state.
+    if (e.key !== currentStorageKey) return;
     cachedState = e.newValue;
   });
   storageListenerAttached = true;
@@ -37,16 +55,22 @@ function attachStorageListener(): void {
 /**
  * Initialize the Rango state key in localStorage.
  * Called once at app startup with the build version from the server.
- * If localStorage already has a key with matching version prefix, keeps it
- * (preserves invalidation state across refresh). Otherwise writes a new key.
+ * The routerId scopes the storage key to this app; in multi-app setups
+ * each app owns its own `rango-state:{routerId}` key and cannot observe
+ * invalidations from sibling apps on the same origin.
+ *
+ * If localStorage already has a matching-version entry under the key,
+ * keeps it (preserves invalidation state across refresh). Otherwise
+ * writes a new value.
  */
-export function initRangoState(version: string): void {
+export function initRangoState(version: string, routerId?: string): void {
+  currentStorageKey = buildStorageKey(routerId);
   if (typeof window === "undefined") return;
 
   attachStorageListener();
 
   try {
-    const existing = localStorage.getItem(STORAGE_KEY);
+    const existing = localStorage.getItem(currentStorageKey);
     if (existing) {
       const colonIdx = existing.indexOf(":");
       if (colonIdx > 0) {
@@ -59,7 +83,7 @@ export function initRangoState(version: string): void {
     }
     // New version or first load
     const newState = `${version}:${Date.now()}`;
-    localStorage.setItem(STORAGE_KEY, newState);
+    localStorage.setItem(currentStorageKey, newState);
     cachedState = newState;
   } catch {
     // localStorage may be unavailable (private browsing in some browsers)
@@ -77,7 +101,7 @@ export function getRangoState(): string {
   if (typeof window === "undefined") return "0:0";
 
   try {
-    const stored = localStorage.getItem(STORAGE_KEY);
+    const stored = localStorage.getItem(currentStorageKey);
     if (stored) {
       cachedState = stored;
       return stored;
@@ -105,7 +129,7 @@ export function invalidateRangoState(): void {
   if (typeof window === "undefined") return;
 
   try {
-    localStorage.setItem(STORAGE_KEY, newState);
+    localStorage.setItem(currentStorageKey, newState);
   } catch {
     // Silently handle localStorage errors
   }

package/src/browser/react/Link.tsx

@@ -98,25 +98,30 @@ export interface LinkProps extends Omit<
    */
   prefetch?: PrefetchStrategy;
   /**
-   * Custom prefetch cache key for source-agnostic cache reuse.
-   * When set, prefetch responses are cached independently of the current
-   * page URL, so navigating to the same target from different source pages
-   * reuses the cached prefetch.
+   * Opt-in override for the prefetch cache scope.
    *
-   * - String: static group name (e.g., `"pages"`)
-   * - Function: receives current URL (`window.location.href`), returns a
-   *   normalized source key
+   * The default cache is source-agnostic: one shared entry per target,
+   * keyed on Rango state + target URL. This is correct for routes whose
+   * response shape doesn't depend on where the user navigates from.
+   *
+   * Set `":source"` when this Link's response would legitimately differ
+   * based on the source page — typically when the target route (or one
+   * of its layouts) uses a custom `revalidate()` handler that reads
+   * `currentUrl` / `currentParams`, and the wildcard entry would
+   * therefore serve the wrong diff to a navigation from a different
+   * source.
+   *
+   * Intercept responses are auto-scoped to the source via a server-side
+   * tag, so `":source"` is only needed for custom revalidation logic.
    *
    * @example
    * ```tsx
-   * // Static group — all "pages" links share one cache entry per target
-   * <Link to="/page/3" prefetch="hover" prefetchKey="pages" />
-   *
-   * // Normalize — strip trailing page number from source URL
-   * <Link to="/page/3" prefetch="hover" prefetchKey={(from) => from.replace(/\/\d+$/, '')} />
+   * // Route uses a `revalidate()` that branches on currentUrl — opt in
+   * // so prefetches don't bleed across source pages.
+   * <Link to="/dashboard" prefetch="hover" prefetchKey=":source" />
    * ```
    */
-  prefetchKey?: string | ((from: string) => string);
+  prefetchKey?: ":source";
   /**
    * State to pass to history.pushState/replaceState.
    * Accessible via useLocationState() hook.