@rangojs/router 0.0.0-experimental.39 → 0.0.0-experimental.3b1deca8

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);
+  });
+}

package/src/browser/react/Link.tsx

@@ -279,7 +279,15 @@ export const Link: ForwardRefExoticComponent<
   );
 
   const handleMouseEnter = useCallback(() => {
-    if (resolvedStrategy === "hover" && !isExternal && ctx?.store) {
+    if (
+      (resolvedStrategy === "hover" || resolvedStrategy === "viewport") &&
+      !isExternal &&
+      ctx?.store
+    ) {
+      // For "hover", this is the primary prefetch trigger.
+      // For "viewport", this upgrades/prioritizes a potentially queued
+      // 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);
     }

package/src/browser/react/NavigationProvider.tsx

@@ -3,8 +3,10 @@
 import React, {
   useState,
   useEffect,
+  useLayoutEffect,
   useCallback,
   useMemo,
+  useRef,
   use,
   type ReactNode,
 } from "react";
@@ -25,6 +27,7 @@ import { ThemeProvider } from "../../theme/ThemeProvider.js";
 import { NonceContext } from "./nonce-context.js";
 import type { ResolvedThemeConfig, Theme } from "../../theme/types.js";
 import { cancelAllPrefetches } from "../prefetch/queue.js";
+import { handleNavigationEnd } from "../scroll-restoration.js";
 
 /**
  * Process handles from an async generator, updating the event controller
@@ -286,24 +289,50 @@ 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;
     });
     return unsub;
   }, [eventController]);
 
+  // Pending scroll action to apply after React commits
+  const pendingScrollRef = useRef<NavigationUpdate["scroll"]>(undefined);
+
+  // Apply scroll after React commits the new content to the DOM
+  useLayoutEffect(() => {
+    const scrollAction = pendingScrollRef.current;
+    if (!scrollAction) return;
+    pendingScrollRef.current = undefined;
+
+    if (scrollAction.enabled === false) return;
+
+    handleNavigationEnd({
+      restore: scrollAction.restore,
+      scroll: scrollAction.enabled,
+      isStreaming: scrollAction.isStreaming,
+    });
+  });
+
   // Subscribe to UI updates (for re-rendering the tree)
   useEffect(() => {
     const unsubscribe = store.onUpdate((update) => {
+      // Capture scroll intent — it will be applied in useLayoutEffect
+      // after React commits this state update to the DOM.
+      // Always assign (even undefined) to clear stale scroll from prior navigations,
+      // so server actions or error updates don't accidentally replay old scroll.
+      pendingScrollRef.current = update.scroll;
+
       setPayload({
         root: update.root,
         metadata: update.metadata,

package/src/browser/rsc-router.tsx

@@ -263,71 +263,123 @@ export async function initBrowserApp(
   // Build initial tree with rootLayout
   const initialTree = renderSegments(initialPayload.metadata!.segments);
 
-  // Setup HMR
+  // Setup HMR with debounce — burst saves (format-on-save, rapid edits)
+  // fire many rsc:update events in quick succession. Without debouncing,
+  // each event triggers a fetchPartial() which on slow routes can pile up
+  // and overwhelm the worker (cross-request promise issues, 500s).
   if (import.meta.hot) {
-    import.meta.hot.on("rsc:update", async () => {
-      console.log("[RSCRouter] HMR: Server update, refetching RSC");
-
-      const handle = eventController.startNavigation(window.location.href, {
-        replace: true,
-      });
-      const streamingToken = handle.startStreaming();
-
-      const interceptSourceUrl = store.getInterceptSourceUrl();
-
-      try {
-        const { payload, streamComplete } = await client.fetchPartial({
-          targetUrl: window.location.href,
-          segmentIds: [],
-          previousUrl: store.getSegmentState().currentUrl,
-          interceptSourceUrl: interceptSourceUrl || undefined,
-          hmr: true,
-        });
+    let hmrTimer: ReturnType<typeof setTimeout> | null = null;
+    let hmrAbort: AbortController | null = null;
 
-        if (payload.metadata?.isPartial) {
-          const segments = payload.metadata.segments || [];
-          const matched = payload.metadata.matched || [];
+    import.meta.hot.on("rsc:update", () => {
+      // Cancel any pending debounce timer
+      if (hmrTimer !== null) {
+        clearTimeout(hmrTimer);
+      }
 
-          // Derive intercept state from the returned payload, not the
-          // pre-fetch store snapshot. If the HMR edit removed intercept
-          // behavior, the response won't contain intercept segments.
-          const responseIsIntercept = segments.some(isInterceptSegment);
+      // Abort any in-flight HMR fetch so it doesn't race with the next one
+      if (hmrAbort) {
+        hmrAbort.abort();
+        hmrAbort = null;
+      }
 
-          // Sync store intercept state with what the server returned
-          if (!responseIsIntercept && interceptSourceUrl) {
-            store.setInterceptSourceUrl(null);
-          }
+      // Debounce: wait 200ms of quiet before fetching
+      hmrTimer = setTimeout(async () => {
+        hmrTimer = null;
+
+        // Don't interrupt an active user navigation — startNavigation()
+        // would abort it and refetch the old URL (window.location.href
+        // hasn't updated yet). The user's navigation will pick up the
+        // new server code when it completes. isNavigating covers the
+        // full lifecycle (fetching + streaming, before commit) without
+        // blocking on server actions.
+        if (eventController.getState().isNavigating) {
+          console.log("[RSCRouter] HMR: Skipping — navigation in progress");
+          return;
+        }
 
-          store.setSegmentIds(matched);
-          store.setCurrentUrl(window.location.href);
+        console.log("[RSCRouter] HMR: Server update, refetching RSC");
 
-          const historyKey = generateHistoryKey(window.location.href, {
-            intercept: responseIsIntercept,
-          });
-          store.setHistoryKey(historyKey);
-          const currentHandleData = eventController.getHandleState().data;
-          store.cacheSegmentsForHistory(
-            historyKey,
-            segments,
-            currentHandleData,
-          );
-
-          const { main, intercept } = splitInterceptSegments(segments);
-          store.emitUpdate({
-            root: renderSegments(main, {
-              interceptSegments: intercept.length > 0 ? intercept : undefined,
-            }),
-            metadata: payload.metadata,
+        const abort = new AbortController();
+        hmrAbort = abort;
+
+        const handle = eventController.startNavigation(window.location.href, {
+          replace: true,
+        });
+        const streamingToken = handle.startStreaming();
+
+        const interceptSourceUrl = store.getInterceptSourceUrl();
+
+        try {
+          const { payload, streamComplete } = await client.fetchPartial({
+            targetUrl: window.location.href,
+            segmentIds: [],
+            previousUrl: store.getSegmentState().currentUrl,
+            interceptSourceUrl: interceptSourceUrl || undefined,
+            hmr: true,
+            signal: abort.signal,
           });
-        }
 
-        await streamComplete;
-        handle.complete(new URL(window.location.href));
-        console.log("[RSCRouter] HMR: RSC stream complete");
-      } finally {
-        streamingToken.end();
-        handle[Symbol.dispose]();
-      }
+          if (abort.signal.aborted) return;
+
+          // If the server returned a non-RSC response (404, 500 without
+          // error boundary), the payload won't have valid metadata.
+          // Reload to recover rather than leaving the page stale.
+          if (!payload.metadata) {
+            throw new Error("HMR refetch returned invalid payload");
+          }
+
+          if (payload.metadata?.isPartial) {
+            const segments = payload.metadata.segments || [];
+            const matched = payload.metadata.matched || [];
+
+            // Derive intercept state from the returned payload, not the
+            // pre-fetch store snapshot. If the HMR edit removed intercept
+            // behavior, the response won't contain intercept segments.
+            const responseIsIntercept = segments.some(isInterceptSegment);
+
+            // Sync store intercept state with what the server returned
+            if (!responseIsIntercept && interceptSourceUrl) {
+              store.setInterceptSourceUrl(null);
+            }
+
+            store.setSegmentIds(matched);
+            store.setCurrentUrl(window.location.href);
+
+            const historyKey = generateHistoryKey(window.location.href, {
+              intercept: responseIsIntercept,
+            });
+            store.setHistoryKey(historyKey);
+            const currentHandleData = eventController.getHandleState().data;
+            store.cacheSegmentsForHistory(
+              historyKey,
+              segments,
+              currentHandleData,
+            );
+
+            const { main, intercept } = splitInterceptSegments(segments);
+            store.emitUpdate({
+              root: renderSegments(main, {
+                interceptSegments: intercept.length > 0 ? intercept : undefined,
+              }),
+              metadata: payload.metadata,
+            });
+          }
+
+          await streamComplete;
+          handle.complete(new URL(window.location.href));
+          console.log("[RSCRouter] HMR: RSC stream complete");
+        } catch (err) {
+          if (abort.signal.aborted) return;
+          console.warn("[RSCRouter] HMR: Refetch failed, reloading page", err);
+          window.location.reload();
+          return;
+        } finally {
+          if (hmrAbort === abort) hmrAbort = null;
+          streamingToken.end();
+          handle[Symbol.dispose]();
+        }
+      }, 200);
     });
   }
 

package/src/browser/scroll-restoration.ts

@@ -10,6 +10,15 @@
 
 import { debugLog } from "./logging.js";
 
+/**
+ * Defers a callback to the next animation frame.
+ * Falls back to setTimeout(0) in environments without requestAnimationFrame.
+ */
+const deferToNextPaint: (fn: () => void) => void =
+  typeof requestAnimationFrame === "function"
+    ? requestAnimationFrame
+    : (fn) => setTimeout(fn, 0);
+
 const SCROLL_STORAGE_KEY = "rsc-router-scroll-positions";
 
 /**
@@ -264,51 +273,35 @@ export function restoreScrollPosition(options?: {
     return false;
   }
 
-  // Check if page is tall enough to scroll to saved position
-  const maxScrollY = document.documentElement.scrollHeight - window.innerHeight;
-  const canScrollToPosition = savedY <= maxScrollY;
-
-  if (canScrollToPosition) {
-    window.scrollTo(0, savedY);
-    debugLog("[Scroll] Restored position:", savedY, "for key:", key);
-    return true;
-  }
-
-  // Scroll as far as we can for now
-  window.scrollTo(0, maxScrollY);
-  debugLog("[Scroll] Partial restore to:", maxScrollY, "target:", savedY);
-
-  // Poll until we can scroll to the target position.
-  // This covers both streaming (content arriving incrementally) and
-  // React's batched startTransition rendering (DOM updates are async
-  // even for cached navigations with no streaming).
-  if (options?.retryIfStreaming) {
+  // If streaming, poll until streaming ends then scroll to saved position
+  if (options?.retryIfStreaming && options?.isStreaming?.()) {
     const startTime = Date.now();
 
     pendingPollInterval = setInterval(() => {
-      // Stop if we've exceeded the timeout
       if (Date.now() - startTime > SCROLL_POLL_TIMEOUT_MS) {
         debugLog("[Scroll] Polling timeout, giving up");
         cancelScrollRestorationPolling();
         return;
       }
 
-      // Check if we can now scroll to the target position
-      const currentMaxScrollY =
-        document.documentElement.scrollHeight - window.innerHeight;
-      if (savedY <= currentMaxScrollY) {
+      if (!options.isStreaming?.()) {
         window.scrollTo(0, savedY);
-        debugLog("[Scroll] Poll restored position:", savedY);
+        debugLog("[Scroll] Restored after streaming:", savedY);
         cancelScrollRestorationPolling();
       }
     }, SCROLL_POLL_INTERVAL_MS);
 
-    // Return true to prevent handleNavigationEnd from falling through
-    // to scrollToTop(). The polling will handle the final scroll.
     return true;
   }
 
-  return false;
+  // Not streaming — scroll after React commits and browser paints.
+  // startTransition defers the DOM commit, so scrolling synchronously
+  // would be overwritten when React replaces the content.
+  deferToNextPaint(() => {
+    window.scrollTo(0, savedY);
+    debugLog("[Scroll] Restored position:", savedY, "for key:", key);
+  });
+  return true;
 }
 
 /**
@@ -382,13 +375,17 @@ export function handleNavigationEnd(options: {
     // Fall through to hash or top if no saved position
   }
 
-  // Try hash scrolling first
-  if (scrollToHash()) {
-    return;
-  }
+  // Defer hash and scroll-to-top to after React paints the new content,
+  // so the user doesn't see the current page jump before the new route appears.
+  deferToNextPaint(() => {
+    // Try hash scrolling first
+    if (scrollToHash()) {
+      return;
+    }
 
-  // Default: scroll to top
-  scrollToTop();
+    // Default: scroll to top
+    scrollToTop();
+  });
 }
 
 /**

package/src/browser/segment-reconciler.ts

@@ -160,8 +160,13 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
 
       // For non-action actors: cached segments the server decided not to re-render.
       // - Preserve loading=false (suppressed boundary) to maintain tree structure
-      // - Clear truthy loading (active skeleton) to prevent suspense on cached content
+      // - Preserve parallel segment loading so renderSegments can reconstruct
+      //   parallel-owned loader markers from the cached slot metadata
+      // - Clear other truthy loading values to prevent suspense on cached content
       if (actor !== "action") {
+        if (fromCache.type === "parallel" && fromCache.loading !== undefined) {
+          return fromCache;
+        }
         if (fromCache.loading !== undefined && fromCache.loading !== false) {
           return { ...fromCache, loading: undefined };
         }