@rangojs/router 0.4.1 → 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/prefetch/cache.ts

@@ -77,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
@@ -369,6 +370,23 @@ export function clearPrefetchInflight(key: string): 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();

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/rsc-router.tsx

@@ -22,7 +22,7 @@ import type {
 } from "./types.js";
 import type { EventController } from "./event-controller.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
-import { expandSegmentFragments } from "../segment-fragments.js";
+import { expandPayloadFragments } from "../segment-fragments.js";
 import { initRangoState } from "./rango-state.js";
 import { registerNavigationStore } from "./navigation-store-handle.js";
 import { initPrefetchCache } from "./prefetch/cache.js";
@@ -177,9 +177,7 @@ export async function initBrowserApp(
   // renderSegments, history cache). Non-HIT payloads have no envelopes and pay
   // one field scan. The SSR resume pass ran the same expansion (ssr-root.tsx),
   // so the hydrated tree matches the server-rendered one by construction.
-  await expandSegmentFragments(initialPayload.metadata?.segments, (stream) =>
-    deps.createFromReadableStream(stream),
-  );
+  await expandPayloadFragments(initialPayload, deps.createFromReadableStream);
 
   // Extract themeConfig and initialTheme from payload if not explicitly provided
   // This allows virtual entries to work without importing the router
@@ -312,8 +310,16 @@ export async function initBrowserApp(
   }
 
   // Wire the RSC decoder so prefetches decode eagerly and warm the route's
-  // client chunks (same createFromFetch the navigation client uses).
-  setPrefetchDecoder((response) => deps.createFromFetch<RscPayload>(response));
+  // client chunks (same createFromFetch the navigation client uses). Fragment
+  // envelopes (#700) expand BEFORE the decoded payload enters the prefetch
+  // cache, so cached entries only ever resolve to expanded segments; a
+  // fragment-decode failure rejects the entry's payload and rides the cache's
+  // existing eviction path.
+  setPrefetchDecoder(async (response) => {
+    const payload = await deps.createFromFetch<RscPayload>(response);
+    await expandPayloadFragments(payload, deps.createFromReadableStream);
+    return payload;
+  });
 
   // Create a bound renderSegments that reads rootLayout through the shell ref.
   // The shell is set once at init and not swapped within a session (a cross-app

package/src/cache/cache-scope.ts

@@ -401,9 +401,10 @@ export class CacheScope {
       // flag shares fate with the key: a disrupted ALS already missed the
       // seeded record and degraded to the full tail.
       let segments: ResolvedSegment[];
+      const ambientContext = _getRequestContext();
       try {
         const codec = await import("./segment-codec.js");
-        segments = _getRequestContext()?._shellFragmentPayload
+        segments = ambientContext?._shellFragmentPayload
           ? await codec.fragmentSegments(cached.segments)
           : await codec.deserializeSegments(cached.segments);
       } catch (error) {
@@ -417,6 +418,9 @@ export class CacheScope {
           .catch((e) =>
             reportCacheError(e, "cache-delete", `[CacheScope] ${key}: evict`),
           );
+        if (this.isShellImplicitDocScope) {
+          ambientContext?._shellImplicitCache?.onCorrupt?.();
+        }
         return { status: "miss" };
       }