@rangojs/router 0.1.1 → 0.4.0

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,10 +20,14 @@ 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";
 
+/** Partial-navigation status header set only after captured PPR segments are consumed. */
+export const PPR_REPLAY_STATUS_HEADER = "x-rango-ppr-replay";
+
 /**
  * Default shell ttl (seconds) for `ppr: true` and for a PartialPrerenderProps
  * that omits `ttl`.
@@ -59,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),
@@ -69,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/transition-gate.ts

@@ -1,41 +1,58 @@
 import type { MatchResult } from "../types.js";
-import type { TransitionWhenContext } from "../types/segments.js";
 import type { getRequestContext } from "../server/request-context.js";
 import { invokeOnError } from "../router/error-handling.js";
 import type { OnErrorCallback } from "../types/error-types.js";
+import { createTransitionWhenContext } from "../router/transition-when.js";
 
 /**
  * Apply transition({ when }) gates to a payload's segments.
  *
- * The predicates were collected during resolution (keyed by segment id) and
- * stripped from the serialized config; here — after handlers ran and outside any
- * cache scope — we evaluate each and drop the segment's transition when the
- * predicate does not hold, so the navigation streams its loading fallback
- * instead of holding the previous content. A predicate that throws is reported
- * to the router's onError (phase "rendering") and then treated as "do not hold"
- * (conservative), so a buggy predicate degrades to no transition rather than
- * failing the response.
+ * PPR predicates were evaluated from the manifest before cache lookup and route
+ * handlers; their request-specific decisions are projected onto a copy so they
+ * never mutate reusable cache/prerender/shell records. Ordinary-route predicates
+ * were collected during fresh resolution and are evaluated here after handlers.
+ * Both paths drop the segment transition when the predicate does not hold.
  *
  * Mutating the segments here is safe: the segment cache stores a serialized copy
  * (segment-codec), written during match() BEFORE this gate runs, so dropping a
- * transition never corrupts a cache entry. The flip side is that a cache hit
+ * transition never corrupts a cache entry. On an ordinary route, a cache hit
  * skips resolution, collects no predicate, and replays the cached transition
- * as-is (it was serialized before the gate) — combining transition({ when })
- * with cache() on the same segment freezes the gate to its cached state, so
- * avoid caching a route whose transition decision is request-dependent.
+ * as-is (it was serialized before the gate). PPR routes are the exception: their
+ * manifest predicates were evaluated before lookup and apply to replayed data.
  *
- * Returns the same array (mutated) for inline use at the payload's `segments`
- * field.
+ * Returns the same array for the ordinary post-handler path. A PPR drop returns a
+ * copy containing only the request-specific transition changes.
  */
 export function gateTransitions(
   segments: MatchResult["segments"],
   ctx: ReturnType<typeof getRequestContext>,
   onError?: OnErrorCallback,
 ): MatchResult["segments"] {
+  const pprDecisions = ctx._pprTransitionDecisions;
+  let gatedSegments = segments;
+
+  const dropTransition = (id: string): void => {
+    const index = gatedSegments.findIndex((segment) => segment.id === id);
+    if (index === -1) return;
+    if (!pprDecisions) {
+      gatedSegments[index].transition = undefined;
+      return;
+    }
+    if (gatedSegments === segments) gatedSegments = [...segments];
+    gatedSegments[index] = {
+      ...gatedSegments[index],
+      transition: undefined,
+    };
+  };
+
+  if (pprDecisions) {
+    for (const [id, keep] of pprDecisions) {
+      if (!keep) dropTransition(id);
+    }
+  }
   const predicates = ctx._transitionWhen;
-  if (predicates && predicates.length) {
+  if (predicates) {
     for (const { id, when } of predicates) {
-      let drop: boolean;
       try {
         // Assemble the ShouldRevalidateFn-shaped predicate context from the
         // request context. Source fields (currentUrl/currentParams/fromRouteName)
@@ -44,28 +61,11 @@ export function gateTransitions(
         // method/get/env come straight off ctx (setRequestContextParams ran
         // before the gate). Source/action fields are undefined when absent —
         // never fabricated (see TransitionWhenContext).
-        const whenCtx: TransitionWhenContext = {
-          currentUrl: ctx._gateCurrentUrl,
-          currentParams: ctx._gateCurrentParams,
-          fromRouteName:
-            ctx._prevRouteKey as TransitionWhenContext["fromRouteName"],
-          nextUrl: ctx.url,
-          nextParams: ctx.params,
-          toRouteName: ctx.routeName,
-          actionId: ctx._gateActionId,
-          actionUrl: ctx._gateActionUrl,
-          actionResult: ctx._gateActionResult,
-          formData: ctx._gateFormData,
-          method: ctx.request.method,
-          get: ctx.get,
-          env: ctx.env,
-        };
-        drop = when(whenCtx) === false;
+        if (when(createTransitionWhenContext(ctx)) !== false) continue;
       } catch (error) {
         // A throwing predicate must not fail the response: report it and treat
         // the transition as gated off (do not hold). invokeOnError no-ops when
         // onError is undefined.
-        drop = true;
         invokeOnError(
           onError,
           error,
@@ -79,11 +79,8 @@ export function gateTransitions(
           "RSC",
         );
       }
-      if (drop) {
-        const seg = segments.find((s) => s.id === id);
-        if (seg) seg.transition = undefined;
-      }
+      dropTransition(id);
     }
   }
-  return segments;
+  return gatedSegments;
 }

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/server/request-context.ts

@@ -208,6 +208,9 @@ export interface RequestContext<
    */
   _transitionWhen?: Array<{ id: string; when: TransitionWhenFn }>;
 
+  /** @internal PPR transition decisions evaluated before cache lookup/handlers. */
+  _pprTransitionDecisions?: Map<string, boolean>;
+
   /** @internal Cache store for segment caching (optional, used by CacheScope) */
   _cacheStore?: SegmentCacheStore;
 
@@ -276,6 +279,8 @@ export interface RequestContext<
      * segment record even when the triggering request is partial.
      */
     keyPrefix?: "doc";
+    /** @internal Called only after the implicit cache hit decodes successfully. */
+    onHit?: () => void;
   };
 
   /**
@@ -650,6 +655,7 @@ export type PublicRequestContext<
   | "deleteCookie"
   | "_handleStore"
   | "_transitionWhen"
+  | "_pprTransitionDecisions"
   | "_cacheStore"
   | "_shellCaptureRun"
   | "_shellImplicitCache"

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,
@@ -41,10 +44,15 @@ export {
   type CacheStatusTarget,
 } from "../cache-status.js";
 export {
+  assertPprReplayStatus,
   assertShellStatus,
+  parsePprReplayStatus,
   parseShellStatus,
+  PPR_REPLAY_STATUS_HEADER,
   shellCacheKey,
   SHELL_STATUS_HEADER,
+  type PprReplayBypassReason,
+  type PprReplayStatus,
   type ShellStatus,
   type ShellStatusTarget,
 } from "../shell-status.js";
@@ -57,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);
     }
   }
 

package/src/testing/index.ts

@@ -77,12 +77,20 @@ export type {
 } from "../router/telemetry.js";
 
 export {
+  assertPprReplayStatus,
   assertShellStatus,
+  parsePprReplayStatus,
   parseShellStatus,
+  PPR_REPLAY_STATUS_HEADER,
   shellCacheKey,
   SHELL_STATUS_HEADER,
 } from "./shell-status.js";
-export type { ShellStatus, ShellStatusTarget } from "./shell-status.js";
+export type {
+  PprReplayBypassReason,
+  PprReplayStatus,
+  ShellStatus,
+  ShellStatusTarget,
+} from "./shell-status.js";
 
 export { collectHandle } from "./collect-handle.js";