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

package/src/browser/prefetch/fetch.ts

@@ -3,12 +3,16 @@
  *
  * Fetch-based prefetch logic used by Link (hover/viewport/render strategies)
  * and useRouter().prefetch(). Sends the same headers and segment IDs as a
- * real navigation so the server returns a proper diff. The Response is fully
- * buffered and stored in an in-memory cache for instant consumption on
- * subsequent navigation.
+ * real navigation so the server returns a proper diff. The response is fetched
+ * AND eagerly decoded (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 stored in an
+ * in-memory cache and reused verbatim by navigation, so a prefetched click
+ * loads no new code.
  *
  * In-flight promises are tracked in the cache so that navigation can reuse
- * a prefetch that is still downloading instead of starting a duplicate request.
+ * a prefetch that is still downloading/decoding instead of starting a
+ * duplicate request.
  */
 
 import {
@@ -18,13 +22,96 @@ import {
   markPrefetchInflight,
   setInflightPromiseWithAliases,
   storePrefetch,
+  removePrefetch,
   clearPrefetchInflight,
   currentGeneration,
+  isFragmentPassthroughEnabled,
+  type DecodedPrefetch,
 } from "./cache.js";
 import { getRangoState } from "../rango-state.js";
+import { isActionFenceActive } from "../action-fence.js";
 import { enqueuePrefetch } from "./queue.js";
 import { shouldPrefetch } from "./policy.js";
-import { debugLog } from "../logging.js";
+import { debugLog, IS_BROWSER_DEBUG } from "../logging.js";
+import { teeWithCompletion, isForeignRouterId } from "../response-adapter.js";
+import { SEGMENT_FRAGMENT_CAPABILITY_HEADER } from "../../segment-fragments.js";
+import type { RscPayload } from "../types.js";
+
+/**
+ * Decoder injected at app startup (see setPrefetchDecoder). This is
+ * `deps.createFromFetch` — decoupled from the RSC runtime exactly like the
+ * navigation client. Prefetch decodes through it so the route's client chunks
+ * are pulled during the prefetch, not on click.
+ */
+type PrefetchDecoder = (response: Promise<Response>) => Promise<RscPayload>;
+
+let decoder: PrefetchDecoder | null = null;
+
+/**
+ * Hard ceiling for ANY prefetch fetch (hover/direct AND queue-driven). A server
+ * that stalls leaves the fetch pending forever — its `.finally()` never runs,
+ * `clearPrefetchInflight` never fires, and `hasPrefetch(key)` stays true,
+ * permanently deduping every future prefetch of that URL. The hover path passes
+ * no signal; the queue passes its own AbortController signal that only aborts on
+ * navigation, never on a stall — so the timeout is layered on BOTH (combined
+ * with any caller signal via AbortSignal.any) and aborts the stalled fetch so it
+ * settles (rejects) and the inflight key is always released. Generous so a
+ * slow-but-live response is never cut short.
+ */
+const PREFETCH_FETCH_TIMEOUT_MS = 30_000;
+
+/**
+ * Wire the RSC decoder used to eagerly decode prefetched responses. Called
+ * once from initBrowserApp with the same createFromFetch the navigation client
+ * uses. Until set, prefetch warming is inert (prefetches are skipped) — the
+ * browser app always sets it before any Link can fire.
+ */
+export function setPrefetchDecoder(fn: PrefetchDecoder): void {
+  decoder = fn;
+}
+
+/**
+ * Build the respawn closure for a cleanly-completed prefetch entry. Each call
+ * tees the reserve byte branch: one side feeds a fresh decode — a fresh handle
+ * stream and fresh serialized-stream instances, which no cloning of the
+ * revived payload graph could produce — and the other becomes the next
+ * reserve, so the replacement entry can respawn again. `streamComplete`
+ * resolves immediately and `complete` starts true: the buffered bytes are a
+ * finished stream by construction. The chunk imports the decode triggers are
+ * already in the module cache from the original eager decode, so a respawn
+ * costs ~ms with no network.
+ */
+function makeRespawn(
+  storageKey: string,
+  reserve: ReadableStream<Uint8Array>,
+  scope: "source" | "wildcard",
+): () => DecodedPrefetch {
+  return () => {
+    const [body, nextReserve] = reserve.tee();
+    // decoder is non-null here: respawn is only armed after a successful
+    // eager decode, which requires the decoder to have been set.
+    const payload = decoder!(Promise.resolve(new Response(body)));
+    payload.catch(() => {});
+    const entry: DecodedPrefetch = {
+      payload,
+      streamComplete: Promise.resolve(),
+      scope,
+      complete: true,
+      dispose: () => {
+        // Rejects (caught) instead of throwing if the branch is already
+        // locked by a later respawn — cache eviction never races adoption on
+        // the same entry object, so this is belt-and-braces.
+        nextReserve.cancel().catch(() => {});
+      },
+    };
+    entry.respawn = makeRespawn(storageKey, nextReserve, scope);
+    // Parity with the original path: a rejected decode must not stay
+    // consumable. Clean bytes should never fail to decode, but if they do,
+    // evict (identity-guarded) so navigation refetches instead.
+    payload.catch(() => removePrefetch(storageKey, entry));
+    return entry;
+  };
+}
 
 /**
  * Check if a URL resolves to the current page (same pathname + search).
@@ -78,71 +165,240 @@ function buildPrefetchUrl(
 }
 
 /**
- * Core prefetch fetch logic. Fetches the response, tees the body, and stores
- * one branch in the in-memory cache. The returned Promise resolves to the
- * sibling navigation branch (or null on failure) so navigation can safely
- * reuse an in-flight prefetch via consumeInflightPrefetch().
+ * Core prefetch fetch logic. Fetches the response, eagerly decodes it, and
+ * stores the decoded payload in the in-memory cache. The returned Promise
+ * resolves to the decoded entry (or null on failure / control header) so
+ * navigation can safely reuse an in-flight prefetch via
+ * consumeInflightPrefetch().
+ *
+ * Eager decode is the warming step: createFromFetch parses the Flight stream,
+ * which resolves the route's client references and imports its JS chunks. The
+ * stored payload is reused as-is by navigation, so the click loads no new code.
+ *
+ * Control headers are NOT acted on here. A speculative prefetch must never
+ * reload the page or throw a redirect — if the response carries X-RSC-Reload
+ * or X-RSC-Redirect, we drop it (resolve null) and let the real navigation
+ * re-fetch and honor it.
  *
  * Inflight + storage key selection:
  *
  * - `forceSourceScope` (Link opted in with `prefetchKey=":source"`): single
- *   inflight registration under `sourceKey`; response stored under
- *   `sourceKey`. No wildcard leak is possible.
+ *   inflight registration under `sourceKey`; entry stored under `sourceKey`.
+ *   No wildcard leak is possible.
  *
  * - Otherwise: dual inflight registration under both `wildcardKey` and
  *   `sourceKey` so same-source navigations adopt directly via their own
  *   source key. Storage key is chosen at response time from the
  *   `X-RSC-Prefetch-Scope` header — `"source"` → `sourceKey` (intercept
- *   modals etc.), anything else → `wildcardKey`. Cross-source navigations
- *   that adopted via `wildcardKey` must bail out in `navigation-client.ts`
- *   if the adopted response turns out to be source-scoped.
+ *   modals etc.), anything else → `wildcardKey`. The entry records its scope
+ *   so cross-source navigations that adopted via `wildcardKey` can bail out
+ *   in `navigation-client.ts` when the adopted entry turns out source-scoped.
  */
 function executePrefetchFetch(
   wildcardKey: string,
   sourceKey: string,
   fetchUrl: string,
   forceSourceScope: boolean,
+  /** Rango state captured once by the caller (keys + header share one read). */
+  rangoState: string,
+  expectedRouterId?: string,
   signal?: AbortSignal,
-): Promise<Response | null> {
+): Promise<DecodedPrefetch | null> {
   const gen = currentGeneration();
   const inflightKeys = forceSourceScope
     ? [sourceKey]
     : [wildcardKey, sourceKey];
   for (const k of inflightKeys) markPrefetchInflight(k);
 
-  const promise: Promise<Response | null> = fetch(fetchUrl, {
+  // Always layer a stall timeout. It covers BOTH "no response ever arrives"
+  // (strands the inflight key) AND "the body stalls after headers" (leaves a
+  // published entry whose payload/streamComplete never settle, that future
+  // prefetches dedupe against and navigation awaits forever). Applies to the
+  // hover/direct path (no caller signal) and the queue-driven path (whose caller
+  // signal only aborts on navigation, never on a stall). On fire it aborts the
+  // fetch/stream and evicts the published entry if one exists; it is NOT cleared
+  // when headers arrive (see below) — it is cleared when the stream completes, or
+  // in `.finally()` for paths that publish no streaming entry.
+  let publishedKey: string | undefined;
+  let publishedEntry: DecodedPrefetch | undefined;
+  const timeoutController = new AbortController();
+  const timeoutId: ReturnType<typeof setTimeout> = setTimeout(() => {
+    timeoutController.abort();
+    // Body stalled after headers: evict the published-but-never-settling entry
+    // so future prefetches/navigation refetch. Identity-guarded (pass the exact
+    // entry) so a fresh entry republished under the same key — after this one was
+    // consumed — is NOT dropped. The abort cancels the tee (its finally resolves
+    // streamComplete) and rejects the eager decode.
+    if (publishedKey !== undefined && publishedEntry !== undefined) {
+      removePrefetch(publishedKey, publishedEntry);
+    }
+  }, PREFETCH_FETCH_TIMEOUT_MS);
+  let effectiveSignal: AbortSignal;
+  if (!signal) {
+    effectiveSignal = timeoutController.signal;
+  } else if (typeof AbortSignal.any === "function") {
+    // Combine the caller's signal (navigation-abort) with the timeout so either
+    // can settle the fetch.
+    effectiveSignal = AbortSignal.any([signal, timeoutController.signal]);
+  } else {
+    // Legacy runtime without AbortSignal.any: forward the caller's abort onto the
+    // timeout controller so a single signal carries both reasons.
+    effectiveSignal = timeoutController.signal;
+    if (signal.aborted) timeoutController.abort();
+    else
+      signal.addEventListener("abort", () => timeoutController.abort(), {
+        once: true,
+      });
+  }
+
+  const promise: Promise<DecodedPrefetch | null> = fetch(fetchUrl, {
     priority: "low" as RequestPriority,
-    signal,
+    // During an action's flight the state is not rotated, so the old
+    // X-Rango-State still matches the Vary-keyed HTTP-cache entry; bypass it so
+    // a prefetch fetches fresh rather than warming the map with stale bytes (the
+    // fence's HTTP-cache-bypass requirement applies to prefetch as well as
+    // navigation fetches).
+    ...(isActionFenceActive() && { cache: "no-store" as RequestCache }),
+    signal: effectiveSignal,
     headers: {
-      "X-Rango-State": getRangoState(),
+      "X-Rango-State": rangoState,
       "X-RSC-Router-Client-Path": window.location.href,
       "X-Rango-Prefetch": "1",
+      ...(isFragmentPassthroughEnabled() && {
+        [SEGMENT_FRAGMENT_CAPABILITY_HEADER]: "1",
+      }),
     },
   })
     .then((response) => {
-      if (!response.ok) return null;
-      // Don't buffer with arrayBuffer() — that blocks until the entire
-      // body downloads, defeating streaming for slow loaders.
-      // Tee the body: one branch for navigation, one for cache storage.
-      const [navStream, cacheStream] = response.body!.tee();
-      const responseInit = {
-        headers: response.headers,
-        status: response.status,
-        statusText: response.statusText,
-      };
-      let storageKey: string;
-      if (forceSourceScope) {
-        storageKey = sourceKey;
-      } else {
-        const scope = response.headers.get("x-rsc-prefetch-scope");
-        storageKey = scope === "source" ? sourceKey : wildcardKey;
+      if (!response.ok || !decoder) return null;
+      // Control headers mean this response is stale (reload) or redirecting.
+      // Don't warm it — drop so navigation re-fetches and acts on the header.
+      if (
+        response.headers.has("X-RSC-Reload") ||
+        response.headers.has("X-RSC-Redirect")
+      ) {
+        return null;
+      }
+      // Integrity check: never warm (or decode/import the chunks of) a foreign
+      // app's payload. A speculative prefetch must never reload — just drop it;
+      // navigation re-fetches and the server steers it.
+      if (isForeignRouterId(response, expectedRouterId)) {
+        return null;
       }
-      storePrefetch(storageKey, new Response(cacheStream, responseInit), gen);
-      return new Response(navStream, responseInit);
+
+      const scope: "source" | "wildcard" =
+        forceSourceScope ||
+        response.headers.get("x-rsc-prefetch-scope") === "source"
+          ? "source"
+          : "wildcard";
+      const storageKey = scope === "source" ? sourceKey : wildcardKey;
+
+      // Track stream completion off a tee so navigation's scroll/revalidation
+      // gating matches the fresh-fetch path; decode the other branch. The
+      // completion callback reports whether the stream ended on a clean EOF
+      // (true) or was aborted/errored (false) — only a clean end can mark the
+      // entry complete (see below).
+      let resolveStreamComplete!: () => void;
+      let endedCleanly = false;
+      const streamComplete = new Promise<void>((resolve) => {
+        resolveStreamComplete = resolve;
+      });
+      const tracked = teeWithCompletion(
+        response,
+        (clean) => {
+          endedCleanly = clean;
+          resolveStreamComplete();
+        },
+        effectiveSignal,
+        // Speculative prefetch: a never-consumed/aborted stream error is benign.
+        true,
+      );
+
+      // Split the decode branch: one side feeds the eager decoder (unchanged —
+      // client chunks still import at prefetch time), the other stays unread as
+      // a reserve of the raw Flight bytes. A decoded payload is single-render
+      // (its handle stream drains during commit), so adoption would otherwise
+      // spend the entry; the reserve lets a cleanly-completed entry respawn a
+      // fresh decode per adoption instead (see makeRespawn).
+      let decodeSource: Response = tracked;
+      let reserve: ReadableStream<Uint8Array> | undefined;
+      if (tracked.body) {
+        const [decodeBody, reserveBody] = tracked.body.tee();
+        decodeSource = new Response(decodeBody, { headers: tracked.headers });
+        reserve = reserveBody;
+      }
+
+      // Eager decode: parsing the Flight stream imports the route's client
+      // chunks now, not on click.
+      const payload = decoder(Promise.resolve(decodeSource));
+      // Mark handled so an unconsumed prefetch decode error stays quiet; the
+      // error is still surfaced to navigation if it consumes the entry.
+      payload.catch(() => {});
+
+      const entry: DecodedPrefetch = {
+        payload,
+        streamComplete,
+        scope,
+        complete: false,
+        ...(reserve && {
+          dispose: () => {
+            reserve.cancel().catch(() => {});
+          },
+        }),
+      };
+      storePrefetch(storageKey, entry, gen);
+      // The stall timeout now owns the body stream: arm eviction (publishedKey)
+      // and clear the timer once the stream completes. The tee's finally resolves
+      // streamComplete on normal completion AND on abort, so a healthy body pays
+      // no lingering timer while a stalled one is evicted when the timer fires.
+      publishedKey = storageKey;
+      publishedEntry = entry;
+      // Evict a broken prefetch IMMEDIATELY on the earliest failure signal — do not
+      // wait for both branches to settle. A decode that rejects while the tracking
+      // stream is still draining (or hung) would otherwise leave the rejected payload
+      // consumable (navigation reads entry.payload regardless of `complete`) until EOF
+      // or the stall timeout. removePrefetch is identity-guarded, so a fresh entry
+      // republished under the same key is never dropped, and a double call is a no-op.
+      payload.catch(() => removePrefetch(storageKey, entry));
+      streamComplete.then(() => {
+        if (!endedCleanly) removePrefetch(storageKey, entry);
+      });
+      // Mark complete ONLY on a fully-healthy prefetch (decode resolved AND
+      // clean EOF) — and only then arm respawn: a truncated or failed stream's
+      // reserve would replay broken bytes, so it stays one-shot (and its
+      // buffered reserve is released via the removePrefetch dispose above).
+      Promise.allSettled([payload, streamComplete]).then(([decode]) => {
+        if (decode.status === "fulfilled" && endedCleanly) {
+          entry.complete = true;
+          if (reserve) {
+            entry.respawn = makeRespawn(storageKey, reserve, scope);
+            // Refill after an early adoption. A click that lands before this
+            // point adopts the entry with respawn unarmed and leaves the slot
+            // empty — via either path: pre-headers inflight adoption makes
+            // storePrefetch skip publication (adoptedKeys), and a mid-stream
+            // cache adoption deletes the incomplete entry. Now that the bytes
+            // proved themselves complete, publish a respawned sibling so the
+            // revisit is warm. Guards: hasPrefetch skips when the slot is
+            // live again (our own un-adopted entry, a fresh entry, or a new
+            // in-flight prefetch), and storePrefetch's generation check drops
+            // the sibling if the cache was invalidated since the fetch began.
+            if (!hasPrefetch(storageKey)) {
+              storePrefetch(storageKey, entry.respawn(), gen);
+            }
+          }
+        }
+        clearTimeout(timeoutId);
+      });
+      return entry;
     })
     .catch(() => null)
     .finally(() => {
       clearPrefetchInflight(inflightKeys[0]!);
+      // Clear the stall timer here ONLY for paths that published no streaming
+      // entry (null return / fetch error / abort): the operation is fully done.
+      // When an entry WAS published, the timer stays armed to bound the body
+      // stream and is cleared on streamComplete (above) or on fire (eviction).
+      if (publishedKey === undefined) clearTimeout(timeoutId);
     });
 
   setInflightPromiseWithAliases(inflightKeys, promise);
@@ -203,26 +459,32 @@ export function prefetchDirect(
   const wildcardKey = buildPrefetchKey(rangoState, targetUrl);
   const sourceKey = buildSourceKey(rangoState, sourceHref, targetUrl);
   if (hasPrefetchHit(forceSourceScope, wildcardKey, sourceKey)) {
-    debugLog("[prefetch] direct dedup (key already exists)", {
+    if (IS_BROWSER_DEBUG) {
+      debugLog("[prefetch] direct dedup (key already exists)", {
+        url,
+        wildcardKey,
+        sourceKey,
+        forceSourceScope,
+      });
+    }
+    return;
+  }
+  if (IS_BROWSER_DEBUG) {
+    debugLog("[prefetch] direct fetch", {
       url,
       wildcardKey,
       sourceKey,
+      source: sourceHref,
       forceSourceScope,
     });
-    return;
   }
-  debugLog("[prefetch] direct fetch", {
-    url,
-    wildcardKey,
-    sourceKey,
-    source: sourceHref,
-    forceSourceScope,
-  });
   executePrefetchFetch(
     wildcardKey,
     sourceKey,
     targetUrl.toString(),
     forceSourceScope,
+    rangoState,
+    routerId,
   );
 }
 
@@ -252,12 +514,14 @@ export function prefetchQueued(
   const sourceKey = buildSourceKey(rangoState, sourceHref, targetUrl);
   const queueKey = forceSourceScope ? sourceKey : wildcardKey;
   if (hasPrefetchHit(forceSourceScope, wildcardKey, sourceKey)) {
-    debugLog("[prefetch] queued dedup (key already exists)", {
-      url,
-      wildcardKey,
-      sourceKey,
-      forceSourceScope,
-    });
+    if (IS_BROWSER_DEBUG) {
+      debugLog("[prefetch] queued dedup (key already exists)", {
+        url,
+        wildcardKey,
+        sourceKey,
+        forceSourceScope,
+      });
+    }
     return queueKey;
   }
   const fetchUrlStr = targetUrl.toString();
@@ -275,6 +539,8 @@ export function prefetchQueued(
       sourceKey,
       fetchUrlStr,
       forceSourceScope,
+      rangoState,
+      routerId,
       signal,
     ).then(() => {});
   });

package/src/browser/prefetch/invalidation.ts

@@ -0,0 +1,30 @@
+import { notifyListeners } from "../notify-listeners.js";
+
+type PrefetchCacheInvalidationListener = () => void;
+
+const listeners = new Map<symbol, PrefetchCacheInvalidationListener>();
+
+/** Subscribe to completed local prefetch-cache invalidations. */
+export function subscribeToPrefetchCacheInvalidation(
+  listener: PrefetchCacheInvalidationListener,
+): () => void {
+  const subscription = Symbol();
+  listeners.set(subscription, listener);
+
+  return () => listeners.delete(subscription);
+}
+
+/** Notify the registrations that existed when the cache was invalidated. */
+export function notifyPrefetchCacheInvalidated(): void {
+  const registrations = [...listeners];
+  // Finish the current broadcast/action finalizer before re-arming work. A
+  // synchronous callback could throw before cross-tab invalidation is sent or
+  // prefetch while the action fence is still raised.
+  queueMicrotask(() => {
+    notifyListeners(
+      registrations,
+      ([, listener]) => listener(),
+      ([subscription, listener]) => listeners.get(subscription) === listener,
+    );
+  });
+}

package/src/browser/prefetch/loader.ts

@@ -0,0 +1,111 @@
+import type { RscPayload } from "../types.js";
+import type { EventController } from "../event-controller.js";
+
+type PrefetchDecoder = (response: Promise<Response>) => Promise<RscPayload>;
+
+type PrefetchRuntime = typeof import("./runtime.js");
+
+let runtime: PrefetchRuntime | null = null;
+let runtimePromise: Promise<PrefetchRuntime> | null = null;
+let decoder: PrefetchDecoder | null = null;
+let concurrency: number | undefined;
+let requestGeneration = 0;
+
+function loadRuntime(): Promise<PrefetchRuntime> {
+  if (runtime) return Promise.resolve(runtime);
+  if (!runtimePromise) {
+    runtimePromise = import("./runtime.js").then(
+      (loaded) => {
+        runtime = loaded;
+        if (decoder) loaded.setPrefetchDecoder(decoder);
+        if (concurrency !== undefined) {
+          loaded.setPrefetchConcurrency(concurrency);
+        }
+        return loaded;
+      },
+      (error: unknown) => {
+        runtimePromise = null;
+        throw error;
+      },
+    );
+  }
+  return runtimePromise;
+}
+
+function withRuntime(run: (loaded: PrefetchRuntime) => void): void {
+  if (runtime) {
+    run(runtime);
+    return;
+  }
+  const generation = requestGeneration;
+  void loadRuntime()
+    .then((loaded) => {
+      if (generation === requestGeneration) run(loaded);
+    })
+    .catch(() => {});
+}
+
+export function setPrefetchDecoder(fn: PrefetchDecoder): void {
+  decoder = fn;
+  runtime?.setPrefetchDecoder(fn);
+}
+
+export function setPrefetchConcurrency(value: number): void {
+  concurrency = value;
+  runtime?.setPrefetchConcurrency(value);
+}
+
+export function prefetchDirect(
+  url: string,
+  segmentIds: string[],
+  version?: string,
+  routerId?: string,
+  prefetchKey?: ":source",
+): void {
+  withRuntime((loaded) =>
+    loaded.prefetchDirect(url, segmentIds, version, routerId, prefetchKey),
+  );
+}
+
+export function prefetchQueued(
+  url: string,
+  segmentIds: string[],
+  version?: string,
+  routerId?: string,
+  prefetchKey?: ":source",
+): void {
+  withRuntime((loaded) =>
+    loaded.prefetchQueued(url, segmentIds, version, routerId, prefetchKey),
+  );
+}
+
+/** Run speculative work only when no navigation or stream is active. */
+export function schedulePrefetchWhenRouterIdle(
+  eventController: Pick<EventController, "getState" | "subscribe">,
+  callback: () => void,
+): (() => void) | undefined {
+  const state = eventController.getState();
+  if (state.state === "idle" && !state.isStreaming) {
+    callback();
+    return;
+  }
+
+  const unsubscribe = eventController.subscribe(() => {
+    const nextState = eventController.getState();
+    if (nextState.state === "idle" && !nextState.isStreaming) {
+      unsubscribe();
+      callback();
+    }
+  });
+  return unsubscribe;
+}
+
+export function cancelAllPrefetches(keepUrl?: string | null): void {
+  requestGeneration++;
+  runtime?.cancelAllPrefetches(keepUrl);
+}
+
+export function abortAllPrefetches(): void {
+  requestGeneration++;
+  runtime?.abortAllPrefetches();
+}