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

package/src/rsc/shell-serve.ts

@@ -30,11 +30,47 @@ export const SHELL_STATUS_HEADER = "x-rango-shell";
  */
 export const DEFAULT_PPR_TTL_SECONDS = 300;
 
+/**
+ * Timeout for the dev /__rsc_shell endpoint's sequential /__rsc_prerender
+ * pre-flight probe (vite/router-discovery.ts). Hoisted here so the client-side
+ * fetch bound (shell-build-manifest.ts devShellFetchTimeoutMs) enumerates the
+ * SAME term of the endpoint's worst-case envelope — the two cannot drift.
+ */
+export const DEV_SHELL_PROBE_TIMEOUT_MS: number = 10_000;
+
 /** The route's ppr option normalized to a concrete policy. */
 export interface ResolvedPprConfig {
   ttl: number;
   swr?: number;
   tags?: string[];
+  /**
+   * Snapshot size cap, passed through undefaulted (like swr/tags): the single
+   * defaulting site is captureAndStoreShell (DEFAULT_PPR_MAX_SNAPSHOT_BYTES in
+   * shell-capture.ts), so direct descriptor callers and resolved configs
+   * cannot drift.
+   */
+  maxSnapshotBytes?: number;
+  /**
+   * Capture settle budget in ms (`ppr.captureTimeout`). Undefined = the
+   * capture default (SHELL_CAPTURE_MAX_WAIT_MS, 15_000) — the default's single
+   * owner stays shell-capture.ts so build/runtime producers cannot drift.
+   */
+  captureTimeout?: number;
+}
+
+/**
+ * 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.
+ * 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),
+ * whose param crossed an HTTP query string.
+ */
+export function normalizeCaptureTimeout(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 1
+    ? value
+    : undefined;
 }
 
 /**
@@ -42,6 +78,12 @@ export interface ResolvedPprConfig {
  * route does not declare `ppr` (or declares `ppr: false`) — the caller then does
  * NOTHING: no store read, no capture, no logs. Pure axis 1, zero cost.
  *
+ * The route's NAME is irrelevant here (and everywhere on the shell lane):
+ * nameless `path()` routes register their EntryData under a synthesized
+ * `$path_*` manifest key with the `ppr` option intact (urls/path-helper.ts),
+ * so a nameless entry resolves exactly like a named one — pinned by the
+ * nameless-ppr e2e in both apps (issue #714).
+ *
  * PPR is a DOCUMENT-level property of the page route; there is no subtree
  * inheritance (declaring it on a layout is not supported — a follow-up).
  */
@@ -56,6 +98,8 @@ export function resolvePprConfig(
     ttl: ppr.ttl ?? DEFAULT_PPR_TTL_SECONDS,
     swr: ppr.swr,
     tags: ppr.tags,
+    maxSnapshotBytes: ppr.maxSnapshotBytes,
+    captureTimeout: normalizeCaptureTimeout(ppr.captureTimeout),
   };
 }
 

package/src/rsc/ssr-setup.ts

@@ -11,6 +11,11 @@ import type { SSRModule } from "./types.js";
 import type { SSRStreamMode } from "../router/router-options.js";
 import type { MetricsStore } from "../server/context.js";
 import { appendMetric } from "../router/metrics.js";
+import {
+  parseAcceptTypes,
+  prefersFlightRepresentation,
+  RSC_WIRE_MIME,
+} from "../router/content-negotiation.js";
 import { _getRequestContext } from "../server/request-context.js";
 
 export type SSRSetup = readonly [SSRModule, SSRStreamMode];
@@ -90,12 +95,42 @@ export function getSSRSetup<TEnv>(
   );
 }
 
+/**
+ * Accept-based flight opt-in: the client explicitly listed the RSC wire
+ * format (text/x-component) in Accept, ranked above the HTML document, and
+ * did not override with __html.
+ *
+ * The flight stream is an internal transport representation — it is served
+ * ONLY on explicit opt-in (this Accept value, or the _rsc_ / __rsc transport
+ * params). Everything else (missing Accept, wildcards, application/json,
+ * browser Accept strings) gets the HTML document, per RFC 9110: a missing
+ * Accept is equivalent to a full wildcard, and a wildcard gets the server's
+ * canonical representation. The old rule ("no text/html substring → flight")
+ * handed the wire format to every generic client — curl, health checks,
+ * link unfurlers.
+ *
+ * The includes() guard is a parse-skipping fast path: the bulk of traffic
+ * (browsers, curl, monitors) never mentions the wire format and pays no
+ * parseAcceptTypes allocation. Ranking lives in prefersFlightRepresentation
+ * (router/content-negotiation.ts), co-located with the candidate MIME set.
+ */
+function acceptsFlightExplicitly(request: Request, url: URL): boolean {
+  if (url.searchParams.has("__html")) return false;
+  const accept = request.headers.get("accept");
+  if (accept === null || !accept.includes(RSC_WIRE_MIME)) return false;
+  return prefersFlightRepresentation(parseAcceptTypes(accept));
+}
+
 /**
  * Classify whether a request may require SSR (HTML rendering).
  *
- * Returns false for requests that are definitively RSC-only, loader fetches,
- * prerender collection, or Accept-based RSC (no text/html). This mirrors
- * the isRscRequest decision in rsc-rendering.ts.
+ * Returns false for requests that are definitively RSC-only: transport
+ * params (partial/action/loader/__rsc), prerender collection, or an explicit
+ * Accept: text/x-component. Must never return false for a request whose
+ * render-time decision (isRscRequest) will be HTML — the two share
+ * acceptsFlightExplicitly so the Accept rule cannot drift. document-cache.ts
+ * keys its HTML/RSC response slots off this function, so any divergence from
+ * the render decision poisons a cache slot with the wrong representation.
  *
  * Note: response/mime routes are excluded by the caller — this function
  * runs after classifyRequest() determines the request mode.
@@ -112,24 +147,21 @@ export function mayNeedSSR(request: Request, url: URL): boolean {
     return false;
   }
 
-  // Mirror the Accept-based RSC decision from rsc-rendering.ts:
-  // if Accept is present and does not include text/html (and no __html override),
-  // the response will be RSC, not HTML.
-  const accept = request.headers.get("accept");
-  if (
-    accept &&
-    !accept.includes("text/html") &&
-    !url.searchParams.has("__html")
-  ) {
-    return false;
-  }
-
-  return true;
+  return !acceptsFlightExplicitly(request, url);
 }
 
-// Final render-time decision: is the response an RSC stream (vs HTML)? Distinct
-// from mayNeedSSR, which is a conservative pre-classifier (it treats a missing
-// Accept header as needing SSR; this treats it as RSC).
+// Final render-time decision: is the response an RSC stream (vs HTML)?
+// Flight requires explicit opt-in: the partial transport param, __rsc, or
+// Accept: text/x-component. mayNeedSSR is the coarse pre-filter over the
+// transport params; both delegate the Accept call to acceptsFlightExplicitly.
+//
+// _rsc_partial is read from the URL in addition to the plan-derived isPartial
+// flag: the 404 fallback plan hardcodes mode "full-render" even for partial
+// navigations (handler.ts RouteNotFoundError catch), so a partial 404 reaches
+// this decision with isPartial=false. The old Accept rule masked that by
+// classifying */* as flight; without the URL check a client-side navigation
+// to a missing route received an HTML 404 it cannot apply, and the
+// navigation never committed (multi-router soft-404, popstate not-found).
 export function isRscRequest(
   request: Request,
   url: URL,
@@ -137,8 +169,8 @@ export function isRscRequest(
 ): boolean {
   return (
     isPartial ||
-    (!request.headers.get("accept")?.includes("text/html") &&
-      !url.searchParams.has("__html")) ||
-    url.searchParams.has("__rsc")
+    url.searchParams.has("_rsc_partial") ||
+    url.searchParams.has("__rsc") ||
+    acceptsFlightExplicitly(request, url)
   );
 }

package/src/server/context.ts

@@ -27,6 +27,7 @@ export interface PerformanceMetric {
   duration: number; // milliseconds
   startTime: number; // relative to request start
   depth?: number; // nesting level for hierarchical display (0 = top-level)
+  desc?: string; // free-form outcome detail, emitted as Server-Timing desc="..."
 }
 
 /**

package/src/ssr/index.tsx

@@ -2,6 +2,7 @@ import React from "react";
 import { createSsrRootComponent } from "./ssr-root.js";
 import { injectRSCPayloadEager } from "./inject-rsc-eager.js";
 import { runWithPreinitNonce } from "./preinit-client-references.js";
+import { SHELL_CAPTURE_MAX_WAIT_MS } from "../rsc/shell-capture-constants.js";
 import type { ErrorPhase } from "../types.js";
 import type { HeadScriptsOption } from "../vite/plugin-types.js";
 
@@ -181,15 +182,6 @@ export interface SSRDependencies<TEnv = unknown> {
   onError?: (error: Error, context: { phase: ErrorPhase }) => void;
 }
 
-/**
- * Default guard for how long capture waits on the caller's `quiesce` signal
- * before forcing the abort that freezes the shell. This is the ONLY wall-clock
- * on the capture path and it is a pathological guard — it should never fire once
- * the caller's `quiesce` is a task-quantized, frozen-byte signal (the capture
- * gate in shell-capture.ts). See docs/design/ppr-shell-resume.md.
- */
-const DEFAULT_SHELL_CAPTURE_MAX_WAIT_MS = 5000;
-
 /**
  * Fixed number of macrotask hops between `quiesce` resolving and the abort. These
  * give React's fizz worker turns to flush the settled shell into the prelude and
@@ -258,6 +250,38 @@ function createCancelableTimeout(ms: number): {
   return { promise, cancel: () => clearTimeout(id) };
 }
 
+/**
+ * True when a debugger is attached outside a production build: a breakpoint
+ * pauses script execution but not wall-clock, so the capture deadline would
+ * expire mid-inspection and push the key into refusal/backoff while debugging.
+ * Next.js precedent (packages/next/src/export/worker.ts): its static-page
+ * timeout race is disabled when NODE_OPTIONS contains --inspect. The gate is
+ * the bare `process.env.NODE_ENV !== "production"` token — the build define
+ * folds exactly that token to a literal (same dev signal as shell-capture.ts's
+ * isDevMode), and it covers dev servers that never set NODE_ENV, the common
+ * debug case. A production worker launched with --inspect in NODE_OPTIONS
+ * keeps the capture's safety bound unconditionally. Every probe is guarded:
+ * `process` reads are optional-chained and the node:inspector import is
+ * try/caught, so non-Node runtimes (workerd) resolve to false instead of
+ * breaking.
+ */
+export async function isDebuggerAttached(): Promise<boolean> {
+  if (process.env.NODE_ENV === "production") return false;
+  try {
+    // Substring match also catches --inspect-brk / --inspect=PORT.
+    if (globalThis.process?.env?.NODE_OPTIONS?.includes("--inspect")) {
+      return true;
+    }
+    if (globalThis.process?.execArgv?.some((a) => a.startsWith("--inspect"))) {
+      return true;
+    }
+    const inspector = await import("node:inspector");
+    return inspector.url() !== undefined;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Drain a ReadableStream fully into a single Uint8Array. Capture buffers the
  * whole prelude so it can be stored and later prepended byte-for-byte.
@@ -321,7 +345,7 @@ function createDataVariantHtmlStream(): ReadableStream<Uint8Array> {
 interface ShellCaptureOptions {
   /** Caller-provided promise that resolves once the cached content settled. */
   quiesce: Promise<void>;
-  /** Upper bound on how long to wait for `quiesce`. Default 5000ms. */
+  /** Upper bound on how long to wait for `quiesce`. Default SHELL_CAPTURE_MAX_WAIT_MS. */
   maxWaitMs?: number;
 }
 
@@ -509,7 +533,7 @@ export function createShellCaptureHandler<TEnv = unknown>(
     rscStream: ReadableStream<Uint8Array>,
     opts: ShellCaptureOptions,
   ): Promise<ShellCaptureResult | null> {
-    const maxWaitMs = opts.maxWaitMs ?? DEFAULT_SHELL_CAPTURE_MAX_WAIT_MS;
+    const maxWaitMs = opts.maxWaitMs ?? SHELL_CAPTURE_MAX_WAIT_MS;
 
     // Arm the maxWaitMs deadline BEFORE the first await so it bounds the ENTIRE
     // capture, the bootstrap-script load included. loadBootstrapScriptContent()
@@ -517,7 +541,13 @@ export function createShellCaptureHandler<TEnv = unknown>(
     // captureShellHTML with no upper bound and held the background capture task
     // open. One deadline, shared by the bootstrap race below and the quiesce
     // race, keeps the whole path "bounded by maxWaitMs like every quiesce input".
-    const deadline = createCancelableTimeout(maxWaitMs);
+    // Debugger attached (non-production, see isDebuggerAttached): a paused process
+    // must not burn the budget, so the deadline becomes a never-resolving
+    // promise (the Next.js approach) — no timer, so it cannot hold the event
+    // loop open either.
+    const deadline = (await isDebuggerAttached())
+      ? { promise: new Promise<void>(() => {}), cancel: () => {} }
+      : createCancelableTimeout(maxWaitMs);
     try {
       // No nonce (nonce'd requests never reach capture); no formState.
       // payloadSettled: fires when the Flight payload root settles — i.e.

package/src/urls/pattern-types.ts

@@ -62,6 +62,35 @@ export interface PartialPrerenderProps {
    * capture render auto-collects (the shell's own non-loader request tags).
    */
   tags?: string[];
+  /**
+   * Upper bound (serialized UTF-8 bytes) on the capture data snapshot riding
+   * inside the shell entry. The snapshot duplicates every cache-store value
+   * the capture pinned, so a page over a large cache() segment can push the
+   * entry toward store value limits (Cloudflare KV caps a value at 25 MiB).
+   * Over the cap the snapshot is skipped: the shell is still stored and
+   * served, but pinned reads fall back to the live store, so drifted cached
+   * content can hydration-mismatch and be repaired client-side (the
+   * pre-snapshot behavior). Reported once per key. Defaults to 8 MiB.
+   */
+  maxSnapshotBytes?: number;
+  /**
+   * Capture settle budget in MILLISECONDS (default 15000). Bounds the whole
+   * background capture: the wait for deferred shell material — top-level
+   * pushed handle promises (`ctx.use(Meta)(promise.then(...))` and friends)
+   * are AWAITED and their settled values baked into the stored shell — AND
+   * the fizz prerender deadline. Declare it to tighten the budget below the
+   * default or when a route's shell material takes longer than 15s to
+   * settle. A budget that expires with pushes still pending REFUSES the
+   * capture (the route stays MISS with the once-per-key warning) — a shell
+   * with missing head material is never stored. Capture is background work
+   * (waitUntil), so a longer budget costs latency-to-HIT only, never a served
+   * response; the platform waitUntil lifetime (workerd: ~30s past response
+   * completion) is the physical ceiling — the default's derivation lives in
+   * docs/design/ppr-shell-resume.md (Cost model). Build-time captures
+   * (Prerender+ppr, producer B) honor the same budget with no platform
+   * ceiling. Non-finite or sub-1ms values fall back to the default.
+   */
+  captureTimeout?: number;
 }
 
 export interface PathOptions<

package/src/vite/discovery/shell-prerender-phase.ts

@@ -243,6 +243,8 @@ export async function runShellPrerenderPhase(
             ttl: policy.ttl,
             swr: policy.swr,
             tags: policy.tags,
+            maxSnapshotBytes: policy.maxSnapshotBytes,
+            captureTimeout: policy.captureTimeout,
             buildEnv: s.resolvedBuildEnv,
             buildVersion,
             captureShellHTML,

package/src/vite/discovery/state.ts

@@ -73,7 +73,9 @@ export interface ShellPrerenderCandidate {
   urlPath: string;
   routeName: string;
   paramHash: string;
-  ppr: true | { ttl?: number; swr?: number; tags?: string[] };
+  ppr:
+    | true
+    | { ttl?: number; swr?: number; tags?: string[]; captureTimeout?: number };
 }
 
 export interface DiscoveryState {

package/src/vite/router-discovery.ts

@@ -19,6 +19,10 @@ import {
   createScanFilter,
 } from "../build/generate-route-types.js";
 import { firstCodeMatchIndex } from "../build/route-types/source-scan.js";
+import {
+  DEV_SHELL_PROBE_TIMEOUT_MS,
+  normalizeCaptureTimeout,
+} from "../rsc/shell-serve.js";
 import {
   injectClientDebugFlag,
   internalDebugNoCacheMiddleware,
@@ -1144,6 +1148,18 @@ export function createRouterDiscoveryPlugin(
         const swr = swrRaw === null ? undefined : Number(swrRaw);
         const tagsRaw = url.searchParams.get("tags");
         const tags = tagsRaw ? tagsRaw.split(",") : undefined;
+        const maxSnapshotBytesRaw = url.searchParams.get("maxSnapshotBytes");
+        const maxSnapshotBytes =
+          maxSnapshotBytesRaw === null
+            ? undefined
+            : Number(maxSnapshotBytesRaw);
+        // Boundary revalidation via the SHARED normalizer (shell-serve.ts):
+        // the param crossed an HTTP query string, and a garbage value must
+        // fall back to the capture default, never reach setTimeout as NaN
+        // (which Node clamps to ~1ms — an instant abort).
+        const captureTimeout = normalizeCaptureTimeout(
+          Number(url.searchParams.get("captureTimeout")),
+        );
 
         // Resolve the capture realms: main-server envs (Node preset) or the
         // shared temp Node server (Cloudflare preset — no main RSC runner).
@@ -1205,7 +1221,7 @@ export function createRouterDiscoveryPlugin(
         // (this fetch blocks a foreground document request), and the memoized
         // body needs neither the pre-flight round-trip nor a capture. Keyed
         // per router instance (= HMR generation) like the prerender memo.
-        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);
@@ -1224,7 +1240,7 @@ export function createRouterDiscoveryPlugin(
           try {
             const probe = await fetch(
               `${s.devServerOrigin}/__rsc_prerender?pathname=${encodeURIComponent(pathname)}&routeName=${encodeURIComponent(routeName)}`,
-              { signal: AbortSignal.timeout(10_000) },
+              { signal: AbortSignal.timeout(DEV_SHELL_PROBE_TIMEOUT_MS) },
             );
             if (!probe.ok) {
               res.statusCode = 404;
@@ -1258,6 +1274,8 @@ export function createRouterDiscoveryPlugin(
               ttl,
               swr,
               tags,
+              maxSnapshotBytes,
+              captureTimeout,
               buildEnv: s.resolvedBuildEnv,
               buildVersion: version,
               captureShellHTML: ssrModule.captureShellHTML,