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

package/dist/index.js

@@ -1,4 +1,4 @@
-import { r as __toESM, t as __commonJSMin } from "./_chunks/chunk-DYhsFzuS.js";
+import { a as __toCommonJS, i as __require, n as __esmMin, o as __toESM, r as __exportAll, t as __commonJSMin } from "./_chunks/chunk-BYIpzuS7.js";
 import { n as setViteServer } from "./_chunks/dev-warnings-DpGRGoDi.js";
 import { i as scanRoutes, n as generateRouteMap, t as collectInterceptionRewrites } from "./_chunks/interception-Dpn_UfAD.js";
 import { t as formatSize } from "./_chunks/format-CYBGxKtc.js";
@@ -6,9 +6,9 @@ import { dirname, extname, join, normalize, resolve } from "node:path";
 import { createRequire } from "node:module";
 import react, { reactCompilerPreset } from "@vitejs/plugin-react";
 import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { constants, createGzip, gzipSync } from "node:zlib";
 import { Readable } from "node:stream";
-import { fileURLToPath } from "node:url";
 import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { createHash, randomUUID } from "node:crypto";
 import { performance as performance$1 } from "node:perf_hooks";
@@ -98,9 +98,169 @@ function timberContent(ctx) {
 	};
 }
 //#endregion
+//#region src/plugins/dev-terminal-error.ts
+/**
+* Terminal error formatting — boxed, color-coded error output for dev mode.
+*
+* Produces a visually scannable error block with:
+* - Unicode box-drawing border around the error
+* - Phase badge and error message
+* - First app frame highlighted as the primary action item
+* - OSC 8 clickable file:line links (VSCode terminal, iTerm2, etc.)
+* - Internal/framework frames collapsed with a count
+* - Component stack (for React render errors)
+*
+* Dev-only: this module is only imported by dev-error-overlay.ts.
+*
+* Design doc: 21-dev-server.md §"Error Overlay"
+*/
+var RED$2 = "\x1B[31m";
+var CYAN = "\x1B[36m";
+var DIM$2 = "\x1B[2m";
+var RESET$2 = "\x1B[0m";
+var BOLD$2 = "\x1B[1m";
+var UNDERLINE = "\x1B[4m";
+/**
+* Wrap text in an OSC 8 hyperlink escape sequence.
+*
+* Terminals that support OSC 8 (VSCode, iTerm2, Windows Terminal, etc.)
+* render this as a clickable link. Others ignore the escape sequences
+* and show the text normally.
+*
+* Format: \x1b]8;;URL\x07TEXT\x1b]8;;\x07
+*/
+function hyperlink(text, url) {
+	return `\x1b]8;;${url}\x07${text}\x1b]8;;\x07`;
+}
+/**
+* Format a file:line:col reference as a clickable terminal link.
+*
+* Uses file:// URLs so terminals open the file in the configured editor.
+* The link text is styled with cyan + underline for visibility.
+*/
+function fileLink(filePath, line, col) {
+	const display = line ? `${filePath}:${line}${col ? `:${col}` : ""}` : filePath;
+	const base = pathToFileURL(filePath).href;
+	return `${CYAN}${UNDERLINE}${hyperlink(display, line ? `${base}:${line}${col ? `:${col}` : ""}` : base)}${RESET$2}`;
+}
+var BOX = {
+	topLeft: "╭",
+	topRight: "╮",
+	bottomLeft: "╰",
+	bottomRight: "╯",
+	horizontal: "─",
+	vertical: "│"
+};
+/**
+* Wrap lines of text in a Unicode box with a colored left border.
+*
+* @param lines - Content lines (no ANSI length calculation — keeps it simple)
+* @param width - Box width (characters). Lines longer than this are not truncated.
+*/
+function box(lines, borderColor, width = 80) {
+	const bar = BOX.horizontal.repeat(width - 2);
+	const output = [];
+	output.push(`${borderColor}${BOX.topLeft}${bar}${BOX.topRight}${RESET$2}`);
+	for (const line of lines) output.push(`${borderColor}${BOX.vertical}${RESET$2} ${line}`);
+	output.push(`${borderColor}${BOX.bottomLeft}${bar}${BOX.bottomRight}${RESET$2}`);
+	return output.join("\n");
+}
+/** Parse file/line/col from a stack frame line. */
+function parseFrame(frameLine) {
+	const parenMatch = /\(([^)]+):(\d+):(\d+)\)/.exec(frameLine);
+	if (parenMatch) return {
+		file: parenMatch[1],
+		line: Number(parenMatch[2]),
+		col: Number(parenMatch[3])
+	};
+	const bareMatch = /at (\/[^:]+):(\d+):(\d+)/.exec(frameLine);
+	if (bareMatch) return {
+		file: bareMatch[1],
+		line: Number(bareMatch[2]),
+		col: Number(bareMatch[3])
+	};
+	return {};
+}
+function classifyFrames(stack, projectRoot) {
+	return stack.split("\n").slice(1).filter((l) => l.trim().startsWith("at ")).map((raw) => {
+		const type = classifyFrame(raw, projectRoot);
+		const { file, line, col } = parseFrame(raw);
+		return {
+			raw,
+			type,
+			file,
+			line,
+			col
+		};
+	});
+}
+/**
+* Format an error for terminal output with a boxed layout.
+*
+* The output is designed to be scannable at a glance:
+* 1. Red box with phase badge and error message
+* 2. First app frame as a clickable link (the primary action item)
+* 3. App frames listed normally
+* 4. Internal/framework frames collapsed with count
+* 5. Component stack (if present)
+*/
+function formatTerminalError$1(error, phase, projectRoot) {
+	const sections = [];
+	const componentStack = extractComponentStack(error);
+	const loc = parseFirstAppFrame(error.stack ?? "", projectRoot);
+	const frames = error.stack ? classifyFrames(error.stack, projectRoot) : [];
+	const appFrames = frames.filter((f) => f.type === "app");
+	const internalCount = frames.filter((f) => f.type !== "app").length;
+	const boxLines = [];
+	boxLines.push(`${RED$2}${BOLD$2}${PHASE_LABELS$1[phase]} Error${RESET$2}`);
+	boxLines.push("");
+	for (const msgLine of error.message.split("\n")) boxLines.push(`${RED$2}${msgLine}${RESET$2}`);
+	if (loc) {
+		boxLines.push("");
+		const relPath = loc.file.startsWith(projectRoot) ? loc.file.slice(projectRoot.length + 1) : loc.file;
+		boxLines.push(`${BOLD$2}→${RESET$2} ${fileLink(loc.file, loc.line, loc.column)} ${DIM$2}(${relPath})${RESET$2}`);
+	}
+	sections.push(box(boxLines, RED$2));
+	if (componentStack) {
+		sections.push("");
+		sections.push(`  ${BOLD$2}Component Stack:${RESET$2}`);
+		for (const csLine of componentStack.trim().split("\n")) sections.push(`  ${DIM$2}${csLine.trim()}${RESET$2}`);
+	}
+	if (appFrames.length > 0) {
+		sections.push("");
+		sections.push(`  ${BOLD$2}Application Frames:${RESET$2}`);
+		for (let i = 0; i < appFrames.length; i++) {
+			const f = appFrames[i];
+			if (f.file && f.line) {
+				const prefix = i === 0 ? `${BOLD$2}▸${RESET$2}` : " ";
+				sections.push(`  ${prefix} ${fileLink(f.file, f.line, f.col)} ${DIM$2}${extractFnName(f.raw)}${RESET$2}`);
+			} else sections.push(`  ${f.raw}`);
+		}
+	}
+	if (internalCount > 0) sections.push(`  ${DIM$2}… ${internalCount} internal frame${internalCount !== 1 ? "s" : ""} hidden${RESET$2}`);
+	sections.push("");
+	return sections.join("\n");
+}
+/** Extract the function name from a stack frame line like "    at fnName (/path:1:2)". */
+function extractFnName(frameLine) {
+	const match = /at\s+(\S+)\s+\(/.exec(frameLine.trim());
+	return match ? match[1] : "";
+}
+//#endregion
 //#region src/plugins/dev-error-overlay.ts
+var _traceMapping = 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() {
+	if (_traceMapping) return _traceMapping;
+	_traceMapping = createRequire(createRequire(import.meta.url).resolve("vite"))("@jridgewell/trace-mapping");
+	return _traceMapping;
+}
 /** Labels for terminal output. */
-var PHASE_LABELS = {
+var PHASE_LABELS$1 = {
 	"module-transform": "Module Transform",
 	"proxy": "Proxy",
 	"middleware": "Middleware",
@@ -167,37 +327,7 @@ function classifyErrorPhase(error, projectRoot) {
 	}
 	return "render";
 }
-var RED = "\x1B[31m";
-var DIM = "\x1B[2m";
-var RESET = "\x1B[0m";
-var 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)
-*/
-function formatTerminalError(error, phase, projectRoot) {
-	const lines = [];
-	lines.push(`${RED}${BOLD}[timber] ${PHASE_LABELS[phase]} Error${RESET}`);
-	lines.push(`${RED}${error.message}${RESET}`);
-	lines.push("");
-	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("");
-	}
-	if (error.stack) {
-		lines.push(`${BOLD}Stack Trace:${RESET}`);
-		const stackLines = error.stack.split("\n").slice(1);
-		for (const stackLine of stackLines) if (classifyFrame(stackLine, projectRoot) === "app") lines.push(stackLine);
-		else lines.push(`${DIM}${stackLine}${RESET}`);
-	}
-	return lines.join("\n");
-}
+var formatTerminalError = formatTerminalError$1;
 /**
 * Format RSC debug component info into a readable string for the overlay.
 *
@@ -231,6 +361,90 @@ function formatRscDebugContext(components) {
 	return lines.join("\n");
 }
 /**
+* Phases where the error originated in the RSC environment.
+* These use `server.environments.rsc.moduleGraph` for source-mapping.
+*/
+var RSC_PHASES = 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, error, phase) {
+	if (!error.stack) return;
+	const primaryEnvName = RSC_PHASES.has(phase) ? "rsc" : "ssr";
+	const fallbackEnvName = primaryEnvName === "rsc" ? "ssr" : "rsc";
+	const primaryEnv = server.environments[primaryEnvName];
+	const fallbackEnv = server.environments[fallbackEnvName];
+	if (primaryEnv?.moduleGraph) {
+		const rewritten = rewriteStacktrace(error.stack, primaryEnv.moduleGraph);
+		if (rewritten.changed) {
+			error.stack = rewritten.stack;
+			return;
+		}
+	}
+	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, moduleGraph) {
+	let changed = false;
+	return {
+		stack: stack.split("\n").map((line) => {
+			return line.replace(/^ {4}at (?:(\S.*?)\s\()?(.+?):(\d+)(?::(\d+))?\)?/, (input, varName, id, lineStr, colStr) => {
+				if (!id) return input;
+				const rawSourceMap = moduleGraph.getModuleById(id)?.transformResult?.map;
+				if (!rawSourceMap) return input;
+				const origLine = Number(lineStr) - 2;
+				const origCol = Number(colStr) - 1;
+				if (origLine <= 0 || origCol < 0) return input;
+				let pos;
+				try {
+					const { TraceMap: TM, originalPositionFor: opf } = getTraceMapping();
+					pos = opf(new TM(rawSourceMap), {
+						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"),
+		changed
+	};
+}
+/**
 * Send an error to Vite's browser overlay and log it to stderr.
 *
 * Uses `server.ssrFixStacktrace()` to map stack traces back to source,
@@ -244,7 +458,7 @@ function formatRscDebugContext(components) {
 * The dev server remains running — errors are handled, not fatal.
 */
 function sendErrorToOverlay(server, error, phase, projectRoot, rscDebugComponents) {
-	server.ssrFixStacktrace(error);
+	fixStacktraceForEnvironment(server, error, phase);
 	const formatted = formatTerminalError(error, phase, projectRoot);
 	process.stderr.write(`${formatted}\n`);
 	const loc = parseFirstAppFrame(error.stack ?? "", projectRoot);
@@ -260,7 +474,7 @@ function sendErrorToOverlay(server, error, phase, projectRoot, rscDebugComponent
 				message,
 				stack: error.stack ?? "",
 				id: loc?.file,
-				plugin: `timber (${PHASE_LABELS[phase]})`,
+				plugin: `timber (${PHASE_LABELS$1[phase]})`,
 				loc: loc ? {
 					file: loc.file,
 					line: loc.line,
@@ -271,7 +485,631 @@ function sendErrorToOverlay(server, error, phase, projectRoot, rscDebugComponent
 	} catch {}
 }
 //#endregion
+//#region src/plugins/dev-error-page.ts
+/**
+* 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"
+*/
+var PHASE_LABELS = {
+	"module-transform": "Module Transform",
+	"proxy": "Proxy",
+	"middleware": "Middleware",
+	"access": "Access Check",
+	"render": "RSC Render",
+	"handler": "Route Handler"
+};
+var PHASE_HINTS = {
+	"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."
+};
+function classifyStack(stack, projectRoot) {
+	return stack.split("\n").slice(1).filter((line) => line.trim().startsWith("at ")).map((line) => ({
+		raw: line,
+		type: classifyFrame(line, projectRoot)
+	}));
+}
+/**
+* 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, line, contextLines = 3) {
+	try {
+		const { readFileSync } = __require("node:fs");
+		const allLines = readFileSync(filePath, "utf-8").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, i) => ({
+				num: start + 1 + i,
+				text,
+				highlight: start + 1 + i === line
+			}))
+		};
+	} catch {
+		return null;
+	}
+}
+function esc(str) {
+	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) {
+	return json.replace(/</g, "\\u003c");
+}
+/**
+* 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) {
+	return `${opts.protocol ?? "ws"}://${opts.host ?? "localhost"}${opts.port ? `:${opts.port}` : ""}${opts.path ?? ""}${opts.token ? `?token=${opts.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.
+*/
+function extractHmrOptions(config) {
+	const hmr = config.server?.hmr;
+	if (hmr === false) return void 0;
+	const hmrOpts = typeof hmr === "object" ? hmr : {};
+	const opts = {
+		protocol: hmrOpts.protocol,
+		host: hmrOpts.host,
+		port: hmrOpts.port,
+		path: hmrOpts.path,
+		token: config.webSocketToken
+	};
+	if (!opts.protocol && !opts.host && !opts.port && !opts.path && !opts.token) return;
+	return opts;
+}
+/**
+* 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
+*/
+function generateDevErrorPage(error, phase, projectRoot, hmrOptions) {
+	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;
+	let sourceContext = null;
+	if (loc) sourceContext = readSourceContext(loc.file, loc.line);
+	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>`;
+}
+var 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;
+  }
+`;
+//#endregion
+//#region src/config-validation.ts
+var config_validation_exports = /* @__PURE__ */ __exportAll({
+	addVirtualModuleContext: () => addVirtualModuleContext,
+	checkPeerDependencies: () => checkPeerDependencies,
+	formatConfigErrors: () => formatConfigErrors,
+	formatMissingPeers: () => formatMissingPeers,
+	validateConfig: () => validateConfig
+});
+/**
+* Validate a TimberUserConfig object.
+*
+* Returns an array of errors. Empty array means the config is valid.
+* Does not throw — the caller decides how to surface errors.
+*/
+function validateConfig(config) {
+	const errors = [];
+	if (config.output !== void 0 && config.output !== "server" && config.output !== "static") errors.push({
+		field: "output",
+		message: `Invalid output mode: "${String(config.output)}". Must be "server" or "static".`,
+		value: config.output,
+		suggestion: "Use output: \"server\" (default) or output: \"static\" for static site generation."
+	});
+	if (config.pageExtensions !== void 0) if (!Array.isArray(config.pageExtensions)) errors.push({
+		field: "pageExtensions",
+		message: "pageExtensions must be an array of strings.",
+		value: config.pageExtensions,
+		suggestion: "Example: pageExtensions: [\"tsx\", \"ts\", \"jsx\", \"js\", \"mdx\"]"
+	});
+	else for (const ext of config.pageExtensions) {
+		if (typeof ext !== "string") {
+			errors.push({
+				field: "pageExtensions",
+				message: `pageExtensions contains a non-string value: ${JSON.stringify(ext)}`,
+				value: ext
+			});
+			break;
+		}
+		if (ext.startsWith(".")) {
+			errors.push({
+				field: "pageExtensions",
+				message: `pageExtensions should not include the leading dot: "${ext}"`,
+				value: ext,
+				suggestion: `Use "${ext.slice(1)}" instead of "${ext}".`
+			});
+			break;
+		}
+	}
+	if (config.slowRequestMs !== void 0) {
+		if (typeof config.slowRequestMs !== "number" || config.slowRequestMs < 0) errors.push({
+			field: "slowRequestMs",
+			message: `slowRequestMs must be a non-negative number (got ${JSON.stringify(config.slowRequestMs)}).`,
+			value: config.slowRequestMs,
+			suggestion: "Use slowRequestMs: 3000 (default) or slowRequestMs: 0 to disable."
+		});
+	}
+	if (config.renderTimeoutMs !== void 0) {
+		if (typeof config.renderTimeoutMs !== "number" || config.renderTimeoutMs < 0) errors.push({
+			field: "renderTimeoutMs",
+			message: `renderTimeoutMs must be a non-negative number (got ${JSON.stringify(config.renderTimeoutMs)}).`,
+			value: config.renderTimeoutMs,
+			suggestion: "Use renderTimeoutMs: 30000 (default) or renderTimeoutMs: 0 to disable."
+		});
+	}
+	if (config.serverTiming !== void 0) {
+		if (config.serverTiming !== "detailed" && config.serverTiming !== "total" && config.serverTiming !== false) errors.push({
+			field: "serverTiming",
+			message: `Invalid serverTiming value: ${JSON.stringify(config.serverTiming)}.`,
+			value: config.serverTiming,
+			suggestion: "Use \"detailed\", \"total\", or false."
+		});
+	}
+	if (config.devBrowserLogs !== void 0) {
+		const valid = [
+			"error",
+			"warn",
+			"info",
+			"none"
+		];
+		if (!valid.includes(config.devBrowserLogs)) errors.push({
+			field: "devBrowserLogs",
+			message: `Invalid devBrowserLogs value: ${JSON.stringify(config.devBrowserLogs)}.`,
+			value: config.devBrowserLogs,
+			suggestion: `Use one of: ${valid.map((v) => `"${v}"`).join(", ")}.`
+		});
+	}
+	if (config.sitemap != null && typeof config.sitemap === "object") {
+		if (config.sitemap.enabled && !config.sitemap.baseUrl) errors.push({
+			field: "sitemap.baseUrl",
+			message: "sitemap.baseUrl is required when sitemap is enabled.",
+			suggestion: "Add sitemap: { enabled: true, baseUrl: \"https://example.com\" }."
+		});
+		if (config.sitemap.defaultPriority !== void 0 && (config.sitemap.defaultPriority < 0 || config.sitemap.defaultPriority > 1)) errors.push({
+			field: "sitemap.defaultPriority",
+			message: `sitemap.defaultPriority must be between 0.0 and 1.0 (got ${config.sitemap.defaultPriority}).`,
+			value: config.sitemap.defaultPriority
+		});
+	}
+	const knownKeys = new Set([
+		"output",
+		"debug",
+		"clientJavascript",
+		"adapter",
+		"cacheHandler",
+		"allowedOrigins",
+		"csrf",
+		"limits",
+		"pageExtensions",
+		"slowRequestMs",
+		"renderTimeoutMs",
+		"devBrowserLogs",
+		"dev",
+		"serverTiming",
+		"appDir",
+		"mdx",
+		"actionEncryption",
+		"reactCompiler",
+		"sitemap",
+		"buildDir",
+		"topLoader"
+	]);
+	for (const key of Object.keys(config)) if (!knownKeys.has(key)) errors.push({
+		field: key,
+		message: `Unknown config option: "${key}".`,
+		suggestion: `Check for typos. Known options: ${[...knownKeys].sort().join(", ")}.`
+	});
+	return errors;
+}
+/**
+* Format config errors for terminal output.
+*/
+function formatConfigErrors(errors) {
+	if (errors.length === 0) return "";
+	const lines = [];
+	lines.push(`${RED$1}${BOLD$1}[timber]${RESET$1} ${RED$1}${errors.length} config error${errors.length !== 1 ? "s" : ""} in timber.config.ts:${RESET$1}`);
+	for (const err of errors) {
+		lines.push("");
+		lines.push(`  ${RED$1}✗${RESET$1} ${BOLD$1}${err.field}${RESET$1}: ${err.message}`);
+		if (err.suggestion) lines.push(`    ${DIM$1}${err.suggestion}${RESET$1}`);
+	}
+	return lines.join("\n");
+}
+/**
+* Add timber-specific context to an error message that references virtual modules.
+*
+* If the error message contains a `virtual:timber-*` ID, appends a
+* human-readable explanation. Does not replace the original message.
+*/
+function addVirtualModuleContext(errorMessage) {
+	for (const [id, name] of Object.entries(VIRTUAL_MODULE_NAMES)) if (errorMessage.includes(id)) return `${errorMessage}\n\n  [timber] This error references "${id}" — timber's ${name}.\n  This is an internal module. The issue is likely in your app code or timber configuration.`;
+	return errorMessage;
+}
+/**
+* Check that required peer dependencies are installed.
+*
+* Uses require.resolve with a try/catch — no fs scanning.
+* Returns only the missing packages.
+*/
+function checkPeerDependencies(projectRoot) {
+	const results = [];
+	for (const name of REQUIRED_PEERS) try {
+		const { createRequire } = __require("node:module");
+		createRequire(`${projectRoot}/package.json`).resolve(name);
+		results.push({
+			name,
+			status: "ok"
+		});
+	} catch {
+		results.push({
+			name,
+			status: "missing"
+		});
+	}
+	return results;
+}
+/**
+* Format missing peer dependencies as an actionable warning.
+*/
+function formatMissingPeers(results) {
+	const missing = results.filter((r) => r.status === "missing");
+	if (missing.length === 0) return "";
+	const names = missing.map((r) => r.name);
+	const lines = [];
+	lines.push(`${RED$1}${BOLD$1}[timber]${RESET$1} ${RED$1}Missing required dependencies:${RESET$1}`);
+	lines.push("");
+	for (const name of names) lines.push(`  ${RED$1}✗${RESET$1} ${name}`);
+	lines.push("");
+	lines.push(`  ${DIM$1}Install with:${RESET$1}`);
+	lines.push(`  ${BOLD$1}pnpm add ${names.join(" ")}${RESET$1}`);
+	return lines.join("\n");
+}
+var RED$1, BOLD$1, DIM$1, RESET$1, VIRTUAL_MODULE_NAMES, REQUIRED_PEERS;
+var init_config_validation = __esmMin((() => {
+	RED$1 = "\x1B[31m";
+	BOLD$1 = "\x1B[1m";
+	DIM$1 = "\x1B[2m";
+	RESET$1 = "\x1B[0m";
+	VIRTUAL_MODULE_NAMES = {
+		"virtual:timber-rsc-entry": "RSC entry (server component handler)",
+		"virtual:timber-ssr-entry": "SSR entry (HTML renderer)",
+		"virtual:timber-browser-entry": "Browser entry (client hydration)",
+		"virtual:timber-config": "Runtime config (timber.config.ts)",
+		"virtual:timber-route-manifest": "Route manifest (app/ file tree)",
+		"virtual:timber-instrumentation": "Instrumentation (instrumentation.ts)",
+		"virtual:timber-cache-handler": "Cache handler (cacheHandler config)",
+		"virtual:timber-build-manifest": "Build manifest (asset mapping)"
+	};
+	REQUIRED_PEERS = [
+		"react",
+		"react-dom",
+		"@vitejs/plugin-react",
+		"@vitejs/plugin-rsc"
+	];
+}));
+//#endregion
 //#region src/server/compress.ts
+init_config_validation();
 /**
 * MIME types that benefit from compression.
 * text/* is handled via prefix matching; these are the specific
@@ -458,6 +1296,7 @@ function timberDevServer(ctx) {
 * calls next() to let Vite handle them.
 */
 function createTimberMiddleware(server, projectRoot) {
+	const hmrOptions = extractHmrOptions(server.config);
 	return async (req, res, next) => {
 		const url = req.url;
 		if (!url) {
@@ -483,8 +1322,11 @@ function createTimberMiddleware(server, projectRoot) {
 				sendErrorToOverlay(server, error, classifyErrorPhase(error, projectRoot), projectRoot, debugComponents);
 			});
 		} catch (error) {
-			if (error instanceof Error) sendErrorToOverlay(server, error, "module-transform", projectRoot);
-			respond500(res, error);
+			if (error instanceof Error) {
+				addTimberContext(error);
+				sendErrorToOverlay(server, error, "module-transform", projectRoot);
+			}
+			respond500(res, error, "module-transform", projectRoot, hmrOptions);
 			return;
 		}
 		if (typeof handler !== "function") {
@@ -497,21 +1339,44 @@ function createTimberMiddleware(server, projectRoot) {
 			const wrapper = server[Symbol.for("timber:dev-request-wrapper")];
 			await sendWebResponse(res, compressResponse(webRequest, wrapper ? await wrapper(() => handler(webRequest)) : await handler(webRequest)));
 		} catch (error) {
-			if (error instanceof Error) sendErrorToOverlay(server, error, classifyErrorPhase(error, projectRoot), projectRoot);
-			else process.stderr.write(`\x1b[31m[timber] Dev server error:\x1b[0m ${String(error)}\n`);
-			respond500(res, error);
+			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);
+			}
 		}
 	};
 }
 /**
 * 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, error) {
-	if (!res.headersSent) {
+function respond500(res, error, phase, projectRoot, hmrOptions) {
+	if (res.headersSent) return;
+	if (error instanceof Error) try {
+		const html = generateDevErrorPage(error, phase, projectRoot, hmrOptions);
 		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)}`);
-	}
+		res.setHeader("content-type", "text/html; charset=utf-8");
+		res.end(html);
+		return;
+	} catch {}
+	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) {
+	const enriched = addVirtualModuleContext(error.message);
+	if (enriched !== error.message) error.message = enriched;
 }
 /**
 * Convert a Node IncomingMessage to a Web Request.
@@ -11917,6 +12782,233 @@ function formatStatusFileLintWarnings(warnings) {
 	return lines.join("\n");
 }
 //#endregion
+//#region src/routing/convention-lint.ts
+/**
+* Convention linter — validates common misconfigurations in the route tree.
+*
+* Runs at scan time (build and dev startup). Each check produces a warning
+* with the file path, what's wrong, and what to do about it.
+*
+* These are warnings, not errors — they don't block the build. The goal is
+* to catch issues that would otherwise produce cryptic runtime behavior
+* (silent 404s, empty pages, confusing React errors).
+*
+* Design doc: 07-routing.md, 10-error-handling.md
+*/
+/**
+* Run all convention lint checks on a route tree.
+*
+* Returns an array of warnings. Empty array means everything looks good.
+*/
+function lintConventions(tree, appDir) {
+	const warnings = [];
+	checkEmptyApp(tree.root, appDir, warnings);
+	checkRouteExports(tree.root, warnings);
+	checkRootLayout(tree.root, warnings);
+	checkDefaultExports(tree.root, warnings);
+	return warnings;
+}
+/**
+* Warn when the app/ directory has no routable files at all.
+*
+* This catches the "I created app/ but didn't add any pages" case where
+* every request silently 404s with no guidance.
+*/
+function checkEmptyApp(root, appDir, warnings) {
+	if (hasAnyRoutable(root)) return;
+	warnings.push({
+		id: "EMPTY_APP",
+		summary: "No pages or route handlers found in app/",
+		details: `  Directory: ${appDir}\n\n  Your app/ directory has no page.tsx or route.ts files.
+  Every request will return 404.
+
+  To fix: Create app/page.tsx with a default export:
+
+    export default function Home() {
+      return <h1>Hello</h1>;
+    }
+`,
+		level: "warn"
+	});
+}
+/**
+* Check if a segment tree has any routable files (page or route) anywhere.
+*/
+function hasAnyRoutable(node) {
+	if (node.page || node.route) return true;
+	for (const child of node.children) if (hasAnyRoutable(child)) return true;
+	for (const [, slot] of node.slots) if (hasAnyRoutable(slot)) return true;
+	return false;
+}
+/**
+* Check if a segment tree has any page files (not just route handlers).
+* Used by checkRootLayout to avoid false positives for API-only apps (TIM-794).
+* API-only apps (just route.ts handlers) don't need a root layout.
+*/
+function hasAnyPage(node) {
+	if (node.page) return true;
+	for (const child of node.children) if (hasAnyPage(child)) return true;
+	for (const [, slot] of node.slots) if (hasAnyPage(slot)) return true;
+	return false;
+}
+/** HTTP methods that route.ts can export. */
+var HTTP_METHODS = [
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE",
+	"HEAD",
+	"OPTIONS"
+];
+/**
+* Pattern to detect named exports that look like HTTP method handlers.
+* Matches: export function GET, export const GET, export async function POST, etc.
+* Also matches: export { GET } or re-exports like export { GET } from './handler'.
+*
+* The re-export branch uses word boundaries (\b) around method names to avoid
+* matching substrings (e.g. TARGET should not match GET). See TIM-795.
+*/
+var EXPORT_PATTERN = new RegExp(`export\\s+(?:async\\s+)?(?:function|const|let|var)\\s+(${HTTP_METHODS.join("|")})\\b|export\\s*\\{[^}]*\\b(${HTTP_METHODS.join("|")})\\b[^}]*\\}`);
+/**
+* Warn when a route.ts file doesn't appear to export any recognized HTTP methods.
+*
+* Uses static analysis (regex on source text) — not module loading.
+* This is intentionally conservative: it may miss complex re-exports but
+* catches the common case of an empty route.ts or one with wrong export names.
+*/
+function checkRouteExports(node, warnings) {
+	if (node.route) {
+		const filePath = node.route.filePath;
+		try {
+			const source = readFileSync(filePath, "utf-8");
+			if (!EXPORT_PATTERN.test(source)) {
+				const hint = /export\s+default\b/.test(source) ? "  It looks like you have a default export. route.ts uses named exports\n  for HTTP methods (GET, POST, etc.), not a default export.\n" : "";
+				warnings.push({
+					id: "ROUTE_NO_METHODS",
+					summary: `route.ts has no HTTP method exports: ${filePath}`,
+					details: `  File: ${filePath}\n\n  route.ts files must export named HTTP method handlers.
+  Without them, the route matches but returns 405 Method Not Allowed.
+
+` + hint + "  Example:\n\n    export function GET(ctx: RouteContext) {\n      return Response.json({ hello: 'world' });\n    }\n",
+					level: "warn"
+				});
+			}
+		} catch {}
+	}
+	for (const child of node.children) checkRouteExports(child, warnings);
+	for (const [, slot] of node.slots) checkRouteExports(slot, warnings);
+}
+/**
+* Warn when the root segment has no layout.tsx.
+*
+* Without a root layout, there's no HTML shell (<html>, <body>).
+* The page will render but may have hydration issues or no proper document structure.
+*/
+function checkRootLayout(root, warnings) {
+	if (root.layout) return;
+	if (!hasAnyPage(root)) return;
+	warnings.push({
+		id: "NO_ROOT_LAYOUT",
+		summary: "No root layout.tsx found",
+		details: "  Your app has pages but no root layout.\n  Without app/layout.tsx, pages have no <html> or <body> wrapper.\n\n  To fix: Create app/layout.tsx:\n\n    export default function RootLayout({ children }: { children: React.ReactNode }) {\n      return (\n        <html lang=\"en\">\n          <body>{children}</body>\n        </html>\n      );\n    }\n",
+		level: "warn"
+	});
+}
+/**
+* Pattern to detect a default export in source code.
+* Matches: export default function, export default class, export default
+* Also matches: export { X as default }, export { default } from './Impl'
+*
+* The third alternative catches bare `default` re-exports (TIM-790).
+* The negative lookahead (?!\s+as\b) prevents matching `export { default as X }`
+* which is a named export, not a default export (TIM-806).
+*/
+var DEFAULT_EXPORT_PATTERN = /export\s+default\b|export\s*\{[^}]*\bas\s+default\b|export\s*\{[^}]*\bdefault\b(?!\s+as\b)[^}]*\}/;
+/**
+* Warn when page.tsx or layout.tsx files don't have a default export.
+*
+* Without a default export:
+* - page.tsx: the page renders nothing (empty content)
+* - layout.tsx: the layout module loads but has no component to render
+*
+* Uses static analysis (regex on source text) — intentionally conservative.
+*/
+function checkDefaultExports(node, warnings) {
+	if (node.page && isScriptExtension(node.page.extension)) checkFileDefaultExport(node.page.filePath, "page", warnings);
+	if (node.layout && isScriptExtension(node.layout.extension)) checkFileDefaultExport(node.layout.filePath, "layout", warnings);
+	for (const child of node.children) checkDefaultExports(child, warnings);
+	for (const [, slot] of node.slots) checkDefaultExports(slot, warnings);
+}
+function isScriptExtension(ext) {
+	return ext === "tsx" || ext === "ts" || ext === "jsx" || ext === "js";
+}
+function checkFileDefaultExport(filePath, fileType, warnings) {
+	try {
+		const source = readFileSync(filePath, "utf-8");
+		if (!DEFAULT_EXPORT_PATTERN.test(source)) warnings.push({
+			id: `NO_DEFAULT_EXPORT:${filePath}`,
+			summary: `${fileType}.tsx has no default export: ${filePath}`,
+			details: `  File: ${filePath}\n\n  ${fileType}.tsx files must export a default React component.\n  Without a default export, the ${fileType === "page" ? "page renders nothing" : "layout has no component to wrap children"}.\n\n  To fix: Add a default export:\n\n    export default function My${fileType === "page" ? "Page" : "Layout"}(${fileType === "layout" ? "{ children }" : ""}) {\n      return ${fileType === "layout" ? "<div>{children}</div>" : "<h1>Hello</h1>"};\n    }\n`,
+			level: "warn"
+		});
+	} catch {}
+}
+/**
+* Check if the app/ directory exists. Called before scanning.
+* Returns a warning if missing, or null if the directory exists.
+*/
+function checkAppDirExists(appDir) {
+	if (existsSync(appDir)) return null;
+	return {
+		id: "NO_APP_DIR",
+		summary: "No app/ directory found",
+		details: `  Expected: ${appDir}\n\n  timber.js requires an app/ directory for file-system routing.
+  Every request will return 404 until you create it.
+
+  To fix: Create the app/ directory with a page:
+
+    mkdir -p app
+    # Create app/layout.tsx and app/page.tsx
+`,
+		level: "error"
+	};
+}
+var YELLOW = "\x1B[33m";
+var RED = "\x1B[31m";
+var BOLD = "\x1B[1m";
+var DIM = "\x1B[2m";
+var RESET = "\x1B[0m";
+/**
+* Format warnings for terminal output.
+*
+* Groups by severity, uses colors, and includes fix suggestions.
+*/
+function formatConventionWarnings(warnings) {
+	if (warnings.length === 0) return "";
+	const errors = warnings.filter((w) => w.level === "error");
+	const warns = warnings.filter((w) => w.level === "warn");
+	const lines = [];
+	if (errors.length > 0) {
+		lines.push(`${RED}${BOLD}[timber]${RESET} ${RED}${errors.length} configuration error${errors.length !== 1 ? "s" : ""}:${RESET}`);
+		for (const e of errors) {
+			lines.push("");
+			lines.push(`  ${RED}✗${RESET} ${e.summary}`);
+			lines.push(`${DIM}${e.details}${RESET}`);
+		}
+	}
+	if (warns.length > 0) {
+		if (errors.length > 0) lines.push("");
+		lines.push(`${YELLOW}${BOLD}[timber]${RESET} ${YELLOW}${warns.length} configuration warning${warns.length !== 1 ? "s" : ""}:${RESET}`);
+		for (const w of warns) {
+			lines.push("");
+			lines.push(`  ${YELLOW}⚠${RESET} ${w.summary}`);
+			lines.push(`${DIM}${w.details}${RESET}`);
+		}
+	}
+	return lines.join("\n");
+}
+//#endregion
 //#region src/plugins/routing.ts
 var VIRTUAL_MODULE_ID$1 = "virtual:timber-route-manifest";
 var RESOLVED_VIRTUAL_ID$1 = `\0${VIRTUAL_MODULE_ID$1}`;
@@ -11968,14 +13060,33 @@ function timberRouting(ctx) {
 	/** Track warned files to avoid repeating warnings on rescan. */
 	const warnedFiles = /* @__PURE__ */ new Set();
 	function rescan() {
+		const appDirWarning = checkAppDirExists(ctx.appDir);
+		if (appDirWarning) {
+			const formatted = formatConventionWarnings([appDirWarning]);
+			if (formatted) process.stderr.write(`${formatted}\n`);
+			ctx.routeTree = { root: {
+				segmentName: "",
+				segmentType: "static",
+				urlPath: "/",
+				children: [],
+				slots: /* @__PURE__ */ new Map()
+			} };
+			return;
+		}
 		ctx.timer.start("route-scan");
 		ctx.routeTree = scanRoutes(ctx.appDir, { pageExtensions: ctx.config.pageExtensions });
 		ctx.timer.end("route-scan");
 		writeCodegen(ctx);
-		const newWarnings = lintStatusFileDirectives(ctx.routeTree).filter((w) => !warnedFiles.has(w.filePath));
-		if (newWarnings.length > 0) {
-			for (const w of newWarnings) warnedFiles.add(w.filePath);
-			console.warn(formatStatusFileLintWarnings(newWarnings));
+		const newStatusWarnings = lintStatusFileDirectives(ctx.routeTree).filter((w) => !warnedFiles.has(w.filePath));
+		if (newStatusWarnings.length > 0) {
+			for (const w of newStatusWarnings) warnedFiles.add(w.filePath);
+			console.warn(formatStatusFileLintWarnings(newStatusWarnings));
+		}
+		const newConventionWarnings = lintConventions(ctx.routeTree, ctx.appDir).filter((w) => !warnedFiles.has(w.id));
+		if (newConventionWarnings.length > 0) {
+			for (const w of newConventionWarnings) warnedFiles.add(w.id);
+			const formatted = formatConventionWarnings(newConventionWarnings);
+			if (formatted) process.stderr.write(`${formatted}\n`);
 		}
 	}
 	return {
@@ -13231,7 +14342,8 @@ function generateFontId(family, config) {
 	const weights = normalizeToArray(config.weight);
 	const styles = normalizeToArray(config.style);
 	const subsets = config.subsets ?? ["latin"];
-	return `${family.toLowerCase()}-${weights.join(",")}-${styles.join(",")}-${subsets.join(",")}`;
+	const display = config.display ?? "swap";
+	return `${family.toLowerCase()}-${weights.join(",")}-${styles.join(",")}-${subsets.join(",")}-${display}`;
 }
 /**
 * Normalize a string or string array to an array.
@@ -15451,6 +16563,11 @@ function timber(config) {
 			ctx.buildDir = resolve(resolved.root, resolved.build.outDir);
 			if (!ctx.dev) ctx.timer = createNoopTimer();
 			else ctx.timer.start("dev-server-setup");
+			const { validateConfig, formatConfigErrors, checkPeerDependencies, formatMissingPeers } = (init_config_validation(), __toCommonJS(config_validation_exports));
+			const configErrors = validateConfig(ctx.config);
+			if (configErrors.length > 0) process.stderr.write(`${formatConfigErrors(configErrors)}\n\n`);
+			const peerWarning = formatMissingPeers(checkPeerDependencies(ctx.root));
+			if (peerWarning) process.stderr.write(`${peerWarning}\n\n`);
 		}
 	};
 	const reactCompilerPlugins = [];