design-clone 2.1.0 → 2.3.0

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

@@ -0,0 +1,178 @@
+/**
+ * Animation Extractor
+ *
+ * Extract @keyframes definitions, animation properties, and transition values
+ * from CSS using css-tree AST walking.
+ *
+ * Usage:
+ *   import { extractAnimations, generateAnimationsCss } from './animation-extractor.js';
+ *   const animations = await extractAnimations(cssString);
+ *   const animCss = generateAnimationsCss(animations);
+ *
+ * @module animation-extractor
+ */
+
+import { extractAllFromAst, processKeyframeRule, processStyleRule, TRANSITION_PROPERTIES, ANIMATION_PROPERTIES } from './animation-extractor-ast.js';
+import { generateAnimationsCss, generateAnimationTokens, extractTimingFromShorthand } from './animation-extractor-output.js';
+
+// Re-export for backward compatibility
+export { generateAnimationsCss, generateAnimationTokens };
+
+// ============================================================================
+// Type Definitions (JSDoc)
+// ============================================================================
+
+/**
+ * @typedef {Object} KeyframeFrame
+ * @property {string} offset - Keyframe selector (e.g., "0%", "50%", "100%", "from", "to")
+ * @property {Object<string, string>} properties - CSS properties and their values
+ */
+
+/**
+ * @typedef {Object} KeyframeData
+ * @property {KeyframeFrame[]} frames - Array of keyframe frames
+ * @property {string} raw - Original CSS text for regeneration
+ * @property {boolean} vendorPrefixed - True if @-webkit-keyframes
+ */
+
+/**
+ * @typedef {Object} ExtractionResult
+ * @property {Object<string, KeyframeData>} keyframes - Map of keyframe name to data
+ * @property {Array} transitions - Array of transition rules
+ * @property {Array} animatedElements - Array of animated element rules
+ * @property {string} [error] - Error message if extraction failed
+ */
+
+/**
+ * @typedef {Object} AnimationTokens
+ * @property {string[]} keyframes - List of keyframe names
+ * @property {number} keyframeCount - Total number of keyframes
+ * @property {number} transitions - Total number of transition rules
+ * @property {number} animatedElements - Total number of animated elements
+ * @property {string[]} durations - Unique duration values found
+ * @property {string[]} timingFunctions - Unique timing functions found
+ */
+
+// ============================================================================
+// Dependency Management
+// ============================================================================
+
+/**
+ * css-tree module reference - loaded dynamically to handle missing dependency
+ * @type {Object|null}
+ */
+let csstree = null;
+
+try {
+  csstree = await import('css-tree');
+} catch (importError) {
+  const errorDetails = importError.code === 'ERR_MODULE_NOT_FOUND'
+    ? 'Module not found in node_modules'
+    : importError.message;
+
+  console.error(
+    '[animation-extractor] Failed to load css-tree dependency.\n' +
+    `  Error: ${errorDetails}\n` +
+    '  Fix: Run "npm install css-tree" to install the required dependency.\n' +
+    '  Note: Animation extraction will be disabled until css-tree is available.'
+  );
+}
+
+// ============================================================================
+// Legacy Individual Extractors (Kept for Testing/Backwards Compatibility)
+// ============================================================================
+
+/**
+ * Extract @keyframes from CSS AST
+ * @param {Object} cssAst - css-tree AST
+ * @returns {Object<string, KeyframeData>}
+ */
+function extractKeyframes(cssAst) {
+  if (!csstree) return {};
+  const { keyframes } = extractAllFromAst(csstree, cssAst);
+  return keyframes;
+}
+
+/**
+ * Extract transition properties from CSS rules
+ * @param {Object} cssAst - css-tree AST
+ * @returns {Array}
+ */
+function extractTransitions(cssAst) {
+  if (!csstree) return [];
+  const { transitions } = extractAllFromAst(csstree, cssAst);
+  return transitions;
+}
+
+/**
+ * Extract animation-* properties from CSS rules
+ * @param {Object} cssAst - css-tree AST
+ * @returns {Array}
+ */
+function extractAnimationProps(cssAst) {
+  if (!csstree) return [];
+  const { animatedElements } = extractAllFromAst(csstree, cssAst);
+  return animatedElements;
+}
+
+// ============================================================================
+// Main Extraction Function
+// ============================================================================
+
+/**
+ * Main extraction function - extract all animation-related CSS data.
+ *
+ * Uses single-pass AST walking for optimal performance.
+ * Falls back to lenient parsing if strict parsing fails.
+ *
+ * @param {string} cssString - Raw CSS string to parse
+ * @returns {Promise<ExtractionResult>}
+ *
+ * @example
+ * const css = '@keyframes fadeIn { 0% { opacity: 0; } 100% { opacity: 1; } }';
+ * const result = await extractAnimations(css);
+ * console.log(result.keyframes.fadeIn.frames.length); // 2
+ */
+export async function extractAnimations(cssString) {
+  if (!cssString || typeof cssString !== 'string') {
+    return { keyframes: {}, transitions: [], animatedElements: [] };
+  }
+
+  if (!csstree) {
+    return {
+      keyframes: {},
+      transitions: [],
+      animatedElements: [],
+      error: 'css-tree dependency not available. Run: npm install css-tree'
+    };
+  }
+
+  let ast;
+  try {
+    ast = csstree.parse(cssString, {
+      parseRulePrelude: true,
+      parseValue: true,
+      parseAtrulePrelude: true
+    });
+  } catch (parseError) {
+    try {
+      ast = csstree.parse(cssString, {
+        parseRulePrelude: true,
+        parseValue: false,
+        parseAtrulePrelude: false
+      });
+    } catch (lenientError) {
+      return {
+        keyframes: {},
+        transitions: [],
+        animatedElements: [],
+        error: `CSS parse error: ${parseError.message}. Lenient parse also failed: ${lenientError.message}`
+      };
+    }
+  }
+
+  return extractAllFromAst(csstree, ast);
+}
+
+// Export individual functions for testing and advanced use
+export { extractKeyframes, extractTransitions, extractAnimationProps };

package/src/core/animation/state-capture-detection.js

@@ -0,0 +1,200 @@
+/**
+ * State Capture Detection
+ *
+ * CSS-based and DOM-based detection of interactive elements that have
+ * hover states. Used by state-capture.js to find elements before
+ * screenshot capture.
+ *
+ * @module state-capture-detection
+ */
+
+import { logError } from '../../utils/log.js';
+
+/** Maximum number of elements to capture (performance limit) */
+export const MAX_ELEMENTS = 50;
+
+/** Maximum elements to scan in DOM for transitions (performance limit) */
+export const MAX_DOM_SCAN = 200;
+
+/** Maximum selector depth when generating unique selectors */
+export const MAX_SELECTOR_DEPTH = 3;
+
+/** Interactive element selectors for DOM query */
+export const INTERACTIVE_SELECTORS = [
+  'button:not(:disabled)',
+  'a[href]',
+  '[role="button"]',
+  '[role="link"]',
+  'input[type="submit"]',
+  'input[type="button"]',
+  '.btn',
+  '.button',
+  '.card',
+  '.nav-link'
+];
+
+let csstree = null;
+try {
+  csstree = await import('css-tree');
+} catch {
+  console.error(
+    '[state-capture] css-tree not available. CSS-based hover detection disabled.\n' +
+    '  Fix: Run "npm install css-tree"'
+  );
+}
+
+/** Strip :hover from selector text (handles compound selectors). */
+export function extractBaseSelector(selectorText) {
+  return selectorText.replace(/:hover/g, '').replace(/\s+/g, ' ').trim();
+}
+
+/** Basic CSS selector validation (non-empty, no HTML chars, ≤500 chars). */
+export function isValidSelector(selector) {
+  if (!selector || typeof selector !== 'string') return false;
+  const trimmed = selector.trim();
+  if (!trimmed || trimmed.length > 500) return false;
+  if (/[<>{}]/.test(trimmed)) return false;
+  return true;
+}
+
+/** Extract base selectors that have :hover rules from a CSS string via AST. */
+export function extractHoverSelectorsFromCss(cssString) {
+  const hoverSelectors = new Set();
+
+  if (!csstree || !cssString || typeof cssString !== 'string') {
+    return hoverSelectors;
+  }
+
+  try {
+    const ast = csstree.parse(cssString, { parseRulePrelude: true });
+
+    csstree.walk(ast, {
+      visit: 'Rule',
+      enter(node) {
+        if (!node.prelude) return;
+
+        const selectorText = csstree.generate(node.prelude);
+        if (selectorText.includes(':hover')) {
+          const baseSelector = extractBaseSelector(selectorText);
+          if (baseSelector && isValidSelector(baseSelector)) {
+            hoverSelectors.add(baseSelector);
+          }
+        }
+      }
+    });
+  } catch (e) {
+    logError(`[state-capture] CSS parse error: ${e.message}`);
+  }
+
+  return hoverSelectors;
+}
+
+/**
+ * Detect interactive elements via DOM query + transition scan (CSP-safe, no new Function).
+ * @param {import('playwright').Page} page
+ * @returns {Promise<Array<{selector, tag, text?, hasTransition?}>>}
+ */
+export async function detectInteractiveElementsFromDom(page) {
+  return await page.evaluate(({ selectors, maxScan, maxDepth }) => {
+    function getUniqueSelector(element) {
+      if (element.id) return '#' + element.id;
+
+      const pathArr = [];
+      let current = element;
+
+      while (current && current.nodeType === 1 && pathArr.length < maxDepth) {
+        let selector = current.tagName.toLowerCase();
+
+        if (current.className && typeof current.className === 'string') {
+          const classes = current.className.trim().split(/\s+/).slice(0, 2).filter(c => c);
+          if (classes.length) selector += '.' + classes.join('.');
+        }
+
+        const siblings = current.parentNode?.children || [];
+        const sameTagSiblings = Array.from(siblings).filter(s => s.tagName === current.tagName);
+        if (sameTagSiblings.length > 1) {
+          const index = sameTagSiblings.indexOf(current) + 1;
+          selector += ':nth-of-type(' + index + ')';
+        }
+
+        pathArr.unshift(selector);
+        current = current.parentElement;
+      }
+
+      return pathArr.join(' > ');
+    }
+
+    const results = [];
+    const seen = new Set();
+    let totalScanned = 0;
+
+    for (const sel of selectors) {
+      if (totalScanned >= maxScan) break;
+
+      try {
+        const elements = document.querySelectorAll(sel);
+        for (const el of elements) {
+          if (totalScanned >= maxScan) break;
+          totalScanned++;
+
+          if (!el.offsetParent && el.tagName !== 'BODY') continue;
+
+          const uniqueSel = getUniqueSelector(el);
+          if (!seen.has(uniqueSel)) {
+            seen.add(uniqueSel);
+            results.push({
+              selector: uniqueSel,
+              tag: el.tagName.toLowerCase(),
+              text: el.textContent?.slice(0, 30)?.trim() || ''
+            });
+          }
+        }
+      } catch {
+        // Invalid selector, skip
+      }
+    }
+
+    const allElements = document.querySelectorAll('*');
+    for (const el of allElements) {
+      if (totalScanned >= maxScan) break;
+      totalScanned++;
+
+      if (!el.offsetParent && el.tagName !== 'BODY') continue;
+
+      const style = getComputedStyle(el);
+      const hasTransition = style.transition &&
+        style.transition !== 'all 0s ease 0s' &&
+        style.transition !== 'none' &&
+        !style.transition.startsWith('none');
+
+      if (hasTransition) {
+        const uniqueSel = getUniqueSelector(el);
+        if (!seen.has(uniqueSel)) {
+          seen.add(uniqueSel);
+          results.push({
+            selector: uniqueSel,
+            tag: el.tagName.toLowerCase(),
+            hasTransition: true
+          });
+        }
+      }
+    }
+
+    return results;
+  }, { selectors: INTERACTIVE_SELECTORS, maxScan: MAX_DOM_SCAN, maxDepth: MAX_SELECTOR_DEPTH });
+}
+
+/**
+ * Detect interactive elements via CSS + DOM, deduped and limited to MAX_ELEMENTS.
+ * @param {import('playwright').Page} page
+ * @param {string|null} cssString
+ * @returns {Promise<{fromCss: string[], fromDom: Array, combined: string[]}>}
+ */
+export async function detectInteractiveElements(page, cssString) {
+  if (!page) throw new Error('Page parameter is required');
+  const hoverSelectors = extractHoverSelectorsFromCss(cssString);
+  const domInteractive = await detectInteractiveElementsFromDom(page);
+  const validDomSelectors = domInteractive.map(e => e.selector).filter(s => isValidSelector(s));
+  const combined = Array.from(new Set([...hoverSelectors, ...validDomSelectors])).slice(0, MAX_ELEMENTS);
+  return { fromCss: Array.from(hoverSelectors), fromDom: domInteractive, combined };
+}

package/src/core/animation/state-capture.js

@@ -0,0 +1,193 @@
+/**
+ * State Capture Module
+ *
+ * Capture hover states for interactive elements using Playwright.
+ * Screenshots before/after, computes style differences, generates :hover CSS.
+ *
+ * Usage:
+ *   import { captureAllHoverStates, generateHoverCss } from './state-capture.js';
+ *   const result = await captureAllHoverStates(page, cssString, outputDir);
+ *   const hoverCss = generateHoverCss(result.elements);
+ *
+ * @module state-capture
+ */
+
+import path from 'path';
+import fs from 'fs/promises';
+import { logInfo } from '../../utils/log.js';
+
+import {
+  detectInteractiveElements,
+  extractHoverSelectorsFromCss,
+  detectInteractiveElementsFromDom,
+  isValidSelector
+} from './state-capture-detection.js';
+
+/** Delay after hover for CSS transitions to complete (ms) */
+const HOVER_SETTLE_DELAY = 100;
+
+/** Delay after mouse reset for state to clear (ms) */
+const MOUSE_RESET_DELAY = 50;
+
+/** Padding around element for screenshots (px) */
+const SCREENSHOT_PADDING = 20;
+
+/** CSS properties to capture for style diff */
+const STYLE_PROPERTIES = [
+  'backgroundColor',
+  'color',
+  'transform',
+  'boxShadow',
+  'borderColor',
+  'opacity',
+  'scale',
+  'filter',
+  'textDecoration',
+  'outline'
+];
+
+/** Convert camelCase to kebab-case (e.g. backgroundColor → background-color). */
+function toKebabCase(str) {
+  return str.replace(/([A-Z])/g, '-$1').toLowerCase();
+}
+
+// Logging via centralized utils/log.js
+
+/** Capture computed styles for STYLE_PROPERTIES on a given selector. */
+async function captureElementStyles(page, selector) {
+  return await page.evaluate(({ sel, props }) => {
+    const el = document.querySelector(sel);
+    if (!el) return null;
+
+    const style = getComputedStyle(el);
+    const result = {};
+    for (const prop of props) {
+      result[prop] = style[prop];
+    }
+    return result;
+  }, { sel: selector, props: STYLE_PROPERTIES });
+}
+
+/**
+ * Capture hover state for a single element (normal + hover screenshots + style diff).
+ * @param {import('playwright').Page} page
+ * @param {string} selector
+ * @param {string} outputDir
+ * @param {number} index - used in output filename
+ * @returns {Promise<{selector, success, normalScreenshot, hoverScreenshot, styleDiff, error?}>}
+ */
+export async function captureHoverState(page, selector, outputDir, index) {
+  const result = {
+    selector,
+    success: false,
+    normalScreenshot: null,
+    hoverScreenshot: null,
+    normalStyles: null,
+    hoverStyles: null,
+    styleDiff: {}
+  };
+
+  if (!isValidSelector(selector)) {
+    result.error = 'Invalid selector';
+    return result;
+  }
+
+  try {
+    const locator = page.locator(selector);
+    const isVisible = await locator.isVisible().catch(() => false);
+    if (!isVisible) { result.error = 'Element not visible'; return result; }
+    const box = await locator.boundingBox();
+    if (!box) { result.error = 'No bounding box'; return result; }
+
+    const clip = {
+      x: Math.max(0, box.x - SCREENSHOT_PADDING), y: Math.max(0, box.y - SCREENSHOT_PADDING),
+      width: box.width + SCREENSHOT_PADDING * 2, height: box.height + SCREENSHOT_PADDING * 2
+    };
+
+    result.normalStyles = await captureElementStyles(page, selector);
+    const normalPath = path.join(outputDir, `hover-${index}-normal.png`);
+    await page.screenshot({ path: normalPath, clip });
+    result.normalScreenshot = normalPath;
+
+    await locator.hover();
+    await new Promise(r => setTimeout(r, HOVER_SETTLE_DELAY));
+
+    result.hoverStyles = await captureElementStyles(page, selector);
+    const hoverPath = path.join(outputDir, `hover-${index}-hover.png`);
+    await page.screenshot({ path: hoverPath, clip });
+    result.hoverScreenshot = hoverPath;
+
+    if (result.normalStyles && result.hoverStyles) {
+      for (const [prop, normalVal] of Object.entries(result.normalStyles)) {
+        const hoverVal = result.hoverStyles[prop];
+        if (hoverVal !== normalVal) result.styleDiff[prop] = { from: normalVal, to: hoverVal };
+      }
+    }
+    await page.mouse.move(0, 0);
+    await new Promise(r => setTimeout(r, MOUSE_RESET_DELAY));
+    result.success = Object.keys(result.styleDiff).length > 0;
+  } catch (e) {
+    result.error = e.message;
+  }
+
+  return result;
+}
+
+/**
+ * Capture hover states for all detected interactive elements.
+ * Writes screenshots to hover-states/ subdir and hover-diff.json summary.
+ * @param {import('playwright').Page} page
+ * @param {string|null} cssString - Raw CSS for :hover detection
+ * @param {string} outputDir
+ * @returns {Promise<{directory, detected, captured, summaryPath, elements}>}
+ */
+export async function captureAllHoverStates(page, cssString, outputDir) {
+  if (!page) throw new Error('Page parameter is required');
+  if (!outputDir || typeof outputDir !== 'string') throw new Error('Output directory parameter is required');
+
+  const hoverDir = path.join(outputDir, 'hover-states');
+  await fs.mkdir(hoverDir, { recursive: true });
+  const interactive = await detectInteractiveElements(page, cssString);
+  const elements = [];
+  let capturedCount = 0;
+
+  for (let i = 0; i < interactive.combined.length; i++) {
+    const selector = interactive.combined[i];
+    const result = await captureHoverState(page, selector, hoverDir, i);
+    elements.push(result);
+    if (result.success) { capturedCount++; logInfo(`[hover] ${capturedCount}: ${selector}`); }
+  }
+
+  const summaryPath = path.join(hoverDir, 'hover-diff.json');
+  await fs.writeFile(summaryPath, JSON.stringify({
+    detected: interactive.combined.length, captured: capturedCount,
+    fromCss: interactive.fromCss.length, fromDom: interactive.fromDom.length,
+    elements: elements.filter(e => e.success).map(r => ({
+      selector: r.selector, styleDiff: r.styleDiff,
+      normalScreenshot: r.normalScreenshot ? path.basename(r.normalScreenshot) : null,
+      hoverScreenshot: r.hoverScreenshot ? path.basename(r.hoverScreenshot) : null
+    }))
+  }, null, 2), 'utf-8');
+
+  return { directory: hoverDir, detected: interactive.combined.length, captured: capturedCount, summaryPath, elements };
+}
+
+/** Generate :hover CSS rules from captured style diffs. */
+export function generateHoverCss(results) {
+  if (!results || !Array.isArray(results)) return '/* No hover style changes detected */\n';
+  const successful = results.filter(r => r.success && Object.keys(r.styleDiff).length > 0);
+  if (successful.length === 0) return '/* No hover style changes detected */\n';
+
+  const lines = ['/**', ' * Generated :hover Styles', ' * Captured by design-clone state-capture', ' */\n'];
+  for (const result of successful) {
+    lines.push(`/* Element: ${result.selector} */`, `${result.selector}:hover {`);
+    for (const [prop, diff] of Object.entries(result.styleDiff)) {
+      lines.push(`  ${toKebabCase(prop)}: ${diff.to};`);
+    }
+    lines.push('}\n');
+  }
+  return lines.join('\n');
+}
+
+// Re-exports for backward compatibility
+export { detectInteractiveElements, extractHoverSelectorsFromCss, detectInteractiveElementsFromDom };

package/src/core/capture/browser-context-pool.js

@@ -0,0 +1,96 @@
+/**
+ * Browser Context Pool
+ *
+ * Manages a pool of Playwright browser contexts for parallel page capture.
+ * Includes memory guard to prevent OOM and queue for overflow requests.
+ */
+
+import os from 'os';
+
+const DEFAULT_MAX_CONTEXTS = 3;
+const MIN_FREE_MEMORY_MB = 500;
+const DEFAULT_ACQUIRE_TIMEOUT = 30000;
+
+export class BrowserContextPool {
+  #browser;
+  #maxContexts;
+  #acquireTimeout;
+  #active = new Set();
+  #waitQueue = [];
+
+  /**
+   * @param {import('playwright').Browser} browser
+   * @param {{ maxContexts?: number, acquireTimeout?: number }} options
+   */
+  constructor(browser, options = {}) {
+    this.#browser = browser;
+    this.#maxContexts = options.maxContexts || DEFAULT_MAX_CONTEXTS;
+    this.#acquireTimeout = options.acquireTimeout ?? DEFAULT_ACQUIRE_TIMEOUT;
+  }
+
+  /**
+   * Acquire a browser context + page from the pool.
+   * Waits if pool is full or memory is low.
+   * Rejects with an error if acquireTimeout is exceeded.
+   * @returns {Promise<{context: import('playwright').BrowserContext, page: import('playwright').Page}>}
+   */
+  async acquire() {
+    // Memory guard: wait for a release if free memory is low
+    const freeMB = os.freemem() / (1024 * 1024);
+    if (freeMB < MIN_FREE_MEMORY_MB && this.#active.size > 0) {
+      return this.#waitForRelease();
+    }
+
+    if (this.#active.size >= this.#maxContexts) {
+      return this.#waitForRelease();
+    }
+
+    const context = await this.#browser.newContext();
+    const page = await context.newPage();
+    this.#active.add(context);
+    return { context, page };
+  }
+
+  /**
+   * Release a context back to the pool (closes it).
+   * @param {import('playwright').BrowserContext} context
+   */
+  async release(context) {
+    await context.close().catch(() => {});
+    this.#active.delete(context);
+    if (this.#waitQueue.length > 0) {
+      const resolve = this.#waitQueue.shift();
+      resolve(this.acquire());
+    }
+  }
+
+  /** @returns {Promise<{context, page}>} */
+  #waitForRelease() {
+    const timeout = this.#acquireTimeout;
+    return new Promise((resolve, reject) => {
+      let timer;
+      const entry = (result) => {
+        clearTimeout(timer);
+        resolve(result);
+      };
+      this.#waitQueue.push(entry);
+      if (timeout > 0) {
+        timer = setTimeout(() => {
+          const idx = this.#waitQueue.indexOf(entry);
+          if (idx !== -1) this.#waitQueue.splice(idx, 1);
+          reject(new Error(`Context pool acquire timed out after ${timeout}ms`));
+        }, timeout);
+      }
+    });
+  }
+
+  /** Close all active contexts */
+  async drain() {
+    const contexts = [...this.#active];
+    await Promise.all(contexts.map(c => c.close().catch(() => {})));
+    this.#active.clear();
+    this.#waitQueue = [];
+  }
+
+  get activeCount() { return this.#active.size; }
+}