@timber-js/app 0.2.0-alpha.8 → 0.2.0-alpha.80

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 ──────────────────────────────────────────────────────────────
@@ -102,30 +109,27 @@ function matchPathname(root: ManifestSegmentNode, pathname: string): RouteMatch
   const matched = matchSegments(root, parts, 0, segments, params);
   if (!matched) return null;
 
-  // Convert ManifestSegmentNodes to the SegmentNode shape expected by RouteMatch.
-  // The pipeline and tree builder use SegmentNode which has RouteFile references,
-  // but we pass the manifest nodes directly — they're structurally compatible
-  // for the fields the pipeline cares about (segments array + params).
-  // Resolve the leaf segment's middleware.ts if present.
-  // Only the leaf route's middleware runs — no chain, no inheritance.
-  const leafSegment = segments[segments.length - 1];
-  let middleware: MiddlewareFn | undefined;
-  if (leafSegment?.middleware) {
-    const loader = leafSegment.middleware.load;
-    middleware = async (ctx) => {
-      const mod = (await loader()) as { default?: MiddlewareFn };
-      if (mod.default) {
-        return mod.default(ctx);
-      }
-    };
+  // Collect middleware from all segments in the chain, root to leaf.
+  // Each middleware is lazy-loaded via dynamic import on first invocation.
+  const middlewareChain: MiddlewareFn[] = [];
+  for (const segment of segments) {
+    if (segment.middleware) {
+      const loader = segment.middleware.load;
+      middlewareChain.push(async (ctx) => {
+        const mod = (await loader()) as { default?: MiddlewareFn };
+        if (mod.default) {
+          return mod.default(ctx);
+        }
+      });
+    }
   }
 
   return {
     // The pipeline uses segments as opaque objects passed to the renderer.
     // Cast is safe — the renderer receives what the manifest provides.
     segments: segments as unknown as RouteMatch['segments'],
-    params,
-    middleware,
+    segmentParams: params,
+    middlewareChain,
   };
 }
 

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

@@ -6,13 +6,14 @@
  * 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 { loadModule } from '../safe-load.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,
@@ -26,10 +27,8 @@ export async function handleApiRoute(
   // Each access.ts is independent — deny()/redirect() throws a signal.
   for (const segment of segments) {
     if (segment.access) {
-      const accessMod = (await segment.access.load()) as Record<string, unknown>;
-      const accessFn = accessMod.default as
-        | ((ctx: { params: Record<string, string | string[]>; searchParams: unknown }) => unknown)
-        | undefined;
+      const accessMod = await loadModule(segment.access);
+      const accessFn = accessMod.default as (() => unknown) | undefined;
       if (accessFn) {
         try {
           await withSpan(
@@ -37,7 +36,7 @@ export async function handleApiRoute(
             { 'timber.segment': segment.segmentName ?? 'unknown' },
             async () => {
               try {
-                await accessFn({ params: match.params, searchParams: {} });
+                await accessFn();
                 await setSpanAttribute('timber.result', 'pass');
               } catch (error) {
                 if (error instanceof DenySignal) {
@@ -68,10 +67,10 @@ export async function handleApiRoute(
   }
 
   // Load route.ts module and dispatch
-  const routeMod = (await leaf.route!.load()) as RouteModule;
+  const routeMod = await loadModule<RouteModule>(leaf.route!);
   const ctx: RouteContext = {
     req,
-    params: match.params,
+    params: match.segmentParams,
     searchParams: new URL(req.url).searchParams,
     headers: responseHeaders,
   };
@@ -90,11 +89,11 @@ 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) {
-    const mod = (await resolution.file.load()) as Record<string, unknown>;
+    const mod = await loadModule(resolution.file);
     const jsonContent = mod.default ?? mod;
     responseHeaders.set('content-type', 'application/json; charset=utf-8');
     return new Response(JSON.stringify(jsonContent), {

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

@@ -1,136 +1,347 @@
 /**
  * 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';
+import { loadModule } from '../safe-load.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));
+  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.segmentParams).length === 0
+        ? ''
+        : `<script>self.__timber_params=${JSON.stringify(match.segmentParams)}</script>`;
+
+    const navContext: NavContext = {
+      pathname: url.pathname,
+      params: 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 });
+  }
 
-  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
+  );
 }
 
 /**
@@ -151,7 +362,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 +372,7 @@ export async function renderNoMatchPage(
   }
 
   const deny = new DenySignal(404);
-  const match: RouteMatch = { segments: segments as never, params: {} };
+  const match: RouteMatch = { segments: segments as never, segmentParams: {}, middlewareChain: [] };
 
   return renderDenyPage(
     deny,