@timber-js/app 0.2.0-alpha.16 → 0.2.0-alpha.160

package/src/fonts/pipeline.ts

@@ -0,0 +1,316 @@
+/**
+ * FontPipeline — owns all per-font state for the timber-fonts plugin.
+ *
+ * Before TIM-829, font state was spread across three parallel mutable maps:
+ *
+ *   - `registry: Map<string, ExtractedFont>`
+ *   - `googleFontFacesMap: Map<string, FontFaceDescriptor[]>`
+ *   - `cachedFonts: CachedFont[]`
+ *
+ * Every plugin hook had to remember which map(s) it owned and which it
+ * read. The TIM-824 bug existed because `transform` could write to
+ * `registry` multiple times for the same `(importer, family)` pair without
+ * a corresponding cleanup of the entries that `buildStart` / `load` would
+ * later use. The fix in TIM-824 added prune calls in `transform` for the
+ * registry, but the parallel maps still had the same hazard latent in
+ * them: any future code path that ran `buildStart`-equivalent logic on
+ * HMR could re-introduce a stale-entry leak in a different map.
+ *
+ * TIM-829 collapses the three maps into a single `Map<string, FontEntry>`
+ * keyed by font ID. Mutation goes through a small set of methods that
+ * maintain the core invariant: **every piece of state belonging to a font
+ * lives on its `FontEntry`, and `pruneFor` removes the entry along with
+ * everything attached to it in one call.** No code path inside the plugin
+ * touches the underlying map directly.
+ *
+ * Design doc: 24-fonts.md
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, normalize } from 'node:path';
+import type { ExtractedFont, FontEntry, FontFaceDescriptor } from './types.js';
+import type { CachedFont } from './google.js';
+import { contentHash } from './google.js';
+import { generateVariableClass, generateFontFamilyClass, generateFontFaces } from './css.js';
+import { generateFallbackCss } from './fallbacks.js';
+import { generateLocalFontFaces } from './local.js';
+import { hashedFontBasename, fontUrlPrefix } from './paths.js';
+import { VirtualFontCssIdMap } from './virtual-modules.js';
+
+export class FontPipeline {
+  /**
+   * The single per-font store. Keyed by `FontEntry.id` (which is itself
+   * derived from `family + weights + styles + subsets + display`, so any
+   * config change produces a new key).
+   *
+   * Marked `readonly` so the field reference can never be reassigned, but
+   * the map contents are mutable through the methods below.
+   */
+  private readonly _entries = new Map<string, FontEntry>();
+
+  /** When true, local font sources are content-hashed at registration time. */
+  private readonly _hashOnRegister: boolean;
+
+  /**
+   * Vite's resolved `base`. Set from the plugin's `configResolved` hook so
+   * every @font-face URL the pipeline renders carries the prefix.
+   */
+  private _base = '/';
+
+  constructor(opts?: { hashOnRegister?: boolean }) {
+    this._hashOnRegister = opts?.hashOnRegister ?? false;
+  }
+
+  /** Set Vite's resolved `base` (from `configResolved`). */
+  setBase(base: string): void {
+    this._base = base;
+  }
+
+  /**
+   * Per-importer virtual CSS module id registry. Populated by the
+   * transform hook when it inlines a font function call, read by the
+   * plugin's `load` hook when Vite asks for the module's CSS source.
+   *
+   * Lives on the pipeline (rather than a module-level singleton) so
+   * multiple parallel plugin instances — e.g. in the test suite — cannot
+   * collide on the hash-to-importer map. Also makes `clear()` reset the
+   * id map alongside the font entries so test fixtures start clean.
+   */
+  readonly cssIdMap = new VirtualFontCssIdMap();
+
+  // ── Read-only accessors ─────────────────────────────────────────────────
+
+  /** Number of registered fonts. */
+  size(): number {
+    return this._entries.size;
+  }
+
+  /** Iterate every entry as a `FontEntry` (with `faces` / `cachedFiles`). */
+  entries(): IterableIterator<FontEntry> {
+    return this._entries.values();
+  }
+
+  /** Iterate every entry typed as the narrower `ExtractedFont` shape. */
+  fonts(): IterableIterator<ExtractedFont> {
+    return this._entries.values();
+  }
+
+  /** Iterate every Google-provider entry. */
+  *googleFonts(): IterableIterator<FontEntry> {
+    for (const entry of this._entries.values()) {
+      if (entry.provider === 'google') yield entry;
+    }
+  }
+
+  /** Lookup an entry by font ID. */
+  getEntry(id: string): FontEntry | undefined {
+    return this._entries.get(id);
+  }
+
+  /**
+   * True if `attachFaces()` has been called for `fontId` — even with an
+   * empty array. This intentionally treats an empty resolution as
+   * "already processed" so the dev `load()` path doesn't keep retrying
+   * `resolveDevFontFaces()` on every request when Google returns no
+   * matching faces for the requested subset(s). Mirrors the previous
+   * `Map.has()` semantics this method replaced. (Codex review on PR #596.)
+   *
+   * Failures inside `resolveDevFontFaces` do not call `attachFaces` at
+   * all, so they correctly stay retryable on the next request — see the
+   * TIM-636 comment in `plugins/fonts.ts`.
+   */
+  hasFaces(fontId: string): boolean {
+    const entry = this._entries.get(fontId);
+    return entry?.faces !== undefined;
+  }
+
+  /**
+   * True if `attachCachedFiles()` has been called for `fontId` — even
+   * with an empty array. Same presence-vs-content rationale as
+   * `hasFaces`: an empty resolution is a deterministic outcome, not a
+   * "not yet processed" signal.
+   */
+  hasCachedFiles(fontId: string): boolean {
+    const entry = this._entries.get(fontId);
+    return entry?.cachedFiles !== undefined;
+  }
+
+  // ── Mutators ────────────────────────────────────────────────────────────
+
+  /**
+   * Register an extracted font under its content-derived ID.
+   *
+   * If an entry with the same ID already exists it is replaced wholesale,
+   * dropping any previously-attached `faces` and `cachedFiles`. Callers
+   * must call `pruneFor(importer, family)` first to ensure that any
+   * previous registration from the same `(importer, family)` pair has been
+   * dropped (TIM-824).
+   */
+  register(extracted: ExtractedFont): void {
+    // Wholesale replace — never merge faces/cachedFiles from a previous
+    // registration. Re-registration with the same ID always represents the
+    // newest authoritative config and must start from a clean slate.
+    const entry: FontEntry = { ...extracted };
+    if (this._hashOnRegister && entry.provider === 'local' && entry.localSources) {
+      for (const src of entry.localSources) {
+        const absolutePath = normalize(resolve(src.path));
+        if (!existsSync(absolutePath)) continue;
+        const data = readFileSync(absolutePath);
+        src.hashedBasename = hashedFontBasename(src.path, contentHash(data));
+      }
+    }
+    this._entries.set(entry.id, entry);
+  }
+
+  /** Attach pre-resolved `@font-face` descriptors to a font entry. */
+  attachFaces(fontId: string, faces: FontFaceDescriptor[]): void {
+    const entry = this._entries.get(fontId);
+    if (!entry) {
+      throw new Error(
+        `[timber-fonts] attachFaces: no font entry registered for id "${fontId}". ` +
+          `Call register() first.`
+      );
+    }
+    entry.faces = faces;
+  }
+
+  /** Attach downloaded Google Font binaries to a font entry. */
+  attachCachedFiles(fontId: string, files: CachedFont[]): void {
+    const entry = this._entries.get(fontId);
+    if (!entry) {
+      throw new Error(
+        `[timber-fonts] attachCachedFiles: no font entry registered for id "${fontId}". ` +
+          `Call register() first.`
+      );
+    }
+    entry.cachedFiles = files;
+  }
+
+  /**
+   * Drop every registry entry that originated from `importer` and shares
+   * `family` (case-insensitive), **along with all of its attached state**.
+   *
+   * This is the single chokepoint that guarantees stale `@font-face`
+   * descriptors and orphaned cached binaries cannot leak across HMR edits.
+   * Because every piece of per-font state lives on the `FontEntry`,
+   * deleting the entry from the underlying map drops everything in one
+   * operation — no parallel maps to keep in sync.
+   *
+   * See TIM-824 (the original prune fix) and TIM-829 (single-store
+   * refactor that made this guarantee structural).
+   */
+  pruneFor(importer: string, family: string): void {
+    const familyKey = family.toLowerCase();
+    for (const [id, entry] of this._entries) {
+      if (entry.importer === importer && entry.family.toLowerCase() === familyKey) {
+        this._entries.delete(id);
+      }
+    }
+  }
+
+  /** Drop every registered font. Used by tests and rebuild flows. */
+  clear(): void {
+    this._entries.clear();
+    this.cssIdMap.clear();
+  }
+
+  // ── Derived views ───────────────────────────────────────────────────────
+
+  /**
+   * Iterate every cached Google Font binary across all registered entries,
+   * deduplicated by `hashedFilename`. Multiple entries that share the same
+   * family hold references to the same `CachedFont` objects, so this
+   * iterator yields each unique binary exactly once.
+   */
+  *uniqueCachedFiles(): IterableIterator<CachedFont> {
+    const seen = new Set<string>();
+    for (const entry of this._entries.values()) {
+      if (!entry.cachedFiles) continue;
+      for (const cf of entry.cachedFiles) {
+        if (seen.has(cf.hashedFilename)) continue;
+        seen.add(cf.hashedFilename);
+        yield cf;
+      }
+    }
+  }
+
+  /**
+   * Generate the combined CSS output for every registered font.
+   *
+   * Includes `@font-face` rules for local and Google fonts, fallback
+   * `@font-face` rules, and scoped class rules. Google fonts use the
+   * `faces` attached via `attachFaces()` (in `buildStart` for production
+   * or lazily in `load` for dev).
+   */
+  getCss(): string {
+    const urlPrefix = fontUrlPrefix(this._base);
+    const cssParts: string[] = [];
+    for (const entry of this._entries.values()) {
+      cssParts.push(renderEntryCss(entry, urlPrefix));
+    }
+    return cssParts.join('\n\n');
+  }
+
+  /**
+   * Render the combined CSS for every font registered from a specific
+   * importer file. This is the anchor point for the per-importer virtual
+   * CSS module (`virtual:timber-font-css/<hash>.css`) that the transform
+   * hook injects as a side-effect import.
+   *
+   * Scoping by importer means two concurrent requests rendering different
+   * routes cannot see each other's font CSS: each importer's virtual
+   * module only contains CSS for fonts that module registered. It also
+   * means Vite's CSS HMR can surgically reload just the affected importer
+   * when a single file changes, rather than rebuilding one giant blob.
+   *
+   * Returns an empty string when no fonts are registered under `importer`.
+   * The empty string is semantically equivalent to "no CSS" — Vite's CSS
+   * pipeline handles it as a valid empty CSS module.
+   */
+  getCssForSegment(importer: string): string {
+    const urlPrefix = fontUrlPrefix(this._base);
+    const cssParts: string[] = [];
+    for (const entry of this._entries.values()) {
+      if (entry.importer !== importer) continue;
+      cssParts.push(renderEntryCss(entry, urlPrefix));
+    }
+    return cssParts.join('\n\n');
+  }
+}
+
+/**
+ * Render the combined CSS for a single font entry.
+ *
+ * Reads `faces` straight off the entry. Private to this module — the only
+ * public way to render a `FontEntry`'s CSS is through `FontPipeline.getCss()`.
+ */
+function renderEntryCss(entry: FontEntry, urlPrefix: string): string {
+  const cssParts: string[] = [];
+
+  if (entry.provider === 'local' && entry.localSources) {
+    const faces = generateLocalFontFaces(
+      entry.family,
+      entry.localSources,
+      entry.display,
+      urlPrefix
+    );
+    const faceCss = generateFontFaces(faces);
+    if (faceCss) cssParts.push(faceCss);
+  }
+
+  if (entry.provider === 'google' && entry.faces && entry.faces.length > 0) {
+    const faceCss = generateFontFaces(entry.faces);
+    if (faceCss) cssParts.push(faceCss);
+  }
+
+  const fallbackCss = generateFallbackCss(entry.family);
+  if (fallbackCss) cssParts.push(fallbackCss);
+
+  if (entry.variable) {
+    cssParts.push(generateVariableClass(entry.className, entry.variable, entry.fontFamily));
+  } else {
+    cssParts.push(generateFontFamilyClass(entry.className, entry.fontFamily));
+  }
+
+  return cssParts.join('\n\n');
+}

package/src/fonts/transform.ts

@@ -0,0 +1,305 @@
+/**
+ * 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;
+
+/**
+ * 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.
+ *
+ * Pre-filtering (extension allow-list, node_modules exclusion, and code
+ * substring checks) is handled by Vite 8's rolldown-native `transform.filter`
+ * in the plugin hook definition (plugins/fonts.ts). See TIM-840, TIM-1147.
+ */
+export function runFontsTransform(
+  code: string,
+  id: string,
+  pipeline: FontPipeline,
+  emitError: EmitError
+): { code: string; map: ReturnType<MagicString['generateMap']> } | 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.`
+    );
+  }
+
+  // Bail on namespace imports of font modules — the transform cannot
+  // rewrite `fonts.Inter(...)` member calls, so the font would silently
+  // never load.
+  if (analysis.namespaceImports.length > 0) {
+    const first = analysis.namespaceImports[0];
+    emitError(
+      `Namespace imports of font modules are not supported ` +
+        `(\`* as ${first.name}\` at line ${first.line}, column ${first.column}). ` +
+        `Use a named import instead: \`import { Inter } from 'next/font/google'\`.`
+    );
+  }
+
+  // Bail on font binding references the transform cannot rewrite
+  // (`export default Inter({...})`, object-literal nesting, member access
+  // on the call result, aliasing, re-exports). The import declaration is
+  // removed, so leaving these would be a silent runtime ReferenceError.
+  if (analysis.unsupportedUsages.length > 0) {
+    const first = analysis.unsupportedUsages[0];
+    emitError(
+      `Unsupported usage of font function \`${first.name}\` at ` +
+        `line ${first.line}, column ${first.column}. ` +
+        `A font call must be \`const x = Font({...})\` at module scope ` +
+        `(export const is fine). The call result cannot be nested in other ` +
+        `expressions, and the imported font function cannot be aliased or re-exported.`
+    );
+  }
+
+  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[];
+}