dembrandt 0.12.8 → 0.12.10

package/README.md

@@ -67,9 +67,9 @@ dembrandt example.com --mobile         # Use mobile viewport (390x844) for respo
 dembrandt example.com --slow           # 3x longer timeouts (24s hydration) for JavaScript-heavy sites
 dembrandt example.com --brand-guide    # Generate a brand guide PDF
 dembrandt example.com --design-md      # Generate a DESIGN.md file for AI agents
-dembrandt example.com --pages 5        # Analyze 5 pages (homepage + 4 discovered pages), merges results
+dembrandt example.com --crawl 5        # Analyze 5 pages (homepage + 4 discovered pages), merges results
 dembrandt example.com --sitemap        # Discover pages from sitemap.xml instead of DOM links
-dembrandt example.com --pages 10 --sitemap # Combine: up to 10 pages discovered via sitemap
+dembrandt example.com --crawl 10 --sitemap # Combine: up to 10 pages discovered via sitemap
 dembrandt example.com --no-sandbox     # Disable Chromium sandbox (required for Docker/CI)
 dembrandt example.com --browser=firefox # Use Firefox instead of Chromium (better for Cloudflare bypass)
 dembrandt example.com --wcag           # WCAG 2.1 contrast analysis — real DOM pairs, AA/AAA grades
@@ -83,13 +83,13 @@ Analyze multiple pages to get a more complete picture of a site's design system.
 
 ```bash
 # Analyze homepage + 4 auto-discovered pages (default: 5 total)
-dembrandt example.com --pages 5
+dembrandt example.com --crawl 5
 
 # Use sitemap.xml for page discovery instead of DOM link scraping
 dembrandt example.com --sitemap
 
 # Combine both: up to 10 pages from sitemap
-dembrandt example.com --pages 10 --sitemap
+dembrandt example.com --crawl 10 --sitemap
 ```
 
 **Page discovery** works two ways:
@@ -197,7 +197,7 @@ dembrandt braintree.com --save-output
 
 **Multi-page audit** — get a fuller picture across the whole site
 ```bash
-dembrandt stripe.com --pages 10 --sitemap --save-output
+dembrandt stripe.com --crawl 10 --sitemap --save-output
 ```
 
 **Spot-check a value** — verify a specific token fast

package/index.js

@@ -32,6 +32,7 @@ program
   .description("Extract design tokens from any website")
   .version(version)
   .argument("<url>")
+  .argument("[paths...]", "Additional paths to extract and merge, e.g. /pricing /docs")
   .option("--browser <type>", "Browser to use (chromium|firefox); set BROWSER_CDP_ENDPOINT env var to connect to an existing Chromium instance via CDP", "chromium")
   .option("--json-only", "Output raw JSON")
   .option("--save-output", "Save JSON file to output folder")
@@ -45,13 +46,19 @@ program
   .option("--raw-colors", "Include pre-filter raw colors in JSON output")
   .option("--screenshot <path>", "Save a screenshot of the page")
   .option("--wcag", "Analyze WCAG contrast ratios between palette colors")
-  .option("--pages <n>", "Analyze up to N total pages including start URL (default: 5)", (v) => {
+  .option("--crawl [n]", "Auto-discover and extract up to N pages via DOM links (default: 5)", (v) => {
+    if (v === undefined || v === true) return 5;
+    const n = parseInt(v, 10);
+    if (isNaN(n) || n < 1) throw new Error(`--crawl must be a positive integer, got: ${v}`);
+    return n;
+  })
+  .option("--pages <n>", "Alias for --crawl (deprecated)", (v) => {
     const n = parseInt(v, 10);
     if (isNaN(n) || n < 1) throw new Error(`--pages must be a positive integer, got: ${v}`);
     return n;
   })
   .option("--sitemap", "Discover pages from sitemap.xml instead of DOM links")
-  .action(async (input, opts) => {
+  .action(async (input, paths, opts) => {
     let url = input;
     if (!url.startsWith("http://") && !url.startsWith("https://")) {
       url = "https://" + url;
@@ -113,70 +120,80 @@ program
         }
 
         try {
-          const isMultiPage = opts.pages || opts.sitemap;
-          const maxPages = (opts.pages || 5) - 1; // -1 because homepage counts
+          const crawlN = opts.crawl ?? opts.pages ?? null;
+          const isAutoCrawl = crawlN && !opts.sitemap && (!paths || paths.length === 0);
+          const hasExplicitPaths = paths && paths.length > 0;
+
           result = await extractBranding(url, spinner, browser, {
             navigationTimeout: 90000,
             darkMode: opts.darkMode,
             mobile: opts.mobile,
             slow: opts.slow,
             screenshotPath: opts.screenshot,
-            discoverLinks: isMultiPage && !opts.sitemap ? maxPages : null,
+            discoverLinks: isAutoCrawl ? crawlN - 1 : null,
             wcag: opts.wcag,
+            includeRawColors: opts.rawColors,
           });
 
-          // Multi-page crawl
-          if (isMultiPage && maxPages > 0) {
-            if (!opts.jsonOnly) spinner.start("Discovering pages...");
-
-            let additionalUrls;
-            if (opts.sitemap) {
-              // Try post-redirect URL first, fall back to user-provided URL
-              // (some sites redirect to a subdomain while the sitemap stays on www)
-              additionalUrls = await parseSitemap(result.url, maxPages);
-              if (additionalUrls.length === 0 && result.url !== url) {
-                additionalUrls = await parseSitemap(url, maxPages);
-              }
-            } else {
-              additionalUrls = result._discoveredLinks || [];
+          // Build list of additional URLs to extract
+          let additionalUrls = [];
+
+          if (hasExplicitPaths) {
+            // Explicit paths: resolve against base URL
+            const base = new URL(result.url);
+            additionalUrls = paths.map(p => {
+              if (p.startsWith('http')) return p;
+              return `${base.protocol}//${base.host}${p.startsWith('/') ? p : '/' + p}`;
+            });
+          } else if (opts.sitemap) {
+            if (!opts.jsonOnly) spinner.start("Fetching sitemap...");
+            const max = crawlN ? crawlN - 1 : 20;
+            additionalUrls = await parseSitemap(result.url, max);
+            if (additionalUrls.length === 0 && result.url !== url) {
+              additionalUrls = await parseSitemap(url, max);
             }
+          } else if (isAutoCrawl) {
+            additionalUrls = result._discoveredLinks || [];
+          }
 
-            delete result._discoveredLinks;
-
-            if (additionalUrls.length === 0) {
-              if (!opts.jsonOnly) spinner.warn("No additional pages discovered");
-            } else {
-              spinner.stop();
-              if (!opts.jsonOnly) console.log(chalk.dim(`  Found ${additionalUrls.length} page(s) to analyze`));
-
-              const allResults = [result];
-              for (let i = 0; i < additionalUrls.length; i++) {
-                const pageUrl = additionalUrls[i];
-                const pageNum = i + 2;
-                const total = additionalUrls.length + 1;
-                if (!opts.jsonOnly) spinner.start(`Extracting page ${pageNum}/${total}: ${new URL(pageUrl).pathname}`);
-
-                // Polite delay between pages
-                await new Promise(r => setTimeout(r, 2000 + Math.random() * 3000));
-
-                try {
-                  const pageResult = await extractBranding(pageUrl, spinner, browser, {
-                    navigationTimeout: 90000,
-                    darkMode: opts.darkMode,
-                    mobile: opts.mobile,
-                    slow: opts.slow,
-                  });
-                  delete pageResult._discoveredLinks;
-                  allResults.push(pageResult);
-                } catch (err) {
-                  if (!opts.jsonOnly) spinner.warn(`Skipping ${pageUrl}: ${String(err?.message || err).slice(0, 80)}`);
-                }
-              }
+          delete result._discoveredLinks;
 
-              spinner.stop();
-              result = mergeResults(allResults);
+          if (additionalUrls.length === 0) {
+            if ((hasExplicitPaths || opts.sitemap || isAutoCrawl) && !opts.jsonOnly) {
+              spinner.warn("No additional pages discovered");
             }
           } else {
+            spinner.stop();
+            if (!opts.jsonOnly) console.log(chalk.dim(`  Found ${additionalUrls.length} page(s) to analyze`));
+
+            const allResults = [result];
+            for (let i = 0; i < additionalUrls.length; i++) {
+              const pageUrl = additionalUrls[i];
+              const pageNum = i + 2;
+              const total = additionalUrls.length + 1;
+              if (!opts.jsonOnly) spinner.start(`Extracting page ${pageNum}/${total}: ${new URL(pageUrl).pathname}`);
+
+              await new Promise(r => setTimeout(r, 1500 + Math.random() * 1500));
+
+              try {
+                const pageResult = await extractBranding(pageUrl, spinner, browser, {
+                  navigationTimeout: 90000,
+                  darkMode: opts.darkMode,
+                  mobile: opts.mobile,
+                  slow: opts.slow,
+                });
+                delete pageResult._discoveredLinks;
+                allResults.push(pageResult);
+              } catch (err) {
+                if (!opts.jsonOnly) spinner.warn(`Skipping ${pageUrl}: ${String(err?.message || err).slice(0, 80)}`);
+              }
+            }
+
+            spinner.stop();
+            result = mergeResults(allResults);
+          }
+
+          if (!hasExplicitPaths && !opts.sitemap && !isAutoCrawl) {
             delete result._discoveredLinks;
           }
 

package/lib/extractors/colors.js

@@ -45,6 +45,12 @@ export async function extractColors(page) {
       return result;
     }
 
+    function colorAlpha(color) {
+      if (!color) return 1;
+      const m = color.match(/rgba?\(\d+,\s*\d+,\s*\d+,\s*([\d.]+)\)/);
+      return m ? parseFloat(m[1]) : 1;
+    }
+
     function isValidColorValue(value) {
       if (!value) return false;
       if (value.includes("calc(") || value.includes("clamp(") || value.includes("var(")) {
@@ -105,6 +111,7 @@ export async function extractColors(page) {
 
     const elements = document.querySelectorAll("*");
     const totalElements = elements.length;
+    const ctaPrimaryMap = new Map(); // normalized hex → original color for CTA backgrounds
 
     const contextScores = {
       logo: 5, brand: 5, primary: 4, cta: 4, hero: 3, button: 3, link: 2, header: 2, nav: 1,
@@ -133,12 +140,20 @@ export async function extractColors(page) {
         if (context.includes(keyword)) score = Math.max(score, weight);
       }
 
-      if (
-        (context.includes('button') || context.includes('btn') || context.includes('cta')) &&
+      const isCta = (context.includes('button') || context.includes('btn') || context.includes('cta')) &&
         bgColor && bgColor !== 'rgba(0, 0, 0, 0)' && bgColor !== 'transparent' &&
-        bgColor !== 'rgb(255, 255, 255)' && bgColor !== 'rgb(0, 0, 0)' && bgColor !== 'rgb(239, 239, 239)'
-      ) {
+        bgColor !== 'rgb(255, 255, 255)' && bgColor !== 'rgb(0, 0, 0)' && bgColor !== 'rgb(239, 239, 239)' &&
+        colorAlpha(bgColor) >= 0.7;
+
+      if (isCta) {
         score = Math.max(score, 25);
+        // CTA background is a strong primary signal — count occurrences
+        const ctaNorm = normalizeColor(bgColor);
+        if (ctaNorm) {
+          const existing = ctaPrimaryMap.get(ctaNorm) || { original: bgColor, count: 0 };
+          existing.count++;
+          ctaPrimaryMap.set(ctaNorm, existing);
+        }
       }
 
       function extractColorsFromValue(colorValue) {
@@ -159,7 +174,7 @@ export async function extractColors(page) {
       ];
 
       allColors.forEach((color) => {
-        if (color && color !== "rgba(0, 0, 0, 0)" && color !== "transparent") {
+        if (color && color !== "rgba(0, 0, 0, 0)" && color !== "transparent" && colorAlpha(color) >= 0.3) {
           const normalized = normalizeColor(color);
           const existing = colorMap.get(normalized) || { original: color, count: 0, bgCount: 0, score: 0, sources: new Set() };
           existing.count++;
@@ -174,11 +189,26 @@ export async function extractColors(page) {
       });
 
       if (context.includes("primary") || el.matches('[class*="primary"]')) {
-        semanticColors.primary = bgColor !== "rgba(0, 0, 0, 0)" && bgColor !== "transparent" ? bgColor : textColor;
+        const candidate = bgColor !== "rgba(0, 0, 0, 0)" && bgColor !== "transparent" ? bgColor : textColor;
+        if (colorAlpha(candidate) >= 0.7) semanticColors.primary = candidate;
       }
       if (context.includes("secondary")) semanticColors.secondary = bgColor;
     });
 
+    // Use most-common CTA background as primary if class-based detection missed it
+    // Require at least 2 CTA occurrences to avoid single "Sign up" buttons dominating
+    if (!semanticColors.primary && ctaPrimaryMap.size > 0) {
+      let bestScore = -1;
+      for (const [norm, entry] of ctaPrimaryMap) {
+        if (entry.count < 2) continue;
+        const data = colorMap.get(norm);
+        if (data && data.score > bestScore) {
+          bestScore = data.score;
+          semanticColors.primary = entry.original;
+        }
+      }
+    }
+
     const threshold = Math.max(3, Math.floor(totalElements * 0.01));
 
     function isStructuralColor(data, totalElements) {
@@ -295,6 +325,27 @@ export async function extractColors(page) {
       if (converted) return { ...colorItem, lch: converted.lch, oklch: converted.oklch };
       return colorItem;
     });
+
+    // Cluster alpha/lightness variants of the same hue under one token
+    // e.g. rgba(99,91,255,0.1) is a variant of #635bff, not a separate brand color
+    const primaryHex = result.semantic?.primary
+      ? hexToRgb(toOpaque(result.semantic.primary)) : null;
+
+    result.palette = result.palette.map((colorItem) => {
+      const hex = colorItem.normalized || colorItem.color;
+      const role = colorRole(hex, colorItem);
+      const onColor = bestOnColor(hex);
+      const hover = hoverVariant(hex);
+      // Mark alpha/lightness variants of primary
+      let variantOf = null;
+      if (primaryHex && role !== 'surface') {
+        const rgb = hexToRgb(hex);
+        if (rgb && isSameHueFamily(rgb, primaryHex)) {
+          variantOf = 'primary';
+        }
+      }
+      return { ...colorItem, role, onColor, hover, ...(variantOf ? { variantOf } : {}) };
+    });
   }
 
   if (result && result.cssVariables) {
@@ -313,6 +364,96 @@ export async function extractColors(page) {
   return result;
 }
 
+function hexToRgb(hex) {
+  const m = /^#([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+  if (!m) return null;
+  return { r: parseInt(m[1], 16), g: parseInt(m[2], 16), b: parseInt(m[3], 16) };
+}
+
+function relativeLuminance({ r, g, b }) {
+  const lin = c => { c /= 255; return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4); };
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+function contrastRatio(hex1, hex2) {
+  const rgb1 = hexToRgb(hex1);
+  const rgb2 = hexToRgb(hex2);
+  if (!rgb1 || !rgb2) return 1;
+  const l1 = relativeLuminance(rgb1);
+  const l2 = relativeLuminance(rgb2);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+function bestOnColor(hex) {
+  const onWhite = contrastRatio(hex, '#ffffff');
+  const onBlack = contrastRatio(hex, '#000000');
+  return onWhite >= onBlack ? '#ffffff' : '#000000';
+}
+
+function colorRole(hex, colorItem) {
+  const rgb = hexToRgb(hex);
+  if (!rgb) return 'unknown';
+  const lum = relativeLuminance(rgb);
+  // Surface: near-pure white or black only
+  if (lum > 0.9 || lum < 0.005) return 'surface';
+  // Neutral: low HSL saturation (grays, off-whites, taupes)
+  const max = Math.max(rgb.r, rgb.g, rgb.b) / 255;
+  const min = Math.min(rgb.r, rgb.g, rgb.b) / 255;
+  const saturation = max === 0 ? 0 : (max - min) / max;
+  if (saturation < 0.12) return 'neutral';
+  // Accent: anything chromatic with meaningful confidence
+  if (colorItem.confidence === 'high' || colorItem.confidence === 'medium') return 'accent';
+  return 'supporting';
+}
+
+function hoverVariant(hex) {
+  const rgb = hexToRgb(hex);
+  if (!rgb) return null;
+  const lum = relativeLuminance(rgb);
+  // Lighten dark colors, darken light ones — always move toward better contrast
+  const factor = lum < 0.18 ? 1.2 : 0.85;
+  const clamp = v => Math.min(255, Math.max(0, Math.round(v)));
+  const r = clamp(rgb.r * factor);
+  const g = clamp(rgb.g * factor);
+  const b = clamp(rgb.b * factor);
+  return `#${r.toString(16).padStart(2,'0')}${g.toString(16).padStart(2,'0')}${b.toString(16).padStart(2,'0')}`;
+}
+
+function toOpaque(color) {
+  if (!color) return null;
+  if (color.startsWith('#')) return color;
+  const m = color.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/i);
+  if (!m) return null;
+  return `#${(+m[1]).toString(16).padStart(2,'0')}${(+m[2]).toString(16).padStart(2,'0')}${(+m[3]).toString(16).padStart(2,'0')}`;
+}
+
+function isSameHueFamily(rgb, primaryRgb, threshold = 30) {
+  // Compare hue in HSL space — same hue ±threshold degrees = variant
+  function toHsl({ r, g, b }) {
+    r /= 255; g /= 255; b /= 255;
+    const max = Math.max(r, g, b), min = Math.min(r, g, b);
+    const l = (max + min) / 2;
+    if (max === min) return { h: 0, s: 0, l };
+    const d = max - min;
+    const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    let h;
+    switch (max) {
+      case r: h = ((g - b) / d + (g < b ? 6 : 0)) / 6; break;
+      case g: h = ((b - r) / d + 2) / 6; break;
+      default: h = ((r - g) / d + 4) / 6;
+    }
+    return { h: h * 360, s, l };
+  }
+  const h1 = toHsl(rgb);
+  const h2 = toHsl(primaryRgb);
+  // Low saturation colors are not hue-family variants
+  if (h1.s < 0.1 || h2.s < 0.1) return false;
+  const diff = Math.abs(h1.h - h2.h);
+  return Math.min(diff, 360 - diff) < threshold;
+}
+
 export async function extractWcagPairs(page) {
   let rawPairs = [];
   try {

package/lib/extractors/index.js

@@ -168,7 +168,7 @@ export async function extractBranding(url, spinner, browser, options = {}) {
     spinner.stop();
     console.log(color.info("\n  Extracting design tokens...\n"));
 
-    spinner.start("Analyzing design system (16 parallel tasks)...");
+    spinner.start("Analyzing design system (17 parallel tasks)...");
     const [
       { logo, instances: logoInstances, favicons },
       colors,

package/lib/extractors/logo.js

@@ -161,7 +161,7 @@ export async function extractLogo(page, url) {
 
       if (rect.top < 200) score += 10;
       if (rect.left < 400) score += 10;
-      if (rect.top > 800) score -= 30;   // deeply buried elements are unlikely primary logos
+      if (rect.top > 500) score -= 50;   // anything below fold is not a primary logo
 
       // Penalize images hosted on a different domain (CDN paths on same domain are fine)
       if (el.tagName === 'IMG') {
@@ -178,8 +178,9 @@ export async function extractLogo(page, url) {
       const width = el.tagName === 'IMG' ? (el.naturalWidth || rect.width) : rect.width;
       const height = el.tagName === 'IMG' ? (el.naturalHeight || rect.height) : rect.height;
       if (width < 20 || height < 20) score -= 30;
-      if (width > 600 || height > 400) score -= 40;
-      if (altText.length > 50) score -= 30;
+      if (width > 800 || height > 500) score -= 80;   // large editorial/hero images are never logos
+      else if (width > 600 || height > 400) score -= 40;
+      if (altText.length > 50) score -= 40;           // long alt text = content image, not logo
       if (width > height && width < 400 && width > 40 && height > 10 && height < 120) score += 15;
 
       return score;
@@ -360,7 +361,24 @@ export async function extractLogo(page, url) {
       return candidates;
     }
 
-    const headerEl = document.querySelector('header, [role="banner"], [class*="header"], [id*="header"]');
+    // SPA/PWA apps often render into a root div — treat it as transparent wrapper
+    const spaRoot = document.querySelector('#app, #root, #__next, #__nuxt, [data-reactroot]');
+
+    const headerEl = document.querySelector(
+      'header, [role="banner"], [class*="header"], [id*="header"]'
+    ) || (() => {
+      // Fallback: find first visually top element in SPA root or body that spans full width
+      const root = spaRoot || document.body;
+      const children = Array.from(root.children);
+      for (const child of children) {
+        const rect = child.getBoundingClientRect();
+        const s = getComputedStyle(child);
+        if (rect.top < 100 && rect.width > window.innerWidth * 0.5 && s.display !== 'none') {
+          return child;
+        }
+      }
+      return null;
+    })();
     const navEl = document.querySelector('nav, [role="navigation"]');
     const footerEl = document.querySelector('footer, [role="contentinfo"], [class*="footer"], [id*="footer"]');
 
@@ -374,15 +392,109 @@ export async function extractLogo(page, url) {
       return null;
     })();
 
+    // Sidebar: fixed/sticky left-edge containers and semantic sidebar elements
+    // Logo is typically in the first 1-3 children of a sidebar
+    const sidebarEl = (() => {
+      // Semantic sidebar selectors
+      const candidates = document.querySelectorAll(
+        'aside, [role="complementary"], [class*="sidebar"], [class*="side-nav"], [class*="sidenav"], [class*="side-bar"], [id*="sidebar"]'
+      );
+      for (const el of candidates) {
+        const rect = el.getBoundingClientRect();
+        if (rect.width > 0 && rect.height > 100) return el;
+      }
+      // Fallback: fixed/sticky element pinned to left edge
+      const all = document.querySelectorAll('*');
+      for (const el of all) {
+        try {
+          const s = getComputedStyle(el);
+          if ((s.position === 'fixed' || s.position === 'sticky') && s.display !== 'none') {
+            const rect = el.getBoundingClientRect();
+            if (rect.left < 100 && rect.height > 200 && rect.width < 400) return el;
+          }
+        } catch {}
+      }
+      return null;
+    })();
+
+    // For header: scan first 3 children and their direct children only
+    function firstChildrenZone(container, context) {
+      if (!container) return [];
+      const candidates = [];
+      const children = Array.from(container.children).slice(0, 3);
+      for (const child of children) {
+        const shallow = document.createElement('div');
+        // Scan the child itself + its direct children
+        const els = [child, ...Array.from(child.children)];
+        for (const el of els) {
+          if (el.matches('img, svg')) {
+            const found = findLogosInZone(el.parentElement || container, context);
+            candidates.push(...found.filter(c => c.el === el || c.cssBackground));
+          }
+        }
+        // Also run full zone scan on the first child subtree (logo is often nested 1-2 levels)
+        candidates.push(...findLogosInZone(child, context));
+      }
+      return candidates;
+    }
+
+    // For sidebar: scan first 3 children and their direct children
+    function sidebarZone(container) {
+      if (!container) return [];
+      const children = Array.from(container.children).slice(0, 3);
+      const candidates = [];
+      for (const child of children) {
+        candidates.push(...findLogosInZone(child, 'header'));
+      }
+      return candidates;
+    }
+
+    // Global pre-scan: strong semantic signals that identify a logo anywhere in the document
+    const globalLogoCandidates = (() => {
+      const results = [];
+      const selectors = [
+        'img[class*="logo"]',
+        'img[id*="logo"]',
+        'a[class*="logo"] img',
+        'a[id*="logo"] img',
+        '[class*="logo-link"] img',
+        '[class*="logo-wrap"] img',
+        '[class*="logo-container"] img',
+        'a[href="/"] img',
+        'a[href="./"] img',
+      ];
+      const seen = new Set();
+      for (const sel of selectors) {
+        try {
+          document.querySelectorAll(sel).forEach(el => {
+            if (seen.has(el)) return;
+            seen.add(el);
+            const rect = el.getBoundingClientRect();
+            if (rect.width === 0 || rect.height === 0) return;
+            if (rect.top > 500) return; // must be near top
+            if (rect.width > 600 || rect.height > 200) return; // too large
+            const score = scoreLogo(el, 'header') + 20; // bonus for semantic match
+            results.push({ el, score, context: 'header' });
+          });
+        } catch {}
+      }
+      return results;
+    })();
+
     // Deduplicate zones — nav might be inside header, avoid double-scanning
-    const headerCandidates = findLogosInZone(headerEl, 'header');
+    const headerCandidates = firstChildrenZone(headerEl, 'header');
     const navCandidates = (navEl && !headerEl?.contains(navEl))
-      ? findLogosInZone(navEl, 'header')  // same score weight as header
+      ? firstChildrenZone(navEl, 'header')
+      : [];
+    const sidebarCandidates = (sidebarEl && !headerEl?.contains(sidebarEl))
+      ? sidebarZone(sidebarEl)
       : [];
 
     const allCandidates = [
+      ...globalLogoCandidates,
       ...headerCandidates,
       ...navCandidates,
+      ...sidebarCandidates,
       ...findLogosInZone(footerEl, 'footer'),
       ...findLogosInZone(heroEl, 'hero'),
     ];

package/lib/extractors/typography.js

@@ -80,15 +80,20 @@ export async function extractTypography(page) {
         el.getAttribute("role") === "button" ||
         className.includes("btn")
       ) {
-        context = "button";
+        context = "ui";
       } else if (el.tagName === "A" && el.href) {
         context = "link";
       } else if (headingMatch) {
-        context = `heading-${headingMatch[1]}`;
-      } else if (size <= 14) {
+        const level = parseInt(headingMatch[1]);
+        // h1 at very large size = display, otherwise heading
+        context = (level === 1 && size >= 56) ? "display" : `heading-${level}`;
+      } else if (size >= 56) {
+        context = "display";  // non-heading super-sized text (hero, marketing)
+      } else if (size <= 12) {
         context = "caption";
-      } else if (size >= 20) {
-        context = "display";
+      } else if (el.tagName === "LABEL" || el.tagName === "SMALL" ||
+                 className.includes("label") || className.includes("caption") || className.includes("badge")) {
+        context = "ui";
       }
 
       const key = `${family}|${size}|${weight}|${context}|${letterSpacing}|${textTransform}`;

package/lib/formatters/terminal.js

@@ -185,7 +185,10 @@ function displayColors(colors) {
         hasAlpha: formats.hasAlpha,
         label: '',
         type: 'palette',
-        confidence: c.confidence
+        confidence: c.confidence,
+        role: c.role,
+        onColor: c.onColor,
+        hover: c.hover,
       });
     });
   }
@@ -220,14 +223,14 @@ function displayColors(colors) {
 
   // Display each color on a single line: swatch, hex, role, rgb, oklch.
   // lch is omitted here for compactness but remains in JSON output.
-  uniqueColors.forEach(({ hex, rgb, oklch, label, confidence }, index) => {
+  uniqueColors.forEach(({ hex, rgb, oklch, label, confidence, role, onColor, hover }, index) => {
     const isLast = index === uniqueColors.length - 1;
     const branch = isLast ? '└─' : '├─';
 
     let conf;
     if (confidence === 'high') conf = color.success('●');
     else if (confidence === 'medium') conf = color.warning('●');
-    else conf = chalk.gray('●'); // low confidence
+    else conf = chalk.gray('●');
 
     let swatch;
     try {
@@ -236,17 +239,25 @@ function displayColors(colors) {
       swatch = '  ';
     }
 
-    const rawLabel = label || '';
-    const truncated = rawLabel.length > 22 ? rawLabel.slice(0, 21) + '…' : rawLabel;
-    const labelText = chalk.dim(truncated.padEnd(23));
+    let onSwatch = '';
+    if (onColor && role === 'accent') {
+      try { onSwatch = ' on:' + chalk.bgHex(hex)(chalk.hex(onColor)(' Aa ')); } catch {}
+    }
+
+    const rawLabel = label || (role && role !== 'palette' ? role : '');
+    const truncated = rawLabel.length > 14 ? rawLabel.slice(0, 13) + '…' : rawLabel;
+    const labelText = chalk.dim(truncated.padEnd(15));
     const rgbText = chalk.dim((rgb || '').padEnd(20));
 
+    const hoverText = (hover && role === 'accent') ? chalk.dim(` hover:${hover}`) : '';
+
     console.log(
       chalk.dim(`│  ${branch}`) + ' ' +
       `${conf} ${swatch} ${hex}  ` +
       labelText + ' ' +
-      rgbText + ' ' +
-      chalk.dim(oklch || '')
+      rgbText +
+      onSwatch +
+      hoverText
     );
   });
 

package/lib/merger.js

@@ -275,6 +275,56 @@ function mergeByName(results, getter) {
   return out;
 }
 
+function mergeGradients(results) {
+  const map = new Map();
+  results.forEach(r => {
+    (r.gradients || []).forEach(g => {
+      const key = g.gradient;
+      if (!map.has(key)) {
+        map.set(key, { ...g });
+      } else {
+        map.get(key).count += (g.count || 1);
+      }
+    });
+  });
+  return [...map.values()].sort((a, b) => b.count - a.count);
+}
+
+function mergeMotion(results) {
+  const base = results[0].motion || { durations: [], easings: [], animations: [], contexts: {}, interactiveDeltas: [] };
+
+  const durationMap = new Map();
+  results.forEach(r => {
+    (r.motion?.durations || []).forEach(d => {
+      if (!durationMap.has(d.value)) durationMap.set(d.value, { ...d });
+      else durationMap.get(d.value).count += (d.count || 1);
+    });
+  });
+
+  const easingMap = new Map();
+  results.forEach(r => {
+    (r.motion?.easings || []).forEach(e => {
+      if (!easingMap.has(e.value)) easingMap.set(e.value, { ...e });
+      else easingMap.get(e.value).count += (e.count || 1);
+    });
+  });
+
+  const animMap = new Map();
+  results.forEach(r => {
+    (r.motion?.animations || []).forEach(a => {
+      if (!animMap.has(a.name || a.value)) animMap.set(a.name || a.value, { ...a });
+      else animMap.get(a.name || a.value).count += (a.count || 1);
+    });
+  });
+
+  return {
+    ...base,
+    durations: [...durationMap.values()].sort((a, b) => a.ms - b.ms),
+    easings: [...easingMap.values()].sort((a, b) => b.count - a.count).slice(0, 8),
+    animations: [...animMap.values()].sort((a, b) => b.count - a.count).slice(0, 8),
+  };
+}
+
 /**
  * Merge an array of per-page result objects into a single unified result.
  * @param {Object[]} results - Array of extractBranding() result objects
@@ -298,6 +348,8 @@ export function mergeResults(results) {
     borderRadius: mergeBorderRadius(results),
     borders: mergeBorders(results),
     shadows: mergeShadows(results),
+    gradients: mergeGradients(results),
+    motion: mergeMotion(results),
     components: mergeComponents(results),
     breakpoints: [
       ...new Map(

package/mcp-server.js

@@ -99,16 +99,119 @@ function errorResult(message) {
   return { content: [{ type: "text", text: message }], isError: true };
 }
 
+// ── Job Queue ──────────────────────────────────────────────────────────
+
+class JobQueue {
+  #jobs = new Map();
+  #queue = [];
+  #running = new Set();
+  #maxConcurrent = 2;
+
+  enqueue(url, opts, pick) {
+    const id = `job_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    this.#jobs.set(id, {
+      status: "queued",
+      url,
+      opts,
+      pick,
+      createdAt: Date.now(),
+      startedAt: undefined,
+      completedAt: undefined,
+      result: undefined,
+      error: undefined,
+    });
+    this.#queue.push(id);
+    void this.#drain();
+    return id;
+  }
+
+  get(id) {
+    return this.#jobs.get(id) ?? null;
+  }
+
+  cancel(id) {
+    const job = this.#jobs.get(id);
+    if (!job || job.status !== "queued") return false;
+    job.status = "cancelled";
+    job.completedAt = Date.now();
+    const idx = this.#queue.indexOf(id);
+    if (idx !== -1) this.#queue.splice(idx, 1);
+    return true;
+  }
+
+  async #drain() {
+    while (this.#queue.length > 0 && this.#running.size < this.#maxConcurrent) {
+      const id = this.#queue.shift();
+      const job = this.#jobs.get(id);
+      if (!job || job.status === "cancelled") continue;
+
+      job.status = "running";
+      job.startedAt = Date.now();
+      this.#running.add(id);
+
+      runExtraction(job.url, job.opts)
+        .then((result) => {
+          if (job.status === "cancelled") return;
+          if (result.ok) {
+            job.status = "completed";
+            job.result = job.pick(result.data);
+          } else {
+            job.status = "failed";
+            job.error = result.error;
+          }
+        })
+        .catch((err) => {
+          if (job.status !== "cancelled") {
+            job.status = "failed";
+            job.error = err.message || String(err);
+          }
+        })
+        .finally(() => {
+          job.completedAt = Date.now();
+          this.#running.delete(id);
+          void this.#drain();
+        });
+    }
+  }
+
+  // Remove completed/failed/cancelled jobs older than 1 hour
+  cleanup() {
+    const cutoff = Date.now() - 3_600_000;
+    for (const [id, job] of this.#jobs) {
+      if (
+        ["completed", "failed", "cancelled"].includes(job.status) &&
+        job.completedAt !== undefined &&
+        job.completedAt < cutoff
+      ) {
+        this.#jobs.delete(id);
+      }
+    }
+  }
+}
+
+const jobQueue = new JobQueue();
+setInterval(() => jobQueue.cleanup(), 600_000);
+
+// ── Helpers ────────────────────────────────────────────────────────────
+
 /**
- * Wrapper that handles extraction + error formatting for all tools.
- * `pick` receives the full result and returns the filtered subset.
+ * Wrapper for extraction tools.
+ * Async by default: enqueues and returns a job_id immediately.
+ * Pass sync: true to block and return the result directly.
  */
 function toolHandler(pick, extraOptions = {}) {
   return async (params) => {
-    const { url, slow, darkMode } = params;
-    const result = await runExtraction(url, { slow, darkMode, ...extraOptions });
-    if (!result.ok) return errorResult(result.error);
-    return jsonResult(pick(result.data));
+    const { url, slow, darkMode, sync } = params;
+    const opts = { slow, darkMode, ...extraOptions };
+
+    if (sync) {
+      const result = await runExtraction(url, opts);
+      if (!result.ok) return errorResult(result.error);
+      return jsonResult(pick(result.data));
+    }
+
+    const jobId = jobQueue.enqueue(url, opts, pick);
+    return jsonResult({ job_id: jobId, status: "queued" });
   };
 }
 
@@ -116,21 +219,22 @@ function toolHandler(pick, extraOptions = {}) {
 
 const url = z.string().describe("Website URL (e.g. example.com)");
 const slow = z.boolean().optional().default(false).describe("3x timeouts for heavy SPAs");
+const sync = z.boolean().optional().default(false).describe("Wait for result directly instead of returning a job_id (blocks 15-40s)");
 
-// ── Tools ──────────────────────────────────────────────────────────────
+// ── Extraction tools ───────────────────────────────────────────────────
 
 server.tool(
   "get_design_tokens",
-  "Extract the full design system from a live website. Launches a real browser, navigates to the site, and returns production-ready design tokens: color palette (hex, RGB, LCH, OKLCH) with semantic roles and CSS custom properties, typography scale (families, fallbacks, sizes, weights, line heights, letter spacing by context), spacing system with grid detection, border radii, border patterns, box shadows for elevation, component styles (buttons with hover/focus states, inputs, links, badges), responsive breakpoints, logo and favicons, site name, detected CSS frameworks, and icon systems. Takes 15-40 seconds depending on site complexity.",
-  { url, slow },
+  "Extract the full design system from a live website. Launches a real browser, navigates to the site, and returns production-ready design tokens: color palette (hex, RGB, LCH, OKLCH) with semantic roles and CSS custom properties, typography scale (families, fallbacks, sizes, weights, line heights, letter spacing by context), spacing system with grid detection, border radii, border patterns, box shadows for elevation, component styles (buttons with hover/focus states, inputs, links, badges), responsive breakpoints, logo and favicons, site name, detected CSS frameworks, and icon systems. Returns a job_id by default — use get_job_status to poll for the result.",
+  { url, slow, sync },
   toolHandler((d) => d),
 );
 
 server.tool(
   "get_color_palette",
-  "Extract brand colors from a live website. Returns semantic colors (primary, secondary, accent), full palette ranked by usage frequency and confidence (high/medium/low), CSS custom properties with their design-system names, and hover/focus state colors discovered by simulating real user interactions. Each color in hex, RGB, LCH, and OKLCH.",
+  "Extract brand colors from a live website. Returns semantic colors (primary, secondary, accent), full palette ranked by usage frequency and confidence (high/medium/low), CSS custom properties with their design-system names, and hover/focus state colors discovered by simulating real user interactions. Each color in hex, RGB, LCH, and OKLCH. Returns a job_id by default — use get_job_status to poll for the result.",
   {
-    url, slow,
+    url, slow, sync,
     darkMode: z.boolean().optional().default(false).describe("Also extract dark mode palette"),
   },
   toolHandler((d) => ({ url: d.url, colors: d.colors })),
@@ -138,22 +242,22 @@ server.tool(
 
 server.tool(
   "get_typography",
-  "Extract typography from a live website. Returns every font family with its fallback stack, the complete type scale grouped by context (heading, body, button, link, caption) with pixel and rem sizes, weights, line heights, letter spacing, and text transforms. Also reports font sources: Google Fonts URLs, Adobe Fonts usage, and variable font detection.",
-  { url, slow },
+  "Extract typography from a live website. Returns every font family with its fallback stack, the complete type scale grouped by context (heading, body, button, link, caption) with pixel and rem sizes, weights, line heights, letter spacing, and text transforms. Also reports font sources: Google Fonts URLs, Adobe Fonts usage, and variable font detection. Returns a job_id by default — use get_job_status to poll for the result.",
+  { url, slow, sync },
   toolHandler((d) => ({ url: d.url, typography: d.typography })),
 );
 
 server.tool(
   "get_component_styles",
-  "Extract UI component styles from a live website. Returns button variants with default, hover, active, and focus states (background, text color, padding, border radius, border, shadow, outline, opacity), input field styles (border, focus ring, padding, placeholder), link styles (color, text decoration, hover changes), and badge/tag styles.",
-  { url, slow },
+  "Extract UI component styles from a live website. Returns button variants with default, hover, active, and focus states (background, text color, padding, border radius, border, shadow, outline, opacity), input field styles (border, focus ring, padding, placeholder), link styles (color, text decoration, hover changes), and badge/tag styles. Returns a job_id by default — use get_job_status to poll for the result.",
+  { url, slow, sync },
   toolHandler((d) => ({ url: d.url, components: d.components })),
 );
 
 server.tool(
   "get_surfaces",
-  "Extract surface treatment tokens from a live website: border radii with element context (which radii are used on buttons vs cards vs inputs vs modals), border patterns (width + style + color combinations), and box shadow elevation levels.",
-  { url, slow },
+  "Extract surface treatment tokens from a live website: border radii with element context (which radii are used on buttons vs cards vs inputs vs modals), border patterns (width + style + color combinations), and box shadow elevation levels. Returns a job_id by default — use get_job_status to poll for the result.",
+  { url, slow, sync },
   toolHandler((d) => ({
     url: d.url,
     borderRadius: d.borderRadius,
@@ -164,15 +268,15 @@ server.tool(
 
 server.tool(
   "get_spacing",
-  "Extract the spacing system from a live website: common margin and padding values sorted by frequency, pixel and rem values, and grid system detection (4px, 8px, or custom scale).",
-  { url, slow },
+  "Extract the spacing system from a live website: common margin and padding values sorted by frequency, pixel and rem values, and grid system detection (4px, 8px, or custom scale). Returns a job_id by default — use get_job_status to poll for the result.",
+  { url, slow, sync },
   toolHandler((d) => ({ url: d.url, spacing: d.spacing })),
 );
 
 server.tool(
   "get_brand_identity",
-  "Extract brand identity from a live website: site name, logo (source, dimensions, safe zone), all favicon variants (icon, apple-touch-icon, og:image, twitter:image with sizes and URLs), detected CSS frameworks (Tailwind, Bootstrap, MUI, etc.), icon systems (Font Awesome, Material Icons, SVG), and responsive breakpoints.",
-  { url, slow },
+  "Extract brand identity from a live website: site name, logo (source, dimensions, safe zone), all favicon variants (icon, apple-touch-icon, og:image, twitter:image with sizes and URLs), detected CSS frameworks (Tailwind, Bootstrap, MUI, etc.), icon systems (Font Awesome, Material Icons, SVG), and responsive breakpoints. Returns a job_id by default — use get_job_status to poll for the result.",
+  { url, slow, sync },
   toolHandler((d) => ({
     url: d.url,
     siteName: d.siteName,
@@ -184,6 +288,31 @@ server.tool(
   })),
 );
 
+// ── Job management tools ───────────────────────────────────────────────
+
+server.tool(
+  "get_job_status",
+  "Poll for the result of an async extraction job. Returns status (queued/running/completed/failed/cancelled) and the full result once completed. Call this after any extraction tool that returned a job_id.",
+  { job_id: z.string().describe("The job_id returned by an extraction tool") },
+  ({ job_id }) => {
+    const job = jobQueue.get(job_id);
+    if (!job) return errorResult(`No job found with id: ${job_id}`);
+    if (job.status === "completed") return jsonResult({ job_id, status: "completed", result: job.result });
+    if (job.status === "failed") return errorResult(`Job failed: ${job.error}`);
+    return jsonResult({ job_id, status: job.status });
+  },
+);
+
+server.tool(
+  "cancel_job",
+  "Cancel a queued extraction job. Has no effect on jobs that are already running.",
+  { job_id: z.string().describe("The job_id to cancel") },
+  ({ job_id }) => {
+    const cancelled = jobQueue.cancel(job_id);
+    return jsonResult({ job_id, cancelled });
+  },
+);
+
 // ── Start ──────────────────────────────────────────────────────────────
 
 const transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dembrandt",
-  "version": "0.12.8",
+  "version": "0.12.10",
   "description": "Extract design tokens and publicly visible CSS information from any website",
   "mcpName": "io.github.dembrandt/dembrandt",
   "main": "index.js",
@@ -19,7 +19,13 @@
     "install-browser": "npx playwright install chromium firefox || echo 'Playwright browser installation failed. You may need to install system dependencies manually.'",
     "qa:baseline": "node test/qa.mjs --baseline",
     "qa:diff": "node test/qa.mjs --diff",
-    "qa:site": "node test/qa.mjs --site"
+    "qa:site": "node test/qa.mjs --site",
+    "gold:label": "node tools/gold-label.mjs",
+    "gold:run": "node tools/gold-run.mjs",
+    "gold:judge": "node tools/gold-ai-judge.mjs",
+    "gold:tune": "node tools/gold-tune.mjs",
+    "gold:cluster": "node tools/gold-cluster.mjs",
+    "gold:analyze": "node tools/gold-analyze.mjs"
   },
   "keywords": [
     "design-tokens",
@@ -41,11 +47,10 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",
-    "@playwright/browser-chromium": "^1.57.0",
-    "@playwright/browser-firefox": "^1.57.0",
     "chalk": "^5.3.0",
     "commander": "^11.1.0",
     "ora": "^7.0.1",
+    "playwright": "^1.57.0",
     "playwright-core": "^1.57.0",
     "zod": "4.3.6"
   },