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

package/dist/adapters/nitro.js

@@ -1,11 +1,11 @@
-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 { t as RSC_CONTENT_TYPE } from "../_chunks/rsc-media-type-DDc7duTD.js";
+import { a as IMMUTABLE_CACHE, i as writeHeadersFile, n as findUnhashedStaticFiles, r as runSharedBuildSteps, t as buildStaticDirectoryOutput } from "../_chunks/build-output-helper-9dqCv1pZ.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";
+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.ts';\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
 /**
@@ -19,7 +19,7 @@ var compress_default = "// Response compression for self-hosted deployments (dev
 * 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,
+	pattern: /^import\s*\{\s*RSC_CONTENT_TYPE\s*,?\s*\}\s*from\s*["'][^"']*shared\/rsc-media-type\.(?:js|ts)["'];?[ \t]*$/m,
 	replacement: `const RSC_CONTENT_TYPE = ${JSON.stringify(RSC_CONTENT_TYPE)};`
 }];
 /**
@@ -72,7 +72,7 @@ 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
+//#region src/adapters/nitro-presets.ts
 var PRESET_CONFIGS = {
 	"vercel": {
 		nitroPreset: "vercel",
@@ -148,135 +148,17 @@ var PRESET_CONFIGS = {
 		runtimeName: "bun"
 	}
 };
+/** Presets that produce a locally-runnable server entry. */
+var LOCALLY_PREVIEWABLE = /* @__PURE__ */ new Set(["node-server", "bun"]);
 /**
-* Create a Nitro-based adapter for multi-platform deployment.
-*
-* Nitro abstracts deployment targets — the same timber.js app can deploy
-* to Vercel, Netlify, AWS, Deno Deploy, or Azure by changing the preset.
-*
-* @example
-* ```ts
-* import { nitro } from '@timber-js/app/adapters/nitro'
-*
-* export default {
-*   output: 'server',
-*   adapter: nitro({ preset: 'vercel' }),
-* }
-* ```
+* Get the preset configuration for a given preset name.
+* @internal Exported for testing.
 */
-function nitro(options = {}) {
-	const preset = options.preset ?? "node-server";
-	const compress = options.compress ?? true;
-	PRESET_CONFIGS[preset];
-	return {
-		name: `nitro-${preset}`,
-		async buildOutput(config, buildDir) {
-			const outDir = join(buildDir, "nitro");
-			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");
-				await writeFile(rscEntry, `${config.manifestInit}\n${rscContent}`);
-			}
-			const entry = generateNitroEntry(buildDir, outDir, preset, compress);
-			await writeFile(join(outDir, "entry.ts"), entry);
-			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
-	};
-}
-/** @internal Exported for testing. */
-function generateNitroEntry(buildDir, outDir, preset, compress = true) {
-	const serverEntryRelative = "./rsc/index.js";
-	const runtimeName = PRESET_CONFIGS[preset].runtimeName;
-	const earlyHints = PRESET_CONFIGS[preset].supportsEarlyHints;
-	const supportsWaitUntil = PRESET_CONFIGS[preset].supportsWaitUntil;
-	let handlerCall;
-	if (earlyHints && supportsWaitUntil) handlerCall = `  const nodeRes = event.node?.res
-  const earlyHintsSender = (typeof nodeRes?.writeEarlyHints === 'function')
-    ? (links) => { try { nodeRes.writeEarlyHints({ link: links }) } catch {} }
-    : undefined
-
-  const waitUntilFn = (typeof event.waitUntil === 'function')
-    ? (p) => event.waitUntil(p)
-    : undefined
-
-  const callHandler = () => handler(webRequest)
-  let wrappedHandler = earlyHintsSender
-    ? () => runWithEarlyHintsSender(earlyHintsSender, callHandler)
-    : callHandler
-  const webResponse = waitUntilFn
-    ? await runWithWaitUntil(waitUntilFn, wrappedHandler)
-    : await wrappedHandler()`;
-	else if (earlyHints) handlerCall = `  const nodeRes = event.node?.res
-  const earlyHintsSender = (typeof nodeRes?.writeEarlyHints === 'function')
-    ? (links) => { try { nodeRes.writeEarlyHints({ link: links }) } catch {} }
-    : undefined
-
-  const webResponse = earlyHintsSender
-    ? await runWithEarlyHintsSender(earlyHintsSender, () => handler(webRequest))
-    : await handler(webRequest)`;
-	else if (supportsWaitUntil) handlerCall = `  const waitUntilFn = (typeof event.waitUntil === 'function')
-    ? (p) => event.waitUntil(p)
-    : undefined
-
-  const webResponse = waitUntilFn
-    ? await runWithWaitUntil(waitUntilFn, () => handler(webRequest))
-    : await handler(webRequest)`;
-	else handlerCall = `  const webResponse = await handler(webRequest)`;
-	return `// Generated by @timber-js/app/adapters/nitro
-// Do not edit — this file is regenerated on each build.
-
-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".
-process.env.TIMBER_RUNTIME = '${runtimeName}'
-
-// Nitro's index.mjs wraps this import with defineLazyEventHandler, which
-// already handles the event handler protocol. We export a plain async
-// function — no defineEventHandler wrapper needed.
-// Nitro bundles h3 into its internal _libs/ directory but doesn't make
-// it available as a bare specifier in the output's node_modules.
-export default async function timberHandler(event) {
-  // h3 v2: event.req is the Web Request
-  const webRequest = event.req
-${handlerCall}
-  return ${compress ? "compressResponse(webRequest, webResponse)" : "webResponse"}
-}
-`;
+function getPresetConfig(preset) {
+	return PRESET_CONFIGS[preset];
 }
-/** Presets that produce a locally-runnable server entry. */
-var LOCALLY_PREVIEWABLE = /* @__PURE__ */ new Set(["node-server", "bun"]);
+//#endregion
+//#region src/adapters/nitro-preview.ts
 /**
 * Generate a standalone preview server script that uses Node's built-in
 * HTTP server. This bypasses Nitro entirely — the Nitro entry.ts imports
@@ -301,7 +183,7 @@ import { fileURLToPath } from 'node:url';
 import { existsSync } from 'node:fs';
 
 // Set runtime before importing the handler.
-process.env.TIMBER_RUNTIME = '${PRESET_CONFIGS[preset].runtimeName}';
+process.env.TIMBER_RUNTIME = '${getPresetConfig(preset).runtimeName}';
 
 // Load the build manifest if it exists.
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
@@ -501,41 +383,6 @@ try {
 }
 `;
 }
-/** @internal Exported for testing. */
-function generateNitroPreviewCommand(buildDir, preset) {
-	if (!LOCALLY_PREVIEWABLE.has(preset)) return null;
-	const nitroDir = join(buildDir, "nitro");
-	const entryPath = join(nitroDir, "entry.ts");
-	return {
-		command: preset === "bun" ? "bun" : "node",
-		args: [entryPath],
-		cwd: nitroDir
-	};
-}
-async function runNitroBuild(nitroDir, preset, userConfig) {
-	const presetConfig = PRESET_CONFIGS[preset];
-	const { createNitro, build: nitroBuild, prepare, copyPublicAssets } = await import("nitro/builder");
-	const nitro = await createNitro({
-		rootDir: nitroDir,
-		preset: presetConfig.nitroPreset,
-		renderer: { handler: join(nitroDir, "entry.ts") },
-		output: { dir: join(nitroDir, presetConfig.outputDir) },
-		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) {
 	return new Promise((resolve, reject) => {
@@ -613,12 +460,218 @@ export function sendNodeResponse(nodeRes, webRes) {
 }
 `;
 }
+//#endregion
+//#region src/adapters/nitro.ts
 /**
-* Get the preset configuration for a given preset name.
+* Create a Nitro-based adapter for multi-platform deployment.
+*
+* Nitro abstracts deployment targets — the same timber.js app can deploy
+* to Vercel, Netlify, AWS, Deno Deploy, or Azure by changing the preset.
+*
+* @example
+* ```ts
+* import { nitro } from '@timber-js/app/adapters/nitro'
+*
+* export default {
+*   output: 'server',
+*   adapter: nitro({ preset: 'vercel' }),
+* }
+* ```
+*/
+function nitro(options = {}) {
+	const preset = options.preset ?? "node-server";
+	const compress = options.compress ?? true;
+	return {
+		name: `nitro-${preset}`,
+		async buildOutput(config, buildDir) {
+			const outDir = join(buildDir, "nitro");
+			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");
+				await writeFile(rscEntry, `${config.manifestInit}\n${rscContent}`);
+			}
+			const entry = generateNitroEntry(buildDir, outDir, preset, compress);
+			await writeFile(join(outDir, "entry.ts"), entry);
+			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
+	};
+}
+/** @internal Exported for testing. */
+function generateNitroEntry(buildDir, outDir, preset, compress = true) {
+	const serverEntryRelative = "./rsc/index.js";
+	const runtimeName = PRESET_CONFIGS[preset].runtimeName;
+	const earlyHints = PRESET_CONFIGS[preset].supportsEarlyHints;
+	const supportsWaitUntil = PRESET_CONFIGS[preset].supportsWaitUntil;
+	let handlerCall;
+	if (earlyHints && supportsWaitUntil) handlerCall = `  const nodeRes = event.node?.res
+  const earlyHintsSender = (typeof nodeRes?.writeEarlyHints === 'function')
+    ? (links) => { try { nodeRes.writeEarlyHints({ link: links }) } catch {} }
+    : undefined
+
+  const waitUntilFn = (typeof event.waitUntil === 'function')
+    ? (p) => event.waitUntil(p)
+    : undefined
+
+  const callHandler = () => handler(webRequest)
+  let wrappedHandler = earlyHintsSender
+    ? () => runWithEarlyHintsSender(earlyHintsSender, callHandler)
+    : callHandler
+  const webResponse = waitUntilFn
+    ? await runWithWaitUntil(waitUntilFn, wrappedHandler)
+    : await wrappedHandler()`;
+	else if (earlyHints) handlerCall = `  const nodeRes = event.node?.res
+  const earlyHintsSender = (typeof nodeRes?.writeEarlyHints === 'function')
+    ? (links) => { try { nodeRes.writeEarlyHints({ link: links }) } catch {} }
+    : undefined
+
+  const webResponse = earlyHintsSender
+    ? await runWithEarlyHintsSender(earlyHintsSender, () => handler(webRequest))
+    : await handler(webRequest)`;
+	else if (supportsWaitUntil) handlerCall = `  const waitUntilFn = (typeof event.waitUntil === 'function')
+    ? (p) => event.waitUntil(p)
+    : undefined
+
+  const webResponse = waitUntilFn
+    ? await runWithWaitUntil(waitUntilFn, () => handler(webRequest))
+    : await handler(webRequest)`;
+	else handlerCall = `  const webResponse = await handler(webRequest)`;
+	return `// Generated by @timber-js/app/adapters/nitro
+// Do not edit — this file is regenerated on each build.
+
+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".
+process.env.TIMBER_RUNTIME = '${runtimeName}'
+
+// Nitro's index.mjs wraps this import with defineLazyEventHandler, which
+// already handles the event handler protocol. We export a plain async
+// function — no defineEventHandler wrapper needed.
+// Nitro bundles h3 into its internal _libs/ directory but doesn't make
+// it available as a bare specifier in the output's node_modules.
+export default async function timberHandler(event) {
+  // h3 v2: event.req is the Web Request
+  const webRequest = event.req
+${handlerCall}
+  return ${compress ? "compressResponse(webRequest, webResponse)" : "webResponse"}
+}
+`;
+}
+/**
+* Prefixes of nitro build-output lines that give wrong advice for timber
+* builds. Every nitro bundler path emits these hints via `logger.success` —
+* the rollup path hardcodes `npx nitro preview`; rolldown and vite default
+* to it. That command resolves `.output/nitro.json` relative to cwd, but
+* timber's nitro build lives at `.timber/dist/nitro/.output`, so the
+* suggested command can never work from the project root.
+* Prefix matching degrades gracefully: if upstream rewords the line
+* entirely, it passes through rather than being silently eaten.
+*/
+var NITRO_PREVIEW_HINT_PREFIX = "You can preview this build using";
+var NITRO_DEPLOY_HINT_PREFIX = "You can deploy this build using";
+var SUPPRESSED_NITRO_HINT_PREFIXES = [NITRO_PREVIEW_HINT_PREFIX, NITRO_DEPLOY_HINT_PREFIX];
+/** @internal Exported for testing. */
+function isSuppressedNitroHint(message, prefixes = SUPPRESSED_NITRO_HINT_PREFIXES) {
+	return typeof message === "string" && prefixes.some((prefix) => message.startsWith(prefix));
+}
+/**
+* Nitro's rolldown and vite builders render `framework.previewCommand` /
+* `framework.deployCommand` into these hints. A user who explicitly set one
+* via `nitroConfig` has provided valid guidance — only suppress the hints
+* whose command is still nitro's broken default.
+*
 * @internal Exported for testing.
 */
-function getPresetConfig(preset) {
-	return PRESET_CONFIGS[preset];
+function selectSuppressedHintPrefixes(framework) {
+	return [...framework?.previewCommand ? [] : [NITRO_PREVIEW_HINT_PREFIX], ...framework?.deployCommand ? [] : [NITRO_DEPLOY_HINT_PREFIX]];
+}
+/**
+* Wrap a nitro logger's `success` so hardcoded preview/deploy hints are
+* dropped for this programmatic build only. Returns the original
+* (unfiltered) success fn so timber can print its own hint — which shares
+* the suppressed prefix on purpose, replacing nitro's wording.
+*
+* @internal Exported for testing.
+*/
+function wrapNitroLoggerForBuild(logger, prefixes = SUPPRESSED_NITRO_HINT_PREFIXES) {
+	const originalSuccess = logger.success.bind(logger);
+	const wrapped = (message, ...args) => {
+		if (isSuppressedNitroHint(message, prefixes)) return;
+		originalSuccess(message, ...args);
+	};
+	logger.success = Object.assign(wrapped, logger.success);
+	return originalSuccess;
+}
+/**
+* Timber's own post-build hint. Locally-runnable presets are previewed via
+* `timber preview`, which invokes this adapter's `preview()` to run the
+* generated `_preview-server.mjs`. Serverless presets get no hint — their
+* output lives under `.timber/dist/nitro/`, so any cwd-relative deploy
+* command would be as wrong as the nitro hint this replaces.
+*
+* @internal Exported for testing.
+*/
+function getPostBuildHint(preset) {
+	return LOCALLY_PREVIEWABLE.has(preset) ? "You can preview this build using `timber preview`" : null;
+}
+async function runNitroBuild(nitroDir, preset, userConfig) {
+	const presetConfig = PRESET_CONFIGS[preset];
+	const { createNitro, build: nitroBuild, prepare, copyPublicAssets } = await import("nitro/builder");
+	const nitro = await createNitro({
+		rootDir: nitroDir,
+		preset: presetConfig.nitroPreset,
+		renderer: { handler: join(nitroDir, "entry.ts") },
+		output: { dir: join(nitroDir, presetConfig.outputDir) },
+		routeRules: {
+			"/assets/**": { headers: { "Cache-Control": IMMUTABLE_CACHE } },
+			"/_timber/fonts/**": { headers: { "Cache-Control": IMMUTABLE_CACHE } }
+		},
+		rollupConfig: { external: [/\.\.\/rsc\//] },
+		...presetConfig.extraConfig,
+		...userConfig
+	});
+	const framework = nitro.options.builder === "rollup" ? void 0 : nitro.options.framework;
+	const logSuccess = wrapNitroLoggerForBuild(nitro.logger, selectSuppressedHintPrefixes(framework));
+	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();
+	const hint = framework?.previewCommand ? null : getPostBuildHint(preset);
+	if (hint) logSuccess(hint);
+	return { serverDir };
 }
 /**
 * Resolve the destination path for prebuilt flight payloads in the Nitro
@@ -657,6 +710,6 @@ async function copyPrebuiltToVercelFuncClones(functionsDir, prebuiltSrc, baseFun
 	})));
 }
 //#endregion
-export { copyPrebuiltToVercelFuncClones, generateNitroEntry, generateNitroPreviewCommand, generatePreviewScript, generateSendResponseModule, getPresetConfig, nitro, resolvePrebuiltOutputPath };
+export { copyPrebuiltToVercelFuncClones, generateNitroEntry, getPostBuildHint, isSuppressedNitroHint, nitro, resolvePrebuiltOutputPath, selectSuppressedHintPrefixes, wrapNitroLoggerForBuild };
 
 //# sourceMappingURL=nitro.js.map