@timber-js/app 0.2.0-alpha.97 → 0.2.0-alpha.99

package/dist/index.js

@@ -1,7 +1,8 @@
 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-BbqMCVXa.js";
-import { t as formatSize } from "./_chunks/format-CYBGxKtc.js";
+import { n as setViteServer } from "./_chunks/warnings-Cg47l5sk.js";
+import { h as swallow } from "./_chunks/logger-0m8MsKdc.js";
+import { i as scanRoutes, n as collectInterceptionRewrites, r as generateRouteMap, t as collectLeafRoutes } from "./_chunks/walkers-Tg0Alwcg.js";
+import { t as formatSize } from "./_chunks/format-Bcn-Iv1x.js";
 import { dirname, extname, join, normalize, resolve } from "node:path";
 import { createRequire } from "node:module";
 import react, { reactCompilerPreset } from "@vitejs/plugin-react";
@@ -98,7 +99,60 @@ function timberContent(ctx) {
 	};
 }
 //#endregion
-//#region src/plugins/dev-terminal-error.ts
+//#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.
 *
@@ -165,35 +219,6 @@ function box(lines, borderColor, width = 80) {
 	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.
 *
@@ -208,7 +233,7 @@ 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 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 = [];
@@ -247,7 +272,7 @@ function extractFnName(frameLine) {
 	return match ? match[1] : "";
 }
 //#endregion
-//#region src/plugins/dev-error-overlay.ts
+//#region src/dev-tools/overlay.ts
 var _traceMapping = null;
 /**
 * Lazy-load @jridgewell/trace-mapping from Vite's dependency tree.
@@ -269,21 +294,6 @@ var PHASE_LABELS$1 = {
 	"handler": "Route Handler"
 };
 /**
-* Classify a 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";
-}
-/**
 * Extract the React component stack from an error, if present.
 * React attaches this as `componentStack` during renderToReadableStream errors.
 */
@@ -528,7 +538,24 @@ function sendErrorToOverlay(server, error, phase, projectRoot, rscDebugComponent
 	} catch {}
 }
 //#endregion
-//#region src/plugins/dev-error-page.ts
+//#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/error-page.ts
 /**
 * Dev error page — self-contained HTML error page for dev server 500s.
 *
@@ -560,12 +587,6 @@ var PHASE_HINTS = {
 	"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).
@@ -588,9 +609,7 @@ function readSourceContext(filePath, line, contextLines = 3) {
 		return null;
 	}
 }
-function esc(str) {
-	return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
-}
+var esc = escapeHtml;
 /**
 * Escape a JSON string for safe embedding in an HTML `<script>` block.
 *
@@ -12392,10 +12411,6 @@ var require_acorn = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 * avoiding false positives from regex matching inside string literals,
 * comments, or template expressions.
 *
-* The function-body directive detection (findFunctionsWithDirective) is a
-* general-purpose utility kept for future use. Custom directives like
-* 'use cache' are not currently implemented — see design/06-caching.md.
-*
 * @module
 */
 var import_acorn_jsx = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin(((exports, module) => {
@@ -12850,17 +12865,18 @@ function lintStatusFileDirectives(tree) {
 }
 function walkNode(node, warnings) {
 	if (node.error) checkFile(node.error.filePath, node.error.extension, "error", warnings);
-	if (node.statusFiles) for (const [code, file] of node.statusFiles) checkFile(file.filePath, file.extension, code, warnings);
-	if (node.legacyStatusFiles) for (const [name, file] of node.legacyStatusFiles) checkFile(file.filePath, file.extension, name, warnings);
+	if (node.statusFiles) for (const [code, file] of Object.entries(node.statusFiles)) checkFile(file.filePath, file.extension, code, warnings);
+	if (node.legacyStatusFiles) for (const [name, file] of Object.entries(node.legacyStatusFiles)) checkFile(file.filePath, file.extension, name, warnings);
 	for (const child of node.children) walkNode(child, warnings);
-	for (const [, slotNode] of node.slots) walkNode(slotNode, warnings);
+	for (const slotNode of Object.values(node.slots)) walkNode(slotNode, warnings);
 }
 function checkFile(filePath, extension, fileType, warnings) {
 	if (!CLIENT_REQUIRED_EXTENSIONS.has(extension)) return;
 	let code;
 	try {
 		code = readFileSync(filePath, "utf-8");
-	} catch {
+	} catch (err) {
+		swallow(err, `status-file-lint: unreadable file ${filePath}`);
 		return;
 	}
 	if (!detectFileDirective(code, ["use client"])) warnings.push({
@@ -12935,7 +12951,7 @@ function checkEmptyApp(root, appDir, warnings) {
 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;
+	for (const slot of Object.values(node.slots)) if (hasAnyRoutable(slot)) return true;
 	return false;
 }
 /**
@@ -12946,7 +12962,7 @@ function hasAnyRoutable(node) {
 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;
+	for (const slot of Object.values(node.slots)) if (hasAnyPage(slot)) return true;
 	return false;
 }
 /** HTTP methods that route.ts can export. */
@@ -12992,10 +13008,12 @@ function checkRouteExports(node, warnings) {
 					level: "warn"
 				});
 			}
-		} catch {}
+		} catch (err) {
+			swallow(err, `convention-lint: unreadable route.ts ${filePath}`);
+		}
 	}
 	for (const child of node.children) checkRouteExports(child, warnings);
-	for (const [, slot] of node.slots) checkRouteExports(slot, warnings);
+	for (const slot of Object.values(node.slots)) checkRouteExports(slot, warnings);
 }
 /**
 * Warn when the root segment has no layout.tsx.
@@ -13036,7 +13054,7 @@ 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);
+	for (const slot of Object.values(node.slots)) checkDefaultExports(slot, warnings);
 }
 function isScriptExtension(ext) {
 	return ext === "tsx" || ext === "ts" || ext === "jsx" || ext === "js";
@@ -13050,7 +13068,9 @@ function checkFileDefaultExport(filePath, fileType, warnings) {
 			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 {}
+	} catch (err) {
+		swallow(err, `convention-lint: unreadable ${fileType} file ${filePath}`);
+	}
 }
 /**
 * Check if the app/ directory exists. Called before scanning.
@@ -13169,7 +13189,7 @@ function timberRouting(ctx) {
 				segmentType: "static",
 				urlPath: "/",
 				children: [],
-				slots: /* @__PURE__ */ new Map()
+				slots: {}
 			} };
 			return;
 		}
@@ -13293,7 +13313,7 @@ function generateSearchParamsRegistryModule(tree) {
 			});
 		}
 		for (const child of node.children) walk(child);
-		for (const [, slot] of node.slots) walk(slot);
+		for (const slot of Object.values(node.slots)) walk(slot);
 	}
 	walk(tree.root);
 	entries.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
@@ -13395,33 +13415,33 @@ function generateManifestModule(tree, viteRoot) {
 			const v = addImport(node.params);
 			parts.push(`${nextIndent}params: { load: ${v}, filePath: ${JSON.stringify(node.params.filePath)} },`);
 		}
-		if (node.statusFiles && node.statusFiles.size > 0) {
+		if (node.statusFiles && Object.keys(node.statusFiles).length > 0) {
 			const statusEntries = [];
-			for (const [code, file] of node.statusFiles) {
+			for (const [code, file] of Object.entries(node.statusFiles)) {
 				const v = addImport(file);
 				statusEntries.push(`${nextIndent}    ${JSON.stringify(code)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`);
 			}
 			parts.push(`${nextIndent}statusFiles: {\n${statusEntries.join(",\n")}\n${nextIndent}},`);
 		}
-		if (node.jsonStatusFiles && node.jsonStatusFiles.size > 0) {
+		if (node.jsonStatusFiles && Object.keys(node.jsonStatusFiles).length > 0) {
 			const jsonEntries = [];
-			for (const [code, file] of node.jsonStatusFiles) {
+			for (const [code, file] of Object.entries(node.jsonStatusFiles)) {
 				const v = addImport(file);
 				jsonEntries.push(`${nextIndent}    ${JSON.stringify(code)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`);
 			}
 			parts.push(`${nextIndent}jsonStatusFiles: {\n${jsonEntries.join(",\n")}\n${nextIndent}},`);
 		}
-		if (node.legacyStatusFiles && node.legacyStatusFiles.size > 0) {
+		if (node.legacyStatusFiles && Object.keys(node.legacyStatusFiles).length > 0) {
 			const legacyEntries = [];
-			for (const [name, file] of node.legacyStatusFiles) {
+			for (const [name, file] of Object.entries(node.legacyStatusFiles)) {
 				const v = addImport(file);
 				legacyEntries.push(`${nextIndent}    ${JSON.stringify(name)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`);
 			}
 			parts.push(`${nextIndent}legacyStatusFiles: {\n${legacyEntries.join(",\n")}\n${nextIndent}},`);
 		}
-		if (node.metadataRoutes && node.metadataRoutes.size > 0) {
+		if (node.metadataRoutes && Object.keys(node.metadataRoutes).length > 0) {
 			const metaEntries = [];
-			for (const [name, file] of node.metadataRoutes) {
+			for (const [name, file] of Object.entries(node.metadataRoutes)) {
 				const v = addImport(file);
 				metaEntries.push(`${nextIndent}    ${JSON.stringify(name)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`);
 			}
@@ -13431,9 +13451,13 @@ function generateManifestModule(tree, viteRoot) {
 			const childNodes = node.children.map((c) => serializeNode(c, nextIndent));
 			parts.push(`${nextIndent}children: [\n${childNodes.join(",\n")}\n${nextIndent}],`);
 		} else parts.push(`${nextIndent}children: [],`);
-		if (node.slots.size > 0) {
+		const slotKeys = Object.keys(node.slots);
+		if (slotKeys.length > 0) {
 			const slotEntries = [];
-			for (const [slotName, slotNode] of node.slots) slotEntries.push(`${nextIndent}    ${JSON.stringify(slotName)}: ${serializeNode(slotNode, nextIndent + "  ")}`);
+			for (const slotName of slotKeys) {
+				const slotNode = node.slots[slotName];
+				slotEntries.push(`${nextIndent}    ${JSON.stringify(slotName)}: ${serializeNode(slotNode, nextIndent + "  ")}`);
+			}
 			parts.push(`${nextIndent}slots: {\n${slotEntries.join(",\n")}\n${nextIndent}},`);
 		} else parts.push(`${nextIndent}slots: {},`);
 		return `${indent}{\n${parts.join("\n")}\n${indent}}`;
@@ -13590,7 +13614,7 @@ export const headers = stub;
 export const cookies = stub;
 export const getHeaders = stub;
 export const getHeader = stub;
-export const getCookies = stub;
+export const getCookieJar = stub;
 export const getCookie = stub;
 export const getSearchParams = stub;
 export const getSegmentParams = stub;
@@ -15214,8 +15238,8 @@ function timberFonts(ctx) {
 */
 var DYNAMIC_API_PATTERNS = [
 	{
-		pattern: /\bgetCookies\s*\(/,
-		name: "getCookies()"
+		pattern: /\bgetCookieJar\s*\(/,
+		name: "getCookieJar()"
 	},
 	{
 		pattern: /\bgetHeaders\s*\(/,
@@ -15592,7 +15616,7 @@ function timberBuildManifest(ctx) {
 	};
 }
 //#endregion
-//#region src/plugins/dev-logs.ts
+//#region src/dev-tools/logs.ts
 var LOG_LEVELS = [
 	"log",
 	"warn",
@@ -15671,7 +15695,7 @@ function extractCallerLocation(projectRoot) {
 	const lines = stack.split("\n");
 	for (let i = 1; i < lines.length; i++) {
 		const line = lines[i].trim();
-		if (line.includes("dev-logs")) continue;
+		if (line.includes("dev-tools/logs")) continue;
 		if (line.includes("node:") || line.includes("node_modules")) continue;
 		const match = line.match(/\((.+?):(\d+):(\d+)\)/) ?? line.match(/at (.+?):(\d+):(\d+)/);
 		if (match) {
@@ -15699,7 +15723,7 @@ function isFrameworkInternalCaller() {
 	const lines = stack.split("\n");
 	for (let i = 1; i < lines.length; i++) {
 		const line = lines[i].trim();
-		if (line.includes("dev-logs")) continue;
+		if (line.includes("dev-tools/logs")) continue;
 		if (line.includes("node:")) continue;
 		if (!(line.includes("timber-app/") || line.includes("@timber-js/app/"))) return false;
 		return line.includes("/plugins/") || line.includes("/adapters/");
@@ -15757,7 +15781,7 @@ function timberDevLogs(_ctx) {
 	};
 }
 //#endregion
-//#region src/plugins/dev-browser-logs.ts
+//#region src/dev-tools/browser-logs.ts
 /** Max message size in bytes before truncation. */
 var MAX_MESSAGE_BYTES = 2048;
 /** HMR event name for browser→server log forwarding. */
@@ -16163,7 +16187,8 @@ async function stripJsFromRscAssetsManifests(buildDir) {
 		let manifest;
 		try {
 			manifest = JSON.parse(jsonStr);
-		} catch {
+		} catch (err) {
+			swallow(err, `corrupted RSC assets manifest: ${path}`, { level: "warn" });
 			continue;
 		}
 		const deps = manifest.clientReferenceDeps;
@@ -16211,32 +16236,22 @@ function green(text) {
 /**
 * Walk the route tree and collect all leaf routes (pages + API endpoints).
 *
-* Parallel slots (`@artists`, `@shows`, etc.) are intentionally skipped —
-* they render alongside the parent page at the same URL and are not
-* separately URL-addressable. Their JS is captured in shared/layout chunks.
+* Wraps the shared `collectLeafRoutes` walker (TIM-848). Parallel slots
+* (`@artists`, `@shows`, etc.) are intentionally skipped — they render
+* alongside the parent page at the same URL and are not separately
+* URL-addressable. Their JS is captured in shared/layout chunks.
 *
 * After collection, entries are deduplicated by URL path so that overlapping
 * route groups (e.g. `(browse)` and `(marketing)` both producing `/`) only
-* appear once. The entry with the largest route-specific size wins.
+* appear once. The entry with the longest segment chain (most specific
+* match) wins.
 */
 function collectRoutes(tree) {
-	const routes = [];
-	function walk(node, chain) {
-		const currentChain = [...chain, node];
-		const path = node.urlPath || "/";
-		if (node.page) routes.push({
-			path,
-			segments: currentChain,
-			entryFilePath: node.page.filePath
-		});
-		if (node.route) routes.push({
-			path,
-			segments: currentChain,
-			entryFilePath: node.route.filePath
-		});
-		for (const child of node.children) walk(child, currentChain);
-	}
-	walk(tree.root, []);
+	const routes = collectLeafRoutes(tree.root).map((leaf) => ({
+		path: leaf.urlPath,
+		segments: leaf.segments,
+		entryFilePath: leaf.page?.filePath ?? leaf.route?.filePath ?? null
+	}));
 	const seen = /* @__PURE__ */ new Map();
 	for (const route of routes) {
 		const existing = seen.get(route.path);
@@ -16544,7 +16559,7 @@ function validateKeyFormat(key) {
 	}
 }
 //#endregion
-//#region src/server/dev-holding-server.ts
+//#region src/dev-tools/holding-server.ts
 /**
 * Dev holding server — serves a loading page while Vite initializes.
 *
@@ -16645,9 +16660,11 @@ var HOLDING_PAGE_HTML = [
 *
 * Usage (inside Vite plugin):
 * ```ts
-* // In config() hook — earliest point where port is known
+* // In config() hook — earliest point where port is known.
+* // Use bindWithBump() to honor the default-3000 + auto-bump policy
+* // (see ../server/port-resolution.ts and TIM-842).
 * const holding = createHoldingServer();
-* holding.listen(config.server?.port ?? 5173);
+* await bindWithBump((p) => holding.listen(p), { startPort: 3000, autoBump: true });
 *
 * // In last plugin's configureServer() — wrap listen for seamless handoff
 * const originalListen = server.listen.bind(server);
@@ -16701,6 +16718,122 @@ function createHoldingServer() {
 	};
 }
 //#endregion
+//#region src/server/port-resolution.ts
+/**
+* Port resolution for the dev server, Vite preview, and the Node
+* production preview server.
+*
+* Behavior (see TIM-842):
+*
+*   1. Default port is **3000** for both dev and prod.
+*   2. If the user did NOT set an explicit port, auto-bump from 3000
+*      until a free port is found (3000 → 3001 → 3002 → …).
+*   3. If the user DID set an explicit port (via `--port`, `PORT` env
+*      var, or `vite.config.ts` `server.port`), use it as-is and let
+*      the bind fail loudly on conflict (`strictPort: true`).
+*
+* The port-bump probe is performed by binding the **actual** server
+* (e.g. the dev holding server) — not a throwaway probe — so there is
+* no time-of-check / time-of-use race between probing and listening.
+*
+* Design doc: 21-dev-server.md §"Default Port and Auto-Bump".
+*/
+/** Default port used by `timber dev` and `timber preview`. */
+var DEFAULT_PORT = 3e3;
+/**
+* Pure: compute the starting port from config / env / defaults.
+*
+* Performs no I/O — pair with {@link bindWithBump} to actually listen.
+*/
+function resolveStartPort(input) {
+	const defaultPort = input.defaultPort ?? 3e3;
+	if (typeof input.configPort === "number" && Number.isFinite(input.configPort)) return {
+		port: input.configPort,
+		explicit: true
+	};
+	if (input.envPort != null && input.envPort !== "") {
+		const parsed = Number(input.envPort);
+		if (Number.isFinite(parsed) && parsed > 0) return {
+			port: parsed,
+			explicit: true
+		};
+	}
+	return {
+		port: defaultPort,
+		explicit: false
+	};
+}
+/**
+* Bind a server starting at `startPort`, optionally bumping the port
+* on `EADDRINUSE` until a free one is found.
+*
+* Use this with the actual server you intend to keep listening (e.g.
+* the dev holding server). Pairing the probe with the real listen
+* eliminates the TOCTOU race that a throwaway probe would introduce.
+*/
+async function bindWithBump(listen, options) {
+	const maxAttempts = options.autoBump ? options.maxAttempts ?? 100 : 1;
+	let lastErr = null;
+	for (let i = 0; i < maxAttempts; i++) {
+		const port = options.startPort + i;
+		try {
+			return {
+				port: await listen(port),
+				bumped: i > 0
+			};
+		} catch (err) {
+			lastErr = err;
+			if (!isAddrInUse(err)) throw err;
+		}
+	}
+	throw lastErr ?? /* @__PURE__ */ new Error(`Could not bind to a free port starting at ${options.startPort}`);
+}
+/** True if `err` is a Node `EADDRINUSE` error from `server.listen()`. */
+function isAddrInUse(err) {
+	return typeof err === "object" && err !== null && err.code === "EADDRINUSE";
+}
+/**
+* Run the full dev-server port resolution + holding-server bind sequence.
+*
+* Resolves the port from config / env / default, attempts to bind the
+* holding server (auto-bumping when the port came from the default),
+* and logs the chosen URL. On a clean failure for an explicit port, it
+* warns and falls back to the requested port so Vite can surface the
+* conflict via `strictPort: true`.
+*
+* Extracted from `index.ts` so the rootSync `config()` hook stays
+* focused on plugin assembly.
+*/
+async function startDevServerPort(input) {
+	const log = input.log ?? ((msg) => console.log(msg));
+	const warn = input.warn ?? ((msg) => console.warn(msg));
+	const start = resolveStartPort({
+		configPort: input.configPort,
+		envPort: input.envPort,
+		defaultPort: DEFAULT_PORT
+	});
+	try {
+		const result = await bindWithBump(input.listen, {
+			startPort: start.port,
+			autoBump: !start.explicit
+		});
+		if (result.bumped) log(`\n  \x1b[33m[timber]\x1b[0m Port ${start.port} in use, using ${result.port}\n`);
+		log(`\n  \x1b[2m\u{1FAB5} timber.js dev server starting at\x1b[0m \x1b[36mhttp://localhost:${result.port}\x1b[0m\n`);
+		return {
+			port: result.port,
+			explicit: start.explicit,
+			bound: true
+		};
+	} catch (err) {
+		if (start.explicit && isAddrInUse(err)) warn(`\n  \x1b[33m[timber]\x1b[0m Port ${start.port} is already in use. Set PORT (or remove the override) to pick another port.\n`);
+		return {
+			port: start.port,
+			explicit: start.explicit,
+			bound: false
+		};
+	}
+}
+//#endregion
 //#region src/plugin-context.ts
 /**
 * Plugin context — internal types and helpers for timber sub-plugins.
@@ -16942,7 +17075,7 @@ function timber(config) {
 	const earlyFileConfig = loadTimberConfigFile(process.cwd());
 	const rootSync = {
 		name: "timber-root-sync",
-		config(userConfig, { command }) {
+		async config(userConfig, { command, isPreview }) {
 			const viteRoot = resolve(userConfig.root ?? process.cwd());
 			ctx.timer.start("config-load");
 			const fileConfig = loadTimberConfigFile(viteRoot);
@@ -16960,19 +17093,26 @@ function timber(config) {
 				const hadCompilerInEarly = !config?.reactCompiler && earlyFileConfig?.reactCompiler;
 				if (hasCompilerInReloaded && !hadCompilerInEarly) console.warn("[timber] reactCompiler is set in timber.config.ts but could not be registered because the config file is in a non-cwd root directory. Move reactCompiler to the inline timber() config in vite.config.ts, or run vite from the project root directory.");
 			}
-			if (command === "serve") {
-				const port = userConfig.server?.port ?? 5173;
-				try {
-					ctx.holdingServer = createHoldingServer();
-					ctx.holdingServer.listen(port).then((boundPort) => {
-						const url = `http://localhost:${boundPort}`;
-						console.log(`\n  \x1b[2m🪵 timber.js dev server starting at\x1b[0m \x1b[36m${url}\x1b[0m\n`);
-					}, () => {
-						ctx.holdingServer = null;
-					});
-				} catch {
-					ctx.holdingServer = null;
-				}
+			let resolvedDevPort = null;
+			let resolvedDevPortExplicit = false;
+			if (command === "serve" && !isPreview) {
+				ctx.holdingServer = createHoldingServer();
+				const holdingRef = ctx.holdingServer;
+				const result = await startDevServerPort({
+					configPort: typeof userConfig.server?.port === "number" ? userConfig.server.port : void 0,
+					envPort: process.env.PORT,
+					listen: (p) => holdingRef.listen(p)
+				});
+				resolvedDevPort = result.port;
+				resolvedDevPortExplicit = result.explicit;
+				if (!result.bound) ctx.holdingServer = null;
+			} else if (command === "serve" && isPreview) {
+				const start = resolveStartPort({
+					configPort: typeof userConfig.preview?.port === "number" ? userConfig.preview.port : typeof userConfig.server?.port === "number" ? userConfig.server.port : void 0,
+					envPort: process.env.PORT
+				});
+				resolvedDevPort = start.port;
+				resolvedDevPortExplicit = start.explicit;
 			}
 			const buildOutDir = timberBuildDir ? timberBuildDir : viteOutDir && viteOutDir !== "dist" ? viteOutDir : DEFAULT_BUILD_DIR;
 			const envOutDirs = {};
@@ -16986,9 +17126,21 @@ function timber(config) {
 				environments: envOutDirs,
 				oxc: { jsx: { development: false } }
 			};
+			const serverConfig = {};
+			const previewConfig = {};
+			if (resolvedDevPort != null) {
+				if (!isPreview) {
+					serverConfig.port = resolvedDevPort;
+					serverConfig.strictPort = true;
+				}
+				previewConfig.port = resolvedDevPort;
+				previewConfig.strictPort = resolvedDevPortExplicit;
+			}
 			return {
 				build: { outDir: buildOutDir },
-				environments: envOutDirs
+				environments: envOutDirs,
+				server: serverConfig,
+				preview: previewConfig
 			};
 		},
 		configResolved(resolved) {