@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.80daa23e

package/src/browser/link-interceptor.ts

@@ -1,4 +1,163 @@
 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.
+ */
+function isHashOnlyNavigationToPath(
+  anchor: HTMLAnchorElement,
+  pathname: string,
+): boolean {
+  return (
+    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
@@ -14,44 +173,119 @@ import type { LinkInterceptorOptions, NavigateOptions } from "./types.js";
  * @returns true if the link should be intercepted
  */
 export function defaultShouldIntercept(link: HTMLAnchorElement): boolean {
-  // Only intercept same-origin links
+  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;
+  }
+
+  // Only handle same-origin links
   if (link.origin !== window.location.origin) {
     return false;
   }
 
-  // Don't intercept if it has download attribute
-  if (link.hasAttribute("download")) {
+  // Skip links with a download attribute
+  if (link.hasAttribute(ELIGIBILITY_ATTRIBUTES.download)) {
     return false;
   }
 
-  // Don't intercept if target is set to something other than _self
-  if (link.target && link.target !== "_self") {
+  // Skip links targeting another browsing context
+  const target = link.getAttribute(ELIGIBILITY_ATTRIBUTES.target);
+  if (target && target !== "_self") {
     return false;
   }
 
-  // Don't intercept if explicitly disabled
-  if (link.getAttribute("data-no-intercept") === "true") {
+  // Skip links explicitly excluded from delegated handling
+  if (link.getAttribute(ELIGIBILITY_ATTRIBUTES.noIntercept) === "true") {
     return false;
   }
 
-  // Don't intercept Link component anchors - they handle their own navigation
-  if (link.hasAttribute("data-link-component")) {
+  // Link components handle their own navigation and prefetch
+  if (link.hasAttribute(ELIGIBILITY_ATTRIBUTES.linkComponent)) {
     return false;
   }
 
-  // Don't intercept external links
-  if (link.hasAttribute("data-external")) {
+  // 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
@@ -70,7 +304,7 @@ export function defaultShouldIntercept(link: HTMLAnchorElement): boolean {
  */
 export function setupLinkInterception(
   onNavigate: (url: string, options?: NavigateOptions) => void,
-  options?: LinkInterceptorOptions
+  options?: LinkInterceptorOptions,
 ): () => void {
   const shouldIntercept = options?.shouldIntercept ?? defaultShouldIntercept;
 
@@ -80,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)) {
@@ -98,6 +333,7 @@ export function setupLinkInterception(
     // Read navigation options from data attributes (set by Link component)
     const scrollAttr = link.getAttribute("data-scroll");
     const replaceAttr = link.getAttribute("data-replace");
+    const revalidateAttr = link.getAttribute("data-revalidate");
 
     const navigateOptions: NavigateOptions = {};
     if (scrollAttr === "false") {
@@ -106,16 +342,249 @@ export function setupLinkInterception(
     if (replaceAttr === "true") {
       navigateOptions.replace = true;
     }
+    if (revalidateAttr === "false") {
+      navigateOptions.revalidate = false;
+    }
 
     onNavigate(href, navigateOptions);
   };
 
   document.addEventListener("click", handleClick);
 
-  console.log("[Browser] Link interception enabled");
-
   return () => {
     document.removeEventListener("click", handleClick);
-    console.log("[Browser] Link interception disabled");
+  };
+}
+
+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/logging.ts

@@ -0,0 +1,83 @@
+import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
+
+/**
+ * Module-level debug flag for guarding call sites whose debug arguments do
+ * non-trivial work (joins, maps, spreads, object literals). Because the Vite
+ * transform folds INTERNAL_RANGO_DEBUG to a literal, an `if (IS_BROWSER_DEBUG)`
+ * guard is minifier-DCE-able — the whole block drops from the production bundle.
+ * Prefer this over isBrowserDebugEnabled() at hot call sites: a const guard folds
+ * where a function call may not.
+ */
+export const IS_BROWSER_DEBUG: boolean = INTERNAL_RANGO_DEBUG;
+
+interface BrowserLogContext {
+  requestId: string;
+  txId: string;
+  operation: string;
+}
+
+let txCounter = 0;
+let requestCounter = 0;
+
+export function isBrowserDebugEnabled(): boolean {
+  return INTERNAL_RANGO_DEBUG;
+}
+
+function nextId(prefix: string, counter: number): string {
+  return `${prefix}${counter.toString(36)}`;
+}
+
+export function startBrowserTransaction(operation: string): BrowserLogContext {
+  txCounter += 1;
+  requestCounter += 1;
+  return {
+    operation,
+    txId: nextId("ctx-", txCounter),
+    requestId: nextId("creq-", requestCounter),
+  };
+}
+
+export function browserDebugLog(
+  ctx: BrowserLogContext,
+  message: string,
+  details?: Record<string, unknown>,
+): void {
+  if (!INTERNAL_RANGO_DEBUG) return;
+
+  const prefix = `[Browser][req:${ctx.requestId}][tx:${ctx.operation}-${ctx.txId}]`;
+  if (details) {
+    console.log(`${prefix} ${message}`, details);
+    return;
+  }
+
+  console.log(`${prefix} ${message}`);
+}
+
+/**
+ * Simple gated console.log for browser-side debug output.
+ * Unlike browserDebugLog, this doesn't require a transaction context -
+ * use it for standalone debug messages in partial-update, navigation-bridge, etc.
+ */
+export function debugLog(msg: string, ...args: unknown[]): void {
+  if (INTERNAL_RANGO_DEBUG) {
+    console.log(msg, ...args);
+  }
+}
+
+/**
+ * Boot-sequence debug log: one line per initial-document step (flight decode,
+ * handle stream, bridge wiring, initial tree build, hydration commit), each
+ * stamped with performance.now() so the gap BEFORE hydrateRoot is visible.
+ * The initial document path was otherwise silent — FE debug only started
+ * talking at the first soft navigation, so a boot stall (e.g. an await that
+ * holds initBrowserApp, and with it hydrateRoot) was invisible.
+ */
+export function bootLog(step: string, details?: Record<string, unknown>): void {
+  if (!INTERNAL_RANGO_DEBUG) return;
+  const prefix = `[Browser][boot] ${step} @ ${Math.round(performance.now())}ms`;
+  if (details) {
+    console.log(prefix, details);
+    return;
+  }
+  console.log(prefix);
+}