Skip to content

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

fix(branding): keep the heading font and the brand-colored button in Jev answers (#5296)

Abimael Martell2f73ce58a481
diff --git a/apps/api/src/__tests__/lib/branding/jev.test.ts b/apps/api/src/__tests__/lib/branding/jev.test.ts
index 9b2d76eb0..56b248c20 100644
--- a/apps/api/src/__tests__/lib/branding/jev.test.ts
+++ b/apps/api/src/__tests__/lib/branding/jev.test.ts
@@ -671,6 +671,113 @@ describe("branding with Jev", () => {
]);
});
+ it("reads the heading face from headings even when the first paragraph uses it", () => {
+ const input = baseInput(new CostTracking());
+ input.jsAnalysis.typography = {
+ fontFamilies: { primary: "IBM Plex Sans", heading: "Libre Baskerville" },
+ fontStacks: {
+ body: ["IBM Plex Sans", "ui-sans-serif"],
+ heading: ["Libre Baskerville", "Georgia"],
+ paragraph: ["Libre Baskerville", "Georgia"],
+ },
+ };
+ input.jsAnalysis.fonts = [
+ { family: "IBM Plex Sans", count: 54 },
+ { family: "Libre Baskerville", count: 26 },
+ { family: "Lato", count: 10 },
+ ];
+ expect(buildJevRequest(input).fonts.map(f => [f.family, f.role])).toEqual([
+ ["IBM Plex Sans", "body"],
+ ["Libre Baskerville", "heading"],
+ ["Lato", undefined],
+ ]);
+
+ // A paragraph font nothing else places is still body text.
+ input.jsAnalysis.typography.fontStacks!.paragraph = ["Lato"];
+ expect(buildJevRequest(input).fonts[2].role).toBe("body");
+ });
+
+ it("drops the browser's default font when a real face is the body text", async () => {
+ const input = baseInput(new CostTracking());
+ // The page styles inner elements, so <body> measures the default serif.
+ input.jsAnalysis.typography = {
+ fontFamilies: { primary: "Times New Roman" },
+ fontStacks: { paragraph: ["Heebo", "sans-serif"] },
+ };
+ input.jsAnalysis.fonts = [
+ { family: "Heebo", count: 200 },
+ { family: "Times New Roman", count: 2 },
+ ];
+ respondWith(
+ jevResponse({
+ font_0_is_brand: { type: "noul", noul: 0.9 },
+ font_1_is_brand: { type: "noul", noul: 0.6 },
+ }),
+ );
+
+ expect((await enhanceBrandingWithLLM(input)).cleanedFonts).toEqual([
+ { family: "Heebo", role: "body" },
+ ]);
+ });
+
+ it("keeps the measured fonts when Jev rejects every one", async () => {
+ const input = baseInput(new CostTracking());
+ input.jsAnalysis.typography = {
+ fontFamilies: { primary: "Times New Roman" },
+ };
+ input.jsAnalysis.fonts = [{ family: "Times New Roman", count: 5 }];
+ respondWith(jevResponse({ font_0_is_brand: { type: "noul", noul: 0.4 } }));
+
+ expect((await enhanceBrandingWithLLM(input)).cleanedFonts).toEqual([
+ { family: "Times New Roman", role: "body" },
+ ]);
+ });
+
+ it("shows Jev one button the scan reported twice, keeping the styled one", () => {
+ const input = baseInput(new CostTracking());
+ const cta = {
+ ...input.buttons[0],
+ text: "Book a demo",
+ background: "#0D46DB",
+ top: 459,
+ left: 200,
+ width: 140,
+ };
+ input.buttons = [
+ // the link around the button: inherited text color, square corners
+ { ...cta, index: 0, textColor: "#333333", borderRadius: "0px" },
+ { ...cta, index: 1, textColor: "#FFFFFF", borderRadius: "6px", top: 461 },
+ // the same label lower down the page is a different button
+ {
+ ...cta,
+ index: 2,
+ textColor: "#333333",
+ borderRadius: "0px",
+ top: 9000,
+ },
+ // and so is one beside it in the same row
+ {
+ ...cta,
+ index: 3,
+ textColor: "#333333",
+ borderRadius: "0px",
+ left: 360,
+ },
+ ];
+
+ expect(Object.keys(buildJevRequest(input).state.buttons as object)).toEqual(
+ ["button_1", "button_2", "button_3"],
+ );
+ });
+
+ it("tells Jev the primary button is usually the brand-colored one", () => {
+ const request = buildJevRequest(baseInput(new CostTracking()));
+ expect(
+ (request.questions.primary_button as { instructions: string })
+ .instructions,
+ ).toMatch(/brand's color/);
+ });
+
it("treats a pick between identical-looking buttons as confident", async () => {
const input = baseInput(new CostTracking());
input.buttons.push({
@@ -985,6 +1092,30 @@ describe("Jev request building", () => {
expect(cleanFontFamily("Newsreader Variable")).toBe("Newsreader");
});
+ it("drops the weight from self-hosted font names and spaces run-together ones", () => {
+ expect(cleanFontFamily("OpenSans--Regular")).toBe("Open Sans");
+ expect(cleanFontFamily("Verdana-Regular")).toBe("Verdana");
+ expect(cleanFontFamily("Inter Bold")).toBe("Inter");
+ expect(cleanFontFamily("GmarketSansMedium")).toBe("Gmarket Sans");
+ expect(cleanFontFamily("GlacialIndifference")).toBe("Glacial Indifference");
+ expect(cleanFontFamily("Playfair Display Italic")).toBe("Playfair Display");
+ // A weight alone is not a family; names that only contain one stay.
+ expect(cleanFontFamily("Regular")).toBeUndefined();
+ expect(cleanFontFamily("Bold Italic")).toBeUndefined();
+ expect(cleanFontFamily("Times New Roman")).toBe("Times New Roman");
+ expect(cleanFontFamily("Black Han Sans")).toBe("Black Han Sans");
+ expect(cleanFontFamily("Book Antiqua")).toBe("Book Antiqua");
+ // Families that end in a heavy weight keep it; a self-hosted face doesn't.
+ expect(cleanFontFamily("Cooper Black")).toBe("Cooper Black");
+ expect(cleanFontFamily("Arial Black")).toBe("Arial Black");
+ expect(cleanFontFamily("Roboto-Black")).toBe("Roboto");
+ expect(cleanFontFamily("Roboto_Black")).toBe("Roboto");
+ expect(cleanFontFamily("__Roboto_Mono_Book_c8ca7d")).toBe("Roboto Mono");
+ // Acronyms aren't split.
+ expect(cleanFontFamily("TIActuBeta")).toBe("TIActuBeta");
+ expect(cleanFontFamily("HardwoodLP")).toBe("HardwoodLP");
+ });
+
it("merges a family listed with and without spaces", () => {
const input = baseInput(new CostTracking());
input.jsAnalysis.fonts = [
diff --git a/apps/api/src/lib/branding/jev.ts b/apps/api/src/lib/branding/jev.ts
index 8c3d2f551..edd45801b 100644
--- a/apps/api/src/lib/branding/jev.ts
+++ b/apps/api/src/lib/branding/jev.ts
@@ -6,7 +6,7 @@ import type {
RequestOptions,
SystemOneResult,
} from "@typesafe-ai/sdk";
-import { formatHex, hsl, parse } from "culori";
+import { formatHex, hsl, parse, wcagContrast } from "culori";
import { config } from "../../config";
import { setSpanAttributes, SpanKind, withSpan } from "../otel-tracer";
@@ -273,6 +273,31 @@ const FALLBACK_FONTS = new Set([
"noto color emoji",
]);
+// Families can end in a heavy weight ("Cooper Black", "Arial Black"), so
+// after a space only the weights no family name ends in are stripped. After a
+// hyphen or underscore ("Roboto-Black") the name is a self-hosted face.
+const SPACED_WEIGHTS =
+ "regular|reg|medium|semi-?bold|demi-?bold|bold|extra-?bold|ultra-?bold|light|extra-?light|ultra-?light|thin|hairline|italic|oblique";
+const WEIGHTS = `${SPACED_WEIGHTS}|book|black|heavy`;
+const FONT_WEIGHT = new RegExp(`^\\s*(?:(?:${WEIGHTS})\\s*)+$`, "i");
+const DELIMITED_WEIGHT_SUFFIX = new RegExp(`(?<=\\S)[_-]+(?:${WEIGHTS})$`, "i");
+const FONT_WEIGHT_SUFFIX = new RegExp(
+ `(?<=\\S)(?:[_-]+(?:${WEIGHTS})|\\s+(?:${SPACED_WEIGHTS}))$`,
+ "i",
+);
+
+// "GlacialIndifference" → "Glacial Indifference". Only words made of whole
+// capitalized parts split, so "TIActuBeta" and "HardwoodLP" stay.
+const splitCamelCase = (name: string) =>
+ name
+ .split(" ")
+ .map(word =>
+ /^(?:[A-Z][a-z]{2,}){2,}$/.test(word)
+ ? word.replace(/(?<=[a-z])(?=[A-Z])/g, " ")
+ : word,
+ )
+ .join(" ");
+
export function cleanFontFamily(raw: string): string | undefined {
// A whole stack ("system-ui, sans-serif") reports its first family.
let name = raw
@@ -283,9 +308,20 @@ export function cleanFontFamily(raw: string): string | 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, "");
+ // "Roboto_Black": the weight goes before underscores turn into spaces.
+ while (DELIMITED_WEIGHT_SUFFIX.test(name))
+ name = name.replace(DELIMITED_WEIGHT_SUFFIX, "");
name = name.replace(/_/g, " ").replace(/\s+/g, " ").trim();
// Variable-font builds name the same family: "Newsreader Variable".
name = name.replace(/\s+(variable|vf)$/i, "");
+ // Self-hosted faces carry their weight: "OpenSans--Regular", "Inter Bold".
+ // A name that is only a weight ("Regular") is not a family.
+ if (FONT_WEIGHT.test(name)) return undefined;
+ // Before and after the weight goes: "GmarketSansMedium", "OpenSans--Regular".
+ name = splitCamelCase(name);
+ while (FONT_WEIGHT_SUFFIX.test(name))
+ name = name.replace(FONT_WEIGHT_SUFFIX, "");
+ name = splitCamelCase(name);
if (!name || GENERIC_FONTS.has(name.toLowerCase())) return undefined;
if (name === name.toLowerCase()) {
name = name.replace(/\b\w/g, ch => ch.toUpperCase());
@@ -315,11 +351,7 @@ function typographyRole(
};
const name = familyKey(family);
if (/\b(mono|code)\b|consolas|menlo/i.test(family)) return "monospace";
- const body = [
- first(t?.fontFamilies?.primary),
- first(t?.fontStacks?.body),
- first(t?.fontStacks?.paragraph),
- ];
+ const body = [first(t?.fontFamilies?.primary), first(t?.fontStacks?.body)];
const heading = [
first(t?.fontFamilies?.heading),
first(t?.fontStacks?.heading),
@@ -327,6 +359,9 @@ function typographyRole(
// A family used for both is reported as body, the page's primary font.
if (body.includes(name)) return "body";
if (heading.includes(name)) return "heading";
+ // The first paragraph is often a styled lead in the heading face, so it
+ // only names a body font the other measurements don't place.
+ if (first(t?.fontStacks?.paragraph) === name) return "body";
return undefined;
}
@@ -411,6 +446,58 @@ const buttonStyle = (b: {
b.shadow ?? "",
].join("/");
+const readability = (b: { background?: string; textColor?: string }) => {
+ const bg = normalizeHex(b.background);
+ const fg = normalizeHex(b.textColor);
+ return bg && fg ? wcagContrast(bg, fg) : 0;
+};
+const radiusPx = (b: { borderRadius?: string }) =>
+ parseFloat(b.borderRadius ?? "") || 0;
+
+/**
+ * The scan can report one button twice, as the link and as the styled element
+ * inside it: same label, fill and box, but the outer one has the inherited
+ * text color and square corners. Keep the one that reads as a button.
+ * Buttons side by side don't overlap, so they are never twins.
+ */
+function withoutTwins<
+ T extends {
+ button: {
+ text?: string;
+ background?: string;
+ textColor?: string;
+ borderRadius?: string;
+ top?: number;
+ left?: number;
+ width?: number;
+ };
+ },
+>(entries: T[]): T[] {
+ const near = (a?: number, b?: number) =>
+ a !== undefined && b !== undefined && Math.abs(a - b) <= 8;
+ const overlapping = (a: T["button"], b: T["button"]) =>
+ a.left !== undefined &&
+ b.left !== undefined &&
+ (near(a.left, b.left) ||
+ (a.left < b.left + (b.width ?? 0) && b.left < a.left + (a.width ?? 0)));
+ const twins = (a: T["button"], b: T["button"]) =>
+ clip(a.text, 80).toLowerCase() === clip(b.text, 80).toLowerCase() &&
+ normalizeHex(a.background) === normalizeHex(b.background) &&
+ near(a.top, b.top) &&
+ overlapping(a, b);
+ const better = (a: T["button"], b: T["button"]) =>
+ readability(a) - readability(b) || radiusPx(a) - radiusPx(b);
+ return entries.filter(
+ ({ button }) =>
+ !entries.some(
+ other =>
+ other.button !== button &&
+ twins(button, other.button) &&
+ better(other.button, button) > 0,
+ ),
+ );
+}
+
const isHighSurrogate = (code: number) => code >= 0xd800 && code <= 0xdbff;
// slice() counts UTF-16 code units, so never end on the first half of a pair.
@@ -498,9 +585,11 @@ export function buildJevRequest(input: BrandingLLMInput): JevRequest {
}
// Ids keep each button's index in `input.buttons`, which is what merge reads.
- const ctaButtons = buttons
- .map((button, i) => ({ button, id: `button_${i}` }))
- .filter(({ button }) => !isConsentButton(button));
+ const ctaButtons = withoutTwins(
+ buttons
+ .map((button, i) => ({ button, id: `button_${i}` }))
+ .filter(({ button }) => !isConsentButton(button)),
+ );
if (ctaButtons.length > 0) {
state.buttons = Object.fromEntries(
@@ -575,7 +664,7 @@ export function buildJevRequest(input: BrandingLLMInput): JevRequest {
questions.primary_button = {
type: "choice",
instructions:
- "Which entry in `buttons` is the site's primary call-to-action button: the most prominent action a visitor is invited to take (such as Sign up, Get started, Buy, Book a demo, Donate)? Cookie-consent buttons are not calls to action.",
+ "Which entry in `buttons` is the site's primary call-to-action button: the most prominent action a visitor is invited to take (such as Sign up, Get started, Buy, Book a demo, Donate)? It is usually filled with the brand's color; a white, gray, black or transparent button is the primary only when no call to action uses a brand color, or the brand is deliberately monochrome. Cookie-consent buttons are not calls to action.",
// No "none": when a page has buttons, one of them is the primary style.
criteria: options(buttonIds),
};
@@ -826,11 +915,16 @@ function mapJevAnswers(
keep: isBrand?.type === "noul" ? isBrand.noul >= 0.5 : true,
};
})
- .filter(f => f.keep);
+ .filter((f, _, all) => f.keep || (f.measured && !all.some(o => o.keep)));
// Drop fallback faces the page doesn't use for text, and once headings or
- // body are covered, fonts nobody could place.
+ // body are covered, fonts nobody could place. A fallback measured as body
+ // (the browser default on a page that styles inner elements) goes too when
+ // a real face also is body text.
+ const fallbackFace = (f: { family: string }) =>
+ FALLBACK_FONTS.has(f.family.toLowerCase());
+ const realBody = realFonts.some(f => f.role === "body" && !fallbackFace(f));
const isFallback = (f: (typeof realFonts)[number]) =>
- FALLBACK_FONTS.has(f.family.toLowerCase()) && !f.measured;
+ fallbackFace(f) && (!f.measured || (f.role === "body" && realBody));
const withoutFallbacks = realFonts.some(f => !isFallback(f))
? realFonts.filter(f => !isFallback(f))
: realFonts;
diff --git a/apps/api/src/lib/branding/processor.ts b/apps/api/src/lib/branding/processor.ts
index 09f8c7ff2..e681fdc94 100644
--- a/apps/api/src/lib/branding/processor.ts
+++ b/apps/api/src/lib/branding/processor.ts
@@ -519,7 +519,13 @@ export function processRawBranding(raw: BrandingScriptReturn): BrandingProfile {
borderRadius: representativeBorderRadius,
borderRadiusCorners: corners,
shadow: s.shadow || null,
- ...(s.position ? { top: Math.round(s.position.top) } : {}),
+ ...(s.position
+ ? {
+ top: Math.round(s.position.top),
+ left: Math.round(s.position.left),
+ width: Math.round(s.rect.w),
+ }
+ : {}),
// Debug: original color values before hex conversion
originalBackgroundColor: s.colors.background || undefined,
originalTextColor: s.colors.text || undefined,
diff --git a/apps/api/src/lib/branding/types.ts b/apps/api/src/lib/branding/types.ts
index 8454c6bcf..d2e00e545 100644
--- a/apps/api/src/lib/branding/types.ts
+++ b/apps/api/src/lib/branding/types.ts
@@ -20,6 +20,9 @@ export interface ButtonSnapshot {
shadow?: string | null;
/** Distance from the top of the page in px, when the scan measured it. */
top?: number;
+ /** Left edge and width in px, when the scan measured them. */
+ left?: number;
+ width?: number;
// Debug: original color values before conversion to hex
originalBackgroundColor?: string;
originalTextColor?: string;