@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/src/browser/prefetch/cache.ts

@@ -1,24 +1,29 @@
 /**
  * Prefetch Cache
  *
- * In-memory cache storing prefetched Response objects for instant cache hits
- * on subsequent navigation. Two key scopes are in play:
+ * In-memory cache storing eagerly-decoded prefetch payloads for instant,
+ * already-warm cache hits on subsequent navigation. A prefetch fetches the
+ * RSC partial AND decodes it (createFromFetch) up front — decoding the Flight
+ * stream resolves the route's client references, so the route's JS chunks are
+ * imported during prefetch rather than on click. The decoded payload is reused
+ * verbatim by navigation, so a prefetched click loads no new code. Two key
+ * scopes are in play:
  * - Wildcard (default): built by `buildPrefetchKey(rangoState, target)` —
  *   shape `rangoState\0/target?...`. Shared across all source pages and
- *   invalidated automatically when Rango state bumps (deploy or
- *   server-action invalidation).
+ *   source segment trees; `_rsc_segments` is omitted from this key. Invalidated
+ *   automatically when Rango state bumps (deploy or server-action invalidation).
  * - Source-scoped: built by `buildSourceKey(rangoState, sourceHref, target)`
  *   — shape `rangoState\0sourceHref\0/target?...`. Embeds the Rango state
- *   (so rotation invalidates source-scoped entries too) plus the source
- *   href (so each originating page gets its own slot). Populated when the
+ *   (so rotation invalidates source-scoped entries too), the source href, and
+ *   the exact source segment tree. Populated when the
  *   server tags a response with `X-RSC-Prefetch-Scope: source` (intercept
  *   modals etc.), OR when a Link opts in with `prefetchKey=":source"` — in
  *   both cases so source-sensitive responses cannot bleed into navigations
  *   from other pages.
  *
  * Also tracks in-flight prefetch promises. Each promise resolves to the
- * navigation branch of a tee'd Response, allowing navigation to adopt a
- * still-downloading prefetch without reparsing or buffering the body. A
+ * decoded prefetch entry (or null), letting navigation adopt a
+ * still-downloading prefetch without issuing a duplicate request. A
  * single promise can be registered under multiple alias keys (see
  * `setInflightPromiseWithAliases`) so same-source navigations adopt via
  * their source key while cross-source ones fall through to the wildcard
@@ -26,23 +31,95 @@
  *
  * Replaces the previous browser HTTP cache approach which was unreliable
  * due to response draining race conditions and browser inconsistencies.
+ *
+ * State here lives in module-level singletons (cache, inflight, generation,
+ * cacheTTL, etc.) rather than a per-instance factory. This is correct because
+ * exactly one router is live per document — an SPA navigation crossing a
+ * host-router boundary forces a full document reload — so the singletons are
+ * effectively per-document. Unit tests reset them via clearPrefetchCache().
  */
 
-import { abortAllPrefetches } from "./queue.js";
+import { abortAllPrefetches } from "./loader.js";
+import { notifyPrefetchCacheInvalidated } from "./invalidation.js";
 import { invalidateRangoState } from "../rango-state.js";
+import type { RscPayload } from "../types.js";
+
+/**
+ * A prefetch that has been fetched AND eagerly decoded. Storing the decoded
+ * payload (not the raw Response) is what makes a prefetched navigation "warm":
+ * decoding the Flight stream during prefetch pulls the route's client chunks,
+ * so the click reuses ready elements and loads no new JS.
+ */
+export interface DecodedPrefetch {
+  /** The eagerly-decoded RSC payload. Reused verbatim by navigation. */
+  payload: Promise<RscPayload>;
+  /**
+   * Resolves when the underlying RSC stream finishes draining. Navigation
+   * forwards this as its streamComplete so scroll/revalidation gating is
+   * unchanged from the fresh-fetch path.
+   */
+  streamComplete: Promise<void>;
+  /**
+   * Prefetch scope as tagged by the server via `X-RSC-Prefetch-Scope`.
+   * `"source"` means the response is source-page-sensitive and must not be
+   * reused by a navigation from a different page — navigation enforces this
+   * when it adopted an inflight entry through the wildcard key.
+   */
+  scope: "source" | "wildcard";
+  /**
+   * Synchronously-readable flag, flipped to true when `streamComplete` resolves
+   * (the entire RSC stream has drained). Navigation reads this at click time to
+   * tell a FULLY warmed prefetch (payload commits without suspending → safe to
+   * commit in a startTransition, no fallback flash) from a partially-warmed one
+   * (still streaming → stream its fallbacks like a cold load). Starts false.
+   *
+   * On a respawned entry (see `respawn`) this starts true: the buffered bytes
+   * are a complete stream by construction.
+   */
+  complete: boolean;
+  /**
+   * Re-create this entry from its buffered raw Flight bytes. Attached (by
+   * `executePrefetchFetch`) only after the stream ended cleanly AND the eager
+   * decode succeeded — a truncated or failed prefetch must stay one-shot.
+   *
+   * Why bytes and not the decoded payload: the revived payload is a live graph
+   * with one-shot stream edges (the handle stream is an async generator drained
+   * during commit; userland payloads may embed serialized ReadableStreams).
+   * Re-decoding from the wire bytes manufactures fresh instances of every
+   * stream, which no amount of cloning the revived graph can do. Each call tees
+   * the reserve branch, so the replacement entry carries its own `respawn` —
+   * one prefetch serves unlimited adoptions within TTL/state validity.
+   */
+  respawn?: () => DecodedPrefetch;
+  /**
+   * Release the buffered reserve bytes. Called when the entry is evicted
+   * without being consumed (expiry, FIFO, sweep, cache clear) so the tee
+   * buffer is dropped promptly instead of waiting for GC.
+   */
+  dispose?: () => void;
+}
 
-// Default TTL: 5 minutes. Overridden by initPrefetchCache() with
-// the server-configured prefetchCacheTTL from router options.
-// 0 disables the in-memory cache entirely.
 let cacheTTL = 300_000;
+let fragmentPassthroughEnabled = true;
+
+// Max stored entries before FIFO eviction. Mirrors DEFAULT_PREFETCH_CACHE_SIZE
+// (router/prefetch-limits.ts); kept as a local literal so the client bundle
+// doesn't pull in router-layer code, matching the cacheTTL default above.
+// Overridden at startup by initPrefetchCache from server metadata.
+let maxPrefetchCacheSize = 100;
 
 /**
- * Initialize the prefetch cache with the configured TTL.
- * Called once at app startup with the value from server metadata.
- * A TTL of 0 disables the in-memory cache and all prefetching.
+ * Initialize the prefetch cache with the configured TTL and max size.
+ * Called once at app startup with the values from server metadata. Each
+ * argument is applied only when provided, so a caller can set just the TTL.
+ * A TTL of 0 disables the in-memory cache and all prefetching. A size below 1
+ * is ignored (the default is kept) — disabling prefetch is the TTL's job.
  */
-export function initPrefetchCache(ttlMs: number): void {
-  cacheTTL = ttlMs;
+export function initPrefetchCache(ttlMs?: number, maxSize?: number): void {
+  if (ttlMs !== undefined) cacheTTL = ttlMs;
+  if (maxSize !== undefined && Number.isFinite(maxSize) && maxSize >= 1) {
+    maxPrefetchCacheSize = Math.floor(maxSize);
+  }
 }
 
 /**
@@ -52,34 +129,31 @@ export function initPrefetchCache(ttlMs: number): void {
 export function isPrefetchCacheDisabled(): boolean {
   return cacheTTL <= 0;
 }
-const MAX_PREFETCH_CACHE_SIZE = 50;
 
 interface PrefetchCacheEntry {
-  response: Response;
+  entry: DecodedPrefetch;
   timestamp: number;
 }
 
 const cache = new Map<string, PrefetchCacheEntry>();
 const inflight = new Set<string>();
 
-/**
- * In-flight promise map. When a prefetch fetch is in progress, its
- * Promise<Response | null> is stored here so navigation can await
- * it instead of starting a duplicate request.
- */
-const inflightPromises = new Map<string, Promise<Response | null>>();
+// Watermark: the smallest entry timestamp currently in `cache`, i.e. a lower
+// bound on when the oldest entry expires (timestamp + cacheTTL). storePrefetch's
+// eager expiry sweep is skipped while `now - earliestTimestamp <= cacheTTL` — the
+// oldest entry cannot be expired yet, so nothing would be evicted. Deletions
+// (consume/has/remove) may leave it stale-LOW, which only forces a harmless extra
+// sweep that recomputes it exactly; it is never stale-high, so a skipped sweep
+// can never retain an expired entry. consume/has still TTL-check lazily, so a
+// skipped sweep never serves a stale entry. Infinity when the cache is empty.
+let earliestTimestamp = Infinity;
+
+const inflightPromises = new Map<string, Promise<DecodedPrefetch | null>>();
 
-/**
- * Alias map for in-flight promises registered under multiple keys (see
- * dual inflight in prefetch/fetch.ts). Records each key's sibling set so
- * that consuming or clearing any one key atomically removes every alias —
- * guaranteeing a single consumer for the shared Response stream.
- */
 const inflightAliases = new Map<string, string[]>();
 
-// Generation counter incremented on each clearPrefetchCache(). Fetches that
-// started before a clear carry a stale generation and must not store their
-// response (the data may be stale due to a server action invalidation).
+const adoptedKeys = new Set<string>();
+
 let generation = 0;
 
 /**
@@ -90,7 +164,9 @@ let generation = 0;
  * - Wildcard (source-agnostic): prefix is the Rango state value from
  *   `getRangoState()`. Shared across all source pages. Invalidated
  *   automatically when Rango state bumps (deploy or server-action).
- *   Key shape: `rangoState\0/target?...`.
+ *   `_rsc_segments` is omitted so sibling payloads prefetched from one page
+ *   remain reusable after another prefetched navigation commits. Key shape:
+ *   `rangoState\0/target?...`.
  * - Source-scoped: use `buildSourceKey()`. Key shape:
  *   `rangoState\0sourceHref\0/target?...` — embeds the Rango state so
  *   rotation invalidates source-scoped entries alongside wildcard ones,
@@ -99,12 +175,15 @@ let generation = 0;
  *   `X-RSC-Prefetch-Scope: source` (intercept modals, etc.) or when a
  *   Link opts in via `prefetchKey=":source"`.
  *
- * The `_rsc_segments` query param that travels in the target URL means
- * clients with different mounted segment trees naturally get different
- * keys — so segment-level diffs remain consistent across both scopes.
+ * Source-scoped keys retain `_rsc_segments` because their exact source tree is
+ * part of the opt-in contract. Wildcard responses are source-agnostic by
+ * contract; callers use source scope when a custom revalidation decision makes
+ * the response depend on the current URL or segment tree.
  */
 export function buildPrefetchKey(prefix: string, targetUrl: URL): string {
-  return prefix + "\0" + targetUrl.pathname + targetUrl.search;
+  const normalizedTarget = new URL(targetUrl);
+  normalizedTarget.searchParams.delete("_rsc_segments");
+  return prefix + "\0" + normalizedTarget.pathname + normalizedTarget.search;
 }
 
 /**
@@ -120,7 +199,14 @@ export function buildSourceKey(
   sourceHref: string,
   targetUrl: URL,
 ): string {
-  return buildPrefetchKey(rangoState + "\0" + sourceHref, targetUrl);
+  return (
+    rangoState +
+    "\0" +
+    sourceHref +
+    "\0" +
+    targetUrl.pathname +
+    targetUrl.search
+  );
 }
 
 /**
@@ -145,6 +231,7 @@ export function hasPrefetch(key: string): boolean {
   const entry = cache.get(key);
   if (!entry) return false;
   if (Date.now() - entry.timestamp > cacheTTL) {
+    entry.entry.dispose?.();
     cache.delete(key);
     return false;
   }
@@ -152,29 +239,42 @@ export function hasPrefetch(key: string): boolean {
 }
 
 /**
- * Consume a cached prefetch response. Returns null if not found or expired.
- * One-time consumption: the entry is deleted after retrieval.
- * Returns null when caching is disabled (TTL <= 0).
+ * Consume a cached, eagerly-decoded prefetch. Returns null if not found or
+ * expired. Returns null when caching is disabled (TTL <= 0).
+ *
+ * A decoded payload is single-render (its handle stream is drained during the
+ * commit), so the returned entry is never served twice. When the entry carries
+ * `respawn` (clean-EOF prefetch with buffered bytes), the slot is re-armed in
+ * place with a fresh decode of those bytes — the ORIGINAL timestamp is kept so
+ * TTL bounds the age of the data, not of the latest adoption. Without
+ * `respawn` the entry is deleted (legacy one-shot behavior).
  *
  * Does NOT check in-flight prefetches — use consumeInflightPrefetch()
- * for that (returns a Promise instead of a Response).
+ * for that (returns a Promise instead of a resolved entry).
  */
-export function consumePrefetch(key: string): Response | null {
+export function consumePrefetch(key: string): DecodedPrefetch | null {
   if (cacheTTL <= 0) return null;
-  const entry = cache.get(key);
-  if (!entry) return null;
-  if (Date.now() - entry.timestamp > cacheTTL) {
+  const cached = cache.get(key);
+  if (!cached) return null;
+  if (Date.now() - cached.timestamp > cacheTTL) {
+    cached.entry.dispose?.();
     cache.delete(key);
     return null;
   }
-  cache.delete(key);
-  return entry.response;
+  const entry = cached.entry;
+  if (entry.respawn) {
+    cached.entry = entry.respawn();
+  } else {
+    cache.delete(key);
+  }
+  return entry;
 }
 
 /**
  * Consume an in-flight prefetch promise. Returns null if no prefetch is
- * in-flight for this key. The returned Promise resolves to the buffered
- * Response (or null if the fetch failed/was aborted).
+ * in-flight for this key. The returned Promise resolves to the decoded
+ * prefetch entry (or null if the fetch failed/was aborted, or carried a
+ * control header the navigation must re-fetch to honor).
  *
  * One-time consumption: the promise entry is removed (along with any
  * sibling aliases registered via `setInflightPromiseWithAliases`) so a
@@ -188,49 +288,97 @@ export function consumePrefetch(key: string): Response | null {
  */
 export function consumeInflightPrefetch(
   key: string,
-): Promise<Response | null> | null {
+): Promise<DecodedPrefetch | null> | null {
   const promise = inflightPromises.get(key);
   if (!promise) return null;
   // Remove the promise under every alias so a second consumer cannot
-  // adopt the same stream and race on the body. `inflightAliases` is
-  // intentionally preserved — `clearPrefetchInflight()` in the fetch's
-  // `.finally()` still needs it to clear every inflight flag; deleting
-  // here would strand the sibling's flag forever.
-  forEachAlias(key, (k) => inflightPromises.delete(k));
+  // adopt the same stream and race on the body, and mark every alias as
+  // adopted so the pending `storePrefetch` (which resolves later, after this
+  // adoption) does not leave the now-owned, single-use entry in the cache map.
+  // `inflightAliases` is intentionally preserved — `clearPrefetchInflight()` in
+  // the fetch's `.finally()` still needs it to clear every inflight flag and
+  // adopted marker; deleting here would strand the sibling's flag forever.
+  forEachAlias(key, (k) => {
+    inflightPromises.delete(k);
+    adoptedKeys.add(k);
+  });
   return promise;
 }
 
 /**
- * Store a prefetch response in the in-memory cache.
- * The response should be a clone() of the original so the caller can
- * still consume the body. The clone's body streams independently.
+ * Store an eagerly-decoded prefetch in the in-memory cache.
  *
  * Skips storage if the generation has changed since the fetch started
  * (a server action invalidated the cache mid-flight).
  */
 export function storePrefetch(
   key: string,
-  response: Response,
+  entry: DecodedPrefetch,
   fetchGeneration: number,
 ): void {
   if (cacheTTL <= 0) return;
   if (fetchGeneration !== generation) return;
 
-  // Evict expired entries
+  // If a navigation already adopted this prefetch's in-flight promise, it owns
+  // the single-use entry (and has drained its handle generator). Do NOT also
+  // publish it to the cache map, or a later navigation would be served the
+  // exhausted entry and lose that route's handles. Clear the marker (under all
+  // aliases) now that the decision is made.
+  if (adoptedKeys.has(key)) {
+    forEachAlias(key, (k) => adoptedKeys.delete(k));
+    return;
+  }
+
+  // Evict expired entries — but only when the watermark says the oldest entry
+  // could have expired, so a burst of stores no longer walks the whole map each
+  // time. The sweep recomputes the exact watermark from the survivors.
   const now = Date.now();
-  for (const [k, entry] of cache) {
-    if (now - entry.timestamp > cacheTTL) {
-      cache.delete(k);
+  if (now - earliestTimestamp > cacheTTL) {
+    let min = Infinity;
+    for (const [k, cached] of cache) {
+      if (now - cached.timestamp > cacheTTL) {
+        cached.entry.dispose?.();
+        cache.delete(k);
+      } else if (cached.timestamp < min) {
+        min = cached.timestamp;
+      }
     }
+    earliestTimestamp = min;
   }
 
   // FIFO eviction if at capacity
-  if (cache.size >= MAX_PREFETCH_CACHE_SIZE) {
+  if (cache.size >= maxPrefetchCacheSize) {
     const oldest = cache.keys().next().value;
-    if (oldest) cache.delete(oldest);
+    if (oldest) {
+      cache.get(oldest)?.entry.dispose?.();
+      cache.delete(oldest);
+    }
   }
 
-  cache.set(key, { response, timestamp: now });
+  cache.set(key, { entry, timestamp: now });
+  // The new entry is the newest, so it only moves the watermark when the cache
+  // was empty (Infinity); otherwise the older watermark stands.
+  if (now < earliestTimestamp) earliestTimestamp = now;
+}
+
+/**
+ * Remove a single stored prefetch entry. Used to evict an entry whose body
+ * stream stalled after headers arrived (its payload / streamComplete never
+ * settle), so future prefetches and navigation refetch instead of dedupe-ing
+ * against — and awaiting — a stuck entry.
+ *
+ * Identity-guarded: only evicts when the entry CURRENTLY stored under `key` is
+ * the exact `entry` we published. A generation check alone is insufficient —
+ * after this entry is consumed (consumePrefetch) and a fresh prefetch
+ * republishes under the SAME key in the SAME generation, a gen-only guard would
+ * delete that valid newer entry. Reference identity drops only our own stalled
+ * entry.
+ */
+export function removePrefetch(key: string, entry: DecodedPrefetch): void {
+  if (cache.get(key)?.entry === entry) {
+    entry.dispose?.();
+    cache.delete(key);
+  }
 }
 
 /**
@@ -245,12 +393,9 @@ export function markPrefetchInflight(key: string): void {
   inflight.add(key);
 }
 
-/**
- * Store the in-flight Promise for a prefetch so navigation can reuse it.
- */
 export function setInflightPromise(
   key: string,
-  promise: Promise<Response | null>,
+  promise: Promise<DecodedPrefetch | null>,
 ): void {
   inflightPromises.set(key, promise);
 }
@@ -263,7 +408,7 @@ export function setInflightPromise(
  */
 export function setInflightPromiseWithAliases(
   keys: string[],
-  promise: Promise<Response | null>,
+  promise: Promise<DecodedPrefetch | null>,
 ): void {
   for (const k of keys) {
     inflightPromises.set(k, promise);
@@ -276,39 +421,37 @@ export function clearPrefetchInflight(key: string): void {
     inflight.delete(k);
     inflightPromises.delete(k);
     inflightAliases.delete(k);
+    adoptedKeys.delete(k);
   });
 }
 
-/**
- * Invalidate all prefetch state. Called when server actions mutate data.
- * Clears the in-memory cache, cancels in-flight prefetches, and rotates
- * the Rango state key so CDN-cached responses are also invalidated.
- *
- * Uses abortAllPrefetches (hard cancel) because in-flight responses
- * may contain stale data after a mutation.
- */
-export function clearPrefetchCache(): void {
-  generation++;
-  inflight.clear();
-  inflightPromises.clear();
-  inflightAliases.clear();
-  cache.clear();
-  abortAllPrefetches();
-  invalidateRangoState();
+/** Whether this document may request stored segment fragment envelopes. */
+export function isFragmentPassthroughEnabled(): boolean {
+  return fragmentPassthroughEnabled;
 }
 
 /**
- * Drop all in-memory prefetch state for this tab without rotating rango-state.
- *
- * Use for local-only invalidations (e.g. app switch in this tab) where
- * other tabs should NOT observe a state rotation. Unlike clearPrefetchCache,
- * does not call invalidateRangoState, so the shared X-Rango-State token
- * stays intact and siblings in the old app keep their prefetches.
+ * Disable fragment passthrough for the rest of this document after one stored
+ * fragment fails to decode. The recovery replaces shared cache entries, while
+ * this guard prevents the current tab's HTTP cache from serving its already-
+ * cached corrupt variant again.
  */
-export function clearPrefetchCacheLocal(): void {
+export function disableFragmentPassthrough(): void {
+  if (!fragmentPassthroughEnabled) return;
+  fragmentPassthroughEnabled = false;
+  clearPrefetchCache(false);
+}
+
+export function clearPrefetchCache(rotateRangoState = true): void {
   generation++;
   inflight.clear();
   inflightPromises.clear();
+  inflightAliases.clear();
+  adoptedKeys.clear();
+  for (const cached of cache.values()) cached.entry.dispose?.();
   cache.clear();
+  earliestTimestamp = Infinity;
   abortAllPrefetches();
+  if (rotateRangoState) invalidateRangoState();
+  notifyPrefetchCacheInvalidated();
 }

package/src/browser/prefetch/default-strategy.ts

@@ -0,0 +1,74 @@
+/**
+ * Router-wide default prefetch strategy (client seat).
+ *
+ * The server resolves `createRouter({ defaultPrefetch })` once at router init
+ * (router/prefetch-default.ts) and ships it in initial payload metadata; the
+ * browser entry applies it here before hydration — same lifecycle as
+ * `initPrefetchCache` / `setPrefetchConcurrency`. Every `<Link>` without an
+ * explicit `prefetch` prop and every eligible intercepted plain anchor that has
+ * not opted out with `data-prefetch="false"` or `data-prefetch="none"` uses it.
+ * Containers use the same `false`/`none` vocabulary via
+ * `data-prefetch-scope`.
+ *
+ * The module initial value must equal the server resolver's environment default:
+ * `"none"` in development and `"viewport"` in production. During SSR this
+ * module is never initialized from metadata, so keeping both seats aligned also
+ * gives metadata-less payloads the documented behavior.
+ */
+
+import type { PrefetchStrategy } from "../../router/prefetch-default.js";
+
+let hoverNoneQuery: MediaQueryList | null = null;
+
+// Mirrors DEFAULT_PREFETCH_STRATEGY without pulling router-layer code into the
+// client bundle. NODE_ENV is folded by the app build.
+let defaultStrategy: PrefetchStrategy =
+  process.env.NODE_ENV === "production" ? "viewport" : "none";
+
+function getHoverNoneQuery(): MediaQueryList | null {
+  if (typeof window === "undefined") return null;
+  if (!hoverNoneQuery) {
+    hoverNoneQuery = window.matchMedia("(hover: none)");
+  }
+  return hoverNoneQuery;
+}
+
+/** Reset module state between tests that replace browser media globals. */
+export function resetAdaptiveStrategyForTesting(): void {
+  hoverNoneQuery = null;
+}
+
+/**
+ * Apply the server-resolved default strategy. Called once at browser app init
+ * from payload metadata; also used by tests to reset state.
+ */
+export function setDefaultPrefetchStrategy(strategy: PrefetchStrategy): void {
+  defaultStrategy = strategy;
+}
+
+/** Current default strategy for Links and delegated plain anchors. */
+export function getDefaultPrefetchStrategy(): PrefetchStrategy {
+  return defaultStrategy;
+}
+
+/** Resolve adaptive to the strategy for the current input capability. */
+export function resolveAdaptiveStrategy(
+  strategy: PrefetchStrategy,
+): PrefetchStrategy {
+  if (strategy !== "adaptive") return strategy;
+  return getHoverNoneQuery()?.matches ? "viewport" : "hover";
+}
+
+/** Subscribe to changes in the input capability used by adaptive prefetch. */
+export function subscribeToAdaptiveStrategyChange(
+  listener: () => void,
+): () => void {
+  const query = getHoverNoneQuery();
+  if (!query) return () => {};
+  if (typeof query.addEventListener === "function") {
+    query.addEventListener("change", listener);
+    return () => query.removeEventListener("change", listener);
+  }
+  query.addListener(listener);
+  return () => query.removeListener(listener);
+}