@rangojs/router 0.0.0-experimental.f3c21dba → 0.0.0-experimental.f4a8e8de

package/src/browser/rango-state.ts

@@ -1,112 +1,215 @@
 /**
  * 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).
+ * Manages a session-cookie-based state value for HTTP cache invalidation. The
+ * value is sent as the `X-Rango-State` header on 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.
+ * Value format: `{buildVersion}:{invalidationTimestamp}`
+ * - Build version changes on deploy, busting all cached prefetches at boot.
+ * - Timestamp rotates on invalidation (server action, invalidateClientCache).
  *
- * 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.
+ * Storage is a session cookie named by the server-resolved name passed to
+ * initRangoState (`{prefix}_{routerId}`, default prefix `rango-state`). The
+ * cookie jar is shared across tabs, so a per-request read IS the cross-tab
+ * value sync — no `storage` event is needed. An in-memory mirror is a
+ * write-through copy that is authoritative only when the cookie is unreadable
+ * (e.g. a sandboxed frame, or site data blocked wholesale): the failure
+ * direction is always toward freshness.
+ *
+ * Precedence is load-bearing: when `document.cookie` is readable, the
+ * per-request read wins; the mirror is a fallback, never a cache of the read.
+ * Caching the read across requests would reintroduce the staleness this
+ * mechanism removes.
  */
 
-const STORAGE_KEY = "rango-state";
+import {
+  DEFAULT_STATE_COOKIE_PREFIX,
+  decodeStateValue,
+  getRawCookieValue,
+  mintStateValue,
+  serializeStateCookie,
+} from "./cookie-name.js";
 
-// Module-level cache avoids hitting localStorage on every getRangoState() call.
-// Initialized from localStorage on first access or by initRangoState().
-let cachedState: string | null = null;
+let cookieName: string = DEFAULT_STATE_COOKIE_PREFIX;
 
-// Cross-tab sync: the `storage` event fires in OTHER tabs when one tab writes
-// to localStorage, keeping cachedState fresh without polling.
-let storageListenerAttached = false;
+let currentVersion = "0";
 
-function attachStorageListener(): void {
-  if (storageListenerAttached || typeof window === "undefined") return;
-  window.addEventListener("storage", (e) => {
-    if (e.key !== STORAGE_KEY) return;
-    cachedState = e.newValue;
-  });
-  storageListenerAttached = true;
-}
+let mirror: string | null = null;
+let cookieBacked = false;
+
+let externalRotationObserver: ((value: string) => void) | null = null;
 
 /**
- * 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.
+ * Register the observer invoked when a read detects an EXTERNAL rotation (a
+ * sibling tab, a server `Set-Cookie`, or a cookie clear). Self-rotations
+ * (invalidateRangoState) update the mirror synchronously and never fire it.
  */
-export function initRangoState(version: string): void {
-  if (typeof window === "undefined") return;
+export function setRangoStateObserver(
+  observer: ((value: string) => void) | null,
+): void {
+  externalRotationObserver = observer;
+}
 
-  attachStorageListener();
+/** Return the resolved cookie name used to namespace cross-tab messages. */
+export function getRangoStateCookieName(): string {
+  return cookieName;
+}
+
+function notifyExternalRotation(value: string): void {
+  externalRotationObserver?.(value);
+}
+
+interface CookieRead {
+  /** False when there is no document or the read threw (sandboxed frame). */
+  readable: boolean;
+  /** The cookie value, or null when readable but absent. */
+  value: string | null;
+}
 
+function readCookie(name: string): CookieRead {
+  if (typeof document === "undefined") return { readable: false, value: null };
+  let raw: string;
   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;
+    raw = document.cookie;
   } catch {
-    // localStorage may be unavailable (private browsing in some browsers)
-    cachedState = `${version}:${Date.now()}`;
+    return { readable: false, value: null };
   }
+  return { readable: true, value: getRawCookieValue(raw, name) };
+}
+
+function writeCookie(name: string, value: string): void {
+  if (typeof document === "undefined") return;
+  const secure =
+    typeof location !== "undefined" && location.protocol === "https:";
+  try {
+    document.cookie = serializeStateCookie(name, value, secure);
+  } catch {}
+}
+
+function mintValue(): string {
+  return mintStateValue(currentVersion, mirror);
 }
 
 /**
- * Get the current Rango state key value.
- * Used as the `X-Rango-State` header value for prefetch and navigation requests.
+ * Initialize the Rango state cookie at app startup. `version` is the build
+ * version; `stateCookieName` is the server-resolved cookie name from payload
+ * metadata (falls back to the bare default prefix when a payload arrives
+ * without it). Keeps an existing matching-version cookie (preserves the cache
+ * key across reloads); mints fresh on a version change or a missing cookie.
+ */
+export function initRangoState(
+  version: string,
+  stateCookieName?: string,
+): void {
+  currentVersion = version;
+  cookieName = stateCookieName || DEFAULT_STATE_COOKIE_PREFIX;
+  cleanupLegacyStorage();
+
+  const read = readCookie(cookieName);
+  if (!read.readable) {
+    // Cookies unreadable: the mirror is the source of truth for this session.
+    mirror = mintValue();
+    cookieBacked = false;
+    return;
+  }
+  if (read.value !== null) {
+    const decoded = decodeStateValue(read.value);
+    if (decoded && decoded.version === version) {
+      // Keep: a matching-version cookie survives the reload warm.
+      mirror = read.value;
+      cookieBacked = true;
+      return;
+    }
+  }
+  // Absent, malformed, or a version change (deploy): mint fresh and write.
+  mirror = mintValue();
+  cookieBacked = false;
+  writeCookie(cookieName, mirror);
+}
+
+/**
+ * Get the current Rango state value, used as the `X-Rango-State` header on
+ * prefetch and navigation requests. Reads the cookie every call (the read is
+ * the cross-tab sync channel) and reconciles the mirror.
  */
 export function getRangoState(): string {
-  if (cachedState) return cachedState;
+  const read = readCookie(cookieName);
 
-  if (typeof window === "undefined") return "0:0";
+  if (!read.readable) {
+    // Mirror authoritative when the jar is unreadable.
+    return mirror ?? "0:0";
+  }
 
-  try {
-    const stored = localStorage.getItem(STORAGE_KEY);
-    if (stored) {
-      cachedState = stored;
-      return stored;
+  if (read.value !== null) {
+    if (read.value !== mirror) {
+      // External rotation (sibling tab / server Set-Cookie): adopt it. The
+      // mirror update makes this idempotent across a burst of reads.
+      mirror = read.value;
+      cookieBacked = true;
+      notifyExternalRotation(read.value);
+    } else {
+      cookieBacked = true;
     }
-  } catch {
-    // Fallback for unavailable localStorage
+    return read.value;
   }
 
-  return "0:0";
+  // Readable but absent.
+  if (cookieBacked) {
+    // present -> absent: an external clear. Mint fresh, write back, and notify
+    // once (cookieBacked flips to false so we don't re-fire on the next read).
+    mirror = mintValue();
+    cookieBacked = false;
+    writeCookie(cookieName, mirror);
+    notifyExternalRotation(mirror);
+  } else if (mirror === null) {
+    // First access with no cookie yet (pre-boot): mint silently — there is
+    // nothing to invalidate.
+    mirror = mintValue();
+    writeCookie(cookieName, mirror);
+  }
+  return mirror;
 }
 
 /**
- * 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.
+ * Invalidate the Rango state (self-rotation). Called when the client clears its
+ * prefetch caches (e.g. via the server-action bridge). Rotates the timestamp,
+ * keeps the version, writes the cookie, and updates the mirror synchronously so
+ * the external-rotation observer is NOT triggered by our own write.
  */
 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;
+  mirror = mintValue();
+  cookieBacked = false;
+  writeCookie(cookieName, mirror);
+}
 
-  if (typeof window === "undefined") return;
+/** Adopt the state carried by a same-origin cache-invalidation broadcast. */
+export function adoptRangoState(value: string): boolean {
+  const incoming = decodeStateValue(value);
+  if (!incoming || incoming.version !== currentVersion) return false;
+  const current = mirror ? decodeStateValue(mirror) : null;
+  if (
+    current?.version === incoming.version &&
+    current.timestamp >= incoming.timestamp
+  ) {
+    return false;
+  }
+  mirror = value;
+  cookieBacked = false;
+  return true;
+}
 
+function cleanupLegacyStorage(): void {
+  if (typeof localStorage === "undefined") return;
   try {
-    localStorage.setItem(STORAGE_KEY, newState);
-  } catch {
-    // Silently handle localStorage errors
-  }
+    const toRemove: string[] = [];
+    for (let i = 0; i < localStorage.length; i++) {
+      const key = localStorage.key(i);
+      if (key === "rango-state" || (key && key.startsWith("rango-state:"))) {
+        toRemove.push(key);
+      }
+    }
+    for (const key of toRemove) localStorage.removeItem(key);
+  } catch {}
 }

package/src/browser/react/Link.tsx

@@ -5,14 +5,21 @@ import React, {
   useCallback,
   useContext,
   useEffect,
+  useMemo,
   useRef,
+  useSyncExternalStore,
   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 {
+  isHashOnlyNavigation,
+  isPrefetchScopeDisabled,
+  subscribeToPrefetchScopeChange,
+} from "../link-interceptor.js";
+import { subscribeToLocationChange } from "../event-controller.js";
 import {
   isLocationStateEntry,
   type LocationStateEntry,
@@ -31,31 +38,27 @@ export type LinkState =
   | LocationStateEntry[]
   | StateOrGetter<Record<string, unknown>>;
 
-import { prefetchDirect, prefetchQueued } from "../prefetch/fetch.js";
 import {
-  observeForPrefetch,
-  unobserveForPrefetch,
-} from "../prefetch/observer.js";
+  prefetchDirect,
+  prefetchQueued,
+  schedulePrefetchWhenRouterIdle,
+} from "../prefetch/loader.js";
+import { observeForPrefetch } from "../prefetch/observer.js";
+import {
+  getDefaultPrefetchStrategy,
+  resolveAdaptiveStrategy,
+  subscribeToAdaptiveStrategyChange,
+} from "../prefetch/default-strategy.js";
+import { getAppVersion } from "../app-version.js";
+import type { PrefetchStrategy } from "../../router/prefetch-default.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;
+// The PrefetchStrategy union is defined in router/prefetch-default.ts (both
+// the server-side option resolver and this client seat consume it); re-export
+// so the public `PrefetchStrategy` import path via client.tsx is unchanged.
+export type { PrefetchStrategy } from "../../router/prefetch-default.js";
+export { resolveAdaptiveStrategy } from "../prefetch/default-strategy.js";
 
-/**
- * Prefetch strategy for the Link component
- * - "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"
-  | "render"
-  | "adaptive"
-  | "none";
+const IGNORE_STRATEGY_CHANGES = (_listener: () => void) => () => {};
 
 /**
  * Link component props
@@ -91,10 +94,41 @@ export interface LinkProps extends Omit<
    */
   revalidate?: boolean;
   /**
-   * Prefetch strategy for the link destination
-   * @default "none"
+   * Prefetch strategy for the link destination. When omitted, falls back to
+   * the router-wide default (`createRouter({ defaultPrefetch })`: `"none"` in
+   * development, `"viewport"` in production). An explicit value always wins
+   * over the router default, including `"none"` to opt a single Link out. An
+   * ancestor with `data-prefetch-scope="false"` or `"none"` remains a hard
+   * subtree opt-out.
+   *
+   * @default the router's environment-aware `defaultPrefetch`
    */
   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.
@@ -181,7 +215,8 @@ export const Link: ForwardRefExoticComponent<
     scroll = true,
     reloadDocument = false,
     revalidate,
-    prefetch = "none",
+    prefetch,
+    prefetchKey,
     state,
     children,
     onClick,
@@ -192,9 +227,29 @@ 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;
+  // 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]);
+
+  // No explicit `prefetch` prop: fall back to the router-wide default
+  // (server-resolved, applied at browser init — before hydration, so this
+  // render-time read never races the metadata). Adaptive reads the current
+  // input capability rather than a module-load snapshot.
+  const configuredStrategy =
+    prefetch ?? ctx?.defaultPrefetch ?? getDefaultPrefetchStrategy();
+  const resolvedStrategy = useSyncExternalStore(
+    configuredStrategy === "adaptive"
+      ? subscribeToAdaptiveStrategyChange
+      : IGNORE_STRATEGY_CHANGES,
+    () => resolveAdaptiveStrategy(configuredStrategy),
+    () => (configuredStrategy === "adaptive" ? "hover" : configuredStrategy),
+  );
 
   // Internal ref for viewport observation; merge with forwarded ref
   const internalRef = useRef<HTMLAnchorElement | null>(null);
@@ -273,25 +328,48 @@ export const Link: ForwardRefExoticComponent<
         resolvedState = currentState;
       }
 
-      ctx.navigate(to, { replace, scroll, state: resolvedState, revalidate });
+      ctx.navigate(resolvedTo, {
+        replace,
+        scroll,
+        state: resolvedState,
+        revalidate,
+      });
     },
-    [to, isExternal, reloadDocument, replace, scroll, revalidate, ctx, onClick],
+    [
+      resolvedTo,
+      isExternal,
+      reloadDocument,
+      replace,
+      scroll,
+      revalidate,
+      ctx,
+      onClick,
+    ],
   );
 
   const handleMouseEnter = useCallback(() => {
+    const element = internalRef.current;
     if (
       (resolvedStrategy === "hover" || resolvedStrategy === "viewport") &&
       !isExternal &&
-      ctx?.store
+      ctx?.store &&
+      (!element ||
+        (!isHashOnlyNavigation(element) && !isPrefetchScopeDisabled(element)))
     ) {
       // 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?.(),
+        prefetchKey,
+      );
     }
-  }, [resolvedStrategy, to, isExternal, ctx]);
+  }, [resolvedStrategy, resolvedTo, isExternal, ctx, prefetchKey]);
 
   // Viewport/render prefetch: waits for idle before starting,
   // uses concurrency-limited queue to avoid flooding.
@@ -301,58 +379,84 @@ export const Link: ForwardRefExoticComponent<
     const isRender = resolvedStrategy === "render";
     if (!isViewport && !isRender) return;
 
-    let cancelled = false;
-    let unsubIdle: (() => void) | undefined;
-    let observedElement: Element | null = null;
+    const armPrefetch = (): (() => void) => {
+      const element = internalRef.current;
+      if (
+        element &&
+        (isHashOnlyNavigation(element) || isPrefetchScopeDisabled(element))
+      ) {
+        return () => {};
+      }
 
-    const triggerPrefetch = () => {
-      if (cancelled) return;
-      const segmentState = ctx.store.getSegmentState();
-      prefetchQueued(to, segmentState.currentSegmentIds, ctx.version);
-    };
+      let cancelled = false;
+      let unsubIdle: (() => void) | undefined;
+      let stopObserving: (() => void) | undefined;
+
+      const triggerPrefetch = () => {
+        if (cancelled) return;
+        const currentElement = internalRef.current;
+        if (currentElement && isPrefetchScopeDisabled(currentElement)) 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();
+      if (isRender) {
+        unsubIdle = schedulePrefetchWhenRouterIdle(
+          ctx.eventController,
+          triggerPrefetch,
+        );
+      } else {
+        const viewportElement = internalRef.current;
+        if (viewportElement) {
+          stopObserving = observeForPrefetch(viewportElement, () => {
+            unsubIdle = schedulePrefetchWhenRouterIdle(
+              ctx.eventController,
+              triggerPrefetch,
+            );
+          });
         }
-      });
-      unsubIdle = unsub;
+      }
+
+      return () => {
+        cancelled = true;
+        unsubIdle?.();
+        stopObserving?.();
+      };
     };
 
-    if (isRender) {
-      scheduleWhenIdle(triggerPrefetch);
-    } else if (isViewport) {
-      const element = internalRef.current;
-      if (!element) return;
-      observedElement = element;
-      observeForPrefetch(element, () => {
-        scheduleWhenIdle(triggerPrefetch);
-      });
-    }
+    let disarmPrefetch = armPrefetch();
+    const element = internalRef.current;
+    const unsubscribeScope = element
+      ? subscribeToPrefetchScopeChange(element, () => {
+          disarmPrefetch();
+          disarmPrefetch = armPrefetch();
+        })
+      : undefined;
+    const unsubscribeLocation = subscribeToLocationChange(
+      ctx.eventController,
+      () => {
+        disarmPrefetch();
+        disarmPrefetch = armPrefetch();
+      },
+    );
 
     return () => {
-      cancelled = true;
-      unsubIdle?.();
-      if (isViewport && observedElement) {
-        unobserveForPrefetch(observedElement);
-      }
+      unsubscribeScope?.();
+      unsubscribeLocation();
+      disarmPrefetch();
     };
-  }, [resolvedStrategy, to, isExternal, ctx]);
+  }, [resolvedStrategy, resolvedTo, isExternal, ctx, prefetchKey]);
 
   return (
     <a
       ref={setRef}
-      href={to}
+      href={resolvedTo}
       onClick={handleClick}
       onMouseEnter={handleMouseEnter}
       data-link-component
@@ -362,7 +466,7 @@ export const Link: ForwardRefExoticComponent<
       data-revalidate={revalidate === false ? "false" : undefined}
       {...props}
     >
-      <LinkContext.Provider value={to}>{children}</LinkContext.Provider>
+      <LinkContext.Provider value={resolvedTo}>{children}</LinkContext.Provider>
     </a>
   );
 });