@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/src/plugins/fonts.ts

@@ -1,411 +1,152 @@
 /**
- * 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 { parseAst } from 'vite';
+import type { Plugin, ResolvedConfig, ViteDevServer } from 'vite';
+import type { PluginContext } from '../plugin-context.ts';
+import type { BuildManifest } from '../server/build-manifest.ts';
 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');
-}
+  downloadAndCacheFonts,
+  generateProductionFontFaces,
+  resolveDevFontFaces,
+} from '../fonts/google.ts';
+import { FONT_OUTPUT_DIR, fontUrlPrefix } from '../fonts/paths.ts';
+import { FontPipeline } from '../fonts/pipeline.ts';
+import { runFontsTransform } from '../fonts/transform.ts';
+import { installFontDevMiddleware } from '../fonts/dev-middleware.ts';
+import { emitFontAssets, writeFontManifest, groupCachedFontsByFamily } from '../fonts/bundle.ts';
+import {
+  RESOLVED_GOOGLE,
+  RESOLVED_LOCAL,
+  VIRTUAL_GOOGLE,
+  VIRTUAL_LOCAL,
+  generateGoogleVirtualModule,
+  generateLocalVirtualModule,
+} from '../fonts/virtual-modules.ts';
+
+// ── 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 } from '../fonts/pipeline.ts';
+export {
+  generateFontId,
+  extractFontConfig,
+  detectDynamicFontCall,
+  parseGoogleFontImports,
+  parseGoogleFontFamilies,
+  parseLocalFontImportName,
+} from '../fonts/transform.ts';
 
 /**
- * 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'
+ * What the post-build phase asks of the font plugin (plugins/post-build.ts).
+ * Called after every environment has been built, so the font entries are
+ * complete — no environment's `generateBundle` has to run after the build
+ * manifest exists.
  */
-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;
+export interface FontsBuildStep {
+  /** Write this build's font entries into the build manifest. */
+  contributeManifest(manifest: BuildManifest): void;
+  /**
+   * Directories of the client bundle this build filled with content-hashed
+   * font binaries — `[FONT_OUTPUT_DIR]` when any were emitted, else none.
+   */
+  immutableDirs(): string[];
 }
 
 /**
  * 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[] = [];
+export function timberFonts(ctx: PluginContext): Plugin & { api: FontsBuildStep } {
+  const pipeline = new FontPipeline({ hashOnRegister: !ctx.dev });
+  /** Whether the client environment emitted a binary this build. */
+  let emittedToClient = false;
 
   return {
     name: 'timber-fonts',
 
+    api: {
+      contributeManifest: (manifest) => writeFontManifest(pipeline, manifest, ctx.base),
+      immutableDirs: () => (emittedToClient ? [FONT_OUTPUT_DIR] : []),
+    },
+
+    /**
+     * Push Vite's resolved `base` into the pipeline so every font URL it
+     * emits (@font-face src, manifest hrefs, dev middleware matching)
+     * carries the prefix. Emitted file locations are unaffected — only URLs.
+     *
+     * `config.base` is read here rather than `ctx.base`: this plugin is
+     * `enforce: 'pre'`, so its configResolved runs before timber-root-sync
+     * populates `ctx.base`. Every *later* hook reads `ctx.base` — the single
+     * copy (TIM-1261).
+     */
+    configResolved(config: ResolvedConfig) {
+      pipeline.setBase(config.base);
+
+      // Font binaries are emitted in generateBundle, after Vite's CSS
+      // url() resolution runs. The warnings are benign — suppress them.
+      const originalWarnOnce = config.logger.warnOnce.bind(config.logger);
+      config.logger.warnOnce = (msg, options) => {
+        if (msg.includes('_timber/fonts/') && msg.includes("didn't resolve at build time")) return;
+        originalWarnOnce(msg, options);
+      };
+    },
+
+    /**
+     * `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=...>`.
+     *
+     * 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 `virtual:timber-font-css` virtual modules.
+     * Resolve `@timber/fonts/google`, `@timber/fonts/local`, and the
+     * per-importer `virtual:timber-font-css/<hash>.css` modules injected
+     * by the transform hook.
      *
-     * Handles \0 prefix and root prefix stripping for RSC/SSR
-     * environments where the RSC plugin re-imports virtual modules
-     * with additional prefixes.
+     * 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('?');
+      const query = qIdx !== -1 ? cleanId.slice(qIdx) : '';
+      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 +158,179 @@ 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;
+      // Preserve query suffix (notably `?direct`) on the resolved CSS id.
+      // Vite's transform middleware appends `?direct` when the browser
+      // fetches the URL as a `<link rel="stylesheet">`, and the CSS plugin
+      // only skips its JS-wrapping step when `isDirectCSSRequest(id)` sees
+      // that query on the resolved id. Dropping it here caused virtual
+      // font CSS to be served as Vite's HMR JS shim, leaving the
+      // `<link>`-loaded stylesheet empty (TIM-937 follow-up).
+      if (pipeline.cssIdMap.matches(cleanId)) return '\0' + cleanId + query;
       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.
+     *
+     * Google `@font-face` descriptors are resolved lazily here (both
+     * dev and production) because `load` runs after `transform` has
+     * registered the font. `buildStart` runs before any transforms,
+     * so fonts aren't in the pipeline yet when it fires for the first
+     * environment.
      */
-    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)};`;
-      }
-      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.
-     */
-    configureServer(server: ViteDevServer) {
-      server.middlewares.use((req, res, next) => {
-        const url = req.url;
-        if (!url || !url.startsWith('/_timber/fonts/')) return next();
+      if (pipeline.cssIdMap.matches(id)) {
+        const importer = pipeline.cssIdMap.importerFor(id);
+        if (!importer) {
+          return '';
+        }
 
-        const requestedFilename = url.slice('/_timber/fonts/'.length);
-        // Reject path traversal attempts
-        if (requestedFilename.includes('..') || requestedFilename.includes('/')) {
-          res.statusCode = 400;
-          res.end('Bad request');
-          return;
+        // The analyze crawl only needs import edges, not actual font
+        // CSS. Return an empty stylesheet so transforms resolve
+        // without triggering network fetches or cache writes.
+        if (process.env.TIMBER_ANALYZE === '1') {
+          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.).
+        const skipFonts = process.env.TIMBER_SKIP_FONTS === '1';
 
-        // 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;
+        for (const font of pipeline.googleFonts()) {
+          if (font.importer !== importer) continue;
+          if (pipeline.hasFaces(font.id)) continue;
+          if (skipFonts && !ctx.dev) {
+            console.warn(`[timber-fonts] Skipping font "${font.family}" (TIMBER_SKIP_FONTS=1)`);
+            continue;
+          }
+          try {
+            if (ctx.dev) {
+              const faces = await resolveDevFontFaces(font);
+              pipeline.attachFaces(font.id, faces);
+            } else {
+              const cached = await downloadAndCacheFonts([font], ctx.root);
+              const byFamily = groupCachedFontsByFamily(cached);
+              const familyCached = byFamily.get(font.family.toLowerCase()) ?? [];
+              pipeline.attachCachedFiles(font.id, familyCached);
+              pipeline.attachFaces(
+                font.id,
+                generateProductionFontFaces(familyCached, font.display, fontUrlPrefix(ctx.base))
+              );
             }
+          } catch (e) {
+            if (!ctx.dev) throw e;
+            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.`
+            );
           }
         }
 
-        next();
-      });
+        return pipeline.getCssForSegment(importer);
+      }
+      return null;
     },
 
     /**
-     * Download and cache Google Fonts during production builds.
-     *
-     * In dev mode this is a no-op — fonts point to the Google CDN.
-     * The registry is populated by the transform hook which runs before
-     * buildStart in the build pipeline, so all fonts are known here.
+     * Serve local font files in dev mode under `/_timber/fonts/<basename>`.
+     * Font CSS goes through Vite's CSS pipeline (virtual modules), not
+     * this middleware.
      */
-    async buildStart() {
-      if (ctx.dev) return;
-
-      const googleFonts = [...registry.values()].filter((f) => f.provider === 'google');
-      if (googleFonts.length === 0) return;
-
-      cachedFonts = await downloadAndCacheFonts(googleFonts, ctx.root);
+    configureServer(server: ViteDevServer) {
+      installFontDevMiddleware(server, pipeline, ctx.base);
     },
 
     /**
-     * Scan source files for font function calls and extract static config.
+     * No-op. Font downloading and face attachment happen lazily in `load()`
+     * because `buildStart` runs before `transform` — fonts aren't registered
+     * in the pipeline yet when this fires for the first environment.
      *
-     * 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
+     * Local font hashing is handled at registration time by the pipeline
+     * (when `hashOnRegister` is set) so hashed filenames are available
+     * before the virtual CSS `load()` hook runs.
      */
-    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.`
-            );
-          }
+    buildStart() {},
 
-          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)
-        );
+    /**
+     * Prune stale font entries when a module that previously imported fonts
+     * no longer contains any font import. The transform hook's `filter.code`
+     * skips such modules, so without this hook the old entries would persist
+     * until dev restart. See TIM-1087.
+     */
+    async hotUpdate({ type, file, read }) {
+      if (!pipeline.hasImporter(file)) return;
+      if (type === 'delete') {
+        pipeline.pruneImporter(file);
+        return;
       }
-
-      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 };
+      const code = await read();
+      const hasFontImport =
+        code.includes('@timber/fonts/') ||
+        code.includes('@timber-js/app/fonts/') ||
+        code.includes('next/font/');
+      if (hasFontImport) return;
+      // Only prune if the new source parses successfully. A syntax error
+      // means the HMR update will fail and the old module stays active —
+      // pruning would leave it without font CSS until the next valid save.
+      try {
+        parseAst(code, { lang: 'tsx' });
+      } catch {
+        return;
       }
-
-      return null;
+      pipeline.pruneImporter(file);
     },
 
     /**
-     * Emit font files and metadata into the build output.
+     * Scan source files for font function calls and extract static config.
      *
-     * For Google fonts: emits the downloaded, content-hashed woff2 files
-     * and writes ManifestFontEntry arrays using real hashed URLs.
+     * Delegates to `runFontsTransform`. Errors raised through the
+     * `this.error` callback are surfaced as Vite plugin errors.
      *
-     * For local fonts: emits entries using the source file paths.
+     * The `filter` option uses Vite 8's rolldown-native hook filters to
+     * skip non-JS/TS files and files that don't mention any font module
+     * before crossing into JS — replacing the hand-rolled pre-filter that
+     * was previously inside `runFontsTransform` (TIM-840, TIM-1147).
+     */
+    transform: {
+      filter: {
+        id: {
+          include: /^[^?]*\.(?:js|jsx|ts|tsx|mjs|cjs|mts|cts)(?:\?|$)/,
+          exclude: /(?:^\0|(?:^|\/)node_modules\/)/,
+        },
+        code: ['@timber/fonts/', '@timber-js/app/fonts/', 'next/font/'],
+      },
+      handler(code: string, id: string) {
+        return runFontsTransform(code, id, pipeline, (msg) => this.error(msg));
+      },
+    },
+
+    /**
+     * Emit font binaries.
      *
-     * In dev mode the build manifest is null, so this is a no-op.
+     * All font binaries (Google and local) use content-hashed filenames
+     * for immutable caching. Font CSS is handled by Vite's CSS pipeline
+     * via virtual modules — we only emit binaries here. Manifest entries are
+     * written by the post-build phase through `api.contributeManifest`.
      */
     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.
-
-      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;
-      }
+      let emitted = 0;
+      emitFontAssets(
+        pipeline,
+        (asset) => {
+          emitted++;
+          return this.emitFile(asset);
+        },
+        (msg) => this.warn(msg)
+      );
+      if (this.environment?.name === 'client') emittedToClient = emitted > 0;
     },
   };
 }