webgl-forensics 3.1.0

package/scripts/24-ai-reconstruction.js

@@ -0,0 +1,226 @@
+/**
+ * webgl-forensics — AI Reconstruction Report Generator (Script 24)
+ *
+ * Node.js module (NOT a browser script). Called by the runner after forensics
+ * completes. Pipes the forensics JSON to an AI (Claude or Gemini via API) and
+ * returns a human-readable "how to rebuild this site" guide.
+ *
+ * REQUIRES: ANTHROPIC_API_KEY or GEMINI_API_KEY in environment.
+ */
+
+const https = require('https');
+
+/**
+ * Compress the large forensics report into a focused prompt payload.
+ * We cherry-pick the highest-signal data to stay under token limits.
+ */
+function buildPromptPayload(report) {
+  const phases = report?.meta?.phases || {};
+
+  const techStack = phases['tech-stack'] || {};
+  const gsap = phases['gsap-timeline'] || {};
+  const tokens = phases['design-token-export'] || {};
+  const fonts = phases['font-extractor'] || {};
+  const scroll = phases['interaction-model'] || {};
+  const r3f = phases['r3f-serializer'] || {};
+  const fiber = phases['react-fiber-walker'] || {};
+  const complexity = phases['complexity-scorer'] || {};
+  const loading = phases['loading-sequence'] || {};
+  const lighthouse = phases['lighthouse'] || {};
+  const transitions = phases['page-transitions'] || {};
+
+  return {
+    url: report?.meta?.url,
+    framework: techStack?.framework,
+    libraries: techStack?.libraries,
+    animations: techStack?.animations,
+    scroll: techStack?.scroll,
+    gsap: {
+      version: gsap?.version,
+      tweenCount: gsap?.tweens?.length,
+      scrollTriggerCount: gsap?.scrollTriggers?.length,
+      sampleTweens: (gsap?.tweens || []).slice(0, 5),
+      sampleSTs: (gsap?.scrollTriggers || []).slice(0, 5),
+    },
+    designTokens: {
+      colorCount: tokens?.colors?.length,
+      sampleColors: (tokens?.colors || []).slice(0, 10),
+      bodyFont: tokens?.bodyStyles?.fontFamily,
+      bodyBg: tokens?.bodyStyles?.backgroundColor,
+    },
+    fonts: (fonts?.webFonts || []).slice(0, 8),
+    r3fTree: r3f?.jsxTree ? r3f.jsxTree.substring(0, 1500) : null,
+    canvas: fiber?.canvasConfig,
+    complexity: complexity?.score,
+    complexityBreakdown: complexity?.breakdown,
+    lighthouse: {
+      performance: lighthouse?.categories?.performance?.score,
+      accessibility: lighthouse?.categories?.accessibility?.score,
+    },
+    loading: {
+      hasPreloader: loading?.hasPreloader,
+      preloaderSelector: loading?.preloaderSelector,
+    },
+    pageTransitions: transitions?.detected,
+  };
+}
+
+function buildPrompt(payload) {
+  return `You are a senior creative frontend engineer specializing in WebGL, Three.js, GSAP, and high-fidelity site reconstruction.
+
+Below is a structured forensics report for the website: ${payload.url}
+
+Your task: Write a concrete, actionable "Reconstruction Guide" that a developer can follow to rebuild this site from scratch. Be specific — reference actual values from the data.
+
+## FORENSICS DATA:
+${JSON.stringify(payload, null, 2)}
+
+## OUTPUT STRUCTURE:
+Return a detailed Markdown document with these sections:
+
+### 1. Site Overview
+- What this site is and who it's likely built for
+- Stack summary (framework, rendering, animation system)
+- Complexity rating and what drives it
+
+### 2. Project Setup
+- Exact \`npx create-next-app\` command or equivalent
+- Dependencies to install with exact npm/pnpm commands
+- File structure overview
+
+### 3. Design System
+- Color palette from tokens (actual hex values)
+- Typography (font families, weights, sizes)
+- How to set up the CSS variables
+- Tailwind config snippet if applicable
+
+### 4. Animation System
+- GSAP setup code (version, plugins to register)
+- How ScrollTrigger is used (pin sections, scrub, etc.)
+- Sample tween reconstructions based on the data
+- Lenis/smooth scroll config if detected
+
+### 5. 3D / WebGL Layer
+- Three.js / R3F scene setup
+- Key geometries and materials detected
+- Camera configuration
+- Any shader patterns identified
+
+### 6. Loading & Transitions
+- Preloader implementation approach
+- Page transition system
+- Initial animation sequence
+
+### 7. Critical Implementation Notes
+- Gotchas, performance tips, order of operations
+- What NOT to do when rebuilding this specific site
+
+Be specific. Use code blocks. Reference the actual values from the JSON. Don't be generic.`;
+}
+
+/**
+ * Call Claude API (Anthropic)
+ */
+async function callClaude(prompt, apiKey) {
+  return new Promise((resolve, reject) => {
+    const body = JSON.stringify({
+      model: 'claude-opus-4-5',
+      max_tokens: 4096,
+      messages: [{ role: 'user', content: prompt }],
+    });
+
+    const req = https.request({
+      hostname: 'api.anthropic.com',
+      path: '/v1/messages',
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+        'Content-Length': Buffer.byteLength(body),
+      },
+    }, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        try {
+          const parsed = JSON.parse(data);
+          if (parsed.error) return reject(new Error(parsed.error.message));
+          resolve(parsed.content?.[0]?.text || '');
+        } catch (e) {
+          reject(e);
+        }
+      });
+    });
+
+    req.on('error', reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+/**
+ * Call Gemini API (Google)
+ */
+async function callGemini(prompt, apiKey) {
+  return new Promise((resolve, reject) => {
+    const body = JSON.stringify({
+      contents: [{ parts: [{ text: prompt }] }],
+      generationConfig: { maxOutputTokens: 4096 },
+    });
+
+    const req = https.request({
+      hostname: 'generativelanguage.googleapis.com',
+      path: `/v1beta/models/gemini-1.5-pro:generateContent?key=${apiKey}`,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+      },
+    }, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        try {
+          const parsed = JSON.parse(data);
+          if (parsed.error) return reject(new Error(parsed.error.message));
+          resolve(parsed.candidates?.[0]?.content?.parts?.[0]?.text || '');
+        } catch (e) {
+          reject(e);
+        }
+      });
+    });
+
+    req.on('error', reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+/**
+ * Main export — generate the AI reconstruction report.
+ * @param {Object} report - Full forensics report object
+ * @returns {Promise<string>} Markdown content of the reconstruction guide
+ */
+async function generateReconstructionReport(report) {
+  const anthropicKey = process.env.ANTHROPIC_API_KEY;
+  const geminiKey = process.env.GEMINI_API_KEY;
+
+  if (!anthropicKey && !geminiKey) {
+    return `# AI Reconstruction Report — Skipped\n\nNo API key found. Set \`ANTHROPIC_API_KEY\` or \`GEMINI_API_KEY\` to generate this report.\n\nRaw forensics data is saved in \`forensics-report.json\`.`;
+  }
+
+  const payload = buildPromptPayload(report);
+  const prompt = buildPrompt(payload);
+
+  let markdown = '';
+  if (anthropicKey) {
+    markdown = await callClaude(prompt, anthropicKey);
+  } else if (geminiKey) {
+    markdown = await callGemini(prompt, geminiKey);
+  }
+
+  return markdown;
+}
+
+module.exports = generateReconstructionReport;

package/scripts/25-shader-annotator.js

@@ -0,0 +1,226 @@
+/**
+ * webgl-forensics — Shader GLSL Annotator (Script 25)
+ *
+ * Node.js module. Called by the runner when shader source code is found.
+ * Sends each shader's GLSL to an AI and returns a structured annotation:
+ *  - What it does visually
+ *  - The math pattern (Voronoi, FBM, SDF, etc.)
+ *  - Key uniforms and what they control
+ *  - A simplified "recipe" a dev can follow to recreate it
+ */
+
+const https = require('https');
+
+const MATH_PATTERNS = [
+  { pattern: /fbm|fBm|fractal.*brownian|octave/i, name: 'Fractional Brownian Motion (fBm)', desc: 'Layered noise for organic, cloud-like textures' },
+  { pattern: /voronoi|worley/i, name: 'Voronoi / Worley Noise', desc: 'Cell-based patterns for geometric, cracked-surface effects' },
+  { pattern: /sdf|signed.*distance|distanceField/i, name: 'Signed Distance Field (SDF)', desc: 'Math-driven shapes — clean edges, morphing, ray marching' },
+  { pattern: /perlin|simplex/i, name: 'Perlin / Simplex Noise', desc: 'Smooth gradient noise for flowing, organic motion' },
+  { pattern: /ray.*march|rayMarch|render.*sphere/i, name: 'Ray Marching', desc: 'Volumetric 3D rendering entirely in the fragment shader' },
+  { pattern: /chromatic.*aberation|rgb.*split|rgbShift/i, name: 'Chromatic Aberration', desc: 'RGB channel splitting for lens distortion effect' },
+  { pattern: /blur|gaussian|bokeh/i, name: 'Blur / Bokeh', desc: 'Sample-based blurring for depth of field or post-processing' },
+  { pattern: /ripple|wave.*distort|distortion/i, name: 'Wave Distortion', desc: 'UV displacement for liquid or heat shimmer effects' },
+  { pattern: /hsl|hsv|rgb2hsl|hue.*rotate/i, name: 'Color Space Manipulation', desc: 'HSL/HSV color shifting for palette effects' },
+  { pattern: /dither|threshold.*pattern/i, name: 'Dithering', desc: 'Ordered or random pixel patterns for retro/lo-fi effects' },
+  { pattern: /metaball|blob|merge.*sphere/i, name: 'Metaballs / Isosurface', desc: 'Organic blobs that merge and separate' },
+  { pattern: /glitch|block.*displace|scanline/i, name: 'Glitch Effect', desc: 'Digital corruption, block displacement, scan lines' },
+  { pattern: /particle|point.*sprite|billboard/i, name: 'Particle System', desc: 'Per-particle position/color animation in the shader' },
+];
+
+/**
+ * Detect math patterns from GLSL source without AI (fast, offline)
+ */
+function detectPatternsLocally(glsl) {
+  const detected = [];
+  for (const { pattern, name, desc } of MATH_PATTERNS) {
+    if (pattern.test(glsl)) {
+      detected.push({ name, desc });
+    }
+  }
+  return detected;
+}
+
+/**
+ * Extract uniform declarations from GLSL
+ */
+function extractUniforms(glsl) {
+  const uniformRegex = /uniform\s+([\w]+)\s+([\w]+)\s*(?:=\s*[^;]+)?;/g;
+  const uniforms = [];
+  let match;
+  while ((match = uniformRegex.exec(glsl)) !== null) {
+    uniforms.push({ type: match[1], name: match[2] });
+  }
+  return uniforms;
+}
+
+/**
+ * Extract varying declarations
+ */
+function extractVaryings(glsl) {
+  const varyingRegex = /varying\s+([\w]+)\s+([\w]+)\s*;/g;
+  const varyings = [];
+  let match;
+  while ((match = varyingRegex.exec(glsl)) !== null) {
+    varyings.push({ type: match[1], name: match[2] });
+  }
+  return varyings;
+}
+
+/**
+ * Build a structured prompt for a single shader
+ */
+function buildShaderPrompt(shader) {
+  const maxGlslLength = 3000;
+  const truncated = shader.source.length > maxGlslLength;
+  const glslSnippet = shader.source.substring(0, maxGlslLength);
+
+  return `You are an expert WebGL/GLSL engineer and creative technologist.
+
+Analyze this ${shader.type} shader and provide a detailed breakdown.
+
+## SHADER TYPE: ${shader.type.toUpperCase()}
+## UNIFORMS: ${JSON.stringify(shader.uniforms)}
+## DETECTED PATTERN HINTS: ${shader.localPatterns.map(p => p.name).join(', ') || 'None auto-detected'}
+## GLSL SOURCE${truncated ? ' (truncated)' : ''}:
+\`\`\`glsl
+${glslSnippet}
+${truncated ? '\n// ... (truncated)' : ''}
+\`\`\`
+
+Respond with a JSON object with these exact keys:
+{
+  "visualEffect": "1-2 sentence description of what this shader produces visually",
+  "mathPattern": "Primary mathematical technique used (e.g., Fractional Brownian Motion, SDF Ray Marching, Voronoi)",
+  "complexity": "simple|moderate|complex|advanced",
+  "uniforms": [
+    { "name": "uniformName", "role": "What this uniform controls visually" }
+  ],
+  "keyFunctions": ["List of notable custom functions and what they do"],
+  "recreationRecipe": "Step-by-step instructions to recreate this effect (4-8 steps)",
+  "similarExamples": ["Names of well-known effects/sites that use a similar technique"],
+  "performance": "Note about performance characteristics (vertex count, texture samples, etc.)"
+}
+
+Return ONLY valid JSON. No markdown fences.`;
+}
+
+async function callAI(prompt) {
+  const anthropicKey = process.env.ANTHROPIC_API_KEY;
+  const geminiKey = process.env.GEMINI_API_KEY;
+
+  if (!anthropicKey && !geminiKey) return null;
+
+  return new Promise((resolve) => {
+    const useAnthropic = !!anthropicKey;
+    const apiKey = anthropicKey || geminiKey;
+
+    const body = useAnthropic
+      ? JSON.stringify({
+          model: 'claude-haiku-4-5',
+          max_tokens: 1024,
+          messages: [{ role: 'user', content: prompt }],
+        })
+      : JSON.stringify({
+          contents: [{ parts: [{ text: prompt }] }],
+          generationConfig: { maxOutputTokens: 1024 },
+        });
+
+    const options = useAnthropic
+      ? {
+          hostname: 'api.anthropic.com',
+          path: '/v1/messages',
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'x-api-key': apiKey,
+            'anthropic-version': '2023-06-01',
+            'Content-Length': Buffer.byteLength(body),
+          },
+        }
+      : {
+          hostname: 'generativelanguage.googleapis.com',
+          path: `/v1beta/models/gemini-1.5-flash:generateContent?key=${apiKey}`,
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Content-Length': Buffer.byteLength(body),
+          },
+        };
+
+    const req = https.request(options, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        try {
+          const parsed = JSON.parse(data);
+          const text = useAnthropic
+            ? parsed.content?.[0]?.text
+            : parsed.candidates?.[0]?.content?.parts?.[0]?.text;
+          if (text) {
+            try { resolve(JSON.parse(text)); } catch { resolve({ raw: text }); }
+          } else {
+            resolve(null);
+          }
+        } catch { resolve(null); }
+      });
+    });
+
+    req.on('error', () => resolve(null));
+    req.write(body);
+    req.end();
+  });
+}
+
+/**
+ * Main export — annotate all shaders in the forensics report
+ * @param {Object} sheaderData - Output of shader-hotpatch phase
+ * @returns {Promise<Array>} Array of annotated shader objects
+ */
+async function annotateShaders(shaderData) {
+  const shaders = [];
+
+  // Collect shaders from report
+  const programs = shaderData?.interceptedPrograms || shaderData?.programs || [];
+
+  for (const prog of programs) {
+    const types = ['vertex', 'fragment'];
+    for (const type of types) {
+      const source = prog[`${type}Shader`] || prog[`${type}Source`];
+      if (!source || source.length < 50) continue;
+
+      const shader = {
+        id: prog.id || shaders.length,
+        type,
+        source,
+        uniforms: extractUniforms(source),
+        varyings: extractVaryings(source),
+        localPatterns: detectPatternsLocally(source),
+        lineCount: source.split('\n').length,
+      };
+
+      shaders.push(shader);
+    }
+  }
+
+  if (shaders.length === 0) {
+    return [{
+      note: 'No intercepted shader source found.',
+      hint: 'Ensure --no-headless is used and the site renders WebGL before extraction.',
+    }];
+  }
+
+  const hasApiKey = process.env.ANTHROPIC_API_KEY || process.env.GEMINI_API_KEY;
+
+  if (hasApiKey) {
+    // Annotate each shader with AI (limit to first 5 to control API cost)
+    const toAnnotate = shaders.slice(0, 5);
+    for (const shader of toAnnotate) {
+      const prompt = buildShaderPrompt(shader);
+      shader.aiAnnotation = await callAI(prompt);
+    }
+  }
+
+  return shaders;
+}
+
+module.exports = annotateShaders;

package/tui.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+/**
+ * webgl-forensics — Interactive TUI
+ * Uses inquirer + chalk + ora for a rich terminal dashboard experience.
+ * Called when --interactive flag is passed.
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+// Dynamic imports for ESM-only packages (chalk v5, ora v8)
+async function loadModules() {
+  const { default: chalk } = await import('chalk');
+  const { default: ora } = await import('ora');
+  const { default: inquirer } = await import('inquirer');
+  return { chalk, ora, inquirer };
+}
+
+const PHASES = [
+  { id: 'loading-sequence',    label: '⚡ Loading Sequence',      script: '05-loading-sequence.js' },
+  { id: 'tech-stack',          label: '🔍 Tech Stack Detection',  script: '00-tech-stack-detect.js' },
+  { id: 'source-maps',         label: '🗺️  Source Maps',           script: '01-source-map-extractor.js' },
+  { id: 'sitemap-crawler',     label: '🗂️  Sitemap Crawler',       script: '22-sitemap-crawler.js' },
+  { id: 'network-waterfall',   label: '🌊 Network Waterfall',     script: '12-network-waterfall.js' },
+  { id: 'react-fiber-walker',  label: '⚛️  React Fiber Walker',    script: '13-react-fiber-walker.js' },
+  { id: 'r3f-serializer',      label: '🎲 R3F Serializer',        script: '17-r3f-fiber-serializer.js' },
+  { id: 'shader-hotpatch',     label: '✨ Shader Hot-Patch',      script: '14-shader-hotpatch.js' },
+  { id: 'gsap-timeline',       label: '🎬 GSAP Timeline',         script: '16-gsap-timeline-recorder.js' },
+  { id: 'interaction-model',   label: '👆 Interaction Model',     script: '02-interaction-model.js' },
+  { id: 'page-transitions',    label: '↔️  Page Transitions',      script: '04-page-transitions.js' },
+  { id: 'font-extractor',      label: '🔤 Font Extractor',        script: '18-font-extractor.js' },
+  { id: 'design-token-export', label: '🎨 Design Tokens',         script: '19-design-token-export.js' },
+  { id: 'responsive-analysis', label: '📐 Responsive Analysis',   script: '03-responsive-analysis.js' },
+  { id: 'audio-extraction',    label: '🔊 Audio Extraction',       script: '06-audio-extraction.js' },
+  { id: 'accessibility',       label: '♿ Accessibility',          script: '07-accessibility-reduced-motion.js' },
+  { id: 'complexity-scorer',   label: '📊 Complexity Scorer',     script: '08-complexity-scorer.js' },
+  { id: 'visual-diff',         label: '🔬 Visual Diff',           script: '09-visual-diff-validator.js' },
+];
+
+function banner(chalk) {
+  return chalk.bold.cyan(`
+╔═══════════════════════════════════════════════════════╗
+║   ██╗    ██╗███████╗██████╗  ██████╗ ██╗              ║
+║   ██║    ██║██╔════╝██╔══██╗██╔════╝ ██║              ║
+║   ██║ █╗ ██║█████╗  ██████╔╝██║  ███╗██║              ║
+║   ██║███╗██║██╔══╝  ██╔══██╗██║   ██║██║              ║
+║   ╚███╔███╔╝███████╗██████╔╝╚██████╔╝███████╗         ║
+║    ╚══╝╚══╝ ╚══════╝╚═════╝  ╚═════╝ ╚══════╝         ║
+║                                                        ║
+║   ${chalk.white('FORENSICS')} ${chalk.gray('v3.1')} ${chalk.green('— Universal Site Analyzer')}           ║
+╚═══════════════════════════════════════════════════════╝
+`);
+}
+
+async function promptConfig(inquirer, chalk) {
+  console.log(banner(chalk));
+  console.log(chalk.gray('  Interactive mode — configure your forensics run\n'));
+
+  const answers = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'url',
+      message: chalk.cyan('Target URL:'),
+      validate: (v) => v.startsWith('http') ? true : 'Must start with http/https',
+    },
+    {
+      type: 'list',
+      name: 'focus',
+      message: chalk.cyan('Analysis scope:'),
+      choices: [
+        { name: '🌍 All phases (recommended)', value: 'all' },
+        { name: '🎭 3D / WebGL only', value: '3d' },
+        { name: '🎬 Animations only', value: 'animations' },
+        { name: '📜 Scroll systems only', value: 'scroll' },
+        { name: '🎨 Layout & design tokens', value: 'layout' },
+      ],
+      default: 'all',
+    },
+    {
+      type: 'checkbox',
+      name: 'features',
+      message: chalk.cyan('Enable features:'),
+      choices: [
+        { name: '📸 Scroll screenshots', value: 'screenshots', checked: false },
+        { name: '🗺️  Multi-page crawl (sitemap)', value: 'multipage', checked: true },
+        { name: '⬇️  Download assets (GLB, fonts, HDR)', value: 'downloadAssets', checked: false },
+        { name: '🎥 Record scroll video', value: 'record', checked: false },
+        { name: '🏗️  Generate Next.js scaffold', value: 'scaffold', checked: true },
+        { name: '🤖 AI reconstruction report (needs API key)', value: 'aiReport', checked: false },
+        { name: '✨ AI shader annotation (needs API key)', value: 'annotateShaders', checked: false },
+        { name: '🏆 Run Lighthouse audit', value: 'lighthouse', checked: false },
+        { name: '📃 Generate HTML report', value: 'formatHtml', checked: false },
+        { name: '📂 Save run to history', value: 'history', checked: false },
+      ],
+    },
+    {
+      type: 'list',
+      name: 'headless',
+      message: chalk.cyan('Browser mode:'),
+      choices: [
+        { name: '🔮 Headless (faster)', value: true },
+        { name: '👁️  Visible — required for some WebGL sites', value: false },
+      ],
+      default: false,
+    },
+    {
+      type: 'input',
+      name: 'compareUrl',
+      message: chalk.cyan('Compare URL (optional — leave blank to skip):'),
+      default: '',
+    },
+    {
+      type: 'input',
+      name: 'output',
+      message: chalk.cyan('Output directory:'),
+      default: './forensics-output',
+    },
+  ]);
+
+  // Convert checkbox array to flags
+  const features = answers.features;
+  return {
+    url: answers.url,
+    focus: answers.focus,
+    headless: answers.headless,
+    compareUrl: answers.compareUrl || null,
+    output: answers.output,
+    screenshots: features.includes('screenshots'),
+    multipage: features.includes('multipage'),
+    downloadAssets: features.includes('downloadAssets'),
+    record: features.includes('record'),
+    scaffold: features.includes('scaffold'),
+    aiReport: features.includes('aiReport'),
+    annotateShaders: features.includes('annotateShaders'),
+    lighthouse: features.includes('lighthouse'),
+    formatHtml: features.includes('formatHtml'),
+    history: features.includes('history'),
+    dryRun: false,
+  };
+}
+
+/**
+ * Phase progress renderer
+ */
+function createPhaseRenderer(chalk, ora) {
+  const states = {};
+  let activeSpinner = null;
+
+  return {
+    start(phaseId, label) {
+      if (activeSpinner) activeSpinner.stop();
+      states[phaseId] = 'running';
+      activeSpinner = ora({
+        text: chalk.white(label),
+        color: 'cyan',
+      }).start();
+    },
+    succeed(phaseId, detail = '') {
+      if (activeSpinner) {
+        activeSpinner.succeed(chalk.green(`✓ `) + chalk.white(PHASES.find(p => p.id === phaseId)?.label || phaseId) + (detail ? chalk.gray(` — ${detail}`) : ''));
+        activeSpinner = null;
+      }
+      states[phaseId] = 'done';
+    },
+    fail(phaseId, err = '') {
+      if (activeSpinner) {
+        activeSpinner.fail(chalk.red(`✗ `) + chalk.white(PHASES.find(p => p.id === phaseId)?.label || phaseId) + chalk.gray(` — ${err}`));
+        activeSpinner = null;
+      }
+      states[phaseId] = 'failed';
+    },
+    log(msg) {
+      if (activeSpinner) activeSpinner.stop();
+      console.log(chalk.gray(`  ${msg}`));
+    },
+    complete(report, outputDir, chalk) {
+      const complexity = report?.meta?.phases?.['complexity-scorer']?.score || 0;
+      const techStack = report?.meta?.phases?.['tech-stack'];
+
+      console.log('\n' + chalk.bold.green('═'.repeat(56)));
+      console.log(chalk.bold.green('  ✅ FORENSICS COMPLETE'));
+      console.log(chalk.bold.green('═'.repeat(56)));
+      console.log(chalk.cyan(`  URL:        `) + chalk.white(report?.meta?.url));
+      console.log(chalk.cyan(`  Output:     `) + chalk.white(outputDir));
+      console.log(chalk.cyan(`  Complexity: `) + chalk.yellow(`${complexity}/100`));
+      if (techStack?.framework?.name) {
+        console.log(chalk.cyan(`  Framework:  `) + chalk.white(techStack.framework.name));
+      }
+      console.log(chalk.bold.green('═'.repeat(56)) + '\n');
+    },
+  };
+}
+
+module.exports = { promptConfig, createPhaseRenderer, loadModules, PHASES };