@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.181

package/src/params/codec-registry.ts

@@ -0,0 +1,34 @@
+/**
+ * Client-side registry for schema segment param codecs.
+ *
+ * The Link component uses codec `serialize` functions to convert typed
+ * segment param values back to URL-safe strings. Without this registry,
+ * Link falls back to `String(value)` — which works for simple types
+ * but breaks for custom codecs (e.g., Date → '2026-04-10').
+ *
+ * Populated at startup by the browser entry importing `virtual:timber-schema`.
+ * Also usable on the server (isomorphic).
+ *
+ * Design doc: design/41-global-params.md §"Link Component"
+ */
+
+import type { Codec } from '../codec.js';
+
+let _codecs: Record<string, Codec<unknown>> | null = null;
+
+/**
+ * Register the resolved schema codecs for use by Link's URL interpolation.
+ * Called once at startup from the browser entry or RSC entry.
+ * @internal
+ */
+export function setLinkCodecs(codecs: Record<string, Codec<unknown>> | null): void {
+  _codecs = codecs;
+}
+
+/**
+ * Look up a codec by bracket key (e.g. '[id]', '[...slug]').
+ * Returns undefined if no schema is registered or the key has no codec.
+ */
+export function getLinkCodec(bracketKey: string): Codec<unknown> | undefined {
+  return _codecs?.[bracketKey] ?? undefined;
+}

package/src/params/define-schema.ts

@@ -0,0 +1,115 @@
+/**
+ * defineSchema — global segment param schema definition.
+ *
+ * Identity function at runtime; the type information is what matters.
+ * The Vite plugin reads the schema at build time for codegen, and
+ * the pipeline reads it at runtime for coercion.
+ *
+ * Design doc: design/41-global-params.md
+ */
+
+import type { Codec, CatchAllCodec, OptionalCatchAllCodec } from '../codec.js';
+import type { StandardSchemaV1 } from '../schema-bridge.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Infer the output type from a Codec, StandardSchemaV1, or nuqs parser.
+ *
+ * Used by codegen to reference schema types without hardcoding:
+ *   `InferCodecType<typeof schema.segmentParams['[year]']>`
+ */
+export type InferCodecType<V> =
+  V extends Codec<infer T>
+    ? T
+    : V extends StandardSchemaV1<infer T>
+      ? T
+      : V extends { parseServerSide: (value: string) => infer T }
+        ? T
+        : string;
+
+/** Acceptable codec value for segment params: a Codec or Standard Schema. */
+export type SegmentParamCodec = Codec<unknown> | StandardSchemaV1<unknown>;
+
+/** Codec constraint for catch-all segment keys (`[...name]`). */
+export type CatchAllParamCodec = CatchAllCodec<unknown> | StandardSchemaV1<readonly unknown[]>;
+
+/** Codec constraint for optional catch-all segment keys (`[[...name]]`). */
+export type OptionalCatchAllParamCodec =
+  | OptionalCatchAllCodec<unknown>
+  | StandardSchemaV1<readonly unknown[] | undefined>;
+
+/**
+ * Resolves the required codec type for a given bracket key pattern.
+ * - `[...name]`    → requires a catch-all codec
+ * - `[[...name]]`  → requires an optional catch-all codec
+ * - `[name]`       → accepts any segment param codec
+ */
+export type CodecForKey<K extends string> = K extends `[[...${string}]]`
+  ? OptionalCatchAllParamCodec
+  : K extends `[...${string}]`
+    ? CatchAllParamCodec
+    : SegmentParamCodec;
+
+/**
+ * Registry interface augmented by codegen with known filesystem bracket keys.
+ * When empty (no codegen yet), ValidDynamicSegmentKeys falls back to string.
+ */
+// eslint-disable-next-line typescript/no-empty-interface -- augmented by codegen
+export interface ValidDynamicSegmentKeysRegistry {}
+
+/**
+ * Union of valid bracket keys for defineSchema.
+ * After codegen runs, this is the set of filesystem segment names.
+ * Before codegen (fresh project), accepts any string.
+ */
+export type ValidDynamicSegmentKeys = keyof ValidDynamicSegmentKeysRegistry extends never
+  ? string
+  : keyof ValidDynamicSegmentKeysRegistry & string;
+
+/** Configuration object for defineSchema. */
+export interface SchemaConfig<S extends Record<string, SegmentParamCodec>> {
+  segmentParams: S;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Define the global segment param schema.
+ *
+ * Each key uses the bracket syntax from the filesystem (`[id]`, `[...slug]`,
+ * `[[...slug]]`) mapped to a codec. This makes the relationship between
+ * filesystem segments and codecs visually obvious.
+ *
+ * A dynamic segment with no key here defaults to `string` at codegen time.
+ *
+ * ```ts
+ * // app/schema.ts
+ * import { defineSchema } from '@timber-js/app/params';
+ * import { codec } from '@timber-js/app/codec';
+ * import { z } from 'zod';
+ *
+ * export default defineSchema({
+ *   segmentParams: {
+ *     '[artistSlug]': codec.string,
+ *     '[year]': codec.integer,
+ *     '[id]': z.coerce.number().int(),
+ *   },
+ * });
+ * ```
+ */
+export function defineSchema<
+  S extends {
+    [K in keyof S]: K extends ValidDynamicSegmentKeys
+      ? K extends string
+        ? CodecForKey<K>
+        : SegmentParamCodec
+      : never;
+  },
+>(config: { segmentParams: S }): { segmentParams: S } {
+  return config;
+}

package/src/params/index.ts

@@ -0,0 +1,17 @@
+// @timber-js/app/params — Global segment param schema and typed accessors.
+//
+// This is the import path for defineSchema, InferCodecType, and
+// the future getSegmentParams/useSegmentParams with route narrowing.
+//
+// See design/41-global-params.md
+
+export { defineSchema } from './define-schema.js';
+export type {
+  InferCodecType,
+  SchemaConfig,
+  SegmentParamCodec,
+  ValidDynamicSegmentKeys,
+  ValidDynamicSegmentKeysRegistry,
+} from './define-schema.js';
+export { resolveSchemaCodecs, toBracketKey } from './resolve-schema.js';
+export { setLinkCodecs, getLinkCodec } from './codec-registry.js';

package/src/params/resolve-schema.ts

@@ -0,0 +1,84 @@
+/**
+ * Schema resolution — resolves the global schema's segmentParams into
+ * a runtime-ready codec map keyed by bracket name (e.g. '[id]').
+ *
+ * Bracket keys are preserved so that `[id]`, `[...id]`, and `[[...id]]`
+ * remain distinct entries. The coercion layer reconstructs bracket keys
+ * from matched segment metadata to look up the correct codec.
+ *
+ * Design doc: design/41-global-params.md §Pipeline Integration
+ */
+
+import type { Codec } from '../codec.js';
+import { isCodec, resolveCodecOrSchema } from '../schema-bridge.js';
+
+/**
+ * Reconstruct the bracket key for a segment from its type and param name.
+ * Used by the coercion layer to look up codecs in the bracket-keyed map.
+ *
+ * 'dynamic'          + 'id'   → '[id]'
+ * 'catch-all'        + 'slug' → '[...slug]'
+ * 'optional-catch-all' + 'slug' → '[[...slug]]'
+ */
+export function toBracketKey(segmentType: string, paramName: string): string {
+  switch (segmentType) {
+    case 'catch-all':
+      return `[...${paramName}]`;
+    case 'optional-catch-all':
+      return `[[...${paramName}]]`;
+    default:
+      return `[${paramName}]`;
+  }
+}
+
+const CATCH_ALL_RE = /^\[\.\.\..+\]$/;
+const OPTIONAL_CATCH_ALL_RE = /^\[\[\.\.\..+\]\]$/;
+
+function isCatchAllKey(key: string): boolean {
+  return CATCH_ALL_RE.test(key) || OPTIONAL_CATCH_ALL_RE.test(key);
+}
+
+function isOptionalCatchAllKey(key: string): boolean {
+  return OPTIONAL_CATCH_ALL_RE.test(key);
+}
+
+/**
+ * Resolve the global schema's segmentParams into a map of bracket-keyed
+ * param name → resolved Codec.
+ *
+ * Keys are preserved exactly as written in `app/schema.ts` so that
+ * `[id]`, `[...id]`, and `[[...id]]` remain distinct entries.
+ * The coercion layer in `param-coercion.ts` reconstructs bracket keys
+ * from matched segment metadata to look up the correct codec.
+ *
+ * Input:  { '[id]': z.coerce.number(), '[...slug]': codec.string }
+ * Output: { '[id]': Codec<number>, '[...slug]': Codec<string> }
+ */
+export function resolveSchemaCodecs(
+  segmentParams: Record<string, unknown>
+): Record<string, Codec<unknown>> {
+  const resolved: Record<string, Codec<unknown>> = Object.create(null);
+
+  for (const [bracketName, value] of Object.entries(segmentParams)) {
+    if (isCatchAllKey(bracketName) && isCodec(value) && !('__catchAll' in value)) {
+      throw new Error(
+        `[timber] Schema error: '${bracketName}' is a catch-all segment and requires an array codec ` +
+          `(e.g. codec.catchAll(codec.string)). Got a scalar codec.`
+      );
+    }
+    if (
+      isOptionalCatchAllKey(bracketName) &&
+      isCodec(value) &&
+      '__catchAll' in value &&
+      !('__optional' in value)
+    ) {
+      throw new Error(
+        `[timber] Schema error: '${bracketName}' is an optional catch-all segment and requires codec.optionalCatchAll() ` +
+          `(e.g. codec.optionalCatchAll(codec.string)). Got a non-optional catch-all codec.`
+      );
+    }
+    resolved[bracketName] = resolveCodecOrSchema(bracketName, value, 'param');
+  }
+
+  return resolved;
+}

package/src/plugin-context.ts

@@ -0,0 +1,432 @@
+/**
+ * Plugin context — internal types and helpers for timber sub-plugins.
+ *
+ * These are NOT part of the user-facing API. They are consumed by
+ * sub-plugins (routing, entries, shims, etc.) via relative imports.
+ * The root entry point (index.ts) does not re-export them.
+ *
+ * Design doc: 18-build-system.md §"Shared Plugin Context"
+ */
+
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+import { parseAst } from 'vite';
+import type { RouteTree } from './routing/types';
+import type { BuildManifest } from './server/build-manifest';
+import type { CaptureSummary } from './server/prebuilt-builder';
+import type { StartupTimer } from './utils/startup-timer';
+import { createStartupTimer } from './utils/startup-timer';
+import type { TimberUserConfig, ClientJavascriptConfig } from './config-types.js';
+import type { HoldingServer } from './dev-tools/holding-server.js';
+import type { ProgramNode } from './plugins/callsite-ast.js';
+
+// Re-export for sub-plugin convenience — they import from plugin-context.ts
+export type { TimberUserConfig, ClientJavascriptConfig } from './config-types.js';
+
+// ── Client JavaScript config ─────────────────────────────────────────────
+
+/** Fully resolved client JavaScript configuration (no optionals). */
+export interface ResolvedClientJavascript {
+  disabled: boolean;
+  enableHMRInDev: boolean;
+}
+
+/**
+ * Resolve `clientJavascript` into a fully resolved config.
+ */
+export function resolveClientJavascript(config: TimberUserConfig): ResolvedClientJavascript {
+  if (config.clientJavascript !== undefined) {
+    if (typeof config.clientJavascript === 'boolean') {
+      return {
+        disabled: !config.clientJavascript,
+        enableHMRInDev: !config.clientJavascript,
+      };
+    }
+    return {
+      disabled: config.clientJavascript.disabled,
+      enableHMRInDev: config.clientJavascript.enableHMRInDev ?? config.clientJavascript.disabled,
+    };
+  }
+  return { disabled: false, enableHMRInDev: false };
+}
+
+// ── Plugin Context ────────────────────────────────────────────────────────
+
+/**
+ * Shared context object passed to all sub-plugins via closure.
+ *
+ * Sub-plugins communicate through this context — not through Vite's
+ * plugin API or global state.
+ * See design/18-build-system.md §"Shared Plugin Context".
+ */
+export 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;
+  /** 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;
+  /** Holding server that binds the port during dev startup (closed in timber-dev-server) */
+  holdingServer?: HoldingServer | null;
+  /**
+   * Resolved absolute path to the build output directory.
+   *
+   * Defaults to `<root>/.timber/dist`. Can be overridden via
+   * `timber.config.ts` `buildDir` or Vite's `build.outDir`.
+   * Timber config takes precedence when both are set.
+   *
+   * Used by adapter-build and cli preview.
+   */
+  buildDir: string;
+  /**
+   * Per-route client reference keys captured during the RSC build.
+   * Maps absolute route file paths to the set of client reference
+   * hash keys they transitively import. Used by adapter-build to
+   * populate per-route modulepreload entries from clientReferenceDeps.
+   */
+  routeClientRefKeys?: Map<string, Set<string>>;
+  /**
+   * Maps absolute module IDs of client references in non-facade RSC
+   * chunks to the absolute paths of their consuming facade modules.
+   * Built during the RSC `generateBundle` phase by timber-chunks,
+   * consumed by `clientChunkGroup` to reclassify `shared:` modules
+   * that are only used by a single route boundary.
+   * See design/27-chunking-strategy.md, TIM-1107.
+   */
+  sharedModuleFacades?: Map<string, string[]>;
+  /**
+   * Module ID → prebuilt component IDs declared in it. Recorded by the
+   * timber-prebuilt transform (RSC environment, production builds only),
+   * consumed by the RSC `generateBundle` module-graph walk that computes
+   * `routePrebuiltComponents`. See design/44-render-at-build-time.md.
+   */
+  prebuiltModuleComponents?: Map<string, string[]>;
+  /**
+   * Module ID → mapping of variable name to component ID for the prebuilt
+   * components declared in that module. Used at `generateBundle` time to
+   * trace imports from other modules back to specific component IDs.
+   */
+  prebuiltBindingNames?: Map<string, Map<string, string>>;
+  /**
+   * Component ID → distinct static call-site prop objects captured from
+   * JSX usage sites during the transform and generateBundle phases.
+   * Consumed by the post-build capture pass to render with actual props
+   * instead of empty `{}`. See design/44 §Props Derivation.
+   */
+  prebuiltCallSiteProps?: Map<string, Record<string, unknown>[]>;
+  /**
+   * Route file path (page or layout, absolute) → prebuilt component IDs
+   * transitively reachable from it. Computed during RSC `generateBundle`,
+   * consumed by the post-build capture pass (TIM-1119) to decide which
+   * components to render under which route's param combos.
+   */
+  routePrebuiltComponents?: Map<string, string[]>;
+  /**
+   * Page file paths that were desugared from `export const prerender` by
+   * timber-prerender-sugar. The prebuilt transform uses this to verify
+   * the generated `cache.component(...)` call was picked up.
+   */
+  prerenderSugarPages?: Set<string>;
+  /**
+   * Component ID → built chunk file name for prebuilt-declaring modules
+   * that are only reachable via dynamic imports (import.meta.glob, lazy
+   * routes). The capture pass imports these chunks to trigger
+   * cache.component() registration before rendering. Populated during
+   * RSC generateBundle alongside routePrebuiltComponents.
+   */
+  prebuiltLazyChunks?: Map<string, string>;
+  /** Post-build prebuilt capture summary (populated by timber-prebuilt, consumed by build-report). */
+  captureSummary?: CaptureSummary;
+  /**
+   * Content-keyed AST parse memo shared across cache/prebuilt/prerender-sugar
+   * transforms. Collapses both cross-plugin and cross-environment duplicate
+   * parses: identical code hits, rewritten code misses (correct because Vite
+   * transforms chain — a rewrite produces different code). Bounded LRU (32
+   * entries) so it doesn't hold programs for the whole build.
+   *
+   * Consumers MUST treat the returned ProgramNode as read-only — they collect
+   * ranges and rewrite CODE via MagicString; the AST itself is never mutated.
+   */
+  parseCached?: ParseMemo;
+}
+
+// ── AST parse memo ───────────────────────────────────────────────────────
+
+const PARSE_MEMO_CAPACITY = 32;
+
+/**
+ * Content-keyed LRU memo for `parseAst`. Transforms for the same module run
+ * back-to-back across plugins and environments, so a tiny window captures the
+ * wins. The returned ProgramNode is shared — callers MUST NOT mutate it.
+ */
+export class ParseMemo {
+  private cache = new Map<string, ProgramNode>();
+
+  /**
+   * Parse code, returning a cached ProgramNode if the same code was parsed
+   * before. The returned AST MUST NOT be mutated — it may be shared across
+   * multiple consumers.
+   */
+  parse(code: string): ProgramNode {
+    const existing = this.cache.get(code);
+    if (existing) {
+      // LRU refresh: move to end
+      this.cache.delete(code);
+      this.cache.set(code, existing);
+      return existing;
+    }
+    const program = parseAst(code, { lang: 'tsx' }) as unknown as ProgramNode;
+    if (this.cache.size >= PARSE_MEMO_CAPACITY) {
+      // Evict oldest (first inserted)
+      const firstKey = this.cache.keys().next().value!;
+      this.cache.delete(firstKey);
+    }
+    this.cache.set(code, program);
+    return program;
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+}
+
+// ── App directory resolution ──────────────────────────────────────────────
+
+/**
+ * Resolve the app directory. Checks (in order):
+ * 1. Explicit `configAppDir` from timber.config.ts
+ * 2. `<root>/app`
+ * 3. `<root>/src/app`
+ *
+ * Throws if none exist.
+ */
+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.`
+  );
+}
+
+// ── Plugin context factory ────────────────────────────────────────────────
+
+export function createPluginContext(config?: TimberUserConfig, root?: string): PluginContext {
+  const projectRoot = root ?? process.cwd();
+  const resolvedConfig: TimberUserConfig = { ...config };
+  return {
+    config: resolvedConfig,
+    clientJavascript: resolveClientJavascript(resolvedConfig),
+    routeTree: null,
+    appDir: join(projectRoot, 'app'),
+    root: projectRoot,
+    dev: false,
+    buildManifest: null,
+    deploymentId: null,
+    timer: createStartupTimer(),
+    holdingServer: null,
+    buildDir: resolveBuildDir(projectRoot, resolvedConfig.buildDir),
+    parseCached: new ParseMemo(),
+  };
+}
+
+// ── Build directory resolution ────────────────────────────────────────────
+
+/** Default build output directory (relative to root). */
+export const DEFAULT_BUILD_DIR = join('.timber', 'dist');
+
+/**
+ * Resolve the build output directory.
+ *
+ * Priority:
+ * 1. Explicit `timberBuildDir` from timber.config.ts
+ * 2. Explicit `viteBuildOutDir` from Vite's build.outDir (if not the default 'dist')
+ * 3. Default: `.timber/dist`
+ *
+ * Returns an absolute path.
+ */
+export function resolveBuildDir(
+  root: string,
+  timberBuildDir?: string,
+  viteBuildOutDir?: string
+): string {
+  if (timberBuildDir) {
+    return resolve(root, timberBuildDir);
+  }
+  if (viteBuildOutDir && viteBuildOutDir !== 'dist') {
+    return resolve(root, viteBuildOutDir);
+  }
+  return join(root, DEFAULT_BUILD_DIR);
+}
+
+// ── Config file loading ───────────────────────────────────────────────────
+
+/**
+ * Map known timber.config load failures to actionable hints (TIM-1040).
+ * Returns null when the error has no known remedy beyond its own message.
+ *
+ * Known failure modes of loading timber.config.ts via native require():
+ * - Node < 22.18 has no default type stripping → ERR_UNKNOWN_FILE_EXTENSION
+ * - Non-erasable TS syntax (enums, namespaces, parameter properties)
+ *   → ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX / ERR_INVALID_TYPESCRIPT_SYNTAX
+ * - ESM syntax in a `"type": "commonjs"` package → the stripped .ts is
+ *   parsed as CJS and throws SyntaxError: "Unexpected token 'export'"
+ *   (export statements) or "Cannot use import statement outside a
+ *   module" (import statements)
+ */
+export function configLoadHint(configName: string, err: unknown): string | null {
+  const code = (err as NodeJS.ErrnoException | null)?.code;
+  const isTs = configName.endsWith('.ts');
+
+  if (isTs && code === 'ERR_UNKNOWN_FILE_EXTENSION') {
+    return (
+      'Loading a TypeScript config requires Node.js 22.18+ (built-in type stripping). ' +
+      'Upgrade Node.js or rewrite the config as timber.config.js.'
+    );
+  }
+  if (code === 'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX' || code === 'ERR_INVALID_TYPESCRIPT_SYNTAX') {
+    return (
+      'Node.js loads the config with type stripping, which only supports erasable TypeScript syntax — ' +
+      'replace enums, namespaces, and constructor parameter properties with plain objects and types.'
+    );
+  }
+  if (
+    isTs &&
+    err instanceof SyntaxError &&
+    /Unexpected token '(export|import)'|Cannot use import statement outside a module/.test(
+      err.message
+    )
+  ) {
+    return (
+      'The config uses ESM syntax but Node.js parsed it as CommonJS — ' +
+      'set "type": "module" in package.json, or use module.exports instead of export default.'
+    );
+  }
+  return null;
+}
+
+/**
+ * Load timber.config.ts (or .js, .mjs) from the project root.
+ * Returns the config object or null if no config file is found.
+ * Throws a descriptive error naming the file when a config file exists
+ * but fails to load — a broken config must fail loudly, never silently
+ * degrade (see TIM-1066). Known failure modes get an actionable hint
+ * appended (see configLoadHint, TIM-1040).
+ *
+ * Uses require() — Node 22.12+ can require() ESM modules, and Node
+ * 22.18+ strips types from .ts files by default (hence the engines
+ * field requiring >=22.18.0). This keeps timber() synchronous — no
+ * async config loading needed.
+ * This is the single config loader — dev, build, and preview all use it.
+ */
+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)) {
+      try {
+        const mod = req(configPath);
+        return (mod.default ?? mod) as TimberUserConfig;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const hint = configLoadHint(name, err);
+        throw new Error(
+          `[timber] Failed to load ${configPath}: ${message}${hint ? `\n${hint}` : ''}`,
+          { cause: err }
+        );
+      }
+    }
+  }
+  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.
+ *
+ * Returns the list of conflicting key names (for testing).
+ */
+export function warnConfigConflicts(
+  inline: TimberUserConfig,
+  fileConfig: TimberUserConfig
+): string[] {
+  const conflicts: string[] = [];
+  for (const key of Object.keys(fileConfig) as (keyof TimberUserConfig)[]) {
+    if (key in inline && inline[key] !== undefined) {
+      conflicts.push(key);
+    }
+  }
+  if (conflicts.length > 0) {
+    console.warn(
+      `[timber] Config conflict: ${conflicts.map((k) => `"${k}"`).join(', ')} set in both ` +
+        `vite.config.ts (inline) and timber.config.ts. ` +
+        `Move all config to timber.config.ts to avoid confusion. ` +
+        `The inline value from vite.config.ts will be used.`
+    );
+  }
+  return conflicts;
+}
+
+/**
+ * Drop own keys whose value is `undefined` so they don't clobber file
+ * config during spread merging. `timber({ buildDir: process.env.BUILD_DIR })`
+ * with the var unset must not erase the timber.config.ts value.
+ */
+function stripUndefined<T extends object>(obj: T): T {
+  return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined)) as T;
+}
+
+/**
+ * Merge file-based config (timber.config.ts) with inline config (vite.config.ts).
+ * Inline config takes precedence — file config only fills in missing fields.
+ * Inline keys explicitly set to `undefined` are treated as absent, matching
+ * the `!== undefined` check in warnConfigConflicts.
+ */
+export function mergeFileConfig(
+  inline: TimberUserConfig,
+  fileConfig: TimberUserConfig
+): TimberUserConfig {
+  warnConfigConflicts(inline, fileConfig);
+  const definedInline = stripUndefined(inline);
+
+  return {
+    ...fileConfig,
+    ...definedInline,
+    ...(fileConfig.limits && definedInline.limits
+      ? { limits: { ...fileConfig.limits, ...stripUndefined(definedInline.limits) } }
+      : {}),
+    ...(fileConfig.dev && definedInline.dev
+      ? { dev: { ...fileConfig.dev, ...stripUndefined(definedInline.dev) } }
+      : {}),
+    ...(fileConfig.mdx && definedInline.mdx
+      ? { mdx: { ...fileConfig.mdx, ...stripUndefined(definedInline.mdx) } }
+      : {}),
+  };
+}