@timber-js/app 0.2.0-alpha.200 → 0.2.0-alpha.201

package/dist/_chunks/dev-server-DioP7tkQ.js

@@ -0,0 +1,2288 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
+import { S as isSsrStreamError, h as swallow } from "./logger-DqJ2VoAY.js";
+import "./csp-nonce-hOGniaG4.js";
+import { t as RSC_CONTENT_TYPE } from "./rsc-media-type-DDc7duTD.js";
+import { l as registerDevDiscovery } from "./graph-cache-Cv3njEH8.js";
+import { n as isScannableSourceFile, t as buildSourceExtensions } from "./scan-BoP17W3w.js";
+import { o as isMetadataRouteServePath } from "./metadata-routes-DSDjM_hJ.js";
+import { r as canonicalize } from "./canonicalize-CgHoscYO.js";
+import { t as matchUrlParts } from "./tree-match-CdbvYTBz.js";
+import { normalizePath } from "vite";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { createRequire } from "node:module";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import "node:http";
+import { Readable, pipeline } from "node:stream";
+import { pipeline as pipeline$1 } from "node:stream/promises";
+import "node:https";
+import "node:http2";
+import { pathToFileURL } from "node:url";
+import { styleText } from "node:util";
+import { randomUUID } from "node:crypto";
+import { realpath, stat } from "node:fs/promises";
+import { isIP } from "node:net";
+import { constants, createGzip } from "node:zlib";
+//#region ../../node_modules/.pnpm/srvx@1.0.5/node_modules/srvx/dist/adapters/node.mjs
+function sendNodeResponse(nodeRes, webRes) {
+	try {
+		return _sendNodeResponse(nodeRes, webRes, false) || Promise.resolve();
+	} catch (error) {
+		return Promise.reject(error);
+	}
+}
+function _sendNodeResponse(nodeRes, webRes, detached) {
+	if (!webRes) {
+		nodeRes.statusCode = 500;
+		return endNodeResponse(nodeRes, detached);
+	}
+	if (webRes._toNodeResponse) {
+		const res = webRes._toNodeResponse();
+		if (res.body) {
+			if (res.body instanceof ReadableStream) {
+				writeHead(nodeRes, res.status, res.statusText, res.headers);
+				return streamBody(res.body, nodeRes);
+			} else if (typeof res.body?.pipe === "function") return pipeBody(res.body, nodeRes, res.status, res.statusText, res.headers);
+			writeHead(nodeRes, res.status, res.statusText, res.headers);
+			nodeRes.write(res.body);
+		} else writeHead(nodeRes, res.status, res.statusText, res.headers);
+		return endNodeResponse(nodeRes, detached);
+	}
+	const rawHeaders = [];
+	for (const [key, value] of webRes.headers) rawHeaders.push(key, value);
+	writeHead(nodeRes, webRes.status, webRes.statusText, rawHeaders);
+	return webRes.body ? streamBody(webRes.body, nodeRes) : endNodeResponse(nodeRes, detached);
+}
+function writeHead(nodeRes, status, statusText, rawHeaders) {
+	if (!nodeRes.headersSent) {
+		if (nodeRes.req?.httpVersion === "2.0") nodeRes.writeHead(status, rawHeaders);
+		else nodeRes.writeHead(status, safeStatusText(statusText), rawHeaders);
+	}
+}
+var INVALID_REASON_PHRASE_RE = /[^\t\u0020-\u007E\u0080-\u00FF]/g;
+function safeStatusText(statusText) {
+	return typeof statusText === "string" && statusText ? statusText.replace(INVALID_REASON_PHRASE_RE, "") : statusText;
+}
+function endNodeResponse(nodeRes, detached) {
+	if (detached) {
+		nodeRes.end();
+		return;
+	}
+	return new Promise((resolve) => nodeRes.end(resolve));
+}
+function pipeBody(stream, nodeRes, status, statusText, headers) {
+	if (nodeRes.destroyed) {
+		stream.destroy?.();
+		return;
+	}
+	if (nodeRes.req?.method === "HEAD") {
+		if (typeof stream.destroy === "function") stream.destroy();
+		else stream.abort?.();
+		writeHead(nodeRes, status, statusText, headers);
+		return endNodeResponse(nodeRes);
+	}
+	if (typeof stream.on !== "function" || typeof stream.destroy !== "function") {
+		writeHead(nodeRes, status, statusText, headers);
+		stream.pipe(nodeRes);
+		return new Promise((resolve) => nodeRes.on("close", resolve));
+	}
+	if (stream.destroyed) {
+		writeHead(nodeRes, 500, "Internal Server Error", []);
+		return endNodeResponse(nodeRes);
+	}
+	return new Promise((resolve) => {
+		function cleanup() {
+			stream.off("error", onEarlyError);
+			stream.off("readable", onReadable);
+			nodeRes.off("close", onResClose);
+		}
+		function onEarlyError() {
+			cleanup();
+			stream.destroy();
+			writeHead(nodeRes, 500, "Internal Server Error", []);
+			endNodeResponse(nodeRes).then(resolve);
+		}
+		function onReadable() {
+			cleanup();
+			if (nodeRes.destroyed) {
+				stream.destroy();
+				return resolve();
+			}
+			writeHead(nodeRes, status, statusText, headers);
+			pipeline$1(stream, nodeRes).catch(() => {}).then(() => resolve());
+		}
+		function onResClose() {
+			cleanup();
+			stream.destroy();
+			resolve();
+		}
+		stream.once("error", onEarlyError);
+		stream.once("readable", onReadable);
+		nodeRes.once("close", onResClose);
+	});
+}
+function streamBody(stream, nodeRes) {
+	if (nodeRes.destroyed) {
+		stream.cancel().catch(() => {});
+		return;
+	}
+	if (nodeRes.req?.method === "HEAD") {
+		stream.cancel().catch(() => {});
+		return endNodeResponse(nodeRes);
+	}
+	const reader = stream.getReader();
+	function streamCancel(error) {
+		reader.cancel(error).catch(() => {});
+		if (error) nodeRes.destroy(error);
+	}
+	function streamHandle({ done, value }) {
+		try {
+			if (done) nodeRes.end();
+			else if (nodeRes.write(value)) reader.read().then(streamHandle, streamCancel);
+			else nodeRes.once("drain", () => reader.read().then(streamHandle, streamCancel));
+		} catch (error) {
+			streamCancel(error instanceof Error ? error : void 0);
+		}
+	}
+	nodeRes.on("close", streamCancel);
+	nodeRes.on("error", streamCancel);
+	reader.read().then(streamHandle, streamCancel);
+	return reader.closed.catch(streamCancel).finally(() => {
+		nodeRes.off("close", streamCancel);
+		nodeRes.off("error", streamCancel);
+	});
+}
+//#endregion
+//#region src/dev-tools/stack-classifier.ts
+/** 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 {};
+}
+/**
+* Classify a single stack frame line by origin.
+*
+* - 'app': user application code (in project root, not node_modules)
+* - 'framework': timber-app internal code
+* - 'internal': node_modules, Node.js internals
+*/
+function classifyFrame(frameLine, projectRoot) {
+	const trimmed = frameLine.trim();
+	if (trimmed.includes("packages/timber-app/")) return "framework";
+	if (trimmed.includes("node_modules/")) return "internal";
+	if (trimmed.startsWith("at node:") || trimmed.includes("(node:")) return "internal";
+	if (trimmed.includes(projectRoot)) return "app";
+	return "internal";
+}
+/**
+* Classify all frames in a full stack trace string.
+*
+* Parses the stack, skips the first line (error message), filters to
+* lines starting with "at ", and returns classified frames with optional
+* file/line/col metadata.
+*/
+function classifyStack(stack, projectRoot) {
+	return stack.split("\n").slice(1).filter((line) => line.trim().startsWith("at ")).map((raw) => {
+		const type = classifyFrame(raw, projectRoot);
+		const { file, line, col } = parseFrame(raw);
+		return {
+			raw,
+			type,
+			file,
+			line,
+			col
+		};
+	});
+}
+//#endregion
+//#region src/dev-tools/terminal.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 noValidate = { validateStream: false };
+var style = (fmt, text) => styleText(fmt, text, noValidate);
+/**
+* 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 style(["cyan", "underline"], hyperlink(display, line ? `${base}:${line}${col ? `:${col}` : ""}` : base));
+}
+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, borderFormat, width = 80) {
+	const bar = BOX.horizontal.repeat(width - 2);
+	const output = [];
+	output.push(style(borderFormat, `${BOX.topLeft}${bar}${BOX.topRight}`));
+	for (const line of lines) output.push(`${style(borderFormat, BOX.vertical)} ${line}`);
+	output.push(style(borderFormat, `${BOX.bottomLeft}${bar}${BOX.bottomRight}`));
+	return output.join("\n");
+}
+/**
+* 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 ? classifyStack(error.stack, projectRoot) : [];
+	const appFrames = frames.filter((f) => f.type === "app");
+	const internalCount = frames.filter((f) => f.type !== "app").length;
+	const boxLines = [];
+	boxLines.push(style(["red", "bold"], `${PHASE_LABELS$1[phase]} Error`));
+	boxLines.push("");
+	for (const msgLine of error.message.split("\n")) boxLines.push(style("red", msgLine));
+	if (loc) {
+		boxLines.push("");
+		const relPath = loc.file.startsWith(projectRoot) ? loc.file.slice(projectRoot.length + 1) : loc.file;
+		boxLines.push(`${style("bold", "→")} ${fileLink(loc.file, loc.line, loc.column)} ${style("dim", `(${relPath})`)}`);
+	}
+	sections.push(box(boxLines, "red"));
+	if (componentStack) {
+		sections.push("");
+		sections.push(`  ${style("bold", "Component Stack:")}`);
+		for (const csLine of componentStack.trim().split("\n")) sections.push(`  ${style("dim", csLine.trim())}`);
+	}
+	if (appFrames.length > 0) {
+		sections.push("");
+		sections.push(`  ${style("bold", "Application Frames:")}`);
+		for (let i = 0; i < appFrames.length; i++) {
+			const f = appFrames[i];
+			if (f.file && f.line) {
+				const prefix = i === 0 ? style("bold", "▸") : " ";
+				sections.push(`  ${prefix} ${fileLink(f.file, f.line, f.col)} ${style("dim", extractFnName(f.raw))}`);
+			} else sections.push(`  ${f.raw}`);
+		}
+	}
+	if (internalCount > 0) sections.push(`  ${style("dim", `… ${internalCount} internal frame${internalCount !== 1 ? "s" : ""} hidden`)}`);
+	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/dev-tools/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;
+	const vitePath = createRequire(import.meta.url).resolve("vite");
+	_traceMapping = createRequire(vitePath)("@jridgewell/trace-mapping");
+	return _traceMapping;
+}
+/** Labels for terminal output. */
+var PHASE_LABELS$1 = {
+	"module-transform": "Module Transform",
+	"proxy": "Proxy",
+	"middleware": "Middleware",
+	"access": "Access Check",
+	"render": "RSC Render",
+	"handler": "Route Handler"
+};
+/**
+* Extract the React component stack from an error, if present.
+* React attaches this as `componentStack` during renderToReadableStream errors.
+*/
+function extractComponentStack(error) {
+	if (error && typeof error === "object" && "componentStack" in error && typeof error.componentStack === "string") return error.componentStack;
+	return null;
+}
+/**
+* Parse the first application frame from a stack trace.
+* Returns file/line/column for the overlay's `loc` field.
+*/
+function parseFirstAppFrame(stack, projectRoot) {
+	const lines = stack.split("\n");
+	const parenRegex = /\(([^)]+):(\d+):(\d+)\)/;
+	const bareRegex = /at (\/[^:]+):(\d+):(\d+)/;
+	for (const line of lines) {
+		if (classifyFrame(line, projectRoot) !== "app") continue;
+		const match = parenRegex.exec(line) ?? bareRegex.exec(line);
+		if (!match) continue;
+		const [, file, lineNum, col] = match;
+		if (file && lineNum && col) return {
+			file,
+			line: parseInt(lineNum, 10),
+			column: parseInt(col, 10)
+		};
+	}
+	return null;
+}
+/**
+* Classify the error phase by inspecting the error's stack trace.
+* Falls back to 'render' if no specific phase can be determined.
+*/
+function classifyErrorPhase(error, projectRoot) {
+	const stack = error.stack ?? "";
+	if (extractComponentStack(error)) return "render";
+	const appRoot = projectRoot.replace(/\/$/, "");
+	if (stack.includes(`${appRoot}/app/`) || stack.includes("/app/")) {
+		if (stack.includes("/middleware.ts") || stack.includes("/middleware.js")) return "middleware";
+		if (stack.includes("/access.ts") || stack.includes("/access.js")) return "access";
+		if (stack.includes("/route.ts") || stack.includes("/route.js")) return "handler";
+	}
+	return "render";
+}
+var formatTerminalError = formatTerminalError$1;
+/**
+* Format RSC debug component info into a readable string for the overlay.
+*
+* Renders the server component tree that was active when an error occurred,
+* including component names and source locations from stack frames. This
+* gives developers visibility into which server components were rendering
+* without exposing source code.
+*
+* Returns an empty string if no components are provided.
+*/
+function formatRscDebugContext(components) {
+	if (!components || components.length === 0) return "";
+	const seen = /* @__PURE__ */ new Set();
+	const unique = [];
+	for (const c of components) if (!seen.has(c.name)) {
+		seen.add(c.name);
+		unique.push(c);
+	}
+	const lines = ["Server Component Tree:"];
+	for (let i = 0; i < unique.length; i++) {
+		const c = unique[i];
+		const indent = "  ".repeat(i + 1);
+		const envLabel = c.env ? ` [${c.env}]` : "";
+		let locStr = "";
+		if (c.stack && c.stack.length > 0) {
+			const frame = c.stack[0];
+			if (Array.isArray(frame) && frame.length >= 3) locStr = ` (${frame[1]}:${frame[2]})`;
+		}
+		lines.push(`${indent}${c.name}${envLabel}${locStr}`);
+	}
+	return lines.join("\n");
+}
+/**
+* Dynamically compute the line offset that Vite's module runner adds
+* when wrapping modules in an async function.
+*
+* Vite's `calculateOffsetOnce()` uses the same technique: create a new
+* AsyncFunction, throw from line 1, and check where the engine reports
+* the error. The difference between the reported line and 1 is the offset.
+*
+* This is engine-dependent (currently 2 on Node 18-22) and could change
+* in future Node.js or V8 versions. Computing it at runtime ensures we
+* always match the actual behavior.
+*/
+var _cachedOffset = null;
+function calculateModuleRunnerOffset() {
+	if (_cachedOffset !== null) return _cachedOffset;
+	try {
+		const AsyncFunction = async function() {}.constructor;
+		const src = new AsyncFunction("BODY").toString();
+		const bodyIndex = src.indexOf("BODY");
+		if (bodyIndex === -1) {
+			_cachedOffset = 2;
+			return _cachedOffset;
+		}
+		_cachedOffset = (src.slice(0, bodyIndex).match(/\n/g) || []).length;
+	} catch (e) {
+		console.debug("[timber] overlay offset calculation failed:", e instanceof Error ? e.message : e);
+		_cachedOffset = 2;
+	}
+	return _cachedOffset;
+}
+/**
+* Phases where the error originated in the RSC environment.
+* These use `server.environments.rsc.moduleGraph` for source-mapping.
+*/
+var RSC_PHASES = /* @__PURE__ */ 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 OFFSET = calculateModuleRunnerOffset();
+				const origLine = Number(lineStr) - OFFSET;
+				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 (e) {
+					console.debug("[timber] source map tracing failed:", e instanceof Error ? e.message : e);
+					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
+	};
+}
+/**
+* Source-map an error's stack trace using the Vite dev server's module graph.
+*
+* Exported so that the fallback error renderer (fallback-error.ts) can
+* source-map errors before rendering the dev error page. Without this,
+* the dev error page shows transpiled positions (e.g. page.tsx:1:1 instead
+* of page.tsx:4:9).
+*
+* See TIM-811.
+*/
+function fixErrorStacktrace(server, error, phase) {
+	fixStacktraceForEnvironment(server, error, phase ?? classifyErrorPhase(error, server.config.root));
+}
+/**
+* Send an error to Vite's browser overlay and log it to stderr.
+*
+* Uses `server.ssrFixStacktrace()` to map stack traces back to source,
+* then sends the error via `server.hot.send()` for the browser overlay.
+*
+* When `rscDebugComponents` is provided (dev mode only), the server
+* component tree context is appended to the error message. This helps
+* developers identify which server component caused the error without
+* exposing source code.
+*
+* The dev server remains running — errors are handled, not fatal.
+*/
+function sendErrorToOverlay(server, error, phase, projectRoot, rscDebugComponents) {
+	fixStacktraceForEnvironment(server, error, phase);
+	const formatted = formatTerminalError(error, phase, projectRoot);
+	process.stderr.write(`${formatted}\n`);
+	const loc = parseFirstAppFrame(error.stack ?? "", projectRoot);
+	const componentStack = extractComponentStack(error);
+	let message = error.message;
+	if (componentStack) message = `${error.message}\n\nComponent Stack:\n${componentStack.trim()}`;
+	const debugContext = formatRscDebugContext(rscDebugComponents ?? []);
+	if (debugContext) message = `${message}\n\n${debugContext}`;
+	try {
+		server.hot.send({
+			type: "error",
+			err: {
+				message,
+				stack: error.stack ?? "",
+				id: loc?.file,
+				plugin: `timber (${PHASE_LABELS$1[phase]})`,
+				loc: loc ? {
+					file: loc.file,
+					line: loc.line,
+					column: loc.column
+				} : void 0
+			}
+		});
+	} catch (e) {
+		console.debug("[timber] overlay error send failed:", e instanceof Error ? e.message : e);
+	}
+}
+//#endregion
+//#region src/server/utils/escape-html.ts
+/**
+* Shared HTML escaping utility.
+*
+* Used by both dev-only paths (error pages, 404 page) and production
+* paths (deny-renderer, RSC helpers). Lives in server/utils/ because
+* it's not dev-only.
+*/
+/**
+* Escape a string for safe embedding in HTML content or attributes.
+*
+* Replaces `&`, `<`, `>`, and `"` with their HTML entity equivalents.
+*/
+function escapeHtml(str) {
+	return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+//#endregion
+//#region src/dev-tools/dev-page-shell.ts
+/**
+* Shared scaffold for dev-mode HTML pages (dev error page, dev 404 page).
+*
+* Both pages are self-contained HTML documents served when the normal
+* render pipeline can't produce a page. They share:
+* - The document scaffold (head, container, footer)
+* - Base CSS (layout, light/dark variables, common components)
+* - The HMR auto-reload script that watches Vite's WebSocket and reloads
+*   when the developer fixes the error / adds the missing route
+*
+* Dev-only: this module is only imported by dev-mode code paths. It is
+* never included in production builds.
+*
+* Design doc: 21-dev-server.md §"Error Overlay", §"Dev 404 Page"
+*/
+/**
+* Extract HMR connection options from a Vite resolved config.
+* Used by the dev server to pass HMR config to the dev page generators
+* 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.clientPort || hmrOpts.port,
+		path: hmrOpts.path,
+		token: config.webSocketToken
+	};
+	if (!opts.protocol && !opts.host && !opts.port && !opts.path && !opts.token) return;
+	return opts;
+}
+/**
+* Build the inline auto-reload script for dev pages.
+*
+* The page is static HTML, not a Vite-managed module, so the normal HMR
+* update flow can't reach it. Instead we connect to Vite's HMR WebSocket
+* directly and reload on any update event.
+*
+* URL construction mirrors Vite's own client.mjs: explicitly configured
+* values win, and the browser's location fills any gaps at runtime. This
+* matters because Vite 8 requires a `?token=` on browser WS upgrades in
+* every config — a config with only a token still needs the host and port
+* from `location` (TIM-1067).
+*/
+function buildReloadScript(hmrOptions) {
+	return `    (function() {
+      try {
+        var o = ${JSON.stringify(hmrOptions ?? {}).replace(/</g, "\\u003c")};
+        var protocol = o.protocol || (location.protocol === 'https:' ? 'wss' : 'ws');
+        var host = o.host || location.hostname;
+        var port = o.port || location.port;
+        var url = protocol + '://' + host + (port ? ':' + port : '') + (o.path || '')
+          + (o.token ? '?token=' + encodeURIComponent(o.token) : '');
+        var ws = new WebSocket(url, 'vite-hmr');
+        ws.addEventListener('message', function(e) {
+          try {
+            var data = JSON.parse(e.data);
+            if (data.type === 'full-reload' || data.type === 'update') {
+              location.reload();
+            }
+          } catch (ex) {}
+        });
+      } catch (ex) {}
+    })();`;
+}
+/**
+* Render a self-contained dev page: scaffold + shared CSS + footer +
+* HMR auto-reload script.
+*/
+function renderDevPageShell(opts) {
+	return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escapeHtml(opts.title)}</title>
+  <style>${SHARED_CSS}${opts.extraCss ?? ""}</style>
+</head>
+<body>
+  <div class="container">
+    ${opts.bodyHtml}
+
+    <footer class="footer">
+      <span class="timber-logo">🪵 timber.js</span>
+      <span class="footer-hint">${opts.footerHint}</span>
+    </footer>
+  </div>
+
+  <script>
+${opts.extraScript ?? ""}
+    // Auto-reload when Vite HMR signals an update (file fixed, route added).
+${buildReloadScript(opts.hmrOptions)}
+  <\/script>
+</body>
+</html>`;
+}
+/**
+* Base CSS shared by all dev pages. Pages override the --badge-* variables
+* (and add their own component styles) via `extraCss`.
+*/
+var SHARED_CSS = `
+  :root {
+    --bg: #fff;
+    --fg: #1a1a1a;
+    --fg-dim: #6b7280;
+    --border: #e5e7eb;
+    --source-bg: #fafafa;
+    --link: #2563eb;
+    --code-bg: #f3f4f6;
+    --btn-bg: #f3f4f6;
+    --btn-fg: #374151;
+    --btn-border: #d1d5db;
+    --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;
+      --source-bg: #18181b;
+      --link: #60a5fa;
+      --code-bg: #27272a;
+      --btn-bg: #27272a;
+      --btn-fg: #e5e7eb;
+      --btn-border: #3f3f46;
+    }
+  }
+
+  * { 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;
+  }
+
+  .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);
+  }
+
+  .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/dev-tools/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')
+* and via dynamic import from fallback-error.ts in dev mode. 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."
+};
+/**
+* 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).
+*
+* Uses a top-level `node:fs` import — this module is dev-server-only and
+* Node-only. A bare `require()` here would throw in the ESM build and the
+* code frame would silently never render (TIM-1067, B48).
+*/
+function readSourceContext(filePath, line, contextLines = 3) {
+	try {
+		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 (e) {
+		console.debug("[timber] source context extraction failed:", e instanceof Error ? e.message : e);
+		return null;
+	}
+}
+var esc = escapeHtml;
+/**
+* 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 the equivalent unicode escape, 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");
+}
+/**
+* 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;
+	const bodyHtml = `<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="section-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>`;
+	const copyScript = `    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); }
+      });
+    }
+`;
+	return renderDevPageShell({
+		title: `Error — ${phaseLabel} | timber.js`,
+		extraCss: ERROR_CSS,
+		bodyHtml,
+		footerHint: "Fix the error and save — the page will reload automatically via HMR.",
+		extraScript: copyScript,
+		hmrOptions
+	});
+}
+var ERROR_CSS = `
+  :root {
+    --badge-bg: #fef2f2;
+    --badge-fg: #991b1b;
+    --badge-border: #fecaca;
+    --highlight-bg: #fef2f2;
+    --highlight-border: #ef4444;
+    --line-num: #9ca3af;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --badge-bg: #450a0a;
+      --badge-fg: #fca5a5;
+      --badge-border: #7f1d1d;
+      --highlight-bg: #450a0a;
+      --highlight-border: #dc2626;
+      --line-num: #6b7280;
+    }
+  }
+
+  .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-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;
+  }
+
+  .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; }
+`;
+//#endregion
+//#region src/config-validation.ts
+/**
+* Config validation — validates timber.config.ts at startup.
+*
+* Runs in the plugin's configResolved hook (once, at startup/build).
+* Each check produces a clear error message with the invalid value,
+* what's expected, and how to fix it.
+*
+* Design doc: 18-build-system.md
+*/
+var knownKeys = new Set(Object.keys({
+	output: true,
+	debug: true,
+	clientJavascript: true,
+	adapter: true,
+	allowedOrigins: true,
+	csrf: true,
+	limits: true,
+	forms: true,
+	pageExtensions: true,
+	slowRequestMs: true,
+	renderTimeoutMs: true,
+	devBrowserLogs: true,
+	dev: true,
+	serverTiming: true,
+	appDir: true,
+	mdx: true,
+	actionEncryption: true,
+	reactCompiler: true,
+	sitemap: true,
+	buildDir: true,
+	cache: true,
+	clientSegmentCache: true,
+	topLoader: true,
+	budget: true
+}));
+/**
+* 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). Setting 0 uses a 120s safety ceiling."
+		});
+	}
+	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
+		});
+	}
+	if (config.budget != null && typeof config.budget === "object") {
+		if (config.budget.firstLoadJs !== void 0 && (typeof config.budget.firstLoadJs !== "number" || config.budget.firstLoadJs <= 0)) errors.push({
+			field: "budget.firstLoadJs",
+			message: `budget.firstLoadJs must be a positive number in bytes (got ${JSON.stringify(config.budget.firstLoadJs)}).`,
+			value: config.budget.firstLoadJs,
+			suggestion: "Example: budget: { firstLoadJs: 150_000 } for a ~150 kB limit."
+		});
+	}
+	if (config.cache != null && typeof config.cache === "object") {
+		if (config.cache.strictKeyDiscipline !== void 0 && typeof config.cache.strictKeyDiscipline !== "boolean") errors.push({
+			field: "cache.strictKeyDiscipline",
+			message: `cache.strictKeyDiscipline must be a boolean (got ${JSON.stringify(config.cache.strictKeyDiscipline)}).`,
+			value: config.cache.strictKeyDiscipline,
+			suggestion: "Use cache: { strictKeyDiscipline: true } to promote key-discipline warnings to errors."
+		});
+	}
+	const MOVED_TO_CACHE_FILE = /* @__PURE__ */ new Set(["cacheHandler", "cdnPurge"]);
+	for (const key of Object.keys(config)) if (!knownKeys.has(key)) errors.push({
+		field: key,
+		message: `Unknown config option: "${key}".`,
+		suggestion: MOVED_TO_CACHE_FILE.has(key) ? `"${key}" has moved to timber.cache.ts. Export cacheHandler as default, cdnPurge as a named export.` : `Check for typos. Known options: ${[...knownKeys].sort().join(", ")}.`
+	});
+	return errors;
+}
+var RED = "\x1B[31m";
+var BOLD = "\x1B[1m";
+var DIM = "\x1B[2m";
+var RESET = "\x1B[0m";
+/**
+* Format config errors for terminal output.
+*/
+function formatConfigErrors(errors) {
+	if (errors.length === 0) return "";
+	const lines = [];
+	lines.push(`${RED}${BOLD}[timber]${RESET} ${RED}${errors.length} config error${errors.length !== 1 ? "s" : ""} in timber.config.ts:${RESET}`);
+	for (const err of errors) {
+		lines.push("");
+		lines.push(`  ${RED}✗${RESET} ${BOLD}${err.field}${RESET}: ${err.message}`);
+		if (err.suggestion) lines.push(`    ${DIM}${err.suggestion}${RESET}`);
+	}
+	return lines.join("\n");
+}
+var 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 (timber.cache.ts)",
+	"virtual:timber-build-manifest": "Build manifest (asset mapping)"
+};
+/**
+* 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;
+}
+/**
+* Required (non-optional) peer dependencies that must be installed.
+*/
+var REQUIRED_PEERS = [
+	"react",
+	"react-dom",
+	"@vitejs/plugin-react",
+	"@vitejs/plugin-rsc"
+];
+/**
+* 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 = [];
+	const userRequire = createRequire(`${projectRoot}/package.json`);
+	for (const name of REQUIRED_PEERS) try {
+		userRequire.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}${BOLD}[timber]${RESET} ${RED}Missing required dependencies:${RESET}`);
+	lines.push("");
+	for (const name of names) lines.push(`  ${RED}✗${RESET} ${name}`);
+	lines.push("");
+	lines.push(`  ${DIM}Install with:${RESET}`);
+	lines.push(`  ${BOLD}pnpm add ${names.join(" ")}${RESET}`);
+	return lines.join("\n");
+}
+//#endregion
+//#region src/server/rsc-entry/helpers.ts
+/**
+* Parse React Flight debug rows into component entries.
+*
+* The Flight debug channel writes rows in `hexId:json\n` format. Each row
+* with a JSON object containing a `name` field is a component debug info
+* entry. Rows without `name` (timing rows, reference rows like `D"$id"`)
+* are skipped.
+*
+* Security: `props` are explicitly stripped from parsed entries — they may
+* contain rendered output or user data. Only `name`, `env`, `key`, and
+* `stack` are retained.
+*/
+function parseDebugRows(text) {
+	if (!text) return [];
+	const entries = [];
+	const lines = text.split("\n");
+	for (const line of lines) {
+		if (!line) continue;
+		const colonIdx = line.indexOf(":");
+		if (colonIdx === -1) continue;
+		let payload = line.slice(colonIdx + 1);
+		if (payload.length > 0 && payload[0] !== "{" && payload[0] !== "[" && payload[0] !== "\"") payload = payload.slice(1);
+		if (!payload.startsWith("{")) continue;
+		try {
+			const parsed = JSON.parse(payload);
+			if (typeof parsed !== "object" || parsed === null) continue;
+			if (typeof parsed.name !== "string") continue;
+			entries.push({
+				name: parsed.name,
+				env: parsed.env ?? null,
+				key: parsed.key ?? null,
+				stack: Array.isArray(parsed.stack) ? parsed.stack : null
+			});
+		} catch (e) {
+			swallow(e, "malformed JSON in RSC client reference row");
+		}
+	}
+	return entries;
+}
+//#endregion
+//#region src/dev-tools/debug-channel.ts
+/**
+* Dev-mode RSC debug channel transport — pipes Flight debug data to
+* the browser via Vite's HMR WebSocket.
+*
+* React Flight writes debug rows (component info, owner stacks, $E
+* source entries) to a debug channel writable. This module reads
+* from the paired readable and buffers chunks until the browser
+* subscribes via 'timber:debug-subscribe'. Chunks are then replayed
+* and live-forwarded to that specific client (never broadcast).
+*
+* This matches the approach used by Next.js and Waku — debug data
+* travels out-of-band via WebSocket, not inline in the HTML response.
+*
+* Design ref: 13-security.md §7, TIM-1507
+*/
+var DEBUG_CHANNEL_EVENT = "timber:debug-data";
+var DEBUG_SUBSCRIBE_EVENT = "timber:debug-subscribe";
+var SESSION_TTL_MS = 6e4;
+/**
+* Registry of active debug channel sessions. The dev-server plugin
+* creates one instance and wires it into the HMR handlers.
+*/
+var DebugChannelRegistry = class {
+	sessions = /* @__PURE__ */ new Map();
+	/** Called by pipeToTransport when a chunk arrives from the RSC render. */
+	push(id, chunk) {
+		const session = this.sessions.get(id);
+		if (!session) return;
+		session.chunks.push(chunk);
+		if (session.client) session.client(DEBUG_CHANNEL_EVENT, {
+			id,
+			chunk
+		});
+	}
+	/** Called by pipeToTransport when the debug channel stream ends. */
+	finish(id) {
+		const session = this.sessions.get(id);
+		if (!session) return;
+		session.done = true;
+		if (session.client) {
+			session.client(DEBUG_CHANNEL_EVENT, {
+				id,
+				done: true
+			});
+			this.evict(id);
+		}
+	}
+	/** Called by the HMR subscribe handler when the browser requests its debug data. */
+	subscribe(id, clientSend) {
+		const session = this.sessions.get(id);
+		if (!session) {
+			clientSend(DEBUG_CHANNEL_EVENT, {
+				id,
+				done: true
+			});
+			return;
+		}
+		session.client = clientSend;
+		for (const chunk of session.chunks) clientSend(DEBUG_CHANNEL_EVENT, {
+			id,
+			chunk
+		});
+		if (session.done) {
+			clientSend(DEBUG_CHANNEL_EVENT, {
+				id,
+				done: true
+			});
+			this.evict(id);
+		}
+	}
+	/** Parse buffered debug rows into component entries for the error overlay. */
+	getComponents(id) {
+		const session = this.sessions.get(id);
+		if (!session) return [];
+		return parseDebugRows(session.chunks.map((b64) => Buffer.from(b64, "base64").toString("utf-8")).join(""));
+	}
+	/** Create a new session for a render request. Returns the requestId. */
+	create() {
+		const id = randomUUID();
+		const timer = setTimeout(() => this.evict(id), SESSION_TTL_MS);
+		if (typeof timer === "object" && "unref" in timer) timer.unref();
+		this.sessions.set(id, {
+			chunks: [],
+			done: false,
+			timer
+		});
+		return id;
+	}
+	evict(id) {
+		const session = this.sessions.get(id);
+		if (session) {
+			if (session.client && !session.done) session.client(DEBUG_CHANNEL_EVENT, {
+				id,
+				done: true
+			});
+			clearTimeout(session.timer);
+			this.sessions.delete(id);
+		}
+	}
+};
+/** HMR custom event name for graph-affecting file changes. */
+var GRAPH_UPDATE_EVENT = "timber:graph-update";
+/**
+* Host-header allowlist check, ported branch-for-branch from Vite's
+* host-validation middleware (`isHostAllowedWithoutCache`) so this
+* endpoint's reachability matches the rest of the dev server:
+*
+* - `allowedHosts: true` allows everything
+* - a MISSING Host header is allowed (Vite parity — HTTP/1.0 probes)
+* - any IP-literal host is allowed (`vite --host` LAN access sends
+*   `Host: 192.168.x.x:port`; rejecting it would 403 this endpoint
+*   while every other dev route works)
+* - `localhost` and `*.localhost` are always allowed
+* - allowedHosts entries: exact match, or `.suffix` subdomain entries
+*/
+function isAllowedGraphHost(hostHeader, allowedHosts) {
+	if (allowedHosts === true) return true;
+	if (hostHeader === void 0) return true;
+	let host = hostHeader;
+	const bracket = host.match(/^\[([^\]]+)\](?::\d+)?$/);
+	if (bracket) return isIP(bracket[1]) === 6;
+	const colon = host.lastIndexOf(":");
+	if (colon !== -1) host = host.slice(0, colon);
+	host = host.toLowerCase();
+	if (isIP(host) !== 0) return true;
+	if (host === "localhost" || host.endsWith(".localhost")) return true;
+	for (const entry of allowedHosts ?? []) {
+		const allowed = entry.toLowerCase();
+		if (allowed.startsWith(".")) {
+			if (host === allowed.slice(1) || host.endsWith(allowed)) return true;
+		} else if (host === allowed) return true;
+	}
+	return false;
+}
+/**
+* Non-http(s) origins admitted without a host check: Vite's own
+* `file:` / `*-extension:` set (its host-validation regex), plus
+* `vscode-webview:` — VS Code webviews fetch with that Origin, and the
+* extension is this endpoint's primary consumer. Vite itself never
+* origin-checks plain HTTP GETs (only WebSocket upgrades), so this
+* layer is strictly additional; the additions keep it from rejecting
+* consumers Vite would serve.
+*
+* NOT admitted: `Origin: null`. Browsers serialize file:// pages'
+* opaque origin as the literal string `null` — but so do sandboxed
+* iframes and data: documents, exactly the untrusted embedders the
+* check exists to stop, and the header offers nothing to tell them
+* apart. file:// pages therefore cannot use this endpoint from a
+* browser; the `file:` scheme entry covers non-browser clients that
+* send a real scheme-form Origin (Vite admits the same set).
+*/
+var TRUSTED_ORIGIN_SCHEMES = /^(?:file|vscode-webview|.+-extension):/i;
+/** Origin check: absent is fine (CLI probe); present must pass the host allowlist. */
+function isAllowedGraphOrigin(originHeader, allowedHosts) {
+	if (originHeader === void 0) return true;
+	if (TRUSTED_ORIGIN_SCHEMES.test(originHeader)) return true;
+	let originUrl;
+	try {
+		originUrl = new URL(originHeader);
+	} catch {
+		return false;
+	}
+	if (originUrl.host === "") return false;
+	const bareHost = originUrl.hostname.replace(/^\[|\]$/g, "");
+	if (isIP(bareHost) !== 0) {
+		if (bareHost === "127.0.0.1" || bareHost === "::1") return true;
+		if (allowedHosts === true) return true;
+		return (allowedHosts ?? []).some((entry) => entry.toLowerCase() === bareHost);
+	}
+	return isAllowedGraphHost(originUrl.host, allowedHosts);
+}
+function sendJson(res, status, body) {
+	res.statusCode = status;
+	res.setHeader("content-type", "application/json; charset=utf-8");
+	res.end(JSON.stringify(body));
+}
+/**
+* Echo an ADMITTED origin back as CORS headers. A webview fetch from
+* `vscode-webview://…` passes the origin check but the browser rejects
+* the response body without `Access-Control-Allow-Origin` — the exact
+* transport design/47 specifies for the extension. Only the validated
+* origin is echoed (never `*`), with `Vary: Origin` for any cache in
+* between; unadmitted origins were already 403'd and get nothing.
+*/
+function reflectCors(res, origin) {
+	if (!origin) return;
+	res.setHeader("Access-Control-Allow-Origin", origin);
+	res.setHeader("Vary", "Origin");
+}
+/**
+* Create the Connect middleware handling GET /__timber/graph.
+*
+* Query surface: `?file=<path>` (absolute or project-root-relative) or
+* `?all=1`. Anything else is a 400 — fail loudly, like the CLI.
+*/
+function createGraphEndpointMiddleware(server, ctx) {
+	const sourceExtensions = buildSourceExtensions(ctx.config.pageExtensions);
+	return async (req, res, next) => {
+		const rawUrl = req.url;
+		if (!rawUrl || !rawUrl.startsWith("/__timber/")) {
+			next();
+			return;
+		}
+		const url = new URL(rawUrl, "http://placeholder.invalid");
+		if (url.pathname !== "/__timber/graph") {
+			sendJson(res, 404, { error: `unknown /__timber/ endpoint: ${url.pathname}` });
+			return;
+		}
+		if (req.method !== "GET") {
+			res.setHeader("Allow", "GET");
+			sendJson(res, 405, { error: "GET only" });
+			return;
+		}
+		const origin = req.headers.origin;
+		const allowedHosts = server.config.server.allowedHosts;
+		if (!server.config.server.https && !isAllowedGraphHost(req.headers.host, allowedHosts)) {
+			sendJson(res, 403, { error: "host not allowed" });
+			return;
+		}
+		if (!isAllowedGraphOrigin(origin, allowedHosts)) {
+			sendJson(res, 403, { error: "origin not allowed" });
+			return;
+		}
+		reflectCors(res, origin);
+		try {
+			const { classifyLiveFile, classifyLiveProject } = await import("./live-graph-VjHFF5EV.js");
+			const preserveSymlinks = server.config.resolve.preserveSymlinks;
+			const root = normalizePath(preserveSymlinks ? ctx.root : await realpath(ctx.root));
+			const appDir = normalizePath(preserveSymlinks ? ctx.appDir : await realpath(ctx.appDir).catch(() => join(root, relative(ctx.root, ctx.appDir))));
+			const liveCtx = {
+				rsc: server.environments.rsc.moduleGraph,
+				ssr: server.environments.ssr.moduleGraph,
+				client: server.environments.client.moduleGraph,
+				root,
+				appDir,
+				pageExtensions: ctx.config.pageExtensions
+			};
+			const allParam = url.searchParams.get("all");
+			if (allParam !== null && allParam !== "1") {
+				sendJson(res, 400, { error: `unsupported all value: ${allParam} (use ?all=1)` });
+				return;
+			}
+			if (allParam === "1") {
+				sendJson(res, 200, {
+					version: 1,
+					source: "dev-server",
+					cached: false,
+					...await classifyLiveProject(liveCtx)
+				});
+				return;
+			}
+			const fileParam = url.searchParams.get("file");
+			if (!fileParam) {
+				sendJson(res, 400, { error: "missing ?file=<path> (or ?all=1)" });
+				return;
+			}
+			const absolute = normalizePath(isAbsolute(fileParam) ? resolve(fileParam) : resolve(root, fileParam));
+			let target;
+			try {
+				const physical = normalizePath(await realpath(absolute));
+				const rootPhysical = preserveSymlinks ? normalizePath(await realpath(root)) : root;
+				if (physical !== rootPhysical && !physical.startsWith(rootPhysical + "/") && !physical.startsWith(rootPhysical + "\\")) {
+					sendJson(res, 404, { error: `not a project file under ${root}` });
+					return;
+				}
+				if (preserveSymlinks) {
+					if (physical !== rootPhysical + absolute.slice(root.length)) {
+						sendJson(res, 404, { error: `not a project source file: ${absolute}` });
+						return;
+					}
+				}
+				target = normalizePath(preserveSymlinks ? absolute : physical);
+			} catch {
+				sendJson(res, 404, { error: `file not found: ${absolute}` });
+				return;
+			}
+			if (target !== root && !target.startsWith(root + "/") && !target.startsWith(root + "\\")) {
+				sendJson(res, 404, { error: `not a project file under ${root}` });
+				return;
+			}
+			if (!(await stat(target).catch(() => null))?.isFile() || !isScannableSourceFile(normalizePath(target), normalizePath(root), sourceExtensions)) {
+				sendJson(res, 404, { error: `not a project source file: ${target}` });
+				return;
+			}
+			const errors = [];
+			const module = await classifyLiveFile(target, liveCtx, void 0, errors);
+			sendJson(res, 200, {
+				version: 1,
+				source: "dev-server",
+				cached: false,
+				target: {
+					input: fileParam,
+					resolved: target
+				},
+				kind: module.kind,
+				pending: module.pending,
+				subtreeUnknown: module.subtreeUnknown,
+				envs: module.envs,
+				boundary: module.boundary,
+				chains: module.chains,
+				poisonings: module.poisonings,
+				errors
+			});
+		} catch (error) {
+			sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+		}
+	};
+}
+/**
+* Build the push channel: `timber:graph-update` custom HMR events per
+* project-source change. Consumers (the VS Code extension) re-query
+* and debounce on their side; the channel just emits. Non-source noise
+* (build output, dotdirs) is filtered by the same extension set the
+* scanners use.
+*
+* Two phases per edit, because one is not enough (codex review, PR
+* #1057): the `invalidated` event fires from the plugin's `hotUpdate`
+* hook — after Vite clears the module's transform result, but its
+* importer EDGES are only rebuilt when the module is next transformed.
+* The `transformed` event fires for exactly the files with a pending
+* invalidation, and only once the node's `transformResult` is set
+* again — the plugin transform hook itself runs BEFORE Vite's trailing
+* `vite:import-analysis` (which rebuilds the edges), so the hook only
+* marks the file "settling" and a short bounded timer confirms
+* completion via `isTransformed` before emitting. (A module nothing
+* re-requests never re-transforms — its `transformed` event waits for
+* the next render, which is also when the graph has new information.)
+*/
+function makeGraphUpdateChannel(ctx, send, isTransformed, canonicalize = (file) => file) {
+	/** Files invalidated but not yet re-transformed, per environment. */
+	const pending = /* @__PURE__ */ new Set();
+	const key = (file, environment) => `${environment}\0${file}`;
+	const root = normalizePath(canonicalize(ctx.root));
+	const extensions = buildSourceExtensions(ctx.config.pageExtensions);
+	const emitTransformed = (file, environment, structural) => {
+		send({
+			type: "custom",
+			event: GRAPH_UPDATE_EVENT,
+			data: structural ? {
+				file,
+				event: "update",
+				environment,
+				phase: "transformed",
+				structural: true
+			} : {
+				file,
+				event: "update",
+				environment,
+				phase: "transformed"
+			}
+		});
+	};
+	/**
+	* Confirm the transform request finished (transformResult set again)
+	* before emitting phase `transformed`. If confirmation never arrives
+	* within the bounded schedule below, the pending key is RE-ARMED
+	* rather than emitted — a `transformed` event over a still-stale
+	* graph would be a false all-clear with no corrective event.
+	*/
+	/**
+	* Delays between confirmation re-checks: dense while a normal
+	* transform request finishes, then exponential backoff for slow
+	* import-analysis passes (large graphs, cold dep optimizer) — a
+	* completed slow transform is CACHED, so no later transform hook may
+	* ever fire for it and the tail checks are the only chance to emit.
+	* Total window ≈ 16 s, then give up (bounded — the async-safety
+	* rules ban open-ended polling) and re-arm the pending key.
+	*/
+	const CONFIRM_DELAYS_MS = [
+		...Array.from({ length: 25 }, () => 20),
+		500,
+		1e3,
+		2e3,
+		4e3,
+		8e3
+	];
+	const confirmAndEmit = (file, environment, attempt = 0, structural = false) => {
+		if (!isTransformed || isTransformed(file, environment)) {
+			emitTransformed(file, environment, structural);
+			return;
+		}
+		if (attempt >= CONFIRM_DELAYS_MS.length) {
+			if (!structural) pending.add(key(file, environment));
+			return;
+		}
+		setTimeout(() => confirmAndEmit(file, environment, attempt + 1, structural), CONFIRM_DELAYS_MS[attempt]);
+	};
+	return {
+		onHotUpdate(update) {
+			const file = normalizePath(canonicalize(update.file));
+			if (!isScannableSourceFile(file, root, extensions)) return;
+			if (update.type === "delete") pending.delete(key(file, update.environment));
+			else pending.add(key(file, update.environment));
+			send({
+				type: "custom",
+				event: GRAPH_UPDATE_EVENT,
+				data: {
+					file,
+					event: update.type,
+					environment: update.environment,
+					phase: "invalidated"
+				}
+			});
+		},
+		onTransform(id, environment) {
+			const file = normalizePath(id.split("?")[0]);
+			if (file.includes("virtual:timber-route-manifest")) {
+				confirmAndEmit(file, environment, 25, true);
+				return;
+			}
+			const pendingKey = key(file, environment);
+			if (!pending.has(pendingKey)) return;
+			pending.delete(pendingKey);
+			confirmAndEmit(file, environment);
+		}
+	};
+}
+//#endregion
+//#region src/server/compress.ts
+/**
+* MIME types that benefit from compression.
+* text/* is handled via prefix matching; these are the specific
+* application/* and image/* types that are compressible.
+*/
+var COMPRESSIBLE_TYPES = /* @__PURE__ */ new Set([
+	"text/html",
+	"text/css",
+	"text/plain",
+	"text/xml",
+	"text/javascript",
+	RSC_CONTENT_TYPE,
+	"application/json",
+	"application/javascript",
+	"application/xml",
+	"application/xhtml+xml",
+	"application/rss+xml",
+	"application/atom+xml",
+	"image/svg+xml"
+]);
+/**
+* Status codes that should never be compressed (no body or special semantics).
+*/
+var NO_COMPRESS_STATUSES = /* @__PURE__ */ new Set([204, 304]);
+/**
+* Parse Accept-Encoding and return the best supported encoding.
+* Returns 'gzip' if the client accepts it, null otherwise.
+*
+* Brotli (br) is intentionally not handled at the application level.
+* At the streaming-friendly quality levels (0–4), brotli's compression
+* ratio advantage over gzip is marginal, and node:zlib's brotli transform
+* buffers output internally — turning smooth streaming responses into
+* large infrequent bursts. Brotli's real wins come from offline/static
+* compression at higher quality levels (5–11), which CDNs and reverse
+* proxies (Cloudflare, nginx, Caddy) apply on cached responses.
+*
+* See design/25-production-deployments.md.
+*/
+function negotiateEncoding(acceptEncoding) {
+	if (!acceptEncoding) return null;
+	const parts = acceptEncoding.split(",");
+	for (const part of parts) {
+		const [token, ...params] = part.split(";");
+		if (token.trim().toLowerCase() !== "gzip") continue;
+		let qValue = 1;
+		for (const param of params) {
+			const trimmed = param.trim().toLowerCase();
+			if (trimmed.startsWith("q=")) {
+				qValue = parseFloat(trimmed.slice(2));
+				if (Number.isNaN(qValue)) qValue = 1;
+				break;
+			}
+		}
+		if (qValue > 0) return "gzip";
+	}
+	return null;
+}
+/**
+* Determine if a response should be compressed.
+*
+* Returns false for:
+* - Responses without a body (204, 304, null body)
+* - Already-encoded responses (Content-Encoding set)
+* - Non-compressible content types (images, binary)
+* - SSE streams (text/event-stream — must not be buffered)
+*/
+function shouldCompress(response) {
+	if (!response.body) return false;
+	if (NO_COMPRESS_STATUSES.has(response.status)) return false;
+	if (response.headers.has("Content-Encoding")) return false;
+	const contentType = response.headers.get("Content-Type");
+	if (!contentType) return false;
+	const mimeType = contentType.split(";")[0].trim().toLowerCase();
+	if (mimeType === "text/event-stream") return false;
+	return COMPRESSIBLE_TYPES.has(mimeType);
+}
+/**
+* Compress a Web Response if the client supports it and the content is compressible.
+*
+* Returns the original response unchanged if compression is not applicable.
+* Returns a new Response with the compressed body, Content-Encoding, and Vary headers.
+*
+* The body is piped through a compression stream — no buffering of the full response.
+* This preserves streaming behavior for HTML shell + deferred Suspense chunks.
+*/
+function compressResponse(request, response) {
+	if (!shouldCompress(response)) return response;
+	const encoding = negotiateEncoding(request.headers.get("Accept-Encoding") ?? "");
+	if (!encoding) return response;
+	const compressedBody = compressWithGzip(response.body);
+	const headers = new Headers(response.headers);
+	headers.set("Content-Encoding", encoding);
+	headers.delete("Content-Length");
+	const existingVary = headers.get("Vary");
+	if (existingVary) {
+		if (!existingVary.toLowerCase().includes("accept-encoding")) headers.set("Vary", `${existingVary}, Accept-Encoding`);
+	} else headers.set("Vary", "Accept-Encoding");
+	return new Response(compressedBody, {
+		status: response.status,
+		statusText: response.statusText,
+		headers
+	});
+}
+/**
+* Compress a ReadableStream with gzip, flushing each chunk immediately.
+*
+* Uses node:zlib's createGzip with Z_SYNC_FLUSH to ensure each HTML chunk
+* (shell, Suspense resolution, RSC payload) is delivered to the browser
+* as soon as it's available — preserving streaming semantics.
+*/
+function compressWithGzip(body) {
+	const gzip = createGzip({ flush: constants.Z_SYNC_FLUSH });
+	const nodeInput = Readable.fromWeb(body);
+	pipeline(nodeInput, gzip, () => {});
+	return Readable.toWeb(gzip);
+}
+//#endregion
+//#region src/plugins/dev-server.ts
+var dev_server_exports = /* @__PURE__ */ __exportAll({
+	RESTART_EXIT_CODE: () => 75,
+	timberDevServer: () => timberDevServer,
+	toWebRequest: () => toWebRequest
+});
+var RSC_ENTRY_ID = "virtual:timber-rsc-entry";
+/**
+* Config file names that trigger a full dev server restart when changed.
+* See 21-dev-server.md §HMR Wiring — config is loaded once at startup.
+*/
+var CONFIG_FILE_NAMES = [
+	"timber.config.ts",
+	"timber.config.js",
+	"timber.config.mjs"
+];
+/**
+* URL prefixes that are Vite-internal and should never be intercepted.
+* These are passed through to Vite's built-in middleware.
+*/
+var VITE_INTERNAL_PREFIXES = [
+	"/@",
+	"/__vite",
+	"/node_modules/"
+];
+/**
+* File extensions that indicate static asset requests.
+* These are passed through to Vite's static file serving.
+*/
+var ASSET_EXTENSIONS = /\.(?:js|ts|tsx|jsx|css|map|json|svg|png|jpg|jpeg|gif|webp|avif|ico|woff|woff2|ttf|eot|mp4|webm|ogg|mp3|wav)(?:\?.*)?$/;
+/**
+* Create the timber-dev-server Vite plugin.
+*
+* Hook: configureServer (returns post-hook to register after Vite's middleware)
+*/
+function timberDevServer(ctx) {
+	let graphChannel = null;
+	return {
+		name: "timber-dev-server",
+		apply: "serve",
+		/**
+		* Push channel for the graph endpoint, phase 1: `invalidated`, one
+		* per (file, environment). Emitted from hotUpdate — which runs
+		* AFTER Vite invalidates the environment module graphs — never
+		* from a raw watcher listener, which would race consumers into
+		* querying pre-invalidation memberships (design/47 §"Dev-server
+		* endpoint").
+		*/
+		hotUpdate({ file, type }) {
+			graphChannel?.onHotUpdate({
+				file,
+				type,
+				environment: this.environment.name
+			});
+		},
+		/**
+		* Push channel phase 2: `transformed`, when a pending-invalidated
+		* module's import edges are actually rebuilt. A Set lookup for
+		* everything without a pending invalidation — free on the hot
+		* path. Returning nothing leaves the code untouched.
+		*/
+		transform(_code, id) {
+			graphChannel?.onTransform(id, this.environment.name);
+		},
+		/**
+		* Register the dev server middleware and config file watcher.
+		*
+		* Registers as a pre-hook (no return value) so our middleware runs
+		* before Vite's built-in SPA fallback / historyApiFallback. This
+		* ensures we see the original URL (e.g. /blog) rather than a
+		* rewritten /index.html. Vite-internal and asset requests are
+		* filtered out explicitly and passed through to Vite.
+		*/
+		async configureServer(server) {
+			const configPaths = CONFIG_FILE_NAMES.map((name) => join(ctx.root, name));
+			server.watcher.add(configPaths);
+			const configPathSet = new Set(configPaths);
+			const hasSupervisor = Boolean(process.env.__TIMBER_DEV_WORKER);
+			const onConfigChange = (filePath) => {
+				if (!configPathSet.has(filePath)) return;
+				if (hasSupervisor) {
+					console.log(`\n[timber] ${basename(filePath)} changed — restarting dev server...\n`);
+					process.exit(75);
+				} else {
+					console.log(`\n[timber] ${basename(filePath)} changed — restarting dev server...\n[timber] Run \`timber dev\` instead of \`vite dev\` for guaranteed fresh config on restart.\n`);
+					server.restart();
+				}
+			};
+			server.watcher.on("change", onConfigChange);
+			server.watcher.on("add", onConfigChange);
+			server.watcher.on("unlink", onConfigChange);
+			listenForClientErrors(server, ctx.root);
+			server.middlewares.use(createGraphEndpointMiddleware(server, ctx));
+			graphChannel = makeGraphUpdateChannel(ctx, (payload) => server.hot.send(payload), (file, environment) => {
+				const graph = server.environments[environment]?.moduleGraph;
+				if (!graph) return false;
+				const nodes = graph.getModulesByFile(file);
+				if (nodes) {
+					for (const node of nodes) if (node.transformResult != null) return true;
+					return false;
+				}
+				return graph.getModuleById(file)?.transformResult != null;
+			}, (file) => {
+				if (server.config?.resolve?.preserveSymlinks || file.includes("virtual:")) return file;
+				try {
+					return realpathSync(file);
+				} catch {
+					try {
+						return join(realpathSync(dirname(file)), basename(file));
+					} catch {
+						return file;
+					}
+				}
+			});
+			server.middlewares.use(createTimberMiddleware(server, ctx));
+			registerDevDiscovery(server.httpServer, ctx.root, server.config);
+			if (ctx.holdingServer) {
+				await ctx.holdingServer.close().catch(() => {});
+				ctx.holdingServer = null;
+			}
+			ctx.timer.end("dev-server-setup");
+			const summary = ctx.timer.formatSummary();
+			if (summary) console.log(summary);
+		}
+	};
+}
+/**
+* Create the Connect middleware that routes requests through the timber pipeline.
+*
+* For route requests (HTML pages, API endpoints), the middleware:
+* 1. Loads the RSC entry via ssrLoadModule
+* 2. Converts the Node request to a Web Request
+* 3. Passes it through the RSC handler (which runs the full pipeline)
+* 4. Converts the Web Response back to a Node response
+*
+* For non-route requests (assets, Vite internals, HMR), the middleware
+* calls next() to let Vite handle them.
+*/
+function createTimberMiddleware(server, ctx) {
+	const projectRoot = ctx.root;
+	const hmrOptions = extractHmrOptions(server.config);
+	const debugRegistry = new DebugChannelRegistry();
+	server.hot.on(DEBUG_SUBSCRIBE_EVENT, (data, client) => {
+		const msg = data;
+		if (msg?.id) debugRegistry.subscribe(msg.id, (event, payload) => {
+			client.send(event, payload);
+		});
+	});
+	return async (req, res, next) => {
+		const url = req.url;
+		if (!url) {
+			next();
+			return;
+		}
+		if (isViteInternal(url)) {
+			next();
+			return;
+		}
+		if (isPublicFile(server, url)) {
+			next();
+			return;
+		}
+		if (isAssetRequest(url) && !isMetadataRouteServePath(url) && !isRouteOwnedAsset(ctx.routeTree, server, url)) {
+			next();
+			return;
+		}
+		let handler;
+		try {
+			const rscEnv = server.environments.rsc;
+			if (!rscEnv?.runner?.import) throw new Error("[timber] RSC environment is not runnable");
+			const rscModule = await rscEnv.runner.import(RSC_ENTRY_ID);
+			handler = rscModule.default;
+			const config = rscModule.pipelineConfig;
+			if (config) {
+				config.devPipelineErrorHandler = (error, _phase, debugComponents) => {
+					sendErrorToOverlay(server, error, classifyErrorPhase(error, projectRoot), projectRoot, debugComponents);
+				};
+				config.devHmrOptions = hmrOptions;
+				config.devDebugRegistry = debugRegistry;
+			}
+			const setSourceMap = rscModule.setDevSourceMapHandler;
+			if (typeof setSourceMap === "function") setSourceMap((error) => {
+				fixErrorStacktrace(server, error);
+			});
+		} catch (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") {
+			console.error("[timber] RSC entry module does not export a default function");
+			next();
+			return;
+		}
+		try {
+			const webRequest = toWebRequest(req);
+			const wrapper = server[Symbol.for("timber:dev-request-wrapper")];
+			const finalResponse = compressResponse(webRequest, wrapper ? await wrapper(() => handler(webRequest)) : await handler(webRequest));
+			res.writeHead(finalResponse.status, [...finalResponse.headers].flat());
+			res.flushHeaders();
+			await sendNodeResponse(res, finalResponse);
+		} catch (error) {
+			if (error instanceof Error) {
+				const displayError = isSsrStreamError(error) && error.cause instanceof Error ? error.cause : error;
+				const phase = classifyErrorPhase(displayError, projectRoot);
+				sendErrorToOverlay(server, displayError, phase, projectRoot);
+				respond500(res, displayError, 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, 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/html; charset=utf-8");
+		res.end(html);
+		return;
+	} catch (e) {
+		console.debug("[timber] dev error page generation failed, falling back to text/plain:", e instanceof Error ? e.message : e);
+	}
+	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.
+*
+* Constructs the full URL from the Host header and request URL,
+* and forwards the method, headers, and body.
+*
+* The scheme comes from the socket's TLS state — with `server.https` the
+* browser sends `Origin: https://host`, and a hardcoded `http://` would
+* fail CSRF origin comparison on every POST. X-Forwarded-Proto is NOT
+* consulted: dev connections are direct, so the header would be
+* attacker-controlled. (TIM-1067, B32)
+*
+* Exported for tests.
+*/
+function toWebRequest(nodeReq) {
+	const protocol = nodeReq.socket?.encrypted ? "https" : "http";
+	const host = nodeReq.headers.host ?? nodeReq.headers[":authority"] ?? "localhost";
+	const url = `${protocol}://${host}${nodeReq.url}`;
+	const headers = new Headers();
+	for (const [key, value] of Object.entries(nodeReq.headers)) {
+		if (value === void 0) continue;
+		if (key.startsWith(":")) continue;
+		if (Array.isArray(value)) for (const v of value) headers.append(key, v);
+		else headers.set(key, value);
+	}
+	if (!headers.has("host")) headers.set("host", host);
+	const method = nodeReq.method ?? "GET";
+	const hasBody = method !== "GET" && method !== "HEAD";
+	return new Request(url, {
+		method,
+		headers,
+		body: hasBody ? nodeReadableToWebStream(nodeReq) : void 0,
+		duplex: hasBody ? "half" : void 0
+	});
+}
+/**
+* Convert a Node Readable stream to a Web ReadableStream.
+*/
+function nodeReadableToWebStream(nodeStream) {
+	return new ReadableStream({ start(controller) {
+		nodeStream.on("data", (chunk) => {
+			controller.enqueue(new Uint8Array(chunk));
+		});
+		nodeStream.on("end", () => {
+			controller.close();
+		});
+		nodeStream.on("error", (err) => {
+			controller.error(err);
+		});
+	} });
+}
+/**
+* Check if a URL is a Vite-internal request that should be passed through.
+*/
+function isViteInternal(url) {
+	return VITE_INTERNAL_PREFIXES.some((prefix) => url.startsWith(prefix));
+}
+/**
+* Check if a URL looks like a static asset request.
+*/
+function isAssetRequest(url) {
+	return ASSET_EXTENSIONS.test(url);
+}
+/**
+* Check if a URL maps to a real file in the project's public/ directory.
+* Vite serves public/ files as static assets — if a file exists there it
+* must be passed through to Vite regardless of extension.
+*/
+function isPublicFile(server, url) {
+	const { publicDir } = server.config;
+	if (!publicDir) return false;
+	const pathname = url.split("?")[0];
+	const relativePath = pathname.startsWith("/") ? pathname.slice(1) : pathname;
+	if (!relativePath) return false;
+	const fullPath = join(publicDir, relativePath);
+	try {
+		return statSync(fullPath).isFile();
+	} catch {
+		return false;
+	}
+}
+/**
+* Check whether an asset-extension URL belongs to a scanned route rather
+* than a static file.
+*
+* Route handlers may live at paths ending in asset-like extensions
+* (app/feed.json/route.ts → /feed.json), which the asset bypass would
+* otherwise hand to Vite — 404ing in dev while working in production.
+* Uses the same canonicalization and tree walker as the runtime matcher
+* so dev classification agrees with what the pipeline would match.
+*
+* A file that actually exists on disk wins over the route match: the
+* production server serves public/ statics before the RSC handler (see
+* adapters/nitro.ts), and Vite serves root-relative source files (e.g.
+* /app/global.css) in dev. Without this, a broad catch-all route like
+* app/[...slug] would shadow every static asset. Joining the canonical
+* pathname is traversal-safe — canonicalize() resolves `..` segments and
+* rejects root escapes and encoded separators.
+*
+* Reads ctx.routeTree per request — the routing plugin rescans it on
+* file add/unlink/change, so newly created routes are picked up live.
+*/
+function isRouteOwnedAsset(routeTree, server, url) {
+	if (!routeTree) return false;
+	const rawPathname = url.split("?")[0];
+	const result = canonicalize(rawPathname);
+	if (!result.ok) return false;
+	const parts = result.pathname === "/" ? [] : result.pathname.slice(1).split("/");
+	if (matchUrlParts(routeTree.root, parts) === null) return false;
+	const relativePath = result.pathname.slice(1);
+	const { publicDir, root } = server.config;
+	if (publicDir && existsSync(join(publicDir, relativePath))) return false;
+	if (existsSync(join(root, relativePath))) return false;
+	return true;
+}
+/**
+* Listen for client-side errors forwarded from the browser via HMR.
+*
+* The browser entry catches uncaught errors and unhandled rejections,
+* then sends them as 'timber:client-error' custom events. We parse
+* the first app frame for the overlay's loc field and forward the
+* error to Vite's overlay protocol.
+*/
+function listenForClientErrors(server, projectRoot) {
+	server.hot.on("timber:client-error", (data) => {
+		const loc = parseFirstAppFrame(data.stack, projectRoot);
+		let message = data.message;
+		if (data.componentStack) message = `${data.message}\n\nComponent Stack:\n${data.componentStack.trim()}`;
+		const RED = "\x1B[31m";
+		const BOLD = "\x1B[1m";
+		const RESET = "\x1B[0m";
+		process.stderr.write(`${RED}${BOLD}[timber] Client Error${RESET}\n${RED}${data.message}${RESET}\n\n`);
+		try {
+			server.hot.send({
+				type: "error",
+				err: {
+					message,
+					stack: data.stack,
+					id: loc?.file,
+					plugin: "timber (Client)",
+					loc: loc ? {
+						file: loc.file,
+						line: loc.line,
+						column: loc.column
+					} : void 0
+				}
+			});
+		} catch (e) {
+			console.debug("[timber] overlay send failed:", e instanceof Error ? e.message : e);
+		}
+	});
+}
+//#endregion
+export { formatMissingPeers as a, formatConfigErrors as i, timberDevServer as n, validateConfig as o, checkPeerDependencies as r, dev_server_exports as t };
+
+//# sourceMappingURL=dev-server-DioP7tkQ.js.map