@timber-js/app 0.2.0-alpha.83 → 0.2.0-alpha.85

package/src/plugins/dev-error-page.ts

@@ -0,0 +1,536 @@
+/**
+ * Dev error page — self-contained HTML error page for dev server 500s.
+ *
+ * Generates a styled, self-contained HTML page when the RSC pipeline fails
+ * and the Vite error overlay can't fire (e.g., first page load before HMR
+ * WebSocket connects, RSC entry module crash, early pipeline errors).
+ *
+ * This is NOT a replacement for Vite's error overlay — it's the fallback
+ * for when the overlay's transport (WebSocket) isn't available yet.
+ *
+ * Dev-only: this module is only imported by dev-server.ts (apply: 'serve').
+ * It is never included in production builds.
+ *
+ * Design doc: 21-dev-server.md §"Error Overlay"
+ */
+
+import {
+  classifyFrame,
+  extractComponentStack,
+  parseFirstAppFrame,
+  type ErrorPhase,
+  type FrameType,
+} from './dev-error-overlay.js';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+interface ClassifiedFrame {
+  raw: string;
+  type: FrameType;
+}
+
+// ─── Phase Labels ───────────────────────────────────────────────────────────
+
+const PHASE_LABELS: Record<ErrorPhase, string> = {
+  'module-transform': 'Module Transform',
+  'proxy': 'Proxy',
+  'middleware': 'Middleware',
+  'access': 'Access Check',
+  'render': 'RSC Render',
+  'handler': 'Route Handler',
+};
+
+const PHASE_HINTS: Record<ErrorPhase, string> = {
+  'module-transform':
+    'This error occurred while Vite was transforming a module. Check for syntax errors or missing imports.',
+  'proxy': 'This error occurred in proxy.ts. Check your proxy configuration.',
+  'middleware':
+    'This error occurred in a middleware.ts file. Check the middleware function for unhandled exceptions.',
+  'access': 'This error occurred in an access.ts file. Check your access control logic.',
+  'render':
+    'This error occurred while rendering a server component. Check the component for runtime errors.',
+  'handler': 'This error occurred in a route handler (route.ts). Check the handler function.',
+};
+
+// ─── Stack Trace Processing ─────────────────────────────────────────────────
+
+function classifyStack(stack: string, projectRoot: string): ClassifiedFrame[] {
+  return stack
+    .split('\n')
+    .slice(1) // skip first line (error message)
+    .filter((line) => line.trim().startsWith('at '))
+    .map((line) => ({
+      raw: line,
+      type: classifyFrame(line, projectRoot),
+    }));
+}
+
+// ─── Source Context ─────────────────────────────────────────────────────────
+
+/**
+ * Try to read a few lines of source code around the error location.
+ * Returns null if the file can't be read (e.g., virtual modules).
+ */
+function readSourceContext(
+  filePath: string,
+  line: number,
+  contextLines = 3
+): { lines: Array<{ num: number; text: string; highlight: boolean }>; startLine: number } | null {
+  try {
+    const { readFileSync } = require('node:fs');
+    const content = readFileSync(filePath, 'utf-8');
+    const allLines = content.split('\n');
+
+    const start = Math.max(0, line - 1 - contextLines);
+    const end = Math.min(allLines.length, line + contextLines);
+
+    return {
+      startLine: start + 1,
+      lines: allLines.slice(start, end).map((text: string, i: number) => ({
+        num: start + 1 + i,
+        text,
+        highlight: start + 1 + i === line,
+      })),
+    };
+  } catch {
+    return null;
+  }
+}
+
+// ─── HTML Escaping ──────────────────────────────────────────────────────────
+
+function esc(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/**
+ * Escape a JSON string for safe embedding in an HTML `<script>` block.
+ *
+ * `JSON.stringify` does not escape `</script>`, so error text containing
+ * that sequence breaks out of the script block — an XSS vector.
+ * We replace all `<` with `\u003c` which is valid in JSON strings and
+ * prevents the HTML parser from seeing a closing `</script>` tag.
+ *
+ * Security: TIM-788
+ */
+function escJsonForScript(json: string): string {
+  return json.replace(/</g, '\\u003c');
+}
+
+// ─── HMR Options ────────────────────────────────────────────────────────────
+
+/**
+ * HMR connection options for the dev error page auto-reload WebSocket.
+ * Derived from Vite's resolved server config so the error page can
+ * connect to the correct HMR endpoint (TIM-789).
+ */
+export interface DevErrorHmrOptions {
+  protocol?: string;
+  host?: string;
+  port?: number;
+  path?: string;
+  token?: string;
+}
+
+/**
+ * Build a WebSocket URL from Vite HMR options.
+ * Mirrors the logic in Vite's client.mjs for constructing the WS connection URL.
+ */
+function buildWsUrl(opts: DevErrorHmrOptions): string {
+  const protocol = opts.protocol ?? 'ws';
+  const host = opts.host ?? 'localhost';
+  const port = opts.port ? `:${opts.port}` : '';
+  const path = opts.path ?? '';
+  const token = opts.token ? `?token=${opts.token}` : '';
+  return `${protocol}://${host}${port}${path}${token}`;
+}
+
+/**
+ * Extract HMR connection options from a Vite resolved config.
+ * Used by the dev server to pass HMR config to the error page generator
+ * so the auto-reload WebSocket connects to the correct endpoint.
+ */
+export function extractHmrOptions(config: {
+  server?: { hmr?: { protocol?: string; host?: string; port?: number; path?: string } | boolean };
+  webSocketToken?: string;
+}): DevErrorHmrOptions | undefined {
+  const hmr = config.server?.hmr;
+  if (hmr === false) return undefined;
+  const hmrOpts = typeof hmr === 'object' ? hmr : {};
+  const opts: DevErrorHmrOptions = {
+    protocol: hmrOpts.protocol,
+    host: hmrOpts.host,
+    port: hmrOpts.port,
+    path: hmrOpts.path,
+    token: config.webSocketToken,
+  };
+  // If no HMR fields were explicitly configured, return undefined so the
+  // error page falls back to `'ws://' + location.host` which correctly
+  // includes the browser's current port (TIM-805).
+  if (!opts.protocol && !opts.host && !opts.port && !opts.path && !opts.token) {
+    return undefined;
+  }
+  return opts;
+}
+
+// ─── HTML Generation ────────────────────────────────────────────────────────
+
+/**
+ * Generate a self-contained HTML error page for dev server 500 responses.
+ *
+ * The page includes:
+ * - Error message and phase label
+ * - Source code context around the first app frame (if readable)
+ * - Component stack (for React render errors)
+ * - Classified stack trace (app frames highlighted, internals collapsed)
+ * - Copy button for the full error
+ * - Dark/light mode via prefers-color-scheme
+ * - Auto-reconnect script that watches for Vite HMR and reloads
+ */
+export function generateDevErrorPage(
+  error: Error,
+  phase: ErrorPhase,
+  projectRoot: string,
+  hmrOptions?: DevErrorHmrOptions
+): string {
+  const message = error.message || 'Unknown error';
+  const phaseLabel = PHASE_LABELS[phase];
+  const phaseHint = PHASE_HINTS[phase];
+  const componentStack = extractComponentStack(error);
+  const loc = parseFirstAppFrame(error.stack ?? '', projectRoot);
+  const frames = error.stack ? classifyStack(error.stack, projectRoot) : [];
+  const appFrames = frames.filter((f) => f.type === 'app');
+  const internalFrameCount = frames.filter((f) => f.type !== 'app').length;
+
+  // Try to read source code context
+  let sourceContext: ReturnType<typeof readSourceContext> = null;
+  if (loc) {
+    sourceContext = readSourceContext(loc.file, loc.line);
+  }
+
+  // Relative path for display
+  const relPath = loc?.file.startsWith(projectRoot)
+    ? loc.file.slice(projectRoot.length + 1)
+    : loc?.file;
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Error — ${esc(phaseLabel)} | timber.js</title>
+  <style>${CSS}</style>
+</head>
+<body>
+  <div class="container">
+    <header class="header">
+      <div class="badge">${esc(phaseLabel)} Error</div>
+      <h1 class="message">${esc(message)}</h1>
+      ${phaseHint ? `<p class="hint">${esc(phaseHint)}</p>` : ''}
+    </header>
+
+    ${relPath ? `<div class="location">${esc(relPath)}${loc ? `:${loc.line}:${loc.column}` : ''}</div>` : ''}
+
+    ${
+      sourceContext
+        ? `<div class="source-context">
+        <div class="source-header">Source</div>
+        <pre class="source-code"><code>${sourceContext.lines
+          .map(
+            (l) =>
+              `<span class="source-line${l.highlight ? ' source-line-highlight' : ''}"` +
+              `><span class="line-num">${l.num}</span>${esc(l.text)}</span>`
+          )
+          .join('\n')}</code></pre>
+      </div>`
+        : ''
+    }
+
+    ${
+      componentStack
+        ? `<div class="section">
+        <div class="section-header">Component Stack</div>
+        <pre class="component-stack">${esc(componentStack.trim())}</pre>
+      </div>`
+        : ''
+    }
+
+    ${
+      appFrames.length > 0
+        ? `<div class="section">
+        <div class="section-header">Application Frames</div>
+        <pre class="stack">${appFrames.map((f) => esc(f.raw)).join('\n')}</pre>
+      </div>`
+        : ''
+    }
+
+    ${
+      internalFrameCount > 0
+        ? `<details class="section internal-frames">
+        <summary class="section-header clickable">${internalFrameCount} internal frame${internalFrameCount !== 1 ? 's' : ''}</summary>
+        <pre class="stack dimmed">${frames
+          .filter((f) => f.type !== 'app')
+          .map((f) => esc(f.raw))
+          .join('\n')}</pre>
+      </details>`
+        : ''
+    }
+
+    <div class="actions">
+      <button class="btn" onclick="copyError()">Copy Error</button>
+    </div>
+
+    <footer class="footer">
+      <span class="timber-logo">🪵 timber.js</span>
+      <span class="footer-hint">Fix the error and save — the page will reload automatically via HMR.</span>
+    </footer>
+  </div>
+
+  <script>
+    function copyError() {
+      var text = ${escJsonForScript(
+        JSON.stringify(
+          `${phaseLabel} Error: ${message}\n\n` +
+            (relPath ? `File: ${relPath}${loc ? `:${loc.line}:${loc.column}` : ''}\n\n` : '') +
+            (componentStack ? `Component Stack:\n${componentStack.trim()}\n\n` : '') +
+            `Stack Trace:\n${error.stack ?? ''}`
+        )
+      )};
+      navigator.clipboard.writeText(text).then(function() {
+        var btn = document.querySelector('.btn');
+        if (btn) { btn.textContent = 'Copied!'; setTimeout(function() { btn.textContent = 'Copy Error'; }, 1500); }
+      });
+    }
+
+    // Auto-reload when Vite HMR reconnects.
+    // When the developer fixes the error and saves, Vite's module graph
+    // invalidates. We can't rely on the normal HMR update flow (the page
+    // is a static error page, not a Vite-managed module), so we connect
+    // to Vite's WebSocket and reload on any update event.
+    (function() {
+      try {
+        var wsUrl = ${hmrOptions ? escJsonForScript(JSON.stringify(buildWsUrl(hmrOptions))) : "'ws://' + location.host"};
+        var ws = new WebSocket(wsUrl, 'vite-hmr');
+        ws.addEventListener('message', function(e) {
+          try {
+            var data = JSON.parse(e.data);
+            if (data.type === 'full-reload' || data.type === 'update' || data.type === 'connected') {
+              if (data.type !== 'connected') location.reload();
+            }
+          } catch(ex) {}
+        });
+      } catch(ex) {}
+    })();
+  </script>
+</body>
+</html>`;
+}
+
+// ─── CSS ────────────────────────────────────────────────────────────────────
+
+const CSS = `
+  :root {
+    --bg: #fff;
+    --fg: #1a1a1a;
+    --fg-dim: #6b7280;
+    --border: #e5e7eb;
+    --badge-bg: #fef2f2;
+    --badge-fg: #991b1b;
+    --badge-border: #fecaca;
+    --source-bg: #fafafa;
+    --highlight-bg: #fef2f2;
+    --highlight-border: #ef4444;
+    --line-num: #9ca3af;
+    --btn-bg: #f3f4f6;
+    --btn-fg: #374151;
+    --btn-border: #d1d5db;
+    --link: #2563eb;
+    --code-font: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #0a0a0a;
+      --fg: #f5f5f5;
+      --fg-dim: #9ca3af;
+      --border: #27272a;
+      --badge-bg: #450a0a;
+      --badge-fg: #fca5a5;
+      --badge-border: #7f1d1d;
+      --source-bg: #18181b;
+      --highlight-bg: #450a0a;
+      --highlight-border: #dc2626;
+      --line-num: #6b7280;
+      --btn-bg: #27272a;
+      --btn-fg: #e5e7eb;
+      --btn-border: #3f3f46;
+      --link: #60a5fa;
+    }
+  }
+
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+    background: var(--bg);
+    color: var(--fg);
+    line-height: 1.6;
+    padding: 2rem;
+  }
+
+  .container {
+    max-width: 56rem;
+    margin: 0 auto;
+  }
+
+  .header { margin-bottom: 1.5rem; }
+
+  .badge {
+    display: inline-block;
+    font-size: 0.75rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    padding: 0.25rem 0.625rem;
+    border-radius: 0.375rem;
+    background: var(--badge-bg);
+    color: var(--badge-fg);
+    border: 1px solid var(--badge-border);
+    margin-bottom: 0.75rem;
+  }
+
+  .message {
+    font-size: 1.375rem;
+    font-weight: 600;
+    line-height: 1.3;
+    word-break: break-word;
+  }
+
+  .hint {
+    margin-top: 0.5rem;
+    color: var(--fg-dim);
+    font-size: 0.875rem;
+  }
+
+  .location {
+    font-family: var(--code-font);
+    font-size: 0.8125rem;
+    color: var(--link);
+    margin-bottom: 1rem;
+    padding: 0.5rem 0.75rem;
+    background: var(--source-bg);
+    border-radius: 0.375rem;
+    border: 1px solid var(--border);
+  }
+
+  .source-context {
+    margin-bottom: 1rem;
+    border: 1px solid var(--border);
+    border-radius: 0.5rem;
+    overflow: hidden;
+  }
+
+  .source-header, .section-header {
+    font-size: 0.75rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    padding: 0.5rem 0.75rem;
+    background: var(--source-bg);
+    border-bottom: 1px solid var(--border);
+    color: var(--fg-dim);
+  }
+
+  .source-code {
+    overflow-x: auto;
+    font-family: var(--code-font);
+    font-size: 0.8125rem;
+    line-height: 1.7;
+    padding: 0;
+    margin: 0;
+  }
+
+  .source-code code {
+    display: block;
+  }
+
+  .source-line {
+    display: block;
+    padding: 0 0.75rem;
+    border-left: 3px solid transparent;
+  }
+
+  .source-line-highlight {
+    background: var(--highlight-bg);
+    border-left-color: var(--highlight-border);
+  }
+
+  .line-num {
+    display: inline-block;
+    width: 3rem;
+    text-align: right;
+    margin-right: 1rem;
+    color: var(--line-num);
+    user-select: none;
+  }
+
+  .section {
+    margin-bottom: 1rem;
+    border: 1px solid var(--border);
+    border-radius: 0.5rem;
+    overflow: hidden;
+  }
+
+  .clickable { cursor: pointer; }
+  .clickable:hover { background: var(--btn-bg); }
+
+  .component-stack, .stack {
+    font-family: var(--code-font);
+    font-size: 0.8125rem;
+    line-height: 1.7;
+    padding: 0.75rem;
+    overflow-x: auto;
+    white-space: pre;
+    margin: 0;
+  }
+
+  .dimmed { color: var(--fg-dim); }
+
+  .actions {
+    margin: 1.5rem 0;
+  }
+
+  .btn {
+    font-family: inherit;
+    font-size: 0.8125rem;
+    font-weight: 500;
+    padding: 0.5rem 1rem;
+    border-radius: 0.375rem;
+    border: 1px solid var(--btn-border);
+    background: var(--btn-bg);
+    color: var(--btn-fg);
+    cursor: pointer;
+    transition: background 0.15s;
+  }
+
+  .btn:hover { opacity: 0.85; }
+
+  .footer {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    padding-top: 1rem;
+    border-top: 1px solid var(--border);
+    font-size: 0.75rem;
+    color: var(--fg-dim);
+  }
+
+  .timber-logo {
+    font-weight: 600;
+    white-space: nowrap;
+  }
+`;

package/src/plugins/dev-server.ts

@@ -17,7 +17,18 @@ import type { IncomingMessage, ServerResponse } from 'node:http';
 import { join } from 'node:path';
 import type { PluginContext } from '../plugin-context.js';
 import { setViteServer } from '../server/dev-warnings.js';
-import { sendErrorToOverlay, classifyErrorPhase, parseFirstAppFrame } from './dev-error-overlay.js';
+import {
+  sendErrorToOverlay,
+  classifyErrorPhase,
+  parseFirstAppFrame,
+  type ErrorPhase,
+} from './dev-error-overlay.js';
+import {
+  generateDevErrorPage,
+  extractHmrOptions,
+  type DevErrorHmrOptions,
+} from './dev-error-page.js';
+import { addVirtualModuleContext } from '../config-validation.js';
 import { compressResponse } from '../server/compress.js';
 
 // ─── Constants ────────────────────────────────────────────────────────────
@@ -137,6 +148,10 @@ export function timberDevServer(ctx: PluginContext): Plugin {
  * calls next() to let Vite handle them.
  */
 function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
+  // Extract HMR connection options once so the error page can construct
+  // a correct WebSocket URL (TIM-789).
+  const hmrOptions = extractHmrOptions(server.config);
+
   return async (req: IncomingMessage, res: ServerResponse, next: () => void): Promise<void> => {
     const url = req.url;
     if (!url) {
@@ -203,9 +218,11 @@ function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
       // Vite may already show its own overlay for these, but we still
       // log to stderr with frame dimming for the terminal.
       if (error instanceof Error) {
+        // Add context for virtual:timber-* module errors
+        addTimberContext(error);
         sendErrorToOverlay(server, error, 'module-transform', projectRoot);
       }
-      respond500(res, error);
+      respond500(res, error, 'module-transform', projectRoot, hmrOptions);
       return;
     }
 
@@ -248,24 +265,60 @@ function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
       if (error instanceof Error) {
         const phase = classifyErrorPhase(error, projectRoot);
         sendErrorToOverlay(server, error, phase, projectRoot);
+        respond500(res, error, phase, projectRoot, hmrOptions);
       } else {
         process.stderr.write(`\x1b[31m[timber] Dev server error:\x1b[0m ${String(error)}\n`);
+        respond500(res, error, 'render', projectRoot, hmrOptions);
       }
-      respond500(res, error);
     }
   };
 }
 
 /**
  * Send a 500 response without crashing the dev server.
+ *
+ * In dev mode, renders a styled HTML error page with source context,
+ * classified stack trace, and auto-reload on HMR. Falls back to
+ * text/plain if the HTML generator fails (must never crash).
  */
-function respond500(res: ServerResponse, error: unknown): void {
-  if (!res.headersSent) {
-    res.statusCode = 500;
-    res.setHeader('content-type', 'text/plain');
-    res.end(
-      `[timber] Internal server error\n\n${error instanceof Error ? (error.stack ?? error.message) : String(error)}`
-    );
+function respond500(
+  res: ServerResponse,
+  error: unknown,
+  phase: ErrorPhase,
+  projectRoot: string,
+  hmrOptions?: DevErrorHmrOptions
+): void {
+  if (res.headersSent) return;
+
+  // Try to render the rich HTML error page
+  if (error instanceof Error) {
+    try {
+      const html = generateDevErrorPage(error, phase, projectRoot, hmrOptions);
+      res.statusCode = 500;
+      res.setHeader('content-type', 'text/html; charset=utf-8');
+      res.end(html);
+      return;
+    } catch {
+      // Fall through to text/plain if the HTML generator fails
+    }
+  }
+
+  // Fallback: plain text (same as before)
+  res.statusCode = 500;
+  res.setHeader('content-type', 'text/plain');
+  res.end(
+    `[timber] Internal server error\n\n${error instanceof Error ? (error.stack ?? error.message) : String(error)}`
+  );
+}
+
+/**
+ * Add timber-specific context to an error's message if it references
+ * internal virtual modules (virtual:timber-*). Mutates the error in place.
+ */
+function addTimberContext(error: Error): void {
+  const enriched = addVirtualModuleContext(error.message);
+  if (enriched !== error.message) {
+    error.message = enriched;
   }
 }