@rangojs/router 0.0.0-experimental.148 → 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.148",
+  version: "0.0.0-experimental.149",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

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

package/src/rsc/shell-capture-constants.ts

@@ -0,0 +1,27 @@
+/**
+ * Default upper bound on the capture prerender wait before forcing the abort
+ * that freezes the shell — the ONLY wall-clock on the capture path, and 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).
+ *
+ * Leaf module on purpose (imports nothing): shell-capture.ts re-exports it
+ * (single import site for the rsc graph — shell-build-manifest.ts sizes the
+ * dev fetch envelope from that re-export) and ssr/index.tsx uses it as
+ * captureShellHTML's own fallback; the ssr graph must not pull the capture
+ * orchestration module for one number.
+ *
+ * 15s, raised from 5s: captures are background work (waitUntil), so the budget
+ * costs latency-to-HIT only — never a served response — and 5s spuriously
+ * refused legitimately-slow deferred shell material (a real storefront's meta
+ * chains settle at ~7s). Ceiling math: workerd's waitUntil lifetime is ~30s
+ * past response completion, and a guaranteed two-attempt envelope needs
+ * 2x budget + the in-place retry delay + store I/O, i.e. budget <= ~14s. The
+ * 15s default deliberately sits just past that: attempt 1 always gets its
+ * full 15s, but when it consumed the whole budget the in-place RETRY may be
+ * truncated by the platform kill on workerd — degrading to the existing
+ * best-effort contract (the key stays MISS; a later request re-captures).
+ * Node/dev and build-time captures have no waitUntil ceiling. The per-route
+ * `ppr.captureTimeout` knob remains for tightening below the default. See
+ * docs/design/ppr-shell-resume.md (Cost model).
+ */
+export const SHELL_CAPTURE_MAX_WAIT_MS = 15_000;

package/src/rsc/shell-capture.ts

@@ -21,6 +21,7 @@ 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 { 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";
 import {
@@ -80,11 +81,12 @@ import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
 const FLIGHT_QUIET_HOPS = 2;
 
 /**
- * Default upper bound on the capture prerender wait before forcing the abort.
- * Single owner of the default budget — shell-build-manifest.ts imports it so
- * the dev fetch bound's envelope math cannot drift from the capture.
+ * Default capture budget. Canonical value, raise rationale, and ceiling math
+ * live on the leaf module (shell-capture-constants.ts, importable from the ssr
+ * graph too). Re-exported here so shell-build-manifest.ts's envelope math
+ * keeps its existing import site and cannot drift from the capture.
  */
-export const SHELL_CAPTURE_MAX_WAIT_MS = 5000;
+export { SHELL_CAPTURE_MAX_WAIT_MS };
 
 /**
  * Upper bound on waiting for the capture's DEFERRED cache writes to settle before
@@ -807,7 +809,7 @@ export interface ShellCaptureDescriptor {
    * bounding the whole capture, so it covers BOTH the fizz prerender AND the
    * deferred-material settle window (the handlesBaked/loader-container
    * holdUntil that keeps the gate from freezing while top-level pushes are
-   * pending). Undefined = SHELL_CAPTURE_MAX_WAIT_MS (5000).
+   * pending). Undefined = SHELL_CAPTURE_MAX_WAIT_MS (15_000).
    */
   captureTimeout?: number;
   store?: SegmentCacheStore<any>;

package/src/rsc/shell-serve.ts

@@ -52,7 +52,7 @@ export interface ResolvedPprConfig {
   maxSnapshotBytes?: number;
   /**
    * Capture settle budget in ms (`ppr.captureTimeout`). Undefined = the
-   * capture default (SHELL_CAPTURE_MAX_WAIT_MS, 5000) — the default's single
+   * 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;

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

@@ -74,19 +74,21 @@ export interface PartialPrerenderProps {
    */
   maxSnapshotBytes?: number;
   /**
-   * Capture settle budget in MILLISECONDS (default 5000). Bounds the whole
+   * 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 when a route's shell material
-   * takes longer than 5s 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. 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.
+   * 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;
 }