@rangojs/router 0.0.0-experimental.19 → 0.0.0-experimental.1fa245e2

package/src/browser/prefetch/cache.ts

@@ -1,67 +1,206 @@
 /**
- * Prefetch Tracking
+ * Prefetch Cache
  *
- * Tracks in-flight and completed prefetches for deduplication.
- * The actual response caching is handled by the browser's HTTP cache
- * via Vary: X-Rango-State.
+ * 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.
+ *
+ * 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.
+ *
+ * Replaces the previous browser HTTP cache approach which was unreliable
+ * due to response draining race conditions and browser inconsistencies.
  */
 
-import { cancelAllPrefetches } from "./queue.js";
+import { abortAllPrefetches } from "./queue.js";
 import { invalidateRangoState } from "../rango-state.js";
 
+// Default TTL: 5 minutes. Overridden by initPrefetchCache() with
+// the server-configured prefetchCacheTTL from router options.
+// 0 disables the in-memory cache entirely.
+let cacheTTL = 300_000;
+
+/**
+ * Initialize the prefetch cache with the configured TTL.
+ * Called once at app startup with the value from server metadata.
+ * A TTL of 0 disables the in-memory cache and all prefetching.
+ */
+export function initPrefetchCache(ttlMs: number): void {
+  cacheTTL = ttlMs;
+}
+
+/**
+ * Check if the prefetch cache is disabled (TTL <= 0).
+ * When disabled, no prefetch requests should be issued.
+ */
+export function isPrefetchCacheDisabled(): boolean {
+  return cacheTTL <= 0;
+}
+const MAX_PREFETCH_CACHE_SIZE = 50;
+
+interface PrefetchCacheEntry {
+  response: Response;
+  timestamp: number;
+}
+
+const cache = new Map<string, PrefetchCacheEntry>();
 const inflight = new Set<string>();
-const prefetched = new Set<string>();
+
+/**
+ * In-flight promise map. When a prefetch fetch is in progress, its
+ * Promise<Response | null> is stored here so navigation can await
+ * it instead of starting a duplicate request.
+ */
+const inflightPromises = new Map<string, Promise<Response | null>>();
 
 // Generation counter incremented on each clearPrefetchCache(). Fetches that
-// started before a clear carry a stale generation and must not re-add their
-// key to the prefetched set (the browser HTTP cache entry is already invalid
-// due to Rango-State rotation).
+// 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;
 
 /**
- * Check if a prefetch is already in-flight or completed for the given key.
+ * 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).
+ */
+export function buildPrefetchKey(sourceHref: string, targetUrl: URL): string {
+  return sourceHref + "\0" + targetUrl.pathname + targetUrl.search;
+}
+
+/**
+ * Check if a prefetch is already cached, in-flight, or queued for the given key.
  */
 export function hasPrefetch(key: string): boolean {
-  return prefetched.has(key) || inflight.has(key);
+  if (inflight.has(key)) return true;
+  if (cacheTTL <= 0) return false;
+  const entry = cache.get(key);
+  if (!entry) return false;
+  if (Date.now() - entry.timestamp > cacheTTL) {
+    cache.delete(key);
+    return false;
+  }
+  return true;
 }
 
 /**
- * Capture the current generation. The returned value is passed to
- * markPrefetched so it can detect stale completions.
+ * Consume a cached prefetch response. Returns null if not found or expired.
+ * One-time consumption: the entry is deleted after retrieval.
+ * Returns null when caching is disabled (TTL <= 0).
+ *
+ * Does NOT check in-flight prefetches — use consumeInflightPrefetch()
+ * for that (returns a Promise instead of a Response).
  */
-export function currentGeneration(): number {
-  return generation;
+export function consumePrefetch(key: string): Response | null {
+  if (cacheTTL <= 0) return null;
+  const entry = cache.get(key);
+  if (!entry) return null;
+  if (Date.now() - entry.timestamp > cacheTTL) {
+    cache.delete(key);
+    return null;
+  }
+  cache.delete(key);
+  return entry.response;
+}
+
+/**
+ * Consume an in-flight prefetch promise. Returns null if no prefetch is
+ * in-flight for this key. The returned Promise resolves to the buffered
+ * Response (or null if the fetch failed/was aborted).
+ *
+ * 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().
+ */
+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);
+  return promise;
 }
 
 /**
- * Mark a key as successfully prefetched (response is in browser HTTP cache).
- * Skips if the generation has changed since the fetch started (cache was
- * invalidated mid-flight, so the response uses a stale X-Rango-State).
+ * Store a prefetch response in the in-memory cache.
+ * The response should be a clone() of the original so the caller can
+ * still consume the body. The clone's body streams independently.
+ *
+ * Skips storage if the generation has changed since the fetch started
+ * (a server action invalidated the cache mid-flight).
  */
-export function markPrefetched(key: string, fetchGeneration: number): void {
-  if (fetchGeneration === generation) {
-    prefetched.add(key);
+export function storePrefetch(
+  key: string,
+  response: Response,
+  fetchGeneration: number,
+): void {
+  if (cacheTTL <= 0) return;
+  if (fetchGeneration !== generation) return;
+
+  // Evict expired entries
+  const now = Date.now();
+  for (const [k, entry] of cache) {
+    if (now - entry.timestamp > cacheTTL) {
+      cache.delete(k);
+    }
   }
+
+  // FIFO eviction if at capacity
+  if (cache.size >= MAX_PREFETCH_CACHE_SIZE) {
+    const oldest = cache.keys().next().value;
+    if (oldest) cache.delete(oldest);
+  }
+
+  cache.set(key, { response, timestamp: now });
+}
+
+/**
+ * Capture the current generation. The returned value is passed to
+ * storePrefetch so it can detect stale completions.
+ */
+export function currentGeneration(): number {
+  return generation;
 }
 
 export function markPrefetchInflight(key: string): void {
   inflight.add(key);
 }
 
+/**
+ * Store the in-flight Promise for a prefetch so navigation can reuse it.
+ */
+export function setInflightPromise(
+  key: string,
+  promise: Promise<Response | null>,
+): void {
+  inflightPromises.set(key, promise);
+}
+
 export function clearPrefetchInflight(key: string): void {
   inflight.delete(key);
+  inflightPromises.delete(key);
 }
 
 /**
- * Invalidate prefetch state. Called when server actions mutate data.
- * Updates the localStorage state key so next fetch has a different
- * X-Rango-State value, causing Vary mismatch in browser HTTP cache.
- * Also cancels any in-flight or queued speculative prefetches.
+ * Invalidate all prefetch state. Called when server actions mutate data.
+ * Clears the in-memory cache, cancels in-flight prefetches, and rotates
+ * the Rango state key so CDN-cached responses are also invalidated.
+ *
+ * Uses abortAllPrefetches (hard cancel) because in-flight responses
+ * may contain stale data after a mutation.
  */
 export function clearPrefetchCache(): void {
   generation++;
   inflight.clear();
-  prefetched.clear();
-  cancelAllPrefetches();
+  inflightPromises.clear();
+  cache.clear();
+  abortAllPrefetches();
   invalidateRangoState();
 }

package/src/browser/prefetch/fetch.ts

@@ -2,15 +2,21 @@
  * Prefetch Fetch
  *
  * Fetch-based prefetch logic used by Link (hover/viewport/render strategies)
- * and useRouter().prefetch(). Sends low-priority fetch requests with
- * X-Rango-State and X-Rango-Prefetch headers so the browser HTTP cache
- * can serve the response on subsequent navigation.
+ * 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.
+ *
+ * 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.
  */
 
 import {
+  buildPrefetchKey,
   hasPrefetch,
   markPrefetchInflight,
-  markPrefetched,
+  setInflightPromise,
+  storePrefetch,
   clearPrefetchInflight,
   currentGeneration,
 } from "./cache.js";
@@ -20,14 +26,15 @@ import { shouldPrefetch } from "./policy.js";
 
 /**
  * Build an RSC partial URL for prefetching.
- * Includes _rsc_v for version mismatch detection when available.
- * Returns null for malformed or cross-origin URLs to prevent
- * leaking router headers to external origins.
+ * Includes _rsc_segments so the server can diff against currently mounted
+ * segments, and _rsc_v for version mismatch detection.
+ * Returns null for malformed or cross-origin URLs.
  */
 function buildPrefetchUrl(
   url: string,
   segmentIds: string[],
   version?: string,
+  routerId?: string,
 ): URL | null {
   let targetUrl: URL;
   try {
@@ -45,32 +52,27 @@ function buildPrefetchUrl(
   if (version) {
     targetUrl.searchParams.set("_rsc_v", version);
   }
+  if (routerId) {
+    targetUrl.searchParams.set("_rsc_rid", routerId);
+  }
   return targetUrl;
 }
 
 /**
- * Build the dedup key for prefetch tracking.
- * Includes the source page pathname so the same target prefetched from
- * different pages gets separate entries — the server response varies on
- * X-RSC-Router-Client-Path (source page context).
- */
-function buildPrefetchKey(targetUrl: URL): string {
-  return window.location.href + "\0" + targetUrl.pathname + targetUrl.search;
-}
-
-/**
- * Core prefetch fetch logic. Returns a Promise and accepts an optional
- * AbortSignal for cancellation by the prefetch queue.
+ * 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().
  */
 function executePrefetchFetch(
   key: string,
   fetchUrl: string,
   signal?: AbortSignal,
-): Promise<void> {
+): Promise<Response | null> {
   const gen = currentGeneration();
   markPrefetchInflight(key);
 
-  return fetch(fetchUrl, {
+  const promise: Promise<Response | null> = fetch(fetchUrl, {
     priority: "low" as RequestPriority,
     signal,
     headers: {
@@ -80,36 +82,43 @@ function executePrefetchFetch(
     },
   })
     .then((response) => {
-      // Drain body to ensure full download for browser HTTP cache.
-      // pipeTo avoids decoding the stream into a JS string (unlike .text()).
-      if (response.ok && response.body) {
-        return response.body
-          .pipeTo(new WritableStream())
-          .then(() => markPrefetched(key, gen));
-      }
-    })
-    .catch(() => {
-      // Silently ignore prefetch failures (including abort)
+      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);
     })
+    .catch(() => null)
     .finally(() => {
       clearPrefetchInflight(key);
     });
+
+  setInflightPromise(key, promise);
+  return promise;
 }
 
 /**
- * Prefetch (direct): fetch with low priority and store in browser HTTP cache.
+ * Prefetch (direct): fetch with low priority and store in in-memory cache.
  * Used by hover strategy -- fires immediately without queueing.
  */
 export function prefetchDirect(
   url: string,
   segmentIds: string[],
   version?: string,
+  routerId?: string,
 ): void {
   if (!shouldPrefetch()) return;
 
-  const targetUrl = buildPrefetchUrl(url, segmentIds, version);
+  const targetUrl = buildPrefetchUrl(url, segmentIds, version, routerId);
   if (!targetUrl) return;
-  const key = buildPrefetchKey(targetUrl);
+  const key = buildPrefetchKey(window.location.href, targetUrl);
   if (hasPrefetch(key)) return;
   executePrefetchFetch(key, targetUrl.toString());
 }
@@ -123,15 +132,19 @@ export function prefetchQueued(
   url: string,
   segmentIds: string[],
   version?: string,
+  routerId?: string,
 ): string {
   if (!shouldPrefetch()) return "";
-  const targetUrl = buildPrefetchUrl(url, segmentIds, version);
+  const targetUrl = buildPrefetchUrl(url, segmentIds, version, routerId);
   if (!targetUrl) return "";
-  const key = buildPrefetchKey(targetUrl);
+  const key = buildPrefetchKey(window.location.href, targetUrl);
   if (hasPrefetch(key)) return key;
   const fetchUrlStr = targetUrl.toString();
-  enqueuePrefetch(key, (signal) =>
-    executePrefetchFetch(key, fetchUrlStr, signal),
-  );
+  enqueuePrefetch(key, (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(() => {});
+  });
   return key;
 }

package/src/browser/prefetch/policy.ts

@@ -5,6 +5,8 @@
  * Honors browser reduced-data preferences when available.
  */
 
+import { isPrefetchCacheDisabled } from "./cache.js";
+
 type NavigatorWithConnection = Navigator & {
   connection?: {
     saveData?: boolean;
@@ -18,6 +20,10 @@ type NavigatorWithConnection = Navigator & {
 export function shouldPrefetch(): boolean {
   if (typeof window === "undefined") return false;
 
+  // When prefetchCacheTTL is false/0, prefetching is fully disabled —
+  // no point issuing requests whose responses will be discarded.
+  if (isPrefetchCacheDisabled()) return false;
+
   const nav =
     typeof navigator !== "undefined"
       ? (navigator as NavigatorWithConnection)

package/src/browser/prefetch/queue.ts

@@ -5,11 +5,19 @@
  * Hover prefetches bypass this queue — they fire directly for immediate response
  * to user intent.
  *
- * All queued/executing prefetches share a single AbortController so they can
- * be cancelled in bulk when a navigation starts.
+ * Draining waits for an idle main-thread moment and for viewport images to
+ * finish loading, so prefetch fetch() calls never compete with critical
+ * resources for the browser's connection pool.
+ *
+ * When a navigation starts, queued prefetches are cancelled but executing ones
+ * are left running. Navigation can reuse their in-flight responses via the
+ * prefetch cache's inflight promise map, avoiding duplicate requests.
  */
 
+import { wait, waitForIdle, waitForViewportImages } from "./resource-ready.js";
+
 const MAX_CONCURRENT = 2;
+const IMAGE_WAIT_TIMEOUT = 2000;
 
 let active = 0;
 const queue: Array<{
@@ -18,7 +26,9 @@ const queue: Array<{
 }> = [];
 const queued = new Set<string>();
 const executing = new Set<string>();
-let abortController: AbortController | null = null;
+const abortControllers = new Map<string, AbortController>();
+let drainScheduled = false;
+let drainGeneration = 0;
 
 function startExecution(
   key: string,
@@ -26,18 +36,49 @@ function startExecution(
 ): void {
   active++;
   executing.add(key);
-  abortController ??= new AbortController();
-  execute(abortController.signal).finally(() => {
+  const ac = new AbortController();
+  abortControllers.set(key, ac);
+  execute(ac.signal).finally(() => {
+    abortControllers.delete(key);
     // Only decrement if this key wasn't already cleared by cancelAllPrefetches.
     // Without this guard, cancelled tasks' .finally() would underflow active
     // below zero, breaking the MAX_CONCURRENT guarantee.
     if (executing.delete(key)) {
       active--;
     }
-    drain();
+    scheduleDrain();
   });
 }
 
+/**
+ * Schedule a drain after the browser is idle and viewport images are loaded.
+ * Coalesces multiple drain requests into a single deferred callback so
+ * batch completion doesn't schedule redundant waits.
+ *
+ * The two-step wait ensures prefetch fetch() calls don't compete with
+ * images for the browser's connection pool:
+ * 1. waitForIdle — yield until the main thread has a quiet moment
+ * 2. waitForViewportImages OR 2s timeout — yield until visible images
+ *    finish loading, but don't let slow/broken images block indefinitely
+ */
+function scheduleDrain(): void {
+  if (drainScheduled) return;
+  if (active >= MAX_CONCURRENT || queue.length === 0) return;
+  drainScheduled = true;
+  const gen = drainGeneration;
+  waitForIdle()
+    .then(() =>
+      Promise.race([waitForViewportImages(), wait(IMAGE_WAIT_TIMEOUT)]),
+    )
+    .then(() => {
+      drainScheduled = false;
+      // Stale drain: a cancel/abort happened while we were waiting.
+      // A fresh scheduleDrain will be called by whatever enqueues next.
+      if (gen !== drainGeneration) return;
+      if (queue.length > 0) drain();
+    });
+}
+
 function drain(): void {
   while (active < MAX_CONCURRENT && queue.length > 0) {
     const item = queue.shift()!;
@@ -48,9 +89,10 @@ function drain(): void {
 
 /**
  * Enqueue a prefetch for concurrency-limited execution.
- * If below the concurrency limit, executes immediately.
- * Otherwise queues for later execution.
- * Deduplicates by key — items already queued or executing are skipped.
+ * Execution is deferred until the browser is idle and viewport images
+ * have finished loading, so prefetches never compete with critical
+ * resources. Deduplicates by key — items already queued or executing
+ * are skipped.
  *
  * The executor receives an AbortSignal that is aborted when
  * cancelAllPrefetches() is called (e.g. on navigation start).
@@ -61,22 +103,50 @@ export function enqueuePrefetch(
 ): void {
   if (queued.has(key) || executing.has(key)) return;
 
-  if (active < MAX_CONCURRENT) {
-    startExecution(key, execute);
-  } else {
-    queued.add(key);
-    queue.push({ key, execute });
+  queued.add(key);
+  queue.push({ key, execute });
+  scheduleDrain();
+}
+
+/**
+ * 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
+ * navigation can reuse its response via consumeInflightPrefetch.
+ *
+ * Called when a navigation starts via the NavigationProvider's
+ * event controller subscription.
+ */
+export function cancelAllPrefetches(keepUrl?: string | null): void {
+  queue.length = 0;
+  queued.clear();
+  drainScheduled = false;
+  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.
+  for (const [key, ac] of abortControllers) {
+    const target = key.split("\0")[1];
+    if (keepUrl && target && keepUrl.startsWith(target)) continue;
+    ac.abort();
+    abortControllers.delete(key);
+    if (executing.delete(key)) {
+      active--;
+    }
   }
 }
 
 /**
- * Cancel all in-flight and queued prefetches.
- * Called when a navigation starts — speculative prefetches should not
- * compete with navigation fetches for connection slots.
+ * Hard-cancel everything including in-flight prefetches.
+ * Used by clearPrefetchCache (server action invalidation) where
+ * in-flight responses would be stale.
  */
-export function cancelAllPrefetches(): void {
-  abortController?.abort();
-  abortController = null;
+export function abortAllPrefetches(): void {
+  for (const ac of abortControllers.values()) {
+    ac.abort();
+  }
+  abortControllers.clear();
 
   queue.length = 0;
   queued.clear();
@@ -85,4 +155,6 @@ export function cancelAllPrefetches(): void {
   // so active settles at 0 without underflow.
   executing.clear();
   active = 0;
+  drainScheduled = false;
+  drainGeneration++;
 }

package/src/browser/prefetch/resource-ready.ts

@@ -0,0 +1,77 @@
+/**
+ * Resource Readiness
+ *
+ * Utilities to defer speculative prefetches until critical resources
+ * (viewport images) have finished loading. Prevents prefetch fetch()
+ * calls from competing with images for the browser's connection pool.
+ */
+
+/**
+ * Resolve when all in-viewport images have finished loading.
+ * Returns immediately if no images are pending.
+ *
+ * Only checks images that exist at call time — does not observe
+ * dynamically added images. For SPA navigations where new images
+ * appear after render, call this after the navigation settles.
+ */
+export function waitForViewportImages(): Promise<void> {
+  if (typeof document === "undefined") return Promise.resolve();
+
+  const pending = Array.from(document.querySelectorAll("img")).filter((img) => {
+    if (img.complete) return false;
+    const rect = img.getBoundingClientRect();
+    return (
+      rect.bottom > 0 &&
+      rect.right > 0 &&
+      rect.top < window.innerHeight &&
+      rect.left < window.innerWidth
+    );
+  });
+
+  if (pending.length === 0) return Promise.resolve();
+
+  return new Promise((resolve) => {
+    const settled = new Set<HTMLImageElement>();
+
+    const settle = (img: HTMLImageElement) => {
+      if (settled.has(img)) return;
+      settled.add(img);
+      if (settled.size >= pending.length) resolve();
+    };
+
+    for (const img of pending) {
+      img.addEventListener("load", () => settle(img), { once: true });
+      img.addEventListener("error", () => settle(img), { once: true });
+      // Re-check: image may have completed between the initial filter
+      // and listener attachment. settle() is idempotent per image, so
+      // a queued load event firing afterward is harmless.
+      if (img.complete) settle(img);
+    }
+  });
+}
+
+/**
+ * Resolve after the given number of milliseconds.
+ */
+export function wait(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Resolve when the browser has an idle main-thread moment.
+ * Uses requestIdleCallback where available, falls back to setTimeout.
+ *
+ * This is a scheduling hint, not an asset-loaded detector — combine
+ * with waitForViewportImages() for full resource readiness.
+ */
+export function waitForIdle(timeout = 200): Promise<void> {
+  if (typeof window !== "undefined" && "requestIdleCallback" in window) {
+    return new Promise((resolve) => {
+      window.requestIdleCallback(() => resolve(), { timeout });
+    });
+  }
+
+  return new Promise((resolve) => {
+    setTimeout(resolve, 0);
+  });
+}