@rangojs/router 0.0.0-experimental.cb54cbba → 0.0.0-experimental.ea6d5eec

package/src/browser/prefetch/queue.ts

@@ -5,12 +5,22 @@
  * 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 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.
+ *
+ * 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;
 
+const deferToNextPaint: (fn: () => void) => void =
+  typeof requestAnimationFrame === "function"
+    ? requestAnimationFrame
+    : (fn) => setTimeout(fn, 0);
+
 let active = 0;
 const queue: Array<{
   key: string;
@@ -19,6 +29,7 @@ const queue: Array<{
 const queued = new Set<string>();
 const executing = new Set<string>();
 let abortController: AbortController | null = null;
+let drainScheduled = false;
 
 function startExecution(
   key: string,
@@ -34,6 +45,21 @@ function startExecution(
     if (executing.delete(key)) {
       active--;
     }
+    scheduleDrain();
+  });
+}
+
+/**
+ * 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.
+ */
+function scheduleDrain(): void {
+  if (drainScheduled) return;
+  if (active >= MAX_CONCURRENT || queue.length === 0) return;
+  drainScheduled = true;
+  deferToNextPaint(() => {
+    drainScheduled = false;
     drain();
   });
 }
@@ -48,8 +74,8 @@ function drain(): void {
 
 /**
  * Enqueue a prefetch for concurrency-limited execution.
- * If below the concurrency limit, executes immediately.
- * Otherwise queues for later 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.
  *
  * The executor receives an AbortSignal that is aborted when
@@ -61,20 +87,33 @@ 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 all in-flight and queued prefetches.
- * Called when a navigation starts — speculative prefetches should not
- * compete with navigation fetches for connection slots.
+ * 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.
+ *
+ * Called when a navigation starts via the NavigationProvider's
+ * event controller subscription.
  */
 export function cancelAllPrefetches(): void {
+  queue.length = 0;
+  queued.clear();
+  drainScheduled = false;
+}
+
+/**
+ * Hard-cancel everything including in-flight prefetches.
+ * Used by clearPrefetchCache (server action invalidation) where
+ * in-flight responses would be stale.
+ */
+export function abortAllPrefetches(): void {
   abortController?.abort();
   abortController = null;
 
@@ -85,4 +124,5 @@ export function cancelAllPrefetches(): void {
   // so active settles at 0 without underflow.
   executing.clear();
   active = 0;
+  drainScheduled = false;
 }

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
@@ -301,9 +304,33 @@ export function NavigationProvider({
     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,104 @@ 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;
+        console.log("[RSCRouter] HMR: Server update, refetching RSC");
 
-          store.setSegmentIds(matched);
-          store.setCurrentUrl(window.location.href);
+        const abort = new AbortController();
+        hmrAbort = abort;
 
-          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 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 (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 while streaming until we can scroll to target position
+  // 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;
       }
 
-      // Stop if streaming ended
       if (!options.isStreaming?.()) {
-        debugLog("[Scroll] Streaming ended, stopping poll");
-        cancelScrollRestorationPolling();
-        return;
-      }
-
-      // Check if we can now scroll to the target position
-      const currentMaxScrollY =
-        document.documentElement.scrollHeight - window.innerHeight;
-      if (savedY <= currentMaxScrollY) {
         window.scrollTo(0, savedY);
-        debugLog("[Scroll] Poll restored position:", savedY);
+        debugLog("[Scroll] Restored after streaming:", savedY);
         cancelScrollRestorationPolling();
       }
     }, SCROLL_POLL_INTERVAL_MS);
+
+    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/types.ts

@@ -215,6 +215,15 @@ export interface SegmentState {
 export interface NavigationUpdate {
   root: ReactNode | Promise<ReactNode>;
   metadata: RscMetadata;
+  /** Scroll behavior to apply after React commits this update */
+  scroll?: {
+    /** For back/forward: restore saved position */
+    restore?: boolean;
+    /** Set to false to disable scrolling entirely */
+    enabled?: boolean;
+    /** Function to check if streaming is in progress */
+    isStreaming?: () => boolean;
+  };
 }
 
 /**

package/src/build/route-types/router-processing.ts

@@ -45,7 +45,9 @@ function isRoutableSourceFile(name: string): boolean {
       name.endsWith(".tsx") ||
       name.endsWith(".js") ||
       name.endsWith(".jsx")) &&
-    !name.includes(".gen.")
+    !name.includes(".gen.") &&
+    !name.includes(".test.") &&
+    !name.includes(".spec.")
   );
 }
 
@@ -70,7 +72,15 @@ function findRouterFilesRecursive(
   for (const entry of entries) {
     const fullPath = join(dir, entry.name);
     if (entry.isDirectory()) {
-      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      if (
+        entry.name === "node_modules" ||
+        entry.name === "dist" ||
+        entry.name === "coverage" ||
+        entry.name === "__tests__" ||
+        entry.name === "__mocks__" ||
+        entry.name.startsWith(".")
+      )
+        continue;
       childDirs.push(fullPath);
       continue;
     }

package/src/cache/cache-scope.ts

@@ -73,7 +73,7 @@ function getDefaultRouteCacheKey(
   isIntercept?: boolean,
 ): string {
   const ctx = getRequestContext();
-  const isPartial = ctx?.url.searchParams.has("_rsc_partial") ?? false;
+  const isPartial = ctx?.originalUrl?.searchParams.has("_rsc_partial") ?? false;
   const searchParams = ctx?.url.searchParams;
   const host = ctx?.url.host ?? "localhost";
 
@@ -326,7 +326,7 @@ export class CacheScope {
     const key = await this.resolveKey(pathname, params, isIntercept);
 
     // Check if this is a partial request (navigation) vs document request
-    const isPartial = requestCtx.url.searchParams.has("_rsc_partial");
+    const isPartial = requestCtx.originalUrl.searchParams.has("_rsc_partial");
 
     requestCtx.waitUntil(async () => {
       await handleStore.settled;