webgl-forensics 3.1.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "webgl-forensics",
+  "version": "3.1.0",
+  "description": "The definitive 24-phase reverse engineering engine for WebGL, Three.js, GSAP, and animated websites. Clone any site.",
+  "bin": {
+    "webgl-forensics": "puppeteer-runner.js"
+  },
+  "scripts": {
+    "forensics": "node puppeteer-runner.js",
+    "test": "node puppeteer-runner.js https://example.com --dry-run",
+    "lint": "node -e \"require('./puppeteer-runner.js')\" 2>&1 || true"
+  },
+  "keywords": [
+    "webgl",
+    "three.js",
+    "gsap",
+    "forensics",
+    "reverse-engineering",
+    "website-cloning",
+    "shader-extraction",
+    "scroll-animation",
+    "puppeteer",
+    "r3f",
+    "react-three-fiber",
+    "design-tokens",
+    "framer-motion",
+    "lenis"
+  ],
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "inquirer": "^9.3.8",
+    "lighthouse": "^13.0.3",
+    "ora": "^8.2.0",
+    "puppeteer": "^22.0.0",
+    "puppeteer-screen-recorder": "^3.0.6"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "author": "404kidwiz",
+  "license": "MIT",
+  "homepage": "https://github.com/404kidwiz/webgl-forensics#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/404kidwiz/webgl-forensics.git"
+  },
+  "bugs": {
+    "url": "https://github.com/404kidwiz/webgl-forensics/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/project summary.md

@@ -0,0 +1,33 @@
+# WebGL Forensics (v3.1)
+
+## Overview
+WebGL Forensics is the definitive reverse engineering engine for WebGL, Three.js, GSAP, and complex animated websites. It acts as an automated "site cloner" and forensics tool for developers who want to understand or reconstruct high-end Awwwards-style sites. It leverages Puppeteer to seamlessly analyze page payloads, intercept WebGL shaders, capture GSAP timelines, and serialize React-Three-Fiber (R3F) fiber trees.
+
+With the release of v3.1, WebGL Forensics shifts from merely being an analysis tool into being an **actionable scaffolding engine** that can auto-generate the foundation of a modern Next.js 15 site from the extracted design, animation, and 3D data.
+
+## Value Proposition
+Instead of manually inspecting the network tab for shaders or trying to guess easing curves for scroll animations, developers can run this CLI and instantly get:
+1. **Design Tokens**: Standardized CSS variables extracted from the target DOM.
+2. **Animation Signatures**: Hard data on `gsap.to()` calls including durations and triggers.
+3. **3D Assets & Logic**: GLSL shaders (vertex + fragment) and the physical tree structure of Three.js scenes.
+4. **Instant Scaffolding**: Automatically built `Next.js` setups integrating `lenis`, `gsap`, and `@react-three/fiber` wired specifically to replicate the target site.
+5. **AI Guides**: Formatted system prompts designed to assist Claude/Gemini in reconstructing the exact UI and Logic based on forensic data.
+
+## Core v3.1 Additions
+- **Sitemap Crawler** (`22-sitemap-crawler.js`): Intelligent crawler prioritizing links found in `/sitemap.xml` with automatic DOM-scraping fallback.
+- **Next.js Scaffold Generator** (`23-scaffold-generator.js`): Parses forensic JSON and auto-generates a boilerplate React framework folder pre-configured with the exact libraries detected (e.g. framer-motion, R3F, gsap).
+- **AI Reconstruction** (`24-ai-reconstruction.js`): Automatically packages forensic metadata and GLSL dumps into a Claude-ready "Here is a website, write the code to clone it" prompt.
+- **Shader Annotator** (`25-shader-annotator.js`): Identifies common GLSL patterns offline and passes ambiguous shaders to local or remote AI for mathematical annotation.
+- **TUI Dashboard** (`tui.js`): Terminal user interface using Ink/Chalk with real-time feedback on forensics progress instead of raw logs.
+
+## Quick Start
+```bash
+# Full automated run with scaffolding and AI prep
+npx webgl-forensics https://example.com --scaffold --ai-report --screenshots --sitemap
+
+# Interactive CLI mode
+npx webgl-forensics --interactive
+```
+
+## Architecture Notes
+The engine runs scripts consecutively in a headless browser context by injecting them into the DOM (`page.evaluate()`) to access core objects like `window.__THREE__`, `window.gsap`, or `WebGLRenderingContext.prototype.shaderSource`. Data is aggregated into a central `forensics-report-[domain].json` which drives the secondary AI and scaffolding steps.

package/puppeteer-runner.js

@@ -0,0 +1,486 @@
+#!/usr/bin/env node
+/**
+ * webgl-forensics — Standalone Puppeteer Runner v3.1
+ * The definitive 24-phase forensics engine for WebGL, GSAP, R3F, and animated sites.
+ *
+ * USAGE:
+ *   npx webgl-forensics [URL] [options]
+ *   node puppeteer-runner.js [URL] [options]
+ *
+ * ─── FLAGS ────────────────────────────────────────────────────────────────────
+ *
+ * v3.1 (new):
+ *   --interactive                 Interactive TUI — configure run from terminal menu
+ *   --scaffold                    Generate a Next.js 15 starter project from forensics
+ *   --ai-report                   Generate AI Claude/Gemini reconstruction report (needs API key)
+ *   --annotate-shaders            AI-annotate extracted GLSL shaders (needs API key)
+ *   --sitemap                     Use sitemap.xml for page discovery instead of DOM crawl
+ *
+ * v3.0:
+ *   --compare [URL]               Diff against a local clone URL
+ *   --record                      Record an MP4 of the scroll session
+ *   --download-assets             Download GLB, WOFF2, HDR assets
+ *   --format [json|html]          Output format (default: json)
+ *   --history                     Persist run metrics to local JSON history
+ *
+ * v2.0:
+ *   --focus [3d|animations|scroll|layout|all]
+ *   --output [path]               Output directory (default: ./forensics-output)
+ *   --headless / --no-headless    Browser mode
+ *   --screenshots                 Capture scroll screenshots
+ *   --multipage                   Crawl all internal pages
+ *   --timeout [ms]                Navigation timeout (default: 30000)
+ *   --dry-run                     Show what would run without fetching
+ *
+ * ──────────────────────────────────────────────────────────────────────────────
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+// ═══════════════════════════════════════════════════════
+// OPTIONAL V3 DEPS — graceful fallback if not installed
+// ═══════════════════════════════════════════════════════
+let PuppeteerScreenRecorder;
+try { PuppeteerScreenRecorder = require('puppeteer-screen-recorder').PuppeteerScreenRecorder; } catch {}
+
+let runLighthouseAudit;
+try { runLighthouseAudit = require('./scripts/21-lighthouse-audit.js'); } catch {}
+
+let generateTimelineHtml;
+try { generateTimelineHtml = require('./scripts/20-timeline-visualizer.js'); } catch {}
+
+// V3.1 modules
+let generateScaffold;
+try { generateScaffold = require('./scripts/23-scaffold-generator.js'); } catch {}
+
+let generateReconstructionReport;
+try { generateReconstructionReport = require('./scripts/24-ai-reconstruction.js'); } catch {}
+
+let annotateShaders;
+try { annotateShaders = require('./scripts/25-shader-annotator.js'); } catch {}
+
+let tuiModule;
+try { tuiModule = require('./tui.js'); } catch {}
+
+// ═══════════════════════════════════════════════════════
+// ARG PARSING
+// ═══════════════════════════════════════════════════════
+const rawArgs = process.argv.slice(2);
+let targetUrl = rawArgs.find(a => a.startsWith('http'));
+
+function argVal(flag, def, args = rawArgs) {
+  const idx = args.indexOf(flag);
+  return idx !== -1 && args[idx + 1] && !args[idx + 1].startsWith('--') ? args[idx + 1] : def;
+}
+function hasFlag(flag) { return rawArgs.includes(flag); }
+
+let opts = {
+  focus: argVal('--focus', 'all'),
+  output: argVal('--output', './forensics-output'),
+  headless: !hasFlag('--no-headless'),
+  screenshots: hasFlag('--screenshots'),
+  multipage: hasFlag('--multipage'),
+  sitemap: hasFlag('--sitemap'),
+  timeout: parseInt(argVal('--timeout', '30000'), 10),
+  dryRun: hasFlag('--dry-run'),
+  interactive: hasFlag('--interactive'),
+  // V3.0
+  compareUrl: argVal('--compare', null),
+  record: hasFlag('--record'),
+  downloadAssets: hasFlag('--download-assets'),
+  formatHtml: argVal('--format', 'json') === 'html',
+  history: hasFlag('--history'),
+  // V3.1
+  scaffold: hasFlag('--scaffold'),
+  aiReport: hasFlag('--ai-report'),
+  annotateShaders: hasFlag('--annotate-shaders'),
+};
+
+// ═══════════════════════════════════════════════════════
+// HELP / DRY-RUN
+// ═══════════════════════════════════════════════════════
+if (!targetUrl && !opts.interactive && !opts.dryRun) {
+  console.log(`
+╔══════════════════════════════════════════════════════════╗
+║  webgl-forensics v3.1 — The Site Reverse-Engineering CLI  ║
+╚══════════════════════════════════════════════════════════╝
+
+  BASIC:       npx webgl-forensics https://site.com
+  INTERACTIVE: npx webgl-forensics --interactive
+  COMPARE:     npx webgl-forensics https://site.com --compare http://localhost:3000
+  SCAFFOLD:    npx webgl-forensics https://site.com --scaffold --ai-report
+  SHADERS:     npx webgl-forensics https://site.com --annotate-shaders --no-headless
+  FULL RUN:    npx webgl-forensics https://site.com --scaffold --ai-report --screenshots --sitemap
+
+  Run with --interactive for an interactive configuration menu.
+  Run with --dry-run to preview phases without fetching.
+`);
+  process.exit(0);
+}
+
+if (opts.dryRun) {
+  console.log('📋 DRY RUN — would analyze:', targetUrl || '(no URL given)');
+  console.log('   Focus:', opts.focus);
+  console.log('   Scaffold:', opts.scaffold);
+  console.log('   AI Report:', opts.aiReport);
+  console.log('   Sitemap:', opts.sitemap);
+  console.log('   Compare:', opts.compareUrl || 'None');
+  process.exit(0);
+}
+
+// ═══════════════════════════════════════════════════════
+// SCRIPT LOADER
+// ═══════════════════════════════════════════════════════
+const SCRIPTS_DIR = path.join(__dirname, 'scripts');
+
+function loadScript(filename) {
+  const p = path.join(SCRIPTS_DIR, filename);
+  if (!fs.existsSync(p)) throw new Error(`Script not found: ${p}`);
+  return fs.readFileSync(p, 'utf-8');
+}
+
+function getPhases(focus) {
+  const all = [
+    { name: 'loading-sequence',     script: '05-loading-sequence.js',               focus: ['all', '3d', 'animations'] },
+    { name: 'tech-stack',           script: '00-tech-stack-detect.js',              focus: ['all', '3d', 'animations', 'scroll', 'layout'] },
+    { name: 'source-maps',          script: '01-source-map-extractor.js',           focus: ['all'] },
+    { name: 'sitemap-crawler',      script: '22-sitemap-crawler.js',                focus: ['all', 'layout'] },
+    { name: 'network-waterfall',    script: '12-network-waterfall.js',              focus: ['all', 'layout'] },
+    { name: 'react-fiber-walker',   script: '13-react-fiber-walker.js',             focus: ['all', '3d'] },
+    { name: 'r3f-serializer',       script: '17-r3f-fiber-serializer.js',           focus: ['all', '3d'] },
+    { name: 'shader-hotpatch',      script: '14-shader-hotpatch.js',                focus: ['all', '3d'] },
+    { name: 'webgpu-extractor',     script: '10-webgpu-extractor.js',              focus: ['all', '3d'] },
+    { name: 'gsap-timeline',        script: '16-gsap-timeline-recorder.js',         focus: ['all', 'animations', 'scroll'] },
+    { name: 'interaction-model',    script: '02-interaction-model.js',              focus: ['all', 'animations'] },
+    { name: 'page-transitions',     script: '04-page-transitions.js',              focus: ['all', 'animations'] },
+    { name: 'font-extractor',       script: '18-font-extractor.js',                focus: ['all', 'layout'] },
+    { name: 'design-token-export',  script: '19-design-token-export.js',           focus: ['all', 'layout'] },
+    { name: 'responsive-analysis',  script: '03-responsive-analysis.js',            focus: ['all', 'layout'] },
+    { name: 'audio-extraction',     script: '06-audio-extraction.js',              focus: ['all'] },
+    { name: 'accessibility',        script: '07-accessibility-reduced-motion.js',  focus: ['all'] },
+    { name: 'complexity-scorer',    script: '08-complexity-scorer.js',             focus: ['all'] },
+    { name: 'visual-diff',          script: '09-visual-diff-validator.js',         focus: ['all'] },
+  ];
+
+  // Plugin discovery
+  if (fs.existsSync(SCRIPTS_DIR)) {
+    for (const f of fs.readdirSync(SCRIPTS_DIR)) {
+      if (f.startsWith('custom-') && f.endsWith('.js')) {
+        all.push({ name: f.replace('.js', ''), script: f, focus: ['all'] });
+      }
+    }
+  }
+
+  return focus === 'all' ? all : all.filter(p => p.focus.includes(focus));
+}
+
+// ═══════════════════════════════════════════════════════
+// HISTORY
+// ═══════════════════════════════════════════════════════
+function writeHistory(report, outputDir) {
+  if (!opts.history) return;
+  const histFile = path.join(outputDir, 'run-history.json');
+  let history = [];
+  if (fs.existsSync(histFile)) {
+    try { history = JSON.parse(fs.readFileSync(histFile, 'utf8')); } catch {}
+  }
+  history.push({
+    url: report.meta.url,
+    timestamp: report.meta.timestamp,
+    complexity: report.meta.phases['complexity-scorer']?.score || 0,
+    tech: Object.keys(report.meta.phases['tech-stack']?.detected || {}).filter(k => report.meta.phases['tech-stack'].detected[k]),
+  });
+  fs.writeFileSync(histFile, JSON.stringify(history, null, 2));
+}
+
+// ═══════════════════════════════════════════════════════
+// DIFF
+// ═══════════════════════════════════════════════════════
+function calculateDiff(source, clone) {
+  const scoreDiff = Math.abs(
+    (source.meta.phases['complexity-scorer']?.score || 0) -
+    (clone.meta.phases['complexity-scorer']?.score || 0)
+  );
+  const srcTech = Object.keys(source.meta.phases['tech-stack']?.detected || {}).filter(k => source.meta.phases['tech-stack'].detected[k]);
+  const clnTech = Object.keys(clone.meta.phases['tech-stack']?.detected || {}).filter(k => clone.meta.phases['tech-stack'].detected[k]);
+  return {
+    fidelityScore: Math.max(0, 100 - scoreDiff * 0.5),
+    techOverlap: srcTech.filter(t => clnTech.includes(t)),
+    missingInClone: srcTech.filter(t => !clnTech.includes(t)),
+  };
+}
+
+// ═══════════════════════════════════════════════════════
+// MAIN ANALYZER
+// ═══════════════════════════════════════════════════════
+async function analyzeUrl(url, browser, isCompare = false, renderer = null) {
+  const domain = new URL(url).hostname.replace(/[^a-z0-9]/gi, '-');
+  const ts = new Date().toISOString().slice(0, 16).replace(/[:T]/g, '-');
+  const dirName = isCompare ? `compare-${domain}-${ts}` : `${domain}-${ts}`;
+  const outputDir = path.resolve(opts.output, dirName);
+  fs.mkdirSync(outputDir, { recursive: true });
+
+  const log = renderer
+    ? (msg) => renderer.log(msg)
+    : (msg) => console.log(`[${new Date().toLocaleTimeString()}] [${isCompare ? 'CLONE' : 'SRC'}] ${msg}`);
+
+  log(`Analyzing: ${url}`);
+  const page = await browser.newPage();
+
+  // VIDEO RECORDING
+  let recorder;
+  if (opts.record && PuppeteerScreenRecorder && !isCompare) {
+    log('Starting video recording...');
+    recorder = new PuppeteerScreenRecorder(page, { format: 'mp4' });
+    await recorder.start(path.join(outputDir, 'scroll-recording.mp4'));
+  }
+
+  // ASSET DOWNLOAD INTERCEPTOR
+  if (opts.downloadAssets) {
+    const assetsDir = path.join(outputDir, 'assets');
+    fs.mkdirSync(assetsDir, { recursive: true });
+    page.on('response', async (response) => {
+      const rUrl = response.url();
+      const ext = rUrl.split('.').pop()?.split('?')[0]?.toLowerCase();
+      if (['glb', 'gltf', 'woff2', 'hdr', 'ttf', 'exr'].includes(ext)) {
+        try {
+          const buf = await response.buffer();
+          const fname = rUrl.split('/').pop().split('?')[0];
+          fs.writeFileSync(path.join(assetsDir, fname), buf);
+          log(`Downloaded: ${fname}`);
+        } catch {}
+      }
+    });
+  }
+
+  // SHADER HOTPATCH (pre-navigation)
+  try {
+    const shaderScript = loadScript('14-shader-hotpatch.js');
+    await page.evaluateOnNewDocument(shaderScript);
+  } catch {}
+
+  log('Navigating...');
+  await page.goto(url, { waitUntil: 'networkidle2', timeout: opts.timeout });
+  await page.waitForTimeout(3000);
+
+  const report = {
+    meta: { url, domain, timestamp: new Date().toISOString(), focus: opts.focus, phases: {} },
+    errors: [],
+  };
+
+  // ── RUN ALL PHASES ──────────────────────────────────
+  const phases = getPhases(opts.focus);
+  for (const phase of phases) {
+    if (renderer) renderer.start(phase.name, `Running ${phase.name}...`);
+    try {
+      const script = loadScript(phase.script);
+      const result = await page.evaluate(new Function(`
+        try { return eval(${JSON.stringify(script)}) }
+        catch(e) { return { error: e.message, phase: '${phase.name}' }; }
+      `));
+      report.meta.phases[phase.name] = result;
+      fs.writeFileSync(path.join(outputDir, `${phase.name}.json`), JSON.stringify(result, null, 2));
+
+      const detail = getPhaseDetail(phase.name, result);
+      if (renderer) renderer.succeed(phase.name, detail);
+      else log(`✓ ${phase.name}${detail ? ` — ${detail}` : ''}`);
+    } catch (err) {
+      report.errors.push(`Phase ${phase.name}: ${err.message}`);
+      if (renderer) renderer.fail(phase.name, err.message);
+      else log(`✗ ${phase.name} failed: ${err.message}`);
+    }
+  }
+
+  // ── LIGHTHOUSE ─────────────────────────────────────
+  if (opts.lighthouse !== false && runLighthouseAudit) {
+    log('Running Lighthouse audit...');
+    try {
+      const wsPort = new URL(browser.wsEndpoint()).port;
+      const lhResult = await runLighthouseAudit(url, wsPort);
+      report.meta.phases['lighthouse'] = lhResult;
+      fs.writeFileSync(path.join(outputDir, 'lighthouse.json'), JSON.stringify(lhResult, null, 2));
+    } catch (e) {
+      log(`Lighthouse failed: ${e.message}`);
+    }
+  }
+
+  // ── SCROLL (screenshots / recording) ───────────────
+  if (opts.screenshots || (opts.record && !isCompare)) {
+    const totalH = await page.evaluate(() => document.documentElement.scrollHeight);
+    const viewH = 900;
+    const steps = 10;
+    const ssDir = path.join(outputDir, 'screenshots');
+    if (opts.screenshots) fs.mkdirSync(ssDir, { recursive: true });
+
+    for (let i = 0; i <= steps; i++) {
+      const pct = i / steps;
+      await page.evaluate(y => window.scrollTo({ top: y, behavior: 'smooth' }), Math.round(pct * (totalH - viewH)));
+      await page.waitForTimeout(1000);
+      if (opts.screenshots) {
+        await page.screenshot({ path: path.join(ssDir, `scroll-${Math.round(pct * 100)}pct.png`) });
+      }
+    }
+    await page.evaluate(() => window.scrollTo({ top: 0, behavior: 'smooth' }));
+    await page.waitForTimeout(1000);
+  }
+
+  if (recorder) await recorder.stop();
+
+  // ── HTML TIMELINE ───────────────────────────────────
+  if (opts.formatHtml && generateTimelineHtml) {
+    const html = generateTimelineHtml(report.meta.phases['gsap-timeline']?.keyTimelines || []);
+    fs.writeFileSync(path.join(outputDir, 'timeline.html'), html);
+    log('Generated timeline.html');
+  }
+
+  // ── V3.1: SHADER ANNOTATION ─────────────────────────
+  if (opts.annotateShaders && annotateShaders) {
+    log('Annotating shaders with AI...');
+    try {
+      const shaderData = report.meta.phases['shader-hotpatch'];
+      const annotations = await annotateShaders(shaderData);
+      report.meta.phases['shader-annotations'] = annotations;
+      fs.writeFileSync(path.join(outputDir, 'shader-annotations.json'), JSON.stringify(annotations, null, 2));
+      log(`Annotated ${annotations.length} shader(s)`);
+    } catch (e) {
+      log(`Shader annotation failed: ${e.message}`);
+    }
+  }
+
+  // ── V3.1: SCAFFOLD ──────────────────────────────────
+  if (opts.scaffold && generateScaffold && !isCompare) {
+    log('Generating Next.js scaffold...');
+    try {
+      const result = generateScaffold(report, outputDir);
+      report.meta.scaffold = result;
+      log(`Scaffold generated: ${result.filesGenerated} files → ${result.scaffoldDir}`);
+    } catch (e) {
+      log(`Scaffold failed: ${e.message}`);
+    }
+  }
+
+  // ── V3.1: AI RECONSTRUCTION REPORT ─────────────────
+  if (opts.aiReport && generateReconstructionReport && !isCompare) {
+    log('Generating AI reconstruction report...');
+    try {
+      const md = await generateReconstructionReport(report);
+      const mdPath = path.join(outputDir, 'reconstruction-guide.md');
+      fs.writeFileSync(mdPath, md);
+      log(`AI report saved: reconstruction-guide.md`);
+    } catch (e) {
+      log(`AI report failed: ${e.message}`);
+    }
+  }
+
+  // ── WRITE MASTER REPORT ─────────────────────────────
+  fs.writeFileSync(path.join(outputDir, 'forensics-report.json'), JSON.stringify(report, null, 2));
+  await page.close();
+  writeHistory(report, opts.output);
+
+  return { report, outputDir };
+}
+
+function getPhaseDetail(name, result) {
+  if (!result || result.error) return result?.error || '';
+  switch (name) {
+    case 'tech-stack': return Object.keys(result.detected || {}).filter(k => result.detected[k]).join(', ') || '';
+    case 'gsap-timeline': return `${result.tweens?.length || 0} tweens, ${result.scrollTriggers?.length || 0} STs`;
+    case 'react-fiber-walker': return `${result.componentCount || 0} components`;
+    case 'r3f-serializer': return result.canvasCount ? `${result.canvasCount} canvas(es)` : '';
+    case 'complexity-scorer': return result.score ? `score: ${result.score}/100` : '';
+    case 'sitemap-crawler': return result.sitemapFound ? `${result.data?.total || 0} URLs` : 'no sitemap (DOM fallback)';
+    case 'font-extractor': return result.webFonts?.length ? `${result.webFonts.length} fonts` : '';
+    case 'design-token-export': return result.cssVariables?.length ? `${result.cssVariables.length} vars` : '';
+    default: return '';
+  }
+}
+
+// ═══════════════════════════════════════════════════════
+// ENTRY POINT
+// ═══════════════════════════════════════════════════════
+async function run() {
+  // ── INTERACTIVE MODE ─────────────────────────────────
+  if (opts.interactive && tuiModule) {
+    const { promptConfig, createPhaseRenderer, loadModules } = tuiModule;
+    const { chalk, ora, inquirer } = await loadModules();
+    const config = await promptConfig(inquirer, chalk);
+
+    // Merge TUI config into opts
+    Object.assign(opts, config);
+    targetUrl = config.url;
+
+    // Override opts with TUI selections
+    opts.output = config.output;
+
+    let puppeteer;
+    try { puppeteer = require('puppeteer'); }
+    catch { console.error('Puppeteer not installed.'); process.exit(1); }
+
+    const browser = await puppeteer.launch({
+      headless: opts.headless ? 'new' : false,
+      defaultViewport: { width: 1440, height: 900, deviceScaleFactor: 2 },
+      args: ['--no-sandbox', '--disable-setuid-sandbox', '--enable-webgl', '--enable-webgl2', '--use-gl=desktop', '--enable-unsafe-webgpu'],
+    });
+
+    const renderer = createPhaseRenderer(chalk, ora);
+    const { report, outputDir } = await analyzeUrl(targetUrl, browser, false, renderer);
+
+    if (opts.compareUrl) {
+      const { report: cloneReport, outputDir: cloneDir } = await analyzeUrl(opts.compareUrl, browser, true, renderer);
+      const diff = calculateDiff(report, cloneReport);
+      fs.writeFileSync(path.join(outputDir, 'comparison-diff.json'), JSON.stringify(diff, null, 2));
+      renderer.log(`🏆 Fidelity Score: ${diff.fidelityScore.toFixed(1)}/100`);
+    }
+
+    renderer.complete(report, outputDir, chalk);
+    await browser.close();
+    return;
+  }
+
+  // ── CLI MODE ─────────────────────────────────────────
+  let puppeteer;
+  try { puppeteer = require('puppeteer'); }
+  catch { console.error('❌ Puppeteer not installed. Run: npm install puppeteer'); process.exit(1); }
+
+  console.log(`\n╔══════════════════════════════════╗`);
+  console.log(`║  webgl-forensics v3.1 — Running  ║`);
+  console.log(`╚══════════════════════════════════╝\n`);
+
+  const browser = await puppeteer.launch({
+    headless: opts.headless ? 'new' : false,
+    defaultViewport: { width: 1440, height: 900, deviceScaleFactor: 2 },
+    args: [
+      '--no-sandbox', '--disable-setuid-sandbox',
+      '--enable-webgl', '--enable-webgl2', '--use-gl=desktop',
+      '--enable-features=WebGL2ComputeContext',
+      '--enable-unsafe-webgpu', '--enable-features=WebGPU',
+    ],
+  });
+
+  const { report: sourceReport, outputDir: sourceDir } = await analyzeUrl(targetUrl, browser, false);
+
+  if (opts.compareUrl) {
+    console.log(`\n⚖️  COMPARING WITH: ${opts.compareUrl}`);
+    const { report: cloneReport } = await analyzeUrl(opts.compareUrl, browser, true);
+    const diff = calculateDiff(sourceReport, cloneReport);
+    fs.writeFileSync(path.join(sourceDir, 'comparison-diff.json'), JSON.stringify(diff, null, 2));
+    console.log(`\n🏆 FIDELITY SCORE: ${diff.fidelityScore.toFixed(1)}/100`);
+    console.log(`✅ Tech Overlap: ${diff.techOverlap.join(', ') || 'None'}`);
+    console.log(`❌ Missing in clone: ${diff.missingInClone.join(', ') || 'None'}`);
+  }
+
+  console.log(`\n✅ Done! Output: ${sourceDir}`);
+  if (sourceReport.meta.scaffold) {
+    console.log(`🏗️  Scaffold: ${sourceReport.meta.scaffold.scaffoldDir} (${sourceReport.meta.scaffold.filesGenerated} files)`);
+  }
+
+  await browser.close();
+}
+
+run().catch(err => {
+  console.error('❌ Fatal:', err.message);
+  process.exit(1);
+});