@rangojs/router 0.0.0-experimental.5 → 0.0.0-experimental.50

package/src/browser/react/use-segments.ts

@@ -2,6 +2,7 @@
 
 import { useContext, useState, useEffect, useRef } from "react";
 import { NavigationStoreContext } from "./context.js";
+import { shallowEqual } from "./shallow-equal.js";
 
 /**
  * Segments state returned by useSegments hook
@@ -15,65 +16,6 @@ export interface SegmentsState {
   location: URL;
 }
 
-/**
- * SSR module-level state.
- * Populated by initSegmentsSync before React renders.
- * Used by useState initializer during SSR.
- */
-let ssrSegmentOrder: string[] = [];
-let ssrPathname: string = "/";
-
-/**
- * Filter segment IDs to only include routes and layouts.
- * Excludes parallels (contain .@) and loaders (contain D followed by digit).
- */
-function filterSegmentOrder(matched: string[]): string[] {
-  return matched.filter((id) => {
-    if (id.includes(".@")) return false;
-    if (/D\d+\./.test(id)) return false;
-    return true;
-  });
-}
-
-/**
- * Initialize segments data synchronously for SSR.
- * Called before rendering to populate state for useState initializer.
- *
- * @param matched - Segment order from RSC metadata
- * @param pathname - Current pathname
- */
-export function initSegmentsSync(matched?: string[], pathname?: string): void {
-  ssrSegmentOrder = filterSegmentOrder(matched ?? []);
-  ssrPathname = pathname ?? "/";
-}
-
-/**
- * Shallow equality check for selector results
- */
-function shallowEqual<T>(a: T, b: T): boolean {
-  if (Object.is(a, b)) return true;
-  if (
-    typeof a !== "object" ||
-    a === null ||
-    typeof b !== "object" ||
-    b === null
-  ) {
-    return false;
-  }
-  const keysA = Object.keys(a);
-  const keysB = Object.keys(b);
-  if (keysA.length !== keysB.length) return false;
-  for (const key of keysA) {
-    if (
-      !Object.hasOwn(b, key) ||
-      !Object.is((a as any)[key], (b as any)[key])
-    ) {
-      return false;
-    }
-  }
-  return true;
-}
-
 /**
  * Parse pathname into path segments
  * /shop/products/123 → ["shop", "products", "123"]
@@ -87,7 +29,7 @@ function parsePathname(pathname: string): string[] {
  */
 function buildSegmentsState(
   location: URL,
-  segmentOrder: string[]
+  segmentOrder: string[],
 ): SegmentsState {
   return {
     path: parsePathname(location.pathname),
@@ -96,18 +38,6 @@ function buildSegmentsState(
   };
 }
 
-/**
- * Build SSR state from module-level variables
- */
-function buildSsrState(): SegmentsState {
-  const location = new URL(ssrPathname, "http://localhost");
-  return {
-    path: parsePathname(ssrPathname),
-    segmentIds: ssrSegmentOrder,
-    location,
-  };
-}
-
 /**
  * Hook to access current route segments with optional selector for performance
  *
@@ -127,62 +57,115 @@ function buildSsrState(): SegmentsState {
 export function useSegments(): SegmentsState;
 export function useSegments<T>(selector: (state: SegmentsState) => T): T;
 export function useSegments<T>(
-  selector?: (state: SegmentsState) => T
+  selector?: (state: SegmentsState) => T,
 ): T | SegmentsState {
   const ctx = useContext(NavigationStoreContext);
 
-  // Build initial state from SSR module state or event controller
+  // Build initial state from event controller when context exists.
+  // Inlined rather than calling recompute() because the segmentsCache ref
+  // is not yet initialized during the useState initializer.
   const [state, setState] = useState<T | SegmentsState>(() => {
-    // During SSR or when no context, use module-level SSR state
-    if (typeof document === "undefined" || !ctx) {
-      const ssrState = buildSsrState();
-      return selector ? selector(ssrState) : ssrState;
+    if (!ctx) {
+      const fallbackLocation = new URL("/", "http://localhost");
+      const fallbackState = buildSegmentsState(fallbackLocation, []);
+      return selector ? selector(fallbackState) : fallbackState;
     }
-    // On client with context, use event controller state
-    const navState = ctx.eventController.getState();
+    const location = ctx.eventController.getLocation();
     const handleState = ctx.eventController.getHandleState();
     const segmentsState = buildSegmentsState(
-      navState.location as URL,
-      handleState.segmentOrder
+      location as URL,
+      handleState.segmentOrder,
     );
     return selector ? selector(segmentsState) : segmentsState;
   });
 
   const prevState = useRef(state);
+  const selectorRef = useRef(selector);
+  selectorRef.current = selector;
+
+  // Track selector identity to detect when the selector function changes.
+  // Only then do we eagerly recompute during render to avoid staleness.
+  // Without this guard, no-selector mode causes infinite re-renders because
+  // buildSegmentsState creates fresh arrays that fail Object.is checks.
+  const prevSelectorIdentity = useRef(selector);
+
+  // Cache SegmentsState to stabilize nested references (path, segmentIds
+  // arrays) so selectors returning composite values don't cause spurious
+  // render-time setState calls.
+  const segmentsCache = useRef<{
+    location: URL;
+    segmentOrder: string[];
+    state: SegmentsState;
+  } | null>(null);
+
+  // Recompute selected value from current store state and apply selector.
+  // Shared by the render-time eager check and the subscription callback.
+  function recompute(
+    sel: ((state: SegmentsState) => T) | undefined,
+  ): T | SegmentsState {
+    const location = ctx!.eventController.getLocation();
+    const handleState = ctx!.eventController.getHandleState();
+
+    // Reuse cached state when inputs haven't changed by reference,
+    // keeping array/object references stable for composite selectors.
+    const cache = segmentsCache.current;
+    let segmentsState: SegmentsState;
+    if (
+      cache &&
+      cache.location === location &&
+      cache.segmentOrder === handleState.segmentOrder
+    ) {
+      segmentsState = cache.state;
+    } else {
+      segmentsState = buildSegmentsState(
+        location as URL,
+        handleState.segmentOrder,
+      );
+      segmentsCache.current = {
+        location: location as URL,
+        segmentOrder: handleState.segmentOrder,
+        state: segmentsState,
+      };
+    }
+    return sel ? sel(segmentsState) : segmentsState;
+  }
+
+  if (ctx && selector !== prevSelectorIdentity.current) {
+    prevSelectorIdentity.current = selector;
+    const nextSelected = recompute(selector);
+    if (!shallowEqual(nextSelected, prevState.current)) {
+      prevState.current = nextSelected;
+      setState(nextSelected);
+    }
+  }
 
-  // Subscribe to both navigation state and handle state changes
+  // Subscribe to store changes. The eager block above handles selector
+  // changes and SSR drift, so no initial updateState() call is needed.
   useEffect(() => {
     if (!ctx) {
       return;
     }
 
     const updateState = () => {
-      const navState = ctx.eventController.getState();
-      const handleState = ctx.eventController.getHandleState();
-      const segmentsState = buildSegmentsState(
-        navState.location as URL,
-        handleState.segmentOrder
-      );
-      const nextSelected = selector ? selector(segmentsState) : segmentsState;
-
+      const nextSelected = recompute(selectorRef.current);
       if (!shallowEqual(nextSelected, prevState.current)) {
         prevState.current = nextSelected;
         setState(nextSelected);
       }
     };
 
-    // Initial update in case SSR state differs from client state
-    updateState();
-
-    // Subscribe to both state sources
     const unsubscribeNav = ctx.eventController.subscribe(updateState);
-    const unsubscribeHandles = ctx.eventController.subscribeToHandles(updateState);
+    const unsubscribeHandles =
+      ctx.eventController.subscribeToHandles(updateState);
 
     return () => {
       unsubscribeNav();
       unsubscribeHandles();
     };
-  }, [selector]);
+    // Stable subscription: selector changes are handled via selectorRef,
+    // state comparison uses prevState ref. No re-subscribe needed.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
 
   return state as T | SegmentsState;
 }

package/src/browser/response-adapter.ts

@@ -0,0 +1,73 @@
+import { validateRedirectOrigin } from "./validate-redirect-origin.js";
+
+type HeaderResult = { url: string } | "blocked" | null;
+
+/**
+ * Extract and validate an RSC response header URL (X-RSC-Reload, X-RSC-Redirect).
+ * Returns { url } if valid, "blocked" if present but invalid origin, null if absent.
+ */
+export function extractRscHeaderUrl(
+  response: Response,
+  header: string,
+): HeaderResult {
+  const raw = response.headers.get(header);
+  if (!raw) return null;
+  const url = validateRedirectOrigin(raw, window.location.origin);
+  return url ? { url } : "blocked";
+}
+
+/**
+ * Empty 200 response that won't choke Flight parsing.
+ * Used when a header URL is blocked by origin validation.
+ */
+export function emptyResponse(): Response {
+  return new Response(null, { status: 200 });
+}
+
+/**
+ * Tee a response body for RSC parsing and stream completion tracking.
+ * Returns a new Response with one branch; the other is consumed to detect
+ * end-of-stream, calling onComplete when done.
+ *
+ * If the response has no body, onComplete fires synchronously.
+ * If signal is provided, an abort cancels the tracking reader.
+ */
+export function teeWithCompletion(
+  response: Response,
+  onComplete: () => void,
+  signal?: AbortSignal,
+): Response {
+  if (!response.body) {
+    onComplete();
+    return response;
+  }
+
+  const [rscStream, trackingStream] = response.body.tee();
+
+  (async () => {
+    const reader = trackingStream.getReader();
+    const onAbort = signal ? reader.cancel.bind(reader) : undefined;
+    if (onAbort) signal!.addEventListener("abort", onAbort, { once: true });
+    try {
+      while (true) {
+        const { done } = await reader.read();
+        if (done) break;
+      }
+    } finally {
+      if (onAbort) signal!.removeEventListener("abort", onAbort);
+      reader.releaseLock();
+      onComplete();
+    }
+  })().catch((error) => {
+    if (!signal?.aborted) {
+      console.error("[Browser] Error reading tracking stream:", error);
+    }
+    onComplete();
+  });
+
+  return new Response(rscStream, {
+    headers: response.headers,
+    status: response.status,
+    statusText: response.statusText,
+  });
+}

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
 
@@ -106,6 +111,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
@@ -121,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 =
@@ -131,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 ??
@@ -153,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
@@ -171,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);
 
@@ -188,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,
@@ -203,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();
 
@@ -216,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();
@@ -224,47 +263,123 @@ export async function initBrowserApp(
   // Build initial tree with rootLayout
   const initialTree = renderSegments(initialPayload.metadata!.segments);
 
-  // Setup HMR
+  // Setup HMR with debounce — burst saves (format-on-save, rapid edits)
+  // fire many rsc:update events in quick succession. Without debouncing,
+  // each event triggers a fetchPartial() which on slow routes can pile up
+  // and overwhelm the worker (cross-request promise issues, 500s).
   if (import.meta.hot) {
-    import.meta.hot.on("rsc:update", async () => {
-      console.log("[RSCRouter] HMR: Server update, refetching RSC");
-
-      const handle = eventController.startNavigation(window.location.href, {
-        replace: true,
-      });
-      const streamingToken = handle.startStreaming();
-
-      try {
-        const { payload, streamComplete } = await client.fetchPartial({
-          targetUrl: window.location.href,
-          segmentIds: [],
-          previousUrl: store.getSegmentState().currentUrl,
-        });
+    let hmrTimer: ReturnType<typeof setTimeout> | null = null;
+    let hmrAbort: AbortController | null = null;
+
+    import.meta.hot.on("rsc:update", () => {
+      // Cancel any pending debounce timer
+      if (hmrTimer !== null) {
+        clearTimeout(hmrTimer);
+      }
+
+      // Abort any in-flight HMR fetch so it doesn't race with the next one
+      if (hmrAbort) {
+        hmrAbort.abort();
+        hmrAbort = null;
+      }
 
-        if (payload.metadata?.isPartial) {
-          const segments = payload.metadata.segments || [];
-          const matched = payload.metadata.matched || [];
+      // Debounce: wait 200ms of quiet before fetching
+      hmrTimer = setTimeout(async () => {
+        hmrTimer = null;
+
+        // Don't interrupt an active user navigation — startNavigation()
+        // would abort it and refetch the old URL (window.location.href
+        // hasn't updated yet). The user's navigation will pick up the
+        // new server code when it completes. isNavigating covers the
+        // full lifecycle (fetching + streaming, before commit) without
+        // blocking on server actions.
+        if (eventController.getState().isNavigating) {
+          console.log("[RSCRouter] HMR: Skipping — navigation in progress");
+          return;
+        }
 
-          store.setSegmentIds(matched);
-          store.setCurrentUrl(window.location.href);
+        console.log("[RSCRouter] HMR: Server update, refetching RSC");
 
-          const historyKey = generateHistoryKey(window.location.href);
-          store.setHistoryKey(historyKey);
-          const currentHandleData = eventController.getHandleState().data;
-          store.cacheSegmentsForHistory(historyKey, segments, currentHandleData);
+        const abort = new AbortController();
+        hmrAbort = abort;
 
-          store.emitUpdate({
-            root: renderSegments(segments),
-            metadata: payload.metadata,
+        const handle = eventController.startNavigation(window.location.href, {
+          replace: true,
+        });
+        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,
+            signal: abort.signal,
           });
-        }
 
-        await streamComplete;
-      } finally {
-        streamingToken.end();
-      }
-      handle.complete(new URL(window.location.href));
-      console.log("[RSCRouter] HMR: RSC stream complete");
+          if (abort.signal.aborted) return;
+
+          // If the server returned a non-RSC response (404, 500 without
+          // error boundary), the payload won't have valid metadata.
+          // Reload to recover rather than leaving the page stale.
+          if (!payload.metadata) {
+            throw new Error("HMR refetch returned invalid payload");
+          }
+
+          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, {
+              intercept: responseIsIntercept,
+            });
+            store.setHistoryKey(historyKey);
+            const currentHandleData = eventController.getHandleState().data;
+            store.cacheSegmentsForHistory(
+              historyKey,
+              segments,
+              currentHandleData,
+            );
+
+            const { main, intercept } = splitInterceptSegments(segments);
+            store.emitUpdate({
+              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");
+        } catch (err) {
+          if (abort.signal.aborted) return;
+          console.warn("[RSCRouter] HMR: Refetch failed, reloading page", err);
+          window.location.reload();
+          return;
+        } finally {
+          if (hmrAbort === abort) hmrAbort = null;
+          streamingToken.end();
+          handle[Symbol.dispose]();
+        }
+      }, 200);
     });
   }
 
@@ -278,6 +393,7 @@ export async function initBrowserApp(
     themeConfig: effectiveThemeConfig,
     initialTheme: effectiveInitialTheme,
     warmupEnabled: initialPayload.metadata?.warmupEnabled ?? true,
+    version,
   };
   browserAppContext = context;
 
@@ -290,7 +406,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;
@@ -333,18 +449,35 @@ export interface RSCRouterProps {}
  * ```
  */
 export function RSCRouter(_props: RSCRouterProps): React.ReactElement {
-  const { store, eventController, bridge, initialPayload, initialTree, themeConfig, initialTheme, warmupEnabled } =
-    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}
     />
   );
 }