backend/docs/VERSION_COMPARISON.md

Version Comparison Feature

Overview

After regenerating screenshots with new settings, the system displays an interactive slider-based comparison that lets you drag a center line to see the differences between versions. This professional, device-friendly interface makes it easy to compare quality and choose which version to keep.

Visual Layout

┌─────────────────────────────────────────────────────────────┐
│  Compare versions and choose which to keep. Drag the slider │
└─────────────────────────────────────────────────────────────┘

        [Keep Previous Version]  [Keep New Version]

┌──────────────────────────────────────────────────────────────┐
│  ← Previous        Part 1              New →                 │
├──────────────────────────────────────────────────────────────┤
│                          │                                    │
│   Previous Image         │  New Image                         │
│                          │                                    │
│                      [Draggable                               │
│                       Slider]                                 │
│                          │                                    │
└──────────────────────────────────────────────────────────────┘
         Drag the center line left/right to compare

Interactive Slider

Features

• Draggable Center Line: Drag left or right to reveal more of either version
• Visual Handle: White circular handle with arrows for easy grabbing
• Smooth Animation: Fluid movement as you drag
• Touch Support: Works on mobile devices and tablets
• Responsive: Adapts to any screen size
• Professional Look: Clean design with subtle shadows

How to Use

1. Click and Drag: Click the center handle and drag left/right
2. Touch and Drag: On mobile, touch and drag the handle
3. Compare: Move the slider to see differences in quality, layout, zoom
4. Choose: Click "Keep Previous Version" or "Keep New Version" at the top

User Flow

Step 1: Regenerate

User changes settings and clicks "Regenerate with New Settings"

Step 2: Slider Comparison

System displays interactive sliders:

• One slider for each screenshot pair
• Previous version on left (gray label)
• New version on right (green label)
• Draggable center line at 50% position

Step 3: Interactive Review

User can:

• Drag each slider to compare versions
• See exact differences in zoom, quality, layout
• Compare multiple screenshots if available
• Works smoothly on desktop and mobile

Step 4: Choose Version

User clicks one of the buttons at top:

• "Keep Previous Version" (left button)
• "Keep New Version" (right button)

Step 5: Confirmation

System shows confirmation dialog:

Keep [previous/new] version? 
This will delete X file(s) from the other version.

Step 6: Automatic Cleanup

After confirmation:

• Selected version's files are kept
• Other version's files are deleted from server
• Display updates to show only kept version
• Notification confirms the action

Visual Design

Slider Components

Header Bar:

• Light gray background
• "← Previous" label on left
• "Part X" in center
• "New →" label on right (green)

Slider Container:

• White border and shadow
• Rounded corners
• Hover effect (lifts slightly)
• Responsive width (max 1200px)

Center Handle:

• White circular button (48px)
• Up/down arrows icon
• Drop shadow for depth
• Scales on hover
• Smooth transitions

Divider Line:

• Vertical white line (4px)
• Extends full height
• Shadow for visibility
• Moves with handle

Special Cases

Different Screenshot Counts:

• If previous has more: Shows warning badge "⚠️ Only in Previous Version"
• If new has more: Shows success badge "✨ Only in New Version"
• Single-version screenshots shown with colored borders

Color Coding:

• Previous only: Yellow/amber border (#ffc107)
• New only: Green border (#4CAF50)
• Comparison: White divider line

Technical Implementation

Function: showVersionComparison(type, previousFiles, newFiles)

Creates the slider-based comparison:

• Generates action buttons at top
• Creates slider for each screenshot pair
• Handles different screenshot counts
• Initializes interactive sliders

Function: initComparisonSlider(sliderId)

Makes sliders interactive:

• Sets up mouse event listeners
• Sets up touch event listeners
• Handles drag calculations
• Updates overlay width and handle position
• Prevents image dragging

Event Handling

// Mouse events
mousedown → start dragging
mousemove → update position
mouseup → stop dragging

// Touch events
touchstart → start dragging
touchmove → update position
touchend → stop dragging

Position Calculation

const rect = slider.getBoundingClientRect();
const offsetX = x - rect.left;
const percentage = (offsetX / rect.width) * 100;
// Clamp between 0-100%

Example Scenario

Initial Generation

Settings: Zoom 2.5x, Viewport 1920x1080
Result: 3 screenshots created

Regeneration

Changed Settings: Zoom 3.5x, Viewport 1280x720
Result: 3 screenshots created

Slider Comparison

Part 1: [Slider] - Drag to compare zoom difference
Part 2: [Slider] - Drag to compare zoom difference  
Part 3: [Slider] - Drag to compare zoom difference

User Interaction

1. Drag Part 1 slider → See zoom 2.5x vs 3.5x
2. Drag Part 2 slider → Compare layout changes
3. Drag Part 3 slider → Check text readability
4. Click "Keep New Version"
5. Confirm deletion
6. Old version deleted, new version kept

Benefits

1. Professional Interface: Modern slider design like image editing tools
2. Easy Comparison: Drag to see exact differences
3. Device Friendly: Works on desktop, tablet, and mobile
4. Intuitive: Natural drag interaction
5. Precise: See differences pixel-by-pixel
6. Responsive: Adapts to any screen size
7. Touch Optimized: Smooth touch gestures on mobile

Responsive Design

Desktop (>768px)

• Full-width sliders (max 1200px)
• 48px handle size
• Hover effects enabled
• Mouse drag support

Mobile (≤768px)

• Full-width sliders
• 40px handle size (easier to tap)
• Touch drag support
• Optimized spacing

CSS Features

Animations

• Smooth handle movement
• Hover scale effect
• Active press effect
• Shadow transitions

Visual Polish

• Box shadows for depth
• Border radius for modern look
• Subtle hover lift effect
• Crisp image rendering

Error Handling

Edge Cases

• No previous version: Shows only new version
• Different file counts: Shows badges for unique screenshots
• Failed image load: Browser handles gracefully
• Touch/mouse conflicts: Proper event handling

Browser Compatibility

• Modern browsers: Full slider support
• Touch devices: Native touch events
• Older browsers: Graceful degradation

Future Enhancements

Potential improvements:

• Keyboard arrow key support
• Double-click to reset to 50%
• Zoom in/out on images
• Settings diff display
• Animation between positions
• Preset positions (25%, 50%, 75%)
• Fullscreen comparison mode