@rangojs/router 0.0.0-experimental.15 → 0.0.0-experimental.151

package/src/browser/scroll-restoration.ts

@@ -8,8 +8,27 @@
  * - Supports hash link scrolling
  */
 
+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";
 
+/**
+ * Maximum number of scroll position entries to retain.
+ * When exceeded, the oldest entries (by insertion order) are evicted.
+ * 200 entries is well within sessionStorage limits while covering
+ * realistic back/forward navigation depth.
+ */
+const MAX_SCROLL_ENTRIES = 200;
+
 /**
  * Interval for polling scroll restoration during streaming (ms).
  * If content is still loading and we can't scroll to saved position,
@@ -29,6 +48,13 @@ const SCROLL_POLL_TIMEOUT_MS = 5000;
  */
 let savedScrollPositions: Record<string, number> = {};
 
+/**
+ * Tracks insertion order of scroll position keys for LRU eviction.
+ * Most recent entries are at the end of the array.
+ * When a key is updated, it is moved to the end.
+ */
+let scrollKeyOrder: string[] = [];
+
 /**
  * Whether scroll restoration has been initialized
  */
@@ -37,9 +63,12 @@ let initialized = false;
 /**
  * Custom getKey function for determining scroll restoration key
  */
-type GetScrollKeyFunction = (
-  location: { pathname: string; search: string; hash: string; key: string }
-) => string;
+type GetScrollKeyFunction = (location: {
+  pathname: string;
+  search: string;
+  hash: string;
+  key: string;
+}) => string;
 
 let customGetKey: GetScrollKeyFunction | null = null;
 
@@ -99,9 +128,13 @@ export function initScrollRestoration(options?: {
     const stored = sessionStorage.getItem(SCROLL_STORAGE_KEY);
     if (stored) {
       savedScrollPositions = JSON.parse(stored);
+      // Rebuild key order from loaded positions.
+      // Exact original order is lost across page loads, but this is
+      // acceptable -- the important invariant is bounded size.
+      scrollKeyOrder = Object.keys(savedScrollPositions);
     }
   } catch (e) {
-    // Ignore parse errors
+    // Ignore parse errors, start with empty state
   }
 
   // Ensure current history entry has a key
@@ -117,31 +150,89 @@ export function initScrollRestoration(options?: {
 
   window.addEventListener("pagehide", handlePageHide);
 
-  console.log("[Scroll] Initialized, loaded positions:", Object.keys(savedScrollPositions).length);
+  if (IS_BROWSER_DEBUG) {
+    debugLog(
+      "[Scroll] Initialized, loaded positions:",
+      Object.keys(savedScrollPositions).length,
+    );
+  }
 
   return () => {
+    cancelScrollRestorationPolling();
     window.removeEventListener("pagehide", handlePageHide);
     window.history.scrollRestoration = "auto";
     initialized = false;
+    savedScrollPositions = {};
+    scrollKeyOrder = [];
   };
 }
 
 /**
- * Save the current scroll position for the current history entry
+ * Save the current scroll position for the current history entry.
+ * Maintains bounded size by evicting oldest entries when the limit is exceeded.
  */
 export function saveCurrentScrollPosition(): void {
   const key = getScrollKey();
+
+  // If this key already exists, remove it from its current position
+  // in the order array so it can be re-appended at the end (most recent).
+  const existingIndex = scrollKeyOrder.indexOf(key);
+  if (existingIndex !== -1) {
+    scrollKeyOrder.splice(existingIndex, 1);
+  }
+
   savedScrollPositions[key] = window.scrollY;
+  scrollKeyOrder.push(key);
+
+  // Evict oldest entries if we exceed the limit
+  while (scrollKeyOrder.length > MAX_SCROLL_ENTRIES) {
+    const oldestKey = scrollKeyOrder.shift()!;
+    delete savedScrollPositions[oldestKey];
+  }
 }
 
 /**
- * Persist scroll positions to sessionStorage
+ * Persist scroll positions to sessionStorage.
+ * 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, JSON.stringify(savedScrollPositions));
+    sessionStorage.setItem(
+      SCROLL_STORAGE_KEY,
+      JSON.stringify(savedScrollPositions),
+    );
   } catch (e) {
-    console.warn("[Scroll] Failed to persist to sessionStorage:", e);
+    // Likely QuotaExceededError. Evict oldest entries and retry.
+    const evictCount = Math.max(1, Math.floor(scrollKeyOrder.length / 4));
+    for (let i = 0; i < evictCount && scrollKeyOrder.length > 0; i++) {
+      const oldestKey = scrollKeyOrder.shift()!;
+      delete savedScrollPositions[oldestKey];
+    }
+
+    try {
+      sessionStorage.setItem(
+        SCROLL_STORAGE_KEY,
+        JSON.stringify(savedScrollPositions),
+      );
+    } catch (retryErr) {
+      // Storage still full after eviction. Clear our key entirely so we
+      // don't block other sessionStorage consumers.
+      console.warn(
+        "[Scroll] Failed to persist to sessionStorage after eviction, clearing scroll data:",
+        retryErr,
+      );
+      try {
+        sessionStorage.removeItem(SCROLL_STORAGE_KEY);
+      } catch {
+        // Nothing more we can do
+      }
+    }
   }
 }
 
@@ -189,50 +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);
-    console.log("[Scroll] Restored position:", savedY, "for key:", key);
-    return true;
-  }
-
-  // Scroll as far as we can for now
-  window.scrollTo(0, maxScrollY);
-  console.log("[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) {
-        console.log("[Scroll] Polling timeout, giving up");
+        debugLog("[Scroll] Polling timeout, giving up");
         cancelScrollRestorationPolling();
         return;
       }
 
-      // Stop if streaming ended
       if (!options.isStreaming?.()) {
-        console.log("[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);
-        console.log("[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;
 }
 
 /**
@@ -249,7 +325,7 @@ export function scrollToHash(): boolean {
     const element = document.getElementById(id);
     if (element) {
       element.scrollIntoView();
-      console.log("[Scroll] Scrolled to hash element:", id);
+      debugLog("[Scroll] Scrolled to hash element:", id);
       return true;
     }
   } catch (e) {
@@ -263,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);
 }
 
@@ -287,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

@@ -0,0 +1,253 @@
+import type { ResolvedSegment } from "./types.js";
+import {
+  mergeSegmentLoaders,
+  needsLoaderMerge,
+  insertMissingDiffSegments,
+} 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.
+ *
+ * - 'action': From server-action-bridge's own merge. Always merges loaders,
+ *   always preserves cached loading (even undefined), never clears cached
+ *   segment loading.
+ * - 'navigation': From partial-update during normal navigation. Does NOT merge
+ *   loaders, preserves cached loading only when defined, clears truthy loading
+ *   on cached segments not in server diff.
+ * - 'stale-revalidation': From partial-update during stale revalidation or
+ *   action-triggered refetch. Merges loaders, always preserves cached loading
+ *   (same as action), clears truthy loading on cached segments not in server diff.
+ */
+export type ReconcileActor = "navigation" | "action" | "stale-revalidation";
+
+export interface ReconcileInput {
+  actor: ReconcileActor;
+  /** All segment IDs the server expects the client to have (matched array) */
+  matched: string[];
+  /** Segment IDs that changed (diff array) */
+  diff: string[];
+  /** Segments returned from server (raw array, keyed internally by ID) */
+  serverSegments: ResolvedSegment[];
+  /** Cached segments from current page (raw array, keyed internally by ID) */
+  cachedSegments: ResolvedSegment[];
+  /** When true, diff segments not in matched are inserted after their parent
+   *  layout. Used during navigation when consolidation fetch returns loader
+   *  segments that aren't in the matched array. */
+  insertMissingDiff?: boolean;
+}
+
+export interface ReconcileResult {
+  /** All merged segments in matched order (for caching and committing) */
+  segments: ResolvedSegment[];
+  /** Main segments excluding intercepts (for rendering) */
+  mainSegments: ResolvedSegment[];
+  /** Intercept segments only (passed via render options) */
+  interceptSegments: ResolvedSegment[];
+}
+
+/**
+ * Single source of truth for merging server segments with cached segments.
+ *
+ * Replaces the duplicated merge loops in server-action-bridge.ts and
+ * partial-update.ts. The actor parameter controls the subtle behavioral
+ * differences between action and navigation merging:
+ *
+ * Loading preservation:
+ * - action/stale-revalidation: Always preserves cached loading value when it
+ *   differs from server (even when cached is undefined). This prevents tree
+ *   structure changes that would remount components and destroy useActionState
+ *   during action revalidation or action-triggered refetch.
+ * - navigation: Preserves cached loading only when the cached value is defined
+ *   (not undefined). When cached is undefined, lets server value through
+ *   because we're building a new tree.
+ *
+ * Loader merging:
+ * - action/stale-revalidation: Merges partial loader data when server returns
+ *   fewer loaders than cached (revalidation only updated some loaders).
+ * - navigation: Does not merge (full navigation fetches complete data).
+ *
+ * Cached segment handling (segments in matched but not in server response):
+ * - action: Returns cached segment as-is (preserve tree structure).
+ * - navigation/stale-revalidation: Clears truthy loading to undefined
+ *   (prevents showing stale skeletons), but preserves loading=false
+ *   (suppressed boundary is structural).
+ */
+export function reconcileSegments(input: ReconcileInput): ReconcileResult {
+  const { actor, matched, diff, insertMissingDiff } = input;
+  const shouldMergeLoaders = actor !== "navigation";
+  const context = actor === "action" ? "action-bridge" : "partial-update";
+
+  // Build lookup maps from arrays
+  const serverSegments = new Map<string, ResolvedSegment>();
+  input.serverSegments.forEach((s) => serverSegments.set(s.id, s));
+  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);
+        }
+
+        // Preserve cached structural properties to maintain consistent React tree.
+        // Changing these between renders alters the element nesting
+        // (with/without RouteContentWrapper, MountContextProvider, etc.),
+        // causing React to remount components and destroy useActionState.
+        if (fromCache) {
+          let merged = fromServer;
+
+          // When server returns component: null for a layout segment, it means
+          // "this segment doesn't need re-rendering" - preserve the cached component
+          // to maintain the outlet chain and prevent React tree changes
+          if (
+            fromServer.component === null &&
+            fromServer.type === "layout" &&
+            fromCache.component != null
+          ) {
+            merged = { ...merged, component: fromCache.component };
+          }
+
+          // Loading preservation is actor-aware:
+          // - action/stale-revalidation: always preserve cached value to prevent
+          //   tree remount (even when cached is undefined, to avoid adding a
+          //   Suspense boundary that wasn't there before)
+          // - navigation: only when cached is defined (building a new tree)
+          if (actor !== "navigation") {
+            if (fromServer.loading !== fromCache.loading) {
+              merged = { ...merged, loading: fromCache.loading };
+            }
+          } else {
+            if (
+              fromCache.loading !== undefined &&
+              fromServer.loading !== fromCache.loading
+            ) {
+              merged = { ...merged, loading: fromCache.loading };
+            }
+          }
+
+          // mountPath: SSR segments may lack mountPath while revalidated segments
+          // include it. The conditional MountContextProvider wrapper changes tree depth.
+          if (fromServer.mountPath !== fromCache.mountPath) {
+            merged = { ...merged, mountPath: fromCache.mountPath };
+          }
+
+          // Dev-mode assertion: warn if the merged result still differs from cache
+          // in tree-structural properties. This catches bugs where the merge code
+          // 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;
+      }
+
+      // Fall back to cached segment (server expects client to already have it)
+      if (!fromCache) {
+        if (actor === "action") {
+          console.error(`[Browser] MISSING SEGMENT: ${segId} not in cache!`);
+        } else {
+          console.warn(`[Browser] Missing segment: ${segId}`);
+        }
+        return fromCache;
+      }
+
+      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[];
+
+  // Insert diff segments not in matched (e.g., loader segments from consolidation fetch).
+  // Only needed during navigation - action bridge doesn't use this.
+  if (insertMissingDiff) {
+    const matchedIdSet = new Set(matched);
+    insertMissingDiffSegments(segments, diff, matchedIdSet, serverSegments);
+  }
+
+  const { main, intercept } = splitInterceptSegments(segments);
+
+  return {
+    segments,
+    mainSegments: main,
+    interceptSegments: intercept,
+  };
+}
+
+/**
+ * Reconcile error segments with cached segments.
+ *
+ * For error responses, the server returns the error boundary segment.
+ * This function overlays error segments onto the full cached tree,
+ * preserving sibling layouts that aren't in the error parent chain.
+ */
+export function reconcileErrorSegments(
+  cachedSegments: ResolvedSegment[],
+  errorSegments: ResolvedSegment[],
+): ReconcileResult {
+  const errorMap = new Map<string, ResolvedSegment>();
+  errorSegments.forEach((s) => errorMap.set(s.id, s));
+
+  const segments = cachedSegments.map((cached) => {
+    const fromServer = errorMap.get(cached.id);
+    return fromServer || cached;
+  });
+
+  const { main, intercept } = splitInterceptSegments(segments);
+
+  return {
+    segments,
+    mainSegments: main,
+    interceptSegments: intercept,
+  };
+}

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)}). ` +
@@ -57,6 +57,22 @@ export function assertSegmentStructure(
         `The merge code should preserve the cached loading value.`,
     );
   }
+
+  // Check mountPath consistency. MountContextProvider is conditionally added
+  // in renderSegments() when mountPath is truthy, changing tree depth.
+  const cachedHasMount = !!cached.mountPath;
+  const incomingHasMount = !!incoming.mountPath;
+  if (cachedHasMount !== incomingHasMount) {
+    console.warn(
+      `[Rango] MountContextProvider mismatch detected in ${context} ` +
+        `for segment "${cached.id}": mountPath changed from ` +
+        `${cachedHasMount ? `"${cached.mountPath}"` : "undefined"} to ` +
+        `${incomingHasMount ? `"${incoming.mountPath}"` : "undefined"}. ` +
+        `This will cause React to remount the component, destroying ` +
+        `useActionState and other client state. ` +
+        `The merge code should preserve the cached mountPath value.`,
+    );
+  }
 }
 
 function describeLoading(loading: unknown): string {