@rangojs/router 0.0.0-experimental.12 → 0.0.0-experimental.120

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

@@ -0,0 +1,47 @@
+"use client";
+
+import { useContext, useState, useEffect, useRef } from "react";
+import { NavigationStoreContext } from "./context.js";
+
+/**
+ * Hook to access the current pathname.
+ *
+ * Returns the committed pathname string (excludes search params and hash).
+ * Updates when navigation completes, not during pending navigation.
+ *
+ * @example
+ * ```tsx
+ * const pathname = usePathname();
+ * // "/products/123"
+ * ```
+ */
+export function usePathname(): string {
+  const ctx = useContext(NavigationStoreContext);
+
+  const [pathname, setPathname] = useState<string>(() => {
+    if (!ctx) {
+      return "/";
+    }
+    return (ctx.eventController.getState().location as URL).pathname;
+  });
+
+  const prevPathname = useRef(pathname);
+
+  useEffect(() => {
+    if (!ctx) return;
+
+    const update = () => {
+      const next = (ctx.eventController.getState().location as URL).pathname;
+      if (next !== prevPathname.current) {
+        prevPathname.current = next;
+        setPathname(next);
+      }
+    };
+
+    update();
+
+    return ctx.eventController.subscribe(update);
+  }, []);
+
+  return pathname;
+}

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

@@ -0,0 +1,106 @@
+"use client";
+
+import { useCallback } from "react";
+import type { LocalReverseFunction } from "../../reverse.js";
+import { substitutePatternParams } from "../../router/substitute-pattern-params.js";
+import { serializeSearchParams } from "../../search-params.js";
+import { useMount } from "./use-mount.js";
+import { useParams } from "./use-params.js";
+
+type RouteEntry = string | { readonly path: string };
+type LocalRouteMap = Readonly<Record<string, RouteEntry>>;
+
+function getPattern(entry: RouteEntry | undefined): string | undefined {
+  if (entry === undefined) return undefined;
+  return typeof entry === "string" ? entry : entry.path;
+}
+
+/**
+ * Join an include mount prefix with a mount-relative pattern.
+ *
+ * `pattern === "/"` is the index of the local module — under a non-root
+ * mount it must collapse so `/` under `/blog` becomes `/blog`, not
+ * `/blog/`. This matches `ctx.reverse(".index")` on the server.
+ */
+function joinMount(mount: string, pattern: string): string {
+  if (pattern === "/") {
+    if (mount === "" || mount === "/") return "/";
+    return mount.endsWith("/") ? mount.slice(0, -1) : mount;
+  }
+  const normalizedMount = mount === "/" ? "" : mount.replace(/\/+$/, "");
+  return normalizedMount + pattern;
+}
+
+/**
+ * Mount-aware reverse function for a locally-imported `routes` map.
+ *
+ * The `routes` map you pass IS the scope: `reverse("name")` looks the name up
+ * in that map (verbatim), prefixes the result with the surrounding `include()`
+ * mount path via `useMount()`, and substitutes params — auto-filling from the
+ * current matched route's params, with explicit params overriding. A module's
+ * components can therefore reverse their own routes without knowing where the
+ * module is mounted: include it under any prefix and the URLs resolve correctly.
+ *
+ * The leading dot is optional and cosmetic: `reverse("post")` and
+ * `reverse(".post")` resolve identically. The dot exists only as a readability
+ * convention and for parity with `ctx.reverse(".name")` on the server; here the
+ * passed map is the scope, so there is no separate global namespace to
+ * disambiguate and the dot carries no meaning.
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { Link, useReverse } from "@rangojs/router/client";
+ * import { routes as blogRoutes } from "../urls/blog.gen.js";
+ *
+ * function BlogNav() {
+ *   const reverse = useReverse(blogRoutes);
+ *   return (
+ *     <>
+ *       <Link to={reverse("index")}>Blog</Link>
+ *       <Link to={reverse("post", { postId: "hello" })}>Post</Link>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function useReverse<const TRoutes extends LocalRouteMap>(
+  routes: TRoutes,
+): LocalReverseFunction<TRoutes> {
+  const mount = useMount();
+  const currentParams = useParams();
+
+  return useCallback(
+    ((
+      name: string,
+      explicitParams?: Record<string, string | undefined>,
+      search?: Record<string, unknown>,
+    ): string => {
+      // The leading dot is optional. The passed map IS the scope, so a dot to
+      // signal "local" is unnecessary — "detail" and ".detail" resolve the same.
+      // A dot is accepted (and stripped) for readability / ctx.reverse parity.
+      const lookupName = name.startsWith(".") ? name.slice(1) : name;
+      const entry = (routes as LocalRouteMap)[lookupName];
+      const pattern = getPattern(entry);
+      if (pattern === undefined) {
+        throw new Error(`Unknown route: "${name}"`);
+      }
+
+      const joined = joinMount(mount, pattern);
+
+      const mergedParams = explicitParams
+        ? { ...currentParams, ...explicitParams }
+        : currentParams;
+
+      const substituted = substitutePatternParams(joined, mergedParams, name);
+
+      if (search) {
+        const qs = serializeSearchParams(search);
+        if (qs) return `${substituted}?${qs}`;
+      }
+
+      return substituted;
+    }) as LocalReverseFunction<TRoutes>,
+    [routes, mount, currentParams],
+  );
+}

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

@@ -0,0 +1,97 @@
+"use client";
+
+import { useContext, useMemo } from "react";
+import { NavigationStoreContext } from "./context.js";
+import { prefetchDirect } from "../prefetch/fetch.js";
+import { getAppVersion } from "../app-version.js";
+import type { RouterInstance, RouterNavigateOptions } from "../types.js";
+
+/**
+ * Hook to access router actions (push, replace, refresh, prefetch, back, forward).
+ *
+ * Returns a STABLE reference that never changes, so components using
+ * useRouter() do not re-render on navigation state changes.
+ * For reactive navigation state, use useNavigation() instead.
+ *
+ * Methods read `basename` from the context on each call. It is set once from
+ * the initial payload and is stable within a session — a cross-app navigation
+ * is a full document load (X-RSC-Reload), so the target app mounts fresh with
+ * its own basename.
+ *
+ * @example
+ * ```tsx
+ * const router = useRouter();
+ * router.push("/products");
+ * router.replace("/login", { scroll: false });
+ * router.prefetch("/dashboard");
+ * router.back();
+ * ```
+ */
+export function useRouter(): RouterInstance {
+  const ctx = useContext(NavigationStoreContext);
+
+  if (!ctx) {
+    throw new Error("useRouter must be used within NavigationProvider");
+  }
+
+  // Stable reference: ctx itself is stable, and reads on each method call
+  // pick up live basename values from the context (backed by a live ref
+  // in NavigationProvider), so app-switch transitions are reflected without
+  // recreating this object.
+  return useMemo<RouterInstance>(() => {
+    /** Prefix a root-relative path with basename if not already prefixed. */
+    function withBasename(url: string): string {
+      const bn = ctx!.basename;
+      if (!bn || !url.startsWith("/") || url.startsWith(bn + "/") || url === bn)
+        return url;
+      return url === "/" ? bn : bn + url;
+    }
+
+    return {
+      push(url: string, options?: RouterNavigateOptions): Promise<void> {
+        return ctx.navigate(withBasename(url), { ...options, replace: false });
+      },
+
+      replace(url: string, options?: RouterNavigateOptions): Promise<void> {
+        return ctx.navigate(withBasename(url), { ...options, replace: true });
+      },
+
+      refresh(): Promise<void> {
+        return ctx.refresh();
+      },
+
+      prefetch(url: string): void {
+        const segmentState = ctx.store?.getSegmentState();
+        if (segmentState) {
+          prefetchDirect(
+            withBasename(url),
+            segmentState.currentSegmentIds,
+            getAppVersion(),
+            ctx.store?.getRouterId?.(),
+          );
+        }
+      },
+
+      back(): void {
+        // Avoid escaping the host on the first entry of this session.
+        // Prefer the Navigation API; fall back to the router-stamped
+        // history.state.idx (set by pushHistoryWithIdx) for older browsers.
+        const nav = (window as { navigation?: { canGoBack: boolean } })
+          .navigation;
+        const canGoBack =
+          nav && typeof nav.canGoBack === "boolean"
+            ? nav.canGoBack
+            : ((window.history.state as { idx?: number } | null)?.idx ?? 0) > 0;
+        if (canGoBack) {
+          window.history.back();
+        } else {
+          ctx.navigate(withBasename("/"), { replace: true });
+        }
+      },
+
+      forward(): void {
+        window.history.forward();
+      },
+    };
+  }, []);
+}

package/src/browser/react/use-search-params.ts

@@ -0,0 +1,56 @@
+"use client";
+
+import { useContext, useState, useEffect, useRef } from "react";
+import { NavigationStoreContext } from "./context.js";
+import type { ReadonlyURLSearchParams } from "../types.js";
+
+/**
+ * Hook to access the current URL search params.
+ *
+ * Returns a read-only URLSearchParams object from the committed location.
+ * Updates when navigation completes, not during pending navigation.
+ *
+ * Note: During SSR the search params are not available (the server only sends
+ * the pathname). The hook returns empty params during SSR and syncs from
+ * the browser URL on mount.
+ *
+ * @example
+ * ```tsx
+ * const searchParams = useSearchParams();
+ * const query = searchParams.get("q"); // "react"
+ * const page = searchParams.get("page"); // "2"
+ * ```
+ */
+export function useSearchParams(): ReadonlyURLSearchParams {
+  const ctx = useContext(NavigationStoreContext);
+
+  // Always initialize with empty URLSearchParams to match SSR output
+  // and avoid hydration mismatch. The useEffect below syncs from
+  // the real URL after hydration.
+  const [searchParams, setSearchParams] = useState<ReadonlyURLSearchParams>(
+    () => new URLSearchParams(),
+  );
+
+  const prevSearch = useRef("");
+
+  useEffect(() => {
+    if (!ctx) return;
+
+    const update = () => {
+      const location = ctx.eventController.getState().location as URL;
+      const nextSearch = location.searchParams.toString();
+      if (nextSearch !== prevSearch.current) {
+        prevSearch.current = nextSearch;
+        // Create a snapshot so callers cannot mutate the source URLSearchParams
+        setSearchParams(new URLSearchParams(nextSearch));
+      }
+    };
+
+    // Sync on mount (picks up search params from browser URL)
+    update();
+
+    return ctx.eventController.subscribe(update);
+  }, []);
+
+  return searchParams;
+}

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"]
@@ -83,27 +25,18 @@ function parsePathname(pathname: string): string[] {
 }
 
 /**
- * Build segments state from event controller
+ * Build segments state from event controller. `segmentIds` is the
+ * route-only list (parallels and loaders stripped) — distinct from the
+ * controller's `segmentOrder` which drives handle collection and includes
+ * parallel slot ids.
  */
 function buildSegmentsState(
   location: URL,
-  segmentOrder: string[]
+  routeSegmentIds: string[],
 ): SegmentsState {
   return {
     path: parsePathname(location.pathname),
-    segmentIds: segmentOrder,
-    location,
-  };
-}
-
-/**
- * Build SSR state from module-level variables
- */
-function buildSsrState(): SegmentsState {
-  const location = new URL(ssrPathname, "http://localhost");
-  return {
-    path: parsePathname(ssrPathname),
-    segmentIds: ssrSegmentOrder,
+    segmentIds: routeSegmentIds,
     location,
   };
 }
@@ -127,62 +60,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.routeSegmentIds,
     );
     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;
+    routeSegmentIds: 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.routeSegmentIds === handleState.routeSegmentIds
+    ) {
+      segmentsState = cache.state;
+    } else {
+      segmentsState = buildSegmentsState(
+        location as URL,
+        handleState.routeSegmentIds,
+      );
+      segmentsCache.current = {
+        location: location as URL,
+        routeSegmentIds: handleState.routeSegmentIds,
+        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,124 @@
+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 });
+}
+
+/**
+ * Whether an RSC content response carries a server-stamped router identity
+ * (`X-RSC-Router-Id`) that DIFFERS from the id this client expects (its own
+ * routerId, also sent as `_rsc_rid`). Pre-decode integrity check: lets a caller
+ * refuse a foreign app's payload before `createFromFetch` imports its chunks.
+ *
+ * True ONLY when both the header and the expected id are present and differ. An
+ * absent header (control-only reload/redirect responses are not stamped) or an
+ * absent expected id (e.g. before the client is seeded) is a pass-through —
+ * never a false reject.
+ */
+export function isForeignRouterId(
+  response: Response,
+  expectedId: string | undefined,
+): boolean {
+  const got = response.headers.get("X-RSC-Router-Id");
+  if (!got || !expectedId) return false;
+  return got !== expectedId;
+}
+
+/**
+ * Handle the X-RSC-Reload control header (server requests a full page reload on
+ * a version mismatch). Returns a short-circuit response when the header is
+ * present -- emptyResponse() if the URL was blocked by origin validation, or a
+ * never-resolving promise while the page reloads -- and null when absent, so
+ * the caller continues processing (e.g. the X-RSC-Redirect check). Scoped to
+ * X-RSC-Reload only; redirect handling differs between callers.
+ */
+export function handleReloadHeader(
+  response: Response,
+  opts: { onBlocked: () => void; onReload: (url: string) => void },
+): Response | Promise<Response> | null {
+  const reload = extractRscHeaderUrl(response, "X-RSC-Reload");
+  if (reload === "blocked") {
+    opts.onBlocked();
+    return emptyResponse();
+  }
+  if (reload) {
+    opts.onReload(reload.url);
+    window.location.href = reload.url;
+    return new Promise<Response>(() => {});
+  }
+  return null;
+}
+
+/**
+ * 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.
+ *
+ * `silent` suppresses the stream-error log. Prefetch passes it: a speculative,
+ * low-priority prefetch that is aborted or never consumed can error its stream
+ * benignly, which is not worth surfacing. The fresh-navigation path keeps the
+ * log (default), where a stream error reflects a real failed navigation.
+ */
+export function teeWithCompletion(
+  response: Response,
+  onComplete: () => void,
+  signal?: AbortSignal,
+  silent = false,
+): 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 (!silent && !signal?.aborted) {
+      console.error("[Browser] Error reading tracking stream:", error);
+    }
+    onComplete();
+  });
+
+  return new Response(rscStream, {
+    headers: response.headers,
+    status: response.status,
+    statusText: response.statusText,
+  });
+}