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

package/src/fonts/pipeline.ts

@@ -0,0 +1,314 @@
+/**
+ * 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';
+import { VirtualFontCssIdMap } from './virtual-modules.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>();
+
+  /**
+   * 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.
+    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();
+    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 cssParts: string[] = [];
+    for (const entry of this._entries.values()) {
+      cssParts.push(renderEntryCss(entry));
+    }
+    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 cssParts: string[] = [];
+    for (const entry of this._entries.values()) {
+      if (entry.importer !== importer) continue;
+      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);
+    }
+  }
+}