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

package/src/fonts/bundle.ts

@@ -0,0 +1,131 @@
+/**
+ * Build-output emission for the timber-fonts plugin.
+ *
+ * Splits the `generateBundle` hook into pure helpers so the plugin shell
+ * can stay focused on Vite wiring. The functions here are deliberately
+ * Rollup-agnostic — they take an `EmitFile` callback so the plugin can
+ * pass `this.emitFile` from the `generateBundle` context.
+ *
+ * Design doc: 24-fonts.md
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, normalize, extname } from 'node:path';
+import type { ManifestFontEntry, BuildManifest } from '../server/build-manifest.js';
+import { contentHash } from './google.js';
+
+/**
+ * Minimal shape of the asset descriptor accepted by Rollup's `emitFile`.
+ * Declared inline rather than importing from `rollup` to keep `bundle.ts`
+ * Rollup-agnostic and avoid pulling the type into the build graph.
+ */
+interface EmittedAsset {
+  type: 'asset';
+  fileName: string;
+  source: string | Uint8Array;
+}
+import type { FontPipeline } from './pipeline.js';
+import type { CachedFont } from './google.js';
+import { inferFontFormat } from './local.js';
+
+type EmitFile = (asset: EmittedAsset) => string;
+type EmitWarning = (msg: string) => void;
+
+/** Group cached Google Font binaries by lowercase family name. */
+export function groupCachedFontsByFamily(
+  cachedFonts: readonly CachedFont[]
+): Map<string, CachedFont[]> {
+  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);
+  }
+  return cachedByFamily;
+}
+
+/**
+ * Emit cached Google Font binaries and local font files into the build
+ * output under `_timber/fonts/`. Local files missing on disk produce a
+ * warning rather than an error so the build still succeeds.
+ *
+ * Cached Google Font binaries are deduplicated by `hashedFilename` so
+ * each unique file is written exactly once even when multiple font
+ * entries share a family (and therefore share `CachedFont` references).
+ */
+export function emitFontAssets(
+  pipeline: FontPipeline,
+  emitFile: EmitFile,
+  warn: EmitWarning
+): void {
+  // Cached Google Font binaries (content-hashed, deduped by filename)
+  for (const cf of pipeline.uniqueCachedFiles()) {
+    emitFile({
+      type: 'asset',
+      fileName: `_timber/fonts/${cf.hashedFilename}`,
+      source: cf.data,
+    });
+  }
+
+  // Local font files (content-hashed for immutable caching)
+  for (const font of pipeline.fonts()) {
+    if (font.provider !== 'local' || !font.localSources) continue;
+    for (const src of font.localSources) {
+      const absolutePath = normalize(resolve(src.path));
+      if (!existsSync(absolutePath)) {
+        warn(`Local font file not found: ${absolutePath}`);
+        continue;
+      }
+      const filename = src.hashedBasename ?? src.path.split('/').pop() ?? src.path;
+      const data = readFileSync(absolutePath);
+      emitFile({
+        type: 'asset',
+        fileName: `_timber/fonts/${filename}`,
+        source: data,
+      });
+    }
+  }
+}
+
+/**
+ * Populate `buildManifest.fonts` with `ManifestFontEntry[]` keyed by the
+ * absolute importer path. This matches the runtime route manifest's
+ * `filePath` values (which are absolute) and is consistent with how
+ * `buildManifest.css` keys work after TIM-1014.
+ *
+ * All font binaries use content-hashed filenames for immutable caching.
+ */
+export function writeFontManifest(pipeline: FontPipeline, buildManifest: BuildManifest): void {
+  const fontsByImporter = new Map<string, ManifestFontEntry[]>();
+
+  for (const entry of pipeline.entries()) {
+    const manifestEntries = fontsByImporter.get(entry.importer) ?? [];
+
+    if (entry.provider === 'local' && entry.localSources) {
+      for (const src of entry.localSources) {
+        const filename = src.hashedBasename ?? src.path.split('/').pop() ?? src.path;
+        const format = inferFontFormat(src.path);
+        manifestEntries.push({
+          href: `/_timber/fonts/${filename}`,
+          format,
+          crossOrigin: 'anonymous',
+        });
+      }
+    } else if (entry.cachedFiles) {
+      for (const cf of entry.cachedFiles) {
+        manifestEntries.push({
+          href: `/_timber/fonts/${cf.hashedFilename}`,
+          format: 'woff2',
+          crossOrigin: 'anonymous',
+        });
+      }
+    }
+
+    fontsByImporter.set(entry.importer, manifestEntries);
+  }
+
+  for (const [importer, entries] of fontsByImporter) {
+    buildManifest.fonts[importer] = entries;
+  }
+}

package/src/fonts/dev-middleware.ts

@@ -0,0 +1,74 @@
+/**
+ * Dev-mode middleware that serves local font binaries under
+ * `/_timber/fonts/<basename>`.
+ *
+ * Only files registered in the FontPipeline are served, and only by
+ * basename — directory traversal and path separators in the requested
+ * filename are rejected up front. Font CSS is no longer served here; it
+ * goes through Vite's CSS pipeline via virtual modules.
+ *
+ * Design doc: 24-fonts.md
+ */
+
+import type { ViteDevServer } from 'vite';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, normalize } from 'node:path';
+import type { FontPipeline } from './pipeline.js';
+
+const FONT_MIME_TYPES: Record<string, string> = {
+  woff2: 'font/woff2',
+  woff: 'font/woff',
+  ttf: 'font/ttf',
+  otf: 'font/otf',
+  eot: 'application/vnd.ms-fontopen',
+};
+
+/**
+ * Wire the timber-fonts dev middleware onto a Vite dev server.
+ *
+ * Returns synchronously after registering the middleware. The pipeline is
+ * captured by reference so that fonts registered after `configureServer`
+ * runs (during transform) are still resolvable.
+ */
+export function installFontDevMiddleware(server: ViteDevServer, pipeline: FontPipeline): void {
+  server.middlewares.use((req, res, next) => {
+    const url = req.url;
+    if (!url || !url.startsWith('/_timber/fonts/')) return next();
+
+    const requestedFilename = url.slice('/_timber/fonts/'.length);
+    // Reject path traversal attempts and any subdirectory access. We only
+    // serve flat basenames out of the registry.
+    if (requestedFilename.includes('..') || requestedFilename.includes('/')) {
+      res.statusCode = 400;
+      res.end('Bad request');
+      return;
+    }
+
+    // Find the matching font file in the registry. We iterate every local
+    // font's source list and match by basename. The set is small (one per
+    // localFont() call) so this is cheap.
+    for (const font of pipeline.fonts()) {
+      if (font.provider !== 'local' || !font.localSources) continue;
+      for (const src of font.localSources) {
+        const basename = src.path.split('/').pop() ?? '';
+        if (basename !== requestedFilename && src.hashedBasename !== requestedFilename) continue;
+
+        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();
+        res.setHeader('Content-Type', FONT_MIME_TYPES[ext ?? ''] ?? 'application/octet-stream');
+        res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.end(data);
+        return;
+      }
+    }
+
+    next();
+  });
+}

package/src/fonts/local.ts

@@ -112,10 +112,10 @@ export function generateLocalFontFaces(
 ): FontFaceDescriptor[] {
   return sources.map((entry) => {
     const format = inferFontFormat(entry.path);
-    const basename = entry.path.split('/').pop() ?? entry.path;
+    const filename = entry.hashedBasename ?? entry.path.split('/').pop() ?? entry.path;
     return {
       family,
-      src: `url('${urlPrefix}/${basename}') format('${format}')`,
+      src: `url('${urlPrefix}/${filename}') format('${format}')`,
       weight: entry.weight,
       style: entry.style,
       display,
@@ -173,7 +173,7 @@ export function processLocalFont(config: LocalFontConfig, importerPath: string):
  *
  * Returns null if the call cannot be statically analyzed.
  *
- * Uses acorn AST parsing for robust handling of comments, trailing commas,
+ * Uses OXC (via vite.parseAst) AST parsing for robust handling of comments, trailing commas,
  * and multi-line configs.
  */
 export function extractLocalFontConfig(callSource: string): LocalFontConfig | null {

package/src/fonts/pipeline.ts

@@ -0,0 +1,337 @@
+/**
+ * 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, extname } 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 { 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>();
+
+  /** When true, local font sources are content-hashed at registration time. */
+  private readonly _hashOnRegister: boolean;
+
+  constructor(opts?: { hashOnRegister?: boolean }) {
+    this._hashOnRegister = opts?.hashOnRegister ?? false;
+  }
+
+  /**
+   * 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);
+        const hash = contentHash(data);
+        const basename = src.path.split('/').pop() ?? src.path;
+        const ext = extname(basename);
+        const stem = ext ? basename.slice(0, -ext.length) : basename;
+        src.hashedBasename = `${stem}-${hash}${ext}`;
+      }
+    }
+    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 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);
+    }
+  }
+}