@rangojs/router 0.4.0 → 0.4.2

package/src/browser/link-interceptor.ts

@@ -1,18 +1,164 @@
 import type { LinkInterceptorOptions, NavigateOptions } from "./types.js";
+import {
+  subscribeToLocationChange,
+  type EventController,
+} from "./event-controller.js";
+import {
+  getDefaultPrefetchStrategy,
+  resolveAdaptiveStrategy,
+  subscribeToAdaptiveStrategyChange,
+} from "./prefetch/default-strategy.js";
+import { observeForPrefetch } from "./prefetch/observer.js";
+import { subscribeToPrefetchCacheInvalidation } from "./prefetch/invalidation.js";
+import { notifyListeners } from "./notify-listeners.js";
+import type { PrefetchStrategy } from "../router/prefetch-default.js";
+
+const ELIGIBILITY_ATTRIBUTES = {
+  href: "href",
+  target: "target",
+  download: "download",
+  noIntercept: "data-no-intercept",
+  linkComponent: "data-link-component",
+  external: "data-external",
+  prefetch: "data-prefetch",
+  prefetchScope: "data-prefetch-scope",
+} as const;
+
+const ELIGIBILITY_ATTRIBUTE_FILTER = Object.values(ELIGIBILITY_ATTRIBUTES);
+const ANCHOR_SELECTOR = "a";
+const ELIGIBLE_ANCHOR_SELECTOR = `a[${ELIGIBILITY_ATTRIBUTES.href}]`;
+const LINK_COMPONENT_SELECTOR = `a[${ELIGIBILITY_ATTRIBUTES.linkComponent}]`;
+const HTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
+const PREFETCH_OPT_OUT_VALUES = new Set(["false", "none"]);
+const PREFETCH_SCOPE_OPT_OUT_SELECTOR =
+  `[${ELIGIBILITY_ATTRIBUTES.prefetchScope}="false"],` +
+  `[${ELIGIBILITY_ATTRIBUTES.prefetchScope}="none"]`;
+const STATIC_RESOURCE_EXTENSION =
+  /\.(?:7z|avif|bmp|bz2|cjs|css|csv|docx?|eot|gif|gz|ico|jpe?g|js|json|m4a|map|mjs|mov|mp3|mp4|ogg|ogv|otf|pdf|png|pptx?|rar|svg|tar|tgz|tiff?|ttf|txt|wasm|wav|webm|webp|woff2?|xlsx?|xml|zip)$/i;
+
+function isElementNode(value: unknown): value is Element {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Node).nodeType === 1 &&
+    typeof (value as Element).matches === "function"
+  );
+}
+
+function isNode(value: unknown): value is Node {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as Node).nodeType === "number"
+  );
+}
+
+type PrefetchScopeChangeListener = () => void;
+
+interface PrefetchScopeObserverState {
+  observer: MutationObserver;
+  subscriptions: Map<Element, Set<PrefetchScopeChangeListener>>;
+}
+
+const prefetchScopeObservers = new WeakMap<
+  Document,
+  PrefetchScopeObserverState
+>();
+
+function createPrefetchScopeObserverState(
+  ownerDocument: Document,
+): PrefetchScopeObserverState | undefined {
+  if (
+    typeof MutationObserver === "undefined" ||
+    !ownerDocument.documentElement
+  ) {
+    return undefined;
+  }
+
+  const subscriptions = new Map<Element, Set<PrefetchScopeChangeListener>>();
+  const observer = new MutationObserver((mutations) => {
+    const affected = new Set<PrefetchScopeChangeListener>();
+    const collect = (element: Element) => {
+      subscriptions.get(element)?.forEach((listener) => affected.add(listener));
+    };
+
+    for (const mutation of mutations) {
+      if (!isElementNode(mutation.target)) continue;
+      collect(mutation.target);
+      mutation.target
+        .querySelectorAll(LINK_COMPONENT_SELECTOR)
+        .forEach(collect);
+    }
+    notifyListeners(affected, (listener) => listener());
+  });
+  observer.observe(ownerDocument.documentElement, {
+    subtree: true,
+    attributes: true,
+    attributeFilter: [ELIGIBILITY_ATTRIBUTES.prefetchScope],
+  });
+  return { observer, subscriptions };
+}
+
+export function subscribeToPrefetchScopeChange(
+  element: HTMLAnchorElement,
+  listener: PrefetchScopeChangeListener,
+): () => void {
+  const ownerDocument = element.ownerDocument;
+  let state = prefetchScopeObservers.get(ownerDocument);
+  if (!state) {
+    state = createPrefetchScopeObserverState(ownerDocument);
+    if (!state) return () => {};
+    prefetchScopeObservers.set(ownerDocument, state);
+  }
+
+  let listeners = state.subscriptions.get(element);
+  if (!listeners) {
+    listeners = new Set();
+    state.subscriptions.set(element, listeners);
+  }
+  listeners.add(listener);
+
+  let active = true;
+  return () => {
+    if (!active) return;
+    active = false;
+    listeners.delete(listener);
+    if (
+      listeners.size === 0 &&
+      state.subscriptions.get(element) === listeners
+    ) {
+      state.subscriptions.delete(element);
+    }
+    if (
+      state.subscriptions.size === 0 &&
+      prefetchScopeObservers.get(ownerDocument) === state
+    ) {
+      state.observer.disconnect();
+      prefetchScopeObservers.delete(ownerDocument);
+    }
+  };
+}
 
 /**
  * Check if an anchor points to the same page with only a hash change.
  * Used by both Link component and link-interceptor to let the browser
  * handle anchor scrolling natively.
  */
-export function isHashOnlyNavigation(anchor: HTMLAnchorElement): boolean {
+function isHashOnlyNavigationToPath(
+  anchor: HTMLAnchorElement,
+  pathname: string,
+): boolean {
   return (
-    anchor.pathname === window.location.pathname &&
+    pathname === window.location.pathname &&
     anchor.search === window.location.search &&
     !!anchor.hash
   );
 }
 
+export function isHashOnlyNavigation(anchor: HTMLAnchorElement): boolean {
+  return isHashOnlyNavigationToPath(anchor, anchor.pathname);
+}
+
 /**
  * Default link interception predicate
  *
@@ -27,50 +173,119 @@ export function isHashOnlyNavigation(anchor: HTMLAnchorElement): boolean {
  * @returns true if the link should be intercepted
  */
 export function defaultShouldIntercept(link: HTMLAnchorElement): boolean {
-  // Only intercept same-origin links
-  if (link.origin !== window.location.origin) {
+  if (!isEligiblePlainAnchor(link)) return false;
+
+  // Don't intercept hash-only navigation (same path, only fragment changes).
+  // Let the browser handle anchor scrolling natively.
+  return !isHashOnlyNavigation(link);
+}
+
+function isEligiblePlainAnchor(link: HTMLAnchorElement): boolean {
+  // Namespace identity survives adoptNode/importNode across realms; instanceof
+  // does not. Structural test doubles omit namespaceURI and retain the legacy
+  // property-based behavior.
+  if (link.namespaceURI && link.namespaceURI !== HTML_NAMESPACE) {
     return false;
   }
 
-  // Don't intercept if it has download attribute
-  if (link.hasAttribute("download")) {
+  // Only handle same-origin links
+  if (link.origin !== window.location.origin) {
     return false;
   }
 
-  // Don't intercept if target is set to something other than _self
-  if (link.target && link.target !== "_self") {
+  // Skip links with a download attribute
+  if (link.hasAttribute(ELIGIBILITY_ATTRIBUTES.download)) {
     return false;
   }
 
-  // Don't intercept if explicitly disabled
-  if (link.getAttribute("data-no-intercept") === "true") {
+  // Skip links targeting another browsing context
+  const target = link.getAttribute(ELIGIBILITY_ATTRIBUTES.target);
+  if (target && target !== "_self") {
     return false;
   }
 
-  // Don't intercept Link component anchors - they handle their own navigation
-  if (link.hasAttribute("data-link-component")) {
+  // Skip links explicitly excluded from delegated handling
+  if (link.getAttribute(ELIGIBILITY_ATTRIBUTES.noIntercept) === "true") {
     return false;
   }
 
-  // Don't intercept external links
-  if (link.hasAttribute("data-external")) {
+  // Link components handle their own navigation and prefetch
+  if (link.hasAttribute(ELIGIBILITY_ATTRIBUTES.linkComponent)) {
     return false;
   }
 
-  // Don't intercept hash-only navigation (same path, only fragment changes).
-  // Let the browser handle anchor scrolling natively.
-  if (isHashOnlyNavigation(link)) {
+  // Skip links explicitly marked external
+  if (link.hasAttribute(ELIGIBILITY_ATTRIBUTES.external)) {
     return false;
   }
 
   return true;
 }
 
+function normalizePathname(pathname: string): string {
+  return pathname
+    .replace(/%[0-9a-f]{2}/gi, (escape) => escape.toUpperCase())
+    .replace(/\/+$/, "");
+}
+
+function canonicalizeBasenamePathname(basename?: string): string | undefined {
+  if (!basename) return undefined;
+  return normalizePathname(new URL(basename, window.location.origin).pathname);
+}
+
+export function isPrefetchScopeDisabled(element: Element): boolean {
+  return (
+    typeof element.closest === "function" &&
+    element.closest(PREFETCH_SCOPE_OPT_OUT_SELECTOR) !== null
+  );
+}
+
+type PrefetchEligibility = "eligible" | "location-dependent" | "ineligible";
+
+function defaultPrefetchEligibilityInBasename(
+  link: HTMLAnchorElement,
+  basename?: string,
+): PrefetchEligibility {
+  if (!isEligiblePlainAnchor(link)) return "ineligible";
+  if (isPrefetchScopeDisabled(link)) return "ineligible";
+
+  const prefetch = link.getAttribute(ELIGIBILITY_ATTRIBUTES.prefetch);
+  if (prefetch && PREFETCH_OPT_OUT_VALUES.has(prefetch)) return "ineligible";
+
+  const rawPathname = link.pathname;
+  if (isHashOnlyNavigationToPath(link, rawPathname)) {
+    return "location-dependent";
+  }
+  const pathname = normalizePathname(rawPathname);
+  if (
+    basename !== undefined &&
+    pathname !== basename &&
+    !pathname.startsWith(`${basename}/`)
+  ) {
+    return "ineligible";
+  }
+
+  if (prefetch === "true") return "eligible";
+
+  // Scope is decided on canonical encoded path segments. Decode only for
+  // resource classification so malformed escapes cannot expand router scope.
+  let resourcePathname: string;
+  try {
+    resourcePathname = decodeURIComponent(pathname);
+  } catch {
+    return "ineligible";
+  }
+  if (STATIC_RESOURCE_EXTENSION.test(resourcePathname)) {
+    return "ineligible";
+  }
+  return "eligible";
+}
+
 /**
  * Set up link interception for SPA navigation
  *
- * Attaches a global click handler to intercept clicks on anchor elements
- * and call the onNavigate callback instead of performing a full page load.
+ * Attaches a global click handler to intercept clicks on anchor elements and
+ * call the onNavigate callback instead of performing a full page load.
  *
  * @param onNavigate - Callback when a link should navigate via SPA
  * @param options - Configuration options
@@ -99,7 +314,8 @@ export function setupLinkInterception(
       return;
     }
 
-    const target = event.target as HTMLElement;
+    if (!isElementNode(event.target)) return;
+    const target = event.target;
     const link = target.closest("a");
 
     if (!link || !shouldIntercept(link)) {
@@ -139,3 +355,236 @@ export function setupLinkInterception(
     document.removeEventListener("click", handleClick);
   };
 }
+
+export type DelegatedPrefetchCallback = (
+  url: string,
+  priority: "direct" | "queued",
+) => void | (() => void);
+
+export interface DelegatedPrefetchOptions {
+  eventController: Pick<EventController, "getState" | "subscribe">;
+  shouldPrefetch?: (link: HTMLAnchorElement) => boolean;
+  defaultPrefetch?: PrefetchStrategy;
+  root?: HTMLElement;
+  basename?: string;
+}
+
+interface DelegatedPrefetchState {
+  stopObserving?: () => void;
+  cancelPending?: () => void;
+}
+
+export function setupDelegatedLinkPrefetch(
+  onPrefetch: DelegatedPrefetchCallback,
+  options: DelegatedPrefetchOptions,
+): () => void {
+  const defaultStrategy =
+    options.defaultPrefetch ?? getDefaultPrefetchStrategy();
+  if (defaultStrategy === "none") return () => {};
+
+  const basename = canonicalizeBasenamePathname(options.basename);
+  const customShouldPrefetch = options.shouldPrefetch;
+  const getEligibility = customShouldPrefetch
+    ? (link: HTMLAnchorElement): PrefetchEligibility => {
+        if (isPrefetchScopeDisabled(link)) return "ineligible";
+        return customShouldPrefetch(link) ? "eligible" : "ineligible";
+      }
+    : (link: HTMLAnchorElement) =>
+        defaultPrefetchEligibilityInBasename(link, basename);
+  const states = new Map<HTMLAnchorElement, DelegatedPrefetchState>();
+  const parked = new Set<HTMLAnchorElement>();
+  let strategy = resolveAdaptiveStrategy(defaultStrategy);
+
+  const disarm = (link: HTMLAnchorElement) => {
+    const state = states.get(link);
+    state?.stopObserving?.();
+    state?.cancelPending?.();
+    states.delete(link);
+    if (strategy === "hover") syncMutationObserver();
+  };
+
+  const evaluateEligibility = (link: HTMLAnchorElement): PrefetchEligibility =>
+    link.hasAttribute(ELIGIBILITY_ATTRIBUTES.href)
+      ? getEligibility(link)
+      : "ineligible";
+
+  const updateParked = (
+    link: HTMLAnchorElement,
+    eligibility: PrefetchEligibility,
+  ) => {
+    if (eligibility === "location-dependent" && strategy !== "hover") {
+      parked.add(link);
+    } else parked.delete(link);
+  };
+
+  const forget = (link: HTMLAnchorElement) => {
+    disarm(link);
+    parked.delete(link);
+  };
+
+  const trigger = (link: HTMLAnchorElement, priority: "direct" | "queued") => {
+    const eligibility = evaluateEligibility(link);
+    updateParked(link, eligibility);
+    if (eligibility !== "eligible") {
+      disarm(link);
+      return;
+    }
+
+    let state = states.get(link);
+    if (!state) {
+      state = {};
+      states.set(link, state);
+    }
+    state.cancelPending?.();
+    state.cancelPending = undefined;
+    try {
+      state.cancelPending = onPrefetch(link.href, priority) ?? undefined;
+    } finally {
+      if (strategy === "hover" && !state.cancelPending) states.delete(link);
+      syncMutationObserver();
+    }
+  };
+
+  const register = (link: HTMLAnchorElement) => {
+    disarm(link);
+    const eligibility = evaluateEligibility(link);
+    updateParked(link, eligibility);
+    if (eligibility !== "eligible") return;
+    if (strategy === "hover") return;
+
+    const state: DelegatedPrefetchState = {};
+    states.set(link, state);
+
+    if (strategy === "render") {
+      trigger(link, "queued");
+    } else if (strategy === "viewport") {
+      state.stopObserving = observeForPrefetch(link, () => {
+        state.stopObserving = undefined;
+        trigger(link, "queued");
+      });
+    }
+  };
+
+  const visitAnchors = (
+    node: Node,
+    visit: (link: HTMLAnchorElement) => void,
+  ) => {
+    if (!isElementNode(node)) return;
+    if (node.matches(ANCHOR_SELECTOR)) {
+      visit(node as HTMLAnchorElement);
+    }
+    node
+      .querySelectorAll<HTMLAnchorElement>(ANCHOR_SELECTOR)
+      .forEach((link) => visit(link));
+  };
+
+  const root = options.root ?? document.documentElement;
+  let mutationObserver: MutationObserver | undefined;
+  function syncMutationObserver(): void {
+    const shouldObserve =
+      strategy === "viewport" || strategy === "render" || states.size > 0;
+    if (!shouldObserve) {
+      mutationObserver?.disconnect();
+      mutationObserver = undefined;
+      return;
+    }
+    if (mutationObserver || typeof MutationObserver === "undefined" || !root) {
+      return;
+    }
+
+    mutationObserver = new MutationObserver((mutations) => {
+      const affected = new Set<HTMLAnchorElement>();
+      const markAffected = (link: HTMLAnchorElement) => affected.add(link);
+      for (const mutation of mutations) {
+        if (mutation.type === "attributes") {
+          if (mutation.attributeName === ELIGIBILITY_ATTRIBUTES.prefetchScope) {
+            visitAnchors(mutation.target, markAffected);
+          } else if (
+            isElementNode(mutation.target) &&
+            mutation.target.matches(ANCHOR_SELECTOR)
+          ) {
+            affected.add(mutation.target as HTMLAnchorElement);
+          }
+          continue;
+        }
+        mutation.removedNodes.forEach((node) =>
+          visitAnchors(node, markAffected),
+        );
+        mutation.addedNodes.forEach((node) => visitAnchors(node, markAffected));
+      }
+      for (const link of affected) {
+        if (link.isConnected && root.contains(link)) register(link);
+        else forget(link);
+      }
+    });
+    mutationObserver.observe(root, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+      attributeFilter: ELIGIBILITY_ATTRIBUTE_FILTER,
+    });
+  }
+
+  const rescan = () => {
+    for (const link of [...states.keys()]) disarm(link);
+    parked.clear();
+    strategy = resolveAdaptiveStrategy(defaultStrategy);
+    syncMutationObserver();
+    if ((strategy === "viewport" || strategy === "render") && root) {
+      visitAnchors(root, register);
+    }
+  };
+
+  rescan();
+
+  const handleMouseOver = (event: MouseEvent) => {
+    if (!isElementNode(event.target)) return;
+
+    const link = event.target.closest<HTMLAnchorElement>(
+      ELIGIBLE_ANCHOR_SELECTOR,
+    );
+    if (!link || !root.contains(link)) return;
+    if (isNode(event.relatedTarget) && link.contains(event.relatedTarget)) {
+      return;
+    }
+    trigger(link, "direct");
+  };
+
+  if (strategy === "hover" || strategy === "viewport") {
+    root.addEventListener("mouseover", handleMouseOver);
+  }
+
+  const unsubscribeLocation =
+    defaultStrategy === "viewport" ||
+    defaultStrategy === "render" ||
+    defaultStrategy === "adaptive"
+      ? subscribeToLocationChange(options.eventController, () => {
+          if (strategy !== "viewport" && strategy !== "render") return;
+          for (const link of [...parked]) {
+            if (link.isConnected && root.contains(link)) register(link);
+            else forget(link);
+          }
+        })
+      : undefined;
+  const unsubscribeAdaptive =
+    defaultStrategy === "adaptive"
+      ? subscribeToAdaptiveStrategyChange(rescan)
+      : undefined;
+  const unsubscribeInvalidation = subscribeToPrefetchCacheInvalidation(() => {
+    if (strategy !== "viewport" && strategy !== "render") return;
+    for (const link of [...states.keys()]) {
+      if (link.isConnected && root.contains(link)) register(link);
+      else forget(link);
+    }
+  });
+
+  return () => {
+    mutationObserver?.disconnect();
+    root.removeEventListener("mouseover", handleMouseOver);
+    unsubscribeLocation?.();
+    unsubscribeAdaptive?.();
+    unsubscribeInvalidation();
+    for (const link of [...states.keys()]) disarm(link);
+    parked.clear();
+  };
+}

package/src/browser/navigation-bridge.ts

@@ -1,6 +1,7 @@
 import type {
   NavigationBridge,
   NavigationBridgeConfig,
+  NavigationStore,
   NavigateOptionsInternal,
   ResolvedSegment,
 } from "./types.js";
@@ -24,7 +25,10 @@ import {
 const addTransitionType: ((type: string) => void) | undefined =
   "addTransitionType" in React ? (React as any).addTransitionType : undefined;
 
-import { setupLinkInterception } from "./link-interceptor.js";
+import {
+  setupDelegatedLinkPrefetch,
+  setupLinkInterception,
+} from "./link-interceptor.js";
 import { createPartialUpdater } from "./partial-update.js";
 import { generateHistoryKey } from "./navigation-store.js";
 import type { EventController } from "./event-controller.js";
@@ -38,6 +42,12 @@ import {
 import { debugLog } from "./logging.js";
 import { ServerRedirect } from "../errors.js";
 import { validateRedirectOrigin } from "./validate-redirect-origin.js";
+import {
+  prefetchDirect,
+  prefetchQueued,
+  schedulePrefetchWhenRouterIdle,
+} from "./prefetch/loader.js";
+import type { PrefetchStrategy } from "../router/prefetch-default.js";
 
 // Polyfill Symbol.dispose for Safari and older browsers
 if (typeof Symbol.dispose === "undefined") {
@@ -53,6 +63,48 @@ export interface NavigationBridgeConfigWithController extends NavigationBridgeCo
   eventController: EventController;
   /** RSC version from initial payload metadata. */
   version?: string;
+  /** Server-resolved default used by both Links and delegated anchors. */
+  defaultPrefetch?: PrefetchStrategy;
+  /** Canonical router basename used to scope delegated anchor prefetch. */
+  basename?: string;
+}
+
+export interface NavigationBridgeDelegatedPrefetchOptions {
+  defaultPrefetch?: PrefetchStrategy;
+  root?: HTMLElement;
+  basename?: string;
+}
+
+/** Register delegated anchor prefetch with the production bridge wiring. */
+export function setupNavigationBridgeDelegatedPrefetch(
+  store: NavigationStore,
+  eventController: EventController,
+  getVersion: () => string | undefined,
+  options: NavigationBridgeDelegatedPrefetchOptions = {},
+): () => void {
+  return setupDelegatedLinkPrefetch(
+    (url, priority) => {
+      const trigger = () => {
+        const segmentState = store.getSegmentState();
+        const prefetch =
+          priority === "direct" ? prefetchDirect : prefetchQueued;
+        prefetch(
+          url,
+          segmentState.currentSegmentIds,
+          getVersion(),
+          store.getRouterId?.(),
+        );
+      };
+
+      if (priority === "direct") {
+        trigger();
+        return;
+      }
+
+      return schedulePrefetchWhenRouterIdle(eventController, trigger);
+    },
+    { eventController, ...options },
+  );
 }
 
 /**
@@ -71,7 +123,15 @@ export interface NavigationBridgeConfigWithController extends NavigationBridgeCo
 export function createNavigationBridge(
   config: NavigationBridgeConfigWithController,
 ): NavigationBridge {
-  const { store, client, eventController, onUpdate, renderSegments } = config;
+  const {
+    store,
+    client,
+    eventController,
+    onUpdate,
+    renderSegments,
+    defaultPrefetch,
+    basename,
+  } = config;
   let version = config.version;
 
   // Create shared partial updater
@@ -724,6 +784,15 @@ export function createNavigationBridge(
       };
     },
 
+    registerDelegatedPrefetch(): () => void {
+      return setupNavigationBridgeDelegatedPrefetch(
+        store,
+        eventController,
+        () => version,
+        { defaultPrefetch, basename },
+      );
+    },
+
     getVersion(): string | undefined {
       return version;
     },