@timber-js/app 0.2.0-alpha.11 → 0.2.0-alpha.111

package/src/index.ts

@@ -1,10 +1,19 @@
+/**
+ * @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 { join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
-import react from '@vitejs/plugin-react';
-import { cacheTransformPlugin } from './plugins/cache-transform';
+import react, { reactCompilerPreset } from '@vitejs/plugin-react';
 import { timberContent } from './plugins/content';
 import { timberDevServer } from './plugins/dev-server';
 import { timberEntries } from './plugins/entries';
@@ -13,356 +22,271 @@ 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 { timberDevLogs } from './dev-tools/logs';
+import { timberDevBrowserLogs } from './dev-tools/browser-logs';
 import { timberReactProd } from './plugins/react-prod';
 import { timberChunks } from './plugins/chunks';
+import { clientChunkGroup } from './plugins/client-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 { createNoopTimer } from './utils/startup-timer';
+import { resolveEncryptionKeyExpression, shouldEnableEncryption } from './server/action-encryption';
+import { createHoldingServer } from './dev-tools/holding-server.js';
+import { resolveStartPort, startDevServerPort } from './server/port-resolution.js';
+import type { TimberUserConfig } from './config-types.js';
+import type { PluginContext } from './plugin-context.js';
+import {
+  createPluginContext,
+  loadTimberConfigFile,
+  mergeFileConfig,
+  resolveAppDir,
+  resolveClientJavascript,
+  resolveBuildDir,
+  DEFAULT_BUILD_DIR,
+} from './plugin-context.js';
 
-/** 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[];
-  };
-  /**
-   * 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;
-  };
-  /**
-   * Response-level caching and deduplication.
-   *
-   * When enabled, concurrent requests to the same URL share a single render
-   * (singleflight), and recently rendered responses are reused from a short-TTL
-   * LRU cache without re-executing the RSC-to-SSR pipeline.
-   *
-   * Set to `false` to disable entirely. Default: enabled with sensible defaults.
-   *
-   * See design/31-benchmarking.md for performance context.
-   */
-  responseCache?:
-    | false
-    | {
-        /** Maximum number of entries in the LRU cache. Default: 150. */
-        maxSize?: number;
-        /** TTL for cached entries in milliseconds. Default: 5000 (5s). */
-        ttlMs?: number;
-        /**
-         * When true (default), requests with Cookie or Authorization headers
-         * bypass the cache entirely. This prevents sharing user-specific
-         * responses across requests.
-         *
-         * Set to false to cache all responses regardless of auth state.
-         * Only do this if your pages are truly public and don't vary by user.
-         */
-        publicOnly?: boolean;
-      };
-}
+export type { TimberUserConfig } from './config-types.js';
 
-/**
- * Resolve `clientJavascript` into a fully resolved config.
- */
-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,
-    };
-  }
+// Global segment param schema types — re-exported from root for convenience.
+// The value export `defineSchema` lives at '@timber-js/app/params' (canonical).
+// See design/41-global-params.md.
+export type { InferCodecType, SchemaConfig } from './params/define-schema.js';
 
-  // Default: client JS enabled
-  return { disabled: false, enableHMRInDev: false };
-}
+// 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.js';
 
 /**
- * Shared context object passed to all sub-plugins via closure.
+ * Route map interface — augmented by the generated timber-routes.d.ts.
  *
- * Sub-plugins communicate through this context — not through Vite's
- * plugin API or global state.
- * See design/18-build-system.md §"Shared Plugin Context".
+ * Each key is a route path pattern. Values have:
+ *   segmentParams: shape of URL segment 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".
  */
-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;
-}
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface Routes {}
 
 /**
- * Resolve the app directory. Checks (in order):
- * 1. Explicit `configAppDir` from timber.config.ts
- * 2. `<root>/app`
- * 3. `<root>/src/app`
+ * Type-safe helper for timber.config.ts files.
  *
- * Throws if none exist.
+ * 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';
+ *
+ * export default defineConfig({
+ *   output: 'server',
+ *   pageExtensions: ['tsx', 'ts', 'mdx'],
+ * });
+ * ```
  */
-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;
-  }
-
-  const rootApp = join(root, 'app');
-  if (existsSync(rootApp)) return rootApp;
-
-  const srcApp = join(root, 'src', 'app');
-  if (existsSync(srcApp)) return srcApp;
-
-  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.`
-  );
+export function defineConfig(config: TimberUserConfig): TimberUserConfig {
+  return config;
 }
 
-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(),
-  };
-}
+// ── Private helpers ───────────────────────────────────────────────────────
 
 /**
- * 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;
-}
-
-/**
- * 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.
+ * Resolve the React Compiler plugin via @rolldown/plugin-babel.
+ *
+ * Uses the `reactCompilerPreset` from @vitejs/plugin-react, which:
+ * - Uses Babel ONLY for the compiler pass (OXC handles JSX)
+ * - Automatically scopes to client environment via applyToEnvironmentHook
+ * - Uses react/compiler-runtime built into React 19
  *
- * Returns the list of conflicting key names (for testing).
+ * @rolldown/plugin-babel and babel-plugin-react-compiler are optional peer deps.
+ * If either is missing, require() fails with a clear error message.
  */
-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.`
+function resolveReactCompilerPlugin(
+  config: true | { compilationMode?: string; target?: string },
+  req: NodeRequire
+): PluginOption {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let babel: any;
+  try {
+    babel = req('@rolldown/plugin-babel');
+  } catch {
+    throw new Error(
+      '[timber] reactCompiler requires @rolldown/plugin-babel. ' +
+        'Install it: pnpm add -D @rolldown/plugin-babel babel-plugin-react-compiler'
     );
   }
-  return conflicts;
+  const options = typeof config === 'object' ? config : {};
+  const babelPlugin = babel.default ?? babel;
+  return babelPlugin({
+    presets: [reactCompilerPreset(options as Parameters<typeof reactCompilerPreset>[0])],
+  }) as PluginOption;
 }
 
 /**
- * Merge file-based config into ctx.config. Inline config (already in ctx.config)
- * takes precedence — file config only fills in missing fields.
+ * Build the options object for @vitejs/plugin-rsc.
+ *
+ * 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.
  */
-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 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),
   };
-}
 
-function timberCache(_ctx: PluginContext): Plugin {
-  return cacheTransformPlugin();
+  // 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,
+  });
+
+  // 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;
+  }
+
+  return options;
 }
 
+// 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.
+
+// ── Main plugin factory ──────────────────────────────────────────────────
+
+/**
+ * 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.
+ *
+ * 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 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();
+    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.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');
 
+      // ── 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.
+      const viteOutDir = userConfig.build?.outDir;
+      const timberBuildDir = ctx.config.buildDir;
+      const resolvedRoot = resolve(userConfig.root ?? process.cwd());
+      ctx.buildDir = resolveBuildDir(resolvedRoot, timberBuildDir, viteOutDir);
+
+      // 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 transform for builds.
       //
       // Vite determines dev vs prod JSX via `isProduction`, which checks
@@ -376,8 +300,102 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
       // 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.
+      // ── Resolve dev/preview port (TIM-842) ───────────────────────
+      // Default port is 3000 with auto-bump on conflict. Explicit user
+      // overrides (`--port`, `PORT` env, `vite.config.ts` server.port)
+      // are honored as-is and fail loudly via `strictPort: true`.
+      //
+      // For dev (`command === 'serve' && !isPreview`) we start the
+      // holding server and use its `listen()` as the probe, pairing
+      // the probe with the real bind to eliminate TOCTOU races.
+      //
+      // 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;
+      if (command === 'serve' && !isPreview) {
+        ctx.holdingServer = createHoldingServer();
+        const holdingRef = ctx.holdingServer;
+        const result = await startDevServerPort({
+          configPort:
+            typeof userConfig.server?.port === 'number' ? userConfig.server.port : undefined,
+          envPort: process.env.PORT,
+          listen: (p) => holdingRef.listen(p),
+        });
+        resolvedDevPort = result.port;
+        resolvedDevPortExplicit = result.explicit;
+        if (!result.bound) {
+          // Holding server failed to bind. Drop the reference so the
+          // dev-server plugin doesn't try to close a server that was
+          // never listening, and let Vite surface the conflict.
+          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;
+      }
+
+      // Return the resolved buildDir as Vite's build.outDir so the RSC
+      // plugin and all environment builds write to the correct location.
+      // This is always set — either from timber config, Vite config, or default.
+      const buildOutDir = timberBuildDir
+        ? timberBuildDir
+        : viteOutDir && viteOutDir !== 'dist'
+          ? viteOutDir
+          : DEFAULT_BUILD_DIR;
+
+      // 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/segment-params',
+        '@timber-js/app/codec',
+      ];
+
       if (command === 'build') {
         return {
+          build: { outDir: buildOutDir },
+          environments: envOutDirs,
+          optimizeDeps: { exclude: timberOptimizeDepsExclude },
           oxc: {
             jsx: {
               development: false,
@@ -385,11 +403,60 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
           },
         };
       }
+
+      // Dev/preview mode: set outDir so dev-time references are
+      // consistent, and surface the resolved port to Vite.
+      //
+      // For dev, we set strictPort: true so Vite uses exactly the port
+      // the holding server probed for — without strictPort, Vite would
+      // run its own auto-bump starting from `port`, which would skip
+      // straight past whatever holding-server-bumped port we picked.
+      //
+      // 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 } = {};
+      const previewConfig: { port?: number; strictPort?: boolean } = {};
+      if (resolvedDevPort != null) {
+        if (!isPreview) {
+          serverConfig.port = resolvedDevPort;
+          serverConfig.strictPort = true;
+        }
+        previewConfig.port = resolvedDevPort;
+        previewConfig.strictPort = resolvedDevPortExplicit;
+      }
+      return {
+        build: { outDir: buildOutDir },
+        environments: envOutDirs,
+        optimizeDeps: { exclude: timberOptimizeDepsExclude },
+        server: serverConfig,
+        preview: previewConfig,
+      };
     },
     configResolved(resolved) {
       ctx.root = resolved.root;
       ctx.appDir = resolveAppDir(resolved.root, ctx.config.appDir);
       ctx.dev = resolved.command === 'serve';
+
+      // Register all timber config file candidates as Vite config file
+      // dependencies so Vite's built-in restart-on-change handles them
+      // (including atomic writes that emit unlink+add instead of change).
+      // All candidates are registered — not just the one that exists — so
+      // that creating a config file after server start also triggers a
+      // restart. The watcher.add() call in dev-server.ts ensures all
+      // candidates are in the watch set.
+      // See design/21-dev-server.md §HMR Wiring.
+      const configNames = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];
+      for (const name of configNames) {
+        resolved.configFileDependencies.push(resolve(resolved.root, name));
+      }
+
+      // Sync buildDir from Vite's resolved build.outDir. 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();
@@ -397,19 +464,47 @@ 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.
+      // Errors are logged to stderr but don't block startup — Vite may
+      // still work partially, and the errors guide the user to fix things.
+      const { validateConfig, formatConfigErrors, checkPeerDependencies, formatMissingPeers } =
+        require('./config-validation.js') as typeof import('./config-validation.js');
+
+      const configErrors = validateConfig(ctx.config);
+      if (configErrors.length > 0) {
+        process.stderr.write(`${formatConfigErrors(configErrors)}\n\n`);
+      }
+
+      const peerResults = checkPeerDependencies(ctx.root);
+      const peerWarning = formatMissingPeers(peerResults);
+      if (peerWarning) {
+        process.stderr.write(`${peerWarning}\n\n`);
+      }
     },
   };
+
+  // ── Step 5: Resolve optional plugins ────────────────────────────────
+  // React Compiler — resolved eagerly from either inline or file config.
+  // Vite's config() hook return type is Omit<UserConfig, 'plugins'>, so
+  // plugins MUST be in the top-level array — returning them from config()
+  // silently drops them. See TIM-632.
+  //
+  // Inline config takes precedence. File config (from the early cwd-based
+  // load) is used when inline config doesn't set reactCompiler.
+  const reactCompilerPlugins: PluginOption[] = [];
+  const effectiveReactCompiler = config?.reactCompiler ?? earlyFileConfig?.reactCompiler;
+  if (effectiveReactCompiler) {
+    reactCompilerPlugins.push(resolveReactCompilerPlugin(effectiveReactCompiler, consumerRequire));
+  }
+
+  // ── 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
@@ -422,30 +517,6 @@ 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',
-        },
-        // No custom clientChunks — Rolldown handles natural code splitting.
-        // See design/27-chunking-strategy.md and LOCAL-337.
-      });
-    }
-  );
-
   return [
     rootSync,
     timberReactProd(),
@@ -454,15 +525,13 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
     // following Vinext's convention — the RSC plugin's virtual browser entry
     // coordinates with plugin-react via __vite_plugin_react_preamble_installed__.
     react(),
-    timberServerActionExports(),
-    rscPluginsPromise,
+    ...reactCompilerPlugins,
+    vitePluginRsc(createRscOptions(ctx, encryptionKeyExpr)),
     timberShims(ctx),
     timberRouting(ctx),
     timberEntries(ctx),
     timberBuildManifest(ctx),
-    timberCache(ctx),
     timberStaticBuild(ctx),
-    timberDynamicTransform(ctx),
     timberFonts(ctx),
     timberMdx(ctx),
     timberContent(ctx),
@@ -471,21 +540,9 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
     timberBuildReport(ctx), // Post-build: route table with bundle sizes
     timberAdapterBuild(ctx), // Post-build: invoke adapter.buildOutput()
     timberDevLogs(ctx), // Dev-only: forward server console.* to browser console
+    timberDevBrowserLogs(ctx), // Dev-only: forward browser console.* to server terminal
     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;