@timber-js/app 0.2.0-alpha.4 → 0.2.0-alpha.41

package/src/server/rsc-entry/index.ts

@@ -47,7 +47,11 @@ import { buildClientScripts } from '#/server/html-injectors.js';
 import type { InterceptionContext, PipelineConfig, RouteMatch } from '#/server/pipeline.js';
 import { createPipeline } from '#/server/pipeline.js';
 import { DenySignal, RedirectSignal } from '#/server/primitives.js';
-import { buildRouteElement, RouteSignalWithContext } from '#/server/route-element-builder.js';
+import {
+  buildRouteElement,
+  RouteSignalWithContext,
+  ParamCoercionError,
+} from '#/server/route-element-builder.js';
 import type { ManifestSegmentNode } from '#/server/route-matcher.js';
 import { createMetadataRouteMatcher, createRouteMatcher } from '#/server/route-matcher.js';
 import { initDevTracing } from '#/server/tracing.js';
@@ -61,33 +65,62 @@ import {
   createDebugChannelSink,
   escapeHtml,
   isRscPayloadRequest,
+  type DebugComponentEntry,
 } from './helpers.js';
 import { parseClientStateTree } from '#/server/state-tree-diff.js';
-import {
-  createResponseCache,
-  resolveResponseCacheConfig,
-  type ResponseCache,
-} from '#/server/response-cache.js';
 import { buildRscPayloadResponse } from './rsc-payload.js';
 import { renderRscStream } from './rsc-stream.js';
 import { renderSsrResponse } from './ssr-renderer.js';
 import { callSsr } from './ssr-bridge.js';
-import { isDebug, setDebugFromConfig } from '#/server/debug.js';
+import { isDebug, isDevMode, setDebugFromConfig } from '#/server/debug.js';
+import { recordTiming } from '#/server/server-timing.js';
+
+/**
+ * Resolve the Server-Timing mode from timber.config.ts.
+ *
+ * If the user set `serverTiming` explicitly, use that value.
+ * Otherwise: `'detailed'` in dev, `'total'` in production.
+ */
+function resolveServerTimingMode(
+  config: Record<string, unknown>,
+  isDev: boolean
+): 'detailed' | 'total' | false {
+  const userValue = config.serverTiming as 'detailed' | 'total' | false | undefined;
+  if (userValue !== undefined) return userValue;
+  return isDev ? 'detailed' : 'total';
+}
 
 // Dev-only pipeline error handler, set by the dev server after import.
 // In production this is always undefined — no overhead.
-let _devPipelineErrorHandler: ((error: Error, phase: string) => void) | undefined;
+// The third argument provides RSC debug component data (from the Flight
+// debug channel) when available — used by the error overlay to show the
+// server component tree context for render errors.
+let _devPipelineErrorHandler:
+  | ((error: Error, phase: string, debugComponents?: DebugComponentEntry[]) => void)
+  | undefined;
 
 /**
  * Set the dev pipeline error handler.
  *
  * Called by the dev server after importing this module to wire pipeline
  * errors into the Vite browser error overlay. No-op in production.
+ *
+ * The handler receives an optional third argument with RSC debug component
+ * info — component names, environments, and stack frames from the Flight
+ * debug channel. This is only populated for render-phase errors.
  */
-export function setDevPipelineErrorHandler(handler: (error: Error, phase: string) => void): void {
+export function setDevPipelineErrorHandler(
+  handler: (error: Error, phase: string, debugComponents?: DebugComponentEntry[]) => void
+): void {
   _devPipelineErrorHandler = handler;
 }
 
+// Dev-only: holds a getter for the current request's RSC debug components.
+// Updated on each renderRscStream call so the onPipelineError callback can
+// include component tree context for render-phase errors. This is request-
+// scoped by convention — each renderRoute call sets it before returning.
+let _lastDebugComponentsGetter: (() => DebugComponentEntry[]) | undefined;
+
 /**
  * Create the RSC request handler from the route manifest.
  *
@@ -101,13 +134,15 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
   // See design/17-logging.md §"register() — Server Startup"
   await loadInstrumentation(loadUserInstrumentation);
 
-  // Initialize cookie signing secrets from config (design/29-cookies.md §"Signed Cookies")
-  const cookieSecrets = (runtimeConfig as Record<string, unknown>).cookieSecrets as
-    | string[]
+  // Initialize deployment ID for version skew detection (TIM-446).
+  // The manifest init module sets globalThis.__TIMBER_DEPLOYMENT_ID__ at startup.
+  // In dev mode this is undefined — skew checks are skipped.
+  const deploymentId = (globalThis as Record<string, unknown>).__TIMBER_DEPLOYMENT_ID__ as
+    | string
     | undefined;
-  if (cookieSecrets?.length) {
-    const { setCookieSecrets } = await import('#/server/request-context.js');
-    setCookieSecrets(cookieSecrets);
+  if (deploymentId) {
+    const { setDeploymentId } = await import('#/server/version-skew.js');
+    setDeploymentId(deploymentId);
   }
 
   const matchRoute = createRouteMatcher(manifest);
@@ -127,9 +162,6 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
     buildManifest: buildManifest as BuildManifest,
   });
 
-  // Dev logging — initialize OTEL-based dev tracing once at handler creation.
-  // In production, isDev is false — no tracing, no overhead.
-  // The DevSpanProcessor handles all formatting and stderr output.
   // Initialize debug flag from config before anything else.
   // This allows timber.config.ts `debug: true` to enable debug logging
   // in production without the TIMBER_DEBUG env var.
@@ -137,10 +169,24 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
     setDebugFromConfig(true);
   }
 
-  const isDev = isDebug();
+  // Two separate flags for two different security levels:
+  //
+  // isDev (isDevMode) — gates client-visible behavior: dev error pages with
+  //   stack traces, detailed Server-Timing headers, error messages in action
+  //   payloads. Statically replaced in production → tree-shaken to zero.
+  //   TIMBER_DEBUG cannot enable this.
+  //
+  // debugEnabled (isDebug) — gates server-side logging only: stderr warnings,
+  //   OTEL dev tracing, console.error fallbacks. TIMBER_DEBUG enables this.
+  //   Never affects what clients see.
+  const isDev = isDevMode();
+  const debugEnabled = isDebug();
   const slowPhaseMs = (runtimeConfig as Record<string, unknown>).slowPhaseMs as number | undefined;
 
-  if (isDev) {
+  // Dev logging — initialize OTEL-based dev tracing once at handler creation.
+  // In production with TIMBER_DEBUG, this enables server-side tracing output
+  // without exposing anything to clients.
+  if (debugEnabled) {
     const devLogMode = resolveLogMode();
     if (devLogMode !== 'quiet') {
       await initDevTracing({ mode: devLogMode, slowPhaseMs });
@@ -153,17 +199,6 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
 
   const typedBuildManifest = buildManifest as BuildManifest;
 
-  // Initialize response-level caching and singleflight deduplication.
-  // See design/31-benchmarking.md for performance motivation.
-  const responseCacheRaw = (runtimeConfig as Record<string, unknown>).responseCache as
-    | { maxSize?: number; ttlMs?: number; publicOnly?: boolean }
-    | false
-    | undefined;
-  const responseCacheConfig = resolveResponseCacheConfig(responseCacheRaw);
-  const responseCache: ResponseCache | null = responseCacheConfig
-    ? createResponseCache(responseCacheConfig)
-    : null;
-
   const pipelineConfig: PipelineConfig = {
     proxyLoader: manifest.proxy?.load,
     matchRoute,
@@ -194,17 +229,15 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
       _requestHeaderOverlay: Headers,
       interception?: InterceptionContext
     ) => {
-      const doRender = () =>
-        renderRoute(req, match, responseHeaders, clientBootstrap, clientJsDisabled, interception);
-
-      // Response cache wraps the render with singleflight + LRU.
-      // Interception requests (modals) are excluded — they depend on
-      // X-Timber-URL which makes caching semantics ambiguous.
-      if (responseCache && !interception) {
-        const isRsc = (req.headers.get('Accept') ?? '').includes('text/x-component');
-        return responseCache.getOrRender(req, isRsc, doRender);
-      }
-      return doRender();
+      return renderRoute(
+        req,
+        match,
+        responseHeaders,
+        clientBootstrap,
+        clientJsDisabled,
+        interception,
+        manifest.root
+      );
     },
     renderNoMatch: async (req: Request, responseHeaders: Headers) => {
       return renderNoMatchPage(req, manifest.root, responseHeaders, clientBootstrap);
@@ -213,10 +246,18 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
     // Slow request threshold from timber.config.ts. Default 3000ms, 0 to disable.
     // See design/17-logging.md §"slowRequestMs"
     slowRequestMs: (runtimeConfig as Record<string, unknown>).slowRequestMs as number | undefined,
-    enableServerTiming: isDev,
+    serverTiming: resolveServerTimingMode(runtimeConfig, isDev),
     onPipelineError: isDev
       ? (error: Error, phase: string) => {
-          if (_devPipelineErrorHandler) _devPipelineErrorHandler(error, phase);
+          if (_devPipelineErrorHandler) {
+            // For render-phase errors, include RSC debug component data
+            // from the Flight debug channel (if available from the current request).
+            const debugComponents =
+              phase === 'render' && _lastDebugComponentsGetter
+                ? _lastDebugComponentsGetter()
+                : undefined;
+            _devPipelineErrorHandler(error, phase, debugComponents);
+          }
         }
       : undefined,
     renderFallbackError: (error, req, responseHeaders) =>
@@ -296,7 +337,8 @@ async function renderRoute(
   responseHeaders: Headers,
   clientBootstrap: ClientBootstrapConfig,
   clientJsDisabled: boolean,
-  interception?: InterceptionContext
+  interception?: InterceptionContext,
+  rootSegment?: ManifestSegmentNode
 ): Promise<Response> {
   const segments = match.segments as unknown as ManifestSegmentNode[];
   const leaf = segments[segments.length - 1];
@@ -318,6 +360,7 @@ async function renderRoute(
   // Build the React element tree — loads modules, runs access checks,
   // resolves metadata. DenySignal/RedirectSignal propagate for HTTP handling.
   let routeResult;
+  const _buildStart = performance.now();
   try {
     routeResult = await buildRouteElement(_req, match, interception, clientStateTree);
   } catch (error) {
@@ -350,14 +393,29 @@ async function renderRoute(
         return buildRedirectResponse(_req, signal, responseHeaders);
       }
     }
-    // No PageComponent found
+    // Param coercion failed — render the custom 404 page (status files / not-found).
+    // Previously returned a bare Response(null, { status: 404 }) which bypassed
+    // custom not-found pages. Now routes through renderNoMatchPage so apps with
+    // 404.tsx / not-found status files render their custom page.
+    if (error instanceof ParamCoercionError) {
+      return renderNoMatchPage(_req, rootSegment!, responseHeaders, clientBootstrap);
+    }
+    // No PageComponent found — same treatment as param coercion: render custom 404.
     if (error instanceof Error && error.message.startsWith('No page component')) {
-      return new Response(null, { status: 404 });
+      return renderNoMatchPage(_req, rootSegment!, responseHeaders, clientBootstrap);
     }
     throw error;
   }
 
-  const { element, headElements, layoutComponents, deferSuspenseFor, skippedSegments } = routeResult;
+  const _buildEnd = performance.now();
+  recordTiming({
+    name: 'build',
+    dur: Math.round(_buildEnd - _buildStart),
+    desc: 'build element tree',
+  });
+
+  const { element, headElements, layoutComponents, deferSuspenseFor, skippedSegments } =
+    routeResult;
 
   // Build head HTML for injection into the SSR output.
   // Collects CSS, fonts, and modulepreload from the build manifest for matched segments.
@@ -374,6 +432,14 @@ async function renderRoute(
     headHtml += buildCssLinkTags(cssUrls);
   }
 
+  // Inline font CSS as a <style> tag — @font-face rules and scoped classes.
+  // The font CSS is set on globalThis by the transformed font file's
+  // side-effect import of virtual:timber-font-css-register.
+  const fontCss = (globalThis as Record<string, unknown>).__timber_font_css as string | undefined;
+  if (fontCss) {
+    headHtml += `<style data-timber-fonts>${fontCss}</style>`;
+  }
+
   const fontEntries = collectRouteFonts(segments, typedManifest);
   if (fontEntries.length > 0) {
     headHtml += buildFontPreloadTags(fontEntries);
@@ -400,7 +466,17 @@ async function renderRoute(
   }
 
   // Render to RSC Flight stream with signal tracking.
-  const { rscStream, signals } = renderRscStream(element, _req);
+  const _rscStart = performance.now();
+  const { rscStream, signals, getDebugComponents } = renderRscStream(element, _req);
+
+  // Store the debug components getter so onPipelineError can include
+  // component tree context for render-phase errors (dev mode only).
+  _lastDebugComponentsGetter = getDebugComponents;
+  recordTiming({
+    name: 'rsc-init',
+    dur: Math.round(performance.now() - _rscStart),
+    desc: 'RSC stream init',
+  });
 
   // Synchronous redirect — redirect() in access.ts or a non-async component
   // throws during renderToReadableStream creation. Return HTTP redirect.

package/src/server/rsc-entry/rsc-payload.ts

@@ -45,18 +45,45 @@ export async function buildRscPayloadResponse(
   skippedSegments?: string[]
 ): Promise<Response> {
   // Read the first chunk from the RSC stream before committing headers.
+  // Race the first read against signal detection — if an async component
+  // throws a RedirectSignal or DenySignal, the onError callback fires
+  // signals.onSignal() and we can react immediately without waiting for
+  // the full macrotask queue.
+  //
+  // The rejection chain for an async-wrapped page component:
+  //   1. PageComponent throws RedirectSignal
+  //   2. withSpan catches and re-throws (microtask 1)
+  //   3. TracedPage promise rejects (microtask 2)
+  //   4. React Flight rejection handler → onError (microtask 3+)
+  //
+  // Promise.race reacts the instant onError fires, eliminating the
+  // per-request setTimeout(0) macrotask delay for the common case
+  // (no signal). A 50ms ceiling timeout guards against edge cases
+  // where onError never fires.
   const reader = rscStream.getReader();
-  const firstRead = await reader.read();
+  const signalDetected = new Promise<void>((resolve) => {
+    signals.onSignal = resolve;
+  });
 
-  // Yield to the microtask queue so that async component rejections
-  // (e.g. an async-wrapped page component that throws redirect())
-  // propagate to the onError callback before we check the signals.
-  // The rejected Promise from an async component resolves in the next
-  // microtask after read(), so we need at least one tick.
-  //
-  // Uses queueMicrotask instead of setTimeout(0) to stay within the
-  // same tick — no full event loop round-trip needed.
-  await new Promise<void>((r) => queueMicrotask(r));
+  type RaceResult =
+    | { type: 'data'; chunk: ReadableStreamReadResult<Uint8Array> }
+    | { type: 'signal' };
+
+  const first: RaceResult = await Promise.race([
+    reader.read().then((chunk) => ({ type: 'data' as const, chunk })),
+    signalDetected.then(() => ({ type: 'signal' as const })),
+  ]);
+
+  // If data arrived first, still check signals — they may have fired
+  // concurrently. Also do a final ceiling timeout check for edge cases
+  // where the signal fires just after the first read resolves.
+  if (first.type === 'data' && !signals.redirectSignal && !signals.denySignal) {
+    // Brief yield to let any in-flight microtask rejections complete.
+    await new Promise<void>((r) => setTimeout(r, 0));
+  }
+
+  // Detach the callback — no longer needed after this point.
+  signals.onSignal = undefined;
 
   // Check for redirect/deny signals detected during initial rendering
   const trackedRedirect = signals.redirectSignal as RedirectSignal | null;
@@ -75,6 +102,19 @@ export async function buildRscPayloadResponse(
     );
   }
 
+  // Extract the first chunk from the race result.
+  // If the signal won the race but neither redirect nor deny was detected
+  // (edge case), cancel the reader immediately rather than issuing a bare
+  // read() that could hang forever if the RSC stream has stalled.
+  // See TIM-519.
+  let firstRead: ReadableStreamReadResult<Uint8Array>;
+  if (first.type === 'data') {
+    firstRead = first.chunk;
+  } else {
+    await reader.cancel();
+    firstRead = { done: true, value: undefined };
+  }
+
   // Reconstruct the stream: prepend the buffered first chunk,
   // then continue piping from the original reader.
   const patchedStream = new ReadableStream<Uint8Array>({
@@ -123,8 +163,8 @@ export async function buildRscPayloadResponse(
     responseHeaders.set('X-Timber-Skipped-Segments', JSON.stringify(skippedSegments));
   }
 
-  // Send route params so the client can populate useParams() after
-  // SPA navigation. Without this, useParams() returns {}.
+  // Send route params so the client can populate useSegmentParams() after
+  // SPA navigation. Without this, useSegmentParams() returns {}.
   if (Object.keys(match.params).length > 0) {
     responseHeaders.set('X-Timber-Params', JSON.stringify(match.params));
   }

package/src/server/rsc-entry/rsc-stream.ts

@@ -16,24 +16,38 @@ import { logRenderError } from '#/server/logger.js';
 import { DenySignal, RedirectSignal, RenderError } from '#/server/primitives.js';
 import { checkAndWarnRscPropError } from '#/server/rsc-prop-warnings.js';
 
-import { createDebugChannelSink, isAbortError } from './helpers.js';
+import {
+  createDebugChannelSink,
+  createDebugChannelCollector,
+  isAbortError,
+  type DebugComponentEntry,
+} from './helpers.js';
 import { isDebug } from '#/server/debug.js';
+import { isDevMode } from '#/server/debug.js';
 
 /**
  * Mutable signal state captured during RSC rendering.
  *
  * Signals fire asynchronously via `onError` during stream consumption.
  * The first signal of each type wins — subsequent signals are ignored.
+ *
+ * `onSignal` is an optional callback fired when a DenySignal or
+ * RedirectSignal is captured. Consumers use it with Promise.race to
+ * react immediately instead of polling with setTimeout/queueMicrotask.
  */
 export interface RenderSignals {
   denySignal: DenySignal | null;
   redirectSignal: RedirectSignal | null;
   renderError: { error: unknown; status: number } | null;
+  /** Callback fired when a redirect or deny signal is captured in onError. */
+  onSignal?: () => void;
 }
 
 export interface RscStreamResult {
   rscStream: ReadableStream<Uint8Array> | undefined;
   signals: RenderSignals;
+  /** Dev-only: server component debug info from the Flight debug channel. */
+  getDebugComponents?: () => DebugComponentEntry[];
 }
 
 /**
@@ -56,6 +70,10 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
 
   let rscStream: ReadableStream<Uint8Array> | undefined;
 
+  // In dev mode, collect debug channel data for the error overlay.
+  // In production, use the discard sink (no overhead).
+  const debugChannel = isDevMode() ? createDebugChannelCollector() : createDebugChannelSink();
+
   try {
     rscStream = renderToReadableStream(
       element,
@@ -67,11 +85,13 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
           if (isAbortError(error) || req.signal?.aborted) return;
           if (error instanceof DenySignal) {
             signals.denySignal = error;
+            signals.onSignal?.();
             // Return structured digest for client-side error boundaries
             return JSON.stringify({ type: 'deny', status: error.status, data: error.data });
           }
           if (error instanceof RedirectSignal) {
             signals.redirectSignal = error;
+            signals.onSignal?.();
             return JSON.stringify({
               type: 'redirect',
               location: error.location,
@@ -98,11 +118,7 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
           // directive isn't at the very top of the file, or the component is
           // re-exported through a barrel file without 'use client'.
           // See LOCAL-297.
-          if (
-            isDebug() &&
-            error instanceof Error &&
-            error.message.includes('Invalid hook call')
-          ) {
+          if (isDebug() && error instanceof Error && error.message.includes('Invalid hook call')) {
             console.error(
               '[timber] A React hook was called during RSC rendering. This usually means a ' +
                 "'use client' component is being executed as a server component instead of " +
@@ -128,7 +144,7 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
           }
           logRenderError({ method: req.method, path: new URL(req.url).pathname, error });
         },
-        debugChannel: createDebugChannelSink(),
+        debugChannel,
       },
       {
         onClientReference(info: { id: string; name: string; deps: unknown }) {
@@ -156,5 +172,14 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
     }
   }
 
-  return { rscStream, signals };
+  return {
+    rscStream,
+    signals,
+    // Expose the debug channel collector's getComponents in dev mode.
+    // The caller can retrieve component tree info when handling errors.
+    getDebugComponents:
+      'getComponents' in debugChannel
+        ? (debugChannel as { getComponents: () => DebugComponentEntry[] }).getComponents
+        : undefined,
+  };
 }

package/src/server/rsc-entry/ssr-renderer.ts

@@ -13,6 +13,7 @@
  */
 
 import type { ClientBootstrapConfig } from '#/server/html-injectors.js';
+import { flightInitScript } from '#/server/flight-scripts.js';
 import type { LayoutEntry } from '#/server/deny-renderer.js';
 import { renderDenyPage } from '#/server/deny-renderer.js';
 import type { RouteMatch } from '#/server/pipeline.js';
@@ -26,11 +27,12 @@ import {
   buildSegmentInfo,
   createDebugChannelSink,
   isAbortError,
-  parseCookiesFromHeader,
 } from './helpers.js';
+import { getCookiesForSsr } from '#/server/request-context.js';
 import { renderErrorPage } from './error-renderer.js';
 import { callSsr } from './ssr-bridge.js';
 import type { RenderSignals } from './rsc-stream.js';
+import { recordTiming } from '#/server/server-timing.js';
 
 interface SsrRenderOptions {
   req: Request;
@@ -91,8 +93,8 @@ export async function renderSsrResponse(opts: SsrRenderOptions): Promise<Respons
     ? ''
     : `<script>self.__timber_segments=${JSON.stringify(buildSegmentInfo(segments, layoutComponents))}</script>`;
 
-  // Embed route params in HTML so useParams() works on initial hydration.
-  // Without this, useParams() returns {} until the first client navigation.
+  // Embed route params in HTML so useSegmentParams() works on initial hydration.
+  // Without this, useSegmentParams() returns {} until the first client navigation.
   const paramsScript =
     clientJsDisabled || Object.keys(match.params).length === 0
       ? ''
@@ -104,13 +106,20 @@ export async function renderSsrResponse(opts: SsrRenderOptions): Promise<Respons
     searchParams: Object.fromEntries(new URL(req.url).searchParams),
     statusCode: 200,
     responseHeaders,
-    headHtml: headHtml + clientBootstrap.preloadLinks + segmentScript + paramsScript,
+    headHtml:
+      headHtml +
+      clientBootstrap.preloadLinks +
+      segmentScript +
+      paramsScript +
+      // Initialize __timber_f in <head> so it exists before any streaming
+      // chunk scripts arrive in <body>. See flight-scripts.ts, LOCAL-415.
+      (clientJsDisabled ? '' : flightInitScript()),
     bootstrapScriptContent: clientBootstrap.bootstrapScriptContent,
     // Skip RSC inline stream when client JS is disabled — no client to hydrate.
     rscStream: clientJsDisabled ? undefined : inlineStream,
     deferSuspenseFor: deferSuspenseFor > 0 ? deferSuspenseFor : undefined,
     signal: req.signal,
-    cookies: parseCookiesFromHeader(req.headers.get('cookie') ?? ''),
+    cookies: getCookiesForSsr(),
   };
 
   // Helper: check if render-phase signals were captured and return the
@@ -156,16 +165,34 @@ export async function renderSsrResponse(opts: SsrRenderOptions): Promise<Respons
   try {
     const ssrResponse = await callSsr(ssrStream, navContext);
 
-    // Signal promotion: yield one microtask so async component rejections
-    // propagate to the RSC onError callback, then check if any signals
-    // were captured during rendering inside Suspense boundaries.
-    // The Response hasn't been sent yet — it's an unconsumed stream.
+    // Record SSR sub-phase timings for Server-Timing header (detailed mode).
+    // These are populated by handleSsr() in the SSR environment and passed
+    // back via navContext._ssrTimings across the RSC→SSR boundary.
+    if (navContext._ssrTimings) {
+      const t = navContext._ssrTimings;
+      recordTiming({ name: 'ssr-decode', dur: t.decodeMs, desc: 'RSC Flight decode' });
+      recordTiming({ name: 'ssr-shell', dur: t.shellMs, desc: 'Fizz onShellReady' });
+      recordTiming({ name: 'ssr-pipeline', dur: t.pipelineMs, desc: 'stream transforms' });
+      recordTiming({
+        name: 'ssr-total',
+        dur: t.totalMs,
+        desc: t.nodeStreams ? 'SSR (Node streams)' : 'SSR (Web Streams)',
+      });
+    }
+
+    // Signal promotion: check if any signals were captured during rendering
+    // inside Suspense boundaries. If no signals are present yet, yield one
+    // microtask so async component rejections propagate to the RSC onError
+    // callback before we commit the response.
     //
-    // Uses queueMicrotask instead of setTimeout(0) to avoid yielding to
-    // the full event loop (timers phase). Microtask resolution happens
-    // within the same tick, eliminating per-request idle time under load.
+    // When signals are already captured (onSignal already fired), skip the
+    // yield entirely — react immediately. Uses queueMicrotask instead of
+    // setTimeout(0) for the fallback to avoid yielding to the full event
+    // loop (timers phase).
     // See design/05-streaming.md §"deferSuspenseFor and the Hold Window"
-    await new Promise<void>((r) => queueMicrotask(r));
+    if (!signals.redirectSignal && !signals.denySignal && !signals.renderError) {
+      await new Promise<void>((r) => queueMicrotask(r));
+    }
 
     const promoted = checkCapturedSignals(/* skipHandledDeny */ true);
     if (promoted) {