@rangojs/router 0.0.0-experimental.f3c21dba → 0.0.0-experimental.f4a8e8de

package/src/browser/prefetch/loader.ts

@@ -0,0 +1,111 @@
+import type { RscPayload } from "../types.js";
+import type { EventController } from "../event-controller.js";
+
+type PrefetchDecoder = (response: Promise<Response>) => Promise<RscPayload>;
+
+type PrefetchRuntime = typeof import("./runtime.js");
+
+let runtime: PrefetchRuntime | null = null;
+let runtimePromise: Promise<PrefetchRuntime> | null = null;
+let decoder: PrefetchDecoder | null = null;
+let concurrency: number | undefined;
+let requestGeneration = 0;
+
+function loadRuntime(): Promise<PrefetchRuntime> {
+  if (runtime) return Promise.resolve(runtime);
+  if (!runtimePromise) {
+    runtimePromise = import("./runtime.js").then(
+      (loaded) => {
+        runtime = loaded;
+        if (decoder) loaded.setPrefetchDecoder(decoder);
+        if (concurrency !== undefined) {
+          loaded.setPrefetchConcurrency(concurrency);
+        }
+        return loaded;
+      },
+      (error: unknown) => {
+        runtimePromise = null;
+        throw error;
+      },
+    );
+  }
+  return runtimePromise;
+}
+
+function withRuntime(run: (loaded: PrefetchRuntime) => void): void {
+  if (runtime) {
+    run(runtime);
+    return;
+  }
+  const generation = requestGeneration;
+  void loadRuntime()
+    .then((loaded) => {
+      if (generation === requestGeneration) run(loaded);
+    })
+    .catch(() => {});
+}
+
+export function setPrefetchDecoder(fn: PrefetchDecoder): void {
+  decoder = fn;
+  runtime?.setPrefetchDecoder(fn);
+}
+
+export function setPrefetchConcurrency(value: number): void {
+  concurrency = value;
+  runtime?.setPrefetchConcurrency(value);
+}
+
+export function prefetchDirect(
+  url: string,
+  segmentIds: string[],
+  version?: string,
+  routerId?: string,
+  prefetchKey?: ":source",
+): void {
+  withRuntime((loaded) =>
+    loaded.prefetchDirect(url, segmentIds, version, routerId, prefetchKey),
+  );
+}
+
+export function prefetchQueued(
+  url: string,
+  segmentIds: string[],
+  version?: string,
+  routerId?: string,
+  prefetchKey?: ":source",
+): void {
+  withRuntime((loaded) =>
+    loaded.prefetchQueued(url, segmentIds, version, routerId, prefetchKey),
+  );
+}
+
+/** Run speculative work only when no navigation or stream is active. */
+export function schedulePrefetchWhenRouterIdle(
+  eventController: Pick<EventController, "getState" | "subscribe">,
+  callback: () => void,
+): (() => void) | undefined {
+  const state = eventController.getState();
+  if (state.state === "idle" && !state.isStreaming) {
+    callback();
+    return;
+  }
+
+  const unsubscribe = eventController.subscribe(() => {
+    const nextState = eventController.getState();
+    if (nextState.state === "idle" && !nextState.isStreaming) {
+      unsubscribe();
+      callback();
+    }
+  });
+  return unsubscribe;
+}
+
+export function cancelAllPrefetches(keepUrl?: string | null): void {
+  requestGeneration++;
+  runtime?.cancelAllPrefetches(keepUrl);
+}
+
+export function abortAllPrefetches(): void {
+  requestGeneration++;
+  runtime?.abortAllPrefetches();
+}

package/src/browser/prefetch/observer.ts

@@ -12,32 +12,53 @@
  * scrolls in and out repeatedly.
  */
 
+import { notifyListeners } from "../notify-listeners.js";
+
 type PrefetchCallback = () => void;
 
-const callbacks = new Map<Element, PrefetchCallback>();
+const callbacks = new Map<Element, Map<symbol, PrefetchCallback>>();
 let observer: IntersectionObserver | null = null;
 
 function getObserver(): IntersectionObserver {
   if (!observer) {
     observer = new IntersectionObserver(
-      (entries) => {
-        for (const entry of entries) {
-          if (entry.isIntersecting) {
-            const callback = callbacks.get(entry.target);
-            if (callback) {
-              observer!.unobserve(entry.target);
-              callbacks.delete(entry.target);
-              callback();
+      (entries, currentObserver) => {
+        function* intersectingCallbacks(): Generator<
+          [Map<symbol, PrefetchCallback>, symbol, PrefetchCallback]
+        > {
+          for (const entry of entries) {
+            if (entry.isIntersecting) {
+              const subscriptions = callbacks.get(entry.target);
+              if (subscriptions) {
+                currentObserver.unobserve(entry.target);
+                callbacks.delete(entry.target);
+                for (const [subscription, callback] of subscriptions) {
+                  yield [subscriptions, subscription, callback];
+                }
+              }
             }
           }
         }
+        notifyListeners(
+          intersectingCallbacks(),
+          ([, , callback]) => callback(),
+          ([subscriptions, subscription]) => subscriptions.has(subscription),
+        );
       },
       { rootMargin: "200px" },
     );
+    for (const element of callbacks.keys()) observer.observe(element);
   }
   return observer;
 }
 
+/** Reset module state between tests that replace browser observer globals. */
+export function resetPrefetchObserverForTesting(): void {
+  observer?.disconnect();
+  observer = null;
+  callbacks.clear();
+}
+
 /**
  * Observe an element for viewport intersection.
  * When the element becomes visible (within 200px margin), the callback fires
@@ -47,19 +68,26 @@ function getObserver(): IntersectionObserver {
 export function observeForPrefetch(
   element: Element,
   onVisible: PrefetchCallback,
-): void {
-  if (typeof IntersectionObserver === "undefined") return;
-  callbacks.set(element, onVisible);
-  getObserver().observe(element);
-}
+): () => void {
+  if (typeof IntersectionObserver === "undefined") return () => {};
+  const currentObserver = getObserver();
 
-/**
- * Stop observing an element. Used for cleanup when a Link unmounts
- * before entering the viewport.
- */
-export function unobserveForPrefetch(element: Element): void {
-  callbacks.delete(element);
-  if (observer) {
-    observer.unobserve(element);
+  let subscriptions = callbacks.get(element);
+  if (!subscriptions) {
+    subscriptions = new Map();
+    callbacks.set(element, subscriptions);
   }
+
+  const subscription = Symbol();
+  subscriptions.set(subscription, onVisible);
+  if (subscriptions.size === 1) currentObserver.observe(element);
+
+  return () => {
+    const current = callbacks.get(element);
+    subscriptions.delete(subscription);
+    if (current !== subscriptions) return;
+    if (current.size > 0) return;
+    callbacks.delete(element);
+    observer?.unobserve(element);
+  };
 }

package/src/browser/prefetch/queue.ts

@@ -5,21 +5,34 @@
  * 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);
+// Max prefetches executing at once. Mirrors DEFAULT_PREFETCH_CONCURRENCY
+// (router/prefetch-limits.ts); kept as a local literal so the client bundle
+// doesn't pull in router-layer code. Overridden at startup by
+// setPrefetchConcurrency from server metadata.
+let maxConcurrent = 2;
+const IMAGE_WAIT_TIMEOUT = 2000;
+
+/**
+ * Set the max number of concurrently-executing speculative prefetches.
+ * Called once at app startup with the value from server metadata. A value
+ * below 1 (or non-finite) is ignored, keeping the default.
+ */
+export function setPrefetchConcurrency(n: number): void {
+  if (Number.isFinite(n) && n >= 1) {
+    maxConcurrent = Math.floor(n);
+  }
+}
 
 let active = 0;
 const queue: Array<{
@@ -28,8 +41,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,11 +51,13 @@ 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.
+    // below zero, breaking the maxConcurrent guarantee.
     if (executing.delete(key)) {
       active--;
     }
@@ -50,22 +66,39 @@ 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;
+  if (active >= maxConcurrent || queue.length === 0) return;
   drainScheduled = true;
-  deferToNextPaint(() => {
-    drainScheduled = false;
-    drain();
-  });
+  const gen = drainGeneration;
+  waitForIdle()
+    .then(() =>
+      Promise.race([waitForViewportImages(), wait(IMAGE_WAIT_TIMEOUT)]),
+    )
+    .then(() => {
+      // Stale drain: a cancel/abort happened while we were waiting, and a fresh
+      // scheduleDrain may already own drainScheduled for the new generation.
+      // Bail WITHOUT clearing the flag so we don't clobber the live wait's
+      // single-in-flight-drain coalescing (clearing it here would let the next
+      // enqueue start a third overlapping wait).
+      if (gen !== drainGeneration) return;
+      drainScheduled = false;
+      if (queue.length > 0) drain();
+    });
 }
 
 function drain(): void {
-  while (active < MAX_CONCURRENT && queue.length > 0) {
+  while (active < maxConcurrent && queue.length > 0) {
     const item = queue.shift()!;
     queued.delete(item.key);
     startExecution(item.key, item.execute);
@@ -74,9 +107,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 +127,63 @@ 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.
+ * 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 targets 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.
+  // 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 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)) {
+      active--;
+    }
+  }
 }
 
 /**
@@ -114,8 +192,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 +205,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/prefetch/runtime.ts

@@ -0,0 +1,6 @@
+export { prefetchDirect, prefetchQueued, setPrefetchDecoder } from "./fetch.js";
+export {
+  abortAllPrefetches,
+  cancelAllPrefetches,
+  setPrefetchConcurrency,
+} from "./queue.js";