@rangojs/router 0.0.0-experimental.0f44aca1

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

@@ -0,0 +1,171 @@
+"use client";
+
+import { useContext, useState, useEffect, useRef } from "react";
+import { NavigationStoreContext } from "./context.js";
+import { shallowEqual } from "./shallow-equal.js";
+
+/**
+ * Segments state returned by useSegments hook
+ */
+export interface SegmentsState {
+  /** URL path segments (e.g., /shop/products/123 → ["shop", "products", "123"]) */
+  path: readonly string[];
+  /** Matched segment IDs in order (layouts and routes only, e.g., ["L0", "L0L1", "L0L1R0"]) */
+  segmentIds: readonly string[];
+  /** Current URL location */
+  location: URL;
+}
+
+/**
+ * Parse pathname into path segments
+ * /shop/products/123 → ["shop", "products", "123"]
+ */
+function parsePathname(pathname: string): string[] {
+  return pathname.split("/").filter(Boolean);
+}
+
+/**
+ * Build segments state from event controller
+ */
+function buildSegmentsState(
+  location: URL,
+  segmentOrder: string[],
+): SegmentsState {
+  return {
+    path: parsePathname(location.pathname),
+    segmentIds: segmentOrder,
+    location,
+  };
+}
+
+/**
+ * Hook to access current route segments with optional selector for performance
+ *
+ * Provides information about the current URL path and matched route segments.
+ * Uses the event controller for reactive state management.
+ *
+ * @example
+ * ```tsx
+ * // Get full segments state
+ * const { path, segmentIds, location } = useSegments();
+ *
+ * // Use selector for specific values (better performance)
+ * const path = useSegments(s => s.path);
+ * const isShopRoute = useSegments(s => s.path[0] === "shop");
+ * ```
+ */
+export function useSegments(): SegmentsState;
+export function useSegments<T>(selector: (state: SegmentsState) => T): T;
+export function useSegments<T>(
+  selector?: (state: SegmentsState) => T,
+): T | SegmentsState {
+  const ctx = useContext(NavigationStoreContext);
+
+  // 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>(() => {
+    if (!ctx) {
+      const fallbackLocation = new URL("/", "http://localhost");
+      const fallbackState = buildSegmentsState(fallbackLocation, []);
+      return selector ? selector(fallbackState) : fallbackState;
+    }
+    const location = ctx.eventController.getLocation();
+    const handleState = ctx.eventController.getHandleState();
+    const segmentsState = buildSegmentsState(
+      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 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 nextSelected = recompute(selectorRef.current);
+      if (!shallowEqual(nextSelected, prevState.current)) {
+        prevState.current = nextSelected;
+        setState(nextSelected);
+      }
+    };
+
+    const unsubscribeNav = ctx.eventController.subscribe(updateState);
+    const unsubscribeHandles =
+      ctx.eventController.subscribeToHandles(updateState);
+
+    return () => {
+      unsubscribeNav();
+      unsubscribeHandles();
+    };
+    // 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

@@ -0,0 +1,431 @@
+import React from "react";
+import {
+  renderSegments as baseRenderSegments,
+  type RenderSegmentsOptions,
+} from "../segment-system.js";
+import {
+  createNavigationStore,
+  generateHistoryKey,
+} from "./navigation-store.js";
+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 } from "./react/index.js";
+import type {
+  RscPayload,
+  RscBrowserDependencies,
+  ResolvedSegment,
+  NavigationStore,
+  NavigationBridge,
+} 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
+
+/**
+ * Options for initializing the browser app
+ */
+export interface InitBrowserAppOptions {
+  /**
+   * RSC stream containing the initial payload (from rsc-html-stream/client)
+   */
+  rscStream: ReadableStream<Uint8Array>;
+
+  /**
+   * RSC browser dependencies from @vitejs/plugin-rsc/browser
+   */
+  deps: RscBrowserDependencies;
+
+  /**
+   * Optional store configuration
+   */
+  storeOptions?: {
+    /**
+     * Maximum number of history entries to cache
+     * @default 10
+     */
+    cacheSize?: number;
+  };
+
+  /**
+   * Enable global link interception for SPA navigation.
+   * When enabled, clicks on same-origin anchor elements are intercepted
+   * and handled via client-side navigation instead of full page loads.
+   *
+   * Links rendered with the Link component handle their own navigation
+   * regardless of this setting.
+   *
+   * Set to false to disable global interception and rely solely on
+   * Link components for SPA navigation.
+   *
+   * @default true
+   */
+  linkInterception?: boolean;
+
+  /**
+   * Theme configuration from router.
+   * When provided, enables theme support via useTheme hook.
+   * Pass router.themeConfig here to enable theme features.
+   *
+   * @example
+   * ```tsx
+   * import { router } from "./router.js";
+   *
+   * await initBrowserApp({
+   *   rscStream,
+   *   deps: rscBrowser,
+   *   themeConfig: router.themeConfig,
+   *   initialTheme: document.documentElement.className.includes("dark") ? "dark" : "light",
+   * });
+   * ```
+   */
+  themeConfig?: ResolvedThemeConfig | null;
+
+  /**
+   * Initial theme from server (typically read from cookie).
+   * Only used when themeConfig is provided.
+   */
+  initialTheme?: Theme;
+}
+
+/**
+ * Result from initializing the browser app
+ */
+export interface BrowserAppContext {
+  store: NavigationStore;
+  eventController: EventController;
+  bridge: NavigationBridge;
+  initialPayload: RscPayload;
+  initialTree: React.ReactNode | Promise<React.ReactNode>;
+  /** Theme configuration (null if theme not enabled) */
+  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
+let browserAppContext: BrowserAppContext | null = null;
+
+/**
+ * Initialize the browser app. Must be called before rendering RSCRouter.
+ *
+ * This function:
+ * - Loads the initial RSC payload from the stream
+ * - Creates the navigation store and event controller
+ * - Sets up action and navigation bridges
+ * - Configures HMR support
+ */
+export async function initBrowserApp(
+  options: InitBrowserAppOptions,
+): Promise<BrowserAppContext> {
+  const {
+    rscStream,
+    deps,
+    storeOptions,
+    linkInterception = true,
+    themeConfig,
+    initialTheme,
+  } = options;
+
+  // Load initial payload from SSR-injected __FLIGHT_DATA__
+  const initialPayload =
+    await deps.createFromReadableStream<RscPayload>(rscStream);
+
+  // 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;
+
+  // Get initial segments and compute history key from current URL
+  const initialSegments = (initialPayload.metadata?.segments ??
+    []) as ResolvedSegment[];
+  const initialHistoryKey = generateHistoryKey(window.location.href);
+
+  // Create navigation store with history-based caching
+  const store = createNavigationStore({
+    initialLocation: window.location,
+    initialSegmentIds: initialSegments.map((s) => s.id),
+    initialHistoryKey,
+    initialSegments,
+    ...(storeOptions?.cacheSize && { cacheSize: storeOptions.cacheSize }),
+  });
+
+  // Create event controller for reactive state management
+  const eventController = createEventController({
+    initialLocation: new URL(window.location.href),
+  });
+
+  // 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
+  if (initialPayload.metadata?.handles) {
+    const handlesGenerator = initialPayload.metadata.handles;
+    let lastHandleData: Record<string, Record<string, unknown[]>> = {};
+    for await (const handleData of handlesGenerator) {
+      lastHandleData = handleData;
+    }
+    // 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);
+
+  // Extract rootLayout and version from metadata for browser-side re-renders
+  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,
+  ) => 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,
+    eventController,
+    client,
+    deps,
+    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();
+
+  // Setup navigation bridge
+  const navigationBridge = createNavigationBridge({
+    store,
+    eventController,
+    client,
+    onUpdate: (update) => store.emitUpdate(update),
+    renderSegments,
+    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();
+  }
+
+  // Build initial tree with rootLayout
+  const initialTree = renderSegments(initialPayload.metadata!.segments);
+
+  // Setup HMR
+  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();
+
+      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, {
+            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");
+      } finally {
+        streamingToken.end();
+        handle[Symbol.dispose]();
+      }
+    });
+  }
+
+  // Store context for RSCRouter component
+  const context: BrowserAppContext = {
+    store,
+    eventController,
+    bridge: navigationBridge,
+    initialPayload,
+    initialTree,
+    themeConfig: effectiveThemeConfig,
+    initialTheme: effectiveInitialTheme,
+    warmupEnabled: initialPayload.metadata?.warmupEnabled ?? true,
+    version,
+  };
+  browserAppContext = context;
+
+  return context;
+}
+
+/**
+ * Get the browser app context. Throws if initBrowserApp hasn't been called.
+ */
+export function getBrowserAppContext(): BrowserAppContext {
+  if (!browserAppContext) {
+    throw new Error(
+      "RSCRouter: initBrowserApp() must be called before rendering RSCRouter",
+    );
+  }
+  return browserAppContext;
+}
+
+/**
+ * Reset the browser app context (for testing)
+ */
+export function resetBrowserAppContext(): void {
+  browserAppContext = null;
+}
+
+/**
+ * Props for the RSCRouter component
+ */
+export interface RSCRouterProps {}
+
+/**
+ * RSCRouter component - renders the RSC router with all internal wiring.
+ *
+ * Must be called after initBrowserApp() has completed.
+ *
+ * @example
+ * ```tsx
+ * import { initBrowserApp, RSCRouter } from "rsc-router/browser";
+ * import { rscStream } from "rsc-html-stream/client";
+ * import * as rscBrowser from "@vitejs/plugin-rsc/browser";
+ *
+ * async function main() {
+ *   await initBrowserApp({ rscStream, deps: rscBrowser });
+ *
+ *   hydrateRoot(
+ *     document,
+ *     <React.StrictMode>
+ *       <RSCRouter />
+ *     </React.StrictMode>
+ *   );
+ * }
+ * main();
+ * ```
+ */
+export function RSCRouter(_props: RSCRouterProps): React.ReactElement {
+  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={{ root: initialTree, metadata: initialPayload.metadata! }}
+      bridge={bridge}
+      themeConfig={themeConfig}
+      initialTheme={initialTheme}
+      warmupEnabled={warmupEnabled}
+      version={version}
+    />
+  );
+}