@timber-js/app 0.2.0-alpha.6 → 0.2.0-alpha.61

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>;
 
@@ -69,6 +69,13 @@ export interface ManifestSegmentNode {
 export interface ManifestRoot {
   root: ManifestSegmentNode;
   proxy?: ManifestFile;
+  /**
+   * Global error page: app/global-error.{tsx,ts,jsx,js}
+   * Tier 2 — standalone full-page replacement (no layouts) when no
+   * segment-level error file is found. SSR-only render.
+   * See design/10-error-handling.md §"Tier 2"
+   */
+  globalError?: ManifestFile;
 }
 
 // ─── Matcher ──────────────────────────────────────────────────────────────

package/src/server/rsc-entry/api-handler.ts

@@ -6,13 +6,13 @@
  * See design/04-authorization.md §"Auth in API Routes".
  */
 
-import { withSpan, setSpanAttribute } from '#/server/tracing.js';
-import type { ManifestSegmentNode } from '#/server/route-matcher.js';
-import type { RouteMatch } from '#/server/pipeline.js';
-import { DenySignal, RedirectSignal } from '#/server/primitives.js';
-import { handleRouteRequest } from '#/server/route-handler.js';
-import type { RouteModule } from '#/server/route-handler.js';
-import type { RouteContext } from '#/server/types.js';
+import { withSpan, setSpanAttribute } from '../tracing.js';
+import type { ManifestSegmentNode } from '../route-matcher.js';
+import type { RouteMatch } from '../pipeline.js';
+import { DenySignal, RedirectSignal } from '../primitives.js';
+import { handleRouteRequest } from '../route-handler.js';
+import type { RouteModule } from '../route-handler.js';
+import type { RouteContext } from '../types.js';
 
 export async function handleApiRoute(
   req: Request,
@@ -90,7 +90,7 @@ async function renderApiDeny(
   segments: ManifestSegmentNode[],
   responseHeaders: Headers
 ): Promise<Response> {
-  const { resolveManifestStatusFile } = await import('#/server/manifest-status-resolver.js');
+  const { resolveManifestStatusFile } = await import('../manifest-status-resolver.js');
 
   const resolution = resolveManifestStatusFile(deny.status, segments, 'json');
   if (resolution) {

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

@@ -1,63 +1,98 @@
 /**
  * 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 } from '../flight-scripts.js';
+import { renderDenyPage } from '../deny-renderer.js';
+import type { LayoutEntry } from '../deny-renderer.js';
+import type { NavContext } from '../ssr-entry.js';
+import { createDebugChannelSink } from './helpers.js';
+import { getCookiesForSsr } from '../request-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';
 
 /**
- * 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;
+          return {
+            component: mod.default as (...args: unknown[]) => unknown,
+            segmentIndex: i,
+            isMdx: isMdxFile(specificFile.filePath),
+          };
         }
       }
 
@@ -66,9 +101,11 @@ export async function renderErrorPage(
       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;
+          return {
+            component: mod.default as (...args: unknown[]) => unknown,
+            segmentIndex: i,
+            isMdx: isMdxFile(categoryFile.filePath),
+          };
         }
       }
     }
@@ -77,60 +114,228 @@ export async function renderErrorPage(
     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;
+        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));
+  return {
+    message: err.message,
+    name: err.name,
+    ...(isDevMode() && 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> {
+  // 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(),
+    });
+
+    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.params).length === 0
+        ? ''
+        : `<script>self.__timber_params=${JSON.stringify(match.params)}</script>`;
+
+    const navContext: NavContext = {
+      pathname: url.pathname,
+      params: match.params,
+      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> {
+  const mod = (await globalError.load()) as Record<string, unknown>;
+  if (!mod.default) {
+    return new Response(null, { status, headers: responseHeaders });
+  }
 
-  return callSsr(ssrStream, navContext);
+  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
+  );
 }
 
 /**

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

@@ -4,8 +4,8 @@
  * Small, stateless functions used across the RSC entry modules.
  */
 
-import type { ManifestSegmentNode } from '#/server/route-matcher.js';
-import { RedirectSignal } from '#/server/primitives.js';
+import type { ManifestSegmentNode } from '../route-matcher.js';
+import { RedirectSignal } from '../primitives.js';
 
 /** RSC content type for client navigation payload requests. */
 export const RSC_CONTENT_TYPE = 'text/x-component';
@@ -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,138 @@ 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;
+
+    let payload = line.slice(colonIdx + 1);
+
+    // React Flight debug rows may have a type-tag prefix before the JSON
+    // object (e.g., "D{...}" for debug info rows). Strip the single-char
+    // tag so the JSON parser sees the object. Non-JSON payloads like
+    // D"$a" reference rows are caught by the JSON.parse try/catch below.
+    // See TIM-556.
+    if (payload.length > 0 && payload[0] !== '{' && payload[0] !== '[' && payload[0] !== '"') {
+      payload = payload.slice(1);
+    }
+
+    // Skip payloads that still aren't JSON objects after tag stripping
+    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