Upload 17 files

Dockerfile

@@ -0,0 +1,63 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# Install system dependencies for Playwright/Chromium
+RUN apt-get update && apt-get install -y \
+    wget \
+    gnupg \
+    curl \
+    libnss3 \
+    libnspr4 \
+    libatk1.0-0 \
+    libatk-bridge2.0-0 \
+    libcups2 \
+    libdrm2 \
+    libdbus-1-3 \
+    libxkbcommon0 \
+    libxcomposite1 \
+    libxdamage1 \
+    libxfixes3 \
+    libxrandr2 \
+    libgbm1 \
+    libasound2 \
+    libpango-1.0-0 \
+    libpangocairo-1.0-0 \
+    libcairo2 \
+    libatspi2.0-0 \
+    libxshmfence1 \
+    libglib2.0-0 \
+    libx11-6 \
+    libx11-xcb1 \
+    libxcb1 \
+    libxext6 \
+    libxrender1 \
+    libxtst6 \
+    fonts-liberation \
+    libnss3-tools \
+    xdg-utils \
+    libgtk-3-0 \
+    libxss1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Set Playwright browser path and install browsers
+ENV PLAYWRIGHT_BROWSERS_PATH=/app/.playwright-browsers
+RUN python -m playwright install chromium
+
+# Copy application files
+COPY . .
+
+# Create data directories
+RUN mkdir -p /app/data/figma /app/data/website /app/data/comparisons /app/reports
+
+# Expose port
+EXPOSE 7860
+
+# Run the app
+CMD ["python", "app.py"]

PROJECT_STATUS.md

@@ -0,0 +1,125 @@
+# 🚀 UI Regression Testing Tool - Project Status
+
+## 📋 Project Overview
+**Goal**: Compare Figma designs with live websites to detect ALL visual differences (114 types across 15 categories)
+
+**Approach**: Phased development with element-by-element comparison
+
+---
+
+## 🎯 Phase Status
+
+| Phase | Description | Status |
+|-------|-------------|--------|
+| **Phase 1** | Core infrastructure + Visual overlay | 🟢 IN PROGRESS |
+| **Phase 2** | Figma element extraction | ⚪ Not started |
+| **Phase 3** | Website DOM element extraction | ⚪ Not started |
+| **Phase 4** | Element-by-element comparison | ⚪ Not started |
+| **Phase 5** | Full 114-difference detection | ⚪ Not started |
+
+---
+
+## 📦 Phase 1: Core Infrastructure + Visual Overlay
+
+### Goals:
+1. ✅ Clean project structure
+2. ✅ Screenshot capture (Figma + Website)
+3. ✅ Fix 2x scaling issue (Figma exports at retina)
+4. ✅ Visual diff overlay (side-by-side with red highlights)
+5. ✅ Improved UI with clear status/results
+6. ✅ Proper logging system
+7. ✅ Similarity scoring (normalized)
+
+### Files Created:
+```
+ui-regression-v2/
+├── app.py                 # Main Gradio interface
+├── workflow.py            # LangGraph workflow orchestration
+├── state_schema.py        # State definitions
+├── requirements.txt       # Dependencies
+├── Dockerfile            # HF Spaces deployment
+├── README.md             # HF Spaces config
+├── PROJECT_STATUS.md     # This file (for context)
+├── agents/
+│   ├── __init__.py
+│   ├── agent_0_super_agent.py      # Test plan generation
+│   ├── agent_1_design_inspector.py # Figma screenshot capture
+│   ├── agent_2_website_inspector.py # Website screenshot capture
+│   └── agent_3_visual_comparator.py # Visual diff analysis
+├── utils/
+│   ├── __init__.py
+│   ├── figma_client.py    # Figma API integration
+│   ├── website_capturer.py # Playwright website capture
+│   └── image_differ.py    # Image comparison & overlay
+└── data/                  # Output directories
+    ├── figma/
+    ├── website/
+    └── comparisons/
+```
+
+### Key Decisions:
+- Using Playwright for website screenshots
+- Figma API for design screenshots
+- PIL/OpenCV for image comparison
+- Gradio for UI
+- LangGraph for workflow orchestration
+
+---
+
+## 🔮 Upcoming Phases
+
+### Phase 2: Figma Element Extraction
+- Use Figma API to get all nodes (frames, components, text, etc.)
+- Extract properties: position, size, color, text content
+- Build element tree with hierarchy
+
+### Phase 3: Website DOM Extraction
+- Use Playwright to extract DOM elements
+- Get computed CSS for each element
+- Extract: buttons, inputs, text, images, etc.
+- Match elements by type/position/content
+
+### Phase 4: Element-by-Element Comparison
+- Match Figma elements to Website elements
+- Compare each property
+- Detect: missing, extra, different elements
+- Calculate per-element similarity
+
+### Phase 5: Full 114-Difference Detection
+- Implement all 15 categories from framework
+- Layout & Structure (8 checks)
+- Typography (10 checks)
+- Colors & Contrast (10 checks)
+- And 12 more categories...
+
+---
+
+## 🔑 Important Information
+
+### HF Space Configuration:
+- SDK: Docker
+- Port: 7860
+- Python: 3.10
+
+### Environment Variables Needed:
+- `FIGMA_API_KEY` - Your Figma API token
+- `HF_TOKEN` - (Optional) For enhanced AI analysis
+
+### Figma File Requirements:
+- File must have frames named with viewport (e.g., "Checkout-Desktop", "Checkout-Mobile")
+- Frame widths: Desktop=1440px, Mobile=375px
+
+---
+
+## 📝 How to Continue Development
+
+When starting a new chat with Claude:
+1. Upload this `PROJECT_STATUS.md` file
+2. Upload any files you want to modify
+3. Say: "Continue UI Regression Tool from Phase X"
+
+---
+
+## 📅 Last Updated
+Date: 2026-01-04
+Phase: 1 (In Progress)

README.md

@@ -1,10 +1,43 @@
 ---
-title: Ui Regression Testing 3
-emoji: 📈
-colorFrom: pink
-colorTo: red
+title: UI Regression Testing v2
+emoji: 🎨
+colorFrom: blue
+colorTo: purple
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🎨 UI Regression Testing Tool v2
+
+Compare Figma designs with live websites to detect visual differences.
+
+## Features
+
+### Phase 1 (Current)
+- ✅ Screenshot capture from Figma designs
+- ✅ Screenshot capture from live websites
+- ✅ Visual diff overlay with highlighted differences
+- ✅ Normalized image comparison (handles Figma 2x export)
+- ✅ Similarity scoring
+- ✅ Side-by-side comparison view
+
+### Coming Soon
+- 🔜 Element-by-element comparison
+- 🔜 Typography detection
+- 🔜 Color palette analysis
+- 🔜 Component detection
+- 🔜 114 visual difference checks
+
+## Usage
+
+1. Enter your **Figma API Key**
+2. Enter the **Figma File ID** (from the URL)
+3. Enter the **Website URL** to compare
+4. Click **"Start Capture"** to take screenshots
+5. Click **"Run Analysis"** to compare and see differences
+
+## Requirements
+
+- Figma file with frames named: `*-Desktop` (1440px) and `*-Mobile` (375px)
+- Website must be publicly accessible

agents/__init__.py

@@ -0,0 +1,16 @@
+"""
+Agents for UI Regression Testing
+Each agent handles a specific part of the comparison workflow.
+"""
+
+from .agent_0_super_agent import agent_0_node
+from .agent_1_design_inspector import agent_1_node
+from .agent_2_website_inspector import agent_2_node
+from .agent_3_visual_comparator import agent_3_node
+
+__all__ = [
+    'agent_0_node',
+    'agent_1_node', 
+    'agent_2_node',
+    'agent_3_node'
+]

agents/agent_0_super_agent.py

@@ -0,0 +1,78 @@
+"""
+Agent 0: Super Agent
+Initializes the test plan and validates inputs.
+"""
+
+from typing import Dict, Any
+
+
+def agent_0_node(state: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Initialize test plan and validate configuration.
+    
+    This agent:
+    1. Validates that all required inputs are present
+    2. Sets up the test plan
+    3. Logs the configuration
+    """
+    print("\n" + "="*60)
+    print("🤖 Agent 0: Super Agent - Initializing Test Plan")
+    print("="*60)
+    
+    # Validate required fields
+    figma_key = state.get("figma_access_token", "")
+    figma_file = state.get("figma_file_key", "")
+    website_url = state.get("website_url", "")
+    execution_id = state.get("execution_id", "")
+    hf_token = state.get("hf_token", "")
+    
+    errors = []
+    if not figma_key:
+        errors.append("Missing Figma API Key")
+    if not figma_file:
+        errors.append("Missing Figma File ID")
+    if not website_url:
+        errors.append("Missing Website URL")
+    
+    if errors:
+        error_msg = "Validation failed: " + ", ".join(errors)
+        print(f"  ❌ {error_msg}")
+        return {
+            "status": "validation_failed",
+            "error_message": error_msg,
+            "logs": state.get("logs", []) + [f"❌ {error_msg}"]
+        }
+    
+    # Log configuration
+    print(f"  ✅ Figma API Key: {'*' * 20}...{figma_key[-4:] if len(figma_key) > 4 else '****'}")
+    print(f"  ✅ Figma File ID: {figma_file}")
+    print(f"  ✅ Website URL: {website_url}")
+    print(f"  ✅ Execution ID: {execution_id}")
+    print(f"  ✅ HF Token: {'Provided' if hf_token else 'Not provided (basic mode)'}")
+    
+    # Define test plan
+    test_plan = {
+        "viewports": ["desktop", "mobile"],
+        "desktop_width": 1440,
+        "mobile_width": 375,
+        "checks": [
+            "layout_comparison",
+            "color_comparison", 
+            "visual_diff_overlay"
+        ]
+    }
+    
+    print(f"\n  📋 Test Plan:")
+    print(f"     • Viewports: {test_plan['viewports']}")
+    print(f"     • Desktop width: {test_plan['desktop_width']}px")
+    print(f"     • Mobile width: {test_plan['mobile_width']}px")
+    print(f"     • Checks: {len(test_plan['checks'])} types")
+    
+    logs = state.get("logs", [])
+    logs.append("✅ Test plan initialized")
+    logs.append(f"   Viewports: desktop ({test_plan['desktop_width']}px), mobile ({test_plan['mobile_width']}px)")
+    
+    return {
+        "status": "plan_ready",
+        "logs": logs
+    }

agents/agent_1_design_inspector.py

@@ -0,0 +1,69 @@
+"""
+Agent 1: Design Inspector
+Captures screenshots from Figma design file.
+"""
+
+from typing import Dict, Any
+import sys
+import os
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from utils.figma_client import FigmaClient
+
+
+def agent_1_node(state: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Capture screenshots from Figma design.
+    
+    This agent:
+    1. Connects to Figma API
+    2. Finds Desktop and Mobile frames
+    3. Exports screenshots at proper scale
+    4. Stores paths and dimensions in state
+    """
+    print("\n" + "="*60)
+    print("🎨 Agent 1: Design Inspector - Capturing Figma Screenshots")
+    print("="*60)
+    
+    figma_key = state.get("figma_access_token", "")
+    figma_file = state.get("figma_file_key", "")
+    execution_id = state.get("execution_id", "")
+    logs = state.get("logs", [])
+    
+    try:
+        # Initialize Figma client
+        client = FigmaClient(figma_key)
+        
+        # Export frames
+        screenshots, dimensions = client.export_frames_for_comparison(
+            file_key=figma_file,
+            output_dir="data/figma",
+            execution_id=execution_id
+        )
+        
+        if not screenshots:
+            raise ValueError("No frames found in Figma file. Ensure frames are named with 'Desktop' or 'Mobile'.")
+        
+        print(f"\n  ✅ Captured {len(screenshots)} Figma screenshots")
+        for viewport, path in screenshots.items():
+            dims = dimensions.get(viewport, {})
+            print(f"     • {viewport}: {dims.get('width', '?')}x{dims.get('height', '?')}px")
+            logs.append(f"📸 Figma {viewport}: {dims.get('width', '?')}x{dims.get('height', '?')}px")
+        
+        return {
+            "figma_screenshots": screenshots,
+            "figma_dimensions": dimensions,
+            "status": "figma_captured",
+            "logs": logs
+        }
+        
+    except Exception as e:
+        error_msg = f"Failed to capture Figma screenshots: {str(e)}"
+        print(f"\n  ❌ {error_msg}")
+        logs.append(f"❌ {error_msg}")
+        return {
+            "status": "figma_capture_failed",
+            "error_message": error_msg,
+            "logs": logs
+        }

agents/agent_2_website_inspector.py

@@ -0,0 +1,66 @@
+"""
+Agent 2: Website Inspector
+Captures screenshots from live website.
+"""
+
+from typing import Dict, Any
+import sys
+import os
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from utils.website_capturer import capture_website_screenshots
+
+
+def agent_2_node(state: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Capture screenshots from live website.
+    
+    This agent:
+    1. Opens website in headless browser
+    2. Captures full-page screenshots at desktop and mobile viewports
+    3. Stores paths and dimensions in state
+    """
+    print("\n" + "="*60)
+    print("🌐 Agent 2: Website Inspector - Capturing Website Screenshots")
+    print("="*60)
+    
+    website_url = state.get("website_url", "")
+    execution_id = state.get("execution_id", "")
+    logs = state.get("logs", [])
+    
+    try:
+        # Capture screenshots
+        screenshots, dimensions = capture_website_screenshots(
+            website_url=website_url,
+            output_dir="data/website",
+            execution_id=execution_id,
+            desktop_width=1440,
+            mobile_width=375
+        )
+        
+        if not screenshots:
+            raise ValueError("Failed to capture any website screenshots")
+        
+        print(f"\n  ✅ Captured {len(screenshots)} website screenshots")
+        for viewport, path in screenshots.items():
+            dims = dimensions.get(viewport, {})
+            print(f"     • {viewport}: {dims.get('width', '?')}x{dims.get('height', '?')}px")
+            logs.append(f"📸 Website {viewport}: {dims.get('width', '?')}x{dims.get('height', '?')}px")
+        
+        return {
+            "website_screenshots": screenshots,
+            "website_dimensions": dimensions,
+            "status": "website_captured",
+            "logs": logs
+        }
+        
+    except Exception as e:
+        error_msg = f"Failed to capture website screenshots: {str(e)}"
+        print(f"\n  ❌ {error_msg}")
+        logs.append(f"❌ {error_msg}")
+        return {
+            "status": "website_capture_failed",
+            "error_message": error_msg,
+            "logs": logs
+        }

agents/agent_3_visual_comparator.py

@@ -0,0 +1,123 @@
+"""
+Agent 3: Visual Comparator
+Compares Figma and Website screenshots, generates diff overlays.
+"""
+
+from typing import Dict, Any
+import sys
+import os
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from utils.image_differ import ImageDiffer
+
+
+def agent_3_node(state: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Compare screenshots and generate visual diff report.
+    
+    This agent:
+    1. Normalizes image sizes (handles Figma 2x)
+    2. Calculates similarity scores
+    3. Creates side-by-side comparison with diff overlay
+    4. Detects specific differences (color, layout, structure)
+    """
+    print("\n" + "="*60)
+    print("🔍 Agent 3: Visual Comparator - Analyzing Differences")
+    print("="*60)
+    
+    figma_screenshots = state.get("figma_screenshots", {})
+    website_screenshots = state.get("website_screenshots", {})
+    figma_dims = state.get("figma_dimensions", {})
+    website_dims = state.get("website_dimensions", {})
+    execution_id = state.get("execution_id", "")
+    logs = state.get("logs", [])
+    
+    if not figma_screenshots or not website_screenshots:
+        error_msg = "Missing screenshots for comparison"
+        print(f"\n  ❌ {error_msg}")
+        return {
+            "status": "comparison_failed",
+            "error_message": error_msg,
+            "logs": logs + [f"❌ {error_msg}"]
+        }
+    
+    try:
+        # Initialize differ
+        differ = ImageDiffer(output_dir="data/comparisons")
+        
+        # Run comparison
+        results = differ.compare_all_viewports(
+            figma_screenshots=figma_screenshots,
+            website_screenshots=website_screenshots,
+            figma_dims=figma_dims,
+            website_dims=website_dims,
+            execution_id=execution_id
+        )
+        
+        # Build comparison images dict
+        comparison_images = {}
+        for viewport, comparison in results["comparisons"].items():
+            comparison_images[viewport] = comparison["comparison_image"]
+        
+        # Log results
+        print(f"\n" + "="*60)
+        print("📊 COMPARISON RESULTS")
+        print("="*60)
+        print(f"  Overall Similarity: {results['overall_score']:.1f}%")
+        
+        for viewport, score in results["viewport_scores"].items():
+            status_emoji = "✅" if score >= 90 else "⚠️" if score >= 70 else "❌"
+            print(f"  {status_emoji} {viewport.capitalize()}: {score:.1f}%")
+            logs.append(f"{status_emoji} {viewport} similarity: {score:.1f}%")
+        
+        if results["all_differences"]:
+            print(f"\n  🔍 Found {len(results['all_differences'])} differences:")
+            for diff in results["all_differences"]:
+                severity_emoji = "🔴" if diff["severity"] == "High" else "🟡" if diff["severity"] == "Medium" else "🟢"
+                print(f"     {severity_emoji} [{diff['category']}] {diff['title']}")
+                logs.append(f"{severity_emoji} {diff['title']}")
+        else:
+            print(f"\n  ✅ No significant differences detected!")
+            logs.append("✅ No significant differences detected")
+        
+        # Convert numpy types to Python native types for serialization
+        def convert_to_native(obj):
+            """Convert numpy types to Python native types."""
+            import numpy as np
+            if isinstance(obj, np.floating):
+                return float(obj)
+            elif isinstance(obj, np.integer):
+                return int(obj)
+            elif isinstance(obj, np.ndarray):
+                return obj.tolist()
+            elif isinstance(obj, dict):
+                return {k: convert_to_native(v) for k, v in obj.items()}
+            elif isinstance(obj, list):
+                return [convert_to_native(i) for i in obj]
+            return obj
+        
+        # Convert all results to native Python types
+        similarity_scores_native = {k: float(v) for k, v in results["viewport_scores"].items()}
+        overall_score_native = float(results["overall_score"])
+        differences_native = convert_to_native(results["all_differences"])
+        
+        return {
+            "comparison_images": comparison_images,
+            "visual_differences": differences_native,
+            "similarity_scores": similarity_scores_native,
+            "overall_score": overall_score_native,
+            "status": "analysis_complete",
+            "logs": logs
+        }
+        
+    except Exception as e:
+        import traceback
+        error_msg = f"Comparison failed: {str(e)}"
+        print(f"\n  ❌ {error_msg}")
+        traceback.print_exc()
+        return {
+            "status": "comparison_failed",
+            "error_message": error_msg,
+            "logs": logs + [f"❌ {error_msg}"]
+        }

app.py

@@ -0,0 +1,402 @@
+"""
+UI Regression Testing Tool v2 - Phase 1
+Main Gradio interface with single action button and blue theme.
+"""
+
+import gradio as gr
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+
+# Add current directory to path
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from workflow import run_workflow_step_1, resume_workflow
+
+# Log file
+LOG_FILE = "app.log"
+
+
+# Custom CSS for blue theme
+CUSTOM_CSS = """
+/* Main background */
+.gradio-container {
+    background: linear-gradient(135deg, #1a1a2e 0%, #16213e 50%, #0f3460 100%) !important;
+}
+
+/* Headers */
+h1, h2, h3, .markdown-text h1, .markdown-text h2, .markdown-text h3 {
+    color: #00d4ff !important;
+}
+
+/* Labels */
+label, .label-wrap {
+    color: #e0e0e0 !important;
+    background: #1e3a5f !important;
+    padding: 4px 8px !important;
+    border-radius: 4px !important;
+}
+
+/* Input fields */
+input, textarea, .textbox {
+    background: #0d1b2a !important;
+    border: 1px solid #1e3a5f !important;
+    color: #ffffff !important;
+}
+
+/* Primary button - Blue */
+.primary {
+    background: linear-gradient(135deg, #0066ff 0%, #0052cc 100%) !important;
+    border: none !important;
+    color: white !important;
+}
+
+.primary:hover {
+    background: linear-gradient(135deg, #0052cc 0%, #003d99 100%) !important;
+}
+
+/* Secondary elements */
+.secondary {
+    background: #1e3a5f !important;
+    border: 1px solid #2d5a87 !important;
+    color: #e0e0e0 !important;
+}
+
+/* Code blocks / Logs */
+.code-wrap, pre, code {
+    background: #0d1b2a !important;
+    border: 1px solid #1e3a5f !important;
+    color: #00ff88 !important;
+}
+
+/* Status boxes */
+.output-class, .input-class {
+    background: #0d1b2a !important;
+    border: 1px solid #1e3a5f !important;
+}
+
+/* Panels */
+.panel {
+    background: rgba(30, 58, 95, 0.5) !important;
+    border: 1px solid #2d5a87 !important;
+    border-radius: 8px !important;
+}
+
+/* Success text */
+.success {
+    color: #00ff88 !important;
+}
+
+/* Error text */
+.error {
+    color: #ff4757 !important;
+}
+
+/* Warning text */
+.warning {
+    color: #ffa502 !important;
+}
+"""
+
+
+def clear_logs():
+    """Clear log file for fresh start."""
+    with open(LOG_FILE, "w") as f:
+        f.write(f"===== New Session: {datetime.now()} =====\n\n")
+
+
+def get_logs():
+    """Get current log contents."""
+    try:
+        with open(LOG_FILE, "r") as f:
+            return f.read()
+    except:
+        return "Logs will appear here..."
+
+
+def run_full_analysis(figma_key, figma_id, url, hf_token, progress=gr.Progress()):
+    """
+    Combined action: Capture screenshots AND run analysis in one step.
+    """
+    clear_logs()
+    
+    print(f"\n{'='*60}")
+    print(f"🚀 STARTING UI REGRESSION TEST")
+    print(f"{'='*60}")
+    print(f"⏰ Time: {datetime.now()}")
+    print(f"🌐 Website: {url}")
+    print(f"📁 Figma File: {figma_id}")
+    print(f"🔑 Figma Key: {'✅ Provided' if figma_key else '❌ Missing'}")
+    print(f"🤗 HF Token: {'✅ Provided' if hf_token else '⚪ Not provided'}")
+    print(f"{'='*60}\n")
+    
+    # Validation
+    if not figma_key or not figma_id or not url:
+        return (
+            "❌ Please fill in all required fields:\n• Figma API Key\n• Figma File ID\n• Website URL",
+            None, None, None, None, get_logs()
+        )
+    
+    execution_id = f"exec_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+    thread_id = f"thread_{execution_id}"
+    
+    try:
+        # ===== STEP 1: Capture Screenshots =====
+        progress(0.1, desc="📸 Capturing Figma screenshots...")
+        print(f"🧵 Thread ID: {thread_id}")
+        print(f"\n📋 STEP 1: Capturing Screenshots...")
+        print("-" * 40)
+        
+        state = run_workflow_step_1(figma_id, figma_key, url, execution_id, thread_id, hf_token)
+        
+        if not state or not state.values:
+            return "❌ Workflow failed to start", None, None, None, None, get_logs()
+        
+        values = state.values
+        status = values.get("status", "unknown")
+        
+        if "failed" in status:
+            error = values.get("error_message", "Unknown error")
+            return f"❌ Capture Failed: {error}", None, None, None, None, get_logs()
+        
+        # Get captured screenshots
+        figma_shots = values.get("figma_screenshots", {})
+        website_shots = values.get("website_screenshots", {})
+        
+        print(f"\n✅ Screenshots captured successfully!")
+        progress(0.5, desc="🔍 Running visual analysis...")
+        
+        # ===== STEP 2: Run Analysis =====
+        print(f"\n{'='*60}")
+        print(f"🔍 STEP 2: RUNNING VISUAL ANALYSIS")
+        print(f"{'='*60}")
+        
+        state = resume_workflow(thread_id, user_approval=True)
+        
+        if not state or not state.values:
+            return "❌ Analysis failed - no state returned", None, None, None, None, get_logs()
+        
+        values = state.values
+        status = values.get("status", "unknown")
+        
+        if "failed" in status:
+            error = values.get("error_message", "Unknown error")
+            return f"❌ Analysis Failed: {error}", None, None, None, None, get_logs()
+        
+        progress(0.9, desc="📊 Generating results...")
+        
+        # Get results
+        overall_score = values.get("overall_score", 0)
+        viewport_scores = values.get("similarity_scores", {})
+        differences = values.get("visual_differences", [])
+        comparison_images = values.get("comparison_images", {})
+        figma_dims = values.get("figma_dimensions", {})
+        website_dims = values.get("website_dimensions", {})
+        
+        print(f"\n{'='*60}")
+        print(f"✅ ANALYSIS COMPLETE!")
+        print(f"{'='*60}")
+        
+        # ===== Build Results =====
+        
+        # Status message
+        status_msg = f"✅ Analysis Complete!\n\n"
+        
+        score_emoji = "🟢" if overall_score >= 90 else "🟡" if overall_score >= 70 else "🔴"
+        status_msg += f"{score_emoji} Overall Similarity: {overall_score:.1f}%\n\n"
+        
+        status_msg += "📱 Viewport Scores:\n"
+        for vp, score in viewport_scores.items():
+            vp_emoji = "✅" if score >= 90 else "⚠️" if score >= 70 else "❌"
+            status_msg += f"   {vp_emoji} {vp.capitalize()}: {score:.1f}%\n"
+        
+        status_msg += f"\n🔍 Differences: {len(differences)} found\n"
+        
+        # Detailed results
+        result_msg = f"{'='*50}\n"
+        result_msg += f"📊 DETAILED ANALYSIS REPORT\n"
+        result_msg += f"{'='*50}\n\n"
+        
+        result_msg += f"📸 Screenshots Captured:\n"
+        result_msg += f"   Figma: {len(figma_shots)} viewports\n"
+        result_msg += f"   Website: {len(website_shots)} viewports\n\n"
+        
+        if differences:
+            result_msg += f"🔍 DIFFERENCES FOUND: {len(differences)}\n"
+            result_msg += "-" * 40 + "\n"
+            
+            for i, diff in enumerate(differences, 1):
+                sev = diff.get("severity", "Medium")
+                sev_emoji = "🔴 HIGH" if sev == "High" else "🟡 MEDIUM" if sev == "Medium" else "🟢 LOW"
+                result_msg += f"\n[{i}] {diff.get('title', 'Unknown')}\n"
+                result_msg += f"    Severity: {sev_emoji}\n"
+                result_msg += f"    Category: {diff.get('category', 'N/A')}\n"
+                result_msg += f"    Viewport: {diff.get('viewport', 'N/A')}\n"
+                if diff.get("description"):
+                    desc = diff["description"][:150]
+                    result_msg += f"    Details: {desc}\n"
+        else:
+            result_msg += "\n✅ No significant differences detected!\n"
+            result_msg += "The website matches the Figma design closely.\n"
+        
+        # Get images
+        figma_preview = figma_shots.get("desktop") or figma_shots.get("mobile")
+        website_preview = website_shots.get("desktop") or website_shots.get("mobile")
+        comparison_img = comparison_images.get("desktop") or comparison_images.get("mobile")
+        gallery_images = list(comparison_images.values()) if comparison_images else None
+        
+        progress(1.0, desc="✅ Complete!")
+        
+        return status_msg, result_msg, figma_preview, website_preview, comparison_img, get_logs()
+        
+    except Exception as e:
+        import traceback
+        error_msg = f"❌ Error: {str(e)}"
+        print(error_msg)
+        traceback.print_exc()
+        return error_msg, None, None, None, None, get_logs()
+
+
+def create_interface():
+    """Create the Gradio interface with blue theme."""
+    
+    with gr.Blocks(
+        title="UI Regression Testing v2",
+        theme=gr.themes.Base(
+            primary_hue="blue",
+            secondary_hue="slate",
+            neutral_hue="slate",
+        ),
+        css=CUSTOM_CSS
+    ) as demo:
+        
+        gr.Markdown("# 🎨 UI Regression Testing Tool")
+        gr.Markdown("*Compare Figma designs with live websites to detect visual differences*")
+        
+        with gr.Row():
+            # LEFT: Configuration
+            with gr.Column(scale=1):
+                gr.Markdown("### 📝 Configuration")
+                
+                figma_key = gr.Textbox(
+                    label="Figma API Key *",
+                    type="password",
+                    placeholder="figd_xxxxx..."
+                )
+                figma_id = gr.Textbox(
+                    label="Figma File ID *",
+                    placeholder="e.g., ENieX2p3Gy3TAtxaB36cZA"
+                )
+                website_url = gr.Textbox(
+                    label="Website URL *",
+                    placeholder="https://your-site.com"
+                )
+                hf_token = gr.Textbox(
+                    label="HF Token (Optional)",
+                    type="password",
+                    placeholder="For future AI enhancements"
+                )
+                
+                gr.Markdown("### 🎮 Action")
+                btn_run = gr.Button(
+                    "🚀 Run Full Analysis",
+                    variant="primary",
+                    size="lg"
+                )
+                
+                gr.Markdown("""
+                *This will:*
+                1. Capture Figma design screenshots
+                2. Capture website screenshots
+                3. Compare and highlight differences
+                4. Generate similarity scores
+                """)
+            
+            # RIGHT: Status & Results
+            with gr.Column(scale=2):
+                gr.Markdown("### 📊 Results Summary")
+                status_box = gr.Textbox(
+                    label="Status",
+                    lines=8,
+                    interactive=False
+                )
+                
+                gr.Markdown("### 📋 Detailed Report")
+                results_box = gr.Textbox(
+                    label="Analysis Details",
+                    lines=12,
+                    interactive=False
+                )
+        
+        # Preview Section
+        gr.Markdown("---")
+        gr.Markdown("### 🖼️ Screenshot Preview")
+        with gr.Row():
+            figma_preview = gr.Image(label="📐 Figma Design", height=250)
+            website_preview = gr.Image(label="🌐 Live Website", height=250)
+        
+        # Comparison Section
+        gr.Markdown("---")
+        gr.Markdown("### 🔍 Visual Comparison")
+        gr.Markdown("*Red areas indicate differences between design and website*")
+        comparison_image = gr.Image(
+            label="Figma | Website | Differences",
+            height=500
+        )
+        
+        # Logs Section
+        gr.Markdown("---")
+        with gr.Accordion("📜 Execution Logs", open=False):
+            log_box = gr.Code(
+                label="Live Logs",
+                language="python",
+                lines=20,
+                interactive=False
+            )
+            log_timer = gr.Timer(value=2)
+            log_timer.tick(get_logs, outputs=[log_box])
+        
+        # Button handler
+        btn_run.click(
+            run_full_analysis,
+            inputs=[figma_key, figma_id, website_url, hf_token],
+            outputs=[status_box, results_box, figma_preview, website_preview, comparison_image, log_box]
+        )
+    
+    return demo
+
+
+# Main entry point
+if __name__ == "__main__":
+    # Setup logging
+    class Logger:
+        def __init__(self):
+            self.terminal = sys.stdout
+            Path(LOG_FILE).parent.mkdir(parents=True, exist_ok=True)
+            with open(LOG_FILE, "w") as f:
+                f.write(f"===== Application Started: {datetime.now()} =====\n\n")
+            self.log = open(LOG_FILE, "a")
+        
+        def write(self, message):
+            self.terminal.write(message)
+            self.log.write(message)
+            self.log.flush()
+        
+        def flush(self):
+            self.terminal.flush()
+            self.log.flush()
+        
+        def isatty(self):
+            return hasattr(self.terminal, 'isatty') and self.terminal.isatty()
+    
+    sys.stdout = Logger()
+    sys.stderr = Logger()
+    
+    print(f"🚀 Starting UI Regression Testing Tool v2")
+    print(f"📅 Date: {datetime.now()}")
+    print(f"📦 Phase: 1 (Visual Comparison)")
+    
+    # Create and launch
+    demo = create_interface()
+    demo.launch(server_name="0.0.0.0", server_port=7860)

requirements.txt

@@ -0,0 +1,28 @@
+# Core Dependencies
+python-dotenv>=1.0.0
+requests>=2.31.0
+
+# LangGraph & LangChain
+langgraph>=0.0.50
+langchain>=0.1.0
+langchain-core>=0.1.0
+
+# Web Automation
+playwright>=1.40.0
+
+# Data Processing
+numpy>=1.24.3
+pillow>=11.0.0
+
+# Image Processing & Comparison
+opencv-python-headless>=4.8.0
+scikit-image>=0.21.0
+
+# Async Support
+aiohttp>=3.9.1
+
+# Gradio (for dashboard)
+gradio>=4.0.0
+
+# Hugging Face (optional - for enhanced AI analysis)
+huggingface-hub>=0.19.0

state_schema.py

@@ -0,0 +1,68 @@
+"""
+State Schema for UI Regression Testing Workflow
+Defines the structure of data passed between agents.
+"""
+
+from typing import TypedDict, Dict, List, Any, Optional
+
+
+class WorkflowState(TypedDict, total=False):
+    """Complete state for the UI regression testing workflow."""
+    
+    # Configuration
+    figma_file_key: str
+    figma_access_token: str
+    website_url: str
+    execution_id: str
+    hf_token: Optional[str]
+    
+    # Screenshot paths
+    figma_screenshots: Dict[str, str]  # {"desktop": "path/to/file.png", "mobile": "..."}
+    website_screenshots: Dict[str, str]
+    
+    # Screenshot metadata (for proper comparison)
+    figma_dimensions: Dict[str, Dict[str, int]]  # {"desktop": {"width": 1440, "height": 1649}}
+    website_dimensions: Dict[str, Dict[str, int]]
+    
+    # Comparison results
+    comparison_images: Dict[str, str]  # {"desktop": "path/to/diff.png"}
+    visual_differences: List[Dict[str, Any]]
+    similarity_scores: Dict[str, float]  # {"desktop": 85.5, "mobile": 78.2}
+    overall_score: float
+    
+    # Workflow control
+    user_approval: bool
+    status: str
+    error_message: Optional[str]
+    
+    # Logs
+    logs: List[str]
+
+
+def create_initial_state(
+    figma_file_key: str,
+    figma_access_token: str,
+    website_url: str,
+    execution_id: str,
+    hf_token: str = ""
+) -> WorkflowState:
+    """Create initial state for a new workflow run."""
+    return WorkflowState(
+        figma_file_key=figma_file_key,
+        figma_access_token=figma_access_token,
+        website_url=website_url,
+        execution_id=execution_id,
+        hf_token=hf_token,
+        figma_screenshots={},
+        website_screenshots={},
+        figma_dimensions={},
+        website_dimensions={},
+        comparison_images={},
+        visual_differences=[],
+        similarity_scores={},
+        overall_score=0.0,
+        user_approval=False,
+        status="initialized",
+        error_message=None,
+        logs=[]
+    )

utils/__init__.py

@@ -0,0 +1,13 @@
+"""
+Utility modules for UI Regression Testing
+"""
+
+from .figma_client import FigmaClient
+from .website_capturer import capture_website_screenshots
+from .image_differ import ImageDiffer
+
+__all__ = [
+    'FigmaClient',
+    'capture_website_screenshots',
+    'ImageDiffer'
+]

utils/figma_client.py

@@ -0,0 +1,168 @@
+"""
+Figma API Client
+Handles communication with Figma API to extract design screenshots.
+"""
+
+import requests
+from typing import Dict, List, Tuple, Optional
+from pathlib import Path
+
+
+class FigmaClient:
+    """Client for interacting with Figma API."""
+    
+    BASE_URL = "https://api.figma.com/v1"
+    
+    def __init__(self, access_token: str):
+        self.access_token = access_token
+        self.headers = {
+            "X-Figma-Token": access_token
+        }
+    
+    def get_file(self, file_key: str) -> Dict:
+        """Get file metadata from Figma."""
+        url = f"{self.BASE_URL}/files/{file_key}"
+        response = requests.get(url, headers=self.headers)
+        response.raise_for_status()
+        return response.json()
+    
+    def get_frame_nodes(self, file_key: str) -> List[Dict]:
+        """
+        Get all top-level frames from the Figma file.
+        Returns frames that match viewport patterns (Desktop/Mobile).
+        """
+        file_data = self.get_file(file_key)
+        frames = []
+        
+        # Navigate through document -> pages -> frames
+        document = file_data.get("document", {})
+        for page in document.get("children", []):
+            if page.get("type") == "CANVAS":
+                for child in page.get("children", []):
+                    if child.get("type") == "FRAME":
+                        frame_name = child.get("name", "")
+                        frame_id = child.get("id", "")
+                        bounds = child.get("absoluteBoundingBox", {})
+                        
+                        # Determine viewport type from name
+                        viewport = None
+                        if "desktop" in frame_name.lower() or bounds.get("width", 0) >= 1000:
+                            viewport = "desktop"
+                        elif "mobile" in frame_name.lower() or bounds.get("width", 0) <= 500:
+                            viewport = "mobile"
+                        
+                        if viewport:
+                            frames.append({
+                                "id": frame_id,
+                                "name": frame_name,
+                                "viewport": viewport,
+                                "width": bounds.get("width", 0),
+                                "height": bounds.get("height", 0)
+                            })
+        
+        return frames
+    
+    def export_frame(
+        self, 
+        file_key: str, 
+        frame_id: str, 
+        output_path: str,
+        scale: float = 1.0,
+        format: str = "png"
+    ) -> Tuple[str, Dict[str, int]]:
+        """
+        Export a frame as an image.
+        
+        Args:
+            file_key: Figma file key
+            frame_id: Node ID of the frame to export
+            output_path: Where to save the image
+            scale: Export scale (1.0 = actual size, 0.5 = half size)
+            format: Image format (png, jpg, svg, pdf)
+            
+        Returns:
+            Tuple of (saved_path, dimensions_dict)
+        """
+        # Get export URL
+        url = f"{self.BASE_URL}/images/{file_key}"
+        params = {
+            "ids": frame_id,
+            "scale": scale,
+            "format": format
+        }
+        
+        response = requests.get(url, headers=self.headers, params=params)
+        response.raise_for_status()
+        
+        data = response.json()
+        image_url = data.get("images", {}).get(frame_id)
+        
+        if not image_url:
+            raise ValueError(f"Could not get export URL for frame {frame_id}")
+        
+        # Download the image
+        img_response = requests.get(image_url)
+        img_response.raise_for_status()
+        
+        # Save to file
+        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+        with open(output_path, "wb") as f:
+            f.write(img_response.content)
+        
+        # Get image dimensions
+        from PIL import Image
+        with Image.open(output_path) as img:
+            width, height = img.size
+        
+        return output_path, {"width": width, "height": height}
+    
+    def export_frames_for_comparison(
+        self,
+        file_key: str,
+        output_dir: str,
+        execution_id: str
+    ) -> Tuple[Dict[str, str], Dict[str, Dict[str, int]]]:
+        """
+        Export all relevant frames for UI comparison.
+        
+        Automatically finds Desktop and Mobile frames and exports them
+        at 1x scale (not 2x) for proper comparison with website screenshots.
+        
+        Returns:
+            Tuple of (screenshot_paths, dimensions)
+        """
+        frames = self.get_frame_nodes(file_key)
+        screenshots = {}
+        dimensions = {}
+        
+        # Group by viewport, prefer larger frames
+        viewport_frames = {}
+        for frame in frames:
+            viewport = frame["viewport"]
+            if viewport not in viewport_frames:
+                viewport_frames[viewport] = frame
+            elif frame["width"] * frame["height"] > viewport_frames[viewport]["width"] * viewport_frames[viewport]["height"]:
+                viewport_frames[viewport] = frame
+        
+        # Export each viewport
+        for viewport, frame in viewport_frames.items():
+            print(f"  📥 Exporting frame: {frame['name']} ({frame['width']}px width)")
+            print(f"     Frame ID: {frame['id']}")
+            print(f"     Dimensions: {frame['width']}x{frame['height']}")
+            
+            output_path = f"{output_dir}/{viewport}_{execution_id}.png"
+            
+            # Export at scale 1.0 (actual design size)
+            # Note: Figma often has designs at 2x, we'll handle normalization in comparison
+            saved_path, dims = self.export_frame(
+                file_key,
+                frame["id"],
+                output_path,
+                scale=1.0  # Export at 1x to get actual design dimensions
+            )
+            
+            screenshots[viewport] = saved_path
+            dimensions[viewport] = dims
+            print(f"  ✓ Exported: {saved_path}")
+        
+        return screenshots, dimensions

utils/image_differ.py

@@ -0,0 +1,347 @@
+"""
+Image Differ Utility
+Compares Figma and Website screenshots, generates visual diff overlays.
+
+Key Features:
+- Normalizes image sizes (handles Figma 2x export)
+- Creates side-by-side comparison
+- Highlights differences in red
+- Calculates similarity score
+"""
+
+import numpy as np
+from PIL import Image, ImageDraw, ImageFont
+from pathlib import Path
+from typing import Dict, List, Tuple, Any
+import cv2
+
+
+class ImageDiffer:
+    """
+    Compares two images and generates visual diff output.
+    """
+    
+    def __init__(self, output_dir: str = "data/comparisons"):
+        self.output_dir = output_dir
+        Path(output_dir).mkdir(parents=True, exist_ok=True)
+    
+    def normalize_images(
+        self,
+        figma_path: str,
+        website_path: str,
+        figma_dims: Dict[str, int],
+        website_dims: Dict[str, int]
+    ) -> Tuple[np.ndarray, np.ndarray, float]:
+        """
+        Normalize images to the same size for comparison.
+        
+        Handles Figma 2x export by detecting and adjusting.
+        
+        Returns:
+            Tuple of (figma_array, website_array, scale_factor)
+        """
+        figma_img = Image.open(figma_path).convert("RGB")
+        website_img = Image.open(website_path).convert("RGB")
+        
+        figma_w, figma_h = figma_img.size
+        website_w, website_h = website_img.size
+        
+        # Detect if Figma is at 2x (common for retina exports)
+        # If Figma is roughly 2x the website width, scale it down
+        width_ratio = figma_w / website_w
+        scale_factor = 1.0
+        
+        if 1.8 <= width_ratio <= 2.2:
+            # Figma is at 2x, scale down to match website
+            scale_factor = 0.5
+            new_figma_w = int(figma_w * scale_factor)
+            new_figma_h = int(figma_h * scale_factor)
+            figma_img = figma_img.resize((new_figma_w, new_figma_h), Image.Resampling.LANCZOS)
+            print(f"     📐 Detected Figma 2x export, scaled to {new_figma_w}x{new_figma_h}")
+        
+        # Now resize both to match (use the smaller dimensions)
+        target_w = min(figma_img.size[0], website_img.size[0])
+        target_h = min(figma_img.size[1], website_img.size[1])
+        
+        figma_img = figma_img.resize((target_w, target_h), Image.Resampling.LANCZOS)
+        website_img = website_img.resize((target_w, target_h), Image.Resampling.LANCZOS)
+        
+        return np.array(figma_img), np.array(website_img), scale_factor
+    
+    def calculate_similarity(
+        self,
+        img1: np.ndarray,
+        img2: np.ndarray
+    ) -> Tuple[float, np.ndarray]:
+        """
+        Calculate similarity score between two images.
+        
+        Uses structural similarity (SSIM) for perceptual comparison.
+        
+        Returns:
+            Tuple of (similarity_score_0_to_100, diff_mask)
+        """
+        from skimage.metrics import structural_similarity as ssim
+        
+        # Convert to grayscale for SSIM
+        gray1 = cv2.cvtColor(img1, cv2.COLOR_RGB2GRAY)
+        gray2 = cv2.cvtColor(img2, cv2.COLOR_RGB2GRAY)
+        
+        # Calculate SSIM
+        score, diff = ssim(gray1, gray2, full=True)
+        
+        # Convert to 0-100 scale
+        similarity = score * 100
+        
+        # Create diff mask (areas with low similarity)
+        diff_mask = ((1 - diff) * 255).astype(np.uint8)
+        
+        return similarity, diff_mask
+    
+    def create_diff_overlay(
+        self,
+        figma_img: np.ndarray,
+        website_img: np.ndarray,
+        diff_mask: np.ndarray,
+        threshold: int = 30
+    ) -> np.ndarray:
+        """
+        Create an overlay image highlighting differences.
+        
+        Args:
+            figma_img: Figma screenshot as numpy array
+            website_img: Website screenshot as numpy array
+            diff_mask: Difference mask from SSIM
+            threshold: Minimum difference to highlight (0-255)
+            
+        Returns:
+            Overlay image with differences highlighted in red
+        """
+        # Create output image (copy of website)
+        overlay = website_img.copy()
+        
+        # Find areas with significant differences
+        significant_diff = diff_mask > threshold
+        
+        # Highlight differences in semi-transparent red
+        red_overlay = overlay.copy()
+        red_overlay[significant_diff] = [255, 0, 0]  # Red
+        
+        # Blend with original (50% opacity for red areas)
+        alpha = 0.5
+        overlay[significant_diff] = (
+            alpha * red_overlay[significant_diff] + 
+            (1 - alpha) * overlay[significant_diff]
+        ).astype(np.uint8)
+        
+        return overlay
+    
+    def create_comparison_image(
+        self,
+        figma_path: str,
+        website_path: str,
+        output_path: str,
+        figma_dims: Dict[str, int],
+        website_dims: Dict[str, int],
+        viewport: str
+    ) -> Dict[str, Any]:
+        """
+        Create a comprehensive comparison image.
+        
+        Generates a side-by-side view:
+        [Figma Design] | [Website] | [Diff Overlay]
+        
+        Returns:
+            Dict with comparison results
+        """
+        print(f"\n  🔍 Comparing {viewport} screenshots...")
+        
+        # Normalize images
+        figma_arr, website_arr, scale = self.normalize_images(
+            figma_path, website_path, figma_dims, website_dims
+        )
+        
+        # Calculate similarity
+        similarity, diff_mask = self.calculate_similarity(figma_arr, website_arr)
+        print(f"     📊 Similarity Score: {similarity:.1f}%")
+        
+        # Create diff overlay
+        overlay = self.create_diff_overlay(figma_arr, website_arr, diff_mask)
+        
+        # Count different pixels
+        significant_diff = diff_mask > 30
+        diff_percentage = (np.sum(significant_diff) / significant_diff.size) * 100
+        print(f"     📍 Pixels with differences: {diff_percentage:.1f}%")
+        
+        # Create side-by-side comparison
+        h, w = figma_arr.shape[:2]
+        padding = 20
+        label_height = 40
+        
+        # Create canvas
+        canvas_w = (w * 3) + (padding * 4)
+        canvas_h = h + label_height + (padding * 2)
+        canvas = np.ones((canvas_h, canvas_w, 3), dtype=np.uint8) * 240  # Light gray bg
+        
+        # Place images
+        y_offset = label_height + padding
+        
+        # Figma (left)
+        x1 = padding
+        canvas[y_offset:y_offset+h, x1:x1+w] = figma_arr
+        
+        # Website (center)
+        x2 = padding * 2 + w
+        canvas[y_offset:y_offset+h, x2:x2+w] = website_arr
+        
+        # Diff overlay (right)
+        x3 = padding * 3 + w * 2
+        canvas[y_offset:y_offset+h, x3:x3+w] = overlay
+        
+        # Convert to PIL for text
+        canvas_pil = Image.fromarray(canvas)
+        draw = ImageDraw.Draw(canvas_pil)
+        
+        # Try to use a font, fall back to default
+        try:
+            font = ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf", 20)
+            small_font = ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", 14)
+        except:
+            font = ImageFont.load_default()
+            small_font = font
+        
+        # Add labels
+        draw.text((x1 + w//2 - 60, 10), "FIGMA DESIGN", fill=(0, 0, 0), font=font)
+        draw.text((x2 + w//2 - 40, 10), "WEBSITE", fill=(0, 0, 0), font=font)
+        draw.text((x3 + w//2 - 80, 10), "DIFFERENCES", fill=(255, 0, 0), font=font)
+        
+        # Add similarity score
+        score_text = f"Similarity: {similarity:.1f}%"
+        draw.text((canvas_w - 150, canvas_h - 30), score_text, fill=(0, 100, 0), font=small_font)
+        
+        # Save
+        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+        canvas_pil.save(output_path)
+        print(f"     ✓ Saved comparison: {output_path}")
+        
+        # Detect specific differences
+        differences = self._detect_differences(figma_arr, website_arr, diff_mask, viewport)
+        
+        return {
+            "viewport": viewport,
+            "similarity_score": similarity,
+            "diff_percentage": diff_percentage,
+            "comparison_image": output_path,
+            "differences": differences,
+            "scale_applied": scale
+        }
+    
+    def _detect_differences(
+        self,
+        figma_arr: np.ndarray,
+        website_arr: np.ndarray,
+        diff_mask: np.ndarray,
+        viewport: str
+    ) -> List[Dict[str, Any]]:
+        """
+        Detect and categorize specific differences.
+        
+        Returns:
+            List of detected differences with details
+        """
+        differences = []
+        
+        # 1. Check overall color difference
+        figma_mean = np.mean(figma_arr, axis=(0, 1))
+        website_mean = np.mean(website_arr, axis=(0, 1))
+        color_diff = np.linalg.norm(figma_mean - website_mean)
+        
+        if color_diff > 10:
+            differences.append({
+                "category": "colors",
+                "severity": "Medium" if color_diff < 30 else "High",
+                "title": "Color scheme differs",
+                "description": f"Average color difference detected (delta: {color_diff:.1f})",
+                "viewport": viewport
+            })
+        
+        # 2. Check for significant regions of difference
+        # Find contours in diff mask
+        _, binary = cv2.threshold(diff_mask, 50, 255, cv2.THRESH_BINARY)
+        contours, _ = cv2.findContours(binary, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+        
+        # Filter significant contours (larger than 1% of image)
+        min_area = (figma_arr.shape[0] * figma_arr.shape[1]) * 0.01
+        significant_regions = [c for c in contours if cv2.contourArea(c) > min_area]
+        
+        if len(significant_regions) > 0:
+            differences.append({
+                "category": "layout",
+                "severity": "High" if len(significant_regions) > 5 else "Medium",
+                "title": f"Layout differences in {len(significant_regions)} regions",
+                "description": f"Found {len(significant_regions)} areas with significant visual differences",
+                "viewport": viewport,
+                "regions_count": len(significant_regions)
+            })
+        
+        # 3. Check edges/borders
+        figma_edges = cv2.Canny(cv2.cvtColor(figma_arr, cv2.COLOR_RGB2GRAY), 50, 150)
+        website_edges = cv2.Canny(cv2.cvtColor(website_arr, cv2.COLOR_RGB2GRAY), 50, 150)
+        edge_diff = np.abs(figma_edges.astype(float) - website_edges.astype(float))
+        edge_diff_percentage = np.mean(edge_diff) / 255 * 100
+        
+        if edge_diff_percentage > 5:
+            differences.append({
+                "category": "structure",
+                "severity": "Medium",
+                "title": "Element borders/edges differ",
+                "description": f"Edge structure differs by {edge_diff_percentage:.1f}%",
+                "viewport": viewport
+            })
+        
+        return differences
+    
+    def compare_all_viewports(
+        self,
+        figma_screenshots: Dict[str, str],
+        website_screenshots: Dict[str, str],
+        figma_dims: Dict[str, Dict[str, int]],
+        website_dims: Dict[str, Dict[str, int]],
+        execution_id: str
+    ) -> Dict[str, Any]:
+        """
+        Compare all viewports and generate comprehensive results.
+        
+        Returns:
+            Complete comparison results
+        """
+        results = {
+            "comparisons": {},
+            "all_differences": [],
+            "viewport_scores": {},
+            "overall_score": 0.0
+        }
+        
+        viewports = set(figma_screenshots.keys()) & set(website_screenshots.keys())
+        
+        for viewport in viewports:
+            output_path = f"{self.output_dir}/comparison_{viewport}_{execution_id}.png"
+            
+            comparison = self.create_comparison_image(
+                figma_screenshots[viewport],
+                website_screenshots[viewport],
+                output_path,
+                figma_dims.get(viewport, {}),
+                website_dims.get(viewport, {}),
+                viewport
+            )
+            
+            results["comparisons"][viewport] = comparison
+            results["all_differences"].extend(comparison["differences"])
+            results["viewport_scores"][viewport] = comparison["similarity_score"]
+        
+        # Calculate overall score (average of viewports)
+        if results["viewport_scores"]:
+            results["overall_score"] = sum(results["viewport_scores"].values()) / len(results["viewport_scores"])
+        
+        return results

utils/website_capturer.py

@@ -0,0 +1,117 @@
+"""
+Website Screenshot Capturer
+Uses Playwright to capture full-page screenshots of websites.
+"""
+
+import asyncio
+from pathlib import Path
+from typing import Dict, Tuple
+
+
+async def _capture_screenshots_async(
+    website_url: str,
+    output_dir: str,
+    execution_id: str,
+    desktop_width: int = 1440,
+    mobile_width: int = 375
+) -> Tuple[Dict[str, str], Dict[str, Dict[str, int]]]:
+    """
+    Async function to capture website screenshots.
+    
+    Captures full-page screenshots at desktop and mobile viewports.
+    """
+    from playwright.async_api import async_playwright
+    
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
+    screenshots = {}
+    dimensions = {}
+    
+    async with async_playwright() as p:
+        browser = await p.chromium.launch(headless=True)
+        
+        try:
+            # Desktop capture
+            print(f"  📱 Capturing desktop ({desktop_width}px width, full height)...")
+            page = await browser.new_page(viewport={"width": desktop_width, "height": 1080})
+            await page.goto(website_url, wait_until="networkidle", timeout=60000)
+            
+            # Wait for any lazy-loaded content
+            await page.wait_for_timeout(2000)
+            
+            # Get full page height
+            desktop_height = await page.evaluate("() => document.documentElement.scrollHeight")
+            print(f"     ℹ️  Desktop full height: {desktop_height}px")
+            
+            # Set viewport to full height and capture
+            await page.set_viewport_size({"width": desktop_width, "height": desktop_height})
+            desktop_path = f"{output_dir}/desktop_{execution_id}.png"
+            await page.screenshot(path=desktop_path, full_page=True)
+            
+            screenshots["desktop"] = desktop_path
+            dimensions["desktop"] = {"width": desktop_width, "height": desktop_height}
+            print(f"     ✓ Saved: {desktop_path}")
+            
+            await page.close()
+            
+            # Mobile capture
+            print(f"  📱 Capturing mobile ({mobile_width}px width, full height)...")
+            page = await browser.new_page(viewport={"width": mobile_width, "height": 812})
+            
+            # Set mobile user agent
+            await page.set_extra_http_headers({
+                "User-Agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/605.1.15"
+            })
+            
+            await page.goto(website_url, wait_until="networkidle", timeout=60000)
+            await page.wait_for_timeout(2000)
+            
+            # Get full page height
+            mobile_height = await page.evaluate("() => document.documentElement.scrollHeight")
+            print(f"     ℹ️  Mobile full height: {mobile_height}px")
+            
+            # Set viewport to full height and capture
+            await page.set_viewport_size({"width": mobile_width, "height": mobile_height})
+            mobile_path = f"{output_dir}/mobile_{execution_id}.png"
+            await page.screenshot(path=mobile_path, full_page=True)
+            
+            screenshots["mobile"] = mobile_path
+            dimensions["mobile"] = {"width": mobile_width, "height": mobile_height}
+            print(f"     ✓ Saved: {mobile_path}")
+            
+            await page.close()
+            
+        finally:
+            await browser.close()
+    
+    return screenshots, dimensions
+
+
+def capture_website_screenshots(
+    website_url: str,
+    output_dir: str,
+    execution_id: str,
+    desktop_width: int = 1440,
+    mobile_width: int = 375
+) -> Tuple[Dict[str, str], Dict[str, Dict[str, int]]]:
+    """
+    Synchronous wrapper for capturing website screenshots.
+    
+    Args:
+        website_url: URL of the website to capture
+        output_dir: Directory to save screenshots
+        execution_id: Unique ID for this execution
+        desktop_width: Desktop viewport width (default 1440)
+        mobile_width: Mobile viewport width (default 375)
+    
+    Returns:
+        Tuple of (screenshot_paths_dict, dimensions_dict)
+    """
+    return asyncio.run(
+        _capture_screenshots_async(
+            website_url,
+            output_dir,
+            execution_id,
+            desktop_width,
+            mobile_width
+        )
+    )

workflow.py

@@ -0,0 +1,107 @@
+"""
+LangGraph Workflow Orchestration
+Manages the flow between agents with persistence and breakpoints.
+"""
+
+from typing import Dict, Any
+from langgraph.graph import StateGraph, END
+from langgraph.checkpoint.memory import MemorySaver
+from state_schema import WorkflowState, create_initial_state
+from agents import (
+    agent_0_node,
+    agent_1_node,
+    agent_2_node,
+    agent_3_node
+)
+
+# Global checkpointer to persist state between function calls
+_global_checkpointer = MemorySaver()
+
+
+def create_workflow():
+    """Create the LangGraph workflow with persistence."""
+    global _global_checkpointer
+    
+    workflow = StateGraph(WorkflowState)
+    
+    # Add nodes (agents)
+    workflow.add_node("initialize", agent_0_node)      # Validate & plan
+    workflow.add_node("capture_figma", agent_1_node)   # Figma screenshots
+    workflow.add_node("capture_website", agent_2_node) # Website screenshots
+    workflow.add_node("compare", agent_3_node)         # Visual comparison
+    
+    # Define flow
+    workflow.set_entry_point("initialize")
+    workflow.add_edge("initialize", "capture_figma")
+    workflow.add_edge("capture_figma", "capture_website")
+    workflow.add_edge("capture_website", "compare")  # Breakpoint before compare
+    workflow.add_edge("compare", END)
+    
+    # Compile with persistence and breakpoint
+    return workflow.compile(
+        checkpointer=_global_checkpointer,
+        interrupt_before=["compare"]  # Pause before analysis for human review
+    )
+
+
+def run_workflow_step_1(
+    figma_id: str,
+    figma_key: str,
+    url: str,
+    execution_id: str,
+    thread_id: str,
+    hf_token: str = ""
+):
+    """
+    Run the first part of the workflow (capture screenshots).
+    Stops at the breakpoint before analysis.
+    """
+    print(f"  ⚙️  Initializing workflow for thread: {thread_id}")
+    
+    app = create_workflow()
+    config = {"configurable": {"thread_id": thread_id}}
+    
+    initial_state = create_initial_state(
+        figma_file_key=figma_id,
+        figma_access_token=figma_key,
+        website_url=url,
+        execution_id=execution_id,
+        hf_token=hf_token
+    )
+    
+    print("  🏃 Running workflow (Step 1: Capture)...")
+    
+    try:
+        for event in app.stream(initial_state, config, stream_mode="values"):
+            if event:
+                status = event.get("status", "")
+                if status:
+                    print(f"    📍 Status: {status}")
+    except Exception as e:
+        print(f"  ❌ Workflow error: {str(e)}")
+        raise
+    
+    return app.get_state(config)
+
+
+def resume_workflow(thread_id: str, user_approval: bool = True):
+    """
+    Resume the workflow after human approval.
+    Continues from the breakpoint to run analysis.
+    """
+    print(f"  🔄 Resuming workflow for thread: {thread_id}")
+    
+    app = create_workflow()
+    config = {"configurable": {"thread_id": thread_id}}
+    
+    # Update state with approval
+    app.update_state(config, {"user_approval": user_approval})
+    
+    print("  🏃 Running workflow (Step 2: Analysis)...")
+    
+    # Resume execution
+    state = None
+    for event in app.stream(None, config, stream_mode="values"):
+        state = event
+    
+    return app.get_state(config)