@timber-js/app 0.2.0-alpha.7 → 0.2.0-alpha.71

package/src/index.ts

@@ -1,10 +1,8 @@
 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,12 +11,13 @@ 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 { timberDevBrowserLogs } from './plugins/dev-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';
@@ -26,6 +25,7 @@ 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';
+import { resolveEncryptionKeyExpression, shouldEnableEncryption } from './server/action-encryption';
 
 /** Configuration for client-side JavaScript output. */
 export interface ClientJavascriptConfig {
@@ -90,23 +90,54 @@ export interface TimberUserConfig {
    * See design/17-logging.md §"slowRequestMs".
    */
   slowRequestMs?: number;
+  /**
+   * Render timeout in milliseconds. If an SSR render or RSC stream read
+   * does not complete within this duration, the render is aborted and
+   * the connection is closed. Protects against hung fetches and Suspense
+   * components that never resolve.
+   *
+   * Set to 0 to disable (not recommended in production).
+   * Default: 30000 (30 seconds).
+   *
+   * See design/02-rendering-pipeline.md §"Streaming Constraints".
+   */
+  renderTimeoutMs?: number;
+  /**
+   * Forward browser console output to the server terminal in dev mode.
+   *
+   * Sets the minimum log level to forward:
+   * - `'error'` — only `console.error`
+   * - `'warn'` — `console.error` + `console.warn` (default)
+   * - `'info'` — `console.error` + `console.warn` + `console.info`
+   * - `'none'` — disabled
+   *
+   * Does not intercept `console.log` or `console.debug` (too noisy).
+   * No effect in production builds.
+   *
+   * See TIM-513.
+   */
+  devBrowserLogs?: 'error' | 'warn' | 'info' | 'none';
   /** 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".
+   * Control Server-Timing header output.
    *
-   * 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.
+   * - `'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.
    */
-  cookies?: {
-    /** Single signing secret. Shorthand for `secrets: [secret]`. */
-    secret?: string;
-    /** Array of signing secrets for key rotation. Index 0 signs; all verify. */
-    secrets?: string[];
-  };
+  serverTiming?: 'detailed' | 'total' | false;
   /**
    * Override the app directory location. By default, timber auto-detects
    * `app/` at the project root, falling back to `src/app/`.
@@ -132,6 +163,72 @@ export interface TimberUserConfig {
    *
    * See LOCAL-336 for design decisions.
    */
+  /**
+   * Server action bound args encryption configuration.
+   *
+   * The RSC plugin encrypts closure variables captured by 'use server' functions
+   * using AES-256-GCM so they are opaque and tamper-proof in the Flight payload.
+   * Encryption is always enabled in production.
+   *
+   * The encryption key is auto-generated at build time and embedded in the server bundle,
+   * so all instances running the same build share the same key automatically.
+   * For rolling/blue-green deployments where multiple builds coexist, set
+   * `TIMBER_ACTIONS_ENCRYPTION_KEY` env var to share a key across builds.
+   *
+   * See design/08-forms-and-actions.md §"Security"
+   */
+  actionEncryption?: {
+    /**
+     * Disable encryption in dev mode for easier debugging of bound args.
+     * Has no effect in production — encryption is always enabled.
+     * Default: false (encryption is on in dev too).
+     */
+    disableInDev?: boolean;
+  };
+  /**
+   * Enable the React Compiler (babel-plugin-react-compiler) for automatic
+   * memoization of components and hooks at build time.
+   *
+   * - `true` — enable with default options
+   * - `{ compilationMode, target }` — enable with custom options
+   *   - `compilationMode: 'annotation'` — only compile files with `'use memo'`
+   *   - `target: '18'` — target React 18 (uses react-compiler-runtime package)
+   * - `false` or omitted — disabled (default)
+   *
+   * Uses `@vitejs/plugin-react`'s built-in `reactCompilerPreset`, which:
+   * - Applies Babel only for the compiler pass (OXC handles JSX)
+   * - Automatically scopes to client environment only
+   * - Uses `react/compiler-runtime` built into React 19
+   *
+   * Requires `babel-plugin-react-compiler` as a peer dependency.
+   */
+  reactCompiler?: boolean | { compilationMode?: string; target?: string };
+  /**
+   * Auto-generate sitemap.xml from the route tree.
+   *
+   * When enabled, timber walks the file-system route tree and produces a sitemap
+   * for all discoverable pages. Dynamic routes with `generateStaticParams()` are
+   * enumerated. Routes protected by `access.ts` are excluded by default.
+   *
+   * If a user-authored `sitemap.ts` or `sitemap.xml` exists at the app root,
+   * auto-generation is disabled — the user takes full control.
+   *
+   * Supports automatic pagination (sitemap index) for sites with > 50,000 URLs.
+   *
+   * See design/16-metadata.md §"Auto-generated Sitemap"
+   */
+  sitemap?: {
+    /** Must be explicitly `true` to enable auto-generation. Default: false. */
+    enabled?: boolean;
+    /** Base URL for absolute URLs in the sitemap. Required when enabled. e.g., 'https://example.com' */
+    baseUrl?: string;
+    /** Default `<changefreq>` for all entries. Optional. */
+    defaultChangeFrequency?: string;
+    /** Default `<priority>` for all entries (0.0–1.0). Optional. */
+    defaultPriority?: number;
+    /** Include routes protected by `access.ts`. Default: false. */
+    includeProtected?: boolean;
+  };
   topLoader?: {
     /** Whether the top-loader is enabled. Default: true. */
     enabled?: boolean;
@@ -146,34 +243,6 @@ export interface TimberUserConfig {
     /** 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;
-      };
 }
 
 /**
@@ -221,10 +290,10 @@ export interface PluginContext {
   dev: boolean;
   /** CSS build manifest (populated by adapter after client build, null in dev) */
   buildManifest: BuildManifest | null;
+  /** Per-build deployment ID for version skew detection (null in dev) */
+  deploymentId: string | null;
   /** Startup timer for profiling cold start phases (active in dev, no-op in prod) */
   timer: StartupTimer;
-  /** URL path to font CSS file, set by timber-fonts when fonts are registered */
-  fontCssUrl?: string;
 }
 
 /**
@@ -258,7 +327,10 @@ export function resolveAppDir(root: string, configAppDir?: string): string {
 
 function createPluginContext(config?: TimberUserConfig, root?: string): PluginContext {
   const projectRoot = root ?? process.cwd();
-  const resolvedConfig: TimberUserConfig = { output: 'server', ...config };
+  // Don't apply defaults here — they would override file-based config
+  // during mergeFileConfig (inline spreads over file). Defaults are
+  // applied after merge in timber(). See TIM-451.
+  const resolvedConfig: TimberUserConfig = { ...config };
   // Timer starts as active — swapped to noop in configResolved for production builds
   return {
     config: resolvedConfig,
@@ -268,6 +340,7 @@ function createPluginContext(config?: TimberUserConfig, root?: string): PluginCo
     root: projectRoot,
     dev: false,
     buildManifest: null,
+    deploymentId: null,
     timer: createStartupTimer(),
   };
 }
@@ -275,14 +348,18 @@ function createPluginContext(config?: TimberUserConfig, root?: string): PluginCo
 /**
  * Load timber.config.ts (or .js, .mjs) from the project root.
  * Returns the config object or null if no config file is found.
+ *
+ * Uses require() which works for ESM modules on Node 22.12+.
+ * This keeps timber() synchronous — no async config loading needed.
  */
-async function loadTimberConfigFile(root: string): Promise<TimberUserConfig | null> {
+export function loadTimberConfigFile(root: string): TimberUserConfig | null {
   const configNames = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];
+  const req = createRequire(join(root, 'package.json'));
 
   for (const name of configNames) {
     const configPath = join(root, name);
     if (existsSync(configPath)) {
-      const mod = await import(pathToFileURL(configPath).href);
+      const mod = req(configPath);
       return (mod.default ?? mod) as TimberUserConfig;
     }
   }
@@ -302,7 +379,6 @@ export function warnConfigConflicts(
 ): 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);
     }
@@ -341,30 +417,181 @@ function mergeFileConfig(ctx: PluginContext, fileConfig: TimberUserConfig): void
   };
 }
 
-function timberCache(_ctx: PluginContext): Plugin {
-  return cacheTransformPlugin();
+/**
+ * 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
+ *
+ * @rolldown/plugin-babel and babel-plugin-react-compiler are optional peer deps.
+ * If either is missing, require() fails with a clear error message.
+ */
+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'
+    );
+  }
+  const options = typeof config === 'object' ? config : {};
+  const babelPlugin = babel.default ?? babel;
+  return babelPlugin({
+    presets: [reactCompilerPreset(options as Parameters<typeof reactCompilerPreset>[0])],
+  }) as PluginOption;
+}
+
+/**
+ * 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 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),
+  };
+
+  // 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.
+
+/**
+ * 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();
+    config(userConfig, { command }) {
+      // ── 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');
 
+      // 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
@@ -401,17 +628,28 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
       }
     },
   };
+
+  // ── 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
@@ -424,30 +662,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(),
@@ -456,15 +670,14 @@ 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(),
+    ...reactCompilerPlugins,
     timberServerActionExports(),
-    rscPluginsPromise,
+    vitePluginRsc(createRscOptions(ctx, encryptionKeyExpr)),
     timberShims(ctx),
     timberRouting(ctx),
     timberEntries(ctx),
     timberBuildManifest(ctx),
-    timberCache(ctx),
     timberStaticBuild(ctx),
-    timberDynamicTransform(ctx),
     timberFonts(ctx),
     timberMdx(ctx),
     timberContent(ctx),
@@ -473,6 +686,7 @@ 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
   ];
 }
@@ -481,7 +695,7 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
  * 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 })
+ *   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.
@@ -490,4 +704,26 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface Routes {}
 
+/**
+ * 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';
+ *
+ * export default defineConfig({
+ *   output: 'server',
+ *   pageExtensions: ['tsx', 'ts', 'mdx'],
+ * });
+ * ```
+ */
+export function defineConfig(config: TimberUserConfig): TimberUserConfig {
+  return config;
+}
+
 export default timber;

package/src/plugins/adapter-build.ts

@@ -16,8 +16,8 @@
 import type { Plugin } from 'vite';
 import { join } from 'node:path';
 import { readFile, writeFile } from 'node:fs/promises';
-import type { PluginContext } from '#/index.js';
-import type { TimberPlatformAdapter, TimberConfig } from '#/adapters/types.js';
+import type { PluginContext } from '../index.js';
+import type { TimberPlatformAdapter, TimberConfig } from '../adapters/types.js';
 
 export function timberAdapterBuild(ctx: PluginContext): Plugin {
   return {
@@ -50,6 +50,12 @@ export function timberAdapterBuild(ctx: PluginContext): Plugin {
             : ctx.buildManifest;
           const json = JSON.stringify(manifest);
           manifestInit = `globalThis.__TIMBER_BUILD_MANIFEST__ = ${json};\n`;
+
+          // Embed the deployment ID for version skew detection (TIM-446).
+          // The server reads this at startup via setDeploymentId().
+          if (ctx.deploymentId) {
+            manifestInit += `globalThis.__TIMBER_DEPLOYMENT_ID__ = ${JSON.stringify(ctx.deploymentId)};\n`;
+          }
         }
 
         // Strip JS from the RSC plugin's assets manifest when client JS

package/src/plugins/build-manifest.ts

@@ -16,9 +16,10 @@
  * Design docs: 18-build-system.md §"Build Manifest", 02-rendering-pipeline.md §"Early Hints"
  */
 
+import { randomUUID } from 'node:crypto';
 import type { Plugin, ResolvedConfig } from 'vite';
-import type { PluginContext } from '#/index.js';
-import type { BuildManifest } from '#/server/build-manifest.js';
+import type { PluginContext } from '../index.js';
+import type { BuildManifest } from '../server/build-manifest.js';
 
 // Rollup types used by generateBundle hook — imported from vite which re-exports them.
 // We define minimal interfaces here to avoid a direct 'rollup' dependency.
@@ -242,6 +243,16 @@ export function timberBuildManifest(ctx: PluginContext): Plugin {
     configResolved(config: ResolvedConfig) {
       resolvedBase = config.base;
       isDev = config.command === 'serve';
+
+      // Generate a per-build deployment ID early so virtual:timber-config
+      // can serialize it during the load hook (which runs before generateBundle).
+      // A random UUID is used instead of a content hash — determinism provides
+      // no real benefit here since you almost never redeploy identical code,
+      // and a random ID avoids the timing problem where the content hash was
+      // only available after generateBundle (TIM-452).
+      if (!isDev && !ctx.deploymentId) {
+        ctx.deploymentId = randomUUID().replace(/-/g, '').slice(0, 16);
+      }
     },
 
     resolveId(id: string) {

package/src/plugins/build-report.ts

@@ -15,9 +15,9 @@
 
 import { gzipSync } from 'node:zlib';
 import type { Plugin, Logger } from 'vite';
-import type { PluginContext } from '#/index.js';
-import type { SegmentNode, RouteTree } from '#/routing/types.js';
-import { formatSize } from '#/utils/format.js';
+import type { PluginContext } from '../index.js';
+import type { SegmentNode, RouteTree } from '../routing/types.js';
+import { formatSize } from '../utils/format.js';
 
 // ─── Public types ─────────────────────────────────────────────────────────