@rangojs/router 0.0.0-experimental.141 → 0.0.0-experimental.142

package/src/browser/partial-update.ts

@@ -20,7 +20,11 @@ import {
 } from "./intercept-utils.js";
 import type { BoundTransaction } from "./navigation-transaction.js";
 import { ServerRedirect } from "../errors.js";
-import { debugLog, isBrowserDebugEnabled } from "./logging.js";
+import {
+  debugLog,
+  isBrowserDebugEnabled,
+  IS_BROWSER_DEBUG,
+} from "./logging.js";
 import {
   validateRedirectOrigin,
   validateExternalRedirect,
@@ -147,9 +151,11 @@ export function createPartialUpdater(
         currentCached.filter(isInterceptSegment).map((s) => s.id),
       );
       segments = currentSegments.filter((id) => !interceptIds.has(id));
-      debugLog(
-        `[Browser] Leaving intercept - filtered segments: ${segments.join(", ")}`,
-      );
+      if (IS_BROWSER_DEBUG) {
+        debugLog(
+          `[Browser] Leaving intercept - filtered segments: ${segments.join(", ")}`,
+        );
+      }
     } else {
       segments = segmentIds ?? segmentState.currentSegmentIds;
     }
@@ -159,12 +165,14 @@ export function createPartialUpdater(
         ? segmentState.currentUrl || tx.currentUrl
         : interceptSourceUrl || tx.currentUrl || segmentState.currentUrl;
 
-    debugLog(`\n[Browser] >>> NAVIGATION`);
-    debugLog(`[Browser] From: ${previousUrl}`);
-    debugLog(`[Browser] To: ${url}`);
-    debugLog(`[Browser] Segments to send: ${segments.join(", ")}`);
-    if (interceptSourceUrl) {
-      debugLog(`[Browser] Intercept context from: ${interceptSourceUrl}`);
+    if (IS_BROWSER_DEBUG) {
+      debugLog(`\n[Browser] >>> NAVIGATION`);
+      debugLog(`[Browser] From: ${previousUrl}`);
+      debugLog(`[Browser] To: ${url}`);
+      debugLog(`[Browser] Segments to send: ${segments.join(", ")}`);
+      if (interceptSourceUrl) {
+        debugLog(`[Browser] Intercept context from: ${interceptSourceUrl}`);
+      }
     }
 
     const targetCache =
@@ -173,9 +181,11 @@ export function createPartialUpdater(
         : undefined;
     const cachedSegs = targetCache ?? getCurrentCachedSegments();
     const cachedSegsSource = targetCache ? "history-cache" : "current-page";
-    debugLog(
-      `[Browser] cachedSegs source: ${cachedSegsSource} (${cachedSegs.length} segments: ${cachedSegs.map((s) => s.id).join(", ")})`,
-    );
+    if (IS_BROWSER_DEBUG) {
+      debugLog(
+        `[Browser] cachedSegs source: ${cachedSegsSource} (${cachedSegs.length} segments: ${cachedSegs.map((s) => s.id).join(", ")})`,
+      );
+    }
 
     let fetchResult: Awaited<ReturnType<NavigationClient["fetchPartial"]>>;
     fetchResult = await client.fetchPartial({
@@ -258,8 +268,10 @@ export function createPartialUpdater(
         return;
       }
 
-      debugLog(`[Browser] Partial update - matched: ${matched?.join(", ")}`);
-      debugLog(`[Browser] Diff: ${diff?.join(", ")}`);
+      if (IS_BROWSER_DEBUG) {
+        debugLog(`[Browser] Partial update - matched: ${matched?.join(", ")}`);
+        debugLog(`[Browser] Diff: ${diff?.join(", ")}`);
+      }
 
       if (!diff || diff.length === 0) {
         const matchedIds = matched || [];

package/src/browser/prefetch/cache.ts

@@ -113,6 +113,16 @@ interface PrefetchCacheEntry {
 const cache = new Map<string, PrefetchCacheEntry>();
 const inflight = new Set<string>();
 
+// Watermark: the smallest entry timestamp currently in `cache`, i.e. a lower
+// bound on when the oldest entry expires (timestamp + cacheTTL). storePrefetch's
+// eager expiry sweep is skipped while `now - earliestTimestamp <= cacheTTL` — the
+// oldest entry cannot be expired yet, so nothing would be evicted. Deletions
+// (consume/has/remove) may leave it stale-LOW, which only forces a harmless extra
+// sweep that recomputes it exactly; it is never stale-high, so a skipped sweep
+// can never retain an expired entry. consume/has still TTL-check lazily, so a
+// skipped sweep never serves a stale entry. Infinity when the cache is empty.
+let earliestTimestamp = Infinity;
+
 const inflightPromises = new Map<string, Promise<DecodedPrefetch | null>>();
 
 const inflightAliases = new Map<string, string[]>();
@@ -269,12 +279,20 @@ export function storePrefetch(
     return;
   }
 
-  // Evict expired entries
+  // Evict expired entries — but only when the watermark says the oldest entry
+  // could have expired, so a burst of stores no longer walks the whole map each
+  // time. The sweep recomputes the exact watermark from the survivors.
   const now = Date.now();
-  for (const [k, cached] of cache) {
-    if (now - cached.timestamp > cacheTTL) {
-      cache.delete(k);
+  if (now - earliestTimestamp > cacheTTL) {
+    let min = Infinity;
+    for (const [k, cached] of cache) {
+      if (now - cached.timestamp > cacheTTL) {
+        cache.delete(k);
+      } else if (cached.timestamp < min) {
+        min = cached.timestamp;
+      }
     }
+    earliestTimestamp = min;
   }
 
   // FIFO eviction if at capacity
@@ -284,6 +302,9 @@ export function storePrefetch(
   }
 
   cache.set(key, { entry, timestamp: now });
+  // The new entry is the newest, so it only moves the watermark when the cache
+  // was empty (Infinity); otherwise the older watermark stands.
+  if (now < earliestTimestamp) earliestTimestamp = now;
 }
 
 /**
@@ -354,6 +375,7 @@ export function clearPrefetchCache(): void {
   inflightAliases.clear();
   adoptedKeys.clear();
   cache.clear();
+  earliestTimestamp = Infinity;
   abortAllPrefetches();
   invalidateRangoState();
 }

package/src/browser/prefetch/fetch.ts

@@ -31,7 +31,7 @@ import { getRangoState } from "../rango-state.js";
 import { isActionFenceActive } from "../action-fence.js";
 import { enqueuePrefetch } from "./queue.js";
 import { shouldPrefetch } from "./policy.js";
-import { debugLog } from "../logging.js";
+import { debugLog, IS_BROWSER_DEBUG } from "../logging.js";
 import { teeWithCompletion, isForeignRouterId } from "../response-adapter.js";
 import type { RscPayload } from "../types.js";
 
@@ -154,6 +154,8 @@ function executePrefetchFetch(
   sourceKey: string,
   fetchUrl: string,
   forceSourceScope: boolean,
+  /** Rango state captured once by the caller (keys + header share one read). */
+  rangoState: string,
   expectedRouterId?: string,
   signal?: AbortSignal,
 ): Promise<DecodedPrefetch | null> {
@@ -214,7 +216,7 @@ function executePrefetchFetch(
     ...(isActionFenceActive() && { cache: "no-store" as RequestCache }),
     signal: effectiveSignal,
     headers: {
-      "X-Rango-State": getRangoState(),
+      "X-Rango-State": rangoState,
       "X-RSC-Router-Client-Path": window.location.href,
       "X-Rango-Prefetch": "1",
     },
@@ -371,26 +373,31 @@ export function prefetchDirect(
   const wildcardKey = buildPrefetchKey(rangoState, targetUrl);
   const sourceKey = buildSourceKey(rangoState, sourceHref, targetUrl);
   if (hasPrefetchHit(forceSourceScope, wildcardKey, sourceKey)) {
-    debugLog("[prefetch] direct dedup (key already exists)", {
+    if (IS_BROWSER_DEBUG) {
+      debugLog("[prefetch] direct dedup (key already exists)", {
+        url,
+        wildcardKey,
+        sourceKey,
+        forceSourceScope,
+      });
+    }
+    return;
+  }
+  if (IS_BROWSER_DEBUG) {
+    debugLog("[prefetch] direct fetch", {
       url,
       wildcardKey,
       sourceKey,
+      source: sourceHref,
       forceSourceScope,
     });
-    return;
   }
-  debugLog("[prefetch] direct fetch", {
-    url,
-    wildcardKey,
-    sourceKey,
-    source: sourceHref,
-    forceSourceScope,
-  });
   executePrefetchFetch(
     wildcardKey,
     sourceKey,
     targetUrl.toString(),
     forceSourceScope,
+    rangoState,
     routerId,
   );
 }
@@ -421,12 +428,14 @@ export function prefetchQueued(
   const sourceKey = buildSourceKey(rangoState, sourceHref, targetUrl);
   const queueKey = forceSourceScope ? sourceKey : wildcardKey;
   if (hasPrefetchHit(forceSourceScope, wildcardKey, sourceKey)) {
-    debugLog("[prefetch] queued dedup (key already exists)", {
-      url,
-      wildcardKey,
-      sourceKey,
-      forceSourceScope,
-    });
+    if (IS_BROWSER_DEBUG) {
+      debugLog("[prefetch] queued dedup (key already exists)", {
+        url,
+        wildcardKey,
+        sourceKey,
+        forceSourceScope,
+      });
+    }
     return queueKey;
   }
   const fetchUrlStr = targetUrl.toString();
@@ -444,6 +453,7 @@ export function prefetchQueued(
       sourceKey,
       fetchUrlStr,
       forceSourceScope,
+      rangoState,
       routerId,
       signal,
     ).then(() => {});

package/src/browser/react/Link.tsx

@@ -39,9 +39,16 @@ import {
   unobserveForPrefetch,
 } from "../prefetch/observer.js";
 
+// The (hover: none) MediaQueryList, created lazily on first client read and
+// reused across every Link render. matchMedia allocates and registers a live
+// query object; a fresh one per render (Link renders can be very frequent) is
+// wasteful when the same object's `.matches` is already live. Left null on the
+// server (no window).
+let hoverNoneQuery: MediaQueryList | null = null;
+
 /**
- * Read current touch/no-hover capability. Evaluated at the point of use (per
- * render) rather than once at module load, so `prefetch="adaptive"` reacts to
+ * Read current touch/no-hover capability from the cached MediaQueryList. The
+ * `.matches` read is live, so `prefetch="adaptive"` still reacts to
  * input-capability changes on hybrid devices (touch laptops, tablets gaining or
  * losing a pointer) and after SSR -> hydrate. The SSR guard returns a stable
  * `false` (pointer/hover default) so the resolved strategy doesn't drift on the
@@ -49,7 +56,10 @@ import {
  */
 function isTouchDevice(): boolean {
   if (typeof window === "undefined") return false;
-  return window.matchMedia("(hover: none)").matches;
+  if (!hoverNoneQuery) {
+    hoverNoneQuery = window.matchMedia("(hover: none)");
+  }
+  return hoverNoneQuery.matches;
 }
 
 /**

package/src/browser/react/NavigationProvider.tsx

@@ -113,14 +113,13 @@ async function processHandles(
         resolvedIds,
       );
       // Keep the cache fresh. The token guard stops a stale same-URL nav writing
-      // a newer entry.
-      if (store.getCacheEntryInstance(historyKey) === myInstance) {
-        store.updateCacheHandleData(
-          historyKey,
-          eventController.getHandleState().data,
-          false,
-        );
-      }
+      // a newer entry; the owned-write folds probe + write into one scan.
+      store.updateCacheHandleDataIfOwned(
+        historyKey,
+        eventController.getHandleState().data,
+        myInstance,
+        false,
+      );
       continue;
     }
 
@@ -146,9 +145,13 @@ async function processHandles(
     // re-streams the handles — a diff-only revalidation would omit the unchanged
     // segments' handles and the deferred value would never land (see the
     // segmentIds branch in navigation-bridge.ts).
-    if (store.getCacheEntryInstance(historyKey) === myInstance) {
-      store.updateCacheHandleData(historyKey, previousSnapshot, true, true);
-    }
+    store.updateCacheHandleDataIfOwned(
+      historyKey,
+      previousSnapshot,
+      myInstance,
+      true,
+      true,
+    );
 
     // Resolve every deferred value (allSettled; rejected + nullish dropped, sync
     // values pass through). Each stream yield is a full cumulative snapshot.
@@ -172,14 +175,13 @@ async function processHandles(
 
     // Still live: apply the fully-resolved snapshot and refresh the cache fresh.
     eventController.setHandleData(resolved, matched, isPartial, resolvedIds);
-    if (store.getCacheEntryInstance(historyKey) === myInstance) {
-      store.updateCacheHandleData(
-        historyKey,
-        eventController.getHandleState().data,
-        false,
-        false,
-      );
-    }
+    store.updateCacheHandleDataIfOwned(
+      historyKey,
+      eventController.getHandleState().data,
+      myInstance,
+      false,
+      false,
+    );
   }
 
   // Check again before final updates

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/types.ts

@@ -494,6 +494,18 @@ export interface NavigationStore {
     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;