@timber-js/app 0.2.0-alpha.84 → 0.2.0-alpha.86

package/src/server/action-client.ts

@@ -140,13 +140,13 @@ export interface ActionBuilder<TCtx> {
   /** Define the action body without input validation. */
   action<TData>(
     fn: (ctx: ActionContext<TCtx, undefined>) => Promise<TData>
-  ): ActionFn<undefined, TData>;
+  ): ActionFn<TData, undefined>;
 }
 
 /** Builder after .schema() has been called. */
 export interface ActionBuilderWithSchema<TCtx, TInput> {
   /** Define the action body with validated input. */
-  action<TData>(fn: (ctx: ActionContext<TCtx, TInput>) => Promise<TData>): ActionFn<TInput, TData>;
+  action<TData>(fn: (ctx: ActionContext<TCtx, TInput>) => Promise<TData>): ActionFn<TData, TInput>;
 }
 
 /**
@@ -169,10 +169,18 @@ export interface ActionBuilderWithSchema<TCtx, TInput> {
 export type InputHint<T> =
   T extends Record<string, unknown> ? { [K in keyof T]: string | undefined } : T;
 
-export type ActionFn<TInput = unknown, TData = unknown> = {
+/**
+ * ActionFn — the callable returned by `createActionClient().action()`.
+ *
+ * Generic order: `<TData, TInput>` — TData first for backward compatibility.
+ * Previously ActionFn had a single `<TData>` generic, so existing code like
+ * `ActionFn<MyResult>` must still work with TData in the first position.
+ * See TIM-797.
+ */
+export type ActionFn<TData = unknown, TInput = unknown> = {
   /** <form action={fn}> compatibility — React discards the return value. */
   (formData: FormData): void;
-  /** Direct call: action(input) — optional when TInput is undefined (no-schema actions). */
+  /** Direct call: action(input) — optional when TInput is undefined/unknown (no-schema actions). */
   (
     ...args: undefined extends TInput ? [input?: TInput] : [input: TInput]
   ): Promise<ActionResult<TData>>;
@@ -310,7 +318,7 @@ export function createActionClient<TCtx = Record<string, never>>(
   function buildAction<TInput, TData>(
     schema: ActionSchema<TInput> | undefined,
     fn: (ctx: ActionContext<TCtx, TInput>) => Promise<TData>
-  ): ActionFn<TInput, TData> {
+  ): ActionFn<TData, TInput> {
     async function actionHandler(...args: unknown[]): Promise<ActionResult<TData>> {
       try {
         // Run middleware
@@ -401,7 +409,7 @@ export function createActionClient<TCtx = Record<string, never>>(
       }
     }
 
-    return actionHandler as ActionFn<TInput, TData>;
+    return actionHandler as ActionFn<TData, TInput>;
   }
 
   return {
@@ -409,14 +417,14 @@ export function createActionClient<TCtx = Record<string, never>>(
       return {
         action<TData>(
           fn: (ctx: ActionContext<TCtx, TInput>) => Promise<TData>
-        ): ActionFn<TInput, TData> {
+        ): ActionFn<TData, TInput> {
           return buildAction(schema, fn);
         },
       };
     },
     action<TData>(
       fn: (ctx: ActionContext<TCtx, undefined>) => Promise<TData>
-    ): ActionFn<undefined, TData> {
+    ): ActionFn<TData, undefined> {
       return buildAction(undefined, fn as (ctx: ActionContext<TCtx, unknown>) => Promise<TData>);
     },
   };
@@ -445,7 +453,7 @@ export function createActionClient<TCtx = Record<string, never>>(
 export function validated<TInput, TData>(
   schema: ActionSchema<TInput>,
   handler: (input: TInput) => Promise<TData>
-): ActionFn<TInput, TData> {
+): ActionFn<TData, TInput> {
   return createActionClient()
     .schema(schema)
     .action(async ({ input }) => handler(input));

package/src/server/dev-source-map.ts

@@ -0,0 +1,31 @@
+/**
+ * Dev-only error source-mapping bridge.
+ *
+ * Stores a callback that rewrites an error's stack trace using the Vite
+ * dev server's module graph. Set by the RSC entry on startup (via
+ * setDevSourceMapHandler), consumed by error renderers before generating
+ * error pages.
+ *
+ * In production, the callback is never set — all calls are no-ops.
+ *
+ * See TIM-811.
+ */
+
+let _sourceMapError: ((error: Error) => void) | undefined;
+
+/**
+ * Set the source-map callback. Called once during dev server initialization.
+ */
+export function setSourceMapCallback(fn: (error: Error) => void): void {
+  _sourceMapError = fn;
+}
+
+/**
+ * Source-map an error's stack trace in-place if the callback is available.
+ * No-op in production or before the dev server initializes.
+ */
+export function sourceMapError(error: unknown): void {
+  if (_sourceMapError && error instanceof Error) {
+    _sourceMapError(error);
+  }
+}

package/src/server/fallback-error.ts

@@ -17,6 +17,7 @@ import type { LayoutEntry } from './deny-renderer.js';
 import type { GlobalErrorFile } from './rsc-entry/error-renderer.js';
 import { logRenderError } from './logger.js';
 import { loadModule } from './safe-load.js';
+import { sourceMapError } from './dev-source-map.js';
 
 /**
  * Render a fallback error page when the render pipeline throws.
@@ -31,10 +32,15 @@ export async function renderFallbackError(
   isDev: boolean,
   rootSegment: ManifestSegmentNode,
   clientBootstrap: ClientBootstrapConfig,
-  globalError?: GlobalErrorFile
+  globalError?: GlobalErrorFile,
+  projectRoot?: string
 ): Promise<Response> {
+  // Source-map the error's stack trace in dev mode so the error page
+  // shows original source positions. See TIM-811.
+  sourceMapError(error);
+
   if (isDev) {
-    return renderDevErrorPage(error);
+    return renderDevErrorPage(error, projectRoot);
   }
   // Lazy import to avoid loading error-renderer in the pipeline module
   const { renderErrorPage } = await import('./rsc-entry/error-renderer.js');
@@ -75,89 +81,35 @@ export async function renderFallbackError(
 }
 
 /**
- * Render a dev-mode 500 error page with error message and stack trace.
+ * Render a dev-mode 500 error page with error details, source context,
+ * classified stack trace, and copy button.
+ *
+ * Dynamically imports the shared template from `plugins/dev-error-page.ts`
+ * so it is NOT pulled into production server bundles. The Vite client script
+ * is injected so the error overlay fires when the HMR WebSocket connects.
  *
- * Returns an HTML Response that displays the error in a styled page.
- * The Vite HMR client script is included so the error overlay still fires.
+ * Dev-only — the dynamic import has zero production cost.
  */
-export function renderDevErrorPage(error: unknown): Response {
+export async function renderDevErrorPage(error: unknown, projectRoot?: string): Promise<Response> {
   const err = error instanceof Error ? error : new Error(String(error));
-  const title = err.name || 'Error';
-  const message = escapeHtml(err.message);
-  const stack = err.stack ? escapeHtml(err.stack) : '';
+  const root = projectRoot ?? process.cwd();
 
-  const html = `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>500 — ${escapeHtml(title)}</title>
-  <script type="module" src="/@vite/client"></script>
-  <style>
-    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
-    body {
-      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
-      background: #1a1a2e;
-      color: #e0e0e0;
-      padding: 2rem;
-      line-height: 1.6;
-    }
-    .container { max-width: 800px; margin: 0 auto; }
-    .badge {
-      display: inline-block;
-      background: #e74c3c;
-      color: white;
-      font-size: 0.75rem;
-      font-weight: 700;
-      padding: 0.2rem 0.6rem;
-      border-radius: 4px;
-      text-transform: uppercase;
-      letter-spacing: 0.05em;
-      margin-bottom: 1rem;
-    }
-    h1 {
-      font-size: 1.5rem;
-      color: #ff6b6b;
-      margin-bottom: 0.5rem;
-      word-break: break-word;
-    }
-    .message {
-      font-size: 1.1rem;
-      color: #ccc;
-      margin-bottom: 1.5rem;
-      word-break: break-word;
-    }
-    .stack-container {
-      background: #16213e;
-      border: 1px solid #2a2a4a;
-      border-radius: 8px;
-      padding: 1rem;
-      overflow-x: auto;
-    }
-    .stack {
-      font-family: 'SF Mono', 'Fira Code', 'Fira Mono', Menlo, Consolas, monospace;
-      font-size: 0.8rem;
-      color: #a0a0c0;
-      white-space: pre-wrap;
-      word-break: break-all;
-    }
-    .hint {
-      margin-top: 1.5rem;
-      font-size: 0.85rem;
-      color: #666;
-    }
-  </style>
-</head>
-<body>
-  <div class="container">
-    <span class="badge">500 Internal Server Error</span>
-    <h1>${escapeHtml(title)}</h1>
-    <p class="message">${message}</p>
-    ${stack ? `<div class="stack-container"><pre class="stack">${stack}</pre></div>` : ''}
-    <p class="hint">This error page is only shown in development.</p>
-  </div>
-</body>
-</html>`;
+  let html: string;
+  try {
+    // Dynamic import — keeps dev-error-page.ts and its transitive deps
+    // (dev-error-overlay.ts, @jridgewell/trace-mapping) out of production bundles.
+    const { generateDevErrorPage } = await import('../plugins/dev-error-page.js');
+    html = generateDevErrorPage(err, 'render', root);
+    // Inject Vite client script so the error overlay fires when HMR connects.
+    html = html.replace(
+      '</head>',
+      '  <script type="module" src="/@vite/client"></script>\n</head>'
+    );
+  } catch {
+    // If the shared template fails (e.g., circular dep, missing module),
+    // fall back to a minimal error page.
+    html = minimalErrorPage(err);
+  }
 
   return new Response(html, {
     status: 500,
@@ -165,11 +117,15 @@ export function renderDevErrorPage(error: unknown): Response {
   });
 }
 
-function escapeHtml(str: string): string {
-  return str
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#x27;');
+/**
+ * Minimal fallback error page — used only if the shared template fails to load.
+ */
+function minimalErrorPage(err: Error): string {
+  const esc = (s: string) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+  return `<!DOCTYPE html><html><head><meta charset="utf-8"><title>500</title>
+<script type="module" src="/@vite/client"></script></head>
+<body style="font-family:system-ui;padding:2rem;background:#1a1a2e;color:#e0e0e0">
+<h1 style="color:#ff6b6b">500 Internal Server Error</h1>
+<pre style="color:#a0a0c0;white-space:pre-wrap">${esc(err.stack ?? err.message)}</pre>
+</body></html>`;
 }

package/src/server/pipeline.ts

@@ -168,6 +168,7 @@ export interface PipelineConfig {
    * Undefined in production — zero overhead.
    */
   onPipelineError?: (error: Error, phase: string) => void;
+
   /**
    * Fallback error renderer — called when a catastrophic error escapes the
    * render phase. Produces an HTML Response instead of a bare empty 500.
@@ -184,6 +185,19 @@ export interface PipelineConfig {
     req: Request,
     responseHeaders: Headers
   ) => Response | Promise<Response>;
+  /**
+   * Fallback deny page renderer — called when a DenySignal escapes from
+   * middleware or the render phase. Renders the appropriate status-code
+   * page (403.tsx, 404.tsx, etc.) instead of returning a bare empty response.
+   *
+   * If this function throws, the pipeline falls back to a bare
+   * `new Response(null, { status: denyStatus })`.
+   */
+  renderDenyFallback?: (
+    deny: DenySignal,
+    req: Request,
+    responseHeaders: Headers
+  ) => Response | Promise<Response>;
 }
 
 // ─── Param Coercion ────────────────────────────────────────────────────────
@@ -624,9 +638,18 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
           applyCookieJar(responseHeaders);
           return buildRedirectResponse(error, req, responseHeaders);
         }
-        // DenySignal from middleware → HTTP deny status
+        // DenySignal from middleware → render deny page with correct status code.
+        // Previously returned bare Response(null) — now renders 403.tsx etc.
         if (error instanceof DenySignal) {
-          return new Response(null, { status: error.status });
+          applyCookieJar(responseHeaders);
+          if (config.renderDenyFallback) {
+            try {
+              return await config.renderDenyFallback(error, req, responseHeaders);
+            } catch {
+              // Deny page rendering failed — fall through to bare response
+            }
+          }
+          return new Response(null, { status: error.status, headers: responseHeaders });
         }
         // Middleware throw → HTTP 500 (middleware runs before rendering,
         // no error boundary to catch it)
@@ -655,9 +678,16 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       return response;
     } catch (error) {
       // DenySignal leaked from render (e.g. notFound() in metadata()).
-      // Return the deny status code instead of 500.
+      // Render the deny page with the correct status code.
       if (error instanceof DenySignal) {
-        return new Response(null, { status: error.status });
+        if (config.renderDenyFallback) {
+          try {
+            return await config.renderDenyFallback(error, req, responseHeaders);
+          } catch {
+            // Deny page rendering failed — fall through to bare response
+          }
+        }
+        return new Response(null, { status: error.status, headers: responseHeaders });
       }
       // RedirectSignal leaked from render — honour the redirect
       if (error instanceof RedirectSignal) {

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

@@ -32,6 +32,7 @@ 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';
 
 /**
  * A manifest file reference with lazy import and path.
@@ -176,6 +177,10 @@ export async function renderErrorPage(
   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);
 

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

@@ -54,6 +54,8 @@ import { initDevTracing } from '../tracing.js';
 
 import { renderFallbackError as renderFallback } from '../fallback-error.js';
 import { loadInstrumentation } from '../instrumentation.js';
+import { loadModule } from '../safe-load.js';
+import { logRenderError } from '../logger.js';
 import { handleApiRoute } from './api-handler.js';
 import { renderErrorPage, renderNoMatchPage } from './error-renderer.js';
 import {
@@ -69,6 +71,7 @@ import { renderRscStream } from './rsc-stream.js';
 import { renderSsrResponse } from './ssr-renderer.js';
 import { callSsr } from './ssr-bridge.js';
 import { isDebug, isDevMode, setDebugFromConfig } from '../debug.js';
+import { setSourceMapCallback } from '../dev-source-map.js';
 import { recordTiming } from '../server-timing.js';
 import { requestContextAls } from '../als-registry.js';
 import { createAutoSitemapHandler } from '../sitemap-handler.js';
@@ -113,6 +116,20 @@ export function setDevPipelineErrorHandler(
   _devPipelineErrorHandler = handler;
 }
 
+/**
+ * Set the dev source-map handler.
+ *
+ * Called by the dev server after importing this module to wire Vite's
+ * module graph source-mapping into the error rendering pipeline. Errors
+ * rendered by renderErrorPage / renderFallbackError will have their
+ * stack traces rewritten to show original source positions.
+ *
+ * No-op in production.
+ */
+export function setDevSourceMapHandler(handler: (error: Error) => void): void {
+  setSourceMapCallback(handler);
+}
+
 // Dev-only: debug components getter is stored per-request in ALS
 // (RequestContextStore.debugComponentsGetter) to avoid cross-request
 // race conditions. See TIM-557.
@@ -247,7 +264,34 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
       );
     },
     renderNoMatch: async (req: Request, responseHeaders: Headers) => {
-      return renderNoMatchPage(req, manifest.root, responseHeaders, clientBootstrap);
+      const response = await renderNoMatchPage(
+        req,
+        manifest.root,
+        responseHeaders,
+        clientBootstrap
+      );
+
+      // In dev mode, if the pipeline returned a bare 404 (no body — meaning
+      // no user-defined 404.tsx was found), replace it with a helpful dev
+      // page that lists available routes and suggests similar paths.
+      // Only for GET requests that accept HTML — HEAD/API/RSC clients
+      // should receive the bare 404 without an HTML body (TIM-793).
+      const acceptsHtml = (req.headers.get('accept') ?? '').includes('text/html');
+      if (isDev && !response.body && req.method === 'GET' && acceptsHtml) {
+        const { generateDev404Page, collectRoutes } = await import('../../plugins/dev-404-page.js');
+        const routes = collectRoutes(manifest.root);
+        const pathname = new URL(req.url).pathname;
+        const html = generateDev404Page(pathname, routes);
+        return new Response(html, {
+          status: 404,
+          headers: {
+            ...Object.fromEntries(responseHeaders.entries()),
+            'content-type': 'text/html; charset=utf-8',
+          },
+        });
+      }
+
+      return response;
     },
     interceptionRewrites: manifest.interceptionRewrites,
     // Slow request threshold from timber.config.ts. Default 3000ms, 0 to disable.
@@ -268,6 +312,7 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
           }
         }
       : undefined,
+
     renderFallbackError: (error, req, responseHeaders) =>
       renderFallback(
         error,
@@ -276,8 +321,49 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
         isDev,
         manifest.root,
         clientBootstrap,
-        manifest.globalError
+        manifest.globalError,
+        // Project root for dev error page frame classification.
+        // Not in runtimeConfig (TIM-787: leaked to client bundles).
+        // manifest.root is the resolved Vite root — correct even when
+        // CWD differs from project root (e.g., monorepo custom root) (TIM-807).
+        isDev ? manifest.root : undefined
       ),
+    renderDenyFallback: async (deny, req, responseHeaders) => {
+      // Render the deny page (403.tsx, 404.tsx, etc.) for DenySignals
+      // that escape from middleware or the render phase. Uses the root
+      // segment to resolve status-code files and layout wrapping.
+      const segments = [
+        manifest.root,
+      ] as unknown as import('../route-matcher.js').ManifestSegmentNode[];
+      const layoutComponents: LayoutEntry[] = [];
+      try {
+        if (manifest.root.layout) {
+          const mod = await loadModule(manifest.root.layout);
+          if (mod.default) {
+            layoutComponents.push({
+              component: mod.default as (...args: unknown[]) => unknown,
+              segment:
+                manifest.root as unknown as import('../route-matcher.js').ManifestSegmentNode,
+            });
+          }
+        }
+      } catch (layoutError) {
+        // Layout failed to load — proceed without it.
+        logRenderError({ method: req.method, path: new URL(req.url).pathname, error: layoutError });
+      }
+      const match = { segments: segments as never, segmentParams: {}, middlewareChain: [] };
+      return renderDenyPage(
+        deny,
+        segments,
+        layoutComponents,
+        req,
+        match,
+        responseHeaders,
+        clientBootstrap,
+        createDebugChannelSink,
+        callSsr
+      );
+    },
     // Auto-generated sitemap handler — enabled when sitemap.enabled is true
     // and no user-authored sitemap exists at the app root.
     // See design/16-metadata.md §"Auto-generated Sitemap"

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

@@ -41,6 +41,16 @@ 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;
 }
@@ -68,6 +78,7 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
     denySignal: null,
     redirectSignal: null,
     renderError: null,
+    lastUnhandledError: null,
   };
 
   let rscStream: ReadableStream<Uint8Array> | undefined;
@@ -150,6 +161,11 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
           // 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;
+
           // Return a digest so React emits a per-row error in the Flight
           // stream instead of leaving the lazy reference unresolved.
           //

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

@@ -337,10 +337,13 @@ export async function renderSsrResponse(opts: SsrRenderOptions): Promise<Respons
         );
       }
       // No captured signal — unhandled error in the RSC stream.
-      // Render the error page using the original error (cause).
-      const cause = (ssrError as { cause?: unknown }).cause ?? ssrError;
+      // Use the lastUnhandledError from RSC onError if available (more
+      // reliable than extracting SsrStreamError.cause). Falls back to
+      // cause extraction for backward compatibility.
+      const originalError =
+        signals.lastUnhandledError ?? (ssrError as { cause?: unknown }).cause ?? ssrError;
       return renderErrorPage(
-        cause,
+        originalError,
         500,
         segments,
         layoutComponents as LayoutEntry[],