@timber-js/app 0.2.0-alpha.13 → 0.2.0-alpha.131

package/dist/fonts/bundle.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 type { BuildManifest } from '../server/build-manifest.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';
+type EmitFile = (asset: EmittedAsset) => string;
+type EmitWarning = (msg: string) => void;
+/** Group cached Google Font binaries by lowercase family name. */
+export declare function groupCachedFontsByFamily(cachedFonts: readonly CachedFont[]): Map<string, CachedFont[]>;
+/**
+ * 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 declare function emitFontAssets(pipeline: FontPipeline, emitFile: EmitFile, warn: EmitWarning): void;
+/**
+ * Populate `buildManifest.fonts` with `ManifestFontEntry[]` keyed by the
+ * importer module path (relative to the project root, matching how Vite's
+ * `manifest.json` keys css/js).
+ *
+ * Google fonts use the content-hashed filenames produced during
+ * `buildStart`. Local fonts use the source basename.
+ */
+export declare function writeFontManifest(pipeline: FontPipeline, buildManifest: BuildManifest, rootDir: string): void;
+export {};
+//# sourceMappingURL=bundle.d.ts.map

package/dist/fonts/bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../src/fonts/bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAqB,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEpF;;;;GAIG;AACH,UAAU,YAAY;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,UAAU,CAAC;CAC7B;AACD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,KAAK,QAAQ,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,CAAC;AAChD,KAAK,WAAW,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;AAEzC,kEAAkE;AAClE,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,SAAS,UAAU,EAAE,GACjC,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAS3B;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,YAAY,EACtB,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,WAAW,GAChB,IAAI,CA4BN;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,YAAY,EACtB,aAAa,EAAE,aAAa,EAC5B,OAAO,EAAE,MAAM,GACd,IAAI,CAwCN"}

package/dist/fonts/dev-middleware.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 type { FontPipeline } from './pipeline.js';
+/**
+ * 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 declare function installFontDevMiddleware(server: ViteDevServer, pipeline: FontPipeline): void;
+//# sourceMappingURL=dev-middleware.d.ts.map

package/dist/fonts/dev-middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-middleware.d.ts","sourceRoot":"","sources":["../../src/fonts/dev-middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAG1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAUlD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAyC5F"}

package/dist/fonts/local.d.ts

@@ -71,7 +71,7 @@ export declare function processLocalFont(config: LocalFontConfig, importerPath:
  *
  * 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 declare function extractLocalFontConfig(callSource: string): LocalFontConfig | null;

package/dist/fonts/pipeline.d.ts

@@ -0,0 +1,167 @@
+/**
+ * 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 { 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 declare 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;
+    /**
+     * 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: VirtualFontCssIdMap;
+    /** Number of registered fonts. */
+    size(): number;
+    /** Iterate every entry as a `FontEntry` (with `faces` / `cachedFiles`). */
+    entries(): IterableIterator<FontEntry>;
+    /** Iterate every entry typed as the narrower `ExtractedFont` shape. */
+    fonts(): IterableIterator<ExtractedFont>;
+    /** Iterate every Google-provider entry. */
+    googleFonts(): IterableIterator<FontEntry>;
+    /** Lookup an entry by font ID. */
+    getEntry(id: string): FontEntry | undefined;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /** Attach pre-resolved `@font-face` descriptors to a font entry. */
+    attachFaces(fontId: string, faces: FontFaceDescriptor[]): void;
+    /** Attach downloaded Google Font binaries to a font entry. */
+    attachCachedFiles(fontId: string, files: CachedFont[]): void;
+    /**
+     * 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;
+    /** Drop every registered font. Used by tests and rebuild flows. */
+    clear(): void;
+    /**
+     * 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>;
+    /**
+     * 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;
+    /**
+     * 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;
+}
+/**
+ * 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 declare function pruneRegistryEntries(registry: FontRegistry, importer: string, family: string): void;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/fonts/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/fonts/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAI9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAEtD,qBAAa,YAAY;IACvB;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgC;IAEzD;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,sBAA6B;IAI9C,kCAAkC;IAClC,IAAI,IAAI,MAAM;IAId,2EAA2E;IAC3E,OAAO,IAAI,gBAAgB,CAAC,SAAS,CAAC;IAItC,uEAAuE;IACvE,KAAK,IAAI,gBAAgB,CAAC,aAAa,CAAC;IAIxC,2CAA2C;IAC1C,WAAW,IAAI,gBAAgB,CAAC,SAAS,CAAC;IAM3C,kCAAkC;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAI3C;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAKjC;;;;;OAKG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAOvC;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,EAAE,aAAa,GAAG,IAAI;IAOxC,oEAAoE;IACpE,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,EAAE,GAAG,IAAI;IAW9D,8DAA8D;IAC9D,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,IAAI;IAW5D;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAShD,mEAAmE;IACnE,KAAK,IAAI,IAAI;IAOb;;;;;OAKG;IACF,iBAAiB,IAAI,gBAAgB,CAAC,UAAU,CAAC;IAYlD;;;;;;;OAOG;IACH,MAAM,IAAI,MAAM;IAQhB;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;CAQ3C;AAoCD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,YAAY,EACtB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,IAAI,CAON"}

package/dist/fonts/transform.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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 { GoogleFontConfig } from './types.js';
+import type { FontPipeline } from './pipeline.js';
+/**
+ * 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 declare function generateFontId(family: string, config: GoogleFontConfig): string;
+/**
+ * Extract static font config from a font function call source.
+ *
+ * Returns `null` if the call cannot be statically analysed.
+ */
+export declare function extractFontConfig(callSource: string): GoogleFontConfig | null;
+/**
+ * Detect dynamic/computed font function calls that cannot be statically
+ * analysed. Returns the offending expression text, or `null` if all calls
+ * are static.
+ */
+export declare function detectDynamicFontCall(source: string, importedNames: string[]): string | null;
+/**
+ * Parse the local names imported from `@timber/fonts/google` /
+ * `next/font/google`. e.g. `import { Inter, JetBrains_Mono as Mono }` →
+ * `['Inter', 'Mono']`.
+ */
+export declare function parseGoogleFontImports(source: string): string[];
+/**
+ * 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 declare function parseGoogleFontFamilies(source: string): Map<string, string>;
+/**
+ * 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 declare function parseLocalFontImportName(source: string): string | null;
+/** 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.
+ */
+export declare function runFontsTransform(code: string, id: string, pipeline: FontPipeline, emitError: EmitError): {
+    code: string;
+    map: ReturnType<MagicString['generateMap']>;
+} | null;
+export {};
+//# sourceMappingURL=transform.d.ts.map

package/dist/fonts/transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../src/fonts/transform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,WAAW,MAAM,cAAc,CAAC;AACvC,OAAO,KAAK,EAAiB,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAUlE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAsBlD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAM/E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAE7E;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAE5F;AAOD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAI/D;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAU3E;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKtE;AASD,wDAAwD;AACxD,KAAK,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,KAAK,CAAC;AA4BxC;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,SAAS,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,UAAU,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC,CAAA;CAAE,GAAG,IAAI,CAsItE"}

package/dist/fonts/types.d.ts

@@ -6,6 +6,7 @@
  *
  * Design doc: 24-fonts.md
  */
+import type { CachedFont } from './google.js';
 /** Configuration passed to a Google font function (e.g. `Inter({ ... })`). */
 export interface GoogleFontConfig {
     weight?: string | string[];
@@ -44,7 +45,16 @@ export interface FontResult {
     /** CSS custom property name when `variable` is specified (e.g. `--font-sans`). */
     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;
@@ -82,4 +92,38 @@ 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[];
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/fonts/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/fonts/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,GAAG,YAAY,EAAE,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,EAAE,EAAE,MAAM,CAAC;IACX,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC7B,+CAA+C;IAC/C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,oDAAoD;IACpD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,YAAY,CAAC,EAAE,YAAY,EAAE,CAAC;IAC9B,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/fonts/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,GAAG,YAAY,EAAE,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,EAAE,EAAE,MAAM,CAAC;IACX,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC7B,+CAA+C;IAC/C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,oDAAoD;IACpD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,YAAY,CAAC,EAAE,YAAY,EAAE,CAAC;IAC9B,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,SAAU,SAAQ,aAAa;IAC9C;;;;;OAKG;IACH,KAAK,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAE7B;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;CAC5B"}

package/dist/fonts/virtual-modules.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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 type { ExtractedFont, FontFaceDescriptor } from './types.js';
+export declare const VIRTUAL_GOOGLE = "@timber/fonts/google";
+export declare const VIRTUAL_LOCAL = "@timber/fonts/local";
+export declare const RESOLVED_GOOGLE = "\0@timber/fonts/google";
+export declare 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 declare const VIRTUAL_FONT_CSS_PREFIX = "virtual:timber-font-css/";
+export declare const VIRTUAL_FONT_CSS_SUFFIX = ".css";
+export declare const RESOLVED_FONT_CSS_PREFIX: string;
+export declare class VirtualFontCssIdMap {
+    private readonly map;
+    /**
+     * 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;
+    /** Decode the importer from a resolved (or unresolved) virtual css id. */
+    importerFor(id: string): string | undefined;
+    /** True if `id` is any form of the virtual font css module. */
+    matches(id: string): boolean;
+    /** Drop every registered mapping. Used by tests. */
+    clear(): void;
+}
+/**
+ * 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 declare function generateGoogleVirtualModule(fonts: Iterable<ExtractedFont>): string;
+/**
+ * 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 declare function generateLocalVirtualModule(): string;
+/**
+ * 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 declare function generateFontCss(font: ExtractedFont, googleFaces?: FontFaceDescriptor[]): string;
+/**
+ * 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 declare function generateAllFontCss(registry: Map<string, ExtractedFont>, googleFontFacesMap?: Map<string, FontFaceDescriptor[]>): string;
+//# sourceMappingURL=virtual-modules.d.ts.map

package/dist/fonts/virtual-modules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-modules.d.ts","sourceRoot":"","sources":["../../src/fonts/virtual-modules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAKpE,eAAO,MAAM,cAAc,yBAAyB,CAAC;AACrD,eAAO,MAAM,aAAa,wBAAwB,CAAC;AACnD,eAAO,MAAM,eAAe,2BAA2B,CAAC;AACxD,eAAO,MAAM,cAAc,0BAA0B,CAAC;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,6BAA6B,CAAC;AAClE,eAAO,MAAM,uBAAuB,SAAS,CAAC;AAC9C,eAAO,MAAM,wBAAwB,QAAiC,CAAC;AAiBvE,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA6B;IAEjD;;;;OAIG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAM/B,0EAA0E;IAC1E,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAW3C,+DAA+D;IAC/D,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAK5B,oDAAoD;IACpD,KAAK,IAAI,IAAI;CAGd;AAUD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,MAAM,CAoClF;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,CAanD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,EAAE,WAAW,CAAC,EAAE,kBAAkB,EAAE,GAAG,MAAM,CAwB/F;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,EACpC,kBAAkB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,EAAE,CAAC,GACrD,MAAM,CAOR"}