@timber-js/app 0.2.0-alpha.4 → 0.2.0-alpha.40

package/dist/index.js

@@ -1,37 +1,16 @@
-import { r as setViteServer, t as formatSize } from "./_chunks/format-CwdaB0_2.js";
-import { i as scanRoutes, n as generateRouteMap, t as collectInterceptionRewrites } from "./_chunks/interception-BOoWmLUA.js";
+import { r as __toESM, t as __commonJSMin } from "./_chunks/chunk-DYhsFzuS.js";
+import { r as setViteServer, t as formatSize } from "./_chunks/format-cX7wzEp2.js";
+import { i as scanRoutes, n as generateRouteMap, t as collectInterceptionRewrites } from "./_chunks/interception-D2djYaIm.js";
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, extname, join, resolve } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { dirname, extname, join, normalize, resolve } from "node:path";
 import { createRequire } from "node:module";
-import react from "@vitejs/plugin-react";
+import react, { reactCompilerPreset } from "@vitejs/plugin-react";
+import { constants, createGzip, gzipSync } from "node:zlib";
+import { Readable } from "node:stream";
+import { fileURLToPath } from "node:url";
 import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
-import { createHash } from "node:crypto";
-import { gzipSync } from "node:zlib";
+import { createHash, randomUUID } from "node:crypto";
 import { performance as performance$1 } from "node:perf_hooks";
-//#region \0rolldown/runtime.js
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __commonJSMin = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
-var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-		key = keys[i];
-		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
-			get: ((k) => from[k]).bind(null, key),
-			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-		});
-	}
-	return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
-	value: mod,
-	enumerable: true
-}) : target, mod));
-//#endregion
 //#region ../../node_modules/.pnpm/acorn@8.16.0/node_modules/acorn/dist/acorn.mjs
 var astralIdentifierCodes = [
 	509,
@@ -11486,14 +11465,51 @@ function formatTerminalError(error, phase, projectRoot) {
 	return lines.join("\n");
 }
 /**
+* 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");
+}
+/**
 * 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) {
+function sendErrorToOverlay(server, error, phase, projectRoot, rscDebugComponents) {
 	server.ssrFixStacktrace(error);
 	const formatted = formatTerminalError(error, phase, projectRoot);
 	process.stderr.write(`${formatted}\n`);
@@ -11501,6 +11517,8 @@ function sendErrorToOverlay(server, error, phase, 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",
@@ -11624,12 +11642,16 @@ function compressResponse(request, response) {
 	});
 }
 /**
-* Compress a ReadableStream with gzip using the Web Platform CompressionStream API.
-* Available in Node 18+, Bun, and Deno — no npm dependency needed.
+* 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 compressionStream = new CompressionStream("gzip");
-	return body.pipeThrough(compressionStream);
+	const gzip = createGzip({ flush: constants.Z_SYNC_FLUSH });
+	Readable.fromWeb(body).pipe(gzip);
+	return Readable.toWeb(gzip);
 }
 //#endregion
 //#region src/plugins/dev-server.ts
@@ -11714,8 +11736,8 @@ function createTimberMiddleware(server, projectRoot) {
 			const rscModule = await rscEnv.runner.import(RSC_ENTRY_ID);
 			handler = rscModule.default;
 			const setHandler = rscModule.setDevPipelineErrorHandler;
-			if (typeof setHandler === "function") setHandler((error) => {
-				sendErrorToOverlay(server, error, classifyErrorPhase(error, projectRoot), projectRoot);
+			if (typeof setHandler === "function") setHandler((error, _phase, debugComponents) => {
+				sendErrorToOverlay(server, error, classifyErrorPhase(error, projectRoot), projectRoot, debugComponents);
 			});
 		} catch (error) {
 			if (error instanceof Error) sendErrorToOverlay(server, error, "module-transform", projectRoot);
@@ -11804,15 +11826,24 @@ async function sendWebResponse(nodeRes, webResponse) {
 	}
 	nodeRes.flushHeaders();
 	const reader = webResponse.body.getReader();
+	let clientDisconnected = false;
+	const onClose = () => {
+		clientDisconnected = true;
+		reader.cancel("Client disconnected").catch(() => {});
+	};
+	nodeRes.on("close", onClose);
 	try {
 		while (true) {
 			const { done, value } = await reader.read();
 			if (done) break;
 			nodeRes.write(value);
 		}
+	} catch (err) {
+		if (!clientDisconnected) throw err;
 	} finally {
+		nodeRes.off("close", onClose);
 		reader.releaseLock();
-		nodeRes.end();
+		if (!nodeRes.writableEnded) nodeRes.end();
 	}
 }
 /**
@@ -11923,7 +11954,6 @@ function stripRootPrefix(id, root) {
 * Serializes output mode and feature flags for runtime consumption.
 */
 function generateConfigModule(ctx) {
-	const cookieSecrets = ctx.config.cookies?.secrets ?? (ctx.config.cookies?.secret ? [ctx.config.cookies.secret] : void 0);
 	const runtimeConfig = {
 		output: ctx.config.output ?? "server",
 		csrf: ctx.config.csrf ?? true,
@@ -11932,10 +11962,11 @@ function generateConfigModule(ctx) {
 		dev: ctx.dev ?? false,
 		slowPhaseMs: ctx.config.dev?.slowPhaseMs ?? 200,
 		slowRequestMs: ctx.config.slowRequestMs ?? 3e3,
-		cookieSecrets,
 		topLoader: ctx.config.topLoader,
-		responseCache: ctx.config.responseCache,
-		debug: ctx.config.debug ?? false
+		debug: ctx.config.debug ?? false,
+		serverTiming: ctx.config.serverTiming,
+		renderTimeoutMs: ctx.config.renderTimeoutMs ?? 3e4,
+		deploymentId: ctx.deploymentId ?? null
 	};
 	return [
 		"// Auto-generated runtime config — do not edit.",
@@ -11953,12 +11984,14 @@ function generateConfigModule(ctx) {
 * extensions as timber.config.ts detection.
 */
 function detectInstrumentationFile(root) {
-	for (const ext of [
+	const extensions = [
 		".ts",
 		".js",
 		".mjs"
-	]) {
-		const candidate = resolve(root, `instrumentation${ext}`);
+	];
+	const dirs = [root, resolve(root, "src")];
+	for (const dir of dirs) for (const ext of extensions) {
+		const candidate = resolve(dir, `instrumentation${ext}`);
 		if (existsSync(candidate)) return candidate;
 	}
 	return null;
@@ -12018,17 +12051,20 @@ function timberEntries(ctx) {
 //#region src/plugins/mdx.ts
 var MDX_EXTENSIONS = ["mdx", "md"];
 /**
-* Check if mdx-components.tsx (or .ts, .jsx, .js) exists at the project root.
+* Check if mdx-components.tsx (or .ts, .jsx, .js) exists at the project root
+* or in src/. Root takes precedence, matching Next.js behavior.
 * Returns the absolute path if found, otherwise undefined.
 */
 function findMdxComponents(root) {
-	for (const name of [
+	const candidates = [
 		"mdx-components.tsx",
 		"mdx-components.ts",
 		"mdx-components.jsx",
 		"mdx-components.js"
-	]) {
-		const p = join(root, name);
+	];
+	const dirs = [root, join(root, "src")];
+	for (const dir of dirs) for (const name of candidates) {
+		const p = join(dir, name);
 		if (existsSync(p)) return p;
 	}
 }
@@ -12153,7 +12189,8 @@ var CLIENT_REQUIRED_EXTENSIONS = new Set([
 * that are missing it.
 *
 * MDX and JSON status files are excluded — MDX files are server components
-* by design, and JSON files are data, not components.
+* by design (pre-rendered as elements via fallbackElement, see TIM-503),
+* and JSON files are data, not components.
 */
 function lintStatusFileDirectives(tree) {
 	const warnings = [];
@@ -12198,7 +12235,7 @@ var RESOLVED_VIRTUAL_ID$1 = `\0${VIRTUAL_MODULE_ID$1}`;
 /**
 * File convention names we track for changes that require manifest regeneration.
 */
-var ROUTE_FILE_PATTERNS = /\/(page|layout|middleware|access|route|error|default|denied|search-params|\d{3}|[45]xx|not-found|forbidden|unauthorized|sitemap|robots|manifest|favicon|icon|opengraph-image|twitter-image|apple-icon)\./;
+var ROUTE_FILE_PATTERNS = /\/(page|layout|middleware|access|route|error|default|denied|\d{3}|[45]xx|not-found|forbidden|unauthorized|sitemap|robots|manifest|favicon|icon|opengraph-image|twitter-image|apple-icon)\./;
 /**
 * Create the timber-routing Vite plugin.
 *
@@ -12273,14 +12310,40 @@ function timberRouting(ctx) {
 		configureServer(devServer) {
 			rescan();
 			devServer.watcher.add(ctx.appDir);
-			const handleFileChange = (filePath) => {
+			/** Snapshot of the last generated manifest, used to detect structural changes. */
+			let lastManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree) : "";
+			/**
+			* Handle a route-significant file being added or removed.
+			* Always triggers a full-reload since the route tree structure changed.
+			*/
+			const handleStructuralChange = (filePath) => {
 				if (!filePath.startsWith(ctx.appDir)) return;
 				if (!ROUTE_FILE_PATTERNS.test(filePath)) return;
 				rescan();
+				lastManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree) : "";
 				invalidateManifest(devServer);
 			};
-			devServer.watcher.on("add", handleFileChange);
-			devServer.watcher.on("unlink", handleFileChange);
+			/**
+			* Handle a route file's content changing.
+			*
+			* Most content edits (JSX changes, fixing typos) don't affect route
+			* metadata — Vite's React Fast Refresh handles those via normal HMR.
+			* Only rescan and full-reload when route metadata actually changed
+			* (e.g., searchParams export added/removed, metadata export changed).
+			*/
+			const handleContentChange = (filePath) => {
+				if (!filePath.startsWith(ctx.appDir)) return;
+				if (!ROUTE_FILE_PATTERNS.test(filePath)) return;
+				rescan();
+				const newManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree) : "";
+				if (newManifest !== lastManifest) {
+					lastManifest = newManifest;
+					invalidateManifest(devServer);
+				}
+			};
+			devServer.watcher.on("add", handleStructuralChange);
+			devServer.watcher.on("unlink", handleStructuralChange);
+			devServer.watcher.on("change", handleContentChange);
 		}
 	};
 }
@@ -12361,10 +12424,6 @@ function generateManifestModule(tree) {
 			const v = addImport(node.denied);
 			parts.push(`${nextIndent}denied: { load: ${v}, filePath: ${JSON.stringify(node.denied.filePath)} },`);
 		}
-		if (node.searchParams) {
-			const v = addImport(node.searchParams);
-			parts.push(`${nextIndent}searchParams: { load: ${v}, filePath: ${JSON.stringify(node.searchParams.filePath)} },`);
-		}
 		if (node.statusFiles && node.statusFiles.size > 0) {
 			const statusEntries = [];
 			for (const [code, file] of node.statusFiles) {
@@ -12542,6 +12601,59 @@ export const coerce = stub;
 	};
 }
 //#endregion
+//#region src/fonts/css.ts
+/**
+* Generate a single `@font-face` CSS rule from a descriptor.
+*/
+function generateFontFace(desc) {
+	const lines = [];
+	lines.push("@font-face {");
+	lines.push(`  font-family: '${desc.family}';`);
+	lines.push(`  src: ${desc.src};`);
+	if (desc.weight) lines.push(`  font-weight: ${desc.weight};`);
+	if (desc.style) lines.push(`  font-style: ${desc.style};`);
+	if (desc.display) lines.push(`  font-display: ${desc.display};`);
+	if (desc.unicodeRange) lines.push(`  unicode-range: ${desc.unicodeRange};`);
+	lines.push("}");
+	return lines.join("\n");
+}
+/**
+* Generate multiple `@font-face` rules from an array of descriptors.
+*/
+function generateFontFaces(descriptors) {
+	return descriptors.map(generateFontFace).join("\n\n");
+}
+/**
+* Generate a scoped CSS class that sets a CSS custom property for the font.
+*
+* Example output:
+* ```css
+* .timber-font-inter {
+*   --font-sans: 'Inter', 'Inter Fallback', system-ui, sans-serif;
+*   font-family: 'Inter', 'Inter Fallback', system-ui, sans-serif;
+* }
+* ```
+*/
+function generateVariableClass(className, variable, fontFamily) {
+	return `.${className} {\n  ${variable}: ${fontFamily};\n  font-family: ${fontFamily};\n}`;
+}
+/**
+* Generate a scoped CSS class that applies font-family directly.
+*
+* Used when no `variable` is specified — the className applies
+* the font-family inline instead of through a CSS custom property.
+*
+* Example output:
+* ```css
+* .timber-font-inter {
+*   font-family: 'Inter', 'Inter Fallback', system-ui, sans-serif;
+* }
+* ```
+*/
+function generateFontFamilyClass(className, fontFamily) {
+	return `.${className} {\n  font-family: ${fontFamily};\n}`;
+}
+//#endregion
 //#region src/fonts/fallbacks.ts
 /**
 * Lookup table for commonly used Google Fonts.
@@ -12680,6 +12792,26 @@ function getGenericFamily(family) {
 	return "sans-serif";
 }
 /**
+* Generate the full CSS for a size-adjusted fallback font.
+*
+* This produces a complete @font-face block with override descriptors
+* that FontFaceDescriptor doesn't natively support.
+*/
+function generateFallbackCss(family) {
+	const metrics = FALLBACK_METRICS[family.toLowerCase()];
+	if (!metrics) return null;
+	return [
+		"@font-face {",
+		`  font-family: '${`${family} Fallback`}';`,
+		`  src: local('${metrics.fallbackFont}');`,
+		`  size-adjust: ${metrics.sizeAdjust}%;`,
+		`  ascent-override: ${metrics.ascentOverride}%;`,
+		`  descent-override: ${metrics.descentOverride}%;`,
+		`  line-gap-override: ${metrics.lineGapOverride}%;`,
+		"}"
+	].join("\n");
+}
+/**
 * Check whether fallback metrics are available for a font family.
 */
 function hasFallbackMetrics(family) {
@@ -13028,6 +13160,26 @@ function generateFamilyName(sources) {
 	return stem.replace(/[-_]?(Regular|Bold|Italic|Light|Medium|SemiBold|ExtraBold|Thin|Black|Heavy)$/i, "") || stem;
 }
 /**
+* Generate @font-face descriptors for local font sources.
+*
+* Each source entry produces one @font-face rule. The `src` descriptor
+* uses a `url()` pointing to the served path under `/_timber/fonts/`.
+* The `urlPrefix` defaults to `/_timber/fonts` — the path used by both
+* the dev server middleware and the production build output.
+*/
+function generateLocalFontFaces(family, sources, display, urlPrefix = "/_timber/fonts") {
+	return sources.map((entry) => {
+		const format = inferFontFormat(entry.path);
+		return {
+			family,
+			src: `url('${urlPrefix}/${entry.path.split("/").pop() ?? entry.path}') format('${format}')`,
+			weight: entry.weight,
+			style: entry.style,
+			display
+		};
+	});
+}
+/**
 * Build the className for a local font, following the same convention
 * as Google fonts: `timber-font-<lowercase-hyphenated-family>`.
 */
@@ -13263,6 +13415,22 @@ var VIRTUAL_LOCAL = "@timber/fonts/local";
 var RESOLVED_GOOGLE = "\0@timber/fonts/google";
 var RESOLVED_LOCAL = "\0@timber/fonts/local";
 /**
+* Virtual side-effect module that registers font CSS on globalThis.
+*
+* When a file calls localFont() or a Google font function, the transform
+* hook injects `import 'virtual:timber-font-css-register'` into that file.
+* This virtual module sets `globalThis.__timber_font_css` with the combined
+* @font-face CSS. The RSC entry reads it at render time to inline a <style> tag.
+*
+* This approach avoids timing issues because:
+* 1. The font file is in the RSC module graph (imported by layout.tsx)
+* 2. The side-effect import is added to the font file during transform
+* 3. When layout.tsx is loaded, fonts.ts runs → side-effect module runs → globalThis is set
+* 4. RSC entry renders → reads globalThis → inlines <style>
+*/
+var VIRTUAL_FONT_CSS_REGISTER = "virtual:timber-font-css-register";
+var RESOLVED_FONT_CSS_REGISTER = "\0virtual:timber-font-css-register";
+/**
 * Convert a font family name to a PascalCase export name.
 * e.g. "JetBrains Mono" → "JetBrains_Mono"
 */
@@ -13409,6 +13577,35 @@ function generateLocalVirtualModule() {
 	].join("\n");
 }
 /**
+* Generate CSS for a single extracted font.
+*
+* Includes @font-face rules (for local fonts), fallback @font-face,
+* and the scoped class rule.
+*/
+function generateFontCss(font) {
+	const cssParts = [];
+	if (font.provider === "local" && font.localSources) {
+		const faceCss = generateFontFaces(generateLocalFontFaces(font.family, font.localSources, font.display));
+		if (faceCss) cssParts.push(faceCss);
+	}
+	const fallbackCss = generateFallbackCss(font.family);
+	if (fallbackCss) cssParts.push(fallbackCss);
+	if (font.variable) cssParts.push(generateVariableClass(font.className, font.variable, font.fontFamily));
+	else cssParts.push(generateFontFamilyClass(font.className, font.fontFamily));
+	return cssParts.join("\n\n");
+}
+/**
+* Generate the CSS output for all extracted fonts.
+*
+* Includes @font-face rules for local fonts, fallback @font-face rules,
+* and scoped classes.
+*/
+function generateAllFontCss(registry) {
+	const cssParts = [];
+	for (const font of registry.values()) cssParts.push(generateFontCss(font));
+	return cssParts.join("\n\n");
+}
+/**
 * Parse the local name used for the default import of `@timber/fonts/local`.
 *
 * Handles:
@@ -13459,15 +13656,63 @@ function timberFonts(ctx) {
 	return {
 		name: "timber-fonts",
 		resolveId(id) {
-			if (id === VIRTUAL_GOOGLE) return RESOLVED_GOOGLE;
-			if (id === VIRTUAL_LOCAL) return RESOLVED_LOCAL;
+			let cleanId = id.startsWith("\0") ? id.slice(1) : id;
+			if (cleanId.startsWith(ctx.root)) {
+				const stripped = cleanId.slice(ctx.root.length);
+				if (stripped.startsWith("/") || stripped.startsWith("\\")) cleanId = stripped.slice(1);
+				else cleanId = stripped;
+			}
+			if (cleanId === VIRTUAL_GOOGLE) return RESOLVED_GOOGLE;
+			if (cleanId === VIRTUAL_LOCAL) return RESOLVED_LOCAL;
+			if (cleanId === VIRTUAL_FONT_CSS_REGISTER) return RESOLVED_FONT_CSS_REGISTER;
 			return null;
 		},
 		load(id) {
 			if (id === RESOLVED_GOOGLE) return generateGoogleVirtualModule(registry);
 			if (id === RESOLVED_LOCAL) return generateLocalVirtualModule();
+			if (id === RESOLVED_FONT_CSS_REGISTER) {
+				const css = generateAllFontCss(registry);
+				return `globalThis.__timber_font_css = ${JSON.stringify(css)};`;
+			}
 			return null;
 		},
+		configureServer(server) {
+			server.middlewares.use((req, res, next) => {
+				const url = req.url;
+				if (!url || !url.startsWith("/_timber/fonts/")) return next();
+				const requestedFilename = url.slice(15);
+				if (requestedFilename.includes("..") || requestedFilename.includes("/")) {
+					res.statusCode = 400;
+					res.end("Bad request");
+					return;
+				}
+				for (const font of registry.values()) {
+					if (font.provider !== "local" || !font.localSources) continue;
+					for (const src of font.localSources) if ((src.path.split("/").pop() ?? "") === requestedFilename) {
+						const absolutePath = normalize(resolve(src.path));
+						if (!existsSync(absolutePath)) {
+							res.statusCode = 404;
+							res.end("Not found");
+							return;
+						}
+						const data = readFileSync(absolutePath);
+						const ext = absolutePath.split(".").pop()?.toLowerCase();
+						res.setHeader("Content-Type", {
+							woff2: "font/woff2",
+							woff: "font/woff",
+							ttf: "font/ttf",
+							otf: "font/otf",
+							eot: "application/vnd.ms-fontopen"
+						}[ext ?? ""] ?? "application/octet-stream");
+						res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
+						res.setHeader("Access-Control-Allow-Origin", "*");
+						res.end(data);
+						return;
+					}
+				}
+				next();
+			});
+		},
 		async buildStart() {
 			if (ctx.dev) return;
 			const googleFonts = [...registry.values()].filter((f) => f.provider === "google");
@@ -13523,10 +13768,13 @@ function timberFonts(ctx) {
 				}
 			}
 			if (hasLocalImport) transformedCode = transformLocalFonts(transformedCode, code, id, registry, this.error.bind(this));
-			if (transformedCode !== code) return {
-				code: transformedCode,
-				map: null
-			};
+			if (transformedCode !== code) {
+				if (registry.size > 0) transformedCode = `import '${VIRTUAL_FONT_CSS_REGISTER}';\n` + transformedCode;
+				return {
+					code: transformedCode,
+					map: null
+				};
+			}
 			return null;
 		},
 		generateBundle() {
@@ -13535,6 +13783,23 @@ function timberFonts(ctx) {
 				fileName: `_timber/fonts/${cf.hashedFilename}`,
 				source: cf.data
 			});
+			for (const font of registry.values()) {
+				if (font.provider !== "local" || !font.localSources) continue;
+				for (const src of font.localSources) {
+					const absolutePath = normalize(resolve(src.path));
+					if (!existsSync(absolutePath)) {
+						this.warn(`Local font file not found: ${absolutePath}`);
+						continue;
+					}
+					const basename = src.path.split("/").pop() ?? src.path;
+					const data = readFileSync(absolutePath);
+					this.emitFile({
+						type: "asset",
+						fileName: `_timber/fonts/${basename}`,
+						source: data
+					});
+				}
+			}
 			if (!ctx.buildManifest) return;
 			const cachedByFamily = /* @__PURE__ */ new Map();
 			for (const cf of cachedFonts) {
@@ -13661,16 +13926,14 @@ function validateStaticMode(code, fileId, options) {
 * - transform: Validates source files for static mode violations
 */
 function timberStaticBuild(ctx) {
-	const isStatic = ctx.config.output === "static";
-	const clientJavascriptDisabled = ctx.clientJavascript.disabled;
 	return {
 		name: "timber-static-build",
 		transform(code, id) {
-			if (!isStatic) return null;
+			if (!(ctx.config.output === "static")) return null;
 			if (id.includes("node_modules")) return null;
 			if (!id.includes("/app/") && !id.startsWith("app/")) return null;
 			if (!/\.[jt]sx?$/.test(id)) return null;
-			const errors = validateStaticMode(code, id, { clientJavascriptDisabled });
+			const errors = validateStaticMode(code, id, { clientJavascriptDisabled: ctx.clientJavascript.disabled });
 			if (errors.length > 0) {
 				const messages = errors.map((e) => `[timber] Static mode error in ${e.file}${e.line ? `:${e.line}` : ""}: ${e.message}`);
 				this.error(messages.join("\n\n"));
@@ -13680,95 +13943,6 @@ function timberStaticBuild(ctx) {
 	};
 }
 //#endregion
-//#region src/plugins/dynamic-transform.ts
-/**
-* Quick check: does this source file contain 'use dynamic' anywhere?
-* Used as a fast bail-out before doing expensive AST parsing.
-*/
-function containsUseDynamic(code) {
-	return containsDirective(code, "use dynamic");
-}
-/**
-* Find function declarations/expressions containing 'use dynamic' and
-* transform them into markDynamic() calls.
-*
-* Input:
-* ```tsx
-* export default async function AddToCartButton({ productId }) {
-*   'use dynamic'
-*   const user = await getUser()
-*   return <button>Add to cart</button>
-* }
-* ```
-*
-* Output:
-* ```tsx
-* import { markDynamic as __markDynamic } from '@timber-js/app/runtime';
-* export default async function AddToCartButton({ productId }) {
-*   __markDynamic();
-*   const user = await getUser()
-*   return <button>Add to cart</button>
-* }
-* ```
-*
-* The markDynamic() call registers the component boundary as dynamic
-* at render time. The pre-render pass uses this to know which subtrees
-* to skip and leave as holes for per-request rendering.
-*/
-function transformUseDynamic(code) {
-	if (!containsUseDynamic(code)) return null;
-	const functions = findFunctionsWithDirective(code, "use dynamic");
-	if (functions.length === 0) return null;
-	let result = code;
-	for (const fn of functions) {
-		const cleanBody = fn.bodyContent.replace(/['"]use dynamic['"];?/, "__markDynamic();");
-		result = result.slice(0, fn.bodyStart) + cleanBody + result.slice(fn.bodyEnd);
-	}
-	result = `import { markDynamic as __markDynamic } from '@timber-js/app/runtime';\n` + result;
-	return {
-		code: result,
-		map: null
-	};
-}
-/**
-* In `output: 'static'` mode, `'use dynamic'` is a build error.
-* Static mode renders everything at build time — there is no per-request
-* rendering to opt into.
-*/
-function validateNoDynamicInStaticMode(code) {
-	if (!containsUseDynamic(code)) return null;
-	const functions = findFunctionsWithDirective(code, "use dynamic");
-	if (functions.length === 0) return null;
-	return {
-		message: "'use dynamic' cannot be used in static mode (output: 'static'). Static mode renders all content at build time — there is no per-request rendering. Remove the directive or switch to output: 'server'.",
-		line: functions[functions.length - 1].directiveLine
-	};
-}
-/**
-* Create the timber-dynamic-transform Vite plugin.
-*
-* In server mode: transforms 'use dynamic' into markDynamic() calls.
-* In static mode: rejects 'use dynamic' as a build error.
-*/
-function timberDynamicTransform(ctx) {
-	const isStatic = ctx.config.output === "static";
-	return {
-		name: "timber-dynamic-transform",
-		transform(code, id) {
-			if (id.includes("node_modules")) return null;
-			if (!id.includes("/app/") && !id.startsWith("app/")) return null;
-			if (!/\.[jt]sx?$/.test(id)) return null;
-			if (!containsUseDynamic(code)) return null;
-			if (isStatic) {
-				const error = validateNoDynamicInStaticMode(code);
-				if (error) this.error(`[timber] Static mode error in ${id}${error.line ? `:${error.line}` : ""}: ${error.message}`);
-				return null;
-			}
-			return transformUseDynamic(code);
-		}
-	};
-}
-//#endregion
 //#region src/plugins/server-action-exports.ts
 var jsxParser = Parser.extend((0, import_acorn_jsx.default)());
 /**
@@ -13908,6 +14082,23 @@ function rewriteServerActionExportsFallback(code) {
 }
 //#endregion
 //#region src/plugins/build-manifest.ts
+/**
+* timber-build-manifest — Vite sub-plugin for build asset manifest generation.
+*
+* Provides `virtual:timber-build-manifest` which exports a BuildManifest
+* mapping route segment file paths to their CSS, JS, and modulepreload
+* output chunks.
+*
+* - Dev mode: exports an empty manifest (Vite HMR handles CSS/JS).
+* - Build mode: virtual module reads from globalThis.__TIMBER_BUILD_MANIFEST__
+*   at runtime. The actual manifest data is injected by the adapter via a
+*   _timber-manifest-init.js module that runs before the RSC handler.
+*
+* The generateBundle hook (client env only) extracts CSS/JS/modulepreload
+* data from the Rollup bundle and populates ctx.buildManifest.
+*
+* Design docs: 18-build-system.md §"Build Manifest", 02-rendering-pipeline.md §"Early Hints"
+*/
 var VIRTUAL_MODULE_ID = "virtual:timber-build-manifest";
 var RESOLVED_VIRTUAL_ID = `\0${VIRTUAL_MODULE_ID}`;
 /**
@@ -13983,6 +14174,7 @@ function timberBuildManifest(ctx) {
 		configResolved(config) {
 			resolvedBase = config.base;
 			isDev = config.command === "serve";
+			if (!isDev && !ctx.deploymentId) ctx.deploymentId = randomUUID().replace(/-/g, "").slice(0, 16);
 		},
 		resolveId(id) {
 			const cleanId = id.startsWith("\0") ? id.slice(1) : id;
@@ -14253,55 +14445,115 @@ function timberChunks() {
 	return { name: "timber-chunks" };
 }
 //#endregion
+//#region src/plugins/client-chunks.ts
+/**
+* Client chunk grouping strategy for @vitejs/plugin-rsc.
+*
+* Groups client reference modules by layout boundary to balance route-scoped
+* code splitting with HTTP request count. A constant group name would collapse
+* all routes into one chunk (every page downloads every client component).
+* Per-serverChunk grouping creates many sub-500B files. Layout-boundary
+* grouping is the middle ground.
+*
+* See design/27-chunking-strategy.md, TIM-440, TIM-499.
+*/
+/**
+* Derive a chunk group name for a client reference module.
+*
+* Groups by the first non-group route segment under appDir so that all
+* client components belonging to the same layout boundary land in one
+* chunk. For example:
+*   - `facade:app/dashboard/settings/page.tsx` → `"client-dashboard"`
+*   - `facade:app/(group-a)/group-page-a/page.tsx` → `"client-group-page-a"`
+*   - `facade:app/layout.tsx` (root layout) → `"client-shared"`
+*   - `shared:...` (shared across chunks) → `"client-shared"`
+*
+* This balances route-scoped code splitting with HTTP request count:
+* fewer chunks than per-serverChunk, but still avoids downloading every
+* client component on every page.
+*/
+function clientChunkGroup(meta, appDir) {
+	const { normalizedId, serverChunk } = meta;
+	if (serverChunk.startsWith("shared:")) return "client-shared";
+	const relPath = normalizedId.replace(/\\/g, "/");
+	const appDirName = appDir.replace(/\\/g, "/").split("/").pop() || "app";
+	const appIdx = relPath.indexOf(appDirName + "/");
+	if (appIdx === -1) return "client-shared";
+	const segments = relPath.slice(appIdx + appDirName.length + 1).split("/");
+	for (const seg of segments) {
+		if (seg.includes(".")) break;
+		if (seg.startsWith("(") && seg.endsWith(")")) continue;
+		return `client-${seg}`;
+	}
+	return "client-shared";
+}
+//#endregion
 //#region src/plugins/server-bundle.ts
 function timberServerBundle() {
-	return [{
-		name: "timber-server-bundle",
-		config(_cfg, { command }) {
-			if (command === "serve") return { environments: {
-				rsc: { resolve: { noExternal: ["server-only", "client-only"] } },
-				ssr: { resolve: { noExternal: [
-					"server-only",
-					"client-only",
-					"nuqs"
-				] } }
-			} };
-			const serverDefine = { "process.env.NODE_ENV": JSON.stringify("production") };
-			return {
-				ssr: { target: "webworker" },
-				environments: {
-					rsc: {
-						resolve: { noExternal: true },
-						define: serverDefine
-					},
-					ssr: {
-						resolve: { noExternal: true },
-						define: serverDefine
+	return [
+		{
+			name: "timber-server-bundle",
+			config(_cfg, { command }) {
+				if (command === "serve") return { environments: {
+					rsc: { resolve: { noExternal: ["server-only", "client-only"] } },
+					ssr: { resolve: { noExternal: [
+						"server-only",
+						"client-only",
+						"nuqs"
+					] } }
+				} };
+				const serverDefine = { "process.env.NODE_ENV": JSON.stringify("production") };
+				return {
+					ssr: { target: "webworker" },
+					environments: {
+						rsc: {
+							resolve: { noExternal: true },
+							define: serverDefine
+						},
+						ssr: {
+							resolve: { noExternal: true },
+							define: serverDefine
+						}
 					}
-				}
-			};
-		}
-	}, {
-		name: "timber-esm-init-fix",
-		applyToEnvironment(environment) {
-			return environment.name === "rsc" || environment.name === "ssr";
+				};
+			}
 		},
-		renderChunk(code) {
-			const lazy = "var __esmMin = (fn, res) => () => (fn && (res = fn(fn = 0)), res);";
-			if (!code.includes(lazy)) return null;
-			const eager = [
-				"var __esmMin = (fn, res) => {",
-				"  var l = () => { if (fn) { var f = fn; try { res = f(); fn = 0; } catch(e) {} } return res; };",
-				"  l();",
-				"  return l;",
-				"};"
-			].join(" ");
-			return {
-				code: code.replace(lazy, eager),
-				map: null
-			};
+		{
+			name: "timber-esm-init-fix",
+			applyToEnvironment(environment) {
+				return environment.name === "rsc" || environment.name === "ssr";
+			},
+			renderChunk(code) {
+				const lazy = "var __esmMin = (fn, res) => () => (fn && (res = fn(fn = 0)), res);";
+				if (!code.includes(lazy)) return null;
+				const eager = [
+					"var __esmMin = (fn, res) => {",
+					"  var l = () => { if (fn) { var f = fn; try { res = f(); fn = 0; } catch(e) {} } return res; };",
+					"  l();",
+					"  return l;",
+					"};"
+				].join(" ");
+				return {
+					code: code.replace(lazy, eager),
+					map: null
+				};
+			}
+		},
+		{
+			name: "timber-create-require-fix",
+			applyToEnvironment(environment) {
+				return environment.name === "rsc" || environment.name === "ssr";
+			},
+			renderChunk(code) {
+				const pattern = "createRequire(import.meta.url)";
+				if (!code.includes(pattern)) return null;
+				return {
+					code: code.replace(pattern, "createRequire(import.meta.url || \"file:///app\")"),
+					map: null
+				};
+			}
 		}
-	}];
+	];
 }
 //#endregion
 //#region src/plugins/adapter-build.ts
@@ -14323,6 +14575,7 @@ function timberAdapterBuild(ctx) {
 						modulepreload: {}
 					} : ctx.buildManifest;
 					manifestInit = `globalThis.__TIMBER_BUILD_MANIFEST__ = ${JSON.stringify(manifest)};\n`;
+					if (ctx.deploymentId) manifestInit += `globalThis.__TIMBER_DEPLOYMENT_ID__ = ${JSON.stringify(ctx.deploymentId)};\n`;
 				}
 				if (ctx.clientJavascript.disabled) await stripJsFromRscAssetsManifests(buildDir);
 				const adapterConfig = {
@@ -14679,6 +14932,65 @@ function createNoopTimer() {
 	};
 }
 //#endregion
+//#region src/server/action-encryption.ts
+/**
+* Regex for safe `defineEncryptionKey` expressions.
+*
+* The RSC plugin inlines this expression verbatim into generated JavaScript.
+* We restrict it to `process.env.<UPPER_SNAKE_CASE>` to prevent code injection.
+* See "Known Security Considerations" at the top of this file.
+*/
+var SAFE_KEY_EXPR = /^process\.env\.[A-Z_][A-Z0-9_]*$/;
+/**
+* Build the `defineEncryptionKey` expression for the RSC plugin.
+*
+* The RSC plugin accepts a JavaScript expression string that will be
+* inlined into the encryption runtime module. At runtime, this expression
+* must evaluate to the base64-encoded encryption key.
+*
+* Priority:
+* 1. `TIMBER_ACTIONS_ENCRYPTION_KEY` env var (for cross-build key sharing
+*    in rolling/blue-green deployments)
+* 2. Auto-generated at build time (RSC plugin default — embedded in bundle,
+*    consistent across all instances of the same build)
+*
+* For env var keys, we generate a runtime expression that reads the env var.
+* For auto-generated keys, we return undefined and let the RSC plugin handle it.
+*/
+function resolveEncryptionKeyExpression() {
+	const envKey = process.env.TIMBER_ACTIONS_ENCRYPTION_KEY;
+	if (envKey) {
+		validateKeyFormat(envKey);
+		const expr = "process.env.TIMBER_ACTIONS_ENCRYPTION_KEY";
+		if (!SAFE_KEY_EXPR.test(expr)) throw new Error(`Unsafe encryption key expression: ${expr}`);
+		return expr;
+	}
+}
+/**
+* Determine whether action encryption should be enabled.
+*
+* Encryption is always enabled in production. In dev mode, it's enabled
+* by default but can be disabled via config for debugging.
+*/
+function shouldEnableEncryption(isDev, config) {
+	if (!isDev) return true;
+	if (config?.disableInDev) return false;
+	return true;
+}
+/**
+* Validate that a key string is a valid base64-encoded 256-bit key.
+* Throws a descriptive error if the key is malformed.
+*/
+function validateKeyFormat(key) {
+	try {
+		const bytes = atob(key).length;
+		if (bytes !== 32) throw new Error(`TIMBER_ACTIONS_ENCRYPTION_KEY must be a base64-encoded 256-bit (32-byte) key. Got ${bytes} bytes. Generate one with: node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"`);
+	} catch (error) {
+		if (error instanceof Error && error.message.includes("TIMBER_ACTIONS_ENCRYPTION_KEY")) throw error;
+		throw new Error("TIMBER_ACTIONS_ENCRYPTION_KEY is not valid base64. Generate a key with: node -e \"console.log(require('crypto').randomBytes(32).toString('base64'))\"");
+	}
+}
+//#endregion
 //#region src/index.ts
 /**
 * Resolve `clientJavascript` into a fully resolved config.
@@ -14721,10 +15033,7 @@ function resolveAppDir(root, configAppDir) {
 }
 function createPluginContext(config, root) {
 	const projectRoot = root ?? process.cwd();
-	const resolvedConfig = {
-		output: "server",
-		...config
-	};
+	const resolvedConfig = { ...config };
 	return {
 		config: resolvedConfig,
 		clientJavascript: resolveClientJavascript(resolvedConfig),
@@ -14733,22 +15042,28 @@ function createPluginContext(config, root) {
 		root: projectRoot,
 		dev: false,
 		buildManifest: null,
+		deploymentId: null,
 		timer: createStartupTimer()
 	};
 }
 /**
 * Load timber.config.ts (or .js, .mjs) from the project root.
 * Returns the config object or null if no config file is found.
+*
+* Uses require() which works for ESM modules on Node 22.12+.
+* This keeps timber() synchronous — no async config loading needed.
 */
-async function loadTimberConfigFile(root) {
-	for (const name of [
+function loadTimberConfigFile(root) {
+	const configNames = [
 		"timber.config.ts",
 		"timber.config.js",
 		"timber.config.mjs"
-	]) {
+	];
+	const req = createRequire(join(root, "package.json"));
+	for (const name of configNames) {
 		const configPath = join(root, name);
 		if (existsSync(configPath)) {
-			const mod = await import(pathToFileURL(configPath).href);
+			const mod = req(configPath);
 			return mod.default ?? mod;
 		}
 	}
@@ -14763,10 +15078,7 @@ async function loadTimberConfigFile(root) {
 */
 function warnConfigConflicts(inline, fileConfig) {
 	const conflicts = [];
-	for (const key of Object.keys(fileConfig)) {
-		if (key === "output") continue;
-		if (key in inline && inline[key] !== void 0) conflicts.push(key);
-	}
+	for (const key of Object.keys(fileConfig)) if (key in inline && inline[key] !== void 0) conflicts.push(key);
 	if (conflicts.length > 0) console.warn(`[timber] Config conflict: ${conflicts.map((k) => `"${k}"`).join(", ")} set in both vite.config.ts (inline) and timber.config.ts. Move all config to timber.config.ts to avoid confusion. The inline value from vite.config.ts will be used.`);
 	return conflicts;
 }
@@ -14794,21 +15106,92 @@ function mergeFileConfig(ctx, fileConfig) {
 		} } : {}
 	};
 }
+/**
+* Resolve the React Compiler plugin via @rolldown/plugin-babel.
+*
+* Uses the `reactCompilerPreset` from @vitejs/plugin-react, which:
+* - Uses Babel ONLY for the compiler pass (OXC handles JSX)
+* - Automatically scopes to client environment via applyToEnvironmentHook
+* - Uses react/compiler-runtime built into React 19
+*
+* @rolldown/plugin-babel and babel-plugin-react-compiler are optional peer deps.
+* If either is missing, require() fails with a clear error message.
+*/
+function resolveReactCompilerPlugin(config, req) {
+	let babel;
+	try {
+		babel = req("@rolldown/plugin-babel");
+	} catch {
+		throw new Error("[timber] reactCompiler requires @rolldown/plugin-babel. Install it: pnpm add -D @rolldown/plugin-babel babel-plugin-react-compiler");
+	}
+	const options = typeof config === "object" ? config : {};
+	return (babel.default ?? babel)({ presets: [reactCompilerPreset(options)] });
+}
+/**
+* Build the options object for @vitejs/plugin-rsc.
+*
+* Uses a getter for `enableActionEncryption` so the RSC plugin reads
+* the value lazily — after ctx.dev is set in configResolved. This lets
+* `actionEncryption.disableInDev` work correctly even though the RSC
+* plugin is created before Vite resolves the command.
+*/
+function createRscOptions(ctx, encryptionKeyExpr) {
+	const options = {
+		serverHandler: false,
+		customClientEntry: true,
+		entries: {
+			rsc: "virtual:timber-rsc-entry",
+			ssr: "virtual:timber-ssr-entry",
+			client: "virtual:timber-browser-entry"
+		},
+		clientChunks: (meta) => clientChunkGroup(meta, ctx.appDir)
+	};
+	Object.defineProperty(options, "enableActionEncryption", {
+		get() {
+			return shouldEnableEncryption(ctx.dev, ctx.config.actionEncryption);
+		},
+		enumerable: true
+	});
+	if (encryptionKeyExpr) options.defineEncryptionKey = encryptionKeyExpr;
+	return options;
+}
 function timberCache(_ctx) {
 	return cacheTransformPlugin();
 }
+/**
+* Create the timber Vite plugin array.
+*
+* Loads timber.config.ts and all dependencies synchronously before
+* constructing the plugin array. This ensures ALL plugins — including
+* the RSC plugin and React Compiler — see the fully merged config
+* (inline + file-based). No async, no deferred config, no stale reads.
+*
+* Requires Node >= 22.12 for synchronous require() of ESM modules
+* (@vitejs/plugin-rsc is ESM-only).
+*
+* Previous versions used async loading and deferred config merging,
+* causing file-based config for reactCompiler, actionEncryption, and
+* output mode to be silently ignored. See TIM-451.
+*/
 function timber(config) {
 	const ctx = createPluginContext(config);
+	const consumerRequire = createRequire(join(process.cwd(), "package.json"));
+	ctx.timer.start("rsc-plugin-import");
+	const rscMod = consumerRequire("@vitejs/plugin-rsc");
+	const vitePluginRsc = rscMod.default ?? rscMod;
+	ctx.timer.end("rsc-plugin-import");
+	const encryptionKeyExpr = resolveEncryptionKeyExpression();
 	const rootSync = {
 		name: "timber-root-sync",
-		async config(userConfig, { command }) {
-			const root = userConfig.root ?? process.cwd();
+		config(userConfig, { command }) {
+			const viteRoot = resolve(userConfig.root ?? process.cwd());
 			ctx.timer.start("config-load");
-			const fileConfig = await loadTimberConfigFile(root);
+			const fileConfig = loadTimberConfigFile(viteRoot);
 			if (fileConfig) {
 				mergeFileConfig(ctx, fileConfig);
 				ctx.clientJavascript = resolveClientJavascript(ctx.config);
 			}
+			ctx.config.output ??= "server";
 			ctx.timer.end("config-load");
 			if (command === "build") return { oxc: { jsx: { development: false } } };
 		},
@@ -14820,33 +15203,31 @@ function timber(config) {
 			else ctx.timer.start("dev-server-setup");
 		}
 	};
-	const rscPluginPath = createRequire(join(process.cwd(), "package.json")).resolve("@vitejs/plugin-rsc");
-	ctx.timer.start("rsc-plugin-import");
-	const rscPluginsPromise = import(pathToFileURL(rscPluginPath).href).then(({ default: vitePluginRsc }) => {
-		ctx.timer.end("rsc-plugin-import");
-		return vitePluginRsc({
-			serverHandler: false,
-			customClientEntry: true,
-			entries: {
-				rsc: "virtual:timber-rsc-entry",
-				ssr: "virtual:timber-ssr-entry",
-				client: "virtual:timber-browser-entry"
-			}
-		});
-	});
+	const reactCompilerPlugins = [];
+	if (config?.reactCompiler) reactCompilerPlugins.push(resolveReactCompilerPlugin(config.reactCompiler, consumerRequire));
+	const lazyReactCompiler = {
+		name: "timber-react-compiler",
+		configResolved() {
+			if (config?.reactCompiler || !ctx.config.reactCompiler) return;
+			const resolved = resolveReactCompilerPlugin(ctx.config.reactCompiler, consumerRequire);
+			for (const key of Object.keys(resolved)) if (key !== "name") lazyReactCompiler[key] = resolved[key];
+		}
+	};
+	// @vitejs/plugin-rsc handles:
 	return [
 		rootSync,
 		timberReactProd(),
 		react(),
+		...reactCompilerPlugins,
+		lazyReactCompiler,
 		timberServerActionExports(),
-		rscPluginsPromise,
+		vitePluginRsc(createRscOptions(ctx, encryptionKeyExpr)),
 		timberShims(ctx),
 		timberRouting(ctx),
 		timberEntries(ctx),
 		timberBuildManifest(ctx),
 		timberCache(ctx),
 		timberStaticBuild(ctx),
-		timberDynamicTransform(ctx),
 		timberFonts(ctx),
 		timberMdx(ctx),
 		timberContent(ctx),
@@ -14858,7 +15239,28 @@ function timber(config) {
 		timberDevServer(ctx)
 	];
 }
+/**
+* Type-safe helper for timber.config.ts files.
+*
+* A pass-through identity function that provides autocomplete and
+* type checking for timber configuration. No runtime validation —
+* purely a DX convenience (same pattern as Vite's defineConfig).
+*
+* @example
+* ```ts
+* // timber.config.ts
+* import { defineConfig } from '@timber-js/app';
+*
+* export default defineConfig({
+*   output: 'server',
+*   pageExtensions: ['tsx', 'ts', 'mdx'],
+* });
+* ```
+*/
+function defineConfig(config) {
+	return config;
+}
 //#endregion
-export { timber as default, timber, resolveAppDir, resolveClientJavascript, warnConfigConflicts };
+export { timber as default, timber, defineConfig, loadTimberConfigFile, resolveAppDir, resolveClientJavascript, warnConfigConflicts };
 
 //# sourceMappingURL=index.js.map