@rangojs/router 0.0.0-experimental.147 → 0.0.0-experimental.149

package/dist/vite/index.js

@@ -2520,7 +2520,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.147",
+  version: "0.0.0-experimental.149",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -4671,6 +4671,13 @@ import { readFileSync as readFileSync7 } from "node:fs";
 import { createRequire as createRequire3, register } from "node:module";
 import { pathToFileURL as pathToFileURL2 } from "node:url";
 
+// src/rsc/shell-serve.ts
+import React from "react";
+var DEV_SHELL_PROBE_TIMEOUT_MS = 1e4;
+function normalizeCaptureTimeout(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 1 ? value : void 0;
+}
+
 // src/vite/inject-client-debug.ts
 function isRouterInternalDebugId(id) {
   if (!id.includes("internal-debug")) return false;
@@ -6410,6 +6417,8 @@ async function runShellPrerenderPhase(s, builder) {
             ttl: policy.ttl,
             swr: policy.swr,
             tags: policy.tags,
+            maxSnapshotBytes: policy.maxSnapshotBytes,
+            captureTimeout: policy.captureTimeout,
             buildEnv: s.resolvedBuildEnv,
             buildVersion,
             captureShellHTML,
@@ -7701,6 +7710,11 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
         const swr = swrRaw === null ? void 0 : Number(swrRaw);
         const tagsRaw = url.searchParams.get("tags");
         const tags = tagsRaw ? tagsRaw.split(",") : void 0;
+        const maxSnapshotBytesRaw = url.searchParams.get("maxSnapshotBytes");
+        const maxSnapshotBytes = maxSnapshotBytesRaw === null ? void 0 : Number(maxSnapshotBytesRaw);
+        const captureTimeout = normalizeCaptureTimeout(
+          Number(url.searchParams.get("captureTimeout"))
+        );
         const rscEnvMain = server.environments?.rsc;
         let rscRealm = null;
         let ssrRealm = null;
@@ -7750,7 +7764,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
           res.end("Shell capture registry not available");
           return;
         }
-        const cacheKey = `shell|${pathname}|r=${routeName}|t=${ttl}|s=${swr ?? ""}|g=${(tags ?? []).join("+")}|v=${version}`;
+        const cacheKey = `shell|${pathname}|r=${routeName}|t=${ttl}|s=${swr ?? ""}|g=${(tags ?? []).join("+")}|c=${captureTimeout ?? ""}|v=${version}`;
         for (const [, routerInstance] of registry) {
           if (typeof routerInstance.match !== "function") continue;
           const cached = devPrerenderCache.get(routerInstance, cacheKey);
@@ -7765,7 +7779,7 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
           try {
             const probe = await fetch(
               `${s.devServerOrigin}/__rsc_prerender?pathname=${encodeURIComponent(pathname)}&routeName=${encodeURIComponent(routeName)}`,
-              { signal: AbortSignal.timeout(1e4) }
+              { signal: AbortSignal.timeout(DEV_SHELL_PROBE_TIMEOUT_MS) }
             );
             if (!probe.ok) {
               res.statusCode = 404;
@@ -7798,6 +7812,8 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
               ttl,
               swr,
               tags,
+              maxSnapshotBytes,
+              captureTimeout,
               buildEnv: s.resolvedBuildEnv,
               buildVersion: version,
               captureShellHTML: ssrModule.captureShellHTML,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.147",
+  "version": "0.0.0-experimental.149",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/mime-routes/SKILL.md

@@ -41,26 +41,33 @@ When an API client requests the same URL (`Accept: application/json`), the JSON
 1. **Q-value priority** — higher `q` wins (`Accept: application/json;q=0.9, text/html;q=1.0` serves RSC)
 2. **Client order tiebreaker** — when q-values are equal, the type listed first in Accept wins (matches Express/Hono behavior)
 3. **Specific MIME match** — the variant whose MIME type appears in Accept wins
-4. **Wildcard / empty Accept** — `*/*` and missing Accept fall back to route definition order (the first-defined variant wins)
+4. **Wildcard / empty Accept** — `*/*` and missing Accept fall back to route definition order (the first-defined variant wins); when the RSC route wins this way, it serves the HTML document
 5. **All responses** on a negotiated URL get `Vary: Accept` header, including the RSC side
 
-RSC participates as a `text/html` candidate alongside response-type variants.
-There is no special short-circuit — RSC follows the same negotiation rules as other types.
+RSC participates as a candidate alongside response-type variants under two MIME
+types: `text/html` (the document — its canonical representation) and
+`text/x-component` (the RSC flight wire format). There is no special
+short-circuit — RSC follows the same negotiation rules as other types.
 
 The MIME mapping used for matching:
 
-| Tag                  | MIME type                                                    |
-| -------------------- | ------------------------------------------------------------ |
-| RSC (plain `path()`) | `text/html` (negotiation) / `text/x-component` (wire format) |
-| `json`               | `application/json`                                           |
-| `text`               | `text/plain`                                                 |
-| `xml`                | `application/xml`                                            |
-| `html`               | `text/html`                                                  |
-| `md`                 | `text/markdown`                                              |
-
-RSC routes negotiate as `text/html` but respond with `text/x-component` (the RSC wire format).
-The browser's RSC runtime decodes this transparently — clients requesting `text/html` get
-the RSC page rendered normally.
+| Tag                  | MIME type                              |
+| -------------------- | -------------------------------------- |
+| RSC (plain `path()`) | `text/html` **and** `text/x-component` |
+| `json`               | `application/json`                     |
+| `text`               | `text/plain`                           |
+| `xml`                | `application/xml`                      |
+| `html`               | `text/html`                            |
+| `md`                 | `text/markdown`                        |
+
+Which representation an RSC win renders is decided by the same Accept header:
+the flight wire format is **explicit opt-in only** (`Accept: text/x-component`,
+or the internal `_rsc_*`/`__rsc` transport params the client runtime sends).
+Everything else — browsers, `curl` (`*/*`), a missing Accept header, mismatched
+types like `application/json` on a URL with no JSON variant — gets the HTML
+document. A generic HTTP client never sees the wire format by accident, and an
+explicit `Accept: text/x-component` selects the RSC flight stream even on a
+route where a response variant is defined first.
 
 Tags `image`, `stream`, and `any` are pass-through and do not participate in Accept matching.
 
@@ -77,11 +84,12 @@ export const urlpatterns = urls(({ path }) => [
 ]);
 ```
 
-- `Accept: text/html` — RSC page
+- `Accept: text/html` — RSC page (HTML document)
 - `Accept: application/json` — JSON handler
 - `Accept: text/plain` — text handler
 - `Accept: application/xml` — XML handler
-- `Accept: */*` — RSC page (the primary, since it was registered first)
+- `Accept: */*` — RSC page as HTML (the primary, since it was registered first)
+- `Accept: text/x-component` — RSC page as the flight wire format
 
 ## Wildcard Routes
 

package/skills/ppr/SKILL.md

@@ -171,13 +171,12 @@ auth middleware anywhere (global or route DSL) and it guards PPR for free.
 
 ## Verifying it works
 
-The header exists on DOCUMENT responses only. A bare `curl` (no `Accept`)
-content-negotiates a Flight payload (`text/x-component`) with NO
-`x-rango-shell` header at all — which reads as "PPR is off" but is only the
-wrong request shape:
+The header exists on DOCUMENT responses only. A bare `curl` gets the HTML
+document (Flight is explicit-opt-in via `Accept: text/x-component`), so it
+sees the header directly; only an explicit Flight request shape lacks it:
 
 ```
-curl -s -D - -o /dev/null -H "Accept: text/html" https://app.example.com/products/1 | grep -i x-rango-shell
+curl -s -D - -o /dev/null https://app.example.com/products/1 | grep -i x-rango-shell
 ```
 
 - First document GET: `MISS`, plus a background capture.
@@ -193,6 +192,16 @@ curl -s -D - -o /dev/null -H "Accept: text/html" https://app.example.com/product
 - 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
+  (`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
+  snapshot bytes, backoff state); pass a function to receive each
+  `ShellCaptureDebugEvent` instead. 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="…"`.
 
 ## The hole doctrine (encode this in your head)
 
@@ -505,11 +514,12 @@ path(
 );
 ```
 
-| Field  | Default | Notes                                                                                              |
-| ------ | ------- | -------------------------------------------------------------------------------------------------- |
-| `ttl`  | `300`   | shell freshness window in seconds (`ppr: true` uses the default)                                   |
-| `swr`  | —       | stale window: serve the stale shell + background recapture                                         |
-| `tags` | —       | operational tags UNIONED with the tags the capture render auto-collects — see "Invalidation" below |
+| Field              | Default | Notes                                                                                                                                                     |
+| ------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ttl`              | `300`   | shell freshness window in seconds (`ppr: true` uses the default)                                                                                          |
+| `swr`              | —       | stale window: serve the stale shell + background recapture                                                                                                |
+| `tags`             | —       | operational tags UNIONED with the tags the capture render auto-collects — see "Invalidation" below                                                        |
+| `maxSnapshotBytes` | 8 MiB   | cap on the entry's capture data snapshot; over it the snapshot is skipped (shell still stored, warned once per key) so the entry stays under store limits |
 
 The shell store is always the app-level `createRouter({ cache })` store; the
 default key is `${host}${pathname}${sortedSearch}:shell` (host-scoped so

package/src/cache/cf/cf-cache-store.ts

@@ -137,6 +137,13 @@ const warnedNoKvReadInvalidation = new Set<string>();
  */
 const warnedTagInvalidationTtlFloor = new Set<string>();
 
+/**
+ * Stores (by namespace) already warned about the shell family being inert
+ * (getShell/putShell no-op without a KV namespace), so a ppr route hitting the
+ * silent fail-open warns once per isolate instead of on every request.
+ */
+const warnedShellFamilyInert = new Set<string>();
+
 /**
  * Stores (by namespace) already warned that tag invalidation is writing KV
  * markers with no expiry (tagInvalidationTtl unset), so the unbounded-growth
@@ -1642,6 +1649,27 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   // still applies: shell entries carry tags/taggedAt and are checked against the
   // same KV markers isGloballyInvalidated() reads for every other tier.
 
+  /**
+   * Warn once per isolate that the shell family is inert: getShell/putShell
+   * are ONLY called for routes that declared the `ppr` path option, so firing
+   * here (not in the constructor) scopes the warning to apps that actually
+   * use PPR — a KV-less CFCacheStore is a perfectly fine config otherwise.
+   * Without it, the correctness-first fail-open (issue #651) is invisible:
+   * every ppr route is a permanent MISS with zero diagnostics.
+   * @internal
+   */
+  private warnShellFamilyInertOnce(): void {
+    this.warnOncePerNamespace(
+      warnedShellFamilyInert,
+      `[CFCacheStore] a ppr route resolved to this store, but no KV namespace ` +
+        `is configured, so the shell family (getShell/putShell) is a no-op: ` +
+        `every ppr route stays a permanent shell MISS (the page still serves ` +
+        `via a full render). Bind a KV namespace and pass it — ` +
+        `new CFCacheStore({ ctx, kv: env.CACHE_KV }) — or use a shell-capable ` +
+        `store via createRouter({ cache }).`,
+    );
+  }
+
   /**
    * Get a cached PPR shell entry by key from KV (no L1). Applies the KV read
    * budget, corrupt-entry eviction, hard-expiry, and tag invalidation exactly
@@ -1652,7 +1680,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   async getShell(
     key: string,
   ): Promise<{ entry: ShellCacheEntry; shouldRevalidate?: boolean } | null> {
-    if (!this.kv) return null;
+    if (!this.kv) {
+      this.warnShellFamilyInertOnce();
+      return null;
+    }
     try {
       const kvKey = this.toKVKey(`shell:${key}`);
       const { value: envelope, timedOut } =
@@ -1709,7 +1740,11 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     tags?: string[],
   ): Promise<void> {
     // KV-only tier: needs a KV namespace and waitUntil (writes are non-blocking).
-    if (!this.kv || !this.waitUntil) return;
+    if (!this.kv) {
+      this.warnShellFamilyInertOnce();
+      return;
+    }
+    if (!this.waitUntil) return;
     try {
       const ttl = resolveTtl(ttlSeconds, this.defaults, DEFAULT_FUNCTION_TTL);
       const swrWindow = resolveSwrWindow(swrSeconds, this.defaults);

package/src/index.rsc.ts

@@ -88,6 +88,12 @@ export type {
   OriginCheckPhase,
 } from "./rsc/origin-guard.js";
 
+// PPR shell-capture debug sink types (RangoOptions.debugShellCapture)
+export type {
+  ShellCaptureDebug,
+  ShellCaptureDebugEvent,
+} from "./rsc/shell-capture.js";
+
 // Server-side createLoader and redirect
 export {
   createLoader,

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

@@ -49,7 +49,9 @@ import {
  * drift from the serve-side one.
  */
 export function resolveBuildPprConfig(
-  ppr: true | { ttl?: number; swr?: number; tags?: string[] },
+  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
@@ -76,6 +78,18 @@ export interface BuildShellCaptureOptions {
   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;
   /**
@@ -183,8 +197,10 @@ async function attemptBuildCapture(
     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;

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/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/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/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) &&

package/src/rsc/rsc-rendering.ts

@@ -31,6 +31,9 @@ import { gateTransitions } from "./transition-gate.js";
 import { buildFullPayload } from "./full-payload.js";
 import {
   scheduleShellCapture,
+  resolveShellCaptureDebugSink,
+  takeCaptureDebugEventForTiming,
+  describeShellCaptureEvent,
   type ShellCaptureDescriptor,
 } from "./shell-capture.js";
 import {
@@ -140,6 +143,29 @@ async function handleRscRenderingInner<TEnv>(
       const activeNonce = nonce ?? contextGet(reqCtx._variables, nonceToken);
       const store = reqCtx._cacheStore;
       const key = buildShellKey(url);
+      // Dev Server-Timing mirror (issue #651): a capture runs AFTER its
+      // triggering response committed, so its outcome can only ride a LATER
+      // response's header. When the metrics surface is active
+      // (debugPerformance), fold the buffered terminal capture event for this
+      // key into THIS request's Server-Timing as `ppr-capture;dur=<attempt
+      // ms>;desc="<outcome + sizes + waits>"`. Consuming (read-and-clear)
+      // keeps one capture = one report. Dev-only: the buffer is only written
+      // in dev (see takeCaptureDebugEventForTiming), and production folds the
+      // whole branch away.
+      if (process.env.NODE_ENV !== "production" && reqCtx._metricsStore) {
+        const lastCapture = takeCaptureDebugEventForTiming(key);
+        if (lastCapture) {
+          appendMetric(
+            reqCtx._metricsStore,
+            "ppr:capture",
+            performance.now(),
+            lastCapture.attemptMs ?? 0,
+            undefined,
+            // attemptMs already rides as this entry's dur — drop it from desc.
+            describeShellCaptureEvent({ ...lastCapture, attemptMs: undefined }),
+          );
+        }
+      }
       if (activeNonce !== undefined) {
         // Declared intent that cannot be honored deserves a diagnostic (unlike an
         // undeclared route, which is silent): a ppr route gated off by an active
@@ -170,8 +196,16 @@ async function handleRscRenderingInner<TEnv>(
             ttl: pprConfig.ttl,
             swr: pprConfig.swr,
             tags: pprConfig.tags,
+            captureTimeout: pprConfig.captureTimeout,
             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
@@ -204,12 +238,25 @@ async function handleRscRenderingInner<TEnv>(
             );
           };
           let cached: Awaited<ReturnType<typeof store.getShell>> = null;
+          const shellReadStart = reqCtx._metricsStore ? performance.now() : 0;
           try {
             cached = await store.getShell(key);
           } catch (error) {
             // A failing store read degrades to axis 1 (MISS), never a 500.
             reportCacheError(error, "cache-read", "[ShellServe] getShell");
           }
+          if (reqCtx._metricsStore) {
+            // Raw store outcome (pre-validity-gates), so a version-mismatch
+            // lifecycle miss is still distinguishable from a store miss.
+            appendMetric(
+              reqCtx._metricsStore,
+              "ppr:shell-read",
+              shellReadStart,
+              performance.now() - shellReadStart,
+              undefined,
+              cached ? "hit" : "miss",
+            );
+          }
           if (cached && isValidShellHit(cached.entry, ctx.version)) {
             if (!hasIntactShellPayload(cached.entry)) {
               // Corrupt stored payload (undecodable prelude / unparseable
@@ -257,6 +304,8 @@ async function handleRscRenderingInner<TEnv>(
                   ttl: pprConfig.ttl,
                   swr: pprConfig.swr,
                   tags: pprConfig.tags,
+                  maxSnapshotBytes: pprConfig.maxSnapshotBytes,
+                  captureTimeout: pprConfig.captureTimeout,
                 }
               : undefined,
           );