design-clone 2.1.0 → 3.0.0

package/src/route-discoverers/base-discoverer.js

@@ -10,6 +10,14 @@
  *   }
  */
 
+import {
+  normalizeRoute,
+  isDynamicRoute,
+  titleCase,
+  extractPageName,
+  deduplicateRoutes
+} from './base-discoverer-utils.js';
+
 /**
  * @typedef {Object} DiscoveredRoute
  * @property {string} path - Route path (e.g., '/about', '/blog/[slug]')
@@ -20,15 +28,6 @@
  * @property {string} source - Discovery source ('framework'|'link-scrape'|'interception')
  */
 
-// Dynamic segment patterns
-const DYNAMIC_PATTERNS = [
-  /\[[\w-]+\]/,     // Next.js [slug]
-  /\[\.\.\.([\w-]+)\]/, // Next.js catch-all [...slug]
-  /:[\w-]+/,        // Vue/React :id
-  /\{[\w-]+\}/,     // Angular {id}
-  /\*[\w-]*/        // Wildcard
-];
-
 /**
  * Abstract base class for route discoverers
  */
@@ -52,150 +51,64 @@ export class BaseDiscoverer {
   }
 
   /**
-   * Normalize a route path
-   * - Removes trailing slashes (except for root)
-   * - Removes query params and hash
-   * - Ensures leading slash
-   * @param {string} path - Route path to normalize
-   * @returns {string} Normalized path
+   * Normalize a route path (delegates to utility)
+   * @param {string} path
+   * @returns {string}
    */
   normalizeRoute(path) {
-    if (!path || typeof path !== 'string') return '/';
-
-    // Handle full URLs
-    if (path.startsWith('http')) {
-      try {
-        path = new URL(path).pathname;
-      } catch {
-        return '/';
-      }
-    }
-
-    // Ensure leading slash
-    if (!path.startsWith('/')) {
-      path = '/' + path;
-    }
-
-    // Remove query params and hash
-    path = path.split('?')[0].split('#')[0];
-
-    // Remove trailing slash (except for root)
-    if (path.length > 1 && path.endsWith('/')) {
-      path = path.slice(0, -1);
-    }
-
-    return path;
+    return normalizeRoute(path);
   }
 
   /**
-   * Check if a path contains dynamic segments
-   * @param {string} path - Route path
+   * Check if a path contains dynamic segments (delegates to utility)
+   * @param {string} path
    * @returns {boolean}
    */
   isDynamicRoute(path) {
-    return DYNAMIC_PATTERNS.some(pattern => pattern.test(path));
+    return isDynamicRoute(path);
   }
 
   /**
-   * Extract a human-readable page name from a path
-   * @param {string} path - Route path
-   * @param {string} [componentName] - Optional component name
+   * Extract a human-readable page name from a path (delegates to utility)
+   * @param {string} path
+   * @param {string} [componentName]
    * @returns {string}
    */
   extractPageName(path, componentName) {
-    // Use component name if available
-    if (componentName && componentName !== 'default' && componentName !== 'index') {
-      // Convert camelCase/PascalCase to Title Case
-      return componentName
-        .replace(/([A-Z])/g, ' $1')
-        .replace(/^./, s => s.toUpperCase())
-        .trim();
-    }
-
-    // Extract from path
-    const normalized = this.normalizeRoute(path);
-
-    if (normalized === '/') return 'Home';
-
-    // Get last segment
-    const segments = normalized.split('/').filter(Boolean);
-    if (segments.length === 0) return 'Home';
-
-    let lastSegment = segments[segments.length - 1];
-
-    // Handle dynamic segments
-    if (this.isDynamicRoute(lastSegment)) {
-      lastSegment = lastSegment.replace(/[\[\]:{}*\.]/g, '');
-      return `${this.titleCase(lastSegment)} (Dynamic)`;
-    }
-
-    // Convert kebab-case/snake_case to Title Case
-    return this.titleCase(lastSegment);
+    return extractPageName(path, componentName);
   }
 
   /**
-   * Convert string to Title Case
-   * @param {string} str - Input string
+   * Convert string to Title Case (delegates to utility)
+   * @param {string} str
    * @returns {string}
    */
   titleCase(str) {
-    return str
-      .replace(/[-_]/g, ' ')
-      .replace(/\b\w/g, c => c.toUpperCase());
+    return titleCase(str);
   }
 
   /**
-   * Deduplicate routes by path, preferring 'framework' source over others
-   * @param {DiscoveredRoute[]} routes - Array of routes
-   * @returns {DiscoveredRoute[]} Deduplicated routes
+   * Deduplicate routes by path, preferring higher-priority sources
+   * @param {DiscoveredRoute[]} routes
+   * @returns {DiscoveredRoute[]}
    */
   deduplicateRoutes(routes) {
-    const seen = new Map();
-
-    // Source priority: framework > interception > sitemap > link-scrape
-    const sourcePriority = {
-      'framework': 4,
-      'interception': 3,
-      'sitemap': 2,
-      'link-scrape': 1
-    };
-
-    for (const route of routes) {
-      const normalized = this.normalizeRoute(route.path);
-      const existing = seen.get(normalized);
-
-      const currentPriority = sourcePriority[route.source] || 0;
-      const existingPriority = existing ? (sourcePriority[existing.source] || 0) : -1;
-
-      // Replace if higher priority or if same priority but has a name while existing doesn't
-      if (!existing || currentPriority > existingPriority ||
-          (currentPriority === existingPriority && route.name && !existing.name)) {
-        seen.set(normalized, {
-          ...route,
-          path: normalized,
-          url: this.buildFullUrl(normalized),
-          dynamic: this.isDynamicRoute(normalized)
-        });
-      }
-    }
-
-    return Array.from(seen.values());
+    return deduplicateRoutes(routes, this.baseOrigin);
   }
 
   /**
    * Build full URL from path
-   * @param {string} path - Route path
+   * @param {string} path
    * @returns {string}
    */
   buildFullUrl(path) {
-    const normalized = this.normalizeRoute(path);
-    return `${this.baseOrigin}${normalized}`;
+    return `${this.baseOrigin}${normalizeRoute(path)}`;
   }
 
   /**
    * Scrape link elements from navigation areas
    * Common utility for all discoverers as fallback
-   * @param {string[]} [selectors] - CSS selectors to search
+   * @param {string[]} [selectors]
    * @returns {Promise<DiscoveredRoute[]>}
    */
   async scrapeLinkElements(selectors = ['nav a', 'header a', '[role="navigation"] a']) {
@@ -210,11 +123,9 @@ export class BaseDiscoverer {
         const href = el.getAttribute('href');
         if (!href) return;
 
-        // Skip non-http links
         if (href.startsWith('mailto:') || href.startsWith('tel:') ||
             href.startsWith('javascript:') || href === '#') return;
 
-        // Skip external links
         try {
           const url = new URL(href, origin);
           if (url.origin !== origin) return;

package/src/route-discoverers/index.js

@@ -63,7 +63,7 @@ export async function discoverRoutes(page, baseUrl, frameworkInfo = null) {
 
   if (!frameworkInfo) {
     try {
-      const { detectFramework } = await import('../core/framework-detector.js');
+      const { detectFramework } = await import('../core/detection/framework-detector.js');
       const info = await detectFramework(page);
       detectedFramework = info.framework;
     } catch {

package/src/shared/config.js

@@ -0,0 +1,38 @@
+/**
+ * Centralized configuration constants for design-clone
+ * Single source of truth for timeouts, size limits, and CDN URLs
+ */
+
+/** Browser timing constants (ms) */
+export const TIMING = {
+  VIEWPORT_SETTLE_DELAY: 1500,
+  NETWORK_IDLE_TIMEOUT: 8000,
+  POST_NAVIGATION_DELAY: 3000,
+  POST_RESIZE_DELAY: 2000,
+  VERIFICATION_DELAY: 500,
+};
+
+/** Size limits (bytes) */
+export const SIZE_LIMITS = {
+  MAX_CSS_INPUT: 50 * 1024 * 1024,   // 50MB (supports large enterprise CSS)
+  MAX_STATE: 1024 * 1024,             // 1MB
+  CSS_CHUNK_THRESHOLD: 2 * 1024 * 1024, // 2MB: use chunked processing above this
+};
+
+/** Browser context pool defaults */
+export const POOL = {
+  MAX_BROWSER_CONTEXTS: 3,
+  MIN_FREE_MEMORY_MB: 500,
+};
+
+/** CDN URLs */
+export const CDN = {
+  FONT_AWESOME_VERSION: '6.5.1',
+  FONT_AWESOME_CSS: 'https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css',
+  GOSNAP_WIDGET_VERSION: '1.0.1',
+};
+
+/** Layout constants */
+export const LAYOUT = {
+  SIDEBAR_MAX_WIDTH: 400,
+};

package/src/shared/error-codes.js

@@ -0,0 +1,31 @@
+/**
+ * Structured error catalog for design-clone.
+ * Descriptive codes for easy parsing by LLM agents.
+ */
+
+export const ERROR_CODES = {
+  CSS_SIZE_EXCEEDED: { message: 'CSS file exceeds size limit', suggestion: 'Split CSS or increase SIZE_LIMITS.MAX_CSS_INPUT in config.js' },
+  CSS_PARSE_FAILED: { message: 'CSS parse failed', suggestion: 'Check for syntax errors in source CSS. Try --verbose for details' },
+  CSS_CORS_BLOCKED: { message: 'Stylesheet blocked by CORS', suggestion: 'Site restricts cross-origin CSS access. Inline styles still captured' },
+  HTML_EXTRACTION_FAILED: { message: 'HTML extraction failed', suggestion: 'Page may use heavy JS rendering. Try increasing --scroll-delay' },
+  ASSET_DOWNLOAD_FAILED: { message: 'Asset download failed', suggestion: 'Check network connectivity. CORS or auth may block downloads' },
+  BROWSER_LAUNCH_FAILED: { message: 'Browser launch failed', suggestion: 'Run: npx playwright install chromium' },
+  NAV_TIMEOUT: { message: 'Page navigation timeout', suggestion: 'Site may be slow. Try increasing timeout or check URL' },
+  FILE_IO_FAILED: { message: 'File read/write failed', suggestion: 'Check file permissions and disk space' },
+  DISCOVERY_FAILED: { message: 'Page discovery failed', suggestion: 'Site may block bots. Try with --no-spa-detect' },
+  SCREENSHOT_FAILED: { message: 'Screenshot capture failed', suggestion: 'Page may have infinite scroll. Try --full-page false' },
+  INVALID_ARGS: { message: 'Invalid arguments', suggestion: 'Run: design-clone help' },
+};
+
+export class DesignCloneError extends Error {
+  constructor(code, context = {}) {
+    const def = ERROR_CODES[code] || { message: 'Unknown error', suggestion: '' };
+    super(def.message);
+    this.code = code;
+    this.suggestion = def.suggestion;
+    this.context = context;
+    this.name = 'DesignCloneError';
+  }
+}
+
+export function createError(code, context) { return new DesignCloneError(code, context); }

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

@@ -8,9 +8,6 @@
  * - getPage(browser)
  * - closeBrowser()
  * - disconnectBrowser()
- * - parseArgs(argv)
- * - outputJSON(data)
- * - outputError(error)
  */
 
 let browserModule = null;
@@ -27,10 +24,6 @@ async function initProvider() {
   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} 'playwright'

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

@@ -8,82 +8,16 @@
  * - Compatible API with previous Puppeteer wrapper
  */
 
-import fs from 'fs';
+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;
-/** @type {typeof import('playwright')|null} */
-let playwright = null;
 
 /** Default viewport dimensions */
-const DEFAULT_VIEWPORT = { width: 1920, height: 1080 };
-
-/**
- * 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
- */
-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;
-}
-
-/**
- * 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
- */
-async function loadPlaywright() {
-  if (playwright) return playwright;
-
-  try {
-    // Try full playwright first (includes bundled browsers)
-    playwright = await import('playwright');
-    return playwright;
-  } catch (e1) {
-    try {
-      // Fall back to playwright-core (requires Chrome)
-      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}`
-      );
-    }
-  }
-}
+const DEFAULT_VIEWPORT = { width: VIEWPORTS_HD.desktop.width, height: VIEWPORTS_HD.desktop.height };
 
 /**
  * Launch browser instance

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;
+}