@rangojs/router 0.0.0-experimental.146 → 0.0.0-experimental.148

package/src/prerender/build-shell-capture.ts

@@ -0,0 +1,253 @@
+/**
+ * Producer B: build-time PPR shell capture for Prerender+ppr routes (#699).
+ *
+ * Runs in the RSC realm of the build's temp server, AFTER all bundles are
+ * written (the prelude embeds built client asset URLs — bootstrap module,
+ * chunk preloads — that only exist post-client-build). The capture core is
+ * producer A's, verbatim: deriveShellCaptureContext (mask funnel, liveness,
+ * snapshot recording, implicit doc-cache scope) + captureAndStoreShell (gates,
+ * quiesce, tags union, putShell barrier). The differences are only the base
+ * context (a synthetic build request created via createRequestContext over the
+ * build env — no ambient identity, so the identity guard is trivially
+ * satisfied) and the sink (an entry collector instead of a runtime store).
+ *
+ * The capture's match() re-enters withCacheLookup, HITs the in-realm prerender
+ * store seeded from the just-collected Flight payloads, and REPLAYS the
+ * build-time segments — no handler execution, exactly the runtime composition
+ * path (#697). Live-lane loaders mask into holes; bake-lane loaders execute
+ * under the build context and refuse the capture if they reject or read
+ * identity, the same eligibility rules as at runtime.
+ */
+
+import type { ShellCacheEntry } from "../cache/types.js";
+import { MemorySegmentCacheStore } from "../cache/memory-segment-store.js";
+import {
+  createRequestContext,
+  runWithRequestContext,
+  setRequestContextParams,
+} from "../server/request-context.js";
+import {
+  deriveShellCaptureContext,
+  captureAndStoreShell,
+  delay,
+  SHELL_CAPTURE_RETRY_DELAY_MS,
+  type ShellCaptureDescriptor,
+} from "../rsc/shell-capture.js";
+import { buildFullPayload } from "../rsc/full-payload.js";
+import type { RscPayload, SSRModule } from "../rsc/types.js";
+import type { HandlerContext } from "../rsc/handler-context.js";
+import { renderToReadableStream } from "../deps/rsc.js";
+import {
+  resolvePprConfig,
+  type ResolvedPprConfig,
+} from "../rsc/shell-serve.js";
+
+/**
+ * Normalize a collected truthy `ppr` path option into the SAME concrete
+ * policy the runtime serve path derives — through resolvePprConfig itself,
+ * over a synthetic route entry — so the build-stamped ttl default can never
+ * drift from the serve-side one.
+ */
+export function resolveBuildPprConfig(
+  ppr:
+    | true
+    | { ttl?: number; swr?: number; tags?: string[]; captureTimeout?: number },
+): ResolvedPprConfig {
+  const resolved = resolvePprConfig({ type: "route", ppr } as any);
+  // resolvePprConfig returns null only for undefined/false ppr; the collector
+  // filtered those out. Guard for the type only.
+  if (!resolved) throw new Error("[rango] unreachable: ppr option was falsy");
+  return resolved;
+}
+
+export interface BuildShellCaptureOptions {
+  /** The router instance (from RouterRegistry in the same realm). */
+  router: any;
+  /** Concrete URL path to capture (e.g. "/pp/alpha"). */
+  urlPath: string;
+  /**
+   * The candidate's trie route key. The capture's match() must land on THIS
+   * route: the phase sweeps every registered router, and a router that does
+   * not own the URL matches something else (its catch-all, a 404 shape) —
+   * that capture must not be baked.
+   */
+  routeName: string;
+  /** Shell store key to stamp into the descriptor (host-free at build). */
+  key: string;
+  ttl?: number;
+  swr?: number;
+  /** The route's static ppr.tags (the capture unions render-recorded tags). */
+  tags?: string[];
+  /**
+   * The route's resolved snapshot size cap (ResolvedPprConfig.maxSnapshotBytes)
+   * — build captures apply the same over-cap skip as runtime captures, so a
+   * raised per-route cap behaves identically across both producers.
+   */
+  maxSnapshotBytes?: number;
+  /**
+   * The route's `ppr.captureTimeout` (ms) — producer B honors the same settle
+   * budget as the runtime capture. Build has no waitUntil lifetime bound, so
+   * the option is the only ceiling here.
+   */
+  captureTimeout?: number;
+  /** Build-time env bindings (rango plugin buildEnv), if configured. */
+  buildEnv?: unknown;
+  /**
+   * The MAIN build's version (the version plugin's value folded into the
+   * shipped worker) — NOT the temp server's own version-plugin value. The
+   * serve-side isValidShellHit gate compares entry.buildVersion against the
+   * running worker's ctx.version; stamping the temp server's would make every
+   * build entry an eternal MISS.
+   */
+  buildVersion: string;
+  /**
+   * The SSR half, composed by the plugin from the temp server's SSR
+   * environment runner (react-dom/static prerender + Flight client), with the
+   * bootstrap script content overridden to the BUILT client entry URL.
+   */
+  captureShellHTML: NonNullable<SSRModule["captureShellHTML"]>;
+  /** Verbose per-attempt breadcrumbs (build log). */
+  debug?: boolean;
+}
+
+export interface BuildShellCaptureResult {
+  outcome:
+    | "stored"
+    | "no-shell"
+    | "redirect"
+    | "refused"
+    /** The router swept does not own this URL — try the next one. */
+    | "route-mismatch";
+  /** Present iff outcome === "stored". */
+  entry?: ShellCacheEntry;
+  /** The putShell-barrier tag union (static ppr.tags + render-recorded). */
+  tags?: string[];
+  /** On route-mismatch: what this router's match actually landed on. */
+  matchedRouteName?: string;
+}
+
+/**
+ * Capture the PPR shell for one prerendered URL at build time. Retries once
+ * in place on `no-shell` (the first attempt warms the temp server's SSR/Flight
+ * transform graph, mirroring producer A's cold-start retry — same delay).
+ */
+export async function captureShellForBuild(
+  opts: BuildShellCaptureOptions,
+): Promise<BuildShellCaptureResult> {
+  const first = await attemptBuildCapture(opts);
+  if (first.outcome !== "no-shell") return first;
+  if (opts.debug) {
+    console.log(
+      `[rango] shell capture attempt 1/2 for ${opts.urlPath} produced no shell (cold graph?) — retrying`,
+    );
+  }
+  await delay(SHELL_CAPTURE_RETRY_DELAY_MS);
+  return attemptBuildCapture(opts);
+}
+
+/** One attempt: fresh base context, fresh derivation, fresh render. */
+async function attemptBuildCapture(
+  opts: BuildShellCaptureOptions,
+): Promise<BuildShellCaptureResult> {
+  const router = opts.router;
+  const url = new URL(opts.urlPath, "http://build.invalid");
+  const request = new Request(url, { method: "GET" });
+
+  // Synthetic build request context: same factory the runtime handler uses,
+  // so the capture's ALS surface (cookie machinery, variables, waitUntil,
+  // theme resolution) is production-shaped. No cookie header → theme resolves
+  // to the app default, exactly like a first anonymous visitor's capture.
+  const baseCtx = createRequestContext({
+    env: (opts.buildEnv ?? {}) as any,
+    request,
+    url,
+    variables: {},
+    // Fresh empty store per attempt: cache()/"use cache" reads MISS, execute,
+    // and are recorded into the snapshot by the derivation's RecordingShell
+    // wrapper — the entry pins its own generation, nothing preexisting leaks.
+    cacheStore: new MemorySegmentCacheStore(),
+    themeConfig: router.themeConfig ?? null,
+    stateCookieName: router.resolvedStateCookieName,
+    version: opts.buildVersion,
+  });
+
+  const { derivedCtx, freshHandleStore } = deriveShellCaptureContext(baseCtx, {
+    ttl: opts.ttl,
+    swr: opts.swr,
+  });
+
+  // Entry collector: captureAndStoreShell's sink. putShell never fails here,
+  // so a "stored" outcome always carries the entry.
+  let collected: { entry: ShellCacheEntry; tags?: string[] } | null = null;
+  const collector = {
+    putShell: async (
+      _key: string,
+      entry: ShellCacheEntry,
+      _ttl?: number,
+      _swr?: number,
+      tags?: string[],
+    ): Promise<void> => {
+      collected = { entry, tags };
+    },
+  };
+
+  const descriptor: ShellCaptureDescriptor = {
+    key: opts.key,
+    buildVersion: opts.buildVersion,
+    ttl: opts.ttl,
+    swr: opts.swr,
+    tags: opts.tags,
+    captureTimeout: opts.captureTimeout,
+    store: collector as any,
+    debug: opts.debug,
+    maxSnapshotBytes: opts.maxSnapshotBytes,
+  };
+
+  let mismatchedRouteName: string | undefined;
+  const outcome = await runWithRequestContext(derivedCtx, async () => {
+    const match = await router.match(request, { env: opts.buildEnv ?? {} });
+    if (match.routeName !== opts.routeName) {
+      mismatchedRouteName = match.routeName;
+      return "route-mismatch" as const;
+    }
+    if (match.redirect) return "redirect" as const;
+
+    setRequestContextParams(match.params, match.routeName);
+
+    const payload = buildFullPayload(
+      match,
+      // buildFullPayload reads only ctx.router.* and ctx.version.
+      { router, version: opts.buildVersion } as unknown as HandlerContext<any>,
+      url,
+      derivedCtx,
+      freshHandleStore,
+    );
+    const rscStream = renderToReadableStream<RscPayload>(payload, {
+      onError: (error: unknown) => {
+        if (opts.debug) {
+          console.warn(
+            `[rango] shell capture render error for ${opts.urlPath}:`,
+            error,
+          );
+        }
+      },
+    });
+
+    return captureAndStoreShell(
+      { captureShellHTML: opts.captureShellHTML } as SSRModule,
+      rscStream,
+      freshHandleStore,
+      derivedCtx,
+      descriptor,
+    );
+  });
+
+  if (outcome === "stored" && collected !== null) {
+    const hit: { entry: ShellCacheEntry; tags?: string[] } = collected;
+    return { outcome, entry: hit.entry, tags: hit.tags };
+  }
+  if (outcome === "route-mismatch") {
+    return { outcome, matchedRouteName: mismatchedRouteName };
+  }
+  return { outcome };
+}

package/src/prerender/shell-manifest-key.ts

@@ -0,0 +1,20 @@
+/**
+ * Build shell manifest key, shared by the producer (the build's shell
+ * prerender phase, vite/discovery/shell-prerender-phase.ts) and the consumer
+ * (the runtime read-through, rsc/shell-build-manifest.ts) so the format
+ * cannot drift. Dependency-free: the producer runs node-side in the plugin,
+ * the consumer in the RSC runtime.
+ *
+ * PATHNAME-ONLY by design. Host-free because the build knows no request
+ * host. Router-free because the router id ($$id) is a hash of
+ * filePath:lineNumber of the TRANSFORMED source, which differs between the
+ * discovery temp server's dev-style transform chain and the main build's —
+ * a temp-realm router id can never be looked up by the shipped worker. The
+ * producer instead detects pathname collisions across routers at build time
+ * and declines both entries (loudly), keeping the key unambiguous. This is
+ * a manifest namespace, never a store keyspace: the runtime shell key
+ * (host + pathname + search + ":shell") stays untouched.
+ */
+export function buildShellManifestKey(pathname: string): string {
+  return pathname;
+}

package/src/prerender/store.ts

@@ -73,7 +73,16 @@ export function createDevPrerenderStore(devUrl: string): PrerenderStore {
       if (isIntercept) url += "&intercept=1";
       if (meta.isPassthroughRoute) url += "&passthrough=1";
       try {
-        const res = await fetch(url);
+        // Bounded: this fetch also runs inside the PPR shell capture (a
+        // workerd waitUntil task), where an unsettled fetch does not reject —
+        // it pends until the task is torn down. Unbounded, one pending fetch
+        // wedged the per-isolate capture queue on GH runners (rotating dev
+        // capture failures; endpoint instrumentation showed 3-4ms memo HITs,
+        // so latency was never the issue — settlement was). On timeout the
+        // catch degrades to a store miss and the pipeline falls through to
+        // the live handler render (the documented dev fall-through), so the
+        // capture still lands with live content.
+        const res = await fetch(url, { signal: AbortSignal.timeout(10_000) });
         if (!res.ok) return null;
         return res.json();
       } catch {

package/src/router/content-negotiation.ts

@@ -76,6 +76,46 @@ export function parseAcceptTypes(accept: string): AcceptEntry[] {
 
 export const RSC_RESPONSE_TYPE = "__rsc__";
 
+/** RSC wire-format MIME type; explicit-opt-in flight transport. */
+export const RSC_WIRE_MIME = "text/x-component";
+
+/**
+ * The two representations an RSC route serves, in canonical-first order:
+ * text/html (the document) and text/x-component (the flight wire format).
+ * Both register as negotiation candidates in pickNegotiateVariant; without
+ * the wire-format entry, an explicit Accept: text/x-component fell through
+ * to the definition-order fallback — a JSON-first route answered a
+ * wire-format request with JSON. Which representation an RSC win actually
+ * renders is decided by prefersFlightRepresentation below, from the same
+ * Accept header (wired in via isRscRequest, rsc/ssr-setup.ts).
+ */
+const RSC_MIMES: readonly string[] = ["text/html", RSC_WIRE_MIME];
+
+/**
+ * Rank the RSC route's two representations against a parsed Accept list:
+ * true when the flight wire format outranks the HTML document. Wildcard
+ * entries count for the HTML side — they express "anything", and the
+ * canonical representation of anything is the document. Co-located with
+ * RSC_MIMES so the candidate registration and the representation choice
+ * cannot drift.
+ */
+export function prefersFlightRepresentation(
+  acceptEntries: AcceptEntry[],
+): boolean {
+  for (const entry of acceptEntries) {
+    if (entry.q === 0) continue;
+    if (entry.mime === RSC_WIRE_MIME) return true;
+    if (
+      entry.mime === "text/html" ||
+      entry.mime === "text/*" ||
+      entry.mime === "*/*"
+    ) {
+      return false;
+    }
+  }
+  return false;
+}
+
 /**
  * Pick the best negotiate variant by walking the client's sorted Accept list.
  * For each accepted MIME type (in q-value/order priority), check if any
@@ -87,12 +127,14 @@ export function pickNegotiateVariant<
 >(acceptEntries: AcceptEntry[], candidates: T[]): T {
   const byCandidateMime = new Map<string, T>();
   for (const c of candidates) {
-    const mime =
+    const mimes =
       c.responseType === RSC_RESPONSE_TYPE
-        ? "text/html"
-        : RESPONSE_TYPE_MIME[c.responseType];
-    if (mime && !byCandidateMime.has(mime)) {
-      byCandidateMime.set(mime, c);
+        ? RSC_MIMES
+        : [RESPONSE_TYPE_MIME[c.responseType]];
+    for (const mime of mimes) {
+      if (mime && !byCandidateMime.has(mime)) {
+        byCandidateMime.set(mime, c);
+      }
     }
   }
 

package/src/router/match-middleware/cache-lookup.ts

@@ -112,6 +112,9 @@ let prerenderStoreInstance: PrerenderStore | null | undefined;
 let _deserializeSegments:
   | typeof import("../../cache/segment-codec.js").deserializeSegments
   | undefined;
+let _fragmentSegments:
+  | typeof import("../../cache/segment-codec.js").fragmentSegments
+  | undefined;
 let _restoreHandles:
   | typeof import("../../cache/handle-snapshot.js").restoreHandles
   | undefined;
@@ -135,6 +138,7 @@ async function ensurePrerenderDeps() {
       import("../../prerender/store.js"),
     ]);
     _deserializeSegments = codec.deserializeSegments;
+    _fragmentSegments = codec.fragmentSegments;
     _restoreHandles = snapshot.restoreHandles;
     _decodeHandles = snapshot.decodeHandles;
     _hashParams = paramHash.hashParams;
@@ -237,6 +241,7 @@ async function* yieldFromStore<TEnv>(
 
   if (
     !_deserializeSegments ||
+    !_fragmentSegments ||
     !_restoreHandles ||
     !_decodeHandles ||
     !_hashParams ||
@@ -245,7 +250,13 @@ async function* yieldFromStore<TEnv>(
     throw new Error("yieldFromStore called before ensurePrerenderDeps");
   }
 
-  const segments = await _deserializeSegments(entry.segments);
+  // Shell-HIT tail (issue #700): a Prerender+ppr route's tail serves from THIS
+  // store (the prerender lookup runs before the cache scope), so the fragment
+  // splice must apply here too — otherwise producer B entries re-serialize the
+  // whole tree per request while producer A entries do not.
+  const segments = _getRequestContext()?._shellFragmentPayload
+    ? await _fragmentSegments(entry.segments)
+    : await _deserializeSegments(entry.segments);
 
   // Replay handle data (same as runtime cache hit path). entry.handles is a
   // Flight-encoded string ("" when none) — decode before restore so

package/src/router/metrics.ts

@@ -79,6 +79,7 @@ export function appendMetric(
   start: number,
   duration: number,
   depth?: number,
+  desc?: string,
 ): void {
   if (!metricsStore) return;
   metricsStore.metrics.push({
@@ -86,6 +87,7 @@ export function appendMetric(
     duration,
     startTime: start - metricsStore.requestStart,
     depth,
+    desc,
   });
 }
 
@@ -104,6 +106,7 @@ interface DisplayRow {
   startTime: number;
   duration: number;
   depth: number | undefined;
+  desc: string | undefined;
   spans: Span[];
 }
 
@@ -137,6 +140,7 @@ function buildDisplayRows(sorted: PerformanceMetric[]): DisplayRow[] {
           startTime: m.startTime,
           duration: m.duration + post.duration,
           depth: m.depth,
+          desc: m.desc,
           spans: [
             { startTime: m.startTime, duration: m.duration },
             { startTime: post.startTime, duration: post.duration },
@@ -151,6 +155,7 @@ function buildDisplayRows(sorted: PerformanceMetric[]): DisplayRow[] {
         startTime: m.startTime,
         duration: m.duration,
         depth: m.depth,
+        desc: m.desc,
         spans: [{ startTime: m.startTime, duration: m.duration }],
       });
       continue;
@@ -169,6 +174,7 @@ function buildDisplayRows(sorted: PerformanceMetric[]): DisplayRow[] {
         startTime: m.startTime,
         duration: m.duration,
         depth: m.depth,
+        desc: m.desc,
         spans: [{ startTime: m.startTime, duration: m.duration }],
       });
       continue;
@@ -180,6 +186,7 @@ function buildDisplayRows(sorted: PerformanceMetric[]): DisplayRow[] {
       startTime: m.startTime,
       duration: m.duration,
       depth: m.depth,
+      desc: m.desc,
       spans: [{ startTime: m.startTime, duration: m.duration }],
     });
   }
@@ -199,7 +206,9 @@ export function logMetrics(
 
   const labels = displayRows.map(
     (r) =>
-      `${" ".repeat(BASE_INDENT + (r.depth ?? 0) * DEPTH_INDENT)}${r.label}`,
+      `${" ".repeat(BASE_INDENT + (r.depth ?? 0) * DEPTH_INDENT)}${r.label}${
+        r.desc ? ` (${r.desc})` : ""
+      }`,
   );
   const startValues = displayRows.map((r) => formatMs(r.startTime));
   const durationValues = displayRows.map((r) => formatMs(r.duration));
@@ -247,7 +256,13 @@ export function generateServerTiming(metricsStore: MetricsStore): string {
         .replace(/[^a-zA-Z0-9-]/g, "")
         .toLowerCase();
       const name = m.depth ? `d${m.depth}-${base}` : base;
-      return `${name};dur=${m.duration.toFixed(2)}`;
+      // desc is a quoted-string: backslash-escape the two delimiters; our
+      // producers emit plain printable text, so nothing else needs stripping.
+      const desc =
+        m.desc !== undefined
+          ? `;desc="${m.desc.replace(/[\\"]/g, "\\$&")}"`
+          : "";
+      return `${name};dur=${m.duration.toFixed(2)}${desc}`;
     })
     .join(", ");
 }

package/src/router/prerender-match.ts

@@ -21,6 +21,7 @@ import type { RouterContext } from "./router-context.js";
 import type { ResolveSegmentOptions } from "./segment-resolution.js";
 import { runWithRouterContext } from "./router-context.js";
 import type { EntryData, InterceptEntry } from "../server/context";
+import type { PartialPrerenderProps } from "../urls/pattern-types.js";
 import type {
   HandlerContext,
   InternalHandlerContext,
@@ -74,6 +75,13 @@ export async function matchForPrerender<TEnv = any>(
    *  the sinks store it as-is (no longer merge raw records). */
   interceptHandles?: string;
   passthrough?: true;
+  /**
+   * The matched route entry's `ppr` path option, surfaced so the build
+   * collection can flag Prerender+ppr routes as build-time shell candidates
+   * (issue #699 producer B). Runtime-only today; the build otherwise never
+   * sees the option (it lives on EntryData, not the trie).
+   */
+  ppr?: boolean | PartialPrerenderProps;
 } | null> {
   // 1. Find the matching route entry
   const matched = await deps.findMatch(pathname);
@@ -306,6 +314,18 @@ export async function matchForPrerender<TEnv = any>(
       // Use the trie-level route key (e.g., "docs", "docs.article")
       const routeName = matched.routeKey;
 
+      // Surface the matched route entry's ppr option for the build collection
+      // (leaf-first: the deepest type:"route" entry in the ancestor chain is
+      // the matched page route; ancestors are layouts/includes).
+      let routePpr: boolean | PartialPrerenderProps | undefined;
+      for (let i = entries.length - 1; i >= 0; i--) {
+        const e = entries[i]!;
+        if (e.type === "route") {
+          routePpr = e.ppr;
+          break;
+        }
+      }
+
       // 14. Resolve intercept segments for this route (if any ancestor defines
       //     an intercept targeting this route). At build time we skip when()
       //     evaluation -- we pre-render all intercepts unconditionally and let
@@ -420,6 +440,7 @@ export async function matchForPrerender<TEnv = any>(
         params: matchedParams,
         interceptSegments,
         interceptHandles,
+        ppr: routePpr,
       };
     });
   });

package/src/router/router-interfaces.ts

@@ -6,6 +6,7 @@ import type { UrlBuilder, EnvCompatible } from "../urls/pattern-types.js";
 import type { EntryData } from "../server/context";
 import type { ErrorInfo, MatchResult } from "../types";
 import type { NonceProvider } from "../rsc/types.js";
+import type { ShellCaptureDebug } from "../rsc/shell-capture.js";
 import type { ExecutionContext } from "../server/request-context.js";
 import type { SerializedSegmentData } from "../cache/types.js";
 import type { MiddlewareEntry, MiddlewareFn } from "./middleware.js";
@@ -344,6 +345,12 @@ export interface RangoInternal<
    */
   readonly debugPerformance?: boolean;
 
+  /**
+   * PPR shell-capture debug sink (createRouter({ debugShellCapture })), read
+   * by rsc-rendering when it builds the capture descriptor for a ppr route.
+   */
+  readonly debugShellCapture?: ShellCaptureDebug;
+
   /**
    * Resolved platform phase-span tracing (Cloudflare custom spans or OTel), or
    * undefined when off. Threaded onto the request context and read at each

package/src/router/router-options.ts

@@ -6,6 +6,7 @@ import type {
   OnErrorCallback,
 } from "../types";
 import type { NonceProvider } from "../rsc/types.js";
+import type { ShellCaptureDebug } from "../rsc/shell-capture.js";
 import type { ExecutionContext } from "../server/request-context.js";
 import type { UrlPatterns } from "../urls.js";
 import type { UrlBuilder } from "../urls/pattern-types.js";
@@ -148,6 +149,18 @@ export interface RangoOptions<TEnv = any> {
    */
   debugCacheSignal?: boolean;
 
+  /**
+   * Debug sink for the PPR shell-capture pipeline (routes with the `ppr` path
+   * option). `true` logs one structured line per capture attempt/skip to
+   * console (visible via `wrangler tail`); a function receives each
+   * `ShellCaptureDebugEvent` (outcome per attempt, snapshot bytes,
+   * write-barrier wait, backoff state) for programmatic capture. Off by
+   * default; the events also mirror into the dev Server-Timing surface when
+   * `debugPerformance` is on. Intended for validating capture behavior on a
+   * real deployment, not steady-state production.
+   */
+  debugShellCapture?: ShellCaptureDebug;
+
   /**
    * Document component that wraps the entire application.
    *

package/src/router.ts

@@ -168,6 +168,7 @@ export function createRouter<TEnv = any>(
     originCheck: originCheckOption,
     viewTransition: viewTransitionOption = "auto",
     debugCacheSignal: debugCacheSignalOption = false,
+    debugShellCapture: debugShellCaptureOption,
     strictMode: strictModeOption = true,
   } = options;
 
@@ -1007,6 +1008,10 @@ export function createRouter<TEnv = any>(
     // Expose router-wide performance debugging for request-level metrics setup
     debugPerformance,
 
+    // Expose the PPR shell-capture debug sink for the render layer
+    // (rsc-rendering resolves it into the capture descriptor)
+    debugShellCapture: debugShellCaptureOption,
+
     // Expose resolved span tracing for the handler (Cloudflare custom spans)
     tracing: resolvedTracing,
 

package/src/rsc/capture-queue.ts

@@ -0,0 +1,67 @@
+/**
+ * Per-isolate shell-capture serialization.
+ *
+ * Captures are CPU-bound background renders whose quiet detection is
+ * task-quantized (FLIGHT_QUIET_HOPS macrotask hops with zero new bytes). Two
+ * captures running concurrently starve each other: one grinding capture —
+ * e.g. a prerender+ppr route whose capture round-trips the dev
+ * /__rsc_prerender endpoint, whose per-request module re-import can peg a
+ * slow CI runner for seconds — keeps the sibling's render byte-silent past
+ * its abort budget, so the sibling freezes a trivial prelude and stores
+ * nothing. Observed on GH runners as ROTATING eternal-MISS victims (the
+ * warmup on one shard, a composition probe, then /ppr-shell?probe=stream once
+ * the first was quieted) while every local run passed.
+ *
+ * Serializing capture execution removes the cross-talk: each capture's quiet
+ * window observes only its own work. Captures are TTL-scale background work,
+ * so queueing costs latency-to-HIT only — never a served response. On workerd
+ * a queued capture rides the scheduling request's waitUntil, whose lifetime
+ * is bounded; a capture killed mid-queue by that bound simply recaptures on a
+ * later request (the existing best-effort contract).
+ *
+ * The chain link resolves in `finally` and the prior link is awaited with a
+ * swallow, so one rejected capture can never wedge every later one.
+ */
+let captureQueue: Promise<void> = Promise.resolve();
+
+/**
+ * Upper bound on how long one queue link may hold the queue. A capture task
+ * normally settles well inside this (attempt + in-place retry + writes), but
+ * a task wedged on never-settling I/O — a workerd waitUntil fetch that pends
+ * instead of rejecting (seen on GH runners with the dev prerender store
+ * before its fetch was time-bounded) — must not block every later capture in
+ * the isolate. At the cap the QUEUE is released; the wedged task itself stays
+ * detached (its own per-key guards clean up when/if it settles).
+ */
+const QUEUE_LINK_CAP_MS = 60_000;
+
+/**
+ * Run `task` after every previously enqueued capture has settled. Returns a
+ * promise for THIS task's completion (rejections propagate to the caller —
+ * the queue itself is insulated).
+ */
+export function enqueueSerializedCapture(
+  task: () => Promise<void>,
+): Promise<void> {
+  const prior = captureQueue;
+  let releaseQueue!: () => void;
+  captureQueue = new Promise<void>((resolve) => {
+    releaseQueue = resolve;
+  });
+  return (async () => {
+    await prior.catch(() => {});
+    let capTimer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await Promise.race([
+        task(),
+        new Promise<void>((resolve) => {
+          capTimer = setTimeout(resolve, QUEUE_LINK_CAP_MS);
+          (capTimer as { unref?: () => void }).unref?.();
+        }),
+      ]);
+    } finally {
+      if (capTimer) clearTimeout(capTimer);
+      releaseQueue();
+    }
+  })();
+}

package/src/rsc/handler.ts

@@ -885,8 +885,10 @@ export function createRSCHandler<
     // submissions always render HTML (handleProgressiveEnhancement renders via
     // getSSRSetup regardless of Accept). For full/partial-render and action,
     // the render-time HTML decision is exactly !isRscRequest — mayNeedSSR is
-    // the coarse transport pre-filter, isRscRequest is the precise Accept call
-    // (it, unlike mayNeedSSR, treats a MISSING Accept as RSC). Both must pass.
+    // the coarse transport pre-filter, isRscRequest adds the partial/__rsc
+    // flags; both share the same Accept rule (acceptsFlightExplicitly in
+    // ssr-setup.ts), so the Accept call cannot drift between them. Both must
+    // pass.
     const willRenderHtml =
       plan.mode === "pe-render" ||
       (mayNeedSSR(request, url) &&