@rangojs/router 0.2.0 → 0.4.1

package/src/browser/notify-listeners.ts

@@ -0,0 +1,22 @@
+/** Notify every active listener and surface every callback failure. */
+export function notifyListeners<T>(
+  entries: Iterable<T>,
+  notify: (entry: T) => void,
+  isActive?: (entry: T) => boolean,
+  shouldContinue?: () => boolean,
+): void {
+  const errors: unknown[] = [];
+  for (const entry of entries) {
+    if (shouldContinue && !shouldContinue()) break;
+    if (isActive && !isActive(entry)) continue;
+    try {
+      notify(entry);
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+  if (errors.length === 1) throw errors[0];
+  if (errors.length > 1) {
+    throw new AggregateError(errors, "Multiple listener callbacks failed");
+  }
+}

package/src/browser/prefetch/cache.ts

@@ -40,6 +40,7 @@
  */
 
 import { abortAllPrefetches } from "./loader.js";
+import { notifyPrefetchCacheInvalidated } from "./invalidation.js";
 import { invalidateRangoState } from "../rango-state.js";
 import type { RscPayload } from "../types.js";
 
@@ -368,7 +369,7 @@ export function clearPrefetchInflight(key: string): void {
   });
 }
 
-export function clearPrefetchCache(): void {
+export function clearPrefetchCache(rotateRangoState = true): void {
   generation++;
   inflight.clear();
   inflightPromises.clear();
@@ -377,5 +378,6 @@ export function clearPrefetchCache(): void {
   cache.clear();
   earliestTimestamp = Infinity;
   abortAllPrefetches();
-  invalidateRangoState();
+  if (rotateRangoState) invalidateRangoState();
+  notifyPrefetchCacheInvalidated();
 }

package/src/browser/prefetch/default-strategy.ts

@@ -0,0 +1,74 @@
+/**
+ * Router-wide default prefetch strategy (client seat).
+ *
+ * The server resolves `createRouter({ defaultPrefetch })` once at router init
+ * (router/prefetch-default.ts) and ships it in initial payload metadata; the
+ * browser entry applies it here before hydration — same lifecycle as
+ * `initPrefetchCache` / `setPrefetchConcurrency`. Every `<Link>` without an
+ * explicit `prefetch` prop and every eligible intercepted plain anchor that has
+ * not opted out with `data-prefetch="false"` or `data-prefetch="none"` uses it.
+ * Containers use the same `false`/`none` vocabulary via
+ * `data-prefetch-scope`.
+ *
+ * The module initial value must equal the server resolver's environment default:
+ * `"none"` in development and `"viewport"` in production. During SSR this
+ * module is never initialized from metadata, so keeping both seats aligned also
+ * gives metadata-less payloads the documented behavior.
+ */
+
+import type { PrefetchStrategy } from "../../router/prefetch-default.js";
+
+let hoverNoneQuery: MediaQueryList | null = null;
+
+// Mirrors DEFAULT_PREFETCH_STRATEGY without pulling router-layer code into the
+// client bundle. NODE_ENV is folded by the app build.
+let defaultStrategy: PrefetchStrategy =
+  process.env.NODE_ENV === "production" ? "viewport" : "none";
+
+function getHoverNoneQuery(): MediaQueryList | null {
+  if (typeof window === "undefined") return null;
+  if (!hoverNoneQuery) {
+    hoverNoneQuery = window.matchMedia("(hover: none)");
+  }
+  return hoverNoneQuery;
+}
+
+/** Reset module state between tests that replace browser media globals. */
+export function resetAdaptiveStrategyForTesting(): void {
+  hoverNoneQuery = null;
+}
+
+/**
+ * Apply the server-resolved default strategy. Called once at browser app init
+ * from payload metadata; also used by tests to reset state.
+ */
+export function setDefaultPrefetchStrategy(strategy: PrefetchStrategy): void {
+  defaultStrategy = strategy;
+}
+
+/** Current default strategy for Links and delegated plain anchors. */
+export function getDefaultPrefetchStrategy(): PrefetchStrategy {
+  return defaultStrategy;
+}
+
+/** Resolve adaptive to the strategy for the current input capability. */
+export function resolveAdaptiveStrategy(
+  strategy: PrefetchStrategy,
+): PrefetchStrategy {
+  if (strategy !== "adaptive") return strategy;
+  return getHoverNoneQuery()?.matches ? "viewport" : "hover";
+}
+
+/** Subscribe to changes in the input capability used by adaptive prefetch. */
+export function subscribeToAdaptiveStrategyChange(
+  listener: () => void,
+): () => void {
+  const query = getHoverNoneQuery();
+  if (!query) return () => {};
+  if (typeof query.addEventListener === "function") {
+    query.addEventListener("change", listener);
+    return () => query.removeEventListener("change", listener);
+  }
+  query.addListener(listener);
+  return () => query.removeListener(listener);
+}

package/src/browser/prefetch/invalidation.ts

@@ -0,0 +1,30 @@
+import { notifyListeners } from "../notify-listeners.js";
+
+type PrefetchCacheInvalidationListener = () => void;
+
+const listeners = new Map<symbol, PrefetchCacheInvalidationListener>();
+
+/** Subscribe to completed local prefetch-cache invalidations. */
+export function subscribeToPrefetchCacheInvalidation(
+  listener: PrefetchCacheInvalidationListener,
+): () => void {
+  const subscription = Symbol();
+  listeners.set(subscription, listener);
+
+  return () => listeners.delete(subscription);
+}
+
+/** Notify the registrations that existed when the cache was invalidated. */
+export function notifyPrefetchCacheInvalidated(): void {
+  const registrations = [...listeners];
+  // Finish the current broadcast/action finalizer before re-arming work. A
+  // synchronous callback could throw before cross-tab invalidation is sent or
+  // prefetch while the action fence is still raised.
+  queueMicrotask(() => {
+    notifyListeners(
+      registrations,
+      ([, listener]) => listener(),
+      ([subscription, listener]) => listeners.get(subscription) === listener,
+    );
+  });
+}

package/src/browser/prefetch/loader.ts

@@ -1,4 +1,5 @@
 import type { RscPayload } from "../types.js";
+import type { EventController } from "../event-controller.js";
 
 type PrefetchDecoder = (response: Promise<Response>) => Promise<RscPayload>;
 
@@ -78,25 +79,25 @@ export function prefetchQueued(
   );
 }
 
-export function observeForPrefetch(
-  element: Element,
+/** Run speculative work only when no navigation or stream is active. */
+export function schedulePrefetchWhenRouterIdle(
+  eventController: Pick<EventController, "getState" | "subscribe">,
   callback: () => void,
-): () => void {
-  if (typeof IntersectionObserver === "undefined") return () => {};
-  let active = true;
-  if (runtime) {
-    runtime.observeForPrefetch(element, callback);
-  } else {
-    void loadRuntime()
-      .then((loaded) => {
-        if (active) loaded.observeForPrefetch(element, callback);
-      })
-      .catch(() => {});
+): (() => void) | undefined {
+  const state = eventController.getState();
+  if (state.state === "idle" && !state.isStreaming) {
+    callback();
+    return;
   }
-  return () => {
-    active = false;
-    runtime?.unobserveForPrefetch(element);
-  };
+
+  const unsubscribe = eventController.subscribe(() => {
+    const nextState = eventController.getState();
+    if (nextState.state === "idle" && !nextState.isStreaming) {
+      unsubscribe();
+      callback();
+    }
+  });
+  return unsubscribe;
 }
 
 export function cancelAllPrefetches(keepUrl?: string | null): void {

package/src/browser/prefetch/observer.ts

@@ -12,32 +12,53 @@
  * scrolls in and out repeatedly.
  */
 
+import { notifyListeners } from "../notify-listeners.js";
+
 type PrefetchCallback = () => void;
 
-const callbacks = new Map<Element, PrefetchCallback>();
+const callbacks = new Map<Element, Map<symbol, PrefetchCallback>>();
 let observer: IntersectionObserver | null = null;
 
 function getObserver(): IntersectionObserver {
   if (!observer) {
     observer = new IntersectionObserver(
-      (entries) => {
-        for (const entry of entries) {
-          if (entry.isIntersecting) {
-            const callback = callbacks.get(entry.target);
-            if (callback) {
-              observer!.unobserve(entry.target);
-              callbacks.delete(entry.target);
-              callback();
+      (entries, currentObserver) => {
+        function* intersectingCallbacks(): Generator<
+          [Map<symbol, PrefetchCallback>, symbol, PrefetchCallback]
+        > {
+          for (const entry of entries) {
+            if (entry.isIntersecting) {
+              const subscriptions = callbacks.get(entry.target);
+              if (subscriptions) {
+                currentObserver.unobserve(entry.target);
+                callbacks.delete(entry.target);
+                for (const [subscription, callback] of subscriptions) {
+                  yield [subscriptions, subscription, callback];
+                }
+              }
             }
           }
         }
+        notifyListeners(
+          intersectingCallbacks(),
+          ([, , callback]) => callback(),
+          ([subscriptions, subscription]) => subscriptions.has(subscription),
+        );
       },
       { rootMargin: "200px" },
     );
+    for (const element of callbacks.keys()) observer.observe(element);
   }
   return observer;
 }
 
+/** Reset module state between tests that replace browser observer globals. */
+export function resetPrefetchObserverForTesting(): void {
+  observer?.disconnect();
+  observer = null;
+  callbacks.clear();
+}
+
 /**
  * Observe an element for viewport intersection.
  * When the element becomes visible (within 200px margin), the callback fires
@@ -47,19 +68,26 @@ function getObserver(): IntersectionObserver {
 export function observeForPrefetch(
   element: Element,
   onVisible: PrefetchCallback,
-): void {
-  if (typeof IntersectionObserver === "undefined") return;
-  callbacks.set(element, onVisible);
-  getObserver().observe(element);
-}
+): () => void {
+  if (typeof IntersectionObserver === "undefined") return () => {};
+  const currentObserver = getObserver();
 
-/**
- * Stop observing an element. Used for cleanup when a Link unmounts
- * before entering the viewport.
- */
-export function unobserveForPrefetch(element: Element): void {
-  callbacks.delete(element);
-  if (observer) {
-    observer.unobserve(element);
+  let subscriptions = callbacks.get(element);
+  if (!subscriptions) {
+    subscriptions = new Map();
+    callbacks.set(element, subscriptions);
   }
+
+  const subscription = Symbol();
+  subscriptions.set(subscription, onVisible);
+  if (subscriptions.size === 1) currentObserver.observe(element);
+
+  return () => {
+    const current = callbacks.get(element);
+    subscriptions.delete(subscription);
+    if (current !== subscriptions) return;
+    if (current.size > 0) return;
+    callbacks.delete(element);
+    observer?.unobserve(element);
+  };
 }

package/src/browser/prefetch/runtime.ts

@@ -4,4 +4,3 @@ export {
   cancelAllPrefetches,
   setPrefetchConcurrency,
 } from "./queue.js";
-export { observeForPrefetch, unobserveForPrefetch } from "./observer.js";

package/src/browser/rango-state.ts

@@ -52,6 +52,11 @@ export function setRangoStateObserver(
   externalRotationObserver = observer;
 }
 
+/** Return the resolved cookie name used to namespace cross-tab messages. */
+export function getRangoStateCookieName(): string {
+  return cookieName;
+}
+
 function notifyExternalRotation(value: string): void {
   externalRotationObserver?.(value);
 }
@@ -179,6 +184,22 @@ export function invalidateRangoState(): void {
   writeCookie(cookieName, mirror);
 }
 
+/** 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 {

package/src/browser/react/Link.tsx

@@ -7,13 +7,19 @@ import React, {
   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,
@@ -33,63 +39,26 @@ export type LinkState =
   | StateOrGetter<Record<string, unknown>>;
 
 import {
-  observeForPrefetch,
   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";
 
-// The (hover: none) MediaQueryList, created lazily on first client read and
-// reused across every Link render. matchMedia allocates and registers a live
-// query object; a fresh one per render (Link renders can be very frequent) is
-// wasteful when the same object's `.matches` is already live. Left null on the
-// server (no window).
-let hoverNoneQuery: MediaQueryList | null = null;
-
-/**
- * Read current touch/no-hover capability from the cached MediaQueryList. The
- * `.matches` read is live, so `prefetch="adaptive"` still reacts to
- * input-capability changes on hybrid devices (touch laptops, tablets gaining or
- * losing a pointer) and after SSR -> hydrate. The SSR guard returns a stable
- * `false` (pointer/hover default) so the resolved strategy doesn't drift on the
- * server vs the first client render.
- */
-function isTouchDevice(): boolean {
-  if (typeof window === "undefined") return false;
-  if (!hoverNoneQuery) {
-    hoverNoneQuery = window.matchMedia("(hover: none)");
-  }
-  return hoverNoneQuery.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";
-
-/**
- * Resolve a prefetch strategy, expanding "adaptive" to the concrete strategy
- * for the CURRENT input capability: "viewport" on touch (no-hover) devices,
- * "hover" on pointer devices. Non-adaptive strategies pass through unchanged.
- * Reads touch capability live (not a module-load snapshot) so the result
- * tracks input-capability changes.
- */
-export function resolveAdaptiveStrategy(
-  prefetch: PrefetchStrategy,
-): PrefetchStrategy {
-  if (prefetch !== "adaptive") return prefetch;
-  return isTouchDevice() ? "viewport" : "hover";
-}
+const IGNORE_STRATEGY_CHANGES = (_listener: () => void) => () => {};
 
 /**
  * Link component props
@@ -125,8 +94,14 @@ 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;
   /**
@@ -240,7 +215,7 @@ export const Link: ForwardRefExoticComponent<
     scroll = true,
     reloadDocument = false,
     revalidate,
-    prefetch = "none",
+    prefetch,
     prefetchKey,
     state,
     children,
@@ -262,10 +237,19 @@ export const Link: ForwardRefExoticComponent<
     return to === "/" ? bn : bn + to;
   }, [to, isExternal, ctx?.basename]);
 
-  // Resolve adaptive: viewport on touch devices, hover on pointer devices.
-  // isTouchDevice() is read here (per render), not from a module-load snapshot,
-  // so a device whose input capability changes resolves to the current value.
-  const resolvedStrategy = resolveAdaptiveStrategy(prefetch);
+  // 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);
@@ -364,10 +348,13 @@ export const Link: ForwardRefExoticComponent<
   );
 
   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
@@ -392,54 +379,77 @@ export const Link: ForwardRefExoticComponent<
     const isRender = resolvedStrategy === "render";
     if (!isViewport && !isRender) return;
 
-    let cancelled = false;
-    let unsubIdle: (() => void) | undefined;
-    let stopObserving: (() => void) | undefined;
+    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(
-        resolvedTo,
-        segmentState.currentSegmentIds,
-        getAppVersion(),
-        ctx.store.getRouterId?.(),
-        prefetchKey,
-      );
-    };
+      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;
-      stopObserving = 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?.();
-      stopObserving?.();
+      unsubscribeScope?.();
+      unsubscribeLocation();
+      disarmPrefetch();
     };
   }, [resolvedStrategy, resolvedTo, isExternal, ctx, prefetchKey]);
 

package/src/browser/react/NavigationProvider.tsx

@@ -349,6 +349,7 @@ export function NavigationProvider({
       eventController,
       navigate,
       refresh,
+      defaultPrefetch: initialPayload.metadata.defaultPrefetch,
     } as NavigationStoreContextValue;
     Object.defineProperty(value, "basename", {
       configurable: true,

package/src/browser/react/context.ts

@@ -3,6 +3,7 @@
 import { createContext, type Context } from "react";
 import type { NavigationStore, NavigateOptions } from "../types.js";
 import type { EventController } from "../event-controller.js";
+import type { PrefetchStrategy } from "../../router/prefetch-default.js";
 
 /**
  * Navigation context value provided by NavigationProvider
@@ -52,6 +53,9 @@ export interface NavigationStoreContextValue {
    * Used by Link and useRouter() to auto-prefix app-local paths.
    */
   basename: string | undefined;
+
+  /** Router default from this instance's initial payload. */
+  defaultPrefetch?: PrefetchStrategy;
 }
 
 /**