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): 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.tsindex 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.tsindex 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.tsindex 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 conversionoriginalBackgroundColor: 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.tsindex 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 hexoriginalBackgroundColor?: string;originalTextColor?: string;