@timber-js/app 0.2.0-alpha.1 → 0.2.0-alpha.100

package/src/fonts/transform.ts

@@ -0,0 +1,406 @@
+/**
+ * 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';
+
+/**
+ * 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 a side-effect
+ * `import 'virtual:timber-font-css/<hash>.css'` prepended so Vite's CSS
+ * pipeline owns the font CSS) or `null` if the file does not import from
+ * any timber-fonts virtual module and therefore needs no transformation.
+ */
+/**
+ * File extensions that may contain real font imports. Only JS/TS module
+ * variants are scanned. Excluding non-JS extensions (.mdx, .md, .css,
+ * .json, etc.) prevents false-positive matches on text that mentions a
+ * font specifier inside documentation, code fences, or asset metadata.
+ *
+ * Why this matters: the heuristic below is a substring check (`code.includes`),
+ * not an AST parse. An MDX file documenting Next.js font compatibility
+ * (e.g. a code fence containing `import { Inter } from 'next/font/google'`)
+ * would trigger the same match as a real import. The transform then prepends
+ * `import 'virtual:timber-font-css/<hash>.css';` to the file, which breaks
+ * downstream parsers that require the file to start with their own delimiter
+ * — most notably MDX frontmatter, which must start at line 1 col 1 for
+ * `remark-frontmatter` to recognise it. See TIM-840.
+ */
+const FONT_IMPORT_SCANNABLE_EXTENSIONS = new Set([
+  '.js',
+  '.jsx',
+  '.ts',
+  '.tsx',
+  '.mjs',
+  '.cjs',
+  '.mts',
+  '.cts',
+]);
+
+function hasScannableExtension(id: string): boolean {
+  // Strip Vite query suffixes (?v=..., ?import, ?worker, etc.) before
+  // matching so files imported with a query string are still scanned.
+  const path = id.split('?', 1)[0];
+  const dot = path.lastIndexOf('.');
+  if (dot === -1) return false;
+  return FONT_IMPORT_SCANNABLE_EXTENSIONS.has(path.slice(dot).toLowerCase());
+}
+
+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;
+
+  // Only scan JS/TS module variants. .mdx, .md, .css, .json, etc. may
+  // mention font specifiers in documentation or asset metadata without
+  // ever importing them — a substring match would be a false positive
+  // and the prepended virtual CSS import would corrupt downstream
+  // parsers (e.g. MDX frontmatter, which must start at line 1).
+  // See TIM-840.
+  if (!hasScannableExtension(id)) 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 a side-effect import for this file's per-importer virtual
+    // CSS module. The `.css` suffix is what makes Vite's CSS pipeline
+    // own the module — in dev that gives us HMR + source maps, and in
+    // production @vitejs/plugin-rsc walks the RSC module graph via
+    // `collectCss`, finds this virtual CSS import, and injects a
+    // `<link rel="stylesheet" data-rsc-css-href=...>` through React
+    // Float's preinit mechanism (the same path component CSS rides on).
+    //
+    // The per-importer id guarantees two concurrent requests rendering
+    // different routes never see each other's font CSS: each importer's
+    // virtual module only resolves to the fonts that importer registered
+    // via `FontPipeline.getCssForSegment(importer)`. See TIM-828.
+    if (pipeline.size() > 0) {
+      const virtualCssId = pipeline.cssIdMap.idFor(id);
+      transformedCode = `import '${virtualCssId}';\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,227 @@
+/**
+ * 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/<hash>.css` — per-importer CSS module that
+ *   holds the combined `@font-face` + fallback + class CSS for every
+ *   font registered under that importer. The transform hook injects a
+ *   side-effect `import 'virtual:timber-font-css/<hash>.css'` into each
+ *   file that calls a font function, so Vite's CSS pipeline picks it up
+ *   like any other CSS asset. @vitejs/plugin-rsc's `collectCss` walks
+ *   the RSC module graph, finds the virtual module, and injects a
+ *   `<link rel="stylesheet" data-rsc-css-href=...>` via React Float —
+ *   the same machinery component CSS rides on (TIM-828).
+ *
+ *   The `.css` suffix is load-bearing: Vite's `isCSSRequest` regex matches
+ *   on file extension, so keeping it in the virtual id is how we tell
+ *   Vite's CSS pipeline (dev HMR + build asset emission) that this
+ *   module is CSS. The old `virtual:timber-font-css-register` side-effect
+ *   module, `globalThis.__timber_font_css` channel, and inline `<style>`
+ *   tag in the RSC entry were all removed in TIM-828.
+ *
+ * Design doc: 24-fonts.md
+ */
+
+import { createHash } from 'node:crypto';
+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';
+
+/**
+ * Prefix used for the per-importer virtual CSS modules. The full id is
+ * `virtual:timber-font-css/<hash>.css` where `<hash>` is a short SHA-256
+ * digest of the importer path. We encode the hash (not the path itself)
+ * so the id stays filesystem-safe and opaque to downstream consumers.
+ */
+export const VIRTUAL_FONT_CSS_PREFIX = 'virtual:timber-font-css/';
+export const VIRTUAL_FONT_CSS_SUFFIX = '.css';
+export const RESOLVED_FONT_CSS_PREFIX = '\0' + VIRTUAL_FONT_CSS_PREFIX;
+
+/**
+ * In-memory map from the short hash used in virtual module ids back to
+ * the absolute importer path. Populated by `virtualFontCssIdFor()` when
+ * the transform hook registers an importer and read by the plugin's
+ * `load` hook when Vite asks for the CSS content.
+ *
+ * Scoped to a single `FontPipeline` instance to avoid cross-plugin-
+ * instance collisions during multi-build pipelines.
+ */
+export class VirtualFontCssIdMap {
+  private readonly map = new Map<string, string>();
+
+  /**
+   * Return a stable virtual module id for `importer`. Calling this twice
+   * with the same importer returns the same id. Registering under an
+   * existing hash is idempotent.
+   */
+  idFor(importer: string): string {
+    const hash = createHash('sha256').update(importer).digest('hex').slice(0, 16);
+    this.map.set(hash, importer);
+    return `${VIRTUAL_FONT_CSS_PREFIX}${hash}${VIRTUAL_FONT_CSS_SUFFIX}`;
+  }
+
+  /** Decode the importer from a resolved (or unresolved) virtual css id. */
+  importerFor(id: string): string | undefined {
+    const body = id.startsWith('\0') ? id.slice(1) : id;
+    if (!body.startsWith(VIRTUAL_FONT_CSS_PREFIX)) return undefined;
+    if (!body.endsWith(VIRTUAL_FONT_CSS_SUFFIX)) return undefined;
+    const hash = body.slice(
+      VIRTUAL_FONT_CSS_PREFIX.length,
+      body.length - VIRTUAL_FONT_CSS_SUFFIX.length
+    );
+    return this.map.get(hash);
+  }
+
+  /** True if `id` is any form of the virtual font css module. */
+  matches(id: string): boolean {
+    const body = id.startsWith('\0') ? id.slice(1) : id;
+    return body.startsWith(VIRTUAL_FONT_CSS_PREFIX) && body.endsWith(VIRTUAL_FONT_CSS_SUFFIX);
+  }
+
+  /** Drop every registered mapping. Used by tests. */
+  clear(): void {
+    this.map.clear();
+  }
+}
+
+/**
+ * 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');
+}