v1.2.3

Screenshot CLI v1.2.3 Release Notes

🔧 Enhancement Release: Verbose Logging Control

Version: 1.2.3
Type: Patch Release (Enhancement)
Release Date: September 25, 2025

---

🎯 Overview

Version 1.2.3 introduces a new --verbose flag that provides users with fine-grained control over image loading progress logging. This enhancement addresses the need for cleaner output during normal operations while maintaining the ability to access detailed diagnostic information when troubleshooting image loading issues with the images wait strategy.

✨ New Features

🗣️ Verbose Logging Control

New Command Line Option

• -v, --verbose - Enable detailed image loading progress logging

Key Benefits

• Clean Default Output: Normal operations now show minimal, essential logging only
• Detailed Diagnostics: Enable comprehensive image loading progress when needed
• Better User Experience: Reduces console noise for everyday screenshot capture
• Enhanced Debugging: Full visibility into image loading process when troubleshooting
• Backward Compatible: Existing commands work unchanged, verbose logging is opt-in

Example Usage

# Normal operation with minimal logging
pnpm capture --wait-strategy images --file urls.txt

# Enable detailed image loading progress
pnpm capture --wait-strategy images --verbose --file urls.txt

# Combine with custom timeout for comprehensive debugging
pnpm capture --wait-strategy images --verbose --image-wait-timeout 20000 --file urls.txt

📊 Logging Behavior

Without --verbose Flag (Default)

Clean, minimal output focusing on essential information:

🚀 Starting screenshot capture...
📋 Found 5 URLs to process
✔ Browser launched
📷 Taking screenshots...
✔ Screenshot saved: https://example.com
💾 Saving data file...
✅ Complete! Screenshot capture finished in 45s

With --verbose Flag

Detailed image loading diagnostics:

🚀 Starting screenshot capture...
📋 Found 5 URLs to process
✔ Browser launched
📷 Taking screenshots...
🖼️  Starting image loading detection with 10000ms timeout...
📊 Image analysis:
   • Found 23 <img> elements
   • Found 3 elements with background images
   ✅ Loaded Image 1: https://cdn.example.com/logo.png...
   ⏳ Loading Image 2: https://cdn.example.com/hero.jpg...
   ✅ Loaded Image 2: https://cdn.example.com/hero.jpg...
🎨 Background images found:
   • DIV.hero-section: url("https://cdn.example.com/bg.jpg")...
📜 Scrolling through page to trigger lazy loading...
📈 Image loading completed in 3.2s:
   • Total images: 23
   • Successfully loaded: 21
   • Failed to load: 1
   • Timed out: 1
✅ All images successfully loaded!
✔ Screenshot saved: https://example.com
💾 Saving data file...
✅ Complete! Screenshot capture finished in 45s

🔧 Technical Implementation

Enhanced Image Loading Detection

The verbose flag controls the visibility of:

• Image Discovery: Detailed analysis of found <img> elements and background images
• Loading Progress: Individual image loading status and progress updates
• Lazy Loading Activation: Scrolling behavior for triggering deferred image loading
• Timeout Handling: Individual image timeout warnings and error reporting
• Final Statistics: Comprehensive summary of image loading results

Performance Impact

• Zero Performance Cost: The verbose flag only affects logging output, not processing speed
• Conditional Logging: All detailed logging is conditionally executed based on the flag
• Memory Efficient: No additional memory overhead when verbose mode is disabled

📋 Use Cases & Workflows

1. Production Monitoring (Default Behavior)

# Clean output for automated scripts and production monitoring
pnpm capture --wait-strategy images --file production-urls.txt --title "Production-Check"

2. Development and Debugging

# Detailed diagnostics for troubleshooting image loading issues
pnpm capture --wait-strategy images --verbose --file development-urls.txt --title "Debug-Session"

3. Performance Analysis

# Monitor image loading performance with detailed timing information
pnpm capture --wait-strategy images --verbose --image-wait-timeout 30000 --file performance-urls.txt

4. CI/CD Integration

# Clean logs for CI/CD pipelines with optional verbose mode for debugging
pnpm capture --wait-strategy images --file urls.txt --title "CI-Screenshots"

# Enable verbose for debugging CI issues
pnpm capture --wait-strategy images --verbose --file urls.txt --title "CI-Debug"

⚠️ Important Usage Guidelines

When to Use Verbose Mode

✅ Recommended For:

• Debugging image loading issues
• Performance analysis of image-heavy sites
• Understanding lazy loading behavior
• Troubleshooting timeout problems
• Development and testing phases

⚠️ Not Necessary For:

• Regular production screenshot capture
• Automated monitoring scripts
• CI/CD pipelines (unless debugging)
• Sites with minimal image content

Best Practices

# Start without verbose for normal operations
pnpm capture --wait-strategy images --file urls.txt

# Enable verbose only when you need detailed diagnostics
pnpm capture --wait-strategy images --verbose --file problematic-urls.txt

# Use with increased timeout for comprehensive analysis
pnpm capture --wait-strategy images --verbose --image-wait-timeout 25000 --file slow-sites.txt

🛠️ Breaking Changes

⚠️ None

This is a fully backward-compatible release. All existing commands, workflows, and scripts continue to work exactly as before. The verbose flag is completely optional and defaults to disabled, ensuring no changes to existing behavior.

🔄 Migration Guide

From v1.2.2 to v1.2.3

No migration needed! This release is fully backward compatible.

Optional: Adopt Verbose Logging

# Current workflow (continues to work unchanged)
pnpm capture --wait-strategy images --file urls.txt
# Now shows cleaner, minimal output

# New option: Enable detailed diagnostics when needed
pnpm capture --wait-strategy images --verbose --file urls.txt
# Shows comprehensive image loading progress

📖 Documentation Updates

Enhanced README

• New Logging & Debugging section: Complete coverage of verbose flag
• Updated examples: Practical usage scenarios for verbose mode
• Best practices guide: When and how to use verbose logging
• Version history: Updated with v1.2.3 entry

Improved User Experience

• Cleaner default output: Reduced console noise for regular usage
• On-demand diagnostics: Detailed information available when needed
• Better debugging: Enhanced troubleshooting capabilities for image loading issues

📊 Performance & Compatibility

Performance Characteristics

• No Performance Impact: Verbose flag affects only logging output
• Conditional Execution: Detailed logging only runs when enabled
• Memory Efficient: Zero additional memory overhead when disabled
• Network Neutral: No impact on network requests or image loading speed

Compatibility

• ✅ Node.js: 16.x, 18.x, 20.x+
• ✅ Operating Systems: Windows, macOS, Linux
• ✅ Browsers: Chromium (via Playwright)
• ✅ Existing Scripts: All current commands work unchanged
• ✅ CI/CD Systems: Compatible with all automation platforms

🔧 Development Improvements

Code Quality Enhancements

• Dynamic Versioning: Data persistence now uses dynamic version from package.json
• Consistent Logging: Unified approach to conditional logging throughout the codebase
• Type Safety: Enhanced TypeScript interfaces for verbose option handling

Maintenance Benefits

• Automatic Version Sync: Data file versions stay synchronized with package.json
• Reduced Manual Updates: No more hardcoded version strings to maintain
• Future-Proof: Version management improvements for easier releases

🙏 Acknowledgments

This release addresses user feedback requesting cleaner console output during normal operations while maintaining the ability to access detailed diagnostic information when needed. The verbose flag provides the perfect balance between clean everyday usage and comprehensive debugging capabilities.

📝 Summary

Version 1.2.3 enhances the user experience by providing:

• Cleaner default output for everyday screenshot capture
• Detailed diagnostics on demand with the --verbose flag
• Better debugging capabilities for image loading troubleshooting
• Backward compatibility with all existing workflows
• Improved maintainability with dynamic version management

The verbose flag gives users complete control over the level of detail in their console output, making Screenshot CLI more suitable for both interactive debugging sessions and automated production workflows.

v1.2.2

Screenshot CLI v1.2.2 Release Notes

🚀 Feature Release: Intelligent Image Loading Detection

Version: 1.2.2
Type: Minor Release (New Feature)
Release Date: September 25, 2025

---

🎯 Overview

Version 1.2.2 introduces a revolutionary new wait strategy for screenshot capture: Intelligent Image Loading Detection. This enhancement ensures that all images—including lazy-loaded, background, and dynamically loaded images—are fully loaded before taking screenshots, resulting in more complete and reliable visual captures for image-heavy websites.

✨ New Features

🖼️ Images Wait Strategy

New Wait Strategy Option

• --wait-strategy images - Comprehensive image loading detection and waiting
• --image-wait-timeout <timeout> - Configurable timeout for image loading (default: 10000ms)

Key Capabilities

• Complete Image Detection: Finds all <img> elements and elements with background images
• Lazy Loading Support: Detects and triggers lazy-loaded images through intelligent scrolling
• Individual Image Tracking: Monitors each image's loading state with detailed progress reporting
• Timeout Management: Per-image timeout handling to prevent indefinite waiting
• Comprehensive Logging: Detailed status reporting for troubleshooting and monitoring

Example Usage

# Basic image loading detection
pnpm capture --wait-strategy images --file urls.txt

# Custom image timeout for slower loading sites
pnpm capture --wait-strategy images --image-wait-timeout 15000 --file urls.txt

# Combine with other options for comprehensive capture
pnpm capture --wait-strategy images --image-wait-timeout 20000 \
  --before --json-only --title "Image-Heavy-Site"

🔄 Intelligent Scrolling System

Lazy Loading Activation

• Progressive Scrolling: Automatically scrolls through the entire page to trigger lazy-loaded images
• Viewport-Based Movement: Scrolls in half-viewport increments for optimal lazy loading activation
• Return to Top: Automatically scrolls back to the original position after triggering all images
• Configurable Delays: Built-in delays between scroll actions to allow images to load

Smart Detection Patterns

• Data Attributes: Detects data-src, data-lazy, and similar lazy loading patterns
• CSS Classes: Identifies common lazy loading class names like .lazy
• Loading States: Monitors HTML5 loading attribute states
• Visibility Tracking: Distinguishes between visible and hidden images

📊 Enhanced Image Analysis & Logging

Comprehensive Image Status Reporting

🖼️  Starting image loading detection with 15000ms timeout...
📊 Image analysis:
   • Found 24 <img> elements
   • Found 8 elements with background images
   ✅ Loaded Image 1: https://example.com/hero-image.jpg...
   ⏳ Loading Image 2: https://example.com/lazy-image.jpg... (LAZY)
   🎨 Background images found:
   • DIV.hero-section: url("https://example.com/bg.jpg")...
📜 Scrolling through page to trigger lazy loading...
📈 Image loading completed in 3247ms:
   • Total images: 24
   • Successfully loaded: 22
   • Failed to load: 1
   • Timed out: 1
✅ All images successfully loaded!

Detailed Progress Tracking

• Real-time Status: Live updates as each image loads or fails
• Loading Statistics: Summary of total, loaded, failed, and timed-out images
• Error Reporting: Clear indication of which images failed to load with reasons
• Performance Metrics: Timing information for optimization insights

🌐 Enhanced Site Compatibility

Improved User Agent

• Realistic Browser Identity: Uses Chrome user agent to avoid bot detection
• Better Site Access: Reduces likelihood of being blocked by anti-bot measures
• Consistent Behavior: Ensures more predictable website behavior during capture

WordPress & Staging Site Optimizations

• Existing Timeout Logic: Maintains current intelligent timeout adjustments
• Enhanced Reliability: Better handling of slower staging and WordPress environments
• Seamless Integration: Works alongside existing site-specific optimizations

🔧 Technical Implementation

Enhanced Wait Strategy Architecture

Multi-Phase Loading Process

1. Initial Page Load: Standard page loading using specified wait strategy
2. Image Discovery: Comprehensive scan for all image elements and background images
3. Lazy Loading Activation: Intelligent scrolling to trigger deferred loading
4. Individual Image Monitoring: Promise-based tracking of each image's load state
5. Timeout Management: Per-image timeout handling with graceful degradation

Advanced Image Detection

// Detects both standard and background images
const images = Array.from(document.querySelectorAll('img'));
const backgroundImages = Array.from(document.querySelectorAll('*')).filter((el) => {
  const style = window.getComputedStyle(el);
  return style.backgroundImage && style.backgroundImage !== 'none';
});

Performance Optimizations

• Parallel Processing: All images monitored simultaneously for optimal performance
• Memory Efficient: Minimal overhead with smart cleanup of event listeners
• Graceful Degradation: Continues screenshot capture even if some images fail to load
• Configurable Timeouts: Prevents indefinite waiting while maximizing image loading success

📋 Use Cases & Workflows

1. E-commerce Product Pages

# Ensure all product images load before screenshot
pnpm capture --wait-strategy images --image-wait-timeout 20000 \
  --file product-urls.txt --title "Product-Catalog"

2. Marketing Landing Pages

# Capture complete hero sections with background images
pnpm capture --wait-strategy images --before \
  --urls "https://marketing-site.com/landing" --title "Landing-Page-Test"

3. News and Media Sites

# Handle lazy-loaded article images and advertisements
pnpm capture --wait-strategy images --image-wait-timeout 15000 \
  --file news-urls.txt --title "Media-Site-Monitoring"

4. Social Media and Galleries

# Comprehensive image loading for gallery-heavy sites
pnpm capture --wait-strategy images --image-wait-timeout 25000 \
  --before-after --file gallery-urls.txt --title "Gallery-Comparison"

⚠️ Important Usage Guidelines

When to Use Images Wait Strategy

✅ Recommended For:

• Image-heavy websites (e-commerce, portfolios, galleries)
• Sites with lazy-loaded content
• Marketing pages with background images
• Social media platforms
• News sites with inline images

⚠️ Use With Caution For:

• Simple text-based sites (unnecessary overhead)
• Sites with very slow image loading (increase timeout)
• High-volume automated testing (may slow down capture)

Timeout Configuration

# Fast sites (default)
--image-wait-timeout 10000

# Medium-speed sites
--image-wait-timeout 15000

# Slow or image-heavy sites
--image-wait-timeout 20000

# Very slow international sites
--image-wait-timeout 30000

Best Practices

• Start with default timeout: 10 seconds works for most sites
• Monitor logs: Use detailed logging to optimize timeout values
• Test incrementally: Start with a few URLs to determine optimal settings
• Combine strategies: Use with --before-after for comprehensive testing

🛠️ Breaking Changes

⚠️ None

This is a fully backward-compatible release. All existing commands, workflows, and data files continue to work exactly as before. The new images wait strategy is completely optional and doesn't affect existing functionality.

🔄 Migration Guide

From v1.2.1 to v1.2.2

No migration needed! This release is fully backward compatible.

Optional: Adopt Images Wait Strategy

# Current workflow (continues to work)
pnpm capture --wait-strategy load --file urls.txt
# Standard page loading, may miss some images

# New option: Comprehensive image loading
pnpm capture --wait-strategy images --file urls.txt
# Ensures all images are loaded before screenshot

# Enhanced with custom timeout
pnpm capture --wait-strategy images --image-wait-timeout 15000 --file urls.txt

📖 Documentation Updates

Comprehensive README Enhancements

• New wait strategy documentation: Complete coverage of images strategy
• Usage examples: Real-world scenarios for image-heavy sites
• Best practices guide: When and how to use image loading detection
• Troubleshooting section: Common issues and solutions
• Performance considerations: Timeout optimization guidelines

Enhanced Content

• Command reference updates: All relevant commands show new options
• Workflow patterns: Updated common patterns with image loading examples
• Feature comparison: Clear differences between wait strategies
• Real-world examples: E-commerce, media, and gallery site examples

📊 Performance & Compatibility

Performance Characteristics

• Image Detection: ~50-200ms additional overhead for image discovery
• Loading Time: Varies by site (typically 2-10 seconds additional wait time)
• Memory Usage: Minimal additional memory footprint
• CPU Impact: Low impact during image monitoring phase

Compatibility

• ✅ Node.js: 16.x, 18.x, 20.x+
• ✅ Operating Systems: Windows, macOS, Linux
• ✅ Browsers: Chromium (via Playwright)
• ✅ Image Formats: All formats supported by browser (PNG, JPG, WEBP, SVG, GIF)
• ✅ Loading Patterns: Standard, lazy-loaded, background images, dynamic loading

🙏 Acknowledgments

This release addresses a long-standing challenge in auto...

v1.2.1

Screenshot CLI v1.2.1 Release Notes

🚀 Feature Release: JSON Output Format Support

Version: 1.2.1
Type: Patch Release (New Feature)

---

🎯 Overview

Version 1.2.1 introduces a new data output format option for users who prefer plain JSON files over the default JSONC (JSON with Comments) format. This enhancement provides flexibility for automated processing, CI/CD pipelines, and scenarios requiring minimal file size or strict JSON compliance.

✨ New Features

📄 JSON-Only Output Format

New Command Flag

• --json-only - Save data files as plain JSON instead of JSONC (JSON with comments)

Key Benefits

• Smaller file size: No comment overhead for storage-conscious environments
• Standard JSON: Fully compliant JSON for automated processing
• CI/CD friendly: Perfect for build pipelines and automated workflows
• Cross-platform: Better compatibility with JSON parsers that don't support comments

Example Usage

# Create plain JSON data file
pnpm capture --json-only --file urls.txt --title "CI-Build"
# Creates: ci-build-data.json (instead of ci-build-data.jsonc)

# Use with independent before/after workflow
pnpm capture --before --json-only --file urls.txt --title "Deploy-Check"
pnpm capture --after --json-only --file urls.txt --title "Deploy-Check"
# Creates and updates: deploy-check-data.json

🔄 Dual Format Support

Universal Command Compatibility

Both compare and generate commands now seamlessly work with either format:

# Works with JSONC files (default)
pnpm compare report-data.jsonc
pnpm generate report-data.jsonc

# Also works with JSON files
pnpm compare report-data.json
pnpm generate report-data.json

Smart File Detection

• Automatic format recognition: Commands detect file format by extension
• Cross-format compatibility: No need to specify format manually
• Seamless workflows: Switch between formats without changing commands

🔧 Technical Implementation

Enhanced Filename Generation

• Dynamic extensions: .json with --json-only, .jsonc by default
• Consistent naming: Maintains same filename structure across formats
• Path resolution: Updated logic handles both extensions correctly

Data Persistence Updates

• Format-aware saving: Conditional output based on flag
• Content optimization: Plain JSON uses JSON.stringify() for clean output
• Backward compatibility: Default JSONC behavior unchanged

CLI Integration

• Help text updates: All relevant commands mention both format support
• Error handling: Clear messages for format-related issues
• Option placement: Logically grouped under "Data File Format" section

⚠️ Important Usage Guidelines

Consistent Flag Usage

When using independent before/after modes (--before/--after), be consistent with the --json-only flag:

# ✅ Correct - consistent flag usage
pnpm capture --before --json-only --title "test" -u "https://example.com"
pnpm capture --after --json-only --title "test" -u "https://example.com"
# Result: Single test-data.json file with merged data

# ❌ Problematic - inconsistent flag usage
pnpm capture --before --json-only --title "test" -u "https://example.com"  # Creates test-data.json
pnpm capture --after --title "test" -u "https://example.com"              # Creates test-data.jsonc
# Result: Two separate files instead of merged data

Best Practices

• Choose your format early: Decide on JSON or JSONC at project start
• Document your choice: Make format preference clear in team workflows
• Automation-first: Use --json-only for CI/CD and automated processing
• Human-readable: Stick with JSONC for documentation and manual inspection

📋 Use Cases & Workflows

1. CI/CD Pipeline Integration

# Automated deployment verification
pnpm capture --before --json-only --file urls.txt --title "Build-${BUILD_ID}"
# Deploy application
pnpm capture --after --json-only --file urls.txt --title "Build-${BUILD_ID}"
# Generate reports for artifact storage
pnpm compare build-${BUILD_ID}-data.json
pnpm generate --report-type all build-${BUILD_ID}-data.json

2. Storage-Optimized Monitoring

# Long-term monitoring with minimal storage
pnpm capture --json-only --file monitoring-urls.txt --title "Daily-$(date +%Y-%m-%d)"
# Smaller files for better storage efficiency

3. API Integration

# Generate JSON for API consumption
pnpm capture --json-only --urls "https://api-docs.com" --title "API-Status"
# Parse JSON data in external systems
curl -X POST api.example.com/screenshots -d @api-status-data.json

🛠️ Breaking Changes

⚠️ None

This is a fully backward-compatible release. All existing commands, workflows, and data files continue to work exactly as before. The new --json-only flag is completely optional.

📖 Documentation Updates

Comprehensive README Enhancements

• New sections: Data file formats, JSON vs JSONC comparison
• Usage examples: JSON-only workflows and best practices
• Important warnings: Consistent flag usage guidelines
• Command updates: All relevant commands show both format support
• Workflow patterns: Updated common patterns with JSON examples

Enhanced Content

• Format comparison table: Clear differences between JSON and JSONC
• Troubleshooting guide: Common pitfalls and solutions
• Real-world examples: CI/CD and automation use cases
• Cross-command compatibility: Complete coverage of format support

🔄 Migration Guide

From v1.2.0 to v1.2.1

No migration needed! This release is fully backward compatible.

Optional: Adopt JSON Format

# Current workflow (continues to work)
pnpm capture --file urls.txt --title "Report"
# Creates: report-data.jsonc

# New option: JSON format
pnpm capture --json-only --file urls.txt --title "Report"
# Creates: report-data.json

# Both work with existing commands
pnpm compare report-data.jsonc  # Works
pnpm compare report-data.json   # Also works

📊 Performance & Compatibility

Performance Characteristics

• JSON files: ~15-20% smaller than JSONC (no comments)
• Parsing speed: Marginally faster JSON parsing (no comment stripping)
• Memory usage: Identical runtime memory footprint
• Processing time: No measurable difference in capture/compare operations

Compatibility

• ✅ Node.js: 16.x, 18.x, 20.x+
• ✅ Operating Systems: Windows, macOS, Linux
• ✅ JSON Parsers: Full compatibility with all standard JSON libraries
• ✅ Data Files: Both formats work with all existing and future commands

🙏 Acknowledgments

This release addresses user requests for cleaner JSON output in automated environments while maintaining the human-readable JSONC format for documentation and manual workflows. The dual-format approach provides the best of both worlds.

---

📥 Installation & Upgrade

New Installation

git clone git@github.com:refactorau/screenshot-cli.git
cd screenshot-cli
pnpm install
pnpx playwright install chromium
pnpm build

Upgrading from v1.2.0

git pull origin main
pnpm install
pnpm build

Verify Installation

pnpm capture --help
# Should show new --json-only option in help text

🏷️ Release Assets

• Source Code: Available on GitHub
• Documentation: Updated README.md with format comparison and examples
• Migration Guide: This document (no migration needed)
• Examples: JSON workflow patterns and best practices

---

Happy Screenshot Capturing! 📸

The Screenshot CLI Team

v1.2.0

Screenshot CLI v1.2.0 Release Notes

🚀 Major Feature Release: Independent Before/After Capture

Release Date: TBD
Version: 1.2.0
Type: Minor Release (New Features)

---

🎯 Overview

Version 1.2.0 introduces a revolutionary new workflow for before/after screenshot comparison: Independent Capture Mode. This allows you to capture "before" and "after" screenshots at completely different times, making the tool perfect for deployment verification, A/B testing, long-term monitoring, and any scenario where you need flexible timing between captures.

✨ New Features

🆕 Independent Before/After Capture Modes

New Command Flags

• --before - Capture only before screenshots
• --after - Capture only after screenshots
• --before-after - Original sequential mode (unchanged)

Mutual Exclusion: Only one of these flags can be used at a time, with clear error messages for conflicts.

Example Workflow

# Step 1: Capture before screenshots (e.g., before deployment)
pnpm capture --before --file urls.txt --title "Deploy-v2.1"

# Step 2: Deploy your changes...

# Step 3: Later, capture after screenshots (e.g., after deployment)
pnpm capture --after --file urls.txt --title "Deploy-v2.1"

# Step 4: Generate comparison report
pnpm compare deploy-v2.1-data.jsonc
pnpm generate deploy-v2.1-data.jsonc

🔁 Smart Data Merging

Intelligent Data Persistence

• Timestamp Preservation: Original capture times are never overwritten
• Partial Updates: Re-capture specific URLs without losing other data
• Automatic Merging: Seamlessly combines new captures with existing data
• Data Integrity: Maintains consistency across all merge operations

Before/After Timestamp Management

• Separate beforeTimestamp and afterTimestamp fields
• Proper preservation when re-capturing either phase
• Works bidirectionally (before→after or after→before)

Single Mode Merging

• Added smart merging to single screenshot mode
• Re-capture individual URLs without losing existing data
• Preserves unmodified URLs and their timestamps

📊 Enhanced Data Structure

New ScreenshotResult Fields

interface ScreenshotResult {
  // ... existing fields
  beforeTimestamp?: Date; // NEW: Specific before capture time
  afterTimestamp?: Date; // NEW: Specific after capture time
}

Improved Data File Format

• Accurate timestamp tracking for each capture phase
• Better support for partial data states
• Enhanced metadata preservation

🔧 Technical Improvements

Merging Logic Enhancements

• Cross-Mode Compatibility: Merge data from any capture mode
• Conflict Resolution: Intelligent handling of overlapping data
• State Preservation: Maintains existing screenshots and metadata
• Error Handling: Graceful fallback when merging fails

Timestamp System Overhaul

• Phase-Specific Tracking: Each capture phase has its own timestamp
• Preservation Logic: Original timestamps never overwritten during merging
• Fallback Handling: Smart defaults when timestamp data is missing
• JSON Serialization Fix: Proper handling of undefined values in data files

Data Persistence Improvements

• Merge Detection: Automatically detects existing data files
• Smart Updates: Only modifies data that's being re-captured
• Backward Compatibility: Existing data files continue to work
• Enhanced Validation: Better error detection and reporting

📋 Use Cases & Workflows

1. Deployment Verification

# Before deployment
pnpm capture --before --file production-urls.txt --title "Deploy-v2.1"
# Deploy changes
pnpm capture --after --file production-urls.txt --title "Deploy-v2.1"
# Compare results
pnpm compare deploy-v2.1-data.jsonc

2. A/B Testing

# Capture variant A
pnpm capture --before --urls "https://site.com/variant-a" --title "AB-Test"
# Switch to variant B
pnpm capture --after --urls "https://site.com/variant-b" --title "AB-Test"
# Generate comparison
pnpm compare ab-test-data.jsonc

3. Long-term Monitoring

# Weekly baseline
pnpm capture --before --file monitoring-urls.txt --title "Weekly-Check"
# Next week comparison
pnpm capture --after --file monitoring-urls.txt --title "Weekly-Check"

4. Progressive Capture

# Start with critical pages
pnpm capture --urls "site.com,site.com/pricing" --title "Site-Check"
# Add more pages later
pnpm capture --urls "site.com/about,site.com/contact" --title "Site-Check"

🛠️ Breaking Changes

⚠️ None

This is a fully backward-compatible release. All existing commands, workflows, and data files continue to work exactly as before.

🐛 Bug Fixes

Fixed: Timestamp Overwriting Issue

• Problem: When using --after mode, beforeTimestamp was incorrectly updated
• Solution: Implemented separate timestamp tracking and preservation logic
• Impact: All timestamp data now remains accurate and consistent

Fixed: Single Mode Data Loss

• Problem: Re-capturing in single mode would overwrite entire data file
• Solution: Extended smart merging to single mode captures
• Impact: Partial re-captures now preserve existing data

Fixed: JSON Serialization of Undefined Values

• Problem: Undefined values were serialized as string "undefined" instead of null
• Solution: Proper null handling in JSON generation
• Impact: Data files now parse correctly in all scenarios

📖 Documentation Updates

Comprehensive README Overhaul

• New Sections: Independent capture modes, smart merging, workflow patterns
• Enhanced Examples: Real-world use cases and step-by-step guides
• Reorganized Options: Categorized capture options for better clarity
• Expanded by 39%: From 380 to 528 lines with detailed coverage

New Content Added

• Independent before/after workflow documentation
• Common workflow patterns section
• Smart data merging explanation
• Enhanced capture options reference
• Multiple real-world examples

🔄 Migration Guide

From v1.1.x to v1.2.0

No migration needed! This release is fully backward compatible.

Optional: Take Advantage of New Features

# Old way (still works)
pnpm capture --before-after --file urls.txt

# New way (more flexible)
pnpm capture --before --file urls.txt    # When ready
pnpm capture --after --file urls.txt     # Any time later
pnpm compare data-file.jsonc              # Add comparison data

📊 Performance & Compatibility

Performance Improvements

• Smarter File I/O: Only loads existing data when merging is needed
• Efficient Merging: Minimal overhead when combining datasets
• Optimized JSON: Reduced data file size with better serialization

Compatibility

• ✅ Node.js: 16.x, 18.x, 20.x+
• ✅ Operating Systems: Windows, macOS, Linux
• ✅ Browsers: Chromium (via Playwright)
• ✅ Data Files: Full backward compatibility with v1.0.x and v1.1.x

🚦 What's Next

Future Enhancements Being Considered

• Scheduling Integration: Built-in cron-like scheduling for automated captures
• Webhook Support: Trigger captures via HTTP endpoints
• Multi-Environment Comparisons: Compare across dev/staging/prod environments
• Advanced Filtering: More granular control over what gets compared
• Cloud Storage: Direct integration with S3, GCS, Azure Blob storage

Feedback Welcome

We'd love to hear how you're using the new independent capture modes! Please share your workflows and suggestions in our GitHub Issues.

🙏 Acknowledgments

This release represents a significant enhancement to the tool's flexibility and usability. The independent capture functionality opens up entirely new workflows that weren't possible before, making the tool more powerful for real-world deployment and monitoring scenarios.

---

📥 Installation & Upgrade

New Installation

git clone git@github.com:refactorau/screenshot-cli.git
cd screenshot-cli
pnpm install
pnpx playwright install chromium
pnpm build

Upgrading from v1.1.x

git pull origin main
pnpm install
pnpm build

Verify Installation

pnpm capture --help
# Should show new --before and --after options

🏷️ Release Assets

• Source Code: Available on GitHub
• Documentation: Updated README.md with comprehensive examples
• Migration Guide: This document (no migration needed)
• Examples: Multiple workflow patterns documented

---

Happy Screenshot Capturing! 📸

The Screenshot CLI Team

v1.1.0

🎉 Release v1.1.0: Image Comparison System

A major feature release that transforms screenshot-cli into a comprehensive visual regression testing solution with real-time image comparison and persistent data storage.

🌟 What's New

🔍 Real-Time Image Comparison

• Live comparison during capture: See changes as they happen during before/after screenshots
• Progress indicators: Real-time display of comparison results and statistics
• Automatic analysis: Powered by pixelmatch for pixel-perfect accuracy

📊 Advanced Change Detection

• 6-level classification system: None → Minimal → Minor → Moderate → Major → Extreme
• Smart thresholds: Configurable sensitivity with intelligent defaults
• Dimension handling: Graceful handling of screenshots with different sizes
• Percentage-based analysis: Precise change quantification

🔧 New Compare Command

# Add comparison data to existing captures
pnpm compare report-data.jsonc

# Customize sensitivity and options
pnpm compare --comparison-threshold 0.05 --min-change-threshold 1.0 report-data.jsonc

💾 Persistent Data Storage

• Enhanced JSONC files: Comparison data stored with full metadata
• Backward compatibility: Existing data files continue to work
• Rich metadata: Timestamps, durations, options, and comparison results

📄 Enhanced Reports

PDF Improvements

• Comparison badges: Color-coded change indicators with percentages
• Statistics cards: Changed/unchanged counts on title page
• Smart layouts: Automatic 2-column (before/after) or 3-column (with diff) views
• Change-level sorting: Most significant changes displayed first

HTML Improvements

• Comparison data display: Fixed bug where comparison data wasn't showing
• Consistent styling: Matching badge system with PDF reports

🖼️ Intelligent Diff Images

• Auto-generation: Created for all major and moderate changes
• Threshold-aware: Respects --min-change-threshold settings
• Visual highlighting: Red/green/yellow color coding for different change types
• Storage optimization: Optional --skip-diff-images flag to save space

🚀 New Command Options

Capture Command

pnpm capture --file urls.txt --before-after \
  --comparison-threshold 0.1 \
  --min-change-threshold 0.5 \
  --skip-diff-images \
  --comparison-only

Compare Command

pnpm compare --comparison-threshold 0.1 \
  --min-change-threshold 1.0 \
  --skip-diff-images \
  --ignore-antialiasing \
  data-file.jsonc

📈 Performance & Quality

• Efficient processing: Optimized comparison algorithms
• Error resilience: Graceful handling of comparison failures
• Memory management: Smart image processing for large screenshots
• Progress feedback: Real-time status updates during operations

🔄 Backward Compatibility

• ✅ Existing data files work without modification
• ✅ All previous commands and options preserved
• ✅ Report generation unchanged for single-mode captures
• ✅ No breaking changes to API or CLI interface

🛠️ Technical Details

New Dependencies

• pixelmatch: Industry-standard image comparison library
• pngjs: PNG image processing for diff generation

Architecture

• ImageComparator class: Centralized comparison logic
• Enhanced data persistence: Extended JSONC format with comparison metadata
• Modular design: Clean separation between capture, comparison, and reporting

📖 Documentation Updates

• Updated README: Comprehensive command documentation and examples
• Usage examples: Real-world workflows for visual regression testing
• Best practices: Guidelines for thresholds and comparison strategies

🐛 Bug Fixes

• HTML comparison display: Fixed issue where comparison data wasn't appearing in HTML reports
• Data file loading: Improved error handling and validation
• Diff image paths: Corrected relative path handling in reports

🎯 Use Cases

This release enables powerful new workflows:

• Visual regression testing: Detect unintended UI changes
• A/B testing: Compare design variations with precise metrics
• QA automation: Integrate visual testing into CI/CD pipelines
• Design review: Share before/after comparisons with stakeholders
• Performance monitoring: Track visual changes over time

---

Full Changelog: v1.0.0...v1.1.0

v1.0.0

🚀 Screenshot CLI v1.0.0 - Initial Stable Release

We're excited to announce the first stable release of Screenshot CLI - a powerful TypeScript CLI tool for taking website screenshots with professional HTML and PDF reporting capabilities.

🎯 What is Screenshot CLI?

Screenshot CLI is a command-line tool that captures full-page screenshots of websites and generates beautiful, styled reports. Perfect for web developers, QA teams, and anyone who needs to document website changes or perform visual comparisons.

✨ Key Features

📸 Dual Screenshot Modes

• Single Mode: Capture individual screenshots of multiple URLs
• Before/After Mode: Interactive comparison workflow for documenting changes

📊 Professional Reporting

• HTML Reports: Modern, responsive dark-themed galleries
• PDF Reports: Print-ready formatted documents with A4 landscape layout
• Data Persistence: .jsonc files for report regeneration without re-capturing screenshots

🔧 Flexible Input Methods

• Direct URL input via command line
• Text files with URL lists (with comment support)
• JavaScript files with URL arrays (CommonJS format)

🚀 Robust Performance

• Built on Playwright for reliable screenshot capture
• Automatic retry mechanism for network errors
• Intelligent timeout adjustment for staging/WordPress sites
• Configurable wait strategies (load, networkidle, domcontentloaded)

⚙️ Highly Configurable

• Custom viewport sizes (default: 1920x1080)
• Adjustable timeouts and retry settings
• Multiple report formats (HTML, PDF, or both)
• Customizable output directories and filenames

🛠️ Installation

# Clone and install dependencies
git clone git@github.com:refactorau/screenshot-cli.git
cd screenshot-cli
pnpm install

# Install Playwright browsers
pnpx playwright install chromium

# Build the project
pnpm build

🎯 Quick Start

Single Screenshots

# Capture multiple URLs
pnpm capture --urls "https://example.com,https://google.com"

# Use a URL file
pnpm capture --file urls.txt --title "My Website Audit"

Before/After Comparison

# Interactive comparison workflow
pnpm capture --file urls.txt --before-after --title "Site Updates"

# The tool will:
# 1. Take "before" screenshots
# 2. Prompt you to make changes
# 3. Take "after" screenshots
# 4. Generate side-by-side comparison report

Report Generation

# Generate PDF from existing data
pnpm generate --report-type pdf report-data.jsonc

# Generate both HTML and PDF
pnpm generate --report-type all report-data.jsonc

🔍 Advanced Usage

Custom Viewport & Error Handling

pnpm capture --file urls.txt \
  --width 1440 --height 900 \
  --max-retries 5 --retry-delay 3000 \
  --wait-strategy networkidle \
  --report-type all

JavaScript URL Configuration

// urls.js
module.exports = ['https://example.com', 'https://staging.example.com', 'https://docs.example.com'];

🏗️ Technical Specifications

• Node.js: >=20.0.0
• Package Manager: pnpm >=9.0.0
• Browser Engine: Chromium (via Playwright)
• Output Formats: PNG screenshots, HTML reports, PDF documents
• Data Format: JSON with comments (.jsonc)

📁 Project Structure

screenshot-cli/
├── src/
│   ├── index.ts             # CLI entry point
│   ├── screenshotter.ts     # Screenshot capture logic
│   ├── html-generator.ts    # HTML report generation
│   ├── pdf-generator.ts     # PDF report generation
│   ├── data-persistence.ts  # Data file management
│   ├── types.ts            # TypeScript definitions
│   └── utils.ts            # Utility functions
├── dist/                   # Built JavaScript files
└── output/                # Generated screenshots and reports

🎨 What's Generated

• Screenshots: High-quality PNG files in output/screenshots/
• Data Files: Metadata and results in {title}-data.jsonc
• HTML Reports: Responsive galleries with dark theme
• PDF Reports: Professional documents with statistics and configuration details

🚀 Use Cases

• Web Development: Document changes during development
• QA Testing: Visual regression testing workflows
• Client Reports: Professional documentation for stakeholders
• Site Audits: Capture multiple pages for review
• Migration Projects: Before/after comparisons for site updates

🔄 Workflow Integration

The tool's separation of capture and generation phases makes it perfect for:

• CI/CD Pipelines: Capture screenshots, generate reports later
• Collaborative Work: Share data files between team members
• Archival: Store screenshot sessions with full metadata
• Multi-format Output: Generate both HTML and PDF from same data

📋 Development Standards

Versioning

• Follows Semantic Versioning (SemVer) specification
• Clear version increment guidelines for MAJOR.MINOR.PATCH releases
• Comprehensive versioning rules for maintainers

Commit Standards

• Uses Conventional Commits specification
• Structured commit messages for automated changelog generation
• Consistent development workflow and release management

Code Quality

• TypeScript implementation with strict type checking
• CommonJS module system for broad compatibility
• Comprehensive error handling and retry mechanisms
• Prettier code formatting with consistent style rules
• VS Code configuration for optimal development experience

🤝 Community & Support

Open Source

• MIT License - Commercial and private use allowed
• GitHub Issues - Bug reports and feature requests
• Pull Requests - Community contributions welcome

Professional Support

• Comprehensive documentation and examples
• Clear installation and usage instructions
• Active maintenance and updates

Developer Experience

• Prettier Integration - Automatic code formatting with consistent style
• VS Code Settings - Format-on-save and import organization
• Extension Recommendations - Suggested VS Code extensions for best experience
• Development Workflow - Clear contribution guidelines and formatting standards

---

Requirements: Node.js 20+, pnpm 9+
License: MIT License
Repository: github.com/refactorau/screenshot-cli
Support: GitHub Issues

---

This release marks the first stable version of Screenshot CLI with a complete feature set, professional documentation, and industry-standard development practices ready for production use.