design-clone 1.2.0 → 2.1.0

package/src/core/semantic-enhancer.js

@@ -0,0 +1,492 @@
+/**
+ * Semantic HTML Enhancer
+ *
+ * Injects WordPress-compatible semantic IDs, classes, and ARIA roles
+ * into extracted HTML while preserving original styling.
+ *
+ * Key features:
+ * - Detects sections via semantic tags, ARIA roles, class patterns
+ * - Adds IDs only if none exist
+ * - Appends classes (never replaces)
+ * - Sets roles only if not present
+ * - Handles multiple navs with aria-labels
+ */
+
+/**
+ * WordPress-compatible semantic mappings
+ */
+export const SEMANTIC_MAPPINGS = {
+  header: {
+    id: 'site-header',
+    classes: ['site-header'],
+    role: 'banner'
+  },
+  nav: {
+    id: 'site-navigation',
+    classes: ['main-navigation', 'nav-menu'],
+    role: 'navigation'
+  },
+  main: {
+    id: 'main-content',
+    classes: ['site-main', 'content-area'],
+    role: 'main'
+  },
+  sidebar: {
+    id: 'primary-sidebar',
+    classes: ['widget-area', 'sidebar'],
+    role: 'complementary'
+  },
+  footer: {
+    id: 'site-footer',
+    classes: ['site-footer'],
+    role: 'contentinfo'
+  },
+  hero: {
+    id: 'hero-section',
+    classes: ['hero'],
+    role: null  // No ARIA landmark role for hero
+  }
+};
+
+/**
+ * Class patterns for section detection (case-insensitive)
+ */
+const CLASS_PATTERNS = {
+  header: ['header', 'masthead', 'site-header', 'page-header'],
+  nav: ['nav', 'menu', 'navigation'],
+  main: ['main', 'content', 'page-content'],
+  sidebar: ['sidebar', 'aside', 'widget-area'],
+  footer: ['footer', 'site-footer', 'page-footer'],
+  hero: ['hero', 'banner', 'jumbotron', 'splash']
+};
+
+/**
+ * Detect section type from element
+ *
+ * Priority:
+ * 1. Semantic HTML tags
+ * 2. ARIA role attributes
+ * 3. Class pattern matching
+ *
+ * @param {Element} element - DOM element to analyze
+ * @returns {string|null} Section type or null
+ */
+export function detectSectionType(element) {
+  const tag = element.tagName?.toLowerCase();
+  const ariaRole = element.getAttribute?.('role');
+
+  // Priority 1: Semantic HTML tags
+  if (tag === 'header') return 'header';
+  if (tag === 'nav') return 'nav';
+  if (tag === 'main') return 'main';
+  if (tag === 'aside') return 'sidebar';
+  if (tag === 'footer') return 'footer';
+
+  // Priority 2: ARIA roles
+  if (ariaRole === 'banner') return 'header';
+  if (ariaRole === 'navigation') return 'nav';
+  if (ariaRole === 'main') return 'main';
+  if (ariaRole === 'complementary') return 'sidebar';
+  if (ariaRole === 'contentinfo') return 'footer';
+
+  // Priority 3: Class patterns
+  const className = (element.className || '').toString().toLowerCase();
+  if (!className) return null;
+
+  for (const [sectionType, patterns] of Object.entries(CLASS_PATTERNS)) {
+    if (patterns.some(pattern => className.includes(pattern))) {
+      // Avoid false positives: ensure it's a container element
+      if (tag === 'div' || tag === 'section' || tag === 'article') {
+        return sectionType;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Apply semantic attributes to element
+ *
+ * Rules:
+ * - Add ID only if none exists
+ * - Append classes (preserve existing)
+ * - Set role only if none exists
+ *
+ * @param {Element} element - DOM element to enhance
+ * @param {string} sectionType - Type from SEMANTIC_MAPPINGS
+ * @param {Object} options - Configuration options
+ * @param {Set} options.usedIds - Track used IDs to avoid duplicates
+ * @param {number} options.navIndex - Index for multiple nav labeling
+ */
+export function applySemanticAttributes(element, sectionType, options = {}) {
+  const mapping = SEMANTIC_MAPPINGS[sectionType];
+  if (!mapping) return;
+
+  const { usedIds = new Set(), navIndex = 0 } = options;
+
+  // Add ID only if not present and not already used
+  if (!element.id && mapping.id) {
+    let targetId = mapping.id;
+
+    // Handle multiple instances (e.g., footer-navigation for secondary nav)
+    if (usedIds.has(targetId)) {
+      targetId = `${mapping.id}-${navIndex + 1}`;
+    }
+
+    if (!usedIds.has(targetId)) {
+      element.id = targetId;
+      usedIds.add(targetId);
+    }
+  }
+
+  // Append classes (preserve existing)
+  if (mapping.classes && mapping.classes.length > 0) {
+    const existingClasses = element.className
+      ? element.className.toString().split(/\s+/).filter(Boolean)
+      : [];
+    const newClasses = mapping.classes.filter(c => !existingClasses.includes(c));
+
+    if (newClasses.length > 0) {
+      element.className = [...existingClasses, ...newClasses].join(' ').trim();
+    }
+  }
+
+  // Set role only if not present
+  if (mapping.role && !element.getAttribute('role')) {
+    element.setAttribute('role', mapping.role);
+  }
+}
+
+/**
+ * Handle multiple navigation elements with proper labeling
+ *
+ * @param {NodeList|Array} navElements - All nav elements
+ * @param {Set} usedIds - Track used IDs
+ */
+export function handleMultipleNavs(navElements, usedIds = new Set()) {
+  const navs = Array.from(navElements);
+  if (navs.length === 0) return;
+
+  navs.forEach((nav, index) => {
+    const isInHeader = nav.closest?.('header') !== null;
+    const isInFooter = nav.closest?.('footer') !== null;
+
+    if (isInHeader && index === 0) {
+      // Primary navigation in header
+      applySemanticAttributes(nav, 'nav', { usedIds, navIndex: 0 });
+      if (!nav.getAttribute('aria-label')) {
+        nav.setAttribute('aria-label', 'Primary Menu');
+      }
+    } else if (isInFooter) {
+      // Footer navigation
+      if (!nav.id) {
+        nav.id = usedIds.has('footer-navigation')
+          ? `footer-navigation-${index}`
+          : 'footer-navigation';
+        usedIds.add(nav.id);
+      }
+      nav.setAttribute('role', 'navigation');
+      if (!nav.getAttribute('aria-label')) {
+        nav.setAttribute('aria-label', 'Footer Menu');
+      }
+    } else {
+      // Secondary/other navigation
+      applySemanticAttributes(nav, 'nav', { usedIds, navIndex: index });
+      if (!nav.getAttribute('aria-label')) {
+        nav.setAttribute('aria-label', `Navigation ${index + 1}`);
+      }
+    }
+  });
+}
+
+/**
+ * Enhance HTML string with semantic attributes
+ *
+ * **IMPORTANT:** This function requires browser context (uses DOMParser).
+ * For Node.js/Playwright, use `enhanceSemanticHTMLInPage()` instead.
+ *
+ * @param {string} html - Original HTML string (must be valid HTML)
+ * @param {Object} [domHierarchy=null] - Optional DOM hierarchy from dom-tree-analyzer
+ * @returns {{html: string, stats: Object}} Enhanced HTML and stats
+ * @throws {Error} If html is empty or DOMParser is unavailable
+ *
+ * @example
+ * // In browser context:
+ * const result = enhanceSemanticHTML(htmlString);
+ * console.log(result.stats.sectionsEnhanced);
+ */
+export function enhanceSemanticHTML(html, domHierarchy = null) {
+  // Validate input
+  if (!html || typeof html !== 'string') {
+    throw new Error('enhanceSemanticHTML requires a valid HTML string');
+  }
+
+  // Check for browser context
+  if (typeof DOMParser === 'undefined') {
+    throw new Error('enhanceSemanticHTML requires browser context (DOMParser). Use enhanceSemanticHTMLInPage() for Playwright.');
+  }
+
+  const stats = {
+    sectionsEnhanced: 0,
+    idsAdded: 0,
+    classesAdded: 0,
+    rolesAdded: 0,
+    warnings: []
+  };
+
+  // Parse HTML
+  const parser = new DOMParser();
+  const doc = parser.parseFromString(html, 'text/html');
+
+  const usedIds = new Set();
+
+  // Collect existing IDs to avoid duplicates
+  doc.querySelectorAll('[id]').forEach(el => {
+    usedIds.add(el.id);
+  });
+
+  // Optimized: Combined landmark selector (reduces querySelectorAll calls from 8 to 1)
+  const combinedLandmarkSelector = [
+    'header:not(header header)',  // Top-level headers only
+    'footer:not(footer footer)',  // Top-level footers only
+    'main',
+    'aside',
+    '[role="banner"]',
+    '[role="contentinfo"]',
+    '[role="main"]',
+    '[role="complementary"]'
+  ].join(', ');
+
+  const processedElements = new Set();
+
+  try {
+    doc.querySelectorAll(combinedLandmarkSelector).forEach(el => {
+      // Skip if already processed (avoid double-counting from overlapping selectors)
+      if (processedElements.has(el)) return;
+      processedElements.add(el);
+
+      const sectionType = detectSectionType(el);
+      if (sectionType) {
+        const hadId = !!el.id;
+        const hadRole = !!el.getAttribute('role');
+        const oldClasses = el.className;
+
+        applySemanticAttributes(el, sectionType, { usedIds });
+
+        if (!hadId && el.id) stats.idsAdded++;
+        if (!hadRole && el.getAttribute('role')) stats.rolesAdded++;
+        if (oldClasses !== el.className) stats.classesAdded++;
+        stats.sectionsEnhanced++;
+      }
+    });
+  } catch (err) {
+    stats.warnings.push(`Landmark selector error: ${err.message}`);
+  }
+
+  // Handle nav elements specially (multiple navs need labeling)
+  // Count only navs not already processed
+  const navElements = doc.querySelectorAll('nav, [role="navigation"]');
+  let newNavCount = 0;
+  navElements.forEach(nav => {
+    if (!processedElements.has(nav)) {
+      processedElements.add(nav);
+      newNavCount++;
+    }
+  });
+  if (navElements.length > 0) {
+    handleMultipleNavs(navElements, usedIds);
+    stats.sectionsEnhanced += newNavCount;
+  }
+
+  // Detect hero sections via class patterns
+  const heroSelectors = [
+    '.hero', '.banner', '.jumbotron', '.splash',
+    '[class*="hero"]', '[class*="banner"]'
+  ];
+  heroSelectors.forEach(selector => {
+    try {
+      doc.querySelectorAll(selector).forEach(el => {
+        // Only top-level hero elements
+        if (!el.closest('header') && !el.closest('footer')) {
+          const hadId = !!el.id;
+          applySemanticAttributes(el, 'hero', { usedIds });
+          if (!hadId && el.id) stats.idsAdded++;
+          stats.sectionsEnhanced++;
+        }
+      });
+    } catch (err) {
+      // Some selectors may not be valid in all contexts
+    }
+  });
+
+  // Serialize back to HTML
+  const enhancedHtml = '<!DOCTYPE html>\n' + doc.documentElement.outerHTML;
+
+  return { html: enhancedHtml, stats };
+}
+
+/**
+ * Enhance HTML using page.evaluate (for Playwright integration)
+ *
+ * This is the recommended method for Node.js/Playwright usage.
+ *
+ * @param {import('playwright').Page} page - Playwright page
+ * @param {string} html - Original HTML string (must be valid HTML)
+ * @returns {Promise<{html: string, stats: Object}>}
+ * @throws {Error} If page is null or html is invalid
+ *
+ * @example
+ * const result = await enhanceSemanticHTMLInPage(page, extractedHtml);
+ * console.log(result.stats.sectionsEnhanced);
+ */
+export async function enhanceSemanticHTMLInPage(page, html) {
+  // Validate inputs
+  if (!page || typeof page.evaluate !== 'function') {
+    throw new Error('enhanceSemanticHTMLInPage requires a valid Playwright page');
+  }
+  if (!html || typeof html !== 'string') {
+    throw new Error('enhanceSemanticHTMLInPage requires a valid HTML string');
+  }
+
+  return await page.evaluate((htmlStr) => {
+    // Re-define functions inside evaluate context
+    const SEMANTIC_MAPPINGS = {
+      header: { id: 'site-header', classes: ['site-header'], role: 'banner' },
+      nav: { id: 'site-navigation', classes: ['main-navigation', 'nav-menu'], role: 'navigation' },
+      main: { id: 'main-content', classes: ['site-main', 'content-area'], role: 'main' },
+      sidebar: { id: 'primary-sidebar', classes: ['widget-area', 'sidebar'], role: 'complementary' },
+      footer: { id: 'site-footer', classes: ['site-footer'], role: 'contentinfo' },
+      hero: { id: 'hero-section', classes: ['hero'], role: null }
+    };
+
+    const CLASS_PATTERNS = {
+      header: ['header', 'masthead', 'site-header', 'page-header'],
+      nav: ['nav', 'menu', 'navigation'],
+      sidebar: ['sidebar', 'aside', 'widget-area'],
+      footer: ['footer', 'site-footer', 'page-footer'],
+      hero: ['hero', 'banner', 'jumbotron', 'splash']
+    };
+
+    function detectSectionType(element) {
+      const tag = element.tagName?.toLowerCase();
+      const ariaRole = element.getAttribute?.('role');
+
+      if (tag === 'header') return 'header';
+      if (tag === 'nav') return 'nav';
+      if (tag === 'main') return 'main';
+      if (tag === 'aside') return 'sidebar';
+      if (tag === 'footer') return 'footer';
+
+      if (ariaRole === 'banner') return 'header';
+      if (ariaRole === 'navigation') return 'nav';
+      if (ariaRole === 'main') return 'main';
+      if (ariaRole === 'complementary') return 'sidebar';
+      if (ariaRole === 'contentinfo') return 'footer';
+
+      const className = (element.className || '').toString().toLowerCase();
+      if (!className) return null;
+
+      for (const [sectionType, patterns] of Object.entries(CLASS_PATTERNS)) {
+        if (patterns.some(pattern => className.includes(pattern))) {
+          if (['div', 'section', 'article'].includes(tag)) {
+            return sectionType;
+          }
+        }
+      }
+
+      return null;
+    }
+
+    function applySemanticAttributes(element, sectionType, usedIds, navIndex = 0) {
+      const mapping = SEMANTIC_MAPPINGS[sectionType];
+      if (!mapping) return;
+
+      if (!element.id && mapping.id) {
+        let targetId = mapping.id;
+        if (usedIds.has(targetId)) {
+          targetId = `${mapping.id}-${navIndex + 1}`;
+        }
+        if (!usedIds.has(targetId)) {
+          element.id = targetId;
+          usedIds.add(targetId);
+        }
+      }
+
+      if (mapping.classes && mapping.classes.length > 0) {
+        const existingClasses = element.className
+          ? element.className.toString().split(/\s+/).filter(Boolean)
+          : [];
+        const newClasses = mapping.classes.filter(c => !existingClasses.includes(c));
+        if (newClasses.length > 0) {
+          element.className = [...existingClasses, ...newClasses].join(' ').trim();
+        }
+      }
+
+      if (mapping.role && !element.getAttribute('role')) {
+        element.setAttribute('role', mapping.role);
+      }
+    }
+
+    const stats = { sectionsEnhanced: 0, idsAdded: 0, classesAdded: 0, rolesAdded: 0, warnings: [] };
+
+    const parser = new DOMParser();
+    const doc = parser.parseFromString(htmlStr, 'text/html');
+
+    const usedIds = new Set();
+    doc.querySelectorAll('[id]').forEach(el => usedIds.add(el.id));
+
+    // Process landmarks
+    ['header:not(header header)', 'footer:not(footer footer)', 'main', 'aside'].forEach(selector => {
+      try {
+        doc.querySelectorAll(selector).forEach(el => {
+          const sectionType = detectSectionType(el);
+          if (sectionType) {
+            const hadId = !!el.id;
+            const hadRole = !!el.getAttribute('role');
+            applySemanticAttributes(el, sectionType, usedIds);
+            if (!hadId && el.id) stats.idsAdded++;
+            if (!hadRole && el.getAttribute('role')) stats.rolesAdded++;
+            stats.sectionsEnhanced++;
+          }
+        });
+      } catch (err) {
+        stats.warnings.push(`Selector error: ${selector}`);
+      }
+    });
+
+    // Handle nav elements
+    const navElements = doc.querySelectorAll('nav, [role="navigation"]');
+    navElements.forEach((nav, index) => {
+      const isInHeader = nav.closest('header') !== null;
+      const isInFooter = nav.closest('footer') !== null;
+
+      if (isInHeader && index === 0) {
+        applySemanticAttributes(nav, 'nav', usedIds, 0);
+        if (!nav.getAttribute('aria-label')) {
+          nav.setAttribute('aria-label', 'Primary Menu');
+        }
+      } else if (isInFooter) {
+        if (!nav.id) {
+          nav.id = usedIds.has('footer-navigation') ? `footer-navigation-${index}` : 'footer-navigation';
+          usedIds.add(nav.id);
+        }
+        nav.setAttribute('role', 'navigation');
+        if (!nav.getAttribute('aria-label')) {
+          nav.setAttribute('aria-label', 'Footer Menu');
+        }
+      } else {
+        applySemanticAttributes(nav, 'nav', usedIds, index);
+        if (!nav.getAttribute('aria-label')) {
+          nav.setAttribute('aria-label', `Navigation ${index + 1}`);
+        }
+      }
+      stats.sectionsEnhanced++;
+    });
+
+    return {
+      html: '<!DOCTYPE html>\n' + doc.documentElement.outerHTML,
+      stats
+    };
+  }, html);
+}

package/src/core/state-capture.js

@@ -1,7 +1,7 @@
 /**
  * State Capture Module
  *
- * Capture hover states for interactive elements using Puppeteer.
+ * Capture hover states for interactive elements using Playwright.
  * Screenshots before/after, computes style differences, generates :hover CSS.
  *
  * Usage:
@@ -220,11 +220,11 @@ function extractHoverSelectorsFromCss(cssString) {
  * Detect interactive elements on page via DOM query.
  * Uses inline function to avoid new Function() for CSP compliance.
  *
- * @param {import('puppeteer').Page} page - Puppeteer page
+ * @param {import('playwright').Page} page - Playwright page
  * @returns {Promise<InteractiveElement[]>} Array of interactive elements
  */
 async function detectInteractiveElementsFromDom(page) {
-  return await page.evaluate((selectors, maxScan, maxDepth) => {
+  return await page.evaluate(({ selectors, maxScan, maxDepth }) => {
     // Inline getUniqueSelector to avoid new Function()
     function getUniqueSelector(element) {
       if (element.id) return '#' + element.id;
@@ -316,7 +316,7 @@ async function detectInteractiveElementsFromDom(page) {
     }
 
     return results;
-  }, INTERACTIVE_SELECTORS, MAX_DOM_SCAN, MAX_SELECTOR_DEPTH);
+  }, { selectors: INTERACTIVE_SELECTORS, maxScan: MAX_DOM_SCAN, maxDepth: MAX_SELECTOR_DEPTH });
 }
 
 // ============================================================================
@@ -326,7 +326,7 @@ async function detectInteractiveElementsFromDom(page) {
 /**
  * Detect interactive elements using CSS + DOM analysis.
  *
- * @param {import('puppeteer').Page} page - Puppeteer page
+ * @param {import('playwright').Page} page - Playwright page
  * @param {string|null} cssString - Raw CSS for :hover detection
  * @returns {Promise<{fromCss: string[], fromDom: InteractiveElement[], combined: string[]}>}
  */
@@ -370,12 +370,12 @@ export async function detectInteractiveElements(page, cssString) {
 /**
  * Capture computed styles for an element.
  *
- * @param {import('puppeteer').Page} page - Puppeteer page
+ * @param {import('playwright').Page} page - Playwright page
  * @param {string} selector - CSS selector
  * @returns {Promise<Object<string, string>|null>} Style object or null
  */
 async function captureElementStyles(page, selector) {
-  return await page.evaluate((sel, props) => {
+  return await page.evaluate(({ sel, props }) => {
     const el = document.querySelector(sel);
     if (!el) return null;
 
@@ -385,13 +385,13 @@ async function captureElementStyles(page, selector) {
       result[prop] = style[prop];
     }
     return result;
-  }, selector, STYLE_PROPERTIES);
+  }, { sel: selector, props: STYLE_PROPERTIES });
 }
 
 /**
  * Capture hover state for a single element.
  *
- * @param {import('puppeteer').Page} page - Puppeteer page
+ * @param {import('playwright').Page} page - Playwright page
  * @param {string} selector - CSS selector for element
  * @param {string} outputDir - Directory for screenshots
  * @param {number} index - Element index for filename
@@ -415,22 +415,18 @@ export async function captureHoverState(page, selector, outputDir, index) {
   }
 
   try {
-    // Find element
-    const element = await page.$(selector);
-    if (!element) {
-      result.error = 'Element not found';
-      return result;
-    }
+    // Use Playwright locator API for reliability
+    const locator = page.locator(selector);
 
-    // Check visibility
-    const isVisible = await element.isVisible().catch(() => false);
+    // Check visibility via locator
+    const isVisible = await locator.isVisible().catch(() => false);
     if (!isVisible) {
       result.error = 'Element not visible';
       return result;
     }
 
-    // Get bounding box
-    const box = await element.boundingBox();
+    // Get bounding box via locator
+    const box = await locator.boundingBox();
     if (!box) {
       result.error = 'No bounding box';
       return result;
@@ -450,8 +446,8 @@ export async function captureHoverState(page, selector, outputDir, index) {
     await page.screenshot({ path: normalPath, clip });
     result.normalScreenshot = normalPath;
 
-    // Hover and wait for transition
-    await page.hover(selector);
+    // Hover via locator (more reliable in Playwright)
+    await locator.hover();
     await new Promise(r => setTimeout(r, HOVER_SETTLE_DELAY));
 
     // Capture hover state using same helper
@@ -491,7 +487,7 @@ export async function captureHoverState(page, selector, outputDir, index) {
 /**
  * Capture all hover states for detected interactive elements.
  *
- * @param {import('puppeteer').Page} page - Puppeteer page
+ * @param {import('playwright').Page} page - Playwright page
  * @param {string|null} cssString - Raw CSS for detection
  * @param {string} outputDir - Base output directory
  * @returns {Promise<HoverCaptureOutput>}