@timber-js/app 0.2.0-alpha.6 → 0.2.0-alpha.61

package/src/index.ts

@@ -1,9 +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 react, { reactCompilerPreset } from '@vitejs/plugin-react';
 import { cacheTransformPlugin } from './plugins/cache-transform';
 import { timberContent } from './plugins/content';
 import { timberDevServer } from './plugins/dev-server';
@@ -13,12 +12,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 +26,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 +91,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.
+   *
+   * - `'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.
    *
-   * 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.
+   * 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 +164,46 @@ 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 };
   topLoader?: {
     /** Whether the top-loader is enabled. Default: true. */
     enabled?: boolean;
@@ -146,34 +218,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,6 +265,8 @@ 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;
 }
@@ -256,7 +302,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,
@@ -266,6 +315,7 @@ function createPluginContext(config?: TimberUserConfig, root?: string): PluginCo
     root: projectRoot,
     dev: false,
     buildManifest: null,
+    deploymentId: null,
     timer: createStartupTimer(),
   };
 }
@@ -273,14 +323,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;
     }
   }
@@ -300,7 +354,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);
     }
@@ -339,28 +392,155 @@ function mergeFileConfig(ctx: PluginContext, fileConfig: TimberUserConfig): void
   };
 }
 
+/**
+ * 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;
+}
+
 function timberCache(_ctx: PluginContext): Plugin {
   return cacheTransformPlugin();
 }
 
+/**
+ * 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: Build rootSync plugin ───────────────────────────────────
+  // rootSync loads timber.config.ts and resolves the Vite root.
+  // Config file loading happens in the `config` hook so it uses Vite's
+  // resolved root (from userConfig.root) instead of process.cwd().
+  // This is critical when running from a workspace root with
+  // `vite --config subdir/vite.config.ts` or a custom `root` option.
+  // See TIM-498.
   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');
 
       // Force production JSX transform for builds.
@@ -399,17 +579,49 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
       }
     },
   };
+
+  // ── Step 4: Resolve optional plugins ────────────────────────────────
+  // React Compiler — controlled by reactCompiler in config (inline or file).
+  // If set in inline config, resolve immediately. If it comes from
+  // timber.config.ts, it's picked up in rootSync's config hook and
+  // resolved lazily via the timber-react-compiler wrapper plugin.
+  const reactCompilerPlugins: PluginOption[] = [];
+  if (config?.reactCompiler) {
+    // Inline config — resolve eagerly (preserves sync throw on missing dep)
+    reactCompilerPlugins.push(resolveReactCompilerPlugin(config.reactCompiler, consumerRequire));
+  }
+  // Lazy wrapper for file-based reactCompiler config (timber.config.ts).
+  // After rootSync loads the file config in its `config` hook, this plugin's
+  // `configResolved` hook checks if reactCompiler was added by the file and
+  // not already resolved from inline config. If so, it resolves and copies
+  // the babel plugin's hooks onto itself so Vite invokes them.
+  const lazyReactCompiler: Plugin = {
+    name: 'timber-react-compiler',
+    configResolved() {
+      // Skip if already resolved from inline config or not configured
+      if (config?.reactCompiler || !ctx.config.reactCompiler) return;
+      // File config set reactCompiler — resolve and copy hooks
+      const resolved = resolveReactCompilerPlugin(
+        ctx.config.reactCompiler,
+        consumerRequire
+      ) as Plugin;
+      // Copy transform/resolveId/etc hooks from the babel plugin
+      for (const key of Object.keys(resolved) as (keyof Plugin)[]) {
+        if (key !== 'name') {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          (lazyReactCompiler as any)[key] = resolved[key];
+        }
+      }
+    },
+  };
+
+  // ── 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 +634,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 +642,16 @@ 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,
+    lazyReactCompiler,
     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),
@@ -471,6 +660,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
   ];
 }
@@ -488,4 +678,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;