diff --git a/packages/producer/src/services/deterministicFonts-googleSubsets.test.ts b/packages/producer/src/services/deterministicFonts-googleSubsets.test.ts
new file mode 100644
index 0000000000..945023b9de
--- /dev/null
+++ b/packages/producer/src/services/deterministicFonts-googleSubsets.test.ts
@@ -0,0 +1,110 @@
+/**
+ * Regression test for the Google Fonts multi-subset cache collision.
+ *
+ * Google Fonts' css2 API returns ONE @font-face per (weight × unicode-range
+ * subset) — e.g. for a single weight you get separate `vietnamese`,
+ * `latin-ext`, and `latin` faces, each pointing at a DISTINCT woff2 whose
+ * glyph coverage matches its `unicode-range`.
+ *
+ * The bug: the on-disk cache keyed woff2 files by `${weight}-${style}` only,
+ * ignoring the subset. So all subsets of a weight collided on one filename —
+ * only the FIRST subset in the CSS (vietnamese, for many display families)
+ * was ever downloaded, and every later subset read that same file back.
+ * Compounding it, the injected @font-face dropped `unicode-range`, so the face
+ * claimed to cover every codepoint while only containing the first subset's
+ * glyphs. Result: Latin letters absent from the embedded font fell back to a
+ * different font (the visible "wrong A" glitch).
+ *
+ * These tests inject `fetchImpl` (no network) and a temp `HYPERFRAMES_FONT_CACHE_DIR`
+ * so they are hermetic.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+let cacheDir: string;
+let prevCacheEnv: string | undefined;
+
+beforeAll(() => {
+ prevCacheEnv = process.env.HYPERFRAMES_FONT_CACHE_DIR;
+ cacheDir = mkdtempSync(join(tmpdir(), "hf-font-cache-"));
+ process.env.HYPERFRAMES_FONT_CACHE_DIR = cacheDir;
+});
+
+afterAll(() => {
+ if (prevCacheEnv === undefined) delete process.env.HYPERFRAMES_FONT_CACHE_DIR;
+ else process.env.HYPERFRAMES_FONT_CACHE_DIR = prevCacheEnv;
+ rmSync(cacheDir, { recursive: true, force: true });
+});
+
+const VIET_RANGE = "U+0102-0103, U+1EA0-1EF9, U+20AB";
+const LATIN_RANGE = "U+0000-00FF, U+0131, U+2000-206F";
+const VIET_URL = "https://fonts.gstatic.com/s/testfam/v1/VIET-subset.woff2";
+const LATIN_URL = "https://fonts.gstatic.com/s/testfam/v1/LATIN-subset.woff2";
+// distinct, identifiable "woff2" bodies (content need not be a real font here)
+const VIET_BYTES = "VIET_SUBSET_BYTES";
+const LATIN_BYTES = "LATIN_SUBSET_BYTES";
+const b64 = (s: string) => Buffer.from(s).toString("base64");
+
+// Two subsets for the SAME weight, vietnamese FIRST (as Google orders it for
+// display families) then latin — exactly the shape that triggered the bug.
+const CSS = `/* vietnamese */
+@font-face {
+ font-family: 'TestFam';
+ font-style: normal;
+ font-weight: 900;
+ font-display: swap;
+ src: url(${VIET_URL}) format('woff2');
+ unicode-range: ${VIET_RANGE};
+}
+/* latin */
+@font-face {
+ font-family: 'TestFam';
+ font-style: normal;
+ font-weight: 900;
+ font-display: swap;
+ src: url(${LATIN_URL}) format('woff2');
+ unicode-range: ${LATIN_RANGE};
+}`;
+
+function makeGoogleFetch(): typeof fetch {
+ return (async (input: unknown) => {
+ const url = String(input);
+ if (url.includes("css2")) return new Response(CSS, { status: 200 });
+ if (url === VIET_URL) return new Response(VIET_BYTES, { status: 200 });
+ if (url === LATIN_URL) return new Response(LATIN_BYTES, { status: 200 });
+ return new Response("", { status: 404 });
+ }) as unknown as typeof fetch;
+}
+
+const HTML = `
CATALOG
`;
+
+describe("Google Fonts multi-subset embedding", () => {
+ it("downloads and embeds EACH subset distinctly (no cache collision)", async () => {
+ const { injectDeterministicFontFaces } = await import("./deterministicFonts.js");
+ const result = await injectDeterministicFontFaces(HTML, { fetchImpl: makeGoogleFetch() });
+
+ // Both subsets' distinct bytes must be present — the latin subset must NOT
+ // be clobbered by the vietnamese one. (Before the fix, the latin face
+ // carried the vietnamese bytes because both shared one cache filename.)
+ expect(result).toContain(b64(VIET_BYTES));
+ expect(result).toContain(b64(LATIN_BYTES));
+ });
+
+ it("preserves each face's unicode-range so the browser picks the right subset per codepoint", async () => {
+ const { injectDeterministicFontFaces } = await import("./deterministicFonts.js");
+ const result = await injectDeterministicFontFaces(HTML, { fetchImpl: makeGoogleFetch() });
+
+ expect(result).toContain(VIET_RANGE);
+ expect(result).toContain(LATIN_RANGE);
+ // the latin bytes and the latin range belong to the same @font-face block
+ const faces = result.split("@font-face").filter((b) => b.includes("TestFam"));
+ const latinFace = faces.find((f) => f.includes(b64(LATIN_BYTES)));
+ expect(latinFace).toBeDefined();
+ expect(latinFace).toContain(LATIN_RANGE);
+ });
+});
diff --git a/packages/producer/src/services/deterministicFonts.ts b/packages/producer/src/services/deterministicFonts.ts
index 0dd0ebbb1b..27f2dbd397 100644
--- a/packages/producer/src/services/deterministicFonts.ts
+++ b/packages/producer/src/services/deterministicFonts.ts
@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { homedir, tmpdir } from "node:os";
import { join } from "node:path";
@@ -234,7 +235,13 @@ function extractRequestedFontFamilies(html: string): Map {
return requested;
}
-function buildFontFaceRule(familyName: string, src: string, weight: string, style: string): string {
+function buildFontFaceRule(
+ familyName: string,
+ src: string,
+ weight: string,
+ style: string,
+ unicodeRange?: string,
+): string {
return [
"@font-face {",
` font-family: "${familyName}";`,
@@ -242,6 +249,9 @@ function buildFontFaceRule(familyName: string, src: string, weight: string, styl
` font-style: ${style};`,
` font-weight: ${weight};`,
" font-display: block;",
+ // Preserve the subset's unicode-range so the browser selects the right
+ // per-codepoint subset (matching Google Fonts' own CSS semantics).
+ ...(unicodeRange ? [` unicode-range: ${unicodeRange};`] : []),
"}",
].join("\n");
}
@@ -278,11 +288,19 @@ async function buildFontFaceCss(
// if the bundle only ships 400/700/900.
const googleFaces = await fetchGoogleFont(originalCaseFamily, options);
for (const face of googleFaces) {
- const key = `${face.weight}:${face.style}`;
- if (!coveredWeights.has(key)) {
- rules.push(buildFontFaceRule(originalCaseFamily, face.dataUri, face.weight, face.style));
- coveredWeights.add(key);
- }
+ // A weight covered by the embedded bundle is already full-coverage —
+ // skip it. For weights the bundle lacks, add EVERY subset face (a
+ // weight has one face per unicode-range subset), not just the first.
+ if (coveredWeights.has(`${face.weight}:${face.style}`)) continue;
+ rules.push(
+ buildFontFaceRule(
+ originalCaseFamily,
+ face.dataUri,
+ face.weight,
+ face.style,
+ face.unicodeRange,
+ ),
+ );
}
continue;
}
@@ -291,7 +309,15 @@ async function buildFontFaceCss(
const googleFaces = await fetchGoogleFont(originalCaseFamily, options);
if (googleFaces.length > 0) {
for (const face of googleFaces) {
- rules.push(buildFontFaceRule(originalCaseFamily, face.dataUri, face.weight, face.style));
+ rules.push(
+ buildFontFaceRule(
+ originalCaseFamily,
+ face.dataUri,
+ face.weight,
+ face.style,
+ face.unicodeRange,
+ ),
+ );
}
continue;
}
@@ -363,14 +389,26 @@ function fontCacheDir(slug: string): string {
return dir;
}
-function cachedWoff2Path(slug: string, weight: string, style: string): string {
- return join(fontCacheDir(slug), `${weight}-${style}.woff2`);
+// A short, stable discriminator for a single subset's woff2. Google Fonts'
+// css2 API returns one @font-face per (weight × unicode-range subset) — e.g.
+// `vietnamese`, `latin-ext`, and `latin` faces for the SAME weight, each with
+// a distinct woff2 URL and glyph set. Keying the cache by weight+style alone
+// collides every subset onto one filename, so only the first subset in the
+// CSS gets downloaded and the rest read it back. Derive the cache key from the
+// (subset-unique, version-stable) woff2 URL so each subset is cached on its own.
+function subsetToken(woff2Url: string): string {
+ return createHash("sha1").update(woff2Url).digest("hex").slice(0, 12);
+}
+
+function cachedWoff2Path(slug: string, weight: string, style: string, subset: string): string {
+ return join(fontCacheDir(slug), `${weight}-${style}-${subset}.woff2`);
}
type GoogleFontFace = {
weight: string;
style: string;
dataUri: string;
+ unicodeRange?: string;
};
/**
@@ -428,6 +466,51 @@ function fontFetchError(
return new FontFetchError(familyName, url, message, "error" in cause ? cause.error : undefined);
}
+/**
+ * Ensure one subset's woff2 is cached on disk (downloading if absent) and
+ * return it as a `data:` URI. Returns `null` when the woff2 isn't served
+ * (4xx) so the caller skips that face. Throws {@link FontFetchError} on
+ * transient (5xx / network) failures when `failClosedFontFetch` is set.
+ */
+async function ensureWoff2DataUri(
+ cachePath: string,
+ woff2Url: string,
+ familyName: string,
+ weight: string,
+ style: string,
+ options: InternalFontFetchOptions,
+): Promise {
+ try {
+ return `data:font/woff2;base64,${readFileSync(cachePath).toString("base64")}`;
+ } catch {
+ // Not cached yet — fall through to fetch.
+ }
+
+ const woff2What = `Google Fonts woff2 (${weight}/${style})` as const;
+ try {
+ const fontRes = await options.fetchImpl(woff2Url);
+ if (!fontRes.ok) {
+ if (fontRes.status >= 500 && options.failClosedFontFetch) {
+ throw fontFetchError(familyName, woff2Url, woff2What, { status: fontRes.status });
+ }
+ return null;
+ }
+ // wx = O_CREAT|O_EXCL: atomic create, rejects symlinks, fails with
+ // EEXIST if a concurrent call cached it between our read and write.
+ writeFileSync(cachePath, Buffer.from(await fontRes.arrayBuffer()), { flag: "wx", mode: 0o644 });
+ } catch (err) {
+ if (err instanceof FontFetchError) throw err;
+ if ((err as NodeJS.ErrnoException).code === "EEXIST") {
+ // Concurrent call wrote it — read their result below.
+ } else if (options.failClosedFontFetch) {
+ throw fontFetchError(familyName, woff2Url, woff2What, { error: err });
+ } else {
+ return null;
+ }
+ }
+ return `data:font/woff2;base64,${readFileSync(cachePath).toString("base64")}`;
+}
+
async function fetchGoogleFont(
familyName: string,
options: InternalFontFetchOptions,
@@ -467,9 +550,12 @@ async function fetchGoogleFont(
return [];
}
- // Parse @font-face blocks from the CSS response
+ // Parse @font-face blocks from the CSS response. The optional trailing
+ // capture grabs each face's `unicode-range` (Google emits it after `src`)
+ // so the injected face only claims the codepoints the subset actually
+ // covers — without it the face would advertise full coverage it lacks.
const faceRegex =
- /@font-face\s*\{[^}]*font-style:\s*(normal|italic)[^}]*font-weight:\s*(\d+)[^}]*src:\s*url\(([^)]+)\)\s*format\(['"]woff2['"]\)[^}]*\}/gi;
+ /@font-face\s*\{[^}]*font-style:\s*(normal|italic)[^}]*font-weight:\s*(\d+)[^}]*src:\s*url\(([^)]+)\)\s*format\(['"]woff2['"]\)(?:[^}]*?unicode-range:\s*([^;}]+))?[^}]*\}/gi;
const faces: GoogleFontFace[] = [];
@@ -477,39 +563,20 @@ async function fetchGoogleFont(
const style = match[1] || "normal";
const weight = match[2] || "400";
const woff2Url = match[3] || "";
+ const unicodeRange = match[4]?.trim() || undefined;
if (!woff2Url) continue;
- const cachePath = cachedWoff2Path(slug, weight, style);
-
- // Check cache first
- if (!existsSync(cachePath)) {
- const woff2What = `Google Fonts woff2 (${weight}/${style})` as const;
- try {
- const fontRes = await options.fetchImpl(woff2Url);
- if (!fontRes.ok) {
- // Same 4xx vs 5xx split as the CSS fetch above: 4xx = the
- // font's woff2 isn't served, skip silently; 5xx = transient
- // upstream failure, may fail closed.
- if (fontRes.status >= 500 && options.failClosedFontFetch) {
- throw fontFetchError(familyName, woff2Url, woff2What, { status: fontRes.status });
- }
- continue;
- }
- const buffer = Buffer.from(await fontRes.arrayBuffer());
- writeFileSync(cachePath, buffer);
- } catch (err) {
- if (err instanceof FontFetchError) throw err;
- if (options.failClosedFontFetch) {
- throw fontFetchError(familyName, woff2Url, woff2What, { error: err });
- }
- continue;
- }
- }
-
- const fontBytes = readFileSync(cachePath);
- const dataUri = `data:font/woff2;base64,${fontBytes.toString("base64")}`;
- faces.push({ weight, style, dataUri });
+ const cachePath = cachedWoff2Path(slug, weight, style, subsetToken(woff2Url));
+ const dataUri = await ensureWoff2DataUri(
+ cachePath,
+ woff2Url,
+ familyName,
+ weight,
+ style,
+ options,
+ );
+ if (dataUri) faces.push({ weight, style, dataUri, unicodeRange });
}
if (faces.length > 0) {