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

package/dist/index.js

@@ -938,6 +938,15 @@ var CSS = `
 `;
 //#endregion
 //#region src/config-validation.ts
+/**
+* Config validation — validates timber.config.ts at startup.
+*
+* Runs in the plugin's configResolved hook (once, at startup/build).
+* Each check produces a clear error message with the invalid value,
+* what's expected, and how to fix it.
+*
+* Design doc: 18-build-system.md
+*/
 var config_validation_exports = /* @__PURE__ */ __exportAll({
 	addVirtualModuleContext: () => addVirtualModuleContext,
 	checkPeerDependencies: () => checkPeerDependencies,
@@ -1096,9 +1105,9 @@ function addVirtualModuleContext(errorMessage) {
 */
 function checkPeerDependencies(projectRoot) {
 	const results = [];
+	const userRequire = createRequire(`${projectRoot}/package.json`);
 	for (const name of REQUIRED_PEERS) try {
-		const { createRequire } = __require("node:module");
-		createRequire(`${projectRoot}/package.json`).resolve(name);
+		userRequire.resolve(name);
 		results.push({
 			name,
 			status: "ok"
@@ -1612,6 +1621,25 @@ function stripRootPrefix(id, root) {
 *
 * Serializes output mode and feature flags for runtime consumption.
 */
+/**
+* Extract the JSON-serializable subset of `forms` config.
+*
+* Drops function-valued `stripSensitiveFields` with a build-time warning —
+* functions cannot cross the JSON boundary to the runtime, so users must
+* configure function predicates per-action via `createActionClient` instead.
+*/
+function serializeFormsConfig(forms) {
+	if (!forms) return void 0;
+	const opt = forms.stripSensitiveFields;
+	if (opt === void 0) return {};
+	if (typeof opt === "boolean") return { stripSensitiveFields: opt };
+	if (Array.isArray(opt)) return { stripSensitiveFields: opt.filter((v) => typeof v === "string") };
+	if (typeof opt === "function") {
+		console.warn("[timber] forms.stripSensitiveFields was set to a function in timber.config.ts — this is not supported at the global level (functions cannot be serialized into the runtime config). Use a per-action override via `createActionClient({ stripSensitiveFields: (name) => ... })` instead. The built-in deny-list will be used globally.");
+		return {};
+	}
+	return {};
+}
 function generateConfigModule(ctx) {
 	const runtimeConfig = {
 		output: ctx.config.output ?? "server",
@@ -1626,6 +1654,7 @@ function generateConfigModule(ctx) {
 		serverTiming: ctx.config.serverTiming,
 		renderTimeoutMs: ctx.config.renderTimeoutMs ?? 3e4,
 		sitemap: ctx.config.sitemap,
+		forms: serializeFormsConfig(ctx.config.forms),
 		deploymentId: ctx.deploymentId ?? null
 	};
 	return [
@@ -13147,7 +13176,7 @@ function timberRouting(ctx) {
 		load(id) {
 			if (id !== RESOLVED_VIRTUAL_ID$1) return null;
 			if (!ctx.routeTree) rescan();
-			return generateManifestModule(ctx.routeTree);
+			return generateManifestModule(ctx.routeTree, ctx.root);
 		},
 		buildStart() {
 			if (ctx.dev) return;
@@ -13157,7 +13186,7 @@ function timberRouting(ctx) {
 			rescan();
 			devServer.watcher.add(ctx.appDir);
 			/** Snapshot of the last generated manifest, used to detect structural changes. */
-			let lastManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree) : "";
+			let lastManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree, ctx.root) : "";
 			/**
 			* Handle a route-significant file being added or removed.
 			* Always triggers a full-reload since the route tree structure changed.
@@ -13166,7 +13195,7 @@ function timberRouting(ctx) {
 				if (!filePath.startsWith(ctx.appDir)) return;
 				if (!ROUTE_FILE_PATTERNS.test(filePath)) return;
 				rescan();
-				lastManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree) : "";
+				lastManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree, ctx.root) : "";
 				invalidateManifest(devServer);
 			};
 			/**
@@ -13181,7 +13210,7 @@ function timberRouting(ctx) {
 				if (!filePath.startsWith(ctx.appDir)) return;
 				if (!ROUTE_FILE_PATTERNS.test(filePath)) return;
 				rescan();
-				const newManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree) : "";
+				const newManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree, ctx.root) : "";
 				if (newManifest !== lastManifest) {
 					lastManifest = newManifest;
 					invalidateManifest(devServer);
@@ -13214,7 +13243,7 @@ function invalidateManifest(server) {
 * The output is a default-exported object containing the serialized route tree.
 * All file references use absolute paths (required for virtual modules).
 */
-function generateManifestModule(tree) {
+function generateManifestModule(tree, viteRoot) {
 	const imports = [];
 	let importIndex = 0;
 	/**
@@ -13334,6 +13363,7 @@ function generateManifestModule(tree) {
 		...imports,
 		"",
 		"const manifest = {",
+		`  viteRoot: ${JSON.stringify(viteRoot)},`,
 		proxyLine,
 		globalErrorLine,
 		rewritesLine,
@@ -13497,6 +13527,240 @@ export const coerce = stub;
 	};
 }
 //#endregion
+//#region src/fonts/google.ts
+/**
+* Google Fonts download, caching, and dev CDN fallback.
+*
+* At build time (production only):
+* 1. Queries Google Fonts CSS API v2 for font metadata and file URLs
+* 2. Downloads woff2 font files
+* 3. Caches them in node_modules/.cache/timber-fonts/
+* 4. Content-hashes filenames for cache busting
+* 5. Emits font files into the build output via generateBundle
+*
+* In dev mode:
+* - Generates @font-face rules pointing to Google Fonts CDN
+* - No downloads, no caching
+*
+* Design doc: 24-fonts.md §"Step 2: Font Download & Subsetting"
+*/
+/** Google Fonts CSS API v2 base URL. */
+var GOOGLE_FONTS_API = "https://fonts.googleapis.com/css2";
+/**
+* User-Agent string that requests woff2 format from Google Fonts API.
+* Google serves different formats based on user-agent.
+*/
+var WOFF2_USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
+/** Default cache directory for downloaded font files. */
+var DEFAULT_CACHE_DIR = "node_modules/.cache/timber-fonts";
+/**
+* Build the Google Fonts CSS API v2 URL for a given font config.
+*
+* Example output:
+* https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap&subset=latin
+*/
+function buildGoogleFontsUrl(font) {
+	const family = font.family.replace(/\s+/g, "+");
+	const hasItalic = font.styles.includes("italic");
+	const weights = font.weights.map(Number).sort((a, b) => a - b);
+	let axisSpec;
+	if (hasItalic && weights.length > 0) {
+		const pairs = [];
+		for (const ital of [0, 1]) {
+			if (ital === 1 && !hasItalic) continue;
+			if (ital === 0 && font.styles.length === 1 && font.styles[0] === "italic") continue;
+			for (const w of weights) pairs.push(`${ital},${w}`);
+		}
+		axisSpec = `ital,wght@${pairs.join(";")}`;
+	} else if (weights.length > 0) axisSpec = `wght@${weights.join(";")}`;
+	else axisSpec = "";
+	const parts = [`family=${axisSpec ? `${family}:${axisSpec}` : family}`];
+	if (font.display) parts.push(`display=${font.display}`);
+	return `${GOOGLE_FONTS_API}?${parts.join("&")}`;
+}
+/**
+* Fetch the CSS from Google Fonts API and parse out @font-face blocks.
+*
+* The API returns CSS with subset comments like:
+* ```
+* /* latin * /
+* @font-face { ... }
+* ```
+*
+* We parse each block to extract the font URL, unicode-range, and subset label.
+*/
+async function fetchGoogleFontsCss(url) {
+	const response = await fetch(url, { headers: { "User-Agent": WOFF2_USER_AGENT } });
+	if (!response.ok) throw new Error(`Google Fonts API returned ${response.status}: ${response.statusText} for ${url}`);
+	return parseGoogleFontsCss(await response.text());
+}
+/**
+* Parse the CSS response from Google Fonts API into structured font face data.
+*
+* Handles the Google Fonts CSS format with subset comments and @font-face blocks.
+*/
+function parseGoogleFontsCss(css) {
+	const faces = [];
+	const blockPattern = /\/\*\s*([a-z0-9-]+)\s*\*\/\s*@font-face\s*\{([^}]+)\}/g;
+	let match;
+	while ((match = blockPattern.exec(css)) !== null) {
+		const subset = match[1];
+		const block = match[2];
+		const familyMatch = block.match(/font-family:\s*'([^']+)'/);
+		const weightMatch = block.match(/font-weight:\s*(\d+)/);
+		const styleMatch = block.match(/font-style:\s*(\w+)/);
+		const urlMatch = block.match(/url\(([^)]+)\)\s*format\('woff2'\)/);
+		const rangeMatch = block.match(/unicode-range:\s*([^;]+)/);
+		if (familyMatch && urlMatch) faces.push({
+			family: familyMatch[1],
+			weight: weightMatch?.[1] ?? "400",
+			style: styleMatch?.[1] ?? "normal",
+			url: urlMatch[1],
+			unicodeRange: rangeMatch?.[1]?.trim() ?? "",
+			subset
+		});
+	}
+	return faces;
+}
+/**
+* Filter parsed font faces to only the requested subsets.
+*/
+function filterBySubsets(faces, subsets) {
+	if (subsets.length === 0) return faces;
+	const subsetSet = new Set(subsets);
+	return faces.filter((f) => subsetSet.has(f.subset));
+}
+/**
+* Generate a content hash for font data.
+* Returns the first 8 hex chars of the SHA-256 hash.
+*/
+function contentHash(data) {
+	return createHash("sha256").update(data).digest("hex").slice(0, 8);
+}
+/**
+* Generate a content-hashed filename for a font face.
+*
+* Format: `<family>-<subset>-<weight>-<style>-<hash>.woff2`
+* Example: `inter-latin-400-normal-abc12345.woff2`
+*/
+function hashedFontFilename(face, data) {
+	const slug = face.family.toLowerCase().replace(/\s+/g, "-");
+	const hash = contentHash(data);
+	return `${slug}-${face.subset}-${face.weight}-${face.style}-${hash}.woff2`;
+}
+/**
+* Build the cache key for a font face.
+* Used to check if a font has already been downloaded.
+*/
+function cacheKey(face) {
+	return `${face.family.toLowerCase().replace(/\s+/g, "-")}-${face.subset}-${face.weight}-${face.style}`;
+}
+/**
+* Download a single font file from its URL.
+*/
+async function downloadFontFile(url) {
+	const response = await fetch(url);
+	if (!response.ok) throw new Error(`Failed to download font from ${url}: ${response.status}`);
+	return Buffer.from(await response.arrayBuffer());
+}
+/**
+* Download and cache all font files for a set of extracted Google fonts.
+*
+* - Checks the local cache first (node_modules/.cache/timber-fonts/)
+* - Downloads missing fonts from Google Fonts CDN
+* - Writes downloaded fonts to cache
+* - Returns CachedFont entries with content-hashed filenames
+*/
+async function downloadAndCacheFonts(fonts, projectRoot) {
+	const cacheDir = join(projectRoot, DEFAULT_CACHE_DIR);
+	await mkdir(cacheDir, { recursive: true });
+	const googleFonts = fonts.filter((f) => f.provider === "google");
+	const cached = [];
+	for (const font of googleFonts) {
+		const filtered = filterBySubsets(await fetchGoogleFontsCss(buildGoogleFontsUrl(font)), font.subsets);
+		for (const face of filtered) {
+			const key = cacheKey(face);
+			const metaPath = join(cacheDir, `${key}.meta.json`);
+			const dataPath = join(cacheDir, `${key}.woff2`);
+			let data;
+			let filename;
+			if (await isCacheHit(metaPath, dataPath)) {
+				data = await readFile(dataPath);
+				filename = JSON.parse(await readFile(metaPath, "utf-8")).hashedFilename;
+			} else {
+				data = await downloadFontFile(face.url);
+				filename = hashedFontFilename(face, data);
+				await writeFile(dataPath, data);
+				await writeFile(metaPath, JSON.stringify({
+					hashedFilename: filename,
+					url: face.url
+				}));
+			}
+			cached.push({
+				face,
+				hashedFilename: filename,
+				cachePath: dataPath,
+				data
+			});
+		}
+	}
+	return cached;
+}
+/**
+* Check if both the meta and data files exist in the cache.
+*/
+async function isCacheHit(metaPath, dataPath) {
+	try {
+		await stat(metaPath);
+		await stat(dataPath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Generate @font-face descriptors for cached (production) Google Fonts.
+*
+* Each CachedFont gets a FontFaceDescriptor pointing to the
+* content-hashed URL under `/_timber/fonts/`.
+*/
+function generateProductionFontFaces(cachedFonts, display) {
+	return cachedFonts.map((cf) => ({
+		family: cf.face.family,
+		src: `url('/_timber/fonts/${cf.hashedFilename}') format('woff2')`,
+		weight: cf.face.weight,
+		style: cf.face.style,
+		display,
+		unicodeRange: cf.face.unicodeRange
+	}));
+}
+/**
+* Generate @font-face descriptors for dev mode (CDN-pointing).
+*
+* In dev mode, we query the Google Fonts API but use the CDN URLs
+* directly instead of downloading. This avoids the download/cache
+* step during `vite dev`.
+*/
+function generateDevFontFaces(faces, display) {
+	return faces.map((face) => ({
+		family: face.family,
+		src: `url('${face.url}') format('woff2')`,
+		weight: face.weight,
+		style: face.style,
+		display,
+		unicodeRange: face.unicodeRange
+	}));
+}
+/**
+* Resolve dev-mode font faces for an extracted font.
+*
+* Fetches the CSS from Google Fonts API and returns FontFaceDescriptors
+* pointing to CDN URLs. No files are downloaded.
+*/
+async function resolveDevFontFaces(font) {
+	return generateDevFontFaces(filterBySubsets(await fetchGoogleFontsCss(buildGoogleFontsUrl(font)), font.subsets), font.display);
+}
+//#endregion
 //#region src/fonts/css.ts
 /**
 * Generate a single `@font-face` CSS rule from a descriptor.
@@ -14113,268 +14377,242 @@ function processLocalFont(config, importerPath) {
 	};
 }
 //#endregion
-//#region src/fonts/google.ts
-/**
-* Google Fonts download, caching, and dev CDN fallback.
-*
-* At build time (production only):
-* 1. Queries Google Fonts CSS API v2 for font metadata and file URLs
-* 2. Downloads woff2 font files
-* 3. Caches them in node_modules/.cache/timber-fonts/
-* 4. Content-hashes filenames for cache busting
-* 5. Emits font files into the build output via generateBundle
-*
-* In dev mode:
-* - Generates @font-face rules pointing to Google Fonts CDN
-* - No downloads, no caching
-*
-* Design doc: 24-fonts.md §"Step 2: Font Download & Subsetting"
-*/
-/** Google Fonts CSS API v2 base URL. */
-var GOOGLE_FONTS_API = "https://fonts.googleapis.com/css2";
-/**
-* User-Agent string that requests woff2 format from Google Fonts API.
-* Google serves different formats based on user-agent.
-*/
-var WOFF2_USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
-/** Default cache directory for downloaded font files. */
-var DEFAULT_CACHE_DIR = "node_modules/.cache/timber-fonts";
-/**
-* Build the Google Fonts CSS API v2 URL for a given font config.
-*
-* Example output:
-* https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap&subset=latin
-*/
-function buildGoogleFontsUrl(font) {
-	const family = font.family.replace(/\s+/g, "+");
-	const hasItalic = font.styles.includes("italic");
-	const weights = font.weights.map(Number).sort((a, b) => a - b);
-	let axisSpec;
-	if (hasItalic && weights.length > 0) {
-		const pairs = [];
-		for (const ital of [0, 1]) {
-			if (ital === 1 && !hasItalic) continue;
-			if (ital === 0 && font.styles.length === 1 && font.styles[0] === "italic") continue;
-			for (const w of weights) pairs.push(`${ital},${w}`);
-		}
-		axisSpec = `ital,wght@${pairs.join(";")}`;
-	} else if (weights.length > 0) axisSpec = `wght@${weights.join(";")}`;
-	else axisSpec = "";
-	const parts = [`family=${axisSpec ? `${family}:${axisSpec}` : family}`];
-	if (font.display) parts.push(`display=${font.display}`);
-	return `${GOOGLE_FONTS_API}?${parts.join("&")}`;
-}
-/**
-* Fetch the CSS from Google Fonts API and parse out @font-face blocks.
-*
-* The API returns CSS with subset comments like:
-* ```
-* /* latin * /
-* @font-face { ... }
-* ```
-*
-* We parse each block to extract the font URL, unicode-range, and subset label.
-*/
-async function fetchGoogleFontsCss(url) {
-	const response = await fetch(url, { headers: { "User-Agent": WOFF2_USER_AGENT } });
-	if (!response.ok) throw new Error(`Google Fonts API returned ${response.status}: ${response.statusText} for ${url}`);
-	return parseGoogleFontsCss(await response.text());
-}
-/**
-* Parse the CSS response from Google Fonts API into structured font face data.
-*
-* Handles the Google Fonts CSS format with subset comments and @font-face blocks.
-*/
-function parseGoogleFontsCss(css) {
-	const faces = [];
-	const blockPattern = /\/\*\s*([a-z0-9-]+)\s*\*\/\s*@font-face\s*\{([^}]+)\}/g;
-	let match;
-	while ((match = blockPattern.exec(css)) !== null) {
-		const subset = match[1];
-		const block = match[2];
-		const familyMatch = block.match(/font-family:\s*'([^']+)'/);
-		const weightMatch = block.match(/font-weight:\s*(\d+)/);
-		const styleMatch = block.match(/font-style:\s*(\w+)/);
-		const urlMatch = block.match(/url\(([^)]+)\)\s*format\('woff2'\)/);
-		const rangeMatch = block.match(/unicode-range:\s*([^;]+)/);
-		if (familyMatch && urlMatch) faces.push({
-			family: familyMatch[1],
-			weight: weightMatch?.[1] ?? "400",
-			style: styleMatch?.[1] ?? "normal",
-			url: urlMatch[1],
-			unicodeRange: rangeMatch?.[1]?.trim() ?? "",
-			subset
-		});
+//#region src/fonts/pipeline.ts
+var FontPipeline = class {
+	/**
+	* 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.
+	*/
+	_entries = /* @__PURE__ */ new Map();
+	/** Number of registered fonts. */
+	size() {
+		return this._entries.size;
 	}
-	return faces;
-}
-/**
-* Filter parsed font faces to only the requested subsets.
-*/
-function filterBySubsets(faces, subsets) {
-	if (subsets.length === 0) return faces;
-	const subsetSet = new Set(subsets);
-	return faces.filter((f) => subsetSet.has(f.subset));
-}
-/**
-* Generate a content hash for font data.
-* Returns the first 8 hex chars of the SHA-256 hash.
-*/
-function contentHash(data) {
-	return createHash("sha256").update(data).digest("hex").slice(0, 8);
-}
-/**
-* Generate a content-hashed filename for a font face.
-*
-* Format: `<family>-<subset>-<weight>-<style>-<hash>.woff2`
-* Example: `inter-latin-400-normal-abc12345.woff2`
-*/
-function hashedFontFilename(face, data) {
-	const slug = face.family.toLowerCase().replace(/\s+/g, "-");
-	const hash = contentHash(data);
-	return `${slug}-${face.subset}-${face.weight}-${face.style}-${hash}.woff2`;
-}
-/**
-* Build the cache key for a font face.
-* Used to check if a font has already been downloaded.
-*/
-function cacheKey(face) {
-	return `${face.family.toLowerCase().replace(/\s+/g, "-")}-${face.subset}-${face.weight}-${face.style}`;
-}
-/**
-* Download a single font file from its URL.
-*/
-async function downloadFontFile(url) {
-	const response = await fetch(url);
-	if (!response.ok) throw new Error(`Failed to download font from ${url}: ${response.status}`);
-	return Buffer.from(await response.arrayBuffer());
-}
-/**
-* Download and cache all font files for a set of extracted Google fonts.
-*
-* - Checks the local cache first (node_modules/.cache/timber-fonts/)
-* - Downloads missing fonts from Google Fonts CDN
-* - Writes downloaded fonts to cache
-* - Returns CachedFont entries with content-hashed filenames
-*/
-async function downloadAndCacheFonts(fonts, projectRoot) {
-	const cacheDir = join(projectRoot, DEFAULT_CACHE_DIR);
-	await mkdir(cacheDir, { recursive: true });
-	const googleFonts = fonts.filter((f) => f.provider === "google");
-	const cached = [];
-	for (const font of googleFonts) {
-		const filtered = filterBySubsets(await fetchGoogleFontsCss(buildGoogleFontsUrl(font)), font.subsets);
-		for (const face of filtered) {
-			const key = cacheKey(face);
-			const metaPath = join(cacheDir, `${key}.meta.json`);
-			const dataPath = join(cacheDir, `${key}.woff2`);
-			let data;
-			let filename;
-			if (await isCacheHit(metaPath, dataPath)) {
-				data = await readFile(dataPath);
-				filename = JSON.parse(await readFile(metaPath, "utf-8")).hashedFilename;
-			} else {
-				data = await downloadFontFile(face.url);
-				filename = hashedFontFilename(face, data);
-				await writeFile(dataPath, data);
-				await writeFile(metaPath, JSON.stringify({
-					hashedFilename: filename,
-					url: face.url
-				}));
+	/** Iterate every entry as a `FontEntry` (with `faces` / `cachedFiles`). */
+	entries() {
+		return this._entries.values();
+	}
+	/** Iterate every entry typed as the narrower `ExtractedFont` shape. */
+	fonts() {
+		return this._entries.values();
+	}
+	/** Iterate every Google-provider entry. */
+	*googleFonts() {
+		for (const entry of this._entries.values()) if (entry.provider === "google") yield entry;
+	}
+	/** Lookup an entry by font ID. */
+	getEntry(id) {
+		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) {
+		return this._entries.get(fontId)?.faces !== void 0;
+	}
+	/**
+	* 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) {
+		return this._entries.get(fontId)?.cachedFiles !== void 0;
+	}
+	/**
+	* 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) {
+		this._entries.set(extracted.id, { ...extracted });
+	}
+	/** Attach pre-resolved `@font-face` descriptors to a font entry. */
+	attachFaces(fontId, faces) {
+		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, files) {
+		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, family) {
+		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() {
+		this._entries.clear();
+	}
+	/**
+	* 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() {
+		const seen = /* @__PURE__ */ new Set();
+		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;
 			}
-			cached.push({
-				face,
-				hashedFilename: filename,
-				cachePath: dataPath,
-				data
-			});
 		}
 	}
-	return cached;
-}
+	/**
+	* 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() {
+		const cssParts = [];
+		for (const entry of this._entries.values()) cssParts.push(renderEntryCss(entry));
+		return cssParts.join("\n\n");
+	}
+};
 /**
-* Check if both the meta and data files exist in the cache.
+* 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()`.
 */
-async function isCacheHit(metaPath, dataPath) {
-	try {
-		await stat(metaPath);
-		await stat(dataPath);
-		return true;
-	} catch {
-		return false;
+function renderEntryCss(entry) {
+	const cssParts = [];
+	if (entry.provider === "local" && entry.localSources) {
+		const faceCss = generateFontFaces(generateLocalFontFaces(entry.family, entry.localSources, entry.display));
+		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");
 }
+var RESOLVED_GOOGLE = "\0@timber/fonts/google";
+var RESOLVED_LOCAL = "\0@timber/fonts/local";
+var VIRTUAL_FONT_CSS_REGISTER = "virtual:timber-font-css-register";
+var RESOLVED_FONT_CSS_REGISTER = "\0virtual:timber-font-css-register";
 /**
-* Generate @font-face descriptors for cached (production) Google Fonts.
-*
-* Each CachedFont gets a FontFaceDescriptor pointing to the
-* content-hashed URL under `/_timber/fonts/`.
+* Convert a font family name to a PascalCase export name.
+* e.g. "JetBrains Mono" → "JetBrains_Mono"
 */
-function generateProductionFontFaces(cachedFonts, display) {
-	return cachedFonts.map((cf) => ({
-		family: cf.face.family,
-		src: `url('/_timber/fonts/${cf.hashedFilename}') format('woff2')`,
-		weight: cf.face.weight,
-		style: cf.face.style,
-		display,
-		unicodeRange: cf.face.unicodeRange
-	}));
+function familyToExportName(family) {
+	return family.replace(/\s+/g, "_");
 }
 /**
-* Generate @font-face descriptors for dev mode (CDN-pointing).
+* Generate the virtual module source for `@timber/fonts/google`.
 *
-* In dev mode, we query the Google Fonts API but use the CDN URLs
-* directly instead of downloading. This avoids the download/cache
-* step during `vite dev`.
+* 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).
 */
-function generateDevFontFaces(faces, display) {
-	return faces.map((face) => ({
-		family: face.family,
-		src: `url('${face.url}') format('woff2')`,
-		weight: face.weight,
-		style: face.style,
-		display,
-		unicodeRange: face.unicodeRange
-	}));
+function generateGoogleVirtualModule(fonts) {
+	const families = /* @__PURE__ */ new Set();
+	for (const font of fonts) if (font.provider === "google") families.add(font.family);
+	const lines = [
+		"// Auto-generated virtual module: @timber/fonts/google",
+		"// Each export is a font loader function that returns a FontResult.",
+		"",
+		"function createFontResult(family, config) {",
+		"  return {",
+		"    className: `timber-font-${family.toLowerCase().replace(/\\s+/g, \"-\")}`,",
+		"    style: { fontFamily: family },",
+		"    variable: config?.variable,",
+		"  };",
+		"}",
+		"",
+		"export default new Proxy({}, {",
+		"  get(_, prop) {",
+		"    if (typeof prop === \"string\") {",
+		"      return (config) => createFontResult(prop.replace(/_/g, \" \"), config);",
+		"    }",
+		"  }",
+		"});"
+	];
+	for (const family of families) {
+		const exportName = familyToExportName(family);
+		lines.push("");
+		lines.push(`export function ${exportName}(config) {`);
+		lines.push(`  return createFontResult('${family}', config);`);
+		lines.push("}");
+	}
+	return lines.join("\n");
 }
 /**
-* Resolve dev-mode font faces for an extracted font.
+* Generate the virtual module source for `@timber/fonts/local`.
 *
-* Fetches the CSS from Google Fonts API and returns FontFaceDescriptors
-* pointing to CDN URLs. No files are downloaded.
+* Like the google virtual module, this is a runtime fallback. The
+* transform hook normally replaces `localFont(...)` calls with static
+* `FontResult` objects at build time.
 */
-async function resolveDevFontFaces(font) {
-	return generateDevFontFaces(filterBySubsets(await fetchGoogleFontsCss(buildGoogleFontsUrl(font)), font.subsets), font.display);
+function generateLocalVirtualModule() {
+	return [
+		"// Auto-generated virtual module: @timber/fonts/local",
+		"",
+		"export default function localFont(config) {",
+		"  const family = config?.family || \"Local Font\";",
+		"  return {",
+		"    className: `timber-font-${family.toLowerCase().replace(/\\s+/g, \"-\")}`,",
+		"    style: { fontFamily: family },",
+		"    variable: config?.variable,",
+		"  };",
+		"}"
+	].join("\n");
 }
 //#endregion
-//#region src/plugins/fonts.ts
-var VIRTUAL_GOOGLE = "@timber/fonts/google";
-var VIRTUAL_LOCAL = "@timber/fonts/local";
-var RESOLVED_GOOGLE = "\0@timber/fonts/google";
-var RESOLVED_LOCAL = "\0@timber/fonts/local";
+//#region src/fonts/transform.ts
 /**
-* Virtual side-effect module that registers font CSS on globalThis.
-*
-* When a file calls localFont() or a Google font function, the transform
-* hook injects `import 'virtual:timber-font-css-register'` into that file.
-* This virtual module sets `globalThis.__timber_font_css` with the combined
-* @font-face CSS. The RSC entry reads it at render time to inline a <style> tag.
-*
-* This approach avoids timing issues because:
-* 1. The font file is in the RSC module graph (imported by layout.tsx)
-* 2. The side-effect import is added to the font file during transform
-* 3. When layout.tsx is loaded, fonts.ts runs → side-effect module runs → globalThis is set
-* 4. RSC entry renders → reads globalThis → inlines <style>
-*/
-var VIRTUAL_FONT_CSS_REGISTER = "virtual:timber-font-css-register";
-var RESOLVED_FONT_CSS_REGISTER = "\0virtual:timber-font-css-register";
-/**
-* Convert a font family name to a PascalCase export name.
-* e.g. "JetBrains Mono" → "JetBrains_Mono"
+* Regex that matches imports from either `@timber/fonts/google` or
+* `next/font/google` (which the shims plugin resolves to the same virtual
+* module). The transform hook still needs to recognise both spellings in
+* source code.
 */
-function familyToExportName(family) {
-	return family.replace(/\s+/g, "_");
-}
+var GOOGLE_FONT_IMPORT_RE = /import\s*\{([^}]+)\}\s*from\s*['"](?:@timber\/fonts\/google|@timber-js\/app\/fonts\/google|next\/font\/google)['"]/g;
 /**
 * Convert a font family name to a scoped class name.
 * e.g. "JetBrains Mono" → "timber-font-jetbrains-mono"
@@ -14382,66 +14620,53 @@ function familyToExportName(family) {
 function familyToClassName(family) {
 	return `timber-font-${family.toLowerCase().replace(/\s+/g, "-")}`;
 }
-/**
-* Generate a unique font ID from family + config hash.
-*/
-function generateFontId(family, config) {
-	const weights = normalizeToArray(config.weight);
-	const styles = normalizeToArray(config.style);
-	const subsets = config.subsets ?? ["latin"];
-	const display = config.display ?? "swap";
-	return `${family.toLowerCase()}-${weights.join(",")}-${styles.join(",")}-${subsets.join(",")}-${display}`;
-}
-/**
-* Normalize a string or string array to an array.
-*/
-function normalizeToArray(value) {
+/** Normalize a string or string array to an array (default `['400']`). */
+function normalizeWeightArray(value) {
 	if (!value) return ["400"];
 	return Array.isArray(value) ? value : [value];
 }
-/**
-* Normalize style to an array.
-*/
+/** Normalize style to an array (default `['normal']`). */
 function normalizeStyleArray(value) {
 	if (!value) return ["normal"];
 	return Array.isArray(value) ? value : [value];
 }
 /**
-* Extract static font config from a font function call in source code.
-*
-* Parses patterns like:
-*   const inter = Inter({ subsets: ['latin'], weight: '400', display: 'swap', variable: '--font-sans' })
+* Generate a unique font ID from family + config hash.
 *
-* Returns null if the call cannot be statically analyzed.
+* 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.
+*/
+function generateFontId(family, config) {
+	const weights = normalizeWeightArray(config.weight);
+	const styles = normalizeStyleArray(config.style);
+	const subsets = config.subsets ?? ["latin"];
+	const display = config.display ?? "swap";
+	return `${family.toLowerCase()}-${weights.join(",")}-${styles.join(",")}-${subsets.join(",")}-${display}`;
+}
+/**
+* Extract static font config from a font function call source.
 *
-* Uses acorn AST parsing for robust handling of comments, trailing commas,
-* and multi-line configs.
+* Returns `null` if the call cannot be statically analysed.
 */
 function extractFontConfig(callSource) {
 	return extractFontConfigAst(callSource);
 }
 /**
-* Detect if a source file contains dynamic/computed font function calls
-* that cannot be statically analyzed.
-*
-* Returns the offending expression if found, null if all calls are static.
-*
-* Uses acorn AST parsing for accurate detection.
+* Detect dynamic/computed font function calls that cannot be statically
+* analysed. Returns the offending expression text, or `null` if all calls
+* are static.
 */
 function detectDynamicFontCall(source, importedNames) {
 	return detectDynamicFontCallAst(source, importedNames);
 }
 /**
-* Regex that matches imports from either `@timber/fonts/google` or `next/font/google`.
-* The shims plugin resolves `next/font/google` to the same virtual module,
-* but the source code still contains the original import specifier.
-*/
-var GOOGLE_FONT_IMPORT_RE = /import\s*\{([^}]+)\}\s*from\s*['"](?:@timber\/fonts\/google|@timber-js\/app\/fonts\/google|next\/font\/google)['"]/g;
-/**
-* Parse the original (remote) font family names from imports.
+* Parse Google font imports into a `localName → familyName` map.
 *
-* Returns a map of local name → family name.
-* e.g. { Inter: 'Inter', JetBrains_Mono: 'JetBrains Mono' }
+* 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.
 */
 function parseGoogleFontFamilies(source) {
 	const importPattern = new RegExp(GOOGLE_FONT_IMPORT_RE.source, "g");
@@ -14460,121 +14685,69 @@ function parseGoogleFontFamilies(source) {
 	return families;
 }
 /**
-* Generate the virtual module source for `@timber/fonts/google`.
-*
-* Each Google Font family gets a named export that returns a FontResult.
-* In this base implementation, the functions return static data.
-* The Google Fonts download task (timber-nk5) will add real font file URLs.
-*/
-function generateGoogleVirtualModule(registry) {
-	const families = /* @__PURE__ */ new Set();
-	for (const font of registry.values()) if (font.provider === "google") families.add(font.family);
-	const lines = [
-		"// Auto-generated virtual module: @timber/fonts/google",
-		"// Each export is a font loader function that returns a FontResult.",
-		""
-	];
-	lines.push("function createFontResult(family, config) {");
-	lines.push("  return {");
-	lines.push("    className: `timber-font-${family.toLowerCase().replace(/\\s+/g, \"-\")}`,");
-	lines.push("    style: { fontFamily: family },");
-	lines.push("    variable: config?.variable,");
-	lines.push("  };");
-	lines.push("}");
-	lines.push("");
-	lines.push("export default new Proxy({}, {");
-	lines.push("  get(_, prop) {");
-	lines.push("    if (typeof prop === \"string\") {");
-	lines.push("      return (config) => createFontResult(prop.replace(/_/g, \" \"), config);");
-	lines.push("    }");
-	lines.push("  }");
-	lines.push("});");
-	for (const family of families) {
-		const exportName = familyToExportName(family);
-		lines.push("");
-		lines.push(`export function ${exportName}(config) {`);
-		lines.push(`  return createFontResult('${family}', config);`);
-		lines.push("}");
-	}
-	return lines.join("\n");
-}
-/**
-* Generate the virtual module source for `@timber/fonts/local`.
-*/
-function generateLocalVirtualModule() {
-	return [
-		"// Auto-generated virtual module: @timber/fonts/local",
-		"",
-		"export default function localFont(config) {",
-		"  const family = config?.family || \"Local Font\";",
-		"  return {",
-		"    className: `timber-font-${family.toLowerCase().replace(/\\s+/g, \"-\")}`,",
-		"    style: { fontFamily: family },",
-		"    variable: config?.variable,",
-		"  };",
-		"}"
-	].join("\n");
-}
-/**
-* Generate CSS for a single extracted font.
-*
-* Includes @font-face rules (for local and Google fonts), fallback @font-face,
-* and the scoped class rule.
-*
-* For Google fonts, pass the resolved FontFaceDescriptor[] from either
-* `generateProductionFontFaces()` (production) or `resolveDevFontFaces()` (dev).
-*/
-function generateFontCss(font, googleFaces) {
-	const cssParts = [];
-	if (font.provider === "local" && font.localSources) {
-		const faceCss = generateFontFaces(generateLocalFontFaces(font.family, font.localSources, font.display));
-		if (faceCss) cssParts.push(faceCss);
-	}
-	if (font.provider === "google" && googleFaces && googleFaces.length > 0) {
-		const faceCss = generateFontFaces(googleFaces);
-		if (faceCss) cssParts.push(faceCss);
-	}
-	const fallbackCss = generateFallbackCss(font.family);
-	if (fallbackCss) cssParts.push(fallbackCss);
-	if (font.variable) cssParts.push(generateVariableClass(font.className, font.variable, font.fontFamily));
-	else cssParts.push(generateFontFamilyClass(font.className, font.fontFamily));
-	return cssParts.join("\n\n");
-}
-/**
-* Generate the CSS output for all extracted fonts.
-*
-* Includes @font-face rules for local and Google fonts, fallback @font-face
-* rules, and scoped classes.
-*
-* `googleFontFacesMap` provides pre-resolved FontFaceDescriptor[] for each
-* Google font ID (keyed by ExtractedFont.id).
-*/
-function generateAllFontCss(registry, googleFontFacesMap) {
-	const cssParts = [];
-	for (const font of registry.values()) {
-		const googleFaces = googleFontFacesMap?.get(font.id);
-		cssParts.push(generateFontCss(font, googleFaces));
-	}
-	return cssParts.join("\n\n");
-}
-/**
 * Parse the local name used for the default import of `@timber/fonts/local`.
 *
-* Handles:
+* Handles either spelling and arbitrary local names:
 *   import localFont from '@timber/fonts/local'
-*   import myLoader from '@timber/fonts/local'
+*   import myLoader from 'next/font/local'
 */
 function parseLocalFontImportName(source) {
 	const match = source.match(/import\s+(\w+)\s+from\s*['"](?:@timber\/fonts\/local|@timber-js\/app\/fonts\/local|next\/font\/local)['"]/);
 	return match ? match[1] : null;
 }
+/** Build the static `FontResult` literal we substitute for a font call. */
+function buildFontResultLiteral(extracted) {
+	return extracted.variable ? `{ className: "${extracted.className}", style: { fontFamily: "${extracted.fontFamily}" }, variable: "${extracted.variable}" }` : `{ className: "${extracted.className}", style: { fontFamily: "${extracted.fontFamily}" } }`;
+}
 /**
-* Transform local font calls in source code.
-*
-* Finds `localFont({ ... })` calls, extracts the config,
-* registers the font, and replaces the call with a static FontResult.
+* Find Google font calls in `originalCode`, register them in the pipeline,
+* and replace each call site in `transformedCode` with a static FontResult.
 */
-function transformLocalFonts(transformedCode, originalCode, importerId, registry, emitError) {
+function transformGoogleFonts(transformedCode, originalCode, importerId, pipeline, emitError) {
+	const families = parseGoogleFontFamilies(originalCode);
+	if (families.size === 0) return transformedCode;
+	const dynamicCall = detectDynamicFontCall(originalCode, [...families.keys()]);
+	if (dynamicCall) emitError(`Font function calls must be statically analyzable. Found dynamic call: ${dynamicCall}. Pass a literal object with string/array values instead.`);
+	for (const [localName, family] of families) {
+		const callPattern = new RegExp(`(?:const|let|var)\\s+(\\w+)\\s*=\\s*${localName}\\s*\\(\\s*(\\{[\\s\\S]*?\\})\\s*\\)`, "g");
+		let callMatch;
+		while ((callMatch = callPattern.exec(originalCode)) !== null) {
+			const varName = callMatch[1];
+			const configSource = callMatch[2];
+			const fullMatch = callMatch[0];
+			const config = extractFontConfig(`(${configSource})`);
+			if (!config) emitError(`Could not statically analyze font config for ${family}. Ensure all config values are string literals or arrays of string literals.`);
+			const fontId = generateFontId(family, config);
+			const className = familyToClassName(family);
+			const fontStack = buildFontStack(family);
+			const display = config.display ?? "swap";
+			const extracted = {
+				id: fontId,
+				family,
+				provider: "google",
+				weights: normalizeWeightArray(config.weight),
+				styles: normalizeStyleArray(config.style),
+				subsets: config.subsets ?? ["latin"],
+				display,
+				variable: config.variable,
+				className,
+				fontFamily: fontStack,
+				importer: importerId
+			};
+			pipeline.pruneFor(importerId, family);
+			pipeline.register(extracted);
+			const replacement = `const ${varName} = ${buildFontResultLiteral(extracted)}`;
+			transformedCode = transformedCode.replace(fullMatch, replacement);
+		}
+	}
+	transformedCode = transformedCode.replace(/import\s*\{[^}]+\}\s*from\s*['"](?:@timber\/fonts\/google|@timber-js\/app\/fonts\/google|next\/font\/google)['"];?\s*\n?/g, "");
+	return transformedCode;
+}
+/**
+* Find local font calls in `originalCode`, register them in the pipeline,
+* and replace each call site in `transformedCode` with a static FontResult.
+*/
+function transformLocalFonts(transformedCode, originalCode, importerId, pipeline, emitError) {
 	const localName = parseLocalFontImportName(originalCode);
 	if (!localName) return transformedCode;
 	const dynamicCall = detectDynamicFontCall(originalCode, [localName]);
@@ -14586,30 +14759,185 @@ function transformLocalFonts(transformedCode, originalCode, importerId, registry
 		const configSource = callMatch[2];
 		const fullMatch = callMatch[0];
 		const config = extractLocalFontConfigAst(`(${configSource})`);
-		if (!config) {
-			emitError("Could not statically analyze local font config. Ensure src is a string or array of { path, weight?, style? } objects.");
-			return transformedCode;
-		}
+		if (!config) emitError("Could not statically analyze local font config. Ensure src is a string or array of { path, weight?, style? } objects.");
 		const extracted = processLocalFont(config, importerId);
-		registry.set(extracted.id, extracted);
-		const replacement = `const ${varName} = ${extracted.variable ? `{ className: "${extracted.className}", style: { fontFamily: "${extracted.fontFamily}" }, variable: "${extracted.variable}" }` : `{ className: "${extracted.className}", style: { fontFamily: "${extracted.fontFamily}" } }`}`;
+		pipeline.pruneFor(importerId, extracted.family);
+		pipeline.register(extracted);
+		const replacement = `const ${varName} = ${buildFontResultLiteral(extracted)}`;
 		transformedCode = transformedCode.replace(fullMatch, replacement);
 	}
 	transformedCode = transformedCode.replace(/import\s+\w+\s+from\s*['"](?:@timber\/fonts\/local|@timber-js\/app\/fonts\/local|next\/font\/local)['"];?\s*\n?/g, "");
 	return transformedCode;
 }
 /**
+* Run the timber-fonts transform pass on a single source file.
+*
+* Returns the rewritten code (with font calls inlined and the side-effect
+* `virtual:timber-font-css-register` import prepended) or `null` if the
+* file does not import from any timber-fonts virtual module and therefore
+* needs no transformation.
+*/
+function runFontsTransform(code, id, pipeline, emitError) {
+	if (id.startsWith("\0") || id.includes("node_modules")) return null;
+	const hasGoogleImport = code.includes("@timber/fonts/google") || code.includes("@timber-js/app/fonts/google") || code.includes("next/font/google");
+	const hasLocalImport = code.includes("@timber/fonts/local") || code.includes("@timber-js/app/fonts/local") || code.includes("next/font/local");
+	if (!hasGoogleImport && !hasLocalImport) return null;
+	let transformedCode = code;
+	if (hasGoogleImport) transformedCode = transformGoogleFonts(transformedCode, code, id, pipeline, emitError);
+	if (hasLocalImport) transformedCode = transformLocalFonts(transformedCode, code, id, pipeline, emitError);
+	if (transformedCode !== code) {
+		if (pipeline.size() > 0) transformedCode = `import '${VIRTUAL_FONT_CSS_REGISTER}';\n` + transformedCode;
+		return {
+			code: transformedCode,
+			map: null
+		};
+	}
+	return null;
+}
+//#endregion
+//#region src/fonts/dev-middleware.ts
+var FONT_MIME_TYPES = {
+	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.
+*/
+function installFontDevMiddleware(server, pipeline) {
+	server.middlewares.use((req, res, next) => {
+		const url = req.url;
+		if (!url || !url.startsWith("/_timber/fonts/")) return next();
+		const requestedFilename = url.slice(15);
+		if (requestedFilename.includes("..") || requestedFilename.includes("/")) {
+			res.statusCode = 400;
+			res.end("Bad request");
+			return;
+		}
+		for (const font of pipeline.fonts()) {
+			if (font.provider !== "local" || !font.localSources) continue;
+			for (const src of font.localSources) {
+				if ((src.path.split("/").pop() ?? "") !== 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();
+	});
+}
+//#endregion
+//#region src/fonts/bundle.ts
+/**
+* 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
+*/
+/** Group cached Google Font binaries by lowercase family name. */
+function groupCachedFontsByFamily(cachedFonts) {
+	const cachedByFamily = /* @__PURE__ */ new Map();
+	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).
+*/
+function emitFontAssets(pipeline, emitFile, warn) {
+	for (const cf of pipeline.uniqueCachedFiles()) emitFile({
+		type: "asset",
+		fileName: `_timber/fonts/${cf.hashedFilename}`,
+		source: cf.data
+	});
+	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 basename = src.path.split("/").pop() ?? src.path;
+			const data = readFileSync(absolutePath);
+			emitFile({
+				type: "asset",
+				fileName: `_timber/fonts/${basename}`,
+				source: data
+			});
+		}
+	}
+}
+/**
+* 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.
+*/
+function writeFontManifest(pipeline, buildManifest, rootDir) {
+	const fontsByImporter = /* @__PURE__ */ new Map();
+	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.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) {
+		const relativePath = importer.startsWith(rootDir) ? importer.slice(rootDir.length + 1) : importer;
+		buildManifest.fonts[relativePath] = entries;
+	}
+}
+//#endregion
+//#region src/plugins/fonts.ts
+/**
 * Create the timber-fonts Vite plugin.
 */
 function timberFonts(ctx) {
-	const registry = /* @__PURE__ */ new Map();
-	/** Fonts downloaded during buildStart (production only). */
-	let cachedFonts = [];
-	/**
-	* Pre-resolved @font-face descriptors for Google fonts, keyed by font ID.
-	* Populated in buildStart (production) or lazily in load (dev).
-	*/
-	const googleFontFacesMap = /* @__PURE__ */ new Map();
+	const pipeline = new FontPipeline();
 	return {
 		name: "timber-fonts",
 		resolveId(id) {
@@ -14619,200 +14947,50 @@ function timberFonts(ctx) {
 				if (stripped.startsWith("/") || stripped.startsWith("\\")) cleanId = stripped.slice(1);
 				else cleanId = stripped;
 			}
-			if (cleanId === VIRTUAL_GOOGLE) return RESOLVED_GOOGLE;
-			if (cleanId === VIRTUAL_LOCAL) return RESOLVED_LOCAL;
-			if (cleanId === VIRTUAL_FONT_CSS_REGISTER) return RESOLVED_FONT_CSS_REGISTER;
+			if (cleanId === "@timber/fonts/google") return RESOLVED_GOOGLE;
+			if (cleanId === "@timber/fonts/local") return RESOLVED_LOCAL;
+			if (cleanId === "virtual:timber-font-css-register") return RESOLVED_FONT_CSS_REGISTER;
 			return null;
 		},
 		async load(id) {
-			if (id === RESOLVED_GOOGLE) return generateGoogleVirtualModule(registry);
-			if (id === RESOLVED_LOCAL) return generateLocalVirtualModule();
-			if (id === RESOLVED_FONT_CSS_REGISTER) {
-				if (ctx.dev) {
-					const googleFonts = [...registry.values()].filter((f) => f.provider === "google");
-					for (const font of googleFonts) if (!googleFontFacesMap.has(font.id)) try {
+			if (id === "\0@timber/fonts/google") return generateGoogleVirtualModule(pipeline.fonts());
+			if (id === "\0@timber/fonts/local") return generateLocalVirtualModule();
+			if (id === "\0virtual:timber-font-css-register") {
+				if (ctx.dev) for (const font of pipeline.googleFonts()) {
+					if (pipeline.hasFaces(font.id)) continue;
+					try {
 						const faces = await resolveDevFontFaces(font);
-						googleFontFacesMap.set(font.id, faces);
+						pipeline.attachFaces(font.id, faces);
 					} catch (e) {
 						const msg = e instanceof Error ? e.message : String(e);
 						console.warn(`[timber-fonts] Failed to resolve Google font "${font.family}": ${msg}. Will retry on next request.`);
 					}
 				}
-				const css = generateAllFontCss(registry, googleFontFacesMap);
-				return `globalThis.__timber_font_css = ${JSON.stringify(css)};`;
+				return `globalThis.__timber_font_css = ${JSON.stringify(pipeline.getCss())};`;
 			}
 			return null;
 		},
 		configureServer(server) {
-			server.middlewares.use((req, res, next) => {
-				const url = req.url;
-				if (!url || !url.startsWith("/_timber/fonts/")) return next();
-				const requestedFilename = url.slice(15);
-				if (requestedFilename.includes("..") || requestedFilename.includes("/")) {
-					res.statusCode = 400;
-					res.end("Bad request");
-					return;
-				}
-				for (const font of registry.values()) {
-					if (font.provider !== "local" || !font.localSources) continue;
-					for (const src of font.localSources) if ((src.path.split("/").pop() ?? "") === requestedFilename) {
-						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", {
-							woff2: "font/woff2",
-							woff: "font/woff",
-							ttf: "font/ttf",
-							otf: "font/otf",
-							eot: "application/vnd.ms-fontopen"
-						}[ext ?? ""] ?? "application/octet-stream");
-						res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
-						res.setHeader("Access-Control-Allow-Origin", "*");
-						res.end(data);
-						return;
-					}
-				}
-				next();
-			});
+			installFontDevMiddleware(server, pipeline);
 		},
 		async buildStart() {
 			if (ctx.dev) return;
-			const googleFonts = [...registry.values()].filter((f) => f.provider === "google");
+			const googleFonts = [...pipeline.googleFonts()];
 			if (googleFonts.length === 0) return;
-			cachedFonts = await downloadAndCacheFonts(googleFonts, ctx.root);
-			const cachedByFamily = /* @__PURE__ */ new Map();
-			for (const cf of cachedFonts) {
-				const key = cf.face.family.toLowerCase();
-				const arr = cachedByFamily.get(key) ?? [];
-				arr.push(cf);
-				cachedByFamily.set(key, arr);
-			}
+			const cachedByFamily = groupCachedFontsByFamily(await downloadAndCacheFonts(googleFonts, ctx.root));
 			for (const font of googleFonts) {
-				const faces = generateProductionFontFaces(cachedByFamily.get(font.family.toLowerCase()) ?? [], font.display);
-				googleFontFacesMap.set(font.id, faces);
+				const familyCached = cachedByFamily.get(font.family.toLowerCase()) ?? [];
+				pipeline.attachCachedFiles(font.id, familyCached);
+				pipeline.attachFaces(font.id, generateProductionFontFaces(familyCached, font.display));
 			}
 		},
 		transform(code, id) {
-			if (id.startsWith("\0") || id.includes("node_modules")) return null;
-			const hasGoogleImport = code.includes("@timber/fonts/google") || code.includes("@timber-js/app/fonts/google") || code.includes("next/font/google");
-			const hasLocalImport = code.includes("@timber/fonts/local") || code.includes("@timber-js/app/fonts/local") || code.includes("next/font/local");
-			if (!hasGoogleImport && !hasLocalImport) return null;
-			let transformedCode = code;
-			if (hasGoogleImport) {
-				const families = parseGoogleFontFamilies(code);
-				if (families.size > 0) {
-					const dynamicCall = detectDynamicFontCall(code, [...families.keys()]);
-					if (dynamicCall) this.error(`Font function calls must be statically analyzable. Found dynamic call: ${dynamicCall}. Pass a literal object with string/array values instead.`);
-					for (const [localName, family] of families) {
-						const callPattern = new RegExp(`(?:const|let|var)\\s+(\\w+)\\s*=\\s*${localName}\\s*\\(\\s*(\\{[\\s\\S]*?\\})\\s*\\)`, "g");
-						let callMatch;
-						while ((callMatch = callPattern.exec(code)) !== null) {
-							const varName = callMatch[1];
-							const configSource = callMatch[2];
-							const fullMatch = callMatch[0];
-							const config = extractFontConfig(`(${configSource})`);
-							if (!config) {
-								this.error(`Could not statically analyze font config for ${family}. Ensure all config values are string literals or arrays of string literals.`);
-								return null;
-							}
-							const fontId = generateFontId(family, config);
-							const className = familyToClassName(family);
-							const fontStack = buildFontStack(family);
-							const display = config.display ?? "swap";
-							const extracted = {
-								id: fontId,
-								family,
-								provider: "google",
-								weights: normalizeToArray(config.weight),
-								styles: normalizeStyleArray(config.style),
-								subsets: config.subsets ?? ["latin"],
-								display,
-								variable: config.variable,
-								className,
-								fontFamily: fontStack,
-								importer: id
-							};
-							registry.set(fontId, extracted);
-							const replacement = `const ${varName} = ${config.variable ? `{ className: "${className}", style: { fontFamily: "${fontStack}" }, variable: "${config.variable}" }` : `{ className: "${className}", style: { fontFamily: "${fontStack}" } }`}`;
-							transformedCode = transformedCode.replace(fullMatch, replacement);
-						}
-					}
-					transformedCode = transformedCode.replace(/import\s*\{[^}]+\}\s*from\s*['"](?:@timber\/fonts\/google|@timber-js\/app\/fonts\/google|next\/font\/google)['"];?\s*\n?/g, "");
-				}
-			}
-			if (hasLocalImport) transformedCode = transformLocalFonts(transformedCode, code, id, registry, this.error.bind(this));
-			if (transformedCode !== code) {
-				if (registry.size > 0) transformedCode = `import '${VIRTUAL_FONT_CSS_REGISTER}';\n` + transformedCode;
-				return {
-					code: transformedCode,
-					map: null
-				};
-			}
-			return null;
+			return runFontsTransform(code, id, pipeline, (msg) => this.error(msg));
 		},
 		generateBundle() {
-			for (const cf of cachedFonts) this.emitFile({
-				type: "asset",
-				fileName: `_timber/fonts/${cf.hashedFilename}`,
-				source: cf.data
-			});
-			for (const font of registry.values()) {
-				if (font.provider !== "local" || !font.localSources) continue;
-				for (const src of font.localSources) {
-					const absolutePath = normalize(resolve(src.path));
-					if (!existsSync(absolutePath)) {
-						this.warn(`Local font file not found: ${absolutePath}`);
-						continue;
-					}
-					const basename = src.path.split("/").pop() ?? src.path;
-					const data = readFileSync(absolutePath);
-					this.emitFile({
-						type: "asset",
-						fileName: `_timber/fonts/${basename}`,
-						source: data
-					});
-				}
-			}
+			emitFontAssets(pipeline, (asset) => this.emitFile(asset), (msg) => this.warn(msg));
 			if (!ctx.buildManifest) return;
-			const cachedByFamily = /* @__PURE__ */ new Map();
-			for (const cf of cachedFonts) {
-				const key = cf.face.family.toLowerCase();
-				const arr = cachedByFamily.get(key) ?? [];
-				arr.push(cf);
-				cachedByFamily.set(key, arr);
-			}
-			const fontsByImporter = /* @__PURE__ */ new Map();
-			for (const font of registry.values()) {
-				const entries = fontsByImporter.get(font.importer) ?? [];
-				if (font.provider === "local" && font.localSources) for (const src of font.localSources) {
-					const filename = src.path.split("/").pop() ?? src.path;
-					const format = inferFontFormat(src.path);
-					entries.push({
-						href: `/_timber/fonts/${filename}`,
-						format,
-						crossOrigin: "anonymous"
-					});
-				}
-				else {
-					const familyKey = font.family.toLowerCase();
-					const familyCached = cachedByFamily.get(familyKey) ?? [];
-					for (const cf of familyCached) entries.push({
-						href: `/_timber/fonts/${cf.hashedFilename}`,
-						format: "woff2",
-						crossOrigin: "anonymous"
-					});
-				}
-				fontsByImporter.set(font.importer, entries);
-			}
-			for (const [importer, entries] of fontsByImporter) {
-				const relativePath = importer.startsWith(ctx.root) ? importer.slice(ctx.root.length + 1) : importer;
-				ctx.buildManifest.fonts[relativePath] = entries;
-			}
+			writeFontManifest(pipeline, ctx.buildManifest, ctx.root);
 		}
 	};
 }