design-clone 1.2.0 → 2.3.0

package/src/shared/viewports.js

@@ -0,0 +1,46 @@
+/**
+ * Shared viewport configurations for Design Clone
+ *
+ * Two viewport sets are provided:
+ * - VIEWPORTS: Standard capture viewports (1440px desktop)
+ * - VIEWPORTS_HD: High-resolution verification viewports (1920px desktop)
+ */
+
+/**
+ * Standard viewport configurations for multi-device capture
+ * Used by: screenshot.js, dimension-output.js
+ * @type {Object.<string, {width: number, height: number, deviceScaleFactor: number}>}
+ */
+export const VIEWPORTS = {
+  desktop: { width: 1440, height: 900, deviceScaleFactor: 1 },
+  tablet: { width: 768, height: 1024, deviceScaleFactor: 1 },
+  mobile: { width: 375, height: 812, deviceScaleFactor: 2 }
+};
+
+/**
+ * High-resolution viewport configurations for verification
+ * Used by: verify-menu.js, verify-layout.js, verify-header.js, verify-footer.js, verify-slider.js
+ * @type {Object.<string, {width: number, height: number, deviceScaleFactor: number}>}
+ */
+export const VIEWPORTS_HD = {
+  desktop: { width: 1920, height: 1080, deviceScaleFactor: 1 },
+  tablet: { width: 768, height: 1024, deviceScaleFactor: 1 },
+  mobile: { width: 375, height: 812, deviceScaleFactor: 2 }
+};
+
+/**
+ * UX Audit viewport configurations (no deviceScaleFactor)
+ * Used by: UX audit prompt templates
+ * @type {Object.<string, {width: number, height: number}>}
+ */
+export const VIEWPORTS_UX = {
+  desktop: { width: 1920, height: 1080 },
+  tablet: { width: 768, height: 1024 },
+  mobile: { width: 375, height: 812 }
+};
+
+/**
+ * Viewport names array for iteration
+ * @type {string[]}
+ */
+export const VIEWPORT_NAMES = ['desktop', 'tablet', 'mobile'];

package/src/utils/browser.js

@@ -1,32 +1,15 @@
 /**
  * Browser abstraction facade for design-clone scripts
  *
- * Auto-detects and uses:
- * 1. chrome-devtools skill (if installed) - Preferred
- * 2. Standalone puppeteer wrapper - Fallback
+ * Uses Playwright wrapper for browser automation.
  *
- * Exports same API regardless of provider:
+ * Exports same API:
  * - getBrowser(options)
  * - getPage(browser)
  * - closeBrowser()
  * - disconnectBrowser()
- * - parseArgs(argv)
- * - outputJSON(data)
- * - outputError(error)
  */
 
-import fs from 'fs';
-import path from 'path';
-import { fileURLToPath } from 'url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-// Chrome DevTools skill path
-const CHROME_DEVTOOLS_PATH = path.join(
-  process.env.HOME,
-  '.claude/skills/chrome-devtools/scripts/lib/browser.js'
-);
-
 let browserModule = null;
 let providerName = 'unknown';
 
@@ -36,31 +19,14 @@ let providerName = 'unknown';
 async function initProvider() {
   if (browserModule) return;
 
-  // Check for chrome-devtools skill
-  if (fs.existsSync(CHROME_DEVTOOLS_PATH)) {
-    try {
-      browserModule = await import(CHROME_DEVTOOLS_PATH);
-      providerName = 'chrome-devtools';
-      console.error('[browser] Using chrome-devtools skill');
-      return;
-    } catch (e) {
-      console.error('[browser] chrome-devtools found but failed to load:', e.message);
-    }
-  }
-
-  // Fall back to standalone puppeteer wrapper
-  browserModule = await import('./puppeteer.js');
-  providerName = 'standalone';
-  console.error('[browser] Using standalone puppeteer wrapper');
+  browserModule = await import('./playwright.js');
+  providerName = 'playwright';
+  console.error('[browser] Using Playwright wrapper');
 }
 
-// Import utilities (always use local helpers)
-import { parseArgs, outputJSON, outputError } from './helpers.js';
-export { parseArgs, outputJSON, outputError };
-
 /**
  * Get current browser provider name
- * @returns {string} 'chrome-devtools' or 'standalone'
+ * @returns {string} 'playwright'
  */
 export function getProviderName() {
   return providerName;
@@ -79,15 +45,16 @@ export async function getBrowser(options = {}) {
 /**
  * Get page from browser
  * @param {Browser} browser - Browser instance
+ * @param {Object} [options] - Page options
  * @returns {Promise<Page>} Page instance
  */
-export async function getPage(browser) {
+export async function getPage(browser, options = {}) {
   await initProvider();
-  return browserModule.getPage(browser);
+  return browserModule.getPage(browser, options);
 }
 
 /**
- * Close browser and clear session
+ * Close browser
  */
 export async function closeBrowser() {
   await initProvider();
@@ -95,7 +62,7 @@ export async function closeBrowser() {
 }
 
 /**
- * Disconnect from browser without closing
+ * Disconnect from browser (alias for close in Playwright)
  */
 export async function disconnectBrowser() {
   await initProvider();

package/src/utils/helpers.js

@@ -61,10 +61,14 @@ export function outputJSON(data) {
 export function outputError(error) {
   const errorMessage = error instanceof Error ? error.message : String(error);
   const errorStack = error instanceof Error ? error.stack : undefined;
+  const isDesignCloneError = error?.name === 'DesignCloneError';
 
   console.error(JSON.stringify({
     success: false,
     error: errorMessage,
+    code: isDesignCloneError ? error.code : undefined,
+    suggestion: isDesignCloneError ? error.suggestion : undefined,
+    context: isDesignCloneError ? error.context : undefined,
     stack: process.env.DEBUG ? errorStack : undefined
   }, null, 2));
   process.exit(1);

package/src/utils/log.js

@@ -0,0 +1,12 @@
+/**
+ * Centralized TTY-aware logging for CLI output.
+ * Logs to stderr only when attached to a terminal.
+ * Keeps stdout clean for JSON output.
+ */
+
+const isTTY = process.stderr.isTTY;
+
+export function logInfo(msg) { if (isTTY) console.error(`[INFO] ${msg}`); }
+export function logWarn(msg) { if (isTTY) console.error(`[WARN] ${msg}`); }
+export function logError(msg) { if (isTTY) console.error(`[ERROR] ${msg}`); }
+export { isTTY };

package/src/utils/playwright-loader.js

@@ -0,0 +1,76 @@
+/**
+ * Playwright Loader Helpers
+ *
+ * Chrome path detection and playwright module loading utilities.
+ * Extracted from playwright.js to keep each file under 200 lines.
+ */
+
+import fs from 'fs';
+
+/**
+ * Detect Chrome executable path by platform
+ * Used for playwright-core fallback when full playwright is not installed
+ * @returns {string|null} Chrome path or null if not found
+ */
+export function detectChromePath() {
+  const platform = process.platform;
+
+  const paths = {
+    darwin: [
+      '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+      '/Applications/Chromium.app/Contents/MacOS/Chromium',
+      '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary'
+    ],
+    linux: [
+      '/usr/bin/google-chrome',
+      '/usr/bin/google-chrome-stable',
+      '/usr/bin/chromium',
+      '/usr/bin/chromium-browser',
+      '/snap/bin/chromium'
+    ],
+    win32: [
+      'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+      'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+      ...(process.env.LOCALAPPDATA
+        ? [`${process.env.LOCALAPPDATA}\\Google\\Chrome\\Application\\chrome.exe`]
+        : [])
+    ]
+  };
+
+  const candidates = paths[platform] || [];
+  for (const chromePath of candidates) {
+    if (fs.existsSync(chromePath)) {
+      return chromePath;
+    }
+  }
+
+  return null;
+}
+
+/** @type {typeof import('playwright')|null} */
+let playwright = null;
+
+/**
+ * Load playwright module (try playwright first, then playwright-core)
+ * @returns {Promise<Object>} Playwright module with chromium browser type
+ * @throws {Error} If neither playwright nor playwright-core is installed
+ */
+export async function loadPlaywright() {
+  if (playwright) return playwright;
+
+  try {
+    playwright = await import('playwright');
+    return playwright;
+  } catch (e1) {
+    try {
+      playwright = await import('playwright-core');
+      return playwright;
+    } catch (e2) {
+      throw new Error(
+        'Playwright not found. Install with: npm install playwright\n' +
+        'Or for smaller install: npm install playwright-core\n' +
+        `Details: playwright: ${e1.message}, playwright-core: ${e2.message}`
+      );
+    }
+  }
+}

package/src/utils/playwright.js

@@ -0,0 +1,147 @@
+/**
+ * Standalone Playwright browser wrapper for design-clone scripts
+ * Provides browser automation with Playwright
+ *
+ * Features:
+ * - Auto-detects Chrome installation path (macOS, Linux, Windows)
+ * - Fast browser launch (no session persistence needed)
+ * - Compatible API with previous Puppeteer wrapper
+ */
+
+import { VIEWPORTS_HD } from '../shared/viewports.js';
+import { detectChromePath, loadPlaywright } from './playwright-loader.js';
+
+/** @type {import('playwright').Browser|null} */
+let browserInstance = null;
+/** @type {import('playwright').Page|null} */
+let pageInstance = null;
+
+/** Default viewport dimensions */
+const DEFAULT_VIEWPORT = { width: VIEWPORTS_HD.desktop.width, height: VIEWPORTS_HD.desktop.height };
+
+/**
+ * Launch browser instance
+ *
+ * @param {Object} options - Browser options
+ * @param {boolean} [options.headless=true] - Run in headless mode
+ * @param {Object} [options.viewport] - Default viewport dimensions (applied per context)
+ * @param {string} [options.executablePath] - Chrome executable path override
+ * @param {string[]} [options.args] - Additional Chrome arguments
+ * @returns {Promise<Browser>} Playwright browser instance
+ * @throws {Error} If Chrome not found and no executablePath provided (playwright-core)
+ */
+export async function getBrowser(options = {}) {
+  const pw = await loadPlaywright();
+
+  // Reuse existing browser if connected
+  if (browserInstance && browserInstance.isConnected()) {
+    return browserInstance;
+  }
+
+  // Determine executable path for playwright-core
+  let executablePath = options.executablePath;
+  if (!executablePath) {
+    // Check if we're using playwright-core (no bundled browser)
+    const isCore = !pw.chromium?.executablePath;
+    if (isCore) {
+      executablePath = detectChromePath();
+      if (!executablePath) {
+        throw new Error(
+          'Chrome not found. Either:\n' +
+          '1. Install Google Chrome\n' +
+          '2. Use full playwright (npm install playwright)\n' +
+          '3. Set executablePath option'
+        );
+      }
+    }
+  }
+
+  // Build launch options
+  const launchOptions = {
+    headless: options.headless !== false,
+    args: [
+      '--no-sandbox',
+      '--disable-setuid-sandbox',
+      '--disable-dev-shm-usage',
+      ...(options.args || [])
+    ]
+  };
+
+  // Only set executablePath if needed (playwright-core or override)
+  if (executablePath) {
+    launchOptions.executablePath = executablePath;
+  }
+
+  // Launch browser
+  browserInstance = await pw.chromium.launch(launchOptions);
+  console.error('[browser] Launched Playwright browser');
+
+  return browserInstance;
+}
+
+/**
+ * Get current page or create new one
+ * Reuses existing page if available
+ *
+ * @param {import('playwright').Browser} browser - Playwright browser instance
+ * @param {Object} [options] - Page options
+ * @param {{width: number, height: number}} [options.viewport] - Viewport dimensions
+ * @returns {Promise<import('playwright').Page>} Playwright page instance
+ * @throws {Error} If browser is null or disconnected
+ */
+export async function getPage(browser, options = {}) {
+  if (!browser || !browser.isConnected()) {
+    throw new Error('Browser not connected. Call getBrowser() first.');
+  }
+
+  if (pageInstance && !pageInstance.isClosed()) {
+    return pageInstance;
+  }
+
+  // Get existing pages or create new context + page
+  const contexts = browser.contexts();
+  if (contexts.length > 0) {
+    const pages = contexts[0].pages();
+    if (pages.length > 0) {
+      pageInstance = pages[0];
+      return pageInstance;
+    }
+  }
+
+  // Create new context with default viewport
+  const contextOptions = {
+    viewport: options.viewport || DEFAULT_VIEWPORT
+  };
+
+  const context = await browser.newContext(contextOptions);
+  pageInstance = await context.newPage();
+
+  return pageInstance;
+}
+
+/**
+ * Close browser
+ * Use when completely done with browser
+ */
+export async function closeBrowser() {
+  if (browserInstance) {
+    try {
+      await browserInstance.close();
+    } catch (err) {
+      console.error(`[browser] Error closing browser: ${err.message}`);
+    }
+    browserInstance = null;
+    pageInstance = null;
+    console.error('[browser] Closed browser');
+  }
+}
+
+/**
+ * Disconnect from browser (alias for closeBrowser in Playwright)
+ * Playwright doesn't support disconnect without close, so this is an alias
+ */
+export async function disconnectBrowser() {
+  // Playwright doesn't have disconnect concept like Puppeteer
+  // Just close the browser for API compatibility
+  return closeBrowser();
+}

package/src/utils/progress.js

@@ -0,0 +1,32 @@
+/**
+ * TTY-aware progress reporting for extraction/capture pipelines.
+ * Writes to stderr only when attached to a terminal.
+ * Keeps stdout clean for JSON output.
+ */
+
+import { isTTY } from './log.js';
+
+export class ProgressReporter {
+  #current = 0;
+  #total = 0;
+  #label = '';
+
+  start(totalSteps, label = '') {
+    this.#total = totalSteps;
+    this.#current = 0;
+    this.#label = label;
+    if (isTTY) process.stderr.write(`[0/${totalSteps}] ${label}\n`);
+  }
+
+  step(label, details = '') {
+    this.#current++;
+    const detailStr = details ? ` (${details})` : '';
+    if (isTTY) process.stderr.write(`[${this.#current}/${this.#total}] ${label}${detailStr}\n`);
+  }
+
+  complete(summary = '') {
+    if (isTTY) process.stderr.write(`[done] ${summary}\n`);
+  }
+}
+
+export function createProgress() { return new ProgressReporter(); }

package/src/verification/generate-audit-report-css-fixes.js

@@ -0,0 +1,52 @@
+/**
+ * Audit Report CSS Fix Suggestions
+ *
+ * Analyzes verification results and generates CSS fix suggestions.
+ * Extracted from generate-audit-report-sections.js to keep files under 200 lines.
+ */
+
+/**
+ * Generate CSS fixes section markdown from all component results
+ * @param {Object} results - Map of component name to verification result
+ * @returns {string} Markdown section or empty string if no fixes
+ */
+export function generateCSSFixes(results) {
+  const fixes = [];
+
+  for (const [component, result] of Object.entries(results)) {
+    if (!result?.viewports) continue;
+
+    for (const [viewport, vpResult] of Object.entries(result.viewports)) {
+      if (component === 'footer') {
+        const positionTest = vpResult.tests?.find(t => t.name === 'Footer at page bottom');
+        if (positionTest && !positionTest.passed) {
+          fixes.push({
+            component, viewport,
+            issue: 'Footer not at page bottom',
+            suggestion: `/* Ensure footer sticks to bottom */\nfooter {\n  margin-top: auto;\n}\nbody {\n  min-height: 100vh;\n  display: flex;\n  flex-direction: column;\n}`
+          });
+        }
+      }
+
+      if (vpResult.warnings) {
+        for (const warning of vpResult.warnings) {
+          if (warning.includes('z-index')) {
+            fixes.push({
+              component, viewport,
+              issue: warning,
+              suggestion: `/* Increase header z-index */\nheader, .header, [role="banner"] {\n  z-index: 1000;\n}`
+            });
+          }
+        }
+      }
+    }
+  }
+
+  if (fixes.length === 0) return '';
+
+  let section = `## Suggested CSS Fixes\n\n`;
+  for (const fix of fixes) {
+    section += `### ${fix.component} (${fix.viewport})\n\n**Issue:** ${fix.issue}\n\n\`\`\`css\n${fix.suggestion}\n\`\`\`\n\n`;
+  }
+  return section;
+}

package/src/verification/generate-audit-report-sections.js

@@ -0,0 +1,158 @@
+/**
+ * Audit Report Section Generators
+ *
+ * Pure functions for generating markdown table and section content
+ * extracted from generate-audit-report.js to keep each file under 200 lines.
+ */
+
+import path from 'path';
+import { generateCSSFixes } from './generate-audit-report-css-fixes.js';
+
+// Re-export so callers only need this one module
+export { generateCSSFixes };
+
+// Status icons
+export const STATUS_ICONS = {
+  pass: '✅',
+  warn: '⚠️',
+  fail: '❌',
+  info: 'ℹ️'
+};
+
+/**
+ * Calculate component status from verification result
+ * @param {Object|null} result
+ * @returns {{status: string, icon: string, label: string}}
+ */
+export function getComponentStatus(result) {
+  if (!result) return { status: 'skip', icon: STATUS_ICONS.info, label: 'Not tested' };
+  const { summary } = result;
+  if (!summary) return { status: 'skip', icon: STATUS_ICONS.info, label: 'No data' };
+  if (summary.failed > 0) return { status: 'fail', icon: STATUS_ICONS.fail, label: `${summary.failed} failed` };
+  if (summary.warnings?.length > 0) return { status: 'warn', icon: STATUS_ICONS.warn, label: `${summary.warnings.length} warnings` };
+  return { status: 'pass', icon: STATUS_ICONS.pass, label: 'Passed' };
+}
+
+/**
+ * Generate summary table markdown
+ * @param {Object} results - Map of component name to result
+ * @returns {string}
+ */
+export function generateSummaryTable(results) {
+  let table = `| Component | Status | Tests | Details |\n|-----------|--------|-------|----------|\n`;
+  for (const [component, result] of Object.entries(results)) {
+    const status = getComponentStatus(result);
+    const tests = result?.summary ? `${result.summary.passed}/${result.summary.totalTests}` : '-';
+    const label = component.charAt(0).toUpperCase() + component.slice(1);
+    table += `| ${label} | ${status.icon} ${status.label} | ${tests} | ${result?.url || '-'} |\n`;
+  }
+  return table;
+}
+
+/**
+ * Generate responsive viewport breakdown table
+ * @param {Object} results
+ * @returns {string}
+ */
+export function generateViewportTable(results) {
+  const viewports = ['mobile', 'tablet', 'desktop'];
+  const components = Object.keys(results).filter(c => results[c]?.viewports);
+  if (components.length === 0) return '';
+
+  let table = `| Component | Mobile | Tablet | Desktop |\n|-----------|--------|--------|----------|\n`;
+  for (const component of components) {
+    const result = results[component];
+    const row = [component.charAt(0).toUpperCase() + component.slice(1)];
+    for (const vp of viewports) {
+      const vpResult = result.viewports?.[vp];
+      if (vpResult) {
+        const icon = vpResult.failed > 0 ? STATUS_ICONS.fail
+          : vpResult.warnings?.length > 0 ? STATUS_ICONS.warn
+          : STATUS_ICONS.pass;
+        row.push(`${icon} ${vpResult.passed}/${vpResult.tests?.length || 0}`);
+      } else {
+        row.push('-');
+      }
+    }
+    table += `| ${row.join(' | ')} |\n`;
+  }
+  return table;
+}
+
+/**
+ * Generate a markdown section for a single component
+ * @param {string} component
+ * @param {Object|null} result
+ * @returns {string}
+ */
+export function generateComponentSection(component, result) {
+  const label = component.charAt(0).toUpperCase() + component.slice(1);
+  if (!result) return `### ${label}\n\n${STATUS_ICONS.info} Not tested\n\n---\n\n`;
+
+  const status = getComponentStatus(result);
+  let section = `### ${label} ${status.icon}\n\n`;
+
+  if (component === 'slider' && result.sliderLibrary) {
+    section += `**Library:** ${result.sliderLibrary}\n\n`;
+  }
+
+  if (result.viewports) {
+    for (const [viewport, vpResult] of Object.entries(result.viewports)) {
+      const vpLabel = viewport.charAt(0).toUpperCase() + viewport.slice(1);
+      section += `#### ${vpLabel} (${vpResult.dimensions?.width}x${vpResult.dimensions?.height})\n\n`;
+
+      if (vpResult.tests?.length > 0) {
+        for (const test of vpResult.tests) {
+          const icon = test.passed ? STATUS_ICONS.pass : STATUS_ICONS.fail;
+          section += `- ${icon} **${test.name}**`;
+          if (test.selector) section += ` - \`${test.selector}\``;
+          if (test.count !== undefined) section += ` (${test.count} found)`;
+          if (test.note) section += ` - ${test.note}`;
+          if (test.error) section += ` - ⚠️ ${test.error}`;
+          section += '\n';
+        }
+      }
+
+      if (vpResult.warnings?.length > 0) {
+        section += '\n**Warnings:**\n';
+        for (const warning of vpResult.warnings) {
+          section += `- ${STATUS_ICONS.warn} ${warning}\n`;
+        }
+      }
+      section += '\n';
+    }
+  }
+
+  if (result.screenshots?.length > 0) {
+    section += `#### Screenshots\n\n| Viewport | Screenshot |\n|----------|------------|\n`;
+    for (const screenshot of result.screenshots) {
+      const name = path.basename(screenshot);
+      const viewport = name.replace(/^[a-z]+-test-/, '').replace('.png', '');
+      section += `| ${viewport} | [${name}](${screenshot}) |\n`;
+    }
+    section += '\n';
+  }
+
+  section += '---\n\n';
+  return section;
+}
+
+/**
+ * Generate the full markdown audit report string
+ * @param {Object} results
+ * @param {string|undefined} url
+ * @returns {string}
+ */
+export function generateMarkdownReport(results, url) {
+  const timestamp = new Date().toISOString();
+  let report = `# Component Audit Report\n\n**Generated:** ${timestamp}\n**URL:** ${url || 'N/A'}\n\n`;
+  report += `## Summary\n\n${generateSummaryTable(results)}\n`;
+  report += `## Responsive Breakdown\n\n${generateViewportTable(results)}\n`;
+  report += `## Component Details\n\n`;
+  for (const [component, result] of Object.entries(results)) {
+    report += generateComponentSection(component, result);
+  }
+  report += generateCSSFixes(results);
+  report += `---\n\n*Report generated by design-clone verification suite*\n`;
+  return report;
+}