@rangojs/router 0.4.1 → 0.4.3

package/dist/types/server/request-context.d.ts

@@ -226,6 +226,12 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
         keyPrefix?: "doc";
         /** @internal Called only after the implicit cache hit decodes successfully. */
         onHit?: () => void;
+        /**
+         * @internal Called when the seeded document record fails server-side
+         * deserialization. Partial replay uses it to replace the enclosing shell
+         * snapshot after serving the fresh fallback.
+         */
+        onCorrupt?: () => void;
         /**
          * @internal The resolved key of the canonical document segment record.
          * Written during a CAPTURE render by CacheScope.cacheRoute when a
@@ -256,15 +262,22 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
         onExplicitBypass?: () => void;
     };
     /**
-     * @internal Shell-HIT tail marker: cache/prerender-store hits during THIS
-     * render emit stored segment fragments VERBATIM into the payload
+     * @internal Fragment-passthrough marker: cache/prerender-store hits during
+     * THIS render emit stored segment fragments VERBATIM into the payload
      * (segment-codec fragmentSegments) instead of deserialize -> re-serialize
-     * per request; the payload consumers (SSR resume + browser hydration)
-     * expand them (segment-fragments.ts, issue #700). Own property of
-     * serveShellHit's derived tail context ONLY — it must never be visible to a
-     * capture render: the capture SSR-prerenders the payload AND serializes
-     * segments into records (cacheRoute), and an envelope reaching
-     * serializeSegments would store a double-encoded fragment.
+     * per request; the payload consumers (SSR resume, browser hydration, and
+     * the client partial-navigation decode chokepoints) expand them
+     * (segment-fragments.ts, issue #700). Partial requests arm only after the
+     * browser advertises `X-Rango-Fragment-Passthrough: 1`; a decode failure
+     * retries without it so CacheScope can evict the bad record. Two arming sites,
+     * both scoped to a
+     * render/match window: serveShellHit's derived tail context (document
+     * HIT), and matchPartialWithPprReplay's mutate-restore around the partial
+     * match (matchPartialForReplay). It must never be visible to a capture
+     * render: the capture SSR-prerenders the payload AND serializes segments
+     * into records (cacheRoute), and an envelope reaching serializeSegments
+     * would store a double-encoded fragment — deriveShellCaptureContext resets
+     * it as an own property for exactly that reason.
      */
     _shellFragmentPayload?: boolean;
     /**
@@ -551,6 +564,12 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * to avoid a second resolveRoute call. Cleared on HMR invalidation.
      */
     _classifiedRoute?: import("../router/route-snapshot.js").RouteSnapshot;
+    /**
+     * @internal Classified request mode from classifyRequest, read by the
+     * rango.response span tail (rsc/handler.ts) for the rango.response.mode
+     * attribute. Unset when middleware short-circuits before core execution.
+     */
+    _requestMode?: import("../router/request-classification.js").RequestPlan["mode"];
     /**
      * @internal Coarse route-level cache signal for the X-Rango-Cache debug
      * header. Populated by match/matchPartial only when the debug cache signal
@@ -566,7 +585,7 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
  * This is the type exported to library consumers. Internal code should
  * use the full RequestContext interface directly.
  */
-export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhen" | "_pprTransitionDecisions" | "_pprReplayPostMatchReason" | "_cacheStore" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureHandleLiveness" | "_shellCaptureLoaderHandleValues" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_locationState" | "_routeName" | "_prevRouteKey" | "_gateCurrentUrl" | "_gateCurrentParams" | "_gateActionId" | "_gateActionUrl" | "_gateActionResult" | "_gateFormData" | "_inActionRevalidation" | "_reportedErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_variables" | "_classifiedRoute" | "_cacheSignal" | "_dynamic" | "res">;
+export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhen" | "_pprTransitionDecisions" | "_pprReplayPostMatchReason" | "_cacheStore" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureHandleLiveness" | "_shellCaptureLoaderHandleValues" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_locationState" | "_routeName" | "_prevRouteKey" | "_gateCurrentUrl" | "_gateCurrentParams" | "_gateActionId" | "_gateActionUrl" | "_gateActionResult" | "_gateFormData" | "_inActionRevalidation" | "_reportedErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
 /**
  * Marker for a waitUntil-scheduled fn whose task promise must NOT enter
  * _pendingBackgroundTasks. Used by the PPR shell capture for its own task:

package/dist/types/vercel/tracing.d.ts

@@ -1,12 +1,13 @@
 /**
  * Vercel OpenTelemetry tracing integration.
  *
- * Bridges the router's performance phases (request, middleware, action,
- * loaders, handler, render, ssr) onto OpenTelemetry spans so they show up in
- * Vercel's trace waterfall next to the platform's automatic spans, with correct
- * nesting. Vercel exposes tracing through OpenTelemetry (not a native import-free
- * API like Cloudflare), so this is a thin convenience over `createOTelTracing`:
- * it reads the global OTel tracer that `@vercel/otel`'s `registerOTel()` installs.
+ * Bridges the router's observable phases (request, middleware, action, loaders,
+ * handler, render, ssr, response, background) onto OpenTelemetry spans so they
+ * show up in Vercel's trace waterfall next to the platform's automatic spans,
+ * with correct nesting. Vercel exposes tracing through OpenTelemetry (not a
+ * native import-free API like Cloudflare), so this is a thin convenience over
+ * `createOTelTracing`: it reads the global OTel tracer that `@vercel/otel`'s
+ * `registerOTel()` installs.
  *
  * Usage (vercel preset). A Rango/Vite app does NOT auto-load `instrumentation.ts`
  * the way Next.js does, so export the tracing config from there and import it —
@@ -59,8 +60,8 @@ export interface VercelTracingOptions extends TracingToggleOptions {
 /**
  * Create the tracing config for a Vercel router. Pass the result to
  * `createRouter({ tracing })`. Spans are emitted for the request, middleware,
- * action, loaders, handler, render, and ssr phases; pass `spans` to turn
- * individual phases off.
+ * action, loaders, handler, render, ssr, response, and background phases; pass
+ * `spans` to turn individual phases off.
  *
  * @see createOTelTracing (`@rangojs/router`) for the underlying adapter on any
  *   platform with an OpenTelemetry SDK.

package/dist/vite/index.js

@@ -2530,7 +2530,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.4.1",
+  version: "0.4.3",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/cloudflare/SKILL.md

@@ -129,8 +129,10 @@ export const router = createRouter<AppBindings>({
 });
 ```
 
-KV is required for durable PPR shells. `CFCacheStore` without `kv` can still
-cache segment/response entries in the Cache API, but its shell family is inert.
+PPR shells use Cache API as the per-colo L1 and KV as the durable cross-colo
+L2; a KV hit promotes the coupled shell envelope back into L1. KV remains
+required for this family. `CFCacheStore` without `kv` can still cache
+segment/response entries in Cache API, but its shell family is inert.
 
 ## Commands
 

package/skills/observability/SKILL.md

@@ -145,10 +145,39 @@ const router = createRouter({ document: Document, urls: urlpatterns, tracing });
 These factories return a `RouterTracingConfig` for the same `tracing` slot;
 `telemetry` stays independent (events only, no phase spans). Phase spans:
 `rango.request`, `rango.middleware`, `rango.action`, `rango.loader`,
-`rango.render`, `rango.ssr` — the same phases the `debugPerformance` timeline
-shows, co-emitted from one site. Off-platform (no Cloudflare tracing destination
-/ no OTel SDK) every span call is a transparent pass-through, so the request
-behaves as if tracing were off.
+`rango.handler`, `rango.render`, `rango.ssr`, `rango.response`,
+`rango.background`. All share the `PHASES` registry and `observePhase`
+execution boundary with `debugPerformance`; phases with `metric: false` either
+use finer-grained perf rows or, for `response` and `background`, remain
+span-only. Off-platform (no Cloudflare tracing destination / no OTel SDK) every
+span call is a transparent pass-through, so the request behaves as if tracing
+were off.
+
+`rango.response` is the explicit handoff marker: at most one per traced
+request, a direct child of `rango.request`, wrapping only response finalization
+(redirect interception/guarding, `Server-Timing` mutation, final response
+selection) and ending immediately before the handler returns the response to
+the host. It is handoff-bound, never drain-bound — it never reads or awaits
+`response.body`. Attributes: `http.response.status_code`,
+`rango.response.mode` (classified request mode, or `middleware-short-circuit`),
+`rango.response.body_kind` (`stream`/`empty`/`websocket`). For request modes
+that render nothing (fetchable `_rsc_loader`, response routes, middleware
+short-circuits) it shows the trace is complete rather than truncated — those
+requests legitimately have no `rango.render`/`rango.ssr`/`rango.handler` spans.
+On deployed Workers it may read 0 ms (frozen non-I/O timers); its position and
+attributes are the value. Disable per-response billing overhead at volume with
+`spans: { response: false }`.
+
+`rango.background` wraps detached waitUntil work — PPR shell captures and SWR
+background revalidations — that runs after the foreground spans ended. Without
+it, a capture or revalidation shows up as an unexplained wave of orphan
+KV/fetch spans minutes into a trace. `rango.background.kind` names the lane
+(`shell-capture` / `document-revalidation` / `loader-revalidation` /
+`use-cache-revalidation`); the shell-capture lane also carries
+`rango.shell_key`, `rango.background.outcome`, and
+`rango.background.queue_wait_ms` (a capture parked behind the per-isolate
+capture queue reads as span duration, not dead air). Toggle with
+`spans: { background: false }`.
 
 Custom sinks implement `emit(event)`:
 

package/skills/ppr/SKILL.md

@@ -37,9 +37,9 @@ PPR is a DOCUMENT-level property declared on the page route via the `ppr` path
 option. Serving is **integral to the router** — there is nothing to mount. The
 only prerequisite is an app-level `createRouter({ cache })` store that
 implements the shell family (`getShell`/`putShell`): `MemorySegmentCacheStore`
-(dev/tests), `CFCacheStore` (Cloudflare KV), or `VercelCacheStore` (runtime
-cache). A ppr route on a store without the family stays on axis 1 with a
-once-per-key warning.
+(dev/tests), `CFCacheStore` (Cache API L1 + KV L2), or `VercelCacheStore`
+(runtime cache). A ppr route on a store without the family stays on axis 1 with
+a once-per-key warning.
 
 ```typescript
 import { createRouter, urls } from "@rangojs/router";
@@ -258,11 +258,21 @@ Partial responses expose the actual decision as `x-rango-ppr-replay`:
 `HIT; freshness=fresh|stale` or `BYPASS; reason=<bounded-token>`. With
 performance metrics enabled, the same decision appears as
 `ppr-navigation-replay` in `Server-Timing`. `HIT` means matching consumed the
-seeded segment record after it decoded successfully, not merely that a snapshot
-existed. An explicit `cache()` scope that supplies the match cannot produce a
+seeded segment record, not merely that a snapshot existed. Fragment-capable
+clients decode its stored ReactNode fields after the response arrives; if that
+decode fails, the client retries once through the server decode-and-evict path
+and disables further passthrough for that browser document. The retry replaces
+the fragment-capable response-cache slot, and a corrupt seeded snapshot is
+recaptured at the key that supplied it. An explicit `cache()` scope that supplies
+the match cannot produce a
 false HIT — it reports `explicit-cache-hit`. There is still no Flight resume
 API; this is segment replay followed by normal Flight streaming, not reuse of
-the HTML `prelude`/`postponed` bytes.
+the HTML `prelude`/`postponed` bytes. Replayed segments do ride the partial
+payload as verbatim `__rangoFragment` envelopes (#700 fragment splice — the
+stored per-segment Flight strings are string-copied instead of
+deserialize→re-serialize per request); the client expands them at its
+navigation/prefetch decode chokepoints before anything renders, so they are
+consumer-invisible.
 
 The bounded bypass tokens, grouped by when they are decided:
 
@@ -344,9 +354,10 @@ curl -s -D - -o /dev/null https://app.example.com/products/1 | grep -i x-rango-s
 - A ppr-declared route that CANNOT be honored (missing shell store family,
   per-request nonce) serves plain axis 1 with NO header and warns once per
   key — no header + a declared `ppr` means look for that warning.
-- On Cloudflare, `CFCacheStore` WITHOUT a KV namespace has an inert shell
-  family (the shell tier is KV-only): every ppr route stays `MISS` forever.
-  The store warns once per isolate — bind KV
+- On Cloudflare, `CFCacheStore` reads PPR shells from the per-colo Cache API,
+  falls through to KV on a miss, and promotes the KV hit back into that colo.
+  WITHOUT a KV namespace its shell family remains inert: every ppr route stays
+  `MISS` forever. The store warns once per isolate — bind KV
   (`new CFCacheStore({ ctx, kv: env.CACHE_KV })`) or use another store.
 - Structured capture diagnostics: `createRouter({ debugShellCapture: true })`
   logs one line per capture attempt/skip (outcome, durations, prelude and
@@ -356,6 +367,11 @@ curl -s -D - -o /dev/null https://app.example.com/products/1 | grep -i x-rango-s
   later request. In dev, with `debugPerformance` on, the
   last capture outcome for a key also rides the next document GET's
   `Server-Timing` as `ppr-capture;desc="…"`.
+- For deployed Cloudflare tier diagnostics, build with
+  `INTERNAL_RANGO_DEBUG=1` and run `wrangler tail`. `[CFCacheStore][shell]`
+  JSON events distinguish L1 hit/miss, KV fallback/promotion, tier writes, and
+  marker rejection, with `cf-ray`/colo and read timings. The flag is baked at
+  build time; setting only a Worker runtime variable is too late.
 
 ### Unit / integration testing (public primitives)
 

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

@@ -10,12 +10,12 @@
  * 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
@@ -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
@@ -140,7 +141,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,
@@ -149,12 +152,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;
 }
 
 /**
@@ -170,7 +176,14 @@ export function buildSourceKey(
   sourceHref: string,
   targetUrl: URL,
 ): string {
-  return buildPrefetchKey(rangoState + "\0" + sourceHref, targetUrl);
+  return (
+    rangoState +
+    "\0" +
+    sourceHref +
+    "\0" +
+    targetUrl.pathname +
+    targetUrl.search
+  );
 }
 
 /**
@@ -369,6 +382,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