@rangojs/router 0.0.0-experimental.31 → 0.0.0-experimental.3232cd17

package/src/browser/react/location-state.ts

@@ -1,9 +1,8 @@
 "use client";
 
-import { useState, useEffect } from "react";
+import { useState, useEffect, useRef } from "react";
 import type { LocationStateDefinition } from "./location-state-shared.js";
 
-// Re-export shared utilities and types
 export {
   createLocationState,
   isLocationStateEntry,
@@ -13,6 +12,24 @@ export {
   type LocationStateOptions,
 } from "./location-state-shared.js";
 
+function readLocationStateValue<TState>(
+  key: string | undefined,
+): TState | undefined {
+  if (typeof window === "undefined") return undefined;
+  if (key) {
+    return window.history.state?.[key] as TState | undefined;
+  }
+  // Plain state: stored under history.state.state
+  return window.history.state?.state as TState | undefined;
+}
+
+function hasHydrated(): boolean {
+  return (
+    typeof document !== "undefined" &&
+    document.documentElement.hasAttribute("data-hydrated")
+  );
+}
+
 /**
  * Hook to read location state from history.state
  *
@@ -48,30 +65,33 @@ export function useLocationState<TArgs extends unknown[], TState>(
   const key = definition?.__rsc_ls_key;
   const isFlash = definition?.__rsc_ls_flash ?? false;
 
+  // Track whether the initial render returned undefined because the page
+  // hadn't hydrated yet. If so, the mount effect catches up by reading
+  // history.state once. If not, we already have the right value and must
+  // not re-read on mount — under StrictMode, the flash-cleanup effect runs
+  // before the second setup pass, so a re-read would clobber the captured
+  // value with the now-cleared `undefined`.
+  const initialReadDeferredRef = useRef(false);
+
   const [state, setState] = useState<TState | undefined>(() => {
-    if (typeof window === "undefined") return undefined;
-    if (key) {
-      return window.history.state?.[key] as TState | undefined;
+    if (!hasHydrated()) {
+      initialReadDeferredRef.current = true;
+      return undefined;
     }
-    // Plain state: stored under history.state.state
-    return window.history.state?.state as TState | undefined;
+    return readLocationStateValue<TState>(key);
   });
 
   // Subscribe to popstate and programmatic state changes
   useEffect(() => {
     const handlePopstate = () => {
-      if (key) {
-        setState(window.history.state?.[key] as TState | undefined);
-      } else {
-        setState(window.history.state?.state as TState | undefined);
-      }
+      setState(readLocationStateValue<TState>(key));
     };
 
     // Handle programmatic state changes (same-page navigation with
     // ctx.setLocationState where components don't remount)
     const handleLocationState = () => {
       if (key) {
-        const val = window.history.state?.[key] as TState | undefined;
+        const val = readLocationStateValue<TState>(key);
         if (isFlash) {
           // For flash state, only update if there's a new value
           if (val !== undefined) {
@@ -81,10 +101,15 @@ export function useLocationState<TArgs extends unknown[], TState>(
           setState(val);
         }
       } else {
-        setState(window.history.state?.state as TState | undefined);
+        setState(readLocationStateValue<TState>(key));
       }
     };
 
+    if (initialReadDeferredRef.current) {
+      initialReadDeferredRef.current = false;
+      setState(readLocationStateValue<TState>(key));
+    }
+
     window.addEventListener("popstate", handlePopstate);
     window.addEventListener("__rsc_locationstate", handleLocationState);
     return () => {

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

@@ -24,32 +24,24 @@ const DEFAULT_ACTION_STATE: TrackedActionState = {
   result: null,
 };
 
-/**
- * Normalize action ID - returns the ID as-is
- *
- * Server actions have IDs like "hash#actionName" or "src/actions.ts#actionName".
- * When using function references, we use the full ID for exact matching.
- * When using strings, the event controller supports suffix matching
- * (e.g., "addToCart" matches "hash#addToCart").
- */
-function normalizeActionId(actionId: string): string {
-  return actionId;
-}
-
 /**
  * Extract action ID from a server action function or string.
  *
  * Actions passed as props from server components lose their metadata
  * during RSC serialization - use a string action name instead.
+ *
+ * The extracted $$id (e.g. "hash#actionName" or "src/actions.ts#actionName")
+ * is returned as-is. Suffix-vs-exact matching against this ID happens
+ * downstream in the event controller, not here.
  */
-export function getActionId(action: ServerActionFunction | string): string {
+function getActionId(action: ServerActionFunction | string): string {
   invariant(
     typeof action === "function" || typeof action === "string",
     `useAction: action must be a function or string, got ${typeof action}`,
   );
   const actionId = (action as any)?.$$id;
   if (actionId) {
-    return normalizeActionId(actionId);
+    return actionId;
   }
 
   // If action is a string, use it directly
@@ -162,7 +154,6 @@ export function useAction<T>(
   });
   const prevSelected = useRef(baseState);
   prevSelected.current = baseState;
-  // useOptimistic allows immediate updates during transitions/actions
   const [optimisticState, setOptimisticState] = useOptimistic<
     T | TrackedActionState
   >(null!);

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

@@ -9,64 +9,11 @@ import {
   startTransition,
 } from "react";
 import type { Handle } from "../../handle.js";
-import { getCollectFn } from "../../handle.js";
+import { collectHandleData } from "../../handle.js";
 import type { HandleData } from "../types.js";
 import { NavigationStoreContext } from "./context.js";
 import { shallowEqual } from "./shallow-equal.js";
 
-/**
- * Resolve the collect function for a handle.
- * 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 {
-  // 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;
-  }
-
-  // Fall back to default flat collect with a dev warning.
-  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.`,
-    );
-  }
-  return ((segments: unknown[][]) => segments.flat()) as unknown as (
-    segments: T[][],
-  ) => A;
-}
-
-/**
- * Collect handle data from segments and transform to final value.
- */
-function collectHandle<T, A>(
-  handle: Handle<T, A>,
-  data: HandleData,
-  segmentOrder: string[],
-): A {
-  const collect = resolveCollect(handle);
-  const segmentData = data[handle.$$id];
-
-  if (!segmentData) {
-    return 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 collect(segmentArrays);
-}
-
 /**
  * Hook to access collected handle data.
  *
@@ -85,51 +32,54 @@ function collectHandle<T, A>(
  * 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 context event controller, or empty fallback without provider.
-  const [value, setValue] = useState<A | S>(() => {
+  const [value, setValue] = useState<Rango.FlightSerialize<A> | S>(() => {
     if (!ctx) {
-      const collected = collectHandle(handle, {}, []);
+      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);
 
-  // Track previous value for shallow comparison
   const prevValueRef = useRef(value);
   prevValueRef.current = value;
 
-  // Ref keeps the latest selector without re-subscribing on every render.
   const selectorRef = useRef(selector);
   selectorRef.current = selector;
 
-  // Subscribe to handle data changes (client only)
   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(
+    const currentCollected = collectHandleData(
       handle,
       currentHandleState.data,
       currentHandleState.segmentOrder,
-    );
+    ) as Rango.FlightSerialize<A>;
     const currentValue = selectorRef.current
       ? selectorRef.current(currentCollected)
       : currentCollected;
@@ -142,7 +92,11 @@ export function useHandle<T, A, S>(
       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-link-status.ts

@@ -82,11 +82,9 @@ export function useLinkStatus(): LinkStatus {
   const linkTo = useContext(LinkContext);
   const ctx = useContext(NavigationStoreContext);
 
-  // Get origin for URL normalization (stable across renders)
   const origin =
     typeof window !== "undefined" ? window.location.origin : "http://localhost";
 
-  // Base state for useOptimistic
   const [basePending, setBasePending] = useState<boolean>(() => {
     if (!ctx || linkTo === null) {
       return false;
@@ -97,7 +95,6 @@ export function useLinkStatus(): LinkStatus {
 
   const prevPending = useRef(basePending);
 
-  // useOptimistic allows immediate updates during transitions
   const [pending, setOptimisticPending] = useOptimistic(basePending);
 
   useEffect(() => {
@@ -105,7 +102,6 @@ export function useLinkStatus(): LinkStatus {
       return;
     }
 
-    // Subscribe to navigation state changes
     return ctx.eventController.subscribe(() => {
       const state = ctx.eventController.getState();
       const isPending = isPendingFor(linkTo, state.pendingUrl, origin);

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

@@ -46,14 +46,18 @@ export function useNavigation<T>(
     throw new Error("useNavigation must be used within NavigationProvider");
   }
 
-  // Base state for useOptimistic
   const [baseValue, setBaseValue] = useState<T | PublicNavigationState>(() => {
     const publicState = toPublicState(ctx.eventController.getState());
     return selector ? selector(publicState) : publicState;
   });
   const prevState = useRef(baseValue);
 
-  // useOptimistic allows immediate updates during transitions/actions
+  // Tracks whether the most recent setOptimisticValue call pinned the value
+  // to a non-idle state. Used to decide whether to emit a release update when
+  // returning to idle, so the optimistic store doesn't stay pinned if a
+  // parent transition (e.g. <Link> click) is still pending.
+  const optimisticPinnedRef = useRef(false);
+
   const [value, setOptimisticValue] = useOptimistic(baseValue);
 
   // Store selector in a ref so the subscription callback always uses the
@@ -66,7 +70,6 @@ export function useNavigation<T>(
 
   // 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);
@@ -82,11 +85,25 @@ export function useNavigation<T>(
         const hasInflightActions =
           ctx.eventController.getInflightActions().size > 0;
 
-        if (hasInflightActions || publicState.state !== "idle") {
-          // Use optimistic update for immediate feedback during transitions
+        const shouldPin = hasInflightActions || publicState.state !== "idle";
+
+        if (shouldPin) {
+          // Pin the optimistic store so the loading value shows immediately
+          // even if a parent transition (e.g. <Link> click) defers the
+          // urgent setBaseValue commit.
+          startTransition(() => {
+            setOptimisticValue(nextSelected);
+          });
+          optimisticPinnedRef.current = true;
+        } else if (optimisticPinnedRef.current) {
+          // Release a previously-pinned optimistic value. Without this,
+          // useOptimistic keeps returning the stale loading value while
+          // any parent transition is still pending, even after baseValue
+          // flipped to idle.
           startTransition(() => {
             setOptimisticValue(nextSelected);
           });
+          optimisticPinnedRef.current = false;
         }
 
         // Always update base state so UI reflects current state

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

@@ -4,6 +4,8 @@ import { useContext, useState, useEffect, useRef } from "react";
 import { NavigationStoreContext } from "./context.js";
 import { shallowEqual } from "./shallow-equal.js";
 
+const EMPTY_PARAMS: Record<string, string> = Object.freeze({});
+
 /**
  * Hook to access the current route params.
  *
@@ -16,30 +18,38 @@ import { shallowEqual } from "./shallow-equal.js";
  * const params = useParams();
  * // { productId: "123" }
  *
+ * // Annotate the expected shape via a generic
+ * const { productId } = useParams<{ productId: string }>();
+ *
  * // With selector
  * const productId = useParams(p => p.productId);
  * ```
  */
-export function useParams(): Record<string, string>;
+// `T extends object` (not `Record<string, string | undefined>`) so that
+// interface shapes pass the constraint — interfaces lack an implicit
+// index signature and would otherwise be rejected. The generic is a
+// shape annotation, not a runtime check; the body always returns the
+// underlying params map unchanged. The default and selector input use
+// `string | undefined` because absent optional params are omitted from
+// the params record at runtime — the type must reflect that so callers
+// don't write `p.locale.length` and crash when the segment is absent.
+export function useParams<
+  T extends object = Record<string, string | undefined>,
+>(): Readonly<T>;
 export function useParams<T>(
-  selector: (params: Record<string, string>) => T,
+  selector: (params: Record<string, string | undefined>) => T,
 ): T;
 export function useParams<T>(
-  selector?: (params: Record<string, string>) => T,
-): T | Record<string, string> {
+  selector?: (params: Record<string, string | undefined>) => T,
+): T | Record<string, string | undefined> {
   const ctx = useContext(NavigationStoreContext);
 
   const [value, setValue] = useState<T | Record<string, string>>(() => {
-    if (!ctx) {
-      return selector ? selector({}) : {};
-    }
-    const params = ctx.eventController.getParams();
+    const params = ctx ? ctx.eventController.getParams() : EMPTY_PARAMS;
     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;
 

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

@@ -3,6 +3,7 @@
 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";
 
 /**
@@ -12,6 +13,11 @@ import type { RouterInstance, RouterNavigateOptions } from "../types.js";
  * 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();
@@ -28,36 +34,65 @@ export function useRouter(): RouterInstance {
     throw new Error("useRouter must be used within NavigationProvider");
   }
 
-  // Stable reference: ctx is itself stable (NavigationProvider memoizes with [])
-  return useMemo<RouterInstance>(
-    () => ({
+  // 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(url, { ...options, replace: false });
+        return ctx.navigate(withBasename(url), { ...options, replace: false });
       },
 
       replace(url: string, options?: RouterNavigateOptions): Promise<void> {
-        return ctx.navigate(url, { ...options, replace: true });
+        return ctx.navigate(withBasename(url), { ...options, replace: true });
       },
 
       refresh(): Promise<void> {
         return ctx.refresh();
       },
 
-      prefetch(url: string): void {
+      prefetch(url: string, options?: { key?: ":source" }): void {
         const segmentState = ctx.store?.getSegmentState();
         if (segmentState) {
-          prefetchDirect(url, segmentState.currentSegmentIds, ctx.version);
+          prefetchDirect(
+            withBasename(url),
+            segmentState.currentSegmentIds,
+            getAppVersion(),
+            ctx.store?.getRouterId?.(),
+            options?.key,
+          );
         }
       },
 
       back(): void {
-        window.history.back();
+        // 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

@@ -24,9 +24,6 @@ import type { ReadonlyURLSearchParams } from "../types.js";
 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(),
   );
@@ -41,12 +38,10 @@ export function useSearchParams(): ReadonlyURLSearchParams {
       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);