@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.191

package/dist/adapters/nitro.js

@@ -1,114 +1,83 @@
-import { join, relative } from "node:path";
-import { cp, mkdir, readFile, writeFile } from "node:fs/promises";
+import { t as RSC_CONTENT_TYPE } from "../_chunks/rsc-media-type-DRqE_lD_.js";
+import { a as IMMUTABLE_CACHE, i as writeHeadersFile, n as findUnhashedStaticFiles, r as runSharedBuildSteps, t as buildStaticDirectoryOutput } from "../_chunks/build-output-helper-C3DrfzZR.js";
+import { transformWithOxc } from "vite";
+import { basename, dirname, join, relative } from "node:path";
+import { cp, glob, readFile, writeFile } from "node:fs/promises";
 import { execFile } from "node:child_process";
+//#region src/server/compress.ts?raw
+var compress_default = "// Response compression for self-hosted deployments (dev server, Nitro preview).\n//\n// Uses CompressionStream (Web Platform API) for gzip. Brotli is intentionally\n// left to CDNs and reverse proxies — at streaming-friendly quality levels its\n// ratio advantage is marginal, and node:zlib's brotli transform buffers output\n// internally, breaking streaming. Cloudflare Workers auto-compress at the edge —\n// this module is only used on Node.js/Bun.\n//\n// See design/25-production-deployments.md.\n//\n// This module is also emitted standalone as `_compress.mjs` by\n// `adapters/compress-module.ts`, which strips types but does not bundle. Its\n// imports must therefore be interpolated there — a new import that is not\n// fails the build with an explanatory error rather than resolving to nothing\n// on the deployed server.\n\nimport { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.js';\n\n// ─── Constants ────────────────────────────────────────────────────────────\n\n/**\n * MIME types that benefit from compression.\n * text/* is handled via prefix matching; these are the specific\n * application/* and image/* types that are compressible.\n */\nexport const COMPRESSIBLE_TYPES = new Set([\n  'text/html',\n  'text/css',\n  'text/plain',\n  'text/xml',\n  'text/javascript',\n  RSC_CONTENT_TYPE,\n  'application/json',\n  'application/javascript',\n  'application/xml',\n  'application/xhtml+xml',\n  'application/rss+xml',\n  'application/atom+xml',\n  'image/svg+xml',\n]);\n\n/**\n * Status codes that should never be compressed (no body or special semantics).\n */\nconst NO_COMPRESS_STATUSES = new Set([204, 304]);\n\n// ─── Encoding Negotiation ─────────────────────────────────────────────────\n\n/**\n * Parse Accept-Encoding and return the best supported encoding.\n * Returns 'gzip' if the client accepts it, null otherwise.\n *\n * Brotli (br) is intentionally not handled at the application level.\n * At the streaming-friendly quality levels (0–4), brotli's compression\n * ratio advantage over gzip is marginal, and node:zlib's brotli transform\n * buffers output internally — turning smooth streaming responses into\n * large infrequent bursts. Brotli's real wins come from offline/static\n * compression at higher quality levels (5–11), which CDNs and reverse\n * proxies (Cloudflare, nginx, Caddy) apply on cached responses.\n *\n * See design/25-production-deployments.md.\n */\nexport function negotiateEncoding(acceptEncoding: string): 'gzip' | null {\n  if (!acceptEncoding) return null;\n\n  // Parse tokens with quality values from the Accept-Encoding header.\n  // Per RFC 9110 §12.5.3, q=0 means \"not acceptable\" — the client explicitly\n  // rejects that encoding. Tokens without a q-value default to q=1.\n  // e.g. \"gzip;q=1.0, br;q=0\" → gzip is acceptable, br is rejected.\n  const parts = acceptEncoding.split(',');\n  for (const part of parts) {\n    const [token, ...params] = part.split(';');\n    const name = token.trim().toLowerCase();\n    if (name !== 'gzip') continue;\n\n    // Check for q=0 (explicitly disabled)\n    let qValue = 1; // default quality is 1\n    for (const param of params) {\n      const trimmed = param.trim().toLowerCase();\n      if (trimmed.startsWith('q=')) {\n        qValue = parseFloat(trimmed.slice(2));\n        if (Number.isNaN(qValue)) qValue = 1;\n        break;\n      }\n    }\n\n    if (qValue > 0) return 'gzip';\n  }\n\n  return null;\n}\n\n// ─── Compressibility Check ────────────────────────────────────────────────\n\n/**\n * Determine if a response should be compressed.\n *\n * Returns false for:\n * - Responses without a body (204, 304, null body)\n * - Already-encoded responses (Content-Encoding set)\n * - Non-compressible content types (images, binary)\n * - SSE streams (text/event-stream — must not be buffered)\n */\nexport function shouldCompress(response: Response): boolean {\n  // No body to compress\n  if (!response.body) return false;\n  if (NO_COMPRESS_STATUSES.has(response.status)) return false;\n\n  // Already compressed\n  if (response.headers.has('Content-Encoding')) return false;\n\n  // Check content type\n  const contentType = response.headers.get('Content-Type');\n  if (!contentType) return false;\n\n  // Extract the MIME type (strip charset and other parameters)\n  const mimeType = contentType.split(';')[0].trim().toLowerCase();\n\n  // SSE must not be compressed — it relies on chunk-by-chunk delivery\n  if (mimeType === 'text/event-stream') return false;\n\n  return COMPRESSIBLE_TYPES.has(mimeType);\n}\n\n// ─── Compression ──────────────────────────────────────────────────────────\n\n/**\n * Compress a Web Response if the client supports it and the content is compressible.\n *\n * Returns the original response unchanged if compression is not applicable.\n * Returns a new Response with the compressed body, Content-Encoding, and Vary headers.\n *\n * The body is piped through a compression stream — no buffering of the full response.\n * This preserves streaming behavior for HTML shell + deferred Suspense chunks.\n */\nexport function compressResponse(request: Request, response: Response): Response {\n  // Check if response is compressible\n  if (!shouldCompress(response)) return response;\n\n  // Negotiate encoding with the client\n  const acceptEncoding = request.headers.get('Accept-Encoding') ?? '';\n  const encoding = negotiateEncoding(acceptEncoding);\n  if (!encoding) return response;\n\n  // Compress the body stream with gzip via the Web Platform CompressionStream API.\n  const compressedBody = compressWithGzip(response.body!);\n\n  // Build new headers: copy originals, add compression headers, remove Content-Length\n  // (compressed size is unknown until streaming completes).\n  const headers = new Headers(response.headers);\n  headers.set('Content-Encoding', encoding);\n  headers.delete('Content-Length');\n\n  // Append to Vary header (preserve existing Vary values)\n  const existingVary = headers.get('Vary');\n  if (existingVary) {\n    if (!existingVary.toLowerCase().includes('accept-encoding')) {\n      headers.set('Vary', `${existingVary}, Accept-Encoding`);\n    }\n  } else {\n    headers.set('Vary', 'Accept-Encoding');\n  }\n\n  return new Response(compressedBody, {\n    status: response.status,\n    statusText: response.statusText,\n    headers,\n  });\n}\n\n// ─── Gzip (node:zlib with Z_SYNC_FLUSH) ──────────────────────────────────\n//\n// Uses node:zlib's createGzip with Z_SYNC_FLUSH so each chunk is flushed\n// to the output immediately. The Web Platform CompressionStream API buffers\n// internally and does NOT flush per-chunk — this kills streaming because\n// the browser doesn't receive the HTML shell until the gzip stream closes\n// (i.e. after all Suspense boundaries resolve).\n//\n// Z_SYNC_FLUSH adds ~2–5% size overhead vs Z_NO_FLUSH but preserves\n// correct streaming behavior: the shell renders instantly, Suspense\n// fallbacks are visible immediately, and streamed content appears\n// progressively.\n\nimport { createGzip, constants } from 'node:zlib';\nimport { Readable, pipeline } from 'node:stream';\n\n/**\n * Compress a ReadableStream with gzip, flushing each chunk immediately.\n *\n * Uses node:zlib's createGzip with Z_SYNC_FLUSH to ensure each HTML chunk\n * (shell, Suspense resolution, RSC payload) is delivered to the browser\n * as soon as it's available — preserving streaming semantics.\n */\nfunction compressWithGzip(body: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {\n  const gzip = createGzip({ flush: constants.Z_SYNC_FLUSH });\n  const nodeInput = Readable.fromWeb(body as import('stream/web').ReadableStream);\n\n  // pipeline() instead of bare pipe(): pipe() does not forward source errors,\n  // so an erroring body (streaming route handler, dropped upstream fetch)\n  // would emit an unhandled 'error' event and crash the process. pipeline()\n  // destroys gzip on source error — the returned web stream rejects — and\n  // tears down nodeInput when the consumer cancels the web stream, which\n  // cancels the source body via fromWeb. The error reaches the consumer\n  // through the web stream; the callback only marks it handled at the Node\n  // layer.\n  pipeline(nodeInput, gzip, () => {});\n\n  return Readable.toWeb(gzip) as ReadableStream<Uint8Array>;\n}\n";
+//#endregion
 //#region src/adapters/compress-module.ts
 /**
-* Generate a standalone ESM module that exports compressResponse().
+* The one import `server/compress.ts` is allowed to carry, and its inlined
+* form.
+*
+* The binding list is matched exactly rather than as `{…}`. A second binding
+* added to that import would otherwise be erased along with the statement and
+* become a `ReferenceError` in the deployed `_compress.mjs` — the failure this
+* whole module exists to make impossible. Matching exactly means such an
+* import falls through to the rejection below instead.
+*/
+var INLINED_IMPORTS = [{
+	pattern: /^import\s*\{\s*RSC_CONTENT_TYPE\s*,?\s*\}\s*from\s*["'][^"']*shared\/rsc-media-type\.js["'];?[ \t]*$/m,
+	replacement: `const RSC_CONTENT_TYPE = ${JSON.stringify(RSC_CONTENT_TYPE)};`
+}];
+/**
+* Every way a module specifier can reach the emitted file, minus Node
+* builtins.
+*
+* `node:*` is exempt because it resolves on the deployed server exactly as it
+* does here — `_compress.mjs` already imports `node:zlib` and `node:stream`,
+* and self-hosted (Node/Bun) is the only place this file runs. Everything
+* else — relative paths, bare packages — has no resolution target next to a
+* lone `.mjs` in the build output.
+*
+* All three forms are listed rather than the one `server/compress.ts` happens
+* to use, because a re-export or a lazy `await import()` fails in exactly the
+* same place and is exactly as invisible until deploy.
+*/
+var MODULE_SPECIFIERS = [
+	/^[ \t]*(?:import|export)\b[^\n]*\bfrom\s*["'](?!node:)[^"']+["']/m,
+	/^[ \t]*import\s*["'](?!node:)[^"']+["']/m,
+	/\bimport\s*\(\s*["'](?!node:)[^"']+["']/
+];
+/**
+* Replace the shared-module imports with their values and reject anything
+* else that would leave a dangling specifier in `_compress.mjs`.
 *
-* Written to `_compress.mjs` during buildOutput. Imported by the Nitro entry
-* and preview server.
+* Exported separately from `generateCompressModule` so both branches can be
+* driven with fixtures: the source it normally compiles is fixed, so a test
+* of the generator alone can only ever exercise whichever branch that source
+* happens to take today.
 *
 * @internal Exported for testing.
 */
-function generateCompressModule() {
-	return `// Generated by @timber-js/app — response compression for self-hosted deployments.
-// Do not edit — this file is regenerated on each build.
-// Uses CompressionStream (Web API) for gzip. Brotli is left to CDNs/reverse
-// proxies — at streaming quality levels its ratio advantage is marginal and
-// node:zlib buffers output internally, breaking streaming.
-
-const COMPRESSIBLE_TYPES = new Set([
-  'text/html', 'text/css', 'text/plain', 'text/xml', 'text/javascript',
-  'text/x-component', 'application/json', 'application/javascript',
-  'application/xml', 'application/xhtml+xml', 'application/rss+xml',
-  'application/atom+xml', 'image/svg+xml',
-]);
-
-const NO_COMPRESS_STATUSES = new Set([204, 304]);
-
-function negotiateEncoding(acceptEncoding) {
-  if (!acceptEncoding) return null;
-  // Parse tokens with quality values. Per RFC 9110 §12.5.3, q=0 means
-  // "not acceptable" — the client explicitly rejects that encoding.
-  // Brotli (br) is intentionally not handled at the application level.
-  const parts = acceptEncoding.split(',');
-  for (const part of parts) {
-    const [token, ...params] = part.split(';');
-    const name = token.trim().toLowerCase();
-    if (name !== '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;
-}
-
-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);
-}
-
-function compressWithGzip(body) {
-  return body.pipeThrough(new CompressionStream('gzip'));
-}
-
-export function compressResponse(request, response) {
-  if (!shouldCompress(response)) return response;
-  const acceptEncoding = request.headers.get('Accept-Encoding') || '';
-  const encoding = negotiateEncoding(acceptEncoding);
-  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,
-  });
+function inlineCompressImports(code) {
+	let out = code;
+	for (const { pattern, replacement } of INLINED_IMPORTS) out = out.replace(pattern, replacement);
+	const surviving = MODULE_SPECIFIERS.map((pattern) => pattern.exec(out)).find(Boolean);
+	if (surviving) throw new Error(`[timber] server/compress.ts is emitted as a standalone _compress.mjs (type-stripped, not bundled), so it cannot import anything at runtime. Found: ${surviving[0].trim()}\n  Either inline the value in adapters/compress-module.ts (see INLINED_IMPORTS) or keep the dependency out of server/compress.ts.`);
+	return out;
 }
-`;
+/**
+* Compile server/compress.ts into a standalone ESM module.
+*
+* Uses Vite's OXC transform to strip TypeScript types from the
+* embedded source. The result is written to `_compress.mjs` during
+* buildOutput.
+*
+* @internal Exported for testing.
+*/
+async function generateCompressModule() {
+	return "// Generated by @timber-js/app — compiled from server/compress.ts.\n// Do not edit — this file is regenerated on each build.\n" + inlineCompressImports((await transformWithOxc(compress_default, "compress.ts", { lang: "ts" })).code);
 }
 //#endregion
 //#region src/adapters/nitro.ts
-var IMMUTABLE_CACHE = "public, max-age=31536000, immutable";
-var STATIC_CACHE = "public, max-age=3600, must-revalidate";
-function generateHeadersFile() {
-	return `# Auto-generated by @timber-js/app — static asset cache headers.
-# See design/25-production-deployments.md §"CDN / Edge Cache"
-
-/assets/*
-  Cache-Control: ${IMMUTABLE_CACHE}
-
-/*
-  Cache-Control: ${STATIC_CACHE}
-`;
-}
 var PRESET_CONFIGS = {
 	"vercel": {
 		nitroPreset: "vercel",
 		outputDir: ".vercel/output",
+		serverBundleDir: "functions/__server.func",
 		supportsWaitUntil: true,
 		supportsEarlyHints: false,
 		runtimeName: "vercel",
@@ -117,6 +86,7 @@ var PRESET_CONFIGS = {
 	"vercel-edge": {
 		nitroPreset: "vercel-edge",
 		outputDir: ".vercel/output",
+		serverBundleDir: "functions/__server.func",
 		supportsWaitUntil: true,
 		supportsEarlyHints: false,
 		runtimeName: "vercel-edge"
@@ -124,6 +94,7 @@ var PRESET_CONFIGS = {
 	"netlify": {
 		nitroPreset: "netlify",
 		outputDir: ".netlify/functions-internal",
+		serverBundleDir: "server",
 		supportsWaitUntil: false,
 		supportsEarlyHints: false,
 		runtimeName: "netlify"
@@ -131,6 +102,7 @@ var PRESET_CONFIGS = {
 	"netlify-edge": {
 		nitroPreset: "netlify-edge",
 		outputDir: ".netlify/edge-functions",
+		serverBundleDir: "server",
 		supportsWaitUntil: true,
 		supportsEarlyHints: false,
 		runtimeName: "netlify-edge"
@@ -138,6 +110,7 @@ var PRESET_CONFIGS = {
 	"aws-lambda": {
 		nitroPreset: "aws-lambda",
 		outputDir: ".output",
+		serverBundleDir: "server",
 		supportsWaitUntil: false,
 		supportsEarlyHints: false,
 		runtimeName: "aws-lambda"
@@ -145,6 +118,7 @@ var PRESET_CONFIGS = {
 	"deno-deploy": {
 		nitroPreset: "deno-deploy",
 		outputDir: ".output",
+		serverBundleDir: "server",
 		supportsWaitUntil: true,
 		supportsEarlyHints: false,
 		runtimeName: "deno-deploy"
@@ -152,6 +126,7 @@ var PRESET_CONFIGS = {
 	"azure-functions": {
 		nitroPreset: "azure-functions",
 		outputDir: ".output",
+		serverBundleDir: "server",
 		supportsWaitUntil: false,
 		supportsEarlyHints: false,
 		runtimeName: "azure-functions"
@@ -159,6 +134,7 @@ var PRESET_CONFIGS = {
 	"node-server": {
 		nitroPreset: "node-server",
 		outputDir: ".output",
+		serverBundleDir: "server",
 		supportsWaitUntil: true,
 		supportsEarlyHints: false,
 		runtimeName: "node-server"
@@ -166,6 +142,7 @@ var PRESET_CONFIGS = {
 	"bun": {
 		nitroPreset: "bun",
 		outputDir: ".output",
+		serverBundleDir: "server",
 		supportsWaitUntil: true,
 		supportsEarlyHints: false,
 		runtimeName: "bun"
@@ -190,25 +167,31 @@ var PRESET_CONFIGS = {
 function nitro(options = {}) {
 	const preset = options.preset ?? "node-server";
 	const compress = options.compress ?? true;
-	const presetConfig = PRESET_CONFIGS[preset];
-	const pendingPromises = [];
+	PRESET_CONFIGS[preset];
 	return {
 		name: `nitro-${preset}`,
 		async buildOutput(config, buildDir) {
 			const outDir = join(buildDir, "nitro");
-			await mkdir(outDir, { recursive: true });
-			const clientDir = join(buildDir, "client");
-			const publicDir = join(outDir, "public");
-			await mkdir(publicDir, { recursive: true });
-			await cp(clientDir, publicDir, {
-				recursive: true,
-				filter: config.clientJavascriptDisabled ? (src) => !src.endsWith(".js") : void 0
-			}).catch(() => {});
-			await writeFile(join(publicDir, "_headers"), generateHeadersFile());
-			if (config.manifestInit) await writeFile(join(outDir, "_timber-manifest-init.js"), config.manifestInit);
-			await writeFile(join(outDir, "_compress.mjs"), generateCompressModule());
-			await cp(join(buildDir, "rsc"), join(outDir, "rsc"), { recursive: true });
-			await cp(join(buildDir, "ssr"), join(outDir, "ssr"), { recursive: true }).catch(() => {});
+			if (config.output === "static" && config.staticPagesDir) {
+				await buildStaticDirectoryOutput(config, buildDir, outDir, "public");
+				const publicDir = join(outDir, "public");
+				await writeHeadersFile(publicDir, config, await findUnhashedStaticFiles(publicDir));
+				if ((options.staticTarget ?? "generic") === "github-pages") {
+					await writeFile(join(publicDir, ".nojekyll"), "");
+					try {
+						if ((await readFile(join(publicDir, "_redirects"), "utf-8")).trim().length > 0) console.warn("[timber] Warning: GitHub Pages does not support _redirects files. Redirect rules from middleware/proxy will not work on this platform.");
+					} catch {}
+				}
+				return;
+			}
+			await runSharedBuildSteps({
+				config,
+				buildDir,
+				outDir,
+				publicDirName: "public"
+			});
+			await writeFile(join(outDir, "_compress.mjs"), await generateCompressModule());
+			await writeFile(join(outDir, "_send-response.mjs"), generateSendResponseModule());
 			if (config.manifestInit) {
 				const rscEntry = join(outDir, "rsc", "index.js");
 				const rscContent = await readFile(rscEntry, "utf-8");
@@ -216,24 +199,23 @@ function nitro(options = {}) {
 			}
 			const entry = generateNitroEntry(buildDir, outDir, preset, compress);
 			await writeFile(join(outDir, "entry.ts"), entry);
-			await runNitroBuild(outDir, preset, options.nitroConfig);
+			const { serverDir } = await runNitroBuild(outDir, preset, options.nitroConfig);
+			const prebuiltSrc = join(buildDir, "prebuilt");
+			await cp(prebuiltSrc, join(serverDir, "prebuilt"), { recursive: true }).catch((e) => {
+				if (e.code !== "ENOENT") throw e;
+			});
+			if (preset === "vercel" || preset === "vercel-edge") await copyPrebuiltToVercelFuncClones(dirname(serverDir), prebuiltSrc, basename(serverDir));
 		},
 		preview: LOCALLY_PREVIEWABLE.has(preset) ? async (_config, buildDir) => {
 			const previewScript = generatePreviewScript(buildDir, preset);
 			const scriptPath = join(buildDir, "nitro", "_preview-server.mjs");
 			await writeFile(scriptPath, previewScript);
 			await spawnNitroPreview(preset === "bun" ? "bun" : "node", [scriptPath], join(buildDir, "nitro"));
-		} : void 0,
-		waitUntil: presetConfig.supportsWaitUntil ? (promise) => {
-			const tracked = promise.catch((err) => {
-				console.error("[timber] waitUntil promise rejected:", err);
-			});
-			pendingPromises.push(tracked);
 		} : void 0
 	};
 }
 /** @internal Exported for testing. */
-function generateNitroEntry(buildDir, outDir, preset, compress = true, hasManifestInit = false) {
+function generateNitroEntry(buildDir, outDir, preset, compress = true) {
 	const serverEntryRelative = "./rsc/index.js";
 	const runtimeName = PRESET_CONFIGS[preset].runtimeName;
 	const earlyHints = PRESET_CONFIGS[preset].supportsEarlyHints;
@@ -274,7 +256,7 @@ function generateNitroEntry(buildDir, outDir, preset, compress = true, hasManife
 	return `// Generated by @timber-js/app/adapters/nitro
 // Do not edit — this file is regenerated on each build.
 
-${hasManifestInit ? "import './_timber-manifest-init.js'\n" : ""}import handler, { runWithEarlyHintsSender${supportsWaitUntil ? ", runWithWaitUntil" : ""} } from '${serverEntryRelative}'
+import handler, { runWithEarlyHintsSender${supportsWaitUntil ? ", runWithWaitUntil" : ""} } from '${serverEntryRelative}'
 ${compress ? "import { compressResponse } from './_compress.mjs'\n" : ""}
 // Set TIMBER_RUNTIME for instrumentation.ts conditional SDK initialization.
 // See design/25-production-deployments.md §"TIMBER_RUNTIME".
@@ -293,27 +275,8 @@ ${handlerCall}
 }
 `;
 }
-/** @internal Exported for testing. */
-function generateNitroConfig(preset, userConfig) {
-	const presetConfig = PRESET_CONFIGS[preset];
-	const config = {
-		preset: presetConfig.nitroPreset,
-		entry: "./entry.ts",
-		output: { dir: presetConfig.outputDir },
-		routeRules: { "/assets/**": { headers: { "Cache-Control": IMMUTABLE_CACHE } } },
-		...presetConfig.extraConfig,
-		...userConfig
-	};
-	return `// Generated by @timber-js/app/adapters/nitro
-// Do not edit — this file is regenerated on each build.
-
-import { defineNitroConfig } from 'nitro/config'
-
-export default defineNitroConfig(${JSON.stringify(config, null, 2)})
-`;
-}
 /** Presets that produce a locally-runnable server entry. */
-var LOCALLY_PREVIEWABLE = new Set(["node-server", "bun"]);
+var LOCALLY_PREVIEWABLE = /* @__PURE__ */ new Set(["node-server", "bun"]);
 /**
 * Generate a standalone preview server script that uses Node's built-in
 * HTTP server. This bypasses Nitro entirely — the Nitro entry.ts imports
@@ -353,6 +316,9 @@ const { default: handler, runWithEarlyHintsSender } = await import('${rscEntry}'
 // Import compression helper for self-hosted response compression.
 const { compressResponse } = await import('./_compress.mjs');
 
+// Web→Node response bridge with backpressure (TIM-1154).
+const { sendNodeResponse } = await import('./_send-response.mjs');
+
 const MIME_TYPES = {
   '.html': 'text/html',
   '.js': 'application/javascript',
@@ -379,11 +345,32 @@ const MIME_TYPES = {
 };
 
 const publicDir = join(__dirname, '${publicDir}');
-const port = parseInt(process.env.PORT || '3000', 10);
-const host = process.env.HOST || process.env.HOSTNAME || 'localhost';
+
+// Port resolution (TIM-842):
+//   - Default to 3000
+//   - If PORT env var is set, honor it strictly (fail loudly on conflict)
+//   - Otherwise auto-bump from 3000 until a free port is found
+// Mirrors the dev server behavior so timber dev/preview/production all
+// behave the same way around port selection.
+const envPort = process.env.PORT ? parseInt(process.env.PORT, 10) : null;
+const portIsExplicit = envPort != null && Number.isFinite(envPort) && envPort > 0;
+const startPort = portIsExplicit ? envPort : 3000;
+const host = process.env.HOST || 'localhost';
+
+// Set after listenWithBump() resolves so request handlers can build
+// absolute URLs from the actual bound port (which may differ from
+// startPort after an auto-bump).
+let boundPort = startPort;
 
 const server = createServer(async (req, res) => {
-  const url = new URL(req.url || '/', \`http://\${host}:\${port}\`);
+  // Scheme from the socket's TLS state — a hardcoded http:// breaks CSRF
+  // origin comparison and absolute-URL construction when TLS is terminated
+  // at this server (TIM-1073; mirrors the dev-server fix in TIM-1067).
+  // X-Forwarded-Proto is intentionally not consulted here: on a direct
+  // connection it would be attacker-controlled. The CSRF layer honors it
+  // separately for reverse-proxy deployments.
+  const scheme = req.socket?.encrypted ? 'https' : 'http';
+  const url = new URL(req.url || '/', \`\${scheme}://\${host}:\${boundPort}\`);
 
   // Try serving static files from the public directory first.
   const filePath = join(publicDir, url.pathname);
@@ -396,7 +383,9 @@ const server = createServer(async (req, res) => {
         const contentType = MIME_TYPES[ext] || 'application/octet-stream';
         const body = await readFile(filePath);
         // Hashed assets get immutable cache, others get short cache.
-        const cacheControl = url.pathname.startsWith('/assets/')
+        const isImmutable =
+          url.pathname.startsWith('/assets/') || url.pathname.startsWith('/_timber/fonts/');
+        const cacheControl = isImmutable
           ? 'public, max-age=31536000, immutable'
           : 'public, max-age=3600, must-revalidate';
         res.writeHead(200, {
@@ -453,22 +442,11 @@ const server = createServer(async (req, res) => {
     // Compress the response for self-hosted deployments.
     const webResponse = compressResponse(webRequest, rawResponse);
 
-    // Write the response back to the Node response.
-    res.writeHead(webResponse.status, Object.fromEntries(webResponse.headers.entries()));
-
-    if (webResponse.body) {
-      const reader = webResponse.body.getReader();
-      const pump = async () => {
-        while (true) {
-          const { done, value } = await reader.read();
-          if (done) { res.end(); return; }
-          res.write(value);
-        }
-      };
-      await pump();
-    } else {
-      res.end();
-    }
+    // Write the response to Node's ServerResponse. sendNodeResponse handles
+    // status, headers (including Set-Cookie splitting via [...headers]),
+    // body streaming with backpressure, and client disconnect cleanup.
+    // See TIM-1154.
+    await sendNodeResponse(res, webResponse);
   } catch (err) {
     console.error('[timber preview] Request error:', err);
     if (!res.headersSent) {
@@ -478,13 +456,49 @@ const server = createServer(async (req, res) => {
   }
 });
 
-server.listen(port, host, () => {
+function listenWithBump(port, attempt = 0) {
+  return new Promise((resolveListen, rejectListen) => {
+    const onError = (err) => {
+      server.removeListener('listening', onListening);
+      if (err && err.code === 'EADDRINUSE' && !portIsExplicit && attempt < 100) {
+        if (attempt === 0) {
+          console.log(\`  [timber] Port \${port} in use, trying \${port + 1}...\`);
+        }
+        listenWithBump(port + 1, attempt + 1).then(resolveListen, rejectListen);
+        return;
+      }
+      rejectListen(err);
+    };
+    const onListening = () => {
+      server.removeListener('error', onError);
+      resolveListen(port);
+    };
+    server.once('error', onError);
+    server.once('listening', onListening);
+    server.listen(port, host);
+  });
+}
+
+try {
+  boundPort = await listenWithBump(startPort);
+  if (boundPort !== startPort) {
+    console.log();
+    console.log(\`  [timber] Port \${startPort} in use, using \${boundPort}\`);
+  }
   console.log();
   console.log('  ⚡ timber preview server running at:');
   console.log();
-  console.log(\`    ➜  http://\${host}:\${port}\`);
+  console.log(\`    ➜  http://\${host}:\${boundPort}\`);
   console.log();
-});
+} catch (err) {
+  if (err && err.code === 'EADDRINUSE') {
+    console.error(\`[timber] Port \${startPort} is already in use. \` +
+      'Set PORT to a free port, or unset PORT to auto-pick.');
+  } else {
+    console.error('[timber] Failed to start preview server:', err);
+  }
+  process.exit(1);
+}
 `;
 }
 /** @internal Exported for testing. */
@@ -498,12 +512,6 @@ function generateNitroPreviewCommand(buildDir, preset) {
 		cwd: nitroDir
 	};
 }
-/**
-* Run the Nitro production build using the programmatic API.
-* Uses dynamic import so nitro is only loaded at build time.
-* Externalizes the timber RSC/SSR output — those files are pre-built
-* by timber and have internal references that nitro's bundler can't follow.
-*/
 async function runNitroBuild(nitroDir, preset, userConfig) {
 	const presetConfig = PRESET_CONFIGS[preset];
 	const { createNitro, build: nitroBuild, prepare, copyPublicAssets } = await import("nitro/builder");
@@ -512,15 +520,21 @@ async function runNitroBuild(nitroDir, preset, userConfig) {
 		preset: presetConfig.nitroPreset,
 		renderer: { handler: join(nitroDir, "entry.ts") },
 		output: { dir: join(nitroDir, presetConfig.outputDir) },
-		routeRules: { "/assets/**": { headers: { "Cache-Control": IMMUTABLE_CACHE } } },
+		routeRules: {
+			"/assets/**": { headers: { "Cache-Control": IMMUTABLE_CACHE } },
+			"/_timber/fonts/**": { headers: { "Cache-Control": IMMUTABLE_CACHE } }
+		},
 		rollupConfig: { external: [/\.\.\/rsc\//] },
 		...presetConfig.extraConfig,
 		...userConfig
 	});
+	const raw = nitro.options.output.serverDir;
+	const serverDir = raw.endsWith("/") ? raw.slice(0, -1) : raw;
 	await prepare(nitro);
 	await copyPublicAssets(nitro);
 	await nitroBuild(nitro);
 	await nitro.close();
+	return { serverDir };
 }
 /** Spawn a Nitro preview process and pipe stdio. */
 function spawnNitroPreview(command, args, cwd) {
@@ -534,13 +548,115 @@ function spawnNitroPreview(command, args, cwd) {
 	});
 }
 /**
+* Generate a standalone ESM module that exports sendNodeResponse.
+*
+* Mirrors srvx/node's sendNodeResponse: status + headers via writeHead,
+* body streaming with backpressure (waits for drain on write() === false),
+* and client disconnect cleanup. Written to `_send-response.mjs` during
+* buildOutput for use by the preview server script. See TIM-1154.
+*
+* @internal Exported for testing.
+*/
+function generateSendResponseModule() {
+	return `// Generated by @timber-js/app — Web→Node response bridge.
+// Do not edit — this file is regenerated on each build.
+// Mirrors srvx/node's sendNodeResponse with backpressure support.
+
+export function sendNodeResponse(nodeRes, webRes) {
+  if (!webRes) {
+    nodeRes.statusCode = 500;
+    return new Promise((resolve) => nodeRes.end(resolve));
+  }
+  const rawHeaders = [...webRes.headers];
+  const writeHeaders = rawHeaders.flat();
+  if (!nodeRes.headersSent) {
+    if (nodeRes.req?.httpVersion === '2.0') {
+      nodeRes.writeHead(webRes.status, writeHeaders);
+    } else {
+      nodeRes.writeHead(webRes.status, webRes.statusText, writeHeaders);
+    }
+  }
+  if (!webRes.body) {
+    return new Promise((resolve) => nodeRes.end(resolve));
+  }
+  // Stream with backpressure: pause reading when the kernel buffer is
+  // full (write() returns false) and resume on 'drain'.
+  if (nodeRes.destroyed) {
+    webRes.body.cancel();
+    return;
+  }
+  const reader = webRes.body.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 : undefined);
+    }
+  }
+  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);
+  });
+}
+`;
+}
+/**
 * Get the preset configuration for a given preset name.
 * @internal Exported for testing.
 */
 function getPresetConfig(preset) {
 	return PRESET_CONFIGS[preset];
 }
+/**
+* Resolve the destination path for prebuilt flight payloads in the Nitro
+* output directory. The RSC entry resolves `../prebuilt/` relative to its
+* bundled chunk location (`<serverBundleDir>/_chunks/`), so prebuilt/ must
+* live at `<serverBundleDir>/prebuilt/`.
+*
+* The serverBundleDir varies by preset — Nitro's Vercel preset uses
+* `functions/__server.func` while most others use `server`.
+*
+* @internal Exported for testing.
+*/
+function resolvePrebuiltOutputPath(outDir, preset) {
+	const presetConfig = PRESET_CONFIGS[preset];
+	return join(outDir, presetConfig.outputDir, presetConfig.serverBundleDir, "prebuilt");
+}
+/**
+* Copy prebuilt payloads into cloned Vercel function directories.
+*
+* When users configure `vercel.functionRules`, Nitro's compiled hook clones
+* the base __server.func to per-route .func directories. These clones are
+* created during `runNitroBuild()` — before our post-build prebuilt copy.
+* Each clone resolves `../prebuilt` independently, so they each need a copy.
+*
+* @internal Exported for testing.
+*/
+async function copyPrebuiltToVercelFuncClones(functionsDir, prebuiltSrc, baseFuncName) {
+	const funcDirs = [];
+	try {
+		for await (const match of glob("**/*.func", { cwd: functionsDir })) if (!match.endsWith(baseFuncName)) funcDirs.push(join(functionsDir, match));
+	} catch {
+		return;
+	}
+	await Promise.all(funcDirs.map((dir) => cp(prebuiltSrc, join(dir, "prebuilt"), { recursive: true }).catch((e) => {
+		if (e.code !== "ENOENT") throw e;
+	})));
+}
 //#endregion
-export { generateNitroConfig, generateNitroEntry, generateNitroPreviewCommand, generatePreviewScript, getPresetConfig, nitro };
+export { copyPrebuiltToVercelFuncClones, generateNitroEntry, generateNitroPreviewCommand, generatePreviewScript, generateSendResponseModule, getPresetConfig, nitro, resolvePrebuiltOutputPath };
 
 //# sourceMappingURL=nitro.js.map