@timber-js/app 0.2.0-alpha.208 → 0.2.0-alpha.209

package/src/server/ssr-entry.ts

@@ -33,15 +33,15 @@ import {
   nodeReadableToWeb,
   useNodeStreams,
   buildSsrResponse,
+  type SsrStreamOptions,
 } from './ssr-render.ts';
-import { logRenderError } from './logger.ts';
-import { SsrStreamError } from './primitives.ts';
+import { SsrStreamError } from './signal-identity.ts';
 import { createBufferedTransformStream, injectHead, injectRscPayload } from './html-injectors.ts';
 import { wrapSsrElement } from './ssr-wrappers.tsx';
 import { withSpan } from './tracing.ts';
 import { registerSsrDataProvider, type SsrData } from '../client/ssr-data.ts';
 import { splitPayloadRoot } from '../shared/payload-root.ts';
-import type { NavContext } from './ssr-bridge-types.ts';
+import type { NavContext, SsrRenderResult } from './ssr-bridge-types.ts';
 
 // Pre-import Node.js stream modules at module load time — not per-request.
 // Dynamic imports of node-stream-transforms and node:stream/promises were
@@ -99,34 +99,35 @@ registerSsrDataProvider(() => ssrDataAls.getStore());
  * 2. Render the decoded tree to HTML via renderToReadableStream (streaming)
  * 3. Wait for onShellReady before flushing (handled by renderSsrStream)
  * 4. Inject metadata into <head> and client scripts before </body>
- * 5. Return Response with navContext.statusCode and navContext.responseHeaders
+ * 5. Return the Response (navContext.statusCode, navContext.responseHeaders)
+ *    with the SSR sub-phase timings and whether Fizz allReady settled
+ *    within the hold window
  *
  * The RSC stream is piped progressively — not buffered. For deny() outside
  * Suspense, the RSC stream encodes an error in the shell region, causing
  * renderToReadableStream to reject. The error propagates back to the RSC
- * entry which renders the deny page. For deny() inside Suspense, the shell
+ * entry, which rethrows the captured DenySignal for the pipeline to render
+ * the deny page. For deny() inside Suspense, the shell
  * succeeds and the error streams as a React error boundary after flush.
  *
  * @param rscStream - The ReadableStream from the RSC environment
  * @param navContext - Per-request state passed across RSC→SSR boundary
- * @returns A Response containing the HTML stream with hydration markers
+ * @returns The HTML Response with hydration markers, plus SSR diagnostics
  */
 export async function handleSsr(
   rscStream: ReadableStream<Uint8Array>,
   navContext: NavContext
-): Promise<Response> {
+): Promise<SsrRenderResult> {
   return withSpan('timber.ssr', { 'timber.environment': 'ssr' }, async () => {
     const _runtimeConfig = config;
 
-    // Build per-request SSR data for client hooks (usePathname,
-    // useSearchParams, useCookie, useParams, etc.).
+    // Per-request SSR data for the client code with no React context to
+    // read during SSR (useCookie, <Link preserveSearchParams>; useSearchParams
+    // uses it only to detect SSR). Route params reach client components through
+    // ParamsContext, decoded from the payload root, not through here.
     const ssrData: SsrData = {
-      pathname: navContext.pathname,
       search: navContext.search,
       cookies: navContext.cookies ?? new Map(),
-      params: navContext.segmentParams,
-      slotParams: navContext.slotParams,
-      _navContext: navContext,
     };
 
     // Run the entire render inside the SSR data ALS scope.
@@ -188,6 +189,36 @@ export async function handleSsr(
       //   Entire pipeline stays in C++ native streams until the Response boundary.
       // - Workers: renderToReadableStream → Web TransformStream pipeline → Response
       //   Web Streams are V8-native C++ built-ins on Workers.
+      //
+      // `onFizzAllReadyResolved` fires synchronously before the render
+      // promise resolves, so the flag is settled once the render is awaited.
+      const renderTimeoutMs = _runtimeConfig.renderTimeoutMs ?? undefined;
+      const requestInfo = { method: 'GET', path: navContext.pathname };
+      let fizzAllReadyResolved = false;
+      const renderOptions: SsrStreamOptions = {
+        bootstrapScriptContent: navContext.bootstrapScriptContent || undefined,
+        nonce,
+        deferSuspenseFor: navContext.deferSuspenseFor,
+        signal: navContext.signal,
+        renderTimeoutMs,
+        requestInfo,
+        onFizzAllReadyResolved: (resolved) => {
+          fizzAllReadyResolved = resolved;
+        },
+      };
+      // Not logged here. Fizz's onError (ssr-render.ts) has already logged a
+      // shell error SSR produced itself, and skips one Flight relayed,
+      // which the RSC onError (rsc-stream.ts) logged. Logging the rejection
+      // again doubled every shell failure (TIM-1537).
+      const renderFailed = (renderError: unknown): never => {
+        throw new SsrStreamError(
+          'SSR renderToReadableStream failed due to RSC stream error',
+          renderError
+        );
+      };
+
+      let outputStream: ReadableStream<Uint8Array>;
+      let _renderEnd: number;
       if (_nodeStreamImports) {
         // Node.js fast path: full pipeline in native streams
         const {
@@ -198,30 +229,10 @@ export async function handleSsr(
           runNodePipelineWithErrorHandling,
         } = _nodeStreamImports;
 
-        const renderTimeoutMs = _runtimeConfig.renderTimeoutMs ?? undefined;
-        const requestInfo = { method: 'GET', path: navContext.pathname };
-
-        let nodeHtmlStream: import('node:stream').Readable;
-        try {
-          nodeHtmlStream = await renderSsrNodeStream(wrappedElement, {
-            bootstrapScriptContent: navContext.bootstrapScriptContent || undefined,
-            nonce,
-            deferSuspenseFor: navContext.deferSuspenseFor,
-            signal: navContext.signal,
-            renderTimeoutMs,
-            requestInfo,
-            onFizzAllReadyResolved: (resolved) => {
-              navContext._fizzAllReadyResolved = resolved;
-            },
-          });
-        } catch (renderError) {
-          logRenderError({ ...requestInfo, error: renderError });
-          throw new SsrStreamError(
-            'SSR renderToReadableStream failed due to RSC stream error',
-            renderError
-          );
-        }
-        const _renderEnd = performance.now();
+        const nodeHtmlStream = await renderSsrNodeStream(wrappedElement, renderOptions).catch(
+          renderFailed
+        );
+        _renderEnd = performance.now();
 
         // React 19.3+ emits <!DOCTYPE html> automatically when the root
         // element is <html>, so no framework-level doctype prepend needed.
@@ -240,92 +251,57 @@ export async function handleSsr(
         // Resolve the lazy segment script now that the shell is ready
         // (AccessGates have settled, ALS deny index is authoritative).
         const resolvedHeadHtml = navContext.headHtml + (navContext.getHeadSegmentScript?.() ?? '');
-        const bufferedTransform = createNodeBufferedTransform();
-        const headInjector = createNodeHeadInjector(resolvedHeadHtml);
-        const flightInjector = createNodeFlightInjector(navContext.rscStream, {
-          renderTimeoutMs,
-          errorSignal: navContext._errorSignal,
-          nonce,
-        });
-        const moveSuffix = createNodeMoveSuffixTransform();
-
         const output = runNodePipelineWithErrorHandling(
           nodeHtmlStream,
-          [bufferedTransform, headInjector, flightInjector, moveSuffix],
+          [
+            createNodeBufferedTransform(),
+            createNodeHeadInjector(resolvedHeadHtml),
+            createNodeFlightInjector(navContext.rscStream, {
+              renderTimeoutMs,
+              errorSignal: navContext._errorSignal,
+              nonce,
+            }),
+            createNodeMoveSuffixTransform(),
+          ],
           navContext.signal,
           nonce
         );
-        const _pipelineEnd = performance.now();
-
-        // Record SSR sub-timings for Server-Timing header (detailed mode).
-        navContext._ssrTimings = {
-          decodeMs: Math.round(_decodeEnd - _ssrStart),
-          shellMs: Math.round(_renderEnd - _decodeEnd),
-          pipeMs: 0, // pipe() timing is inside renderSsrNodeStream
-          pipelineMs: Math.round(_pipelineEnd - _renderEnd),
-          totalMs: Math.round(_pipelineEnd - _ssrStart),
-          nodeStreams: true,
-        };
-
-        const webStream = nodeReadableToWeb(output);
-        return buildSsrResponse(webStream, navContext.statusCode, navContext.responseHeaders);
-      }
+        outputStream = nodeReadableToWeb(output);
+      } else {
+        // Web Streams path (CF Workers / fallback)
+        const htmlStream = await renderSsrStream(wrappedElement, renderOptions).catch(renderFailed);
+        _renderEnd = performance.now();
 
-      // Web Streams path (CF Workers / fallback)
-      const renderTimeoutMs = _runtimeConfig.renderTimeoutMs ?? undefined;
-      const requestInfo = { method: 'GET', path: navContext.pathname };
-      let htmlStream: ReadableStream<Uint8Array>;
-      try {
-        htmlStream = await renderSsrStream(wrappedElement, {
-          bootstrapScriptContent: navContext.bootstrapScriptContent || undefined,
-          nonce,
-          deferSuspenseFor: navContext.deferSuspenseFor,
-          signal: navContext.signal,
+        // Pipeline: buffer → injectHead → injectRscPayload
+        //
+        // The buffered transform coalesces Fizz micro-chunks into coherent
+        // HTML fragments so downstream transforms never see chunk boundaries
+        // mid-tag. This prevents RSC script injection from breaking HTML
+        // structure (TIM-527).
+        // Resolve the lazy segment script now that the shell is ready
+        // (AccessGates have settled, ALS deny index is authoritative).
+        const resolvedHeadHtml = navContext.headHtml + (navContext.getHeadSegmentScript?.() ?? '');
+        outputStream = htmlStream.pipeThrough(createBufferedTransformStream());
+        outputStream = injectHead(outputStream, resolvedHeadHtml);
+        outputStream = injectRscPayload(outputStream, navContext.rscStream, {
           renderTimeoutMs,
-          requestInfo,
-          onFizzAllReadyResolved: (resolved) => {
-            navContext._fizzAllReadyResolved = resolved;
-          },
+          errorSignal: navContext._errorSignal,
+          nonce,
         });
-      } catch (renderError) {
-        logRenderError({ ...requestInfo, error: renderError });
-        throw new SsrStreamError(
-          'SSR renderToReadableStream failed due to RSC stream error',
-          renderError
-        );
       }
-
-      const _renderEnd = performance.now();
-
-      // Pipeline: buffer → injectHead → injectRscPayload
-      //
-      // The buffered transform coalesces Fizz micro-chunks into coherent
-      // HTML fragments so downstream transforms never see chunk boundaries
-      // mid-tag. This prevents RSC script injection from breaking HTML
-      // structure (TIM-527).
-      // Resolve the lazy segment script now that the shell is ready
-      // (AccessGates have settled, ALS deny index is authoritative).
-      const resolvedHeadHtml = navContext.headHtml + (navContext.getHeadSegmentScript?.() ?? '');
-      let outputStream = htmlStream.pipeThrough(createBufferedTransformStream());
-      outputStream = injectHead(outputStream, resolvedHeadHtml);
-      outputStream = injectRscPayload(outputStream, navContext.rscStream, {
-        renderTimeoutMs,
-        errorSignal: navContext._errorSignal,
-        nonce,
-      });
       const _pipelineEnd = performance.now();
 
-      navContext._ssrTimings = {
-        decodeMs: Math.round(_decodeEnd - _ssrStart),
-        shellMs: Math.round(_renderEnd - _decodeEnd),
-        pipeMs: 0,
-        pipelineMs: Math.round(_pipelineEnd - _renderEnd),
-        totalMs: Math.round(_pipelineEnd - _ssrStart),
-        nodeStreams: false,
+      return {
+        response: buildSsrResponse(outputStream, navContext.statusCode, navContext.responseHeaders),
+        timings: {
+          decodeMs: Math.round(_decodeEnd - _ssrStart),
+          shellMs: Math.round(_renderEnd - _decodeEnd),
+          pipelineMs: Math.round(_pipelineEnd - _renderEnd),
+          totalMs: Math.round(_pipelineEnd - _ssrStart),
+          nodeStreams: _nodeStreamImports !== null,
+        },
+        fizzAllReadyResolved,
       };
-
-      // Build and return the Response.
-      return buildSsrResponse(outputStream, navContext.statusCode, navContext.responseHeaders);
     });
   });
 }

package/src/server/ssr-render.ts

@@ -36,12 +36,24 @@ import { isAbortError, noindexScript } from './render-utils.ts';
 const REACT_PROD_ERROR_PREFIX = 'An error occurred in the Server Components render';
 
 /**
- * Returns true if the error is React's sanitized production error.
- * These are duplicates of errors already logged by the RSC onError handler
- * with the full original message — logging them again in SSR adds noise.
+ * Returns true if this error was thrown in the RSC render and relayed by
+ * Flight, which means the RSC onError handler (rsc-stream.ts) already logged
+ * it with the full original message. Logging it again in SSR is a duplicate.
+ *
+ * In production React replaces a relayed error's message with a fixed
+ * sanitized one. In development it keeps the message, stamps the revived
+ * Error with the `environmentName` it was thrown in, and copies the digest
+ * our onError returned (`resolveErrorDev` and the `E` row in the Flight
+ * client). Both are needed: an Error passed as a *value* (a prop, `$Z`) is
+ * stamped with `environmentName` too but has no digest, and nothing logged
+ * it. When a client component throws one during SSR, it is logged here once,
+ * like any other error SSR throws itself (TIM-1537).
  */
-function isReactSanitizedError(error: unknown): boolean {
-  return error instanceof Error && error.message.startsWith(REACT_PROD_ERROR_PREFIX);
+function isFlightRelayedError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  if (error.message.startsWith(REACT_PROD_ERROR_PREFIX)) return true;
+  const digest: unknown = Reflect.get(error, 'digest');
+  return 'environmentName' in error && typeof digest === 'string' && digest !== '';
 }
 
 /**
@@ -106,6 +118,26 @@ try {
   // node:stream or renderToPipeableStream not available — use Web Streams path
 }
 
+/** Options shared by both SSR render paths (Node streams and Web Streams). */
+export interface SsrStreamOptions {
+  bootstrapScriptContent?: string;
+  /** Request CSP nonce — stamped by Fizz on the bootstrap and runtime scripts. */
+  nonce?: string;
+  deferSuspenseFor?: number;
+  signal?: AbortSignal;
+  renderTimeoutMs?: number;
+  /** Request info threaded into render-error logs (method/path). */
+  requestInfo?: { method: string; path: string };
+  /**
+   * Fired synchronously when the render function is about to resolve
+   * (i.e. at hold-end / shell-ready). `resolved` reports whether Fizz's
+   * allReady had already settled by that moment. The SSR entry returns it
+   * as `SsrRenderResult.fizzAllReadyResolved` so the RSC renderer can
+   * decide whether signal promotion can be short-circuited.
+   */
+  onFizzAllReadyResolved?: (resolved: boolean) => void;
+}
+
 /**
  * Render a React element tree to a ReadableStream of HTML.
  *
@@ -122,24 +154,7 @@ try {
  */
 export async function renderSsrStream(
   element: ReactNode,
-  options?: {
-    bootstrapScriptContent?: string;
-    /** Request CSP nonce — stamped by Fizz on the bootstrap and runtime scripts. */
-    nonce?: string;
-    deferSuspenseFor?: number;
-    signal?: AbortSignal;
-    renderTimeoutMs?: number;
-    /** Request info threaded into render-error logs (method/path). */
-    requestInfo?: { method: string; path: string };
-    /**
-     * Fired synchronously when the render function is about to resolve
-     * (i.e. at hold-end / shell-ready). `resolved` reports whether Fizz's
-     * `stream.allReady` had already settled by that moment. Callers use
-     * this to decide whether signal promotion can be short-circuited.
-     * See NavContext._fizzAllReadyResolved.
-     */
-    onFizzAllReadyResolved?: (resolved: boolean) => void;
-  }
+  options?: SsrStreamOptions
 ): Promise<ReadableStream<Uint8Array>> {
   return renderViaReadableStream(element, options);
 }
@@ -164,23 +179,7 @@ export const useNodeStreams = _useNodeStreams;
  */
 export async function renderSsrNodeStream(
   element: ReactNode,
-  options?: {
-    bootstrapScriptContent?: string;
-    /** Request CSP nonce — stamped by Fizz on the bootstrap and runtime scripts. */
-    nonce?: string;
-    deferSuspenseFor?: number;
-    signal?: AbortSignal;
-    renderTimeoutMs?: number;
-    /** Request info threaded into render-error logs (method/path). */
-    requestInfo?: { method: string; path: string };
-    /**
-     * Fired synchronously at the moment `renderSsrNodeStream`'s returned
-     * Promise is about to resolve. `resolved` reports whether Fizz's
-     * `onAllReady` had already fired by then. See the twin callback on
-     * `renderSsrStream`.
-     */
-    onFizzAllReadyResolved?: (resolved: boolean) => void;
-  }
+  options?: SsrStreamOptions
 ): Promise<import('node:stream').Readable> {
   const signal = options?.signal;
   const deferMs = options?.deferSuspenseFor;
@@ -235,9 +234,9 @@ export async function renderSsrNodeStream(
 
       onError(error: unknown) {
         if (isAbortError(error) || signal?.aborted) return;
-        // Skip React's sanitized production errors — the original was
-        // already logged by the RSC onError with full details.
-        if (isReactSanitizedError(error)) return;
+        // Skip errors Flight relayed — the original was already logged by
+        // the RSC onError with full details.
+        if (isFlightRelayedError(error)) return;
         logRenderError({
           method: requestInfo?.method ?? '',
           path: requestInfo?.path ?? '',
@@ -301,16 +300,7 @@ export function nodeReadableToWeb(
 
 async function renderViaReadableStream(
   element: ReactNode,
-  options?: {
-    bootstrapScriptContent?: string;
-    /** Request CSP nonce — stamped by Fizz on the bootstrap and runtime scripts. */
-    nonce?: string;
-    deferSuspenseFor?: number;
-    signal?: AbortSignal;
-    renderTimeoutMs?: number;
-    requestInfo?: { method: string; path: string };
-    onFizzAllReadyResolved?: (resolved: boolean) => void;
-  }
+  options?: SsrStreamOptions
 ): Promise<ReadableStream<Uint8Array>> {
   const signal = options?.signal;
   const timeoutMs = options?.renderTimeoutMs;
@@ -345,9 +335,9 @@ async function renderViaReadableStream(
           });
           return;
         }
-        // Skip React's sanitized production errors — the original was
-        // already logged by the RSC onError with full details.
-        if (isReactSanitizedError(error)) return;
+        // Skip errors Flight relayed — the original was already logged by
+        // the RSC onError with full details.
+        if (isFlightRelayedError(error)) return;
         logRenderError({
           method: requestInfo?.method ?? '',
           path: requestInfo?.path ?? '',
@@ -378,7 +368,7 @@ async function renderViaReadableStream(
   //
   // While we're holding, also track whether `stream.allReady` settled
   // before the timer. That boolean is the Option-1 signal-promotion
-  // short-circuit key — see NavContext._fizzAllReadyResolved and
+  // short-circuit key — see SsrRenderResult.fizzAllReadyResolved and
   // design/spike-signal-promotion-protocol.md.
   let fizzAllReadyResolved = false;
   const allReadyTap = stream.allReady.then(
@@ -454,19 +444,20 @@ export function wrapStreamWithErrorHandling(
  * React 19.3+ automatically emits `<!DOCTYPE html>` when the root
  * element is `<html>`, so no framework-level doctype prepending is needed.
  *
- * Sets content-type to text/html if not already set by middleware.
+ * Sets content-type to text/html if not already set by middleware. The
+ * default goes on a response-local copy: `responseHeaders` is the
+ * pipeline's shared bag, handed over on `NavContext`, and SSR only reads
+ * it (design/49 §"A2").
  */
 export function buildSsrResponse(
   htmlStream: ReadableStream<Uint8Array>,
   statusCode: number,
   responseHeaders: Headers
 ): Response {
-  if (!responseHeaders.has('content-type')) {
-    responseHeaders.set('content-type', 'text/html; charset=utf-8');
+  const headers = new Headers(responseHeaders);
+  if (!headers.has('content-type')) {
+    headers.set('content-type', 'text/html; charset=utf-8');
   }
 
-  return new Response(htmlStream, {
-    status: statusCode,
-    headers: responseHeaders,
-  });
+  return new Response(htmlStream, { status: statusCode, headers });
 }

package/src/server/ssr-wrappers.tsx

@@ -30,7 +30,7 @@
  * Per-request isolation is by construction: the provider values are part
  * of this request's element tree, so concurrent requests cannot observe
  * each other's values — stronger than the ALS path, which remains for
- * `useCookie()` and the `_navContext` status-code channel.
+ * `useCookie()`.
  *
  * **What actually shifts a useId is a fork, not depth.** `useId` derives from
  * React's tree context, which only changes where a fiber has more than one
@@ -142,7 +142,7 @@ export interface SsrWrapOptions {
  */
 export function wrapSsrElement(element: ReactNode, opts: SsrWrapOptions): ReactNode {
   // Build inside-out to match the client's createElement chain in
-  // hydrate.ts / router-init.ts renderTree().
+  // browser-entry/router-init.ts renderTree(), which hydration builds with too.
 
   // 1. Innermost: PayloadRoot publishes the payload's params over the tree.
   const withParams = createElement(PayloadRoot, { source: opts.paramsSource }, element);

package/src/server/static-generator.ts

@@ -22,6 +22,8 @@
 import type { ManifestRoot, ManifestSegmentNode, ManifestFile } from './route-matcher.ts';
 import { hasDynamicSegments, hasUserSitemap, resolvePathWithParams } from './sitemap-generator.ts';
 import { loadModule } from './safe-load.ts';
+import { readAllBytesWithDeadline } from './stream-utils.ts';
+import { DEFAULT_RENDER_TIMEOUT_MS, resolveRenderTimeoutMs } from './render-timeout.ts';
 import { METADATA_ROUTE_CONVENTIONS, resolveServePathForFile } from './metadata-routes.ts';
 import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.ts';
 import {
@@ -346,8 +348,6 @@ function normalizeRedirectTarget(rawLocation: string): string {
 
 // ─── Rendering ───────────────────────────────────────────────────────────
 
-const DEFAULT_RENDER_TIMEOUT_MS = 30_000;
-
 async function loadModuleWithTimeout(
   file: ManifestFile,
   timeoutMs: number
@@ -365,44 +365,6 @@ async function loadModuleWithTimeout(
   }
 }
 
-async function drainResponse(response: Response, timeoutMs: number): Promise<Uint8Array> {
-  if (!response.body) return new Uint8Array(0);
-
-  const reader = response.body.getReader();
-  const chunks: Uint8Array[] = [];
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  let timedOut = false;
-
-  const deadline = new Promise<never>((_, reject) => {
-    timer = setTimeout(() => {
-      timedOut = true;
-      reject(new Error(`response did not complete within ${timeoutMs}ms`));
-    }, timeoutMs);
-  });
-
-  try {
-    for (;;) {
-      const { done, value } = await Promise.race([reader.read(), deadline]);
-      if (done) break;
-      chunks.push(value as Uint8Array);
-    }
-  } finally {
-    clearTimeout(timer);
-    // Always cancel — design/13-security.md A3: never leave a reader open.
-    await reader.cancel().catch(() => {});
-  }
-
-  let total = 0;
-  for (const c of chunks) total += c.byteLength;
-  const out = new Uint8Array(total);
-  let off = 0;
-  for (const c of chunks) {
-    out.set(c, off);
-    off += c.byteLength;
-  }
-  return out;
-}
-
 function headersToRecord(headers: Headers): Record<string, string> {
   const record: Record<string, string> = {};
   headers.forEach((value, key) => {
@@ -428,7 +390,7 @@ export async function generateStaticSite(
   options: StaticGenerationOptions
 ): Promise<StaticGenerationSummary> {
   const log = options.log ?? ((msg: string) => console.log(msg));
-  const timeoutMs = options.renderTimeoutMs ?? DEFAULT_RENDER_TIMEOUT_MS;
+  const timeoutMs = resolveRenderTimeoutMs(options.renderTimeoutMs);
   const summary: StaticGenerationSummary = {
     rendered: 0,
     errors: [],
@@ -705,7 +667,10 @@ async function renderUrl(
     clearTimeout(timer);
   }
 
-  const body = await drainResponse(response, timeoutMs);
+  // The reader is cancelled on every exit — design/13-security.md A3.
+  const body = response.body
+    ? await readAllBytesWithDeadline(response.body, timeoutMs, 'response')
+    : new Uint8Array(0);
 
   return {
     status: response.status,

package/src/server/static-not-found.ts

@@ -51,9 +51,9 @@ export interface NotFoundResult {
 /**
  * Whether the not-found chain has anything to render for this root.
  *
- * Asks the resolver rather than inspecting file names: `renderNoMatchPage`
- * builds its chain from the root segment alone and resolves through exactly
- * these two calls, so this cannot drift from what the request path does. A
+ * Asks the resolver rather than inspecting file names: the no-match 404 (the
+ * deny fallback with no match, `rsc-entry/deny-fallback.ts`) builds its chain
+ * from the root segment alone and resolves through exactly these two calls, so this cannot drift from what the request path does. A
  * hand-rolled key check gets it wrong — a root that declares only `500.tsx`
  * has status files but nothing a 404 can select.
  */

package/src/server/stream-utils.ts

@@ -290,3 +290,54 @@ function formatBytes(bytes: number): string {
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} KB`;
   return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
 }
+
+/**
+ * Read a byte stream to completion under one overall deadline and return
+ * the concatenated bytes. Every read is raced against the time remaining,
+ * and the reader is cancelled on every exit, so a stalled upstream never
+ * outlives the deadline. See design/02-rendering-pipeline.md §"Always
+ * Timeout-Guard Stream Reads".
+ *
+ * @param label - Prefix for the timeout error message. Both ways the deadline
+ *   can pass (between reads, or while a read is pending) reject with the same
+ *   `${label} did not complete within ${timeoutMs}ms`.
+ */
+export async function readAllBytesWithDeadline(
+  stream: ReadableStream<Uint8Array>,
+  timeoutMs: number,
+  label: string
+): Promise<Uint8Array> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  let totalLength = 0;
+  const deadline = Date.now() + timeoutMs;
+  const deadlineError = () => new Error(`${label} did not complete within ${timeoutMs}ms`);
+  try {
+    for (;;) {
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) throw deadlineError();
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const timeout = new Promise<never>((_, reject) => {
+        timer = setTimeout(() => reject(deadlineError()), remaining);
+      });
+      let result: ReadableStreamReadResult<Uint8Array>;
+      try {
+        result = await Promise.race([reader.read(), timeout]);
+      } finally {
+        clearTimeout(timer);
+      }
+      if (result.done) break;
+      chunks.push(result.value);
+      totalLength += result.value.byteLength;
+    }
+  } finally {
+    reader.cancel().catch(() => {});
+  }
+  const bytes = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}