@timber-js/app 0.2.0-alpha.13 → 0.2.0-alpha.131

package/src/server/rsc-entry/render-route.ts

@@ -0,0 +1,313 @@
+/**
+ * Route renderer — turns a matched route into a Response.
+ *
+ * Extracted from `rsc-entry/index.ts` so the entry can stay focused on
+ * pipeline construction. This module owns the steps that happen *after*
+ * the pipeline has matched a route and before it commits a response:
+ * element-tree build, RSC Flight render, and dispatch to either the SSR
+ * HTML path or the RSC payload path. It also handles the
+ * synchronous-signal escape hatches (deny / redirect / render error
+ * thrown during stream creation) so the entry doesn't carry that logic.
+ *
+ * The function is parameterized over its dependencies — `clientBootstrap`,
+ * `clientJsDisabled`, `rootSegment`, `globalError` — so the entry passes
+ * them in once at handler-construction time and they ride along on every
+ * call. No globals, no closures over the entry's createRequestHandler
+ * scope.
+ *
+ * Design docs: 02-rendering-pipeline.md, 19-client-navigation.md.
+ */
+
+import type { BuildManifest } from '../build-manifest.js';
+import {
+  buildFontPreloadTags,
+  buildModulepreloadTags,
+  collectRouteFonts,
+  collectRouteModulepreloads,
+} from '../build-manifest.js';
+import { isDevMode } from '../debug.js';
+import type { LayoutEntry } from '../deny-renderer.js';
+import { renderDenyPage, renderDenyPageAsRsc } from '../deny-renderer.js';
+import type { ClientBootstrapConfig } from '../html-injectors.js';
+import type { InterceptionContext, RouteMatch } from '../pipeline.js';
+import { buildRouteElement, ParamCoercionError } from '../route-element-builder.js';
+import type { ManifestSegmentNode } from '../route-matcher.js';
+import { recordTiming } from '../server-timing.js';
+import { requestContextAls } from '../als-registry.js';
+import { parseClientStateTree } from '../state-tree-diff.js';
+
+import { handleApiRoute } from './api-handler.js';
+import { renderErrorPage, renderNoMatchPage } from './error-renderer.js';
+import {
+  buildRedirectResponse,
+  createDebugChannelSink,
+  escapeHtml,
+  isRscPayloadRequest,
+} from './helpers.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';
+
+/**
+ * Static-per-handler dependencies for `renderRoute` — captured once at
+ * handler construction so each per-request call site only has to pass
+ * the request-specific arguments.
+ */
+export interface RenderRouteDeps {
+  clientBootstrap: ClientBootstrapConfig;
+  clientJsDisabled: boolean;
+  rootSegment: ManifestSegmentNode;
+  buildManifest: BuildManifest;
+  globalError?: { load: () => Promise<unknown>; filePath: string };
+}
+
+/**
+ * Render a matched route to an HTML Response via RSC → SSR pipeline,
+ * or return a raw RSC Flight stream for client-side navigation requests.
+ *
+ * 1. Load page/layout components from the segment chain
+ * 2. Resolve metadata
+ * 3. Render to RSC Flight stream (serializes "use client" as references)
+ * 4. If Accept: text/x-component → return RSC stream directly
+ *    Otherwise → pass RSC stream to SSR entry for HTML rendering
+ */
+export async function renderRoute(
+  req: Request,
+  match: RouteMatch,
+  responseHeaders: Headers,
+  deps: RenderRouteDeps,
+  interception?: InterceptionContext
+): Promise<Response> {
+  const { clientBootstrap, clientJsDisabled, rootSegment, buildManifest, globalError } = deps;
+  const segments = match.segments;
+  const leaf = segments[segments.length - 1];
+
+  // API routes (route.ts) — run access.ts standalone then dispatch to handler.
+  // No React render pass — AccessGate is not used, React.cache is not active.
+  // See design/04-authorization.md §"Auth in API Routes".
+  if (leaf.route && !leaf.page) {
+    return handleApiRoute(req, match, segments, responseHeaders);
+  }
+
+  // Parse X-Timber-State-Tree for RSC payload requests (client navigation).
+  // The state tree lists sync segments the client has cached — the server
+  // skips re-rendering those layouts for a smaller, faster RSC payload.
+  // Only used for RSC requests — HTML requests always get a full render.
+  // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+  const clientStateTree = isRscPayloadRequest(req) ? parseClientStateTree(req) : null;
+
+  // Build the React element tree — loads modules, collects access checks,
+  // resolves metadata. Access checks are NOT run here — they run inside
+  // AccessPreRunner during renderToReadableStream so that access.ts and
+  // render components share the same React.cache scope (TIM-662).
+  //
+  // DenySignal/RedirectSignal from access checks are caught by onError
+  // during stream consumption and handled by renderSsrResponse /
+  // buildRscPayloadResponse.
+  let routeResult;
+  const _buildStart = performance.now();
+  try {
+    routeResult = await buildRouteElement(
+      req,
+      match,
+      interception,
+      clientStateTree,
+      buildManifest.metadataRouteHashes
+    );
+  } catch (error) {
+    // 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')) {
+      if (process.env.NODE_ENV !== 'production') {
+        console.warn(`[timber] ${error.message}`);
+      }
+      return renderNoMatchPage(req, rootSegment, responseHeaders, clientBootstrap);
+    }
+    throw error;
+  }
+
+  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.
+  // In dev mode the manifest is empty — Vite HMR handles CSS/JS.
+  //
+  // Link headers (for 103 Early Hints) are emitted by the earlyHints pipeline
+  // stage before middleware runs. Here we only emit the <head> HTML fallback tags
+  // — these ensure resources load even on platforms without Early Hints support.
+  let headHtml = '';
+
+  // CSS is handled by the RSC plugin via ReactDOM.preinit() with
+  // data-precedence attributes. This injects <link rel="stylesheet">
+  // tags during the RSC render phase — before our headHtml injection.
+  // We do NOT emit additional <link rel="stylesheet"> tags here because:
+  // 1. React's Float system deduplicates them, making ours redundant
+  // 2. The duplicate reference confuses React's client-side preload
+  //    deduplication, causing "preload ignored" browser warnings
+  //
+  // CSS URLs are still collected for Early Hints (Link headers) in
+  // buildEarlyHintsHeaders() — those are HTTP headers, not DOM elements,
+  // so they don't conflict with Float.
+
+  // Font CSS is NOT inlined here anymore (TIM-828). The transform hook
+  // injects a side-effect `import 'virtual:timber-font-css/<hash>.css'`
+  // into each file that calls a font function. @vitejs/plugin-rsc's
+  // `collectCss` walks the RSC module graph, finds the virtual CSS
+  // module, and React Float `preinit()`s it as
+  // `<link rel="stylesheet" data-rsc-css-href=...>` — the same path
+  // component CSS rides on. Dev and production share a single path,
+  // with no `globalThis` channel and no dev/prod skew.
+  //
+  // Font preload hints (distinct from the @font-face CSS) still flow
+  // through `BuildManifest.fonts[importer]` and are emitted below plus
+  // as 103 Early Hints via `buildEarlyHintsHeaders()`.
+  const fontEntries = collectRouteFonts(segments, buildManifest);
+  if (fontEntries.length > 0) {
+    headHtml += buildFontPreloadTags(fontEntries);
+  }
+
+  // Skip modulepreload tags when client JavaScript is disabled — no JS to preload.
+  if (!clientJsDisabled) {
+    const preloadUrls = collectRouteModulepreloads(segments, buildManifest);
+    if (preloadUrls.length > 0) {
+      headHtml += buildModulepreloadTags(preloadUrls);
+    }
+  }
+
+  for (const el of headElements) {
+    if (el.tag === 'title' && el.content) {
+      headHtml += `<title>${escapeHtml(el.content)}</title>`;
+    } else if (el.attrs) {
+      const attrs = Object.entries(el.attrs)
+        .filter(([, v]) => v != null)
+        .map(([k, v]) => `${k}="${escapeHtml(v as string)}"`)
+        .join(' ');
+      headHtml += `<${el.tag} ${attrs}>`;
+    }
+  }
+
+  // In dev mode, inject the browser log forwarding script so console
+  // errors/warnings from the browser appear in the server terminal.
+  // Set by timber-dev-browser-logs plugin via globalThis (TIM-575).
+  if (isDevMode()) {
+    const devLogScript = (globalThis as Record<string, unknown>).__timber_dev_browser_log_script as
+      | string
+      | undefined;
+    if (devLogScript) {
+      headHtml += devLogScript;
+    }
+  }
+
+  // Render to RSC Flight stream with signal tracking.
+  const _rscStart = performance.now();
+  const { rscStream, signals, getDebugComponents } = renderRscStream(element, req);
+
+  // Store the debug components getter in ALS so onPipelineError can
+  // include component tree context for render-phase errors (dev mode only).
+  // Per-request via ALS — no cross-request race. See TIM-557.
+  const alsStore = requestContextAls.getStore();
+  if (alsStore) {
+    alsStore.debugComponentsGetter = 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.
+  if (signals.redirectSignal) {
+    return buildRedirectResponse(req, signals.redirectSignal, responseHeaders);
+  }
+
+  // Synchronous deny — deny() in a non-async component throws during
+  // renderToReadableStream creation, caught in the try/catch above.
+  if (signals.denySignal) {
+    if (isRscPayloadRequest(req)) {
+      return renderDenyPageAsRsc(
+        signals.denySignal,
+        segments,
+        layoutComponents as LayoutEntry[],
+        responseHeaders,
+        createDebugChannelSink
+      );
+    }
+    return renderDenyPage(
+      signals.denySignal,
+      segments,
+      layoutComponents as LayoutEntry[],
+      req,
+      match,
+      responseHeaders,
+      clientBootstrap,
+      createDebugChannelSink,
+      callSsr
+    );
+  }
+
+  // Synchronous render error — renderToReadableStream threw before
+  // creating the stream. Render the error page with correct 5xx status.
+  // (Async render errors are tracked in onError and handled after SSR.)
+  if (signals.renderError && !rscStream) {
+    return renderErrorPage(
+      signals.renderError.error,
+      signals.renderError.status,
+      segments,
+      layoutComponents as LayoutEntry[],
+      req,
+      match,
+      responseHeaders,
+      clientBootstrap,
+      globalError
+    );
+  }
+
+  // For RSC payload requests (client navigation), return the RSC Flight
+  // stream directly — skip SSR HTML rendering entirely.
+  // See design/19-client-navigation.md §"RSC Payload Handling"
+  if (isRscPayloadRequest(req)) {
+    return buildRscPayloadResponse(
+      req,
+      rscStream!,
+      signals,
+      segments,
+      layoutComponents,
+      headElements,
+      match,
+      responseHeaders,
+      skippedSegments
+    );
+  }
+
+  // Pipe through SSR for HTML rendering with streaming Suspense support.
+  return renderSsrResponse({
+    req,
+    rscStream: rscStream!,
+    signals,
+    segments,
+    layoutComponents,
+    match,
+    responseHeaders,
+    clientBootstrap,
+    clientJsDisabled,
+    headHtml,
+    deferSuspenseFor,
+    globalError,
+  });
+}

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

@@ -9,12 +9,12 @@
  *              16-metadata.md §"Head Elements"
  */
 
-import type { LayoutEntry } from '#/server/deny-renderer.js';
-import { renderDenyPageAsRsc } from '#/server/deny-renderer.js';
-import type { RouteMatch } from '#/server/pipeline.js';
-import type { RedirectSignal } from '#/server/primitives.js';
-import type { HeadElement, LayoutComponentEntry } from '#/server/route-element-builder.js';
-import type { ManifestSegmentNode } from '#/server/route-matcher.js';
+import type { LayoutEntry } from '../deny-renderer.js';
+import { renderDenyPageAsRsc } from '../deny-renderer.js';
+import type { RouteMatch } from '../pipeline.js';
+import type { RedirectSignal } from '../primitives.js';
+import type { HeadElement, LayoutComponentEntry } from '../route-element-builder.js';
+import type { ManifestSegmentNode } from '../route-matcher.js';
 
 import {
   buildRedirectResponse,
@@ -69,10 +69,25 @@ export async function buildRscPayloadResponse(
     | { 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 })),
-  ]);
+  let first: RaceResult;
+  try {
+    first = await Promise.race([
+      reader.read().then((chunk) => ({ type: 'data' as const, chunk })),
+      signalDetected.then(() => ({ type: 'signal' as const })),
+    ]);
+  } catch (_readError) {
+    // RSC stream failed on first read — unhandled error in the page component.
+    // Return an error response so the client can hard-navigate for the
+    // SSR-rendered error page. See design/10-error-handling.md.
+    reader.cancel().catch(() => {});
+    signals.onSignal = undefined;
+    responseHeaders.set('X-Timber-Error', '1');
+    responseHeaders.set('content-type', 'application/json; charset=utf-8');
+    return new Response(JSON.stringify({ error: true, status: 500 }), {
+      status: 500,
+      headers: responseHeaders,
+    });
+  }
 
   // If data arrived first, still check signals — they may have fired
   // concurrently. Also do a final ceiling timeout check for edge cases
@@ -102,10 +117,36 @@ export async function buildRscPayloadResponse(
     );
   }
 
+  // Check for unhandled errors (RenderError or plain Error).
+  // These aren't redirect/deny signals but the RSC stream will be broken.
+  // Return an error response so the client can hard-navigate for the
+  // SSR-rendered error page. See design/10-error-handling.md
+  // §"Error Page Rendering for Client Navigation".
+  if (signals.renderError) {
+    reader.cancel().catch(() => {});
+    responseHeaders.set('X-Timber-Error', '1');
+    responseHeaders.set('content-type', 'application/json; charset=utf-8');
+    return new Response(
+      JSON.stringify({
+        error: true,
+        status: signals.renderError.status,
+      }),
+      { status: signals.renderError.status, headers: responseHeaders }
+    );
+  }
+
   // 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.
@@ -155,14 +196,20 @@ 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 {}.
-  if (Object.keys(match.params).length > 0) {
-    responseHeaders.set('X-Timber-Params', JSON.stringify(match.params));
+  // Send route params so the client can populate useSegmentParams() after
+  // SPA navigation. Without this, useSegmentParams() returns {}.
+  if (Object.keys(match.segmentParams).length > 0) {
+    responseHeaders.set('X-Timber-Params', JSON.stringify(match.segmentParams));
   }
 
+  // Check if a DenySignal was caught in-tree by AccessGate or
+  // PageDenyBoundary. The deny page is in the Flight stream as a normal
+  // element — use the deny status for the HTTP response. See TIM-666.
+  const { getDenyStatus } = await import('../deny-boundary.js');
+  const denyStatus = getDenyStatus();
+
   return new Response(patchedStream, {
-    status: 200,
+    status: denyStatus ?? 200,
     headers: responseHeaders,
   });
 }

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

@@ -10,14 +10,22 @@
  *              13-security.md §"Errors don't leak"
  */
 
-import { renderToReadableStream } from '#/rsc-runtime/rsc.js';
+import { renderToReadableStream } from '../../rsc-runtime/rsc.js';
 
-import { logRenderError } from '#/server/logger.js';
-import { DenySignal, RedirectSignal, RenderError } from '#/server/primitives.js';
-import { checkAndWarnRscPropError } from '#/server/rsc-prop-warnings.js';
+import { randomUUID } from 'node:crypto';
 
-import { createDebugChannelSink, isAbortError } from './helpers.js';
-import { isDebug } from '#/server/debug.js';
+import { logRenderError } from '../logger.js';
+import { DenySignal, RedirectSignal, RenderError } from '../primitives.js';
+import { checkAndWarnRscPropError } from '../rsc-prop-warnings.js';
+
+import {
+  createDebugChannelSink,
+  createDebugChannelCollector,
+  isAbortError,
+  type DebugComponentEntry,
+} from './helpers.js';
+import { isDebug } from '../debug.js';
+import { isDevMode } from '../debug.js';
 
 /**
  * Mutable signal state captured during RSC rendering.
@@ -33,13 +41,28 @@ export interface RenderSignals {
   denySignal: DenySignal | null;
   redirectSignal: RedirectSignal | null;
   renderError: { error: unknown; status: number } | null;
+  /**
+   * The last unhandled error seen by RSC onError that isn't a signal.
+   * Used as a fallback when SSR fails (SsrStreamError) but no structured
+   * signal was captured — provides the original error for the error page
+   * instead of relying on SsrStreamError.cause extraction.
+   *
+   * NOT used for page-level error detection (that would break Suspense
+   * error isolation). Only consumed when SSR actually fails.
+   */
+  lastUnhandledError: unknown | null;
   /** Callback fired when a redirect or deny signal is captured in onError. */
   onSignal?: () => void;
+  /** Callback fired when an unhandled error (non-signal) is captured. Used
+   *  to halt Flight data injection into the inline stream. */
+  onUnhandledError?: () => void;
 }
 
 export interface RscStreamResult {
   rscStream: ReadableStream<Uint8Array> | undefined;
   signals: RenderSignals;
+  /** Dev-only: server component debug info from the Flight debug channel. */
+  getDebugComponents?: () => DebugComponentEntry[];
 }
 
 /**
@@ -58,10 +81,15 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
     denySignal: null,
     redirectSignal: null,
     renderError: null,
+    lastUnhandledError: null,
   };
 
   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,
@@ -126,13 +154,48 @@ 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 };
-          }
-          logRenderError({ method: req.method, path: new URL(req.url).pathname, error });
+          // 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.
+
+          // Track the last unhandled error so the pipeline can use it
+          // if SSR fails (SsrStreamError). This is NOT used for page-level
+          // error detection — only as a fallback when SSR actually fails.
+          signals.lastUnhandledError = error;
+          signals.onUnhandledError?.();
+
+          // Return a digest so React emits a per-row error in the Flight
+          // stream instead of leaving the lazy reference unresolved.
+          //
+          // SECURITY: Never include error.message in the digest — it may
+          // contain SQL queries, filesystem paths, secret fragments, or
+          // internal IDs. Use a generic message with a correlation ID so
+          // the error can be matched to server logs.
+          // See design/13-security.md §"Errors don't leak".
+          const errorId = randomUUID();
+          logRenderError({
+            method: req.method,
+            path: new URL(req.url).pathname,
+            error,
+            errorId,
+          });
+          return JSON.stringify({
+            type: 'error',
+            message: isDevMode()
+              ? error instanceof Error
+                ? error.message
+                : String(error)
+              : 'An unexpected error occurred.',
+            errorId,
+          });
         },
-        debugChannel: createDebugChannelSink(),
+        debugChannel,
       },
       {
         onClientReference(info: { id: string; name: string; deps: unknown }) {
@@ -160,5 +223,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-bridge.ts

@@ -1,18 +1,31 @@
 /**
  * SSR Bridge — loads the SSR entry and passes the RSC stream for HTML rendering.
+ *
+ * This is the RSC → SSR environment hop. The two environments are separate
+ * Vite module graphs; `NavContext` is the serializable contract that crosses
+ * the boundary. See `../ssr-bridge-types.ts` for the contract definition.
  */
 
 /// <reference types="@vitejs/plugin-rsc/types" />
 
-import type { NavContext } from '#/server/ssr-entry.js';
+import type { NavContext } from '../ssr-bridge-types.js';
 
 export async function callSsr(
   rscStream: ReadableStream<Uint8Array>,
   navContext: NavContext
 ): Promise<Response> {
-  const ssrEntry = await import.meta.viteRsc.import<typeof import('#/server/ssr-entry.js')>(
-    '../ssr-entry.js',
-    { environment: 'ssr' }
-  );
+  let ssrEntry: typeof import('../ssr-entry.js');
+  try {
+    ssrEntry = await import.meta.viteRsc.import<typeof import('../ssr-entry.js')>(
+      '../ssr-entry.js',
+      { environment: 'ssr' }
+    );
+  } catch (error) {
+    const original = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `[timber] Failed to load SSR entry from RSC environment.\n  ${original}\n  This usually means a module evaluation error in the SSR bundle.`,
+      { cause: error }
+    );
+  }
   return ssrEntry.handleSsr(rscStream, navContext);
 }