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

package/src/adapters/nitro.ts

@@ -5,141 +5,38 @@
 // compression, graceful shutdown, static file serving, and platform quirks.
 // See design/11-platform.md and design/25-production-deployments.md.
 
-import { writeFile, readFile, mkdir, cp } from 'node:fs/promises';
-import { execFile } from 'node:child_process';
-import { join, relative } from 'node:path';
-import type { TimberPlatformAdapter, TimberConfig } from './types';
-import { generateCompressModule } from './compress-module.js';
-// Inlined from server/asset-headers.ts — adapters are loaded by Node at
-// Vite startup time, before Vite's module resolver is available, so cross-
-// directory .ts imports don't resolve.
-const IMMUTABLE_CACHE = 'public, max-age=31536000, immutable';
-const STATIC_CACHE = 'public, max-age=3600, must-revalidate';
-
-function generateHeadersFile(): string {
-  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}
-`;
-}
+import { cp, glob, readFile, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import {
+  buildStaticDirectoryOutput,
+  findUnhashedStaticFiles,
+  runSharedBuildSteps,
+  writeHeadersFile,
+} from './build-output-helper.ts';
+import { generateCompressModule } from './compress-module.ts';
+import { LOCALLY_PREVIEWABLE, PRESET_CONFIGS, type NitroPreset } from './nitro-presets.ts';
+import {
+  generatePreviewScript,
+  generateSendResponseModule,
+  spawnNitroPreview,
+} from './nitro-preview.ts';
+import { IMMUTABLE_CACHE } from './shared.ts';
+import type { TimberConfig, TimberPlatformAdapter } from './types.ts';
+
+// NitroPreset is part of the public adapter API (NitroAdapterOptions.preset),
+// so it stays importable from this module.
+export type { NitroPreset } from './nitro-presets.ts';
 
-// ─── Presets ─────────────────────────────────────────────────────────────────
+// ─── Options ─────────────────────────────────────────────────────────────────
 
 /**
- * Supported Nitro deployment presets.
+ * Static deploy target for `output: 'static'` mode.
  *
- * Each preset maps to a Nitro deployment target. The adapter generates
- * the appropriate configuration and entry point for the selected platform.
+ * Controls platform-specific files written alongside the static output:
+ * - `'github-pages'` — writes `.nojekyll` to skip Jekyll processing
+ * - `'generic'` — no extra files (default)
  */
-export type NitroPreset =
-  | 'vercel'
-  | 'vercel-edge'
-  | 'netlify'
-  | 'netlify-edge'
-  | 'aws-lambda'
-  | 'deno-deploy'
-  | 'azure-functions'
-  | 'node-server'
-  | 'bun';
-
-/** Preset-specific Nitro configuration. */
-interface PresetConfig {
-  /** Nitro preset name passed to the Nitro build. */
-  nitroPreset: string;
-  /** Output directory name within the build dir. */
-  outputDir: string;
-  /** Whether the runtime supports waitUntil. */
-  supportsWaitUntil: boolean;
-  /** Whether the runtime supports application-level 103 Early Hints. */
-  supportsEarlyHints: boolean;
-  /** Value for TIMBER_RUNTIME env var. See design/25-production-deployments.md. */
-  runtimeName: string;
-  /** Additional nitro.config fields for this preset. */
-  extraConfig?: Record<string, unknown>;
-}
-
-const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
-  'vercel': {
-    nitroPreset: 'vercel',
-    outputDir: '.vercel/output',
-    supportsWaitUntil: true,
-    supportsEarlyHints: false,
-    runtimeName: 'vercel',
-    extraConfig: { vercel: { functions: { maxDuration: 30 } } },
-  },
-  'vercel-edge': {
-    nitroPreset: 'vercel-edge',
-    outputDir: '.vercel/output',
-    supportsWaitUntil: true,
-    supportsEarlyHints: false,
-    runtimeName: 'vercel-edge',
-  },
-  'netlify': {
-    nitroPreset: 'netlify',
-    outputDir: '.netlify/functions-internal',
-    supportsWaitUntil: false,
-    supportsEarlyHints: false,
-    runtimeName: 'netlify',
-  },
-  'netlify-edge': {
-    nitroPreset: 'netlify-edge',
-    outputDir: '.netlify/edge-functions',
-    supportsWaitUntil: true,
-    supportsEarlyHints: false,
-    runtimeName: 'netlify-edge',
-  },
-  'aws-lambda': {
-    nitroPreset: 'aws-lambda',
-    outputDir: '.output',
-    supportsWaitUntil: false,
-    supportsEarlyHints: false,
-    runtimeName: 'aws-lambda',
-  },
-  'deno-deploy': {
-    nitroPreset: 'deno-deploy',
-    outputDir: '.output',
-    supportsWaitUntil: true,
-    supportsEarlyHints: false,
-    runtimeName: 'deno-deploy',
-  },
-  'azure-functions': {
-    nitroPreset: 'azure-functions',
-    outputDir: '.output',
-    supportsWaitUntil: false,
-    supportsEarlyHints: false,
-    runtimeName: 'azure-functions',
-  },
-  'node-server': {
-    nitroPreset: 'node-server',
-    outputDir: '.output',
-    supportsWaitUntil: true,
-    // Disabled by default: most node-server deployments sit behind a
-    // reverse proxy (nginx, caddy, traefik) that doesn't support 103
-    // Early Hints over HTTP/1.1. Sending 103 causes nginx to intermittently
-    // treat the response as an error and retry after proxy_connect_timeout
-    // (~5s stalls on ~23% of requests). Link headers on the 200 response
-    // are the safe fallback — Cloudflare and other CDNs convert them to
-    // 103 automatically at the edge (over HTTP/2+ to the browser).
-    supportsEarlyHints: false,
-    runtimeName: 'node-server',
-  },
-  'bun': {
-    nitroPreset: 'bun',
-    outputDir: '.output',
-    supportsWaitUntil: true,
-    // Disabled for same reason as node-server — reverse proxies choke on 103.
-    // Link headers on the 200 response are converted to 103 by CDNs.
-    supportsEarlyHints: false,
-    runtimeName: 'bun',
-  },
-};
-
-// ─── Options ─────────────────────────────────────────────────────────────────
+export type StaticTarget = 'github-pages' | 'generic';
 
 /** Options for the Nitro adapter. */
 export interface NitroAdapterOptions {
@@ -149,6 +46,30 @@ export interface NitroAdapterOptions {
    */
   preset?: NitroPreset;
 
+  /**
+   * Enable application-level gzip compression for HTML and RSC responses.
+   *
+   * When `true` (default), the origin compresses responses using the Web
+   * `CompressionStream` API. This is useful for self-hosted deployments
+   * where no reverse proxy or CDN handles compression.
+   *
+   * Set to `false` when deploying behind a reverse proxy (nginx, caddy)
+   * or CDN (Cloudflare, Fastly, Vercel) that compresses at the edge.
+   * Disabling origin compression saves CPU on the Node.js event loop —
+   * compressing 1MB+ streaming HTML responses takes 10-15ms of main
+   * thread time per request, directly reducing throughput under load.
+   *
+   * @default true
+   */
+  compress?: boolean;
+
+  /**
+   * Static deploy target for `output: 'static'` mode. Controls
+   * platform-specific files (e.g. `.nojekyll` for GitHub Pages).
+   * @default 'generic'
+   */
+  staticTarget?: StaticTarget;
+
   /**
    * Additional Nitro configuration to merge into the generated config.
    * Overrides default values for the selected preset.
@@ -176,47 +97,64 @@ export interface NitroAdapterOptions {
  */
 export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter {
   const preset = options.preset ?? 'node-server';
-  const presetConfig = PRESET_CONFIGS[preset];
-  const pendingPromises: Promise<unknown>[] = [];
-
+  const compress = options.compress ?? true;
   return {
     name: `nitro-${preset}`,
 
     async buildOutput(config: TimberConfig, buildDir: string) {
       const outDir = join(buildDir, 'nitro');
-      await mkdir(outDir, { recursive: true });
-
-      // Copy client assets to public directory.
-      // When client JavaScript is disabled, skip .js files — only CSS,
-      // fonts, images, and other static assets are needed.
-      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: string) => !src.endsWith('.js') : undefined,
-      }).catch(() => {
-        // Client dir may not exist when client JavaScript is disabled
-      });
 
-      // Write _headers file for platforms that support it (Netlify, etc.).
-      // See design/25-production-deployments.md §"CDN / Edge Cache"
-      await writeFile(join(publicDir, '_headers'), generateHeadersFile());
+      // ── Static mode: plain directory output ────────────────────────
+      // No Nitro server — just pre-rendered HTML + client assets.
+      if (config.output === 'static' && config.staticPagesDir) {
+        await buildStaticDirectoryOutput(config, buildDir, outDir, 'public');
+        const publicDir = join(outDir, 'public');
+
+        // Write _headers for cache control + extensionless Content-Type.
+        // Netlify supports the _headers convention just like Cloudflare.
+        await writeHeadersFile(publicDir, config, await findUnhashedStaticFiles(publicDir));
+
+        // Platform-specific files for static deploy targets.
+        const target = options.staticTarget ?? 'generic';
+        if (target === 'github-pages') {
+          // Deploy-from-a-branch runs Jekyll, which drops `_`-prefixed paths —
+          // every `_rsc/` payload. Written unconditionally: GitHub reads only
+          // that the file exists, never its contents.
+          await writeFile(join(publicDir, '.nojekyll'), '');
+          // GitHub Pages doesn't support _redirects files. Warn if any
+          // redirects were generated — those routes will 404 on GH Pages.
+          try {
+            const redirects = await readFile(join(publicDir, '_redirects'), 'utf-8');
+            if (redirects.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 {
+            // No _redirects file — nothing to warn about
+          }
+        }
 
-      // Write the build manifest init module (if manifest data was produced).
-      if (config.manifestInit) {
-        await writeFile(join(outDir, '_timber-manifest-init.js'), config.manifestInit);
+        return;
       }
 
-      // Write the compression helper module for runtime use.
+      // Steps 1–5: shared across all adapters (mkdir, copy client/rsc/ssr,
+      // write _headers, write manifest-init).
+      await runSharedBuildSteps({
+        config,
+        buildDir,
+        outDir,
+        publicDirName: 'public',
+      });
+
+      // Write runtime helper modules used by the preview server.
       // See design/25-production-deployments.md — self-hosted deployments
       // need application-level compression (Cloudflare handles it at the edge).
-      await writeFile(join(outDir, '_compress.mjs'), generateCompressModule());
+      await writeFile(join(outDir, '_compress.mjs'), await generateCompressModule());
 
-      // Copy rsc/ssr build output into the nitro dir so imports stay local
-      // during the Nitro bundling step (avoids broken relative paths in output).
-      await cp(join(buildDir, 'rsc'), join(outDir, 'rsc'), { recursive: true });
-      await cp(join(buildDir, 'ssr'), join(outDir, 'ssr'), { recursive: true }).catch(() => {});
+      // Web→Node response bridge with backpressure. See TIM-1154.
+      await writeFile(join(outDir, '_send-response.mjs'), generateSendResponseModule());
 
       // Prepend the manifest assignment directly into the RSC entry so
       // globalThis.__TIMBER_BUILD_MANIFEST__ is set before any module reads it.
@@ -229,13 +167,35 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
       }
 
       // Generate the Nitro entry point (imports from ./rsc/ within nitro dir)
-      const entry = generateNitroEntry(buildDir, outDir, preset);
+      const entry = generateNitroEntry(buildDir, outDir, preset, compress);
       await writeFile(join(outDir, 'entry.ts'), entry);
 
       // Run the Nitro build to produce a production-ready server bundle.
       // The output goes to dist/nitro/.output/server/index.mjs (for node-server preset).
       // Config is passed programmatically — no nitro.config.ts file needed.
-      await runNitroBuild(outDir, preset, options.nitroConfig);
+      const { serverDir } = await runNitroBuild(outDir, preset, options.nitroConfig);
+
+      // Copy prebuilt flight payloads from the canonical build source
+      // (buildDir/prebuilt, cleaned by the prebuilt plugin each build) into
+      // the Nitro output. The RSC entry resolves `../prebuilt/` relative to
+      // its bundled chunk (<serverDir>/_chunks/), so prebuilt/ must live at
+      // <serverDir>/prebuilt/. serverDir is the resolved path from Nitro
+      // (honors user overrides via nitroConfig.output.serverDir).
+      const prebuiltSrc = join(buildDir, 'prebuilt');
+      await cp(prebuiltSrc, join(serverDir, 'prebuilt'), {
+        recursive: true,
+      }).catch((e: NodeJS.ErrnoException) => {
+        if (e.code !== 'ENOENT') throw e;
+      });
+
+      // Vercel with functionRules clones __server.func to per-route .func
+      // directories during the Nitro build. Copy prebuilt into those clones
+      // so requests routed to them also resolve ../prebuilt correctly.
+      if (preset === 'vercel' || preset === 'vercel-edge') {
+        const functionsDir = dirname(serverDir);
+        const baseFuncName = basename(serverDir);
+        await copyPrebuiltToVercelFuncClones(functionsDir, prebuiltSrc, baseFuncName);
+      }
     },
 
     // Only presets that produce a locally-runnable server get preview().
@@ -254,15 +214,6 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
           await spawnNitroPreview(command, [scriptPath], join(buildDir, 'nitro'));
         }
       : undefined,
-
-    waitUntil: presetConfig.supportsWaitUntil
-      ? (promise: Promise<unknown>) => {
-          const tracked = promise.catch((err) => {
-            console.error('[timber] waitUntil promise rejected:', err);
-          });
-          pendingPromises.push(tracked);
-        }
-      : undefined,
   };
 }
 
@@ -273,7 +224,7 @@ export function generateNitroEntry(
   buildDir: string,
   outDir: string,
   preset: NitroPreset,
-  hasManifestInit = false
+  compress = true
 ): string {
   // The RSC entry is the main request handler — it exports the fetch handler as default.
   // rsc/ is copied into the nitro dir so the import is local.
@@ -330,20 +281,17 @@ export function generateNitroEntry(
     handlerCall = `  const webResponse = await handler(webRequest)`;
   }
 
-  // Build manifest init must be imported before the handler so that
-  // globalThis.__TIMBER_BUILD_MANIFEST__ is set when the virtual module evaluates.
-  // ESM guarantees imports are evaluated in order.
-  const manifestImport = hasManifestInit ? "import './_timber-manifest-init.js'\n" : '';
-
   // Import runWithWaitUntil only when the preset supports it.
   const waitUntilImport = supportsWaitUntil ? ', runWithWaitUntil' : '';
 
+  const compressImport = compress ? "import { compressResponse } from './_compress.mjs'\n" : '';
+  const compressCall = compress ? 'compressResponse(webRequest, webResponse)' : 'webResponse';
+
   return `// Generated by @timber-js/app/adapters/nitro
 // Do not edit — this file is regenerated on each build.
 
-${manifestImport}import handler, { runWithEarlyHintsSender${waitUntilImport} } from '${serverEntryRelative}'
-import { compressResponse } from './_compress.mjs'
-
+import handler, { runWithEarlyHintsSender${waitUntilImport} } from '${serverEntryRelative}'
+${compressImport}
 // Set TIMBER_RUNTIME for instrumentation.ts conditional SDK initialization.
 // See design/25-production-deployments.md §"TIMBER_RUNTIME".
 process.env.TIMBER_RUNTIME = '${runtimeName}'
@@ -357,246 +305,93 @@ export default async function timberHandler(event) {
   // h3 v2: event.req is the Web Request
   const webRequest = event.req
 ${handlerCall}
-  return compressResponse(webRequest, webResponse)
+  return ${compressCall}
 }
 `;
 }
 
-/** @internal Exported for testing. */
-export function generateNitroConfig(
-  preset: NitroPreset,
-  userConfig?: Record<string, unknown>
-): string {
-  const presetConfig = PRESET_CONFIGS[preset];
-
-  const config: Record<string, unknown> = {
-    preset: presetConfig.nitroPreset,
-    entry: './entry.ts',
-    output: { dir: presetConfig.outputDir },
-    // Static asset cache headers — hashed assets are immutable, others get 1h.
-    // See design/25-production-deployments.md §"CDN / Edge Cache"
-    routeRules: {
-      '/assets/**': { headers: { 'Cache-Control': IMMUTABLE_CACHE } },
-    },
-    ...presetConfig.extraConfig,
-    ...userConfig,
-  };
+// ─── Build Hint Filtering ────────────────────────────────────────────────────
 
-  const configJson = JSON.stringify(config, null, 2);
-
-  return `// Generated by @timber-js/app/adapters/nitro
-// Do not edit — this file is regenerated on each build.
-
-import { defineNitroConfig } from 'nitro/config'
+/**
+ * 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.
+ */
+const NITRO_PREVIEW_HINT_PREFIX = 'You can preview this build using';
+const NITRO_DEPLOY_HINT_PREFIX = 'You can deploy this build using';
+const SUPPRESSED_NITRO_HINT_PREFIXES = [NITRO_PREVIEW_HINT_PREFIX, NITRO_DEPLOY_HINT_PREFIX];
 
-export default defineNitroConfig(${configJson})
-`;
+/** @internal Exported for testing. */
+export function isSuppressedNitroHint(
+  message: unknown,
+  prefixes: readonly string[] = SUPPRESSED_NITRO_HINT_PREFIXES
+): boolean {
+  return typeof message === 'string' && prefixes.some((prefix) => message.startsWith(prefix));
 }
 
-// ─── Preview ─────────────────────────────────────────────────────────────────
-
-/** Presets that produce a locally-runnable server entry. */
-const LOCALLY_PREVIEWABLE = new Set<NitroPreset>(['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
- * h3 which isn't available outside a Nitro build. For local preview we
- * just need to serve static files and route requests to the RSC handler.
+ * 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.
  */
-export function generatePreviewScript(buildDir: string, preset: NitroPreset): string {
-  const rscEntryRelative = relative(join(buildDir, 'nitro'), join(buildDir, 'rsc', 'index.js'));
-  const rscEntry = rscEntryRelative.startsWith('.') ? rscEntryRelative : './' + rscEntryRelative;
-  const publicDir = './public';
-  const manifestInitPath = './_timber-manifest-init.js';
-  const runtimeName = PRESET_CONFIGS[preset].runtimeName;
-
-  return `// Generated by @timber-js/app — standalone preview server.
-// Uses Node's built-in HTTP server to serve static assets and route
-// dynamic requests through the RSC handler. No Nitro/h3 dependency.
-
-import { createServer } from 'node:http';
-import { readFile, stat } from 'node:fs/promises';
-import { join, extname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { existsSync } from 'node:fs';
-
-// Set runtime before importing the handler.
-process.env.TIMBER_RUNTIME = '${runtimeName}';
-
-// Load the build manifest if it exists.
-const __dirname = fileURLToPath(new URL('.', import.meta.url));
-const manifestPath = join(__dirname, '${manifestInitPath}');
-if (existsSync(manifestPath)) {
-  await import('${manifestInitPath}');
+export function selectSuppressedHintPrefixes(framework?: {
+  previewCommand?: string;
+  deployCommand?: string;
+}): string[] {
+  return [
+    ...(framework?.previewCommand ? [] : [NITRO_PREVIEW_HINT_PREFIX]),
+    ...(framework?.deployCommand ? [] : [NITRO_DEPLOY_HINT_PREFIX]),
+  ];
 }
 
-// Import the RSC handler (default export is the fetch-like handler).
-const { default: handler, runWithEarlyHintsSender } = await import('${rscEntry}');
-
-// Import compression helper for self-hosted response compression.
-const { compressResponse } = await import('./_compress.mjs');
-
-const MIME_TYPES = {
-  '.html': 'text/html',
-  '.js': 'application/javascript',
-  '.mjs': 'application/javascript',
-  '.css': 'text/css',
-  '.json': 'application/json',
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.svg': 'image/svg+xml',
-  '.ico': 'image/x-icon',
-  '.woff': 'font/woff',
-  '.woff2': 'font/woff2',
-  '.ttf': 'font/ttf',
-  '.otf': 'font/otf',
-  '.webp': 'image/webp',
-  '.avif': 'image/avif',
-  '.webm': 'video/webm',
-  '.mp4': 'video/mp4',
-  '.txt': 'text/plain',
-  '.xml': 'application/xml',
-  '.wasm': 'application/wasm',
-};
-
-const publicDir = join(__dirname, '${publicDir}');
-const port = parseInt(process.env.PORT || '3000', 10);
-const host = process.env.HOST || process.env.HOSTNAME || 'localhost';
-
-const server = createServer(async (req, res) => {
-  const url = new URL(req.url || '/', \`http://\${host}:\${port}\`);
-
-  // Try serving static files from the public directory first.
-  const filePath = join(publicDir, url.pathname);
-  // Prevent path traversal.
-  if (filePath.startsWith(publicDir)) {
-    try {
-      const fileStat = await stat(filePath);
-      if (fileStat.isFile()) {
-        const ext = extname(filePath);
-        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/')
-          ? 'public, max-age=31536000, immutable'
-          : 'public, max-age=3600, must-revalidate';
-        res.writeHead(200, {
-          'Content-Type': contentType,
-          'Content-Length': body.length,
-          'Cache-Control': cacheControl,
-        });
-        res.end(body);
-        return;
-      }
-    } catch {
-      // File not found — fall through to the RSC handler.
-    }
-  }
-
-  // Convert Node request to Web Request.
-  const headers = new Headers();
-  for (const [key, value] of Object.entries(req.headers)) {
-    if (value) {
-      if (Array.isArray(value)) {
-        for (const v of value) headers.append(key, v);
-      } else {
-        headers.set(key, value);
-      }
-    }
-  }
-
-  let body = undefined;
-  if (req.method !== 'GET' && req.method !== 'HEAD') {
-    body = await new Promise((resolve) => {
-      const chunks = [];
-      req.on('data', (chunk) => chunks.push(chunk));
-      req.on('end', () => resolve(Buffer.concat(chunks)));
-    });
-  }
-
-  const webRequest = new Request(url.href, {
-    method: req.method,
-    headers,
-    body,
-    duplex: body ? 'half' : undefined,
-  });
-
-  try {
-    // Support 103 Early Hints when available.
-    const earlyHintsSender = (typeof res.writeEarlyHints === 'function')
-      ? (links) => { try { res.writeEarlyHints({ link: links }); } catch {} }
-      : undefined;
-
-    const rawResponse = earlyHintsSender && runWithEarlyHintsSender
-      ? await runWithEarlyHintsSender(earlyHintsSender, () => handler(webRequest))
-      : await handler(webRequest);
-
-    // 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();
-    }
-  } catch (err) {
-    console.error('[timber preview] Request error:', err);
-    if (!res.headersSent) {
-      res.writeHead(500, { 'Content-Type': 'text/plain' });
-    }
-    res.end('Internal Server Error');
-  }
-});
-
-server.listen(port, host, () => {
-  console.log();
-  console.log('  ⚡ timber preview server running at:');
-  console.log();
-  console.log(\`    ➜  http://\${host}:\${port}\`);
-  console.log();
-});
-`;
+/** Minimal structural view of the nitro (consola) logger the wrap needs. */
+interface NitroBuildLogger {
+  success: (message: unknown, ...args: unknown[]) => void;
 }
 
-/** Command descriptor for Nitro preview — testable without spawning. */
-export interface NitroPreviewCommand {
-  command: string;
-  args: string[];
-  cwd: string;
+/**
+ * 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.
+ */
+export function wrapNitroLoggerForBuild(
+  logger: NitroBuildLogger,
+  prefixes: readonly string[] = SUPPRESSED_NITRO_HINT_PREFIXES
+): NitroBuildLogger['success'] {
+  const originalSuccess = logger.success.bind(logger);
+  const wrapped = (message: unknown, ...args: unknown[]) => {
+    if (isSuppressedNitroHint(message, prefixes)) return;
+    originalSuccess(message, ...args);
+  };
+  // Preserve consola LogFn properties (e.g. `.raw`) on the replacement.
+  logger.success = Object.assign(wrapped, logger.success);
+  return originalSuccess;
 }
 
-/** @internal Exported for testing. */
-export function generateNitroPreviewCommand(
-  buildDir: string,
-  preset: NitroPreset
-): NitroPreviewCommand | null {
-  if (!LOCALLY_PREVIEWABLE.has(preset)) return null;
-
-  const nitroDir = join(buildDir, 'nitro');
-  const entryPath = join(nitroDir, 'entry.ts');
-
-  const command = preset === 'bun' ? 'bun' : 'node';
-  return {
-    command,
-    args: [entryPath],
-    cwd: nitroDir,
-  };
+/**
+ * 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.
+ */
+export function getPostBuildHint(preset: NitroPreset): string | null {
+  return LOCALLY_PREVIEWABLE.has(preset)
+    ? 'You can preview this build using `timber preview`'
+    : null;
 }
 
 /**
@@ -605,13 +400,23 @@ export function generateNitroPreviewCommand(
  * Externalizes the timber RSC/SSR output — those files are pre-built
  * by timber and have internal references that nitro's bundler can't follow.
  */
+interface NitroBuildResult {
+  /** Resolved output.serverDir — where the server bundle + _chunks/ live. */
+  serverDir: string;
+}
+
 async function runNitroBuild(
   nitroDir: string,
   preset: NitroPreset,
   userConfig?: Record<string, unknown>
-): Promise<void> {
+): Promise<NitroBuildResult> {
   const presetConfig = PRESET_CONFIGS[preset];
-  const { createNitro, build: nitroBuild, prepare, copyPublicAssets } = await import('nitro/builder');
+  const {
+    createNitro,
+    build: nitroBuild,
+    prepare,
+    copyPublicAssets,
+  } = await import('nitro/builder');
 
   const nitro = await createNitro({
     rootDir: nitroDir,
@@ -623,6 +428,7 @@ async function runNitroBuild(
     output: { dir: join(nitroDir, presetConfig.outputDir) },
     routeRules: {
       '/assets/**': { headers: { 'Cache-Control': IMMUTABLE_CACHE } },
+      '/_timber/fonts/**': { headers: { 'Cache-Control': IMMUTABLE_CACHE } },
     },
     // Don't bundle the timber RSC/SSR build output — it has its own
     // internal file references that nitro's bundler can't follow.
@@ -634,30 +440,85 @@ async function runNitroBuild(
     ...userConfig,
   });
 
+  // Drop nitro's `npx nitro preview` / `npx nitro deploy` hints —
+  // they can never work from the project root (see TIM-1375). Hints whose
+  // command the user explicitly configured via framework.previewCommand /
+  // deployCommand pass through untouched — except on the rollup builder,
+  // which ignores framework commands and unconditionally prints the broken
+  // defaults (nitro/dist/_build/rollup.mjs), so user commands are treated
+  // as absent there: defaults stay suppressed, timber's hint still prints.
+  // logSuccess is the unfiltered fn used below to print timber's hint.
+  const framework = nitro.options.builder === 'rollup' ? undefined : nitro.options.framework;
+  const logSuccess = wrapNitroLoggerForBuild(nitro.logger, selectSuppressedHintPrefixes(framework));
+
+  // Read the resolved serverDir AFTER config merging — userConfig may
+  // override output.dir or output.serverDir. Nitro appends a trailing
+  // slash during resolution; strip it for join() compatibility.
+  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();
-}
 
-/** Spawn a Nitro preview process and pipe stdio. */
-function spawnNitroPreview(command: string, args: string[], cwd: string): Promise<void> {
-  return new Promise<void>((resolve, reject) => {
-    const child = execFile(command, args, { cwd }, (err) => {
-      if (err) reject(err);
-      else resolve();
-    });
-    child.stdout?.pipe(process.stdout);
-    child.stderr?.pipe(process.stderr);
-  });
-}
+  // A user-configured previewCommand already printed via nitro's own hint —
+  // don't print a second, conflicting one.
+  const hint = framework?.previewCommand ? null : getPostBuildHint(preset);
+  if (hint) logSuccess(hint);
 
+  return { serverDir };
+}
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
 /**
- * Get the preset configuration for a given preset name.
+ * 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.
  */
-export function getPresetConfig(preset: NitroPreset): PresetConfig {
-  return PRESET_CONFIGS[preset];
+export function resolvePrebuiltOutputPath(outDir: string, preset: NitroPreset): string {
+  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.
+ */
+export async function copyPrebuiltToVercelFuncClones(
+  functionsDir: string,
+  prebuiltSrc: string,
+  baseFuncName: string
+): Promise<void> {
+  const funcDirs: string[] = [];
+  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: NodeJS.ErrnoException) => {
+          if (e.code !== 'ENOENT') throw e;
+        }
+      )
+    )
+  );
 }