design-clone 2.1.0 → 3.0.0

package/src/core/capture/screenshot-orchestrator.js

@@ -0,0 +1,174 @@
+/**
+ * Screenshot Orchestrator
+ *
+ * Post-capture orchestration: hover state capture, video recording,
+ * section-based cropping, and component dimension output assembly.
+ * Called after per-viewport screenshots are complete.
+ *
+ * @module screenshot-orchestrator
+ */
+
+import path from 'path';
+import fs from 'fs/promises';
+import { captureAllHoverStates, generateHoverCss } from '../animation/state-capture.js';
+import { captureVideo, hasFfmpeg, FFMPEG_REQUIRED_FORMATS } from '../media/video-capture.js';
+import { buildDimensionsOutput, generateAISummary } from '../dimension/dimension-output.js';
+import { VIEWPORTS } from '../../shared/viewports.js';
+import { logInfo, logWarn } from '../../utils/log.js';
+
+/**
+ * Capture hover states with headed→headless fallback.
+ * Writes hover.css to output if captures succeed.
+ */
+export async function runHoverCapture(
+  browserMgr, extraction, output, url,
+  initBrowser, getHeadlessForViewport, requestedViewports
+) {
+  const readCss = async () => extraction?.css?.path ? fs.readFile(extraction.css.path, 'utf-8') : null;
+  try {
+    const wasHeadless = browserMgr.getCurrentHeadless();
+    let hoverResult = null;
+    let hoverCaptureSuccess = false;
+
+    if (!wasHeadless) {
+      try {
+        hoverResult = await captureAllHoverStates(browserMgr.getPage(), await readCss(), output);
+        hoverCaptureSuccess = hoverResult.captured > 0;
+      } catch (headedError) {
+        logWarn(`Headed hover capture failed, switching to headless: ${headedError.message}`);
+      }
+    }
+
+    if (!hoverCaptureSuccess) {
+      if (!browserMgr.getCurrentHeadless()) await initBrowser(true, url);
+      hoverResult = await captureAllHoverStates(browserMgr.getPage(), await readCss(), output);
+    }
+
+    if (hoverResult?.elements && hoverResult.captured > 0) {
+      const hoverCssPath = path.join(output, 'hover.css');
+      await fs.writeFile(hoverCssPath, generateHoverCss(hoverResult.elements), 'utf-8');
+      hoverResult.generatedCss = path.resolve(hoverCssPath);
+    }
+    if (hoverResult) logInfo(`Hover states: ${hoverResult.captured}/${hoverResult.detected} captured`);
+    if (!wasHeadless && browserMgr.getCurrentHeadless() && requestedViewports.some(v => !getHeadlessForViewport(v))) {
+      await initBrowser(false, url);
+    }
+    return hoverResult;
+  } catch (error) {
+    logWarn(`Hover capture failed: ${error.message}`);
+    return { error: error.message, failed: true };
+  }
+}
+
+/** Record a scroll video (WebM → optionally MP4/GIF). Returns error object on failure. */
+export async function runVideoCapture(browserMgr, output, videoFormat, videoDuration) {
+  try {
+    if (FFMPEG_REQUIRED_FORMATS.includes(videoFormat)) {
+      const hasFf = await hasFfmpeg();
+      if (!hasFf) {
+        logWarn(`ffmpeg not found. Will output WebM instead of ${videoFormat}`);
+        logWarn('Install: npm install fluent-ffmpeg @ffmpeg-installer/ffmpeg');
+      }
+    }
+
+    const videoPage = browserMgr.getPage();
+    await videoPage.setViewportSize(VIEWPORTS.desktop);
+    await new Promise(r => setTimeout(r, 1000));
+
+    logInfo(`Recording video (${videoDuration / 1000}s)...`);
+
+    const videoResult = await captureVideo(videoPage, output, {
+      format: videoFormat,
+      duration: videoDuration,
+      filename: 'preview'
+    });
+
+    const outputFormat = videoResult.output.split('.').pop();
+    logInfo(`Video saved: ${outputFormat} (${(videoResult.duration / 1000).toFixed(1)}s)`);
+
+    return videoResult;
+  } catch (error) {
+    logWarn(`Video capture failed: ${error.message}`);
+    return { error: error.message, failed: true };
+  }
+}
+
+/** Detect sections and crop desktop screenshot into individual section images. */
+export async function runSectionCapture(browserMgr, desktopScreenshot, output) {
+  try {
+    const { detectSections } = await import('../section/section-detector.js');
+    const { cropSections } = await import('../section/section-cropper.js');
+
+    const sectionPage = browserMgr.getPage();
+    await sectionPage.setViewportSize(VIEWPORTS.desktop);
+    await new Promise(r => setTimeout(r, 500));
+
+    logInfo('Detecting sections...');
+
+    const sections = await detectSections(sectionPage, {
+      padding: 40,
+      minSections: 3,
+      fallbackToViewport: true
+    });
+
+    logInfo(`Found ${sections.length} sections, cropping...`);
+
+    const croppedResult = await cropSections(desktopScreenshot.path, sections, output);
+
+    logInfo(`Sections: ${croppedResult.sections.length} cropped, ${croppedResult.skipped.length} skipped`);
+
+    return {
+      enabled: true,
+      count: croppedResult.sections.length,
+      skipped: croppedResult.skipped.length,
+      sections: croppedResult.sections.map(s => ({
+        index: s.index,
+        name: s.name,
+        path: s.relativePath,
+        bounds: s.bounds,
+        role: s.role
+      })),
+      directory: croppedResult.directory,
+      summary: croppedResult.summary
+    };
+  } catch (err) {
+    logWarn(`Section processing failed: ${err.message}`);
+    return { enabled: true, error: err.message };
+  }
+}
+
+/** Build component-dimensions.json + dimensions-summary.json; return stats. */
+export async function runDimensionOutput(screenshots, url, output) {
+  const allViewportDimensions = {};
+  for (const screenshot of screenshots) {
+    if (screenshot.componentDimensions) {
+      allViewportDimensions[screenshot.viewport] = screenshot.componentDimensions;
+    }
+  }
+
+  const dimensionsOutput = buildDimensionsOutput(allViewportDimensions, url);
+  const dimensionsPath = path.join(output, 'component-dimensions.json');
+  await fs.writeFile(dimensionsPath, JSON.stringify(dimensionsOutput, null, 2));
+
+  const aiSummary = generateAISummary(dimensionsOutput);
+  const summaryPath = path.join(output, 'dimensions-summary.json');
+  await fs.writeFile(summaryPath, JSON.stringify(aiSummary, null, 2));
+
+  const vpValues = Object.values(dimensionsOutput.viewports);
+  const sum = (key) => vpValues.reduce((s, vp) => s + (vp[key]?.length || 0), 0);
+  const stats = { containers: sum('containers'), cards: sum('cards'), gridLayouts: sum('gridLayouts'), typography: sum('typography') };
+
+  logInfo(`Extracted: ${stats.containers} containers, ${stats.cards} card groups, ${stats.gridLayouts} grid layouts`);
+
+  return { dimensionsOutput, dimensionsPath: path.resolve(dimensionsPath), summaryPath: path.resolve(summaryPath), stats };
+}
+
+/** Write dom-hierarchy.json from desktopScreenshot.domHierarchy. Returns path or null. */
+export async function writeDomHierarchy(desktopScreenshot, output) {
+  if (!desktopScreenshot?.domHierarchy) return null;
+  const hierarchyPath = path.join(output, 'dom-hierarchy.json');
+  await fs.writeFile(hierarchyPath, JSON.stringify(desktopScreenshot.domHierarchy, null, 2));
+  const s = desktopScreenshot.domHierarchy.stats || {};
+  logInfo(`DOM hierarchy: ${s.totalNodes || 0} nodes, ${s.landmarkCount || 0} landmarks, ${s.extractionTimeMs || 0}ms`);
+  return path.resolve(hierarchyPath);
+}

package/src/core/capture/screenshot-viewport.js

@@ -0,0 +1,93 @@
+/**
+ * Screenshot Viewport Capture
+ *
+ * Single-viewport screenshot: sets viewport size, waits for DOM stability,
+ * triggers lazy-load, forces animated elements visible, then takes the screenshot.
+ *
+ * @module screenshot-viewport
+ */
+
+import path from 'path';
+
+import { waitForDomStable, waitForFontsLoaded, waitForStylesStable } from '../page-prep/page-readiness.js';
+import { forceLazyImages, forceAnimatedElementsVisible, triggerLazyLoad, waitForAllImages, LAZY_LOAD_MAX_ITERATIONS } from '../page-prep/lazy-loader.js';
+import { extractComponentDimensions } from '../dimension/dimension-extractor.js';
+import { extractDOMHierarchy } from '../dimension/dom-tree-analyzer.js';
+import { compressIfNeeded, VIEWPORT_SETTLE_DELAY, NETWORK_IDLE_TIMEOUT, DEFAULT_SCROLL_DELAY } from './screenshot-helpers.js';
+import { VIEWPORTS } from '../../shared/viewports.js';
+
+/**
+ * Capture screenshot for a single viewport.
+ * Handles DOM stability, lazy images, animations, and optional compression.
+ *
+ * @param {{page, viewport, outputPath, fullPage?, maxSize?, scrollDelay?}} options
+ * @returns {Promise<{viewport, path, dimensions, componentDimensions, domHierarchy, scrollInfo, imageStats, size, compressed}>}
+ */
+export async function captureViewport(options) {
+  const {
+    page,
+    viewport,
+    outputPath,
+    fullPage = true,
+    maxSize = 5,
+    scrollDelay = DEFAULT_SCROLL_DELAY,
+    viewportMap = VIEWPORTS
+  } = options;
+
+  await page.setViewportSize(viewportMap[viewport]);
+  await new Promise(r => setTimeout(r, VIEWPORT_SETTLE_DELAY));
+  await waitForDomStable(page, 300, 5000);
+  await waitForFontsLoaded(page, 3000);
+  await waitForStylesStable(page, 200, 2000);
+
+  const componentDimensions = await extractComponentDimensions(page, viewport);
+
+  // Extract DOM hierarchy on desktop only (perf: skip on tablet/mobile)
+  let domHierarchy = null;
+  if (viewport === 'desktop') {
+    try {
+      domHierarchy = await extractDOMHierarchy(page, { maxDepth: 8 });
+    } catch (err) {
+      console.error(`[WARN] DOM hierarchy extraction failed: ${err.message}`);
+    }
+  }
+
+  await forceLazyImages(page);
+  const scrollInfo = await triggerLazyLoad(page, LAZY_LOAD_MAX_ITERATIONS, scrollDelay);
+  await forceLazyImages(page);
+  const imageStats = await waitForAllImages(page, 15000);
+
+  try {
+    await page.waitForLoadState('networkidle', { timeout: NETWORK_IDLE_TIMEOUT });
+  } catch {
+    // Acceptable: page may have long-polling connections
+  }
+
+  await new Promise(r => setTimeout(r, 2000));
+  await waitForDomStable(page, 300, 3000);
+  await waitForFontsLoaded(page, 2000);
+  await forceAnimatedElementsVisible(page);
+  await new Promise(r => setTimeout(r, 300));
+
+  await page.evaluate(() => {
+    window.scrollTo(0, 0);
+    document.documentElement.scrollTop = 0;
+    document.body.scrollTop = 0;
+  });
+  await new Promise(r => setTimeout(r, 500));
+
+  await page.screenshot({ path: outputPath, type: 'png', fullPage });
+  const compression = await compressIfNeeded(outputPath, maxSize);
+
+  return {
+    viewport,
+    path: path.resolve(outputPath),
+    dimensions: viewportMap[viewport],
+    componentDimensions,
+    domHierarchy,
+    scrollInfo,
+    imageStats,
+    size: compression.finalSize,
+    compressed: compression.compressed
+  };
+}

package/src/core/capture/screenshot.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * Multi-viewport screenshot capture for design cloning
+ *
+ * Usage: node screenshot.js --url <url> --output <dir> [options]
+ *
+ * Options:
+ *   --url, --output, --viewports, --full-page, --max-size, --headless,
+ *   --scroll-delay, --close, --extract-html, --extract-css, --filter-unused,
+ *   --capture-hover, --video, --video-format, --video-duration,
+ *   --section-mode, --no-semantic
+ */
+
+import path from 'path';
+import fs from 'fs/promises';
+
+import { getBrowser, getPage, closeBrowser, disconnectBrowser } from '../../utils/browser.js';
+import { parseArgs, outputJSON, outputError } from '../../utils/helpers.js';
+import { parseScreenshotArgs, createBrowserManager, VIEWPORTS } from './screenshot-helpers.js';
+import { runExtractionPipeline } from './screenshot-extraction.js';
+import { runHoverCapture, runVideoCapture, runSectionCapture, runDimensionOutput, writeDomHierarchy } from './screenshot-orchestrator.js';
+import { logInfo } from '../../utils/log.js';
+import { createProgress } from '../../utils/progress.js';
+import { captureViewport } from './screenshot-viewport.js';
+
+// ============================================================================
+// Main Orchestration
+// ============================================================================
+
+async function captureMultiViewport() {
+  const options = parseScreenshotArgs(process.argv.slice(2));
+  let {
+    url, output, viewports: requestedViewports,
+    fullPage, maxSize, scrollDelay,
+    extractHtml, extractCss, filterUnused,
+    captureHover, captureVideo: captureVideoFlag,
+    videoFormat, videoDuration, sectionMode,
+    enhanceSemantic, extractAnimations: extractAnimationsFlag,
+    headless: cliHeadless, close: shouldClose
+  } = options;
+
+  try {
+    await fs.mkdir(output, { recursive: true });
+
+    const browserMgr = createBrowserManager(cliHeadless);
+    const { getHeadlessForViewport, init: initBrowser } = browserMgr;
+    await initBrowser(getHeadlessForViewport(requestedViewports[0]), url);
+
+    const cookieResult = browserMgr.getCookieResult();
+
+    // HTML/CSS/animation extraction
+    let extraction = null;
+    if (extractHtml || extractCss) {
+      extraction = await runExtractionPipeline(browserMgr.getPage(), url, output, {
+        extractHtml, extractCss, filterUnused, enhanceSemantic,
+        extractAnimations: extractAnimationsFlag,
+        extractComputed: options.extractComputed,
+        aggressiveFilter: options.aggressiveFilter
+      });
+    }
+
+    // Hover state capture
+    let hoverResult = null;
+    if (captureHover) {
+      hoverResult = await runHoverCapture(
+        browserMgr, extraction, output, url,
+        initBrowser, getHeadlessForViewport, requestedViewports
+      );
+    }
+
+    // Breakpoint detection: override viewports with CSS-detected breakpoints
+    // Use a local copy to avoid mutating the global VIEWPORTS object (side-effect prevention)
+    let localViewports = { ...VIEWPORTS };
+    let detectedBreakpoints = null;
+    if (options.detectBreakpoints && extraction?.css?.path && !extraction.css.failed) {
+      try {
+        const rawCss = await fs.readFile(extraction.css.path, 'utf-8');
+        const { detectBreakpoints, mergeWithFixed } = await import('../css/breakpoint-detector.js');
+        detectedBreakpoints = detectBreakpoints(rawCss);
+        const bpPath = path.join(output, 'breakpoints.json');
+        await fs.writeFile(bpPath, JSON.stringify(detectedBreakpoints, null, 2));
+        if (detectedBreakpoints.breakpoints.length > 0) {
+          const mergedViewports = mergeWithFixed(detectedBreakpoints.breakpoints);
+          requestedViewports = Object.keys(mergedViewports);
+          for (const [name, config] of Object.entries(mergedViewports)) {
+            if (!localViewports[name]) localViewports[name] = config;
+          }
+        }
+      } catch { /* breakpoint detection optional, continue with defaults */ }
+    }
+
+    // Per-viewport screenshots
+    const screenshots = [];
+    const browserRestarts = [];
+    const allHeadless = requestedViewports.every(vp => getHeadlessForViewport(vp));
+    const vpProgress = createProgress();
+    vpProgress.start(requestedViewports.length, 'Viewport capture');
+
+    if (allHeadless) {
+      // Fast path: single browser session, just resize viewport
+      for (const viewport of requestedViewports) {
+        vpProgress.step(`Capturing ${viewport}`, `${localViewports[viewport].width}px`);
+        screenshots.push(await captureViewport({
+          page: browserMgr.getPage(), viewport,
+          outputPath: path.join(output, `${viewport}.png`),
+          fullPage, maxSize, scrollDelay, viewportMap: localViewports
+        }));
+      }
+    } else {
+      // Restart path for mixed headless/headed scenarios
+      for (const viewport of requestedViewports) {
+        vpProgress.step(`Capturing ${viewport}`, `${localViewports[viewport].width}px`);
+        const viewportHeadless = getHeadlessForViewport(viewport);
+        if (browserMgr.getCurrentHeadless() !== viewportHeadless) {
+          browserRestarts.push({ viewport, from: browserMgr.getCurrentHeadless() ? 'headless' : 'headed', to: viewportHeadless ? 'headless' : 'headed' });
+          logInfo(`Switching to ${viewportHeadless ? 'headless' : 'headed'} for ${viewport}`);
+          await initBrowser(viewportHeadless, url);
+        }
+        screenshots.push(await captureViewport({
+          page: browserMgr.getPage(), viewport,
+          outputPath: path.join(output, `${viewport}.png`),
+          fullPage, maxSize, scrollDelay, viewportMap: localViewports
+        }));
+      }
+    }
+    vpProgress.complete(`${screenshots.length} viewports captured`);
+
+    // Optional: video, dimensions, DOM hierarchy, sections
+    const videoResult = captureVideoFlag
+      ? await runVideoCapture(browserMgr, output, videoFormat, videoDuration)
+      : null;
+
+    const dimResult = await runDimensionOutput(screenshots, url, output);
+    const desktopScreenshot = screenshots.find(s => s.viewport === 'desktop');
+    const hierarchyPath = await writeDomHierarchy(desktopScreenshot, output);
+    const sectionResult = (sectionMode && desktopScreenshot)
+      ? await runSectionCapture(browserMgr, desktopScreenshot, output)
+      : null;
+
+    // Quality score: auto for clone-px, opt-in for basic clone
+    const isClonePx = captureHover || options.extractAssets;
+    let qualityScore = null;
+    if (isClonePx || options.qualityScore) {
+      try {
+        const { scoreCapture } = await import('../../verification/quality-scorer.js');
+        qualityScore = await scoreCapture({
+          extraction, screenshots, assetStats: null, outputDir: output
+        });
+        const scorePath = path.join(output, 'quality-score.json');
+        await fs.writeFile(scorePath, JSON.stringify(qualityScore, null, 2));
+      } catch { /* quality scoring optional */ }
+    }
+
+    outputJSON({
+      success: true, url, outputDir: path.resolve(output), cookieHandling: cookieResult,
+      extraction,
+      qualityScore: qualityScore || undefined,
+      hoverStates: hoverResult && !hoverResult.failed
+        ? { directory: hoverResult.directory, detected: hoverResult.detected, captured: hoverResult.captured, summaryPath: hoverResult.summaryPath, generatedCss: hoverResult.generatedCss }
+        : (hoverResult?.error ? { error: hoverResult.error } : undefined),
+      video: videoResult && !videoResult.failed
+        ? { path: videoResult.output, format: videoResult.output.split('.').pop(), duration: videoResult.duration, pageHeight: videoResult.pageHeight, webm: videoResult.webm, mp4: videoResult.mp4, gif: videoResult.gif, conversionError: videoResult.conversionError }
+        : (videoResult?.error ? { error: videoResult.error } : undefined),
+      componentDimensions: { full: dimResult.dimensionsPath, summary: dimResult.summaryPath, viewports: Object.keys(dimResult.dimensionsOutput.viewports), stats: dimResult.stats },
+      domHierarchy: desktopScreenshot?.domHierarchy ? { path: hierarchyPath, stats: desktopScreenshot.domHierarchy.stats } : undefined,
+      sections: sectionResult, screenshots,
+      browserRestarts: browserRestarts.length > 0 ? browserRestarts : undefined,
+      scrollDelay, totalSize: screenshots.reduce((sum, s) => sum + s.size, 0),
+      capturedAt: new Date().toISOString()
+    });
+
+    if (shouldClose) await closeBrowser(); else await disconnectBrowser();
+    process.exit(0);
+  } catch (error) {
+    outputError(error);
+    process.exit(1);
+  } finally {
+    try { await closeBrowser(); } catch { /* ignore */ }
+  }
+}
+
+// ============================================================================
+// Exports (backward-compatible)
+// ============================================================================
+
+export { captureViewport } from './screenshot-viewport.js';
+export { compressIfNeeded, parseScreenshotArgs, createBrowserManager, VIEWPORT_SETTLE_DELAY, DEFAULT_SCROLL_DELAY, VIEWPORTS } from './screenshot-helpers.js';
+
+// Run if called directly
+if (process.argv[1]?.endsWith('screenshot.js') || process.argv[1]?.includes('screenshot')) {
+  captureMultiViewport();
+}

package/src/core/content/content-counter-dom.js

@@ -0,0 +1,191 @@
+/**
+ * DOM content counting logic executed inside page.evaluate.
+ *
+ * Exports a single serializable function string (domCountingScript) that
+ * is passed into page.evaluate() by content-counter.js. Keeping it separate
+ * allows the browser-side counting logic to be maintained independently of
+ * the Node.js orchestration and summary-generation code.
+ *
+ * All code inside the function runs in browser context — no imports allowed.
+ */
+
+/**
+ * Browser-side DOM counting function.
+ * Returns structured content counts for sections, grids, repeated items,
+ * navigation, media, and interactive elements.
+ *
+ * @returns {Object} content counts
+ */
+export function domCountingFn() {
+  const counts = {
+    extractedAt: new Date().toISOString(),
+    sections: { total: 0, withBackground: 0, details: [] },
+    grids: { total: 0, details: [] },
+    repeatedItems: { total: 0, byType: {} },
+    navigation: { headerLinks: 0, footerLinks: 0, allLinks: 0 },
+    media: { images: 0, videos: 0, svgIcons: 0 },
+    interactive: { buttons: 0, inputs: 0, forms: 0 }
+  };
+
+  const isVisible = (el) => {
+    if (!el) return false;
+    const style = getComputedStyle(el);
+    return style.display !== 'none' &&
+           style.visibility !== 'hidden' &&
+           !el.hasAttribute('hidden');
+  };
+
+  const getSelector = (el) => {
+    if (el.id) return `#${el.id}`;
+    const classes = [...el.classList].filter(c =>
+      !c.match(/^(js-|is-|has-|data-)/) && c.length > 2
+    ).slice(0, 3).join('.');
+    return classes ? `.${classes}` : el.tagName.toLowerCase();
+  };
+
+  // 1. Count sections
+  const sectionSelectors = [
+    'section',
+    '[class*="section"]',
+    '[class*="py-lg"]', '[class*="py-xl"]', '[class*="py-2xl"]',
+    '[class*="py-md"]',
+    '[class*="bg-background"]',
+    '[class*="bg-white"]',
+    '[class*="bg-gray"]'
+  ];
+
+  const sectionElements = new Set();
+  const MAX_SECTION_DETAILS = 30;
+
+  sectionSelectors.forEach(sel => {
+    try {
+      document.querySelectorAll(sel).forEach(el => {
+        if (sectionElements.size >= MAX_SECTION_DETAILS) return;
+        const rect = el.getBoundingClientRect();
+        const isSignificant = rect.height > 100 && rect.width > 200;
+        const parent = el.parentElement;
+        const isTopLevel = parent?.tagName === 'BODY' ||
+                          parent?.tagName === 'MAIN' ||
+                          parent?.id === 'root' ||
+                          parent?.id === '__next' ||
+                          parent?.classList.contains('container');
+        if (isTopLevel || (isSignificant && isVisible(el))) {
+          sectionElements.add(el);
+        }
+      });
+    } catch (e) { /* invalid selector */ }
+  });
+
+  sectionElements.forEach(el => {
+    const style = getComputedStyle(el);
+    const hasBg = style.backgroundColor !== 'rgba(0, 0, 0, 0)' &&
+                  style.backgroundColor !== 'transparent';
+    counts.sections.total++;
+    if (hasBg) counts.sections.withBackground++;
+    counts.sections.details.push({
+      selector: getSelector(el),
+      visible: isVisible(el),
+      hasBackground: hasBg,
+      childCount: el.children.length
+    });
+  });
+
+  // 2. Count grid/flex containers
+  const gridSelectors = ['[class*="grid"]', '[style*="display: grid"]'];
+  const flexSelectors = [
+    '[class*="flex"][class*="gap"]',
+    '[class*="flex"][class*="wrap"]',
+    '[class*="flex"][class*="col"]'
+  ];
+
+  const processedGrids = new Set();
+  const MIN_ITEMS_FOR_GRID = 2;
+  const MAX_GRID_DETAILS = 50;
+
+  [...gridSelectors, ...flexSelectors].forEach(sel => {
+    try {
+      document.querySelectorAll(sel).forEach(el => {
+        if (processedGrids.has(el)) return;
+        if (counts.grids.details.length >= MAX_GRID_DETAILS) return;
+
+        const style = getComputedStyle(el);
+        if (style.display === 'grid' || style.display === 'flex' ||
+            style.display === 'inline-grid' || style.display === 'inline-flex') {
+          processedGrids.add(el);
+          const items = [...el.children].filter(child =>
+            child.tagName !== 'SCRIPT' && child.tagName !== 'STYLE'
+          );
+          if (items.length < MIN_ITEMS_FOR_GRID) return;
+          const visibleItems = items.filter(isVisible);
+          const hiddenItems = items.filter(i => !isVisible(i));
+          if (visibleItems.length >= MIN_ITEMS_FOR_GRID) {
+            counts.grids.total++;
+            counts.grids.details.push({
+              selector: getSelector(el),
+              display: style.display,
+              totalItems: items.length,
+              visibleItems: visibleItems.length,
+              hiddenItems: hiddenItems.length,
+              gridCols: style.gridTemplateColumns || null,
+              visible: isVisible(el)
+            });
+          }
+        }
+      });
+    } catch (e) { /* invalid selector */ }
+  });
+
+  // 3. Count repeated items
+  const repeatPatterns = [
+    { name: 'cards',        selectors: ['[class*="card"]', '[class*="Card"]'] },
+    { name: 'listItems',    selectors: ['li', '[class*="item"]', '[class*="Item"]'] },
+    { name: 'services',     selectors: ['[class*="service"]', '[class*="Service"]'] },
+    { name: 'features',     selectors: ['[class*="feature"]', '[class*="Feature"]'] },
+    { name: 'testimonials', selectors: ['[class*="testimonial"]', '[class*="review"]'] },
+    { name: 'teamMembers',  selectors: ['[class*="team"]', '[class*="member"]', '[class*="person"]'] },
+    { name: 'faqItems',     selectors: ['[class*="faq"]', '[class*="accordion"]', 'details'] },
+    { name: 'pricingCards', selectors: ['[class*="pricing"]', '[class*="plan"]'] },
+    { name: 'blogPosts',    selectors: ['[class*="post"]', '[class*="article"]', 'article'] },
+    { name: 'products',     selectors: ['[class*="product"]', '[class*="Product"]'] },
+    { name: 'categories',   selectors: ['[class*="category"]', '[class*="Category"]'] }
+  ];
+
+  repeatPatterns.forEach(({ name, selectors }) => {
+    let total = 0, visible = 0;
+    selectors.forEach(sel => {
+      try { document.querySelectorAll(sel).forEach(el => { total++; if (isVisible(el)) visible++; }); }
+      catch (e) { /* invalid selector */ }
+    });
+    if (total > 0) {
+      counts.repeatedItems.byType[name] = { total, visible, hidden: total - visible };
+      counts.repeatedItems.total += total;
+    }
+  });
+
+  // 4. Navigation
+  const hdr = document.querySelector('header, [class*="header"], nav');
+  const ftr = document.querySelector('footer, [class*="footer"]');
+  if (hdr) counts.navigation.headerLinks = hdr.querySelectorAll('a').length;
+  if (ftr) counts.navigation.footerLinks = ftr.querySelectorAll('a').length;
+  counts.navigation.allLinks = document.querySelectorAll('a').length;
+
+  // 5. Media & interactive
+  counts.media.images = document.querySelectorAll('img, picture').length;
+  counts.media.videos = document.querySelectorAll('video, iframe[src*="youtube"], iframe[src*="vimeo"]').length;
+  counts.media.svgIcons = document.querySelectorAll('svg').length;
+  counts.interactive.buttons = document.querySelectorAll('button, [role="button"], input[type="submit"], input[type="button"]').length;
+  counts.interactive.inputs = document.querySelectorAll('input, textarea, select').length;
+  counts.interactive.forms = document.querySelectorAll('form').length;
+
+  // 6. Summary
+  counts.summary = {
+    majorSections: counts.sections.total, gridContainers: counts.grids.total,
+    totalRepeatedItems: counts.repeatedItems.total, totalLinks: counts.navigation.allLinks,
+    totalImages: counts.media.images, totalButtons: counts.interactive.buttons,
+    recommendedItemCounts: {}
+  };
+  counts.grids.details.forEach(g => { if (g.visibleItems >= 3) counts.summary.recommendedItemCounts[g.selector] = g.visibleItems; });
+  Object.entries(counts.repeatedItems.byType).forEach(([t, d]) => { if (d.visible >= 2) counts.summary.recommendedItemCounts[t] = d.visible; });
+
+  return counts;
+}