@rangojs/router 0.4.0 → 0.4.2

package/src/browser/navigation-client.ts

@@ -14,6 +14,12 @@ import {
 } from "./logging.js";
 import { getRangoState } from "./rango-state.js";
 import { isActionFenceActive } from "./action-fence.js";
+import {
+  expandPayloadFragments,
+  SEGMENT_FRAGMENT_CAPABILITY_HEADER,
+  SEGMENT_FRAGMENT_RECOVERY_HEADER,
+  SegmentFragmentDecodeError,
+} from "../segment-fragments.js";
 import {
   extractRscHeaderUrl,
   emptyResponse,
@@ -26,6 +32,8 @@ import {
   buildSourceKey,
   consumeInflightPrefetch,
   consumePrefetch,
+  disableFragmentPassthrough,
+  isFragmentPassthroughEnabled,
   type DecodedPrefetch,
 } from "./prefetch/cache.js";
 import { cancelAllPrefetches } from "./prefetch/loader.js";
@@ -46,7 +54,10 @@ import { cancelAllPrefetches } from "./prefetch/loader.js";
  * @returns NavigationClient instance
  */
 export function createNavigationClient(
-  deps: Pick<RscBrowserDependencies, "createFromFetch">,
+  deps: Pick<
+    RscBrowserDependencies,
+    "createFromFetch" | "createFromReadableStream"
+  >,
 ): NavigationClient {
   return {
     /**
@@ -150,12 +161,6 @@ export function createNavigationClient(
           if (inflightEntryPromise) hitKey = wildcardKey;
         }
       }
-      // Track when the stream completes
-      let resolveStreamComplete: () => void;
-      const streamComplete = new Promise<void>((resolve) => {
-        resolveStreamComplete = resolve;
-      });
-
       /**
        * Validate RSC control headers on any response (fresh, cached, or
        * in-flight). Handles version-mismatch reloads and server redirects.
@@ -164,6 +169,7 @@ export function createNavigationClient(
       const validateRscHeaders = (
         response: Response,
         source: string,
+        resolveStreamComplete: () => void,
       ): Response | Promise<Response> => {
         // Version mismatch — server wants a full page reload
         const reloadResult = handleReloadHeader(response, {
@@ -213,20 +219,35 @@ export function createNavigationClient(
         return response;
       };
 
-      /** Start a fresh navigation fetch (no cache / inflight hit). */
-      const doFreshFetch = (): Promise<Response> => {
+      /** Start and decode one fresh navigation fetch. */
+      const freshResult = (
+        fragmentPassthrough = isFragmentPassthroughEnabled(),
+        fragmentRecovery = false,
+      ): {
+        payload: Promise<RscPayload>;
+        streamComplete: Promise<void>;
+      } => {
+        let resolveStreamComplete!: () => void;
+        const streamComplete = new Promise<void>((resolve) => {
+          resolveStreamComplete = resolve;
+        });
+
         if (tx) {
           browserDebugLog(tx, "fetching", {
             path: `${fetchUrl.pathname}${fetchUrl.search}`,
+            fragmentPassthrough,
           });
         }
 
-        return fetch(fetchUrl, {
+        const responsePromise = fetch(fetchUrl, {
           // 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 genuine mid-action navigation fetches fresh instead of being
-          // served the stale prefetched bytes.
-          ...(isActionFenceActive() && { cache: "no-store" as RequestCache }),
+          // served the stale prefetched bytes. Fragment recovery also bypasses
+          // HTTP caches so it reaches the server's decode-and-evict path.
+          ...((isActionFenceActive() || fragmentRecovery) && {
+            cache: "no-store" as RequestCache,
+          }),
           headers: {
             "X-RSC-Router-Client-Path": previousUrl,
             // Reuse the single per-operation read (see rangoState above): the
@@ -234,6 +255,12 @@ export function createNavigationClient(
             // cookie read has side effects (external-rotation notify) we do not
             // want to fire twice per navigation.
             "X-Rango-State": rangoState,
+            ...(fragmentPassthrough && {
+              [SEGMENT_FRAGMENT_CAPABILITY_HEADER]: "1",
+            }),
+            ...(fragmentRecovery && {
+              [SEGMENT_FRAGMENT_RECOVERY_HEADER]: "1",
+            }),
             ...(tx && { "X-RSC-Router-Request-Id": tx.requestId }),
             ...(interceptSourceUrl && {
               "X-RSC-Router-Intercept-Source": interceptSourceUrl,
@@ -242,7 +269,11 @@ export function createNavigationClient(
           },
           signal,
         }).then((response) => {
-          const validated = validateRscHeaders(response, "fetch");
+          const validated = validateRscHeaders(
+            response,
+            "fetch",
+            resolveStreamComplete,
+          );
           if (validated instanceof Promise) return validated;
 
           return teeWithCompletion(
@@ -254,20 +285,12 @@ export function createNavigationClient(
             signal,
           );
         });
-      };
 
-      // A warm prefetch hit returns its eagerly-decoded payload directly: the
-      // route's chunks were imported during the prefetch, so this click runs
-      // no decode and no network. Only the fresh path runs createFromFetch and
-      // resolves the local streamComplete (via doFreshFetch's teeWithCompletion
-      // and the control-header short-circuits in validateRscHeaders).
-      const freshResult = (): {
-        payload: Promise<RscPayload>;
-        streamComplete: Promise<void>;
-      } => ({
-        payload: deps.createFromFetch<RscPayload>(doFreshFetch()),
-        streamComplete,
-      });
+        return {
+          payload: deps.createFromFetch<RscPayload>(responsePromise),
+          streamComplete,
+        };
+      };
 
       let payloadPromise: Promise<RscPayload>;
       let streamCompletePromise: Promise<void>;
@@ -332,7 +355,34 @@ export function createNavigationClient(
         // model is not flushed early (server/runtime buffering, e.g. wrangler
         // dev gzip); fast means the block, if any, is downstream in render.
         const vtDebugStart = isBrowserDebugEnabled() ? performance.now() : 0;
-        const payload = await payloadPromise;
+        let payload: RscPayload;
+        try {
+          payload = await payloadPromise;
+          // Fragment envelopes (#700): expand replay-HIT envelopes before any
+          // consumer renders — this await is the single point all three payload
+          // sources (fresh fetch, warm prefetch, adopted inflight) flow through.
+          await expandPayloadFragments(payload, deps.createFromReadableStream);
+        } catch (error) {
+          if (
+            !(error instanceof SegmentFragmentDecodeError) ||
+            signal?.aborted
+          ) {
+            throw error;
+          }
+
+          // A fragment-only failure means the outer payload was valid but one
+          // stored segment was not. Retry once without the capability header:
+          // the server then takes CacheScope's decode-and-evict path and renders
+          // fresh. Never recurse; a failed recovery remains an ordinary
+          // unprocessable navigation response.
+          if (tx) browserDebugLog(tx, "fragment decode failed, retrying");
+          disableFragmentPassthrough();
+          const recovery = freshResult(false, true);
+          streamCompletePromise = recovery.streamComplete;
+          fullyPrefetched = false;
+          payload = await recovery.payload;
+          await expandPayloadFragments(payload, deps.createFromReadableStream);
+        }
         if (isBrowserDebugEnabled()) {
           debugLog("[VT-DIAG] payloadResolved", {
             ms: Math.round(performance.now() - vtDebugStart),

package/src/browser/navigation-store.ts

@@ -8,6 +8,11 @@ import type {
   HandleData,
 } from "./types.js";
 import { clearPrefetchCache } from "./prefetch/cache.js";
+import {
+  adoptRangoState,
+  getRangoState,
+  getRangoStateCookieName,
+} from "./rango-state.js";
 
 // Maximum number of history entries to cache (URLs visited)
 const HISTORY_CACHE_SIZE = 20;
@@ -316,6 +321,8 @@ export function createNavigationStore(
         type: "invalidate",
         path: currentPath,
         segmentIds: currentSegmentIds,
+        rangoState: getRangoState(),
+        stateCookieName: getRangoStateCookieName(),
       });
     }
   }
@@ -341,7 +348,23 @@ export function createNavigationStore(
             return;
           }
 
-          markCacheAsStaleInternal();
+          const rangoState = event.data.rangoState;
+          const stateCookieName = event.data.stateCookieName;
+          if (
+            typeof rangoState === "string" &&
+            typeof stateCookieName === "string"
+          ) {
+            if (stateCookieName !== getRangoStateCookieName()) return;
+            // The sender already rotated the same-origin cookie. Adopt that
+            // value before clearing locally so tabs cannot ping-pong rotations
+            // and obsolete each other's post-invalidation prefetches.
+            const adopted = adoptRangoState(rangoState);
+            markHistoryStale();
+            clearPrefetchCache(!adopted);
+          } else {
+            // Compatibility with an already-open tab running an older sender.
+            markCacheAsStaleInternal();
+          }
 
           // Auto-refresh if enabled and callback is registered
           if (crossTabAutoRefresh && crossTabRefreshCallback) {

package/src/browser/notify-listeners.ts

@@ -0,0 +1,22 @@
+/** Notify every active listener and surface every callback failure. */
+export function notifyListeners<T>(
+  entries: Iterable<T>,
+  notify: (entry: T) => void,
+  isActive?: (entry: T) => boolean,
+  shouldContinue?: () => boolean,
+): void {
+  const errors: unknown[] = [];
+  for (const entry of entries) {
+    if (shouldContinue && !shouldContinue()) break;
+    if (isActive && !isActive(entry)) continue;
+    try {
+      notify(entry);
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+  if (errors.length === 1) throw errors[0];
+  if (errors.length > 1) {
+    throw new AggregateError(errors, "Multiple listener callbacks failed");
+  }
+}

package/src/browser/prefetch/cache.ts

@@ -40,6 +40,7 @@
  */
 
 import { abortAllPrefetches } from "./loader.js";
+import { notifyPrefetchCacheInvalidated } from "./invalidation.js";
 import { invalidateRangoState } from "../rango-state.js";
 import type { RscPayload } from "../types.js";
 
@@ -76,6 +77,7 @@ export interface DecodedPrefetch {
 }
 
 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
@@ -368,7 +370,24 @@ export function clearPrefetchInflight(key: string): void {
   });
 }
 
-export function clearPrefetchCache(): void {
+/** Whether this document may request stored segment fragment envelopes. */
+export function isFragmentPassthroughEnabled(): boolean {
+  return fragmentPassthroughEnabled;
+}
+
+/**
+ * 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 disableFragmentPassthrough(): void {
+  if (!fragmentPassthroughEnabled) return;
+  fragmentPassthroughEnabled = false;
+  clearPrefetchCache(false);
+}
+
+export function clearPrefetchCache(rotateRangoState = true): void {
   generation++;
   inflight.clear();
   inflightPromises.clear();
@@ -377,5 +396,6 @@ export function clearPrefetchCache(): void {
   cache.clear();
   earliestTimestamp = Infinity;
   abortAllPrefetches();
-  invalidateRangoState();
+  if (rotateRangoState) invalidateRangoState();
+  notifyPrefetchCacheInvalidated();
 }

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

@@ -1,11 +1,14 @@
 /**
- * Router-wide default Link prefetch strategy (client seat).
+ * 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 reads the value at render time.
+ * 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
@@ -15,11 +18,26 @@
 
 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.
@@ -28,7 +46,29 @@ export function setDefaultPrefetchStrategy(strategy: PrefetchStrategy): void {
   defaultStrategy = strategy;
 }
 
-/** Current default strategy for Links without an explicit `prefetch` prop. */
+/** 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);
+}

package/src/browser/prefetch/fetch.ts

@@ -25,6 +25,7 @@ import {
   removePrefetch,
   clearPrefetchInflight,
   currentGeneration,
+  isFragmentPassthroughEnabled,
   type DecodedPrefetch,
 } from "./cache.js";
 import { getRangoState } from "../rango-state.js";
@@ -33,6 +34,7 @@ import { enqueuePrefetch } from "./queue.js";
 import { shouldPrefetch } from "./policy.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";
 
 /**
@@ -219,6 +221,9 @@ function executePrefetchFetch(
       "X-Rango-State": rangoState,
       "X-RSC-Router-Client-Path": window.location.href,
       "X-Rango-Prefetch": "1",
+      ...(isFragmentPassthroughEnabled() && {
+        [SEGMENT_FRAGMENT_CAPABILITY_HEADER]: "1",
+      }),
     },
   })
     .then((response) => {

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

@@ -1,8 +1,5 @@
 import type { RscPayload } from "../types.js";
-import {
-  observeForPrefetch as observeElementForPrefetch,
-  unobserveForPrefetch,
-} from "./observer.js";
+import type { EventController } from "../event-controller.js";
 
 type PrefetchDecoder = (response: Promise<Response>) => Promise<RscPayload>;
 
@@ -82,15 +79,25 @@ export function prefetchQueued(
   );
 }
 
-export function observeForPrefetch(
-  element: Element,
+/** Run speculative work only when no navigation or stream is active. */
+export function schedulePrefetchWhenRouterIdle(
+  eventController: Pick<EventController, "getState" | "subscribe">,
   callback: () => void,
-): () => void {
-  if (typeof IntersectionObserver === "undefined") return () => {};
-  observeElementForPrefetch(element, callback);
-  return () => {
-    unobserveForPrefetch(element);
-  };
+): (() => 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 {

package/src/browser/prefetch/observer.ts

@@ -12,32 +12,53 @@
  * scrolls in and out repeatedly.
  */
 
+import { notifyListeners } from "../notify-listeners.js";
+
 type PrefetchCallback = () => void;
 
-const callbacks = new Map<Element, PrefetchCallback>();
+const callbacks = new Map<Element, Map<symbol, 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();
+      (entries, currentObserver) => {
+        function* intersectingCallbacks(): Generator<
+          [Map<symbol, PrefetchCallback>, symbol, PrefetchCallback]
+        > {
+          for (const entry of entries) {
+            if (entry.isIntersecting) {
+              const subscriptions = callbacks.get(entry.target);
+              if (subscriptions) {
+                currentObserver.unobserve(entry.target);
+                callbacks.delete(entry.target);
+                for (const [subscription, callback] of subscriptions) {
+                  yield [subscriptions, subscription, callback];
+                }
+              }
             }
           }
         }
+        notifyListeners(
+          intersectingCallbacks(),
+          ([, , callback]) => callback(),
+          ([subscriptions, subscription]) => subscriptions.has(subscription),
+        );
       },
       { rootMargin: "200px" },
     );
+    for (const element of callbacks.keys()) observer.observe(element);
   }
   return observer;
 }
 
+/** Reset module state between tests that replace browser observer globals. */
+export function resetPrefetchObserverForTesting(): void {
+  observer?.disconnect();
+  observer = null;
+  callbacks.clear();
+}
+
 /**
  * Observe an element for viewport intersection.
  * When the element becomes visible (within 200px margin), the callback fires
@@ -47,19 +68,26 @@ function getObserver(): IntersectionObserver {
 export function observeForPrefetch(
   element: Element,
   onVisible: PrefetchCallback,
-): void {
-  if (typeof IntersectionObserver === "undefined") return;
-  callbacks.set(element, onVisible);
-  getObserver().observe(element);
-}
+): () => void {
+  if (typeof IntersectionObserver === "undefined") return () => {};
+  const currentObserver = getObserver();
 
-/**
- * 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);
+  let subscriptions = callbacks.get(element);
+  if (!subscriptions) {
+    subscriptions = new Map();
+    callbacks.set(element, subscriptions);
   }
+
+  const subscription = Symbol();
+  subscriptions.set(subscription, onVisible);
+  if (subscriptions.size === 1) currentObserver.observe(element);
+
+  return () => {
+    const current = callbacks.get(element);
+    subscriptions.delete(subscription);
+    if (current !== subscriptions) return;
+    if (current.size > 0) return;
+    callbacks.delete(element);
+    observer?.unobserve(element);
+  };
 }

package/src/browser/rango-state.ts

@@ -52,6 +52,11 @@ export function setRangoStateObserver(
   externalRotationObserver = observer;
 }
 
+/** Return the resolved cookie name used to namespace cross-tab messages. */
+export function getRangoStateCookieName(): string {
+  return cookieName;
+}
+
 function notifyExternalRotation(value: string): void {
   externalRotationObserver?.(value);
 }
@@ -179,6 +184,22 @@ export function invalidateRangoState(): void {
   writeCookie(cookieName, mirror);
 }
 
+/** Adopt the state carried by a same-origin cache-invalidation broadcast. */
+export function adoptRangoState(value: string): boolean {
+  const incoming = decodeStateValue(value);
+  if (!incoming || incoming.version !== currentVersion) return false;
+  const current = mirror ? decodeStateValue(mirror) : null;
+  if (
+    current?.version === incoming.version &&
+    current.timestamp >= incoming.timestamp
+  ) {
+    return false;
+  }
+  mirror = value;
+  cookieBacked = false;
+  return true;
+}
+
 function cleanupLegacyStorage(): void {
   if (typeof localStorage === "undefined") return;
   try {