Skip to content

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

21.3 KB
Raw Blame
import { BrandingProfile } from "../../types/branding";
import {
  colorDistance,
  fitsColorScheme,
  isBrowserLinkColor,
  isGrayish,
  isNearBlack,
  isNeutralDark,
  isUsableAccent,
  isUsableBrandPrimary,
  normalizeRoleHex,
  shouldApplyLlmColorRoles,
} from "./color-roles";
import { LogoCandidate } from "./logo-selector";
import { BrandingEnhancement } from "./schema";
import { ButtonSnapshot, calculateLogoArea } from "./types";
import { logger } from "../logger";

export function mergeBrandingResults(
  js: BrandingProfile,
  llm: BrandingEnhancement,
  buttonSnapshots: ButtonSnapshot[],
  logoCandidates?: LogoCandidate[],
): BrandingProfile {
  const merged: BrandingProfile = { ...js };
  // The heuristic link is the accent's stand-in when the page's links gave
  // no color of their own; such a link follows the accent through every
  // change below. One measured on the page's links is the brand's and stays,
  // even when it happens to equal the heuristic accent.
  const linkFollowsAccent =
    !!js.colors?.link && (js as any).__link_measured !== true;

  // Handle logo selection only when we had logo candidates; ignore logoSelection when there were none
  const hasLogoCandidates = !!(logoCandidates && logoCandidates.length > 0);
  if (
    hasLogoCandidates &&
    llm.logoSelection &&
    llm.logoSelection.selectedLogoIndex !== undefined
  ) {
    // If LLM explicitly says no logo (returns -1), remove any logo that was set
    if (llm.logoSelection.selectedLogoIndex === -1) {
      if (merged.images) {
        delete merged.images.logo;
        delete merged.images.logoHref;
        delete merged.images.logoAlt;
      }
      (merged as any).__llm_logo_reasoning = {
        selectedIndex: -1,
        reasoning:
          llm.logoSelection.selectedLogoReasoning || "No valid logo found",
        confidence: llm.logoSelection.confidence || 0,
        rejected: true,
        source: "llm",
      };
    }
    // If LLM selected a valid logo index
    else if (
      llm.logoSelection.selectedLogoIndex >= 0 &&
      logoCandidates &&
      logoCandidates.length > 0 &&
      llm.logoSelection.selectedLogoIndex < logoCandidates.length
    ) {
      const selectedLogo = logoCandidates[llm.logoSelection.selectedLogoIndex];
      if (selectedLogo) {
        // Quality checks before accepting the logo
        const confidence = llm.logoSelection.confidence || 0;
        const alt = selectedLogo.alt || "";
        const altLower = alt.toLowerCase().trim();
        const href = selectedLogo.href || "";

        // Red flags: these patterns indicate it's NOT a brand logo
        const isLanguageWord =
          /^(english|español|français|deutsch|italiano|português|中文|日本語|한국어|русский|العربية|en|es|fr|de|it|pt|zh|ja|ko|ru|ar)$/i.test(
            altLower,
          );
        const isCommonMenuWord =
          /^(menu|search|cart|login|signup|register|account|profile|settings|help|support|contact|about|home|shop|store|products|services|blog|news)$/i.test(
            altLower,
          );
        const isUIIcon =
          /search|icon|menu|hamburger|cart|user|bell|notification|settings|close|times/i.test(
            altLower,
          );

        // Check for external links - brand logos should NOT link to external websites
        // Note: External links should already be filtered out in brandingScript.ts
        // This is a minimal safety check - we can't verify external links without page URL
        let isExternalLink = false;
        if (href && href.trim()) {
          const hrefLower = href.toLowerCase().trim();
          // Relative URLs (starting with /) are always internal
          // Full URLs should have been filtered already, but if they got through,
          // we can't verify they're internal without the page URL (window.location not available in Node.js)
          // So we'll only flag known external service patterns that should have been filtered
          if (
            hrefLower.startsWith("http://") ||
            hrefLower.startsWith("https://") ||
            hrefLower.startsWith("//")
          ) {
            // Check for known external service domains (should have been filtered already)
            const externalServiceDomains = [
              "github.com",
              "twitter.com",
              "x.com",
              "facebook.com",
              "linkedin.com",
            ];
            if (
              externalServiceDomains.some(domain => hrefLower.includes(domain))
            ) {
              isExternalLink = true;
            }
            // Note: We can't verify other full URLs without page URL, so we trust
            // that brandingScript.ts already filtered them correctly
          }
        }

        // Check for very small square icons (typical UI icons: 16x16, 20x20, 24x24, etc.)
        const width = selectedLogo.position?.width || 0;
        const height = selectedLogo.position?.height || 0;
        const isSmallSquareIcon =
          Math.abs(width - height) < 5 && width < 40 && width > 0;
        const trustLLMForLogo = confidence >= 0.7;
        const smallSquareIconLikelyUi =
          isSmallSquareIcon &&
          !(trustLLMForLogo && selectedLogo.indicators?.inHeader);

        // Only set logo if:
        // 1. Confidence is good (>= 0.5) OR
        // 2. Logo has very strong indicators (inHeader + hrefMatch + reasonable size)
        // AND no red flags (small square icons are allowed only with strong indicators)
        const area = calculateLogoArea(selectedLogo.position);
        const hasReasonableSize = area >= 500 && area <= 100000;
        const hasStrongIndicators =
          selectedLogo.indicators?.inHeader &&
          selectedLogo.indicators?.hrefMatch &&
          hasReasonableSize;

        const reasoning = llm.logoSelection.selectedLogoReasoning ?? "";
        const isHeuristicOrFallback =
          reasoning.includes("Heuristic") ||
          reasoning.includes("heuristic") ||
          reasoning === "LLM failed" ||
          reasoning.includes("invalid index");

        // Trust LLM logo choice: don't reject for "small square icon" when LLM selected it
        const smallSquareRedFlag =
          smallSquareIconLikelyUi &&
          !hasStrongIndicators &&
          isHeuristicOrFallback;
        const hasRedFlagsWithLLMTrust =
          isLanguageWord ||
          isCommonMenuWord ||
          isUIIcon ||
          smallSquareRedFlag ||
          isExternalLink;
        const shouldIncludeLogoWithLLMTrust =
          !hasRedFlagsWithLLMTrust &&
          (confidence >= 0.5 || (hasStrongIndicators && confidence >= 0.4));

        if (shouldIncludeLogoWithLLMTrust) {
          // Initialize images object if it doesn't exist
          if (!merged.images) {
            merged.images = {};
          }
          merged.images.logo = selectedLogo.src;
          if (selectedLogo.href) {
            merged.images.logoHref = selectedLogo.href;
          } else {
            delete merged.images.logoHref;
          }
          if (selectedLogo.alt) {
            merged.images.logoAlt = selectedLogo.alt;
          } else {
            delete merged.images.logoAlt;
          }
          (merged as any).__llm_logo_reasoning = {
            selectedIndex: llm.logoSelection.selectedLogoIndex,
            reasoning: llm.logoSelection.selectedLogoReasoning,
            confidence: llm.logoSelection.confidence,
            source: isHeuristicOrFallback ? "heuristic" : "llm",
          };
          logger.debug("[branding merge] Logo included", {
            result: "included",
            selectedIndex: llm.logoSelection.selectedLogoIndex,
            source: isHeuristicOrFallback ? "heuristic" : "llm",
            confidence,
            reasoning: (reasoning || "").slice(0, 120),
          });
        } else {
          // Log why we're not including the logo
          let rejectionReason = "Low confidence";
          const redFlagReasons: string[] = [];
          if (hasRedFlagsWithLLMTrust) {
            if (isLanguageWord) redFlagReasons.push("language word");
            if (isCommonMenuWord) redFlagReasons.push("menu word");
            if (isUIIcon) redFlagReasons.push("UI icon");
            if (smallSquareRedFlag) redFlagReasons.push("small square icon");
            if (isExternalLink) redFlagReasons.push("external link");
            rejectionReason = `Red flags detected (${redFlagReasons.join(", ")})`;
          }
          const selectedLogoReasoning = reasoning.trim();
          (merged as any).__llm_logo_reasoning = {
            selectedIndex: llm.logoSelection.selectedLogoIndex,
            reasoning: selectedLogoReasoning
              ? `Logo rejected: ${rejectionReason}. ${selectedLogoReasoning}`
              : `Logo rejected: ${rejectionReason}.`,
            confidence: llm.logoSelection.confidence,
            rejected: true,
            source: isHeuristicOrFallback ? "heuristic" : "llm",
          };
          logger.debug("[branding merge] Logo rejected (override)", {
            result: "rejected",
            selectedIndex: llm.logoSelection.selectedLogoIndex,
            source: isHeuristicOrFallback ? "heuristic" : "llm",
            confidence,
            hasRedFlags: hasRedFlagsWithLLMTrust,
            redFlagReasons: redFlagReasons.length ? redFlagReasons : undefined,
            confidenceOk:
              confidence >= 0.5 || (hasStrongIndicators && confidence >= 0.4),
            isHeuristicOrFallback,
            smallSquareRedFlag,
            reasoning: (reasoning || "").slice(0, 120),
          });
        }
      }
    }
  }

  if (buttonSnapshots.length > 0) {
    const primaryIdx = llm.buttonClassification.primaryButtonIndex;
    const secondaryIdx = llm.buttonClassification.secondaryButtonIndex;

    (merged as any).__llm_button_reasoning = {
      primary: {
        index: primaryIdx,
        text: primaryIdx >= 0 ? buttonSnapshots[primaryIdx]?.text : "N/A",
        reasoning: llm.buttonClassification.primaryButtonReasoning,
      },
      secondary: {
        index: secondaryIdx,
        text: secondaryIdx >= 0 ? buttonSnapshots[secondaryIdx]?.text : "N/A",
        reasoning: llm.buttonClassification.secondaryButtonReasoning,
      },
      confidence: llm.buttonClassification.confidence,
    };
  }

  // A model that answered gave its most likely buttons. Jev's confidence is a
  // calibrated probability, often under 0.5 when a page has several plausible
  // calls to action, and its pick still beats a page without buttons. A
  // failed call reports 0 and keeps the heuristic result.
  if (llm.buttonClassification.confidence > 0 && buttonSnapshots.length > 0) {
    const primaryIdx = llm.buttonClassification.primaryButtonIndex;
    const secondaryIdx = llm.buttonClassification.secondaryButtonIndex;

    if (primaryIdx >= 0 && primaryIdx < buttonSnapshots.length) {
      const primaryBtn = buttonSnapshots[primaryIdx];
      if (!merged.components) merged.components = {};
      merged.components.buttonPrimary = {
        background: primaryBtn.background,
        textColor: primaryBtn.textColor,
        borderColor: primaryBtn.borderColor || undefined,
        borderRadius: primaryBtn.borderRadius || "0px",
        borderRadiusCorners: primaryBtn.borderRadiusCorners,
        shadow: primaryBtn.shadow || undefined,
      };
    }

    if (secondaryIdx >= 0 && secondaryIdx < buttonSnapshots.length) {
      const secondaryBtn = buttonSnapshots[secondaryIdx];
      const primaryBtn = buttonSnapshots[primaryIdx];

      if (!primaryBtn || secondaryBtn.background !== primaryBtn.background) {
        if (!merged.components) merged.components = {};
        merged.components.buttonSecondary = {
          background: secondaryBtn.background,
          textColor: secondaryBtn.textColor,
          borderColor: secondaryBtn.borderColor || undefined,
          borderRadius: secondaryBtn.borderRadius || "0px",
          borderRadiusCorners: secondaryBtn.borderRadiusCorners,
          shadow: secondaryBtn.shadow || undefined,
        };
      }
    }
  }

  if (
    shouldApplyLlmColorRoles(
      llm.colorRoles.confidence,
      llm.colorRoles.primaryColor,
      merged.colors?.primary,
      merged.colorScheme,
    )
  ) {
    // A browser's default link color is never a brand color.
    const brandHex = (value?: string | null) =>
      isBrowserLinkColor(value) ? undefined : normalizeRoleHex(value);
    const llmPrimary = brandHex(llm.colorRoles.primaryColor);
    const llmSecondary = brandHex(llm.colorRoles.secondaryColor);
    const llmAccent = brandHex(llm.colorRoles.accentColor);
    // A dark background on a light page is a hero or a footer, not the page.
    const llmBackgroundHex = normalizeRoleHex(llm.colorRoles.backgroundColor);
    const llmBackground =
      llmBackgroundHex && fitsColorScheme(llmBackgroundHex, merged.colorScheme)
        ? llmBackgroundHex
        : undefined;
    const llmText = normalizeRoleHex(llm.colorRoles.textPrimary);
    const usablePrimary =
      llmPrimary && isUsableBrandPrimary(llmPrimary, merged.colorScheme)
        ? llmPrimary
        : undefined;
    // A pale tint or a gray can't call attention to anything: the measured
    // accent stays, or the primary when that is pale too.
    const usableAccent = (hex?: string) =>
      hex && isUsableAccent(hex, merged.colorScheme) ? hex : undefined;
    const rawSecondary = llm.colorRoles.secondaryColor;
    const omittedSecondary =
      rawSecondary == null || String(rawSecondary).trim() === "";

    merged.colors = {
      ...merged.colors,
      primary: usablePrimary || merged.colors?.primary,
      ...(llmSecondary ? { secondary: llmSecondary } : {}),
      accent:
        usableAccent(llmAccent) ||
        usableAccent(merged.colors?.accent) ||
        usablePrimary ||
        merged.colors?.primary,
      background: llmBackground || merged.colors?.background,
      // Body text is written in a neutral; a saturated pick is usually the
      // link color, so the measured neutral text color stays.
      textPrimary: keepsMeasuredText(llmText, merged.colors?.textPrimary)
        ? merged.colors?.textPrimary
        : llmText || merged.colors?.textPrimary,
    };
    if (linkFollowsAccent) merged.colors.link = merged.colors.accent;

    // When the LLM omits secondaryColor, remove the JS-heuristic secondary
    // to avoid propagating spurious colors from CSS presets (e.g. WordPress themes).
    // Invalid values (color names) must not look like an omission.
    if (omittedSecondary && merged.colors?.secondary) {
      delete merged.colors.secondary;
    }

    // Add LLM-selected colors to debug output
    if ((merged as any).__debug_colors) {
      (merged as any).__debug_colors.llmSelectedColors = {
        primary: llm.colorRoles.primaryColor,
        secondary: llm.colorRoles.secondaryColor,
        accent: llm.colorRoles.accentColor,
        background: llm.colorRoles.backgroundColor,
        textPrimary: llm.colorRoles.textPrimary,
        confidence: llm.colorRoles.confidence,
      };
    }
  }

  // Monochrome brands (black logo and calls to action, color only in links or
  // artwork) have black as their primary color, which the chrome filters above
  // reject on light pages. A near-black primary button is that signal, unless
  // the chosen color also fills a button, as when a brand pairs a black call to
  // action with colored ones.
  const primaryFill = normalizeRoleHex(
    merged.components?.buttonPrimary?.background,
  );
  const primaryColor = normalizeRoleHex(merged.colors?.primary);
  let displaced: string | undefined;
  if (
    merged.colorScheme !== "dark" &&
    primaryFill &&
    isNeutralDark(primaryFill) &&
    primaryColor &&
    primaryColor !== primaryFill &&
    !buttonSnapshots.some(
      b =>
        colorDistance(b.background, primaryColor) < 40 ||
        colorDistance(b.borderColor, primaryColor) < 40,
    )
  ) {
    merged.colors = {
      ...merged.colors,
      primary: primaryFill,
      accent: merged.colors?.accent ?? primaryColor,
    };
    displaced = primaryColor;
  }

  applyLogoAndMonochromeColors(
    merged,
    buttonSnapshots,
    logoCandidates,
    displaced,
    linkFollowsAccent,
  );

  if (llm.personality) {
    (merged as any).personality = llm.personality;
  }

  if (llm.designSystem) {
    (merged as any).designSystem = llm.designSystem;
  }

  if (llm.cleanedFonts && llm.cleanedFonts.length > 0) {
    merged.fonts = llm.cleanedFonts;

    const cleanFontName = (font: string): string => {
      const fontLower = font.toLowerCase();

      for (const cleanedFont of llm.cleanedFonts) {
        const cleanedLower = cleanedFont.family.toLowerCase();

        if (fontLower === cleanedLower) {
          return cleanedFont.family;
        }

        if (fontLower.includes(cleanedLower)) {
          return cleanedFont.family;
        }

        const nextJsPattern = /^__(.+?)(?:_Fallback)?_[a-f0-9]{8}$/i;
        const match = font.match(nextJsPattern);
        if (match) {
          const extractedName = match[1].toLowerCase();
          if (
            extractedName === cleanedLower ||
            cleanedLower.includes(extractedName)
          ) {
            return cleanedFont.family;
          }
        }
      }

      return font;
    };

    if (merged.typography?.fontStacks) {
      const cleanStack = (
        stack: string[] | undefined,
      ): string[] | undefined => {
        if (!stack) return stack;

        const cleaned = stack.map(cleanFontName);
        const seen = new Set<string>();
        return cleaned.filter(font => {
          if (seen.has(font.toLowerCase())) return false;
          seen.add(font.toLowerCase());
          return true;
        });
      };

      merged.typography.fontStacks = {
        primary: cleanStack(merged.typography.fontStacks.primary),
        heading: cleanStack(merged.typography.fontStacks.heading),
        body: cleanStack(merged.typography.fontStacks.body),
        paragraph: cleanStack(merged.typography.fontStacks.paragraph),
      };
    }

    if (merged.typography?.fontFamilies) {
      const headingFont = llm.cleanedFonts.find(f => f.role === "heading");
      const bodyFont = llm.cleanedFonts.find(f => f.role === "body");
      const displayFont = llm.cleanedFonts.find(f => f.role === "display");
      const primaryFont = bodyFont || llm.cleanedFonts[0];

      if (primaryFont) {
        merged.typography.fontFamilies.primary = primaryFont.family;
      }

      const headingToUse = headingFont || displayFont || primaryFont;
      if (headingToUse) {
        merged.typography.fontFamilies.heading = headingToUse.family;
      }
    }
  }

  (merged as any).confidence = {
    buttons: llm.buttonClassification.confidence,
    colors: llm.colorRoles.confidence,
    overall:
      (llm.buttonClassification.confidence + llm.colorRoles.confidence) / 2,
  };

  return merged;
}

const isNeutral = (hex: string) => isGrayish(hex) || isNearBlack(hex);

function keepsMeasuredText(llmText?: string, measured?: string | null) {
  const heuristic = normalizeRoleHex(measured);
  return (
    !!llmText && !!heuristic && !isGrayish(llmText) && isGrayish(heuristic)
  );
}

/**
 * The logo is the most reliable brand evidence: a clear color in the chosen
 * logo is the primary when the extracted one is neutral, pale or far from it.
 * A brand whose primary stays neutral (black call to action) is monochrome: a saturated accent, secondary or link no button uses then comes
 * from imagery or CSS presets, and the neutral takes its place. The color the
 * monochrome rule moved out of primary (the brand's link color) is kept.
 */
function applyLogoAndMonochromeColors(
  merged: BrandingProfile,
  buttonSnapshots: ButtonSnapshot[],
  logoCandidates: LogoCandidate[] | undefined,
  displaced: string | undefined,
  linkFollowsAccent: boolean,
): void {
  if (!merged.colors) return;
  const scheme = merged.colorScheme;
  const logoSrc = merged.images?.logo;
  const logo = logoSrc
    ? logoCandidates?.find(c => c.src === logoSrc)
    : undefined;
  const logoColors = (logo?.colors ?? [])
    .map(c => ({ hex: normalizeRoleHex(c.color), share: c.share }))
    .filter((c): c is { hex: string; share: number } => !!c.hex);
  const onButton = (hex: string) =>
    buttonSnapshots.some(
      b =>
        colorDistance(b.background, hex) < 40 ||
        colorDistance(b.borderColor, hex) < 40,
    );

  const logoBrand = logoColors.find(
    c => c.share >= 0.25 && isUsableBrandPrimary(c.hex, scheme),
  );
  const primary = normalizeRoleHex(merged.colors.primary);
  if (
    logoBrand &&
    (!primary ||
      !isUsableBrandPrimary(primary, scheme) ||
      logoColors.every(c => colorDistance(c.hex, primary) > 60))
  ) {
    merged.colors = { ...merged.colors, primary: logoBrand.hex };
    return;
  }

  // A black or white logo alone can't tell a brand accent (Bloomberg's red)
  // from campaign imagery, and a gray or navy primary may just be chrome, so
  // only a neutral black primary that is also the primary button's fill (the
  // black call to action above) marks the brand as monochrome.
  const neutral =
    primary &&
    isNeutralDark(primary) &&
    colorDistance(merged.components?.buttonPrimary?.background, primary) < 40
      ? primary
      : undefined;
  if (!neutral || scheme === "dark") return;

  const incidental = (value?: string | null) => {
    const hex = normalizeRoleHex(value);
    return !!hex && hex !== displaced && !isNeutral(hex) && !onButton(hex);
  };
  const colors = { ...merged.colors, primary: neutral };
  if (incidental(colors.accent)) colors.accent = neutral;
  if (linkFollowsAccent) colors.link = colors.accent;
  if (incidental(colors.secondary)) delete colors.secondary;
  merged.colors = colors;
}