IMPLEMENTATION-COMPLETE.md

Screenshot Visual Regression Skill - Implementation Complete ✓

Installation Location

The skill has been successfully installed at:

~/.claude/skills/screenshot-visual-regression/

What Was Implemented

Core Files Created

1. Skill Manifest (skill.json)

   • Defines the three commands: discover, capture, compare
   • Skill metadata and version information

2. Package Configuration (package.json)

   • Dependencies: Playwright, Pixelmatch, pngjs
   • Build scripts and TypeScript configuration

3. Main Entry Point (src/index.ts)

   • Command-line argument parsing
   • Command routing to appropriate handlers
   • Usage help display

4. Helper Modules

   • state-manager.ts - Manages .screenshot-config.json persistence
   • screenshot-utils.ts - Browser automation and screenshot capture
   • page-navigator.ts - Generic navigation engine
   • codebase-analyzer.ts - Framework detection and route discovery

5. Command Implementations

   • discover.ts - Analyzes codebase and generates configuration
   • capture.ts - Captures screenshots using Playwright
   • compare.ts - Generates visual diffs and HTML reports

Dependencies Installed

• Playwright (Chromium browser)
• Pixelmatch (pixel-level image comparison)
• pngjs (PNG image processing)
• TypeScript and type definitions

All dependencies are isolated in the skill directory and do not affect target applications.

How to Use the Skill

1. Discover Routes and Pages

Navigate to your web application directory and run:

cd /path/to/your/app
node ~/.claude/skills/screenshot-visual-regression/dist/index.js discover --url http://localhost:3000

This will:

• Analyze your codebase structure
• Detect routing framework (React Router, Next.js, state-based)
• Generate .screenshots/.screenshot-config.json with discovered targets

2. Capture Baseline Screenshots

Before making any changes:

# Make sure your dev server is running
npm run dev

# Capture baseline
node ~/.claude/skills/screenshot-visual-regression/dist/index.js capture --baseline

Screenshots will be saved to .screenshots/baseline/

3. Make Your Changes

Perform your migration, refactoring, or code changes.

4. Capture Comparison Screenshots

After making changes:

# Restart dev server with updated code
npm run dev

# Capture comparison
node ~/.claude/skills/screenshot-visual-regression/dist/index.js capture --comparison

Screenshots will be saved to .screenshots/comparison/

5. Generate Visual Diff Report

node ~/.claude/skills/screenshot-visual-regression/dist/index.js compare

This generates:

• Pixel diff images in .screenshots/diff/
• HTML report in .screenshots/reports/
• Console summary of changes

Features

Framework Support

• React Router v6 - Automatically detects routes from JSX
• Next.js - Supports both Pages Router and App Router
• State-based routing - Analyzes component state patterns
• Generic navigation - Falls back to navigation component analysis

Navigation Types

The skill supports multiple navigation strategies:

• Click navigation - Click elements by selector or text
• URL navigation - Direct URL navigation
• Sequence navigation - Multi-step navigation flows
• Wait navigation - Custom wait conditions

Configuration

Edit .screenshots/.screenshot-config.json to customize:

{
  "version": "1.0",
  "devServerUrl": "http://localhost:3000",
  "viewport": { "width": 1920, "height": 1080 },
  "targets": [
    {
      "name": "target-name",
      "description": "Human-readable description",
      "navigation": {
        "type": "click",
        "text": "Navigation Link"
      },
      "waitFor": ".content-loaded",
      "enabled": true
    }
  ]
}

Directory Structure

Skill Installation

~/.claude/skills/screenshot-visual-regression/
├── skill.json              # Skill manifest
├── package.json            # Dependencies
├── tsconfig.json           # TypeScript config
├── README.md               # Documentation
├── src/                    # TypeScript source
│   ├── index.ts
│   ├── discover.ts
│   ├── capture.ts
│   ├── compare.ts
│   └── helpers/
│       ├── state-manager.ts
│       ├── screenshot-utils.ts
│       ├── page-navigator.ts
│       └── codebase-analyzer.ts
├── dist/                   # Compiled JavaScript
└── node_modules/           # Isolated dependencies

Target Application (Generated)

your-app/
├── src/                    # Your code (untouched)
├── package.json            # Your dependencies (untouched)
└── .screenshots/           # Created by skill
    ├── .screenshot-config.json
    ├── baseline/
    ├── comparison/
    ├── diff/
    └── reports/

Example Workflow

For a PatternFly migration:

# 1. Discover pages
cd /path/to/patternfly-app
node ~/.claude/skills/screenshot-visual-regression/dist/index.js discover --url http://localhost:3000

# 2. Review generated config
cat .screenshots/.screenshot-config.json

# 3. Capture baseline (before migration)
npm run dev
node ~/.claude/skills/screenshot-visual-regression/dist/index.js capture --baseline

# 4. Perform PatternFly migration
# ... make code changes ...

# 5. Capture comparison (after migration)
npm run dev
node ~/.claude/skills/screenshot-visual-regression/dist/index.js capture --comparison

# 6. Generate visual diff report
node ~/.claude/skills/screenshot-visual-regression/dist/index.js compare

# 7. Open report in browser
xdg-open .screenshots/reports/comparison-report-*.html

Verification

Test the skill is working:

# Show help
node ~/.claude/skills/screenshot-visual-regression/dist/index.js

# Test discovery (example)
cd /tmp && mkdir test-app && cd test-app
node ~/.claude/skills/screenshot-visual-regression/dist/index.js discover

System Requirements

The skill runs in headless mode. For best results, install system dependencies:

cd ~/.claude/skills/screenshot-visual-regression
sudo npx playwright install-deps

Next Steps

1. Navigate to a web application directory
2. Run the discover command to analyze your codebase
3. Review and customize the generated configuration
4. Capture baseline screenshots
5. Make your changes
6. Capture comparison screenshots
7. Generate and review the visual diff report

Notes

• Zero modifications required to target applications
• All dependencies are isolated in the skill directory
• Works with headless browsers (no GUI required)
• Generates HTML reports for easy visual review
• Configuration can be shared across teams
• Baseline screenshots can be version controlled

Troubleshooting

Issue: Browser fails to launch

cd ~/.claude/skills/screenshot-visual-regression
npx playwright install-deps chromium

Issue: Dev server not responding

• Ensure your dev server is running
• Check the URL in .screenshot-config.json matches your server

Issue: No routes discovered

• Check your routing framework is supported
• Manually edit .screenshot-config.json to add targets
• Review discovery logic in src/helpers/codebase-analyzer.ts

Success!

The screenshot visual regression skill is now fully implemented and ready to use. All components are working:

✓ Discovery command - analyzes codebases and finds routes ✓ Capture command - takes screenshots with Playwright ✓ Compare command - generates visual diffs and reports ✓ State management - persists configuration ✓ Generic navigation - works with any framework ✓ Headless browser - runs in VMs without GUI ✓ Isolated dependencies - zero impact on target apps

Happy visual regression testing!