@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.81

package/src/browser/prefetch/resource-ready.ts

@@ -0,0 +1,77 @@
+/**
+ * Resource Readiness
+ *
+ * Utilities to defer speculative prefetches until critical resources
+ * (viewport images) have finished loading. Prevents prefetch fetch()
+ * calls from competing with images for the browser's connection pool.
+ */
+
+/**
+ * Resolve when all in-viewport images have finished loading.
+ * Returns immediately if no images are pending.
+ *
+ * Only checks images that exist at call time — does not observe
+ * dynamically added images. For SPA navigations where new images
+ * appear after render, call this after the navigation settles.
+ */
+export function waitForViewportImages(): Promise<void> {
+  if (typeof document === "undefined") return Promise.resolve();
+
+  const pending = Array.from(document.querySelectorAll("img")).filter((img) => {
+    if (img.complete) return false;
+    const rect = img.getBoundingClientRect();
+    return (
+      rect.bottom > 0 &&
+      rect.right > 0 &&
+      rect.top < window.innerHeight &&
+      rect.left < window.innerWidth
+    );
+  });
+
+  if (pending.length === 0) return Promise.resolve();
+
+  return new Promise((resolve) => {
+    const settled = new Set<HTMLImageElement>();
+
+    const settle = (img: HTMLImageElement) => {
+      if (settled.has(img)) return;
+      settled.add(img);
+      if (settled.size >= pending.length) resolve();
+    };
+
+    for (const img of pending) {
+      img.addEventListener("load", () => settle(img), { once: true });
+      img.addEventListener("error", () => settle(img), { once: true });
+      // Re-check: image may have completed between the initial filter
+      // and listener attachment. settle() is idempotent per image, so
+      // a queued load event firing afterward is harmless.
+      if (img.complete) settle(img);
+    }
+  });
+}
+
+/**
+ * Resolve after the given number of milliseconds.
+ */
+export function wait(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Resolve when the browser has an idle main-thread moment.
+ * Uses requestIdleCallback where available, falls back to setTimeout.
+ *
+ * This is a scheduling hint, not an asset-loaded detector — combine
+ * with waitForViewportImages() for full resource readiness.
+ */
+export function waitForIdle(timeout = 200): Promise<void> {
+  if (typeof window !== "undefined" && "requestIdleCallback" in window) {
+    return new Promise((resolve) => {
+      window.requestIdleCallback(() => resolve(), { timeout });
+    });
+  }
+
+  return new Promise((resolve) => {
+    setTimeout(resolve, 0);
+  });
+}

package/src/browser/rango-state.ts

@@ -0,0 +1,112 @@
+/**
+ * Rango State
+ *
+ * Manages a localStorage-based state key for HTTP cache invalidation.
+ * The key is sent as the `X-Rango-State` header on both prefetch and
+ * navigation requests. The server responds with `Vary: X-Rango-State`,
+ * so the browser HTTP cache keys responses by (URL, X-Rango-State value).
+ *
+ * Format: `{buildVersion}:{invalidationTimestamp}`
+ * - Build version changes on deploy, busting all cached prefetches.
+ * - Timestamp changes on server action invalidation.
+ *
+ * localStorage is cross-tab and survives page refresh, so:
+ * - One tab's prefetch warms the cache for all tabs.
+ * - Invalidation in one tab is picked up by other tabs on next fetch.
+ */
+
+const STORAGE_KEY = "rango-state";
+
+// Module-level cache avoids hitting localStorage on every getRangoState() call.
+// Initialized from localStorage on first access or by initRangoState().
+let cachedState: string | null = null;
+
+// Cross-tab sync: the `storage` event fires in OTHER tabs when one tab writes
+// to localStorage, keeping cachedState fresh without polling.
+let storageListenerAttached = false;
+
+function attachStorageListener(): void {
+  if (storageListenerAttached || typeof window === "undefined") return;
+  window.addEventListener("storage", (e) => {
+    if (e.key !== STORAGE_KEY) return;
+    cachedState = e.newValue;
+  });
+  storageListenerAttached = true;
+}
+
+/**
+ * Initialize the Rango state key in localStorage.
+ * Called once at app startup with the build version from the server.
+ * If localStorage already has a key with matching version prefix, keeps it
+ * (preserves invalidation state across refresh). Otherwise writes a new key.
+ */
+export function initRangoState(version: string): void {
+  if (typeof window === "undefined") return;
+
+  attachStorageListener();
+
+  try {
+    const existing = localStorage.getItem(STORAGE_KEY);
+    if (existing) {
+      const colonIdx = existing.indexOf(":");
+      if (colonIdx > 0) {
+        const existingVersion = existing.slice(0, colonIdx);
+        if (existingVersion === version) {
+          cachedState = existing;
+          return;
+        }
+      }
+    }
+    // New version or first load
+    const newState = `${version}:${Date.now()}`;
+    localStorage.setItem(STORAGE_KEY, newState);
+    cachedState = newState;
+  } catch {
+    // localStorage may be unavailable (private browsing in some browsers)
+    cachedState = `${version}:${Date.now()}`;
+  }
+}
+
+/**
+ * Get the current Rango state key value.
+ * Used as the `X-Rango-State` header value for prefetch and navigation requests.
+ */
+export function getRangoState(): string {
+  if (cachedState) return cachedState;
+
+  if (typeof window === "undefined") return "0:0";
+
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored) {
+      cachedState = stored;
+      return stored;
+    }
+  } catch {
+    // Fallback for unavailable localStorage
+  }
+
+  return "0:0";
+}
+
+/**
+ * Invalidate the Rango state key. Called when server actions mutate data.
+ * Updates the timestamp portion while keeping the version prefix.
+ * The new value takes effect immediately for all subsequent fetches,
+ * causing Vary mismatches with previously cached responses.
+ */
+export function invalidateRangoState(): void {
+  const current = getRangoState();
+  const colonIdx = current.indexOf(":");
+  const version = colonIdx > 0 ? current.slice(0, colonIdx) : "0";
+  const newState = `${version}:${Date.now()}`;
+  cachedState = newState;
+
+  if (typeof window === "undefined") return;
+
+  try {
+    localStorage.setItem(STORAGE_KEY, newState);
+  } catch {
+    // Silently handle localStorage errors
+  }
+}

package/src/browser/react/Link.tsx

@@ -1,69 +1,73 @@
 "use client";
 
-import React, { forwardRef, useCallback, useContext, useRef, type ForwardRefExoticComponent, type RefAttributes } from "react";
+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 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>>;
 
-// Track prefetched URLs to avoid duplicate <link> elements
-const prefetchedUrls = new Set<string>();
-
-/**
- * Inject a <link rel="prefetch"> element into the document head
- * for the given URL with RSC partial request parameters.
- */
-function prefetchUrl(url: string, segmentIds: string[]): void {
-  if (prefetchedUrls.has(url)) return;
-  prefetchedUrls.add(url);
-
-  // Build RSC partial URL with segment IDs
-  const targetUrl = new URL(url, window.location.origin);
-  targetUrl.searchParams.set("_rsc_partial", "true");
-  if (segmentIds.length > 0) {
-    targetUrl.searchParams.set("_rsc_segments", segmentIds.join(","));
-  }
+import { prefetchDirect, prefetchQueued } from "../prefetch/fetch.js";
+import { getAppVersion } from "../app-version.js";
+import {
+  observeForPrefetch,
+  unobserveForPrefetch,
+} from "../prefetch/observer.js";
 
-  // Inject <link rel="prefetch"> into head
-  const link = document.createElement("link");
-  link.rel = "prefetch";
-  link.href = targetUrl.toString();
-  link.as = "fetch";
-  document.head.appendChild(link);
-}
+// 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
  */
-export interface LinkProps
-  extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+export interface LinkProps extends Omit<
+  React.AnchorHTMLAttributes<HTMLAnchorElement>,
+  "href"
+> {
   /**
-   * The URL to navigate to (typically from router.href())
+   * The URL to navigate to (typically from router.reverse())
    */
   to: string;
   /**
@@ -78,11 +82,41 @@ export interface LinkProps
    * 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;
+  /**
+   * Custom prefetch cache key for source-agnostic cache reuse.
+   * When set, prefetch responses are cached independently of the current
+   * page URL, so navigating to the same target from different source pages
+   * reuses the cached prefetch.
+   *
+   * - String: static group name (e.g., `"pages"`)
+   * - Function: receives current URL (`window.location.href`), returns a
+   *   normalized source key
+   *
+   * @example
+   * ```tsx
+   * // Static group — all "pages" links share one cache entry per target
+   * <Link to="/page/3" prefetch="hover" prefetchKey="pages" />
+   *
+   * // Normalize — strip trailing page number from source URL
+   * <Link to="/page/3" prefetch="hover" prefetchKey={(from) => from.replace(/\/\d+$/, '')} />
+   * ```
+   */
+  prefetchKey?: string | ((from: string) => string);
   /**
    * State to pass to history.pushState/replaceState.
    * Accessible via useLocationState() hook.
@@ -90,16 +124,29 @@ export interface LinkProps
    * @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>
    * ```
    */
@@ -134,9 +181,9 @@ function isExternalUrl(href: string): boolean {
 /**
  * Type-safe Link component for SPA navigation
  *
- * Works with router.href() for type-safe URLs:
+ * Works with router.reverse() for type-safe URLs:
  * ```tsx
- * <Link to={router.href("shop.products.detail", { slug: "my-product" })}>
+ * <Link to={router.reverse("shop.products.detail", { slug: "my-product" })}>
  *   View Product
  * </Link>
  * ```
@@ -147,23 +194,56 @@ function isExternalUrl(href: string): boolean {
  * <Link to="https://example.com">External</Link>
  * ```
  */
-export const Link: ForwardRefExoticComponent<LinkProps & RefAttributes<HTMLAnchorElement>> = forwardRef<HTMLAnchorElement, LinkProps>(function Link(
+export const Link: ForwardRefExoticComponent<
+  LinkProps & RefAttributes<HTMLAnchorElement>
+> = forwardRef<HTMLAnchorElement, LinkProps>(function Link(
   {
     to,
     replace = false,
     scroll = true,
     reloadDocument = false,
+    revalidate,
     prefetch = "none",
+    prefetchKey,
     state,
     children,
     onClick,
     ...props
   },
-  ref
+  ref,
 ) {
   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);
@@ -194,55 +274,154 @@ export const Link: ForwardRefExoticComponent<LinkProps & RefAttributes<HTMLAncho
       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>
   );
 });