@timber-js/app 0.2.0-alpha.207 → 0.2.0-alpha.209

package/src/adapters/nitro.ts

@@ -5,23 +5,29 @@
 // compression, graceful shutdown, static file serving, and platform quirks.
 // See design/11-platform.md and design/25-production-deployments.md.
 
+import { existsSync } from 'node:fs';
 import { cp, glob, readFile, writeFile } from 'node:fs/promises';
-import { basename, dirname, join } from 'node:path';
+import { basename, dirname, join, relative, sep } from 'node:path';
 import {
   buildStaticDirectoryOutput,
-  findUnhashedStaticFiles,
   runSharedBuildSteps,
   writeHeadersFile,
 } from './build-output-helper.ts';
 import { generateCompressModule } from './compress-module.ts';
+import { generateCanonicalizeModule } from './canonicalize-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';
+import { adapterBase, IMMUTABLE_CACHE } from './shared.ts';
+import type {
+  BuildArtifacts,
+  PreviewTarget,
+  TimberConfig,
+  TimberPlatformAdapter,
+} from './types.ts';
 
 // NitroPreset is part of the public adapter API (NitroAdapterOptions.preset),
 // so it stays importable from this module.
@@ -101,18 +107,30 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
   return {
     name: `nitro-${preset}`,
 
-    async buildOutput(config: TimberConfig, buildDir: string) {
-      const outDir = join(buildDir, 'nitro');
+    async buildOutput(config: TimberConfig, artifacts: BuildArtifacts) {
+      const outDir = join(artifacts.outputDir, 'nitro');
 
       // ── 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');
+      if (artifacts.output === 'static') {
+        await buildStaticDirectoryOutput(config, artifacts, 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));
+        await writeHeadersFile(publicDir, config, artifacts);
+
+        // Local preview serves the site as the build recorded it.
+        await writeFile(join(outDir, CANONICALIZE_MODULE), await generateCanonicalizeModule());
+        await writeFile(
+          join(outDir, PREVIEW_SCRIPT),
+          generatePreviewScript({
+            output: 'static',
+            immutableDirs: artifacts.immutableDirs,
+            base: adapterBase(config),
+            contentTypes: artifacts.contentTypes,
+          })
+        );
 
         // Platform-specific files for static deploy targets.
         const target = options.staticTarget ?? 'generic';
@@ -143,7 +161,7 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
       // write _headers, write manifest-init).
       await runSharedBuildSteps({
         config,
-        buildDir,
+        artifacts,
         outDir,
         publicDirName: 'public',
       });
@@ -156,76 +174,116 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
       // Web→Node response bridge with backpressure. See TIM-1154.
       await writeFile(join(outDir, '_send-response.mjs'), generateSendResponseModule());
 
+      // Standalone preview server for presets with a local runtime. It loads
+      // the build's own RSC bundle — not the copy under nitro/rsc/ — because
+      // the handler reads prebuilt payloads from ../prebuilt beside its
+      // bundle, and the build's prebuilt/ is cleaned every build while
+      // nitro/prebuilt/ is not: a build that captured nothing would otherwise
+      // preview an earlier build's payloads.
+      if (LOCALLY_PREVIEWABLE.has(preset)) {
+        await writeFile(join(outDir, CANONICALIZE_MODULE), await generateCanonicalizeModule());
+        await writeFile(
+          join(outDir, PREVIEW_SCRIPT),
+          generatePreviewScript({
+            output: 'server',
+            runtimeName: PRESET_CONFIGS[preset].runtimeName,
+            rscEntry: importSpecifier(outDir, join(artifacts.rsc.path, 'index.js')),
+            hasManifestInit: !!artifacts.manifestInit,
+            immutableDirs: artifacts.immutableDirs,
+            base: adapterBase(config),
+          })
+        );
+      }
+
       // Prepend the manifest assignment directly into the RSC entry so
       // globalThis.__TIMBER_BUILD_MANIFEST__ is set before any module reads it.
       // This must be top-level code, not an import, because rollup tree-shakes
       // side-effect-only globalThis assignments from imported modules.
-      if (config.manifestInit) {
+      if (artifacts.manifestInit) {
         const rscEntry = join(outDir, 'rsc', 'index.js');
         const rscContent = await readFile(rscEntry, 'utf-8');
-        await writeFile(rscEntry, `${config.manifestInit}\n${rscContent}`);
+        await writeFile(rscEntry, `${artifacts.manifestInit}\n${rscContent}`);
       }
 
       // Generate the Nitro entry point (imports from ./rsc/ within nitro dir)
-      const entry = generateNitroEntry(buildDir, outDir, preset, compress);
+      const entry = generateNitroEntry(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.
-      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
+      const { serverDir } = await runNitroBuild(
+        outDir,
+        preset,
+        artifacts.immutableDirs,
+        options.nitroConfig
+      );
+
+      // Copy prebuilt flight payloads 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);
+      if (artifacts.prebuilt) {
+        const prebuiltSrc = artifacts.prebuilt.path;
+        await cp(prebuiltSrc, join(serverDir, 'prebuilt'), { recursive: true });
+
+        // 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().
-    // Serverless presets (vercel, netlify, aws-lambda, etc.) have no
-    // local runtime — Vite's built-in preview is the fallback.
-    preview: LOCALLY_PREVIEWABLE.has(preset)
-      ? async (_config: TimberConfig, buildDir: string) => {
-          // Generate a standalone preview server that uses Node's built-in
-          // HTTP server. The Nitro entry.ts can't be run directly because
-          // it imports h3 (a Nitro dependency not available at runtime).
-          const previewScript = generatePreviewScript(buildDir, preset);
-          const scriptPath = join(buildDir, 'nitro', '_preview-server.mjs');
-          await writeFile(scriptPath, previewScript);
-
-          const command = preset === 'bun' ? 'bun' : 'node';
-          await spawnNitroPreview(command, [scriptPath], join(buildDir, 'nitro'));
-        }
-      : undefined,
+    // buildOutput wrote the preview server for this build: a static file
+    // server for a static build, and for a server build on a preset with a
+    // local runtime (node-server, bun), one that routes to the RSC handler.
+    // Serverless presets (vercel, netlify, aws-lambda, etc.) have no local
+    // runtime, so a server build on one has nothing to preview.
+    async preview(_config: TimberConfig, { output, outputDir }: PreviewTarget) {
+      if (output === 'server' && !LOCALLY_PREVIEWABLE.has(preset)) {
+        throw new Error(
+          `[timber] The nitro '${preset}' preset has no local runtime, so \`timber preview\` ` +
+            `cannot run its server build. Preview with a node-server build, or with the ` +
+            `platform's own tooling.`
+        );
+      }
+      const nitroDir = join(outputDir, 'nitro');
+      const script = join(nitroDir, PREVIEW_SCRIPT);
+      if (!existsSync(script)) {
+        throw new Error(
+          `[timber] No preview server at ${script}. Run \`timber build\` before \`timber preview\`.`
+        );
+      }
+      // Only a bun server build needs Bun. The static file server uses Node
+      // built-ins, so it runs on the Node already running timber, as does a
+      // node-server build — no PATH lookup for either.
+      const command = output === 'server' && preset === 'bun' ? 'bun' : process.execPath;
+      await spawnNitroPreview(command, [script], nitroDir);
+    },
   };
 }
 
+/** The preview server buildOutput writes into the Nitro output directory. */
+const PREVIEW_SCRIPT = '_preview-server.mjs';
+
+/** The request-path canonicalizer the preview server imports beside it. */
+const CANONICALIZE_MODULE = '_canonicalize.mjs';
+
+/** A relative ESM import specifier for `file`, as imported from a module in `fromDir`. */
+function importSpecifier(fromDir: string, file: string): string {
+  const path = relative(fromDir, file).split(sep).join('/');
+  return path.startsWith('../') ? path : './' + path;
+}
+
 // ─── Entry Generation ────────────────────────────────────────────────────────
 
 /** @internal Exported for testing. */
-export function generateNitroEntry(
-  buildDir: string,
-  outDir: string,
-  preset: NitroPreset,
-  compress = true
-): string {
+export function generateNitroEntry(preset: NitroPreset, 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.
   // The manifest init is prepended to rsc/index.js before the nitro build,
@@ -408,6 +466,7 @@ interface NitroBuildResult {
 async function runNitroBuild(
   nitroDir: string,
   preset: NitroPreset,
+  immutableDirs: readonly string[],
   userConfig?: Record<string, unknown>
 ): Promise<NitroBuildResult> {
   const presetConfig = PRESET_CONFIGS[preset];
@@ -426,10 +485,10 @@ async function runNitroBuild(
     // Using `entry` directly would bypass the Nitro server runtime.
     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 } },
-    },
+    // One rule per content-hashed directory the build recorded.
+    routeRules: Object.fromEntries(
+      immutableDirs.map((dir) => [`/${dir}/**`, { 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.
     // Mark them as external so rollup leaves the imports as-is.
@@ -471,22 +530,6 @@ async function runNitroBuild(
 }
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
-/**
- * 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.
  *
@@ -513,12 +556,6 @@ export async function copyPrebuiltToVercelFuncClones(
     return;
   }
   await Promise.all(
-    funcDirs.map((dir) =>
-      cp(prebuiltSrc, join(dir, 'prebuilt'), { recursive: true }).catch(
-        (e: NodeJS.ErrnoException) => {
-          if (e.code !== 'ENOENT') throw e;
-        }
-      )
-    )
+    funcDirs.map((dir) => cp(prebuiltSrc, join(dir, 'prebuilt'), { recursive: true }))
   );
 }

package/src/adapters/shared.ts

@@ -19,7 +19,7 @@ import { withBasePath } from '../shared/base-path.ts';
  * by callers that predate it (a hand-written adapter, a test harness). Falling
  * back to `'/'` reproduces the pre-TIM-1274 output exactly, which is correct
  * for the only deployments those callers can have: a build under a non-root
- * base always goes through `plugins/adapter-build.ts`, which populates it.
+ * base always goes through `plugins/post-build.ts`, which populates it.
  *
  * Typed structurally rather than as `TimberConfig` so this module keeps no
  * import of `./types.js` at runtime.
@@ -43,7 +43,9 @@ export const STATIC_CACHE = 'public, max-age=3600, must-revalidate';
  * 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
+ * The build's content-hashed directories (`immutableDirs`, recorded on
+ * `BuildArtifacts` by the phases that hashed them) get one wildcard rule
+ * each. 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
@@ -62,13 +64,13 @@ export const STATIC_CACHE = 'public, max-age=3600, must-revalidate';
  * Cloudflare Workers Static Assets without one.
  *
  * The prefix is applied at exactly one point, `rulePath()`, which every rule
- * in this function goes through. Prefixing the three wildcards and
+ * in this function goes through. Prefixing the wildcards and
  * hand-checking that the per-file rules agree is how the next rule gets
  * missed.
  */
-// Cloudflare Workers Static Assets caps _headers at 100 rules.
-// Reserve 3 for the wildcard hashed-asset rules (/assets/*, /_timber/fonts/*, /_rsc/*).
-const MAX_PER_FILE_RULES = 97;
+// Cloudflare Workers Static Assets caps _headers at 100 rules. The wildcard
+// rules for the immutable directories come out of the same budget.
+const MAX_RULES = 100;
 
 export interface HeadersFileOptions {
   /**
@@ -79,6 +81,11 @@ export interface HeadersFileOptions {
    * root-relative rules that match nothing, which is the bug this closes.
    */
   base: string;
+  /**
+   * Content-hashed directories, from `BuildArtifacts.immutableDirs`. Each
+   * gets an immutable `Cache-Control` wildcard rule.
+   */
+  immutableDirs: readonly string[];
   /** Unhashed static files (route-space paths) needing per-file cache rules. */
   unhashedPaths?: string[];
   /** Route-space path → Content-Type, for extensionless API route outputs. */
@@ -154,6 +161,7 @@ function patternsOverlap(a: string, b: string): boolean {
 
 export function generateHeadersFile({
   base,
+  immutableDirs,
   unhashedPaths,
   contentTypes,
   userRules,
@@ -208,24 +216,25 @@ export function generateHeadersFile({
   let content = `# Auto-generated by @timber-js/app — static asset cache headers.
 # See design/25-production-deployments.md §"CDN / Edge Cache"
 `;
-  for (const path of ['/assets/*', '/_timber/fonts/*', '/_rsc/*']) {
-    content += emit(rulePath(path), 'Cache-Control', IMMUTABLE_CACHE);
+  for (const dir of immutableDirs) {
+    content += emit(rulePath(`/${dir}/*`), 'Cache-Control', IMMUTABLE_CACHE);
   }
+  const maxPerFileRules = MAX_RULES - immutableDirs.length;
 
   // Content-Type rules are higher priority than cache headers for
   // extensionless files — without them the file is unreadable.
   const allCtEntries = contentTypes
     ? Object.entries(contentTypes).sort(([a], [b]) => a.localeCompare(b))
     : [];
-  const ctEntries = allCtEntries.slice(0, MAX_PER_FILE_RULES);
-  if (allCtEntries.length > MAX_PER_FILE_RULES) {
+  const ctEntries = allCtEntries.slice(0, maxPerFileRules);
+  if (allCtEntries.length > maxPerFileRules) {
     console.warn(
       `[timber] _headers: ${allCtEntries.length} content-type rules exceed ` +
-        `Cloudflare's 100-rule limit. Only the first ${MAX_PER_FILE_RULES} ` +
+        `Cloudflare's 100-rule limit. Only the first ${maxPerFileRules} ` +
         `extensionless API routes will get Content-Type headers.`
     );
   }
-  const remainingBudget = MAX_PER_FILE_RULES - ctEntries.length;
+  const remainingBudget = maxPerFileRules - ctEntries.length;
 
   if (unhashedPaths && unhashedPaths.length > 0) {
     const capped = unhashedPaths.slice(0, Math.max(0, remainingBudget));
@@ -260,10 +269,10 @@ export function generateHeadersFile({
     content += `\n# User-authored rules from public/_headers\n\n${userRules.trim()}\n`;
 
     const total = countHeaderRules(content);
-    if (total > MAX_PER_FILE_RULES + 3) {
+    if (total > MAX_RULES) {
       console.warn(
         `[timber] _headers: ${total} rules after merging public/_headers, over ` +
-          `Cloudflare's ${MAX_PER_FILE_RULES + 3}-rule limit. Rules past the ` +
+          `Cloudflare's ${MAX_RULES}-rule limit. Rules past the ` +
           `limit are dropped by the platform — remove some, or move static ` +
           `assets under a directory the wildcard rules already cover.`
       );

package/src/adapters/types.ts

@@ -7,6 +7,12 @@
 /**
  * Configuration passed to adapter lifecycle methods.
  * A subset of the resolved timber.config.ts relevant to adapters.
+ *
+ * Configuration only: nothing here is produced by a build phase. What the
+ * build produced — directories, the manifest initialization module, the
+ * static site — arrives separately as {@link BuildArtifacts}, and the output
+ * mode is the discriminant of that union rather than a field here, so an
+ * adapter cannot be handed a static mode with no static site (TIM-1524).
  */
 export interface TimberConfig {
   /** Absolute path to the project root (Vite root). */
@@ -19,40 +25,120 @@ export interface TimberConfig {
    * host matches against the *request* path, so those rules live in deployed-
    * URL space rather than route space and need this prefix (TIM-1274).
    *
-   * Populated by `plugins/adapter-build.ts` from `ctx.base`, the single copy
+   * Populated by `plugins/post-build.ts` from `ctx.base`, the single copy
    * lifted in TIM-1261. Adapters must not re-derive it from `config.base`.
    */
   base?: string;
-  output: 'server' | 'static';
   clientJavascriptDisabled?: boolean;
+}
+
+/** A directory a build phase wrote. */
+export interface DirectoryArtifact {
+  /** Absolute path. Adapters never join it against `outputDir` or `root`. */
+  readonly path: string;
+}
+
+interface BuildArtifactsBase {
   /**
-   * JS module source that sets globalThis.__TIMBER_BUILD_MANIFEST__.
-   * Written by adapters as _timber-manifest-init.js, imported before the RSC handler.
-   * Undefined when no build manifest was produced (e.g., dev mode or no client assets).
+   * The build output directory (`.timber/dist` by default) — where adapters
+   * write their own platform directory (`cloudflare/`, `nitro/`). Not the
+   * project root; that is `TimberConfig.root`.
    */
-  manifestInit?: string;
+  readonly outputDir: string;
   /**
-   * Absolute path to the directory containing pre-rendered static HTML,
-   * RSC flight files, and API route outputs. Present only when
-   * output: 'static' and the static generation pass completed.
-   * Layout: path/index.html, _rsc/path/index.rsc, api-route-path
+   * The browser bundle: client JS, CSS, fonts, and everything Vite copied
+   * out of `public/`. Always produced — with client JavaScript disabled it
+   * still carries the stylesheets and `public/`; adapters drop the `.js`.
    */
-  staticPagesDir?: string;
+  readonly client: DirectoryArtifact;
   /**
-   * Content-Type mappings for extensionless API route outputs.
-   * Map from URL path (e.g. "/api/data") to Content-Type value.
-   * Written during static generation, consumed by adapters when
-   * writing _headers. See TIM-1241.
+   * Directories of the served tree whose every file name carries a content
+   * hash — `'assets'`, `'_timber/fonts'`, and in a static build whose RSC
+   * payloads were hashed, `'_rsc'`. Relative to the site root, `/`-separated,
+   * no leading or trailing slash, and in route space: an adapter writing
+   * platform rules adds the deployment `base` itself.
+   *
+   * Each entry is recorded by the phase that hashed the files — the client
+   * environment from its `build.assetsDir`, the font plugin when it emitted a
+   * binary, static generation when it hashed payloads — so adapters mark
+   * these immutable without knowing which plugin names or hashes what.
    */
-  staticContentTypes?: Record<string, string>;
+  readonly immutableDirs: readonly string[];
+}
+
+/** Build products of an `output: 'server'` build. */
+export interface ServerBuildArtifacts extends BuildArtifactsBase {
+  readonly output: 'server';
+  /** The RSC server bundle. Its `index.js` is the request handler. */
+  readonly rsc: DirectoryArtifact;
+  /**
+   * The SSR bundle. The RSC bundle imports it by a path the RSC plugin
+   * computed between the two build directories — siblings named `rsc/` and
+   * `ssr/` — so adapters deploy them as siblings under those names.
+   */
+  readonly ssr: DirectoryArtifact;
+  /**
+   * `cache.component` flight payloads captured at build time (design/44).
+   * Present only when the capture pass wrote at least one payload.
+   */
+  readonly prebuilt?: DirectoryArtifact;
+  /**
+   * Generated JS module source that sets `globalThis.__TIMBER_BUILD_MANIFEST__`.
+   * Must evaluate before the RSC handler; adapters
+   * write it as `_timber-manifest-init.js` or prepend it to the entry.
+   * Absent when no build manifest was produced.
+   */
+  readonly manifestInit?: string;
+}
+
+/** Build products of an `output: 'static'` build. */
+export interface StaticBuildArtifacts extends BuildArtifactsBase {
+  readonly output: 'static';
+  /**
+   * The pre-rendered site: `path/index.html`, RSC payloads under `_rsc/`
+   * (content-hashed unless client JavaScript is disabled), API route
+   * outputs, `404.html`, and a generated `_redirects` when any redirect was
+   * captured.
+   */
+  readonly pages: DirectoryArtifact;
+  /**
+   * Content-Type for each extensionless API route output, keyed by URL path
+   * (e.g. `/api/data` → `application/json`). Adapters write these as
+   * `_headers` rules; a static host cannot infer them from a file name.
+   * See TIM-1241.
+   */
+  readonly contentTypes: Readonly<Record<string, string>>;
+}
+
+/**
+ * Everything a `timber build` produced, as the adapter consumes it.
+ *
+ * Each field is recorded by the phase that wrote it. The two optional fields
+ * are the two products a build can legitimately lack — `prebuilt` (nothing
+ * captured) and `manifestInit` (no build manifest) — and adapters branch on
+ * their presence (`if (artifacts.prebuilt)`) rather than probing the
+ * filesystem.
+ */
+export type BuildArtifacts = ServerBuildArtifacts | StaticBuildArtifacts;
+
+/**
+ * What `timber preview` asks an adapter to serve. Preview runs in a later
+ * process with no build in memory, so it gets the output directory and the
+ * configured mode rather than {@link BuildArtifacts}; the mode is what tells
+ * an adapter whether a server entry exists to run at all.
+ */
+export interface PreviewTarget {
+  readonly output: 'server' | 'static';
+  /** The build output directory `buildOutput` wrote its platform directory into. */
+  readonly outputDir: string;
 }
 
 /**
  * The formal adapter interface. An adapter transforms the build output
  * into a deployable artifact for a specific platform.
  *
- * Adapters are small: they receive the build output directory and
- * transform or copy it into whatever shape the platform expects.
+ * Adapters are small: they receive a description of what the build
+ * produced and transform or copy it into whatever shape the platform expects.
  */
 export interface TimberPlatformAdapter {
   /** Unique adapter name (e.g. 'cloudflare', 'node', 'bun'). */
@@ -62,13 +148,16 @@ export interface TimberPlatformAdapter {
    * Transform the build output for the target platform.
    * Called at the end of `timber build`.
    */
-  buildOutput(config: TimberConfig, buildDir: string): Promise<void>;
+  buildOutput(config: TimberConfig, artifacts: BuildArtifacts): Promise<void>;
 
   /**
    * Start a local preview server for the built output.
-   * Falls back to the built-in Node.js preview server if not provided.
+   * Falls back to Vite's preview server if not provided.
+   *
+   * Runs in a later process than the build (`timber preview`); see
+   * {@link PreviewTarget}.
    */
-  preview?(config: TimberConfig, buildDir: string): Promise<void>;
+  preview?(config: TimberConfig, target: PreviewTarget): Promise<void>;
 
   /**
    * Send 103 Early Hints to the client before the final response.

package/src/analyze/graph-cache.ts

@@ -22,10 +22,11 @@
 
 import { createHash } from 'node:crypto';
 import { createRequire } from 'node:module';
-import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, stat } from 'node:fs/promises';
 import { dirname, isAbsolute, join } from 'node:path';
 import { buildSourceExtensions, scanProjectSourceFiles } from './scan.ts';
 import type { CrawlReport } from './crawl.ts';
+import { writeFileAtomic } from '../utils/write-file-atomic.ts';
 
 /**
  * JSON contract version (design/47 §9) — one constant for every
@@ -326,7 +327,5 @@ export async function readGraphCache(root: string): Promise<GraphCacheFile | nul
 export async function writeGraphCache(root: string, cache: GraphCacheFile): Promise<void> {
   const target = join(root, CACHE_RELATIVE_PATH);
   await mkdir(dirname(target), { recursive: true });
-  const temp = `${target}.${process.pid}.tmp`;
-  await writeFile(temp, JSON.stringify(cache));
-  await rename(temp, target);
+  await writeFileAtomic(target, JSON.stringify(cache));
 }

package/src/cache/json-lossy-check.ts

@@ -1,3 +1,5 @@
+import { logLossyCacheValue } from '../server/logger.ts';
+
 const LOSSY_TYPES = ['Date', 'Map', 'Set', 'BigInt'] as const;
 
 let hasWarned = false;
@@ -17,15 +19,7 @@ export function warnLossyJsonValue(value: unknown, cacheKey: string): void {
   if (lossy.size === 0) return;
 
   hasWarned = true;
-  const types = [...lossy].join(', ');
-  console.warn(
-    `[timber] cache value for key "${cacheKey}" contains ${types} — ` +
-      'these types lose fidelity through JSON serialization in Redis/KV cache handlers. ' +
-      'Date becomes an ISO string, Map/Set become {}, BigInt throws. ' +
-      'The MemoryCacheHandler preserves them. Consider transforming values ' +
-      'to JSON-safe types before caching, or use MemoryCacheHandler for ' +
-      'values that require type preservation.'
-  );
+  logLossyCacheValue({ cacheKey, types: [...lossy].join(', ') });
 }
 
 function findLossyTypes(value: unknown, seen: Set<unknown>, depth: number): Set<string> {

package/src/cache/singleflight.ts

@@ -52,8 +52,11 @@ export function createSingleflight(opts?: SingleflightOptions): Singleflight {
         // side effects (e.g. cache writes). See TIM-1092.
         promise = new Promise<T>((resolve, reject) => {
           const timer = setTimeout(() => {
-            ac.abort();
-            reject(new SingleflightTimeoutError(key, timeoutMs));
+            // The timeout error is also the signal's reason, so the body
+            // can tell why it was aborted (runBackgroundFlight reports it).
+            const timeout = new SingleflightTimeoutError(key, timeoutMs);
+            ac.abort(timeout);
+            reject(timeout);
           }, timeoutMs);
           try {
             fn(ac.signal).then(

package/src/cache/sizeof.ts

@@ -13,6 +13,8 @@
  * to cache and undercount than to reject the entry.
  */
 
+import { swallow } from '../server/logger.ts';
+
 /**
  * Estimate the byte size of a value.
  *
@@ -27,7 +29,7 @@ export function estimateByteSize(value: unknown): number {
     return json.length * 2;
   } catch (e) {
     // Circular reference or non-serializable value
-    console.debug('[timber] sizeof estimation failed:', e instanceof Error ? e.message : e);
+    swallow(e, 'sizeof estimation failed', { level: 'debug' });
     return 0;
   }
 }