@timber-js/app 0.2.0-alpha.86 → 0.2.0-alpha.88

package/src/fonts/transform.ts

@@ -0,0 +1,353 @@
+/**
+ * Transform-hook logic for the timber-fonts plugin.
+ *
+ * Scans source files for font function calls (`Inter({...})`,
+ * `localFont({...})`), validates that they are statically analysable,
+ * registers the extracted fonts in the `FontPipeline`, and rewrites the
+ * call sites to static `FontResult` literals so the runtime never has to
+ * evaluate the font function.
+ *
+ * Design doc: 24-fonts.md
+ */
+
+import type { ExtractedFont, GoogleFontConfig } from './types.js';
+import { buildFontStack } from './fallbacks.js';
+import { processLocalFont } from './local.js';
+import {
+  extractFontConfigAst,
+  extractLocalFontConfigAst,
+  detectDynamicFontCallAst,
+} from './ast.js';
+import type { FontPipeline } from './pipeline.js';
+import { VIRTUAL_FONT_CSS_REGISTER } from './virtual-modules.js';
+
+/**
+ * Regex that matches imports from either `@timber/fonts/google` or
+ * `next/font/google` (which the shims plugin resolves to the same virtual
+ * module). The transform hook still needs to recognise both spellings in
+ * source code.
+ */
+const GOOGLE_FONT_IMPORT_RE =
+  /import\s*\{([^}]+)\}\s*from\s*['"](?:@timber\/fonts\/google|@timber-js\/app\/fonts\/google|next\/font\/google)['"]/g;
+
+/**
+ * Convert a font family name to a scoped class name.
+ * e.g. "JetBrains Mono" → "timber-font-jetbrains-mono"
+ */
+function familyToClassName(family: string): string {
+  return `timber-font-${family.toLowerCase().replace(/\s+/g, '-')}`;
+}
+
+/** Normalize a string or string array to an array (default `['400']`). */
+function normalizeWeightArray(value: string | string[] | undefined): string[] {
+  if (!value) return ['400'];
+  return Array.isArray(value) ? value : [value];
+}
+
+/** Normalize style to an array (default `['normal']`). */
+function normalizeStyleArray(value: string | string[] | undefined): string[] {
+  if (!value) return ['normal'];
+  return Array.isArray(value) ? value : [value];
+}
+
+/**
+ * Generate a unique font ID from family + config hash.
+ *
+ * The ID intentionally includes every property that affects the rendered
+ * `@font-face` output (`weight`, `style`, `subsets`, `display`) so that an
+ * HMR edit changing any of those produces a new ID and the registry is
+ * forced to re-emit fresh CSS.
+ */
+export function generateFontId(family: string, config: GoogleFontConfig): string {
+  const weights = normalizeWeightArray(config.weight);
+  const styles = normalizeStyleArray(config.style);
+  const subsets = config.subsets ?? ['latin'];
+  const display = config.display ?? 'swap';
+  return `${family.toLowerCase()}-${weights.join(',')}-${styles.join(',')}-${subsets.join(',')}-${display}`;
+}
+
+/**
+ * Extract static font config from a font function call source.
+ *
+ * Returns `null` if the call cannot be statically analysed.
+ */
+export function extractFontConfig(callSource: string): GoogleFontConfig | null {
+  return extractFontConfigAst(callSource);
+}
+
+/**
+ * Detect dynamic/computed font function calls that cannot be statically
+ * analysed. Returns the offending expression text, or `null` if all calls
+ * are static.
+ */
+export function detectDynamicFontCall(source: string, importedNames: string[]): string | null {
+  return detectDynamicFontCallAst(source, importedNames);
+}
+
+/**
+ * Parse the local names imported from `@timber/fonts/google` /
+ * `next/font/google`. e.g. `import { Inter, JetBrains_Mono as Mono }` →
+ * `['Inter', 'Mono']`.
+ */
+export function parseGoogleFontImports(source: string): string[] {
+  const importPattern = new RegExp(GOOGLE_FONT_IMPORT_RE.source, 'g');
+  const names: string[] = [];
+
+  let match;
+  while ((match = importPattern.exec(source)) !== null) {
+    const specifiers = match[1]
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+    for (const spec of specifiers) {
+      // Handle `Inter as MyInter` — we want the local name
+      const parts = spec.split(/\s+as\s+/);
+      names.push(parts[parts.length - 1].trim());
+    }
+  }
+
+  return names;
+}
+
+/**
+ * Parse Google font imports into a `localName → familyName` map.
+ *
+ * e.g. `import { JetBrains_Mono as Mono }` → `{ Mono: 'JetBrains Mono' }`.
+ * The original (pre-`as`) name is converted from PascalCase-with-underscores
+ * to the human-readable family name by replacing `_` with a space.
+ */
+export function parseGoogleFontFamilies(source: string): Map<string, string> {
+  const importPattern = new RegExp(GOOGLE_FONT_IMPORT_RE.source, 'g');
+  const families = new Map<string, string>();
+
+  let match;
+  while ((match = importPattern.exec(source)) !== null) {
+    const specifiers = match[1]
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+    for (const spec of specifiers) {
+      const parts = spec.split(/\s+as\s+/);
+      const originalName = parts[0].trim();
+      const localName = parts[parts.length - 1].trim();
+      // Convert export name back to family name: JetBrains_Mono → JetBrains Mono
+      const family = originalName.replace(/_/g, ' ');
+      families.set(localName, family);
+    }
+  }
+
+  return families;
+}
+
+/**
+ * Parse the local name used for the default import of `@timber/fonts/local`.
+ *
+ * Handles either spelling and arbitrary local names:
+ *   import localFont from '@timber/fonts/local'
+ *   import myLoader from 'next/font/local'
+ */
+export function parseLocalFontImportName(source: string): string | null {
+  const match = source.match(
+    /import\s+(\w+)\s+from\s*['"](?:@timber\/fonts\/local|@timber-js\/app\/fonts\/local|next\/font\/local)['"]/
+  );
+  return match ? match[1] : null;
+}
+
+/** Build the static `FontResult` literal we substitute for a font call. */
+function buildFontResultLiteral(extracted: ExtractedFont): string {
+  return extracted.variable
+    ? `{ className: "${extracted.className}", style: { fontFamily: "${extracted.fontFamily}" }, variable: "${extracted.variable}" }`
+    : `{ className: "${extracted.className}", style: { fontFamily: "${extracted.fontFamily}" } }`;
+}
+
+/** Type for the Vite plugin's `this.error` callback. */
+type EmitError = (msg: string) => never;
+
+/**
+ * Find Google font calls in `originalCode`, register them in the pipeline,
+ * and replace each call site in `transformedCode` with a static FontResult.
+ */
+function transformGoogleFonts(
+  transformedCode: string,
+  originalCode: string,
+  importerId: string,
+  pipeline: FontPipeline,
+  emitError: EmitError
+): string {
+  const families = parseGoogleFontFamilies(originalCode);
+  if (families.size === 0) return transformedCode;
+
+  const importedNames = [...families.keys()];
+
+  const dynamicCall = detectDynamicFontCall(originalCode, importedNames);
+  if (dynamicCall) {
+    emitError(
+      `Font function calls must be statically analyzable. ` +
+        `Found dynamic call: ${dynamicCall}. ` +
+        `Pass a literal object with string/array values instead.`
+    );
+  }
+
+  for (const [localName, family] of families) {
+    const callPattern = new RegExp(
+      `(?:const|let|var)\\s+(\\w+)\\s*=\\s*${localName}\\s*\\(\\s*(\\{[\\s\\S]*?\\})\\s*\\)`,
+      'g'
+    );
+
+    let callMatch;
+    while ((callMatch = callPattern.exec(originalCode)) !== null) {
+      const varName = callMatch[1];
+      const configSource = callMatch[2];
+      const fullMatch = callMatch[0];
+
+      const config = extractFontConfig(`(${configSource})`);
+      if (!config) {
+        emitError(
+          `Could not statically analyze font config for ${family}. ` +
+            `Ensure all config values are string literals or arrays of string literals.`
+        );
+      }
+
+      const fontId = generateFontId(family, config!);
+      const className = familyToClassName(family);
+      const fontStack = buildFontStack(family);
+      const display = config!.display ?? 'swap';
+
+      const extracted: ExtractedFont = {
+        id: fontId,
+        family,
+        provider: 'google',
+        weights: normalizeWeightArray(config!.weight),
+        styles: normalizeStyleArray(config!.style),
+        subsets: config!.subsets ?? ['latin'],
+        display,
+        variable: config!.variable,
+        className,
+        fontFamily: fontStack,
+        importer: importerId,
+      };
+
+      pipeline.pruneFor(importerId, family);
+      pipeline.register(extracted);
+
+      const replacement = `const ${varName} = ${buildFontResultLiteral(extracted)}`;
+      transformedCode = transformedCode.replace(fullMatch, replacement);
+    }
+  }
+
+  // Strip the import statement; the values it referred to are now inlined.
+  transformedCode = transformedCode.replace(
+    /import\s*\{[^}]+\}\s*from\s*['"](?:@timber\/fonts\/google|@timber-js\/app\/fonts\/google|next\/font\/google)['"];?\s*\n?/g,
+    ''
+  );
+
+  return transformedCode;
+}
+
+/**
+ * Find local font calls in `originalCode`, register them in the pipeline,
+ * and replace each call site in `transformedCode` with a static FontResult.
+ */
+function transformLocalFonts(
+  transformedCode: string,
+  originalCode: string,
+  importerId: string,
+  pipeline: FontPipeline,
+  emitError: EmitError
+): string {
+  const localName = parseLocalFontImportName(originalCode);
+  if (!localName) return transformedCode;
+
+  const dynamicCall = detectDynamicFontCall(originalCode, [localName]);
+  if (dynamicCall) {
+    emitError(
+      `Font function calls must be statically analyzable. ` +
+        `Found dynamic call: ${dynamicCall}. ` +
+        `Pass a literal object with string/array values instead.`
+    );
+  }
+
+  const callPattern = new RegExp(
+    `(?:const|let|var)\\s+(\\w+)\\s*=\\s*${localName}\\s*\\(\\s*(\\{[\\s\\S]*?\\})\\s*\\)`,
+    'g'
+  );
+
+  let callMatch;
+  while ((callMatch = callPattern.exec(originalCode)) !== null) {
+    const varName = callMatch[1];
+    const configSource = callMatch[2];
+    const fullMatch = callMatch[0];
+
+    const config = extractLocalFontConfigAst(`(${configSource})`);
+    if (!config) {
+      emitError(
+        `Could not statically analyze local font config. ` +
+          `Ensure src is a string or array of { path, weight?, style? } objects.`
+      );
+    }
+
+    const extracted = processLocalFont(config!, importerId);
+    pipeline.pruneFor(importerId, extracted.family);
+    pipeline.register(extracted);
+
+    const replacement = `const ${varName} = ${buildFontResultLiteral(extracted)}`;
+    transformedCode = transformedCode.replace(fullMatch, replacement);
+  }
+
+  // Strip the import statement; the values it referred to are now inlined.
+  transformedCode = transformedCode.replace(
+    /import\s+\w+\s+from\s*['"](?:@timber\/fonts\/local|@timber-js\/app\/fonts\/local|next\/font\/local)['"];?\s*\n?/g,
+    ''
+  );
+
+  return transformedCode;
+}
+
+/**
+ * Run the timber-fonts transform pass on a single source file.
+ *
+ * Returns the rewritten code (with font calls inlined and the side-effect
+ * `virtual:timber-font-css-register` import prepended) or `null` if the
+ * file does not import from any timber-fonts virtual module and therefore
+ * needs no transformation.
+ */
+export function runFontsTransform(
+  code: string,
+  id: string,
+  pipeline: FontPipeline,
+  emitError: EmitError
+): { code: string; map: null } | null {
+  // Skip virtual modules and node_modules
+  if (id.startsWith('\0') || id.includes('node_modules')) return null;
+
+  const hasGoogleImport =
+    code.includes('@timber/fonts/google') ||
+    code.includes('@timber-js/app/fonts/google') ||
+    code.includes('next/font/google');
+  const hasLocalImport =
+    code.includes('@timber/fonts/local') ||
+    code.includes('@timber-js/app/fonts/local') ||
+    code.includes('next/font/local');
+  if (!hasGoogleImport && !hasLocalImport) return null;
+
+  let transformedCode = code;
+
+  if (hasGoogleImport) {
+    transformedCode = transformGoogleFonts(transformedCode, code, id, pipeline, emitError);
+  }
+
+  if (hasLocalImport) {
+    transformedCode = transformLocalFonts(transformedCode, code, id, pipeline, emitError);
+  }
+
+  if (transformedCode !== code) {
+    // Inject side-effect import that registers font CSS on globalThis.
+    // The RSC entry reads globalThis.__timber_font_css to inline a <style> tag.
+    if (pipeline.size() > 0) {
+      transformedCode = `import '${VIRTUAL_FONT_CSS_REGISTER}';\n` + transformedCode;
+    }
+    return { code: transformedCode, map: null };
+  }
+
+  return null;
+}

package/src/fonts/types.ts

@@ -7,6 +7,10 @@
  * Design doc: 24-fonts.md
  */
 
+// `CachedFont` lives in `google.ts`. Importing it here is type-only so
+// there is no runtime dependency cycle — TypeScript erases the import.
+import type { CachedFont } from './google.js';
+
 /** Configuration passed to a Google font function (e.g. `Inter({ ... })`). */
 export interface GoogleFontConfig {
   weight?: string | string[];
@@ -47,7 +51,16 @@ export interface FontResult {
   variable?: string;
 }
 
-/** Internal representation of a font extracted during static analysis. */
+/**
+ * Internal representation of a font extracted during static analysis.
+ *
+ * `ExtractedFont` is the **registration input** to `FontPipeline.register()`.
+ * Once a font has been registered the pipeline stores a `FontEntry` (which
+ * extends `ExtractedFont` with optional resolved `@font-face` descriptors
+ * and cached binary files). External code that needs to model a font that
+ * is not yet inside a pipeline (e.g. test fixtures) should use
+ * `ExtractedFont` directly.
+ */
 export interface ExtractedFont {
   /** Unique identifier for this font instance (e.g. `inter-400-normal-latin`). */
   id: string;
@@ -86,3 +99,39 @@ export interface FontFaceDescriptor {
   display?: string;
   unicodeRange?: string;
 }
+
+/**
+ * The unified per-font store entry held inside `FontPipeline`.
+ *
+ * Combines what used to live in three parallel maps:
+ *
+ * - `registry: Map<string, ExtractedFont>`            → the base extracted config
+ * - `googleFontFacesMap: Map<string, FontFaceDescriptor[]>` → `faces`
+ * - `cachedFonts: CachedFont[]` (flat, family-grouped)       → `cachedFiles`
+ *
+ * `pruneFor` drops the entry **and** all of its attached state in one
+ * operation, so future code paths cannot reintroduce a TIM-824-style
+ * desync between parallel maps.
+ *
+ * See TIM-829.
+ */
+export interface FontEntry extends ExtractedFont {
+  /**
+   * Pre-resolved `@font-face` descriptors. Populated in `buildStart`
+   * (production) or lazily in `load` (dev). For local fonts the descriptors
+   * are derived from the source list at CSS-generation time and are not
+   * stored here.
+   */
+  faces?: FontFaceDescriptor[];
+
+  /**
+   * Downloaded Google Font binaries that back this entry's `@font-face`
+   * declarations. Empty for local fonts and in dev mode (where Google fonts
+   * are served straight from the CDN).
+   *
+   * Multiple entries that share the same `family` will hold references to
+   * the same `CachedFont` objects. The bundle emitter dedupes by
+   * `hashedFilename` so each binary is written exactly once.
+   */
+  cachedFiles?: CachedFont[];
+}

package/src/fonts/virtual-modules.ts

@@ -0,0 +1,159 @@
+/**
+ * Virtual module source generators for the timber-fonts plugin.
+ *
+ * The plugin exposes three virtual modules:
+ *
+ * - `@timber/fonts/google` — exports Google font loader functions. The
+ *   transform hook replaces actual call sites with static `FontResult`
+ *   objects, so this module is only loaded as a fallback (e.g. when the
+ *   transform hook hasn't run yet, or when an unknown font is referenced
+ *   via the default export proxy).
+ * - `@timber/fonts/local` — exports `localFont()` as a fallback default.
+ * - `virtual:timber-font-css-register` — side-effect module that sets the
+ *   combined `@font-face` CSS on `globalThis.__timber_font_css`. The RSC
+ *   entry reads this at render time to inline a `<style>` tag.
+ *
+ * Design doc: 24-fonts.md
+ */
+
+import type { ExtractedFont, FontFaceDescriptor } from './types.js';
+import { generateVariableClass, generateFontFamilyClass, generateFontFaces } from './css.js';
+import { generateFallbackCss } from './fallbacks.js';
+import { generateLocalFontFaces } from './local.js';
+
+export const VIRTUAL_GOOGLE = '@timber/fonts/google';
+export const VIRTUAL_LOCAL = '@timber/fonts/local';
+export const RESOLVED_GOOGLE = '\0@timber/fonts/google';
+export const RESOLVED_LOCAL = '\0@timber/fonts/local';
+
+export const VIRTUAL_FONT_CSS_REGISTER = 'virtual:timber-font-css-register';
+export const RESOLVED_FONT_CSS_REGISTER = '\0virtual:timber-font-css-register';
+
+/**
+ * Convert a font family name to a PascalCase export name.
+ * e.g. "JetBrains Mono" → "JetBrains_Mono"
+ */
+function familyToExportName(family: string): string {
+  return family.replace(/\s+/g, '_');
+}
+
+/**
+ * Generate the virtual module source for `@timber/fonts/google`.
+ *
+ * The transform hook replaces real call sites at build time, so this
+ * module only matters as a runtime fallback. We export a Proxy default
+ * that handles any font name plus named exports for known families
+ * (for tree-shaking).
+ */
+export function generateGoogleVirtualModule(fonts: Iterable<ExtractedFont>): string {
+  const families = new Set<string>();
+  for (const font of fonts) {
+    if (font.provider === 'google') families.add(font.family);
+  }
+
+  const lines = [
+    '// Auto-generated virtual module: @timber/fonts/google',
+    '// Each export is a font loader function that returns a FontResult.',
+    '',
+    'function createFontResult(family, config) {',
+    '  return {',
+    '    className: `timber-font-${family.toLowerCase().replace(/\\s+/g, "-")}`,',
+    '    style: { fontFamily: family },',
+    '    variable: config?.variable,',
+    '  };',
+    '}',
+    '',
+    'export default new Proxy({}, {',
+    '  get(_, prop) {',
+    '    if (typeof prop === "string") {',
+    '      return (config) => createFontResult(prop.replace(/_/g, " "), config);',
+    '    }',
+    '  }',
+    '});',
+  ];
+
+  for (const family of families) {
+    const exportName = familyToExportName(family);
+    lines.push('');
+    lines.push(`export function ${exportName}(config) {`);
+    lines.push(`  return createFontResult('${family}', config);`);
+    lines.push('}');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate the virtual module source for `@timber/fonts/local`.
+ *
+ * Like the google virtual module, this is a runtime fallback. The
+ * transform hook normally replaces `localFont(...)` calls with static
+ * `FontResult` objects at build time.
+ */
+export function generateLocalVirtualModule(): string {
+  return [
+    '// Auto-generated virtual module: @timber/fonts/local',
+    '',
+    'export default function localFont(config) {',
+    '  const family = config?.family || "Local Font";',
+    '  return {',
+    '    className: `timber-font-${family.toLowerCase().replace(/\\s+/g, "-")}`,',
+    '    style: { fontFamily: family },',
+    '    variable: config?.variable,',
+    '  };',
+    '}',
+  ].join('\n');
+}
+
+/**
+ * Generate combined CSS for a single extracted font.
+ *
+ * Includes `@font-face` rules (local or Google), the size-adjusted fallback
+ * `@font-face`, and the scoped class rule. For Google fonts the resolved
+ * `FontFaceDescriptor[]` must be passed in (from `generateProductionFontFaces`
+ * in production or `resolveDevFontFaces` in dev).
+ */
+export function generateFontCss(font: ExtractedFont, googleFaces?: FontFaceDescriptor[]): string {
+  const cssParts: string[] = [];
+
+  if (font.provider === 'local' && font.localSources) {
+    const faces = generateLocalFontFaces(font.family, font.localSources, font.display);
+    const faceCss = generateFontFaces(faces);
+    if (faceCss) cssParts.push(faceCss);
+  }
+
+  if (font.provider === 'google' && googleFaces && googleFaces.length > 0) {
+    const faceCss = generateFontFaces(googleFaces);
+    if (faceCss) cssParts.push(faceCss);
+  }
+
+  const fallbackCss = generateFallbackCss(font.family);
+  if (fallbackCss) cssParts.push(fallbackCss);
+
+  if (font.variable) {
+    cssParts.push(generateVariableClass(font.className, font.variable, font.fontFamily));
+  } else {
+    cssParts.push(generateFontFamilyClass(font.className, font.fontFamily));
+  }
+
+  return cssParts.join('\n\n');
+}
+
+/**
+ * Generate the CSS output for all extracted fonts.
+ *
+ * Includes `@font-face` rules for local and Google fonts, fallback rules,
+ * and scoped classes. `googleFontFacesMap` provides pre-resolved
+ * `FontFaceDescriptor[]` for each Google font (keyed by `ExtractedFont.id`).
+ */
+export function generateAllFontCss(
+  registry: Map<string, ExtractedFont>,
+  googleFontFacesMap?: Map<string, FontFaceDescriptor[]>
+): string {
+  const cssParts: string[] = [];
+  for (const font of registry.values()) {
+    const googleFaces = googleFontFacesMap?.get(font.id);
+    cssParts.push(generateFontCss(font, googleFaces));
+  }
+  return cssParts.join('\n\n');
+}

package/src/plugins/dev-error-overlay.ts

@@ -234,6 +234,49 @@ export function formatRscDebugContext(components: RscDebugComponentInfo[]): stri
   return lines.join('\n');
 }
 
+// ─── Module Runner Offset ───────────────────────────────────────────────────
+
+/**
+ * Dynamically compute the line offset that Vite's module runner adds
+ * when wrapping modules in an async function.
+ *
+ * Vite's `calculateOffsetOnce()` uses the same technique: create a new
+ * AsyncFunction, throw from line 1, and check where the engine reports
+ * the error. The difference between the reported line and 1 is the offset.
+ *
+ * This is engine-dependent (currently 2 on Node 18-22) and could change
+ * in future Node.js or V8 versions. Computing it at runtime ensures we
+ * always match the actual behavior.
+ */
+let _cachedOffset: number | null = null;
+
+export function calculateModuleRunnerOffset(): number {
+  if (_cachedOffset !== null) return _cachedOffset;
+
+  try {
+    // Parse the AsyncFunction source to count wrapper lines before the body.
+    // AsyncFunction.toString() returns something like:
+    //   "async function anonymous(\n) {\nBODY\n}"
+    // The number of newlines before BODY is the offset Vite's module runner adds.
+    // eslint-disable-next-line no-new-func -- intentional: mirrors Vite's technique
+    const AsyncFunction = async function () {}.constructor as typeof Function;
+    const wrapper = new AsyncFunction('BODY');
+    const src = wrapper.toString();
+    const bodyIndex = src.indexOf('BODY');
+    if (bodyIndex === -1) {
+      _cachedOffset = 2; // fallback
+      return _cachedOffset;
+    }
+    const beforeBody = src.slice(0, bodyIndex);
+    const newlineCount = (beforeBody.match(/\n/g) || []).length;
+    _cachedOffset = newlineCount;
+  } catch {
+    _cachedOffset = 2; // fallback to known-good value
+  }
+
+  return _cachedOffset;
+}
+
 // ─── Stack Trace Source-Mapping ──────────────────────────────────────────────
 
 /**
@@ -310,9 +353,10 @@ function rewriteStacktrace(
           const rawSourceMap = mod?.transformResult?.map;
           if (!rawSourceMap) return input;
 
-          // Vite's module runner adds a 2-line offset for the async wrapper.
-          // This matches Vite's internal `calculateOffsetOnce()` behavior.
-          const OFFSET = 2;
+          // Vite's module runner wraps each module in an async function,
+          // adding N lines before the module body. The offset is computed
+          // dynamically to match the actual engine behavior (see TIM-783).
+          const OFFSET = calculateModuleRunnerOffset();
           const origLine = Number(lineStr) - OFFSET;
           const origCol = Number(colStr) - 1;
           if (origLine <= 0 || origCol < 0) return input;

package/src/plugins/entries.ts

@@ -98,6 +98,38 @@ function stripRootPrefix(id: string, root: string): string {
  *
  * Serializes output mode and feature flags for runtime consumption.
  */
+/**
+ * Extract the JSON-serializable subset of `forms` config.
+ *
+ * Drops function-valued `stripSensitiveFields` with a build-time warning —
+ * functions cannot cross the JSON boundary to the runtime, so users must
+ * configure function predicates per-action via `createActionClient` instead.
+ */
+function serializeFormsConfig(
+  forms: { stripSensitiveFields?: unknown } | undefined
+): { stripSensitiveFields?: boolean | readonly string[] } | undefined {
+  if (!forms) return undefined;
+  const opt = forms.stripSensitiveFields;
+  if (opt === undefined) return {};
+  if (typeof opt === 'boolean') return { stripSensitiveFields: opt };
+  if (Array.isArray(opt)) {
+    // Coerce to a string array and drop any non-string entries.
+    const names = opt.filter((v): v is string => typeof v === 'string');
+    return { stripSensitiveFields: names };
+  }
+  if (typeof opt === 'function') {
+    console.warn(
+      '[timber] forms.stripSensitiveFields was set to a function in timber.config.ts — ' +
+        'this is not supported at the global level (functions cannot be serialized ' +
+        'into the runtime config). Use a per-action override via ' +
+        '`createActionClient({ stripSensitiveFields: (name) => ... })` instead. ' +
+        'The built-in deny-list will be used globally.'
+    );
+    return {};
+  }
+  return {};
+}
+
 function generateConfigModule(ctx: PluginContext): string {
   const runtimeConfig = {
     output: ctx.config.output ?? 'server',
@@ -114,6 +146,11 @@ function generateConfigModule(ctx: PluginContext): string {
     // Auto-generated sitemap config — opt-in via timber.config.ts.
     // See design/16-metadata.md §"Auto-generated Sitemap"
     sitemap: ctx.config.sitemap,
+    // Forms config — only the serializable subset. `stripSensitiveFields`
+    // accepts boolean | string[] at the global level. Functions must be
+    // configured per-action via `createActionClient({ stripSensitiveFields })`
+    // because JSON.stringify would silently drop them here. See TIM-816.
+    forms: serializeFormsConfig(ctx.config.forms),
     // Per-build deployment ID for version skew detection (TIM-446).
     // Null in dev mode — HMR handles code updates without full reloads.
     deploymentId: ctx.deploymentId ?? null,