@rangojs/router 0.0.0-experimental.35 → 0.0.0-experimental.358c376d

package/src/browser/scroll-restoration.ts

@@ -8,7 +8,16 @@
  * - 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.
+ * 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";
 
@@ -141,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();
@@ -182,10 +193,15 @@ export function saveCurrentScrollPosition(): void {
 
 /**
  * Persist scroll positions to sessionStorage.
- * If the write fails due to quota exceeded, progressively evict the oldest
- * entries and retry until it succeeds or the store is empty.
+ * If the write fails (typically QuotaExceededError), evict the oldest ~1/4 of
+ * entries ONCE and retry the write a single time; if that still fails, remove
+ * our storage key entirely so we don't block other sessionStorage consumers.
+ * This is a single evict-then-retry-then-clear ladder, not a loop.
+ *
+ * Exported so that single eviction/retry/clear ladder is unit-testable directly.
+ * The browser drives it from the `pagehide` handler.
  */
-function persistToSessionStorage(): void {
+export function persistToSessionStorage(): void {
   try {
     sessionStorage.setItem(
       SCROLL_STORAGE_KEY,
@@ -264,51 +280,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;
 }
 
 /**
@@ -339,6 +339,8 @@ export function scrollToHash(): boolean {
  * Scroll to top of page
  */
 export function scrollToTop(): void {
+  if (typeof window === "undefined") return;
+  if (typeof window.scrollTo !== "function") return;
   window.scrollTo(0, 0);
 }
 
@@ -363,31 +365,43 @@ export function handleNavigationEnd(options: {
   scroll?: boolean;
   isStreaming?: () => boolean;
 }): void {
-  if (!initialized) {
-    return;
-  }
-
   const { restore = false, scroll = true, isStreaming } = options;
 
-  // Don't scroll if explicitly disabled
-  if (scroll === false) {
+  // Don't scroll if explicitly disabled or not in a browser
+  if (scroll === false || typeof window === "undefined") {
     return;
   }
 
-  // For back/forward (restore), try to restore saved position
-  if (restore) {
+  // Save/restore requires initialization (sessionStorage, history state).
+  // But basic scroll-to-top and hash scrolling work without it — this
+  // matters during cross-app navigation where ScrollRestoration unmounts
+  // and remounts, creating a brief window where initialized is false.
+  if (restore && initialized) {
     if (restoreScrollPosition({ retryIfStreaming: true, isStreaming })) {
       return;
     }
     // Fall through to hash or top if no saved position
   }
 
-  // Try hash scrolling first
+  // scrollToHash / scrollToTop run synchronously here.
+  // handleNavigationEnd is invoked from NavigationProvider's
+  // useLayoutEffect (post-commit, pre-paint), so a sync scrollTo is
+  // captured by the upcoming paint AND by startViewTransition's snapshot.
+  // Deferring via rAF here pushed the call past the snapshot capture,
+  // making forward navigations wrapped in a layout/route view transition
+  // skip scroll-to-top — the live DOM scrolled but the captured snapshot
+  // was at the previous scroll position, so the user-facing page stayed
+  // visually clamped at the source page's scrollY (often the new tree's
+  // max scroll for tall→short navs). Y=0 / a hash element are robust
+  // against unmeasured layout, so sync scroll is correct here even
+  // before the new tree's scrollHeight settles.
+  //
+  // (The restore branch above keeps deferToNextPaint because savedY
+  // depends on the new tree's max scroll; sync scrollTo against an
+  // unmeasured DOM would clamp savedY to whatever the old/zero max was.)
   if (scrollToHash()) {
     return;
   }
-
-  // Default: scroll to top
   scrollToTop();
 }
 

package/src/browser/segment-reconciler.ts

@@ -6,6 +6,7 @@ import {
 } from "./merge-segment-loaders.js";
 import { assertSegmentStructure } from "./segment-structure-assert.js";
 import { splitInterceptSegments } from "./intercept-utils.js";
+import { debugLog, IS_BROWSER_DEBUG } from "./logging.js";
 
 /**
  * Determines the merging behavior for segment reconciliation.
@@ -85,14 +86,33 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
   const cachedSegments = new Map<string, ResolvedSegment>();
   input.cachedSegments.forEach((s) => cachedSegments.set(s.id, s));
 
+  const diffSet = new Set(diff);
+  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) => {
       const fromServer = serverSegments.get(segId);
       const fromCache = cachedSegments.get(segId);
 
       if (fromServer) {
+        const inDiff = diffSet.has(segId);
         // Merge partial loader data when server returns fewer loaders than cached
         if (shouldMergeLoaders && needsLoaderMerge(fromServer, fromCache)) {
+          if (IS_BROWSER_DEBUG) {
+            debugLog(
+              `[reconcile] ${segId}: MERGE loaders (server partial, ${inDiff ? "in diff" : "not in diff"})`,
+            );
+          }
           return mergeSegmentLoaders(fromServer, fromCache);
         }
 
@@ -143,8 +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 only (${inDiff ? "in diff" : "not in diff"}, type=${fromServer.type}, no cache entry)`,
+          );
+        }
         return fromServer;
       }
 
@@ -158,15 +188,22 @@ export function reconcileSegments(input: ReconcileInput): ReconcileResult {
         return fromCache;
       }
 
-      // 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
-      if (actor !== "action") {
-        if (fromCache.loading !== undefined && fromCache.loading !== false) {
-          return { ...fromCache, loading: undefined };
-        }
+      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
+      // committing against cached content, but that swapped the render tree
+      // from the LoaderBoundary branch to the plain OutletProvider branch
+      // inside renderSegments, causing React to unmount the entire chain
+      // (LoaderBoundary > Suspense > LoaderResolver > RouteContentWrapper >
+      // Suspender) every time the user opened an intercept or navigated back
+      // to a cached page. The flicker is now prevented by renderSegments'
+      // promise memoization keeping React's use() in "known fulfilled" state,
+      // so preserving `loading` keeps the element tree stable.
       return fromCache;
     })
     .filter(Boolean) as ResolvedSegment[];

package/src/browser/segment-structure-assert.ts

@@ -48,7 +48,7 @@ export function assertSegmentStructure(
 
   if (cachedCategory !== incomingCategory) {
     console.warn(
-      `[RSC Router] Tree structure mismatch detected in ${context} ` +
+      `[Rango] Tree structure mismatch detected in ${context} ` +
         `for segment "${cached.id}": loading category changed from ` +
         `"${cachedCategory}" (${describeLoading(cached.loading)}) to ` +
         `"${incomingCategory}" (${describeLoading(incoming.loading)}). ` +
@@ -64,7 +64,7 @@ export function assertSegmentStructure(
   const incomingHasMount = !!incoming.mountPath;
   if (cachedHasMount !== incomingHasMount) {
     console.warn(
-      `[RSC Router] MountContextProvider mismatch detected in ${context} ` +
+      `[Rango] MountContextProvider mismatch detected in ${context} ` +
         `for segment "${cached.id}": mountPath changed from ` +
         `${cachedHasMount ? `"${cached.mountPath}"` : "undefined"} to ` +
         `${incomingHasMount ? `"${incoming.mountPath}"` : "undefined"}. ` +