@timber-js/app 0.2.0-alpha.34 → 0.2.0-alpha.36

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,12 @@ import { timberRouting } from './plugins/routing';
 import { timberShims } from './plugins/shims';
 import { timberFonts } from './plugins/fonts';
 import { timberStaticBuild } from './plugins/static-build';
-import { timberDynamicTransform } from './plugins/dynamic-transform';
 import { timberServerActionExports } from './plugins/server-action-exports';
 import { timberBuildManifest } from './plugins/build-manifest';
 import { timberDevLogs } from './plugins/dev-logs';
 import { timberReactProd } from './plugins/react-prod';
 import { timberChunks } from './plugins/chunks';
+import { 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 {
@@ -95,18 +95,6 @@ export interface TimberUserConfig {
     /** Threshold in ms to highlight slow phases in dev logging output. Default: 200. */
     slowPhaseMs?: number;
   };
-  /**
-   * Cookie signing configuration. See design/29-cookies.md §"Signed Cookies".
-   *
-   * Provide `secret` for a single key, or `secrets` (array) for key rotation.
-   * When `secrets` is used, index 0 is the signing key; all are tried for verification.
-   */
-  cookies?: {
-    /** Single signing secret. Shorthand for `secrets: [secret]`. */
-    secret?: string;
-    /** Array of signing secrets for key rotation. Index 0 signs; all verify. */
-    secrets?: string[];
-  };
   /**
    * Control Server-Timing header output.
    *
@@ -148,6 +136,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;
@@ -209,6 +237,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;
 }
@@ -244,7 +274,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,
@@ -254,6 +287,7 @@ function createPluginContext(config?: TimberUserConfig, root?: string): PluginCo
     root: projectRoot,
     dev: false,
     buildManifest: null,
+    deploymentId: null,
     timer: createStartupTimer(),
   };
 }
@@ -261,14 +295,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;
     }
   }
@@ -288,7 +326,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);
     }
@@ -327,28 +364,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.
@@ -387,17 +551,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
@@ -410,35 +606,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',
-        },
-        // Group all client reference wrappers into a single chunk instead of
-        // creating one tiny file per "use client" module. Without this, each
-        // server chunk's client references become a separate entry point,
-        // producing many sub-500B wrapper files (e.g., 30-byte re-exports).
-        // A single group eliminates 10+ unnecessary HTTP requests.
-        // See design/27-chunking-strategy.md and TIM-440.
-        clientChunks: () => 'client-refs',
-      });
-    }
-  );
-
   return [
     rootSync,
     timberReactProd(),
@@ -447,15 +614,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),
@@ -481,4 +649,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;