@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.131

package/src/browser/prefetch/observer.ts

@@ -0,0 +1,65 @@
+/**
+ * Prefetch Observer
+ *
+ * Shared singleton IntersectionObserver for viewport-based prefetching.
+ * One observer handles all Link components with prefetch="viewport".
+ *
+ * Lazy-created on first call to avoid issues in SSR or test environments
+ * where IntersectionObserver may not exist.
+ *
+ * Observation is one-shot: once a link enters the viewport and the callback
+ * fires, the element is unobserved. This prevents re-prefetching when a link
+ * scrolls in and out repeatedly.
+ */
+
+type PrefetchCallback = () => void;
+
+const callbacks = new Map<Element, 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();
+            }
+          }
+        }
+      },
+      { rootMargin: "200px" },
+    );
+  }
+  return observer;
+}
+
+/**
+ * Observe an element for viewport intersection.
+ * When the element becomes visible (within 200px margin), the callback fires
+ * and the element is automatically unobserved.
+ * No-op in environments without IntersectionObserver (SSR, some test runners).
+ */
+export function observeForPrefetch(
+  element: Element,
+  onVisible: PrefetchCallback,
+): void {
+  if (typeof IntersectionObserver === "undefined") return;
+  callbacks.set(element, onVisible);
+  getObserver().observe(element);
+}
+
+/**
+ * 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);
+  }
+}

package/src/browser/prefetch/policy.ts

@@ -0,0 +1,48 @@
+/**
+ * Prefetch Policy
+ *
+ * Determines whether speculative prefetching should run for the current user.
+ * Honors browser reduced-data preferences when available.
+ */
+
+import { isPrefetchCacheDisabled } from "./cache.js";
+
+type NavigatorWithConnection = Navigator & {
+  connection?: {
+    saveData?: boolean;
+  };
+};
+
+/**
+ * Evaluate on every call so runtime changes to Save-Data or
+ * prefers-reduced-data are respected immediately.
+ */
+export function shouldPrefetch(): boolean {
+  if (typeof window === "undefined") return false;
+
+  // When prefetchCacheTTL is false/0, prefetching is fully disabled —
+  // no point issuing requests whose responses will be discarded.
+  if (isPrefetchCacheDisabled()) return false;
+
+  const nav =
+    typeof navigator !== "undefined"
+      ? (navigator as NavigatorWithConnection)
+      : undefined;
+
+  if (nav?.connection?.saveData) return false;
+
+  if (typeof window.matchMedia === "function") {
+    try {
+      if (window.matchMedia("(prefers-reduced-data: reduce)").matches) {
+        return false;
+      }
+    } catch {
+      // Ignore unsupported query errors and allow prefetch.
+    }
+  }
+
+  return true;
+}
+
+/** No-op, kept for test compatibility. */
+export function resetPrefetchPolicy(): void {}

package/src/browser/prefetch/queue.ts

@@ -0,0 +1,194 @@
+/**
+ * Prefetch Queue
+ *
+ * Concurrency-limited FIFO queue for speculative prefetches (viewport/render).
+ * Hover prefetches bypass this queue — they fire directly for immediate response
+ * to user intent.
+ *
+ * Draining waits for an idle main-thread moment and for viewport images to
+ * finish loading, so prefetch fetch() calls never compete with critical
+ * resources for the browser's connection pool.
+ *
+ * When a navigation starts, queued prefetches are cancelled but executing ones
+ * are left running. Navigation can reuse their in-flight responses via the
+ * prefetch cache's inflight promise map, avoiding duplicate requests.
+ */
+
+import { wait, waitForIdle, waitForViewportImages } from "./resource-ready.js";
+
+const MAX_CONCURRENT = 2;
+const IMAGE_WAIT_TIMEOUT = 2000;
+
+let active = 0;
+const queue: Array<{
+  key: string;
+  execute: (signal: AbortSignal) => Promise<void>;
+}> = [];
+const queued = new Set<string>();
+const executing = new Set<string>();
+const abortControllers = new Map<string, AbortController>();
+let drainScheduled = false;
+let drainGeneration = 0;
+
+function startExecution(
+  key: string,
+  execute: (signal: AbortSignal) => Promise<void>,
+): void {
+  active++;
+  executing.add(key);
+  const ac = new AbortController();
+  abortControllers.set(key, ac);
+  execute(ac.signal).finally(() => {
+    abortControllers.delete(key);
+    // Only decrement if this key wasn't already cleared by cancelAllPrefetches.
+    // Without this guard, cancelled tasks' .finally() would underflow active
+    // below zero, breaking the MAX_CONCURRENT guarantee.
+    if (executing.delete(key)) {
+      active--;
+    }
+    scheduleDrain();
+  });
+}
+
+/**
+ * Schedule a drain after the browser is idle and viewport images are loaded.
+ * Coalesces multiple drain requests into a single deferred callback so
+ * batch completion doesn't schedule redundant waits.
+ *
+ * The two-step wait ensures prefetch fetch() calls don't compete with
+ * images for the browser's connection pool:
+ * 1. waitForIdle — yield until the main thread has a quiet moment
+ * 2. waitForViewportImages OR 2s timeout — yield until visible images
+ *    finish loading, but don't let slow/broken images block indefinitely
+ */
+function scheduleDrain(): void {
+  if (drainScheduled) return;
+  if (active >= MAX_CONCURRENT || queue.length === 0) return;
+  drainScheduled = true;
+  const gen = drainGeneration;
+  waitForIdle()
+    .then(() =>
+      Promise.race([waitForViewportImages(), wait(IMAGE_WAIT_TIMEOUT)]),
+    )
+    .then(() => {
+      // Stale drain: a cancel/abort happened while we were waiting, and a fresh
+      // scheduleDrain may already own drainScheduled for the new generation.
+      // Bail WITHOUT clearing the flag so we don't clobber the live wait's
+      // single-in-flight-drain coalescing (clearing it here would let the next
+      // enqueue start a third overlapping wait).
+      if (gen !== drainGeneration) return;
+      drainScheduled = false;
+      if (queue.length > 0) drain();
+    });
+}
+
+function drain(): void {
+  while (active < MAX_CONCURRENT && queue.length > 0) {
+    const item = queue.shift()!;
+    queued.delete(item.key);
+    startExecution(item.key, item.execute);
+  }
+}
+
+/**
+ * Enqueue a prefetch for concurrency-limited execution.
+ * Execution is deferred until the browser is idle and viewport images
+ * have finished loading, so prefetches never compete with critical
+ * resources. Deduplicates by key — items already queued or executing
+ * are skipped.
+ *
+ * The executor receives an AbortSignal that is aborted when
+ * cancelAllPrefetches() is called (e.g. on navigation start).
+ */
+export function enqueuePrefetch(
+  key: string,
+  execute: (signal: AbortSignal) => Promise<void>,
+): void {
+  if (queued.has(key) || executing.has(key)) return;
+
+  queued.add(key);
+  queue.push({ key, execute });
+  scheduleDrain();
+}
+
+/**
+ * Normalize a URL-like string for keep-alive matching: parse against a
+ * placeholder origin and strip internal `_rsc_*` query params. Returns
+ * `pathname + search` so comparisons ignore hash and the internal params
+ * that prefetch appends to targets (`_rsc_partial`, `_rsc_segments`,
+ * `_rsc_v`, `_rsc_rid`, `_rsc_stale`).
+ */
+function normalizeForMatch(urlish: string): string {
+  try {
+    const u = new URL(urlish, "http://placeholder");
+    for (const k of [...u.searchParams.keys()]) {
+      if (k.startsWith("_rsc_")) u.searchParams.delete(k);
+    }
+    return u.pathname + u.search;
+  } catch {
+    return urlish;
+  }
+}
+
+/**
+ * Cancel queued prefetches and abort in-flight ones that don't match
+ * the current navigation target. If `keepUrl` is provided, the
+ * executing prefetch whose key targets that URL is kept alive so
+ * navigation can reuse its response via consumeInflightPrefetch.
+ *
+ * Called when a navigation starts via the NavigationProvider's
+ * event controller subscription.
+ */
+export function cancelAllPrefetches(keepUrl?: string | null): void {
+  queue.length = 0;
+  queued.clear();
+  drainScheduled = false;
+  drainGeneration++;
+
+  // Abort in-flight prefetches that aren't for the navigation target.
+  // Key shapes (see prefetch/cache.ts buildPrefetchKey):
+  //   wildcard:      "rangoState\0/target?..."
+  //   source-scoped: "rangoState\0sourceHref\0/target?..."
+  // The target portion is always the final \0-delimited segment and
+  // includes internal `_rsc_*` params (from buildPrefetchUrl); keepUrl
+  // comes from NavigationProvider's pendingUrl which is the bare
+  // navigation target. Normalize both sides before comparing.
+  const normalizedKeep = keepUrl ? normalizeForMatch(keepUrl) : null;
+  for (const [key, ac] of abortControllers) {
+    const lastNul = key.lastIndexOf("\0");
+    const target = lastNul >= 0 ? key.substring(lastNul + 1) : "";
+    if (
+      normalizedKeep &&
+      target &&
+      normalizeForMatch(target) === normalizedKeep
+    )
+      continue;
+    ac.abort();
+    abortControllers.delete(key);
+    if (executing.delete(key)) {
+      active--;
+    }
+  }
+}
+
+/**
+ * Hard-cancel everything including in-flight prefetches.
+ * Used by clearPrefetchCache (server action invalidation) where
+ * in-flight responses would be stale.
+ */
+export function abortAllPrefetches(): void {
+  for (const ac of abortControllers.values()) {
+    ac.abort();
+  }
+  abortControllers.clear();
+
+  queue.length = 0;
+  queued.clear();
+  // Clear executing before resetting active. In-flight .finally() callbacks
+  // check executing.delete(key) — if the key is gone, they skip decrementing,
+  // so active settles at 0 without underflow.
+  executing.clear();
+  active = 0;
+  drainScheduled = false;
+  drainGeneration++;
+}

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,194 @@
+/**
+ * Rango State
+ *
+ * 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).
+ *
+ * Value format: `{buildVersion}:{invalidationTimestamp}`
+ * - Build version changes on deploy, busting all cached prefetches at boot.
+ * - Timestamp rotates on invalidation (server action, invalidateClientCache).
+ *
+ * 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.
+ */
+
+import {
+  DEFAULT_STATE_COOKIE_PREFIX,
+  decodeStateValue,
+  getRawCookieValue,
+  mintStateValue,
+  serializeStateCookie,
+} from "./cookie-name.js";
+
+let cookieName: string = DEFAULT_STATE_COOKIE_PREFIX;
+
+let currentVersion = "0";
+
+let mirror: string | null = null;
+let cookieBacked = false;
+
+let externalRotationObserver: ((value: string) => void) | null = null;
+
+/**
+ * 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 setRangoStateObserver(
+  observer: ((value: string) => void) | null,
+): void {
+  externalRotationObserver = observer;
+}
+
+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 {
+    raw = document.cookie;
+  } catch {
+    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);
+}
+
+/**
+ * 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 {
+  const read = readCookie(cookieName);
+
+  if (!read.readable) {
+    // Mirror authoritative when the jar is unreadable.
+    return mirror ?? "0:0";
+  }
+
+  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;
+    }
+    return read.value;
+  }
+
+  // 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 (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 {
+  mirror = mintValue();
+  cookieBacked = false;
+  writeCookie(cookieName, mirror);
+}
+
+function cleanupLegacyStorage(): void {
+  if (typeof localStorage === "undefined") return;
+  try {
+    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 {}
+}