Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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;
+ }
+ }
+ }
// Images
const images = {