design-clone 2.1.0 → 3.0.0

package/src/core/dimension/dimension-extractor.js

@@ -0,0 +1,317 @@
+/**
+ * Component Dimension Extractor
+ *
+ * Extract exact pixel dimensions from page elements using
+ * getBoundingClientRect and getComputedStyle.
+ *
+ * Split into two page.evaluate passes:
+ *  1. Containers, typography, buttons, images  (this file)
+ *  2. Card patterns + grid layouts             (second evaluate using card-detector helpers)
+ *
+ * Card/grid helper sources live in dimension-extractor-card-detector.js.
+ */
+
+import { calculateSimilarity, detectLayoutType, calculateGap } from './dimension-extractor-card-detector.js';
+
+// Section detection thresholds (passed into browser context)
+const HERO_THRESHOLD = 0.25;
+const FOOTER_THRESHOLD = 0.85;
+const SIDEBAR_MAX_WIDTH = 400;
+const MAX_BUTTONS = 10;
+const MAX_IMAGES = 15;
+
+/**
+ * Extract component dimensions from page.
+ * @param {import('playwright').Page} page
+ * @param {string} viewportName - 'desktop' | 'tablet' | 'mobile'
+ * @returns {Promise<Object>}
+ */
+export async function extractComponentDimensions(page, viewportName) {
+  const thresholds = { HERO_THRESHOLD, FOOTER_THRESHOLD, SIDEBAR_MAX_WIDTH, MAX_BUTTONS, MAX_IMAGES };
+
+  // Pass 1: containers, typography, buttons, images
+  const results = await page.evaluate(({ vpName, th }) => {
+    const data = {
+      viewport: vpName,
+      extractedAt: new Date().toISOString(),
+      containers: [], cards: [], typography: [], buttons: [], images: []
+    };
+
+    // --- Shared helpers (browser context) ---
+
+    function extractDimensions(el) {
+      const r = el.getBoundingClientRect(), cs = window.getComputedStyle(el);
+      const pf = v => parseFloat(v) || 0;
+      return {
+        width: Math.round(r.width), height: Math.round(r.height),
+        x: Math.round(r.x), y: Math.round(r.y),
+        absoluteX: Math.round(r.x + window.scrollX), absoluteY: Math.round(r.y + window.scrollY),
+        paddingTop: pf(cs.paddingTop), paddingRight: pf(cs.paddingRight),
+        paddingBottom: pf(cs.paddingBottom), paddingLeft: pf(cs.paddingLeft),
+        marginTop: pf(cs.marginTop), marginRight: pf(cs.marginRight),
+        marginBottom: pf(cs.marginBottom), marginLeft: pf(cs.marginLeft),
+        display: cs.display, position: cs.position,
+        flexDirection: cs.flexDirection !== 'row' ? cs.flexDirection : undefined,
+        justifyContent: cs.justifyContent !== 'normal' ? cs.justifyContent : undefined,
+        alignItems: cs.alignItems !== 'normal' ? cs.alignItems : undefined,
+        gap: pf(cs.gap),
+        gridTemplateColumns: cs.gridTemplateColumns !== 'none' ? cs.gridTemplateColumns : undefined,
+        gridTemplateRows: cs.gridTemplateRows !== 'none' ? cs.gridTemplateRows : undefined,
+        backgroundColor: cs.backgroundColor !== 'rgba(0, 0, 0, 0)' ? cs.backgroundColor : undefined,
+        borderRadius: cs.borderRadius !== '0px' ? cs.borderRadius : undefined,
+        boxShadow: cs.boxShadow !== 'none' ? cs.boxShadow : undefined,
+        fontSize: pf(cs.fontSize), fontWeight: cs.fontWeight, lineHeight: cs.lineHeight,
+        letterSpacing: cs.letterSpacing !== 'normal' ? cs.letterSpacing : undefined,
+        color: cs.color
+      };
+    }
+
+    function cleanObject(obj) {
+      return Object.fromEntries(
+        Object.entries(obj).filter(([_, v]) => v !== undefined && v !== null && v !== 0 && v !== '')
+      );
+    }
+
+    const pageHeight = Math.max(document.body.scrollHeight, document.documentElement.scrollHeight);
+
+    function detectSection(el) {
+      const r = el.getBoundingClientRect(), cs = window.getComputedStyle(el);
+      const tag = el.tagName.toLowerCase(), yr = (r.y + window.scrollY) / pageHeight;
+      if (tag === 'header' || el.closest('header')) return 'header';
+      if (tag === 'footer' || el.closest('footer')) return 'footer';
+      if (tag === 'aside'  || el.closest('aside'))  return 'sidebar';
+      if (tag === 'nav'    || el.closest('nav'))     return 'nav';
+      if (yr < th.HERO_THRESHOLD && r.height > 300) return 'hero';
+      if (yr > th.FOOTER_THRESHOLD) return 'footer';
+      if ((cs.position === 'fixed' || cs.position === 'sticky') && r.width < th.SIDEBAR_MAX_WIDTH) return 'sidebar';
+      return 'content';
+    }
+
+    // --- Extraction functions ---
+
+    function extractContainers() {
+      const selectors = [
+        'section','main','article','header','footer',
+        '[role="main"]','[role="region"]',
+        'div[class*="container"]','div[class*="wrapper"]',
+        'div[class*="section"]','div[class*="content"]',
+        'div[class*="grid"]','div[class*="card"]'
+      ];
+      const seen = new Set();
+      selectors.forEach(sel => {
+        try {
+          document.querySelectorAll(sel).forEach(el => {
+            if (seen.has(el)) return;
+            const rect = el.getBoundingClientRect();
+            if (rect.width < 100 || rect.height < 50) return;
+            const children = Array.from(el.children).filter(c => {
+              const cr = c.getBoundingClientRect(); return cr.width > 50 && cr.height > 30;
+            });
+            if (children.length < 2) return;
+            seen.add(el);
+            const dims = extractDimensions(el);
+            dims.selector = el.className
+              ? `.${el.className.split(' ').filter(c => c && !c.includes(':')).slice(0, 2).join('.')}`
+              : el.tagName.toLowerCase();
+            dims.childCount = children.length;
+            dims.section    = detectSection(el);
+            if (children.length >= 2 && (dims.display === 'flex' || dims.display === 'grid')) {
+              const fr = children[0].getBoundingClientRect();
+              const sr = children[1].getBoundingClientRect();
+              const g  = Math.round(dims.flexDirection === 'column' ? sr.top - fr.bottom : sr.left - fr.right);
+              if (g > 0 && g < 200) dims.calculatedGap = g;
+            }
+            data.containers.push(cleanObject(dims));
+          });
+        } catch (e) { /* ignore */ }
+      });
+    }
+
+    function extractTypography() {
+      ['h1','h2','h3','h4','h5','h6','p'].forEach(tag => {
+        try {
+          const els = document.querySelectorAll(tag);
+          if (!els.length) return;
+          const bySection = {};
+          for (const el of els) {
+            const rect = el.getBoundingClientRect();
+            if (rect.width < 50 || rect.height < 10) continue;
+            const section = detectSection(el);
+            const dims    = extractDimensions(el);
+            if (!bySection[section]) bySection[section] = [];
+            if (bySection[section].length < 2) {
+              bySection[section].push({
+                selector: tag, section, fontSize: dims.fontSize, fontWeight: dims.fontWeight,
+                lineHeight: dims.lineHeight, letterSpacing: dims.letterSpacing,
+                color: dims.color, marginTop: dims.marginTop, marginBottom: dims.marginBottom,
+                textSample: el.textContent?.trim().slice(0, 40),
+                y: Math.round(rect.y + window.scrollY)
+              });
+            }
+          }
+          for (const items of Object.values(bySection)) data.typography.push(...items);
+        } catch (e) { /* ignore */ }
+      });
+      data.typography.sort((a, b) => a.y - b.y);
+    }
+
+    function extractButtons() {
+      const seen = new Set();
+      ['button','a[class*="btn"]','a[class*="button"]','[role="button"]','input[type="submit"]'].forEach(sel => {
+        try {
+          document.querySelectorAll(sel).forEach(el => {
+            if (seen.has(el) || data.buttons.length >= th.MAX_BUTTONS) return;
+            const rect = el.getBoundingClientRect();
+            if (rect.width < 40 || rect.height < 20) return;
+            seen.add(el);
+            const dims = extractDimensions(el);
+            data.buttons.push({
+              width: dims.width, height: dims.height,
+              paddingTop: dims.paddingTop, paddingRight: dims.paddingRight,
+              paddingBottom: dims.paddingBottom, paddingLeft: dims.paddingLeft,
+              fontSize: dims.fontSize, fontWeight: dims.fontWeight,
+              borderRadius: dims.borderRadius, backgroundColor: dims.backgroundColor,
+              color: dims.color, text: el.textContent?.trim().slice(0, 30)
+            });
+          });
+        } catch (e) { /* ignore */ }
+      });
+    }
+
+    function extractImages() {
+      try {
+        document.querySelectorAll('img').forEach(el => {
+          if (data.images.length >= th.MAX_IMAGES) return;
+          const rect = el.getBoundingClientRect();
+          if (rect.width < 80 || rect.height < 80) return;
+          data.images.push({
+            width: Math.round(rect.width), height: Math.round(rect.height),
+            aspectRatio: (rect.width / rect.height).toFixed(2),
+            x: Math.round(rect.x), y: Math.round(rect.y + window.scrollY)
+          });
+        });
+      } catch (e) { /* ignore */ }
+    }
+
+    extractContainers();
+    extractTypography();
+    extractButtons();
+    extractImages();
+    return data;
+  }, { vpName: viewportName, th: thresholds });
+
+  // Pass 2: card patterns + grid layouts (using serialized helpers)
+  const helpers = {
+    calculateSimilarity: calculateSimilarity.toString(),
+    detectLayoutType:    detectLayoutType.toString(),
+    calculateGap:        calculateGap.toString()
+  };
+
+  const { cards, gridLayouts } = await page.evaluate(({ containers, helpers }) => {
+    // eslint-disable-next-line no-new-func
+    const calculateSimilarity = new Function('return (' + helpers.calculateSimilarity + ')')();
+    // eslint-disable-next-line no-new-func
+    const detectLayoutType    = new Function('return (' + helpers.detectLayoutType + ')')();
+    // eslint-disable-next-line no-new-func
+    const calculateGap        = new Function('return (' + helpers.calculateGap + ')')();
+
+    const cards = [], gridLayouts = [];
+    let cardGroupId = 0;
+
+    containers.forEach(container => {
+      // Card patterns
+      if (container.childCount >= 2) {
+        try {
+          const parent = document.querySelector(container.selector);
+          if (!parent) return;
+          const children = Array.from(parent.children).filter(c => {
+            const cr = c.getBoundingClientRect(); return cr.width > 80 && cr.height > 60;
+          });
+          if (children.length < 2) return;
+
+          const childDims = children.map(c => {
+            const cr = c.getBoundingClientRect(), cs = window.getComputedStyle(c);
+            return {
+              width: Math.round(cr.width), height: Math.round(cr.height),
+              x: Math.round(cr.x), y: Math.round(cr.y),
+              paddingTop: parseFloat(cs.paddingTop) || 0,
+              paddingRight: parseFloat(cs.paddingRight) || 0,
+              paddingBottom: parseFloat(cs.paddingBottom) || 0,
+              paddingLeft: parseFloat(cs.paddingLeft) || 0,
+              marginTop: parseFloat(cs.marginTop) || 0,
+              marginBottom: parseFloat(cs.marginBottom) || 0,
+              borderRadius: cs.borderRadius,
+              boxShadow: cs.boxShadow !== 'none' ? cs.boxShadow : undefined,
+              backgroundColor: cs.backgroundColor !== 'rgba(0, 0, 0, 0)' ? cs.backgroundColor : undefined
+            };
+          });
+
+          const used = new Set(), groups = [];
+          for (let i = 0; i < childDims.length; i++) {
+            if (used.has(i)) continue;
+            const group = [childDims[i]]; used.add(i);
+            for (let j = i + 1; j < childDims.length; j++) {
+              if (!used.has(j) && calculateSimilarity(childDims[i], childDims[j]) >= 0.70) {
+                group.push(childDims[j]); used.add(j);
+              }
+            }
+            if (group.length >= 2) groups.push(group);
+          }
+
+          groups.forEach(group => {
+            const avg    = (arr, key) => Math.round(arr.reduce((s, el) => s + (el[key] || 0), 0) / arr.length);
+            const layout = detectLayoutType(group);
+            cards.push({
+              id: `card-group-${++cardGroupId}`, parentSelector: container.selector,
+              count: group.length, layout, gap: calculateGap(group, layout),
+              avgDimensions: {
+                width: avg(group, 'width'), height: avg(group, 'height'),
+                paddingTop: avg(group, 'paddingTop'), paddingRight: avg(group, 'paddingRight'),
+                paddingBottom: avg(group, 'paddingBottom'), paddingLeft: avg(group, 'paddingLeft')
+              },
+              borderRadius: group[0].borderRadius !== '0px' ? group[0].borderRadius : undefined,
+              boxShadow: group[0].boxShadow, backgroundColor: group[0].backgroundColor
+            });
+          });
+        } catch (e) { /* ignore */ }
+      }
+
+      // Grid layouts
+      if (container.display === 'grid' || container.display === 'flex') {
+        try {
+          const parent = document.querySelector(container.selector);
+          if (!parent) return;
+          const cs = window.getComputedStyle(parent);
+          if (parent.children.length < 2) return;
+
+          if (cs.display === 'grid') {
+            const cols    = cs.gridTemplateColumns;
+            const colCount = cols && cols !== 'none'
+              ? cols.split(' ').filter(c => c && c !== 'none').length
+              : Math.ceil(parent.children.length / 2);
+            gridLayouts.push({
+              selector: container.selector, display: 'grid',
+              columns: colCount, rows: Math.ceil(parent.children.length / colCount),
+              columnGap: parseFloat(cs.columnGap) || parseFloat(cs.gap) || 0,
+              rowGap: parseFloat(cs.rowGap) || parseFloat(cs.gap) || 0,
+              childCount: parent.children.length
+            });
+          } else if (cs.display === 'flex') {
+            gridLayouts.push({
+              selector: container.selector, display: 'flex',
+              flexDirection: cs.flexDirection, flexWrap: cs.flexWrap,
+              gap: parseFloat(cs.gap) || container.calculatedGap || 0,
+              childCount: parent.children.length
+            });
+          }
+        } catch (e) { /* ignore */ }
+      }
+    });
+
+    return { cards, gridLayouts };
+  }, { containers: results.containers, helpers });
+
+  results.cards       = cards;
+  results.gridLayouts = gridLayouts;
+  return results;
+}

package/src/core/dimension/dimension-output-ai-summary.js

@@ -0,0 +1,111 @@
+/**
+ * AI Summary Generator for Dimension Output
+ *
+ * Generates a compact (<5KB) AI-friendly summary from full component-dimensions.json.
+ * Includes section-aware typography, exact measurements, and responsive breakpoints.
+ */
+
+/**
+ * Infer section padding from container data.
+ * @param {Array} containers
+ * @returns {string} e.g. "64px 0"
+ */
+function inferSectionPadding(containers) {
+  if (!containers || containers.length === 0) return '64px 0';
+  const paddings = containers.slice(0, 5).map(c => ({
+    v: c.paddingTop || c.paddingBottom || 64,
+    h: c.paddingLeft || c.paddingRight || 0
+  }));
+  const avgV = Math.round(paddings.reduce((s, p) => s + p.v, 0) / paddings.length);
+  const avgH = Math.round(paddings.reduce((s, p) => s + p.h, 0) / paddings.length);
+  return `${avgV}px ${avgH}px`;
+}
+
+/**
+ * Infer card dimensions from card pattern data.
+ * @param {Array} cards
+ * @returns {{ width: string, height: string, padding: string }}
+ */
+function inferCardDimensions(cards) {
+  if (!cards || cards.length === 0) {
+    return { width: 'auto', height: 'auto', padding: '24px' };
+  }
+  const first = cards[0].avgDimensions || cards[0];
+  return {
+    width:   first.width  ? first.width + 'px'  : 'auto',
+    height:  first.height > 0 ? first.height + 'px' : 'auto',
+    padding: (first.paddingTop || first.padding || 24) + 'px'
+  };
+}
+
+/**
+ * Convert typographyBySection to AI-friendly format with px units.
+ * Uses desktop size first, then tablet, then mobile.
+ * @param {Object} typographyBySection
+ * @returns {Object}
+ */
+function inferTypographyBySection(typographyBySection) {
+  const result = {};
+  for (const [section, tags] of Object.entries(typographyBySection || {})) {
+    if (!tags || Object.keys(tags).length === 0) continue;
+    result[section] = {};
+    for (const [tag, sizes] of Object.entries(tags)) {
+      const size = sizes.desktop || sizes.tablet || sizes.mobile || 0;
+      if (size > 0) result[section][tag] = size + 'px';
+    }
+    if (Object.keys(result[section]).length === 0) delete result[section];
+  }
+  return result;
+}
+
+/**
+ * Generate AI-friendly summary (compact, <5KB).
+ * Includes section-aware typography for accurate reconstruction.
+ * @param {Object} fullOutput - Full component-dimensions.json
+ * @returns {Object} Compact summary for AI prompts
+ */
+export function generateAISummary(fullOutput) {
+  const { viewports, summary } = fullOutput;
+  const desktop = viewports.desktop || {};
+
+  return {
+    _comment: 'USE THESE EXACT VALUES - DO NOT ESTIMATE',
+    EXACT_DIMENSIONS: {
+      container_max_width: summary.maxContainerWidth + 'px',
+      section_padding:     inferSectionPadding(desktop.containers),
+      card_dimensions:     inferCardDimensions(desktop.cards),
+      gap:                 summary.commonGap + 'px'
+    },
+    EXACT_TYPOGRAPHY: {
+      h1:   (summary.typography.h1.desktop   || 48) + 'px',
+      h2:   (summary.typography.h2.desktop   || 36) + 'px',
+      h3:   (summary.typography.h3.desktop   || 24) + 'px',
+      body: (summary.typography.body.desktop || 16) + 'px'
+    },
+    TYPOGRAPHY_BY_SECTION: inferTypographyBySection(summary.typographyBySection),
+    SECTIONS: {
+      hero:    summary.sections?.hero    || { found: false },
+      content: summary.sections?.content || { found: false },
+      header:  summary.sections?.header  || { found: false },
+      footer:  summary.sections?.footer  || { found: false },
+      sidebar: summary.sections?.sidebar || { found: false }
+    },
+    RESPONSIVE: {
+      desktop_breakpoint: summary.breakpoints.desktop + 'px',
+      tablet_breakpoint:  summary.breakpoints.tablet  + 'px',
+      mobile_breakpoint:  summary.breakpoints.mobile  + 'px',
+      typography_scaling: {
+        h1: {
+          desktop: (summary.typography.h1.desktop || 48) + 'px',
+          tablet:  (summary.typography.h1.tablet  || 36) + 'px',
+          mobile:  (summary.typography.h1.mobile  || 28) + 'px'
+        },
+        h2: {
+          desktop: (summary.typography.h2.desktop || 36) + 'px',
+          tablet:  (summary.typography.h2.tablet  || 28) + 'px',
+          mobile:  (summary.typography.h2.mobile  || 24) + 'px'
+        }
+      }
+    }
+  };
+}

package/src/core/dimension/dimension-output.js

@@ -0,0 +1,173 @@
+/**
+ * Dimension Output Builder
+ *
+ * Build and format component dimension output for JSON files.
+ * Includes sanitization, cross-viewport summary, and AI-friendly format.
+ * AI summary generation lives in dimension-output-ai-summary.js.
+ */
+
+import { VIEWPORTS } from '../../shared/viewports.js';
+export { generateAISummary } from './dimension-output-ai-summary.js';
+
+/**
+ * Build final component-dimensions.json output with proper schema.
+ * @param {Object} allViewportDimensions - Dimensions from all viewports
+ * @param {string} url - Source URL
+ * @returns {Object} Final JSON structure
+ */
+export function buildDimensionsOutput(allViewportDimensions, url) {
+  const output = {
+    meta: {
+      version: '1.0',
+      extractedAt: new Date().toISOString(),
+      url,
+      tool: 'design-clone/screenshot.js'
+    },
+    viewports: {},
+    summary: {}
+  };
+
+  for (const [vpName, vpData] of Object.entries(allViewportDimensions)) {
+    output.viewports[vpName] = sanitizeViewportData(vpData, vpName);
+  }
+
+  output.summary = buildCrossViewportSummary(output.viewports);
+  return output;
+}
+
+/**
+ * Sanitize viewport data for JSON output.
+ * Rounds numbers, truncates long strings, and limits array sizes.
+ * @param {Object} data - Raw viewport dimension data
+ * @param {string} vpName - Viewport name key
+ * @returns {Object}
+ */
+export function sanitizeViewportData(data, vpName) {
+  if (!data) return {};
+
+  const clean  = JSON.parse(JSON.stringify(data));
+  clean.width  = VIEWPORTS[vpName]?.width  || 0;
+  clean.height = VIEWPORTS[vpName]?.height || 0;
+
+  function roundNumbers(obj) {
+    for (const key in obj) {
+      if (typeof obj[key] === 'number') {
+        obj[key] = Math.round(obj[key]);
+      } else if (Array.isArray(obj[key])) {
+        obj[key].forEach(item => roundNumbers(item));
+      } else if (typeof obj[key] === 'object' && obj[key] !== null) {
+        roundNumbers(obj[key]);
+      }
+    }
+    return obj;
+  }
+
+  function truncateStrings(obj, maxLen = 80) {
+    for (const key in obj) {
+      if (typeof obj[key] === 'string' && obj[key].length > maxLen) {
+        obj[key] = obj[key].slice(0, maxLen) + '...';
+      } else if (Array.isArray(obj[key])) {
+        obj[key].forEach(item => truncateStrings(item, maxLen));
+      } else if (typeof obj[key] === 'object' && obj[key] !== null) {
+        truncateStrings(obj[key], maxLen);
+      }
+    }
+    return obj;
+  }
+
+  // Limit array sizes for token efficiency
+  if (clean.containers && clean.containers.length > 15) clean.containers = clean.containers.slice(0, 15);
+  if (clean.images     && clean.images.length     > 10) clean.images     = clean.images.slice(0, 10);
+  if (clean.buttons    && clean.buttons.length     > 10) clean.buttons    = clean.buttons.slice(0, 10);
+
+  return truncateStrings(roundNumbers(clean));
+}
+
+/**
+ * Build cross-viewport summary for AI consumption.
+ * Includes section-aware typography and container data.
+ * @param {Object} viewports - Viewport data keyed by name (desktop, tablet, mobile)
+ * @returns {Object} Summary
+ */
+export function buildCrossViewportSummary(viewports) {
+  const summary = {
+    maxContainerWidth: 0,
+    commonGap: 0,
+    breakpoints: {
+      desktop: VIEWPORTS.desktop.width,
+      tablet:  VIEWPORTS.tablet.width,
+      mobile:  VIEWPORTS.mobile.width
+    },
+    typography: { h1: {}, h2: {}, h3: {}, body: {} },
+    typographyBySection: { hero: {}, content: {}, header: {}, footer: {}, sidebar: {} },
+    cardPatterns: { totalGroups: 0, avgCardSize: null },
+    sections: {
+      hero:    { found: false, containerWidth: null },
+      content: { found: false, containerWidth: null },
+      header:  { found: false, containerWidth: null },
+      footer:  { found: false, containerWidth: null },
+      sidebar: { found: false, width: null }
+    }
+  };
+
+  for (const [vpName, vpData] of Object.entries(viewports)) {
+    if (!vpData) continue;
+
+    // Container section mapping
+    if (vpData.containers) {
+      for (const container of vpData.containers) {
+        if (container.width > summary.maxContainerWidth) {
+          summary.maxContainerWidth = container.width;
+        }
+        const section = container.section || 'content';
+        if (summary.sections[section]) {
+          summary.sections[section].found = true;
+          if (section === 'sidebar') {
+            if (!summary.sections[section].width || container.width > summary.sections[section].width) {
+              summary.sections[section].width = container.width;
+            }
+          } else {
+            if (!summary.sections[section].containerWidth || container.width > summary.sections[section].containerWidth) {
+              summary.sections[section].containerWidth = container.width;
+            }
+          }
+        }
+      }
+    }
+
+    // Typography by section
+    if (vpData.typography) {
+      for (const typo of vpData.typography) {
+        const tag     = typo.selector?.toLowerCase();
+        const section = typo.section || 'content';
+
+        // Flat typography (backward compat)
+        if (tag === 'h1' && !summary.typography.h1[vpName])   summary.typography.h1[vpName]   = typo.fontSize;
+        if (tag === 'h2' && !summary.typography.h2[vpName])   summary.typography.h2[vpName]   = typo.fontSize;
+        if (tag === 'h3' && !summary.typography.h3[vpName])   summary.typography.h3[vpName]   = typo.fontSize;
+        if (tag === 'p'  && !summary.typography.body[vpName]) summary.typography.body[vpName] = typo.fontSize;
+
+        // Section-aware typography
+        if (!summary.typographyBySection[section]) summary.typographyBySection[section] = {};
+        if (!summary.typographyBySection[section][tag]) summary.typographyBySection[section][tag] = {};
+        if (!summary.typographyBySection[section][tag][vpName]) {
+          summary.typographyBySection[section][tag][vpName] = typo.fontSize;
+        }
+      }
+    }
+
+    // Card patterns
+    if (vpData.cards && vpData.cards.length > 0) {
+      summary.cardPatterns.totalGroups += vpData.cards.length;
+      if (vpName === 'desktop' && vpData.cards[0]?.avgDimensions) {
+        summary.cardPatterns.avgCardSize = vpData.cards[0].avgDimensions;
+      }
+      const gaps = vpData.cards.map(g => g.gap).filter(g => g > 0);
+      if (gaps.length > 0) {
+        summary.commonGap = Math.round(gaps.reduce((a, b) => a + b, 0) / gaps.length);
+      }
+    }
+  }
+
+  return summary;
+}

package/src/core/dimension/dom-tree-analyzer-tree-builders.js

@@ -0,0 +1,95 @@
+/**
+ * DOM Tree Post-Processors
+ *
+ * Node-side functions that operate on the traversed DOM tree result
+ * returned from page.evaluate. Builds the landmarks map and heading
+ * tree from the raw root node structure.
+ */
+
+/**
+ * Build a landmarks map from the traversed DOM tree.
+ * @param {Object} root - Root node from traverseDOM
+ * @returns {{ header, main, footer, nav: Array, aside: Array }}
+ */
+export function buildLandmarksMap(root) {
+  const landmarks = {
+    header: null,
+    main: null,
+    footer: null,
+    nav: [],
+    aside: []
+  };
+
+  function walk(node) {
+    if (!node) return;
+    switch (node.role) {
+      case 'header-landmark': landmarks.header = node; break;
+      case 'main':            landmarks.main   = node; break;
+      case 'footer-landmark': landmarks.footer = node; break;
+      case 'nav':             landmarks.nav.push(node); break;
+      case 'aside':           landmarks.aside.push(node); break;
+    }
+    node.children.forEach(walk);
+  }
+
+  walk(root);
+  return landmarks;
+}
+
+/**
+ * Build a heading tree with section context and position, sorted by Y.
+ * Text and fontSize are filled separately (see extractHeadingData).
+ * @param {Object} root - Root node from traverseDOM
+ * @returns {Array<{ level, section, nodeId, y, fontSize, text }>}
+ */
+export function buildHeadingTree(root) {
+  const headings = [];
+
+  function walk(node, sectionContext) {
+    if (!node) return;
+
+    let ctx = sectionContext;
+    if (node.role === 'header-landmark') ctx = 'header';
+    else if (node.role === 'main')        ctx = 'content';
+    else if (node.role === 'footer-landmark') ctx = 'footer';
+    else if (node.role === 'aside')       ctx = 'sidebar';
+    else if (node.role === 'hero')        ctx = 'hero';
+    if (!ctx) ctx = node.section || 'content';
+
+    if (node.role?.startsWith('heading-')) {
+      headings.push({
+        level:    parseInt(node.role.slice(-1)),
+        section:  ctx,
+        nodeId:   node.id,
+        y:        node.dimensions.y,
+        fontSize: null,
+        text:     null
+      });
+    }
+
+    node.children.forEach(c => walk(c, ctx));
+  }
+
+  walk(root, null);
+  return headings.sort((a, b) => a.y - b.y);
+}
+
+/**
+ * Count total nodes and max depth in the traversed tree.
+ * @param {Object} root - Root node
+ * @returns {{ totalNodes: number, maxDepth: number }}
+ */
+export function countTreeStats(root) {
+  let totalNodes = 0;
+  let maxActualDepth = 0;
+
+  function count(n) {
+    if (!n) return;
+    totalNodes++;
+    maxActualDepth = Math.max(maxActualDepth, n.depth);
+    n.children.forEach(count);
+  }
+
+  count(root);
+  return { totalNodes, maxDepth: maxActualDepth };
+}