@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.1

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,
@@ -33,6 +34,9 @@ import type {
 import type { RouteMatchResult } from "./pattern-matching.js";
 
 export interface PrerenderMatchDeps<TEnv = any> {
+  /** Owning router id; scopes bake-time root-scope/search-schema lookups the
+   *  same way reqCtx._routerId does at runtime (issue #762). */
+  routerId?: string;
   findMatch: (
     pathname: string,
   ) => RouteMatchResult<TEnv> | null | Promise<RouteMatchResult<TEnv> | null>;
@@ -74,6 +78,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);
@@ -198,6 +209,11 @@ export async function matchForPrerender<TEnv = any>(
       pathname,
       searchParams: new URLSearchParams(),
       _variables: variables,
+      build: true,
+      // Inert here: the prerender-collect / static-render pass has no live
+      // PPR-shell decision to gate; dynamic() reaches the shell axis only on a
+      // live request or a shell capture.
+      dynamic: () => {},
       get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
       set: ((keyOrVar: any, value: any) => {
         contextSet(variables, keyOrVar, value);
@@ -231,8 +247,13 @@ export async function matchForPrerender<TEnv = any>(
         deps.mergedRouteMap,
         matched.routeKey,
         matchedParams,
-        matched.routeKey ? isRouteRootScoped(matched.routeKey) : undefined,
+        matched.routeKey
+          ? isRouteRootScoped(matched.routeKey, deps.routerId)
+          : undefined,
       ),
+      // Scope the bake context's own lookups (createPrerenderContext reads it
+      // through the request ALS) per router as well.
+      _routerId: deps.routerId,
     };
 
     return runWithRequestContext(minimalRequestContext, async () => {
@@ -306,6 +327,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 +453,7 @@ export async function matchForPrerender<TEnv = any>(
         params: matchedParams,
         interceptSegments,
         interceptHandles,
+        ppr: routePpr,
       };
     });
   });
@@ -438,6 +472,8 @@ export async function renderStaticSegment<TEnv = any>(
   routeName?: string,
   buildEnv?: TEnv,
   devMode?: boolean,
+  routerId?: string,
+  rootScoped?: boolean,
 ): Promise<{ encoded: string; handles: string } | null> {
   const syntheticUrl = new URL("http://prerender/");
   const syntheticRequest = new Request(syntheticUrl);
@@ -455,6 +491,8 @@ export async function renderStaticSegment<TEnv = any>(
     pathname: "/",
     searchParams: syntheticUrl.searchParams,
     _variables: {},
+    build: true,
+    dynamic: () => {},
     get: () => undefined as any,
     set: () => {},
     params: {},
@@ -486,8 +524,15 @@ export async function renderStaticSegment<TEnv = any>(
       mergedRouteMap,
       routeName,
       {},
-      routeName ? isRouteRootScoped(routeName) : undefined,
+      // Def-stamped value first: the collector passes the mount-time
+      // root-scope captured on the Static definition (stampStaticDefScope),
+      // which needs no registry lookup and survives name-prefix arguments.
+      rootScoped ??
+        (routeName ? isRouteRootScoped(routeName, routerId) : undefined),
     ),
+    // Scope the bake context's own lookups (createStaticContext reads it
+    // through the request ALS) per router as well.
+    _routerId: routerId,
   };
 
   return runWithRequestContext(minimalRequestContext, async () => {

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
@@ -359,12 +366,6 @@ export interface RangoInternal<
    */
   readonly telemetry?: TelemetrySink;
 
-  /**
-   * Whether ?__debug_manifest is allowed in production.
-   * Always enabled in development.
-   */
-  readonly allowDebugManifest: boolean;
-
   /**
    * Resolved timeout configuration (merged from shorthand + structured).
    */
@@ -418,6 +419,9 @@ export interface RangoInternal<
   /** @internal basename for runtime manifest generation */
   readonly __basename?: string;
 
+  /** @internal Cloudflare dev worker generation captured at construction. */
+  readonly __devDiscoveryEpoch?: number;
+
   /**
    * @internal Router-level error/notFound fallbacks (`createRouter` options),
    * exposed for the build-time clientChunks discovery so a `"use client"`
@@ -468,6 +472,7 @@ export interface RangoInternal<
     routeName?: string,
     buildEnv?: any,
     devMode?: boolean,
+    rootScoped?: boolean,
   ): Promise<{ encoded: string; handles: string } | null>;
 
   /**

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";
@@ -125,14 +126,6 @@ export interface RangoOptions<TEnv = any> {
    */
   debugPerformance?: boolean;
 
-  /**
-   * Allow the `?__debug_manifest` query parameter to return route manifest data as JSON.
-   * In development mode this is always enabled regardless of this setting.
-   * Defaults to false. Set to true to enable in production.
-   * @internal
-   */
-  allowDebugManifest?: boolean;
-
   /**
    * DEVELOPMENT/TEST ONLY. Emit an `X-Rango-Cache` response header describing
    * the cache status of the matched route, for use by testing primitives such
@@ -148,6 +141,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/segment-resolution/fresh.ts

@@ -40,6 +40,8 @@ import {
   track,
   RangoContext,
   runInsideLoaderScope,
+  latchCachedHeaderScope,
+  latchPprHeaderScopeForEntries,
 } from "../../server/context.js";
 
 // ---------------------------------------------------------------------------
@@ -650,6 +652,12 @@ export async function resolveAllSegments<TEnv>(
   const allSegments: ResolvedSegment[] = [];
   const seenIds = new Set<string>();
 
+  // ppr routes are document-scoped cached territory: the whole chain (root
+  // layout down to the page) bakes into the shared shell, so the header-write
+  // guard latches BEFORE any entry resolves (unlike the positional cache()
+  // latch below). See assertCachedHeaderWriteAllowed (server/context.ts).
+  latchPprHeaderScopeForEntries(entries, routeKey);
+
   // Safe request access: during build-time prerendering, context.request
   // is a throwing getter. Use undefined when unavailable.
   let safeRequest: Request | undefined;
@@ -665,11 +673,13 @@ export async function resolveAllSegments<TEnv>(
 
   for (const entry of entries) {
     // Set ALS flag when entering a cache() boundary so that ctx.get()
-    // can guard non-cacheable variable reads. Also guards response-level
-    // side effects (headers.set). Persists for all descendant entries.
+    // can guard non-cacheable variable reads. Also latch the header-write
+    // scope (response-level side effects — headers/cookies/status).
+    // Persists for all descendant entries.
     if (entry.type === "cache") {
       const store = RangoContext.getStore();
       if (store) store.insideCacheScope = true;
+      latchCachedHeaderScope("cache", routeKey);
     }
     const doneEntry = track(`segment:${entry.id}`, 1);
     const resolvedSegments = await resolveWithErrorBoundary(
@@ -718,6 +728,15 @@ export async function resolveLoadersOnly<TEnv>(
   const loaderSegments: ResolvedSegment[] = [];
   const seenIds = new Set<string>();
 
+  // Loader-only serves (cached non-loader segments) still run loaders live —
+  // on a ppr route their header writes are dead letters (headers flushed with
+  // the shell), so the guard latches here too. cache() needs no latch: loader
+  // writes are exempt under cache() (see assertCachedHeaderWriteAllowed).
+  latchPprHeaderScopeForEntries(
+    entries,
+    (context as InternalHandlerContext<any, TEnv>)._routeName,
+  );
+
   async function collectEntryLoaders(
     entry: EntryData,
     belongsToRoute: boolean,

package/src/router/segment-resolution/helpers.ts

@@ -71,7 +71,7 @@ export function buildLoaderErrorContext<TEnv>(
  * the short-circuit mechanism. Otherwise return the ReactNode.
  */
 export function handleHandlerResult(
-  result: ReactNode | Response | Promise<ReactNode> | Promise<Response>,
+  result: ReactNode | Response | Promise<ReactNode | Response>,
 ): ReactNode {
   if (result instanceof Response) {
     throw result;

package/src/router/segment-resolution/loader-cache.ts

@@ -185,14 +185,45 @@ export function resolveLoaderData<TEnv>(
   if (bakeSegmentKey) {
     const seed = reqCtx?._shellLoaderSeed;
     if (seed && seed.has(bakeSegmentKey)) {
-      const recorded = seed.get(bakeSegmentKey);
-      // HIT tail: run fresh (only the loader body can mint the live nested
-      // promises), then pin the recorded paths over it. A fresh REJECTION here
-      // skips the overlay and flows to the per-loader error boundary — the
-      // payload then diverges from the prelude (same residual class as uncached
-      // nondeterminism in shell material).
+      const recorded = seed.get(bakeSegmentKey)!;
+      if (!recorded.holes) {
+        // Pin-first (hole-free record): the pinned container is what the
+        // payload serves either way (recorded paths win wholesale), so
+        // resolve it immediately instead of gating on the fresh run's
+        // latency — a slow bake-lane loader body otherwise stalls the HIT
+        // tail for values that get discarded. The fresh run still executes
+        // for its side effects and cache read-through writes, lifetime-
+        // extended so the runtime cannot cancel it when the stream closes
+        // first; its rejection is swallowed here (the payload already
+        // matches the prelude, which a fresh error value never could).
+        //
+        // CONTRACT (deliberate divergence from the gated overlay's
+        // fresh-only-keys passthrough): a hole-free pin serves the pinned
+        // SHAPE wholesale — a key the fresh run adds mid-TTL is dropped.
+        // It could never render server-side anyway: no hole was postponed
+        // for it at capture, so the prelude froze the without-that-field
+        // branch and the resume pass has nothing to fill; passing it
+        // through only made the hydration payload disagree with the frozen
+        // prelude (client-side mismatch repair — the divergence class the
+        // snapshot exists to prevent). A field that is per-request must be
+        // promise-shaped at capture (masked -> hole marker -> holes: 1 ->
+        // the gated path below, which preserves fresh-only passthrough) or
+        // live behind loading(). Anything else is uncached nondeterminism
+        // in shell material — the documented drift residual.
+        const fresh = executeLoaderData(loaderEntry, ctx, pathname);
+        fresh.catch(() => {});
+        reqCtx?.executionContext?.waitUntil?.(fresh);
+        return Promise.resolve(
+          overlayLoaderContainer(undefined, recorded.container),
+        );
+      }
+      // Hole-carrying record: run fresh (only the loader body can mint the
+      // live nested promises), then pin the recorded paths over it. A fresh
+      // REJECTION here skips the overlay and flows to the per-loader error
+      // boundary — the payload then diverges from the prelude (same residual
+      // class as uncached nondeterminism in shell material).
       return executeLoaderData(loaderEntry, ctx, pathname).then(
-        (fresh: unknown) => overlayLoaderContainer(fresh, recorded),
+        (fresh: unknown) => overlayLoaderContainer(fresh, recorded.container),
       );
     }
   }

package/src/router/segment-resolution/mask-nested.ts

@@ -51,11 +51,27 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
  * rule, semantic-matrix PPR3) shares the raw container and must keep real
  * values. Cycles are preserved as cycles in the copy.
  */
+/**
+ * Optional single-walk report for maskNestedContainerThenables: `thenable`
+ * flips true when the walk masked at least one thenable. The shell fast path
+ * reads it at handle-push time — a pushed container with a nested thenable
+ * declares per-request data, and a shell entry whose HANDLER layer made such
+ * a declaration cannot be served handler-free (the hole would never fill).
+ * Same single-pass shape as elideLoaderContainer's `hasHole`.
+ */
+export interface MaskReport {
+  thenable: boolean;
+}
+
 export function maskNestedContainerThenables(
   value: unknown,
   seen: Map<object, unknown> = new Map(),
+  report?: MaskReport,
 ): unknown {
-  if (isThenable(value)) return createMaskedLoaderPromise();
+  if (isThenable(value)) {
+    if (report) report.thenable = true;
+    return createMaskedLoaderPromise();
+  }
 
   if (Array.isArray(value)) {
     const cached = seen.get(value);
@@ -63,7 +79,7 @@ export function maskNestedContainerThenables(
     const out: unknown[] = new Array(value.length);
     seen.set(value, out);
     for (let i = 0; i < value.length; i++) {
-      out[i] = maskNestedContainerThenables(value[i], seen);
+      out[i] = maskNestedContainerThenables(value[i], seen, report);
     }
     return out;
   }
@@ -74,7 +90,7 @@ export function maskNestedContainerThenables(
     const out: Record<string, unknown> = {};
     seen.set(value, out);
     for (const key of Object.keys(value)) {
-      out[key] = maskNestedContainerThenables(value[key], seen);
+      out[key] = maskNestedContainerThenables(value[key], seen, report);
     }
     return out;
   }

package/src/router/segment-resolution/revalidation.ts

@@ -50,6 +50,8 @@ import {
   track,
   RangoContext,
   runInsideLoaderScope,
+  latchCachedHeaderScope,
+  latchPprHeaderScopeForEntries,
 } from "../../server/context.js";
 
 /**
@@ -250,6 +252,9 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
   const allMatchedIds: string[] = [];
   const seenIds = new Set<string>();
 
+  // ppr header-write guard latch — see resolveAllSegments (fresh.ts).
+  latchPprHeaderScopeForEntries(entries, routeKey);
+
   async function collectEntryLoaders(
     entry: EntryData,
     belongsToRoute: boolean,
@@ -1260,6 +1265,9 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
   const seenSegIds = new Set<string>();
   const seenMatchIds = new Set<string>();
 
+  // ppr header-write guard latch — see resolveAllSegments (fresh.ts).
+  latchPprHeaderScopeForEntries(entries, routeKey);
+
   const telemetry = getRouterContext()?.telemetry;
 
   for (const entry of entries) {
@@ -1283,6 +1291,7 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
     if (entry.type === "cache") {
       const store = RangoContext.getStore();
       if (store) store.insideCacheScope = true;
+      latchCachedHeaderScope("cache", routeKey);
     }
     const doneEntry = track(`segment:${entry.id}`, 1);
     const resolved = await resolveWithErrorBoundary(

package/src/router/segment-resolution/static-store.ts

@@ -11,14 +11,19 @@ import type { StaticStore } from "../../prerender/store.js";
 import type { SegmentHandleData } from "../../cache/types.js";
 
 // Lazy-initialized static store for production Static handler interception.
-// Remains undefined until first check; null means checked but no manifest.
-// When no __STATIC_MANIFEST exists (dev mode), set to null eagerly to avoid
-// the dynamic import() in ensureStaticDeps() which disrupts AsyncLocalStorage
-// in workerd/Cloudflare runtime.
-let _staticStore: StaticStore | null | undefined =
-  typeof globalThis !== "undefined" && globalThis.__STATIC_MANIFEST
-    ? undefined
-    : null;
+// undefined = not yet checked; null = checked, no manifest (dev mode, or an
+// app without Static handlers) — a permanent SYNCHRONOUS fast path: no await
+// may ever run on that path (an await per lookup disrupts AsyncLocalStorage
+// in workerd/Cloudflare runtime).
+//
+// The check happens on the FIRST LOOKUP, not at module eval: the manifest
+// loader global (__loadStaticManifestModule, bundle-postprocess.ts) is
+// assigned by the RSC entry's BODY, which runs after hoisted module imports
+// evaluate this file — an eval-time read here could never see it. The
+// pre-#760 eager `import "./__static-manifest.js"` existed precisely to beat
+// that hoisting; deferring the manifest module keeps its O(#Static handlers)
+// thunk table off the worker's cold-start path.
+let _staticStore: StaticStore | null | undefined = undefined;
 let _deserializeComponent: ((encoded: string) => Promise<unknown>) | undefined;
 let _decodeHandleValue:
   | typeof import("../../cache/handle-snapshot.js").decodeHandleValue
@@ -26,6 +31,18 @@ let _decodeHandleValue:
 
 async function ensureStaticDeps(): Promise<void> {
   if (_staticStore === undefined) {
+    // Evaluate the deferred manifest module (it assigns __STATIC_MANIFEST);
+    // support a pre-set __STATIC_MANIFEST too (tests, non-postprocess embeds).
+    if (
+      !globalThis.__STATIC_MANIFEST &&
+      globalThis.__loadStaticManifestModule
+    ) {
+      await globalThis.__loadStaticManifestModule();
+    }
+    if (!globalThis.__STATIC_MANIFEST) {
+      _staticStore = null;
+      return;
+    }
     const { createStaticStore } = await import("../../prerender/store.js");
     _staticStore = createStaticStore();
   }
@@ -52,8 +69,17 @@ export async function tryStaticLookup(
   handlerId: string,
   segmentId: string,
 ): Promise<ReactNode | undefined> {
-  // Fast path: already checked and no manifest available (dev mode or no Static handlers).
-  // Avoids await which can disrupt AsyncLocalStorage in workerd/Cloudflare runtime.
+  // Fast path: no manifest available (dev mode or no Static handlers).
+  // Latched SYNCHRONOUSLY — including on the very first call — so this path
+  // never awaits (an await here disrupts AsyncLocalStorage in
+  // workerd/Cloudflare runtime).
+  if (
+    _staticStore === undefined &&
+    !globalThis.__STATIC_MANIFEST &&
+    !globalThis.__loadStaticManifestModule
+  ) {
+    _staticStore = null;
+  }
   if (_staticStore === null) return undefined;
   await ensureStaticDeps();
   if (!_staticStore || !_deserializeComponent) return undefined;

package/src/router/telemetry-otel.ts

@@ -227,6 +227,17 @@ export function createOTelSink(tracer: OTelTracer): TelemetrySink {
           };
           if (event.routeKey) attrs["rango.route_key"] = event.routeKey;
           if (event.actionId) attrs["rango.action_id"] = event.actionId;
+          if (event.render) {
+            attrs["rango.render.mode"] = event.render.mode;
+            attrs["rango.render.phase"] = event.render.phase;
+            attrs["rango.render.state"] = event.render.state;
+            attrs["rango.render.completed"] = event.render.completed;
+            attrs["rango.render.total"] = event.render.total;
+            if (event.render.phaseDurationMs !== undefined) {
+              attrs["rango.render.phase_duration_ms"] =
+                event.render.phaseDurationMs;
+            }
+          }
           const span = instant("rango.request.timeout", attrs);
           span.setStatus({
             code: STATUS_ERROR,

package/src/router/telemetry.ts

@@ -154,6 +154,7 @@ export interface RequestTimeoutEvent extends BaseEvent {
   actionId?: string;
   durationMs: number;
   customHandler: boolean;
+  render?: import("./timeout.js").RenderTimeoutContext;
 }
 
 export interface OriginCheckRejectedEvent extends BaseEvent {

package/src/router/timeout.ts

@@ -17,6 +17,33 @@ export interface RouterTimeouts {
 
 export type TimeoutPhase = "action" | "render-start" | "stream-idle";
 
+/**
+ * Canonical render-pipeline unions, defined here (the dependency-free timeout
+ * leaf) and shared by `import type` so the render driver
+ * (rsc/render-pipeline.ts RscRenderMode/RscRenderPhase), the foreground cursor
+ * (server/request-context.ts RenderForegroundCursor), and RenderTimeoutContext
+ * below cannot drift out of sync.
+ */
+export type RenderMode =
+  | "unknown"
+  | "full"
+  | "partial"
+  | "action-revalidation"
+  | "progressive-enhancement"
+  | "progressive-enhancement-error";
+
+/** Terminal response-construction stage of the render driver. */
+export type RenderPhase = "flight" | "html" | "response";
+
+export interface RenderTimeoutContext {
+  mode: RenderMode;
+  phase: RenderPhase;
+  state: "paused" | "running";
+  completed: number;
+  total: number;
+  phaseDurationMs?: number;
+}
+
 export interface TimeoutContext<TEnv = any> {
   phase: TimeoutPhase;
   request: Request;
@@ -25,6 +52,8 @@ export interface TimeoutContext<TEnv = any> {
   routeKey?: string;
   actionId?: string;
   durationMs: number;
+  /** Foreground render operation active when a render-start timeout fired. */
+  render?: RenderTimeoutContext;
 }
 
 export type OnTimeoutCallback<TEnv = any> = (
@@ -73,6 +102,17 @@ type TimeoutResult<T> =
   | { result: T; timedOut: false }
   | { timedOut: true; durationMs: number };
 
+/**
+ * A timeout phase is active only when its budget is a positive number.
+ * `undefined`/`null` (unset) and `<= 0` (explicit opt-out, e.g.
+ * `timeouts: { renderStartMs: 0 }`) both mean pass-through. withTimeout and the
+ * render-diagnostics gate (rsc/handler.ts) share this so a disabled budget can
+ * never leave one of them still doing bookkeeping the other can never read.
+ */
+export function isTimeoutEnabled(timeoutMs: number | undefined): boolean {
+  return timeoutMs != null && timeoutMs > 0;
+}
+
 /**
  * Race an operation against a deadline.
  *
@@ -87,7 +127,7 @@ export async function withTimeout<T>(
   timeoutMs: number | undefined,
   phase: TimeoutPhase,
 ): Promise<TimeoutResult<T>> {
-  if (timeoutMs == null || timeoutMs <= 0) {
+  if (!isTimeoutEnabled(timeoutMs)) {
     return { result: await operation, timedOut: false };
   }