@rangojs/router 0.0.0-experimental.3 → 0.0.0-experimental.30

package/src/browser/rsc-router.tsx

@@ -11,8 +11,7 @@ import { createEventController } from "./event-controller.js";
 import { createNavigationClient } from "./navigation-client.js";
 import { createServerActionBridge } from "./server-action-bridge.js";
 import { createNavigationBridge } from "./navigation-bridge.js";
-import { NavigationProvider, initHandleDataSync, initSegmentsSync } from "./react/index.js";
-import { initThemeConfigSync } from "../theme/theme-context.js";
+import { NavigationProvider } from "./react/index.js";
 import type {
   RscPayload,
   RscBrowserDependencies,
@@ -22,6 +21,12 @@ import type {
 } from "./types.js";
 import type { EventController } from "./event-controller.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
+import { initRangoState } from "./rango-state.js";
+import { initPrefetchCache } from "./prefetch/cache.js";
+import {
+  isInterceptSegment,
+  splitInterceptSegments,
+} from "./intercept-utils.js";
 
 // Vite HMR types are provided by vite/client
 
@@ -104,6 +109,10 @@ export interface BrowserAppContext {
   themeConfig?: ResolvedThemeConfig | null;
   /** Initial theme from server */
   initialTheme?: Theme;
+  /** Whether connection warmup is enabled */
+  warmupEnabled?: boolean;
+  /** App version for prefetch version mismatch detection */
+  version?: string;
 }
 
 // Module-level state for the initialized app
@@ -119,9 +128,16 @@ let browserAppContext: BrowserAppContext | null = null;
  * - Configures HMR support
  */
 export async function initBrowserApp(
-  options: InitBrowserAppOptions
+  options: InitBrowserAppOptions,
 ): Promise<BrowserAppContext> {
-  const { rscStream, deps, storeOptions, linkInterception = true, themeConfig, initialTheme } = options;
+  const {
+    rscStream,
+    deps,
+    storeOptions,
+    linkInterception = true,
+    themeConfig,
+    initialTheme,
+  } = options;
 
   // Load initial payload from SSR-injected __FLIGHT_DATA__
   const initialPayload =
@@ -129,8 +145,10 @@ export async function initBrowserApp(
 
   // Extract themeConfig and initialTheme from payload if not explicitly provided
   // This allows virtual entries to work without importing the router
-  const effectiveThemeConfig = themeConfig ?? initialPayload.metadata?.themeConfig ?? null;
-  const effectiveInitialTheme = initialTheme ?? initialPayload.metadata?.initialTheme;
+  const effectiveThemeConfig =
+    themeConfig ?? initialPayload.metadata?.themeConfig ?? null;
+  const effectiveInitialTheme =
+    initialTheme ?? initialPayload.metadata?.initialTheme;
 
   // Get initial segments and compute history key from current URL
   const initialSegments = (initialPayload.metadata?.segments ??
@@ -151,15 +169,12 @@ export async function initBrowserApp(
     initialLocation: new URL(window.location.href),
   });
 
-  // Initialize segments state BEFORE hydration to avoid mismatch
-  initSegmentsSync(initialPayload.metadata?.matched, initialPayload.metadata?.pathname);
-
-  // Initialize theme config for MetaTags (must match SSR state)
-  initThemeConfigSync(effectiveThemeConfig);
-
   // Initialize event controller with segment order (even without handles)
   eventController.setHandleData({}, initialPayload.metadata?.matched);
 
+  // Initialize route params
+  eventController.setParams(initialPayload.metadata?.params ?? {});
+
   // Initialize handle data from initial payload BEFORE hydration
   // This ensures useHandle returns correct data during hydration to avoid mismatch
   // The handles property is an async generator that yields on each push
@@ -169,16 +184,17 @@ export async function initBrowserApp(
     for await (const handleData of handlesGenerator) {
       lastHandleData = handleData;
     }
-    // Initialize both event controller AND module-level SSR state for hydration compatibility
-    eventController.setHandleData(lastHandleData, initialPayload.metadata?.matched);
-    initHandleDataSync(lastHandleData, initialPayload.metadata?.matched);
+    // Initialize event controller with initial handle state before hydration.
+    eventController.setHandleData(
+      lastHandleData,
+      initialPayload.metadata?.matched,
+    );
 
     // Update the initial cache entry with the processed handleData
     // The cache entry was created by createNavigationStore but without handleData
     store.updateCacheHandleData(initialHistoryKey, lastHandleData);
   }
 
-
   // Create composable utilities
   const client = createNavigationClient(deps);
 
@@ -186,12 +202,27 @@ export async function initBrowserApp(
   const rootLayout = initialPayload.metadata?.rootLayout;
   const version = initialPayload.metadata?.version;
 
+  // Initialize the localStorage state key for cache invalidation.
+  // Uses the build version so a new deploy automatically busts all cached prefetches.
+  initRangoState(version ?? "0");
+
+  // Initialize the in-memory prefetch cache TTL from server config.
+  // A value of 0 disables the cache; undefined falls back to the module default.
+  const prefetchCacheTTL = initialPayload.metadata?.prefetchCacheTTL;
+  if (prefetchCacheTTL !== undefined) {
+    initPrefetchCache(prefetchCacheTTL);
+  }
+
   // Create a bound renderSegments that includes rootLayout
   const renderSegments = (
     segments: ResolvedSegment[],
-    options?: RenderSegmentsOptions
+    options?: RenderSegmentsOptions,
   ) => baseRenderSegments(segments, { ...options, rootLayout });
 
+  // Lazy reference for navigation bridge — the action bridge is created first
+  // but may need to trigger SPA navigation for action redirects.
+  let navigateFn: ((url: string, options?: any) => Promise<void>) | null = null;
+
   // Setup server action bridge
   const actionBridge = createServerActionBridge({
     store,
@@ -201,6 +232,13 @@ export async function initBrowserApp(
     onUpdate: (update) => store.emitUpdate(update),
     renderSegments,
     version,
+    onNavigate: (url, options) => {
+      if (!navigateFn) {
+        window.location.href = url;
+        return Promise.resolve();
+      }
+      return navigateFn(url, options);
+    },
   });
   actionBridge.register();
 
@@ -214,6 +252,9 @@ export async function initBrowserApp(
     version,
   });
 
+  // Connect action redirect → navigation bridge (now that both are initialized)
+  navigateFn = (url, options) => navigationBridge.navigate(url, options);
+
   // Optionally enable global link interception
   if (linkInterception) {
     navigationBridge.registerLinkInterception();
@@ -232,37 +273,61 @@ export async function initBrowserApp(
       });
       const streamingToken = handle.startStreaming();
 
+      const interceptSourceUrl = store.getInterceptSourceUrl();
+
       try {
         const { payload, streamComplete } = await client.fetchPartial({
           targetUrl: window.location.href,
           segmentIds: [],
           previousUrl: store.getSegmentState().currentUrl,
+          interceptSourceUrl: interceptSourceUrl || undefined,
+          hmr: true,
         });
 
         if (payload.metadata?.isPartial) {
           const segments = payload.metadata.segments || [];
           const matched = payload.metadata.matched || [];
 
+          // Derive intercept state from the returned payload, not the
+          // pre-fetch store snapshot. If the HMR edit removed intercept
+          // behavior, the response won't contain intercept segments.
+          const responseIsIntercept = segments.some(isInterceptSegment);
+
+          // Sync store intercept state with what the server returned
+          if (!responseIsIntercept && interceptSourceUrl) {
+            store.setInterceptSourceUrl(null);
+          }
+
           store.setSegmentIds(matched);
           store.setCurrentUrl(window.location.href);
 
-          const historyKey = generateHistoryKey(window.location.href);
+          const historyKey = generateHistoryKey(window.location.href, {
+            intercept: responseIsIntercept,
+          });
           store.setHistoryKey(historyKey);
           const currentHandleData = eventController.getHandleState().data;
-          store.cacheSegmentsForHistory(historyKey, segments, currentHandleData);
+          store.cacheSegmentsForHistory(
+            historyKey,
+            segments,
+            currentHandleData,
+          );
 
+          const { main, intercept } = splitInterceptSegments(segments);
           store.emitUpdate({
-            root: renderSegments(segments),
+            root: renderSegments(main, {
+              interceptSegments: intercept.length > 0 ? intercept : undefined,
+            }),
             metadata: payload.metadata,
           });
         }
 
         await streamComplete;
+        handle.complete(new URL(window.location.href));
+        console.log("[RSCRouter] HMR: RSC stream complete");
       } finally {
         streamingToken.end();
+        handle[Symbol.dispose]();
       }
-      handle.complete(new URL(window.location.href));
-      console.log("[RSCRouter] HMR: RSC stream complete");
     });
   }
 
@@ -275,6 +340,8 @@ export async function initBrowserApp(
     initialTree,
     themeConfig: effectiveThemeConfig,
     initialTheme: effectiveInitialTheme,
+    warmupEnabled: initialPayload.metadata?.warmupEnabled ?? true,
+    version,
   };
   browserAppContext = context;
 
@@ -287,7 +354,7 @@ export async function initBrowserApp(
 export function getBrowserAppContext(): BrowserAppContext {
   if (!browserAppContext) {
     throw new Error(
-      "RSCRouter: initBrowserApp() must be called before rendering RSCRouter"
+      "RSCRouter: initBrowserApp() must be called before rendering RSCRouter",
     );
   }
   return browserAppContext;
@@ -330,17 +397,35 @@ export interface RSCRouterProps {}
  * ```
  */
 export function RSCRouter(_props: RSCRouterProps): React.ReactElement {
-  const { store, eventController, bridge, initialPayload, initialTree, themeConfig, initialTheme } =
-    getBrowserAppContext();
+  const {
+    store,
+    eventController,
+    bridge,
+    initialPayload,
+    initialTree,
+    themeConfig,
+    initialTheme,
+    warmupEnabled,
+    version,
+  } = getBrowserAppContext();
+
+  // Signal that the React tree has hydrated. useEffect only fires after
+  // hydration completes, so this attribute is a stable readiness marker
+  // that does not depend on React internals like __reactFiber.
+  React.useEffect(() => {
+    document.documentElement.dataset.hydrated = "";
+  }, []);
 
   return (
     <NavigationProvider
       store={store}
       eventController={eventController}
-      initialPayload={{ ...initialPayload, root: initialTree }}
+      initialPayload={{ root: initialTree, metadata: initialPayload.metadata! }}
       bridge={bridge}
       themeConfig={themeConfig}
       initialTheme={initialTheme}
+      warmupEnabled={warmupEnabled}
+      version={version}
     />
   );
 }

package/src/browser/scroll-restoration.ts

@@ -8,8 +8,18 @@
  * - Supports hash link scrolling
  */
 
+import { debugLog } from "./logging.js";
+
 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 +39,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 +54,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 +119,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 +141,82 @@ export function initScrollRestoration(options?: {
 
   window.addEventListener("pagehide", handlePageHide);
 
-  console.log("[Scroll] Initialized, loaded positions:", Object.keys(savedScrollPositions).length);
+  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 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));
+    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
+      }
+    }
   }
 }
 
@@ -195,13 +270,13 @@ export function restoreScrollPosition(options?: {
 
   if (canScrollToPosition) {
     window.scrollTo(0, savedY);
-    console.log("[Scroll] Restored position:", savedY, "for key:", key);
+    debugLog("[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);
+  debugLog("[Scroll] Partial restore to:", maxScrollY, "target:", savedY);
 
   // Poll while streaming until we can scroll to target position
   if (options?.retryIfStreaming && options?.isStreaming?.()) {
@@ -210,23 +285,24 @@ export function restoreScrollPosition(options?: {
     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");
+        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;
+      const currentMaxScrollY =
+        document.documentElement.scrollHeight - window.innerHeight;
       if (savedY <= currentMaxScrollY) {
         window.scrollTo(0, savedY);
-        console.log("[Scroll] Poll restored position:", savedY);
+        debugLog("[Scroll] Poll restored position:", savedY);
         cancelScrollRestorationPolling();
       }
     }, SCROLL_POLL_INTERVAL_MS);
@@ -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) {