designlang 10.0.0 → 10.1.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [10.1.0] — 2026-04-22
+
+**Component screenshots.** The existing `--screenshots` flag now emits cluster-aware, retina (2×), multi-variant PNGs instead of five hardcoded selectors and a full-page image.
+
+### Added
+
+- **`src/extractors/component-screenshots.js`** — queries the live DOM with the same candidate selector the crawler uses, groups matches by `kind + variantHint + sizeHint`, and captures up to three representatives per group. Falls back to the v9 hardcoded list when no clusters produced anything (auth / docs pages).
+- Retina capture via a dedicated Playwright context at `deviceScaleFactor: 2`.
+- **`*-screenshots.json`** — index file mapping every cropped PNG to its cluster name, variant, bounds, and fallback flag.
+- Markdown formatter gains a **Component Screenshots** section listing the first 20 crops.
+
+### Behaviour
+
+- No new CLI flags. `--screenshots` and `--full` continue to opt into capture.
+- Backward compatible — when no clusters match, the v9 hardcoded selector set still fires.
+
+### Tests
+
+297 → **299** passing.
+
 ## [10.0.0] — 2026-04-22
 
 **The Intent Release.** v9 captured *how* a site looks; v10 captures *what it is* — the semantic layer LLM agents need to rebuild a site faithfully, not just restyle a generic scaffold. Six new extractors, a multi-page crawl orchestrator, an optional smart-classifier LLM fallback, and a ready-to-paste prompt pack. 297/297 tests passing.

package/README.md

@@ -7,6 +7,7 @@
   <a href="https://github.com/Manavarya09/design-extract/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Manavarya09/design-extract?color=0A0908&labelColor=F3F1EA" alt="license"></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/designlang?color=0A0908&labelColor=F3F1EA" alt="node version"></a>
   <a href="https://designlang.manavaryasingh.com/"><img src="https://img.shields.io/badge/website-live-FF4800?labelColor=F3F1EA" alt="website"></a>
+[![SafeSkill 77/100](https://img.shields.io/badge/SafeSkill-77%2F100_Passes%20with%20Notes-yellow)](https://safeskill.dev/scan/manavarya09-design-extract)
 </p>
 
 ---

package/bin/design-extract.js

@@ -9,6 +9,7 @@ import { extractDesignLanguage } from '../src/index.js';
 import { refineWithSmart } from '../src/classifiers/smart.js';
 import { crawlCanonicalPages } from '../src/multipage.js';
 import { extractLogo } from '../src/extractors/logo.js';
+import { captureComponentScreenshotsV10 } from '../src/extractors/component-screenshots.js';
 import { buildPromptPack } from '../src/formatters/prompt-pack.js';
 import { formatMarkdown } from '../src/formatters/markdown.js';
 import { formatTokens } from '../src/formatters/tokens.js';
@@ -52,7 +53,7 @@ const program = new Command();
 program
   .name('designlang')
   .description('Extract the complete design language from any website')
-  .version('10.0.0');
+  .version('10.1.0');
 
 // ── Main command: extract ──────────────────────────────────────
 program
@@ -220,6 +221,18 @@ program
         } catch (e) { design.logo = { found: false, error: e.message }; }
       }
 
+      // v10.1: cluster-aware retina component screenshots.
+      if (merged.full || merged.screenshots) {
+        spinner.text = 'Capturing component screenshots (retina)...';
+        try {
+          design.componentScreenshots = await captureComponentScreenshotsV10(url, outDir, {
+            width: merged.width,
+            height: parseInt(merged.height) || 800,
+            channel: merged.systemChrome ? 'chrome' : undefined,
+          });
+        } catch (e) { design.componentScreenshots = { error: e.message }; }
+      }
+
       // v10: multi-page canonical crawl (pricing/docs/blog/about/product).
       const pagesArg = merged.pages != null ? merged.pages : (merged.full ? 5 : 0);
       if (pagesArg > 0) {
@@ -306,6 +319,9 @@ program
       if (design.multiPage) {
         files.push({ name: `${prefix}-multipage.json`, content: JSON.stringify(design.multiPage, null, 2), label: 'Multi-Page Crawl' });
       }
+      if (design.componentScreenshots && (design.componentScreenshots.components || []).length) {
+        files.push({ name: `${prefix}-screenshots.json`, content: JSON.stringify(design.componentScreenshots, null, 2), label: 'Component Screenshots index' });
+      }
       if (merged.prompts !== false) {
         const pack = buildPromptPack(design);
         const promptsDir = join(outDir, `${prefix}-prompts`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "designlang",
-  "version": "10.0.0",
+  "version": "10.1.0",
   "description": "Extract the complete design language from any website — colors, typography, spacing, shadows, motion, component anatomy, brand voice, page intent, section roles, material language, component library, imagery style, and logo. Outputs AI-optimized markdown, W3C design tokens, motion tokens, typed component stubs, Tailwind config, and ready-to-paste v0 / Lovable / Cursor / Claude-Artifacts prompts.",
   "type": "module",
   "bin": {

package/src/extractors/component-screenshots.js

@@ -0,0 +1,161 @@
+// v10.1 — Component Screenshots
+//
+// Given a Playwright Page, crop PNG screenshots for each detected component
+// cluster. We re-query the DOM using the same candidate selector the crawler
+// uses, group matches by `kind + variantHint + sizeHint`, and capture up to
+// three representatives per group at 2× retina. Writes into a `screenshots/`
+// subdirectory under the output root and returns an index the bin emits as
+// `*-screenshots.json`.
+
+import { chromium } from 'playwright';
+import { mkdirSync } from 'fs';
+import { join } from 'path';
+
+const CANDIDATE_SELECTOR = 'button, a[role="button"], .btn, [class*="button"], input[type="text"], input[type="email"], input[type="search"], textarea, [class*="card"]';
+
+const FALLBACK_GROUPS = [
+  { slug: 'button', selector: 'button:not(:empty), a[role="button"], [class*="btn"]:not(:empty)' },
+  { slug: 'card', selector: '[class*="card"]:not(:empty)' },
+  { slug: 'input', selector: 'input[type="text"], input[type="email"], input[type="search"], textarea' },
+  { slug: 'nav', selector: 'nav, [role="navigation"]' },
+  { slug: 'hero', selector: '[class*="hero"], section:first-of-type' },
+];
+
+function slugify(s) {
+  return (s || 'component')
+    .toString()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '') || 'component';
+}
+
+async function collectClusteredHandles(page) {
+  // In-page classification mirrors what the crawler does for candidates but
+  // returns enough to screenshot (unique index so we can re-find handles).
+  const groups = await page.evaluate((sel) => {
+    const out = {};
+    let ix = 0;
+    for (const el of document.querySelectorAll(sel)) {
+      const r = el.getBoundingClientRect();
+      if (r.width < 20 || r.height < 10) continue;
+      if (r.width > window.innerWidth || r.height > window.innerHeight * 2) continue;
+      const cs = getComputedStyle(el);
+      if (cs.visibility === 'hidden' || cs.display === 'none' || parseFloat(cs.opacity) < 0.1) continue;
+
+      const tag = el.tagName.toLowerCase();
+      const cls = typeof el.className === 'string' ? el.className.toLowerCase() : '';
+      let kind = 'other';
+      if (tag === 'button' || el.getAttribute('role') === 'button' || /\bbtn\b|button/.test(cls)) kind = 'button';
+      else if (tag === 'input' || tag === 'textarea') kind = 'input';
+      else if (/card/.test(cls)) kind = 'card';
+      else if (tag === 'a') kind = 'link';
+
+      const variant = ((cls.match(/\b(primary|secondary|tertiary|ghost|outline|solid|destructive|danger|success|warning|subtle)\b/) || [])[1]) || 'default';
+      const size = ((cls.match(/\b(xs|sm|md|lg|xl|small|medium|large)\b/) || [])[1]) || '';
+
+      const key = [kind, variant, size].filter(Boolean).join('--');
+      if (!out[key]) out[key] = [];
+      el.setAttribute('data-dl-shot', String(ix));
+      out[key].push({ ix, w: Math.round(r.width), h: Math.round(r.height), kind, variant, size });
+      ix++;
+    }
+    return out;
+  }, CANDIDATE_SELECTOR);
+  return groups;
+}
+
+async function captureGroup(page, key, entries, screenshotDir, maxPerGroup = 3) {
+  const out = [];
+  const slug = slugify(key);
+  let variant = 0;
+  for (const info of entries.slice(0, maxPerGroup)) {
+    const handle = await page.$(`[data-dl-shot="${info.ix}"]`);
+    if (!handle) continue;
+    const file = `${slug}-${variant}.png`;
+    const path = join(screenshotDir, file);
+    try {
+      await handle.screenshot({ path, omitBackground: false });
+    } catch { continue; }
+    out.push({
+      cluster: key,
+      variant,
+      path: `screenshots/${file}`,
+      bounds: { w: info.w, h: info.h },
+      kind: info.kind,
+      variantHint: info.variant,
+      sizeHint: info.size,
+      retina: true,
+    });
+    variant++;
+  }
+  return out;
+}
+
+async function captureFallbacks(page, screenshotDir) {
+  const out = [];
+  for (const g of FALLBACK_GROUPS) {
+    try {
+      const handles = await page.$$(g.selector);
+      for (const h of handles.slice(0, 2)) {
+        const box = await h.boundingBox();
+        if (!box || box.width < 20 || box.height < 10) continue;
+        const path = join(screenshotDir, `${g.slug}-${out.filter(x => x.cluster === g.slug).length}.png`);
+        await h.screenshot({ path });
+        out.push({
+          cluster: g.slug,
+          variant: out.filter(x => x.cluster === g.slug).length,
+          path: `screenshots/${path.split('screenshots/')[1]}`,
+          bounds: { w: Math.round(box.width), h: Math.round(box.height) },
+          retina: true,
+          fallback: true,
+        });
+      }
+    } catch { /* skip */ }
+  }
+  return out;
+}
+
+// Public entry. Launches a fresh Playwright context at deviceScaleFactor: 2
+// so captures are crisp on retina displays without a second full run.
+export async function captureComponentScreenshotsV10(url, outDir, { width = 1280, height = 800, channel } = {}) {
+  const screenshotDir = join(outDir, 'screenshots');
+  mkdirSync(screenshotDir, { recursive: true });
+
+  const browser = await chromium.launch({ headless: true, ...(channel && { channel }) });
+  try {
+    const context = await browser.newContext({
+      viewport: { width, height },
+      deviceScaleFactor: 2,
+      colorScheme: 'light',
+    });
+    const page = await context.newPage();
+    await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 }).catch(() => {});
+    await page.waitForLoadState('networkidle').catch(() => {});
+    await page.evaluate(() => document.fonts.ready).catch(() => {});
+
+    const groups = await collectClusteredHandles(page);
+    let components = [];
+    for (const [key, entries] of Object.entries(groups)) {
+      if (!entries.length) continue;
+      const rows = await captureGroup(page, key, entries, screenshotDir);
+      components.push(...rows);
+    }
+
+    // If clustering produced nothing (auth / docs pages often do), fall back
+    // to the v9 hardcoded selector list so users still get something.
+    if (!components.length) {
+      components = await captureFallbacks(page, screenshotDir);
+    }
+
+    let fullPage = null;
+    try {
+      const p = join(screenshotDir, 'full-page.png');
+      await page.screenshot({ path: p, fullPage: true });
+      fullPage = { path: 'screenshots/full-page.png', retina: true };
+    } catch { /* non-fatal */ }
+
+    return { components, fullPage, count: components.length };
+  } finally {
+    await browser.close();
+  }
+}

package/src/formatters/markdown.js

@@ -802,6 +802,24 @@ export function formatMarkdown(design) {
     }
   }
 
+  // ── v10.1: Component Screenshots ──
+  if (design.componentScreenshots && Array.isArray(design.componentScreenshots.components) && design.componentScreenshots.components.length) {
+    lines.push('## Component Screenshots');
+    lines.push('');
+    lines.push(`${design.componentScreenshots.components.length} retina crops written to \`screenshots/\`. Index: \`*-screenshots.json\`.`);
+    lines.push('');
+    lines.push('| Cluster | Variant | Size (px) | File |');
+    lines.push('|---------|---------|-----------|------|');
+    for (const c of design.componentScreenshots.components.slice(0, 20)) {
+      lines.push(`| ${c.cluster} | ${c.variant} | ${c.bounds?.w || '?'} × ${c.bounds?.h || '?'} | \`${c.path}\` |`);
+    }
+    if (design.componentScreenshots.fullPage) {
+      lines.push('');
+      lines.push(`Full-page: \`${design.componentScreenshots.fullPage.path}\``);
+    }
+    lines.push('');
+  }
+
   // ── Quick Start ──
   lines.push('## Quick Start');
   lines.push('');

package/src/index.js

@@ -202,6 +202,7 @@ export { extractComponentLibrary } from './extractors/component-library.js';
 export { extractMaterialLanguage } from './extractors/material-language.js';
 export { extractImageryStyle } from './extractors/imagery-style.js';
 export { extractLogo } from './extractors/logo.js';
+export { captureComponentScreenshotsV10 } from './extractors/component-screenshots.js';
 export { refineWithSmart } from './classifiers/smart.js';
 export { crawlCanonicalPages, computeCrossPageConsistency, discoverCanonicalPages } from './multipage.js';
 export { buildPromptPack, formatV0Prompt, formatLovablePrompt, formatCursorPrompt, formatClaudeArtifactPrompt } from './formatters/prompt-pack.js';