@timber-js/app 0.2.0-alpha.5 → 0.2.0-alpha.50

package/src/server/route-matcher.ts

@@ -50,14 +50,14 @@ export interface ManifestSegmentNode {
   middleware?: ManifestFile;
   access?: ManifestFile;
   route?: ManifestFile;
+  /** params.ts — isomorphic convention file for segmentParams + searchParams definitions. */
+  params?: ManifestFile;
   error?: ManifestFile;
   default?: ManifestFile;
   denied?: ManifestFile;
-  searchParams?: ManifestFile;
   statusFiles?: Record<string, ManifestFile>;
   jsonStatusFiles?: Record<string, ManifestFile>;
   legacyStatusFiles?: Record<string, ManifestFile>;
-  prerender?: ManifestFile;
   /** Metadata route files (sitemap.ts, robots.ts, icon.tsx, etc.) keyed by base name */
   metadataRoutes?: Record<string, ManifestFile>;
 

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

@@ -12,10 +12,12 @@ import { logRenderError } from '#/server/logger.js';
 import type { ManifestSegmentNode } from '#/server/route-matcher.js';
 import { DenySignal, RenderError } from '#/server/primitives.js';
 import type { ClientBootstrapConfig } from '#/server/html-injectors.js';
+import { flightInitScript } from '#/server/flight-scripts.js';
 import { renderDenyPage } from '#/server/deny-renderer.js';
 import type { LayoutEntry } from '#/server/deny-renderer.js';
 import type { NavContext } from '#/server/ssr-entry.js';
-import { createDebugChannelSink, parseCookiesFromHeader } from './helpers.js';
+import { createDebugChannelSink } from './helpers.js';
+import { getCookiesForSsr } from '#/server/request-context.js';
 import { callSsr } from './ssr-bridge.js';
 
 /**
@@ -124,10 +126,10 @@ export async function renderErrorPage(
     searchParams: Object.fromEntries(new URL(req.url).searchParams),
     statusCode: status,
     responseHeaders,
-    headHtml: '',
+    headHtml: flightInitScript(),
     bootstrapScriptContent: clientBootstrap.bootstrapScriptContent,
     rscStream: inlineStream,
-    cookies: parseCookiesFromHeader(req.headers.get('cookie') ?? ''),
+    cookies: getCookiesForSsr(),
   };
 
   return callSsr(ssrStream, navContext);

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

@@ -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

@@ -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, 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);
@@ -164,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,
@@ -205,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);
@@ -224,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) =>
@@ -307,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];
@@ -329,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) {
@@ -361,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.
@@ -385,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);
@@ -411,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 " +
@@ -122,13 +138,25 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
             checkAndWarnRscPropError(error, new URL(req.url).pathname);
           }
 
-          // Track unhandled errors for pre-flush handling (500 status)
-          if (!signals.renderError) {
-            signals.renderError = { error, status: 500 };
-          }
+          // Log the error but do NOT track it as a page-level render error.
+          // If this error is inside a <Suspense> boundary, React will emit
+          // an error row in the Flight stream and the Suspense fallback will
+          // render on the client. Tracking it as signals.renderError would
+          // cause the pipeline to treat the entire page as a 500, even though
+          // the shell rendered successfully. See TIM-524.
+          //
+          // Only track as renderError if no Suspense boundary contains it —
+          // React will call onShellError for truly unrecoverable errors.
           logRenderError({ method: req.method, path: new URL(req.url).pathname, error });
+
+          // Return a digest so React emits a per-row error in the Flight
+          // stream instead of leaving the lazy reference unresolved.
+          return JSON.stringify({
+            type: 'error',
+            message: error instanceof Error ? error.message : String(error),
+          });
         },
-        debugChannel: createDebugChannelSink(),
+        debugChannel,
       },
       {
         onClientReference(info: { id: string; name: string; deps: unknown }) {
@@ -156,5 +184,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,
+  };
 }