@timber-js/app 0.2.0-alpha.87 → 0.2.0-alpha.89

package/src/fonts/pipeline.ts

@@ -0,0 +1,275 @@
+/**
+ * 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 type { ExtractedFont, FontEntry, FontFaceDescriptor } from './types.js';
+import type { CachedFont } from './google.js';
+import { generateVariableClass, generateFontFamilyClass, generateFontFaces } from './css.js';
+import { generateFallbackCss } from './fallbacks.js';
+import { generateLocalFontFaces } from './local.js';
+
+/**
+ * Backwards-compatible alias for the registry shape that the standalone
+ * `pruneRegistryEntries` and `generateAllFontCss` helpers operate on.
+ *
+ * The `FontPipeline` itself stores `Map<string, FontEntry>` internally and
+ * never exposes its underlying map. Tests and external callers that build
+ * their own font registries (e.g. fixtures in `tests/fonts-hmr-prune.test.ts`)
+ * still pass plain `Map<string, ExtractedFont>` instances to the standalone
+ * helpers, which is why the alias survives.
+ */
+export type FontRegistry = Map<string, ExtractedFont>;
+
+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>();
+
+  // ── 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.
+    this._entries.set(extracted.id, { ...extracted });
+  }
+
+  /** 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();
+  }
+
+  // ── 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 cssParts: string[] = [];
+    for (const entry of this._entries.values()) {
+      cssParts.push(renderEntryCss(entry));
+    }
+    return cssParts.join('\n\n');
+  }
+}
+
+/**
+ * Render the combined CSS for a single font entry.
+ *
+ * Mirrors the standalone `generateFontCss` helper exported from
+ * `virtual-modules.ts`, but reads `faces` straight off the entry instead
+ * of from a parallel map. Kept private to this module so the only public
+ * way to render a `FontEntry`'s CSS is through `FontPipeline.getCss()`.
+ */
+function renderEntryCss(entry: FontEntry): string {
+  const cssParts: string[] = [];
+
+  if (entry.provider === 'local' && entry.localSources) {
+    const faces = generateLocalFontFaces(entry.family, entry.localSources, entry.display);
+    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');
+}
+
+/**
+ * Drop every registry entry that originated from `importer` and shares
+ * `family`. Standalone helper retained as a public export for the test
+ * suite (`tests/fonts-hmr-prune.test.ts`) and any external callers that
+ * still build their own `FontRegistry` maps.
+ *
+ * Prefer `FontPipeline#pruneFor` inside the plugin itself — it also drops
+ * attached `faces` and `cachedFiles` in the same operation.
+ */
+export function pruneRegistryEntries(
+  registry: FontRegistry,
+  importer: string,
+  family: string
+): void {
+  const familyKey = family.toLowerCase();
+  for (const [id, font] of registry) {
+    if (font.importer === importer && font.family.toLowerCase() === familyKey) {
+      registry.delete(id);
+    }
+  }
+}

package/src/fonts/transform.ts

@@ -0,0 +1,353 @@
+/**
+ * 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';
+import { VIRTUAL_FONT_CSS_REGISTER } from './virtual-modules.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 the side-effect
+ * `virtual:timber-font-css-register` import prepended) or `null` if the
+ * file does not import from any timber-fonts virtual module and therefore
+ * needs no transformation.
+ */
+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;
+
+  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 side-effect import that registers font CSS on globalThis.
+    // The RSC entry reads globalThis.__timber_font_css to inline a <style> tag.
+    if (pipeline.size() > 0) {
+      transformedCode = `import '${VIRTUAL_FONT_CSS_REGISTER}';\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[];
+}