@timber-js/app 0.2.0-alpha.14 → 0.2.0-alpha.141

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

@@ -1,136 +1,353 @@
 /**
  * RSC Error & No-Match Renderers — handles error pages and 404s.
  *
- * Renders error.tsx / status files and 404 pages through the RSC → SSR pipeline.
+ * All error pages (TSX and MDX) render through the RSC → SSR pipeline:
+ * - TSX ('use client'): Error is converted to SerializableError, wrapped
+ *   with ErrorReconstituter to reconstitute a real Error on the client.
+ * - MDX (server component): Receives plain props ({ status }), no wrapper needed.
+ *
+ * This unified approach replaces the former SSR-only bypass for TSX error
+ * pages. See design/spike-TIM-565-unify-error-pages.md for the full analysis.
+ *
+ * Design docs: 10-error-handling.md §"Three-Tier Error Page Rendering"
  */
 
 import { createElement } from 'react';
-import { renderToReadableStream } from '#/rsc-runtime/rsc.js';
-
-import type { RouteMatch } from '#/server/pipeline.js';
-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 { 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 { renderToReadableStream } from '../../rsc-runtime/rsc.js';
+
+import type { RouteMatch } from '../pipeline.js';
+import { logRenderError } from '../logger.js';
+import type { ManifestSegmentNode } from '../route-matcher.js';
+import { DenySignal, RenderError } from '../primitives.js';
+import type { ClientBootstrapConfig } from '../html-injectors.js';
+import { flightInitScript, htmlEscapeJsonString } from '../flight-scripts.js';
+import { renderDenyPage, renderDenyPageAsRsc } from '../deny-renderer.js';
+import type { LayoutEntry } from '../deny-renderer.js';
+import type { NavContext } from '../ssr-bridge-types.js';
+import { createDebugChannelSink, isRscPayloadRequest } from './helpers.js';
+import { getCookiesForSsr } from '../cookie-context.js';
 import { callSsr } from './ssr-bridge.js';
+import { teeWithErrorPropagation } from '../stream-utils.js';
+import { isDevMode } from '../debug.js';
+import { ErrorReconstituter } from '../../client/error-reconstituter.js';
+import type { SerializableError } from '../../client/error-reconstituter.js';
+import { loadModule } from '../safe-load.js';
+import { sourceMapError } from '../dev-source-map.js';
 
 /**
- * Render an error page for unhandled throws or RenderError outside Suspense.
- *
- * Walks the segment chain from leaf to root looking for:
- *   1. Specific status file (e.g. 503.tsx) matching the error's status
- *   2. 5xx.tsx category catch-all
- *   3. error.tsx
- *
- * Renders the found component with { error, digest, reset } props
- * wrapped in layouts, with the correct HTTP status code.
+ * A manifest file reference with lazy import and path.
+ * Mirrors the shape from ManifestSegmentNode but kept local to avoid
+ * exporting internal types from route-matcher.
  */
-export async function renderErrorPage(
-  error: unknown,
-  status: number,
-  segments: ManifestSegmentNode[],
-  layoutComponents: LayoutEntry[],
-  req: Request,
-  match: RouteMatch,
-  responseHeaders: Headers,
-  clientBootstrap: ClientBootstrapConfig
-): Promise<Response> {
-  const h = createElement as (...args: unknown[]) => React.ReactElement;
+export interface GlobalErrorFile {
+  load: () => Promise<unknown>;
+  filePath: string;
+}
 
-  // Walk segments from leaf to root to find the error component
-  let errorComponent: ((...args: unknown[]) => unknown) | null = null;
-  let foundSegmentIndex = -1;
+/** MDX/markdown extensions — server components that need RSC rendering. */
+const MDX_EXTENSIONS = new Set(['.mdx', '.md']);
+
+/**
+ * Check if a file path ends with an MDX/markdown extension.
+ */
+function isMdxFile(filePath: string): boolean {
+  const dotIndex = filePath.lastIndexOf('.');
+  if (dotIndex === -1) return false;
+  return MDX_EXTENSIONS.has(filePath.slice(dotIndex));
+}
 
+/**
+ * Result of walking the segment chain for an error file.
+ */
+interface ErrorFileResolution {
+  /** The loaded component */
+  component: (...args: unknown[]) => unknown;
+  /** Index of the segment where the file was found */
+  segmentIndex: number;
+  /** Whether the file is MDX (server component) */
+  isMdx: boolean;
+}
+
+/**
+ * Walk segments from leaf to root to find the nearest error file.
+ *
+ * Fallback chain at each segment:
+ *   1. Specific status file (e.g., 503.tsx) — exact match
+ *   2. 5xx.tsx — category catch-all
+ *   3. error.tsx — catches all unmatched errors
+ */
+async function resolveErrorFile(
+  status: number,
+  segments: ManifestSegmentNode[]
+): Promise<ErrorFileResolution | null> {
   for (let i = segments.length - 1; i >= 0; i--) {
     const segment = segments[i];
 
-    // Check specific status file (e.g. 503.tsx)
     if (segment.statusFiles) {
+      // Check specific status file (e.g. 503.tsx)
       const statusKey = String(status);
       const specificFile = segment.statusFiles[statusKey];
       if (specificFile) {
-        const mod = (await specificFile.load()) as Record<string, unknown>;
-        if (mod.default) {
-          errorComponent = mod.default as (...args: unknown[]) => unknown;
-          foundSegmentIndex = i;
-          break;
+        // .catch: if the error page module itself fails to load (syntax error,
+        // missing file), fall through to next tier instead of recursive failure.
+        // See TIM-584, design/spike-TIM-551-dynamic-import-audit.md §H1.
+        const mod = await loadModule(specificFile).catch(() => null);
+        if (mod?.default) {
+          return {
+            component: mod.default as (...args: unknown[]) => unknown,
+            segmentIndex: i,
+            isMdx: isMdxFile(specificFile.filePath),
+          };
         }
       }
 
       // Check 5xx.tsx category catch-all
       const categoryFile = segment.statusFiles['5xx'];
       if (categoryFile && status >= 500 && status <= 599) {
-        const mod = (await categoryFile.load()) as Record<string, unknown>;
-        if (mod.default) {
-          errorComponent = mod.default as (...args: unknown[]) => unknown;
-          foundSegmentIndex = i;
-          break;
+        const mod = await loadModule(categoryFile).catch(() => null);
+        if (mod?.default) {
+          return {
+            component: mod.default as (...args: unknown[]) => unknown,
+            segmentIndex: i,
+            isMdx: isMdxFile(categoryFile.filePath),
+          };
         }
       }
     }
 
     // Check error.tsx
     if (segment.error) {
-      const mod = (await segment.error.load()) as Record<string, unknown>;
-      if (mod.default) {
-        errorComponent = mod.default as (...args: unknown[]) => unknown;
-        foundSegmentIndex = i;
-        break;
+      const mod = await loadModule(segment.error).catch(() => null);
+      if (mod?.default) {
+        return {
+          component: mod.default as (...args: unknown[]) => unknown,
+          segmentIndex: i,
+          isMdx: isMdxFile(segment.error.filePath),
+        };
       }
     }
   }
 
-  // No error component found — fall back to bare response
-  if (!errorComponent) {
+  return null;
+}
+
+/**
+ * Build the layouts-to-wrap list for an error file at a given segment index.
+ */
+function getLayoutsForErrorFile(
+  segments: ManifestSegmentNode[],
+  layoutComponents: LayoutEntry[],
+  foundSegmentIndex: number
+): LayoutEntry[] {
+  const resolvedSegments = new Set(segments.slice(0, foundSegmentIndex + 1));
+  return layoutComponents.filter((lc) => resolvedSegments.has(lc.segment));
+}
+
+/**
+ * Convert an error to a SerializableError for RSC Flight serialization.
+ * Stack traces are stripped in production (gated by isDevMode).
+ *
+ * See design/13-security.md §"Debug Flag Security Boundary" — uses isDevMode(),
+ * not isDebug(), because this data crosses the RSC → client boundary.
+ */
+function toSerializableError(error: unknown): SerializableError {
+  const err = error instanceof Error ? error : new Error(String(error));
+  const devMode = isDevMode();
+  return {
+    message: devMode ? err.message : 'An unexpected error occurred.',
+    name: devMode ? err.name : 'Error',
+    ...(devMode && err.stack ? { stack: err.stack } : {}),
+  };
+}
+
+/**
+ * Render an error page for unhandled throws or RenderError outside Suspense.
+ *
+ * All error pages (TSX and MDX) go through RSC → SSR:
+ * - TSX: ErrorReconstituter wrapper converts SerializableError → real Error
+ * - MDX: Plain props ({ status }), no wrapper needed
+ */
+export async function renderErrorPage(
+  error: unknown,
+  status: number,
+  segments: ManifestSegmentNode[],
+  layoutComponents: LayoutEntry[],
+  req: Request,
+  match: RouteMatch,
+  responseHeaders: Headers,
+  clientBootstrap: ClientBootstrapConfig,
+  globalError?: GlobalErrorFile
+): Promise<Response> {
+  // Source-map the error's stack trace in dev mode so the error page
+  // shows original source positions instead of transpiled/bundled ones.
+  // See TIM-811.
+  sourceMapError(error);
+  // Walk segments from leaf to root to find the error component
+  const resolution = await resolveErrorFile(status, segments);
+
+  // Tier 2: No segment-level error file — try global-error.tsx
+  if (!resolution && globalError) {
+    return renderGlobalErrorPage(
+      error,
+      status,
+      globalError,
+      req,
+      match,
+      responseHeaders,
+      clientBootstrap
+    );
+  }
+
+  // Tier 3: No error component found at any level — bare response
+  if (!resolution) {
     return new Response(null, { status, headers: responseHeaders });
   }
 
-  // Build digest prop for RenderError, null for unhandled errors
-  const digest =
-    error instanceof RenderError ? { code: error.code, data: error.digest.data } : null;
+  const { component: errorComponent, segmentIndex, isMdx } = resolution;
+  const layoutsToWrap = getLayoutsForErrorFile(segments, layoutComponents, segmentIndex);
 
-  // Error pages receive { error, digest, reset } per design/10-error-handling.md
-  let element = h(errorComponent, {
-    error: error instanceof Error ? error : new Error(String(error)),
-    digest,
-    reset: undefined, // reset is only meaningful on the client
-  });
+  return renderErrorPageViaRsc(
+    error,
+    errorComponent,
+    isMdx,
+    status,
+    layoutsToWrap,
+    req,
+    match,
+    responseHeaders,
+    clientBootstrap
+  );
+}
 
-  // Wrap in layouts from root up to the segment where the error file was found
-  const resolvedSegments = new Set(segments.slice(0, foundSegmentIndex + 1));
-  const layoutsToWrap = layoutComponents.filter((lc) => resolvedSegments.has(lc.segment));
+/**
+ * Render an error page through the RSC → SSR pipeline.
+ *
+ * Handles both TSX and MDX error pages:
+ * - TSX: Wrapped with ErrorReconstituter to reconstitute Error on client
+ * - MDX: Receives plain props ({ status }), rendered as server component
+ */
+async function renderErrorPageViaRsc(
+  error: unknown,
+  errorComponent: (...args: unknown[]) => unknown,
+  isMdx: boolean,
+  status: number,
+  layoutsToWrap: LayoutEntry[],
+  req: Request,
+  match: RouteMatch,
+  responseHeaders: Headers,
+  clientBootstrap: ClientBootstrapConfig
+): Promise<Response> {
+  const h = createElement as (...args: unknown[]) => React.ReactElement;
+  const url = new URL(req.url);
+
+  let element: React.ReactElement;
+
+  if (isMdx) {
+    // MDX error pages receive plain props — no Error serialization issue
+    element = h(errorComponent, { status });
+  } else {
+    // TSX error pages: wrap with ErrorReconstituter for Error reconstitution.
+    // The ErrorReconstituter is a 'use client' component that receives
+    // SerializableError (plain object) and reconstitutes a real Error
+    // before passing to the user's error component.
+    const serializedError = toSerializableError(error);
+    const digest =
+      error instanceof RenderError ? { code: error.code, data: error.digest.data } : null;
+
+    element = h(ErrorReconstituter, {
+      error: serializedError,
+      digest,
+      reset: undefined,
+      component: errorComponent,
+    });
+  }
+
+  // Wrap in layouts
   for (let i = layoutsToWrap.length - 1; i >= 0; i--) {
     const { component } = layoutsToWrap[i];
     element = h(component, null, element);
   }
 
-  // Render to fresh RSC Flight stream
-  const rscStream = renderToReadableStream(element, {
-    onError(err: unknown) {
-      logRenderError({ method: req.method, path: new URL(req.url).pathname, error: err });
-    },
-    debugChannel: createDebugChannelSink(),
-  });
-
-  const [ssrStream, inlineStream] = rscStream.tee();
-
-  const navContext: NavContext = {
-    pathname: new URL(req.url).pathname,
-    params: match.params,
-    searchParams: Object.fromEntries(new URL(req.url).searchParams),
-    statusCode: status,
-    responseHeaders,
-    headHtml: '',
-    bootstrapScriptContent: clientBootstrap.bootstrapScriptContent,
-    rscStream: inlineStream,
-    cookies: parseCookiesFromHeader(req.headers.get('cookie') ?? ''),
-  };
+  // Render through RSC → SSR (same path as deny pages)
+  try {
+    const rscStream = renderToReadableStream(element, {
+      signal: req.signal,
+      onError(err: unknown) {
+        logRenderError({ method: req.method, path: url.pathname, error: err });
+      },
+      debugChannel: createDebugChannelSink(),
+    });
 
-  return callSsr(ssrStream, navContext);
+    const [ssrStream, inlineStream] = teeWithErrorPropagation(rscStream);
+
+    // Build params bootstrap script so useSegmentParams() works on hydration.
+    // Without this, error pages on dynamic routes hydrate with empty params.
+    const paramsScript =
+      Object.keys(match.segmentParams).length === 0
+        ? ''
+        : `<script>self.__timber_params=${htmlEscapeJsonString(JSON.stringify(match.segmentParams))}</script>`;
+
+    const navContext: NavContext = {
+      pathname: url.pathname,
+      segmentParams: match.segmentParams,
+      searchParams: Object.fromEntries(url.searchParams),
+      statusCode: status,
+      responseHeaders,
+      headHtml: paramsScript + flightInitScript(),
+      bootstrapScriptContent: clientBootstrap.bootstrapScriptContent,
+      rscStream: inlineStream,
+      signal: req.signal,
+      cookies: getCookiesForSsr(),
+    };
+
+    return callSsr(ssrStream, navContext);
+  } catch (renderError) {
+    // Error page itself failed to render — fall through to bare response.
+    // This guards against recursive errors in user error page code.
+    logRenderError({ method: req.method, path: url.pathname, error: renderError });
+    return new Response(null, { status, headers: responseHeaders });
+  }
+}
+
+/**
+ * Tier 2 — Render global-error.tsx as a standalone full-page replacement.
+ *
+ * No layout wrapping. The component must provide its own <html> and <body>.
+ * All formats (TSX and MDX) go through RSC → SSR.
+ *
+ * See design/10-error-handling.md §"Tier 2 — Global Error Page"
+ */
+async function renderGlobalErrorPage(
+  error: unknown,
+  status: number,
+  globalError: GlobalErrorFile,
+  req: Request,
+  match: RouteMatch,
+  responseHeaders: Headers,
+  clientBootstrap: ClientBootstrapConfig
+): Promise<Response> {
+  // .catch: if global-error.tsx fails to load, fall through to bare response.
+  // This is the last tier — no further recovery. See TIM-584.
+  const mod = await loadModule(globalError).catch(() => null);
+  if (!mod?.default) {
+    return new Response(null, { status, headers: responseHeaders });
+  }
+
+  const component = mod.default as (...args: unknown[]) => unknown;
+  const isMdx = isMdxFile(globalError.filePath);
+
+  // Reuse the unified RSC path with no layouts
+  return renderErrorPageViaRsc(
+    error,
+    component,
+    isMdx,
+    status,
+    [], // No layouts — global-error is standalone
+    req,
+    match,
+    responseHeaders,
+    clientBootstrap
+  );
 }
 
 /**
@@ -151,7 +368,7 @@ export async function renderNoMatchPage(
   // Load root layout if present
   const layoutComponents: LayoutEntry[] = [];
   if (rootSegment.layout) {
-    const mod = (await rootSegment.layout.load()) as Record<string, unknown>;
+    const mod = await loadModule(rootSegment.layout);
     if (mod.default) {
       layoutComponents.push({
         component: mod.default as (...args: unknown[]) => unknown,
@@ -161,7 +378,17 @@ export async function renderNoMatchPage(
   }
 
   const deny = new DenySignal(404);
-  const match: RouteMatch = { segments: segments as never, params: {} };
+  const match: RouteMatch = { segments, segmentParams: {}, middlewareChain: [] };
+
+  if (isRscPayloadRequest(req)) {
+    return renderDenyPageAsRsc(
+      deny,
+      segments,
+      layoutComponents,
+      responseHeaders,
+      createDebugChannelSink
+    );
+  }
 
   return renderDenyPage(
     deny,