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

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

@@ -0,0 +1,418 @@
+/**
+ * Dev 404 page — self-contained HTML page for dev-mode route misses.
+ *
+ * When no route matches and the user has no 404.tsx, this page shows:
+ * - The requested path
+ * - All registered routes in the app
+ * - "Did you mean?" suggestions based on string similarity
+ * - Setup instructions for new projects with no routes
+ *
+ * Dev-only: this module is only imported in dev mode. It is never
+ * included in production builds.
+ *
+ * Design doc: 21-dev-server.md, 07-routing.md
+ */
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+interface RouteInfo {
+  /** URL path pattern (e.g., "/dashboard/[id]") */
+  path: string;
+  /** Whether this is a page route or API route handler */
+  type: 'page' | 'route';
+}
+
+/** Minimal segment node shape — matches ManifestSegmentNode. */
+interface SegmentNode {
+  segmentName: string;
+  segmentType: string;
+  urlPath: string;
+  page?: { filePath: string };
+  route?: { filePath: string };
+  children: SegmentNode[];
+  slots: Record<string, SegmentNode> | Map<string, SegmentNode>;
+}
+
+// ─── Route Collection ───────────────────────────────────────────────────────
+
+/**
+ * Collect all routable paths from the manifest tree.
+ *
+ * Walks the segment tree and collects paths for segments that have
+ * a page or route handler.
+ */
+export function collectRoutes(root: SegmentNode): RouteInfo[] {
+  const routes: RouteInfo[] = [];
+  walkRoutes(root, routes);
+  return routes.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+function walkRoutes(node: SegmentNode, routes: RouteInfo[]): void {
+  if (node.page) {
+    routes.push({ path: node.urlPath || '/', type: 'page' });
+  }
+  if (node.route) {
+    routes.push({ path: node.urlPath || '/', type: 'route' });
+  }
+
+  for (const child of node.children) {
+    walkRoutes(child, routes);
+  }
+
+  // Handle both Map and plain object for slots
+  const slots = node.slots;
+  if (slots instanceof Map) {
+    for (const [, slotNode] of slots) {
+      walkRoutes(slotNode, routes);
+    }
+  } else if (slots && typeof slots === 'object') {
+    for (const key of Object.keys(slots)) {
+      walkRoutes((slots as Record<string, SegmentNode>)[key]!, routes);
+    }
+  }
+}
+
+// ─── String Similarity ──────────────────────────────────────────────────────
+
+/**
+ * Compute Levenshtein distance between two strings.
+ *
+ * Used for "did you mean?" suggestions. Simple O(n*m) implementation
+ * — fine for short URL paths.
+ */
+function levenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+
+  // Optimization: use single-row DP
+  const row = Array.from({ length: n + 1 }, (_, i) => i);
+
+  for (let i = 1; i <= m; i++) {
+    let prev = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      const val = Math.min(
+        row[j]! + 1, // deletion
+        prev + 1, // insertion
+        row[j - 1]! + cost // substitution
+      );
+      row[j - 1] = prev;
+      prev = val;
+    }
+    row[n] = prev;
+  }
+
+  return row[n]!;
+}
+
+/**
+ * Find routes similar to the requested path.
+ *
+ * Returns up to 3 suggestions, sorted by similarity.
+ * Only includes routes with distance ≤ 40% of the longer string.
+ */
+export function findSimilarRoutes(requestedPath: string, routes: RouteInfo[]): RouteInfo[] {
+  if (routes.length === 0) return [];
+
+  const scored = routes
+    .map((route) => ({
+      route,
+      distance: levenshtein(requestedPath.toLowerCase(), route.path.toLowerCase()),
+    }))
+    .filter((s) => {
+      const maxLen = Math.max(requestedPath.length, s.route.path.length);
+      return s.distance <= maxLen * 0.4;
+    })
+    .sort((a, b) => a.distance - b.distance);
+
+  return scored.slice(0, 3).map((s) => s.route);
+}
+
+// ─── HTML Escaping ──────────────────────────────────────────────────────────
+
+function esc(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+// ─── HTML Generation ────────────────────────────────────────────────────────
+
+/**
+ * Generate a dev-mode 404 page with route listing and suggestions.
+ *
+ * Returns an HTML string for a self-contained error page.
+ */
+export function generateDev404Page(requestedPath: string, routes: RouteInfo[]): string {
+  const suggestions = findSimilarRoutes(requestedPath, routes);
+  const isEmpty = routes.length === 0;
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>404 — ${esc(requestedPath)} | timber.js</title>
+  <style>${CSS}</style>
+</head>
+<body>
+  <div class="container">
+    <header class="header">
+      <div class="badge">404 Not Found</div>
+      <h1 class="message">No route matches <code>${esc(requestedPath)}</code></h1>
+    </header>
+
+    ${
+      isEmpty
+        ? `<div class="welcome">
+        <h2>Welcome to timber.js</h2>
+        <p>Your app has no pages yet. Create your first page to get started:</p>
+        <div class="code-block">
+          <div class="code-header">app/page.tsx</div>
+          <pre><code>export default function Home() {
+  return &lt;h1&gt;Hello, timber.js!&lt;/h1&gt;;
+}</code></pre>
+        </div>
+        <p class="hint">Save the file and this page will reload automatically.</p>
+      </div>`
+        : ''
+    }
+
+    ${
+      suggestions.length > 0
+        ? `<div class="section">
+        <div class="section-header">Did you mean?</div>
+        <ul class="route-list suggestions">
+          ${suggestions.map((r) => `<li><a href="${esc(r.path)}">${esc(r.path)}</a> <span class="route-type">${r.type}</span></li>`).join('\n          ')}
+        </ul>
+      </div>`
+        : ''
+    }
+
+    ${
+      routes.length > 0
+        ? `<div class="section">
+        <div class="section-header">Available Routes (${routes.length})</div>
+        <ul class="route-list">
+          ${routes.map((r) => `<li><a href="${esc(r.path)}">${esc(r.path)}</a> <span class="route-type">${r.type}</span></li>`).join('\n          ')}
+        </ul>
+      </div>`
+        : ''
+    }
+
+    <footer class="footer">
+      <span class="timber-logo">🪵 timber.js</span>
+      <span class="footer-hint">Add or edit routes and this page will reload automatically.</span>
+    </footer>
+  </div>
+
+  <script>
+    // Auto-reload when Vite HMR fires (route added, file changed, etc.)
+    (function() {
+      try {
+        const ws = new WebSocket('ws://' + location.host, 'vite-hmr');
+        ws.addEventListener('message', function(e) {
+          try {
+            const data = JSON.parse(e.data);
+            if (data.type === 'full-reload' || data.type === 'update') {
+              location.reload();
+            }
+          } catch {}
+        });
+      } catch {}
+    })();
+  </script>
+</body>
+</html>`;
+}
+
+// ─── CSS ────────────────────────────────────────────────────────────────────
+
+const CSS = `
+  :root {
+    --bg: #fff;
+    --fg: #1a1a1a;
+    --fg-dim: #6b7280;
+    --border: #e5e7eb;
+    --badge-bg: #fefce8;
+    --badge-fg: #854d0e;
+    --badge-border: #fde68a;
+    --source-bg: #fafafa;
+    --link: #2563eb;
+    --code-bg: #f3f4f6;
+    --btn-bg: #f3f4f6;
+    --route-type-bg: #e0f2fe;
+    --route-type-fg: #0369a1;
+    --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: #422006;
+      --badge-fg: #fde68a;
+      --badge-border: #854d0e;
+      --source-bg: #18181b;
+      --link: #60a5fa;
+      --code-bg: #27272a;
+      --btn-bg: #27272a;
+      --route-type-bg: #0c4a6e;
+      --route-type-fg: #bae6fd;
+    }
+  }
+
+  * { 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;
+  }
+
+  .message code {
+    font-family: var(--code-font);
+    background: var(--code-bg);
+    padding: 0.125rem 0.375rem;
+    border-radius: 0.25rem;
+    font-size: 1.125rem;
+  }
+
+  .welcome {
+    margin-bottom: 1.5rem;
+    padding: 1.5rem;
+    border: 1px solid var(--border);
+    border-radius: 0.5rem;
+    background: var(--source-bg);
+  }
+
+  .welcome h2 {
+    font-size: 1.125rem;
+    margin-bottom: 0.5rem;
+  }
+
+  .welcome p { color: var(--fg-dim); margin-bottom: 1rem; }
+
+  .code-block {
+    border: 1px solid var(--border);
+    border-radius: 0.5rem;
+    overflow: hidden;
+    margin-bottom: 1rem;
+  }
+
+  .code-header {
+    font-size: 0.75rem;
+    font-weight: 600;
+    padding: 0.5rem 0.75rem;
+    background: var(--code-bg);
+    border-bottom: 1px solid var(--border);
+    color: var(--fg-dim);
+    font-family: var(--code-font);
+  }
+
+  .code-block pre {
+    padding: 0.75rem;
+    font-family: var(--code-font);
+    font-size: 0.8125rem;
+    line-height: 1.7;
+    overflow-x: auto;
+    margin: 0;
+  }
+
+  .section {
+    margin-bottom: 1rem;
+    border: 1px solid var(--border);
+    border-radius: 0.5rem;
+    overflow: hidden;
+  }
+
+  .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);
+  }
+
+  .route-list {
+    list-style: none;
+    padding: 0.5rem 0;
+  }
+
+  .route-list li {
+    padding: 0.375rem 0.75rem;
+    font-family: var(--code-font);
+    font-size: 0.8125rem;
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+  }
+
+  .route-list li:hover { background: var(--source-bg); }
+
+  .route-list a {
+    color: var(--link);
+    text-decoration: none;
+  }
+
+  .route-list a:hover { text-decoration: underline; }
+
+  .route-type {
+    font-size: 0.625rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    padding: 0.125rem 0.375rem;
+    border-radius: 0.25rem;
+    background: var(--route-type-bg);
+    color: var(--route-type-fg);
+  }
+
+  .suggestions { background: var(--source-bg); }
+
+  .hint { font-size: 0.875rem; color: var(--fg-dim); }
+
+  .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-error-overlay.ts

@@ -1,13 +1,53 @@
 /**
  * Dev error overlay — formats and sends errors to Vite's browser overlay and stderr.
  *
- * Integrates with Vite's built-in error overlay (`server.ssrFixStacktrace` +
- * `server.hot.send`) rather than implementing a custom overlay.
+ * Integrates with Vite's built-in error overlay (`server.hot.send`) rather
+ * than implementing a custom overlay.
+ *
+ * Stack trace source-mapping uses the correct Vite environment module graph:
+ * RSC errors use `server.environments.rsc.moduleGraph`, SSR/other errors use
+ * `server.environments.ssr.moduleGraph`. `server.ssrFixStacktrace()` is NOT
+ * used because it hardcodes the SSR module graph, which doesn't contain
+ * source maps for RSC modules (separate Vite environment with its own
+ * module graph). This caused RSC errors to show transpiled line numbers
+ * instead of original source positions.
  *
  * Design doc: 21-dev-server.md §"Error Overlay"
  */
 
-import type { ViteDevServer } from 'vite';
+import type { ViteDevServer, DevEnvironment } from 'vite';
+import { createRequire } from 'node:module';
+import { resolve, dirname } from 'node:path';
+
+// ─── Trace Mapping (lazy-loaded) ─────────────────────────────────────────────
+
+interface TraceMappingModule {
+  TraceMap: new (map: unknown) => unknown;
+  originalPositionFor: (
+    map: unknown,
+    needle: { line: number; column: number }
+  ) => { source: string | null; line: number | null; column: number | null };
+}
+
+let _traceMapping: TraceMappingModule | null = null;
+
+/**
+ * Lazy-load @jridgewell/trace-mapping from Vite's dependency tree.
+ * Vite bundles it internally; we resolve from Vite's package to avoid
+ * adding a direct dependency.
+ */
+function getTraceMapping(): TraceMappingModule {
+  if (_traceMapping) return _traceMapping;
+  // Resolve from Vite's package location so we pick up its transitive
+  // @jridgewell/trace-mapping without declaring it as a direct dependency.
+  // createRequire(import.meta.url) gives us ESM-compatible require (TIM-796),
+  // then we hop to Vite's path to reach its dependency tree (TIM-804).
+  const esmRequire = createRequire(import.meta.url);
+  const vitePath = esmRequire.resolve('vite');
+  const viteRequire = createRequire(vitePath);
+  _traceMapping = viteRequire('@jridgewell/trace-mapping') as TraceMappingModule;
+  return _traceMapping;
+}
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -21,7 +61,7 @@ export type ErrorPhase =
   | 'handler';
 
 /** Labels for terminal output. */
-const PHASE_LABELS: Record<ErrorPhase, string> = {
+export const PHASE_LABELS: Record<ErrorPhase, string> = {
   'module-transform': 'Module Transform',
   'proxy': 'Proxy',
   'middleware': 'Middleware',
@@ -131,54 +171,11 @@ export function classifyErrorPhase(error: Error, projectRoot: string): ErrorPhas
 
 // ─── Terminal Formatting ────────────────────────────────────────────────────
 
-// ANSI codes
-const RED = '\x1b[31m';
-const DIM = '\x1b[2m';
-const RESET = '\x1b[0m';
-const BOLD = '\x1b[1m';
-
-/**
- * Format an error for terminal output.
- *
- * - Red for the error message and phase label
- * - Dim for framework-internal frames
- * - Normal for application frames
- * - Separate section for component stack (if present)
- */
-export function formatTerminalError(error: Error, phase: ErrorPhase, projectRoot: string): string {
-  const lines: string[] = [];
-
-  // Phase header + error message
-  lines.push(`${RED}${BOLD}[timber] ${PHASE_LABELS[phase]} Error${RESET}`);
-  lines.push(`${RED}${error.message}${RESET}`);
-  lines.push('');
-
-  // Component stack (if present)
-  const componentStack = extractComponentStack(error);
-  if (componentStack) {
-    lines.push(`${BOLD}Component Stack:${RESET}`);
-    for (const csLine of componentStack.trim().split('\n')) {
-      lines.push(`  ${csLine.trim()}`);
-    }
-    lines.push('');
-  }
-
-  // Stack trace with frame dimming
-  if (error.stack) {
-    lines.push(`${BOLD}Stack Trace:${RESET}`);
-    const stackLines = error.stack.split('\n').slice(1); // Skip the first line (message)
-    for (const stackLine of stackLines) {
-      const frameType = classifyFrame(stackLine, projectRoot);
-      if (frameType === 'app') {
-        lines.push(stackLine);
-      } else {
-        lines.push(`${DIM}${stackLine}${RESET}`);
-      }
-    }
-  }
-
-  return lines.join('\n');
-}
+// formatTerminalError is implemented in the dedicated terminal formatter module
+// (dev-terminal-error.ts) to keep this file under 500 lines.
+// Import for use in sendErrorToOverlay, and re-export for external consumers.
+import { formatTerminalError as _formatTerminalError } from './dev-terminal-error.js';
+export const formatTerminalError = _formatTerminalError;
 
 // ─── RSC Debug Context ──────────────────────────────────────────────────────
 
@@ -237,6 +234,116 @@ export function formatRscDebugContext(components: RscDebugComponentInfo[]): stri
   return lines.join('\n');
 }
 
+// ─── Stack Trace Source-Mapping ──────────────────────────────────────────────
+
+/**
+ * Phases where the error originated in the RSC environment.
+ * These use `server.environments.rsc.moduleGraph` for source-mapping.
+ */
+const RSC_PHASES: ReadonlySet<ErrorPhase> = new Set(['render', 'access', 'middleware', 'handler']);
+
+/**
+ * Rewrite an error's stack trace using the correct Vite environment module graph.
+ *
+ * `server.ssrFixStacktrace()` hardcodes `server.environments.ssr.moduleGraph`,
+ * but RSC errors have stack frames pointing to modules loaded in the RSC
+ * environment — a separate Vite module graph with separate transform results
+ * and source maps. Using the SSR module graph silently fails to find the
+ * modules, leaving transpiled/bundled line numbers in the stack trace.
+ *
+ * This function picks the RSC module graph for render-phase errors and falls
+ * back to SSR for module-transform/proxy errors. If the first pass doesn't
+ * rewrite any frames (e.g., mixed RSC+SSR stack), it tries the other graph.
+ */
+function fixStacktraceForEnvironment(server: ViteDevServer, error: Error, phase: ErrorPhase): void {
+  if (!error.stack) return;
+
+  // Pick the primary environment based on error phase
+  const primaryEnvName = RSC_PHASES.has(phase) ? 'rsc' : 'ssr';
+  const fallbackEnvName = primaryEnvName === 'rsc' ? 'ssr' : 'rsc';
+
+  const primaryEnv = server.environments[primaryEnvName] as DevEnvironment | undefined;
+  const fallbackEnv = server.environments[fallbackEnvName] as DevEnvironment | undefined;
+
+  // Try primary environment first
+  if (primaryEnv?.moduleGraph) {
+    const rewritten = rewriteStacktrace(error.stack, primaryEnv.moduleGraph);
+    if (rewritten.changed) {
+      error.stack = rewritten.stack;
+      return;
+    }
+  }
+
+  // Fall back to the other environment if primary didn't rewrite anything
+  if (fallbackEnv?.moduleGraph) {
+    const rewritten = rewriteStacktrace(error.stack, fallbackEnv.moduleGraph);
+    if (rewritten.changed) {
+      error.stack = rewritten.stack;
+      return;
+    }
+  }
+}
+
+/**
+ * Rewrite stack trace frames using source maps from an environment's module graph.
+ *
+ * Mirrors Vite's internal `ssrRewriteStacktrace` logic but works with any
+ * `EnvironmentModuleGraph`, not just the SSR one.
+ *
+ * Returns the rewritten stack and whether any frames were actually changed.
+ */
+function rewriteStacktrace(
+  stack: string,
+  moduleGraph: DevEnvironment['moduleGraph']
+): { stack: string; changed: boolean } {
+  let changed = false;
+
+  const result = stack
+    .split('\n')
+    .map((line) => {
+      return line.replace(
+        /^ {4}at (?:(\S.*?)\s\()?(.+?):(\d+)(?::(\d+))?\)?/,
+        (input, varName, id, lineStr, colStr) => {
+          if (!id) return input;
+
+          const mod = moduleGraph.getModuleById(id);
+          const rawSourceMap = mod?.transformResult?.map;
+          if (!rawSourceMap) return input;
+
+          // Vite's module runner adds a 2-line offset for the async wrapper.
+          // This matches Vite's internal `calculateOffsetOnce()` behavior.
+          const OFFSET = 2;
+          const origLine = Number(lineStr) - OFFSET;
+          const origCol = Number(colStr) - 1;
+          if (origLine <= 0 || origCol < 0) return input;
+
+          // Use @jridgewell/trace-mapping resolved from Vite's dependency tree.
+          // Vite bundles it internally; we resolve from Vite's package location
+          // to avoid adding a direct dependency.
+          let pos: { source: string | null; line: number | null; column: number | null };
+          try {
+            const { TraceMap: TM, originalPositionFor: opf } = getTraceMapping();
+            const traced = new TM(rawSourceMap);
+            pos = opf(traced, { line: origLine, column: origCol });
+          } catch {
+            return input;
+          }
+
+          if (!pos.source || pos.line == null) return input;
+
+          changed = true;
+          const source = `${resolve(dirname(id), pos.source)}:${pos.line}:${(pos.column ?? 0) + 1}`;
+          const trimmedVarName = varName?.trim();
+          if (!trimmedVarName || trimmedVarName === 'eval') return `    at ${source}`;
+          return `    at ${trimmedVarName} (${source})`;
+        }
+      );
+    })
+    .join('\n');
+
+  return { stack: result, changed };
+}
+
 // ─── Overlay Integration ────────────────────────────────────────────────────
 
 /**
@@ -259,8 +366,12 @@ export function sendErrorToOverlay(
   projectRoot: string,
   rscDebugComponents?: RscDebugComponentInfo[]
 ): void {
-  // Fix stack trace to use source-mapped positions
-  server.ssrFixStacktrace(error);
+  // Fix stack trace to use source-mapped positions.
+  // Use the RSC environment's module graph for render/access/middleware errors
+  // (which originate in the RSC environment), and fall back to SSR for others.
+  // server.ssrFixStacktrace() is NOT used — it hardcodes the SSR module graph
+  // which doesn't contain source maps for RSC-loaded modules.
+  fixStacktraceForEnvironment(server, error, phase);
 
   // Log to stderr with frame dimming
   const formatted = formatTerminalError(error, phase, projectRoot);