Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
fix(branding): name the font each stack renders, not its fallbacks or a builder's alias (#5555)
Abimael Martellc4fe71b2372e
diff --git a/apps/api/src/__tests__/lib/branding/jev.test.ts b/apps/api/src/__tests__/lib/branding/jev.test.tsindex a4af6b287..c71116582 100644--- a/apps/api/src/__tests__/lib/branding/jev.test.ts+++ b/apps/api/src/__tests__/lib/branding/jev.test.ts@@ -1324,6 +1324,46 @@ describe("Jev request building", () => {expect(describeColor("#1A73E8")).toBe("vivid blue");});+ it("names the family a stack renders, not its alias or its system fallbacks", () => {+ // Wix serves a licensed face under a per-site alias and keeps the real+ // name further down the stack.+ expect(+ cleanFontFamily(+ "wfont_2feeec_e1b10df92bd244baba1e35d632c6fa41, wf_e1b10df92bd244baba1e35d63, orig_libre_baskerville",+ ),+ ).toBe("Libre Baskerville");+ expect(cleanFontFamily("wf_38b82f6a99a44d63a0bc6a5d605011dd")).toBeUndefined();+ // Monotype spellings on Wix.+ expect(cleanFontFamily("helvetica-w01-roman")).toBe("Helvetica");+ expect(cleanFontFamily("open-sans-v2, sans-serif")).toBe("Open Sans");+ expect(cleanFontFamily("futura-lt-w01-book")).toBe("Futura");+ expect(cleanFontFamily("proxima-n-w01-reg")).toBe("Proxima Nova");+ expect(cleanFontFamily("dinneuzeitgroteskltw01-_812426")).toBe("DIN Neuzeit Grotesk");+ // Self-hosted builds and a weight glued onto a lowercase alias.+ expect(cleanFontFamily("inter-variable-web")).toBe("Inter");+ expect(cleanFontFamily("recoleta-web, Georgia, serif")).toBe("Recoleta");+ expect(cleanFontFamily("orig_graphikextralight")).toBe("Graphik");+ expect(cleanFontFamily("Cooper Black")).toBe("Cooper Black");+ // A weight alone is still no family, and a known family is matched+ // once its glued weight is gone.+ expect(cleanFontFamily("semibold")).toBeUndefined();+ expect(cleanFontFamily("proximanovabold")).toBe("Proxima Nova");+ // Non-Latin faces are families too, and title case works past ASCII.+ expect(cleanFontFamily("思源黑体, sans-serif")).toBe("思源黑体");+ expect(cleanFontFamily("über grotesk")).toBe("Über Grotesk");+ // A system stack asks for the visitor's font: Segoe UI and Roboto are+ // its spellings per platform, not the brand's choice.+ expect(+ cleanFontFamily("-apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif"),+ ).toBeUndefined();+ expect(cleanFontFamily("system-ui, sans-serif")).toBeUndefined();+ // A real face ahead of the system stack is still that face (hyphenated+ // self-hosted names keep their spelling).+ expect(+ cleanFontFamily("Salesforce-Sans, system-ui, -apple-system, Segoe UI"),+ ).toBe("Salesforce-Sans");+ });+it("cleans font names in code", () => {expect(cleanFontFamily("__Roboto_Mono_c8ca7d")).toBe("Roboto Mono");expect(cleanFontFamily("__suisse_6d5c28")).toBe("Suisse");diff --git a/apps/api/src/__tests__/lib/branding/processor-fonts.test.ts b/apps/api/src/__tests__/lib/branding/processor-fonts.test.tsnew file mode 100644index 000000000..77e362db1--- /dev/null+++ b/apps/api/src/__tests__/lib/branding/processor-fonts.test.ts@@ -0,0 +1,124 @@+import { describe, expect, it } from "vitest";+import { processRawBranding } from "../../../lib/branding/processor";++const snap = (fontStack: string[], text = "Some text") => ({+ tag: "p",+ classes: "",+ text,+ rect: { w: 600, h: 24 },+ position: { top: 300, left: 0 },+ visible: true,+ colors: {+ text: "rgb(20, 20, 20)",+ background: "rgba(0, 0, 0, 0)",+ border: "rgba(0, 0, 0, 0)",+ borderWidth: 0,+ },+ typography: { fontStack, size: "16px", weight: 400 },+ radius: 0,+ borderRadius: { topLeft: 0, topRight: 0, bottomRight: 0, bottomLeft: 0 },+ shadow: null,+ isButton: false,+ isNavigation: false,+ hasCTAIndicator: false,+ isInput: false,+ isLink: false,+});++const raw = (+ stacks: { body: string[]; heading: string[]; paragraph: string[] },+ snapshots: ReturnType<typeof snap>[],+) =>+ ({+ cssData: { colors: [], spacings: [], radii: [] },+ snapshots,+ images: [],+ logoCandidates: [],+ brandName: "Acme",+ pageTitle: "Acme",+ pageUrl: "https://acme.test/",+ typography: { stacks, sizes: {} },+ frameworkHints: [],+ colorScheme: "light" as const,+ pageBackground: "rgb(255, 255, 255)",+ backgroundCandidates: [+ { color: "rgb(255, 255, 255)", source: "body", priority: 100 },+ ],+ }) as any;++const families = (profile: any) =>+ (profile.fonts as Array<{ family: string; count: number }>).map(+ f => `${f.family}:${f.count}`,+ );++describe("fonts the page renders", () => {+ it("counts one family per stack, the one it shows", () => {+ const system = [+ "-apple-system",+ "BlinkMacSystemFont",+ "Segoe UI",+ "Roboto",+ "sans-serif",+ ];+ const inter = ["inter-variable-web", ...system];+ const profile = processRawBranding(+ raw(+ { body: inter, heading: ["recoleta-web", "Georgia", "serif"], paragraph: inter },+ [snap(inter), snap(inter), snap(system), snap(["Georgia", "serif"])],+ ),+ );++ // Not "Segoe UI" or "Roboto": a system stack names no brand font, and+ // the fallbacks of a styled stack are not what it renders. Build+ // suffixes come off the names the API reports.+ expect(families(profile)).toEqual(["Inter:4", "Recoleta:1", "Georgia:1"]);+ });++ it("looks past a site builder's hashed alias to the face behind it", () => {+ const wix = [+ "wfont_2feeec_e1b10df92bd244baba1e35d632c6fa41",+ "wf_e1b10df92bd244baba1e35d63",+ "orig_libre_baskerville",+ ];+ const profile = processRawBranding(+ raw(+ { body: ["Arial", "Helvetica", "sans-serif"], heading: wix, paragraph: wix },+ [snap(wix), snap(wix), snap(["wf_38b82f6a99a44d63a0bc6a5d605011dd"])],+ ),+ );++ // The alias resolves to the face behind it, spelled as a family name.+ expect(families(profile)).toEqual(["Libre Baskerville:4", "Arial:1"]);+ });++ it("reports a page set entirely in generic or system fonts as such, not as its fallbacks", () => {+ const generic = ["sans-serif"];+ const plain = processRawBranding(+ raw({ body: generic, heading: generic, paragraph: generic }, [snap(generic)]),+ );+ expect(families(plain)).toEqual(["sans-serif:1"]);+ expect(plain.typography?.fontFamilies).toEqual({+ primary: "sans-serif",+ heading: "sans-serif",+ });++ const system = ["-apple-system", "BlinkMacSystemFont", "Roboto", "Arial", "sans-serif"];+ const espn = processRawBranding(+ raw({ body: system, heading: system, paragraph: system }, [snap(system), snap(["a"])]),+ );+ // Not "Roboto", "Arial" or the one-letter declaration.+ expect(families(espn)).toEqual(["system-ui:1"]);+ expect(espn.typography?.fontFamilies).toEqual({+ primary: "system-ui",+ heading: "system-ui",+ });++ // An empty body measurement: the fallback still comes from another stack,+ // and a ui-monospace stack is reported as itself, not as system-ui.+ const mono = ["ui-monospace", "Menlo", "monospace"];+ const code = processRawBranding(+ raw({ body: [], heading: mono, paragraph: [] }, [snap(mono)]),+ );+ expect(families(code)).toEqual(["ui-monospace:1"]);+ });+});diff --git a/apps/api/src/lib/branding/font-names.ts b/apps/api/src/lib/branding/font-names.tsnew file mode 100644index 000000000..18664fb5a--- /dev/null+++ b/apps/api/src/lib/branding/font-names.ts@@ -0,0 +1,141 @@+// Which family in a font stack is the one visitors see, and vendor spellings+// of family names. Shared by the processor (counting fonts) and the Jev+// client (naming them), so the two never disagree about what a stack means.++export const GENERIC_FONTS = new Set([+ "serif",+ "sans-serif",+ "monospace",+ "cursive",+ "fantasy",+ "system-ui",+ "ui-sans-serif",+ "ui-serif",+ "ui-monospace",+ "ui-rounded",+ "-apple-system",+ "blinkmacsystemfont",+ "inherit",+ "initial",+ "emoji",+ "math",+]);++// A stack that starts with one of these asks for the visitor's system font;+// the named faces after it (Segoe UI, Roboto, Helvetica Neue) are only the+// per-platform spellings of that request, not fonts the brand chose.+const SYSTEM_STACK_HEADS = new Set([+ "system-ui",+ "-apple-system",+ "blinkmacsystemfont",+ "ui-sans-serif",+ "ui-serif",+ "ui-monospace",+ "ui-rounded",+]);++/**+ * Site builders serve a licensed face under a per-site alias and keep the+ * real name further down the stack: Wix's `wfont_<site>_<hash>` and+ * `wf_<hash>`, then `orig_<family>`. The alias says nothing about the font.+ */+export const isHashedAlias = (family: string): boolean =>+ /^wfont_[0-9a-f]{6}_[0-9a-f]{32}$/i.test(family) ||+ /^wf_[0-9a-f]{20,}$/i.test(family) ||+ /^[a-z]{1,6}_[0-9a-f]{24,}$/i.test(family);++const unquote = (family: string) =>+ family.trim().replace(/^["']|["']$/g, "").trim();++/** A stack that asks for the visitor's system font. */+export const isSystemStack = (stack: readonly string[]): boolean => {+ const first = stack.map(unquote).find(Boolean);+ return !!first && SYSTEM_STACK_HEADS.has(first.toLowerCase());+};++/**+ * What a stack is set in when it names no brand face: the system font+ * ("-apple-system" and "BlinkMacSystemFont" are system-ui; "ui-serif" and+ * "ui-monospace" are themselves), or its generic family ("sans-serif").+ * For reporting a page's typography.+ */+export const genericFamily = (stack: readonly string[]): string | undefined => {+ const first = stack.map(unquote).find(Boolean);+ if (!first) return undefined;+ const head = first.toLowerCase();+ if (head === "-apple-system" || head === "blinkmacsystemfont") {+ return "system-ui";+ }+ return GENERIC_FONTS.has(head) ? head : undefined;+};++/**+ * The family a stack renders: its first entry that is a real face, past any+ * hashed aliases. A stack led by a system keyword renders the system font+ * and names no brand face; a stack of generics names none either.+ */+export function renderedFamily(stack: readonly string[]): string | undefined {+ const families = stack.map(unquote).filter(Boolean);+ if (families.length === 0) return undefined;+ if (SYSTEM_STACK_HEADS.has(families[0].toLowerCase())) return undefined;+ for (const family of families) {+ if (/^var\(/i.test(family)) continue;+ if (isHashedAlias(family)) continue;+ // A one-letter or digits-only "family" is a broken declaration. Any+ // script counts: brands set in CJK or Cyrillic faces name them as such.+ if (!/\p{L}.*\p{L}/u.test(family)) continue;+ if (GENERIC_FONTS.has(family.toLowerCase())) return undefined;+ return family;+ }+ return undefined;+}++// Monotype and Wix spellings that hide a family name: "helvetica-w01-roman",+// "futura-lt-w01-book", "proxima-n-w01-reg", "open-sans-v2", and the+// `orig_` prefix Wix puts on the face behind an alias.+const VENDOR_SUFFIX =+ /(?:[-_]?lt)?[-_]?w0\d(?:[-_]?(?:regular|reg|roman|book|bold|light|medium|italic|it))?[-_]*$/i;+const KNOWN_FAMILIES = new Map<string, string>([+ ["dinneuzeitgrotesk", "DIN Neuzeit Grotesk"],+ ["proximan", "Proxima Nova"],+ ["proximanova", "Proxima Nova"],+ ["helveticaneue", "Helvetica Neue"],+ ["avenir", "Avenir"],+ ["avenirnext", "Avenir Next"],+ ["futura", "Futura"],+ ["opensans", "Open Sans"],+]);++/** The proper spelling of a family the vendor spells its own way, if we know it. */+export const knownFamily = (name: string): string | undefined =>+ KNOWN_FAMILIES.get(name.toLowerCase().replace(/[\s_-]/g, ""));++/**+ * Strips vendor prefixes and suffixes (orig_, -v2, -w01-roman, build+ * suffixes such as -variable-web); a name that matches a known family gets+ * its proper spelling.+ */+export function normalizeVendorName(name: string): string {+ let out = name.replace(/^orig_/i, "").replace(/-v\d+$/i, "");+ if (VENDOR_SUFFIX.test(out) && out.replace(VENDOR_SUFFIX, "").length >= 3) {+ out = out.replace(VENDOR_SUFFIX, "");+ }+ out = out.replace(/(?:[-_]+(?:variable|vf|web|webfont))+$/i, "");+ return knownFamily(out) ?? out;+}++/** First letter of each word up, in any script: "über grotesk" → "Über Grotesk". */+export const titleCase = (name: string): string =>+ name.replace(/(^|[\s-])(\p{L})/gu, (_, sep, ch) => sep + ch.toUpperCase());++/**+ * A family name as the API reports it: vendor spellings resolved,+ * underscores read as spaces, and an all-lowercase alias title-cased.+ * The Jev client goes further (weights, camel case); this is the shared+ * floor the processor's own output also meets.+ */+export function displayFamily(name: string): string {+ let out = normalizeVendorName(name).replace(/_/g, " ").replace(/\s+/g, " ").trim();+ if (out && out === out.toLowerCase()) out = titleCase(out);+ return knownFamily(out) ?? out;+}diff --git a/apps/api/src/lib/branding/jev.ts b/apps/api/src/lib/branding/jev.tsindex a5af34804..91c8e4c44 100644--- a/apps/api/src/lib/branding/jev.ts+++ b/apps/api/src/lib/branding/jev.ts@@ -28,6 +28,13 @@ import {JevScreenshotOutcome,} from "./metrics";import { sampled } from "../rollout";+import {+ GENERIC_FONTS,+ knownFamily,+ normalizeVendorName,+ renderedFamily,+ titleCase,+} from "./font-names";import { BrandingEnhancement } from "./schema";import { BrandingLLMInput } from "./types";@@ -239,24 +246,6 @@ function collectColors(input: BrandingLLMInput): ColorCandidate[] {// Fonts. Name cleanup is deterministic; Jev only judges which are brand fonts// and what role they play.-const GENERIC_FONTS = new Set([- "serif",- "sans-serif",- "monospace",- "cursive",- "fantasy",- "system-ui",- "ui-sans-serif",- "ui-serif",- "ui-monospace",- "ui-rounded",- "-apple-system",- "blinkmacsystemfont",- "inherit",- "initial",- "emoji",- "math",-]);// Fonts pages list as fallbacks in their stacks. They are only reported when// the page's typography uses them, or when nothing else is left.@@ -313,15 +302,23 @@ const splitCamelCase = (name: string) =>.join(" ");export function cleanFontFamily(raw: string): string | undefined {- // A whole stack ("system-ui, sans-serif") reports its first family.- let name = raw- .split(",")[0]- .trim()- .replace(/^["']|["']$/g, "");- if (!name || /^var\(/i.test(name)) return undefined;+ // A whole stack reports the family it renders: past hashed aliases, none+ // for a system stack ("-apple-system, BlinkMacSystemFont, Segoe UI").+ let name = renderedFamily(raw.split(",")) ?? "";+ if (!name) return undefined;if (/fallback/i.test(name)) return undefined;// next/font obfuscation: "__Roboto_Mono_c8ca7d" → "Roboto Mono"name = name.replace(/^_+/, "").replace(/_[0-9a-f]{6}$/i, "");+ // Vendor spellings and build suffixes: "orig_libre_baskerville",+ // "helvetica-w01-roman", "inter-variable-web".+ name = normalizeVendorName(name);+ // A name that is only a weight ("Regular", "semibold") is not a family.+ if (FONT_WEIGHT.test(name)) return undefined;+ // A weight glued onto a lowercase name: "graphikextralight" → "graphik".+ const glued = name.match(+ /^([a-z]{4,}?)(?:extra|ultra|semi|demi)?(?:light|bold|medium|regular|book|black|heavy|thin)$/,+ );+ if (glued) name = knownFamily(glued[1]) ?? glued[1];// "Roboto_Black": the weight goes before underscores turn into spaces.while (DELIMITED_WEIGHT_SUFFIX.test(name))name = name.replace(DELIMITED_WEIGHT_SUFFIX, "");@@ -336,10 +333,10 @@ export function cleanFontFamily(raw: string): string | undefined {while (FONT_WEIGHT_SUFFIX.test(name))name = name.replace(FONT_WEIGHT_SUFFIX, "");name = splitCamelCase(name);+ // A known family can only be matched once its weight is gone.+ name = knownFamily(name) ?? name;if (!name || GENERIC_FONTS.has(name.toLowerCase())) return undefined;- if (name === name.toLowerCase()) {- name = name.replace(/\b\w/g, ch => ch.toUpperCase());- }+ if (name === name.toLowerCase()) name = titleCase(name);return name;}@@ -359,7 +356,8 @@ function typographyRole(): FontRole | undefined {const t = input.jsAnalysis.typography;const first = (value?: string | string[]) => {- const raw = Array.isArray(value) ? value[0] : value;+ // A stack names the family it renders, not its first entry.+ const raw = Array.isArray(value) ? renderedFamily(value) : value;const cleaned = raw ? cleanFontFamily(raw) : undefined;return cleaned ? familyKey(cleaned) : undefined;};diff --git a/apps/api/src/lib/branding/processor.ts b/apps/api/src/lib/branding/processor.tsindex 2aee62629..397b23370 100644--- a/apps/api/src/lib/branding/processor.ts+++ b/apps/api/src/lib/branding/processor.ts@@ -9,6 +9,7 @@ import {pickBrandPrimary,} from "./color-roles";import { BrandingScriptReturn, InputSnapshot } from "./types";+import { displayFamily, genericFamily, renderedFamily } from "./font-names";import { parse, rgb, formatHex } from "culori";// Export for testing@@ -352,15 +353,18 @@ function pickBorderRadius(radii: (number | null)[]): string {return Math.round(med) + "px";}-// Infer fonts list from stacks+// The fonts the page renders, most used first: one family per stack, the+// one it actually shows. Counting every entry of every stack made the+// fallbacks of a system stack ("Segoe UI", "Roboto") and the hashed aliases+// a site builder serves a face under look like the page's main fonts.function inferFontsList(fontStacks: string[][],): Array<{ family: string; count: number }> {const freq: Record<string, number> = {};for (const stack of fontStacks) {- for (const f of stack) {- if (f) freq[f] = (freq[f] || 0) + 1;- }+ const rendered = renderedFamily(stack);+ const f = rendered ? displayFamily(rendered) : undefined;+ if (f) freq[f] = (freq[f] || 0) + 1;}return Object.keys(freq)@@ -389,13 +393,19 @@ export function processRawBranding(raw: BrandingScriptReturn): BrandingProfile {pageBackground,);- // Typography+ // Typography: the family each stack renders, or what it is set in when+ // that is the system font or a generic ("-apple-system, …" is system-ui).+ const familyOf = (stack: string[]) => {+ const rendered = renderedFamily(stack);+ return rendered ? displayFamily(rendered) : genericFamily(stack);+ };const typography = {fontFamilies: {- primary: raw.typography.stacks.body[0] || "system-ui, sans-serif",+ primary:+ familyOf(raw.typography.stacks.body) || "system-ui, sans-serif",heading:- raw.typography.stacks.heading[0] ||- raw.typography.stacks.body[0] ||+ familyOf(raw.typography.stacks.heading) ||+ familyOf(raw.typography.stacks.body) ||"system-ui, sans-serif",},fontStacks: raw.typography.stacks,@@ -409,12 +419,23 @@ export function processRawBranding(raw: BrandingScriptReturn): BrandingProfile {...raw.cssData.radii,]);- // Fonts list (all font stacks flattened)- const allFontStacks = [- ...Object.values(raw.typography.stacks).flat(),- ...raw.snapshots.map(s => s.typography.fontStack).flat(),+ // Fonts list: the page's measured stacks and every sampled element's. A+ // page that names no brand face is reported as set in its system or+ // generic font rather than with no font at all.+ const measuredStacks = [+ ...Object.values(raw.typography.stacks),+ ...raw.snapshots.map(s => s.typography.fontStack),];- const fontsList = inferFontsList([allFontStacks]);+ let fontsList = inferFontsList(measuredStacks);+ if (fontsList.length === 0) {+ for (const stack of measuredStacks) {+ const generic = genericFamily(stack);+ if (generic) {+ fontsList = [{ family: generic, count: 1 }];+ break;+ }+ }+ }// Imagesconst images = {