@timber-js/app 0.2.0-alpha.12 → 0.2.0-alpha.121

package/src/plugins/fonts.ts

@@ -1,411 +1,104 @@
 /**
- * timber-fonts — Vite sub-plugin for build-time font processing.
+ * timber-fonts — Vite sub-plugin shell for build-time font processing.
  *
- * Handles:
- * - Virtual module resolution for `@timber/fonts/google` and `@timber/fonts/local`
- * - Static analysis of font function calls during `transform`
- * - @font-face CSS generation and scoped class output
- * - Size-adjusted fallback font generation
+ * This file is intentionally thin: it wires the Vite plugin hooks to the
+ * pipeline + per-concern modules under `../fonts/`. All real logic lives
+ * in:
  *
- * Does NOT handle (separate tasks):
- * - Google Fonts downloading/caching (timber-nk5)
- * - Build manifest / Early Hints integration (timber-qnx)
+ * - `../fonts/pipeline.ts`        — `FontPipeline` (state, mutators)
+ * - `../fonts/transform.ts`       — transform-hook logic, parsing helpers
+ * - `../fonts/dev-middleware.ts`  — dev font binary server
+ * - `../fonts/virtual-modules.ts` — virtual module ID constants + source
+ *
+ * The public exports below are the stable API that the test suite and
+ * other parts of the framework import. Anything new should be added to
+ * one of the per-concern modules and re-exported here only if external
+ * consumers need it.
  *
  * Design doc: 24-fonts.md
  */
 
 import type { Plugin, ViteDevServer } from 'vite';
-import { readFileSync, existsSync } from 'node:fs';
-import { resolve, normalize } from 'node:path';
-import type { PluginContext } from '#/index.js';
-import type { ExtractedFont, GoogleFontConfig } from '#/fonts/types.js';
-import type { ManifestFontEntry } from '#/server/build-manifest.js';
-import { generateVariableClass, generateFontFamilyClass, generateFontFaces } from '#/fonts/css.js';
-import { generateFallbackCss, buildFontStack } from '#/fonts/fallbacks.js';
-import { processLocalFont, generateLocalFontFaces } from '#/fonts/local.js';
-import { inferFontFormat } from '#/fonts/local.js';
-import { downloadAndCacheFonts, type CachedFont } from '#/fonts/google.js';
+import type { PluginContext } from '../plugin-context.js';
 import {
-  extractFontConfigAst,
-  extractLocalFontConfigAst,
-  detectDynamicFontCallAst,
-} from '#/fonts/ast.js';
-
-const VIRTUAL_GOOGLE = '@timber/fonts/google';
-const VIRTUAL_LOCAL = '@timber/fonts/local';
-const RESOLVED_GOOGLE = '\0@timber/fonts/google';
-const RESOLVED_LOCAL = '\0@timber/fonts/local';
-
-/**
- * Virtual side-effect module that registers font CSS on globalThis.
- *
- * When a file calls localFont() or a Google font function, the transform
- * hook injects `import 'virtual:timber-font-css-register'` into that file.
- * This virtual module sets `globalThis.__timber_font_css` with the combined
- * @font-face CSS. The RSC entry reads it at render time to inline a <style> tag.
- *
- * This approach avoids timing issues because:
- * 1. The font file is in the RSC module graph (imported by layout.tsx)
- * 2. The side-effect import is added to the font file during transform
- * 3. When layout.tsx is loaded, fonts.ts runs → side-effect module runs → globalThis is set
- * 4. RSC entry renders → reads globalThis → inlines <style>
- */
-const VIRTUAL_FONT_CSS_REGISTER = 'virtual:timber-font-css-register';
-const RESOLVED_FONT_CSS_REGISTER = '\0virtual:timber-font-css-register';
-
-/**
- * Registry of fonts extracted during transform.
- * Keyed by a unique font ID derived from family + config.
- */
-export type FontRegistry = Map<string, ExtractedFont>;
-
-/**
- * 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, '_');
-}
-
-/**
- * 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, '-')}`;
-}
-
-/**
- * Generate a unique font ID from family + config hash.
- */
-function generateFontId(family: string, config: GoogleFontConfig): string {
-  const weights = normalizeToArray(config.weight);
-  const styles = normalizeToArray(config.style);
-  const subsets = config.subsets ?? ['latin'];
-  return `${family.toLowerCase()}-${weights.join(',')}-${styles.join(',')}-${subsets.join(',')}`;
-}
-
-/**
- * Normalize a string or string array to an array.
- */
-function normalizeToArray(value: string | string[] | undefined): string[] {
-  if (!value) return ['400'];
-  return Array.isArray(value) ? value : [value];
-}
-
-/**
- * Normalize style to an array.
- */
-function normalizeStyleArray(value: string | string[] | undefined): string[] {
-  if (!value) return ['normal'];
-  return Array.isArray(value) ? value : [value];
-}
-
-/**
- * Extract static font config from a font function call in source code.
- *
- * Parses patterns like:
- *   const inter = Inter({ subsets: ['latin'], weight: '400', display: 'swap', variable: '--font-sans' })
- *
- * Returns null if the call cannot be statically analyzed.
- *
- * Uses acorn AST parsing for robust handling of comments, trailing commas,
- * and multi-line configs.
- */
-export function extractFontConfig(callSource: string): GoogleFontConfig | null {
-  return extractFontConfigAst(callSource);
-}
-
-/**
- * Detect if a source file contains dynamic/computed font function calls
- * that cannot be statically analyzed.
- *
- * Returns the offending expression if found, null if all calls are static.
- *
- * Uses acorn AST parsing for accurate detection.
- */
-export function detectDynamicFontCall(source: string, importedNames: string[]): string | null {
-  return detectDynamicFontCallAst(source, importedNames);
-}
-
-/**
- * Regex that matches imports from either `@timber/fonts/google` or `next/font/google`.
- * The shims plugin resolves `next/font/google` to the same virtual module,
- * but the source code still contains the original import specifier.
- */
-const GOOGLE_FONT_IMPORT_RE =
-  /import\s*\{([^}]+)\}\s*from\s*['"](?:@timber\/fonts\/google|next\/font\/google)['"]/g;
-
-/**
- * Parse import specifiers from a source file that imports from
- * `@timber/fonts/google` or `next/font/google`.
- *
- * Returns the list of imported font names (e.g. ['Inter', 'JetBrains_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 the original (remote) font family names from imports.
- *
- * Returns a map of local name → family name.
- * e.g. { Inter: 'Inter', JetBrains_Mono: 'JetBrains Mono' }
- */
-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;
-}
-
-/**
- * Generate the virtual module source for `@timber/fonts/google`.
- *
- * Each Google Font family gets a named export that returns a FontResult.
- * In this base implementation, the functions return static data.
- * The Google Fonts download task (timber-nk5) will add real font file URLs.
- */
-function generateGoogleVirtualModule(registry: FontRegistry): string {
-  // Collect unique families from the registry
-  const families = new Set<string>();
-  for (const font of registry.values()) {
-    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.',
-    '',
-  ];
-
-  // If no fonts registered yet, export a generic loader for any font
-  // This is the initial load — the transform hook will process actual calls
-  lines.push('function createFontResult(family, config) {');
-  lines.push('  return {');
-  lines.push('    className: `timber-font-${family.toLowerCase().replace(/\\s+/g, "-")}`,');
-  lines.push('    style: { fontFamily: family },');
-  lines.push('    variable: config?.variable,');
-  lines.push('  };');
-  lines.push('}');
-  lines.push('');
-
-  // Export a Proxy-based default that handles any font name import
-  lines.push('export default new Proxy({}, {');
-  lines.push('  get(_, prop) {');
-  lines.push('    if (typeof prop === "string") {');
-  lines.push('      return (config) => createFontResult(prop.replace(/_/g, " "), config);');
-  lines.push('    }');
-  lines.push('  }');
-  lines.push('});');
-
-  // Also export known families as named exports for tree-shaking
-  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`.
- */
-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 CSS for a single extracted font.
- *
- * Includes @font-face rules (for local fonts), fallback @font-face,
- * and the scoped class rule.
- */
-export function generateFontCss(font: ExtractedFont): 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);
-  }
-
-  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 fonts, fallback @font-face rules,
- * and scoped classes.
- */
-export function generateAllFontCss(registry: FontRegistry): string {
-  const cssParts: string[] = [];
-  for (const font of registry.values()) {
-    cssParts.push(generateFontCss(font));
-  }
-  return cssParts.join('\n\n');
-}
-
-/**
- * Parse the local name used for the default import of `@timber/fonts/local`.
- *
- * Handles:
- *   import localFont from '@timber/fonts/local'
- *   import myLoader from '@timber/fonts/local'
- */
-export function parseLocalFontImportName(source: string): string | null {
-  const match = source.match(
-    /import\s+(\w+)\s+from\s*['"](?:@timber\/fonts\/local|next\/font\/local)['"]/
-  );
-  return match ? match[1] : null;
-}
-
-/**
- * Transform local font calls in source code.
- *
- * Finds `localFont({ ... })` calls, extracts the config,
- * registers the font, and replaces the call with a static FontResult.
- */
-function transformLocalFonts(
-  transformedCode: string,
-  originalCode: string,
-  importerId: string,
-  registry: FontRegistry,
-  emitError: (msg: string) => void
-): string {
-  const localName = parseLocalFontImportName(originalCode);
-  if (!localName) return transformedCode;
-
-  // Check for dynamic calls
-  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.`
-    );
-  }
-
-  // Find all calls: const varName = localFont({ ... })
-  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.`
-      );
-      return transformedCode;
-    }
-
-    const extracted = processLocalFont(config, importerId);
-    registry.set(extracted.id, extracted);
-
-    const resultObj = extracted.variable
-      ? `{ className: "${extracted.className}", style: { fontFamily: "${extracted.fontFamily}" }, variable: "${extracted.variable}" }`
-      : `{ className: "${extracted.className}", style: { fontFamily: "${extracted.fontFamily}" } }`;
-
-    const replacement = `const ${varName} = ${resultObj}`;
-    transformedCode = transformedCode.replace(fullMatch, replacement);
-  }
-
-  // Remove the import statement
-  transformedCode = transformedCode.replace(
-    /import\s+\w+\s+from\s*['"](?:@timber\/fonts\/local|next\/font\/local)['"];?\s*\n?/g,
-    ''
-  );
-
-  return transformedCode;
-}
+  downloadAndCacheFonts,
+  generateProductionFontFaces,
+  resolveDevFontFaces,
+} from '../fonts/google.js';
+import { FontPipeline } from '../fonts/pipeline.js';
+import { runFontsTransform } from '../fonts/transform.js';
+import { installFontDevMiddleware } from '../fonts/dev-middleware.js';
+import { emitFontAssets, writeFontManifest, groupCachedFontsByFamily } from '../fonts/bundle.js';
+import {
+  RESOLVED_GOOGLE,
+  RESOLVED_LOCAL,
+  VIRTUAL_GOOGLE,
+  VIRTUAL_LOCAL,
+  generateGoogleVirtualModule,
+  generateLocalVirtualModule,
+} from '../fonts/virtual-modules.js';
+
+// ── Public re-exports ────────────────────────────────────────────────────
+//
+// These exports are part of the stable surface area imported by tests and
+// downstream consumers. Do NOT change their names or signatures without
+// updating every caller. New helpers should be added to the per-concern
+// module first and re-exported here only if external code needs them.
+
+export { FontPipeline, pruneRegistryEntries, type FontRegistry } from '../fonts/pipeline.js';
+export {
+  generateFontId,
+  extractFontConfig,
+  detectDynamicFontCall,
+  parseGoogleFontImports,
+  parseGoogleFontFamilies,
+  parseLocalFontImportName,
+} from '../fonts/transform.js';
+export { generateFontCss, generateAllFontCss } from '../fonts/virtual-modules.js';
 
 /**
  * Create the timber-fonts Vite plugin.
  */
 export function timberFonts(ctx: PluginContext): Plugin {
-  const registry: FontRegistry = new Map();
-  /** Fonts downloaded during buildStart (production only). */
-  let cachedFonts: CachedFont[] = [];
+  const pipeline = new FontPipeline();
 
   return {
     name: 'timber-fonts',
 
     /**
-     * Resolve `@timber/fonts/google`, `@timber/fonts/local`,
-     * and `virtual:timber-font-css` virtual modules.
+     * `enforce: 'pre'` is load-bearing for the font CSS pipeline (TIM-828).
+     *
+     * The transform hook injects a side-effect
+     * `import 'virtual:timber-font-css/<hash>.css'` into every file that
+     * registers a font. @vitejs/plugin-rsc's `rsc:rsc-css-export-transform`
+     * later inspects each server component's source for CSS imports and
+     * wraps the default export in `import.meta.viteRsc.loadCss(...)` so
+     * the matched virtual CSS module ends up `preinit`'d as
+     * `<link rel="stylesheet" data-rsc-css-href=...>`.
      *
-     * Handles \0 prefix and root prefix stripping for RSC/SSR
-     * environments where the RSC plugin re-imports virtual modules
-     * with additional prefixes.
+     * If timber-fonts ran in normal order it would inject the CSS import
+     * *after* plugin-rsc had already scanned the source, and the font CSS
+     * would be silently dropped from the rendered HTML. Running in the
+     * `pre` slot guarantees our injected import is visible to plugin-rsc's
+     * later CSS-export scan.
+     */
+    enforce: 'pre',
+
+    /**
+     * Resolve `@timber/fonts/google`, `@timber/fonts/local`, and the
+     * per-importer `virtual:timber-font-css/<hash>.css` modules injected
+     * by the transform hook.
+     *
+     * Strips the `\0` prefix added by the RSC plugin's re-imports and the
+     * absolute root prefix added by SSR build entries before comparing
+     * against the public IDs. The `.css` suffix on font-css ids is
+     * preserved so Vite's CSS pipeline (`isCSSRequest`) recognises the
+     * resolved id as CSS.
      */
     resolveId(id: string) {
-      // Strip \0 prefix (RSC plugin re-imports)
       let cleanId = id.startsWith('\0') ? id.slice(1) : id;
-      // Strip root prefix (SSR build entries)
+      const qIdx = cleanId.indexOf('?');
+      if (qIdx !== -1) cleanId = cleanId.slice(0, qIdx);
       if (cleanId.startsWith(ctx.root)) {
         const stripped = cleanId.slice(ctx.root.length);
         if (stripped.startsWith('/') || stripped.startsWith('\\')) {
@@ -417,317 +110,127 @@ export function timberFonts(ctx: PluginContext): Plugin {
 
       if (cleanId === VIRTUAL_GOOGLE) return RESOLVED_GOOGLE;
       if (cleanId === VIRTUAL_LOCAL) return RESOLVED_LOCAL;
-      if (cleanId === VIRTUAL_FONT_CSS_REGISTER) return RESOLVED_FONT_CSS_REGISTER;
+      if (pipeline.cssIdMap.matches(cleanId)) return '\0' + cleanId;
       return null;
     },
 
     /**
      * Return generated source for font virtual modules.
      *
-     * `virtual:timber-font-css` exports the combined @font-face CSS
-     * as a string. The RSC entry imports it and inlines a <style> tag.
-     * Because this is loaded lazily (on first request), the font
-     * registry is always populated by the time it's needed.
+     * The per-importer `virtual:timber-font-css/<hash>.css` modules
+     * return the combined font CSS for the specific importer that
+     * registered them. Vite's CSS pipeline handles injection from here:
+     * in dev the module rides the CSS HMR channel; in production it is
+     * emitted as a real CSS asset and @vitejs/plugin-rsc's `collectCss`
+     * walks the RSC module graph to find it.
+     *
+     * In dev mode we also lazily resolve Google `@font-face` descriptors
+     * from the CDN here, since `buildStart` is a no-op in dev.
      */
-    load(id: string) {
-      if (id === RESOLVED_GOOGLE) return generateGoogleVirtualModule(registry);
+    async load(id: string) {
+      if (id === RESOLVED_GOOGLE) return generateGoogleVirtualModule(pipeline.fonts());
       if (id === RESOLVED_LOCAL) return generateLocalVirtualModule();
 
-      if (id === RESOLVED_FONT_CSS_REGISTER) {
-        const css = generateAllFontCss(registry);
-        // Side-effect module: sets font CSS on globalThis for the RSC entry to read.
-        return `globalThis.__timber_font_css = ${JSON.stringify(css)};`;
+      if (pipeline.cssIdMap.matches(id)) {
+        const importer = pipeline.cssIdMap.importerFor(id);
+        if (!importer) {
+          // Hash is valid but no importer is registered — return an empty
+          // CSS module rather than `null`. This can happen if Vite's
+          // module graph invalidates the virtual module between the
+          // transform that registered the hash and the load that asks
+          // for it (e.g. after an HMR edit that removes every font from
+          // the file). An empty stylesheet is a valid, safe no-op.
+          return '';
+        }
+
+        if (ctx.dev) {
+          for (const font of pipeline.googleFonts()) {
+            if (font.importer !== importer) continue;
+            if (pipeline.hasFaces(font.id)) continue;
+            try {
+              const faces = await resolveDevFontFaces(font);
+              pipeline.attachFaces(font.id, faces);
+            } catch (e) {
+              // Fail gracefully — fonts fall back to system fonts. Don't
+              // cache the failure so transient errors (network blips, rate
+              // limits) are retried on the next request. See TIM-636.
+              const msg = e instanceof Error ? e.message : String(e);
+              console.warn(
+                `[timber-fonts] Failed to resolve Google font "${font.family}": ${msg}. Will retry on next request.`
+              );
+            }
+          }
+        }
+
+        return pipeline.getCssForSegment(importer);
       }
       return null;
     },
 
     /**
-     * Serve local font files and font CSS in dev mode under `/_timber/fonts/`.
-     *
-     * Serves:
-     * - `/_timber/fonts/fonts.css` — combined @font-face + scoped class CSS
-     * - `/_timber/fonts/<filename>` — individual font files from the registry
-     *
-     * Only files registered in the font registry are served.
-     * Paths are validated to prevent directory traversal.
+     * Serve local font files in dev mode under `/_timber/fonts/<basename>`.
+     * Font CSS goes through Vite's CSS pipeline (virtual modules), not
+     * this middleware.
      */
     configureServer(server: ViteDevServer) {
-      server.middlewares.use((req, res, next) => {
-        const url = req.url;
-        if (!url || !url.startsWith('/_timber/fonts/')) return next();
-
-        const requestedFilename = url.slice('/_timber/fonts/'.length);
-        // Reject path traversal attempts
-        if (requestedFilename.includes('..') || requestedFilename.includes('/')) {
-          res.statusCode = 400;
-          res.end('Bad request');
-          return;
-        }
-
-        // Font CSS is now injected via Vite's CSS pipeline (virtual:timber-font-css modules).
-        // This middleware only serves font binary files (woff2, etc.).
-
-        // Find the matching font file in the registry
-        for (const font of registry.values()) {
-          if (font.provider !== 'local' || !font.localSources) continue;
-          for (const src of font.localSources) {
-            const basename = src.path.split('/').pop() ?? '';
-            if (basename === requestedFilename) {
-              const absolutePath = normalize(resolve(src.path));
-              if (!existsSync(absolutePath)) {
-                res.statusCode = 404;
-                res.end('Not found');
-                return;
-              }
-              const data = readFileSync(absolutePath);
-              const ext = absolutePath.split('.').pop()?.toLowerCase();
-              const mimeMap: Record<string, string> = {
-                woff2: 'font/woff2',
-                woff: 'font/woff',
-                ttf: 'font/ttf',
-                otf: 'font/otf',
-                eot: 'application/vnd.ms-fontopen',
-              };
-              res.setHeader('Content-Type', mimeMap[ext ?? ''] ?? 'application/octet-stream');
-              res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
-              res.setHeader('Access-Control-Allow-Origin', '*');
-              res.end(data);
-              return;
-            }
-          }
-        }
-
-        next();
-      });
+      installFontDevMiddleware(server, pipeline);
     },
 
     /**
      * Download and cache Google Fonts during production builds.
      *
-     * In dev mode this is a no-op — fonts point to the Google CDN.
+     * In dev mode this is a no-op — fonts point to the Google CDN and are
+     * resolved lazily inside `load()` when the side-effect module runs.
      * The registry is populated by the transform hook which runs before
-     * buildStart in the build pipeline, so all fonts are known here.
+     * `buildStart` in the build pipeline, so all fonts are known here.
      */
     async buildStart() {
       if (ctx.dev) return;
 
-      const googleFonts = [...registry.values()].filter((f) => f.provider === 'google');
+      const googleFonts = [...pipeline.googleFonts()];
       if (googleFonts.length === 0) return;
 
-      cachedFonts = await downloadAndCacheFonts(googleFonts, ctx.root);
+      const cachedFonts = await downloadAndCacheFonts(googleFonts, ctx.root);
+
+      // Build a family→CachedFont[] lookup, then attach the cached files
+      // and resolved @font-face descriptors to each registered Google
+      // font. Multiple fonts that share a family hold references to the
+      // same `CachedFont` objects; the bundle emitter dedupes by
+      // `hashedFilename` so each binary is written to disk exactly once.
+      const cachedByFamily = groupCachedFontsByFamily(cachedFonts);
+      for (const font of googleFonts) {
+        const familyCached = cachedByFamily.get(font.family.toLowerCase()) ?? [];
+        pipeline.attachCachedFiles(font.id, familyCached);
+        pipeline.attachFaces(font.id, generateProductionFontFaces(familyCached, font.display));
+      }
     },
 
     /**
      * Scan source files for font function calls and extract static config.
      *
-     * When a file imports from `@timber/fonts/google`, we:
-     * 1. Parse the import specifiers to get font family names
-     * 2. Find each font function call and extract its config
-     * 3. Validate that all calls are statically analyzable
-     * 4. Register extracted fonts in the registry
-     * 5. Replace the function call with a static FontResult object
+     * Delegates to `runFontsTransform`. Errors raised through the
+     * `this.error` callback are surfaced as Vite plugin errors.
      */
     transform(code: string, id: string) {
-      // 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('next/font/google');
-      const hasLocalImport =
-        code.includes('@timber/fonts/local') || code.includes('next/font/local');
-      if (!hasGoogleImport && !hasLocalImport) return null;
-
-      let transformedCode = code;
-
-      // ── Google font transform ──────────────────────────────────────────
-      if (hasGoogleImport) {
-        const families = parseGoogleFontFamilies(code);
-        if (families.size > 0) {
-          const importedNames = [...families.keys()];
-
-          const dynamicCall = detectDynamicFontCall(code, importedNames);
-          if (dynamicCall) {
-            this.error(
-              `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(code)) !== null) {
-              const varName = callMatch[1];
-              const configSource = callMatch[2];
-              const fullMatch = callMatch[0];
-
-              const config = extractFontConfig(`(${configSource})`);
-              if (!config) {
-                this.error(
-                  `Could not statically analyze font config for ${family}. ` +
-                    `Ensure all config values are string literals or arrays of string literals.`
-                );
-                return null;
-              }
-
-              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: normalizeToArray(config.weight),
-                styles: normalizeStyleArray(config.style),
-                subsets: config.subsets ?? ['latin'],
-                display,
-                variable: config.variable,
-                className,
-                fontFamily: fontStack,
-                importer: id,
-              };
-
-              registry.set(fontId, extracted);
-
-              const resultObj = config.variable
-                ? `{ className: "${className}", style: { fontFamily: "${fontStack}" }, variable: "${config.variable}" }`
-                : `{ className: "${className}", style: { fontFamily: "${fontStack}" } }`;
-
-              const replacement = `const ${varName} = ${resultObj}`;
-              transformedCode = transformedCode.replace(fullMatch, replacement);
-            }
-          }
-
-          transformedCode = transformedCode.replace(
-            /import\s*\{[^}]+\}\s*from\s*['"](?:@timber\/fonts\/google|next\/font\/google)['"];?\s*\n?/g,
-            ''
-          );
-        }
-      }
-
-      // ── Local font transform ───────────────────────────────────────────
-      if (hasLocalImport) {
-        transformedCode = transformLocalFonts(
-          transformedCode,
-          code,
-          id,
-          registry,
-          this.error.bind(this)
-        );
-      }
-
-      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 (registry.size > 0) {
-          transformedCode = `import '${VIRTUAL_FONT_CSS_REGISTER}';\n` + transformedCode;
-        }
-        return { code: transformedCode, map: null };
-      }
-
-      return null;
+      return runFontsTransform(code, id, pipeline, (msg) => this.error(msg));
     },
 
     /**
-     * Emit font files and metadata into the build output.
-     *
-     * For Google fonts: emits the downloaded, content-hashed woff2 files
-     * and writes ManifestFontEntry arrays using real hashed URLs.
+     * Emit font binaries and build-manifest entries.
      *
-     * For local fonts: emits entries using the source file paths.
-     *
-     * In dev mode the build manifest is null, so this is a no-op.
+     * Google fonts use the content-hashed filenames produced during
+     * `buildStart`. Local fonts are emitted by basename. Font CSS is
+     * handled by Vite's CSS pipeline via virtual modules — we only emit
+     * binaries here.
      */
     generateBundle() {
-      // Emit cached Google Font files into the build output
-      for (const cf of cachedFonts) {
-        this.emitFile({
-          type: 'asset',
-          fileName: `_timber/fonts/${cf.hashedFilename}`,
-          source: cf.data,
-        });
-      }
-
-      // Emit local font files as assets
-      for (const font of registry.values()) {
-        if (font.provider !== 'local' || !font.localSources) continue;
-        for (const src of font.localSources) {
-          const absolutePath = normalize(resolve(src.path));
-          if (!existsSync(absolutePath)) {
-            this.warn(`Local font file not found: ${absolutePath}`);
-            continue;
-          }
-          const basename = src.path.split('/').pop() ?? src.path;
-          const data = readFileSync(absolutePath);
-          this.emitFile({
-            type: 'asset',
-            fileName: `_timber/fonts/${basename}`,
-            source: data,
-          });
-        }
-      }
-
-      // Font CSS is emitted by Vite's CSS pipeline via virtual:timber-font-css modules.
-      // We only need to emit font binary files and update the build manifest here.
-
+      emitFontAssets(
+        pipeline,
+        (asset) => this.emitFile(asset),
+        (msg) => this.warn(msg)
+      );
       if (!ctx.buildManifest) return;
-
-      // Build a lookup from font family → cached files for manifest entries
-      const cachedByFamily = new Map<string, CachedFont[]>();
-      for (const cf of cachedFonts) {
-        const key = cf.face.family.toLowerCase();
-        const arr = cachedByFamily.get(key) ?? [];
-        arr.push(cf);
-        cachedByFamily.set(key, arr);
-      }
-
-      const fontsByImporter = new Map<string, ManifestFontEntry[]>();
-
-      for (const font of registry.values()) {
-        const entries = fontsByImporter.get(font.importer) ?? [];
-
-        if (font.provider === 'local' && font.localSources) {
-          // Local fonts: one entry per source file
-          for (const src of font.localSources) {
-            const filename = src.path.split('/').pop() ?? src.path;
-            const format = inferFontFormat(src.path);
-            entries.push({
-              href: `/_timber/fonts/${filename}`,
-              format,
-              crossOrigin: 'anonymous',
-            });
-          }
-        } else {
-          // Google fonts: use real content-hashed URLs from cached downloads
-          const familyKey = font.family.toLowerCase();
-          const familyCached = cachedByFamily.get(familyKey) ?? [];
-          for (const cf of familyCached) {
-            entries.push({
-              href: `/_timber/fonts/${cf.hashedFilename}`,
-              format: 'woff2',
-              crossOrigin: 'anonymous',
-            });
-          }
-        }
-
-        fontsByImporter.set(font.importer, entries);
-      }
-
-      // Normalize importer paths to be relative to project root (matching
-      // how Vite's manifest.json keys work for css/js).
-      for (const [importer, entries] of fontsByImporter) {
-        const relativePath = importer.startsWith(ctx.root)
-          ? importer.slice(ctx.root.length + 1)
-          : importer;
-        ctx.buildManifest.fonts[relativePath] = entries;
-      }
+      writeFontManifest(pipeline, ctx.buildManifest, ctx.root);
     },
   };
 }