dembrandt 0.14.1 → 0.16.0

package/README.md

@@ -59,6 +59,9 @@ Load extractions, track token drift, and compare snapshots. **[dembrandt.com/app
 * **Copy tokens.** Paste values straight into Copilot, Claude, or Cursor.
 * **No login.** Your data stays in the browser, nothing is sent to any server.
 
+## Recipes
+
+**[dembrandt.com/recipes](https://www.dembrandt.com/recipes)** — 38 ready-to-run workflows. Copy a command, paste a prompt, get a result. Covers competitor benchmarking, WCAG audits, CI/CD drift detection, Figma token push, and agentic design system builds. Filterable by role.
 
 ## What to expect from extraction?
 
@@ -84,6 +87,7 @@ 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 /pricing /docs   # Extract specific paths and merge results into one output
 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 --crawl 10 --sitemap # Combine: up to 10 pages discovered via sitemap

package/index.js

@@ -32,7 +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")
+  .argument("[paths...]", "Additional paths on the same domain 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")
@@ -44,24 +44,19 @@ program
   .option("--design-md", "Export a DESIGN.md file")
   .option("--no-sandbox", "Disable browser sandbox (needed for Docker/CI)")
   .option("--raw-colors", "Include pre-filter raw colors in JSON output")
-  .option("--screenshot <path>", "Save a screenshot of the page")
+  .option("--screenshot <path>", "Save a viewport screenshot of the page (not full-page)")
   .option("--wcag", "Analyze WCAG contrast ratios between palette colors")
-  .option("--crawl [n]", "Auto-discover and extract up to N pages via DOM links (default: 5)", (v) => {
+  .option("--crawl [n]", "Auto-discover and extract up to N pages via DOM links (default: 5); combine with --sitemap to use sitemap discovery instead", (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")
-  .option("--stealth", "Enable anti-detection scripts to bypass bot protection (use only when authorized)")
+  .option("--sitemap", "Discover pages from sitemap.xml instead of DOM links; use alone or combine with --crawl to set page limit")
+  .option("--stealth", "Enable anti-detection: navigator spoofing, human mouse simulation, randomized fingerprint (use only when authorized)")
   .option("--user-agent <string>", "Custom user agent string")
-  .option("--locale <string>", "Browser locale, e.g. en-GB, fi-FI (default: en-US)")
-  .option("--timezone <string>", "Browser timezone, e.g. Europe/Helsinki (default: America/New_York)")
+  .option("--locale <string>", "Browser locale for fingerprint, e.g. en-GB, fi-FI; affects content only if the site reacts to Accept-Language (default: en-US)")
+  .option("--timezone <string>", "Browser timezone for fingerprint, e.g. Europe/Helsinki; affects content only if the site reacts to timezone (default: America/New_York)")
   .option("--accept-language <string>", "Custom Accept-Language header value")
   .option("--screen-size <WxH>", "Physical screen resolution to report, e.g. 1920x1080 (default: 1920x1080)")
   .action(async (input, paths, opts) => {
@@ -126,7 +121,7 @@ program
         }
 
         try {
-          const crawlN = opts.crawl ?? opts.pages ?? null;
+          const crawlN = opts.crawl ?? null;
           const isAutoCrawl = crawlN && !opts.sitemap && (!paths || paths.length === 0);
           const hasExplicitPaths = paths && paths.length > 0;
 
@@ -265,7 +260,7 @@ program
           mkdirSync(outputDir, { recursive: true });
 
           const suffix = opts.dtcg ? '.tokens' : '';
-          const filename = `${timestamp}${suffix}.json`;
+          const filename = `${timestamp}_v${version}${suffix}.json`;
           const filepath = join(outputDir, filename);
           writeFileSync(filepath, JSON.stringify(outputData, null, 2));
 

package/lib/extractors/index.js

@@ -241,6 +241,7 @@ async function simulateHumanMouse(page) {
 export async function extractBranding(url, spinner, browser, options = {}) {
   const timeoutMultiplier = options.slow ? 3 : 1;
   const timeouts = [];
+  const degraded = []; // post-extraction stages that failed but did not abort the run
 
   spinner.text = "Creating browser context...";
 
@@ -556,6 +557,7 @@ export async function extractBranding(url, spinner, browser, options = {}) {
     spinner.stop();
 
     // Inject manifest theme_color / background_color as high-confidence palette entries
+    try {
     if (manifest) {
       const manifestColorEntries = [
         manifest.themeColor && { color: manifest.themeColor, label: 'manifest:theme_color' },
@@ -615,6 +617,7 @@ export async function extractBranding(url, spinner, browser, options = {}) {
       ].filter(Boolean);
       console.log(color.success(`  ✓ Manifest: ${parts.join(', ')}`));
     }
+    } catch (e) { degraded.push('manifest'); console.log(color.warning('  ! Manifest injection: failed (continuing)')); }
     console.log(colors.palette.length > 0 ? color.success(`  ✓ Colors: ${colors.palette.length} found`) : color.warning(`  ! Colors: 0 found`));
     console.log(typography.styles.length > 0 ? color.success(`  ✓ Typography: ${typography.styles.length} styles`) : color.warning(`  ! Typography: 0 styles`));
     console.log(spacing.commonValues.length > 0 ? color.success(`  ✓ Spacing: ${spacing.commonValues.length} values`) : color.warning(`  ! Spacing: 0 values`));
@@ -634,8 +637,10 @@ export async function extractBranding(url, spinner, browser, options = {}) {
     console.log();
 
     // Hover/focus state extraction
-    spinner.start("Extracting hover/focus state colors...");
     const hoverFocusColors = [];
+    const interactiveStatePairs = []; // { fg, bg, state, tag } — raw rgb strings, normalized later (consumed by WCAG stage)
+    try {
+    spinner.start("Extracting hover/focus state colors...");
 
     function splitMultiValueColors(colorValue) {
       if (!colorValue) return [];
@@ -655,7 +660,6 @@ export async function extractBranding(url, spinner, browser, options = {}) {
     `);
 
     const sampled = interactiveElements.slice(0, 20);
-    const interactiveStatePairs = []; // { fg, bg, state, tag } — raw rgb strings, normalized later
 
     for (const element of sampled) {
       try {
@@ -837,9 +841,11 @@ export async function extractBranding(url, spinner, browser, options = {}) {
     console.log(hoverFocusColors.length > 0 ?
       color.success(`  ✓ Hover/focus: ${hoverFocusColors.length} state colors found`) :
       color.warning(`  ! Hover/focus: 0 state colors found`));
+    } catch (e) { spinner.stop(); degraded.push('hover-focus'); console.log(color.warning('  ! Hover/focus: failed (continuing)')); }
 
     // Dark mode
     if (options.darkMode) {
+      try {
       spinner.start("Extracting dark mode colors...");
       await page.evaluate(() => {
         document.documentElement.setAttribute("data-theme", "dark");
@@ -867,10 +873,12 @@ export async function extractBranding(url, spinner, browser, options = {}) {
 
       spinner.stop();
       console.log(color.success(`  ✓ Dark mode: +${darkModeColors.palette.length} colors`));
+      } catch (e) { spinner.stop(); degraded.push('dark-mode'); console.log(color.warning('  ! Dark mode: failed (continuing)')); }
     }
 
     // Mobile viewport
     if (options.mobile) {
+      try {
       spinner.start("Extracting mobile viewport colors...");
       await page.setViewportSize({ width: 390, height: 844 });
       await page.waitForTimeout(500 * timeoutMultiplier);
@@ -885,6 +893,7 @@ export async function extractBranding(url, spinner, browser, options = {}) {
 
       spinner.stop();
       console.log(color.success(`  ✓ Mobile: +${mobileColors.palette.length} colors`));
+      } catch (e) { spinner.stop(); degraded.push('mobile'); console.log(color.warning('  ! Mobile: failed (continuing)')); }
     }
 
     spinner.stop();
@@ -992,16 +1001,19 @@ export async function extractBranding(url, spinner, browser, options = {}) {
       ...(options.wcag ? { wcag } : {}),
     };
 
-    const isCanvasOnly = await page.evaluate(() => {
-      const canvases = document.querySelectorAll("canvas");
-      const hasRealContent = document.body.textContent.trim().length > 200;
-      const hasManyCanvases = canvases.length > 3;
-      const hasWebGL = Array.from(canvases).some((c) => {
-        const ctx = c.getContext("webgl") || c.getContext("webgl2");
-        return !!ctx;
+    let isCanvasOnly = false;
+    try {
+      isCanvasOnly = await page.evaluate(() => {
+        const canvases = document.querySelectorAll("canvas");
+        const hasRealContent = document.body.textContent.trim().length > 200;
+        const hasManyCanvases = canvases.length > 3;
+        const hasWebGL = Array.from(canvases).some((c) => {
+          const ctx = c.getContext("webgl") || c.getContext("webgl2");
+          return !!ctx;
+        });
+        return hasManyCanvases && hasWebGL && !hasRealContent;
       });
-      return hasManyCanvases && hasWebGL && !hasRealContent;
-    });
+    } catch { isCanvasOnly = false; }
 
     if (isCanvasOnly) {
       result.note = "This website uses canvas/WebGL rendering. Design system cannot be extracted from DOM.";
@@ -1009,7 +1021,9 @@ export async function extractBranding(url, spinner, browser, options = {}) {
     }
 
     if (options.screenshotPath) {
-      await page.screenshot({ path: options.screenshotPath, fullPage: false });
+      try {
+        await page.screenshot({ path: options.screenshotPath, fullPage: false });
+      } catch (e) { degraded.push('screenshot'); }
     }
 
     if (options.includeRawColors) {
@@ -1024,6 +1038,8 @@ export async function extractBranding(url, spinner, browser, options = {}) {
       }
     }
 
+    if (degraded.length) result.meta.degraded = degraded;
+
     return result;
   } catch (error) {
     spinner.fail("Extraction failed");

package/lib/extractors/logo.js

@@ -262,10 +262,37 @@ export async function extractLogo(page, url) {
           position: { top: rect.top, left: rect.left },
         };
       } else if (el.tagName === 'SVG' || el.tagName === 'svg') {
+        // Inline SVG: the logo lives in the DOM, not at a URL. Capture the
+        // resolved color (currentColor → the element's `color`), serialize the
+        // markup, and emit a self-contained data URI so the logo is usable.
+        const color = toHex(computed.color);
+        const ariaLabel = el.getAttribute('aria-label') || null;
+
+        let markup = null;
+        let dataUri = null;
+        try {
+          const clone = el.cloneNode(true);
+          // Bake the resolved color in so `currentColor` fills render standalone.
+          if (color) clone.style.color = color;
+          if (!clone.getAttribute('xmlns')) clone.setAttribute('xmlns', 'http://www.w3.org/2000/svg');
+          const serialized = clone.outerHTML;
+          // Skip pathological inline SVGs (sprite sheets, embedded rasters).
+          if (serialized && serialized.length <= 50000) {
+            markup = serialized;
+            dataUri = 'data:image/svg+xml;utf8,' + encodeURIComponent(serialized);
+          }
+        } catch {}
+
         return {
           source: 'svg',
           context,
+          inline: true,
+          // Link target the logo points at; the logo itself is `markup`/`dataUri`.
           url: parentLink ? parentLink.href : baseUrl,
+          color,
+          ariaLabel,
+          markup,
+          dataUri,
           width: el.width?.baseVal?.value || rect.width,
           height: el.height?.baseVal?.value || rect.height,
           type: logoType,
@@ -557,7 +584,10 @@ export async function extractLogo(page, url) {
       try { favicons.push({ type: 'twitter:image', url: new URL(twitterImage.getAttribute('content'), baseUrl).href, sizes: null }); } catch {}
     }
 
-    if (!favicons.some(f => f.url.endsWith('/favicon.ico'))) {
+    // Only synthesize the /favicon.ico fallback when the page declares no icon at
+    // all. Sites that ship their icon under another name (e.g. favicon-purple.ico)
+    // often 404 on the bare /favicon.ico, which would surface as a broken entry.
+    if (!favicons.some(f => /icon/i.test(f.type || ''))) {
       favicons.push({ type: 'favicon.ico', url: new URL('/favicon.ico', baseUrl).href, sizes: null });
     }
 

package/lib/formatters/pdf.js

@@ -846,6 +846,11 @@ ${(() => {
 function getLogoImageUrl(data) {
   const isImageUrl = (url) => /\.(svg|png|jpg|jpeg|webp|gif)(\?.*)?$/i.test(url);
 
+  // Inline SVG logos carry their own self-contained data URI.
+  if (data.logo?.inline && data.logo.dataUri) {
+    return data.logo.dataUri;
+  }
+
   if (data.logo?.url && isImageUrl(data.logo.url)) {
     return data.logo.url;
   }

package/lib/formatters/terminal.js

@@ -69,7 +69,13 @@ function displayLogo(logo) {
 
   console.log(chalk.dim('├─') + ' ' + chalk.bold('Logo'));
 
-  if (logo.url) {
+  if (logo.inline) {
+    const colorInfo = logo.color ? ` · ${logo.color}` : '';
+    console.log(chalk.dim('│  ├─') + ' ' + chalk.dim(`inline ${logo.source || 'svg'}${colorInfo}`));
+    if (logo.url && logo.url !== '/') {
+      console.log(chalk.dim('│  ├─') + ' ' + chalk.blue(terminalLink(logo.url)));
+    }
+  } else if (logo.url) {
     console.log(chalk.dim('│  ├─') + ' ' + chalk.blue(terminalLink(logo.url)));
   }
 

package/mcp-server.js

@@ -15,9 +15,11 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { chromium } from "playwright-core";
 import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
 import { extractBranding } from "./lib/extractors/index.js";
 
 const { version } = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8"));
+const pwVersion = createRequire(import.meta.url)("playwright-core/package.json").version;
 
 const server = new McpServer({
   name: "dembrandt",
@@ -50,7 +52,7 @@ async function runExtraction(url, options = {}) {
   } catch (err) {
     return {
       ok: false,
-      error: `Browser launch failed. Is Playwright installed? Run: npx playwright install chromium\n\n${err.message}`,
+      error: `Browser launch failed. Install the matching browser: npx playwright@${pwVersion} install chromium\n\n${err.message}`,
     };
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dembrandt",
-  "version": "0.14.1",
+  "version": "0.16.0",
   "description": "Extract design tokens and publicly visible CSS information from any website",
   "mcpName": "io.github.dembrandt/dembrandt",
   "main": "index.js",