npm - @timber-js/app - Versions diffs - 0.2.0-alpha.37 → 0.2.0-alpha.38 - Mend

@timber-js/app 0.2.0-alpha.37 → 0.2.0-alpha.38

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (56) hide show

package/dist/adapters/nitro.d.ts.map +1 -1
package/dist/adapters/nitro.js +27 -4
package/dist/adapters/nitro.js.map +1 -1
package/dist/cache/index.d.ts +5 -2
package/dist/cache/index.d.ts.map +1 -1
package/dist/cache/index.js +32 -8
package/dist/cache/index.js.map +1 -1
package/dist/cache/singleflight.d.ts +18 -1
package/dist/cache/singleflight.d.ts.map +1 -1
package/dist/cache/timber-cache.d.ts.map +1 -1
package/dist/index.d.ts +12 -0
package/dist/index.d.ts.map +1 -1
package/dist/index.js +53 -4
package/dist/index.js.map +1 -1
package/dist/plugins/dev-error-overlay.d.ts +26 -1
package/dist/plugins/dev-error-overlay.d.ts.map +1 -1
package/dist/plugins/entries.d.ts.map +1 -1
package/dist/server/html-injectors.d.ts +2 -2
package/dist/server/html-injectors.d.ts.map +1 -1
package/dist/server/index.d.ts +2 -0
package/dist/server/index.d.ts.map +1 -1
package/dist/server/index.js +27 -1
package/dist/server/index.js.map +1 -1
package/dist/server/node-stream-transforms.d.ts +13 -1
package/dist/server/node-stream-transforms.d.ts.map +1 -1
package/dist/server/render-timeout.d.ts +51 -0
package/dist/server/render-timeout.d.ts.map +1 -0
package/dist/server/rsc-entry/helpers.d.ts +46 -3
package/dist/server/rsc-entry/helpers.d.ts.map +1 -1
package/dist/server/rsc-entry/index.d.ts +6 -1
package/dist/server/rsc-entry/index.d.ts.map +1 -1
package/dist/server/rsc-entry/rsc-payload.d.ts.map +1 -1
package/dist/server/rsc-entry/rsc-stream.d.ts +3 -0
package/dist/server/rsc-entry/rsc-stream.d.ts.map +1 -1
package/dist/server/ssr-entry.d.ts.map +1 -1
package/dist/server/ssr-render.d.ts +2 -0
package/dist/server/ssr-render.d.ts.map +1 -1
package/package.json +1 -1
package/src/adapters/nitro.ts +27 -4
package/src/cache/index.ts +5 -2
package/src/cache/singleflight.ts +54 -4
package/src/cache/timber-cache.ts +17 -16
package/src/index.ts +12 -0
package/src/plugins/dev-error-overlay.ts +70 -1
package/src/plugins/dev-server.ts +38 -4
package/src/plugins/entries.ts +1 -0
package/src/server/html-injectors.ts +32 -7
package/src/server/index.ts +4 -0
package/src/server/node-stream-transforms.ts +49 -13
package/src/server/render-timeout.ts +108 -0
package/src/server/rsc-entry/helpers.ts +122 -3
package/src/server/rsc-entry/index.ts +34 -4
package/src/server/rsc-entry/rsc-payload.ts +11 -3
package/src/server/rsc-entry/rsc-stream.ts +24 -3
package/src/server/ssr-entry.ts +9 -2
package/src/server/ssr-render.ts +94 -13

package/src/server/html-injectors.ts CHANGED Viewed

@@ -17,6 +17,7 @@ import {
   type FlightInjectionState,
   type FlightInjectionEvent,
 } from './flight-injection-state.js';
+import { withTimeout, RenderTimeoutError } from './render-timeout.js';
 /**
  * Inject HTML content before a closing tag in the stream.
@@ -118,11 +119,13 @@ export function injectScripts(
  * flightInitScript() — see flight-scripts.ts.
  */
 export function createInlinedRscStream(
-  rscStream: ReadableStream<Uint8Array>
+  rscStream: ReadableStream<Uint8Array>,
+  renderTimeoutMs?: number
 ): ReadableStream<Uint8Array> {
   const encoder = new TextEncoder();
   const rscReader = rscStream.getReader();
   const decoder = new TextDecoder('utf-8', { fatal: true });
+  const timeoutMs = renderTimeoutMs ?? 30_000;
   return new ReadableStream<Uint8Array>({
     // No bootstrap signal here — the init script is in <head> via
@@ -130,7 +133,11 @@ export function createInlinedRscStream(
     // __timber_f array exists before any chunk scripts execute.
     async pull(controller) {
       try {
-        const { done, value } = await rscReader.read();
+        const readPromise = rscReader.read();
+        const { done, value } =
+          timeoutMs > 0
+            ? await withTimeout(readPromise, timeoutMs, 'RSC stream read timed out')
+            : await readPromise;
         if (done) {
           controller.close();
           return;
@@ -140,6 +147,9 @@ export function createInlinedRscStream(
           controller.enqueue(encoder.encode(flightChunkScript(decoded)));
         }
       } catch (error) {
+        if (error instanceof RenderTimeoutError) {
+          rscReader.cancel(error).catch(() => {});
+        }
         controller.error(error);
       }
     },
@@ -173,7 +183,8 @@ export function createInlinedRscStream(
  * Inspired by Next.js createFlightDataInjectionTransformStream.
  */
 function createFlightInjectionTransform(
-  rscScriptStream: ReadableStream<Uint8Array>
+  rscScriptStream: ReadableStream<Uint8Array>,
+  renderTimeoutMs?: number
 ): TransformStream<Uint8Array, Uint8Array> {
   const encoder = new TextEncoder();
   const decoder = new TextDecoder();
@@ -181,6 +192,7 @@ function createFlightInjectionTransform(
   const suffixBytes = encoder.encode(suffix);
   const rscReader = rscScriptStream.getReader();
+  const timeoutMs = renderTimeoutMs ?? 30_000;
   const machine = createMachine<FlightInjectionState, FlightInjectionEvent>({
     initial: { phase: 'init' },
@@ -205,7 +217,15 @@ function createFlightInjectionTransform(
     try {
       for (;;) {
-        const { done, value } = await rscReader.read();
+        // Guard each RSC read with a timeout so a permanently hung
+        // RSC stream eventually aborts. When timeoutMs <= 0, the
+        // guard is disabled. See design/02-rendering-pipeline.md
+        // §"Streaming Constraints".
+        const readPromise = rscReader.read();
+        const { done, value } =
+          timeoutMs > 0
+            ? await withTimeout(readPromise, timeoutMs, 'RSC stream read timed out')
+            : await readPromise;
         if (done) {
           machine.send({ type: 'PULL_DONE' });
           return;
@@ -220,6 +240,10 @@ function createFlightInjectionTransform(
         }
       }
     } catch (err) {
+      // On timeout, cancel the RSC reader to release resources.
+      if (err instanceof RenderTimeoutError) {
+        rscReader.cancel(err).catch(() => {});
+      }
       machine.send({ type: 'PULL_ERROR', error: err });
     }
   }
@@ -326,16 +350,17 @@ function createFlightInjectionTransform(
  */
 export function injectRscPayload(
   htmlStream: ReadableStream<Uint8Array>,
-  rscStream: ReadableStream<Uint8Array> | undefined
+  rscStream: ReadableStream<Uint8Array> | undefined,
+  renderTimeoutMs?: number
 ): ReadableStream<Uint8Array> {
   if (!rscStream) return htmlStream;
   // Transform RSC binary stream → stream of <script> tags
-  const rscScriptStream = createInlinedRscStream(rscStream);
+  const rscScriptStream = createInlinedRscStream(rscStream, renderTimeoutMs);
   // Single transform: strip </body></html>, inject RSC scripts at
   // body level, re-emit suffix at the very end.
-  return htmlStream.pipeThrough(createFlightInjectionTransform(rscScriptStream));
+  return htmlStream.pipeThrough(createFlightInjectionTransform(rscScriptStream, renderTimeoutMs));
 }
 /**

package/src/server/index.ts CHANGED Viewed

@@ -222,3 +222,7 @@ export type { DevWarningConfig } from './dev-warnings';
 // Design doc: design/07-routing.md §"route.ts — API Endpoints"
 export { handleRouteRequest, resolveAllowedMethods } from './route-handler';
 export type { RouteModule, RouteHandler, HttpMethod } from './route-handler';
+// Render timeout — design doc: 02-rendering-pipeline.md §"Streaming Constraints"
+export { RenderTimeoutError } from './render-timeout';
+export type { RenderTimeout } from './render-timeout';

package/src/server/node-stream-transforms.ts CHANGED Viewed

@@ -30,6 +30,7 @@ import {
   type FlightInjectionState,
   type FlightInjectionEvent,
 } from './flight-injection-state.js';
+import { withTimeout, RenderTimeoutError } from './render-timeout.js';
 // ─── Head Injection ──────────────────────────────────────────────────────────
@@ -108,8 +109,22 @@ export function createNodeHeadInjector(headHtml: string): Transform {
  * stream). We read from it using the Web API — this is the one bridge
  * point between Web Streams and Node.js streams in the pipeline.
  */
+/**
+ * Options for the Node.js flight injector.
+ */
+export interface NodeFlightInjectorOptions {
+  /**
+   * Timeout in milliseconds for individual RSC stream reads.
+   * If a single `rscReader.read()` call does not resolve within
+   * this duration, the read is aborted and the stream errors with
+   * a RenderTimeoutError. Default: 30000 (30s).
+   */
+  renderTimeoutMs?: number;
+}
 export function createNodeFlightInjector(
-  rscStream: ReadableStream<Uint8Array> | undefined
+  rscStream: ReadableStream<Uint8Array> | undefined,
+  options?: NodeFlightInjectorOptions
 ): Transform {
   if (!rscStream) {
     return new Transform({
@@ -119,6 +134,7 @@ export function createNodeFlightInjector(
     });
   }
+  const timeoutMs = options?.renderTimeoutMs ?? 30_000;
   const suffix = '</body></html>';
   const suffixBuf = Buffer.from(suffix, 'utf-8');
   const rscReader = rscStream.getReader();
@@ -129,6 +145,11 @@ export function createNodeFlightInjector(
     transitions: flightInjectionTransitions,
   });
+  // Stored promise from pullLoop — awaited in flush() via .then()
+  // instead of polling. Matches the Web Streams pattern in
+  // html-injectors.ts (pullPromise.then(finish)).
+  let pullPromise: Promise<void> | null = null;
   // pullLoop reads RSC chunks and pushes them directly to the transform
   // output as <script> tags. This ensures RSC data is delivered to the
   // browser as soon as it's available — not deferred until the next HTML
@@ -141,7 +162,16 @@ export function createNodeFlightInjector(
     await new Promise<void>((r) => setImmediate(r));
     try {
       for (;;) {
-        const { done, value } = await rscReader.read();
+        // Guard each RSC read with a timeout so a permanently hung
+        // RSC stream (e.g. a Suspense component with a fetch that
+        // never resolves) eventually aborts instead of blocking
+        // forever. When timeoutMs <= 0, the guard is disabled.
+        // See design/02-rendering-pipeline.md §"Streaming Constraints".
+        const readPromise = rscReader.read();
+        const { done, value } =
+          timeoutMs > 0
+            ? await withTimeout(readPromise, timeoutMs, 'RSC stream read timed out')
+            : await readPromise;
         if (done) {
           machine.send({ type: 'PULL_DONE' });
           return;
@@ -160,6 +190,10 @@ export function createNodeFlightInjector(
         }
       }
     } catch (err) {
+      // On timeout, cancel the RSC reader to release resources.
+      if (err instanceof RenderTimeoutError) {
+        rscReader.cancel(err).catch(() => {});
+      }
       machine.send({ type: 'PULL_ERROR', error: err });
     }
   }
@@ -196,8 +230,9 @@ export function createNodeFlightInjector(
       // Start the pull loop on the first HTML chunk to stream RSC
       // data chunks alongside the HTML. The __timber_f init script is
       // already in <head> (via flightInitScript), so no bootstrap needed.
+      // Store the promise so flush() can await it instead of polling.
       if (isFirst) {
-        pullLoop(transform);
+        pullPromise = pullLoop(transform);
       }
       callback();
     },
@@ -226,16 +261,17 @@ export function createNodeFlightInjector(
         finish();
         return;
       }
-      // Wait for the RSC stream to finish before closing.
-      // pullLoop is already running and pushing directly.
-      const waitForPull = () => {
-        if (isPullDone(machine.state)) {
-          finish();
-        } else {
-          setImmediate(waitForPull);
-        }
-      };
-      waitForPull();
+      // Wait for the RSC pull loop promise to resolve instead of
+      // polling with setImmediate. This matches the Web Streams
+      // pattern in html-injectors.ts: `pullPromise.then(finish)`.
+      // No CPU spin, no busy-poll — just a Promise chain.
+      if (!pullPromise) {
+        pullPromise = pullLoop(transform);
+      }
+      pullPromise.then(finish, (err) => {
+        machine.send({ type: 'PULL_ERROR', error: err });
+        finish();
+      });
     },
   });

package/src/server/render-timeout.ts ADDED Viewed

@@ -0,0 +1,108 @@
+/**
+ * Render timeout utilities for SSR streaming pipeline.
+ *
+ * Provides a RenderTimeoutError class and a helper to create
+ * timeout-guarded AbortSignals. Used to defend against hung RSC
+ * streams and infinite SSR renders.
+ *
+ * Design doc: 02-rendering-pipeline.md §"Streaming Constraints"
+ */
+/**
+ * Error thrown when an SSR render or RSC stream read exceeds the
+ * configured timeout. Callers can check `instanceof RenderTimeoutError`
+ * to distinguish timeout from other errors and return a 504 or close
+ * the connection cleanly.
+ */
+export class RenderTimeoutError extends Error {
+  readonly timeoutMs: number;
+  constructor(timeoutMs: number, context?: string) {
+    const message = context
+      ? `Render timeout after ${timeoutMs}ms: ${context}`
+      : `Render timeout after ${timeoutMs}ms`;
+    super(message);
+    this.name = 'RenderTimeoutError';
+    this.timeoutMs = timeoutMs;
+  }
+}
+/**
+ * Result of createRenderTimeout — an AbortSignal that fires after
+ * the given duration, plus a cancel function to clear the timer
+ * when the render completes normally.
+ */
+export interface RenderTimeout {
+  /** AbortSignal that aborts after timeoutMs. */
+  signal: AbortSignal;
+  /** Cancel the timeout timer. Call this when the render completes. */
+  cancel: () => void;
+}
+/**
+ * Create a render timeout that aborts after the given duration.
+ *
+ * Returns an AbortSignal and a cancel function. The signal fires
+ * with a RenderTimeoutError as the abort reason after `timeoutMs`.
+ * Call `cancel()` when the render completes to prevent the timeout
+ * from firing.
+ *
+ * If an existing `parentSignal` is provided, the returned signal
+ * aborts when either the parent signal or the timeout fires —
+ * whichever comes first.
+ */
+export function createRenderTimeout(timeoutMs: number, parentSignal?: AbortSignal): RenderTimeout {
+  const controller = new AbortController();
+  const reason = new RenderTimeoutError(timeoutMs, 'RSC stream read timed out');
+  const timer = setTimeout(() => {
+    controller.abort(reason);
+  }, timeoutMs);
+  // If there's a parent signal (e.g. request abort), chain it
+  if (parentSignal) {
+    if (parentSignal.aborted) {
+      clearTimeout(timer);
+      controller.abort(parentSignal.reason);
+    } else {
+      parentSignal.addEventListener(
+        'abort',
+        () => {
+          clearTimeout(timer);
+          controller.abort(parentSignal.reason);
+        },
+        { once: true }
+      );
+    }
+  }
+  return {
+    signal: controller.signal,
+    cancel: () => {
+      clearTimeout(timer);
+    },
+  };
+}
+/**
+ * Race a promise against a timeout. Rejects with RenderTimeoutError
+ * if the promise does not resolve within `timeoutMs`.
+ *
+ * Used to guard individual `rscReader.read()` calls inside pullLoop.
+ */
+export function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  context?: string
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout>;
+  const timeoutPromise = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(new RenderTimeoutError(timeoutMs, context));
+    }, timeoutMs);
+  });
+  return Promise.race([promise, timeoutPromise]).finally(() => {
+    clearTimeout(timer!);
+  });
+}

package/src/server/rsc-entry/helpers.ts CHANGED Viewed

@@ -20,9 +20,6 @@ export const RSC_CONTENT_TYPE = 'text/x-component';
  * stream that we drain and discard.
  *
  * See design/13-security.md §"Server component source leak"
- *
- * TODO: In the future, expose this debug data to the browser in dev mode
- * for inline error overlays (e.g. component stack traces).
  */
 export function createDebugChannelSink(): { readable: ReadableStream; writable: WritableStream } {
   const sink = new TransformStream();
@@ -34,6 +31,128 @@ export function createDebugChannelSink(): { readable: ReadableStream; writable:
   };
 }
+// ─── Debug Channel Collector (dev mode only) ────────────────────────────
+/**
+ * Parsed component debug info extracted from the Flight debug channel.
+ *
+ * Contains only component names, environment labels, and stack frames —
+ * never source code or props. See design/13-security.md §"Server source
+ * never reaches the client".
+ */
+export interface DebugComponentEntry {
+  name: string;
+  env: string | null;
+  key: string | null;
+  stack: unknown[] | null;
+}
+/**
+ * A debug channel that collects Flight debug rows instead of discarding them.
+ *
+ * Used in dev mode to capture server component tree information for the
+ * Vite error overlay. The collector provides the same `{ readable, writable }`
+ * shape as the discard sink, plus methods to retrieve collected data.
+ *
+ * Security: only component names, environments, and stack frames are
+ * extracted — props and source code are stripped. In production builds,
+ * use `createDebugChannelSink()` instead (this function is never called).
+ */
+export interface DebugChannelCollector {
+  readable: ReadableStream;
+  writable: WritableStream;
+  /** Get the raw collected text from the debug channel. */
+  getCollectedText(): string;
+  /** Get parsed component entries (names, stacks — no props or source). */
+  getComponents(): DebugComponentEntry[];
+}
+export function createDebugChannelCollector(): DebugChannelCollector {
+  const chunks: string[] = [];
+  const decoder = new TextDecoder();
+  const sink = new TransformStream();
+  // Collect chunks from the readable side instead of discarding them.
+  sink.readable
+    .pipeTo(
+      new WritableStream({
+        write(chunk: Uint8Array) {
+          chunks.push(decoder.decode(chunk, { stream: true }));
+        },
+        close() {
+          // Flush any remaining bytes in the decoder
+          const remaining = decoder.decode();
+          if (remaining) chunks.push(remaining);
+        },
+      })
+    )
+    .catch(() => {
+      // Stream abort — request cancelled. Not an error.
+    });
+  return {
+    readable: new ReadableStream(), // no commands to send to Flight
+    writable: sink.writable,
+    getCollectedText() {
+      return chunks.join('');
+    },
+    getComponents() {
+      return parseDebugRows(chunks.join(''));
+    },
+  };
+}
+/**
+ * Parse React Flight debug rows into component entries.
+ *
+ * The Flight debug channel writes rows in `hexId:json\n` format. Each row
+ * with a JSON object containing a `name` field is a component debug info
+ * entry. Rows without `name` (timing rows, reference rows like `D"$id"`)
+ * are skipped.
+ *
+ * Security: `props` are explicitly stripped from parsed entries — they may
+ * contain rendered output or user data. Only `name`, `env`, `key`, and
+ * `stack` are retained.
+ */
+export function parseDebugRows(text: string): DebugComponentEntry[] {
+  if (!text) return [];
+  const entries: DebugComponentEntry[] = [];
+  const lines = text.split('\n');
+  for (const line of lines) {
+    if (!line) continue;
+    // Flight row format: hexId:payload
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) continue;
+    const payload = line.slice(colonIdx + 1);
+    // Skip non-JSON payloads (e.g., D"$a" reference rows)
+    if (!payload.startsWith('{')) continue;
+    try {
+      const parsed = JSON.parse(payload);
+      if (typeof parsed !== 'object' || parsed === null) continue;
+      if (typeof parsed.name !== 'string') continue;
+      // Strip props — may contain source-derived data or user data.
+      // Only retain: name, env, key, stack.
+      entries.push({
+        name: parsed.name,
+        env: parsed.env ?? null,
+        key: parsed.key ?? null,
+        stack: Array.isArray(parsed.stack) ? parsed.stack : null,
+      });
+    } catch {
+      // Malformed JSON — skip this row
+    }
+  }
+  return entries;
+}
 /**
  * Build segment metadata for the X-Timber-Segments response header.
  * Describes the rendered segment chain with async status, enabling

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

@@ -65,6 +65,7 @@ import {
   createDebugChannelSink,
   escapeHtml,
   isRscPayloadRequest,
+  type DebugComponentEntry,
 } from './helpers.js';
 import { parseClientStateTree } from '#/server/state-tree-diff.js';
 import { buildRscPayloadResponse } from './rsc-payload.js';
@@ -91,18 +92,35 @@ function resolveServerTimingMode(
 // 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.
  *
@@ -231,7 +249,15 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
     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) =>
@@ -441,7 +467,11 @@ async function renderRoute(
   // Render to RSC Flight stream with signal tracking.
   const _rscStart = performance.now();
-  const { rscStream, signals } = renderRscStream(element, _req);
+  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),

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

@@ -103,9 +103,17 @@ export async function buildRscPayloadResponse(
   }
   // Extract the first chunk from the race result.
-  // If the signal won the race, read the first chunk now (the stream
-  // was already cancelled above, but we need a firstRead shape below).
-  const firstRead = first.type === 'data' ? first.chunk : await reader.read();
+  // 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.

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

@@ -16,8 +16,14 @@ 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.
@@ -40,6 +46,8 @@ export interface RenderSignals {
 export interface RscStreamResult {
   rscStream: ReadableStream<Uint8Array> | undefined;
   signals: RenderSignals;
+  /** Dev-only: server component debug info from the Flight debug channel. */
+  getDebugComponents?: () => DebugComponentEntry[];
 }
 /**
@@ -62,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,
@@ -132,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 }) {
@@ -160,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,
+  };
 }