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
Implement Branding Format (#2326)
Abimael Martell6841a04a6657
diff --git a/apps/api/openapi.json b/apps/api/openapi.jsonindex 716a94901..fcac784bd 100644--- a/apps/api/openapi.json+++ b/apps/api/openapi.json@@ -1331,7 +1331,7 @@"type": "array","items": {"type": "string",- "enum": ["markdown", "json"],+ "enum": ["markdown", "json", "branding"],"default": ["markdown"]}},@@ -1763,7 +1763,8 @@"links","screenshot","screenshot@fullPage",- "json"+ "json",+ "branding"]},"description": "Formats to include in the output",@@ -2100,7 +2101,8 @@"screenshot","screenshot@fullPage","json",- "changeTracking"+ "changeTracking",+ "branding"]},"description": "Formats to include in the output.",@@ -2552,6 +2554,67 @@"description": "JSON comparison results when using 'json' mode. Only present when the mode is set to 'json'. This will emit a list of all the keys and their values from the `previous` and `current` scrapes based on the type defined in the `schema`. Example [here](/features/change-tracking)"}}+ },+ "branding": {+ "type": "object",+ "nullable": true,+ "description": "Brand identity information derived from executing on-page javascript.",+ "properties": {+ "logo": {+ "type": "string",+ "nullable": true,+ "description": "Primary logo URL if detected."+ },+ "fonts": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "family": {+ "type": "string"+ }+ },+ "additionalProperties": true+ },+ "description": "Detected font families."+ },+ "colors": {+ "type": "object",+ "additionalProperties": true+ },+ "typography": {+ "type": "object",+ "additionalProperties": true+ },+ "spacing": {+ "type": "object",+ "additionalProperties": true+ },+ "components": {+ "type": "object",+ "additionalProperties": true+ },+ "icons": {+ "type": "object",+ "additionalProperties": true+ },+ "images": {+ "type": "object",+ "additionalProperties": true+ },+ "animations": {+ "type": "object",+ "additionalProperties": true+ },+ "layout": {+ "type": "object",+ "additionalProperties": true+ },+ "tone": {+ "type": "object",+ "additionalProperties": true+ }+ }}}}@@ -2684,7 +2747,9 @@"robotsBlocked": {"type": "array","description": "List of URLs that were attempted in scraping but were blocked by robots.txt",- "items": { "type": "string" }+ "items": {+ "type": "string"+ }}}},diff --git a/apps/api/package.json b/apps/api/package.jsonindex d50ea97c7..fd68c0474 100644--- a/apps/api/package.json+++ b/apps/api/package.json@@ -44,6 +44,7 @@"@types/amqplib": "^0.10.7","@types/body-parser": "^1.19.2","@types/cors": "^2.8.13",+ "@types/culori": "^4.0.1","@types/escape-html": "^1.0.4","@types/express": "^4.17.21","@types/express-ws": "^3.0.5",@@ -103,6 +104,7 @@"cacheable-lookup": "^6.1.0","cheerio": "^1.0.0-rc.12","cors": "^2.8.5",+ "culori": "^4.0.2","dotenv": "^16.3.1","escape-html": "^1.0.3","express": "^4.21.2",diff --git a/apps/api/pnpm-lock.yaml b/apps/api/pnpm-lock.yamlindex db3d7e2b2..c714383ce 100644--- a/apps/api/pnpm-lock.yaml+++ b/apps/api/pnpm-lock.yaml@@ -125,6 +125,9 @@ importers:cors:specifier: ^2.8.5version: 2.8.5+ culori:+ specifier: ^4.0.2+ version: 4.0.2dotenv:specifier: ^16.3.1version: 16.4.5@@ -255,6 +258,9 @@ importers:'@types/cors':specifier: ^2.8.13version: 2.8.17+ '@types/culori':+ specifier: ^4.0.1+ version: 4.0.1'@types/escape-html':specifier: ^1.0.4version: 1.0.4@@ -3223,6 +3229,9 @@ packages:'@types/[email protected]':resolution: {integrity: sha512-8CGDvrBj1zgo2qE+oS3pOCyYNqCPryMWY2bGfwA0dcfopWGgxs+78df0Rs3rc9THP4JkOhLsAa+15VdpAqkcUA==}+ '@types/[email protected]':+ resolution: {integrity: sha512-43M51r/22CjhbOXyGT361GZ9vncSVQ39u62x5eJdBQFviI8zWp2X5jzqg7k4M6PVgDQAClpy2bUe2dtwEgEDVQ==}+'@types/[email protected]':resolution: {integrity: sha512-vIChWdVG3LG1SMxEvI/AK+FWJthlrqlTu7fbrlywTkkaONwk/UAGaULXRlf8vkzFBLVm0zkMdCquhL5aOjhXPQ==}@@ -3402,6 +3411,7 @@ packages:'@walletconnect/[email protected]':resolution: {integrity: sha512-SSlIG6QEVxClgl1s0LMk4xr2wg4eT3Zn/Hb81IocyqNSGfXpjtawWxKxiC5/9Z95f1INyBD6MctJbL/R1oBwIw==}+ deprecated: 'Reliability and performance improvements. See: https://github.com/WalletConnect/walletconnect-monorepo/releases''@walletconnect/[email protected]':resolution: {integrity: sha512-NPTqaoi0oPBVNuLv7qPaJazmGHs5JGyO8eEAk5VGKmJzDR7AHzD4k6ilox5kxk1iwiOnFopBOOMLs86Oa76HpQ==}@@ -3446,9 +3456,11 @@ packages:'@walletconnect/[email protected]':resolution: {integrity: sha512-z7h+PeLa5Au2R591d/8ZlziE0stJvdzP9jNFzFolf2RG/OiXulgFKum8PrIyXy+Rg2q95U9nRVUF9fWcn78yBA==}+ deprecated: 'Reliability and performance improvements. See: https://github.com/WalletConnect/walletconnect-monorepo/releases''@walletconnect/[email protected]':resolution: {integrity: sha512-QaXzmPsMnKGV6tc4UcdnQVNOz4zyXgarvdIQibJ4L3EmLat73r5ZVl4c0cCOcoaV7rgM9Wbphgu5E/7jNcd3Zg==}+ deprecated: 'Reliability and performance improvements. See: https://github.com/WalletConnect/walletconnect-monorepo/releases''@walletconnect/[email protected]':resolution: {integrity: sha512-uzdd9woDcJ1AaBZRhqy5rNC9laqWGErfc4dxA9a87mPdKOgWMD85mcFo9dIYIts/Jwocfwn07EC6EzclKubk/g==}@@ -3461,9 +3473,11 @@ packages:'@walletconnect/[email protected]':resolution: {integrity: sha512-mtUQvewt+X0VBQay/xOJBvxsB3Xsm1lTwFjZ6WUwSOTR1X+FNb71hSApnV5kbsdDIpYPXeQUbGt2se1n5E5UBg==}+ deprecated: 'Reliability and performance improvements. See: https://github.com/WalletConnect/walletconnect-monorepo/releases''@walletconnect/[email protected]':resolution: {integrity: sha512-Wjx9G8gUHVMnYfxtasC9poGm8QMiPCpXpbbLFT+iPoQskDDly8BwueWnqKs4Mx2SdIAWAwuXeZ5ojk5qQOxJJg==}+ deprecated: 'Reliability and performance improvements. See: https://github.com/WalletConnect/walletconnect-monorepo/releases''@walletconnect/[email protected]':resolution: {integrity: sha512-zfHLiUoBrQ8rP57HTPXW7rQMnYxYI4gT9yTACxVW6LhIFROTF6/ytm5SKNoIvi4a5nX5dfXG4D9XwQUCu8Ilig==}@@ -4038,6 +4052,10 @@ packages:resolution: {integrity: sha512-9+vem03dMXG7gDmZ62uqmRiMRNtinIZ9ZyuF6BdxzfOD+FdN5hretzynkn0ReS2DO2GSw76RWHs0UmJPI2zUjw==}engines: {node: '>=18'}+ resolution: {integrity: sha512-1+BhOB8ahCn4O0cep0Sh2l9KCOfOdY+BXJnKMHFFzDEouSr/el18QwXEMRlOj9UY5nCeA8UN3a/82rUWRBeyBw==}+ engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}+resolution: {integrity: sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==}engines: {node: '>= 12'}@@ -10885,6 +10903,8 @@ snapshots:dependencies:'@types/node': 20.14.1+ '@types/[email protected]': {}+'@types/[email protected]':dependencies:'@types/ms': 2.1.0@@ -12257,6 +12277,8 @@ snapshots:'@asamuzakjp/css-color': 2.8.3rrweb-cssom: 0.8.0+ [email protected]: {}+diff --git a/apps/api/requests/branding.requests.http b/apps/api/requests/branding.requests.httpnew file mode 100644index 000000000..3a0c6881f--- /dev/null+++ b/apps/api/requests/branding.requests.http@@ -0,0 +1,38 @@+### Test 1: Firecrawl, SVG logo, bright colors, light theme+# @name brandingTest1+POST http://localhost:3002/v2/scrape+Authorization: Bearer {{$dotenv TEST_API_KEY}}+Content-Type: application/json++{+ "url": "https://firecrawl.dev",+ "formats": [+ { "type": "branding" }+ ]+}++### Test 2: Supabase, dark mode, dark colors, png logo+# @name brandingTest2+POST http://localhost:3002/v2/scrape+Authorization: Bearer {{$dotenv TEST_API_KEY}}+Content-Type: application/json++{+ "url": "https://supabase.com",+ "formats": [+ { "type": "branding" }+ ]+}++### Test 3: Vercel, light mode, light colors, svg logo+# @name brandingTest3+POST http://localhost:3002/v2/scrape+Authorization: Bearer {{$dotenv TEST_API_KEY}}+Content-Type: application/json++{+ "url": "https://vercel.com",+ "formats": [+ { "type": "branding" }+ ]+}diff --git a/apps/api/src/__tests__/snips/v2/scrape-branding.test.ts b/apps/api/src/__tests__/snips/v2/scrape-branding.test.tsnew file mode 100644index 000000000..a0d697219--- /dev/null+++ b/apps/api/src/__tests__/snips/v2/scrape-branding.test.ts@@ -0,0 +1,340 @@+import { concurrentIf, HAS_AI, TEST_PRODUCTION } from "../lib";+import { scrape, scrapeTimeout, idmux, Identity } from "./lib";++let identity: Identity;++beforeAll(async () => {+ identity = await idmux({+ name: "scrape-branding",+ concurrency: 100,+ credits: 1000000,+ });+}, 10000 + scrapeTimeout);++// TODO: fix this test+// Need to run on fire-engine+describe.skip("Branding extraction", () => {+ describe("Basic branding extraction", () => {+ concurrentIf(TEST_PRODUCTION || HAS_AI)(+ "extracts branding with required fields",+ async () => {+ const response = await scrape(+ {+ url: "https://firecrawl.dev",+ formats: ["branding"],+ },+ identity,+ );++ expect(response.branding).toBeDefined();+ expect(response.branding?.colors).toBeDefined();+ expect(response.branding?.typography).toBeDefined();+ expect(response.branding?.spacing).toBeDefined();+ },+ scrapeTimeout,+ );++ concurrentIf(TEST_PRODUCTION || HAS_AI)(+ "includes color palette with valid colors",+ async () => {+ const response = await scrape(+ {+ url: "https://firecrawl.dev",+ formats: ["branding"],+ },+ identity,+ );++ expect(response.branding?.colors).toBeDefined();+ expect(response.branding?.colors?.primary).toBeDefined();+ expect(response.branding?.colors?.accent).toBeDefined();++ // Check that colors are valid hex or rgba format+ const colorRegex = /^(#[A-F0-9]{6}|rgba?\([^)]+\))$/i;+ if (response.branding?.colors?.primary) {+ expect(response.branding.colors.primary).toMatch(colorRegex);+ }+ },+ scrapeTimeout,+ );++ concurrentIf(TEST_PRODUCTION || HAS_AI)(+ "includes typography information",+ async () => {+ const response = await scrape(+ {+ url: "https://firecrawl.dev",+ formats: ["branding"],+ },+ identity,+ );++ expect(response.branding?.typography).toBeDefined();+ expect(response.branding?.typography?.fontFamilies).toBeDefined();+ expect(+ response.branding?.typography?.fontFamilies?.primary,+ ).toBeDefined();+ expect(+ typeof response.branding?.typography?.fontFamilies?.primary,+ ).toBe("string");+ },+ scrapeTimeout,+ );++ concurrentIf(TEST_PRODUCTION || HAS_AI)(+ "includes spacing information",+ async () => {+ const response = await scrape(+ {+ url: "https://firecrawl.dev",+ formats: ["branding"],+ },+ identity,+ );++ expect(response.branding?.spacing).toBeDefined();+ expect(response.branding?.spacing?.baseUnit).toBeDefined();+ expect(typeof response.branding?.spacing?.baseUnit).toBe("number");+ expect(response.branding?.spacing?.baseUnit).toBeGreaterThan(0);+ expect(response.branding?.spacing?.baseUnit).toBeLessThanOrEqual(128);+ },+ scrapeTimeout,+ );+ });++ describe("Component extraction", () => {+ concurrentIf(TEST_PRODUCTION || HAS_AI)(+ "extracts button components",+ async () => {+ const response = await scrape(+ {+ url: "https://firecrawl.dev",+ formats: ["branding"],+ },+ identity,+ );++ expect(response.branding?.components).toBeDefined();++ // At least primary or secondary button should be present+ const hasPrimary = response.branding?.components?.buttonPrimary;+ const hasSecondary = response.branding?.components?.buttonSecondary;+ expect(hasPrimary || hasSecondary).toBeTruthy();++ if (hasPrimary) {+ expect(+ response.branding?.components?.buttonPrimary?.background,+ ).toBeDefined();+ expect(+ response.branding?.components?.buttonPrimary?.textColor,+ ).toBeDefined();+ expect(+ response.branding?.components?.buttonPrimary?.borderRadius,+ ).toBeDefined();+ }+ },+ scrapeTimeout,+ );++ concurrentIf(TEST_PRODUCTION || HAS_AI)(+ "extracts border radius correctly",+ async () => {+ const response = await scrape(+ {+ url: "https://firecrawl.dev",+ formats: ["branding"],+ },+ identity,+ );++ if (response.branding?.components?.buttonPrimary?.borderRadius) {+ const radiusMatch =+ response.branding.components.buttonPrimary.borderRadius.match(+ /^(\d+(\.\d+)?)(px|rem|em)$/,+ );+ expect(radiusMatch).toBeTruthy();+ }+ },+ scrapeTimeout,+ );+ });++ describe("Image extraction", () => {+ concurrentIf(TEST_PRODUCTION || HAS_AI)(+ "extracts logo when present",+ async () => {+ const response = await scrape(+ {+ url: "https://firecrawl.dev",+ formats: ["branding"],+ },+ identity,+ );++ expect(response.branding?.images).toBeDefined();++ // Logo might not always be present, but if it is, should be valid URL or data URL+ if (response.branding?.images?.logo) {+ expect(+ response.branding.images.logo.startsWith("http") ||+ response.branding.images.logo.startsWith("data:"),+ ).toBe(true);+ }+ },+ scrapeTimeout,+ );++ concurrentIf(TEST_PRODUCTION || HAS_AI)(+ "extracts favicon when present",+ async () => {+ const response = await scrape(+ {+ url: "https://firecrawl.dev",+ formats: ["branding"],+ },+ identity,+ );++ // Favicon should almost always be present+ if (response.branding?.images?.favicon) {+ expect(+ response.branding.images.favicon.startsWith("http") ||+ response.branding.images.favicon.startsWith("data:"),+ ).toBe(true);+ }+ },+ scrapeTimeout,+ );+ });++ describe("LLM enhancement", () => {+ concurrentIf(TEST_PRODUCTION || HAS_AI)(+ "includes LLM-enhanced fields",+ async () => {+ const response = await scrape(+ {+ url: "https://firecrawl.dev",+ formats: ["branding"],+ },+ identity,+ );++ // LLM-enhanced fields should be present+ expect(response.branding?.personality).toBeDefined();+ // Note: confidence and designSystem are internal only, not in API response+ },+ scrapeTimeout,+ );++ concurrentIf(TEST_PRODUCTION || HAS_AI)(+ "includes cleaned fonts from LLM",+ async () => {+ const response = await scrape(+ {+ url: "https://firecrawl.dev",+ formats: ["branding"],+ },+ identity,+ );++ expect(response.branding?.fonts).toBeDefined();+ expect(Array.isArray(response.branding?.fonts)).toBe(true);++ // Check that fonts have expected structure if present+ if (response.branding?.fonts && response.branding.fonts.length > 0) {+ const font = response.branding.fonts[0];+ expect(font.family).toBeDefined();+ expect(typeof font.family).toBe("string");++ // Font should not have Next.js obfuscation patterns+ expect(font.family).not.toMatch(/__\w+_[a-f0-9]{8}/i);+ }+ },+ scrapeTimeout,+ );+ });++ describe("Color scheme detection", () => {+ concurrentIf(TEST_PRODUCTION || HAS_AI)(+ "detects color scheme",+ async () => {+ const response = await scrape(+ {+ url: "https://firecrawl.dev",+ formats: ["branding"],+ },+ identity,+ );++ // Color scheme should be detected+ if (response.branding?.colorScheme) {+ expect(["light", "dark"]).toContain(response.branding.colorScheme);+ }+ },+ scrapeTimeout,+ );+ });++ describe("Multiple formats compatibility", () => {+ concurrentIf(TEST_PRODUCTION || HAS_AI)(+ "works alongside other formats",+ async () => {+ const response = await scrape(+ {+ url: "https://firecrawl.dev",+ formats: ["markdown", "branding"],+ },+ identity,+ );++ expect(response.markdown).toBeDefined();+ expect(response.branding).toBeDefined();+ expect(typeof response.markdown).toBe("string");+ expect(typeof response.branding).toBe("object");+ },+ scrapeTimeout,+ );++ concurrentIf(TEST_PRODUCTION || HAS_AI)(+ "does not interfere with screenshot",+ async () => {+ const response = await scrape(+ {+ url: "https://firecrawl.dev",+ formats: ["branding", "screenshot"],+ },+ identity,+ );++ expect(response.branding).toBeDefined();+ expect(response.screenshot).toBeDefined();+ expect(typeof response.screenshot).toBe("string");+ },+ scrapeTimeout,+ );+ });++ describe("SVG logo handling", () => {+ concurrentIf(TEST_PRODUCTION || HAS_AI)(+ "converts SVG elements to data URLs",+ async () => {+ const response = await scrape(+ {+ url: "https://firecrawl.dev",+ formats: ["branding"],+ },+ identity,+ );++ if (response.branding?.images?.logo?.startsWith("data:image/svg")) {+ // Should be a valid SVG data URL+ expect(response.branding.images.logo).toContain("svg");+ expect(+ response.branding.images.logo.startsWith("data:image/svg+xml"),+ ).toBe(true);+ }+ },+ scrapeTimeout,+ );+ });+});diff --git a/apps/api/src/controllers/v1/types.ts b/apps/api/src/controllers/v1/types.tsindex 356b0b69d..5be946ad0 100644--- a/apps/api/src/controllers/v1/types.ts+++ b/apps/api/src/controllers/v1/types.ts@@ -14,6 +14,7 @@ import Ajv from "ajv";import { ErrorCodes } from "../../lib/error";import { integrationSchema } from "../../utils/integration";import { webhookSchema } from "../../services/webhook/schema";+import { BrandingProfile } from "../../types/branding";type Format =| "markdown"@@ -25,7 +26,8 @@ type Format =| "extract"| "json"| "summary"- | "changeTracking";+ | "changeTracking"+ | "branding";export const url = z.preprocess(x => {@@ -423,6 +425,7 @@ const baseScrapeOptions = z"json","summary","changeTracking",+ "branding",]).array().optional()@@ -954,6 +957,7 @@ export type Document = {extract?: any;json?: any;summary?: string;+ branding?: BrandingProfile;warning?: string;actions?: {screenshots?: string[];diff --git a/apps/api/src/controllers/v2/types.ts b/apps/api/src/controllers/v2/types.tsindex dd800fecf..6ed02d49b 100644--- a/apps/api/src/controllers/v2/types.ts+++ b/apps/api/src/controllers/v2/types.ts@@ -20,6 +20,7 @@ import Ajv from "ajv";import { integrationSchema } from "../../utils/integration";import { webhookSchema } from "../../services/webhook/schema";import { modifyCrawlUrl } from "../../utils/url-utils";+import { BrandingProfile } from "../../types/branding";// Base URL schema with common validation logicconst BASE_URL_SCHEMA = z.preprocess(@@ -409,7 +410,8 @@ export type FormatObject =| JsonFormatWithOptions| ChangeTrackingFormatWithOptions| ScreenshotFormatWithOptions- | AttributesFormatWithOptions;+ | AttributesFormatWithOptions+ | { type: "branding" };const pdfParserWithOptions = z.object({@@ -503,6 +505,7 @@ const baseScrapeOptions = zchangeTrackingFormatWithOptions,screenshotFormatWithOptions,attributesFormatWithOptions,+ z.object({ type: z.literal("branding") }),]).array().optional()@@ -857,6 +860,7 @@ export type Document = {extract?: any;json?: any;summary?: string;+ branding?: BrandingProfile;warning?: string;attributes?: {selector: string;@@ -1348,6 +1352,8 @@ export function fromV1ScrapeOptions(return fmt;} else if (x === "screenshot@fullPage") {return { type: "screenshot" as const, fullPage: true };+ } else if (x === "branding") {+ return { type: "branding" as const };} else {return x;}diff --git a/apps/api/src/lib/branding/llm.ts b/apps/api/src/lib/branding/llm.tsnew file mode 100644index 000000000..d848ec503--- /dev/null+++ b/apps/api/src/lib/branding/llm.ts@@ -0,0 +1,56 @@+import { generateObject } from "ai";+import { logger } from "../logger";+import { BrandingEnhancement, brandingEnhancementSchema } from "./schema";+import { buildBrandingPrompt } from "./prompt";+import { BrandingLLMInput } from "./types";+import { getModel } from "../generic-ai";++export async function enhanceBrandingWithLLM(+ input: BrandingLLMInput,+): Promise<BrandingEnhancement> {+ const model = getModel("gpt-4o-mini");++ const prompt = buildBrandingPrompt(input);++ try {+ const result = await generateObject({+ model,+ schema: brandingEnhancementSchema,+ messages: [+ {+ role: "system",+ content:+ "You are a brand design expert analyzing websites to extract accurate branding information.",+ },+ {+ role: "user",+ content: input.screenshot+ ? [+ { type: "text", text: prompt },+ { type: "image", image: input.screenshot },+ ]+ : prompt,+ },+ ],+ temperature: 0.1,+ });++ return result.object;+ } catch (error) {+ logger.error("LLM branding enhancement failed", { error });++ return {+ cleanedFonts: [],+ buttonClassification: {+ primaryButtonIndex: -1,+ primaryButtonReasoning: "LLM failed",+ secondaryButtonIndex: -1,+ secondaryButtonReasoning: "LLM failed",+ confidence: 0,+ },+ colorRoles: {+ confidence: 0,+ },+ };+ }+}diff --git a/apps/api/src/lib/branding/merge.ts b/apps/api/src/lib/branding/merge.tsnew file mode 100644index 000000000..1a4b5f2df--- /dev/null+++ b/apps/api/src/lib/branding/merge.ts@@ -0,0 +1,163 @@+import { BrandingProfile } from "../../types/branding";+import { BrandingEnhancement } from "./schema";+import { ButtonSnapshot } from "./types";++export function mergeBrandingResults(+ js: BrandingProfile,+ llm: BrandingEnhancement,+ buttonSnapshots: ButtonSnapshot[],+): BrandingProfile {+ const merged: BrandingProfile = { ...js };++ 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,+ };+ }++ if (llm.buttonClassification.confidence > 0.5 && 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",+ 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",+ shadow: secondaryBtn.shadow || undefined,+ };+ }+ }+ }++ if (llm.colorRoles.confidence > 0.7) {+ merged.colors = {+ ...merged.colors,+ primary: llm.colorRoles.primaryColor || merged.colors?.primary,+ accent: llm.colorRoles.accentColor || merged.colors?.accent,+ background: llm.colorRoles.backgroundColor || merged.colors?.background,+ textPrimary: llm.colorRoles.textPrimary || merged.colors?.textPrimary,+ };+ }++ 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;+}diff --git a/apps/api/src/lib/branding/processor.ts b/apps/api/src/lib/branding/processor.tsnew file mode 100644index 000000000..3056ea6fc--- /dev/null+++ b/apps/api/src/lib/branding/processor.ts@@ -0,0 +1,301 @@+import { BrandingProfile } from "../../types/branding";+import { BrandingScriptReturn } from "./types";+import { parse, rgb, formatHex } from "culori";++function hexify(rgba: string): string | null {+ if (!rgba) return null;++ try {+ const color = parse(rgba);+ if (!color) return null;++ // Convert to RGB space+ const rgbColor = rgb(color);+ if (!rgbColor || rgbColor.mode !== "rgb") {+ return null;+ }++ let r = rgbColor.r ?? 0;+ let g = rgbColor.g ?? 0;+ let b = rgbColor.b ?? 0;+ const alpha = rgbColor.alpha ?? 1;++ if (alpha < 1) {+ r = r * alpha + (1 - alpha);+ g = g * alpha + (1 - alpha);+ b = b * alpha + (1 - alpha);+ }++ const blendedColor = { mode: "rgb" as const, r, g, b };+ const hex = formatHex(blendedColor);+ return hex ? hex.toUpperCase() : null;+ } catch (e) {+ return null;+ }+}++// Calculate contrast for text readability+function contrastYIQ(hex: string): number {+ if (!hex) return 0;+ const h = hex.replace("#", "");+ if (h.length < 6) return 0;+ const r = parseInt(h.slice(0, 2), 16),+ g = parseInt(h.slice(2, 4), 16),+ b = parseInt(h.slice(4, 6), 16);+ return (r * 299 + g * 587 + b * 114) / 1000;+}++// Infer color palette from snapshots+function inferPalette(+ snapshots: BrandingScriptReturn["snapshots"],+ cssColors: string[],+) {+ const freq = new Map<string, number>();+ const bump = (hex: string | null, weight = 1) => {+ if (!hex) return;+ freq.set(hex, (freq.get(hex) || 0) + weight);+ };++ for (const s of snapshots) {+ const area = Math.max(1, s.rect.w * s.rect.h);+ bump(hexify(s.colors.background), 0.5 + Math.log10(area + 10));+ bump(hexify(s.colors.text), 1.0);+ bump(hexify(s.colors.border), 0.3);+ }++ for (const c of cssColors) bump(hexify(c), 0.5);++ const ranked = Array.from(freq.entries())+ .sort((a, b) => b[1] - a[1])+ .map(([h]) => h);++ const isGrayish = (hex: string) => {+ const h = hex.replace("#", "");+ if (h.length < 6) return true;+ const r = parseInt(h.slice(0, 2), 16),+ g = parseInt(h.slice(2, 4), 16),+ b = parseInt(h.slice(4, 6), 16);+ const max = Math.max(r, g, b),+ min = Math.min(r, g, b);+ return max - min < 15;+ };++ const background =+ ranked.find(h => isGrayish(h) && contrastYIQ(h) > 180) || "#FFFFFF";+ const textPrimary =+ ranked.find(h => !/^#FFFFFF$/i.test(h) && contrastYIQ(h) < 160) ||+ "#111111";+ const primary =+ ranked.find(h => !isGrayish(h) && h !== textPrimary && h !== background) ||+ "#000000";+ const accent = ranked.find(h => h !== primary && !isGrayish(h)) || primary;++ return {+ primary,+ accent,+ background,+ textPrimary: textPrimary,+ link: accent,+ };+}++// Infer spacing base unit+function inferBaseUnit(values: number[]): number {+ const vs = values+ .filter(v => Number.isFinite(v) && v > 0 && v <= 128)+ .map(v => Math.round(v));+ if (vs.length === 0) return 8;+ const candidates = [4, 6, 8, 10, 12];+ for (const c of candidates) {+ const ok =+ vs.filter(v => v % c === 0 || Math.abs((v % c) - c) <= 1 || v % c <= 1)+ .length / vs.length;+ if (ok >= 0.6) return c;+ }+ vs.sort((a, b) => a - b);+ const med = vs[Math.floor(vs.length / 2)];+ return Math.max(2, Math.min(12, Math.round(med / 2) * 2));+}++// Pick common border radius+function pickBorderRadius(radii: (number | null)[]): string {+ const rs = radii.filter((v): v is number => Number.isFinite(v));+ if (!rs.length) return "8px";+ rs.sort((a, b) => a - b);+ const med = rs[Math.floor(rs.length / 2)];+ return Math.round(med) + "px";+}++// Infer fonts list from stacks+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;+ }+ }++ return Object.keys(freq)+ .sort((a, b) => freq[b] - freq[a])+ .slice(0, 10)+ .map(f => ({ family: f, count: freq[f] }));+}++// Pick logo from images+function pickLogo(images: Array<{ type: string; src: string }>): string | null {+ const byType = (t: string) => images.find(i => i.type === t)?.src;+ return (+ byType("logo") ||+ byType("logo-svg") ||+ byType("og") ||+ byType("twitter") ||+ byType("favicon") ||+ null+ );+}++// Process raw branding data into BrandingProfile+export function processRawBranding(raw: BrandingScriptReturn): BrandingProfile {+ const palette = inferPalette(raw.snapshots, raw.cssData.colors);++ // Typography+ const typography = {+ fontFamilies: {+ primary: raw.typography.stacks.body[0] || "system-ui, sans-serif",+ heading:+ raw.typography.stacks.heading[0] ||+ raw.typography.stacks.body[0] ||+ "system-ui, sans-serif",+ },+ fontStacks: raw.typography.stacks,+ fontSizes: raw.typography.sizes,+ };++ // Spacing+ const baseUnit = inferBaseUnit(raw.cssData.spacings);+ const borderRadius = pickBorderRadius([+ ...raw.snapshots.map(s => s.radius),+ ...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(),+ ];+ const fontsList = inferFontsList([allFontStacks]);++ // Images+ const images = {+ logo: pickLogo(raw.images),+ favicon: raw.images.find(i => i.type === "favicon")?.src || null,+ ogImage:+ raw.images.find(i => i.type === "og")?.src ||+ raw.images.find(i => i.type === "twitter")?.src ||+ null,+ };++ // Components (empty for now - LLM will populate)+ const components = {+ input: {+ borderColor: "#CCCCCC",+ borderRadius: borderRadius,+ },+ };++ const buttonSnapshots = raw.snapshots+ .filter(s => {+ if (!s.isButton) return false;+ if (s.rect.w < 30 || s.rect.h < 30) return false;+ if (!s.text || s.text.trim().length === 0) return false;++ const bgHex = hexify(s.colors.background);+ if (!bgHex) return false;++ return true;+ })+ .map(s => {+ let score = 0;++ if (s.hasCTAIndicator) score += 1000;++ const text = (s.text || "").toLowerCase();+ const ctaKeywords = [+ "sign up",+ "get started",+ "start deploying",+ "start",+ "deploy",+ "try",+ "demo",+ "contact",+ "buy",+ "subscribe",+ "join",+ "register",+ "get",+ "free",+ "join",+ ];+ if (ctaKeywords.some(kw => text.includes(kw))) score += 500;++ const bgHex = hexify(s.colors.background);+ if (+ bgHex &&+ bgHex !== "#FFFFFF" &&+ bgHex !== "#FAFAFA" &&+ bgHex !== "#F5F5F5"+ ) {+ score += 300;+ }++ if (text.length > 0 && text.length < 50) score += 100;++ const area = (s.rect.w || 0) * (s.rect.h || 0);+ score += Math.log10(area + 1) * 10;++ return { ...s, _score: score };+ })+ .sort((a: any, b: any) => (b._score || 0) - (a._score || 0))+ .slice(0, 50)+ .map((s, idx) => {+ let bgHex = hexify(s.colors.background);+ const borderHex =+ s.colors.borderWidth && s.colors.borderWidth > 0+ ? hexify(s.colors.border)+ : null;++ if (!bgHex) {+ bgHex = "transparent";+ }++ return {+ index: idx,+ text: s.text || "",+ html: "",+ classes: s.classes || "",+ background: bgHex,+ textColor: hexify(s.colors.text) || "#000000",+ borderColor: borderHex,+ borderRadius: s.radius ? `${s.radius}px` : "0px",+ shadow: s.shadow || null,+ };+ });++ return {+ colorScheme: raw.colorScheme,+ fonts: fontsList,+ colors: palette,+ typography,+ spacing: {+ baseUnit: baseUnit,+ borderRadius: borderRadius,+ },+ components,+ images,+ __button_snapshots: buttonSnapshots as any,+ __framework_hints: raw.frameworkHints as any,+ };+}diff --git a/apps/api/src/lib/branding/prompt.ts b/apps/api/src/lib/branding/prompt.tsnew file mode 100644index 000000000..09c7c403f--- /dev/null+++ b/apps/api/src/lib/branding/prompt.ts@@ -0,0 +1,232 @@+import { BrandingProfile } from "../../types/branding";+import { ButtonSnapshot } from "./types";+import { parse, rgb } from "culori";++type BrandingLLMInput = {+ jsAnalysis: BrandingProfile;+ buttons: ButtonSnapshot[];+ url: string;+};++export function buildBrandingPrompt(input: BrandingLLMInput): string {+ const { jsAnalysis, buttons, url } = input;++ let prompt = `Analyze the branding of this website: ${url}\n\n`;++ // Add JS analysis context+ prompt += `## JavaScript Analysis (Baseline):\n`;+ prompt += `Color Scheme: ${jsAnalysis.colorScheme || "unknown"}\n`;++ if (jsAnalysis.colors) {+ prompt += `Detected Colors:\n`;+ Object.entries(jsAnalysis.colors).forEach(([key, value]) => {+ if (value) prompt += `- ${key}: ${value}\n`;+ });+ }++ if (jsAnalysis.fonts && jsAnalysis.fonts.length > 0) {+ prompt += `\nRaw Fonts (need cleaning):\n`;+ jsAnalysis.fonts.forEach((font: any) => {+ const family = typeof font === "string" ? font : font.family;+ const count = typeof font === "object" && font.count ? font.count : "";+ prompt += `- ${family}${count ? ` (used ${count}x)` : ""}\n`;+ });+ prompt += `\n**FONT CLEANING INSTRUCTIONS:**\n`;+ prompt += `- Remove obfuscated names (e.g., "__suisse_6d5c28" β "Suisse", "__Roboto_Mono_c8ca7d" β "Roboto Mono")\n`;+ prompt += `- Skip fallback fonts (e.g., "__suisse_Fallback_6d5c28" β ignore)\n`;+ prompt += `- Skip CSS variables (e.g., "var(--font-sans)" β ignore)\n`;+ prompt += `- Skip generic fonts (e.g., "system-ui", "sans-serif", "ui-sans-serif" β ignore)\n`;+ prompt += `- Keep only real, meaningful brand fonts (max 5)\n`;+ prompt += `- Assign roles based on usage: heading, body, monospace, display\n\n`;+ }++ // Helper to analyze color vibrancy+ const getColorInfo = (colorStr: string) => {+ if (!colorStr || colorStr === "transparent")+ return { isVibrant: false, description: "transparent" };++ let r = 0,+ g = 0,+ b = 0;+ try {+ const color = parse(colorStr);+ if (color) {+ const rgbColor = rgb(color);+ if (rgbColor && rgbColor.mode === "rgb") {+ r = Math.round((rgbColor.r ?? 0) * 255);+ g = Math.round((rgbColor.g ?? 0) * 255);+ b = Math.round((rgbColor.b ?? 0) * 255);+ }+ }+ } catch (e) {+ return {+ isVibrant: false,+ description: "unknown",+ saturation: "0.00",+ brightness: "0.00",+ };+ }++ // Calculate saturation and brightness+ const max = Math.max(r, g, b);+ const min = Math.min(r, g, b);+ const saturation = max === 0 ? 0 : (max - min) / max;+ const brightness = max / 255;++ // Vibrant = high saturation (>0.3) and decent brightness (>0.2)+ const isVibrant = saturation > 0.3 && brightness > 0.2;++ // Describe the color+ let description = "";+ if (g > r && g > b && g > 100) description = "green";+ else if (b > r && b > g && b > 100) description = "blue";+ else if (r > g && r > b && r > 100) description = "red/orange";+ else if (max < 50) description = "dark";+ else if (min > 200) description = "light/white";+ else description = "neutral";++ return {+ isVibrant,+ description,+ saturation: saturation.toFixed(2),+ brightness: brightness.toFixed(2),+ };+ };++ // Collect class patterns for framework detection+ const allClasses = new Set<string>();+ if (buttons && buttons.length > 0) {+ buttons.forEach(btn => {+ if (btn.classes) {+ btn.classes.split(/\s+/).forEach(cls => {+ if (cls.length > 0 && cls.length < 50) {+ allClasses.add(cls);+ }+ });+ }+ });+ }++ // Add framework detection hints+ if (allClasses.size > 0) {+ const classSample = Array.from(allClasses).slice(0, 50).join(", ");+ prompt += `\n## CSS Class Patterns (for framework detection):\n`;+ prompt += `Sample classes: ${classSample}\n`;++ // Add framework hints from meta/scripts+ if (+ (jsAnalysis as any).__framework_hints &&+ (jsAnalysis as any).__framework_hints.length > 0+ ) {+ prompt += `Framework hints from page: ${(jsAnalysis as any).__framework_hints.join(", ")}\n`;+ }++ prompt += `\n**Framework Detection Patterns:**\n`;+ prompt += `- Tailwind: Look for utility classes like \`flex\`, \`items-center\`, \`px-*\`, \`py-*\`, \`bg-*-500\`, \`rounded-*\`, \`text-*\`, \`space-x-*\`, \`gap-*\`\n`;+ prompt += `- Bootstrap: Look for \`btn\`, \`btn-primary\`, \`container\`, \`row\`, \`col-*\`, \`d-flex\`, \`justify-*\`, \`mb-*\`, \`mt-*\`\n`;+ prompt += `- Material UI: Look for \`MuiButton\`, \`Mui*\`, \`makeStyles\`, or modern Material classes\n`;+ prompt += `- Chakra UI: Look for \`chakra-*\`, minimal utility-style classes, or data attributes\n`;+ prompt += `- Custom: Mixed or unique class patterns that don't match standard frameworks\n\n`;+ }++ // Add button context with detailed info+ if (buttons && buttons.length > 0) {+ prompt += `## Detected Buttons (${buttons.length} total):\n`;++ // First, show a color summary to help LLM see distinct options+ const colorSummary = new Map<string, number[]>();+ buttons.forEach((btn, idx) => {+ const bg = btn.background || "transparent";+ if (!colorSummary.has(bg)) {+ colorSummary.set(bg, []);+ }+ colorSummary.get(bg)!.push(idx);+ });++ prompt += `\n**COLOR GROUPS** (buttons sharing the same background color):\n`;+ colorSummary.forEach((indices, color) => {+ const count = indices.length;+ const colorInfo = getColorInfo(color);+ prompt += `- ${color} (${colorInfo.description}${colorInfo.isVibrant ? " - VIBRANT" : ""}) β Buttons ${indices.join(", ")} (${count} button${count > 1 ? "s" : ""})\n`;+ });+ prompt += `\nβ οΈ **CRITICAL**: Primary and secondary MUST be from DIFFERENT color groups!\n\n`;++ prompt += `Analyze these buttons and identify which is the PRIMARY CTA and which is SECONDARY:\n\n`;++ buttons.forEach((btn, idx) => {+ const bgInfo = getColorInfo(btn.background);++ prompt += `**Button #${idx}:**\n`;+ prompt += `- Text: "${btn.text}"\n`;+ prompt += `- Background Color: ${btn.background} (${bgInfo.description}${bgInfo.isVibrant ? " - VIBRANT/BRAND COLOR" : ""})\n`;+ prompt += `- Text Color: ${btn.textColor}\n`;+ if (btn.borderColor) prompt += `- Border Color: ${btn.borderColor}\n`;+ if (btn.borderRadius) prompt += `- Border Radius: ${btn.borderRadius}\n`;+ prompt += `- Classes: ${btn.classes.substring(0, 150)}${btn.classes.length > 150 ? "..." : ""}\n`;+ prompt += `- HTML: \`${btn.html.substring(0, 200)}${btn.html.length > 200 ? "..." : ""}\`\n\n`;+ });+ }++ // Add specific questions+ prompt += `\n## Your Task:\n`;+ prompt += `1. **PRIMARY Button**: Identify which button (by index 0-${buttons.length - 1}) is the main call-to-action.\n`;+ prompt += ` - **CRITICAL**: Buttons with VIBRANT/BRAND COLOR backgrounds (like green, blue, orange) are ALMOST ALWAYS the primary CTA\n`;+ prompt += ` - **STRONG INDICATORS**: Look for these class patterns (very high priority):\n`;+ prompt += ` * \`bg-brand-400\`, \`bg-brand-500\`, or similar brand utility classes\n`;+ prompt += ` * \`bg-green-*\`, \`bg-blue-*\`, \`bg-purple-*\` with high numbers (400+)\n`;+ prompt += ` * Any class containing "brand", "primary", or "cta"\n`;+ prompt += ` - Look for: Bright, saturated colors (green, blue, purple, orange) + action-oriented text\n`;+ prompt += ` - Action-oriented text examples: "Get Started", "Sign Up", "Start Free", "Start your Project", "Try Now", "Get Started Free"\n`;+ prompt += ` - If a button has BOTH vibrant color AND strong CTA text, it's DEFINITELY the primary\n`;+ prompt += ` - Avoid buttons with transparent, white, or muted gray backgrounds UNLESS no vibrant buttons exist\n`;+ prompt += ` - Return the button INDEX (not text) and explain your reasoning\n\n`;++ prompt += `2. **SECONDARY Button**: Identify which button is secondary (outline, ghost, or less prominent).\n`;+ prompt += ` - **CRITICAL**: MUST have a DIFFERENT background color than the primary button you selected\n`;+ prompt += ` - **EXAMPLES OF VALID COMBINATIONS**:\n`;+ prompt += ` * Primary: #00C853 (green, vibrant) β Secondary: transparent (outline style) β\n`;+ prompt += ` * Primary: #1976D2 (blue, vibrant) β Secondary: #FFFFFF (white/light) β\n`;+ prompt += ` * Primary: #FF6B35 (orange, vibrant) β Secondary: #F5F5F5 (gray/subtle) β\n`;+ prompt += ` - **INVALID COMBINATION**:\n`;+ prompt += ` * Primary: #00C853 β Secondary: #00C853 β SAME COLOR - NOT ALLOWED!\n`;+ prompt += ` - Usually has transparent/subtle background, border, or muted colors\n`;+ prompt += ` - Common for actions like "Login", "Learn More", "Contact", "Documentation"\n`;+ prompt += ` - Often has an outline/border instead of filled background\n`;+ prompt += ` - Look at the COLOR GROUPS above - pick from a DIFFERENT group than primary\n`;+ prompt += ` - If all remaining buttons have the same color as primary, set secondaryButtonIndex to -1\n`;+ prompt += ` - Return the button INDEX and reasoning\n\n`;++ prompt += `3. **Color Roles**: Based on button colors and page context:\n`;+ prompt += ` - PRIMARY brand color (usually logo/heading color)\n`;+ prompt += ` - ACCENT color (usually the vibrant CTA button background - green, blue, etc.)\n`;+ prompt += ` - Background and text colors\n\n`;++ prompt += `4. **Brand Personality**: Overall tone and energy\n\n`;++ prompt += `5. **Design System**: Based on the class patterns shown above:\n`;+ prompt += ` - **Framework**: Identify the CSS framework (tailwind/bootstrap/material/chakra/custom/unknown)\n`;+ prompt += ` - **Component Library**: Look for prefixes like \`radix-\`, \`shadcn-\`, \`headlessui-\`, or \`react-aria-\` in classes\n`;+ prompt += ` - If using Tailwind + a component library, identify both (e.g., framework: tailwind, componentLibrary: "radix-ui")\n\n`;++ prompt += `6. **Clean Fonts**: Return up to 5 cleaned, human-readable font names\n`;+ prompt += ` - Remove framework obfuscation (Next.js hashes, etc.)\n`;+ prompt += ` - Filter out generics and CSS variables\n`;+ prompt += ` - Prioritize by frequency (shown in usage count)\n`;+ prompt += ` - Assign appropriate roles (heading, body, monospace, display)\n\n`;++ prompt += `## VALIDATION CHECKLIST - VERIFY BEFORE RESPONDING:\n`;+ prompt += `Before finalizing your answer, check:\n`;+ prompt += `1. β Are primaryButtonIndex and secondaryButtonIndex DIFFERENT numbers?\n`;+ prompt += `2. β Do they have DIFFERENT background colors? (Compare the actual hex/color values)\n`;+ prompt += `3. β If you selected buttons from the same COLOR GROUP, go back and pick a different secondary\n`;+ prompt += `4. β If no valid secondary exists (all buttons same color as primary), set secondaryButtonIndex to -1\n\n`;++ prompt += `## FINAL RULES:\n`;+ prompt += `- Primary and secondary buttons MUST have different background colors (not just different shades - completely different colors)\n`;+ prompt += `- Primary and secondary buttons MUST be different buttons (different indices)\n`;+ prompt += `- Refer to the COLOR GROUPS section above to ensure you're picking from different groups\n`;+ prompt += `- Be decisive and confident. Prioritize vibrant, saturated colors over neutral ones for primary buttons\n`;+ prompt += `- If no clear primary/secondary exists with different colors, return -1 for that index`;++ return prompt;+}diff --git a/apps/api/src/lib/branding/schema.ts b/apps/api/src/lib/branding/schema.tsnew file mode 100644index 000000000..807486af1--- /dev/null+++ b/apps/api/src/lib/branding/schema.ts@@ -0,0 +1,97 @@+import { z } from "zod";++// Schema for LLM output+export const brandingEnhancementSchema = z.object({+ // Button classification - LLM picks which buttons are primary/secondary+ buttonClassification: z.object({+ primaryButtonIndex: z+ .number()+ .describe(+ "Index of the primary CTA button in the provided list (0-based), or -1 if none found",+ ),+ primaryButtonReasoning: z+ .string()+ .describe("Why this button was selected as primary"),+ secondaryButtonIndex: z+ .number()+ .describe(+ "Index of the secondary button in the provided list (0-based), or -1 if none found",+ ),+ secondaryButtonReasoning: z+ .string()+ .describe("Why this button was selected as secondary"),+ confidence: z+ .number()+ .min(0)+ .max(1)+ .describe("Confidence in button classification (0-1)"),+ }),++ // Color role clarification+ colorRoles: z.object({+ primaryColor: z.string().nullish().describe("Main brand color (hex)"),+ accentColor: z.string().nullish().describe("Accent/CTA color (hex)"),+ backgroundColor: z+ .string()+ .nullish()+ .describe("Main background color (hex)"),+ textPrimary: z.string().nullish().describe("Primary text color (hex)"),+ confidence: z.number().min(0).max(1),+ }),++ // Brand personality+ personality: z+ .object({+ tone: z+ .enum([+ "professional",+ "playful",+ "modern",+ "traditional",+ "minimalist",+ "bold",+ ])+ .describe("Overall brand tone"),+ energy: z.enum(["low", "medium", "high"]).describe("Visual energy level"),+ targetAudience: z.string().describe("Perceived target audience"),+ })+ .optional(),++ // Design system insights+ designSystem: z+ .object({+ framework: z+ .enum([+ "tailwind",+ "bootstrap",+ "material",+ "chakra",+ "custom",+ "unknown",+ ])+ .describe("Detected CSS framework"),+ componentLibrary: z+ .string()+ .nullish()+ .describe("Detected component library (e.g., radix-ui, shadcn)"),+ })+ .optional(),++ // Font cleaning - LLM cleans and filters font names+ cleanedFonts: z+ .array(+ z.object({+ family: z.string().describe("Cleaned, human-readable font name"),+ role: z+ .enum(["heading", "body", "monospace", "display"])+ .nullish()+ .describe("Font role/usage"),+ }),+ )+ .max(5)+ .describe(+ "Top 5 cleaned fonts (remove obfuscation, fallbacks, generics, CSS vars)",+ ),+});++export type BrandingEnhancement = z.infer<typeof brandingEnhancementSchema>;diff --git a/apps/api/src/lib/branding/transformer.ts b/apps/api/src/lib/branding/transformer.tsnew file mode 100644index 000000000..07af61428--- /dev/null+++ b/apps/api/src/lib/branding/transformer.ts@@ -0,0 +1,65 @@+import { processRawBranding } from "./processor";+import { BrandingProfile } from "../../types/branding";+import { enhanceBrandingWithLLM } from "./llm";+import { Meta } from "../../scraper/scrapeURL";+import { Document } from "../../controllers/v2/types";+import { BrandingScriptReturn, ButtonSnapshot } from "./types";+import { mergeBrandingResults } from "./merge";++export async function brandingTransformer(+ meta: Meta,+ document: Document,+ rawBranding: BrandingScriptReturn,+): Promise<BrandingProfile> {+ let jsBranding = processRawBranding(rawBranding);++ if (!jsBranding) {+ return {};+ }++ let brandingProfile: BrandingProfile = jsBranding;++ try {+ meta.logger.info("Enhancing branding with LLM...");++ const buttonSnapshots: ButtonSnapshot[] =+ (jsBranding as any).__button_snapshots || [];++ meta.logger.info(+ `Sending ${buttonSnapshots.length} buttons to LLM for classification`,+ );++ const llmEnhancement = await enhanceBrandingWithLLM({+ jsAnalysis: jsBranding,+ buttons: buttonSnapshots,+ screenshot: document.screenshot,+ url: document.url || meta.url,+ });++ meta.logger.info("LLM enhancement complete", {+ primary_btn_index: llmEnhancement.buttonClassification.primaryButtonIndex,+ secondary_btn_index:+ llmEnhancement.buttonClassification.secondaryButtonIndex,+ button_confidence: llmEnhancement.buttonClassification.confidence,+ color_confidence: llmEnhancement.colorRoles.confidence,+ });++ brandingProfile = mergeBrandingResults(+ jsBranding,+ llmEnhancement,+ buttonSnapshots,+ );+ } catch (error) {+ meta.logger.error(+ "LLM branding enhancement failed, using JS analysis only",+ { error },+ );+ brandingProfile = jsBranding;+ }++ if (process.env.DEBUG_BRANDING !== "true") {+ delete (brandingProfile as any).__button_snapshots;+ }++ return brandingProfile;+}diff --git a/apps/api/src/lib/branding/types.ts b/apps/api/src/lib/branding/types.tsnew file mode 100644index 000000000..d6e56e4fc--- /dev/null+++ b/apps/api/src/lib/branding/types.ts@@ -0,0 +1,71 @@+import { BrandingProfile } from "../../types/branding";++export interface ButtonSnapshot {+ index: number;+ text: string;+ html: string;+ classes: string;+ background: string;+ textColor: string;+ borderColor?: string | null;+ borderRadius?: string;+ shadow?: string | null;+}++export interface BrandingLLMInput {+ jsAnalysis: BrandingProfile;+ buttons: ButtonSnapshot[];++ screenshot?: string;+ url: string;+}++/**+ * Data structure returned by the branding script+ */+export interface BrandingScriptReturn {+ cssData: {+ colors: string[];+ spacings: number[];+ radii: number[];+ };+ snapshots: Array<{+ tag: string;+ classes: string;+ text: string;+ rect: { w: number; h: number };+ colors: {+ text: string;+ background: string;+ border: string;+ borderWidth: number | null;+ };+ typography: {+ fontStack: string[];+ size: string | null;+ weight: number | null;+ };+ radius: number | null;+ shadow: string | null;+ isButton: boolean;+ isNavigation?: boolean;+ hasCTAIndicator?: boolean;+ isInput: boolean;+ isLink: boolean;+ }>;+ images: Array<{ type: string; src: string }>;+ typography: {+ stacks: {+ body: string[];+ heading: string[];+ paragraph: string[];+ };+ sizes: {+ h1: string;+ h2: string;+ body: string;+ };+ };+ frameworkHints: string[];+ colorScheme: "light" | "dark";+}diff --git a/apps/api/src/lib/entities.ts b/apps/api/src/lib/entities.tsindex bd76e17aa..670188aa3 100644--- a/apps/api/src/lib/entities.ts+++ b/apps/api/src/lib/entities.ts@@ -1,4 +1,5 @@import type { Action } from "../controllers/v1/types";+import type { BrandingProfile } from "../types/branding";export type PageOptions = {includeMarkdown?: boolean;@@ -70,7 +71,13 @@ export class Document {actions?: {screenshots?: string[];scrapes?: ScrapeActionContent[];+ javascriptReturns?: {+ type: string;+ value: unknown;+ }[];+ pdfs?: string[];};+ branding?: BrandingProfile;index?: number;linksOnPage?: string[]; // Add this new field as a separate propertydiff --git a/apps/api/src/scraper/scrapeURL/engines/fire-engine/brandingScript.ts b/apps/api/src/scraper/scrapeURL/engines/fire-engine/brandingScript.tsnew file mode 100644index 000000000..1c1a95946--- /dev/null+++ b/apps/api/src/scraper/scrapeURL/engines/fire-engine/brandingScript.ts@@ -0,0 +1,515 @@+export const getBrandingScript = () => String.raw`+(function __extractBrandDesign() {+ const toPx = v => {+ if (!v || v === "auto") return null;+ if (v.endsWith("px")) return parseFloat(v);+ if (v.endsWith("rem"))+ return (+ parseFloat(v) *+ parseFloat(getComputedStyle(document.documentElement).fontSize || 16)+ );+ if (v.endsWith("em"))+ return (+ parseFloat(v) *+ parseFloat(getComputedStyle(document.body).fontSize || 16)+ );+ if (v.endsWith("%")) return null;+ const num = parseFloat(v);+ return Number.isFinite(num) ? num : null;+ };++ const resolveSvgStyles = svg => {+ const originalElements = [svg, ...svg.querySelectorAll("*")];+ const computedStyles = originalElements.map(el => ({+ el,+ computed: getComputedStyle(el),+ }));++ const clone = svg.cloneNode(true);+ const clonedElements = [clone, ...clone.querySelectorAll("*")];++ const svgDefaults = {+ fill: "rgb(0, 0, 0)",+ stroke: "none",+ "stroke-width": "1px",+ opacity: "1",+ "fill-opacity": "1",+ "stroke-opacity": "1",+ };++ const applyResolvedStyle = (clonedEl, originalEl, computed, prop) => {+ const attrValue = originalEl.getAttribute(prop);+ const value = computed.getPropertyValue(prop);++ if (attrValue && attrValue.includes("var(")) {+ clonedEl.removeAttribute(prop);+ if (value && value.trim() && value !== "none") {+ clonedEl.style.setProperty(prop, value, "important");+ }+ } else if (value && value.trim()) {+ const isExplicit =+ originalEl.hasAttribute(prop) || originalEl.style[prop];+ const isDifferent =+ svgDefaults[prop] !== undefined && value !== svgDefaults[prop];+ if (isExplicit || isDifferent) {+ clonedEl.style.setProperty(prop, value, "important");+ }+ }+ };++ for (let i = 0; i < clonedElements.length; i++) {+ const clonedEl = clonedElements[i];+ const originalEl = originalElements[i];+ const computed = computedStyles[i]?.computed;+ if (!computed) continue;++ const allProps = [+ "fill",+ "stroke",+ "color",+ "stop-color",+ "flood-color",+ "lighting-color",+ "stroke-width",+ "stroke-dasharray",+ "stroke-dashoffset",+ "stroke-linecap",+ "stroke-linejoin",+ "opacity",+ "fill-opacity",+ "stroke-opacity",+ ];++ for (const prop of allProps) {+ applyResolvedStyle(clonedEl, originalEl, computed, prop);+ }+ }++ return clone;+ };++ const collectCSSData = () => {+ const data = {+ colors: [],+ spacings: [],+ radii: [],+ };++ for (const sheet of Array.from(document.styleSheets)) {+ let rules;+ try {+ rules = sheet.cssRules;+ } catch (e) {+ continue;+ }+ if (!rules) continue;++ for (const rule of Array.from(rules)) {+ try {+ if (rule.type === CSSRule.STYLE_RULE) {+ const s = rule.style;++ [+ "color",+ "background-color",+ "border-color",+ "fill",+ "stroke",+ ].forEach(prop => {+ const val = s.getPropertyValue(prop);+ if (val) data.colors.push(val);+ });++ [+ "border-radius",+ "border-top-left-radius",+ "border-top-right-radius",+ "border-bottom-left-radius",+ "border-bottom-right-radius",+ ].forEach(p => {+ const v = toPx(s.getPropertyValue(p));+ if (v) data.radii.push(v);+ });++ [+ "margin",+ "margin-top",+ "margin-right",+ "margin-bottom",+ "margin-left",+ "padding",+ "padding-top",+ "padding-right",+ "padding-bottom",+ "padding-left",+ "gap",+ "row-gap",+ "column-gap",+ ].forEach(p => {+ const v = toPx(s.getPropertyValue(p));+ if (v) data.spacings.push(v);+ });+ }+ } catch {}+ }+ }++ return data;+ };++ const sampleElements = () => {+ const picks = [];+ const pushQ = (q, limit = 10) => {+ for (const el of Array.from(document.querySelectorAll(q)).slice(0, limit))+ picks.push(el);+ };++ pushQ('header img, .site-logo img, img[alt*=logo i], img[src*="logo"]', 5);+ pushQ(+ 'button, [role=button], [data-primary-button], [data-secondary-button], [data-cta], a.button, a.btn, [class*="btn"], [class*="button"], a[class*="bg-brand"], a[class*="bg-primary"], a[class*="bg-accent"], a[type="button"], a[type="button"][class*="bg-"]',+ 50,+ );+ pushQ('input, select, textarea, [class*="form-control"]', 25);+ pushQ("h1, h2, h3, p, a", 50);++ return Array.from(new Set(picks.filter(Boolean)));+ };++ const getStyleSnapshot = el => {+ const cs = getComputedStyle(el);+ const rect = el.getBoundingClientRect();++ const fontStack =+ cs+ .getPropertyValue("font-family")+ ?.split(",")+ .map(f => f.replace(/["']/g, "").trim())+ .filter(Boolean) || [];++ let classNames = "";+ try {+ if (el.getAttribute) {+ const attrClass = el.getAttribute("class");+ if (attrClass) classNames = attrClass.toLowerCase();+ }+ if (!classNames && el.className) {+ if (typeof el.className === "string") {+ classNames = el.className.toLowerCase();+ } else if (el.className.baseVal) {+ classNames = el.className.baseVal.toLowerCase();+ }+ }+ } catch (e) {+ try {+ if (el.className && typeof el.className === "string") {+ classNames = el.className.toLowerCase();+ }+ } catch (e2) {+ classNames = "";+ }+ }++ let bgColor = cs.getPropertyValue("background-color");+ const textColor = cs.getPropertyValue("color");++ const isButton = el.matches(+ 'button,[role=button],[data-primary-button],[data-secondary-button],[data-cta],a.button,a.btn,[class*="btn"],[class*="button"],a[class*="bg-brand"],a[class*="bg-primary"],a[class*="bg-accent"],a[type="button"],a[type="button"][class*="bg-"]',+ );++ let isNavigation = false;+ let hasCTAIndicator = false;++ try {+ hasCTAIndicator =+ el.matches(+ '[data-primary-button],[data-secondary-button],[data-cta],[class*="cta"],[class*="hero"]',+ ) ||+ el.getAttribute("data-primary-button") === "true" ||+ el.getAttribute("data-secondary-button") === "true";++ if (!hasCTAIndicator) {+ isNavigation =+ el.matches(+ '[role="tab"],[role="menuitem"],[aria-haspopup],[class*="nav-"],[class*="-nav"],[class*="menu-"],[class*="-menu"],[class*="toggle"],[class*="trigger"]',+ ) ||+ !!el.closest(+ 'nav, [role="navigation"], [class*="navigation"], [class*="dropdown"], [role="menu"]',+ );+ }+ } catch (e) {}++ if (isButton && bgColor) {+ let isTransparent =+ bgColor === "transparent" || bgColor === "rgba(0, 0, 0, 0)";+ let hasLowAlpha = false;++ const alphaMatch = bgColor.match(+ /(?:rgba?\([^,]*,[^,]*,[^,]*,\s*|color\([^/]*\/\s*)([\d.]+)\)?$/,+ );+ if (alphaMatch) {+ const alpha = parseFloat(alphaMatch[1]);+ hasLowAlpha = alpha < 0.1;+ }++ if (isTransparent || hasLowAlpha) {+ let parent = el.parentElement;+ let depth = 0;+ while (parent && depth < 5) {+ const parentBg =+ getComputedStyle(parent).getPropertyValue("background-color");+ if (+ parentBg &&+ parentBg !== "transparent" &&+ parentBg !== "rgba(0, 0, 0, 0)"+ ) {+ const parentAlphaMatch = parentBg.match(+ /(?:rgba?\([^,]*,[^,]*,[^,]*,\s*|color\([^/]*\/\s*)([\d.]+)\)?$/,+ );+ const parentAlpha = parentAlphaMatch+ ? parseFloat(parentAlphaMatch[1])+ : 1;+ if (parentAlpha >= 0.1) {+ bgColor = parentBg;+ break;+ }+ }+ parent = parent.parentElement;+ depth++;+ }+ }+ }++ return {+ tag: el.tagName.toLowerCase(),+ classes: classNames,+ text: (el.textContent && el.textContent.trim().substring(0, 100)) || "",+ rect: { w: rect.width, h: rect.height },+ colors: {+ text: textColor,+ background: bgColor,+ border: cs.getPropertyValue("border-top-color"),+ borderWidth: toPx(cs.getPropertyValue("border-top-width")),+ },+ typography: {+ fontStack,+ size: cs.getPropertyValue("font-size") || null,+ weight: parseInt(cs.getPropertyValue("font-weight"), 10) || null,+ },+ radius: toPx(cs.getPropertyValue("border-radius")),+ shadow: cs.getPropertyValue("box-shadow") || null,+ isButton: isButton && !isNavigation,+ isNavigation: isNavigation,+ hasCTAIndicator: hasCTAIndicator,+ isInput: el.matches('input,select,textarea,[class*="form-control"]'),+ isLink: el.matches("a"),+ };+ };++ const findImages = () => {+ const imgs = [];+ const push = (src, type) => {+ if (src) imgs.push({ type, src });+ };++ push(document.querySelector('link[rel*="icon" i]')?.href, "favicon");+ push(document.querySelector('meta[property="og:image" i]')?.content, "og");+ push(+ document.querySelector('meta[name="twitter:image" i]')?.content,+ "twitter",+ );++ const headerLinkImg = document.querySelector(+ 'header a img, header a svg, nav a img, nav a svg, [role="banner"] a img, [role="banner"] a svg, .header a img, .header a svg',+ );++ if (headerLinkImg) {+ if (headerLinkImg.tagName.toLowerCase() === "svg") {+ const resolvedSvg = resolveSvgStyles(headerLinkImg);+ const serializer = new XMLSerializer();+ const svgStr =+ "data:image/svg+xml;utf8," ++ encodeURIComponent(serializer.serializeToString(resolvedSvg));+ push(svgStr, "logo-svg");+ } else {+ push(headerLinkImg.src, "logo");+ }+ } else {+ const logoImgCandidates = Array.from(document.images)+ .filter(+ img =>+ /logo/i.test(img.alt || "") ||+ /logo/i.test(img.src) ||+ img.closest('[class*="logo"]'),+ )+ .filter(+ img =>+ !img.closest(+ '[class*="testimonial"], [class*="client"], [class*="partner"]',+ ),+ );++ const logoImg = logoImgCandidates.reduce((best, img) => {+ if (!best) return img;+ const imgInHeader = img.closest('header, nav, [role="banner"]');+ const bestInHeader = best.closest('header, nav, [role="banner"]');+ if (imgInHeader && !bestInHeader) return img;+ if (!imgInHeader && bestInHeader) return best;+ const imgRect = img.getBoundingClientRect();+ const bestRect = best.getBoundingClientRect();+ return imgRect.top < bestRect.top ? img : best;+ }, null);++ if (logoImg) push(logoImg.src, "logo");++ const svgLogoCandidates = Array.from(document.querySelectorAll("svg"))+ .filter(+ s => /logo/i.test(s.id) || /logo/i.test(s.className?.baseVal || ""),+ )+ .filter(+ svg =>+ !svg.closest(+ '[class*="testimonial"], [class*="client"], [class*="partner"]',+ ),+ );++ const svgLogo = svgLogoCandidates.reduce((best, svg) => {+ if (!best) return svg;+ const svgInHeader = svg.closest('header, nav, [role="banner"]');+ const bestInHeader = best.closest('header, nav, [role="banner"]');+ if (svgInHeader && !bestInHeader) return svg;+ if (!svgInHeader && bestInHeader) return best;+ const svgRect = svg.getBoundingClientRect();+ const bestRect = best.getBoundingClientRect();+ return svgRect.top < bestRect.top ? svg : best;+ }, null);++ if (svgLogo) {+ const resolvedSvg = resolveSvgStyles(svgLogo);+ const serializer = new XMLSerializer();+ const svgStr =+ "data:image/svg+xml;utf8," ++ encodeURIComponent(serializer.serializeToString(resolvedSvg));+ push(svgStr, "logo-svg");+ }+ }++ return imgs;+ };++ const getTypography = () => {+ const pickFontStack = el => {+ return (+ getComputedStyle(el)+ .fontFamily?.split(",")+ .map(f => f.replace(/["']/g, "").trim())+ .filter(Boolean) || []+ );+ };++ const h1 = document.querySelector("h1") || document.body;+ const h2 = document.querySelector("h2") || h1;+ const p = document.querySelector("p") || document.body;+ const body = document.body;++ return {+ stacks: {+ body: pickFontStack(body),+ heading: pickFontStack(h1),+ paragraph: pickFontStack(p),+ },+ sizes: {+ h1: getComputedStyle(h1).fontSize || "32px",+ h2: getComputedStyle(h2).fontSize || "24px",+ body: getComputedStyle(p).fontSize || "16px",+ },+ };+ };++ const detectFrameworkHints = () => {+ const hints = [];++ const generator = document.querySelector('meta[name="generator"]');+ if (generator) hints.push(generator.getAttribute("content") || "");++ const scripts = Array.from(document.querySelectorAll("script[src]"))+ .map(s => s.getAttribute("src") || "")+ .filter(Boolean);++ if (+ scripts.some(s => s.includes("tailwind") || s.includes("cdn.tailwindcss"))+ ) {+ hints.push("tailwind");+ }+ if (scripts.some(s => s.includes("bootstrap"))) {+ hints.push("bootstrap");+ }+ if (scripts.some(s => s.includes("mui") || s.includes("material-ui"))) {+ hints.push("material-ui");+ }++ return hints.filter(Boolean);+ };++ const detectColorScheme = () => {+ const body = document.body;+ const html = document.documentElement;++ if (+ html.classList.contains("dark") ||+ body.classList.contains("dark") ||+ html.classList.contains("dark-mode") ||+ body.classList.contains("dark-mode") ||+ html.getAttribute("data-theme") === "dark" ||+ body.getAttribute("data-theme") === "dark" ||+ html.getAttribute("data-bs-theme") === "dark"+ ) {+ return "dark";+ }++ const bg =+ getComputedStyle(body).backgroundColor ||+ getComputedStyle(html).backgroundColor;+ const match = bg.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/);+ if (match) {+ const [r, g, b] = match.slice(1, 4).map(n => parseInt(n, 10));+ const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;+ return luminance < 0.5 ? "dark" : "light";+ }++ return "light";+ };++ const cssData = collectCSSData();+ const elements = sampleElements();+ const snapshots = elements.map(getStyleSnapshot);+ const images = findImages();+ const typography = getTypography();+ const frameworkHints = detectFrameworkHints();+ const colorScheme = detectColorScheme();++ const buttonDebug = snapshots+ .filter(s => s.isButton)+ .slice(0, 10)+ .map((s, idx) => ({+ index: idx,+ text: (s.text || "").substring(0, 50),+ bgColor: s.colors.background,+ textColor: s.colors.text,+ classes: s.classes,+ rect: s.rect,+ }));++ return {+ branding: {+ cssData,+ snapshots,+ images,+ typography,+ frameworkHints,+ colorScheme,+ debug: {+ buttonColors: buttonDebug,+ },+ },+ };+})();`;diff --git a/apps/api/src/scraper/scrapeURL/engines/fire-engine/index.ts b/apps/api/src/scraper/scrapeURL/engines/fire-engine/index.tsindex b8d575112..4b40f031f 100644--- a/apps/api/src/scraper/scrapeURL/engines/fire-engine/index.ts+++ b/apps/api/src/scraper/scrapeURL/engines/fire-engine/index.ts@@ -33,6 +33,7 @@ import { Action } from "../../../../controllers/v1/types";import { AbortManagerThrownError } from "../../lib/abortManager";import { youtubePostprocessor } from "../../postprocessors/youtube";import { withSpan, setSpanAttributes } from "../../../../lib/otel-tracer";+import { getBrandingScript } from "./brandingScript";// This function does not take `Meta` on purpose. It may not access any// meta values to construct the request -- that must be done by the@@ -255,6 +256,14 @@ export async function scrapeURLWithFireEngineChromeCDP(},]: []),+ ...(hasFormatOfType(meta.options.formats, "branding")+ ? [+ {+ type: "executeJavascript" as const,+ script: getBrandingScript(),+ },+ ]+ : []),];const totalWait = actions.reduce(@@ -262,6 +271,13 @@ export async function scrapeURLWithFireEngineChromeCDP(0,);+ const shouldAllowMedia =+ hasFormatOfType(meta.options.formats, "branding") ||+ youtubePostprocessor.shouldRun(+ meta,+ new URL(meta.rewrittenUrl ?? meta.url),+ );+const request: FireEngineScrapeRequestCommon &FireEngineScrapeRequestChromeCDP = {url: meta.rewrittenUrl ?? meta.url,@@ -284,12 +300,7 @@ export async function scrapeURLWithFireEngineChromeCDP(!meta.internalOptions.zeroDataRetention &&meta.internalOptions.saveScrapeResultToGCS,zeroDataRetention: meta.internalOptions.zeroDataRetention,- ...(youtubePostprocessor.shouldRun(- meta,- new URL(meta.rewrittenUrl ?? meta.url),- )- ? { blockMedia: false }- : {}),+ ...(shouldAllowMedia ? { blockMedia: false } : {}),};let response = await performFireEngineScrape(@@ -326,6 +337,40 @@ export async function scrapeURLWithFireEngineChromeCDP(});}+ const javascriptReturns = (response.actionResults ?? [])+ .filter(x => x.type === "executeJavascript")+ .map(x => {+ const rawReturn = (x.result as { return: string }).return;+ try {+ const parsed = JSON.parse(rawReturn);+ if (+ parsed &&+ typeof parsed === "object" &&+ "type" in parsed &&+ typeof (parsed as any).type === "string" &&+ "value" in parsed+ ) {+ return {+ type: String((parsed as any).type),+ value: (parsed as any).value,+ };+ }++ return {+ type: "unknown",+ value: parsed,+ };+ } catch (error) {+ meta.logger.warn("Failed to parse executeJavascript return", {+ error,+ });+ return {+ type: "unknown",+ value: rawReturn,+ };+ }+ });+return {url: response.url ?? meta.url,@@ -344,11 +389,7 @@ export async function scrapeURLWithFireEngineChromeCDP(actions: {screenshots: response.screenshots ?? [],scrapes: response.actionContent ?? [],- javascriptReturns: (response.actionResults ?? [])- .filter(x => x.type === "executeJavascript")- .map(x =>- JSON.parse((x.result as any as { return: string }).return),- ),+ javascriptReturns,pdfs: (response.actionResults ?? []).filter(x => x.type === "pdf").map(x => x.result.link),diff --git a/apps/api/src/scraper/scrapeURL/engines/index.ts b/apps/api/src/scraper/scrapeURL/engines/index.tsindex 8e1e67166..357788beb 100644--- a/apps/api/src/scraper/scrapeURL/engines/index.ts+++ b/apps/api/src/scraper/scrapeURL/engines/index.ts@@ -18,6 +18,7 @@ import { useIndex } from "../../../services";import { hasFormatOfType } from "../../../lib/format-utils";import { getPDFMaxPages } from "../../../controllers/v2/types";import { PdfMetadata } from "@mendable/firecrawl-rs";+import { BrandingProfile } from "../../../types/branding";export type Engine =| "fire-engine;chrome-cdp"@@ -75,6 +76,7 @@ const featureFlags = ["skipTlsVerification","useFastMode","stealthProxy",+ "branding","disableAdblock",] as const;@@ -97,6 +99,7 @@ const featureFlagOptions: {mobile: { priority: 10 },skipTlsVerification: { priority: 10 },stealthProxy: { priority: 20 },+ branding: { priority: 20 }, // Requires CDP executeJavascriptdisableAdblock: { priority: 10 },} as const;@@ -119,6 +122,8 @@ export type EngineScrapeResult = {pdfs: string[];};+ branding?: BrandingProfile;+pdfMetadata?: PdfMetadata;cacheInfo?: {@@ -203,6 +208,7 @@ const engineOptions: {skipTlsVerification: true,useFastMode: true,stealthProxy: false,+ branding: false,disableAdblock: true,},quality: 1000, // index should always be tried first@@ -221,6 +227,7 @@ const engineOptions: {skipTlsVerification: true,useFastMode: false,stealthProxy: false,+ branding: true,disableAdblock: false,},quality: 50,@@ -239,6 +246,7 @@ const engineOptions: {skipTlsVerification: true,useFastMode: false,stealthProxy: false,+ branding: true,disableAdblock: false,},quality: 45,@@ -257,6 +265,7 @@ const engineOptions: {skipTlsVerification: true,useFastMode: true,stealthProxy: false,+ branding: false,disableAdblock: false,},quality: -1,@@ -275,6 +284,7 @@ const engineOptions: {skipTlsVerification: true,useFastMode: false,stealthProxy: true,+ branding: true,disableAdblock: false,},quality: -2,@@ -293,6 +303,7 @@ const engineOptions: {skipTlsVerification: true,useFastMode: false,stealthProxy: true,+ branding: true,disableAdblock: false,},quality: -5,@@ -311,6 +322,7 @@ const engineOptions: {skipTlsVerification: false,useFastMode: false,stealthProxy: false,+ branding: false,disableAdblock: true,},quality: 40,@@ -329,6 +341,7 @@ const engineOptions: {skipTlsVerification: false,useFastMode: false,stealthProxy: true,+ branding: false,disableAdblock: true,},quality: -10,@@ -347,6 +360,7 @@ const engineOptions: {skipTlsVerification: true,useFastMode: false,stealthProxy: false,+ branding: false,disableAdblock: false,},quality: 20,@@ -365,6 +379,7 @@ const engineOptions: {skipTlsVerification: true,useFastMode: true,stealthProxy: false,+ branding: false,disableAdblock: false,},quality: 10,@@ -383,6 +398,7 @@ const engineOptions: {skipTlsVerification: true,useFastMode: true,stealthProxy: true,+ branding: false,disableAdblock: false,},quality: -15,@@ -401,6 +417,7 @@ const engineOptions: {skipTlsVerification: true,useFastMode: true,stealthProxy: false,+ branding: false,disableAdblock: false,},quality: 5,@@ -419,6 +436,7 @@ const engineOptions: {skipTlsVerification: false,useFastMode: true,stealthProxy: true, // kinda...+ branding: false,disableAdblock: true,},quality: -20,@@ -437,6 +455,7 @@ const engineOptions: {skipTlsVerification: false,useFastMode: true,stealthProxy: true, // kinda...+ branding: false,disableAdblock: true,},quality: -20,@@ -448,6 +467,7 @@ export function shouldUseIndex(meta: Meta) {useIndex &&process.env.FIRECRAWL_INDEX_WRITE_ONLY !== "true" &&!hasFormatOfType(meta.options.formats, "changeTracking") &&+ !hasFormatOfType(meta.options.formats, "branding") &&// Skip index if a non-default PDF maxPages is specifiedgetPDFMaxPages(meta.options.parsers) === undefined &&meta.options.maxAge !== 0 &&@@ -553,6 +573,17 @@ export function buildFallbackList(meta: Meta): {selectedEngines,});+ if (meta.featureFlags.has("branding")) {+ const hasCDPEngine = selectedEngines.some(+ f => !f.unsupportedFeatures.has("branding"),+ );+ if (!hasCDPEngine) {+ throw new Error(+ "Branding extraction requires Chrome CDP (fire-engine). ",+ );+ }+ }+return selectedEngines;}diff --git a/apps/api/src/scraper/scrapeURL/index.ts b/apps/api/src/scraper/scrapeURL/index.tsindex d3ad70226..57b43ce19 100644--- a/apps/api/src/scraper/scrapeURL/index.ts+++ b/apps/api/src/scraper/scrapeURL/index.ts@@ -134,6 +134,10 @@ function buildFeatureFlags(}}+ if (hasFormatOfType(options.formats, "branding")) {+ flags.add("branding");+ }+if (options.waitFor !== 0) {flags.add("waitFor");}@@ -721,6 +725,7 @@ async function scrapeURLLoop(meta: Meta): Promise<ScrapeUrlResponse> {rawHtml: engineResult.html,screenshot: engineResult.screenshot,actions: engineResult.actions,+ branding: engineResult.branding,metadata: {sourceURL: meta.internalOptions.unnormalizedSourceURL ?? meta.url,url: engineResult.url,diff --git a/apps/api/src/scraper/scrapeURL/transformers/index.ts b/apps/api/src/scraper/scrapeURL/transformers/index.tsindex 12bbb1c18..956f46490 100644--- a/apps/api/src/scraper/scrapeURL/transformers/index.ts+++ b/apps/api/src/scraper/scrapeURL/transformers/index.ts@@ -15,10 +15,8 @@ import { deriveDiff } from "./diff";import { useIndex, useSearchIndex } from "../../../services/index";import { sendDocumentToIndex } from "../engines/index/index";import { sendDocumentToSearchIndex } from "./sendToSearchIndex";-import {- hasFormatOfType,- hasAnyFormatOfTypes,-} from "../../../lib/format-utils";+import { hasFormatOfType } from "../../../lib/format-utils";+import { brandingTransformer } from "../../../lib/branding/transformer";type Transformer = (meta: Meta,@@ -161,6 +159,46 @@ async function deriveImagesFromHTML(return document;}+async function deriveBrandingFromActions(+ meta: Meta,+ document: Document,+): Promise<Document> {+ const hasBranding = hasFormatOfType(meta.options.formats, "branding");++ if (!hasBranding) {+ return document;+ }++ if (document.branding !== undefined) {+ return document;+ }++ /**+ * Find the branding return in the actions javascript returns+ * @see src/scraper/scrapeURL/engines/fire-engine/scripts/branding.js+ */+ const brandingReturnIndex = document.actions?.javascriptReturns?.findIndex(+ x => x.type === "object" && "branding" in (x.value as any),+ );++ if (brandingReturnIndex === -1 || brandingReturnIndex === undefined) {+ return document;+ }++ // cast as any since this is js return, we might need to validate this+ const javascriptReturn = document.actions!.javascriptReturns![+ brandingReturnIndex+ ].value as any;++ const rawBranding = javascriptReturn?.branding;++ document.actions!.javascriptReturns!.splice(brandingReturnIndex, 1);++ document.branding = await brandingTransformer(meta, document, rawBranding);++ return document;+}+function coerceFieldsToFormats(meta: Meta, document: Document): Document {const hasMarkdown = hasFormatOfType(meta.options.formats, "markdown");const hasRawHtml = hasFormatOfType(meta.options.formats, "rawHtml");@@ -174,6 +212,7 @@ function coerceFieldsToFormats(meta: Meta, document: Document): Document {const hasJson = hasFormatOfType(meta.options.formats, "json");const hasScreenshot = hasFormatOfType(meta.options.formats, "screenshot");const hasSummary = hasFormatOfType(meta.options.formats, "summary");+ const hasBranding = hasFormatOfType(meta.options.formats, "branding");if (!hasMarkdown && document.markdown !== undefined) {delete document.markdown;@@ -288,6 +327,17 @@ function coerceFieldsToFormats(meta: Meta, document: Document): Document {);}+ if (!hasBranding && document.branding !== undefined) {+ meta.logger.warn(+ "Removed branding from Document because it wasn't in formats -- this indicates the engine returned unexpected data.",+ );+ delete document.branding;+ } else if (hasBranding && document.branding === undefined) {+ meta.logger.warn(+ "Request had format branding, but there was no branding field in the result.",+ );+ }+if (!hasChangeTracking && document.changeTracking !== undefined) {meta.logger.warn("Removed changeTracking from Document because it wasn't in formats -- this is extremely wasteful and indicates a bug.",@@ -323,6 +373,20 @@ function coerceFieldsToFormats(meta: Meta, document: Document): Document {if (meta.options.actions === undefined || meta.options.actions.length === 0) {delete document.actions;+ } else if (document.actions) {+ // Check if all action arrays are empty+ const hasScreenshots =+ document.actions.screenshots && document.actions.screenshots.length > 0;+ const hasScrapes =+ document.actions.scrapes && document.actions.scrapes.length > 0;+ const hasJsReturns =+ document.actions.javascriptReturns &&+ document.actions.javascriptReturns.length > 0;+ const hasPdfs = document.actions.pdfs && document.actions.pdfs.length > 0;++ if (!hasScreenshots && !hasScrapes && !hasJsReturns && !hasPdfs) {+ delete document.actions;+ }}return document;@@ -334,6 +398,7 @@ const transformerStack: Transformer[] = [deriveMarkdownFromHTML,deriveLinksFromHTML,deriveImagesFromHTML,+ deriveBrandingFromActions,deriveMetadataFromRawHTML,uploadScreenshot,...(useIndex ? [sendDocumentToIndex] : []),diff --git a/apps/api/src/types/branding.ts b/apps/api/src/types/branding.tsnew file mode 100644index 000000000..001c34069--- /dev/null+++ b/apps/api/src/types/branding.ts@@ -0,0 +1,148 @@+export interface BrandingProfile {+ colorScheme?: "light" | "dark";+ logo?: string | null;+ fonts?: Array<{+ family: string;+ [key: string]: unknown;+ }>;+ colors?: {+ primary?: string;+ secondary?: string;+ accent?: string;+ background?: string;+ textPrimary?: string;+ textSecondary?: string;+ link?: string;+ success?: string;+ warning?: string;+ error?: string;+ [key: string]: string | undefined;+ };+ typography?: {+ fontFamilies?: {+ primary?: string;+ heading?: string;+ code?: string;+ [key: string]: string | undefined;+ };+ fontStacks?: {+ primary?: string[];+ heading?: string[];+ body?: string[];+ paragraph?: string[];+ [key: string]: string[] | undefined;+ };+ fontSizes?: {+ h1?: string;+ h2?: string;+ h3?: string;+ body?: string;+ small?: string;+ [key: string]: string | undefined;+ };+ lineHeights?: {+ heading?: number;+ body?: number;+ [key: string]: number | undefined;+ };+ fontWeights?: {+ light?: number;+ regular?: number;+ medium?: number;+ bold?: number;+ [key: string]: number | undefined;+ };+ };+ spacing?: {+ baseUnit?: number;+ padding?: Record<string, number>;+ margins?: Record<string, number>;+ gridGutter?: number;+ borderRadius?: string;+ [key: string]: number | string | Record<string, number> | undefined;+ };+ components?: {+ buttonPrimary?: {+ background?: string;+ textColor?: string;+ borderColor?: string;+ borderRadius?: string;+ [key: string]: string | undefined;+ };+ buttonSecondary?: {+ background?: string;+ textColor?: string;+ borderColor?: string;+ borderRadius?: string;+ [key: string]: string | undefined;+ };+ input?: {+ borderColor?: string;+ focusBorderColor?: string;+ borderRadius?: string;+ [key: string]: string | undefined;+ };+ [key: string]: unknown;+ };+ icons?: {+ style?: string;+ primaryColor?: string;+ [key: string]: string | undefined;+ };+ images?: {+ logo?: string | null;+ favicon?: string | null;+ ogImage?: string | null;+ [key: string]: string | null | undefined;+ };+ animations?: {+ transitionDuration?: string;+ easing?: string;+ [key: string]: string | undefined;+ };+ layout?: {+ grid?: {+ columns?: number;+ maxWidth?: string;+ [key: string]: number | string | undefined;+ };+ headerHeight?: string;+ footerHeight?: string;+ [key: string]:+ | number+ | string+ | Record<string, number | string | undefined>+ | undefined;+ };+ tone?: {+ voice?: string;+ emojiUsage?: string;+ [key: string]: string | undefined;+ };+ personality?: {+ tone:+ | "professional"+ | "playful"+ | "modern"+ | "traditional"+ | "minimalist"+ | "bold";+ energy: "low" | "medium" | "high";+ targetAudience: string;+ };+ // Debug information (kept for troubleshooting button selection)+ __llm_button_reasoning?: {+ primary: {+ index: number;+ text: string;+ reasoning: string;+ };+ secondary: {+ index: number;+ text: string;+ reasoning: string;+ };+ confidence: number;+ };+ [key: string]: unknown;+}diff --git a/apps/api/v1-openapi.json b/apps/api/v1-openapi.jsonindex ccab024d5..5176e5472 100644--- a/apps/api/v1-openapi.json+++ b/apps/api/v1-openapi.json@@ -1331,7 +1331,7 @@"type": "array","items": {"type": "string",- "enum": ["markdown", "json"],+ "enum": ["markdown", "json", "branding"],"default": ["markdown"]}},@@ -1763,7 +1763,8 @@"links","screenshot","screenshot@fullPage",- "json"+ "json",+ "branding"]},"description": "Formats to include in the output",@@ -2100,7 +2101,8 @@"screenshot","screenshot@fullPage","json",- "changeTracking"+ "changeTracking",+ "branding"]},"description": "Formats to include in the output.",@@ -2552,6 +2554,67 @@"description": "JSON comparison results when using 'json' mode. Only present when the mode is set to 'json'. This will emit a list of all the keys and their values from the `previous` and `current` scrapes based on the type defined in the `schema`. Example [here](/features/change-tracking)"}}+ },+ "branding": {+ "type": "object",+ "nullable": true,+ "description": "Brand identity information derived from executing on-page javascript.",+ "properties": {+ "logo": {+ "type": "string",+ "nullable": true,+ "description": "Primary logo URL if detected."+ },+ "fonts": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "family": {+ "type": "string"+ }+ },+ "additionalProperties": true+ },+ "description": "Detected font families."+ },+ "colors": {+ "type": "object",+ "additionalProperties": true+ },+ "typography": {+ "type": "object",+ "additionalProperties": true+ },+ "spacing": {+ "type": "object",+ "additionalProperties": true+ },+ "components": {+ "type": "object",+ "additionalProperties": true+ },+ "icons": {+ "type": "object",+ "additionalProperties": true+ },+ "images": {+ "type": "object",+ "additionalProperties": true+ },+ "animations": {+ "type": "object",+ "additionalProperties": true+ },+ "layout": {+ "type": "object",+ "additionalProperties": true+ },+ "tone": {+ "type": "object",+ "additionalProperties": true+ }+ }}}}@@ -2684,7 +2747,9 @@"robotsBlocked": {"type": "array","description": "List of URLs that were attempted in scraping but were blocked by robots.txt",- "items": { "type": "string" }+ "items": {+ "type": "string"+ }}}},