@rangojs/router 0.0.0-experimental.e9c0b2f2 → 0.0.0-experimental.ea9f40f2

package/src/browser/response-adapter.ts

@@ -2,6 +2,16 @@ import { validateRedirectOrigin } from "./validate-redirect-origin.js";
 
 type HeaderResult = { url: string } | "blocked" | null;
 
+/**
+ * Null-body statuses: the Fetch spec forbids pairing these with a body, so
+ * `new Response(body, { status })` throws ("Response with null body status
+ * cannot have body"). fetch() can still surface one WITH a body straight from
+ * the network layer (never the JS constructor): a 304 stale-while-revalidate
+ * prefetch revalidated to Not Modified (body from cache), or a 204 soft
+ * redirect. teeWithCompletion must not re-run those through `new Response`.
+ */
+const NULL_BODY_STATUS = new Set([101, 204, 205, 304]);
+
 /**
  * Extract and validate an RSC response header URL (X-RSC-Reload, X-RSC-Redirect).
  * Returns { url } if valid, "blocked" if present but invalid origin, null if absent.
@@ -74,7 +84,13 @@ export function handleReloadHeader(
  * Returns a new Response with one branch; the other is consumed to detect
  * end-of-stream, calling onComplete when done.
  *
- * If the response has no body, onComplete fires synchronously.
+ * `onComplete` receives `endedCleanly`: true only on a normal EOF drain, false
+ * on a read error or an abort (the signal cancelled the reader). Callers that
+ * gate a "fully complete" fast path (e.g. prefetch's `entry.complete`) must
+ * treat a non-clean end as incomplete — a broken stream is not complete data.
+ *
+ * If the response has no body, onComplete fires synchronously with `true`
+ * (an empty body is a clean, complete stream).
  * If signal is provided, an abort cancels the tracking reader.
  *
  * `silent` suppresses the stream-error log. Prefetch passes it: a speculative,
@@ -84,7 +100,7 @@ export function handleReloadHeader(
  */
 export function teeWithCompletion(
   response: Response,
-  onComplete: () => void,
+  onComplete: (endedCleanly: boolean) => void,
   signal?: AbortSignal,
   silent = false,
 ): Response {
@@ -92,15 +108,18 @@ export function teeWithCompletion(
   // rejection's .catch, so onComplete must be settled exactly once across all
   // paths (no-body early return, finally, catch).
   let settled = false;
-  const settle = () => {
+  const settle = (endedCleanly: boolean) => {
     if (!settled) {
       settled = true;
-      onComplete();
+      onComplete(endedCleanly);
     }
   };
 
-  if (!response.body) {
-    settle();
+  // Empty body, or a null-body status fetch() paired with a body: either way the
+  // body can't be re-attached via `new Response` below. Settle and pass the
+  // original response through; its body (when present) stays readable downstream.
+  if (!response.body || NULL_BODY_STATUS.has(response.status)) {
+    settle(true);
     return response;
   }
 
@@ -110,21 +129,31 @@ export function teeWithCompletion(
     const reader = trackingStream.getReader();
     const onAbort = signal ? reader.cancel.bind(reader) : undefined;
     if (onAbort) signal!.addEventListener("abort", onAbort, { once: true });
+    // Only a loop that reaches `done` is a clean EOF. A read error rejects out
+    // of the try and still runs the finally, so the finally must NOT assume
+    // clean — it gates on this flag (false on error) AND on signal.aborted
+    // (an abort cancels the reader so read() resolves { done: true } and the
+    // loop breaks here normally, NOT in the .catch — re-check the signal to
+    // catch that case).
+    let cleanEof = false;
     try {
       while (true) {
         const { done } = await reader.read();
-        if (done) break;
+        if (done) {
+          cleanEof = true;
+          break;
+        }
       }
     } finally {
       if (onAbort) signal!.removeEventListener("abort", onAbort);
       reader.releaseLock();
-      settle();
+      settle(cleanEof && !signal?.aborted);
     }
   })().catch((error) => {
     if (!silent && !signal?.aborted) {
       console.error("[Browser] Error reading tracking stream:", error);
     }
-    settle();
+    settle(false);
   });
 
   return new Response(rscStream, {

package/src/browser/rsc-router.tsx

@@ -25,6 +25,7 @@ import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 import { initRangoState } from "./rango-state.js";
 import { registerNavigationStore } from "./navigation-store-handle.js";
 import { initPrefetchCache } from "./prefetch/cache.js";
+import { setPrefetchConcurrency } from "./prefetch/queue.js";
 import { setPrefetchDecoder } from "./prefetch/fetch.js";
 import { setAppVersion } from "./app-version.js";
 import {
@@ -32,6 +33,7 @@ import {
   splitInterceptSegments,
 } from "./intercept-utils.js";
 import { createAppShellRef } from "./app-shell.js";
+import { bootLog, IS_BROWSER_DEBUG } from "./logging.js";
 
 // Vite HMR types are provided by vite/client
 
@@ -155,6 +157,8 @@ export async function initBrowserApp(
     initialTheme,
   } = options;
 
+  bootLog("initBrowserApp start");
+  bootLog("flight decode: awaiting initial payload from document stream");
   const initialPayload =
     await deps.createFromReadableStream<RscPayload>(rscStream);
 
@@ -168,6 +172,14 @@ export async function initBrowserApp(
   // Get initial segments and compute history key from current URL
   const initialSegments = (initialPayload.metadata?.segments ??
     []) as ResolvedSegment[];
+  if (IS_BROWSER_DEBUG) {
+    bootLog("initial payload decoded", {
+      version: initialPayload.metadata?.version,
+      routerId: initialPayload.metadata?.routerId,
+      segments: initialSegments.map((s) => s.id),
+      matched: initialPayload.metadata?.matched,
+    });
+  }
   const initialHistoryKey = generateHistoryKey(window.location.href);
 
   // Create navigation store with history-based caching
@@ -206,11 +218,24 @@ export async function initBrowserApp(
   // This ensures useHandle returns correct data during hydration to avoid mismatch
   // The handles property is an async generator that yields on each push
   if (initialPayload.metadata?.handles) {
+    // This for-await consumes the handle generator to completion BEFORE
+    // hydrateRoot is called — on a streaming/PPR document the generator only
+    // ends when its stream side does, so the per-push logs below are the
+    // primary probe for "the document render is holding hydration".
+    bootLog("handles: consuming payload handle stream (pre-hydration await)");
     const handlesGenerator = initialPayload.metadata.handles;
     let lastHandleData: Record<string, Record<string, unknown[]>> = {};
+    let handlePushes = 0;
     for await (const handleData of handlesGenerator) {
       lastHandleData = handleData;
+      if (IS_BROWSER_DEBUG) {
+        handlePushes += 1;
+        bootLog(`handles: push #${handlePushes}`, {
+          segments: Object.keys(handleData),
+        });
+      }
     }
+    bootLog("handles: stream complete", { pushes: handlePushes });
     // Initialize event controller with initial handle state before hydration.
     eventController.setHandleData(
       lastHandleData,
@@ -220,6 +245,8 @@ export async function initBrowserApp(
     // Update the initial cache entry with the processed handleData
     // The cache entry was created by createNavigationStore but without handleData
     store.updateCacheHandleData(initialHistoryKey, lastHandleData);
+  } else {
+    bootLog("handles: none in payload");
   }
 
   // Create composable utilities
@@ -245,11 +272,17 @@ export async function initBrowserApp(
   initRangoState(version ?? "0", initialPayload.metadata?.stateCookieName);
   setAppVersion(version);
 
-  // Initialize the in-memory prefetch cache TTL from server config.
-  // A value of 0 disables the cache; undefined falls back to the module default.
+  // Initialize the in-memory prefetch cache (TTL + max size) and the prefetch
+  // queue concurrency from server config. A TTL of 0 disables the cache;
+  // undefined values fall back to the module defaults.
   const prefetchCacheTTL = initialPayload.metadata?.prefetchCacheTTL;
-  if (prefetchCacheTTL !== undefined) {
-    initPrefetchCache(prefetchCacheTTL);
+  const prefetchCacheSize = initialPayload.metadata?.prefetchCacheSize;
+  if (prefetchCacheTTL !== undefined || prefetchCacheSize !== undefined) {
+    initPrefetchCache(prefetchCacheTTL, prefetchCacheSize);
+  }
+  const prefetchConcurrency = initialPayload.metadata?.prefetchConcurrency;
+  if (prefetchConcurrency !== undefined) {
+    setPrefetchConcurrency(prefetchConcurrency);
   }
 
   // Wire the RSC decoder so prefetches decode eagerly and warm the route's
@@ -314,9 +347,17 @@ export async function initBrowserApp(
   if (linkInterception) {
     navigationBridge.registerLinkInterception();
   }
+  bootLog("bridges registered (action + navigation)");
 
   // Build initial tree with rootLayout
+  bootLog("building initial segment tree (renderSegments)");
   const initialTree = renderSegments(initialPayload.metadata!.segments);
+  if (IS_BROWSER_DEBUG && initialTree instanceof Promise) {
+    initialTree.then(
+      () => bootLog("initial segment tree settled"),
+      (err: unknown) => bootLog("initial segment tree rejected", { err }),
+    );
+  }
 
   // Setup HMR with debounce — burst saves (format-on-save, rapid edits)
   // fire many rsc:update events in quick succession. Without debouncing,
@@ -484,9 +525,14 @@ export async function initBrowserApp(
   };
   browserAppContext = context;
 
+  bootLog("initBrowserApp complete -- handing off to hydrateRoot");
   return context;
 }
 
+// Once-flag so the hydration-commit boot log fires a single time (StrictMode
+// re-runs the root effect; the second flush is not a second hydration).
+let hydrationCommitLogged = false;
+
 /**
  * Get the browser app context. Throws if initBrowserApp hasn't been called.
  */
@@ -554,6 +600,10 @@ export function Rango(_props: RangoProps): React.ReactElement {
   // that does not depend on React internals like __reactFiber.
   React.useEffect(() => {
     document.documentElement.dataset.hydrated = "";
+    if (IS_BROWSER_DEBUG && !hydrationCommitLogged) {
+      hydrationCommitLogged = true;
+      bootLog("hydration commit (root effect flushed)");
+    }
   }, []);
 
   return (

package/src/browser/scroll-restoration.ts

@@ -8,7 +8,7 @@
  * - Supports hash link scrolling
  */
 
-import { debugLog } from "./logging.js";
+import { debugLog, IS_BROWSER_DEBUG } from "./logging.js";
 
 /**
  * Defers a callback to the next animation frame.
@@ -150,10 +150,12 @@ export function initScrollRestoration(options?: {
 
   window.addEventListener("pagehide", handlePageHide);
 
-  debugLog(
-    "[Scroll] Initialized, loaded positions:",
-    Object.keys(savedScrollPositions).length,
-  );
+  if (IS_BROWSER_DEBUG) {
+    debugLog(
+      "[Scroll] Initialized, loaded positions:",
+      Object.keys(savedScrollPositions).length,
+    );
+  }
 
   return () => {
     cancelScrollRestorationPolling();

package/src/browser/segment-reconciler.ts

@@ -6,7 +6,7 @@ import {
 } from "./merge-segment-loaders.js";
 import { assertSegmentStructure } from "./segment-structure-assert.js";
 import { splitInterceptSegments } from "./intercept-utils.js";
-import { debugLog } from "./logging.js";
+import { debugLog, IS_BROWSER_DEBUG } from "./logging.js";
 
 /**
  * Determines the merging behavior for segment reconciliation.
@@ -87,15 +87,17 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
   input.cachedSegments.forEach((s) => cachedSegments.set(s.id, s));
 
   const diffSet = new Set(diff);
-  debugLog(
-    `[reconcile] actor=${actor}, matched=${matched.length}, diff=${diff.length}`,
-  );
-  debugLog(
-    `[reconcile] server segments: ${[...serverSegments.keys()].join(", ")}`,
-  );
-  debugLog(
-    `[reconcile] cached segments: ${[...cachedSegments.keys()].join(", ")}`,
-  );
+  if (IS_BROWSER_DEBUG) {
+    debugLog(
+      `[reconcile] actor=${actor}, matched=${matched.length}, diff=${diff.length}`,
+    );
+    debugLog(
+      `[reconcile] server segments: ${[...serverSegments.keys()].join(", ")}`,
+    );
+    debugLog(
+      `[reconcile] cached segments: ${[...cachedSegments.keys()].join(", ")}`,
+    );
+  }
 
   const segments = matched
     .map((segId: string) => {
@@ -106,9 +108,11 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
         const inDiff = diffSet.has(segId);
         // Merge partial loader data when server returns fewer loaders than cached
         if (shouldMergeLoaders && needsLoaderMerge(fromServer, fromCache)) {
-          debugLog(
-            `[reconcile] ${segId}: MERGE loaders (server partial, ${inDiff ? "in diff" : "not in diff"})`,
-          );
+          if (IS_BROWSER_DEBUG) {
+            debugLog(
+              `[reconcile] ${segId}: MERGE loaders (server partial, ${inDiff ? "in diff" : "not in diff"})`,
+            );
+          }
           return mergeSegmentLoaders(fromServer, fromCache);
         }
 
@@ -159,14 +163,18 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
           // above fails to preserve a value it should have.
           assertSegmentStructure(fromCache, merged, context);
 
+          if (IS_BROWSER_DEBUG) {
+            debugLog(
+              `[reconcile] ${segId}: SERVER+CACHE merge (${inDiff ? "in diff" : "not in diff"}, type=${fromServer.type}, component=${fromServer.component === null ? "null→cached" : "server"})`,
+            );
+          }
+          return merged;
+        }
+        if (IS_BROWSER_DEBUG) {
           debugLog(
-            `[reconcile] ${segId}: SERVER+CACHE merge (${inDiff ? "in diff" : "not in diff"}, type=${fromServer.type}, component=${fromServer.component === null ? "null→cached" : "server"})`,
+            `[reconcile] ${segId}: SERVER only (${inDiff ? "in diff" : "not in diff"}, type=${fromServer.type}, no cache entry)`,
           );
-          return merged;
         }
-        debugLog(
-          `[reconcile] ${segId}: SERVER only (${inDiff ? "in diff" : "not in diff"}, type=${fromServer.type}, no cache entry)`,
-        );
         return fromServer;
       }
 
@@ -180,9 +188,11 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
         return fromCache;
       }
 
-      debugLog(
-        `[reconcile] ${segId}: CACHE only (not from server, type=${fromCache.type}, component=${fromCache.component != null ? "yes" : "null"})`,
-      );
+      if (IS_BROWSER_DEBUG) {
+        debugLog(
+          `[reconcile] ${segId}: CACHE only (not from server, type=${fromCache.type}, component=${fromCache.component != null ? "yes" : "null"})`,
+        );
+      }
 
       // Return the cached segment as-is, regardless of actor. We used to clear
       // truthy `loading` here to prevent a stale Suspense fallback from

package/src/browser/server-action-bridge.ts

@@ -558,18 +558,15 @@ export function createServerActionBridge(
           return undefined;
         }
 
-        // Update UI with error boundary
-        startTransition(() => {
-          onUpdate({ root: errorTree, metadata: metadata! });
-        });
-
         // Update segment tracking to exclude error segment IDs
         const errorSegmentIds = new Set(diff);
         const segmentIdsAfterError = segmentState.currentSegmentIds.filter(
           (id) => !errorSegmentIds.has(id),
         );
 
-        // Update store state
+        // Cache (and bump the nav instance) BEFORE the UI update so a deferred
+        // handle pushed by the error-boundary render still applies — see the
+        // "normal" case below for why caching after onUpdate dropped it.
         store.setSegmentIds(segmentIdsAfterError);
         const currentHandleData = eventController.getHandleState().data;
         store.cacheSegmentsForHistory(
@@ -578,6 +575,11 @@ export function createServerActionBridge(
           currentHandleData,
         );
 
+        // Update UI with error boundary
+        startTransition(() => {
+          onUpdate({ root: errorTree, metadata: metadata! });
+        });
+
         // Throw the error so the action promise rejects
         if (returnValue && !returnValue.ok) {
           throw returnValue.data;
@@ -779,10 +781,16 @@ export function createServerActionBridge(
             break;
           }
 
-          startTransition(() => {
-            onUpdate({ root: newTree, metadata: metadata! });
-          });
-
+          // Cache (and bump the nav instance) BEFORE the UI update, matching the
+          // navigation commit order (navigation-transaction.ts:157). processHandles
+          // is spawned by onUpdate and captures the current nav instance up front;
+          // a deferred handle value resolves asynchronously and is only applied
+          // while stillLive() (its captured instance still owns the page). Caching
+          // AFTER onUpdate bumped the instance out from under that in-flight
+          // resolve, so stillLive() turned false and the resolved handle snapshot
+          // was dropped on the action-revalidation path (sync siblings sharing the
+          // yield are held atomically, so they were dropped too).
+          //
           // Location state already applied above (pre-switch). Update store.
           store.setSegmentIds(matched);
           const currentHandleData = eventController.getHandleState().data;
@@ -791,6 +799,10 @@ export function createServerActionBridge(
             fullSegments,
             currentHandleData,
           );
+
+          startTransition(() => {
+            onUpdate({ root: newTree, metadata: metadata! });
+          });
           // Invalidation deferred to finalizeAction() (runs after this caches
           // the fresh segments), suppressed when the action called
           // keepClientCache().

package/src/browser/types.ts

@@ -70,6 +70,16 @@ export interface RscMetadata {
    * Sent on initial render so the browser can configure its cache duration.
    */
   prefetchCacheTTL?: number;
+  /**
+   * Max entries in the client-side in-memory prefetch cache (FIFO eviction).
+   * Sent on initial render so the browser can configure its cache capacity.
+   */
+  prefetchCacheSize?: number;
+  /**
+   * Max concurrent speculative prefetch requests on the client.
+   * Sent on initial render so the browser can configure its prefetch queue.
+   */
+  prefetchConcurrency?: number;
   /**
    * Server-resolved rango state cookie name (`{prefix}_{routerId}`). The client
    * reads it verbatim and binds the rango state cookie to it; composition
@@ -447,6 +457,10 @@ export interface NavigationStore {
   // History-based segment cache (for back/forward navigation and partial merging)
   getHistoryKey(): string;
   setHistoryKey(key: string): void;
+  /** Monotonic token of the most recently committed navigation. */
+  getNavInstance(): number;
+  /** Nav-instance token recorded on a cache entry (undefined if absent). */
+  getCacheEntryInstance(historyKey: string): number | undefined;
   cacheSegmentsForHistory(
     historyKey: string,
     segments: ResolvedSegment[],
@@ -458,10 +472,40 @@ export interface NavigationStore {
         stale: boolean;
         handleData?: HandleData;
         routerId?: string;
+        /**
+         * True when the entry's handle data is incomplete (a deferred Meta was
+         * still pending at navigate-away). A popstate return must revalidate with
+         * a FULL re-render so the server re-streams handles.
+         */
+        handlesPending?: boolean;
       }
     | undefined;
   hasHistoryCache(historyKey: string): boolean;
-  updateCacheHandleData(historyKey: string, handleData: HandleData): void;
+  /**
+   * Update only the handleData (and optionally the stale / handlesPending flags)
+   * of an existing cache entry. When a flag is omitted the entry's current value
+   * is preserved. `stale=true` marks a single entry stale so a popstate return
+   * revalidates it; `handlesPending=true` additionally forces that revalidation
+   * to be a full re-render (so a deferred Meta re-streams).
+   */
+  updateCacheHandleData(
+    historyKey: string,
+    handleData: HandleData,
+    stale?: boolean,
+    handlesPending?: boolean,
+  ): void;
+  /**
+   * Owner-guarded variant of updateCacheHandleData: writes only when the entry
+   * is still owned by `ownerInstance`. Folds the caller's separate ownership
+   * probe and write into one historyCache scan for the per-yield streaming path.
+   */
+  updateCacheHandleDataIfOwned(
+    historyKey: string,
+    handleData: HandleData,
+    ownerInstance: number,
+    stale?: boolean,
+    handlesPending?: boolean,
+  ): void;
   markCacheAsStale(): void;
   markHistoryCacheStale(): void;
   markCacheAsStaleAndBroadcast(): void;
@@ -521,6 +565,15 @@ export interface FetchPartialResult {
   payload: RscPayload;
   /** Promise that resolves when the response stream is fully consumed */
   streamComplete: Promise<void>;
+  /**
+   * True only when this payload came from a prefetch-cache hit whose stream had
+   * ALREADY fully drained at fetch time (the route was fully prefetched). The
+   * commit then runs in a startTransition so loading()/Suspense content — already
+   * resolved — swaps in directly without flashing a fallback. A partially-warmed
+   * (still-streaming) prefetch hit and a cold fetch leave this false so their
+   * fallbacks stream as usual.
+   */
+  fullyPrefetched?: boolean;
 }
 
 /**