@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.26

package/src/browser/react/Link.tsx

@@ -4,40 +4,58 @@ import React, {
   forwardRef,
   useCallback,
   useContext,
+  useEffect,
   useRef,
   type ForwardRefExoticComponent,
   type RefAttributes,
 } from "react";
 import { NavigationStoreContext } from "./context.js";
 import { LinkContext } from "./use-link-status.js";
-import { prefetchUrl } from "./prefetch.js";
 import type { NavigateOptions } from "../types.js";
+import { isHashOnlyNavigation } from "../link-interceptor.js";
 import {
-  type LocationStateEntry,
   isLocationStateEntry,
+  type LocationStateEntry,
   resolveLocationStateEntries,
 } from "./location-state.js";
 
 /**
- * State value or getter function for just-in-time state resolution (legacy)
+ * State prop type for Link component.
+ * - LocationStateEntry[]: Type-safe state entries via createLocationState()
+ * - StateOrGetter: Plain state object or click-time getter function
+ * - Record<string, unknown>: Plain state object passed to history.pushState
  */
 export type StateOrGetter<T = unknown> = T | (() => T);
 
-/**
- * State prop type for Link component
- * - LocationStateEntry[]: Type-safe state entries (always lazy)
- * - StateOrGetter: Legacy format for backwards compatibility
- */
-export type LinkState = LocationStateEntry[] | StateOrGetter;
+export type LinkState =
+  | LocationStateEntry[]
+  | StateOrGetter<Record<string, unknown>>;
+
+import { prefetchDirect, prefetchQueued } from "../prefetch/fetch.js";
+import {
+  observeForPrefetch,
+  unobserveForPrefetch,
+} from "../prefetch/observer.js";
+
+// 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;
 
 /**
  * Prefetch strategy for the Link component
- * - "hover": Prefetch on mouse enter (uses native <link rel="prefetch">)
- * - "viewport": Prefetch when link enters viewport (not yet implemented)
- * - "hybrid": Hover on desktop, viewport on mobile (not yet implemented)
+ * - "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)
+ * - "adaptive": Hover on pointer devices, viewport on touch devices
  * - "none": No prefetching (default)
  */
-export type PrefetchStrategy = "hover" | "viewport" | "hybrid" | "none";
+export type PrefetchStrategy =
+  | "hover"
+  | "viewport"
+  | "render"
+  | "adaptive"
+  | "none";
 
 /**
  * Link component props
@@ -74,16 +92,29 @@ export interface LinkProps extends Omit<
    * @example
    * ```tsx
    * // Type-safe state with createLocationState (recommended)
-   * const ProductState = createLocationState((p: Product) => ({ name: p.name }));
-   * <Link to="/product" state={[ProductState(product)]}>View</Link>
+   * const ProductState = createLocationState<{ name: string; price: number }>();
+   * <Link to="/product" state={[ProductState({ name: product.name, price: product.price })]}>
+   *   View
+   * </Link>
+   *
+   * // Type-safe just-in-time state (getter called at click time, not render time).
+   * // Must be in a client component -- getter can't cross the RSC boundary.
+   * <Link
+   *   to="/product"
+   *   state={[ProductState(() => ({ name: product.name, price: product.price }))]}
+   * >
+   *   View
+   * </Link>
    *
    * // Multiple typed states
-   * <Link to="/checkout" state={[ProductState(p), CartState(c)]}>Checkout</Link>
+   * <Link to="/checkout" state={[ProductState({ name: p.name, price: p.price }), CartState(c)]}>
+   *   Checkout
+   * </Link>
    *
-   * // Legacy: static state
+   * // Plain static state
    * <Link to="/product" state={{ from: "list" }}>View</Link>
    *
-   * // Legacy: dynamic state (called at click time)
+   * // Plain just-in-time state (called at click time, requires client component)
    * <Link to="/product" state={() => ({ scrollY: window.scrollY })}>View</Link>
    * ```
    */
@@ -150,6 +181,25 @@ export const Link: ForwardRefExoticComponent<
   const ctx = useContext(NavigationStoreContext);
   const isExternal = isExternalUrl(to);
 
+  // Resolve adaptive: viewport on touch devices, hover on pointer devices
+  const resolvedStrategy =
+    prefetch === "adaptive" ? (isTouchDevice ? "viewport" : "hover") : prefetch;
+
+  // Internal ref for viewport observation; merge with forwarded ref
+  const internalRef = useRef<HTMLAnchorElement | null>(null);
+  const setRef = useCallback(
+    (node: HTMLAnchorElement | null) => {
+      internalRef.current = node;
+      if (typeof ref === "function") {
+        ref(node);
+      } else if (ref) {
+        (ref as React.MutableRefObject<HTMLAnchorElement | null>).current =
+          node;
+      }
+    },
+    [ref],
+  );
+
   // Use ref to always get the latest state/getter without adding to useCallback deps
   // This enables just-in-time state resolution without causing re-renders
   const stateRef = useRef(state);
@@ -180,49 +230,109 @@ export const Link: ForwardRefExoticComponent<
       const target = (e.currentTarget as HTMLAnchorElement).target;
       if (target && target !== "_self") return;
 
+      // Hash-only navigation: let the browser handle anchor scrolling natively.
+      if (isHashOnlyNavigation(e.currentTarget as HTMLAnchorElement)) {
+        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) {
-        // Resolve state just-in-time based on format
-        let resolvedState: unknown;
-        const currentState = stateRef.current;
-
-        if (
-          Array.isArray(currentState) &&
-          currentState.length > 0 &&
-          isLocationStateEntry(currentState[0])
-        ) {
-          // Type-safe LocationStateEntry[] - resolve each entry into keyed object
-          resolvedState = resolveLocationStateEntries(
-            currentState as LocationStateEntry[],
-          );
-        } else if (typeof currentState === "function") {
-          // Legacy getter function
-          resolvedState = currentState();
-        } else {
-          // Legacy static value
-          resolvedState = currentState;
-        }
+      const currentState = stateRef.current;
+      let resolvedState: unknown;
 
-        ctx.navigate(to, { replace, scroll, state: resolvedState });
+      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 });
     },
     [to, isExternal, reloadDocument, replace, scroll, ctx, onClick],
   );
 
   const handleMouseEnter = useCallback(() => {
-    if (prefetch === "hover" && !isExternal && ctx?.store) {
+    if (resolvedStrategy === "hover" && !isExternal && ctx?.store) {
+      const segmentState = ctx.store.getSegmentState();
+      prefetchDirect(to, segmentState.currentSegmentIds, ctx.version);
+    }
+  }, [resolvedStrategy, to, isExternal, ctx]);
+
+  // Viewport/render prefetch: waits for idle before starting,
+  // uses concurrency-limited queue to avoid flooding.
+  useEffect(() => {
+    if (isExternal || !ctx?.store) return;
+    const isViewport = resolvedStrategy === "viewport";
+    const isRender = resolvedStrategy === "render";
+    if (!isViewport && !isRender) return;
+
+    let cancelled = false;
+    let unsubIdle: (() => void) | undefined;
+    let observedElement: Element | null = null;
+
+    const triggerPrefetch = () => {
+      if (cancelled) return;
       const segmentState = ctx.store.getSegmentState();
-      prefetchUrl(to, segmentState.currentSegmentIds);
+      prefetchQueued(to, segmentState.currentSegmentIds, ctx.version);
+    };
+
+    // Schedule prefetch only when the app is idle (no navigation/streaming).
+    // This avoids competing with hydration and active navigation fetches.
+    const scheduleWhenIdle = (callback: () => void) => {
+      const state = ctx.eventController.getState();
+      if (state.state === "idle" && !state.isStreaming) {
+        callback();
+        return;
+      }
+      const unsub = ctx.eventController.subscribe(() => {
+        const s = ctx.eventController.getState();
+        if (s.state === "idle" && !s.isStreaming) {
+          unsub();
+          callback();
+        }
+      });
+      unsubIdle = unsub;
+    };
+
+    if (isRender) {
+      scheduleWhenIdle(triggerPrefetch);
+    } else if (isViewport) {
+      const element = internalRef.current;
+      if (!element) return;
+      observedElement = element;
+      observeForPrefetch(element, () => {
+        scheduleWhenIdle(triggerPrefetch);
+      });
     }
-  }, [prefetch, to, isExternal, ctx]);
+
+    return () => {
+      cancelled = true;
+      unsubIdle?.();
+      if (isViewport && observedElement) {
+        unobserveForPrefetch(observedElement);
+      }
+    };
+  }, [resolvedStrategy, to, isExternal, ctx]);
 
   return (
     <a
-      ref={ref}
+      ref={setRef}
       href={to}
       onClick={handleClick}
       onMouseEnter={handleMouseEnter}

package/src/browser/react/NavigationProvider.tsx

@@ -22,7 +22,9 @@ 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";
 
 /**
  * Process handles from an async generator, updating the event controller
@@ -126,6 +128,12 @@ export interface NavigationProviderProps {
    * When true, keeps TLS alive by sending HEAD requests after idle periods.
    */
   warmupEnabled?: boolean;
+
+  /**
+   * App version from server payload (stable, immutable).
+   * Forwarded to prefetch requests for version mismatch detection.
+   */
+  version?: string;
 }
 
 /**
@@ -157,6 +165,7 @@ export function NavigationProvider({
   themeConfig,
   initialTheme,
   warmupEnabled,
+  version,
 }: NavigationProviderProps): ReactNode {
   // Track current payload for rendering (this triggers re-renders)
   const [payload, setPayload] = useState(initialPayload);
@@ -185,6 +194,7 @@ export function NavigationProvider({
       eventController,
       navigate,
       refresh,
+      version,
     }),
     [],
   );
@@ -276,6 +286,21 @@ export function NavigationProvider({
     };
   }, [warmupEnabled]);
 
+  // Cancel speculative prefetches when navigation starts.
+  // Viewport/render prefetches should not compete with navigation fetches.
+  useEffect(() => {
+    let wasIdle = true;
+    const unsub = eventController.subscribe(() => {
+      const state = eventController.getState();
+      const isIdle = state.state === "idle" && !state.isStreaming;
+      if (wasIdle && !isIdle) {
+        cancelAllPrefetches();
+      }
+      wasIdle = isIdle;
+    });
+    return unsub;
+  }, [eventController]);
+
   // Subscribe to UI updates (for re-rendering the tree)
   useEffect(() => {
     const unsubscribe = store.onUpdate((update) => {
@@ -346,6 +371,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

@@ -41,6 +41,12 @@ export interface NavigationStoreContextValue {
    * @returns Promise that resolves when refresh is complete
    */
   refresh: () => Promise<void>;
+
+  /**
+   * App version from server payload (stable, immutable).
+   * Used in prefetch requests for version mismatch detection.
+   */
+  version: string | undefined;
 }
 
 /**

package/src/browser/react/filter-segment-order.ts

@@ -0,0 +1,11 @@
+/**
+ * Filter segment IDs to only include routes and layouts.
+ * Excludes parallels (contain .@) and loaders (contain D followed by digit).
+ */
+export function filterSegmentOrder(matched: string[]): string[] {
+  return matched.filter((id) => {
+    if (id.includes(".@")) return false;
+    if (/D\d+\./.test(id)) return false;
+    return true;
+  });
+}

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

@@ -4,11 +4,14 @@
  */
 
 /**
- * Internal entry representing a state value with its unique key
+ * Internal entry representing a state value with its unique key.
+ * When __rsc_ls_lazy is true, __rsc_ls_value holds a getter function
+ * that is called at navigation time (not at entry creation time).
  */
 export interface LocationStateEntry {
   readonly __rsc_ls_key: string;
   readonly __rsc_ls_value: unknown;
+  readonly __rsc_ls_lazy?: boolean;
 }
 
 /**
@@ -55,6 +58,13 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
  * // Use in Link
  * <Link to="/product/123" state={[ProductState({ name: "Widget", price: 9.99 })]}>
  *
+ * // Just-in-time typed state (getter called at click time, not render time).
+ * // Must be in a client component — the getter function can't cross the RSC boundary.
+ * <Link
+ *   to="/product/123"
+ *   state={[ProductState(() => ({ name: product.name, price: product.price }))]}
+ * >
+ *
  * // Read with hook (reactive)
  * const product = useLocationState(ProductState);
  *
@@ -69,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 " +
@@ -79,14 +89,20 @@ export function createLocationState<TState>(
     return _key!;
   }
 
-  const fn = (stateOrGetter: TState | (() => TState)): LocationStateEntry => ({
-    __rsc_ls_key: getKey(),
-    // Resolve getter immediately - lazy evaluation happens via Link's stateRef pattern
-    __rsc_ls_value:
-      typeof stateOrGetter === "function"
-        ? (stateOrGetter as () => TState)()
-        : stateOrGetter,
-  });
+  const fn = (stateOrGetter: TState | (() => TState)): LocationStateEntry => {
+    if (typeof stateOrGetter === "function") {
+      // Store getter as-is; resolved at navigation time by resolveLocationStateEntries()
+      return {
+        __rsc_ls_key: getKey(),
+        __rsc_ls_value: stateOrGetter,
+        __rsc_ls_lazy: true,
+      };
+    }
+    return {
+      __rsc_ls_key: getKey(),
+      __rsc_ls_value: stateOrGetter,
+    };
+  };
 
   // Use defineProperty for __rsc_ls_key to avoid Object.assign evaluating
   // the getter during construction (before the Vite plugin sets the key).
@@ -138,7 +154,9 @@ export function resolveLocationStateEntries(
 ): Record<string, unknown> {
   const result: Record<string, unknown> = {};
   for (const entry of entries) {
-    result[entry.__rsc_ls_key] = entry.__rsc_ls_value;
+    result[entry.__rsc_ls_key] = entry.__rsc_ls_lazy
+      ? (entry.__rsc_ls_value as () => unknown)()
+      : entry.__rsc_ls_value;
   }
   return result;
 }

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

@@ -22,7 +22,7 @@ export {
  *
  * Overloaded:
  * - With definition: Returns typed state from the specific key
- * - With type param only: Returns legacy state from history.state.state (backwards compat)
+ * - With type param only: Returns plain state from history.state.state
  *
  * @example
  * ```typescript
@@ -34,8 +34,8 @@ export {
  * const FlashMsg = createLocationState<{ text: string }>({ flash: true });
  * const flash = useLocationState(FlashMsg);
  *
- * // Legacy typed access (backwards compatible)
- * const legacyState = useLocationState<{ from?: string }>();
+ * // Plain state access (reads from history.state.state)
+ * const state = useLocationState<{ from?: string }>();
  * ```
  */
 export function useLocationState<TArgs extends unknown[], TState>(
@@ -53,7 +53,7 @@ export function useLocationState<TArgs extends unknown[], TState>(
     if (key) {
       return window.history.state?.[key] as TState | undefined;
     }
-    // Legacy: return history.state.state for backwards compatibility
+    // Plain state: stored under history.state.state
     return window.history.state?.state as TState | undefined;
   });
 
@@ -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/shallow-equal.ts

@@ -0,0 +1,27 @@
+/**
+ * Shallow equality check for selector results.
+ * Uses Object.is for value comparison (handles NaN and +-0 correctly).
+ */
+export 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;
+}

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";
 
 /**
@@ -126,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.
  */
@@ -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,7 +197,7 @@ export function useAction<T>(
           ? selectorRef.current(state)
           : state;
 
-        if (!isShallowEqual(selectedState, prevSelected.current)) {
+        if (!shallowEqual(selectedState, prevSelected.current)) {
           prevSelected.current = selectedState;
           setBaseState(selectedState);
           startTransition(() => {
@@ -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 };