@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.204030a9

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

@@ -9,7 +9,8 @@ import {
   startTransition,
 } from "react";
 import { NavigationStoreContext } from "./context.js";
-import type { TrackedActionState, ActionLifecycleState } from "../types.js";
+import { shallowEqual } from "./shallow-equal.js";
+import type { TrackedActionState } from "../types.js";
 import { invariant } from "../../errors.js";
 
 /**
@@ -44,7 +45,7 @@ function normalizeActionId(actionId: string): string {
 export function getActionId(action: ServerActionFunction | string): string {
   invariant(
     typeof action === "function" || typeof action === "string",
-    `useAction: action must be a function or string, got ${typeof action}`
+    `useAction: action must be a function or string, got ${typeof action}`,
   );
   const actionId = (action as any)?.$$id;
   if (actionId) {
@@ -72,7 +73,7 @@ Solutions:
 2. Use the action name as a string:
    const state = useAction("myAction");
 
-The string must match the exported function name from your "use server" file.`
+The string must match the exported function name from your "use server" file.`,
   );
 }
 
@@ -126,19 +127,24 @@ export type ServerActionFunction = ((...args: any[]) => Promise<any>) & {
  * const error = useAction(addToCart, state => state.error);
  * ```
  *
+ * @note The selector is expected to be stable for a given hook instance.
+ * This hook tracks one projection of one action. Changing selector semantics
+ * for the same action ID without a new action event is not a supported pattern;
+ * use separate useAction() subscriptions if you need different projections.
+ *
  * @note Actions passed as props from server components lose their metadata
  * during RSC serialization. Use a string action name or import directly.
  */
 export function useAction(
-  action: ServerActionFunction | string
+  action: ServerActionFunction | string,
 ): TrackedActionState;
 export function useAction<T>(
   action: ServerActionFunction | string,
-  selector: (state: TrackedActionState) => T
+  selector: (state: TrackedActionState) => T,
 ): T;
 export function useAction<T>(
   action: ServerActionFunction | string,
-  selector?: (state: TrackedActionState) => T
+  selector?: (state: TrackedActionState) => T,
 ): T | TrackedActionState {
   const ctx = useContext(NavigationStoreContext);
   const actionId =
@@ -161,7 +167,10 @@ export function useAction<T>(
     T | TrackedActionState
   >(null!);
 
-  // Memoize the selector to avoid unnecessary re-subscriptions
+  // Ref keeps the latest selector for subscription callbacks without
+  // re-subscribing on every render. Selector changes themselves are not
+  // treated as a reactive input; this hook expects a stable selector and
+  // represents one subscription/projection for one action.
   const selectorRef = useRef(selector);
   selectorRef.current = selector;
 
@@ -169,6 +178,17 @@ export function useAction<T>(
   useEffect(() => {
     if (!ctx) return;
 
+    // Sync current state for the (possibly new) actionId so that switching
+    // actions on an idle page doesn't leave stale data from the old action.
+    const currentState = ctx.eventController.getActionState(actionId);
+    const currentSelected = selectorRef.current
+      ? selectorRef.current(currentState)
+      : currentState;
+    if (!shallowEqual(currentSelected, prevSelected.current)) {
+      prevSelected.current = currentSelected;
+      setBaseState(currentSelected);
+    }
+
     // Subscribe to action-specific updates
     const unsubscribe = ctx.eventController.subscribeToAction(
       actionId,
@@ -177,14 +197,14 @@ export function useAction<T>(
           ? selectorRef.current(state)
           : state;
 
-        if (!isShallowEqual(selectedState, prevSelected.current)) {
+        if (!shallowEqual(selectedState, prevSelected.current)) {
           prevSelected.current = selectedState;
           setBaseState(selectedState);
           startTransition(() => {
             setOptimisticState(selectedState);
           });
         }
-      }
+      },
     );
 
     return () => {
@@ -195,46 +215,4 @@ export function useAction<T>(
   return (optimisticState ?? baseState) as T | TrackedActionState;
 }
 
-function isShallowEqual<T, U>(selectedState: T, baseState: U): boolean {
-  // If references are equal, they're shallow equal
-  //@ts-expect-error -- TS doesn't like comparing generics
-  if (selectedState === baseState) {
-    return true;
-  }
-
-  // If either is null/undefined and they're not equal, they're not shallow equal
-  if (selectedState == null || baseState == null) {
-    return false;
-  }
-
-  // If types are different, they're not shallow equal
-  if (typeof selectedState !== typeof baseState) {
-    return false;
-  }
-
-  // For primitives, === comparison is sufficient (already checked above)
-  if (typeof selectedState !== "object") {
-    return false;
-  }
-
-  // For objects, compare keys and values shallowly
-  const keysA = Object.keys(selectedState as object);
-  const keysB = Object.keys(baseState as object);
-
-  if (keysA.length !== keysB.length) {
-    return false;
-  }
-
-  for (const key of keysA) {
-    if (
-      !Object.prototype.hasOwnProperty.call(baseState, key) ||
-      (selectedState as any)[key] !== (baseState as any)[key]
-    ) {
-      return false;
-    }
-  }
-
-  return true;
-}
-
 export type { TrackedActionState };

package/src/browser/react/use-client-cache.ts

@@ -46,10 +46,12 @@ export interface ClientCacheControls {
 export function useClientCache(): ClientCacheControls {
   const ctx = useContext(NavigationStoreContext);
 
+  if (!ctx) {
+    throw new Error("useClientCache must be used within NavigationProvider");
+  }
+
   const clear = useCallback(() => {
-    if (ctx?.store) {
-      ctx.store.clearHistoryCache();
-    }
+    ctx.store.clearHistoryCache();
   }, [ctx]);
 
   return { clear };

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

@@ -9,94 +9,10 @@ import {
   startTransition,
 } from "react";
 import type { Handle } from "../../handle.js";
+import { collectHandleData } 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;
-  });
-}
-
-/**
- * Collect handle data from segments and transform to final value.
- */
-function collectHandle<T, A>(
-  handle: Handle<T, A>,
-  data: HandleData,
-  segmentOrder: string[]
-): A {
-  const segmentData = data[handle.$$id];
-
-  if (!segmentData) {
-    return handle.collect([]);
-  }
-
-  // Build array of segment arrays in parent → child order
-  const segmentArrays: T[][] = [];
-  for (const segmentId of segmentOrder) {
-    const entries = segmentData[segmentId];
-    if (entries && entries.length > 0) {
-      segmentArrays.push(entries as T[]);
-    }
-  }
-
-  // Call collect once with all segment data
-  return handle.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 ?? []);
-}
+import { shallowEqual } from "./shallow-equal.js";
 
 /**
  * Hook to access collected handle data.
@@ -116,28 +32,35 @@ export function initHandleDataSync(data: HandleData, matched?: string[]): void {
  * const lastCrumb = useHandle(Breadcrumbs, (data) => data.at(-1));
  * ```
  */
-export function useHandle<T, A>(handle: Handle<T, A>): A;
+export function useHandle<T, A>(handle: Handle<T, A>): Rango.FlightSerialize<A>;
 export function useHandle<T, A, S>(
   handle: Handle<T, A>,
-  selector: (data: A) => S
+  selector: (data: Rango.FlightSerialize<A>) => S,
 ): S;
 export function useHandle<T, A, S>(
   handle: Handle<T, A>,
-  selector?: (data: A) => S
-): A | S {
+  selector?: (data: Rango.FlightSerialize<A>) => S,
+): Rango.FlightSerialize<A> | S {
   const ctx = useContext(NavigationStoreContext);
 
-  // Initial state from SSR module state or event controller
-  const [value, setValue] = useState<A | S>(() => {
-    // During SSR, use module-level state
-    if (typeof document === "undefined" || !ctx) {
-      const collected = collectHandle(handle, ssrHandleData, ssrSegmentOrder);
+  // Initial state from context event controller, or empty fallback without provider.
+  const [value, setValue] = useState<Rango.FlightSerialize<A> | S>(() => {
+    if (!ctx) {
+      const collected = collectHandleData(
+        handle,
+        {},
+        [],
+      ) as Rango.FlightSerialize<A>;
       return selector ? selector(collected) : collected;
     }
 
     // On client, use event controller state
     const state = ctx.eventController.getHandleState();
-    const collected = collectHandle(handle, state.data, state.segmentOrder);
+    const collected = collectHandleData(
+      handle,
+      state.data,
+      state.segmentOrder,
+    ) as Rango.FlightSerialize<A>;
     return selector ? selector(collected) : collected;
   });
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
@@ -146,7 +69,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;
 
@@ -154,11 +77,31 @@ 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 = collectHandleData(
+      handle,
+      currentHandleState.data,
+      currentHandleState.segmentOrder,
+    ) as Rango.FlightSerialize<A>;
+    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 =
         ctx.eventController.getState().inflightActions.length > 0;
-      const collected = collectHandle(handle, state.data, state.segmentOrder);
+      const collected = collectHandleData(
+        handle,
+        state.data,
+        state.segmentOrder,
+      ) as Rango.FlightSerialize<A>;
       const nextValue = selectorRef.current
         ? selectorRef.current(collected)
         : collected;

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

@@ -1,208 +1,40 @@
 "use client";
 
-import { useContext } from "react";
-import { createHref, type ScopedHrefFunction } from "../../href.js";
-import type { UrlPatterns } from "../../urls.js";
-import { HrefContext, type HrefContextValue } from "../../href-context.js";
-
-// Re-export for backwards compatibility
-export { HrefContext, type HrefContextValue } from "../../href-context.js";
-
-/**
- * Resolution priority for href:
- * 1. Path-based (/blog/:slug) → Use directly
- * 2. Absolute name (shop.cart) → Global lookup (has dot separator)
- * 3. Local name (index) → Prepend current name prefix, then lookup
- */
-function resolveRouteName(
-  name: string,
-  routeMap: Record<string, string>,
-  currentRoutePrefix?: string
-): string | undefined {
-  // 1. Path-based - starts with /
-  if (name.startsWith("/")) {
-    return name;
-  }
-
-  // 2. Absolute name - already has a dot (e.g., "shop.cart")
-  if (name.includes(".")) {
-    return routeMap[name];
-  }
-
-  // 3. Local name - try with current prefix first, then fall back to direct lookup
-  if (currentRoutePrefix) {
-    // Extract the prefix from current route name
-    // e.g., "blog.posts.detail" → prefix is "blog.posts"
-    const lastDot = currentRoutePrefix.lastIndexOf(".");
-    const prefix = lastDot > 0 ? currentRoutePrefix.substring(0, lastDot) : currentRoutePrefix;
-
-    // Try prefixed name
-    const prefixedName = `${prefix}.${name}`;
-    if (routeMap[prefixedName] !== undefined) {
-      return routeMap[prefixedName];
-    }
-
-    // If current route is a nested include, try parent prefixes
-    // e.g., for "blog.posts.detail", try "blog.posts.index", then "blog.index"
-    let currentPrefix = prefix;
-    while (currentPrefix.includes(".")) {
-      const parentDot = currentPrefix.lastIndexOf(".");
-      currentPrefix = currentPrefix.substring(0, parentDot);
-      const parentPrefixedName = `${currentPrefix}.${name}`;
-      if (routeMap[parentPrefixedName] !== undefined) {
-        return routeMap[parentPrefixedName];
-      }
-    }
-  }
-
-  // Fall back to direct lookup (route without prefix)
-  return routeMap[name];
-}
+import { href, type ValidPaths } from "../../href-client.js";
+import { useMount } from "./use-mount.js";
 
 /**
- * Type for href function returned by useHref
- */
-export type HrefFn = {
-  /**
-   * Generate a URL from a route name
-   *
-   * @param name - Route name (local or absolute) or path-based URL
-   * @param params - Optional params for dynamic segments
-   * @returns The resolved URL
-   *
-   * @example
-   * ```tsx
-   * const href = useHref();
-   *
-   * // Local name (resolved with current prefix)
-   * href("index")         // → "/blog" (if inside blog patterns)
-   * href("post", { slug: "hello" }) // → "/blog/hello"
-   *
-   * // Absolute name (direct lookup)
-   * href("shop.cart")     // → "/shop/cart"
-   *
-   * // Path-based (used directly)
-   * href("/about")        // → "/about"
-   * ```
-   */
-  (name: string, params?: Record<string, string>): string;
-};
-
-/**
- * Client-side hook for resolving route names with current name prefix.
+ * Client-side hook for mount-aware URL resolution.
+ *
+ * Returns an href function that automatically prepends the current
+ * include() mount prefix. Inside an include("/shop", ...) scope,
+ * the returned function resolves local paths relative to /shop.
  *
- * Resolution priority:
- * 1. Path-based (`/blog/:slug`) → Use directly
- * 2. Absolute name (`shop.cart`) → Global lookup (contains dot)
- * 3. Local name (`index`) → Prepend current name prefix, then lookup
+ * For absolute paths (outside the current mount), use the bare
+ * href() function directly instead.
  *
- * @typeParam TPatterns - Optional patterns type for type-safe local route names
- * @returns A function to generate URLs from route names
+ * @returns A function that prepends the mount prefix to paths
  *
  * @example
  * ```tsx
  * "use client";
- * import { useHref } from "@rangojs/router/client";
- * import { blogPatterns } from "../urls/blog";
+ * import { useHref, href } from "@rangojs/router/client";
  *
- * function BlogNav() {
- *   // Type-safe: knows "index" | "post" are valid local names
- *   const href = useHref<typeof blogPatterns>();
+ * // Inside include("/shop", shopPatterns)
+ * function ShopNav() {
+ *   const href = useHref();
  *
  *   return (
  *     <>
- *       {/* Local names - type-safe, resolved with current name prefix *\/}
- *       <Link href={href("index")}>Blog Home</Link>
- *       <Link href={href("post", { slug: "hello" })}>Post</Link>
- *
- *       {/* Absolute names - explicit prefix *\/}
- *       <Link href={href("shop.cart")}>Cart</Link>
- *
- *       {/* Path-based - always works *\/}
- *       <Link href={href("/about")}>About</Link>
+ *       {// Local paths - auto-prefixed with /shop}
+ *       <Link to={href("/cart")}>Cart</Link>
+ *       <Link to={href("/product/widget")}>Widget</Link>
  *     </>
  *   );
  * }
  * ```
  */
-export function useHref<
-  TPatterns extends UrlPatterns<any, any> = UrlPatterns<any, Record<string, string>>
->(): TPatterns extends UrlPatterns<any, infer TRoutes>
-  ? ScopedHrefFunction<TRoutes>
-  : HrefFn {
-  const context = useContext(HrefContext);
-
-  if (!context) {
-    // Return a function that warns and returns the name as-is
-    return ((name: string, _params?: Record<string, string>) => {
-      if (process.env.NODE_ENV !== "production") {
-        console.warn(
-          "[useHref] HrefContext not found. Make sure HrefProvider is mounted. Returning name as-is."
-        );
-      }
-      return name;
-    }) as any;
-  }
-
-  const { routeMap, routeName } = context;
-
-  return ((name: string, params?: Record<string, string>) => {
-    // Path-based - return directly (optionally with param substitution)
-    if (name.startsWith("/")) {
-      if (params) {
-        // Substitute params in path-based URL
-        return name.replace(/:([^/]+)/g, (_, key) => {
-          const value = params[key];
-          if (value === undefined) {
-            throw new Error(`Missing param "${key}" for path "${name}"`);
-          }
-          return encodeURIComponent(value);
-        });
-      }
-      return name;
-    }
-
-    // Resolve route name
-    const pattern = resolveRouteName(name, routeMap, routeName);
-
-    if (pattern === undefined) {
-      throw new Error(
-        `Unknown route: "${name}"${routeName ? ` (current route: ${routeName})` : ""}`
-      );
-    }
-
-    // If no params, return pattern directly
-    if (!params) {
-      return pattern;
-    }
-
-    // Substitute params
-    return pattern.replace(/:([^/]+)/g, (_, key) => {
-      const value = params[key];
-      if (value === undefined) {
-        throw new Error(`Missing param "${key}" for route "${name}"`);
-      }
-      return encodeURIComponent(value);
-    });
-  }) as any;
-}
-
-/**
- * Provider component for href context
- * Used internally by NavigationProvider to pass route map from RSC metadata
- */
-export function HrefProvider({
-  routeMap,
-  routeName,
-  children,
-}: {
-  routeMap: Record<string, string>;
-  routeName?: string;
-  children: React.ReactNode;
-}) {
-  return (
-    <HrefContext.Provider value={{ routeMap, routeName }}>
-      {children}
-    </HrefContext.Provider>
-  );
+export function useHref(): (path: `/${string}`) => string {
+  const mount = useMount();
+  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-mount.ts

@@ -0,0 +1,31 @@
+"use client";
+
+import { useContext } from "react";
+import { MountContext } from "./mount-context.js";
+
+/**
+ * Returns the current include() mount path.
+ *
+ * Inside `include("/articles", blogPatterns)`, returns "/articles".
+ * For nested includes, returns the nearest mount path.
+ * At root level (no include), returns "/".
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useMount, href } from "@rangojs/router/client";
+ *
+ * function BlogNav({ slug }: { slug: string }) {
+ *   const mount = useMount(); // "/articles"
+ *   return (
+ *     <>
+ *       <Link to={href("/", mount)}>Blog Home</Link>
+ *       <Link to={href(`/${slug}`, mount)}>Post</Link>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function useMount(): string {
+  return useContext(MountContext);
+}