@rangojs/router 0.2.0 → 0.4.0

package/src/rsc/rsc-rendering.ts

@@ -68,7 +68,11 @@ import {
 import { nonce as nonceToken } from "./nonce.js";
 import { reportCacheError } from "../cache/cache-error.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
-import type { ShellCacheEntry, ShellSnapshotRecord } from "../cache/types.js";
+import type {
+  SegmentCacheStore,
+  ShellCacheEntry,
+  ShellSnapshotRecord,
+} from "../cache/types.js";
 
 type PprReplayBypassReason =
   | "method"
@@ -106,6 +110,43 @@ function describePprReplayStatus(status: PprReplayStatus): string {
     : `bypass:${status.reason}`;
 }
 
+function buildNavigationShellKey(url: URL): string {
+  return `${buildShellKey(url)}:navigation`;
+}
+
+function createShellCaptureDescriptor(
+  ctx: HandlerContext<any>,
+  key: string,
+  pprConfig: ResolvedPprConfig,
+  store: SegmentCacheStore<any>,
+  navigationOnly?: true,
+): ShellCaptureDescriptor {
+  return {
+    key,
+    buildVersion: ctx.version,
+    ttl: pprConfig.ttl,
+    swr: pprConfig.swr,
+    tags: pprConfig.tags,
+    captureTimeout: pprConfig.captureTimeout,
+    store,
+    debug: INTERNAL_RANGO_DEBUG,
+    maxSnapshotBytes: pprConfig.maxSnapshotBytes,
+    debugSink: resolveShellCaptureDebugSink(ctx.router.debugShellCapture),
+    navigationOnly,
+  };
+}
+
+function shouldHealReplayMiss(
+  reason: PprReplayBypassReason | undefined,
+): boolean {
+  return (
+    reason === undefined ||
+    reason === "invalid-version" ||
+    reason === "corrupt-entry" ||
+    reason === "stale-build-entry"
+  );
+}
+
 function resolveDevShellLookup(
   reqCtx: RequestContext<any>,
   pprConfig: ResolvedPprConfig,
@@ -194,6 +235,7 @@ async function handleRscRenderingInner<TEnv>(
   let payload: RscPayload;
   let hasInterceptSlots = false;
   let pprReplayStatus: PprReplayStatus | undefined;
+  let partialCaptureNeeded = false;
 
   // --- Axis 2: integrated PPR shell serve (docs/design/ppr-shell-resume.md) ---
   //
@@ -280,23 +322,12 @@ async function handleRscRenderingInner<TEnv>(
           ssrModule.resumeShellHTML &&
           ssrModule.captureShellHTML
         ) {
-          const descriptor: ShellCaptureDescriptor = {
+          const descriptor = createShellCaptureDescriptor(
+            ctx,
             key,
-            buildVersion: ctx.version,
-            ttl: pprConfig.ttl,
-            swr: pprConfig.swr,
-            tags: pprConfig.tags,
-            captureTimeout: pprConfig.captureTimeout,
+            pprConfig,
             store,
-            debug: INTERNAL_RANGO_DEBUG,
-            maxSnapshotBytes: pprConfig.maxSnapshotBytes,
-            // The resolver owns the whole policy: option wins, the
-            // INTERNAL_RANGO_DEBUG env flag lights the events up when no
-            // option is set, an explicit `false` stays off.
-            debugSink: resolveShellCaptureDebugSink(
-              ctx.router.debugShellCapture,
-            ),
-          };
+          );
           // One serve funnel for BOTH entry sources (runtime store hit below,
           // build-manifest hit further down): schedule the background
           // recapture when asked, then commit the composed response.
@@ -347,7 +378,11 @@ async function handleRscRenderingInner<TEnv>(
               cached ? "hit" : "miss",
             );
           }
-          if (cached && isValidShellHit(cached.entry, ctx.version)) {
+          if (
+            cached &&
+            !cached.entry.navigationOnly &&
+            isValidShellHit(cached.entry, ctx.version)
+          ) {
             if (!hasIntactShellPayload(cached.entry)) {
               // Corrupt stored payload (undecodable prelude / unparseable
               // postponed): a store-layer fault worth a diagnostic, unlike the
@@ -407,6 +442,8 @@ async function handleRscRenderingInner<TEnv>(
     );
     const result = replay.result;
     pprReplayStatus = replay.status;
+    partialCaptureNeeded =
+      "captureNeeded" in replay && replay.captureNeeded === true;
 
     if (!result) {
       // Fall back to full render
@@ -462,6 +499,7 @@ async function handleRscRenderingInner<TEnv>(
           prefetchCacheTTL: ctx.router.prefetchCacheTTL,
           prefetchCacheSize: ctx.router.prefetchCacheSize,
           prefetchConcurrency: ctx.router.prefetchConcurrency,
+          defaultPrefetch: ctx.router.defaultPrefetch,
           stateCookieName: ctx.router.resolvedStateCookieName,
         },
       };
@@ -607,6 +645,40 @@ async function handleRscRenderingInner<TEnv>(
     response.headers.set(SHELL_STATUS_HEADER, "MISS");
   }
 
+  if (
+    isPartial &&
+    partialCaptureNeeded &&
+    !reqCtx._dynamic &&
+    response.status === 200
+  ) {
+    const pprConfig = resolvePprConfig(reqCtx._classifiedRoute?.manifestEntry)!;
+    const store = reqCtx._cacheStore!;
+    scheduleShellCapture(
+      ctx,
+      request,
+      env,
+      url,
+      reqCtx,
+      async (captureRequest, captureUrl) => {
+        const [ssrModule, streamMode] = await getSSRSetup(
+          ctx,
+          captureRequest,
+          env,
+          captureUrl,
+          undefined,
+        );
+        return streamMode === "allReady" ? null : ssrModule;
+      },
+      createShellCaptureDescriptor(
+        ctx,
+        buildNavigationShellKey(url),
+        pprConfig,
+        store,
+        true,
+      ),
+    );
+  }
+
   return response;
 }
 
@@ -668,6 +740,7 @@ async function matchPartialWithPprReplay<TEnv>(
   }
 
   const key = buildShellKey(url);
+  const navigationKey = buildNavigationShellKey(url);
   let cached: Awaited<ReturnType<typeof store.getShell>> = null;
   try {
     cached = await store.getShell(key, { claimRevalidation: false });
@@ -689,6 +762,34 @@ async function matchPartialWithPprReplay<TEnv>(
     }
   }
 
+  if (
+    !snapshot &&
+    bypassReason !== "handler-live-holes" &&
+    bypassReason !== "transition-when"
+  ) {
+    let navigationCached: Awaited<ReturnType<typeof store.getShell>> = null;
+    try {
+      navigationCached = await store.getShell(navigationKey, {
+        claimRevalidation: false,
+      });
+    } catch (error) {
+      reportCacheError(error, "cache-read", "[NavigationPPR] getShell");
+      return runMatch({ outcome: "BYPASS", reason: "read-error" });
+    }
+    if (navigationCached) {
+      const decision = replayableShellSnapshot(
+        navigationCached.entry,
+        ctx.version,
+      );
+      if ("snapshot" in decision) {
+        snapshot = decision.snapshot;
+        freshness = navigationCached.shouldRevalidate ? "stale" : "fresh";
+      } else {
+        bypassReason = decision.reason;
+      }
+    }
+  }
+
   if (!snapshot) {
     // Production build manifests are local module data. In dev, resolving a
     // missing build shell would foreground-fetch /__rsc_shell and block an
@@ -710,10 +811,11 @@ async function matchPartialWithPprReplay<TEnv>(
   }
 
   if (!snapshot) {
-    return runMatch({
+    const match = await runMatch({
       outcome: "BYPASS",
       reason: bypassReason ?? "no-entry",
     });
+    return { ...match, captureNeeded: shouldHealReplayMiss(bypassReason) };
   }
 
   const previousImplicitCache = reqCtx._shellImplicitCache;

package/src/rsc/shell-capture.ts

@@ -20,7 +20,10 @@ import React from "react";
 import { bufferToBase64 } from "../cache/cf/cf-base64.js";
 import { reportCacheError } from "../cache/cache-error.js";
 import { runBackground } from "../cache/background-task.js";
-import { enqueueSerializedCapture } from "./capture-queue.js";
+import {
+  CaptureQueueFullError,
+  enqueueSerializedCapture,
+} from "./capture-queue.js";
 import { SHELL_CAPTURE_MAX_WAIT_MS } from "./shell-capture-constants.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import { observePhase, PHASES } from "../router/instrument.js";
@@ -57,6 +60,7 @@ import type { SSRModule } from "./types.js";
 import { buildFullPayload } from "./full-payload.js";
 import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
 import { renderRscFlightStage } from "./render-pipeline.js";
+import { stripInternalParams } from "../router/handler-context.js";
 
 /**
  * Task-quantized quiesce: the number of consecutive macrotask hops with zero new
@@ -344,39 +348,6 @@ function warnCaptureRefusedOnce(key: string, reason: string): void {
   );
 }
 
-/** Keys already warned about untagged bake-lane data baked into the shell. */
-const warnedUntaggedShellBakes = new Set<string>();
-
-/**
- * Warn once per shell key that a bake-lane loader baked material into the shell
- * but the capture recorded ZERO tags (no render-collected _requestTags, no
- * static ppr.tags). Such data is frozen in the shared shell until TTL and is
- * un-evictable by tag: a server action refreshes the CLIENT only (rotates Rango
- * state, busts the browser HTTP cache) and never touches the server shell store,
- * and updateTag()/revalidateTag() cannot drop data that was baked WITHOUT a tag.
- *
- * Coarse per-shell-key signal, not per-loader attribution — the tag set is
- * unioned globally at the write barrier, not tracked per loader, so we cannot
- * name the offending loader without adding attribution plumbing (deliberately
- * not done). Dev-only + once-per-key so it never spams production or fires on
- * every capture.
- */
-function warnUntaggedShellBakeOnce(key: string): void {
-  if (warnedUntaggedShellBakes.has(key)) return;
-  warnedUntaggedShellBakes.add(key);
-  console.warn(
-    `[rango] Shell capture for "${key}" baked bake-lane loader data into the ` +
-      "shell with NO cache tag. That data is frozen in the shared shell until " +
-      "TTL and cannot be tag-invalidated: a server action refresh touches the " +
-      "client only (not the server shell store), and updateTag() cannot evict " +
-      "data that was baked without a tag.\n" +
-      'Fix: tag the data (cacheTag() / "use cache" / cache({ tags })) so ' +
-      "updateTag() drops the shell, or move the volatile read under a loading() " +
-      "hole so it stays on the live lane and is never baked. See the /ppr skill " +
-      "(node_modules/@rangojs/router/skills/ppr/SKILL.md).",
-  );
-}
-
 /**
  * Default cap (serialized UTF-8 bytes) on the capture data snapshot riding
  * inside a shell entry, when the route's `ppr` option does not set
@@ -444,6 +415,7 @@ export interface ShellCaptureDebugEvent {
    *   the key (stampede guard) and scheduled nothing
    * - skip-backoff: the key is inside its refused-capture backoff window and
    *   the capture was not attempted
+   * - skip-capacity: the isolate capture queue is full; a later request may retry
    * - backoff: the key entered (or escalated) backoff after a terminal
    *   no-shell — carries the new backoff state
    */
@@ -455,6 +427,7 @@ export interface ShellCaptureDebugEvent {
     | "error"
     | "skip-in-flight"
     | "skip-backoff"
+    | "skip-capacity"
     | "backoff";
   /** Attempt number (1 = first, 2 = in-place retry). Absent on skips. */
   attempt?: number;
@@ -476,6 +449,8 @@ export interface ShellCaptureDebugEvent {
   snapshotBytes?: number;
   /** True when the snapshot exceeded maxSnapshotBytes and was dropped. */
   snapshotSkipped?: boolean;
+  /** A bake-lane loader settled into a shell that uses TTL/SWR-only invalidation. */
+  untaggedBake?: true;
   /** Outcome reported by a store that supports shell-write acknowledgements. */
   storeWrite?: "stored" | "invalidated";
   /** Consecutive failure count in the key's backoff entry, when one exists. */
@@ -518,6 +493,7 @@ export function describeShellCaptureEvent(
       `snapshot=${event.snapshotBytes}b${event.snapshotSkipped ? " (over cap, skipped)" : ""}`,
     );
   }
+  if (event.untaggedBake) parts.push("untagged-bake");
   if (event.storeWrite !== undefined) {
     parts.push(`store-write=${event.storeWrite}`);
   }
@@ -835,6 +811,8 @@ export interface ShellCaptureDescriptor {
    * {@link ShellCaptureDebugEvent} per attempt/skip.
    */
   debugSink?: (event: ShellCaptureDebugEvent) => void;
+  /** Store the snapshot for navigation replay, never the captured HTML prelude. */
+  navigationOnly?: true;
 }
 
 /**
@@ -844,9 +822,9 @@ export interface ShellCaptureDescriptor {
  * error is routed through reportCacheError — capture is best-effort; a failure just
  * means the next request recaptures.
  *
- * Eligibility (nonce/allReady/partial/status/strategy) is decided by the caller
- * (rsc-rendering.ts maybeScheduleShellCapture); this function only owns the
- * stampede guard and the background dispatch.
+ * Eligibility (nonce/partial/status/strategy) is decided by the caller. An SSR
+ * module loader may be passed for cold partial requests; it runs only after the
+ * capture enters the guarded background queue, never on response latency.
  */
 export function scheduleShellCapture(
   ctx: HandlerContext<any>,
@@ -854,7 +832,9 @@ export function scheduleShellCapture(
   env: any,
   url: URL,
   reqCtx: RequestContext<any>,
-  ssrModule: SSRModule,
+  ssrModule:
+    | SSRModule
+    | ((request: Request, url: URL) => Promise<SSRModule | null>),
   descriptor: ShellCaptureDescriptor,
 ): void {
   const key = descriptor.key;
@@ -875,13 +855,30 @@ export function scheduleShellCapture(
   inFlightCaptures.add(key);
   const captureTask = async () => {
     try {
+      const setupUrl = descriptor.navigationOnly
+        ? stripInternalParams(url)
+        : url;
+      const setupRequest = descriptor.navigationOnly
+        ? createNavigationCaptureRequest(request, setupUrl)
+        : request;
+      const resolvedSsrModule =
+        typeof ssrModule === "function"
+          ? await ssrModule(setupRequest, setupUrl)
+          : ssrModule;
+      if (
+        !resolvedSsrModule ||
+        !resolvedSsrModule.resumeShellHTML ||
+        !resolvedSsrModule.captureShellHTML
+      ) {
+        return;
+      }
       const outcome = await runShellCapture(
         ctx,
         request,
         env,
         url,
         reqCtx,
-        ssrModule,
+        resolvedSsrModule,
         descriptor,
       );
       // Update the negative cache off the terminal outcome. A stored shell clears
@@ -917,7 +914,21 @@ export function scheduleShellCapture(
   // capture makes the sibling freeze a trivial prelude and store nothing
   // (rotating eternal-MISS victims on GH runners). The stampede guard above
   // stays per-key (dedupe while queued); the queue is cross-key.
-  const serializedTask = () => enqueueSerializedCapture(captureTask);
+  const serializedTask = async () => {
+    try {
+      await enqueueSerializedCapture(captureTask);
+    } catch (error) {
+      if (error instanceof CaptureQueueFullError) {
+        inFlightCaptures.delete(key);
+        publishCaptureDebugEvent(descriptor, {
+          key,
+          outcome: "skip-capacity",
+        });
+        return;
+      }
+      throw error;
+    }
+  };
   // The capture's own task must NOT enter reqCtx._pendingBackgroundTasks: the
   // capture drains that list before rendering (the write-barrier ordering edge),
   // and awaiting its own still-running promise would burn the whole barrier
@@ -939,6 +950,22 @@ export function scheduleShellCapture(
  */
 type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused";
 
+function createNavigationCaptureRequest(request: Request, url: URL): Request {
+  const headers = new Headers(request.headers);
+  headers.set("accept", "text/html");
+  for (const name of [
+    "rsc-action",
+    "x-rango-prefetch",
+    "x-rango-state",
+    "x-rsc-hmr",
+    "x-rsc-router-client-path",
+    "x-rsc-router-intercept-source",
+  ]) {
+    headers.delete(name);
+  }
+  return new Request(url, { method: request.method, headers });
+}
+
 /**
  * Per-attempt observability fields, filled along the capture path (barrier in
  * attemptCapture, the rest in captureAndStoreShell) and folded into the
@@ -953,6 +980,7 @@ type CaptureAttemptStats = Pick<
   | "preludeBytes"
   | "snapshotBytes"
   | "snapshotSkipped"
+  | "untaggedBake"
   | "storeWrite"
 >;
 
@@ -984,6 +1012,10 @@ async function runShellCapture(
   descriptor: ShellCaptureDescriptor,
   retryDelayMs: number = SHELL_CAPTURE_RETRY_DELAY_MS,
 ): Promise<CaptureAttemptOutcome> {
+  const captureUrl = descriptor.navigationOnly ? stripInternalParams(url) : url;
+  const captureRequest = descriptor.navigationOnly
+    ? createNavigationCaptureRequest(request, captureUrl)
+    : request;
   const log = descriptor.debug
     ? (message: string) => console.log(message)
     : () => {};
@@ -1000,9 +1032,9 @@ async function runShellCapture(
     const start = performance.now();
     const outcome = await attemptCapture(
       ctx,
-      request,
+      captureRequest,
       env,
-      url,
+      captureUrl,
       reqCtx,
       ssrModule,
       descriptor,
@@ -1122,6 +1154,7 @@ async function attemptCapture(
   const { derivedCtx, freshHandleStore } = deriveShellCaptureContext(
     reqCtx,
     descriptor,
+    descriptor.navigationOnly ? { request, url } : undefined,
   );
   const captureStartedAt = Date.now();
 
@@ -1195,6 +1228,7 @@ export interface CaptureContextDerivation {
 export function deriveShellCaptureContext(
   reqCtx: RequestContext<any>,
   descriptor: Pick<ShellCaptureDescriptor, "ttl" | "swr">,
+  identity?: { request: Request; url: URL },
 ): CaptureContextDerivation {
   const freshHandleStore = createHandleStore();
   freshHandleStore.onError = reqCtx._handleStore.onError;
@@ -1266,6 +1300,13 @@ export function deriveShellCaptureContext(
   };
 
   const derivedCtx: RequestContext = Object.create(reqCtx);
+  if (identity) {
+    derivedCtx.request = identity.request;
+    derivedCtx.url = identity.url;
+    derivedCtx.originalUrl = new URL(identity.url);
+    derivedCtx.pathname = identity.url.pathname;
+    derivedCtx.searchParams = identity.url.searchParams;
+  }
   derivedCtx._handleStore = freshHandleStore;
   // Own render barrier, closure-bound to the derived ctx and the fresh store
   // (issue #684, plan 009). Without this every _renderBarrier* read fell
@@ -1553,7 +1594,7 @@ async function captureAndStoreShell(
     const loaderRecords = reqCtx._shellCaptureLoaderRecords;
     // Set once a bake-lane loader settles with real (non-hole) material: its data
     // is frozen into the shell prelude regardless of whether snapshot
-    // serialization succeeds. Drives the untagged-bake dev warning below.
+    // serialization succeeds. Drives the opt-in debug metadata below.
     let bakedLoaderMaterial = false;
     if (loaderRecords && loaderRecords.size > 0) {
       // The codec import is deferred past the elide probes: a rejected record
@@ -1638,13 +1679,15 @@ async function captureAndStoreShell(
     const union = new Set<string>([...(capture.tags ?? []), ...collected]);
     const shellTags = union.size > 0 ? [...union] : undefined;
 
-    // Untagged-bake diagnostic: a bake-lane loader froze mutable data into the
-    // shell but nothing tags the entry, so it is un-invalidatable except by TTL —
-    // a read-your-own-writes gap on the document channel (an action refresh skips
-    // the server shell; updateTag cannot drop untagged data). Coarse per-shell-key
-    // signal; dev-only and once-per-key so it never spams production.
-    if (isDevMode() && bakedLoaderMaterial && shellTags === undefined) {
-      warnUntaggedShellBakeOnce(capture.key);
+    // Missing tags are valid: the shell follows TTL/SWR-only invalidation. Expose
+    // that choice only to operators who enabled structured capture diagnostics.
+    if (
+      capture.debugSink &&
+      stats &&
+      bakedLoaderMaterial &&
+      shellTags === undefined
+    ) {
+      stats.untaggedBake = true;
     }
 
     const store = capture.store ?? reqCtx._cacheStore;
@@ -1664,6 +1707,7 @@ async function captureAndStoreShell(
           // ShellCacheEntry.initialTheme.
           initialTheme: reqCtx.theme,
           snapshot,
+          navigationOnly: capture.navigationOnly,
           // Handler-layer liveness folded at the barrier: nested thenables in
           // handler-scoped pushes, handler pushes still pending (liveness
           // unknowable), or a handler-invoked loader execution — any of them

package/src/rsc/shell-serve.ts

@@ -20,6 +20,7 @@ import React from "react";
 import { isPprEntry, type EntryData } from "../server/context.js";
 import { sortedSearchString } from "../cache/cache-key-utils.js";
 import type { ShellCacheEntry, SegmentCacheStore } from "../cache/types.js";
+import { SHELL_CAPTURE_MAX_WAIT_MS } from "./shell-capture-constants.js";
 
 /** Debug/status header the browser (and e2e assertions) can read: HIT | MISS. */
 export const SHELL_STATUS_HEADER = "x-rango-shell";
@@ -62,9 +63,10 @@ export interface ResolvedPprConfig {
 }
 
 /**
- * Validate the raw `ppr.captureTimeout` option: a finite number >= 1ms passes
- * through; anything else (including 0/negative/NaN/Infinity/non-number)
- * resolves to undefined, which means "use the capture default" downstream.
+ * Validate the raw `ppr.captureTimeout` option: a finite number >= 1ms is
+ * clamped to the default ceiling; anything else (including
+ * 0/negative/NaN/Infinity/non-number) resolves to undefined, which means "use
+ * the capture default" downstream.
  * Mirrors the prefetch-limit option policy: invalid values silently fall back
  * to the default rather than throwing at request time. Also the boundary
  * re-normalizer for the dev /__rsc_shell endpoint (vite/router-discovery.ts),
@@ -72,7 +74,7 @@ export interface ResolvedPprConfig {
  */
 export function normalizeCaptureTimeout(value: unknown): number | undefined {
   return typeof value === "number" && Number.isFinite(value) && value >= 1
-    ? value
+    ? Math.min(value, SHELL_CAPTURE_MAX_WAIT_MS)
     : undefined;
 }
 

package/src/rsc/types.ts

@@ -49,6 +49,8 @@ export interface RscPayload {
     prefetchCacheSize?: number;
     /** Max concurrent speculative prefetch requests on the client */
     prefetchConcurrency?: number;
+    /** Router-wide default prefetch strategy for Links without a `prefetch` prop */
+    defaultPrefetch?: import("../router/prefetch-default.js").PrefetchStrategy;
     /** Server-resolved rango state cookie name; the client reads it verbatim. */
     stateCookieName?: string;
     /** Theme configuration for FOUC prevention */

package/src/testing/e2e/index.ts

@@ -5,12 +5,15 @@ import {
   type FixtureOptions,
 } from "./fixture.js";
 import {
+  blockPrefetch,
+  unblockPrefetch,
   createPageHelpers,
   createStopwatch,
   getHistoryState,
   getNumericContent,
   goBack,
   goForward,
+  isPrefetchRequest,
   isVisibleInViewport,
   measureTime,
   type PageHelpers,
@@ -62,6 +65,9 @@ export {
   getHistoryState,
   waitForElement,
   isVisibleInViewport,
+  isPrefetchRequest,
+  blockPrefetch,
+  unblockPrefetch,
   parseNumber,
   getNumericContent,
   createStopwatch,

package/src/testing/e2e/page-helpers.ts

@@ -159,6 +159,53 @@ export async function measureTime<T>(
   return { elapsed, result };
 }
 
+/**
+ * True when the request is a speculative prefetch (Link viewport/hover/render
+ * strategies or `useRouter().prefetch()`). Every prefetch fetch carries the
+ * `X-Rango-Prefetch` header. Links prefetch by default in production unless
+ * the router opts out, so tests that track `_rsc_partial` requests to pin
+ * NAVIGATION behavior must skip these — a request-count or first-request
+ * assertion otherwise races background prefetch traffic.
+ */
+export function isPrefetchRequest(req: {
+  headers: () => Record<string, string>;
+}): boolean {
+  return !!req.headers()["x-rango-prefetch"];
+}
+
+// Module-level matcher + handler so blockPrefetch/unblockPrefetch share
+// stable references — Playwright's unroute matches by identity.
+const rscPartialUrl = (url: URL): boolean =>
+  url.searchParams.has("_rsc_partial");
+async function abortPrefetchRoute(
+  route: import("@playwright/test").Route,
+): Promise<void> {
+  if (isPrefetchRequest(route.request())) {
+    await route.abort("aborted");
+  } else {
+    await route.fallback();
+  }
+}
+
+/**
+ * Abort every speculative prefetch request on this page. Install BEFORE
+ * `page.goto` so no prefetch can complete first. For tests whose semantics
+ * need a virgin prefetch cache: a click on a Link whose target was already
+ * prefetched ADOPTS the warmed entry and issues no navigation fetch at all —
+ * a `page.route` override, a request waiter, or a Set-Cookie assertion aimed
+ * at the navigation request then sees nothing (or sees the prefetch's side
+ * effects instead). Aborted prefetches are benign by design (evicted, never
+ * adopted, no page error), so the click's real fetch is guaranteed live.
+ */
+export async function blockPrefetch(page: Page): Promise<void> {
+  await page.route(rscPartialUrl, abortPrefetchRoute);
+}
+
+/** Remove a `blockPrefetch` guard, restoring normal prefetch traffic. */
+export async function unblockPrefetch(page: Page): Promise<void> {
+  await page.unroute(rscPartialUrl, abortPrefetchRoute);
+}
+
 // ============================================================================
 //  Factory-bound helpers (need the injected `expect`)
 // ============================================================================

package/src/testing/e2e/parity.ts

@@ -7,6 +7,7 @@
 import type { Expect, Page, TestType } from "@playwright/test";
 import type { Fixture, FixtureOptions } from "./fixture.js";
 import { DEFAULT_STATE_COOKIE_PREFIX } from "../../browser/cookie-name.js";
+import { blockPrefetch, unblockPrefetch } from "./page-helpers.js";
 
 export interface ParityDescribeOptions extends Partial<
   Omit<FixtureOptions, "mode">
@@ -318,6 +319,15 @@ export function createParity({
     // navigation away from it.
     const originUrl = page.url();
 
+    // Exclude speculative prefetch traffic from the parity window. Links
+    // prefetch by default in production unless the router opts out, and a
+    // prefetched route's middleware/loader side effects
+    // (Set-Cookie, session state) land in the JS jar only — a no-JS context
+    // cannot prefetch, so that traffic would diverge the jars on requests the
+    // intent never caused. Aborted prefetches are benign by design (evicted,
+    // never adopted), so the intent's real navigation always fetches live.
+    await blockPrefetch(page);
+
     // Settle the intent's observable effect before snapshotting. A `navigate`
     // intent already awaited its navigation in applyIntent (page.goto), so only
     // `submit` needs the DOM-driven settle, and only when no `waitFor` override
@@ -380,6 +390,9 @@ export function createParity({
       );
     } finally {
       await noJsContext.close();
+      // Restore the caller's page: the prefetch guard is scoped to the parity
+      // window, not the rest of the test.
+      await unblockPrefetch(page);
     }
   }