@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.181

package/src/adapters/nitro.ts

@@ -5,28 +5,13 @@
 // 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 { writeFile, readFile, cp, glob } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
-import { join, relative } from 'node:path';
+import { join, relative, dirname, basename } 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 { IMMUTABLE_CACHE } from './shared.js';
+import { runSharedBuildSteps } from './build-output-helper.js';
 
 // ─── Presets ─────────────────────────────────────────────────────────────────
 
@@ -53,6 +38,12 @@ interface PresetConfig {
   nitroPreset: string;
   /** Output directory name within the build dir. */
   outputDir: string;
+  /**
+   * Path to the server bundle directory relative to outputDir.
+   * Nitro places the bundled server entry + _chunks/ here.
+   * Most presets use `server`; Vercel uses `functions/__server.func`.
+   */
+  serverBundleDir: string;
   /** Whether the runtime supports waitUntil. */
   supportsWaitUntil: boolean;
   /** Whether the runtime supports application-level 103 Early Hints. */
@@ -67,6 +58,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'vercel': {
     nitroPreset: 'vercel',
     outputDir: '.vercel/output',
+    serverBundleDir: 'functions/__server.func',
     supportsWaitUntil: true,
     supportsEarlyHints: false,
     runtimeName: 'vercel',
@@ -75,6 +67,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'vercel-edge': {
     nitroPreset: 'vercel-edge',
     outputDir: '.vercel/output',
+    serverBundleDir: 'functions/__server.func',
     supportsWaitUntil: true,
     supportsEarlyHints: false,
     runtimeName: 'vercel-edge',
@@ -82,6 +75,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'netlify': {
     nitroPreset: 'netlify',
     outputDir: '.netlify/functions-internal',
+    serverBundleDir: 'server',
     supportsWaitUntil: false,
     supportsEarlyHints: false,
     runtimeName: 'netlify',
@@ -89,6 +83,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'netlify-edge': {
     nitroPreset: 'netlify-edge',
     outputDir: '.netlify/edge-functions',
+    serverBundleDir: 'server',
     supportsWaitUntil: true,
     supportsEarlyHints: false,
     runtimeName: 'netlify-edge',
@@ -96,6 +91,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'aws-lambda': {
     nitroPreset: 'aws-lambda',
     outputDir: '.output',
+    serverBundleDir: 'server',
     supportsWaitUntil: false,
     supportsEarlyHints: false,
     runtimeName: 'aws-lambda',
@@ -103,6 +99,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'deno-deploy': {
     nitroPreset: 'deno-deploy',
     outputDir: '.output',
+    serverBundleDir: 'server',
     supportsWaitUntil: true,
     supportsEarlyHints: false,
     runtimeName: 'deno-deploy',
@@ -110,6 +107,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'azure-functions': {
     nitroPreset: 'azure-functions',
     outputDir: '.output',
+    serverBundleDir: 'server',
     supportsWaitUntil: false,
     supportsEarlyHints: false,
     runtimeName: 'azure-functions',
@@ -117,6 +115,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'node-server': {
     nitroPreset: 'node-server',
     outputDir: '.output',
+    serverBundleDir: 'server',
     supportsWaitUntil: true,
     // Disabled by default: most node-server deployments sit behind a
     // reverse proxy (nginx, caddy, traefik) that doesn't support 103
@@ -131,6 +130,7 @@ const PRESET_CONFIGS: Record<NitroPreset, PresetConfig> = {
   'bun': {
     nitroPreset: 'bun',
     outputDir: '.output',
+    serverBundleDir: 'server',
     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.
@@ -195,46 +195,28 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
   const preset = options.preset ?? 'node-server';
   const compress = options.compress ?? true;
   const presetConfig = PRESET_CONFIGS[preset];
-  const pendingPromises: Promise<unknown>[] = [];
-
   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());
 
-      // Write the build manifest init module (if manifest data was produced).
-      if (config.manifestInit) {
-        await writeFile(join(outDir, '_timber-manifest-init.js'), config.manifestInit);
-      }
+      // 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 the compression helper module for runtime use.
+      // 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.
@@ -253,7 +235,29 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
       // 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().
@@ -272,15 +276,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,
   };
 }
 
@@ -291,8 +286,7 @@ export function generateNitroEntry(
   buildDir: string,
   outDir: string,
   preset: NitroPreset,
-  compress = true,
-  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.
@@ -349,11 +343,6 @@ 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' : '';
 
@@ -363,7 +352,7 @@ export function generateNitroEntry(
   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 handler, { runWithEarlyHintsSender${waitUntilImport} } from '${serverEntryRelative}'
 ${compressImport}
 // Set TIMBER_RUNTIME for instrumentation.ts conditional SDK initialization.
 // See design/25-production-deployments.md §"TIMBER_RUNTIME".
@@ -383,37 +372,6 @@ ${handlerCall}
 `;
 }
 
-/** @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,
-  };
-
-  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'
-
-export default defineNitroConfig(${configJson})
-`;
-}
-
 // ─── Preview ─────────────────────────────────────────────────────────────────
 
 /** Presets that produce a locally-runnable server entry. */
@@ -460,6 +418,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',
@@ -486,11 +447,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);
@@ -503,7 +485,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, {
@@ -560,22 +544,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) {
@@ -585,13 +558,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);
+}
 `;
 }
 
@@ -626,11 +635,16 @@ 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,
@@ -649,6 +663,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.
@@ -660,10 +675,18 @@ async function runNitroBuild(
     ...userConfig,
   });
 
+  // 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();
+
+  return { serverDir };
 }
 
 /** Spawn a Nitro preview process and pipe stdio. */
@@ -678,6 +701,75 @@ function spawnNitroPreview(command: string, args: string[], cwd: string): Promis
   });
 }
 
+// ─── Send Response Module ───────────────────────────────────────────────────
+
+/**
+ * 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.
+ */
+export function generateSendResponseModule(): string {
+  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);
+  });
+}
+`;
+}
+
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
 /**
@@ -687,3 +779,55 @@ function spawnNitroPreview(command: string, args: string[], cwd: string): Promis
 export function getPresetConfig(preset: NitroPreset): PresetConfig {
   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.
+ */
+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;
+        }
+      )
+    )
+  );
+}

package/src/adapters/raw-imports.d.ts

@@ -0,0 +1,5 @@
+// Vite ?raw import — embeds a file as a string at build time.
+declare module '*?raw' {
+  const content: string;
+  export default content;
+}

package/src/adapters/shared.ts

@@ -0,0 +1,68 @@
+// Shared adapter utilities — leaf module with zero deps on server/, client/,
+// or any Vite-dependent code.
+//
+// Adapters are loaded by Node at Vite startup time, before Vite's module
+// resolver is available. This module uses only Node built-ins and can be
+// imported by both adapters via a relative path.
+//
+// IMPORTANT: Do NOT add imports from ../server/, ../client/, ../plugins/,
+// or any module that transitively depends on Vite. A test in
+// tests/adapters/shared-no-forbidden-imports.test.ts enforces this.
+
+// ─── Static asset cache headers ──────────────────────────────────────────
+
+/** Cache-Control value for hashed (immutable) assets. */
+export const IMMUTABLE_CACHE = 'public, max-age=31536000, immutable';
+
+/** Cache-Control value for unhashed static assets. */
+export const STATIC_CACHE = 'public, max-age=3600, must-revalidate';
+
+/**
+ * Generate a `_headers` file for static asset cache control.
+ *
+ * The `_headers` file is a platform convention supported by Cloudflare Workers
+ * Static Assets, Cloudflare Pages, and Netlify. It maps URL patterns to
+ * HTTP response headers.
+ *
+ * Only hashed (immutable) asset paths are listed here by default. When
+ * `unhashedPaths` is provided, per-file rules are appended for unhashed
+ * static assets (favicon.ico, robots.txt, etc.) so they get Cache-Control
+ * on platforms like Cloudflare Workers Static Assets where the server
+ * handler never sees static file requests.
+ *
+ * A `/*` catch-all is NOT used — it would be additive on Cloudflare,
+ * producing duplicate Cache-Control directives on hashed assets
+ * (invalid per RFC 9111).
+ */
+// Cloudflare Workers Static Assets caps _headers at 100 rules.
+// Reserve 2 for the wildcard hashed-asset rules.
+const MAX_UNHASHED_RULES = 98;
+
+export function generateHeadersFile(unhashedPaths?: string[]): string {
+  let content = `# Auto-generated by @timber-js/app — static asset cache headers.
+# See design/25-production-deployments.md §"CDN / Edge Cache"
+
+/assets/*
+  Cache-Control: ${IMMUTABLE_CACHE}
+
+/_timber/fonts/*
+  Cache-Control: ${IMMUTABLE_CACHE}
+`;
+
+  if (unhashedPaths && unhashedPaths.length > 0) {
+    const capped = unhashedPaths.slice(0, MAX_UNHASHED_RULES);
+    if (unhashedPaths.length > MAX_UNHASHED_RULES) {
+      console.warn(
+        `[timber] _headers: ${unhashedPaths.length} unhashed static files found, ` +
+          `but Cloudflare limits _headers to 100 rules. Only the first ${MAX_UNHASHED_RULES} ` +
+          `unhashed files will get Cache-Control headers.`
+      );
+    }
+    content += `\n# Unhashed static assets — short-lived cache with revalidation\n`;
+    for (const p of capped) {
+      content += `\n${p}\n  Cache-Control: ${STATIC_CACHE}\n`;
+    }
+  }
+
+  return content;
+}