Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
feat(fonts): record resolver stage diagnostics on fail-closed font errors (#5189)
Jerrai0c76e5244647
diff --git a/packages/core/src/fonts/deterministicFonts-diagnostics.test.ts b/packages/core/src/fonts/deterministicFonts-diagnostics.test.tsnew file mode 100644index 0000000000..8eeebce5fd--- /dev/null+++ b/packages/core/src/fonts/deterministicFonts-diagnostics.test.ts@@ -0,0 +1,455 @@+// @vitest-environment node++import { mkdtempSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { beforeEach, describe, expect, it, vi } from "vitest";+import {+ _clearGoogleFontCssCacheForTests,+ FONT_FETCH_FAILED,+ FONT_FETCH_UNAVAILABLE,+ FontFetchError,+ injectDeterministicFontFaces,+} from "./deterministicFonts.js";+import type { FontAttemptDiag, FontDiagnostics } from "./fontDiagnostics.js";++const FAMILY = "Bricolage Grotesque";+const PAGE_TEXT = "quick brown fox";+const PRIVATE_FAMILY = "PRIVATE_FONT_SENTINEL_7f3a";+const WOFF2 = new Uint8Array([0x77, 0x4f, 0x46, 0x32, 1, 2, 3]);++const block = (family = FAMILY, fmt = "woff2", n = 0): string =>+ `/* latin */\n@font-face {\n font-family: '${family}';\n font-style: normal;\n font-weight: 200 800;\n src: url(https://fonts.gstatic.com/s/b/v9/f${n}.woff2) format('${fmt}');\n unicode-range: U+0000-00FF;\n}\n`;+const blocks = (count: number, family = FAMILY, fmt = "woff2"): string =>+ Array.from({ length: count }, (_, n) => block(family, fmt, n)).join("\n");+const urlLessBlocks = `/* latin */\n@font-face {\n font-family: '${FAMILY}';\n font-style: normal;\n font-weight: 200 800;\n unicode-range: U+0000-00FF;\n}\n/* latin-ext */\n@font-face {\n font-family: '${FAMILY}';\n font-style: normal;\n font-weight: 200 800;\n}\n`;++type Rule = (url: string) => Response | Promise<Response>;+interface Stub {+ css: string[];+ woff2: string[];+ fetchImpl: typeof fetch;+}+const status = (code: number): Response => new Response("x", { status: code });+const ok = (body: string): Response => new Response(body, { status: 200 });+function stub(css: Rule, woff: Rule = () => new Response(WOFF2, { status: 200 })): Stub {+ const cssUrls: string[] = [];+ const woff2Urls: string[] = [];+ const fetchImpl: typeof fetch = async (input) => {+ const url = String(input);+ if (url.startsWith("https://fonts.gstatic.com/")) {+ woff2Urls.push(url);+ return woff(url);+ }+ cssUrls.push(url);+ return css(url);+ };+ return { css: cssUrls, woff2: woff2Urls, fetchImpl };+}++const POLICY = { maxAttempts: 2, baseDelayMs: 0, attemptTimeoutMs: 2000, maxElapsedMs: 8000 };+const page = (extraCss = ""): string =>+ `<!doctype html><html><head><style>.a{font-family:'${FAMILY}',sans-serif;font-weight:700}${extraCss}</style></head><body><p class="a">The ${PAGE_TEXT} jumps.</p></body></html>`;++async function fail(html: string, s: Stub, abortSignal?: AbortSignal): Promise<FontFetchError> {+ try {+ await injectDeterministicFontFaces(html, {+ failClosedFontFetch: true,+ allowSystemFontCapture: false,+ fetchImpl: s.fetchImpl,+ abortSignal,+ fontFetchRetryPolicy: POLICY,+ logger: { info: () => undefined, warn: () => undefined },+ });+ } catch (err) {+ if (err instanceof FontFetchError) return err;+ throw err;+ }+ throw new Error("expected FontFetchError");+}++function diagnosticsOf(e: FontFetchError): FontDiagnostics {+ if (!e.diagnostics) throw new Error("expected diagnostics");+ return e.diagnostics;+}++const attempt = (o: Partial<FontAttemptDiag> = {}): FontAttemptDiag => ({+ path: "direct_google",+ urlSource: "default",+ textParam: "present",+ cssCache: "fresh",+ cssStatus: 200,+ blocksTotal: 0,+ regexMatches: 0,+ assets: { total: 0, diskCacheHit: 0, fetchedOk: 0, nonOk: {} },+ ...o,+});+const diagOf = (attempts: FontAttemptDiag[]): FontDiagnostics => ({+ families: [{ required: true, resolved: false, attempts }],+});++beforeEach(() => {+ process.env.HYPERFRAMES_FONT_CACHE_DIR = mkdtempSync(join(tmpdir(), "hf-dp-cache-"));+ _clearGoogleFontCssCacheForTests();+});++const ROWS: Array<{ name: string; css: Rule; woff?: Rule; expected: FontAttemptDiag }> = [+ { name: "CSS 400", css: () => status(400), expected: attempt({ cssStatus: 400 }) },+ {+ name: "CSS 204 empty body keeps the real status",+ css: () => new Response(null, { status: 204 }),+ expected: attempt({ cssStatus: 204 }),+ },+ {+ name: "CSS 206 empty body keeps the real status",+ css: () => new Response("", { status: 206 }),+ expected: attempt({ cssStatus: 206 }),+ },+ {+ name: "CSS 304 keeps the real status",+ css: () => new Response(null, { status: 304 }),+ expected: attempt({ cssStatus: 304 }),+ },+ {+ name: "CSS 200 zero regex matches (woff2-variations label)",+ css: () => ok(blocks(2, FAMILY, "woff2-variations")),+ expected: attempt({ blocksTotal: 2 }),+ },+ {+ name: "CSS 200 blocks without a url",+ css: () => ok(urlLessBlocks),+ expected: attempt({ blocksTotal: 2 }),+ },+ {+ name: "CSS 200 all faces dropped by the family filter",+ css: () => ok(blocks(2, "DM Sans")),+ expected: attempt({ blocksTotal: 2, regexMatches: 2 }),+ },+ {+ name: "CSS ok, all woff2 404",+ css: () => ok(blocks(3)),+ woff: () => status(404),+ expected: attempt({+ blocksTotal: 3,+ regexMatches: 3,+ assets: { total: 3, diskCacheHit: 0, fetchedOk: 0, nonOk: { "404": 3 } },+ }),+ },+];++describe("exact attempt record on the Unresolved error", () => {+ for (const { name, css, woff, expected } of ROWS) {+ it(name, async () => {+ const e = await fail(page(), stub(css, woff));+ expect(e.diagnostics).toEqual(diagOf([expected]));+ });+ }++ it("leaves the pre-existing error contract unchanged", async () => {+ const e = await fail(+ page(),+ stub(() => status(400)),+ );+ expect(e.message).toBe(+ `[Compiler] Unresolved fonts in fail-closed mode: ${FAMILY}. Distributed renders require all fonts to be resolvable.`,+ );+ expect(e.code).toBe(FONT_FETCH_FAILED);+ expect(e.name).toBe("FontFetchError");+ expect(e.familyName).toBe(FAMILY);+ expect(e.unresolvedFamilies).toEqual([FAMILY]);+ });++ it("a cached second failure records a cache hit with the retained status and no new request", async () => {+ const s = stub(() => status(400));+ const e1 = await fail(page(), s);+ const e2 = await fail(page(), s);+ expect(s.css.length).toBe(1);+ expect(e1.diagnostics).toEqual(diagOf([attempt({ cssStatus: 400, cssCache: "fresh" })]));+ expect(e2.diagnostics).toEqual(diagOf([attempt({ cssStatus: 400, cssCache: "hit" })]));+ });+});++describe("shared CSS lookups", () => {+ it("concurrent compiles each record their own attempt: one fresh, one hit, one upstream request", async () => {+ const s = stub(async () => {+ await new Promise((r) => setTimeout(r, 25));+ return status(400);+ });+ const [e1, e2] = await Promise.all([fail(page(), s), fail(page(), s)]);+ expect(s.css.length).toBe(1);+ const caches = [e1, e2].map((e) => diagnosticsOf(e).families[0]?.attempts[0]?.cssCache);+ expect(caches.sort()).toEqual(["fresh", "hit"]);+ for (const e of [e1, e2]) {+ expect(diagnosticsOf(e).families[0]?.attempts[0]?.cssStatus).toBe(400);+ }+ });++ it("a retryable 503 keeps its UNAVAILABLE error and carries no diagnostics", async () => {+ const s = stub(async () => {+ await new Promise((r) => setTimeout(r, 25));+ return status(503);+ });+ const errors = await Promise.all([fail(page(), s), fail(page(), s)]);+ for (const e of errors) {+ expect(e.code).toBe(FONT_FETCH_UNAVAILABLE);+ expect(e.name).toBe("FontFetchUnavailableError");+ expect(e.diagnostics).toBeUndefined();+ }+ });+});++describe("families", () => {+ it("lists every family in resolver order with its required and resolved flags", async () => {+ const html = page(+ ".b{font-family:var(--none, 'Zzz Example')}.i{font-family:'Inter',sans-serif}",+ );+ const e = await fail(+ html,+ stub(() => status(400)),+ );+ const families = diagnosticsOf(e).families;+ expect(families.map((f) => [f.required, f.resolved])).toEqual([+ [true, false],+ [true, true],+ [false, false],+ ]);+ expect(families[0]?.attempts[0]?.path).toBe("direct_google");+ expect(families[1]?.attempts[0]?.path).toBe("bundled_supplement");+ });++ it("carries flags in resolver order while unresolvedFamilies stays sorted by name", async () => {+ const html = `<!doctype html><html><head><style>.z{font-family:'Zzz Required Font',sans-serif}.i{font-family:'Inter',sans-serif}.o{font-family:var(--none, 'Aaa Optional Font')}</style></head><body><p class="z i o">${PAGE_TEXT}</p></body></html>`;+ const e = await fail(+ html,+ stub(() => status(400)),+ );+ expect(diagnosticsOf(e).families.map((f) => [f.required, f.resolved])).toEqual([+ [true, false],+ [true, true],+ [false, false],+ ]);+ expect(e.message).toBe(+ "[Compiler] Unresolved fonts in fail-closed mode: Zzz Required Font. Distributed renders require all fonts to be resolvable.",+ );+ expect(e.code).toBe(FONT_FETCH_FAILED);+ expect(e.familyName).toBe("Zzz Required Font");+ expect(e.unresolvedFamilies).toEqual(["Aaa Optional Font", "Zzz Required Font"]);+ expect(JSON.stringify(e.diagnostics)).not.toMatch(/Aaa|Zzz/);+ });++ it("two required families failing at different stages stay indistinguishable by name", async () => {+ const html = `<!doctype html><html><head><style>.z{font-family:'Zzz Required Font',sans-serif}.a{font-family:'Aaa Required Font',sans-serif}</style></head><body><p class="z a">${PAGE_TEXT}</p></body></html>`;+ const e = await fail(+ html,+ stub((url) =>+ url.includes("Aaa") ? status(400) : ok(blocks(2, FAMILY, "woff2-variations")),+ ),+ );+ const families = diagnosticsOf(e).families;+ expect(families.map((f) => [f.required, f.resolved])).toEqual([+ [true, false],+ [true, false],+ ]);+ const [first, second] = families.map((f) => f.attempts[0]);+ expect(first).toEqual(attempt({ blocksTotal: 2 }));+ expect(second).toEqual(attempt({ cssStatus: 400 }));+ expect({ ...first, blocksTotal: 0, cssStatus: 400 }).toEqual(second);+ // The payload cannot say which family produced which attempt.+ expect(e.message).toBe(+ "[Compiler] Unresolved fonts in fail-closed mode: Aaa Required Font, Zzz Required Font. Distributed renders require all fonts to be resolvable.",+ );+ expect(e.unresolvedFamilies).toEqual(["Aaa Required Font", "Zzz Required Font"]);+ expect(JSON.stringify(e.diagnostics)).not.toMatch(/Aaa|Zzz/);+ });+});++describe("authored stylesheet falling back to the default request", () => {+ const AUTHORED = "Zorblax Display";+ const OTHER = "Quillmark Serif";+ const LINK = `https://fonts.googleapis.com/css2?family=${AUTHORED.replace(" ", "+")}:wght@400;700&display=swap`;+ const authoredPage = (extraFamily = ""): string =>+ `<!doctype html><html><head><link rel="stylesheet" href="${LINK}"><style>.a{font-family:'${AUTHORED}',sans-serif}${extraFamily}</style></head><body><p class="a o">The ${PAGE_TEXT} jumps.</p></body></html>`;+ const isDefault = (url: string): boolean => url.includes("ital,wght@");+ const authoredAttempt = (o: Partial<FontAttemptDiag> = {}): FontAttemptDiag =>+ attempt({ urlSource: "authored", ...o });++ it("records the rejected authored stylesheet and then the default attempt that found no usable file", async () => {+ const e = await fail(+ authoredPage(),+ stub(+ (url) => (isDefault(url) ? ok(blocks(1, AUTHORED)) : status(400)),+ () => status(404),+ ),+ );+ expect(diagnosticsOf(e).families).toEqual([+ {+ required: true,+ resolved: false,+ attempts: [+ authoredAttempt({ cssStatus: 400 }),+ attempt({+ blocksTotal: 1,+ regexMatches: 1,+ assets: { total: 1, diskCacheHit: 0, fetchedOk: 0, nonOk: { "404": 1 } },+ }),+ ],+ },+ ]);+ });++ it("records an authored 200 with zero faces and then the default attempt", async () => {+ const e = await fail(+ authoredPage(),+ stub((url) => (isDefault(url) ? status(400) : ok(blocks(2, AUTHORED, "woff2-variations")))),+ );+ expect(diagnosticsOf(e).families[0]?.attempts).toEqual([+ authoredAttempt({ blocksTotal: 2 }),+ attempt({ cssStatus: 400 }),+ ]);+ });++ it("records no default attempt for a family whose authored stylesheet worked", async () => {+ const s = stub((url) => {+ if (url.includes("Quillmark")) return status(400);+ return ok(blocks(1, AUTHORED));+ });+ const e = await fail(authoredPage(`.o{font-family:'${OTHER}',serif}`), s);+ expect(diagnosticsOf(e).families).toEqual([+ {+ required: true,+ resolved: true,+ attempts: [+ authoredAttempt({+ blocksTotal: 1,+ regexMatches: 1,+ assets: { total: 1, diskCacheHit: 0, fetchedOk: 1, nonOk: {} },+ }),+ ],+ },+ { required: true, resolved: false, attempts: [attempt({ cssStatus: 400 })] },+ ]);+ expect(s.css.filter((url) => isDefault(url) && url.includes("Zorblax"))).toEqual([]);+ });++ it("keeps a transient UNAVAILABLE exactly as before: no default request, no diagnostics", async () => {+ const s = stub(() => status(503));+ const e = await fail(authoredPage(), s);+ expect(e.code).toBe(FONT_FETCH_UNAVAILABLE);+ expect(e.name).toBe("FontFetchUnavailableError");+ expect(e.diagnostics).toBeUndefined();+ expect(s.css.some(isDefault)).toBe(false);+ });++ it("records both attempts when the authored and default requests both fail, with the error contract unchanged", async () => {+ const e = await fail(+ authoredPage(),+ stub(() => status(400)),+ );+ expect(diagnosticsOf(e).families[0]?.attempts).toEqual([+ authoredAttempt({ cssStatus: 400 }),+ attempt({ cssStatus: 400 }),+ ]);+ expect(e.message).toBe(+ `[Compiler] Unresolved fonts in fail-closed mode: ${AUTHORED}. Distributed renders require all fonts to be resolvable.`,+ );+ expect(e.code).toBe(FONT_FETCH_FAILED);+ expect(e.name).toBe("FontFetchError");+ expect(e.familyName).toBe(AUTHORED);+ expect(e.unresolvedFamilies).toEqual([AUTHORED]);+ expect(e.url).toBe("");+ expect(e.cause).toBeUndefined();+ });++ it("labels both attempts of a repeated compile as cache hits while the first compile's are fresh", async () => {+ const s = stub(() => status(400));+ const first = await fail(authoredPage(), s);+ const second = await fail(authoredPage(), s);+ expect(s.css.length).toBe(2);+ expect(diagnosticsOf(first).families[0]?.attempts).toEqual([+ authoredAttempt({ cssStatus: 400, cssCache: "fresh" }),+ attempt({ cssStatus: 400, cssCache: "fresh" }),+ ]);+ expect(diagnosticsOf(second).families[0]?.attempts).toEqual([+ authoredAttempt({ cssStatus: 400, cssCache: "hit" }),+ attempt({ cssStatus: 400, cssCache: "hit" }),+ ]);+ });+});++describe("a lookup joined while another compile's request is in flight", () => {+ const REQUIRED = "Quillmark Serif";+ const OPTIONAL = "Zorblax Display";+ const html = `<!doctype html><html><head><style>.r{font-family:'${REQUIRED}',serif}.o{font-family:var(--none, '${OPTIONAL}')}</style></head><body><p class="r o">The ${PAGE_TEXT} jumps.</p></body></html>`;+ const drain = (): Promise<void> => new Promise((resolve) => setImmediate(resolve));+ const until = async (done: () => boolean, what: string): Promise<void> => {+ for (let turn = 0; turn < 200 && !done(); turn += 1) await drain();+ if (!done()) throw new Error(`timed out waiting for ${what}`);+ };++ it("labels the joiner's swallowed optional lookup as a hit with no status", async () => {+ let release: () => void = () => undefined;+ const gate = new Promise<void>((resolve) => {+ release = resolve;+ });+ let optionalRequests = 0;+ const s = stub(async (url) => {+ if (!url.includes("Zorblax")) return status(400);+ optionalRequests += 1;+ if (optionalRequests === 1) await gate;+ return status(503);+ });+ // A lookup that awaits a shared promise registers an abort listener on its caller's signal, so+ // the second compile's listener count shows when it has reached the optional family's lookup.+ const joiner = new AbortController();+ const joinerListeners = vi.spyOn(joiner.signal, "addEventListener");+ try {+ const first = fail(html, s);+ await until(() => optionalRequests === 1, "the first compile's optional request");+ const second = fail(html, s, joiner.signal);+ await until(+ () => joinerListeners.mock.calls.length >= 2,+ "the second compile to await the optional lookup",+ );+ expect(optionalRequests).toBe(1);+ release();+ const errors = await Promise.all([first, second]);++ expect(optionalRequests).toBe(POLICY.maxAttempts);+ const optional = errors.map((e) => diagnosticsOf(e).families[1]);+ expect(optional.map((f) => [f?.required, f?.resolved, f?.attempts.length])).toEqual([+ [false, false, 1],+ [false, false, 1],+ ]);+ expect(optional.map((f) => f?.attempts[0]?.cssCache)).toEqual(["fresh", "hit"]);+ expect(optional.map((f) => f?.attempts[0]?.cssStatus)).toEqual([null, null]);+ for (const e of errors) {+ expect(e.code).toBe(FONT_FETCH_FAILED);+ expect(e.message).toBe(+ `[Compiler] Unresolved fonts in fail-closed mode: ${REQUIRED}. Distributed renders require all fonts to be resolvable.`,+ );+ expect(e.url).toBe("");+ expect(e.cause).toBeUndefined();+ }+ } finally {+ release();+ }+ });+});++describe("leak check", () => {+ for (const { name, css, woff } of ROWS) {+ it(`${name}: no family name, URL, CSS, page text or hash in the serialized diagnostics`, async () => {+ const e = await fail(+ page(`.b{font-family:var(--n, '${PRIVATE_FAMILY}')}.d{font-family:'${PAGE_TEXT} jumps'}`),+ stub(css, woff),+ );+ const json = JSON.stringify(e.diagnostics);+ expect(json).not.toMatch(+ /https?:|gstatic|googleapis|font-face|\.woff2|text=|src:|%[0-9A-Fa-f]{2}|unicode-range|base64|"family"/i,+ );+ for (const secret of [FAMILY, PRIVATE_FAMILY, PAGE_TEXT]) {+ expect(json).not.toContain(secret);+ }+ });+ }+});diff --git a/packages/core/src/fonts/deterministicFonts.ts b/packages/core/src/fonts/deterministicFonts.tsindex 8f39998c8e..fbc5be4577 100644--- a/packages/core/src/fonts/deterministicFonts.ts+++ b/packages/core/src/fonts/deterministicFonts.ts@@ -10,6 +10,15 @@ import postcss, { type AtRule, type Declaration, type Rule } from "postcss";import { EMBEDDED_FONT_DATA } from "./fontData.generated.js";import { fontToDataUri } from "./fontCompression.js";import { authoredGoogleFontStylesheets, withPageText } from "./authoredGoogleFonts.js";+import {+ FontDiagCollector,+ type FontAssetDiag,+ type FontAttemptDiag,+ type FontDiagnostics,+ type FontDiagPath,+} from "./fontDiagnostics.js";++export type { FontDiagnostics };type FontFaceSpec = {weight: string;@@ -697,7 +706,7 @@ async function bundledFamilyFaceRules(// `emitFamily` so the authored CSS keeps matching.const canonicalFamily = resolveAliasDisplayName(normalizedFamily);const googleFaces = canonicalFamily- ? await fetchFamilyFaces(canonicalFamily, optional, options, fontText)+ ? await fetchFamilyFaces(canonicalFamily, "bundled_supplement", optional, options, fontText): [];// Bundled weights only cover Latin. Keep other subsets (including@@ -738,7 +747,13 @@ async function googleFamilyFaceRules(options: InternalFontFetchOptions,fontText?: string,): Promise<string[] | null> {- const googleFaces = await fetchFamilyFaces(lookupFamily, optional, options, fontText);+ const googleFaces = await fetchFamilyFaces(+ lookupFamily,+ "direct_google",+ optional,+ options,+ fontText,+ );if (googleFaces.length === 0) return null;return googleFaces.map((face) =>buildFontFaceRule(emitFamily, face.dataUri, face.weight, face.style, face.unicodeRange),@@ -1011,6 +1026,7 @@ async function buildFontFaceCss(([, a], [, b]) => Number(a.optional) - Number(b.optional),);for (const [normalizedFamily, { family: originalCaseFamily, optional }] of requiredFirst) {+ options.diag.beginFamily(!optional);const familyRules =(await resolveFamilyFaceRules(normalizedFamily,@@ -1028,6 +1044,7 @@ async function buildFontFaceCss(options,fontText,));+ options.diag.endFamily(Boolean(familyRules));if (familyRules) {rules.push(...familyRules);continue;@@ -1161,6 +1178,11 @@ export class FontFetchError extends Error {readonly cause?: unknown;/** Unlike `message`, holds no URLs: safe for callers that must not echo resolver output. */readonly unresolvedFamilies: readonly string[];+ /**+ * Resolver stage record for log forwarding. Set ONLY on the per-compile Unresolved error; shared+ * (cached or retry-exhausted) errors are never mutated. Never part of `message` or any response body.+ */+ declare diagnostics?: FontDiagnostics;constructor(familyName: string,@@ -1220,6 +1242,7 @@ interface InternalFontFetchOptions {retryDeadlineMs: number;/** Google stylesheet URL the page already wrote, keyed by normalized family name. */authoredStylesheets: ReadonlyMap<string, readonly string[]>;+ diag: FontDiagCollector;}/**@@ -1399,9 +1422,13 @@ async function ensureWoff2DataUri(weight: string,style: string,options: InternalFontFetchOptions,+ tally: FontAssetDiag,): Promise<string | null> {+ tally.total += 1;try {- return `data:font/woff2;base64,${readFileSync(cachePath).toString("base64")}`;+ const cached = `data:font/woff2;base64,${readFileSync(cachePath).toString("base64")}`;+ tally.diskCacheHit += 1;+ return cached;} catch {// Not cached yet — fall through to fetch.}@@ -1416,15 +1443,21 @@ async function ensureWoff2DataUri(woff2What,options,);- if (!fontResult.ok) return null;+ if (!fontResult.ok) {+ const status = String(fontResult.response.status);+ tally.nonOk[status] = (tally.nonOk[status] ?? 0) + 1;+ 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(fontResult.body), { flag: "wx", mode: 0o644 });+ tally.fetchedOk += 1;} catch (err) {throwIfCallerAborted(options.abortSignal);if (err instanceof FontFetchError) throw err;if ((err as NodeJS.ErrnoException).code === "EEXIST") {// Concurrent call wrote it — read their result below.+ tally.diskCacheHit += 1;} else if (options.failClosedFontFetch) {throw fontFetchError(familyName, woff2Url, woff2What, { error: err });} else {@@ -1437,7 +1470,9 @@ async function ensureWoff2DataUri(// Per-process cache for Google Fonts CSS lookups, keyed by request URL —// repeat compiles of the same family reuse one network round trip. A// rejected lookup evicts itself so a later call still retries.-type GoogleFontCssResult = { ok: true; body: string } | { ok: false; status: number };+type GoogleFontCssResult =+ | { ok: true; body: string; status: number }+ | { ok: false; status: number };const googleFontCssCache = new Map<string, Promise<GoogleFontCssResult>>();@@ -1461,11 +1496,13 @@ function fetchGoogleFontCss(url: string,familyName: string,options: InternalFontFetchOptions,+ attempt: FontAttemptDiag,): Promise<GoogleFontCssResult> {// Retries decide the outcome, so only callers with the same mode and attempt count share an entry.const mode = options.failClosedFontFetch ? `closed${options.retryPolicy.maxAttempts}` : "open";const key = `${mode}:${url}`;let shared = googleFontCssCache.get(key);+ attempt.cssCache = shared ? "hit" : "fresh";if (!shared) {// The shared fetch must not carry any one caller's abortSignal, or that// caller cancelling would fail the lookup for every other waiter.@@ -1477,7 +1514,8 @@ function fetchGoogleFontCss("Google Fonts CSS",{ ...options, abortSignal: undefined },).then((result) => {- if (result.ok) return { ok: true as const, body: result.body };+ if (result.ok)+ return { ok: true as const, body: result.body, status: result.response.status };// A transient status must not stick for the process lifetime.if (isRetryableFontFetchStatus(result.response.status)) googleFontCssCache.delete(key);return { ok: false as const, status: result.response.status };@@ -1500,6 +1538,7 @@ function declaredFaceFamily(block: string): string | undefined {// fallow-ignore-next-line complexityasync function fetchGoogleFont(familyName: string,+ path: FontDiagPath,options: InternalFontFetchOptions,fontText?: string,): Promise<GoogleFontFace[]> {@@ -1521,23 +1560,26 @@ async function fetchGoogleFont(// `text=` asks Google for only the characters on the page. A CJK family// without it is a hundred files, and the compile's font budget is 20s.const defaultUrl = `https://fonts.googleapis.com/css2?family=${encodedFamily}:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;0,800;0,900;1,400;1,700${textParam}`;+ const fetchStylesheet = (url: string, urlSource: FontAttemptDiag["urlSource"]) =>+ fetchGoogleFontStylesheet(+ googleFamilyName,+ url,+ options,+ options.diag.startAttempt(path, urlSource, /[?&]text=/.test(url) ? "present" : "absent"),+ );if (!authoredStylesheet) {- return (await fetchGoogleFontStylesheet(googleFamilyName, defaultUrl, options)).faces;+ return (await fetchStylesheet(defaultUrl, "default")).faces;}const faces: GoogleFontFace[] = [];const outcomes: string[] = [];for (const url of authoredStylesheet) {- const result = await fetchGoogleFontStylesheet(- googleFamilyName,- withPageText(url, fontText),- options,- );+ const result = await fetchStylesheet(withPageText(url, fontText), "authored");faces.push(...result.faces);if (result.faces.length === 0)outcomes.push(result.status ? `http_${result.status}` : "no_faces");}if (faces.length > 0) return faces;- const fallback = (await fetchGoogleFontStylesheet(googleFamilyName, defaultUrl, options)).faces;+ const fallback = (await fetchStylesheet(defaultUrl, "default")).faces;options.log.warn(`[Compiler] google_font_link_fallback family="${familyName}" link_outcomes=${outcomes.join(",")} ` +`fallback_faces=${fallback.length}`,@@ -1551,9 +1593,11 @@ async function readGoogleFontStylesheet(familyName: string,url: string,options: InternalFontFetchOptions,+ attempt: FontAttemptDiag,): Promise<GoogleFontStylesheetRead> {try {- const cssResult = await fetchGoogleFontCss(url, familyName, options);+ const cssResult = await fetchGoogleFontCss(url, familyName, options, attempt);+ attempt.cssStatus = cssResult.status;if (!cssResult.ok) {// Missing families are deterministic; transient failures follow the// caller's retry and fail-closed policy.@@ -1595,11 +1639,13 @@ async function fetchGoogleFontStylesheet(familyName: string,url: string,options: InternalFontFetchOptions,+ attempt: FontAttemptDiag,): Promise<{ faces: GoogleFontFace[]; status?: number }> {const slug = fontSlug(familyName);- const read = await readGoogleFontStylesheet(familyName, url, options);+ const read = await readGoogleFontStylesheet(familyName, url, options, attempt);if (read.css === null) return { faces: [], status: read.status };const cssText = read.css;+ attempt.blocksTotal = (cssText.match(/@font-face\s*\{/gi) ?? []).length;// Parse @font-face blocks from the CSS response. The optional trailing// capture grabs each face's `unicode-range` (Google emits it after `src`)@@ -1613,6 +1659,7 @@ async function fetchGoogleFontStylesheet(const faces: GoogleFontFace[] = [];for (const match of cssText.matchAll(faceRegex)) {+ attempt.regexMatches += 1;const source = parseGoogleFontSource(match, familyName);if (!source) continue;const { weight, style, unicodeRange, url: woff2Url } = source;@@ -1625,6 +1672,7 @@ async function fetchGoogleFontStylesheet(weight,style,options,+ attempt.assets,);if (dataUri) faces.push({ weight, style, dataUri, unicodeRange });}@@ -1641,15 +1689,17 @@ async function fetchGoogleFontStylesheet(/** An optional family gets one retry on a transient failure, then renders its fallback with a warning. */async function fetchFamilyFaces(familyName: string,+ path: FontDiagPath,optional: boolean,options: InternalFontFetchOptions,fontText?: string,): Promise<GoogleFontFace[]> {- if (!optional) return fetchGoogleFont(familyName, options, fontText);+ if (!optional) return fetchGoogleFont(familyName, path, options, fontText);const maxAttempts = Math.min(options.retryPolicy.maxAttempts, 2);try {return await fetchGoogleFont(familyName,+ path,{ ...options, retryPolicy: { ...options.retryPolicy, maxAttempts } },fontText,);@@ -1886,6 +1936,7 @@ export async function injectDeterministicFontFaces(html: string,options: InjectDeterministicFontFacesOptions = {},): Promise<string> {+ const diag = new FontDiagCollector();const failClosedFontFetch = options.failClosedFontFetch === true;const fetchImpl = options.fetchImpl ?? fetch;const allowSystemFontCapture = options.allowSystemFontCapture !== false;@@ -1899,6 +1950,7 @@ export async function injectDeterministicFontFaces(retryPolicy,retryDeadlineMs: Date.now() + retryPolicy.maxElapsedMs,authoredStylesheets: authoredGoogleFontStylesheets(html),+ diag,};const existingFaces = extractExistingFontFaces(html);@@ -1927,7 +1979,7 @@ export async function injectDeterministicFontFaces((family) => !pendingFamilies.get(family.toLowerCase())?.optional,);if (required.length > 0 && options.failClosedFontFetch) {- throw new FontFetchError(+ const unresolvedError = new FontFetchError(required.join(", "),"",`[Compiler] Unresolved fonts in fail-closed mode: ${required.join(", ")}. ` +@@ -1936,6 +1988,8 @@ export async function injectDeterministicFontFaces(FONT_FETCH_FAILED,unresolved,);+ unresolvedError.diagnostics = diag.snapshot();+ throw unresolvedError;}if (!css) {if (unresolved.length > 0) {diff --git a/packages/core/src/fonts/fontDiagnostics.ts b/packages/core/src/fonts/fontDiagnostics.tsnew file mode 100644index 0000000000..a16cad2917--- /dev/null+++ b/packages/core/src/fonts/fontDiagnostics.ts@@ -0,0 +1,70 @@+export type FontDiagPath = "bundled_supplement" | "direct_google";++export interface FontAssetDiag {+ total: number;+ diskCacheHit: number;+ fetchedOk: number;+ nonOk: Record<string, number>;+}++export interface FontAttemptDiag {+ path: FontDiagPath;+ urlSource: "authored" | "default";+ textParam: "present" | "absent";+ cssCache: "hit" | "fresh";+ /** The real HTTP status of the CSS lookup; null when no HTTP response was recorded for that attempt. */+ cssStatus: number | null;+ /** blocksTotal > 0 with regexMatches 0 is a coarse stage: no block had a woff2 url in the expected shape. */+ blocksTotal: number;+ regexMatches: number;+ assets: FontAssetDiag;+}++export interface FontFamilyDiag {+ required: boolean;+ resolved: boolean;+ attempts: FontAttemptDiag[];+}++/** Resolver stage record, in resolver family order. Enums, counts and HTTP statuses only: no names, URLs or text. */+export interface FontDiagnostics {+ families: FontFamilyDiag[];+}++export class FontDiagCollector {+ private readonly families: FontFamilyDiag[] = [];+ private current: FontFamilyDiag | undefined;++ beginFamily(required: boolean): void {+ this.current = { required, resolved: false, attempts: [] };+ this.families.push(this.current);+ }++ endFamily(resolved: boolean): void {+ if (this.current) this.current.resolved = resolved;+ this.current = undefined;+ }++ startAttempt(+ path: FontDiagPath,+ urlSource: FontAttemptDiag["urlSource"],+ textParam: FontAttemptDiag["textParam"],+ ): FontAttemptDiag {+ const attempt: FontAttemptDiag = {+ path,+ urlSource,+ textParam,+ cssCache: "fresh",+ cssStatus: null,+ blocksTotal: 0,+ regexMatches: 0,+ assets: { total: 0, diskCacheHit: 0, fetchedOk: 0, nonOk: {} },+ };+ this.current?.attempts.push(attempt);+ return attempt;+ }++ snapshot(): FontDiagnostics {+ return { families: this.families };+ }+}