@rangojs/router 0.0.0-experimental.18 → 0.0.0-experimental.1878aa49

package/src/browser/react/Link.tsx

@@ -5,6 +5,7 @@ import React, {
   useCallback,
   useContext,
   useEffect,
+  useMemo,
   useRef,
   type ForwardRefExoticComponent,
   type RefAttributes,
@@ -31,13 +32,14 @@ export type LinkState =
   | LocationStateEntry[]
   | StateOrGetter<Record<string, unknown>>;
 
-import { prefetchDirect, prefetchQueued } from "../prefetch-fetch.js";
+import { prefetchDirect, prefetchQueued } from "../prefetch/fetch.js";
+import { getAppVersion } from "../app-version.js";
 import {
   observeForPrefetch,
   unobserveForPrefetch,
-} from "../prefetch-observer.js";
+} from "../prefetch/observer.js";
 
-// Touch device detection for hybrid strategy.
+// Touch device detection for adaptive strategy.
 // Checked once at module load (Link.tsx is "use client", runs only in browser).
 const isTouchDevice =
   typeof window !== "undefined" && window.matchMedia("(hover: none)").matches;
@@ -47,14 +49,14 @@ const isTouchDevice =
  * - "hover": Prefetch on mouse enter (direct, no queue)
  * - "viewport": Prefetch when link enters viewport (queued, waits for idle)
  * - "render": Prefetch on component mount regardless of visibility (queued, waits for idle)
- * - "hybrid": Hover on pointer devices, viewport on touch devices
+ * - "adaptive": Hover on pointer devices, viewport on touch devices
  * - "none": No prefetching (default)
  */
 export type PrefetchStrategy =
   | "hover"
   | "viewport"
   | "render"
-  | "hybrid"
+  | "adaptive"
   | "none";
 
 /**
@@ -80,6 +82,16 @@ export interface LinkProps extends Omit<
    * Force full document navigation instead of SPA
    */
   reloadDocument?: boolean;
+  /**
+   * Whether to revalidate server data on navigation.
+   * Set to `false` to skip the RSC server fetch and only update the URL.
+   *
+   * Only takes effect when the pathname stays the same (search param / hash changes).
+   * If the pathname changes, this option is ignored and a full navigation occurs.
+   *
+   * @default true
+   */
+  revalidate?: boolean;
   /**
    * Prefetch strategy for the link destination
    * @default "none"
@@ -170,6 +182,7 @@ export const Link: ForwardRefExoticComponent<
     replace = false,
     scroll = true,
     reloadDocument = false,
+    revalidate,
     prefetch = "none",
     state,
     children,
@@ -181,9 +194,19 @@ export const Link: ForwardRefExoticComponent<
   const ctx = useContext(NavigationStoreContext);
   const isExternal = isExternalUrl(to);
 
-  // Resolve hybrid: viewport on touch devices, hover on pointer devices
+  // Auto-prefix with basename for app-local paths.
+  // Skip if external, already prefixed, or not a root-relative path.
+  const resolvedTo = useMemo(() => {
+    if (isExternal) return to;
+    const bn = ctx?.basename;
+    if (!bn || !to.startsWith("/") || to.startsWith(bn + "/") || to === bn)
+      return to;
+    return to === "/" ? bn : bn + to;
+  }, [to, isExternal, ctx?.basename]);
+
+  // Resolve adaptive: viewport on touch devices, hover on pointer devices
   const resolvedStrategy =
-    prefetch === "hybrid" ? (isTouchDevice ? "viewport" : "hover") : prefetch;
+    prefetch === "adaptive" ? (isTouchDevice ? "viewport" : "hover") : prefetch;
 
   // Internal ref for viewport observation; merge with forwarded ref
   const internalRef = useRef<HTMLAnchorElement | null>(null);
@@ -235,41 +258,71 @@ export const Link: ForwardRefExoticComponent<
         return;
       }
 
+      // No navigation context (outside provider): fall back to native navigation.
+      if (!ctx?.navigate) {
+        return;
+      }
+
       // Prevent default and use SPA navigation
       e.preventDefault();
       // Stop propagation to prevent link-interceptor from also handling this
       e.stopPropagation();
 
-      if (ctx?.navigate) {
-        const currentState = stateRef.current;
-        let resolvedState: unknown;
-
-        if (
-          Array.isArray(currentState) &&
-          currentState.length > 0 &&
-          isLocationStateEntry(currentState[0])
-        ) {
-          resolvedState = resolveLocationStateEntries(
-            currentState as LocationStateEntry[],
-          );
-        } else if (typeof currentState === "function") {
-          resolvedState = currentState();
-        } else if (currentState != null) {
-          resolvedState = currentState;
-        }
-
-        ctx.navigate(to, { replace, scroll, state: resolvedState });
+      const currentState = stateRef.current;
+      let resolvedState: unknown;
+
+      if (
+        Array.isArray(currentState) &&
+        currentState.length > 0 &&
+        isLocationStateEntry(currentState[0])
+      ) {
+        resolvedState = resolveLocationStateEntries(
+          currentState as LocationStateEntry[],
+        );
+      } else if (typeof currentState === "function") {
+        resolvedState = currentState();
+      } else if (currentState != null) {
+        resolvedState = currentState;
       }
+
+      ctx.navigate(resolvedTo, {
+        replace,
+        scroll,
+        state: resolvedState,
+        revalidate,
+      });
     },
-    [to, isExternal, reloadDocument, replace, scroll, ctx, onClick],
+    [
+      resolvedTo,
+      isExternal,
+      reloadDocument,
+      replace,
+      scroll,
+      revalidate,
+      ctx,
+      onClick,
+    ],
   );
 
   const handleMouseEnter = useCallback(() => {
-    if (resolvedStrategy === "hover" && !isExternal && ctx?.store) {
+    if (
+      (resolvedStrategy === "hover" || resolvedStrategy === "viewport") &&
+      !isExternal &&
+      ctx?.store
+    ) {
+      // For "hover", this is the primary prefetch trigger.
+      // For "viewport", this upgrades/prioritizes a potentially queued
+      // prefetch — prefetchDirect bypasses the queue, and hasPrefetch
+      // deduplicates if the viewport prefetch already completed.
       const segmentState = ctx.store.getSegmentState();
-      prefetchDirect(to, segmentState.currentSegmentIds, ctx.version);
+      prefetchDirect(
+        resolvedTo,
+        segmentState.currentSegmentIds,
+        getAppVersion(),
+        ctx.store.getRouterId?.(),
+      );
     }
-  }, [resolvedStrategy, to, isExternal, ctx]);
+  }, [resolvedStrategy, resolvedTo, isExternal, ctx]);
 
   // Viewport/render prefetch: waits for idle before starting,
   // uses concurrency-limited queue to avoid flooding.
@@ -281,11 +334,17 @@ export const Link: ForwardRefExoticComponent<
 
     let cancelled = false;
     let unsubIdle: (() => void) | undefined;
+    let observedElement: Element | null = null;
 
     const triggerPrefetch = () => {
       if (cancelled) return;
       const segmentState = ctx.store.getSegmentState();
-      prefetchQueued(to, segmentState.currentSegmentIds, ctx.version);
+      prefetchQueued(
+        resolvedTo,
+        segmentState.currentSegmentIds,
+        getAppVersion(),
+        ctx.store.getRouterId?.(),
+      );
     };
 
     // Schedule prefetch only when the app is idle (no navigation/streaming).
@@ -311,6 +370,7 @@ export const Link: ForwardRefExoticComponent<
     } else if (isViewport) {
       const element = internalRef.current;
       if (!element) return;
+      observedElement = element;
       observeForPrefetch(element, () => {
         scheduleWhenIdle(triggerPrefetch);
       });
@@ -319,25 +379,26 @@ export const Link: ForwardRefExoticComponent<
     return () => {
       cancelled = true;
       unsubIdle?.();
-      if (isViewport && internalRef.current) {
-        unobserveForPrefetch(internalRef.current);
+      if (isViewport && observedElement) {
+        unobserveForPrefetch(observedElement);
       }
     };
-  }, [resolvedStrategy, to, isExternal, ctx]);
+  }, [resolvedStrategy, resolvedTo, isExternal, ctx]);
 
   return (
     <a
       ref={setRef}
-      href={to}
+      href={resolvedTo}
       onClick={handleClick}
       onMouseEnter={handleMouseEnter}
       data-link-component
       data-external={isExternal ? "" : undefined}
       data-scroll={scroll === false ? "false" : undefined}
       data-replace={replace ? "true" : undefined}
+      data-revalidate={revalidate === false ? "false" : undefined}
       {...props}
     >
-      <LinkContext.Provider value={to}>{children}</LinkContext.Provider>
+      <LinkContext.Provider value={resolvedTo}>{children}</LinkContext.Provider>
     </a>
   );
 });

package/src/browser/react/NavigationProvider.tsx

@@ -3,8 +3,10 @@
 import React, {
   useState,
   useEffect,
+  useLayoutEffect,
   useCallback,
   useMemo,
+  useRef,
   use,
   type ReactNode,
 } from "react";
@@ -22,8 +24,10 @@ import type { EventController } from "../event-controller.js";
 import { RootErrorBoundary } from "../../root-error-boundary.js";
 import type { HandleData } from "../types.js";
 import { ThemeProvider } from "../../theme/ThemeProvider.js";
+import { NonceContext } from "./nonce-context.js";
 import type { ResolvedThemeConfig, Theme } from "../../theme/types.js";
-import { cancelAllPrefetches } from "../prefetch-queue.js";
+import { cancelAllPrefetches } from "../prefetch/queue.js";
+import { handleNavigationEnd } from "../scroll-restoration.js";
 
 /**
  * Process handles from an async generator, updating the event controller
@@ -130,9 +134,14 @@ export interface NavigationProviderProps {
 
   /**
    * App version from server payload (stable, immutable).
-   * Forwarded to prefetch requests for version mismatch detection.
+   * Forwarded to context for cache key building.
    */
   version?: string;
+
+  /**
+   * URL prefix for all routes (from createRouter({ basename })).
+   */
+  basename?: string;
 }
 
 /**
@@ -165,6 +174,7 @@ export function NavigationProvider({
   initialTheme,
   warmupEnabled,
   version,
+  basename,
 }: NavigationProviderProps): ReactNode {
   // Track current payload for rendering (this triggers re-renders)
   const [payload, setPayload] = useState(initialPayload);
@@ -194,6 +204,7 @@ export function NavigationProvider({
       navigate,
       refresh,
       version,
+      basename,
     }),
     [],
   );
@@ -285,24 +296,50 @@ export function NavigationProvider({
     };
   }, [warmupEnabled]);
 
-  // Cancel speculative prefetches when navigation starts.
-  // Viewport/render prefetches should not compete with navigation fetches.
+  // Cancel non-matching prefetches when navigation starts.
+  // Frees connections so the navigation fetch isn't competing with
+  // speculative prefetches. The prefetch matching the navigation target
+  // is kept alive so it can be reused via consumeInflightPrefetch.
   useEffect(() => {
     let wasIdle = true;
     const unsub = eventController.subscribe(() => {
       const state = eventController.getState();
       const isIdle = state.state === "idle" && !state.isStreaming;
       if (wasIdle && !isIdle) {
-        cancelAllPrefetches();
+        cancelAllPrefetches(state.pendingUrl);
       }
       wasIdle = isIdle;
     });
     return unsub;
   }, [eventController]);
 
+  // Pending scroll action to apply after React commits
+  const pendingScrollRef = useRef<NavigationUpdate["scroll"]>(undefined);
+
+  // Apply scroll after React commits the new content to the DOM
+  useLayoutEffect(() => {
+    const scrollAction = pendingScrollRef.current;
+    if (!scrollAction) return;
+    pendingScrollRef.current = undefined;
+
+    if (scrollAction.enabled === false) return;
+
+    handleNavigationEnd({
+      restore: scrollAction.restore,
+      scroll: scrollAction.enabled,
+      isStreaming: scrollAction.isStreaming,
+    });
+  });
+
   // Subscribe to UI updates (for re-rendering the tree)
   useEffect(() => {
     const unsubscribe = store.onUpdate((update) => {
+      // Capture scroll intent — it will be applied in useLayoutEffect
+      // after React commits this state update to the DOM.
+      // Always assign (even undefined) to clear stale scroll from prior navigations,
+      // so server actions or error updates don't accidentally replay old scroll.
+      pendingScrollRef.current = update.scroll;
+
       setPayload({
         root: update.root,
         metadata: update.metadata,
@@ -370,6 +407,13 @@ export function NavigationProvider({
     );
   }
 
+  // Match SSR tree shape: NonceContext.Provider is always present so
+  // hydration sees the same component tree. Value is undefined on the
+  // client — CSP nonces are a server-side HTML concern.
+  content = (
+    <NonceContext.Provider value={undefined}>{content}</NonceContext.Provider>
+  );
+
   return (
     <NavigationStoreContext.Provider value={contextValue}>
       {content}

package/src/browser/react/context.ts

@@ -43,10 +43,15 @@ export interface NavigationStoreContextValue {
   refresh: () => Promise<void>;
 
   /**
-   * App version from server payload (stable, immutable).
-   * Used in prefetch requests for version mismatch detection.
+   * App version from the initial server payload.
    */
   version: string | undefined;
+
+  /**
+   * URL prefix for all routes (from createRouter({ basename })).
+   * Used by Link and useRouter() to auto-prefix app-local paths.
+   */
+  basename: string | undefined;
 }
 
 /**

package/src/browser/react/index.ts

@@ -15,14 +15,10 @@ export { useParams } from "./use-params.js";
 export { useAction, type TrackedActionState } from "./use-action.js";
 
 // Segments state hook
-export {
-  useSegments,
-  initSegmentsSync,
-  type SegmentsState,
-} from "./use-segments.js";
+export { useSegments, type SegmentsState } from "./use-segments.js";
 
 // Handle data hook
-export { useHandle, initHandleDataSync } from "./use-handle.js";
+export { useHandle } from "./use-handle.js";
 
 // Client cache controls hook
 export {

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

@@ -79,7 +79,7 @@ export function createLocationState<TState>(
   let _key: string | undefined;
 
   function getKey(): string {
-    if (!_key && process.env.NODE_ENV !== "production") {
+    if (!_key && process.env.NODE_ENV === "development") {
       throw new Error(
         "[rsc-router] createLocationState key not set. " +
           "Make sure the exposeInternalIds Vite plugin is enabled and " +

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

@@ -80,6 +80,8 @@ export function useLocationState<TArgs extends unknown[], TState>(
         } else {
           setState(val);
         }
+      } else {
+        setState(window.history.state?.state as TState | undefined);
       }
     };
 

package/src/browser/react/nonce-context.ts

@@ -0,0 +1,23 @@
+"use client";
+
+/**
+ * Context for CSP nonce propagation to client components during SSR.
+ *
+ * The SSR renderer wraps the tree with NonceContext.Provider so that
+ * client components (e.g. MetaTags) can apply nonces to inline scripts.
+ * On the browser side, no provider is needed — the default undefined
+ * is correct since CSP nonces are a server-side HTML concern.
+ */
+
+import { createContext, useContext, type Context } from "react";
+
+export const NonceContext: Context<string | undefined> = createContext<
+  string | undefined
+>(undefined);
+
+/**
+ * Read the CSP nonce during SSR. Returns undefined on the client.
+ */
+export function useNonce(): string | undefined {
+  return useContext(NonceContext);
+}

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

@@ -127,6 +127,11 @@ 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.
  */
@@ -162,7 +167,10 @@ export function useAction<T>(
     T | TrackedActionState
   >(null!);
 
-  // Ref keeps the latest selector without re-subscribing on every render.
+  // 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;
 

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

@@ -12,17 +12,8 @@ import type { Handle } from "../../handle.js";
 import { getCollectFn } from "../../handle.js";
 import type { HandleData } from "../types.js";
 import { NavigationStoreContext } from "./context.js";
-import { filterSegmentOrder } from "./filter-segment-order.js";
 import { shallowEqual } from "./shallow-equal.js";
 
-/**
- * SSR module-level state.
- * Populated by initHandleDataSync before React renders.
- * Used by useState initializer during SSR.
- */
-let ssrHandleData: HandleData = {};
-let ssrSegmentOrder: string[] = [];
-
 /**
  * Resolve the collect function for a handle.
  * Handle objects are plain { __brand, $$id } - collect is stored in the registry
@@ -76,18 +67,6 @@ function collectHandle<T, A>(
   return collect(segmentArrays);
 }
 
-/**
- * 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.
  *
@@ -117,11 +96,10 @@ export function useHandle<T, 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;
     }
 

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

@@ -3,7 +3,6 @@
 import { useContext, useState, useEffect, useRef } from "react";
 import { NavigationStoreContext } from "./context.js";
 import { shallowEqual } from "./shallow-equal.js";
-import { getSsrParams } from "./use-segments.js";
 
 /**
  * Hook to access the current route params.
@@ -31,9 +30,8 @@ export function useParams<T>(
   const ctx = useContext(NavigationStoreContext);
 
   const [value, setValue] = useState<T | Record<string, string>>(() => {
-    if (typeof document === "undefined" || !ctx) {
-      const ssrParams = getSsrParams();
-      return selector ? selector(ssrParams) : ssrParams;
+    if (!ctx) {
+      return selector ? selector({}) : {};
     }
     const params = ctx.eventController.getParams();
     return selector ? selector(params) : params;

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

@@ -2,7 +2,6 @@
 
 import { useContext, useState, useEffect, useRef } from "react";
 import { NavigationStoreContext } from "./context.js";
-import { getSsrPathname } from "./use-segments.js";
 
 /**
  * Hook to access the current pathname.
@@ -20,8 +19,8 @@ export function usePathname(): string {
   const ctx = useContext(NavigationStoreContext);
 
   const [pathname, setPathname] = useState<string>(() => {
-    if (typeof document === "undefined" || !ctx) {
-      return getSsrPathname();
+    if (!ctx) {
+      return "/";
     }
     return (ctx.eventController.getState().location as URL).pathname;
   });

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

@@ -2,7 +2,8 @@
 
 import { useContext, useMemo } from "react";
 import { NavigationStoreContext } from "./context.js";
-import { prefetchDirect } from "../prefetch-fetch.js";
+import { prefetchDirect } from "../prefetch/fetch.js";
+import { getAppVersion } from "../app-version.js";
 import type { RouterInstance, RouterNavigateOptions } from "../types.js";
 
 /**
@@ -29,14 +30,22 @@ export function useRouter(): RouterInstance {
   }
 
   // Stable reference: ctx is itself stable (NavigationProvider memoizes with [])
-  return useMemo<RouterInstance>(
-    () => ({
+  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> {
@@ -46,7 +55,12 @@ export function useRouter(): RouterInstance {
       prefetch(url: string): void {
         const segmentState = ctx.store?.getSegmentState();
         if (segmentState) {
-          prefetchDirect(url, segmentState.currentSegmentIds, ctx.version);
+          prefetchDirect(
+            withBasename(url),
+            segmentState.currentSegmentIds,
+            getAppVersion(),
+            ctx.store?.getRouterId?.(),
+          );
         }
       },
 
@@ -57,7 +71,6 @@ export function useRouter(): RouterInstance {
       forward(): void {
         window.history.forward();
       },
-    }),
-    [],
-  );
+    };
+  }, []);
 }

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

@@ -41,7 +41,8 @@ export function useSearchParams(): ReadonlyURLSearchParams {
       const nextSearch = location.searchParams.toString();
       if (nextSearch !== prevSearch.current) {
         prevSearch.current = nextSearch;
-        setSearchParams(location.searchParams);
+        // Create a snapshot so callers cannot mutate the source URLSearchParams
+        setSearchParams(new URLSearchParams(nextSearch));
       }
     };