@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.25dbaac3

package/src/browser/react/Link.tsx

@@ -4,40 +4,60 @@ import React, {
   forwardRef,
   useCallback,
   useContext,
+  useEffect,
+  useMemo,
   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 { getAppVersion } from "../app-version.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
@@ -62,11 +82,46 @@ 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"
    */
   prefetch?: PrefetchStrategy;
+  /**
+   * Opt-in override for the prefetch cache scope.
+   *
+   * The default cache is source-agnostic: one shared entry per target,
+   * keyed on Rango state + target URL. This is correct for routes whose
+   * response shape doesn't depend on where the user navigates from.
+   *
+   * Set `":source"` when this Link's response would legitimately differ
+   * based on the source page — typically when the target route (or one
+   * of its layouts) uses a custom `revalidate()` handler that reads
+   * `currentUrl` / `currentParams`, and the wildcard entry would
+   * therefore serve the wrong diff to a navigation from a different
+   * source.
+   *
+   * Intercept responses are auto-scoped to the source via a server-side
+   * tag, so `":source"` is only needed for custom revalidation logic.
+   *
+   * @example
+   * ```tsx
+   * // Route uses a `revalidate()` that branches on currentUrl — opt in
+   * // so prefetches don't bleed across source pages.
+   * <Link to="/dashboard" prefetch="hover" prefetchKey=":source" />
+   * ```
+   */
+  prefetchKey?: ":source";
   /**
    * State to pass to history.pushState/replaceState.
    * Accessible via useLocationState() hook.
@@ -74,16 +129,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>
    * ```
    */
@@ -139,7 +207,9 @@ export const Link: ForwardRefExoticComponent<
     replace = false,
     scroll = true,
     reloadDocument = false,
+    revalidate,
     prefetch = "none",
+    prefetchKey,
     state,
     children,
     onClick,
@@ -150,6 +220,35 @@ export const Link: ForwardRefExoticComponent<
   const ctx = useContext(NavigationStoreContext);
   const isExternal = isExternalUrl(to);
 
+  // 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 === "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,59 +279,154 @@ 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(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 (prefetch === "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();
-      prefetchUrl(to, segmentState.currentSegmentIds);
+      prefetchDirect(
+        resolvedTo,
+        segmentState.currentSegmentIds,
+        getAppVersion(),
+        ctx.store.getRouterId?.(),
+        prefetchKey,
+      );
     }
-  }, [prefetch, to, isExternal, ctx]);
+  }, [resolvedStrategy, resolvedTo, isExternal, ctx, prefetchKey]);
+
+  // 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();
+      prefetchQueued(
+        resolvedTo,
+        segmentState.currentSegmentIds,
+        getAppVersion(),
+        ctx.store.getRouterId?.(),
+        prefetchKey,
+      );
+    };
+
+    // 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);
+      });
+    }
+
+    return () => {
+      cancelled = true;
+      unsubIdle?.();
+      if (isViewport && observedElement) {
+        unobserveForPrefetch(observedElement);
+      }
+    };
+  }, [resolvedStrategy, resolvedTo, isExternal, ctx, prefetchKey]);
 
   return (
     <a
-      ref={ref}
-      href={to}
+      ref={setRef}
+      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,7 +24,11 @@ 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 { handleNavigationEnd } from "../scroll-restoration.js";
+import type { AppShellRef } from "../app-shell.js";
 
 /**
  * Process handles from an async generator, updating the event controller
@@ -41,10 +47,22 @@ async function processHandles(
     store: NavigationStore;
     matched?: string[];
     isPartial?: boolean;
+    /** Server's `resolvedIds`: every segment re-resolved this request,
+     *  including null-component ones excluded from `diff`/`segments`.
+     *  Drives cleanup of stale handle buckets when a re-resolved segment
+     *  pushed nothing. */
+    resolvedIds?: string[];
     historyKey: string;
   },
 ): Promise<void> {
-  const { eventController, store, matched, isPartial, historyKey } = opts;
+  const {
+    eventController,
+    store,
+    matched,
+    isPartial,
+    resolvedIds,
+    historyKey,
+  } = opts;
 
   let yieldCount = 0;
   for await (const handleData of handlesGenerator) {
@@ -59,7 +77,7 @@ async function processHandles(
     }
 
     yieldCount++;
-    eventController.setHandleData(handleData, matched, isPartial);
+    eventController.setHandleData(handleData, matched, isPartial, resolvedIds);
   }
 
   // Check again before final updates
@@ -67,12 +85,11 @@ async function processHandles(
     return;
   }
 
-  // For partial updates where the generator yielded nothing (cached handlers),
-  // we still need to update the segment order to clean up stale handle data.
-  // This happens when navigating away from a route - the handlers for the new
-  // route might not push any breadcrumbs, but we still need to remove the old ones.
+  // For partial updates where the generator yielded nothing (every
+  // re-resolved handler pushed nothing), still call setHandleData so the
+  // cleanup pass can clear out stale buckets for those segments.
   if (yieldCount === 0 && matched) {
-    eventController.setHandleData({}, matched, true);
+    eventController.setHandleData({}, matched, true, resolvedIds);
   }
 
   // After handles processing completes, update the cache's handleData.
@@ -126,6 +143,25 @@ export interface NavigationProviderProps {
    * When true, keeps TLS alive by sending HEAD requests after idle periods.
    */
   warmupEnabled?: boolean;
+
+  /**
+   * App version from server payload.
+   * Used only as a fallback when `appShellRef` is not supplied.
+   */
+  version?: string;
+
+  /**
+   * URL prefix for all routes (from createRouter({ basename })).
+   * Used only as a fallback when `appShellRef` is not supplied.
+   */
+  basename?: string;
+
+  /**
+   * Live app-shell ref. When provided, the context's `basename` and `version`
+   * properties become live getters that track app-switch updates without
+   * invalidating the memoized context value.
+   */
+  appShellRef?: AppShellRef;
 }
 
 /**
@@ -157,6 +193,9 @@ export function NavigationProvider({
   themeConfig,
   initialTheme,
   warmupEnabled,
+  version,
+  basename,
+  appShellRef,
 }: NavigationProviderProps): ReactNode {
   // Track current payload for rendering (this triggers re-renders)
   const [payload, setPayload] = useState(initialPayload);
@@ -178,16 +217,39 @@ export function NavigationProvider({
     await bridge.refresh();
   }, []);
 
-  // Context value is stable (store, eventController, navigate, refresh never change)
-  const contextValue = useMemo<NavigationStoreContextValue>(
-    () => ({
+  // Context value is stable (store, eventController, navigate, refresh never
+  // change). When an appShellRef is supplied, `basename` and `version` are
+  // installed as live getters so app-switch transitions (which update the ref)
+  // propagate to consumers without forcing a tree-wide rerender.
+  const contextValue = useMemo<NavigationStoreContextValue>(() => {
+    if (appShellRef) {
+      const value = {
+        store,
+        eventController,
+        navigate,
+        refresh,
+      } as NavigationStoreContextValue;
+      Object.defineProperty(value, "basename", {
+        configurable: true,
+        enumerable: true,
+        get: () => appShellRef.get().basename,
+      });
+      Object.defineProperty(value, "version", {
+        configurable: true,
+        enumerable: true,
+        get: () => appShellRef.get().version,
+      });
+      return value;
+    }
+    return {
       store,
       eventController,
       navigate,
       refresh,
-    }),
-    [],
-  );
+      version,
+      basename,
+    };
+  }, []);
 
   // Connection warmup: keep TLS alive after idle periods.
   // After 60s of no user interaction, marks connection as "cold".
@@ -276,16 +338,61 @@ export function NavigationProvider({
     };
   }, [warmupEnabled]);
 
+  // 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(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,
       });
 
-      // Update route params
-      eventController.setParams(update.metadata.params ?? {});
+      // Update route params. Only reset when the server actually sends a params
+      // map — an absent `params` field means "no change" (e.g., legacy action
+      // responses that omitted params). Explicit `{}` still clears correctly.
+      if (update.metadata.params !== undefined) {
+        eventController.setParams(update.metadata.params);
+      }
 
       // Update handle data progressively as it streams in
       if (update.metadata.handles) {
@@ -298,6 +405,7 @@ export function NavigationProvider({
           store,
           matched: update.metadata.matched,
           isPartial: update.metadata.isPartial,
+          resolvedIds: update.metadata.resolvedIds,
           historyKey,
         }).catch((err) =>
           console.error("[NavigationProvider] Error consuming handles:", err),
@@ -316,6 +424,7 @@ export function NavigationProvider({
           {}, // Empty data - all existing data not in matched will be cleaned up
           update.metadata.matched,
           true, // partial update - will clean up segments not in matched
+          update.metadata.resolvedIds,
         );
       }
     });
@@ -337,7 +446,11 @@ export function NavigationProvider({
   // Build the content tree
   let content = <RootErrorBoundary>{root}</RootErrorBoundary>;
 
-  // Wrap with ThemeProvider when theme is enabled
+  // Wrap with ThemeProvider when theme is enabled. The ThemeProvider is
+  // document-lifetime: its config comes from the initial load and does NOT
+  // swap on cross-app transitions, because the ThemeProvider sits above the
+  // segment tree and a smooth (no-reload) app switch cannot safely remount
+  // it. A new theme config only takes effect on a full document load.
   if (themeConfig) {
     content = (
       <ThemeProvider config={themeConfig} initialTheme={initialTheme}>
@@ -346,6 +459,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,17 @@ export interface NavigationStoreContextValue {
    * @returns Promise that resolves when refresh is complete
    */
   refresh: () => Promise<void>;
+
+  /**
+   * 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;
 }
 
 /**