From c51cfdf40ec76ae77af2edbbb3ae818f5321d1d6 Mon Sep 17 00:00:00 2001
From: AnandSundar <anandsundar96@gmail.com>
Date: Sat, 20 Jun 2026 22:20:24 -0600
Subject: [PATCH 1/5] feat(scraper): add typography types and extractTypography
 function

Implements U1 and U2 from the typography extraction plan:

- Add FontSource, FontAsset, HeadingStyle, BodyStyle, TypographyAsset types (src/types.ts)
- Make typography non-optional on BrandExtractionResult
- Re-export extractTypography and new types from src/index.ts
- Implement extractTypography($, html, baseUrl) in src/scraper.ts:

  * Collects CSS from inline <style> + allowlisted external stylesheets (Google Fonts, Typekit, same-origin) via parallel fetch with 5s timeout
  * Parses with brace-counting CSS extractor (strips /* */ comments, splits top-level blocks)
  * Builds FontAsset[] from @font-face rules, classifies source by URL (google-fonts/typekit/self-hosted/system), filters generic family names, dedupes case-insensitively with weights-merge
  * Extracts h1/h2/body styles from CSS rules + inline style override
---
 src/index.ts   |   8 +-
 src/scraper.ts | 379 ++++++++++++++++++++++++++++++++++++++++++++++++-
 src/types.ts   |  31 ++++
 3 files changed, 416 insertions(+), 2 deletions(-)

diff --git a/src/index.ts b/src/index.ts
index b47a8e4..bad4d19 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,7 +1,13 @@
-export { extractBrandAssets } from "./scraper";
+export { extractBrandAssets, extractTypography } from "./scraper";
 export type { ExtractionResult, ExtractionError } from "./scraper";
 export type {
   LogoAsset,
   ColorAsset,
   BackdropAsset,
+  FontAsset,
+  FontSource,
+  HeadingStyle,
+  BodyStyle,
+  TypographyAsset,
+  BrandExtractionResult,
 } from "./types";
diff --git a/src/scraper.ts b/src/scraper.ts
index bbaa4ba..de1fbd0 100644
--- a/src/scraper.ts
+++ b/src/scraper.ts
@@ -1,7 +1,16 @@
 import * as cheerio from "cheerio";
 import probe from "probe-image-size";
 import sharp from "sharp";
-import type { LogoAsset, ColorAsset, BackdropAsset } from "./types";
+import type {
+  LogoAsset,
+  ColorAsset,
+  BackdropAsset,
+  FontAsset,
+  FontSource,
+  TypographyAsset,
+  HeadingStyle,
+  BodyStyle,
+} from "./types";
 
 const USER_AGENT =
   "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";
@@ -649,3 +658,371 @@ function extractBrandName(
 
   return "";
 }
+
+// ── Typography extraction ────────────────────────────────────────────
+
+// Generic CSS family names (CSS Fonts Module Level 4). These appear in
+// font-family stacks as fallbacks; we filter them so we only surface
+// custom font families the site actually loaded.
+const GENERIC_FONT_FAMILIES = new Set([
+  "sans-serif",
+  "serif",
+  "monospace",
+  "system-ui",
+  "cursive",
+  "fantasy",
+  "ui-serif",
+  "ui-sans-serif",
+  "ui-monospace",
+  "ui-rounded",
+  "emoji",
+  "math",
+  "fangsong",
+  "inherit",
+  "initial",
+  "unset",
+  "revert",
+  "none",
+  "revert-layer",
+]);
+
+const GOOGLE_FONTS_HOSTS = ["fonts.googleapis.com", "fonts.gstatic.com"];
+const TYPEKIT_HOSTS = ["use.typekit.net"];
+
+export async function extractTypography(
+  $: cheerio.CheerioAPI,
+  html: string,
+  baseUrl: string
+): Promise<TypographyAsset> {
+  // 1. Collect CSS sources: inline <style> blocks + external stylesheet URLs.
+  const inlineCss: string[] = [];
+  $("style").each((_, el) => {
+    const text = $(el).text();
+    if (text) inlineCss.push(text);
+  });
+
+  const externalUrls: string[] = [];
+  $('link[rel="stylesheet"]').each((_, el) => {
+    const href = $(el).attr("href");
+    const resolved = resolveUrl(href, baseUrl);
+    if (!resolved) return;
+    if (isAllowlistedStylesheet(resolved, baseUrl)) {
+      externalUrls.push(resolved);
+    }
+  });
+
+  // 2. Fetch external CSS in parallel; tolerate individual failures.
+  const externalResults = await Promise.allSettled(
+    externalUrls.map((url) => fetchCss(url))
+  );
+  const fetchedCss: string[] = [];
+  for (const r of externalResults) {
+    if (r.status === "fulfilled" && r.value) {
+      fetchedCss.push(r.value);
+    }
+  }
+
+  // 3. Parse @font-face and selector rules across all CSS (inline + fetched).
+  const combinedCss = [...inlineCss, ...fetchedCss].join("\n");
+  const fontFaces = extractFontFaceRules(combinedCss);
+  const regularRules = extractRegularRules(combinedCss);
+
+  // 4. Build font assets and heading/body styles.
+  const fonts = buildFontAssets(fontFaces, baseUrl);
+  const h1Style = buildHeadingStyle("h1", regularRules, $);
+  const h2Style = buildHeadingStyle("h2", regularRules, $);
+  const bodyStyle = buildBodyStyle(regularRules, $);
+
+  const styles: TypographyAsset["styles"] = {};
+  if (h1Style) styles.h1 = h1Style;
+  if (h2Style) styles.h2 = h2Style;
+  if (bodyStyle) styles.body = bodyStyle;
+
+  return { fonts, styles };
+}
+
+function isAllowlistedStylesheet(url: string, baseUrl: string): boolean {
+  if (GOOGLE_FONTS_HOSTS.some((host) => url.includes(host))) return true;
+  if (TYPEKIT_HOSTS.some((host) => url.includes(host))) return true;
+  try {
+    return new URL(url).origin === new URL(baseUrl).origin;
+  } catch {
+    return false;
+  }
+}
+
+async function fetchCss(url: string): Promise<string | null> {
+  try {
+    const res = await fetch(url, {
+      headers: { "User-Agent": USER_AGENT },
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!res.ok) return null;
+    return res.text();
+  } catch {
+    return null;
+  }
+}
+
+interface FontFaceRule {
+  family: string;
+  srcUrl: string | null;
+  weight: number | null;
+  weightIsRange: boolean;
+}
+
+interface CssRule {
+  selector: string;
+  declarations: Map<string, string>;
+}
+
+function extractFontFaceRules(css: string): FontFaceRule[] {
+  const stripped = stripComments(css);
+  const topBlocks = splitTopLevelBlocks(stripped);
+  const rules: FontFaceRule[] = [];
+  for (const block of topBlocks) {
+    const openBrace = block.indexOf("{");
+    if (openBrace === -1) continue;
+    const selector = block.substring(0, openBrace).trim();
+    if (!/^@font-face\b/i.test(selector)) continue;
+    const body = block.substring(openBrace + 1, block.length - 1);
+    const declarations = parseDeclarations(body);
+    const family = declarations.get("font-family")?.replace(/['"]/g, "").trim();
+    if (!family) continue;
+    const srcDecl = declarations.get("src") || "";
+    const srcMatch = srcDecl.match(/url\(\s*["']?([^"')]+)["']?\s*\)/);
+    const srcUrl = srcMatch ? srcMatch[1] : null;
+    const weightDecl = declarations.get("font-weight")?.trim() || "";
+    let weight: number | null = null;
+    let weightIsRange = false;
+    if (/^\d+$/.test(weightDecl)) {
+      weight = parseInt(weightDecl, 10);
+    } else if (/^\d+\s+\d+$/.test(weightDecl)) {
+      weightIsRange = true;
+    }
+    rules.push({ family, srcUrl, weight, weightIsRange });
+  }
+  return rules;
+}
+
+function extractRegularRules(css: string): CssRule[] {
+  const stripped = stripComments(css);
+  const topBlocks = splitTopLevelBlocks(stripped);
+  const rules: CssRule[] = [];
+  for (const block of topBlocks) {
+    const openBrace = block.indexOf("{");
+    if (openBrace === -1) continue;
+    const selector = block.substring(0, openBrace).trim();
+    if (selector.startsWith("@")) continue; // skip @-rules
+    const body = block.substring(openBrace + 1, block.length - 1);
+    const declarations = parseDeclarations(body);
+    if (declarations.size > 0) {
+      rules.push({ selector, declarations });
+    }
+  }
+  return rules;
+}
+
+function splitTopLevelBlocks(css: string): string[] {
+  const blocks: string[] = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < css.length; i++) {
+    if (css[i] === "{") {
+      if (depth === 0) start = i;
+      depth++;
+    } else if (css[i] === "}") {
+      depth--;
+      if (depth === 0) {
+        blocks.push(css.substring(start, i + 1));
+      }
+    }
+  }
+  return blocks;
+}
+
+function stripComments(css: string): string {
+  return css.replace(/\/\*[\s\S]*?\*\//g, "");
+}
+
+function parseDeclarations(body: string): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const decl of splitOnTopLevel(body, ";")) {
+    const trimmed = decl.trim();
+    if (!trimmed) continue;
+    const colonIdx = trimmed.indexOf(":");
+    if (colonIdx === -1) continue;
+    const key = trimmed.substring(0, colonIdx).trim().toLowerCase();
+    const value = trimmed.substring(colonIdx + 1).trim();
+    if (key && value) map.set(key, value);
+  }
+  return map;
+}
+
+function splitOnTopLevel(s: string, sep: string): string[] {
+  const result: string[] = [];
+  let depth = 0;
+  let current = "";
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === "(") depth++;
+    else if (s[i] === ")") depth--;
+    if (s[i] === sep && depth === 0) {
+      result.push(current);
+      current = "";
+    } else {
+      current += s[i];
+    }
+  }
+  if (current) result.push(current);
+  return result;
+}
+
+function classifyFontSource(srcUrl: string | null): FontSource {
+  if (!srcUrl) return "system";
+  if (srcUrl.includes("fonts.gstatic.com") || srcUrl.includes("fonts.googleapis.com")) {
+    return "google-fonts";
+  }
+  if (srcUrl.includes("use.typekit.net")) {
+    return "typekit";
+  }
+  return "self-hosted";
+}
+
+function buildFontAssets(
+  fontFaces: FontFaceRule[],
+  baseUrl: string
+): FontAsset[] {
+  // Group by family (case-insensitive), filtering generic names.
+  const grouped = new Map<string, FontFaceRule[]>();
+  for (const ff of fontFaces) {
+    if (GENERIC_FONT_FAMILIES.has(ff.family.toLowerCase())) continue;
+    const key = ff.family.toLowerCase();
+    if (!grouped.has(key)) grouped.set(key, []);
+    grouped.get(key)!.push(ff);
+  }
+
+  const assets: FontAsset[] = [];
+  for (const rules of grouped.values()) {
+    const weights: number[] = [];
+    const srcUrls: string[] = [];
+    let hasRange = false;
+    for (const r of rules) {
+      if (r.weight !== null) weights.push(r.weight);
+      if (r.weightIsRange) hasRange = true;
+      if (r.srcUrl) {
+        const resolved = resolveUrl(r.srcUrl, baseUrl);
+        if (resolved) srcUrls.push(resolved);
+      }
+    }
+
+    const family = rules[0].family;
+    const source = classifyFontSource(rules[0].srcUrl);
+
+    const asset: FontAsset = { family, source };
+    if (!hasRange && weights.length > 0) {
+      asset.weights = [...new Set(weights)].sort((a, b) => a - b);
+    }
+    if (srcUrls.length === 1) {
+      asset.url = srcUrls[0];
+    }
+    assets.push(asset);
+  }
+  return assets;
+}
+
+function buildHeadingStyle(
+  tag: "h1" | "h2",
+  rules: CssRule[],
+  $: cheerio.CheerioAPI
+): HeadingStyle | undefined {
+  const style: HeadingStyle = {};
+  for (const rule of rules) {
+    if (!rule.selector.toLowerCase().includes(tag)) continue;
+    applyStyleFromDeclarations(rule.declarations, style);
+    if (style.fontFamily && style.fontSize && style.fontWeight !== undefined) break;
+  }
+  // Inline style attribute on the element takes precedence.
+  const inline = $(tag).first().attr("style") || "";
+  if (inline) {
+    applyInlineStyle(inline, style);
+  }
+  if (style.fontFamily || style.fontSize || style.fontWeight !== undefined) {
+    return style;
+  }
+  return undefined;
+}
+
+function buildBodyStyle(
+  rules: CssRule[],
+  $: cheerio.CheerioAPI
+): BodyStyle | undefined {
+  const style: BodyStyle = {};
+  for (const rule of rules) {
+    const sel = rule.selector.toLowerCase();
+    if (!sel.includes("body") && !sel.includes("html")) continue;
+    applyStyleFromDeclarations(rule.declarations, style);
+    if (style.fontFamily && style.fontSize && style.fontWeight !== undefined) break;
+  }
+  const inline = $("body").first().attr("style") || "";
+  if (inline) {
+    applyInlineStyle(inline, style);
+  }
+  if (style.fontFamily || style.fontSize || style.fontWeight !== undefined) {
+    return style;
+  }
+  return undefined;
+}
+
+function applyStyleFromDeclarations(
+  decls: Map<string, string>,
+  target: { fontFamily?: string; fontSize?: string; fontWeight?: number }
+): void {
+  if (!target.fontFamily) {
+    const ff = decls.get("font-family");
+    if (ff) {
+      const first = firstNonGenericFamily(ff);
+      if (first) target.fontFamily = first;
+    }
+  }
+  if (!target.fontSize) {
+    const fs = decls.get("font-size");
+    if (fs) target.fontSize = fs;
+  }
+  if (target.fontWeight === undefined) {
+    const fw = decls.get("font-weight");
+    if (fw && /^\d+$/.test(fw)) target.fontWeight = parseInt(fw, 10);
+  }
+}
+
+function applyInlineStyle(
+  inline: string,
+  target: { fontFamily?: string; fontSize?: string; fontWeight?: number }
+): void {
+  for (const decl of inline.split(";")) {
+    const trimmed = decl.trim();
+    if (!trimmed) continue;
+    const colonIdx = trimmed.indexOf(":");
+    if (colonIdx === -1) continue;
+    const key = trimmed.substring(0, colonIdx).trim().toLowerCase();
+    const value = trimmed.substring(colonIdx + 1).trim();
+    if (!value) continue;
+    if (key === "font-family") {
+      const first = firstNonGenericFamily(value);
+      if (first) target.fontFamily = first;
+    } else if (key === "font-size") {
+      target.fontSize = value;
+    } else if (key === "font-weight" && /^\d+$/.test(value)) {
+      target.fontWeight = parseInt(value, 10);
+    }
+  }
+}
+
+function firstNonGenericFamily(fontFamilyDecl: string): string | null {
+  for (const raw of splitOnTopLevel(fontFamilyDecl, ",")) {
+    const part = raw.trim().replace(/^['"]|['"]$/g, "");
+    if (!part) continue;
+    if (GENERIC_FONT_FAMILIES.has(part.toLowerCase())) continue;
+    return part;
+  }
+  return null;
+}
diff --git a/src/types.ts b/src/types.ts
index 0d0d64d..836f618 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -19,11 +19,42 @@ export interface BackdropAsset {
   description?: string;
 }
 
+export type FontSource = "google-fonts" | "typekit" | "self-hosted" | "system";
+
+export interface FontAsset {
+  family: string;
+  source: FontSource;
+  weights?: number[];
+  url?: string;
+}
+
+export interface HeadingStyle {
+  fontFamily?: string;
+  fontSize?: string;
+  fontWeight?: number;
+}
+
+export interface BodyStyle {
+  fontFamily?: string;
+  fontSize?: string;
+  fontWeight?: number;
+}
+
+export interface TypographyAsset {
+  fonts: FontAsset[];
+  styles: {
+    h1?: HeadingStyle;
+    h2?: HeadingStyle;
+    body?: BodyStyle;
+  };
+}
+
 export interface BrandExtractionResult {
   brandName: string;
   logos: LogoAsset[];
   colors: ColorAsset[];
   backdrops: BackdropAsset[];
+  typography: TypographyAsset;
 }
 
 export interface ExtractionResponse {

From da0b516a44dcef9a539a1e82641e7baebab7a21b Mon Sep 17 00:00:00 2001
From: AnandSundar <anandsundar96@gmail.com>
Date: Sat, 20 Jun 2026 22:21:23 -0600
Subject: [PATCH 2/5] feat(api): wire typography into parseHtml and extract
 route

Implements U3 from the typography extraction plan:

- Add extractTypography call to parseHtml; include typography in return type
- Add typography to the explicit result construction in the API route
- Normalize legacy cache entries (pre-typography) so cache hits always return the full shape with typography: { fonts: [], styles: {} } when the field is missing
---
 app/api/extract/route.ts | 7 +++++++
 src/scraper.ts           | 3 +++
 2 files changed, 10 insertions(+)

diff --git a/app/api/extract/route.ts b/app/api/extract/route.ts
index d454c36..156c748 100644
--- a/app/api/extract/route.ts
+++ b/app/api/extract/route.ts
@@ -61,6 +61,12 @@ export async function GET(request: NextRequest) {
       if (cached) {
         const result = cached.result as BrandExtractionResult;
 
+        // Normalize legacy cache entries (pre-typography) so the response shape
+        // is always complete even for results cached before this field existed.
+        if (!result.typography) {
+          result.typography = { fonts: [], styles: {} };
+        }
+
         console.log(JSON.stringify({ event: "extract_cache_hit", url, source, user_id: userId, brandName: result.brandName }));
 
         // Log the cache hit (fire-and-forget)
@@ -117,6 +123,7 @@ export async function GET(request: NextRequest) {
       logos: extracted.data.logos || [],
       colors: extracted.data.colors || [],
       backdrops: extracted.data.backdrop_images || [],
+      typography: extracted.data.typography || { fonts: [], styles: {} },
     };
 
     console.log(JSON.stringify({
diff --git a/src/scraper.ts b/src/scraper.ts
index de1fbd0..21a0b4e 100644
--- a/src/scraper.ts
+++ b/src/scraper.ts
@@ -155,6 +155,7 @@ async function parseHtml(
   colors: ColorAsset[];
   backdrop_images: BackdropAsset[];
   brand_name: string;
+  typography: TypographyAsset;
 }> {
   const $ = cheerio.load(html);
   const domainName = getDomainName(baseUrl);
@@ -162,12 +163,14 @@ async function parseHtml(
   const { logos, backdrops: imgBackdrops } = await extractImages($, baseUrl, domainName);
   const colors = await extractColors($, baseUrl, logos);
   const cssBackdrops = extractCssBackdrops($, html, baseUrl);
+  const typography = await extractTypography($, html, baseUrl);
 
   return {
     logos,
     colors,
     backdrop_images: [...cssBackdrops, ...imgBackdrops],
     brand_name: extractBrandName($, domainName),
+    typography,
   };
 }
 

From ec46ad22972ff9e3c9b67bb6a79813dc26670b2f Mon Sep 17 00:00:00 2001
From: AnandSundar <anandsundar96@gmail.com>
Date: Sat, 20 Jun 2026 22:23:14 -0600
Subject: [PATCH 3/5] feat(ui): add TypographyDisplay component and wire into
 brand results

Implements U4 from the typography extraction plan:

- Create components/typography-display.tsx with:

  * Font list with family, weights, url (if single), and color-coded source badge (Google Fonts / Typekit / Self-hosted / System)
  * Heading (h1, h2) and body samples rendered in the actual font with computed font-size/weight
  * Empty case: returns null when both fonts and styles are empty (preserves the existing rendering when a site has none)
- Wire TypographyDisplay into brand-results.tsx between ColorPalette and BackdropGallery
---
 components/brand-results.tsx      |   2 +
 components/typography-display.tsx | 129 ++++++++++++++++++++++++++++++
 2 files changed, 131 insertions(+)
 create mode 100644 components/typography-display.tsx

diff --git a/components/brand-results.tsx b/components/brand-results.tsx
index 7ace847..bcfc13a 100644
--- a/components/brand-results.tsx
+++ b/components/brand-results.tsx
@@ -5,6 +5,7 @@ import type { BrandExtractionResult } from "@/src/types";
 import { ColorPalette } from "./color-palette";
 import { LogoDisplay } from "./logo-display";
 import { BackdropGallery } from "./backdrop-gallery";
+import { TypographyDisplay } from "./typography-display";
 import { JsonView } from "./json-view";
 
 export function BrandResults({ data }: { data: BrandExtractionResult }) {
@@ -79,6 +80,7 @@ export function BrandResults({ data }: { data: BrandExtractionResult }) {
         <>
           <LogoDisplay logos={data.logos} />
           <ColorPalette colors={data.colors} />
+          <TypographyDisplay typography={data.typography} />
           <BackdropGallery backdrops={data.backdrops} />
         </>
       ) : (
diff --git a/components/typography-display.tsx b/components/typography-display.tsx
new file mode 100644
index 0000000..40bded5
--- /dev/null
+++ b/components/typography-display.tsx
@@ -0,0 +1,129 @@
+"use client";
+
+import type { TypographyAsset, FontAsset, HeadingStyle, BodyStyle } from "@/src/types";
+
+const SOURCE_LABELS: Record<FontAsset["source"], string> = {
+  "google-fonts": "Google Fonts",
+  typekit: "Typekit",
+  "self-hosted": "Self-hosted",
+  system: "System",
+};
+
+const SOURCE_STYLES: Record<FontAsset["source"], string> = {
+  "google-fonts": "bg-blue-50 text-blue-700 border-blue-200",
+  typekit: "bg-purple-50 text-purple-700 border-purple-200",
+  "self-hosted": "bg-emerald-50 text-emerald-700 border-emerald-200",
+  system: "bg-neutral-100 text-neutral-600 border-neutral-200",
+};
+
+function styleToString(style: { fontFamily?: string; fontSize?: string; fontWeight?: number }): string {
+  const parts: string[] = [];
+  if (style.fontSize) parts.push(`font-size: ${style.fontSize}`);
+  if (style.fontWeight !== undefined) parts.push(`font-weight: ${style.fontWeight}`);
+  if (style.fontFamily) parts.push(`font-family: ${style.fontFamily}`);
+  return parts.join("; ");
+}
+
+function FontRow({ font }: { font: FontAsset }) {
+  return (
+    <div className="flex items-baseline justify-between gap-3 py-2 border-b border-neutral-100 last:border-0">
+      <div className="min-w-0 flex-1">
+        <div className="font-mono text-sm text-neutral-900 truncate">{font.family}</div>
+        <div className="text-xs text-neutral-500 mt-0.5 flex flex-wrap gap-x-3 gap-y-0.5">
+          {font.weights && font.weights.length > 0 && (
+            <span>weights: {font.weights.join(", ")}</span>
+          )}
+          {font.url && (
+            <a
+              href={font.url}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="text-neutral-400 hover:text-neutral-600 underline truncate"
+            >
+              {font.url}
+            </a>
+          )}
+        </div>
+      </div>
+      <span
+        className={`text-[10px] font-medium px-2 py-0.5 rounded border uppercase tracking-wider shrink-0 ${SOURCE_STYLES[font.source]}`}
+      >
+        {SOURCE_LABELS[font.source]}
+      </span>
+    </div>
+  );
+}
+
+function StyleSample({
+  label,
+  style,
+  text,
+  sizeOverride,
+}: {
+  label: string;
+  style: HeadingStyle | BodyStyle;
+  text: string;
+  sizeOverride?: string;
+}) {
+  const cssStyle: React.CSSProperties = {};
+  if (style.fontFamily) cssStyle.fontFamily = style.fontFamily;
+  if (style.fontWeight !== undefined) cssStyle.fontWeight = style.fontWeight;
+  cssStyle.fontSize = sizeOverride ?? style.fontSize ?? "1rem";
+
+  return (
+    <div className="space-y-1.5">
+      <div className="text-[10px] font-medium text-neutral-500 uppercase tracking-wider">
+        {label}
+      </div>
+      <div style={cssStyle} className="text-neutral-900">
+        {text}
+      </div>
+      <code className="text-[10px] text-neutral-400 font-mono block truncate">
+        {styleToString(style)}
+      </code>
+    </div>
+  );
+}
+
+export function TypographyDisplay({ typography }: { typography: TypographyAsset }) {
+  const { fonts, styles } = typography;
+  const hasFonts = fonts.length > 0;
+  const hasStyles = !!(styles.h1 || styles.h2 || styles.body);
+
+  if (!hasFonts && !hasStyles) return null;
+
+  return (
+    <div>
+      <h3 className="text-sm font-medium text-neutral-500 uppercase tracking-wider mb-3">
+        Typography
+      </h3>
+
+      {hasFonts && (
+        <div className="mb-5">
+          <div className="text-xs font-medium text-neutral-700 mb-1.5">
+            Fonts ({fonts.length})
+          </div>
+          <div className="rounded-lg border border-neutral-200 bg-white px-3 py-1">
+            {fonts.map((font, i) => (
+              <FontRow key={`${font.family}-${i}`} font={font} />
+            ))}
+          </div>
+        </div>
+      )}
+
+      {hasStyles && (
+        <div className="space-y-4">
+          {styles.h1 && (
+            <StyleSample label="H1" style={styles.h1} text="The quick brown fox" sizeOverride="2rem" />
+          )}
+          {styles.h2 && (
+            <StyleSample label="H2" style={styles.h2} text="The quick brown fox" sizeOverride="1.5rem" />
+          )}
+          {styles.body && (
+            <StyleSample label="Body" style={styles.body} text="The quick brown fox jumps over the lazy dog." />
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

From e6b305ba642aea59692f2453ff0a776c16892a7c Mon Sep 17 00:00:00 2001
From: AnandSundar <anandsundar96@gmail.com>
Date: Sat, 20 Jun 2026 22:25:34 -0600
Subject: [PATCH 4/5] test(typography): add integration tests for
 extractTypography

Implements U5 from the typography extraction plan:

Create integration_test/typography-shape.test.ts with 15 tests covering:

  - Live-site shape validation against vercel.com (fonts, styles)
  - Generic CSS family names (sans-serif, serif, monospace, etc.) are filtered out
  - Case-insensitive family dedup merges Inter/inter with weight accumulation
  - URL-based source classification (google-fonts / typekit / self-hosted / system)
  - Heading and body style extraction from CSS rules + inline style override
  - @font-face rules inside CSS comments are ignored
- Fix splitTopLevelBlocks so each top-level block includes its selector (was previously only capturing { body }, missing @font-face / h1 / body)
---
 integration_test/typography-shape.test.ts | 259 ++++++++++++++++++++++
 src/scraper.ts                            |   6 +-
 2 files changed, 262 insertions(+), 3 deletions(-)
 create mode 100644 integration_test/typography-shape.test.ts

diff --git a/integration_test/typography-shape.test.ts b/integration_test/typography-shape.test.ts
new file mode 100644
index 0000000..7ff2be8
--- /dev/null
+++ b/integration_test/typography-shape.test.ts
@@ -0,0 +1,259 @@
+import { describe, test, expect } from "bun:test";
+import { extractBrandAssets, extractTypography } from "../src";
+import * as cheerio from "cheerio";
+
+const VALID_FONT_SOURCES = ["google-fonts", "typekit", "self-hosted", "system"];
+
+describe("extractTypography — shape validation on live sites", () => {
+  // Extract once and share across tests
+  let data: Awaited<ReturnType<typeof extractBrandAssets>> extends { ok: true; data: infer D } ? D : never;
+
+  test("extract from vercel.com for typography tests", async () => {
+    const result = await extractBrandAssets("https://vercel.com");
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("Extraction failed");
+    data = result.data;
+  }, 30000);
+
+  test("typography field exists and has the expected shape", () => {
+    expect(data.typography).toBeDefined();
+    expect(Array.isArray(data.typography.fonts)).toBe(true);
+    expect(typeof data.typography.styles).toBe("object");
+  });
+
+  test("FontAsset shape — family, source are valid, weights are numeric, url is valid", () => {
+    for (const font of data.typography.fonts) {
+      expect(typeof font.family).toBe("string");
+      expect(font.family.length).toBeGreaterThan(0);
+      expect(VALID_FONT_SOURCES).toContain(font.source);
+
+      if (font.weights !== undefined) {
+        expect(Array.isArray(font.weights)).toBe(true);
+        for (const w of font.weights) {
+          expect(typeof w).toBe("number");
+          expect(w).toBeGreaterThan(0);
+          expect(w).toBeLessThanOrEqual(1000);
+        }
+      }
+
+      if (font.url !== undefined) {
+        expect(typeof font.url).toBe("string");
+        expect(
+          font.url.startsWith("http://") ||
+          font.url.startsWith("https://") ||
+          font.url.startsWith("data:") ||
+          font.url.startsWith("/")
+        ).toBe(true);
+      }
+    }
+  });
+
+  test("HeadingStyle / BodyShape — fields are valid types when present", () => {
+    const { h1, h2, body } = data.typography.styles;
+
+    for (const style of [h1, h2, body]) {
+      if (!style) continue;
+      if (style.fontFamily !== undefined) {
+        expect(typeof style.fontFamily).toBe("string");
+        expect(style.fontFamily.length).toBeGreaterThan(0);
+      }
+      if (style.fontSize !== undefined) {
+        expect(typeof style.fontSize).toBe("string");
+        expect(style.fontSize.length).toBeGreaterThan(0);
+      }
+      if (style.fontWeight !== undefined) {
+        expect(typeof style.fontWeight).toBe("number");
+        expect(style.fontWeight).toBeGreaterThan(0);
+      }
+    }
+  });
+});
+
+describe("extractTypography — generic family names are filtered", () => {
+  test("does not include 'sans-serif', 'serif', 'monospace', etc. as custom fonts", async () => {
+    const html = `
+      <html><head>
+        <style>
+          @font-face { font-family: 'Inter'; src: url('/i.woff2'); font-weight: 400; }
+          @font-face { font-family: 'Roboto'; src: url('/r.woff2'); font-weight: 400; }
+        </style>
+      </head><body></body></html>
+    `;
+    const $ = cheerio.load(html);
+    const result = await extractTypography($, html, "https://example.com");
+    const families = result.fonts.map((f) => f.family.toLowerCase());
+    // Only Inter and Roboto should appear; sans-serif/serif should not
+    expect(families).toContain("inter");
+    expect(families).toContain("roboto");
+    expect(families).not.toContain("sans-serif");
+    expect(families).not.toContain("serif");
+    expect(families).not.toContain("monospace");
+  });
+});
+
+describe("extractTypography — case-insensitive family dedup", () => {
+  test("merges 'Inter' and 'inter' into a single entry, accumulating weights", async () => {
+    const html = `
+      <html><head>
+        <style>
+          @font-face { font-family: 'Inter'; src: url('/i-400.woff2'); font-weight: 400; }
+          @font-face { font-family: 'inter'; src: url('/i-700.woff2'); font-weight: 700; }
+        </style>
+      </head><body></body></html>
+    `;
+    const $ = cheerio.load(html);
+    const result = await extractTypography($, html, "https://example.com");
+    expect(result.fonts.length).toBe(1);
+    expect(result.fonts[0].weights).toEqual([400, 700]);
+  });
+});
+
+describe("extractTypography — Google Fonts URL classification", () => {
+  test("@font-face with fonts.gstatic.com src is classified as google-fonts", async () => {
+    const html = `
+      <html><head>
+        <style>
+          @font-face {
+            font-family: 'Roboto';
+            src: url(https://fonts.gstatic.com/s/roboto/v30/abc.woff2) format('woff2');
+            font-weight: 400;
+          }
+        </style>
+      </head><body></body></html>
+    `;
+    const $ = cheerio.load(html);
+    const result = await extractTypography($, html, "https://example.com");
+    expect(result.fonts.length).toBe(1);
+    expect(result.fonts[0].source).toBe("google-fonts");
+    expect(result.fonts[0].family).toBe("Roboto");
+  });
+
+  test("@font-face with use.typekit.net src is classified as typekit", async () => {
+    const html = `
+      <html><head>
+        <style>
+          @font-face {
+            font-family: 'Proxima Nova';
+            src: url(https://use.typekit.net/abc/1234.woff2) format('woff2');
+            font-weight: 400;
+          }
+        </style>
+      </head><body></body></html>
+    `;
+    const $ = cheerio.load(html);
+    const result = await extractTypography($, html, "https://example.com");
+    expect(result.fonts.length).toBe(1);
+    expect(result.fonts[0].source).toBe("typekit");
+  });
+
+  test("@font-face with arbitrary self-hosted URL is classified as self-hosted", async () => {
+    const html = `
+      <html><head>
+        <style>
+          @font-face {
+            font-family: 'MyFont';
+            src: url(/fonts/myfont.woff2) format('woff2');
+            font-weight: 400;
+          }
+        </style>
+      </head><body></body></html>
+    `;
+    const $ = cheerio.load(html);
+    const result = await extractTypography($, html, "https://example.com");
+    expect(result.fonts.length).toBe(1);
+    expect(result.fonts[0].source).toBe("self-hosted");
+  });
+
+  test("@font-face with no src url is classified as system", async () => {
+    const html = `
+      <html><head>
+        <style>
+          @font-face {
+            font-family: 'LocalFont';
+            src: local('LocalFont');
+            font-weight: 400;
+          }
+        </style>
+      </head><body></body></html>
+    `;
+    const $ = cheerio.load(html);
+    const result = await extractTypography($, html, "https://example.com");
+    expect(result.fonts.length).toBe(1);
+    expect(result.fonts[0].source).toBe("system");
+  });
+});
+
+describe("extractTypography — heading and body style extraction", () => {
+  test("extracts h1 font-family, font-size, font-weight from CSS rule", async () => {
+    const html = `
+      <html><head>
+        <style>
+          h1 { font-family: 'Inter', sans-serif; font-size: 48px; font-weight: 700; }
+        </style>
+      </head><body><h1>Title</h1></body></html>
+    `;
+    const $ = cheerio.load(html);
+    const result = await extractTypography($, html, "https://example.com");
+    expect(result.styles.h1).toBeDefined();
+    expect(result.styles.h1!.fontFamily).toBe("Inter");
+    expect(result.styles.h1!.fontSize).toBe("48px");
+    expect(result.styles.h1!.fontWeight).toBe(700);
+  });
+
+  test("extracts body font-family from a body rule", async () => {
+    const html = `
+      <html><head>
+        <style>
+          body { font-family: 'Lato', sans-serif; font-size: 16px; }
+        </style>
+      </head><body></body></html>
+    `;
+    const $ = cheerio.load(html);
+    const result = await extractTypography($, html, "https://example.com");
+    expect(result.styles.body).toBeDefined();
+    expect(result.styles.body!.fontFamily).toBe("Lato");
+    expect(result.styles.body!.fontSize).toBe("16px");
+  });
+
+  test("inline style attribute on h1 overrides the CSS rule", async () => {
+    const html = `
+      <html><head>
+        <style>
+          h1 { font-family: 'Inter', sans-serif; font-size: 48px; font-weight: 700; }
+        </style>
+      </head><body><h1 style="font-family: 'Overridden'; font-size: 24px; font-weight: 400;">Title</h1></body></html>
+    `;
+    const $ = cheerio.load(html);
+    const result = await extractTypography($, html, "https://example.com");
+    expect(result.styles.h1!.fontFamily).toBe("Overridden");
+    expect(result.styles.h1!.fontSize).toBe("24px");
+    expect(result.styles.h1!.fontWeight).toBe(400);
+  });
+
+  test("returns empty styles when no matching rules exist", async () => {
+    const html = `<html><head></head><body><h1>Title</h1></body></html>`;
+    const $ = cheerio.load(html);
+    const result = await extractTypography($, html, "https://example.com");
+    expect(result.styles.h1).toBeUndefined();
+    expect(result.styles.h2).toBeUndefined();
+    expect(result.styles.body).toBeUndefined();
+    expect(result.fonts).toEqual([]);
+  });
+});
+
+describe("extractTypography — comments and braces handled correctly", () => {
+  test("ignores @font-face rules inside CSS comments", async () => {
+    const html = `
+      <html><head>
+        <style>
+          /* @font-face { font-family: 'Commented'; src: url(/c.woff2); font-weight: 400; } */
+          @font-face { font-family: 'RealFont'; src: url(/r.woff2); font-weight: 400; }
+        </style>
+      </head><body></body></html>
+    `;
+    const $ = cheerio.load(html);
+    const result = await extractTypography($, html, "https://example.com");
+    expect(result.fonts.length).toBe(1);
+    expect(result.fonts[0].family).toBe("RealFont");
+  });
+});
diff --git a/src/scraper.ts b/src/scraper.ts
index 21a0b4e..41838d8 100644
--- a/src/scraper.ts
+++ b/src/scraper.ts
@@ -829,15 +829,15 @@ function extractRegularRules(css: string): CssRule[] {
 function splitTopLevelBlocks(css: string): string[] {
   const blocks: string[] = [];
   let depth = 0;
-  let start = 0;
+  let blockStart = 0; // Start of the current top-level construct (selector + body)
   for (let i = 0; i < css.length; i++) {
     if (css[i] === "{") {
-      if (depth === 0) start = i;
       depth++;
     } else if (css[i] === "}") {
       depth--;
       if (depth === 0) {
-        blocks.push(css.substring(start, i + 1));
+        blocks.push(css.substring(blockStart, i + 1));
+        blockStart = i + 1;
       }
     }
   }

From 7eaf5fc854aa88ad028a292e3174bdb1eb4ea823 Mon Sep 17 00:00:00 2001
From: AnandSundar <anandsundar96@gmail.com>
Date: Sat, 20 Jun 2026 22:27:16 -0600
Subject: [PATCH 5/5] docs(mcp+skill): add typography to tool description and
 skill docs

Implements U6 from the typography extraction plan:

- Update MCP tool description for extract_brand_assets to mention typography
- Update SKILL.md frontmatter description, npm example, asset-sources table, and response-format JSON sample to include typography
- Add CHANGELOG.md entry for 0.3.0 documenting the new typography field, scope of CSS sources, generic-name filter, weights-merge dedup, and 5-second fetch timeout
---
 CHANGELOG.md     | 17 +++++++++++++++++
 SKILL.md         | 15 +++++++++++++--
 mcp/src/index.ts |  2 +-
 3 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 62bd0ac..789dfa1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.3.0] - 2026-06-20
+
+### Added
+
+- **Typography extraction:** `extractTypography()` now extracts font families and heading/body styles from any website
+- `BrandExtractionResult.typography` field is now part of the standard response shape (non-optional; defaults to `{ fonts: [], styles: {} }` for legacy cache entries)
+- Each font asset includes `family`, `source` (`google-fonts` | `typekit` | `self-hosted` | `system`), optional `weights`, and optional `url` (omitted when multiple URLs are present)
+- New `TypographyDisplay` component in the web UI renders fonts and live heading/body samples
+- New `mcp` tool description mentions typography as part of the brand asset extraction surface
+
+### Scope
+
+- CSS sources: inline `<style>` blocks, Google Fonts (`fonts.googleapis.com` / `fonts.gstatic.com`), Typekit (`use.typekit.net`), and same-origin stylesheets
+- Generic CSS family names (sans-serif, serif, monospace, system-ui, etc.) are filtered
+- Fonts are deduplicated case-insensitively with weights merged across `@font-face` rules
+- External CSS fetches are bounded by a 5-second timeout via `Promise.allSettled` (failures are silently tolerated)
+
 ## [0.2.0] - 2026-03-14
 
 ### Changed
diff --git a/SKILL.md b/SKILL.md
index 3b3a89f..5851e70 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: openbrand
-description: Extract brand assets (logos, colors, backdrop images, brand name) from any website URL. Use when building branded interfaces, generating style guides, or needing brand identity data from a URL.
+description: Extract brand assets (logos, colors, backdrop images, brand name, typography) from any website URL. Use when building branded interfaces, generating style guides, or needing brand identity data from a URL.
 ---
 
 # OpenBrand
@@ -36,6 +36,7 @@ if (result.ok) {
   // result.data.logos → LogoAsset[]
   // result.data.colors → ColorAsset[]
   // result.data.backdrop_images → BackdropAsset[]
+  // result.data.typography → TypographyAsset
 }
 ```
 
@@ -54,6 +55,7 @@ curl "https://openbrand.sh/api/extract?url=https://stripe.com" \
 | **Brand colors** | theme-color meta tags, manifest.json, dominant colors from logo imagery |
 | **Backdrop images** | og:image, CSS backgrounds, hero/banner images |
 | **Brand name** | og:site_name, application-name, logo alt text, page title |
+| **Typography** | Inline `<style>` blocks, Google Fonts, Typekit, same-origin stylesheets (font families with source classification + h1/h2/body styles) |
 
 ## Response format
 
@@ -69,7 +71,16 @@ curl "https://openbrand.sh/api/extract?url=https://stripe.com" \
   ],
   "backdrops": [
     { "url": "https://...", "description": "Hero image" }
-  ]
+  ],
+  "typography": {
+    "fonts": [
+      { "family": "Inter", "source": "self-hosted", "weights": [400, 700], "url": "https://..." }
+    ],
+    "styles": {
+      "h1": { "fontFamily": "Inter", "fontSize": "48px", "fontWeight": 700 },
+      "body": { "fontFamily": "Inter", "fontSize": "16px", "fontWeight": 400 }
+    }
+  }
 }
 ```
 
diff --git a/mcp/src/index.ts b/mcp/src/index.ts
index 33d32c0..34a91fd 100644
--- a/mcp/src/index.ts
+++ b/mcp/src/index.ts
@@ -15,7 +15,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     {
       name: "extract_brand_assets",
       description:
-        "Extract brand assets (logos, colors, backdrop images, brand name) from a website URL. Returns structured data with logo URLs, hex colors with usage hints, backdrop/OG images, and the detected brand name.",
+        "Extract brand assets (logos, colors, backdrop images, brand name, typography) from a website URL. Returns structured data with logo URLs, hex colors with usage hints, backdrop/OG images, the detected brand name, and typography (font families with sources + heading/body styles).",
       inputSchema: {
         type: "object" as const,
         properties: {