@timber-js/app 0.2.0-alpha.14 → 0.2.0-alpha.141

package/src/fonts/transform.ts

@@ -0,0 +1,317 @@
+/**
+ * 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.
+ *
+ * Uses a single OXC (via vite.parseAst) parse of the source file (via `findFontCallSites`)
+ * and magic-string for precise source rewrites with source maps.
+ *
+ * Design doc: 24-fonts.md
+ */
+
+import MagicString from 'magic-string';
+import type { ExtractedFont, GoogleFontConfig } from './types.js';
+import { buildFontStack } from './fallbacks.js';
+import { processLocalFont } from './local.js';
+import {
+  extractFontConfigAst,
+  detectDynamicFontCallAst,
+  findFontCallSites,
+  extractGoogleFontConfigFromNode,
+  extractLocalFontConfigFromNode,
+} from './ast.js';
+import type { FontPipeline } from './pipeline.js';
+
+/**
+ * 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);
+}
+
+// ── Regex-free import/family parsing (thin wrappers over AST) ────────────────
+//
+// These keep the public surface stable. They use `findFontCallSites`
+// internally so they agree with the transform on what counts as an import.
+
+/**
+ * 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 analysis = findFontCallSites(source);
+  if (!analysis) return [];
+  return analysis.bindings.filter((b) => b.provider === 'google').map((b) => b.localName);
+}
+
+/**
+ * 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 analysis = findFontCallSites(source);
+  const families = new Map<string, string>();
+  if (!analysis) return families;
+  for (const b of analysis.bindings) {
+    if (b.provider !== 'google') continue;
+    const family = b.importedName.replace(/_/g, ' ');
+    families.set(b.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 analysis = findFontCallSites(source);
+  if (!analysis) return null;
+  const localBinding = analysis.bindings.find((b) => b.provider === 'local');
+  return localBinding?.localName ?? 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;
+
+/**
+ * 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.
+ *
+ * See TIM-840.
+ */
+const FONT_IMPORT_SCANNABLE_EXTENSIONS = new Set([
+  '.js',
+  '.jsx',
+  '.ts',
+  '.tsx',
+  '.mjs',
+  '.cjs',
+  '.mts',
+  '.cts',
+]);
+
+function hasScannableExtension(id: string): boolean {
+  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());
+}
+
+/**
+ * Run the timber-fonts transform pass on a single source file.
+ *
+ * Parses the source once with OXC (via vite.parseAst), walks the AST to find font imports
+ * and call sites, then uses magic-string to rewrite call sites to static
+ * `FontResult` literals and strip the import declarations. Returns a
+ * source map alongside the transformed code.
+ *
+ * Returns `null` if the file does not import from any font virtual module.
+ */
+export function runFontsTransform(
+  code: string,
+  id: string,
+  pipeline: FontPipeline,
+  emitError: EmitError
+): { code: string; map: ReturnType<MagicString['generateMap']> } | null {
+  // Skip virtual modules and node_modules
+  if (id.startsWith('\0') || id.includes('node_modules')) return null;
+
+  // Only scan JS/TS module variants (see TIM-840).
+  if (!hasScannableExtension(id)) return null;
+
+  // Fast pre-filter: skip files that don't mention any font module.
+  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;
+
+  // Single parse + AST walk.
+  const analysis = findFontCallSites(code);
+  if (!analysis) return null;
+
+  // Bail on dynamic calls.
+  if (analysis.dynamicCall) {
+    emitError(
+      `Font function calls must be statically analyzable. ` +
+        `Found dynamic call: ${analysis.dynamicCall}. ` +
+        `Pass a literal object with string/array values instead.`
+    );
+  }
+
+  // Bail on nested font calls (must be module-level).
+  if (analysis.nestedCalls.length > 0) {
+    const first = analysis.nestedCalls[0];
+    emitError(
+      `Font function \`${first.name}()\` must be called at module scope. ` +
+        `Found nested call at line ${first.line}, column ${first.column}. ` +
+        `Move the call to the top level of the module.`
+    );
+  }
+
+  if (analysis.callSites.length === 0 && analysis.bindings.length === 0) return null;
+
+  const s = new MagicString(code);
+
+  // Process each call site.
+  for (const site of analysis.callSites) {
+    if (site.binding.provider === 'google') {
+      const family = site.binding.importedName.replace(/_/g, ' ');
+
+      const config = extractGoogleFontConfigFromNode(site.configNode);
+      if (!config) {
+        emitError(
+          `Could not statically analyze font config for ${family} ` +
+            `at line ${site.line}, column ${site.column}. ` +
+            `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: id,
+      };
+
+      pipeline.pruneFor(id, family);
+      pipeline.register(extracted);
+
+      s.overwrite(site.replaceStart, site.replaceEnd, buildFontResultLiteral(extracted));
+    } else {
+      // local font
+      const config = extractLocalFontConfigFromNode(site.configNode);
+      if (!config) {
+        emitError(
+          `Could not statically analyze local font config ` +
+            `at line ${site.line}, column ${site.column}. ` +
+            `Ensure src is a string or array of { path, weight?, style? } objects.`
+        );
+      }
+
+      const extracted = processLocalFont(config!, id);
+      pipeline.pruneFor(id, extracted.family);
+      pipeline.register(extracted);
+
+      s.overwrite(site.replaceStart, site.replaceEnd, buildFontResultLiteral(extracted));
+    }
+  }
+
+  // Remove font import declarations. Use a Set to avoid double-removing
+  // when multiple bindings come from the same ImportDeclaration.
+  const removedRanges = new Set<string>();
+  for (const imp of analysis.importNodesToRemove) {
+    const key = `${imp.start}:${imp.end}`;
+    if (removedRanges.has(key)) continue;
+    removedRanges.add(key);
+
+    // Also remove the trailing newline if present.
+    let end = imp.end;
+    if (code[end] === '\n') end++;
+    else if (code[end] === '\r' && code[end + 1] === '\n') end += 2;
+    // Also remove a trailing semicolon before the newline.
+    if (code[imp.end] === ';') {
+      end = imp.end + 1;
+      if (code[end] === '\n') end++;
+      else if (code[end] === '\r' && code[end + 1] === '\n') end += 2;
+    }
+    s.remove(imp.start, end);
+  }
+
+  if (!s.hasChanged()) return null;
+
+  // Inject a side-effect import for the per-importer virtual CSS module.
+  if (pipeline.size() > 0) {
+    const virtualCssId = pipeline.cssIdMap.idFor(id);
+    s.prepend(`import '${virtualCssId}';\n`);
+  }
+
+  return {
+    code: s.toString(),
+    map: s.generateMap({ hires: true }),
+  };
+}

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[];
@@ -22,6 +26,8 @@ export interface LocalFontSrc {
   path: string;
   weight?: string;
   style?: string;
+  /** Content-hashed basename for production builds (e.g. `MyFont-Bold-a1b2c3d4.woff2`). */
+  hashedBasename?: string;
 }
 
 /** Configuration passed to `localFont()`. */
@@ -47,7 +53,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 +101,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,235 @@
+/**
+ * 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.
+ */
+function stripIdDecorations(id: string): string {
+  const bare = id.startsWith('\0') ? id.slice(1) : id;
+  const qIdx = bare.indexOf('?');
+  return qIdx === -1 ? bare : bare.slice(0, qIdx);
+}
+
+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 = stripIdDecorations(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 = stripIdDecorations(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 {',
+    // eslint-disable-next-line no-template-curly-in-string -- codegen output
+    '    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 {',
+    // eslint-disable-next-line no-template-curly-in-string -- codegen output
+    '    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');
+}