@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/src/index.ts

@@ -1,371 +1,426 @@
+/**
+ * @timber-js/app — Root entry point (public API).
+ *
+ * User-facing exports: timber(), defineConfig(), TimberUserConfig, Routes.
+ *
+ * Internal helpers (PluginContext, resolveAppDir, loadTimberConfigFile,
+ * warnConfigConflicts, resolveClientJavascript) live in plugin-context.ts
+ * and are NOT re-exported here. Sub-plugins import them via relative paths.
+ *
+ * Design doc: 18-build-system.md §"Plugin Architecture"
+ */
+
 import type { Plugin, PluginOption } from 'vite';
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import type { ReactCompilerOptions } from '@vitejs/plugin-react';
+import { createLogger } from 'vite';
+import { join, relative, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 import react from '@vitejs/plugin-react';
-import { cacheTransformPlugin } from './plugins/cache-transform';
-import { timberContent } from './plugins/content';
-import { timberDevServer } from './plugins/dev-server';
-import { timberEntries } from './plugins/entries';
-import { timberMdx } from './plugins/mdx';
-import { timberRouting } from './plugins/routing';
-import { timberShims } from './plugins/shims';
-import { timberFonts } from './plugins/fonts';
-import { timberStaticBuild } from './plugins/static-build';
-import { timberDynamicTransform } from './plugins/dynamic-transform';
-import { timberServerActionExports } from './plugins/server-action-exports';
-import { timberBuildManifest } from './plugins/build-manifest';
-import { timberDevLogs } from './plugins/dev-logs';
-import { timberReactProd } from './plugins/react-prod';
-import { timberChunks } from './plugins/chunks';
-import { timberServerBundle } from './plugins/server-bundle';
-import { timberAdapterBuild } from './plugins/adapter-build';
-import { timberBuildReport } from './plugins/build-report';
-import type { RouteTree } from './routing/types';
-import type { BuildManifest } from './server/build-manifest';
-import type { StartupTimer } from './utils/startup-timer';
-import { createStartupTimer, createNoopTimer } from './utils/startup-timer';
-
-/** Configuration for client-side JavaScript output. */
-export interface ClientJavascriptConfig {
-  /** When true, no client JS bundles are emitted or referenced in HTML. */
-  disabled: boolean;
-  /**
-   * When `disabled` is true, still inject the Vite HMR client in dev mode
-   * so hot reloading works during development. Default: true.
-   */
-  enableHMRInDev?: boolean;
-}
+import { timberContent } from './plugins/content.ts';
+import { timberDevServer } from './plugins/dev-server.ts';
+import { timberEntries, BROWSER_ENTRY_FILE } from './plugins/entries.ts';
+import { timberMdx } from './plugins/mdx.ts';
+import { timberRouting } from './plugins/routing.ts';
+import { timberShims } from './plugins/shims.ts';
+import { timberFonts } from './plugins/fonts.ts';
+import { timberStaticBuild } from './plugins/static-build.ts';
+import { timberBuildManifest } from './plugins/build-manifest.ts';
+import { timberDevLogs, originalConsole, wrapLoggerWithOriginalConsole } from './dev-tools/logs.ts';
+import { resolveForwardConsole } from './dev-tools/browser-logs.ts';
+import { timberReactProd } from './plugins/react-prod.ts';
+import { timberReactResolve } from './plugins/react-resolve.ts';
+import { timberChunks } from './plugins/chunks.ts';
+import { clientChunkGroup } from './plugins/client-chunks.ts';
+import { timberServerBundle } from './plugins/server-bundle.ts';
+import { timberCacheTransform } from './plugins/cache.ts';
+import { timberRequestDep } from './plugins/request-dep/index.ts';
+import { timberPrebuilt } from './plugins/prebuilt.ts';
+import { timberPrerenderSugar } from './plugins/prerender-sugar.ts';
+import { timberCloudflareWasm } from './plugins/cloudflare-wasm.ts';
+import { timberPostBuild } from './plugins/post-build.ts';
+import { timberBuildReport } from './plugins/build-report.ts';
+import { createNoopTimer } from './utils/startup-timer.ts';
+import {
+  validateConfig,
+  reportConfigErrors,
+  checkPeerDependencies,
+  formatMissingPeers,
+} from './config-validation.ts';
+import {
+  resolveEncryptionKeyExpression,
+  shouldEnableEncryption,
+} from './server/action-encryption.ts';
+import { createHoldingServer } from './dev-tools/holding-server.ts';
+import { resolveStartPort } from './server/port-resolution.ts';
+import type { TimberUserConfig } from './config-types.ts';
+import type { PluginContext, TimberPluginApi } from './plugin-context.ts';
+import {
+  createPluginContext,
+  loadTimberConfigFile,
+  mergeFileConfig,
+  resolveAppDir,
+  resolveClientJavascript,
+  resolveBuildDir,
+} from './plugin-context.ts';
 
-/** Fully resolved client JavaScript configuration (no optionals). */
-export interface ResolvedClientJavascript {
-  disabled: boolean;
-  enableHMRInDev: boolean;
-}
+// ── Public API ────────────────────────────────────────────────────────────
 
-export interface TimberUserConfig {
-  output?: 'server' | 'static';
-  /**
-   * Enable timber debug logging in production builds.
-   *
-   * When `true`, timber's own diagnostics (dev warnings, verbose logging)
-   * are active even in production mode. React stays in production mode —
-   * only timber's logs are affected.
-   *
-   * Can also be enabled at runtime via the `TIMBER_DEBUG` environment variable.
-   *
-   * Default: `false`.
-   */
-  debug?: boolean;
-  /**
-   * Control client-side JavaScript output.
-   *
-   * Boolean shorthand:
-   *   `clientJavascript: false` disables all client JS (equivalent to `{ disabled: true }`).
-   *   `clientJavascript: true` enables client JS (the default).
-   *
-   * Object form:
-   *   `clientJavascript: { disabled: true, enableHMRInDev: true }` disables client JS
-   *   in production but preserves Vite HMR in dev mode.
-   *
-   * When `disabled` is true, `enableHMRInDev` defaults to `true`.
-   * Server-side JS still runs — this only affects what is sent to the browser.
-   */
-  clientJavascript?: boolean | ClientJavascriptConfig;
-  adapter?: unknown;
-  cacheHandler?: unknown;
-  allowedOrigins?: string[];
-  csrf?: boolean;
-  limits?: {
-    actionBodySize?: string;
-    uploadBodySize?: string;
-    maxFields?: number;
-  };
-  pageExtensions?: string[];
-  /**
-   * Slow request threshold in milliseconds. Requests exceeding this emit
-   * a warning via the logger. Set to 0 to disable. Default: 3000.
-   *
-   * See design/17-logging.md §"slowRequestMs".
-   */
-  slowRequestMs?: number;
-  /** Dev-mode options. These have no effect in production builds. */
-  dev?: {
-    /** Threshold in ms to highlight slow phases in dev logging output. Default: 200. */
-    slowPhaseMs?: number;
-  };
-  /**
-   * Cookie signing configuration. See design/29-cookies.md §"Signed Cookies".
-   *
-   * Provide `secret` for a single key, or `secrets` (array) for key rotation.
-   * When `secrets` is used, index 0 is the signing key; all are tried for verification.
-   */
-  cookies?: {
-    /** Single signing secret. Shorthand for `secrets: [secret]`. */
-    secret?: string;
-    /** Array of signing secrets for key rotation. Index 0 signs; all verify. */
-    secrets?: string[];
-  };
-  /**
-   * Control Server-Timing header output.
-   *
-   * - `'detailed'` — per-phase breakdown (proxy, middleware, render). Useful
-   *   for APM / network monitoring. Exposes phase names to clients.
-   * - `'total'` — single `total;dur=N` entry. Safe to expose, gives
-   *   browser DevTools useful timing without internal details.
-   * - `false` — no Server-Timing header at all.
-   *
-   * Default: `'detailed'` in dev, `'total'` in production.
-   *
-   * This is separate from `debug` / `TIMBER_DEBUG` — it's an intentional
-   * decision to expose timing data to clients, not a side effect of debug
-   * logging.
-   */
-  serverTiming?: 'detailed' | 'total' | false;
-  /**
-   * Override the app directory location. By default, timber auto-detects
-   * `app/` at the project root, falling back to `src/app/`.
-   *
-   * Set this to a relative path from the project root (e.g. `'src/app'`)
-   * to use a custom location.
-   */
-  appDir?: string;
-  /** MDX compilation options passed to @mdx-js/rollup. See design/20-content-collections.md. */
-  mdx?: {
-    remarkPlugins?: unknown[];
-    rehypePlugins?: unknown[];
-    recmaPlugins?: unknown[];
-    remarkRehypeOptions?: Record<string, unknown>;
-  };
-  /**
-   * Built-in top-loader progress bar for client navigations.
-   * Shows an animated bar at the top of the viewport during RSC navigations.
-   * Enabled by default — set `enabled: false` to opt out.
-   *
-   * Users who want a fully custom progress indicator should disable this
-   * and use `useNavigationPending()` directly.
-   *
-   * See LOCAL-336 for design decisions.
-   */
-  topLoader?: {
-    /** Whether the top-loader is enabled. Default: true. */
-    enabled?: boolean;
-    /** Bar color. Default: '#2299DD'. */
-    color?: string;
-    /** Bar height in pixels. Default: 3. */
-    height?: number;
-    /** Show subtle glow/shadow effect. Default: true. */
-    shadow?: boolean;
-    /** Delay in ms before showing the bar (avoids flash on fast navs). Default: 0. */
-    delay?: number;
-    /** CSS z-index. Default: 1600. */
-    zIndex?: number;
-  };
-}
+export type { TimberUserConfig } from './config-types.ts';
+
+// Metadata route handler types — re-exported so user-authored metadata
+// route files (sitemap.ts, robots.ts, manifest.ts, icon.tsx, etc.) can
+// import them from the package root without reaching into ./server.
+// The canonical location for these types is '@timber-js/app/server'; this
+// root re-export is a convenience for typed metadata route handlers.
+// See design/16-metadata.md §"Metadata Routes".
+export type { Metadata, MetadataRoute, MetadataHandler, MetadataResult } from './server/types.ts';
 
 /**
- * Resolve `clientJavascript` into a fully resolved config.
+ * Route map interface — augmented by the generated timber-routes.d.ts.
+ *
+ * Each key is a route path pattern. Values have:
+ *   segmentParams: shape of URL segment params (e.g. { id: string })
+ *
+ * There is no `searchParams` member: since TIM-1343 the framework does not
+ * scan for search-param definitions, so it has nothing to type them with. A
+ * definition carries its own type to call sites through an ordinary import.
+ *
+ * This interface is empty by default and populated via codegen.
+ * See design/09-typescript.md §"Typed Routes".
  */
-export function resolveClientJavascript(config: TimberUserConfig): ResolvedClientJavascript {
-  if (config.clientJavascript !== undefined) {
-    if (typeof config.clientJavascript === 'boolean') {
-      // `clientJavascript: false` → disabled
-      // `clientJavascript: true` → enabled (default)
-      return {
-        disabled: !config.clientJavascript,
-        enableHMRInDev: !config.clientJavascript, // default true when disabled
-      };
-    }
-    // Object form
-    return {
-      disabled: config.clientJavascript.disabled,
-      enableHMRInDev: config.clientJavascript.enableHMRInDev ?? config.clientJavascript.disabled,
-    };
-  }
-
-  // Default: client JS enabled
-  return { disabled: false, enableHMRInDev: false };
-}
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type, typescript/no-empty-interface
+export interface Routes {}
 
 /**
- * Shared context object passed to all sub-plugins via closure.
+ * Type-safe helper for timber.config.ts files.
+ *
+ * A pass-through identity function that provides autocomplete and
+ * type checking for timber configuration. No runtime validation —
+ * purely a DX convenience (same pattern as Vite's defineConfig).
+ *
+ * @example
+ * ```ts
+ * // timber.config.ts
+ * import { defineConfig } from '@timber-js/app';
  *
- * Sub-plugins communicate through this context — not through Vite's
- * plugin API or global state.
- * See design/18-build-system.md §"Shared Plugin Context".
+ * export default defineConfig({
+ *   output: 'server',
+ *   pageExtensions: ['tsx', 'ts', 'mdx'],
+ * });
+ * ```
  */
-export interface PluginContext {
-  config: TimberUserConfig;
-  /** Resolved client JavaScript configuration */
-  clientJavascript: ResolvedClientJavascript;
-  /** The scanned route tree (populated by timber-routing, consumed by timber-entries) */
-  routeTree: RouteTree | null;
-  /** Absolute path to the app/ directory */
-  appDir: string;
-  /** Absolute path to the project root */
-  root: string;
-  /** Whether the dev server is running (set by timber-root-sync in configResolved) */
-  dev: boolean;
-  /** CSS build manifest (populated by adapter after client build, null in dev) */
-  buildManifest: BuildManifest | null;
-  /** Startup timer for profiling cold start phases (active in dev, no-op in prod) */
-  timer: StartupTimer;
+export function defineConfig(config: TimberUserConfig): TimberUserConfig {
+  return config;
 }
 
+// ── Private helpers ───────────────────────────────────────────────────────
+
 /**
- * Resolve the app directory. Checks (in order):
- * 1. Explicit `configAppDir` from timber.config.ts
- * 2. `<root>/app`
- * 3. `<root>/src/app`
+ * Build the options object for @vitejs/plugin-rsc.
  *
- * Throws if none exist.
+ * Uses a getter for `enableActionEncryption` so the RSC plugin reads
+ * the value lazily — after ctx.dev is set in configResolved. This lets
+ * `actionEncryption.disableInDev` work correctly even though the RSC
+ * plugin is created before Vite resolves the command.
  */
-export function resolveAppDir(root: string, configAppDir?: string): string {
-  if (configAppDir) {
-    const explicit = join(root, configAppDir);
-    if (!existsSync(explicit)) {
-      throw new Error(`[timber] Configured appDir "${configAppDir}" does not exist at ${explicit}`);
-    }
-    return explicit;
-  }
+function createRscOptions(
+  ctx: PluginContext,
+  encryptionKeyExpr: string | undefined
+): Record<string, unknown> {
+  const options: Record<string, unknown> = {
+    serverHandler: false,
+    customClientEntry: true,
+    entries: {
+      rsc: 'virtual:timber-rsc-entry',
+      ssr: 'virtual:timber-ssr-entry',
+      client: 'virtual:timber-browser-entry',
+    },
+    // Group client references by layout boundary to balance route-scoped code
+    // splitting with HTTP request count. A constant group name ('client-refs')
+    // would collapse all routes into one chunk — any page downloads every
+    // client component. Per-serverChunk grouping creates many sub-500B files.
+    // Layout-boundary grouping is the middle ground: components under the same
+    // layout segment share a chunk. See design/27-chunking-strategy.md, TIM-440, TIM-499.
+    clientChunks: (meta: { id: string; normalizedId: string; serverChunk: string }) =>
+      clientChunkGroup(meta, ctx.appDir, ctx.root, ctx.sharedModuleFacades),
+  };
 
-  const rootApp = join(root, 'app');
-  if (existsSync(rootApp)) return rootApp;
+  // Bound args encryption — AES-256-GCM authenticated encryption for
+  // closure variables in 'use server' functions. Always on in production,
+  // configurable in dev. See design/08-forms-and-actions.md §"Bound Args Encryption".
+  //
+  // Uses a getter so the RSC plugin reads the value lazily in its transform
+  // hooks, after ctx.dev is set in configResolved. This lets disableInDev
+  // work correctly — ctx.dev is false at construction time but true during
+  // dev server transforms.
+  Object.defineProperty(options, 'enableActionEncryption', {
+    get() {
+      return shouldEnableEncryption(ctx.dev, ctx.config.actionEncryption);
+    },
+    enumerable: true,
+  });
 
-  const srcApp = join(root, 'src', 'app');
-  if (existsSync(srcApp)) return srcApp;
+  // When TIMBER_ACTIONS_ENCRYPTION_KEY is set, pass it as a runtime expression
+  // so the RSC plugin uses it instead of auto-generating a per-build key.
+  if (encryptionKeyExpr) {
+    options.defineEncryptionKey = encryptionKeyExpr;
+  }
 
-  throw new Error(
-    `[timber] Could not find app directory. Expected "app/" or "src/app/" in ${root}. ` +
-      `You can set appDir in timber.config.ts to specify a custom location.`
-  );
+  return options;
 }
 
-function createPluginContext(config?: TimberUserConfig, root?: string): PluginContext {
-  const projectRoot = root ?? process.cwd();
-  const resolvedConfig: TimberUserConfig = { output: 'server', ...config };
-  // Timer starts as active — swapped to noop in configResolved for production builds
-  return {
-    config: resolvedConfig,
-    clientJavascript: resolveClientJavascript(resolvedConfig),
-    routeTree: null,
-    appDir: join(projectRoot, 'app'),
-    root: projectRoot,
-    dev: false,
-    buildManifest: null,
-    timer: createStartupTimer(),
-  };
-}
+// NOTE: 'use cache' directive transform removed — future feature pending design doc.
+// The timber.cache() API (createCache) remains available for explicit caching.
+// See design/06-caching.md.
 
-/**
- * Load timber.config.ts (or .js, .mjs) from the project root.
- * Returns the config object or null if no config file is found.
- */
-async function loadTimberConfigFile(root: string): Promise<TimberUserConfig | null> {
-  const configNames = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];
-
-  for (const name of configNames) {
-    const configPath = join(root, name);
-    if (existsSync(configPath)) {
-      const mod = await import(pathToFileURL(configPath).href);
-      return (mod.default ?? mod) as TimberUserConfig;
-    }
-  }
-  return null;
-}
+// ── Main plugin factory ──────────────────────────────────────────────────
 
 /**
- * Detect config keys set in both inline (vite.config.ts) and file (timber.config.ts)
- * and warn the user. The `output` key is excluded because it defaults to 'server'
- * in createPluginContext and would always appear as an inline key.
+ * Create the timber Vite plugin array.
+ *
+ * Loads timber.config.ts and all dependencies synchronously before
+ * constructing the plugin array. This ensures ALL plugins — including
+ * the RSC plugin and React Compiler — see the fully merged config
+ * (inline + file-based). No async, no deferred config, no stale reads.
  *
- * Returns the list of conflicting key names (for testing).
+ * Requires Node >= 22.12 for synchronous require() of ESM modules
+ * (@vitejs/plugin-rsc is ESM-only).
+ *
+ * Previous versions used async loading and deferred config merging,
+ * causing file-based config for reactCompiler, actionEncryption, and
+ * output mode to be silently ignored. See TIM-451.
  */
-export function warnConfigConflicts(
-  inline: TimberUserConfig,
-  fileConfig: TimberUserConfig
-): string[] {
-  const conflicts: string[] = [];
-  for (const key of Object.keys(fileConfig) as (keyof TimberUserConfig)[]) {
-    if (key === 'output') continue;
-    if (key in inline && inline[key] !== undefined) {
-      conflicts.push(key);
-    }
-  }
-  if (conflicts.length > 0) {
-    console.warn(
-      `[timber] Config conflict: ${conflicts.map((k) => `"${k}"`).join(', ')} set in both ` +
-        `vite.config.ts (inline) and timber.config.ts. ` +
-        `Move all config to timber.config.ts to avoid confusion. ` +
-        `The inline value from vite.config.ts will be used.`
-    );
-  }
-  return conflicts;
-}
-
 /**
- * Merge file-based config into ctx.config. Inline config (already in ctx.config)
- * takes precedence — file config only fills in missing fields.
+ * Wrap plugin-react's `vite:react-compiler` configResolved so it always
+ * sees `isProduction: true` during builds. The compiler plugin uses
+ * `!config.isProduction` to decide whether to emit jsxDEV calls, but
+ * Vite derives isProduction from process.env.NODE_ENV — which may be
+ * "development" in the shell. Rather than mutating the env, we pass a
+ * prototype-based view with the single property overridden.
  */
-function mergeFileConfig(ctx: PluginContext, fileConfig: TimberUserConfig): void {
-  const inline = ctx.config;
-
-  // Warn if the same key is set in both places
-  warnConfigConflicts(inline, fileConfig);
-
-  // For each top-level key, use inline value if present, otherwise file value
-  ctx.config = {
-    ...fileConfig,
-    ...inline,
-    // Deep merge for nested objects where both exist
-    ...(fileConfig.limits && inline.limits
-      ? { limits: { ...fileConfig.limits, ...inline.limits } }
-      : {}),
-    ...(fileConfig.dev && inline.dev ? { dev: { ...fileConfig.dev, ...inline.dev } } : {}),
-    ...(fileConfig.mdx && inline.mdx ? { mdx: { ...fileConfig.mdx, ...inline.mdx } } : {}),
-  };
-}
-
-function timberCache(_ctx: PluginContext): Plugin {
-  return cacheTransformPlugin();
+function patchReactCompilerForProdJsx(plugins: PluginOption[]): PluginOption[] {
+  for (const p of plugins) {
+    if (p && typeof p === 'object' && 'name' in p && p.name === 'vite:react-compiler') {
+      const orig = (p as Plugin).configResolved;
+      if (typeof orig === 'function') {
+        (p as Plugin).configResolved = function (config) {
+          const view =
+            config.command === 'build' && !config.isProduction
+              ? Object.create(config, { isProduction: { value: true } })
+              : config;
+          return orig.call(this, view);
+        };
+      }
+    }
+  }
+  return plugins;
 }
 
 export function timber(config?: TimberUserConfig): PluginOption[] {
   const ctx = createPluginContext(config);
-  // Sync ctx.root and ctx.appDir with Vite's resolved root, which may
-  // differ from process.cwd() when --config points to a subdirectory.
-  // Also loads timber.config.ts and merges it into ctx.config (inline config wins).
+
+  // Resolve dependencies from the consumer's project (process.cwd()),
+  // not from timber's own node_modules. This is critical for pnpm link:
+  // when linked, timber's node_modules has a separate vite instance, and
+  // the RSC plugin must use the same vite instance as the dev server.
+  const consumerRequire = createRequire(join(process.cwd(), 'package.json'));
+
+  // ── Step 1: Load @vitejs/plugin-rsc ─────────────────────────────────
+  // Synchronous require() works for ESM modules on Node 22.12+.
+  ctx.timer.start('rsc-plugin-import');
+  const rscMod = consumerRequire('@vitejs/plugin-rsc');
+  const vitePluginRsc = rscMod.default ?? rscMod;
+  ctx.timer.end('rsc-plugin-import');
+
+  // ── Step 2: Compute config-dependent options ────────────────────────
+  // encryptionKeyExpr is env-based and doesn't depend on file config.
+  const encryptionKeyExpr = resolveEncryptionKeyExpression();
+
+  // ── Step 3: Pre-load file config for plugin resolution ──────────────
+  // Load timber.config.ts eagerly from process.cwd() so we can resolve
+  // plugins (like React Compiler) and add them to the top-level array.
+  // Vite's config() hook return type is Omit<UserConfig, 'plugins'> —
+  // plugins returned from config() are silently ignored. See TIM-632.
+  //
+  // The config() hook still loads from the correct Vite root (which may
+  // differ from cwd in monorepo setups — see TIM-498), but only for
+  // non-plugin config merging.
+  const earlyFileConfig = loadTimberConfigFile(process.cwd());
+
+  // ── Step 4: Build rootSync plugin ───────────────────────────────────
+
+  // rootSync loads timber.config.ts from Vite's resolved root and merges
+  // it into ctx.config. Plugin resolution is handled eagerly above — the
+  // config() hook must NOT return a `plugins` field (Vite ignores it).
   const rootSync: Plugin = {
     name: 'timber-root-sync',
-    async config(userConfig, { command }) {
-      // Load timber.config.ts early — before configResolved/buildStart — so
-      // all plugins (including timber-mdx) see the merged config in their
-      // buildStart hooks. The config hook runs once and supports async.
-      const root = userConfig.root ?? process.cwd();
+
+    // The plugin context, published for out-of-band callers that need the
+    // *resolved* configuration rather than a second reading of the files it
+    // came from. `timber check` is the one today: it runs Vite's
+    // `resolveConfig()` and reads root, appDir, and pageExtensions from here,
+    // so it scans exactly the tree `timber build` builds — including config
+    // passed inline as `timber({ ... })`, which lives only in this closure and
+    // is invisible to anything that re-reads `timber.config.ts`. See
+    // `cli-check.ts` and design/11-platform.md §`timber check`.
+    //
+    // Valid from `configResolved` onward; `appDir` and `root` are unset before
+    // that, which is why the reader runs a full `resolveConfig()` rather than
+    // just loading the config file.
+    api: { getContext: () => ctx } satisfies TimberPluginApi,
+
+    async config(userConfig, { command, isPreview }) {
+      // ── Load timber.config.ts from the correct root ───────────────
+      // Vite's `config` hook fires before `configResolved`. The user's
+      // `root` option (if set) tells us where the project lives.
+      // `resolve()` mirrors Vite's own root resolution logic.
+      const viteRoot = resolve(userConfig.root ?? process.cwd());
       ctx.timer.start('config-load');
-      const fileConfig = await loadTimberConfigFile(root);
+      const fileConfig = loadTimberConfigFile(viteRoot);
       if (fileConfig) {
-        mergeFileConfig(ctx, fileConfig);
+        ctx.config = mergeFileConfig(ctx.config, fileConfig);
         ctx.clientJavascript = resolveClientJavascript(ctx.config);
       }
+      // Apply defaults AFTER merge so file-based config isn't overridden
+      // by defaults that were baked into the inline config object.
+      ctx.config.output ??= 'server';
       ctx.timer.end('config-load');
 
-      // Force production JSX transform for builds.
+      // ── Resolve build output directory ─────────────────────────
+      // Priority: timber.config.ts `buildDir` > Vite `build.outDir` > .timber/dist
+      // Set Vite's build.outDir so the RSC plugin and all environment
+      // builds write to the correct location. ctx.buildDir is read back
+      // from Vite in configResolved, so there is one answer to where the
+      // build went.
+      const resolvedRoot = resolve(userConfig.root ?? process.cwd());
+      const buildDir = resolveBuildDir(resolvedRoot, ctx.config.buildDir, userConfig.build?.outDir);
+
+      // Warn if the Vite root differs from cwd and the re-loaded config
+      // has reactCompiler but the early cwd-based load missed it. In this
+      // edge case the user must move reactCompiler to inline config.
+      if (viteRoot !== process.cwd()) {
+        const hasCompilerInReloaded = !config?.reactCompiler && ctx.config.reactCompiler;
+        const hadCompilerInEarly = !config?.reactCompiler && earlyFileConfig?.reactCompiler;
+        if (hasCompilerInReloaded && !hadCompilerInEarly) {
+          console.warn(
+            '[timber] reactCompiler is set in timber.config.ts but could not be ' +
+              'registered because the config file is in a non-cwd root directory. ' +
+              'Move reactCompiler to the inline timber() config in vite.config.ts, or ' +
+              'run vite from the project root directory.'
+          );
+        }
+      }
+
+      // Force production JSX for builds.
+      //
+      // Vite derives `config.isProduction` from `process.env.NODE_ENV`.
+      // If the shell has NODE_ENV=development, isProduction stays false
+      // and Vite's built-in OXC transform emits jsxDEV calls (the
+      // production jsx-runtime doesn't export jsxDEV). The oxc.jsx
+      // override below fixes Vite's native path; plugin-react's compiler
+      // plugin is handled by patchReactCompilerForProdJsx above.
+      // ── Resolve dev/preview port (TIM-842) ───────────────────────
+      // Default port is 3000. Vite handles conflicts and honors server.strictPort.
       //
-      // Vite determines dev vs prod JSX via `isProduction`, which checks
-      // `process.env.NODE_ENV === 'production'`. If the shell has
-      // NODE_ENV=development (common in dev toolchains), `vite build`
-      // respects that and emits jsxDEV calls with fileName/lineNumber
-      // args. This causes runtime crashes because the production React
-      // jsx-runtime doesn't export jsxDEV, and also leaks file paths
-      // into production bundles (security concern).
+      // For dev (`command === 'serve' && !isPreview`) we start the
+      // holding server on the requested port when available.
       //
-      // We explicitly set `oxc.jsx.development: false` for builds so
-      // the client bundle always uses jsx/jsxs from react/jsx-runtime,
-      // regardless of the ambient NODE_ENV value.
+      // For `vite preview` (`command === 'serve' && isPreview`) we
+      // resolve the config/env port but delegate the actual bind +
+      // auto-bump to Vite's own preview server. Starting the holding
+      // server in preview mode would self-conflict because the dev
+      // plugin's `configureServer` handoff does not run for preview;
+      // the holding server would keep the port occupied while Vite's
+      // preview tried to bind the same port.
+      //
+      // See design/21-dev-server.md §"Default Port and Auto-Bump".
+      let resolvedDevPort: number | null = null;
+      let resolvedDevPortExplicit = false;
+      // Middleware-mode embeddings (the analyze crawl, custom servers)
+      // never bind a port, and the dev-server plugin's listen() handoff
+      // that closes the holding server never runs — starting it would
+      // occupy the default port for the embedding's lifetime.
+      const isMiddlewareMode = Boolean(userConfig.server?.middlewareMode);
+      // Resolve the host Vite will bind so the holding server probes the
+      // same address. Vite defaults to 'localhost' when server.host is
+      // unset; binding wildcard (no host) would mask conflicts on
+      // localhost due to SO_REUSEADDR address-family differences. TIM-1419.
+      const resolvedHost =
+        typeof userConfig.server?.host === 'string'
+          ? userConfig.server.host
+          : userConfig.server?.host === true
+            ? undefined
+            : 'localhost';
+      if (command === 'serve' && !isPreview && !isMiddlewareMode) {
+        const start = resolveStartPort({
+          configPort: userConfig.server?.port,
+          envPort: process.env.PORT,
+        });
+        // Vite owns port selection and remembers its bound port on restart.
+        // Never forward a probed/bumped port: replacement config runs while
+        // the old listener still owns the port. The holding page is optional.
+        resolvedDevPort = start.port;
+        resolvedDevPortExplicit = userConfig.server?.strictPort ?? false;
+        if (start.port !== 0) {
+          ctx.holdingServer = createHoldingServer();
+          await ctx.holdingServer.listen(start.port, resolvedHost).catch(() => {
+            ctx.holdingServer = null;
+          });
+        }
+      } else if (command === 'serve' && isPreview) {
+        // Preview mode: resolve the starting port from config/env/
+        // default but do NOT probe. Vite's preview server handles the
+        // bind itself, with `preview.strictPort` controlling whether
+        // an in-use port auto-bumps (implicit) or errors (explicit).
+        const previewConfigPort =
+          typeof userConfig.preview?.port === 'number'
+            ? userConfig.preview.port
+            : typeof userConfig.server?.port === 'number'
+              ? userConfig.server.port
+              : undefined;
+        const start = resolveStartPort({
+          configPort: previewConfigPort,
+          envPort: process.env.PORT,
+        });
+        resolvedDevPort = start.port;
+        resolvedDevPortExplicit = start.explicit;
+      }
+
+      // Derive relative buildOutDir from the absolute buildDir (set above)
+      // so Vite's config receives a root-relative path.
+      const buildOutDir = relative(resolvedRoot, buildDir);
+
+      // Set per-environment build.outDir so Vite's RSC plugin writes
+      // each environment to the correct subdirectory under our buildDir.
+      // Without this, the RSC plugin defaults to dist/<envName> instead
+      // of <buildOutDir>/<envName>.
+      const envOutDirs: Record<string, { build: { outDir: string } }> = {};
+      for (const envName of ['rsc', 'ssr', 'client']) {
+        envOutDirs[envName] = { build: { outDir: join(buildOutDir, envName) } };
+      }
+
+      // Exclude @timber-js/app packages from the dep optimizer.
+      // The shims plugin intercepts @timber-js/app/* imports per-environment
+      // (e.g. replacing @timber-js/app/server with a stub in the client env).
+      // The dep optimizer runs before per-environment resolution, so it would
+      // pre-bundle @timber-js/app/cookies with the real server code inlined,
+      // pulling AsyncLocalStorage into the browser bundle.
+      const timberOptimizeDepsExclude = [
+        '@timber-js/app',
+        '@timber-js/app/server',
+        '@timber-js/app/client',
+        '@timber-js/app/cookies',
+        '@timber-js/app/cache',
+        '@timber-js/app/search-params',
+        '@timber-js/app/params',
+        '@timber-js/app/codec',
+      ];
+
       if (command === 'build') {
         return {
+          build: { outDir: buildOutDir },
+          environments: envOutDirs,
+          optimizeDeps: { exclude: timberOptimizeDepsExclude },
           oxc: {
             jsx: {
               development: false,
@@ -373,11 +428,102 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
           },
         };
       }
+
+      // Dev/preview mode: set outDir so dev-time references are
+      // consistent, and surface the resolved port to Vite.
+      //
+      // Dev auto-bumps unless the user sets server.strictPort.
+      // Always forward the requested port so Vite can recognize unchanged
+      // config and reuse its actual bound port across restarts (TIM-1456).
+      //
+      // For `vite preview`, we set `preview.strictPort` based on
+      // whether the user explicitly set the port. Implicit (default)
+      // preview uses strictPort: false so Vite's preview server can
+      // auto-bump from 3000. Explicit preview uses strictPort: true
+      // so conflicts fail loudly, matching the dev behavior and the
+      // TIM-842 spec.
+      const serverConfig: {
+        port?: number;
+        strictPort?: boolean;
+        forwardConsole?: boolean | { unhandledErrors?: boolean; logLevels?: string[] };
+      } = {};
+      const previewConfig: { port?: number; strictPort?: boolean } = {};
+      if (resolvedDevPort != null) {
+        if (!isPreview) {
+          serverConfig.port = resolvedDevPort;
+          serverConfig.strictPort = resolvedDevPortExplicit;
+        }
+        previewConfig.port = resolvedDevPort;
+        previewConfig.strictPort = resolvedDevPortExplicit;
+      }
+
+      // Enable Vite 8's built-in browser→terminal console forwarding.
+      // Vite defaults this OFF for non-agent dev; timber enables it based
+      // on the devBrowserLogs config (default: 'warn'). See TIM-1152.
+      serverConfig.forwardConsole = resolveForwardConsole(ctx.config.devBrowserLogs);
+
+      // Provide a customLogger whose output routes through the pre-patched
+      // console methods so Vite's forwardConsole output never re-enters our
+      // server→browser patch. If the user supplied their own customLogger,
+      // wrap it so its console calls also bypass patching.
+      const customLogger = userConfig.customLogger
+        ? wrapLoggerWithOriginalConsole(userConfig.customLogger)
+        : createLogger(userConfig.logLevel ?? 'info', {
+            allowClearScreen: userConfig.clearScreen ?? true,
+            console: originalConsole as Console,
+          });
+
+      // Seed the client optimizer's startup crawl with every 'use client'
+      // file so client-only packages are pre-bundled before the first
+      // request, not discovered mid-load (which full-reloads the page).
+      // Vite concatenates these with any entries the user sets.
+      // See design/21-dev-server.md §"Client Dependency Pre-Bundling".
+      let environments: Record<string, object> = envOutDirs;
+      if (!isPreview) {
+        ctx.timer.start('client-deps-scan');
+        // Loaded lazily: directive detection pulls in @vitejs/plugin-rsc's
+        // transforms, which builds and preview never need.
+        const { clientOptimizeDepsEntries } = await import('./plugins/client-dep-entries.ts');
+        const entries = await clientOptimizeDepsEntries(resolvedRoot, BROWSER_ENTRY_FILE, buildDir);
+        ctx.timer.end('client-deps-scan');
+        environments = {
+          ...envOutDirs,
+          client: { ...envOutDirs.client, optimizeDeps: { entries } },
+        };
+      }
+
+      return {
+        build: { outDir: buildOutDir },
+        environments,
+        optimizeDeps: { exclude: timberOptimizeDepsExclude },
+        customLogger,
+        server: serverConfig,
+        preview: previewConfig,
+      };
     },
     configResolved(resolved) {
       ctx.root = resolved.root;
       ctx.appDir = resolveAppDir(resolved.root, ctx.config.appDir);
       ctx.dev = resolved.command === 'serve';
+      // Vite's resolved base — the deployment path prefix. Captured once
+      // here so every sub-plugin that emits a URL (assets, fonts, RSC
+      // payloads) reads the same value. See TIM-1261.
+      ctx.base = resolved.base;
+
+      // timber.config.* files are NOT registered as configFileDependencies.
+      // Vite's in-process restart cannot bust Node's require cache for ESM
+      // modules loaded via require(), so the restarted server would serve
+      // stale config. Instead, timber-dev-server watches these files and
+      // calls process.exit(RESTART_EXIT_CODE) so the CLI supervisor
+      // respawns a fresh process. See TIM-1444.
+      // The watcher.add() call in dev-server.ts ensures the files are
+      // watched even if created after server start.
+
+      // The build directory is what Vite resolved build.outDir to — the
+      // config hook's value after every other plugin and the user config had
+      // their say. Vite keeps outDir as-is (may be relative), so resolve
+      // against root.
+      ctx.buildDir = resolve(resolved.root, resolved.build.outDir);
       // In production builds, swap to a no-op timer to avoid overhead
       if (!ctx.dev) {
         ctx.timer = createNoopTimer();
@@ -385,19 +531,33 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
         // Start the overall dev server setup timer — ends in timber-dev-server
         ctx.timer.start('dev-server-setup');
       }
+
+      // Validate config and check peer dependencies at startup. Most errors
+      // are logged and don't block startup; fatal ones (a security setting
+      // that would not mean what it says) stop it. See reportConfigErrors.
+      reportConfigErrors(validateConfig(ctx.config));
+
+      const peerResults = checkPeerDependencies(ctx.root);
+      const peerWarning = formatMissingPeers(peerResults);
+      if (peerWarning) {
+        process.stderr.write(`${peerWarning}\n\n`);
+      }
     },
   };
+
+  // ── Step 5: Resolve React Compiler config ───────────────────────────
+  // Inline config takes precedence. File config (from the early cwd-based
+  // load) is used when inline config doesn't set reactCompiler.
+  // Default: true — oxc-transform-react is a direct dependency.
+  const effectiveReactCompiler = config?.reactCompiler ?? earlyFileConfig?.reactCompiler ?? true;
+
+  // ── Step 6: Assemble plugin array ─────────────────────────────────────
   // @vitejs/plugin-rsc handles:
   // - RSC/SSR/client environment setup
   // - "use client" directive → client reference proxy transformation
   // - "use server" directive → server reference transformation
   // - Client reference tracking and module map generation
   //
-  // Loaded via dynamic import() because @vitejs/plugin-rsc is ESM-only.
-  // Vite's config loader uses esbuild to transpile to CJS, which breaks
-  // static imports of ESM-only packages. The dynamic import() is preserved
-  // by esbuild and runs natively in ESM at runtime.
-  //
   // serverHandler: false — timber has its own dev server (timber-dev-server)
   // entries — tells the RSC plugin about timber's virtual entry modules so
   //   it correctly wires up the browser entry (needed for React Fast Refresh
@@ -410,75 +570,48 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
   // We do NOT set customBuildApp — the RSC plugin's orchestration is correct
   // and handles bundle ordering, asset manifest generation, and environment
   // imports manifest. See @vitejs/plugin-rsc's buildApp implementation.
-  // Resolve @vitejs/plugin-rsc from the consumer's project (process.cwd()),
-  // not from timber's own node_modules. This is critical for pnpm link:
-  // when linked, timber's node_modules has a separate vite instance, and
-  // the RSC plugin must use the same vite instance as the dev server.
-  const consumerRequire = createRequire(join(process.cwd(), 'package.json'));
-  const rscPluginPath = consumerRequire.resolve('@vitejs/plugin-rsc');
-  ctx.timer.start('rsc-plugin-import');
-  const rscPluginsPromise = import(pathToFileURL(rscPluginPath).href).then(
-    ({ default: vitePluginRsc }) => {
-      ctx.timer.end('rsc-plugin-import');
-      return vitePluginRsc({
-        serverHandler: false,
-        customClientEntry: true,
-        entries: {
-          rsc: 'virtual:timber-rsc-entry',
-          ssr: 'virtual:timber-ssr-entry',
-          client: 'virtual:timber-browser-entry',
-        },
-        // Group all client reference wrappers into a single chunk instead of
-        // creating one tiny file per "use client" module. Without this, each
-        // server chunk's client references become a separate entry point,
-        // producing many sub-500B wrapper files (e.g., 30-byte re-exports).
-        // A single group eliminates 10+ unnecessary HTTP requests.
-        // See design/27-chunking-strategy.md and TIM-440.
-        clientChunks: () => 'client-refs',
-      });
-    }
-  );
-
+  //
+  // Everything after it runs in timber-post-build, in the order that plugin
+  // states. The plugins that own a post-build step expose it as their `api`
+  // and are handed to it here, so no step's order depends on where a plugin
+  // sits in this array. See design/18-build-system.md §"Post-Build Phase".
+  const fonts = timberFonts(ctx);
+  const prebuilt = timberPrebuilt(ctx);
+  const buildReport = timberBuildReport(ctx);
   return [
     rootSync,
+    timberReactResolve(),
     timberReactProd(),
     // @vitejs/plugin-react provides React Fast Refresh (state-preserving HMR)
     // for client components via Babel transform. Placed before @vitejs/plugin-rsc
     // following Vinext's convention — the RSC plugin's virtual browser entry
     // coordinates with plugin-react via __vite_plugin_react_preamble_installed__.
-    react(),
-    timberServerActionExports(),
-    rscPluginsPromise,
+    ...patchReactCompilerForProdJsx(
+      react({
+        compiler: (effectiveReactCompiler || false) as boolean | ReactCompilerOptions,
+      })
+    ),
+    vitePluginRsc(createRscOptions(ctx, encryptionKeyExpr)),
     timberShims(ctx),
     timberRouting(ctx),
     timberEntries(ctx),
     timberBuildManifest(ctx),
-    timberCache(ctx),
-    timberStaticBuild(ctx),
-    timberDynamicTransform(ctx),
-    timberFonts(ctx),
+    fonts,
     timberMdx(ctx),
+    timberRequestDep(ctx),
+    timberCacheTransform(ctx),
+    timberPrerenderSugar(ctx), // export const prerender → cache.component() desugaring
+    prebuilt, // cache.component() → __prebuilt() callsite rewrite
+    timberStaticBuild(ctx), // Static mode: validate dynamic API usage
     timberContent(ctx),
     timberServerBundle(), // Bundle all deps in server environments for prod
-    timberChunks(),
-    timberBuildReport(ctx), // Post-build: route table with bundle sizes
-    timberAdapterBuild(ctx), // Post-build: invoke adapter.buildOutput()
+    timberCloudflareWasm(ctx), // Externalize WASM for Cloudflare Workers
+    timberChunks(ctx),
+    buildReport, // Route table with bundle sizes, printed by timber-post-build
+    timberPostBuild(ctx, { fonts: fonts.api, prebuilt: prebuilt.api, report: buildReport.api }),
     timberDevLogs(ctx), // Dev-only: forward server console.* to browser console
     timberDevServer(ctx), // Must be last — configureServer post-hook runs after all watchers
   ];
 }
 
-/**
- * Route map interface — augmented by the generated timber-routes.d.ts.
- *
- * Each key is a route path pattern. Values have:
- *   params: shape of URL params (e.g. { id: string })
- *   searchParams: parsed type from search-params.ts, or {} if none
- *
- * This interface is empty by default and populated via codegen.
- * See design/09-typescript.md §"Typed Routes".
- */
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-export interface Routes {}
-
 export default timber;