@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.20

package/src/browser/prefetch/cache.ts

@@ -0,0 +1,67 @@
+/**
+ * Prefetch Tracking
+ *
+ * Tracks in-flight and completed prefetches for deduplication.
+ * The actual response caching is handled by the browser's HTTP cache
+ * via Vary: X-Rango-State.
+ */
+
+import { cancelAllPrefetches } from "./queue.js";
+import { invalidateRangoState } from "../rango-state.js";
+
+const inflight = new Set<string>();
+const prefetched = new Set<string>();
+
+// Generation counter incremented on each clearPrefetchCache(). Fetches that
+// started before a clear carry a stale generation and must not re-add their
+// key to the prefetched set (the browser HTTP cache entry is already invalid
+// due to Rango-State rotation).
+let generation = 0;
+
+/**
+ * Check if a prefetch is already in-flight or completed for the given key.
+ */
+export function hasPrefetch(key: string): boolean {
+  return prefetched.has(key) || inflight.has(key);
+}
+
+/**
+ * Capture the current generation. The returned value is passed to
+ * markPrefetched so it can detect stale completions.
+ */
+export function currentGeneration(): number {
+  return generation;
+}
+
+/**
+ * Mark a key as successfully prefetched (response is in browser HTTP cache).
+ * Skips if the generation has changed since the fetch started (cache was
+ * invalidated mid-flight, so the response uses a stale X-Rango-State).
+ */
+export function markPrefetched(key: string, fetchGeneration: number): void {
+  if (fetchGeneration === generation) {
+    prefetched.add(key);
+  }
+}
+
+export function markPrefetchInflight(key: string): void {
+  inflight.add(key);
+}
+
+export function clearPrefetchInflight(key: string): void {
+  inflight.delete(key);
+}
+
+/**
+ * Invalidate prefetch state. Called when server actions mutate data.
+ * Updates the localStorage state key so next fetch has a different
+ * X-Rango-State value, causing Vary mismatch in browser HTTP cache.
+ * Also cancels any in-flight or queued speculative prefetches.
+ */
+export function clearPrefetchCache(): void {
+  generation++;
+  inflight.clear();
+  prefetched.clear();
+  cancelAllPrefetches();
+  invalidateRangoState();
+}

package/src/browser/prefetch/fetch.ts

@@ -0,0 +1,137 @@
+/**
+ * Prefetch Fetch
+ *
+ * Fetch-based prefetch logic used by Link (hover/viewport/render strategies)
+ * and useRouter().prefetch(). Sends low-priority fetch requests with
+ * X-Rango-State and X-Rango-Prefetch headers so the browser HTTP cache
+ * can serve the response on subsequent navigation.
+ */
+
+import {
+  hasPrefetch,
+  markPrefetchInflight,
+  markPrefetched,
+  clearPrefetchInflight,
+  currentGeneration,
+} from "./cache.js";
+import { getRangoState } from "../rango-state.js";
+import { enqueuePrefetch } from "./queue.js";
+import { shouldPrefetch } from "./policy.js";
+
+/**
+ * Build an RSC partial URL for prefetching.
+ * Includes _rsc_v for version mismatch detection when available.
+ * Returns null for malformed or cross-origin URLs to prevent
+ * leaking router headers to external origins.
+ */
+function buildPrefetchUrl(
+  url: string,
+  segmentIds: string[],
+  version?: string,
+): URL | null {
+  let targetUrl: URL;
+  try {
+    targetUrl = new URL(url, window.location.origin);
+  } catch {
+    return null;
+  }
+  if (targetUrl.origin !== window.location.origin) {
+    return null;
+  }
+  targetUrl.searchParams.set("_rsc_partial", "true");
+  if (segmentIds.length > 0) {
+    targetUrl.searchParams.set("_rsc_segments", segmentIds.join(","));
+  }
+  if (version) {
+    targetUrl.searchParams.set("_rsc_v", version);
+  }
+  return targetUrl;
+}
+
+/**
+ * Build the dedup key for prefetch tracking.
+ * Includes the source page pathname so the same target prefetched from
+ * different pages gets separate entries — the server response varies on
+ * X-RSC-Router-Client-Path (source page context).
+ */
+function buildPrefetchKey(targetUrl: URL): string {
+  return window.location.href + "\0" + targetUrl.pathname + targetUrl.search;
+}
+
+/**
+ * Core prefetch fetch logic. Returns a Promise and accepts an optional
+ * AbortSignal for cancellation by the prefetch queue.
+ */
+function executePrefetchFetch(
+  key: string,
+  fetchUrl: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  const gen = currentGeneration();
+  markPrefetchInflight(key);
+
+  return fetch(fetchUrl, {
+    priority: "low" as RequestPriority,
+    signal,
+    headers: {
+      "X-Rango-State": getRangoState(),
+      "X-RSC-Router-Client-Path": window.location.href,
+      "X-Rango-Prefetch": "1",
+    },
+  })
+    .then((response) => {
+      // Drain body to ensure full download for browser HTTP cache.
+      // pipeTo avoids decoding the stream into a JS string (unlike .text()).
+      if (response.ok && response.body) {
+        return response.body
+          .pipeTo(new WritableStream())
+          .then(() => markPrefetched(key, gen));
+      }
+    })
+    .catch(() => {
+      // Silently ignore prefetch failures (including abort)
+    })
+    .finally(() => {
+      clearPrefetchInflight(key);
+    });
+}
+
+/**
+ * Prefetch (direct): fetch with low priority and store in browser HTTP cache.
+ * Used by hover strategy -- fires immediately without queueing.
+ */
+export function prefetchDirect(
+  url: string,
+  segmentIds: string[],
+  version?: string,
+): void {
+  if (!shouldPrefetch()) return;
+
+  const targetUrl = buildPrefetchUrl(url, segmentIds, version);
+  if (!targetUrl) return;
+  const key = buildPrefetchKey(targetUrl);
+  if (hasPrefetch(key)) return;
+  executePrefetchFetch(key, targetUrl.toString());
+}
+
+/**
+ * Prefetch (queued): goes through the concurrency-limited queue.
+ * Used by viewport/render strategies to avoid flooding the server.
+ * Returns the cache key for use in cleanup.
+ */
+export function prefetchQueued(
+  url: string,
+  segmentIds: string[],
+  version?: string,
+): string {
+  if (!shouldPrefetch()) return "";
+  const targetUrl = buildPrefetchUrl(url, segmentIds, version);
+  if (!targetUrl) return "";
+  const key = buildPrefetchKey(targetUrl);
+  if (hasPrefetch(key)) return key;
+  const fetchUrlStr = targetUrl.toString();
+  enqueuePrefetch(key, (signal) =>
+    executePrefetchFetch(key, fetchUrlStr, signal),
+  );
+  return key;
+}

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,42 @@
+/**
+ * Prefetch Policy
+ *
+ * Determines whether speculative prefetching should run for the current user.
+ * Honors browser reduced-data preferences when available.
+ */
+
+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;
+
+  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,88 @@
+/**
+ * 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.
+ *
+ * All queued/executing prefetches share a single AbortController so they can
+ * be cancelled in bulk when a navigation starts.
+ */
+
+const MAX_CONCURRENT = 2;
+
+let active = 0;
+const queue: Array<{
+  key: string;
+  execute: (signal: AbortSignal) => Promise<void>;
+}> = [];
+const queued = new Set<string>();
+const executing = new Set<string>();
+let abortController: AbortController | null = null;
+
+function startExecution(
+  key: string,
+  execute: (signal: AbortSignal) => Promise<void>,
+): void {
+  active++;
+  executing.add(key);
+  abortController ??= new AbortController();
+  execute(abortController.signal).finally(() => {
+    // 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--;
+    }
+    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.
+ * If below the concurrency limit, executes immediately.
+ * Otherwise queues for later execution.
+ * 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;
+
+  if (active < MAX_CONCURRENT) {
+    startExecution(key, execute);
+  } else {
+    queued.add(key);
+    queue.push({ key, execute });
+  }
+}
+
+/**
+ * Cancel all in-flight and queued prefetches.
+ * Called when a navigation starts — speculative prefetches should not
+ * compete with navigation fetches for connection slots.
+ */
+export function cancelAllPrefetches(): void {
+  abortController?.abort();
+  abortController = null;
+
+  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;
+}

package/src/browser/rango-state.ts

@@ -0,0 +1,112 @@
+/**
+ * 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).
+ *
+ * Format: `{buildVersion}:{invalidationTimestamp}`
+ * - Build version changes on deploy, busting all cached prefetches.
+ * - Timestamp changes on server action invalidation.
+ *
+ * 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.
+ */
+
+const STORAGE_KEY = "rango-state";
+
+// Module-level cache avoids hitting localStorage on every getRangoState() call.
+// Initialized from localStorage on first access or by initRangoState().
+let cachedState: string | null = null;
+
+// Cross-tab sync: the `storage` event fires in OTHER tabs when one tab writes
+// to localStorage, keeping cachedState fresh without polling.
+let storageListenerAttached = false;
+
+function attachStorageListener(): void {
+  if (storageListenerAttached || typeof window === "undefined") return;
+  window.addEventListener("storage", (e) => {
+    if (e.key !== STORAGE_KEY) return;
+    cachedState = e.newValue;
+  });
+  storageListenerAttached = true;
+}
+
+/**
+ * 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.
+ */
+export function initRangoState(version: string): void {
+  if (typeof window === "undefined") return;
+
+  attachStorageListener();
+
+  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;
+  } catch {
+    // localStorage may be unavailable (private browsing in some browsers)
+    cachedState = `${version}:${Date.now()}`;
+  }
+}
+
+/**
+ * Get the current Rango state key value.
+ * Used as the `X-Rango-State` header value for prefetch and navigation requests.
+ */
+export function getRangoState(): string {
+  if (cachedState) return cachedState;
+
+  if (typeof window === "undefined") return "0:0";
+
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored) {
+      cachedState = stored;
+      return stored;
+    }
+  } catch {
+    // Fallback for unavailable localStorage
+  }
+
+  return "0:0";
+}
+
+/**
+ * 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.
+ */
+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;
+
+  if (typeof window === "undefined") return;
+
+  try {
+    localStorage.setItem(STORAGE_KEY, newState);
+  } catch {
+    // Silently handle localStorage errors
+  }
+}