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

package/src/browser/prefetch/queue.ts

@@ -0,0 +1,191 @@
+/**
+ * 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(() => {
+      drainScheduled = false;
+      // Stale drain: a cancel/abort happened while we were waiting.
+      // A fresh scheduleDrain will be called by whatever enqueues next.
+      if (gen !== drainGeneration) return;
+      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,152 @@
+/**
+ * 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).
+ *
+ * Value format: `{buildVersion}:{invalidationTimestamp}`
+ * - Build version changes on deploy, busting all cached prefetches.
+ * - Timestamp changes on server action invalidation.
+ *
+ * Storage key is namespaced per routerId (`rango-state:{routerId}`) so
+ * tabs in different apps on the same origin do not collide. Two tabs in
+ * the same app share a key → one tab's invalidation is picked up by the
+ * other via the `storage` event. A smooth cross-app transition in this
+ * tab rebinds to the target app's key; other tabs still in the old app
+ * keep their own key intact.
+ *
+ * If no routerId is supplied, falls back to a single legacy key for
+ * backward compatibility (single-app deployments unaffected).
+ */
+
+const LEGACY_STORAGE_KEY = "rango-state";
+
+function buildStorageKey(routerId: string | undefined): string {
+  return routerId ? `${LEGACY_STORAGE_KEY}:${routerId}` : LEGACY_STORAGE_KEY;
+}
+
+// Module-level cache avoids hitting localStorage on every getRangoState() call.
+// Initialized from localStorage on first access or by initRangoState().
+let cachedState: string | null = null;
+
+// The localStorage key this tab is currently bound to. Rebinds on
+// initRangoState (document boot) and setRangoStateLocal (smooth app
+// switch). The storage listener filters cross-tab events by this key so
+// events from tabs in a different app are ignored.
+let currentStorageKey: string = LEGACY_STORAGE_KEY;
+
+// 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) => {
+    // Only react to events for this tab's current app namespace. Events
+    // under other routerId-scoped keys belong to other apps and must not
+    // clobber this tab's state.
+    if (e.key !== currentStorageKey) 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.
+ * The routerId scopes the storage key to this app; in multi-app setups
+ * each app owns its own `rango-state:{routerId}` key and cannot observe
+ * invalidations from sibling apps on the same origin.
+ *
+ * If localStorage already has a matching-version entry under the key,
+ * keeps it (preserves invalidation state across refresh). Otherwise
+ * writes a new value.
+ */
+export function initRangoState(version: string, routerId?: string): void {
+  currentStorageKey = buildStorageKey(routerId);
+  if (typeof window === "undefined") return;
+
+  attachStorageListener();
+
+  try {
+    const existing = localStorage.getItem(currentStorageKey);
+    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(currentStorageKey, 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(currentStorageKey);
+    if (stored) {
+      cachedState = stored;
+      return stored;
+    }
+  } catch {
+    // Fallback for unavailable localStorage
+  }
+
+  return "0:0";
+}
+
+/**
+ * Update the in-memory rango-state to a new version WITHOUT writing
+ * localStorage. Intended for smooth cross-app transitions in this tab only:
+ * subsequent requests from this tab send the new token, but other tabs
+ * still in the previous app do not observe a storage event. Rebinds this
+ * tab's storage key to the target app's namespace (`rango-state:{routerId}`)
+ * so subsequent storage events only reflect the new app. On the next hard
+ * reload, initRangoState reconciles localStorage from the server's
+ * authoritative version.
+ */
+export function setRangoStateLocal(version: string, routerId?: string): void {
+  currentStorageKey = buildStorageKey(routerId);
+  cachedState = `${version}:${Date.now()}`;
+}
+
+/**
+ * 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(currentStorageKey, newState);
+  } catch {
+    // Silently handle localStorage errors
+  }
+}