design-clone 1.2.0 → 2.3.0

package/src/core/capture/multi-page-screenshot-page.js

@@ -0,0 +1,110 @@
+/**
+ * Multi-Page Screenshot: Per-Page Capture
+ *
+ * Single-page capture logic: navigate and take viewport screenshots.
+ * Called once per page by captureMultiplePages.
+ *
+ * @module multi-page-screenshot-page
+ */
+
+import path from 'path';
+import fs from 'fs/promises';
+
+import { captureViewport } from './screenshot-viewport.js';
+import { VIEWPORTS, DEFAULT_SCROLL_DELAY } from './screenshot-helpers.js';
+import { waitForDomStable, waitForPageReady } from '../page-prep/page-readiness.js';
+import { dismissCookieBanner } from '../page-prep/cookie-handler.js';
+
+export const DEFAULT_OPTIONS = {
+  viewports: ['desktop', 'tablet', 'mobile'],
+  fullPage: true,
+  maxSize: 5,
+  scrollDelay: DEFAULT_SCROLL_DELAY,
+  timeout: 60000,
+  onProgress: null
+};
+
+/** Convert URL path to kebab-case filename ('/about' → 'about', '/' → 'index'). */
+export function pathToFilename(pagePath) {
+  if (!pagePath || pagePath === '/') return 'index';
+  return pagePath
+    .replace(/^\//, '')
+    .replace(/\/$/, '')
+    .replace(/\//g, '-')
+    .replace(/[^a-z0-9-]/gi, '-')
+    .replace(/-+/g, '-')
+    .toLowerCase();
+}
+
+/** Create outputDir + analysis/{viewport}/ subdirectories. */
+export async function createOutputStructure(outputDir, viewports) {
+  const dirs = [
+    outputDir,
+    ...viewports.map(vp => path.join(outputDir, 'analysis', vp))
+  ];
+  for (const dir of dirs) {
+    await fs.mkdir(dir, { recursive: true });
+  }
+}
+
+/** Capture all configured viewport screenshots for one page. Returns {screenshots, warnings}. */
+async function capturePageViewports(page, outputDir, filename, options) {
+  const screenshots = {};
+  const warnings = [];
+
+  for (const viewport of options.viewports) {
+    if (!VIEWPORTS[viewport]) {
+      warnings.push(`Invalid viewport: ${viewport}`);
+      continue;
+    }
+    try {
+      const screenshotPath = path.join(outputDir, 'analysis', viewport, `${filename}.png`);
+      const vpResult = await captureViewport({
+        page,
+        viewport,
+        outputPath: screenshotPath,
+        fullPage: options.fullPage,
+        maxSize: options.maxSize,
+        scrollDelay: options.scrollDelay
+      });
+      screenshots[viewport] = {
+        path: vpResult.path,
+        size: vpResult.size,
+        compressed: vpResult.compressed
+      };
+    } catch (err) {
+      warnings.push(`${viewport} capture failed: ${err.message}`);
+      screenshots[viewport] = { error: err.message, failed: true };
+    }
+  }
+
+  return { screenshots, warnings };
+}
+
+/**
+ * Navigate to one page and take viewport screenshots.
+ * @param {import('playwright').Page} page
+ * @param {{path, name, url}} pageInfo
+ * @param {string} outputDir
+ * @param {Object} options
+ * @returns {Promise<{path, name, url, filename, screenshots, warnings, success, error?}>}
+ */
+export async function captureSinglePage(page, pageInfo, outputDir, options) {
+  const filename = pathToFilename(pageInfo.path);
+  const result = { path: pageInfo.path, name: pageInfo.name, url: pageInfo.url, filename, screenshots: {}, warnings: [] };
+
+  try {
+    await page.goto(pageInfo.url, { waitUntil: 'networkidle', timeout: options.timeout });
+    await waitForPageReady(page);
+    await dismissCookieBanner(page).catch(() => {});
+    await waitForDomStable(page, 300, 3000);
+
+    const { screenshots, warnings: vpW } = await capturePageViewports(page, outputDir, filename, options);
+    result.screenshots = screenshots; result.warnings.push(...vpW);
+    result.success = true;
+  } catch (err) {
+    result.success = false; result.error = err.message;
+    result.warnings.push(`Page capture failed: ${err.message}`);
+  }
+  return result;
+}

package/src/core/capture/multi-page-screenshot.js

@@ -0,0 +1,208 @@
+/**
+ * Multi-page Screenshot Capture
+ *
+ * Capture multi-viewport screenshots for multiple pages
+ * using a shared browser session for efficiency.
+ *
+ * Usage:
+ *   import { captureMultiplePages } from './multi-page-screenshot.js';
+ *   const result = await captureMultiplePages(pages, { outputDir: './output' });
+ */
+
+import path from 'path';
+import fs from 'fs/promises';
+
+import { getBrowser, getPage, disconnectBrowser } from '../../utils/browser.js';
+import {
+  captureSinglePage,
+  createOutputStructure,
+  pathToFilename,
+  DEFAULT_OPTIONS
+} from './multi-page-screenshot-page.js';
+import { BrowserContextPool } from './browser-context-pool.js';
+
+// ============================================================================
+// Batch Capture
+// ============================================================================
+
+/**
+ * Capture multiple pages with shared browser session
+ * @param {Array<{path: string, name: string, url: string}>} pages - Pages to capture
+ * @param {Object} options - Capture options (merged with DEFAULT_OPTIONS)
+ * @returns {Promise<Object>} Complete capture result with per-page results and stats
+ */
+export async function captureMultiplePages(pages, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const startTime = Date.now();
+
+  if (!opts.outputDir) throw new Error('outputDir is required');
+
+  await createOutputStructure(opts.outputDir, opts.viewports);
+
+  let browser = null;
+  const results = {
+    success: true,
+    baseUrl: pages[0]?.url ? new URL(pages[0].url).origin : null,
+    outputDir: path.resolve(opts.outputDir),
+    pages: [],
+    stats: {
+      totalPages: pages.length,
+      successfulPages: 0,
+      failedPages: 0,
+      totalScreenshots: 0,
+      totalWarnings: 0
+    },
+    capturedAt: new Date().toISOString()
+  };
+
+  try {
+    browser = await getBrowser({ headless: true });
+    const concurrency = opts.concurrency || 3;
+
+    // Try parallel capture with context pool
+    let usePool = concurrency > 1 && pages.length > 1;
+    if (usePool) {
+      try {
+        const pool = new BrowserContextPool(browser, { maxContexts: concurrency });
+        const pageResults = new Array(pages.length);
+
+        const pagePromises = pages.map(async (pageInfo, i) => {
+          const { context, page } = await pool.acquire();
+          try {
+            if (opts.onProgress) {
+              opts.onProgress(i + 1, pages.length, { path: pageInfo.path, name: pageInfo.name, status: 'capturing' });
+            }
+            pageResults[i] = await captureSinglePage(page, pageInfo, opts.outputDir, opts);
+            if (opts.onProgress) {
+              opts.onProgress(i + 1, pages.length, { path: pageInfo.path, name: pageInfo.name, status: 'done' });
+            }
+          } finally {
+            await pool.release(context);
+          }
+        });
+
+        await Promise.allSettled(pagePromises);
+        await pool.drain();
+
+        for (const pageResult of pageResults) {
+          if (!pageResult) { results.stats.failedPages++; continue; }
+          results.pages.push(pageResult);
+          if (pageResult.success) {
+            results.stats.successfulPages++;
+            results.stats.totalScreenshots += Object.keys(pageResult.screenshots)
+              .filter(vp => !pageResult.screenshots[vp].failed).length;
+          } else {
+            results.stats.failedPages++;
+          }
+          results.stats.totalWarnings += pageResult.warnings?.length || 0;
+        }
+      } catch {
+        // Pool failed, fall back to sequential
+        usePool = false;
+      }
+    }
+
+    // Sequential fallback (single page or pool failure)
+    if (!usePool) {
+      for (let i = 0; i < pages.length; i++) {
+        const pageInfo = pages[i];
+        if (opts.onProgress) {
+          opts.onProgress(i + 1, pages.length, { path: pageInfo.path, name: pageInfo.name, status: 'capturing' });
+        }
+        const page = await getPage(browser);
+        try {
+          const pageResult = await captureSinglePage(page, pageInfo, opts.outputDir, opts);
+          results.pages.push(pageResult);
+          if (pageResult.success) {
+            results.stats.successfulPages++;
+            results.stats.totalScreenshots += Object.keys(pageResult.screenshots)
+              .filter(vp => !pageResult.screenshots[vp].failed).length;
+          } else {
+            results.stats.failedPages++;
+          }
+          results.stats.totalWarnings += pageResult.warnings.length;
+          if (opts.onProgress) {
+            opts.onProgress(i + 1, pages.length, { path: pageInfo.path, name: pageInfo.name, status: 'done' });
+          }
+        } finally {
+          await page.close().catch(() => {});
+        }
+      }
+    }
+  } catch (err) {
+    results.success = false;
+    results.error = err.message;
+  } finally {
+    if (browser) await disconnectBrowser().catch(() => {});
+  }
+
+  results.stats.totalTimeMs = Date.now() - startTime;
+
+  const resultsPath = path.join(opts.outputDir, 'capture-results.json');
+  await fs.writeFile(resultsPath, JSON.stringify(results, null, 2));
+  results.resultsFile = resultsPath;
+
+  return results;
+}
+
+// ============================================================================
+// Re-exports (backward-compatible)
+// ============================================================================
+
+export { pathToFilename };
+
+// ============================================================================
+// CLI Entry Point
+// ============================================================================
+
+const isMainModule = process.argv[1] && (
+  process.argv[1].endsWith('multi-page-screenshot.js') ||
+  process.argv[1].includes('multi-page-screenshot')
+);
+
+if (isMainModule) {
+  const url = process.argv[2];
+  const outputDir = process.argv[3] || './multi-capture-output';
+
+  if (!url) {
+    console.error('Usage: node multi-page-screenshot.js <url> [outputDir]');
+    process.exit(1);
+  }
+
+  import('../discovery/discover-pages.js').then(async ({ discoverPages, estimateCapture }) => {
+    console.error(`[INFO] Discovering pages from ${url}...`);
+    const discovery = await discoverPages(url, { maxPages: 5 });
+
+    if (!discovery.success) {
+      console.error(`[ERROR] Discovery failed: ${discovery.error}`);
+      process.exit(1);
+    }
+
+    console.error(`[INFO] Found ${discovery.pages.length} pages`);
+
+    // Dry-run: show discovery + estimate, exit without capture
+    if (process.argv.includes('--dry-run')) {
+      const estimate = estimateCapture(discovery.pages);
+      console.log(JSON.stringify({
+        dryRun: true,
+        discovery: { pages: discovery.pages, framework: discovery.framework },
+        estimate,
+        hint: 'Remove --dry-run to execute capture'
+      }, null, 2));
+      process.exit(0);
+    }
+
+    const result = await captureMultiplePages(discovery.pages, {
+      outputDir,
+      onProgress: (current, total, info) => {
+        console.error(`[${current}/${total}] ${info.status}: ${info.name} (${info.path})`);
+      }
+    });
+
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.success ? 0 : 1);
+  }).catch(err => {
+    console.error(`[ERROR] ${err.message}`);
+    process.exit(1);
+  });
+}

package/src/core/capture/screenshot-extraction.js

@@ -0,0 +1,186 @@
+/**
+ * Screenshot Extraction
+ *
+ * HTML, CSS, and animation extraction pipeline used during multi-viewport
+ * screenshot capture. Handles content counting, semantic enhancement,
+ * CSS filtering, and animation token generation.
+ *
+ * @module screenshot-extraction
+ */
+
+import path from 'path';
+import fs from 'fs/promises';
+
+import { filterCssFile } from '../css/filter-css.js';
+import { extractCleanHtml, extractAndEnhanceHtml, JS_FRAMEWORK_PATTERNS, MAX_HTML_SIZE } from '../html/html-extractor.js';
+import { extractContentCounts, generateContentSummary } from '../content/content-counter.js';
+import { extractAllCss, MAX_CSS_SIZE } from '../css/css-extractor.js';
+import { extractAnimations, generateAnimationsCss, generateAnimationTokens } from '../animation/animation-extractor.js';
+import { logInfo, logWarn, isTTY } from '../../utils/log.js';
+import { createProgress } from '../../utils/progress.js';
+
+/** Extract and write content counts (grids, repeated items) to output dir. */
+export async function runContentCounting(page, output) {
+  const contentCounts = await extractContentCounts(page);
+  const countsPath = path.join(output, 'content-counts.json');
+  await fs.writeFile(countsPath, JSON.stringify(contentCounts, null, 2), 'utf-8');
+  const contentSummary = generateContentSummary(contentCounts);
+  const summaryPath = path.join(output, 'content-summary.md');
+  await fs.writeFile(summaryPath, contentSummary, 'utf-8');
+  logInfo(`Content counts: ${contentCounts.grids.total} grids, ${contentCounts.repeatedItems.total} items`);
+  return { path: path.resolve(countsPath), summaryPath: path.resolve(summaryPath), summary: contentCounts.summary };
+}
+
+/** Extract and write page HTML (with optional semantic enhancement). */
+export async function runHtmlExtraction(page, output, enhanceSemantic) {
+  const htmlResult = enhanceSemantic
+    ? await extractAndEnhanceHtml(page, { enhanceSemantic: true })
+    : await extractCleanHtml(page, JS_FRAMEWORK_PATTERNS);
+  const html = htmlResult.html;
+  const htmlSize = Buffer.byteLength(html, 'utf-8');
+  if (htmlSize > MAX_HTML_SIZE) throw new Error(`HTML size exceeds ${MAX_HTML_SIZE / 1024 / 1024}MB limit`);
+  const htmlPath = path.join(output, 'source.html');
+  await fs.writeFile(htmlPath, html, 'utf-8');
+  return { path: path.resolve(htmlPath), size: htmlSize, elementCount: htmlResult.elementCount, semanticEnhanced: enhanceSemantic, semanticStats: htmlResult.semanticStats || null, warnings: htmlResult.warnings || [] };
+}
+
+/** Extract and write all page CSS (inline + linked stylesheets). */
+export async function runCssExtraction(page, url, output) {
+  const cssData = await extractAllCss(page, url);
+  const rawCss = cssData.cssBlocks.map(b => `/* Source: ${b.source} */\n${b.css}`).join('\n\n');
+  const cssSize = Buffer.byteLength(rawCss, 'utf-8');
+
+  if (cssSize > MAX_CSS_SIZE) {
+    throw new Error(`CSS size exceeds ${MAX_CSS_SIZE / 1024 / 1024}MB limit`);
+  }
+
+  const rawCssPath = path.join(output, 'source-raw.css');
+  await fs.writeFile(rawCssPath, rawCss, 'utf-8');
+  if (Object.keys(cssData.computedStyles).length > 0) {
+    await fs.writeFile(path.join(output, 'computed-styles.json'), JSON.stringify(cssData.computedStyles, null, 2));
+  }
+  return { path: path.resolve(rawCssPath), size: cssSize, blocks: cssData.cssBlocks.length, totalRules: cssData.totalRules, corsBlocked: cssData.corsBlocked, computedStyles: cssData.computedStyles, warnings: cssData.warnings || [] };
+}
+
+/** Filter CSS against HTML to remove unused selectors. */
+export async function runCssFiltering(htmlPath, cssPath, output, aggressiveFilter = false) {
+  const filteredCssPath = path.join(output, 'source.css');
+  const fr = await filterCssFile(htmlPath, cssPath, filteredCssPath, false, output, aggressiveFilter);
+  logInfo(`CSS filtered: ${fr.stats.reduction} reduction`);
+  return { path: fr.output.path, size: fr.output.size, reduction: fr.stats.reduction, stats: { totalRules: fr.stats.totalRules, keptRules: fr.stats.keptRules, removedRules: fr.stats.removedRules } };
+}
+
+/** Extract animation keyframes, transitions, and tokens from CSS file. */
+export async function runAnimationExtraction(cssFilePath, output) {
+  const rawCss = await fs.readFile(cssFilePath, 'utf-8');
+  const animData = await extractAnimations(rawCss);
+  if (animData.error) throw new Error(animData.error);
+
+  const animPath = path.join(output, 'animations.css');
+  await fs.writeFile(animPath, generateAnimationsCss(animData), 'utf-8');
+  const animTokens = generateAnimationTokens(animData);
+  const animTokensPath = path.join(output, 'animation-tokens.json');
+  await fs.writeFile(animTokensPath, JSON.stringify({ keyframes: animData.keyframes, transitions: animData.transitions, animatedElements: animData.animatedElements, summary: animTokens }, null, 2), 'utf-8');
+  logInfo(`Animations: ${animTokens.keyframeCount} keyframes, ${animTokens.transitions} transitions`);
+  return { path: path.resolve(animPath), tokensPath: path.resolve(animTokensPath), keyframeCount: animTokens.keyframeCount, transitionCount: animTokens.transitions, animatedElementCount: animTokens.animatedElements, tokens: animTokens };
+}
+
+/**
+ * Run the full extraction pipeline: content counts, HTML, CSS, filter, animations.
+ * @param {import('playwright').Page} page
+ * @param {string} url - Page URL
+ * @param {string} output - Output directory
+ * @param {{extractHtml, extractCss, filterUnused, enhanceSemantic, extractAnimations: boolean}} opts
+ * @returns {Promise<Object>} extraction object with html/css/filtered/animations/warnings
+ */
+export async function runExtractionPipeline(page, url, output, opts) {
+  const { extractHtml, extractCss, filterUnused, enhanceSemantic, extractAnimations: extractAnimsFlag } = opts;
+  const extraction = { html: null, css: null, warnings: [] };
+  const extractionWarnings = [];
+
+  const progress = createProgress();
+  const stepCount = [extractHtml && 'content', extractHtml && 'html', extractCss && 'css', filterUnused && 'filter', extractAnimsFlag && 'animations'].filter(Boolean).length;
+  progress.start(stepCount, 'Extraction pipeline');
+
+  // Content counts (before HTML cleanup)
+  if (extractHtml) {
+    progress.step('Content counting');
+    try {
+      extraction.contentCounts = await runContentCounting(page, output);
+    } catch (error) {
+      extractionWarnings.push(`Content counting failed: ${error.message}`);
+    }
+  }
+
+  if (extractHtml) {
+    progress.step('HTML extraction');
+    try {
+      const r = await runHtmlExtraction(page, output, enhanceSemantic);
+      const { warnings, ...htmlData } = r;
+      extraction.html = htmlData;
+      if (warnings.length > 0) extractionWarnings.push(...warnings);
+    } catch (error) {
+      extraction.html = { error: error.message, failed: true };
+      extractionWarnings.push(`HTML extraction failed: ${error.message}`);
+    }
+  }
+
+  if (extractCss) {
+    progress.step('CSS extraction');
+    try {
+      const r = await runCssExtraction(page, url, output);
+      const { warnings, ...cssData } = r;
+      extraction.css = cssData;
+      if (warnings.length > 0) extractionWarnings.push(...warnings);
+      if (r.corsBlocked.length > 0) extractionWarnings.push(`${r.corsBlocked.length} CORS-blocked stylesheets`);
+    } catch (error) {
+      extraction.css = { error: error.message, failed: true };
+      extractionWarnings.push(`CSS extraction failed: ${error.message}`);
+    }
+  }
+
+  if (filterUnused && extraction?.html?.path && extraction?.css?.path &&
+      !extraction.html.failed && !extraction.css.failed) {
+    progress.step('CSS filtering');
+    try {
+      extraction.filtered = await runCssFiltering(extraction.html.path, extraction.css.path, output, opts.aggressiveFilter);
+    } catch (error) {
+      extraction.filtered = { error: error.message, failed: true };
+      extractionWarnings.push(`CSS filtering failed: ${error.message}`);
+    }
+  }
+
+  // Computed style gap-fill (opt-in via --extract-computed)
+  if (opts.extractComputed && extraction?.filtered?.path && !extraction.filtered.failed) {
+    try {
+      const { extractComputedGapFill } = await import('../css/computed-style-extractor.js');
+      const filteredCss = await fs.readFile(extraction.filtered.path, 'utf-8');
+      const computed = await extractComputedGapFill(page, filteredCss);
+      const computedPath = path.join(output, 'computed-gap.css');
+      await fs.writeFile(computedPath, computed.css, 'utf-8');
+      extraction.computedGap = { path: path.resolve(computedPath), ...computed.stats };
+      logInfo(`Computed gap-fill: ${computed.rules} rules for ${computed.stats.elementsAnalyzed} elements`);
+    } catch (error) {
+      extraction.computedGap = { error: error.message, failed: true };
+      extractionWarnings.push(`Computed style extraction failed: ${error.message}`);
+    }
+  }
+
+  if (extractCss && extractAnimsFlag && extraction?.css?.path && !extraction.css.failed) {
+    progress.step('Animation extraction');
+    try {
+      extraction.animations = await runAnimationExtraction(extraction.css.path, output);
+    } catch (error) {
+      extraction.animations = { error: error.message, failed: true };
+      extractionWarnings.push(`Animation extraction failed: ${error.message}`);
+    }
+  }
+
+  progress.complete(`${stepCount} steps completed`);
+
+  extraction.warnings = extractionWarnings;
+  if (extractionWarnings.length > 0) {
+    extractionWarnings.forEach(w => logWarn(w));
+  }
+  return extraction;
+}

package/src/core/capture/screenshot-helpers.js

@@ -0,0 +1,175 @@
+/**
+ * Screenshot Helpers
+ *
+ * CLI argument parsing, browser lifecycle management, and image compression
+ * utilities used by the screenshot capture pipeline.
+ *
+ * @module screenshot-helpers
+ */
+
+import fs from 'fs/promises';
+
+import { filterCssFile } from '../css/filter-css.js';
+import { getBrowser, getPage, closeBrowser } from '../../utils/browser.js';
+import { parseArgs, outputError } from '../../utils/helpers.js';
+import { waitForPageReady } from '../page-prep/page-readiness.js';
+import { dismissCookieBanner } from '../page-prep/cookie-handler.js';
+import { VIEWPORTS } from '../../shared/viewports.js';
+import { TIMING } from '../../shared/config.js';
+
+export { filterCssFile, VIEWPORTS };
+
+export const VIEWPORT_SETTLE_DELAY = TIMING.VIEWPORT_SETTLE_DELAY;
+export const NETWORK_IDLE_TIMEOUT = TIMING.NETWORK_IDLE_TIMEOUT;
+export const DEFAULT_SCROLL_DELAY = 1500;
+
+// Try to import Sharp for compression
+let sharp = null;
+try {
+  sharp = (await import('sharp')).default;
+} catch {
+  // Sharp not available
+}
+
+/**
+ * Parse and validate screenshot command arguments
+ * @param {string[]} argv - Raw CLI arguments
+ * @returns {Object} Parsed and validated options
+ */
+export function parseScreenshotArgs(argv) {
+  const args = parseArgs(argv);
+  const { url, output } = args;
+
+  if (!url) {
+    outputError(new Error('--url is required'));
+    process.exit(1);
+  }
+  if (!output) {
+    outputError(new Error('--output directory is required'));
+    process.exit(1);
+  }
+
+  const requestedViewports = args.viewports
+    ? args.viewports.split(',').map(v => v.trim().toLowerCase())
+    : ['desktop', 'tablet', 'mobile'];
+
+  for (const vp of requestedViewports) {
+    if (!VIEWPORTS[vp]) {
+      outputError(new Error(`Invalid viewport: ${vp}. Valid: desktop, tablet, mobile`));
+      process.exit(1);
+    }
+  }
+
+  return {
+    url: url,
+    output: output,
+    viewports: requestedViewports,
+    fullPage: args['full-page'] !== 'false',
+    maxSize: args['max-size'] ? parseFloat(args['max-size']) : 5,
+    scrollDelay: args['scroll-delay'] ? parseInt(args['scroll-delay'], 10) : DEFAULT_SCROLL_DELAY,
+    extractHtml: args['extract-html'] === 'true',
+    extractCss: args['extract-css'] === 'true',
+    filterUnused: args['filter-unused'] !== 'false',
+    captureHover: args['capture-hover'] === 'true',
+    captureVideo: args['video'] === 'true',
+    videoFormat: args['video-format'] || 'webm',
+    videoDuration: args['video-duration'] ? parseInt(args['video-duration'], 10) : 12000,
+    sectionMode: args['section-mode'] === 'true',
+    enhanceSemantic: args['no-semantic'] !== 'true',
+    extractAnimations: args['extract-animations'] !== 'false',
+    detectBreakpoints: args['detect-breakpoints'] === 'true',
+    extractComputed: args['extract-computed'] === 'true',
+    aggressiveFilter: args['aggressive-filter'],
+    headless: args.headless === 'true',
+    close: args.close === 'true'
+  };
+}
+
+/**
+ * Create browser manager for handling browser lifecycle
+ * @param {boolean} cliHeadless - CLI headless flag
+ * @returns {Object} Browser manager with init/cleanup methods
+ */
+export function createBrowserManager(cliHeadless) {
+  let browser = null;
+  let page = null;
+  let currentHeadless = null;
+  let cookieResult = null;
+
+  const getHeadlessForViewport = (viewport) => viewport === 'desktop' ? true : cliHeadless;
+
+  const init = async (headless, navigateUrl = null) => {
+    if (browser && currentHeadless !== headless) {
+      await closeBrowser();
+      browser = null;
+      page = null;
+    }
+
+    if (!browser) {
+      browser = await getBrowser({
+        headless,
+        args: headless ? [] : ['--start-maximized', '--window-position=0,0']
+      });
+      page = await getPage(browser);
+      currentHeadless = headless;
+
+      if (navigateUrl) {
+        await page.setViewportSize(VIEWPORTS.desktop);
+        await page.goto(navigateUrl, { waitUntil: 'domcontentloaded', timeout: 90000 });
+        await new Promise(r => setTimeout(r, 3000));
+        cookieResult = await dismissCookieBanner(page);
+        await waitForPageReady(page);
+      }
+    }
+    return { browser, page };
+  };
+
+  return {
+    init,
+    getHeadlessForViewport,
+    getPage: () => page,
+    getCookieResult: () => cookieResult,
+    getCurrentHeadless: () => currentHeadless,
+    setCurrentHeadless: (val) => { currentHeadless = val; }
+  };
+}
+
+/**
+ * Compress image if it exceeds max size
+ * @param {string} filePath - Path to the image file
+ * @param {number} [maxSizeMB=5] - Max size in MB
+ * @returns {Promise<Object>} Compression result
+ */
+export async function compressIfNeeded(filePath, maxSizeMB = 5) {
+  const stats = await fs.stat(filePath);
+  const originalSize = stats.size;
+  const maxBytes = maxSizeMB * 1024 * 1024;
+
+  if (originalSize <= maxBytes || !sharp) {
+    return { compressed: false, originalSize, finalSize: originalSize };
+  }
+
+  try {
+    const buffer = await fs.readFile(filePath);
+    const meta = await sharp(buffer).metadata();
+
+    const newWidth = Math.round(meta.width * 0.85);
+    let output = await sharp(buffer)
+      .resize(newWidth)
+      .png({ quality: 80, compressionLevel: 9 })
+      .toBuffer();
+
+    if (output.length > maxBytes) {
+      const smallerWidth = Math.round(meta.width * 0.7);
+      output = await sharp(buffer)
+        .resize(smallerWidth)
+        .png({ quality: 70, compressionLevel: 9 })
+        .toBuffer();
+    }
+
+    await fs.writeFile(filePath, output);
+    return { compressed: true, originalSize, finalSize: output.length };
+  } catch (err) {
+    return { compressed: false, originalSize, finalSize: originalSize, error: err.message };
+  }
+}