@rangojs/router 0.0.0-experimental.002d056c

package/src/browser/scroll-restoration.ts

@@ -0,0 +1,397 @@
+/**
+ * Scroll Restoration Module
+ *
+ * Provides scroll position persistence across navigations, following React Router v7 patterns:
+ * - Saves scroll positions to sessionStorage keyed by unique history entry key
+ * - Restores scroll on back/forward navigation
+ * - Scrolls to top on new navigation (unless scroll: false)
+ * - Supports hash link scrolling
+ */
+
+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";
+
+/**
+ * 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,
+ * keep trying at this interval.
+ */
+const SCROLL_POLL_INTERVAL_MS = 50;
+
+/**
+ * Maximum time to keep polling for scroll restoration (ms).
+ * After this timeout, stop trying even if streaming continues.
+ */
+const SCROLL_POLL_TIMEOUT_MS = 5000;
+
+/**
+ * In-memory cache of scroll positions.
+ * Synced with sessionStorage on pagehide.
+ */
+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
+ */
+let initialized = false;
+
+/**
+ * Custom getKey function for determining scroll restoration key
+ */
+type GetScrollKeyFunction = (location: {
+  pathname: string;
+  search: string;
+  hash: string;
+  key: string;
+}) => string;
+
+let customGetKey: GetScrollKeyFunction | null = null;
+
+/**
+ * Generate a unique key for the current history entry.
+ * Uses history.state.key if available, otherwise generates and stores a new one.
+ */
+export function getHistoryStateKey(): string {
+  const state = window.history.state;
+  if (state?.key) {
+    return state.key;
+  }
+
+  // Generate a new key and store it in history.state
+  const key = Math.random().toString(36).slice(2, 10);
+  window.history.replaceState({ ...state, key }, "");
+  return key;
+}
+
+/**
+ * Get the scroll restoration key for a location.
+ * Uses custom getKey function if set, otherwise uses history state key.
+ */
+export function getScrollKey(): string {
+  if (customGetKey) {
+    const loc = window.location;
+    return customGetKey({
+      pathname: loc.pathname,
+      search: loc.search,
+      hash: loc.hash,
+      key: getHistoryStateKey(),
+    });
+  }
+  return getHistoryStateKey();
+}
+
+/**
+ * Initialize scroll restoration.
+ * Sets manual scroll restoration mode and loads saved positions from sessionStorage.
+ */
+export function initScrollRestoration(options?: {
+  getKey?: GetScrollKeyFunction;
+}): () => void {
+  if (initialized) {
+    console.warn("[Scroll] Already initialized");
+    return () => {};
+  }
+
+  initialized = true;
+  customGetKey = options?.getKey ?? null;
+
+  // Set manual scroll restoration to prevent browser's default behavior
+  window.history.scrollRestoration = "manual";
+
+  // Load saved positions from sessionStorage
+  try {
+    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, start with empty state
+  }
+
+  // Ensure current history entry has a key
+  getHistoryStateKey();
+
+  // Save scroll positions on pagehide (before leaving/refreshing)
+  const handlePageHide = () => {
+    saveCurrentScrollPosition();
+    persistToSessionStorage();
+    // Reset to auto for browser to handle if page is restored from bfcache
+    window.history.scrollRestoration = "auto";
+  };
+
+  window.addEventListener("pagehide", handlePageHide);
+
+  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.
+ * 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.
+ * If the write fails due to quota exceeded, progressively evict the oldest
+ * entries and retry until it succeeds or the store is empty.
+ */
+function persistToSessionStorage(): void {
+  try {
+    sessionStorage.setItem(
+      SCROLL_STORAGE_KEY,
+      JSON.stringify(savedScrollPositions),
+    );
+  } catch (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
+      }
+    }
+  }
+}
+
+/**
+ * Get the saved scroll position for a history key
+ */
+export function getSavedScrollPosition(key?: string): number | undefined {
+  const lookupKey = key ?? getScrollKey();
+  return savedScrollPositions[lookupKey];
+}
+
+/**
+ * Pending poll interval for scroll restoration during streaming
+ */
+let pendingPollInterval: ReturnType<typeof setInterval> | null = null;
+
+/**
+ * Cancel any pending scroll restoration polling
+ */
+export function cancelScrollRestorationPolling(): void {
+  if (pendingPollInterval) {
+    clearInterval(pendingPollInterval);
+    pendingPollInterval = null;
+  }
+}
+
+/**
+ * Restore scroll position for the current history entry.
+ * Returns true if position was fully restored, false otherwise.
+ *
+ * @param options.retryIfStreaming - If true, poll while streaming until we can scroll to target
+ * @param options.isStreaming - Function to check if streaming is in progress
+ */
+export function restoreScrollPosition(options?: {
+  retryIfStreaming?: boolean;
+  isStreaming?: () => boolean;
+}): boolean {
+  // Clear any pending polling
+  cancelScrollRestorationPolling();
+
+  const key = getScrollKey();
+  const savedY = savedScrollPositions[key];
+
+  if (typeof savedY !== "number") {
+    return false;
+  }
+
+  // If streaming, poll until streaming ends then scroll to saved position
+  if (options?.retryIfStreaming && options?.isStreaming?.()) {
+    const startTime = Date.now();
+
+    pendingPollInterval = setInterval(() => {
+      if (Date.now() - startTime > SCROLL_POLL_TIMEOUT_MS) {
+        debugLog("[Scroll] Polling timeout, giving up");
+        cancelScrollRestorationPolling();
+        return;
+      }
+
+      if (!options.isStreaming?.()) {
+        window.scrollTo(0, savedY);
+        debugLog("[Scroll] Restored after streaming:", savedY);
+        cancelScrollRestorationPolling();
+      }
+    }, SCROLL_POLL_INTERVAL_MS);
+
+    return true;
+  }
+
+  // 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;
+}
+
+/**
+ * Handle hash link scrolling.
+ * Scrolls to element with matching ID if hash is present.
+ * Returns true if scrolled to element, false otherwise.
+ */
+export function scrollToHash(): boolean {
+  const hash = window.location.hash;
+  if (!hash) return false;
+
+  try {
+    const id = decodeURIComponent(hash.slice(1));
+    const element = document.getElementById(id);
+    if (element) {
+      element.scrollIntoView();
+      debugLog("[Scroll] Scrolled to hash element:", id);
+      return true;
+    }
+  } catch (e) {
+    console.warn("[Scroll] Failed to decode hash:", hash);
+  }
+
+  return false;
+}
+
+/**
+ * Scroll to top of page
+ */
+export function scrollToTop(): void {
+  window.scrollTo(0, 0);
+}
+
+/**
+ * Handle scroll for a new navigation.
+ * - Saves current position before navigating
+ * - Ensures new history entry has a key
+ */
+export function handleNavigationStart(): void {
+  if (!initialized) return;
+  saveCurrentScrollPosition();
+}
+
+/**
+ * Handle scroll after navigation completes.
+ * @param options.restore - If true, restore saved position (for popstate)
+ * @param options.scroll - If false, don't scroll at all
+ * @param options.isStreaming - Function to check if streaming is in progress (for retry logic)
+ */
+export function handleNavigationEnd(options: {
+  restore?: boolean;
+  scroll?: boolean;
+  isStreaming?: () => boolean;
+}): void {
+  if (!initialized) {
+    return;
+  }
+
+  const { restore = false, scroll = true, isStreaming } = options;
+
+  // Don't scroll if explicitly disabled
+  if (scroll === false) {
+    return;
+  }
+
+  // For back/forward (restore), try to restore saved position
+  if (restore) {
+    if (restoreScrollPosition({ retryIfStreaming: true, isStreaming })) {
+      return;
+    }
+    // Fall through to hash or top if no saved position
+  }
+
+  // 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();
+  });
+}
+
+/**
+ * Update the history state key after pushState/replaceState.
+ * Call this after changing history to ensure new entry has a key.
+ */
+export function ensureHistoryKey(): void {
+  getHistoryStateKey();
+}

package/src/browser/segment-reconciler.ts

@@ -0,0 +1,216 @@
+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";
+
+/**
+ * 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 segments = matched
+    .map((segId: string) => {
+      const fromServer = serverSegments.get(segId);
+      const fromCache = cachedSegments.get(segId);
+
+      if (fromServer) {
+        // Merge partial loader data when server returns fewer loaders than cached
+        if (shouldMergeLoaders && needsLoaderMerge(fromServer, fromCache)) {
+          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);
+
+          return merged;
+        }
+        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;
+      }
+
+      // 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 };
+        }
+      }
+
+      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

@@ -0,0 +1,83 @@
+import type { ResolvedSegment } from "./types.js";
+
+/**
+ * Tree structure categories for the `loading` property.
+ *
+ * The `loading` value on a segment determines the React element tree
+ * that renderSegments() produces. Different categories produce different
+ * element nesting, which causes React to remount components when the
+ * category changes between renders (SSR -> navigation -> action).
+ *
+ * "none"       -> OutletProvider (no boundary wrapping)
+ * "suppressed" -> LoaderBoundary > Suspense > LoaderResolver > OutletProvider
+ *                 (boundary present, but no RouteContentWrapper for children)
+ * "active"     -> LoaderBoundary > Suspense > LoaderResolver > OutletProvider
+ *                 > RouteContentWrapper > Suspense > Suspender > component
+ */
+type LoadingCategory = "none" | "suppressed" | "active";
+
+function getLoadingCategory(loading: unknown): LoadingCategory {
+  if (loading === undefined || loading === null) return "none";
+  if (loading === false) return "suppressed";
+  return "active";
+}
+
+/**
+ * Assert that merging a server segment with a cached segment won't change
+ * the React tree structure. Logs a warning in development when a mismatch
+ * is detected.
+ *
+ * This catches the class of bugs where `loading()` with `{ ssr: false }`
+ * produces `loading=false` on SSR but `loading=<skeleton>` on actions,
+ * causing React to remount LoaderBoundary/RouteContentWrapper and destroy
+ * client state (useActionState, refs, etc.).
+ *
+ * @param cached - The currently cached segment
+ * @param incoming - The new segment from server
+ * @param context - Where this merge is happening (for the warning message)
+ */
+export function assertSegmentStructure(
+  cached: ResolvedSegment,
+  incoming: ResolvedSegment,
+  context: string,
+): void {
+  if (process.env.NODE_ENV === "production") return;
+
+  const cachedCategory = getLoadingCategory(cached.loading);
+  const incomingCategory = getLoadingCategory(incoming.loading);
+
+  if (cachedCategory !== incomingCategory) {
+    console.warn(
+      `[RSC Router] Tree structure mismatch detected in ${context} ` +
+        `for segment "${cached.id}": loading category changed from ` +
+        `"${cachedCategory}" (${describeLoading(cached.loading)}) to ` +
+        `"${incomingCategory}" (${describeLoading(incoming.loading)}). ` +
+        `This will cause React to remount the component, destroying ` +
+        `useActionState and other client state. ` +
+        `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(
+      `[RSC Router] 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 {
+  if (loading === undefined) return "undefined";
+  if (loading === null) return "null";
+  if (loading === false) return "false";
+  return "ReactNode";
+}