@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.26

package/src/browser/rsc-router.tsx

@@ -11,12 +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,
@@ -26,6 +21,11 @@ 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 {
+  isInterceptSegment,
+  splitInterceptSegments,
+} from "./intercept-utils.js";
 
 // Vite HMR types are provided by vite/client
 
@@ -110,6 +110,8 @@ export interface BrowserAppContext {
   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
@@ -166,16 +168,6 @@ 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,
-    initialPayload.metadata?.params,
-  );
-
-  // 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);
 
@@ -191,12 +183,11 @@ export async function initBrowserApp(
     for await (const handleData of handlesGenerator) {
       lastHandleData = handleData;
     }
-    // Initialize both event controller AND module-level SSR state for hydration compatibility
+    // Initialize event controller with initial handle state before hydration.
     eventController.setHandleData(
       lastHandleData,
       initialPayload.metadata?.matched,
     );
-    initHandleDataSync(lastHandleData, initialPayload.metadata?.matched);
 
     // Update the initial cache entry with the processed handleData
     // The cache entry was created by createNavigationStore but without handleData
@@ -210,6 +201,10 @@ export async function initBrowserApp(
   const rootLayout = initialPayload.metadata?.rootLayout;
   const version = initialPayload.metadata?.version;
 
+  // Initialize the localStorage state key for browser HTTP cache invalidation.
+  // Uses the build version so a new deploy automatically busts all cached prefetches.
+  initRangoState(version ?? "0");
+
   // Create a bound renderSegments that includes rootLayout
   const renderSegments = (
     segments: ResolvedSegment[],
@@ -270,11 +265,14 @@ 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,
         });
 
@@ -282,10 +280,22 @@ export async function initBrowserApp(
           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(
@@ -294,18 +304,22 @@ export async function initBrowserApp(
             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");
     });
   }
 
@@ -319,6 +333,7 @@ export async function initBrowserApp(
     themeConfig: effectiveThemeConfig,
     initialTheme: effectiveInitialTheme,
     warmupEnabled: initialPayload.metadata?.warmupEnabled ?? true,
+    version,
   };
   browserAppContext = context;
 
@@ -383,8 +398,16 @@ export function RSCRouter(_props: RSCRouterProps): React.ReactElement {
     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}
@@ -394,6 +417,7 @@ export function RSCRouter(_props: RSCRouterProps): React.ReactElement {
       themeConfig={themeConfig}
       initialTheme={initialTheme}
       warmupEnabled={warmupEnabled}
+      version={version}
     />
   );
 }

package/src/browser/scroll-restoration.ts

@@ -8,6 +8,8 @@
  * - Supports hash link scrolling
  */
 
+import { debugLog } from "./logging.js";
+
 const SCROLL_STORAGE_KEY = "rsc-router-scroll-positions";
 
 /**
@@ -139,12 +141,13 @@ export function initScrollRestoration(options?: {
 
   window.addEventListener("pagehide", handlePageHide);
 
-  console.log(
+  debugLog(
     "[Scroll] Initialized, loaded positions:",
     Object.keys(savedScrollPositions).length,
   );
 
   return () => {
+    cancelScrollRestorationPolling();
     window.removeEventListener("pagehide", handlePageHide);
     window.history.scrollRestoration = "auto";
     initialized = false;
@@ -267,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?.()) {
@@ -282,14 +285,14 @@ 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;
       }
@@ -299,7 +302,7 @@ export function restoreScrollPosition(options?: {
         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);
@@ -322,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) {