@rangojs/router 0.0.0-experimental.760a71d9 → 0.0.0-experimental.78

package/src/browser/prefetch/cache.ts

@@ -61,13 +61,23 @@ const inflightPromises = new Map<string, Promise<Response | null>>();
 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 for prefetched responses.
+ *
+ * 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).
+ *
+ * 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.
  */
-export function buildPrefetchKey(sourceHref: string, targetUrl: URL): string {
-  return sourceHref + "\0" + targetUrl.pathname + targetUrl.search;
+export function buildPrefetchKey(
+  sourceHref: string,
+  targetUrl: URL,
+  prefetchKey?: string | ((from: string) => string),
+): string {
+  const source = prefetchKey != null ? "*" : sourceHref;
+  return source + "\0" + targetUrl.pathname + targetUrl.search;
 }
 
 /**

package/src/browser/prefetch/fetch.ts

@@ -23,6 +23,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 with prefetchKey, which would
+ * produce a trivial diff that corrupts the wildcard cache.
+ */
+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 +52,7 @@ function buildPrefetchUrl(
   url: string,
   segmentIds: string[],
   version?: string,
+  routerId?: string,
 ): URL | null {
   let targetUrl: URL;
   try {
@@ -51,6 +70,9 @@ function buildPrefetchUrl(
   if (version) {
     targetUrl.searchParams.set("_rsc_v", version);
   }
+  if (routerId) {
+    targetUrl.searchParams.set("_rsc_rid", routerId);
+  }
   return targetUrl;
 }
 
@@ -108,13 +130,33 @@ export function prefetchDirect(
   url: string,
   segmentIds: string[],
   version?: string,
+  routerId?: string,
+  prefetchKey?: string | ((from: string) => string),
 ): 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;
+  // 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)) {
+    return;
+  }
+  const key = buildPrefetchKey(window.location.href, targetUrl, prefetchKey);
+  if (hasPrefetch(key)) {
+    debugLog("[prefetch] direct dedup (key already exists)", {
+      url,
+      key,
+      prefetchKey: prefetchKey != null ? String(prefetchKey) : undefined,
+    });
+    return;
+  }
+  debugLog("[prefetch] direct fetch", {
+    url,
+    key,
+    source: window.location.href,
+    prefetchKey: prefetchKey != null ? String(prefetchKey) : undefined,
+  });
   executePrefetchFetch(key, targetUrl.toString());
 }
 
@@ -127,17 +169,37 @@ export function prefetchQueued(
   url: string,
   segmentIds: string[],
   version?: string,
+  routerId?: string,
+  prefetchKey?: string | ((from: string) => string),
 ): 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;
+  // 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)) {
+    return "";
+  }
+  const key = buildPrefetchKey(window.location.href, targetUrl, prefetchKey);
+  if (hasPrefetch(key)) {
+    debugLog("[prefetch] queued dedup (key already exists)", {
+      url,
+      key,
+      prefetchKey: prefetchKey != null ? String(prefetchKey) : undefined,
+    });
+    return key;
+  }
   const fetchUrlStr = targetUrl.toString();
   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();
+    // 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)) {
+      return Promise.resolve();
+    }
     return executePrefetchFetch(key, fetchUrlStr, signal).then(() => {});
   });
   return key;

package/src/browser/prefetch/queue.ts

@@ -5,21 +5,19 @@
  * Hover prefetches bypass this queue — they fire directly for immediate response
  * to user intent.
  *
- * Draining is deferred to the next animation frame so prefetch network activity
- * never blocks paint. This applies to both the initial batch and subsequent
- * batches — every drain cycle yields to the browser first.
+ * 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.
  */
 
-const MAX_CONCURRENT = 2;
+import { wait, waitForIdle, waitForViewportImages } from "./resource-ready.js";
 
-const deferToNextPaint: (fn: () => void) => void =
-  typeof requestAnimationFrame === "function"
-    ? requestAnimationFrame
-    : (fn) => setTimeout(fn, 0);
+const MAX_CONCURRENT = 2;
+const IMAGE_WAIT_TIMEOUT = 2000;
 
 let active = 0;
 const queue: Array<{
@@ -28,8 +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,
@@ -37,8 +36,10 @@ 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.
@@ -50,18 +51,32 @@ function startExecution(
 }
 
 /**
- * Schedule a drain on the next animation frame.
- * Coalesces multiple drain requests into a single rAF callback so
- * batch completion doesn't schedule redundant frames.
+ * 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;
-  deferToNextPaint(() => {
-    drainScheduled = false;
-    drain();
-  });
+  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 {
@@ -74,9 +89,10 @@ function drain(): void {
 
 /**
  * Enqueue a prefetch for concurrency-limited execution.
- * Execution is always deferred to the next animation frame to avoid
- * blocking paint, even when below the concurrency limit.
- * 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).
@@ -93,19 +109,32 @@ export function enqueuePrefetch(
 }
 
 /**
- * Cancel queued prefetches. Executing prefetches are left running so
- * navigation can reuse their in-flight responses (checked via
- * consumeInflightPrefetch in the prefetch cache). With MAX_CONCURRENT=2
- * and priority: "low", in-flight prefetches don't meaningfully compete
- * with navigation fetches under HTTP/2 multiplexing.
+ * 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(): void {
+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--;
+    }
+  }
 }
 
 /**
@@ -114,8 +143,10 @@ export function cancelAllPrefetches(): void {
  * in-flight responses would be stale.
  */
 export function abortAllPrefetches(): void {
-  abortController?.abort();
-  abortController = null;
+  for (const ac of abortControllers.values()) {
+    ac.abort();
+  }
+  abortControllers.clear();
 
   queue.length = 0;
   queued.clear();
@@ -125,4 +156,5 @@ export function abortAllPrefetches(): void {
   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);
+  });
+}

package/src/browser/react/Link.tsx

@@ -5,6 +5,7 @@ import React, {
   useCallback,
   useContext,
   useEffect,
+  useMemo,
   useRef,
   type ForwardRefExoticComponent,
   type RefAttributes,
@@ -32,6 +33,7 @@ export type LinkState =
   | StateOrGetter<Record<string, unknown>>;
 
 import { prefetchDirect, prefetchQueued } from "../prefetch/fetch.js";
+import { getAppVersion } from "../app-version.js";
 import {
   observeForPrefetch,
   unobserveForPrefetch,
@@ -95,6 +97,26 @@ export interface LinkProps extends Omit<
    * @default "none"
    */
   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.
+   *
+   * - String: static group name (e.g., `"pages"`)
+   * - Function: receives current URL (`window.location.href`), returns a
+   *   normalized source key
+   *
+   * @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+$/, '')} />
+   * ```
+   */
+  prefetchKey?: string | ((from: string) => string);
   /**
    * State to pass to history.pushState/replaceState.
    * Accessible via useLocationState() hook.
@@ -182,6 +204,7 @@ export const Link: ForwardRefExoticComponent<
     reloadDocument = false,
     revalidate,
     prefetch = "none",
+    prefetchKey,
     state,
     children,
     onClick,
@@ -192,6 +215,16 @@ export const Link: ForwardRefExoticComponent<
   const ctx = useContext(NavigationStoreContext);
   const isExternal = isExternalUrl(to);
 
+  // Auto-prefix with basename for app-local paths.
+  // Skip if external, already prefixed, or not a root-relative path.
+  const resolvedTo = useMemo(() => {
+    if (isExternal) return to;
+    const bn = ctx?.basename;
+    if (!bn || !to.startsWith("/") || to.startsWith(bn + "/") || to === bn)
+      return to;
+    return to === "/" ? bn : bn + to;
+  }, [to, isExternal, ctx?.basename]);
+
   // Resolve adaptive: viewport on touch devices, hover on pointer devices
   const resolvedStrategy =
     prefetch === "adaptive" ? (isTouchDevice ? "viewport" : "hover") : prefetch;
@@ -273,9 +306,23 @@ export const Link: ForwardRefExoticComponent<
         resolvedState = currentState;
       }
 
-      ctx.navigate(to, { replace, scroll, state: resolvedState, revalidate });
+      ctx.navigate(resolvedTo, {
+        replace,
+        scroll,
+        state: resolvedState,
+        revalidate,
+      });
     },
-    [to, isExternal, reloadDocument, replace, scroll, revalidate, ctx, onClick],
+    [
+      resolvedTo,
+      isExternal,
+      reloadDocument,
+      replace,
+      scroll,
+      revalidate,
+      ctx,
+      onClick,
+    ],
   );
 
   const handleMouseEnter = useCallback(() => {
@@ -289,9 +336,15 @@ export const Link: ForwardRefExoticComponent<
       // prefetch — prefetchDirect bypasses the queue, and hasPrefetch
       // deduplicates if the viewport prefetch already completed.
       const segmentState = ctx.store.getSegmentState();
-      prefetchDirect(to, segmentState.currentSegmentIds, ctx.version);
+      prefetchDirect(
+        resolvedTo,
+        segmentState.currentSegmentIds,
+        getAppVersion(),
+        ctx.store.getRouterId?.(),
+        prefetchKey,
+      );
     }
-  }, [resolvedStrategy, to, isExternal, ctx]);
+  }, [resolvedStrategy, resolvedTo, isExternal, ctx, prefetchKey]);
 
   // Viewport/render prefetch: waits for idle before starting,
   // uses concurrency-limited queue to avoid flooding.
@@ -308,7 +361,13 @@ export const Link: ForwardRefExoticComponent<
     const triggerPrefetch = () => {
       if (cancelled) return;
       const segmentState = ctx.store.getSegmentState();
-      prefetchQueued(to, segmentState.currentSegmentIds, ctx.version);
+      prefetchQueued(
+        resolvedTo,
+        segmentState.currentSegmentIds,
+        getAppVersion(),
+        ctx.store.getRouterId?.(),
+        prefetchKey,
+      );
     };
 
     // Schedule prefetch only when the app is idle (no navigation/streaming).
@@ -347,12 +406,12 @@ export const Link: ForwardRefExoticComponent<
         unobserveForPrefetch(observedElement);
       }
     };
-  }, [resolvedStrategy, to, isExternal, ctx]);
+  }, [resolvedStrategy, resolvedTo, isExternal, ctx, prefetchKey]);
 
   return (
     <a
       ref={setRef}
-      href={to}
+      href={resolvedTo}
       onClick={handleClick}
       onMouseEnter={handleMouseEnter}
       data-link-component
@@ -362,7 +421,7 @@ export const Link: ForwardRefExoticComponent<
       data-revalidate={revalidate === false ? "false" : undefined}
       {...props}
     >
-      <LinkContext.Provider value={to}>{children}</LinkContext.Provider>
+      <LinkContext.Provider value={resolvedTo}>{children}</LinkContext.Provider>
     </a>
   );
 });

package/src/browser/react/NavigationProvider.tsx

@@ -134,9 +134,14 @@ export interface NavigationProviderProps {
 
   /**
    * App version from server payload (stable, immutable).
-   * Forwarded to prefetch requests for version mismatch detection.
+   * Forwarded to context for cache key building.
    */
   version?: string;
+
+  /**
+   * URL prefix for all routes (from createRouter({ basename })).
+   */
+  basename?: string;
 }
 
 /**
@@ -169,6 +174,7 @@ export function NavigationProvider({
   initialTheme,
   warmupEnabled,
   version,
+  basename,
 }: NavigationProviderProps): ReactNode {
   // Track current payload for rendering (this triggers re-renders)
   const [payload, setPayload] = useState(initialPayload);
@@ -198,6 +204,7 @@ export function NavigationProvider({
       navigate,
       refresh,
       version,
+      basename,
     }),
     [],
   );
@@ -289,15 +296,17 @@ export function NavigationProvider({
     };
   }, [warmupEnabled]);
 
-  // Cancel speculative prefetches when navigation starts.
-  // Viewport/render prefetches should not compete with navigation fetches.
+  // Cancel non-matching prefetches when navigation starts.
+  // Frees connections so the navigation fetch isn't competing with
+  // speculative prefetches. The prefetch matching the navigation target
+  // is kept alive so it can be reused via consumeInflightPrefetch.
   useEffect(() => {
     let wasIdle = true;
     const unsub = eventController.subscribe(() => {
       const state = eventController.getState();
       const isIdle = state.state === "idle" && !state.isStreaming;
       if (wasIdle && !isIdle) {
-        cancelAllPrefetches();
+        cancelAllPrefetches(state.pendingUrl);
       }
       wasIdle = isIdle;
     });

package/src/browser/react/context.ts

@@ -43,10 +43,15 @@ export interface NavigationStoreContextValue {
   refresh: () => Promise<void>;
 
   /**
-   * App version from server payload (stable, immutable).
-   * Used in prefetch requests for version mismatch detection.
+   * App version from the initial server payload.
    */
   version: string | undefined;
+
+  /**
+   * URL prefix for all routes (from createRouter({ basename })).
+   * Used by Link and useRouter() to auto-prefix app-local paths.
+   */
+  basename: string | undefined;
 }
 
 /**