@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/dist/dev-tools/terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../../src/dev-tools/terminal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAIL,KAAK,UAAU,EAChB,MAAM,cAAc,CAAC;AAyEtB;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAkEhG"}

package/dist/fonts/ast-walk.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Generic AST node types and recursive walkers for font static analysis.
+ *
+ * `ast.ts` owns parsing, config extraction, and call-site discovery; this
+ * module owns the recursive walks that police where font bindings may be
+ * used (dynamic configs, nested scopes, unconsumed references). Split out
+ * to keep `ast.ts` under the 500-code-line limit (design/18-build-system.md).
+ *
+ * Design doc: 24-fonts.md §"Step 1: Static Analysis"
+ */
+export interface AstNode {
+    type: string;
+    [key: string]: unknown;
+}
+export interface IdentifierNode extends AstNode {
+    type: 'Identifier';
+    name: string;
+}
+export interface PositionedNode extends AstNode {
+    start: number;
+    end: number;
+}
+/** A flagged reference/usage for build-error reporting. */
+export interface FlaggedUsage {
+    name: string;
+    line: number;
+    column: number;
+}
+/** Convert a 0-based byte offset into a 1-based line and 0-based column. */
+export declare function offsetToLineColumn(source: string, offset: number): {
+    line: number;
+    column: number;
+};
+/**
+ * Invoke `visit` on every direct child AST node of `node` (array elements
+ * and object-valued properties with a `type` field).
+ */
+export declare function walkChildNodes(node: AstNode, visit: (child: AstNode) => void): void;
+/**
+ * Recursively walk the AST looking for CallExpression nodes where
+ * the callee is one of the imported font names and the first argument
+ * is not an ObjectExpression (i.e. it's dynamic).
+ */
+export declare function walkForDynamicCalls(node: AstNode, names: ReadonlySet<string>, source: string): string | null;
+/**
+ * Recursively walk an AST node looking for font CallExpressions in nested
+ * scopes (function bodies, if-blocks, loops, etc.). Font calls must be
+ * module-level; nested calls are collected as errors.
+ *
+ * `isNested` tracks whether we've descended past the top-level statement.
+ * Top-level VariableDeclarations and ExpressionStatements are already
+ * handled by the main loop in `findFontCallSites`, so we only flag calls
+ * found deeper.
+ */
+export declare function walkForNestedFontCalls(node: AstNode, bindingNames: ReadonlyMap<string, unknown>, source: string, out: FlaggedUsage[], isNested: boolean): void;
+/**
+ * Recursively walk an AST node looking for references to font bindings
+ * that were not consumed by a recognized call site.
+ *
+ * Skips:
+ * - recognized CallExpressions (the transform rewrites them wholesale)
+ * - TS type-position nodes (erased at runtime)
+ * - non-computed member properties (`obj.Inter` doesn't reference the binding)
+ * - non-computed object keys (`{ Inter: 1 }` doesn't reference the binding)
+ * - export aliases (`export { inter as Inter }` — only `local` is a reference)
+ */
+export declare function walkForUnconsumedReferences(node: AstNode, bindingNames: ReadonlyMap<string, unknown>, consumedCallStarts: ReadonlySet<number>, source: string, out: FlaggedUsage[]): void;
+//# sourceMappingURL=ast-walk.d.ts.map

package/dist/fonts/ast-walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-walk.d.ts","sourceRoot":"","sources":["../../src/fonts/ast-walk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,cAAe,SAAQ,OAAO;IAC7C,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAe,SAAQ,OAAO;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAUlC;AAID;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAcnF;AAID;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,EAC1B,MAAM,EAAE,MAAM,GACb,MAAM,GAAG,IAAI,CAuBf;AAwBD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,OAAO,EACb,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1C,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,YAAY,EAAE,EACnB,QAAQ,EAAE,OAAO,GAChB,IAAI,CAoBN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,OAAO,EACb,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1C,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAC,EACvC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,YAAY,EAAE,GAClB,IAAI,CA8CN"}

package/dist/fonts/ast.d.ts

@@ -1,15 +1,24 @@
 /**
- * Acorn-based AST utilities for extracting static font configs from source code.
+ * AST utilities for extracting static font configs from source code.
+ * Uses OXC via Vite's `parseAst` — handles JS/JSX/TS/TSX natively.
  *
- * Replaces the fragile regex-based extraction in fonts.ts and local.ts.
- * Uses acorn (already a Vite dependency) for robust parsing that handles
- * comments, trailing commas, multi-line configs, and other edge cases
- * the regex approach missed.
+ * Provides two tiers of API:
+ *
+ * 1. **Source-text helpers** (`extractFontConfigAst`, `extractLocalFontConfigAst`,
+ *    `detectDynamicFontCallAst`) — parse a snippet and return extracted config.
+ *    Still used by tests and callers that have only a string.
+ *
+ * 2. **AST-node helpers** (`extractGoogleFontConfigFromNode`,
+ *    `extractLocalFontConfigFromNode`, `findFontCallSites`) — operate on
+ *    nodes from an already-parsed Program so the transform hook can share
+ *    one parse with all analysis steps.
  *
  * Design doc: 24-fonts.md §"Step 1: Static Analysis"
  */
-import type { GoogleFontConfig } from './types.js';
-import type { LocalFontConfig } from './types.js';
+import type { GoogleFontConfig } from './types.ts';
+import type { LocalFontConfig } from './types.ts';
+import type { AstNode, FlaggedUsage } from './ast-walk.ts';
+export type { FlaggedUsage } from './ast-walk.ts';
 /**
  * Extract a GoogleFontConfig from the source text of a font function call's
  * object argument.
@@ -31,8 +40,103 @@ export declare function extractLocalFontConfigAst(callSource: string): LocalFont
  * Detect if source code contains dynamic/computed font function calls
  * that cannot be statically analyzed.
  *
- * Uses acorn to parse the full source and inspect CallExpression nodes.
+ * Uses OXC (via vite.parseAst) to parse the full source and inspect CallExpression nodes.
  * Returns the offending expression string if found, null if all calls are static.
  */
 export declare function detectDynamicFontCallAst(source: string, importedNames: string[]): string | null;
+/**
+ * Extract a GoogleFontConfig from an ObjectExpression AST node.
+ *
+ * This is the node-level equivalent of `extractFontConfigAst` — it skips
+ * the parse step because the caller already has a parsed Program.
+ */
+export declare function extractGoogleFontConfigFromNode(node: AstNode): GoogleFontConfig | null;
+/**
+ * Extract a LocalFontConfig from an ObjectExpression AST node.
+ */
+export declare function extractLocalFontConfigFromNode(node: AstNode): LocalFontConfig | null;
+/** A font import binding discovered from an ImportDeclaration. */
+export interface FontBinding {
+    /** The local name used in the module (after `as`, if present). */
+    localName: string;
+    /**
+     * The original exported name (before `as`). For Google fonts this is
+     * the PascalCase_With_Underscores name that maps to the family. For
+     * local fonts (`default` import), this is `'default'`.
+     */
+    importedName: string;
+    /** `'google'` or `'local'`. */
+    provider: 'google' | 'local';
+    /** The AST node of the ImportDeclaration (for removal via magic-string). */
+    importNode: AstNode & {
+        start: number;
+        end: number;
+    };
+}
+/** A font function call site discovered from a CallExpression. */
+export interface FontCallSite {
+    /** The binding that this call references. */
+    binding: FontBinding;
+    /**
+     * The variable name this call is assigned to, if the call appears in a
+     * VariableDeclarator. `null` for bare expression statements.
+     */
+    assignedName: string | null;
+    /** The first argument AST node (expected to be an ObjectExpression). */
+    configNode: AstNode;
+    /**
+     * The outermost AST node to replace. For a VariableDeclaration with a
+     * single declarator this is the full declaration; for a bare expression
+     * statement it is the ExpressionStatement. The transform replaces
+     * `source[replaceStart..replaceEnd]`.
+     */
+    replaceStart: number;
+    replaceEnd: number;
+    /** Line number (1-based) of the call for error messages. */
+    line: number;
+    /** Column (0-based) of the call for error messages. */
+    column: number;
+}
+/** Result of `findFontCallSites` — everything the transform needs. */
+export interface FontAnalysis {
+    bindings: FontBinding[];
+    callSites: FontCallSite[];
+    /**
+     * Import nodes that should be removed (deduplicated). Only imports that
+     * produced at least one font binding are listed — removing an import
+     * whose bindings the transform doesn't rewrite (e.g. a namespace
+     * import) would leave dangling references behind.
+     */
+    importNodesToRemove: Array<{
+        start: number;
+        end: number;
+    }>;
+    /** First dynamic call expression text, or `null`. */
+    dynamicCall: string | null;
+    /**
+     * Font calls found in nested scopes (functions, if-blocks, etc.).
+     * These are errors — font calls must be module-level.
+     */
+    nestedCalls: FlaggedUsage[];
+    /**
+     * Namespace imports of font modules (`import * as fonts from ...`).
+     * These are errors — the transform cannot rewrite `fonts.Inter(...)`
+     * member calls, so the fonts would silently never load.
+     */
+    namespaceImports: FlaggedUsage[];
+    /**
+     * References to font bindings that were not consumed by a recognized
+     * call site (`export default Inter({...})`, object-literal nesting,
+     * member access on the call result, aliasing, re-exports). These are
+     * errors — the import is removed, so any leftover reference would be a
+     * silent runtime ReferenceError.
+     */
+    unsupportedUsages: FlaggedUsage[];
+}
+/**
+ * Parse a full source file and find all font imports and call sites.
+ *
+ * Returns `null` if the source has no font-related imports.
+ */
+export declare function findFontCallSites(source: string): FontAnalysis | null;
 //# sourceMappingURL=ast.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../../src/fonts/ast.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,YAAY,CAAC;AA0HhE;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CA4DhF;AAiCD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CA4CpF;AAID;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAiB/F"}
+{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../../src/fonts/ast.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EAAE,OAAO,EAAkC,YAAY,EAAE,MAAM,eAAe,CAAC;AAQ3F,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AA+GlD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAIhF;AAiCD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAIpF;AAID;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAa/F;AAQD;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,OAAO,GAAG,gBAAgB,GAAG,IAAI,CAGtF;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAGpF;AA8GD,kEAAkE;AAClE,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC7B,4EAA4E;IAC5E,UAAU,EAAE,OAAO,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CACtD;AAED,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,6CAA6C;IAC7C,OAAO,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,wEAAwE;IACxE,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B;;;;;OAKG;IACH,mBAAmB,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3D,qDAAqD;IACrD,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;;OAGG;IACH,WAAW,EAAE,YAAY,EAAE,CAAC;IAC5B;;;;OAIG;IACH,gBAAgB,EAAE,YAAY,EAAE,CAAC;IACjC;;;;;;OAMG;IACH,iBAAiB,EAAE,YAAY,EAAE,CAAC;CACnC;AA6ED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CA8KrE"}

package/dist/fonts/bundle.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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.ts';
+/**
+ * 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.ts';
+import type { CachedFont } from './google.ts';
+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
+ * 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.
+ * Hrefs are prefixed with Vite's resolved `base` so they match the URLs
+ * the platform serves the emitted binaries under.
+ */
+export declare function writeFontManifest(pipeline: FontPipeline, buildManifest: BuildManifest, base?: 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;AAGpF;;;;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;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,YAAY,EACtB,aAAa,EAAE,aAAa,EAC5B,IAAI,SAAM,GACT,IAAI,CAiCN"}

package/dist/fonts/css.d.ts

@@ -6,7 +6,7 @@
  *
  * Design doc: 24-fonts.md §"Step 3: @font-face Generation"
  */
-import type { FontFaceDescriptor } from './types.js';
+import type { FontFaceDescriptor } from './types.ts';
 /**
  * Generate a single `@font-face` CSS rule from a descriptor.
  */

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.ts';
+/**
+ * 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, base?: string): 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;AAWlD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,YAAY,EACtB,IAAI,SAAM,GACT,IAAI,CA+CN"}

package/dist/fonts/fallbacks.d.ts

@@ -7,14 +7,7 @@
  *
  * Design doc: 24-fonts.md §"Step 4: Size-Adjusted Fallbacks"
  */
-import type { FontFaceDescriptor } from './types.js';
 export declare function getGenericFamily(family: string): string;
-/**
- * Generate a size-adjusted fallback @font-face for a given font family.
- *
- * Returns null if no metrics are available (unknown font — no fallback generated).
- */
-export declare function generateFallbackFontFace(family: string): FontFaceDescriptor | null;
 /**
  * Generate the full CSS for a size-adjusted fallback font.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"fallbacks.d.ts","sourceRoot":"","sources":["../../src/fonts/fallbacks.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAwJrD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOvD;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAclF;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkBjE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAgBrD"}
+{"version":3,"file":"fallbacks.d.ts","sourceRoot":"","sources":["../../src/fonts/fallbacks.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAwJH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOvD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkBjE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAgBrD"}

package/dist/fonts/google.d.ts

@@ -14,7 +14,7 @@
  *
  * Design doc: 24-fonts.md §"Step 2: Font Download & Subsetting"
  */
-import type { ExtractedFont, FontFaceDescriptor } from './types.js';
+import type { ExtractedFont, FontFaceDescriptor } from './types.ts';
 /** A parsed @font-face block from the Google Fonts CSS response. */
 export interface GoogleFontFace {
     family: string;
@@ -101,9 +101,11 @@ export declare function downloadAndCacheFonts(fonts: ExtractedFont[], projectRoo
  * Generate @font-face descriptors for cached (production) Google Fonts.
  *
  * Each CachedFont gets a FontFaceDescriptor pointing to the
- * content-hashed URL under `/_timber/fonts/`.
+ * content-hashed URL under `<base>_timber/fonts/`. The `urlPrefix` comes
+ * from `fontUrlPrefix(viteBase)` so apps deployed under a non-root base
+ * resolve fonts correctly.
  */
-export declare function generateProductionFontFaces(cachedFonts: CachedFont[], display: string): FontFaceDescriptor[];
+export declare function generateProductionFontFaces(cachedFonts: CachedFont[], display: string, urlPrefix?: string): FontFaceDescriptor[];
 /**
  * Generate @font-face descriptors for dev mode (CDN-pointing).
  *

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

@@ -1 +1 @@
-{"version":3,"file":"google.d.ts","sourceRoot":"","sources":["../../src/fonts/google.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAepE,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,iEAAiE;AACjE,MAAM,WAAW,UAAU;IACzB,qCAAqC;IACrC,IAAI,EAAE,cAAc,CAAC;IACrB,4EAA4E;IAC5E,cAAc,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAiC/D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAahF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,EAAE,CA8BjE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,cAAc,EAAE,CAI5F;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAI7E;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAGrD;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAMnE;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,aAAa,EAAE,EACtB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,UAAU,EAAE,CAAC,CAwCvB;AAeD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,UAAU,EAAE,EACzB,OAAO,EAAE,MAAM,GACd,kBAAkB,EAAE,CAStB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE,MAAM,GACd,kBAAkB,EAAE,CAStB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAK5F"}
+{"version":3,"file":"google.d.ts","sourceRoot":"","sources":["../../src/fonts/google.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AA4DpE,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,iEAAiE;AACjE,MAAM,WAAW,UAAU;IACzB,qCAAqC;IACrC,IAAI,EAAE,cAAc,CAAC;IACrB,4EAA4E;IAC5E,cAAc,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAiC/D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CA2BhF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,EAAE,CA8BjE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,cAAc,EAAE,CAI5F;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAI7E;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAGrD;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBnE;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,aAAa,EAAE,EACtB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,UAAU,EAAE,CAAC,CA+CvB;AAeD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,UAAU,EAAE,EACzB,OAAO,EAAE,MAAM,EACf,SAAS,SAAkB,GAC1B,kBAAkB,EAAE,CAStB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE,MAAM,GACd,kBAAkB,EAAE,CAStB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAK5F"}

package/dist/fonts/local.d.ts

@@ -12,7 +12,7 @@
  *
  * Design doc: 24-fonts.md §"Local Fonts"
  */
-import type { LocalFontConfig, LocalFontSrc, FontFaceDescriptor, ExtractedFont } from './types.js';
+import type { LocalFontConfig, LocalFontSrc, FontFaceDescriptor, ExtractedFont } from './types.ts';
 /**
  * Infer the font format from a file extension.
  *
@@ -45,9 +45,9 @@ export declare function generateFamilyName(sources: LocalFontSrc[]): string;
  * Generate @font-face descriptors for local font sources.
  *
  * Each source entry produces one @font-face rule. The `src` descriptor
- * uses a `url()` pointing to the served path under `/_timber/fonts/`.
- * The `urlPrefix` defaults to `/_timber/fonts` — the path used by both
- * the dev server middleware and the production build output.
+ * uses a `url()` pointing to the served path under `<base>_timber/fonts/`.
+ * The `urlPrefix` defaults to `fontUrlPrefix()` (root base) — pass
+ * `fontUrlPrefix(viteBase)` so non-root deployments resolve correctly.
  */
 export declare function generateLocalFontFaces(family: string, sources: LocalFontSrc[], display: string, urlPrefix?: string): FontFaceDescriptor[];
 /**
@@ -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/local.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/fonts/local.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAInG;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAgBxD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,EAAE,GAAG,YAAY,EAAE,CASzE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,YAAY,EAAE,GACtB,YAAY,EAAE,CAMhB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAYlE;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,MAAM,EACf,SAAS,SAAmB,GAC3B,kBAAkB,EAAE,CAYtB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,GAAG,aAAa,CAyB7F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAEjF"}
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/fonts/local.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAKnG;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAgBxD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,EAAE,GAAG,YAAY,EAAE,CASzE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,YAAY,EAAE,GACtB,YAAY,EAAE,CAMhB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAYlE;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,MAAM,EACf,SAAS,SAAkB,GAC1B,kBAAkB,EAAE,CAYtB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,GAAG,aAAa,CAyB7F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAEjF"}

package/dist/fonts/paths.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared path/URL helpers for the timber-fonts pipeline.
+ *
+ * Two concerns live here:
+ *
+ * - `fontUrlPrefix` — the public URL prefix for font binaries, derived
+ *   from Vite's resolved `base`. Every URL the pipeline emits (@font-face
+ *   src, manifest hrefs, dev middleware matching) must go through this so
+ *   apps deployed under a non-root base (`base: '/my-app/'`) resolve
+ *   fonts correctly. Emitted *file* locations are not base-prefixed —
+ *   only URLs are.
+ *
+ * - `fontOutputBasename` / `hashedFontBasename` — basename derivation for
+ *   local font sources. Paths are absolutized with `resolve()`, which
+ *   produces backslash separators on Windows, so `split('/').pop()` is
+ *   not safe. `path.win32.basename` handles both separators.
+ *
+ * Design doc: 24-fonts.md
+ */
+/** Directory (relative to the build output / URL root) holding font binaries. */
+export declare const FONT_OUTPUT_DIR = "_timber/fonts";
+/**
+ * Build the URL prefix for font binaries from Vite's resolved `base`.
+ *
+ * `fontUrlPrefix('/')` → `/_timber/fonts`
+ * `fontUrlPrefix('/my-app/')` → `/my-app/_timber/fonts`
+ */
+export declare function fontUrlPrefix(base?: string): string;
+/**
+ * Derive the output basename for a local font source path.
+ *
+ * Uses `path.win32.basename` because it splits on both `/` and `\`,
+ * handling absolute paths produced by `resolve()` on any platform.
+ */
+export declare function fontOutputBasename(srcPath: string): string;
+/**
+ * Derive the content-hashed output basename for a local font source.
+ *
+ * `hashedFontBasename('C:\\fonts\\MyFont-Bold.woff2', 'a1b2c3d4')`
+ * → `MyFont-Bold-a1b2c3d4.woff2`
+ */
+export declare function hashedFontBasename(srcPath: string, hash: string): string;
+//# sourceMappingURL=paths.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/fonts/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,iFAAiF;AACjF,eAAO,MAAM,eAAe,kBAAkB,CAAC;AAE/C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,SAAM,GAAG,MAAM,CAGhD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKxE"}

package/dist/fonts/pipeline.d.ts

@@ -0,0 +1,177 @@
+/**
+ * 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.ts';
+import type { CachedFont } from './google.ts';
+import { VirtualFontCssIdMap } from './virtual-modules.ts';
+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;
+    /** When true, local font sources are content-hashed at registration time. */
+    private readonly _hashOnRegister;
+    /**
+     * Vite's resolved `base`. Set from the plugin's `configResolved` hook so
+     * every @font-face URL the pipeline renders carries the prefix.
+     */
+    private _base;
+    constructor(opts?: {
+        hashOnRegister?: boolean;
+    });
+    /** Set Vite's resolved `base` (from `configResolved`). */
+    setBase(base: string): void;
+    /**
+     * 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;
+    /** True if at least one entry is registered under `importer`. */
+    hasImporter(importer: string): boolean;
+    /**
+     * Drop **every** registry entry that originated from `importer`,
+     * regardless of family.
+     *
+     * Called at the start of the transform hook before re-registering the
+     * current extraction set. This handles the cases `pruneFor` misses:
+     *
+     * - **Family rename** (Inter → Roboto): the old family's entries are
+     *   cleared because we prune by importer, not by (importer, family).
+     * - **Font call deleted**: the old entries are cleared even though no
+     *   new call provides a family to prune against.
+     *
+     * Other importers' fonts are untouched.
+     *
+     * See TIM-1087.
+     */
+    pruneImporter(importer: 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;
+}
+//# 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;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAM9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,qBAAa,YAAY;IACvB;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgC;IAEzD,6EAA6E;IAC7E,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;IAE1C;;;OAGG;IACH,OAAO,CAAC,KAAK,CAAO;IAEpB,YAAY,IAAI,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,OAAO,CAAA;KAAE,EAE9C;IAED,0DAA0D;IAC1D,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE1B;IAED;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,sBAA6B;IAI9C,kCAAkC;IAClC,IAAI,IAAI,MAAM,CAEb;IAED,2EAA2E;IAC3E,OAAO,IAAI,gBAAgB,CAAC,SAAS,CAAC,CAErC;IAED,uEAAuE;IACvE,KAAK,IAAI,gBAAgB,CAAC,aAAa,CAAC,CAEvC;IAED,2CAA2C;IAC1C,WAAW,IAAI,gBAAgB,CAAC,SAAS,CAAC,CAI1C;IAED,kCAAkC;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAE1C;IAED;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAGhC;IAED;;;;;OAKG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAGtC;IAID;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,EAAE,aAAa,GAAG,IAAI,CAcvC;IAED,oEAAoE;IACpE,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,EAAE,GAAG,IAAI,CAS7D;IAED,8DAA8D;IAC9D,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,IAAI,CAS3D;IAED;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAO/C;IAED,iEAAiE;IACjE,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAKrC;IAED;;;;;;;;;;;;;;;OAeG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAMpC;IAED,mEAAmE;IACnE,KAAK,IAAI,IAAI,CAGZ;IAID;;;;;OAKG;IACF,iBAAiB,IAAI,gBAAgB,CAAC,UAAU,CAAC,CAUjD;IAED;;;;;;;OAOG;IACH,MAAM,IAAI,MAAM,CAOf;IAED;;;;;;;;;;;;;;;OAeG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQzC;CACF"}