@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.8a4d0430

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

@@ -12,40 +12,15 @@ import type { Handle } from "../../handle.js";
 import { getCollectFn } from "../../handle.js";
 import type { HandleData } from "../types.js";
 import { NavigationStoreContext } from "./context.js";
-
-/**
- * SSR module-level state.
- * Populated by initHandleDataSync before React renders.
- * Used by useState initializer during SSR.
- */
-let ssrHandleData: HandleData = {};
-let ssrSegmentOrder: 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;
-  });
-}
+import { shallowEqual } from "./shallow-equal.js";
 
 /**
  * Resolve the collect function for a handle.
- * When a handle is passed as a prop via RSC, toJSON strips the collect function.
- * In that case, look up collect from the registry (populated when createHandle runs
- * on the client), then fall back to flat array default.
+ * Handle objects are plain { __brand, $$id } - collect is stored in the registry
+ * (populated when createHandle runs on the client).
  */
 function resolveCollect<T, A>(handle: Handle<T, A>): (segments: T[][]) => A {
-  if (typeof handle.collect === "function") {
-    return handle.collect;
-  }
-
-  // Handle was deserialized from RSC prop (toJSON stripped collect).
-  // Try the registry first (populated if the handle module was imported on client).
+  // Look up collect from the registry (populated when the handle module is imported).
   const registered = getCollectFn(handle.$$id);
   if (registered) {
     return registered as (segments: T[][]) => A;
@@ -55,11 +30,13 @@ function resolveCollect<T, A>(handle: Handle<T, A>): (segments: T[][]) => A {
   if (process.env.NODE_ENV !== "production") {
     console.warn(
       `[rsc-router] Handle "${handle.$$id}" was passed as a prop but its collect ` +
-      `function could not be resolved. Falling back to flat array. ` +
-      `Import the handle module in a client component to register its collect function.`
+        `function could not be resolved. Falling back to flat array. ` +
+        `Import the handle module in a client component to register its collect function.`,
     );
   }
-  return ((segments: unknown[][]) => segments.flat()) as unknown as (segments: T[][]) => A;
+  return ((segments: unknown[][]) => segments.flat()) as unknown as (
+    segments: T[][],
+  ) => A;
 }
 
 /**
@@ -68,7 +45,7 @@ function resolveCollect<T, A>(handle: Handle<T, A>): (segments: T[][]) => A {
 function collectHandle<T, A>(
   handle: Handle<T, A>,
   data: HandleData,
-  segmentOrder: string[]
+  segmentOrder: string[],
 ): A {
   const collect = resolveCollect(handle);
   const segmentData = data[handle.$$id];
@@ -90,45 +67,6 @@ function collectHandle<T, A>(
   return collect(segmentArrays);
 }
 
-/**
- * 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;
-}
-
-/**
- * Initialize handle data synchronously for SSR.
- * Called before rendering to populate state for useState initializer.
- *
- * @param data - Handle data from RSC payload
- * @param matched - Segment order for reduction
- */
-export function initHandleDataSync(data: HandleData, matched?: string[]): void {
-  ssrHandleData = data;
-  ssrSegmentOrder = filterSegmentOrder(matched ?? []);
-}
-
 /**
  * Hook to access collected handle data.
  *
@@ -150,19 +88,18 @@ export function initHandleDataSync(data: HandleData, matched?: string[]): void {
 export function useHandle<T, A>(handle: Handle<T, A>): A;
 export function useHandle<T, A, S>(
   handle: Handle<T, A>,
-  selector: (data: A) => S
+  selector: (data: A) => S,
 ): S;
 export function useHandle<T, A, S>(
   handle: Handle<T, A>,
-  selector?: (data: A) => S
+  selector?: (data: A) => S,
 ): A | S {
   const ctx = useContext(NavigationStoreContext);
 
-  // Initial state from SSR module state or event controller
+  // Initial state from context event controller, or empty fallback without provider.
   const [value, setValue] = useState<A | S>(() => {
-    // During SSR, use module-level state
-    if (typeof document === "undefined" || !ctx) {
-      const collected = collectHandle(handle, ssrHandleData, ssrSegmentOrder);
+    if (!ctx) {
+      const collected = collectHandle(handle, {}, []);
       return selector ? selector(collected) : collected;
     }
 
@@ -177,7 +114,7 @@ export function useHandle<T, A, S>(
   const prevValueRef = useRef(value);
   prevValueRef.current = value;
 
-  // Memoize selector ref
+  // Ref keeps the latest selector without re-subscribing on every render.
   const selectorRef = useRef(selector);
   selectorRef.current = selector;
 
@@ -185,6 +122,22 @@ export function useHandle<T, A, S>(
   useEffect(() => {
     if (!ctx) return;
 
+    // Sync current state for the (possibly new) handle so that switching
+    // handles on an idle page doesn't leave stale data from the old handle.
+    const currentHandleState = ctx.eventController.getHandleState();
+    const currentCollected = collectHandle(
+      handle,
+      currentHandleState.data,
+      currentHandleState.segmentOrder,
+    );
+    const currentValue = selectorRef.current
+      ? selectorRef.current(currentCollected)
+      : currentCollected;
+    if (!shallowEqual(currentValue, prevValueRef.current)) {
+      prevValueRef.current = currentValue;
+      setValue(currentValue);
+    }
+
     return ctx.eventController.subscribeToHandles(() => {
       const state = ctx.eventController.getHandleState();
       const isAction =

package/src/browser/react/use-href.tsx

@@ -34,7 +34,7 @@ import { useMount } from "./use-mount.js";
  * }
  * ```
  */
-export function useHref(): (path: ValidPaths) => string {
+export function useHref(): (path: `/${string}`) => string {
   const mount = useMount();
-  return (path: ValidPaths) => href(path, mount);
+  return (path: `/${string}`) => href(path as ValidPaths, mount);
 }

package/src/browser/react/use-link-status.ts

@@ -16,7 +16,9 @@ import { NavigationStoreContext } from "./context.js";
  * Context for Link component to provide its destination URL
  * Used by useLinkStatus to determine if this specific link is pending
  */
-export const LinkContext: Context<string | null> = createContext<string | null>(null);
+export const LinkContext: Context<string | null> = createContext<string | null>(
+  null,
+);
 
 /**
  * Link status returned by useLinkStatus hook
@@ -46,7 +48,7 @@ function normalizeUrl(url: string, origin: string): string {
 function isPendingFor(
   linkTo: string | null,
   pendingUrl: string | null,
-  origin: string
+  origin: string,
 ): boolean {
   if (linkTo === null || pendingUrl === null) {
     return false;
@@ -81,9 +83,8 @@ export function useLinkStatus(): LinkStatus {
   const ctx = useContext(NavigationStoreContext);
 
   // Get origin for URL normalization (stable across renders)
-  const origin = typeof window !== "undefined"
-    ? window.location.origin
-    : "http://localhost";
+  const origin =
+    typeof window !== "undefined" ? window.location.origin : "http://localhost";
 
   // Base state for useOptimistic
   const [basePending, setBasePending] = useState<boolean>(() => {

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

@@ -9,36 +9,10 @@ import {
   useRef,
 } from "react";
 import { NavigationStoreContext } from "./context.js";
-import type { PublicNavigationState, NavigateOptions } from "../types.js";
+import { shallowEqual } from "./shallow-equal.js";
+import type { PublicNavigationState } from "../types.js";
 import type { DerivedNavigationState } from "../event-controller.js";
 
-/**
- * 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;
-}
-
 /**
  * Convert derived state to public version (strips inflightActions)
  */
@@ -47,45 +21,29 @@ function toPublicState(state: DerivedNavigationState): PublicNavigationState {
   return publicState;
 }
 
-
 /**
- * Navigation methods returned by useNavigation
- */
-export interface NavigationMethods {
-  navigate: (url: string, options?: NavigateOptions) => Promise<void>;
-  refresh: () => Promise<void>;
-}
-
-/**
- * Full value returned when no selector is provided
- */
-export type NavigationValue = PublicNavigationState & NavigationMethods;
-
-/**
- * Hook to access navigation state with optional selector for performance
+ * Hook to access reactive navigation state with optional selector for performance.
  *
- * Uses the event controller for reactive state management.
- * State is derived from source of truth (currentNavigation, inflightActions).
+ * Returns state only. For actions (push, replace, refresh, prefetch),
+ * use useRouter() instead.
  *
  * @example
  * ```tsx
- * const state = useNavigation(nav => nav.state);
+ * const { state, location } = useNavigation();
  * const isLoading = useNavigation(nav => nav.state === 'loading');
  * ```
  */
-export function useNavigation(): NavigationValue;
+export function useNavigation(): PublicNavigationState;
 export function useNavigation<T>(
   selector: (state: PublicNavigationState) => T,
 ): T;
 export function useNavigation<T>(
   selector?: (state: PublicNavigationState) => T,
-): T | NavigationValue {
+): T | PublicNavigationState {
   const ctx = useContext(NavigationStoreContext);
 
   if (!ctx) {
-    throw new Error(
-      "useNavigation must be used within NavigationStoreContext.Provider"
-    );
+    throw new Error("useNavigation must be used within NavigationProvider");
   }
 
   // Base state for useOptimistic
@@ -98,13 +56,23 @@ export function useNavigation<T>(
   // useOptimistic allows immediate updates during transitions/actions
   const [value, setOptimisticValue] = useOptimistic(baseValue);
 
+  // Store selector in a ref so the subscription callback always uses the
+  // latest selector without re-subscribing on every render (inline functions
+  // have a new identity each render). This is event-driven by design: the
+  // value updates when the store emits, not when the selector changes.
+  // Between events there is nothing new to select from.
+  const selectorRef = useRef(selector);
+  selectorRef.current = selector;
+
   // Subscribe to event controller state changes (only runs on client)
   useEffect(() => {
     // Subscribe to updates from event controller
     return ctx.eventController.subscribe(() => {
       const currentState = ctx.eventController.getState();
       const publicState = toPublicState(currentState);
-      const nextSelected = selector ? selector(publicState) : publicState;
+      const nextSelected = selectorRef.current
+        ? selectorRef.current(publicState)
+        : publicState;
 
       // Check if selected value has changed
       if (!shallowEqual(nextSelected, prevState.current)) {
@@ -125,16 +93,7 @@ export function useNavigation<T>(
         setBaseValue(nextSelected);
       }
     });
-  }, [selector]);
-
-  // If no selector, include navigation methods
-  if (!selector) {
-    return {
-      ...(value as PublicNavigationState),
-      navigate: ctx.navigate,
-      refresh: ctx.refresh,
-    };
-  }
+  }, []);
 
-  return value as T;
+  return value as T | PublicNavigationState;
 }

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

@@ -0,0 +1,65 @@
+"use client";
+
+import { useContext, useState, useEffect, useRef } from "react";
+import { NavigationStoreContext } from "./context.js";
+import { shallowEqual } from "./shallow-equal.js";
+
+/**
+ * Hook to access the current route params.
+ *
+ * Returns the merged route params from the matched route.
+ * Updates when navigation completes, not during pending navigation.
+ *
+ * @example
+ * ```tsx
+ * // Route: /products/:productId
+ * const params = useParams();
+ * // { productId: "123" }
+ *
+ * // With selector
+ * const productId = useParams(p => p.productId);
+ * ```
+ */
+export function useParams(): Record<string, string>;
+export function useParams<T>(
+  selector: (params: Record<string, string>) => T,
+): T;
+export function useParams<T>(
+  selector?: (params: Record<string, string>) => T,
+): T | Record<string, string> {
+  const ctx = useContext(NavigationStoreContext);
+
+  const [value, setValue] = useState<T | Record<string, string>>(() => {
+    if (!ctx) {
+      return selector ? selector({}) : {};
+    }
+    const params = ctx.eventController.getParams();
+    return selector ? selector(params) : params;
+  });
+
+  const prevValue = useRef(value);
+  // Ref keeps the latest selector without re-subscribing. Event-driven by
+  // design: value updates on store events, not on selector identity change.
+  const selectorRef = useRef(selector);
+  selectorRef.current = selector;
+
+  useEffect(() => {
+    if (!ctx) return;
+
+    const update = () => {
+      const params = ctx.eventController.getParams();
+      const next = selectorRef.current ? selectorRef.current(params) : params;
+
+      if (!shallowEqual(next, prevValue.current)) {
+        prevValue.current = next;
+        setValue(next);
+      }
+    };
+
+    update();
+
+    return ctx.eventController.subscribe(update);
+  }, []);
+
+  return value;
+}

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-router.ts

@@ -0,0 +1,63 @@
+"use client";
+
+import { useContext, useMemo } from "react";
+import { NavigationStoreContext } from "./context.js";
+import { prefetchDirect } from "../prefetch/fetch.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.
+ *
+ * @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 is itself stable (NavigationProvider memoizes with [])
+  return useMemo<RouterInstance>(
+    () => ({
+      push(url: string, options?: RouterNavigateOptions): Promise<void> {
+        return ctx.navigate(url, { ...options, replace: false });
+      },
+
+      replace(url: string, options?: RouterNavigateOptions): Promise<void> {
+        return ctx.navigate(url, { ...options, replace: true });
+      },
+
+      refresh(): Promise<void> {
+        return ctx.refresh();
+      },
+
+      prefetch(url: string): void {
+        const segmentState = ctx.store?.getSegmentState();
+        if (segmentState) {
+          prefetchDirect(url, segmentState.currentSegmentIds, ctx.version);
+        }
+      },
+
+      back(): void {
+        window.history.back();
+      },
+
+      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;
+}