claude-flow-novice 2.9.1 → 2.10.0

package/.claude/skills/cfn-webapp-testing/capture-screenshot.sh

@@ -0,0 +1,238 @@
+#!/bin/bash
+# Webapp Testing Skill - Screenshot Capture
+# Purpose: Capture screenshots with Playwright, store metadata in SQLite, coordinate via Redis
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.claude/skills/cfn-cfn-.claude/skills/cfn-cfn-.." && pwd)"
+cd "$PROJECT_ROOT"
+
+# Default configuration
+VARIANT="default"
+TIMEOUT=30000
+WAIT_FOR=""
+SELECTOR=""
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --project) PROJECT="$2"; shift 2 ;;
+    --component) COMPONENT="$2"; shift 2 ;;
+    --viewport) VIEWPORT="$2"; shift 2 ;;
+    --state) STATE="$2"; shift 2 ;;
+    --variant) VARIANT="$2"; shift 2 ;;
+    --url) URL="$2"; shift 2 ;;
+    --task-id) TASK_ID="$2"; shift 2 ;;
+    --agent-id) AGENT_ID="$2"; shift 2 ;;
+    --selector) SELECTOR="$2"; shift 2 ;;
+    --wait-for) WAIT_FOR="$2"; shift 2 ;;
+    --timeout) TIMEOUT="$2"; shift 2 ;;
+    *) echo "Unknown parameter: $1"; exit 1 ;;
+  esac
+done
+
+# Validate required parameters
+if [ -z "$PROJECT" ] || [ -z "$COMPONENT" ] || [ -z "$VIEWPORT" ] || [ -z "$STATE" ] || [ -z "$URL" ]; then
+  echo "Error: Missing required parameters" >&2
+  echo "Usage: $0 --project <project> --component <component> --viewport <viewport> --state <state> --url <url>" >&2
+  echo "" >&2
+  echo "Required:" >&2
+  echo "  --project      Application/feature namespace (e.g., 'auth-system')" >&2
+  echo "  --component    UI component or page (e.g., 'login-form')" >&2
+  echo "  --viewport     Screen dimensions (e.g., '1920x1080', '375x667')" >&2
+  echo "  --state        Interaction state (e.g., 'default', 'hover', 'error')" >&2
+  echo "  --url          Page URL (e.g., 'http://localhost:3000/login')" >&2
+  echo "" >&2
+  echo "Optional:" >&2
+  echo "  --variant      Theme/variant (default: 'default')" >&2
+  echo "  --task-id      CFN task identifier" >&2
+  echo "  --agent-id     Agent identifier" >&2
+  echo "  --selector     CSS selector for element capture" >&2
+  echo "  --wait-for     CSS selector to wait for before capture" >&2
+  echo "  --timeout      Playwright timeout in ms (default: 30000)" >&2
+  exit 1
+fi
+
+# Generate screenshot key and paths
+TIMESTAMP=$(date +%Y%m%d%H%M%S)
+SCREENSHOT_KEY="${PROJECT}/${COMPONENT}/${VIEWPORT}/${STATE}/${VARIANT}"
+OUTPUT_DIR=".screenshots/current/${PROJECT}/${COMPONENT}/${VIEWPORT}/${STATE}"
+OUTPUT_FILE="${OUTPUT_DIR}/${VARIANT}_${TIMESTAMP}.png"
+
+mkdir -p "$OUTPUT_DIR"
+
+# Parse viewport dimensions
+IFS='x' read -r WIDTH HEIGHT <<< "$VIEWPORT"
+
+# Validate viewport dimensions
+if ! [[ "$WIDTH" =~ ^[0-9]+$ ]] || ! [[ "$HEIGHT" =~ ^[0-9]+$ ]]; then
+  echo "Error: Invalid viewport format. Expected format: WIDTHxHEIGHT (e.g., 1920x1080)" >&2
+  exit 1
+fi
+
+# Capture screenshot with Playwright (inline Node.js script)
+echo "Capturing screenshot: $SCREENSHOT_KEY" >&2
+
+CAPTURE_RESULT=$(node -e "
+const { chromium } = require('playwright');
+
+(async () => {
+  const browser = await chromium.launch({ headless: true });
+  const context = await browser.newContext({
+    viewport: { width: ${WIDTH}, height: ${HEIGHT} },
+    deviceScaleFactor: 1
+  });
+  const page = await context.newPage();
+
+  try {
+    await page.goto('${URL}', { waitUntil: 'networkidle', timeout: ${TIMEOUT} });
+
+    ${WAIT_FOR:+await page.waitForSelector('${WAIT_FOR}', { timeout: ${TIMEOUT} });}
+
+    // Simulate state if needed
+    ${SELECTOR:+const element = await page.locator('${SELECTOR}').first();}
+    if ('${STATE}' === 'hover' && '${SELECTOR}') {
+      await element.hover();
+      await page.waitForTimeout(500);  // Allow hover effects to render
+    } else if ('${STATE}' === 'focus' && '${SELECTOR}') {
+      await element.focus();
+      await page.waitForTimeout(300);
+    } else if ('${STATE}' === 'hover' && !'${SELECTOR}') {
+      console.error('Warning: hover state requires --selector parameter');
+    }
+
+    const screenshotOptions = {
+      path: '${OUTPUT_FILE}',
+      type: 'png'
+    };
+
+    ${SELECTOR:+
+    const boundingBox = await element.boundingBox();
+    if (boundingBox) {
+      screenshotOptions.clip = boundingBox;
+    } else {
+      console.error('Warning: Selector element not found, capturing full page');
+      screenshotOptions.fullPage = true;
+    }
+    }
+    ${SELECTOR:-screenshotOptions.fullPage = true;}
+
+    await page.screenshot(screenshotOptions);
+
+    await browser.close();
+
+    console.log(JSON.stringify({
+      screenshot_key: '${SCREENSHOT_KEY}',
+      file_path: '${OUTPUT_FILE}',
+      viewport_actual: { width: ${WIDTH}, height: ${HEIGHT} },
+      captured_at: Math.floor(Date.now() / 1000),
+      url: '${URL}',
+      state: '${STATE}',
+      selector: '${SELECTOR:-null}'
+    }));
+  } catch (error) {
+    await browser.close();
+    console.error('Playwright error:', error.message);
+    process.exit(1);
+  }
+})();
+" 2>&1)
+
+# Check if capture succeeded
+if [ $? -ne 0 ]; then
+  echo "Error: Screenshot capture failed" >&2
+  echo "$CAPTURE_RESULT" >&2
+  exit 1
+fi
+
+# Extract JSON from output (ignore stderr warnings)
+CAPTURE_JSON=$(echo "$CAPTURE_RESULT" | grep -E '^\{.*\}$' | tail -n 1)
+
+if [ -z "$CAPTURE_JSON" ]; then
+  echo "Error: Failed to parse capture result" >&2
+  echo "Output: $CAPTURE_RESULT" >&2
+  exit 1
+fi
+
+# Calculate file hash
+if [ ! -f "$OUTPUT_FILE" ]; then
+  echo "Error: Screenshot file not created: $OUTPUT_FILE" >&2
+  exit 1
+fi
+
+FILE_HASH=$(sha256sum "$OUTPUT_FILE" | awk '{print $1}')
+
+# Check if baseline exists
+DB_PATH="${HOME}/.claude/memory/adaptive-context.db"
+BASELINE_EXISTS=$(sqlite3 "$DB_PATH" \
+  "SELECT COUNT(*) FROM webapp_screenshots WHERE screenshot_key = '${SCREENSHOT_KEY}' AND baseline = 1" 2>/dev/null || echo "0")
+
+# Get git metadata
+GIT_COMMIT=$(git rev-parse --short HEAD 2>/dev/null || echo 'unknown')
+GIT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo 'unknown')
+
+# Prepare metadata JSON (escape single quotes)
+METADATA=$(cat <<EOF | tr '\n' ' ' | sed "s/'/\"/g"
+{
+  "browser": "chromium",
+  "viewport_actual": { "width": ${WIDTH}, "height": ${HEIGHT} },
+  "url": "${URL}",
+  "state": "${STATE}",
+  "selector": "${SELECTOR:-null}",
+  "task_id": "${TASK_ID:-null}",
+  "agent_id": "${AGENT_ID:-null}",
+  "git_commit": "${GIT_COMMIT}",
+  "git_branch": "${GIT_BRANCH}",
+  "captured_by": "webapp-testing-skill"
+}
+EOF
+)
+
+# Store metadata in SQLite
+sqlite3 "$DB_PATH" <<EOF
+INSERT INTO webapp_screenshots (
+  screenshot_key, project, component, viewport, state, variant,
+  file_path, file_hash, baseline, captured_at, task_id, agent_id, metadata
+) VALUES (
+  '${SCREENSHOT_KEY}',
+  '${PROJECT}',
+  '${COMPONENT}',
+  '${VIEWPORT}',
+  '${STATE}',
+  '${VARIANT}',
+  '${OUTPUT_FILE}',
+  'sha256:${FILE_HASH}',
+  0,
+  $(date +%s),
+  '${TASK_ID:-null}',
+  '${AGENT_ID:-null}',
+  '${METADATA}'
+);
+EOF
+
+if [ $? -ne 0 ]; then
+  echo "Warning: Failed to store metadata in SQLite" >&2
+fi
+
+# Push to Redis queue (for orchestrator tracking)
+if [ -n "$TASK_ID" ]; then
+  redis-cli lpush "screenshot:queue:${TASK_ID}" "$SCREENSHOT_KEY" > /dev/null 2>&1 || echo "Warning: Failed to push to Redis queue" >&2
+fi
+
+# Output result (JSON)
+cat <<EOF
+{
+  "screenshot_key": "${SCREENSHOT_KEY}",
+  "file_path": "${OUTPUT_FILE}",
+  "file_hash": "sha256:${FILE_HASH}",
+  "viewport_actual": { "width": ${WIDTH}, "height": ${HEIGHT} },
+  "captured_at": $(date +%s),
+  "baseline_exists": $([[ "$BASELINE_EXISTS" -eq 1 ]] && echo "true" || echo "false"),
+  "url": "${URL}",
+  "state": "${STATE}",
+  "variant": "${VARIANT}",
+  "task_id": "${TASK_ID:-null}",
+  "agent_id": "${AGENT_ID:-null}"
+}
+EOF

package/.claude/skills/cfn-webapp-testing/cfn-loop-integration.sh

@@ -0,0 +1,265 @@
+#!/bin/bash
+# Webapp Testing Skill - CFN Loop Integration Helper
+# Purpose: Helper functions for integrating visual regression testing into CFN Loop workflows
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.claude/skills/cfn-cfn-.claude/skills/cfn-cfn-.." && pwd)"
+
+# Function: Capture all screenshots for a component
+# Usage: capture_component_screenshots <project> <component> <url> <task-id> <agent-id> [viewports...]
+capture_component_screenshots() {
+  local PROJECT="$1"
+  local COMPONENT="$2"
+  local URL="$3"
+  local TASK_ID="$4"
+  local AGENT_ID="$5"
+  shift 5
+  local VIEWPORTS=("${@:-1920x1080}")  # Default to desktop
+
+  local STATES=("default" "hover" "error")
+  local VARIANTS=("light-mode" "dark-mode")
+
+  echo "Capturing screenshots for component: $COMPONENT" >&2
+  local TOTAL=$((${#VIEWPORTS[@]} * ${#STATES[@]} * ${#VARIANTS[@]}))
+  local COUNT=0
+
+  for VIEWPORT in "${VIEWPORTS[@]}"; do
+    for STATE in "${STATES[@]}"; do
+      for VARIANT in "${VARIANTS[@]}"; do
+        COUNT=$((COUNT + 1))
+        echo "[$COUNT/$TOTAL] Capturing: $VIEWPORT / $STATE / $VARIANT" >&2
+
+        "$SCRIPT_DIR/capture-screenshot.sh" \
+          --project "$PROJECT" \
+          --component "$COMPONENT" \
+          --viewport "$VIEWPORT" \
+          --state "$STATE" \
+          --variant "$VARIANT" \
+          --url "$URL" \
+          --task-id "$TASK_ID" \
+          --agent-id "$AGENT_ID" || echo "Warning: Failed to capture $VIEWPORT/$STATE/$VARIANT" >&2
+      done
+    done
+  done
+
+  echo "✅ Captured $COUNT screenshots" >&2
+}
+
+# Function: Compare all screenshots in task queue to baselines
+# Usage: compare_all_screenshots <task-id> [threshold]
+compare_all_screenshots() {
+  local TASK_ID="$1"
+  local THRESHOLD="${2:-0.95}"
+
+  echo "Comparing all screenshots in task queue: $TASK_ID" >&2
+
+  # Get all screenshot keys from Redis queue
+  local SCREENSHOT_KEYS=$(redis-cli lrange "screenshot:queue:${TASK_ID}" 0 -1 2>/dev/null || echo "")
+
+  if [ -z "$SCREENSHOT_KEYS" ]; then
+    echo "Warning: No screenshots found in queue for task: $TASK_ID" >&2
+    return 1
+  fi
+
+  local TOTAL=$(echo "$SCREENSHOT_KEYS" | wc -l)
+  local COUNT=0
+  local PASSED=0
+  local FAILED=0
+  local NO_BASELINE=0
+
+  echo "$SCREENSHOT_KEYS" | while read -r SCREENSHOT_KEY; do
+    [ -z "$SCREENSHOT_KEY" ] && continue
+
+    COUNT=$((COUNT + 1))
+    echo "[$COUNT/$TOTAL] Comparing: $SCREENSHOT_KEY" >&2
+
+    RESULT=$("$SCRIPT_DIR/compare-screenshots.sh" \
+      --screenshot-key "$SCREENSHOT_KEY" \
+      --task-id "$TASK_ID" \
+      --threshold "$THRESHOLD" 2>/dev/null || echo '{"status":"error"}')
+
+    STATUS=$(echo "$RESULT" | jq -r '.status')
+
+    case "$STATUS" in
+      passed)
+        PASSED=$((PASSED + 1))
+        echo "  ✅ PASSED ($(echo "$RESULT" | jq -r '.similarity_score'))" >&2
+        ;;
+      failed)
+        FAILED=$((FAILED + 1))
+        echo "  ❌ FAILED ($(echo "$RESULT" | jq -r '.diff_percentage')% difference)" >&2
+        ;;
+      no-baseline)
+        NO_BASELINE=$((NO_BASELINE + 1))
+        echo "  ⚠️  NO BASELINE" >&2
+        ;;
+      *)
+        echo "  ❌ ERROR" >&2
+        ;;
+    esac
+  done
+
+  # Calculate overall status
+  if [ "$FAILED" -eq 0 ] && [ "$NO_BASELINE" -eq 0 ]; then
+    echo "✅ All comparisons passed: $PASSED/$TOTAL" >&2
+    return 0
+  elif [ "$NO_BASELINE" -gt 0 ]; then
+    echo "⚠️  Some screenshots lack baselines: $NO_BASELINE missing" >&2
+    return 2
+  else
+    echo "❌ Visual regressions detected: $FAILED/$TOTAL failed" >&2
+    return 1
+  fi
+}
+
+# Function: Calculate validation consensus from comparison results
+# Usage: calculate_validation_consensus <task-id>
+calculate_validation_consensus() {
+  local TASK_ID="$1"
+
+  echo "Calculating validation consensus for task: $TASK_ID" >&2
+
+  # Get all comparison results from Redis
+  local DIFF_KEYS=$(redis-cli keys "screenshot:diff:${TASK_ID}:*" 2>/dev/null || echo "")
+
+  if [ -z "$DIFF_KEYS" ]; then
+    echo '{"confidence": 0.0, "status": "no-comparisons", "message": "No comparison results found"}' | jq '.'
+    return 1
+  fi
+
+  local TOTAL=0
+  local PASSED=0
+  local FAILED=0
+  local TOTAL_SIMILARITY=0
+
+  echo "$DIFF_KEYS" | while read -r KEY; do
+    [ -z "$KEY" ] && continue
+
+    RESULT=$(redis-cli get "$KEY" 2>/dev/null || echo '{}')
+    STATUS=$(echo "$RESULT" | jq -r '.status // "unknown"')
+    SIMILARITY=$(echo "$RESULT" | jq -r '.similarity_score // 0')
+
+    TOTAL=$((TOTAL + 1))
+    TOTAL_SIMILARITY=$(echo "$TOTAL_SIMILARITY + $SIMILARITY" | bc -l)
+
+    if [ "$STATUS" = "passed" ]; then
+      PASSED=$((PASSED + 1))
+    elif [ "$STATUS" = "failed" ]; then
+      FAILED=$((FAILED + 1))
+    fi
+  done
+
+  # Calculate average similarity and confidence
+  AVG_SIMILARITY=$(echo "scale=4; $TOTAL_SIMILARITY / $TOTAL" | bc -l)
+  PASS_RATE=$(echo "scale=4; $PASSED / $TOTAL" | bc -l)
+
+  # Confidence = weighted average of pass rate and similarity
+  # Pass rate weighted 60%, average similarity weighted 40%
+  CONFIDENCE=$(echo "scale=4; ($PASS_RATE * 0.6) + ($AVG_SIMILARITY * 0.4)" | bc -l)
+
+  # Determine overall status
+  if [ "$FAILED" -eq 0 ]; then
+    STATUS="passed"
+    MESSAGE="All visual regression tests passed"
+  else
+    STATUS="failed"
+    MESSAGE="Visual regressions detected in $FAILED/$TOTAL screenshots"
+  fi
+
+  # Output JSON result
+  cat <<EOF | jq '.'
+{
+  "confidence": ${CONFIDENCE},
+  "status": "${STATUS}",
+  "message": "${MESSAGE}",
+  "total_comparisons": ${TOTAL},
+  "passed": ${PASSED},
+  "failed": ${FAILED},
+  "average_similarity": ${AVG_SIMILARITY},
+  "pass_rate": ${PASS_RATE},
+  "task_id": "${TASK_ID}"
+}
+EOF
+}
+
+# Function: Update all baselines after Product Owner approval
+# Usage: update_all_baselines <task-id> <reason> <approved-by>
+update_all_baselines() {
+  local TASK_ID="$1"
+  local REASON="$2"
+  local APPROVED_BY="$3"
+
+  echo "Updating baselines for task: $TASK_ID" >&2
+
+  # Get all comparison results from Redis
+  local DIFF_KEYS=$(redis-cli keys "screenshot:diff:${TASK_ID}:*" 2>/dev/null || echo "")
+
+  if [ -z "$DIFF_KEYS" ]; then
+    echo "Error: No comparison results found for task: $TASK_ID" >&2
+    return 1
+  fi
+
+  local TOTAL=0
+  local UPDATED=0
+
+  echo "$DIFF_KEYS" | while read -r KEY; do
+    [ -z "$KEY" ] && continue
+
+    RESULT=$(redis-cli get "$KEY" 2>/dev/null || echo '{}')
+    SCREENSHOT_KEY=$(echo "$KEY" | sed "s|screenshot:diff:${TASK_ID}:||")
+    CURRENT_FILE=$(echo "$RESULT" | jq -r '.current_path')
+    STATUS=$(echo "$RESULT" | jq -r '.status')
+
+    TOTAL=$((TOTAL + 1))
+
+    # Only update if comparison failed (visual change detected)
+    if [ "$STATUS" = "failed" ]; then
+      echo "[$TOTAL] Updating baseline: $SCREENSHOT_KEY" >&2
+
+      "$SCRIPT_DIR/set-baseline.sh" \
+        --screenshot-key "$SCREENSHOT_KEY" \
+        --current-file "$CURRENT_FILE" \
+        --reason "$REASON (approved by $APPROVED_BY)" >/dev/null 2>&1 && UPDATED=$((UPDATED + 1))
+    else
+      echo "[$TOTAL] Skipping (no change): $SCREENSHOT_KEY" >&2
+    fi
+  done
+
+  echo "✅ Updated $UPDATED baselines" >&2
+}
+
+# Export functions for use in other scripts
+export -f capture_component_screenshots
+export -f compare_all_screenshots
+export -f calculate_validation_consensus
+export -f update_all_baselines
+
+# If script is run directly, show usage
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+  cat <<EOF
+CFN Loop Integration Helper Functions
+
+Usage: source $0
+
+Available Functions:
+  capture_component_screenshots <project> <component> <url> <task-id> <agent-id> [viewports...]
+  compare_all_screenshots <task-id> [threshold]
+  calculate_validation_consensus <task-id>
+  update_all_baselines <task-id> <reason> <approved-by>
+
+Example (Loop 3 - Implementation):
+  source ./.claude/skills/cfn-webapp-testing/cfn-loop-integration.sh
+  capture_component_screenshots "auth-system" "login-form" "http://localhost:3000/login" "\$TASK_ID" "\$AGENT_ID" "1920x1080" "375x667"
+
+Example (Loop 2 - Validation):
+  compare_all_screenshots "\$TASK_ID" 0.95
+  CONSENSUS=\$(calculate_validation_consensus "\$TASK_ID")
+  echo "\$CONSENSUS" | jq -r '.confidence'
+
+Example (Product Owner Decision):
+  update_all_baselines "\$TASK_ID" "Approved visual changes from PR #123" "product-owner-agent"
+
+EOF
+fi

package/.claude/skills/cfn-webapp-testing/compare-screenshots.sh

@@ -0,0 +1,199 @@
+#!/bin/bash
+# Webapp Testing Skill - Screenshot Comparison
+# Purpose: Compare captured screenshot to baseline using pixelmatch, store results in Redis
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.claude/skills/cfn-cfn-.claude/skills/cfn-cfn-.." && pwd)"
+cd "$PROJECT_ROOT"
+
+# Default configuration
+THRESHOLD=0.95
+IGNORE_REGIONS=""
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --screenshot-key) SCREENSHOT_KEY="$2"; shift 2 ;;
+    --task-id) TASK_ID="$2"; shift 2 ;;
+    --threshold) THRESHOLD="$2"; shift 2 ;;
+    --ignore-regions) IGNORE_REGIONS="$2"; shift 2 ;;
+    *) echo "Unknown parameter: $1"; exit 1 ;;
+  esac
+done
+
+# Validate required parameters
+if [ -z "$SCREENSHOT_KEY" ] || [ -z "$TASK_ID" ]; then
+  echo "Error: Missing required parameters" >&2
+  echo "Usage: $0 --screenshot-key <key> --task-id <task-id>" >&2
+  echo "" >&2
+  echo "Required:" >&2
+  echo "  --screenshot-key   Screenshot identifier (e.g., 'auth-system/login-form/1920x1080/default/light-mode')" >&2
+  echo "  --task-id          CFN task identifier" >&2
+  echo "" >&2
+  echo "Optional:" >&2
+  echo "  --threshold        Similarity threshold 0.0-1.0 (default: 0.95)" >&2
+  echo "  --ignore-regions   JSON array of regions to ignore (e.g., '[{\"x\":0,\"y\":0,\"width\":100,\"height\":50}]')" >&2
+  exit 1
+fi
+
+DB_PATH="${HOME}/.claude/memory/adaptive-context.db"
+
+# Get baseline path from SQLite
+BASELINE_PATH=$(sqlite3 "$DB_PATH" \
+  "SELECT file_path FROM webapp_screenshots WHERE screenshot_key = '${SCREENSHOT_KEY}' AND baseline = 1" 2>/dev/null)
+
+if [ -z "$BASELINE_PATH" ]; then
+  # No baseline exists
+  echo '{"status": "no-baseline", "screenshot_key": "'"$SCREENSHOT_KEY"'", "message": "No baseline found for comparison. Use set-baseline.sh to create one."}' | jq '.'
+  exit 0
+fi
+
+# Get current screenshot path from SQLite (most recent non-baseline)
+CURRENT_PATH=$(sqlite3 "$DB_PATH" \
+  "SELECT file_path FROM webapp_screenshots WHERE screenshot_key = '${SCREENSHOT_KEY}' AND baseline = 0 ORDER BY captured_at DESC LIMIT 1" 2>/dev/null)
+
+if [ -z "$CURRENT_PATH" ]; then
+  echo "Error: No current screenshot found for key: $SCREENSHOT_KEY" >&2
+  echo "Hint: Run capture-screenshot.sh first to create a capture" >&2
+  exit 1
+fi
+
+# Verify files exist
+if [ ! -f "$BASELINE_PATH" ]; then
+  echo "Error: Baseline file not found: $BASELINE_PATH" >&2
+  exit 1
+fi
+
+if [ ! -f "$CURRENT_PATH" ]; then
+  echo "Error: Current screenshot file not found: $CURRENT_PATH" >&2
+  exit 1
+fi
+
+# Generate diff path
+DIFF_DIR=".screenshots/diffs/${TASK_ID}"
+mkdir -p "$DIFF_DIR"
+SCREENSHOT_KEY_FLAT=$(echo "$SCREENSHOT_KEY" | tr '/' '_')
+DIFF_PATH="${DIFF_DIR}/${SCREENSHOT_KEY_FLAT}_diff.png"
+
+echo "Comparing screenshots:" >&2
+echo "  Baseline: $BASELINE_PATH" >&2
+echo "  Current:  $CURRENT_PATH" >&2
+echo "  Diff:     $DIFF_PATH" >&2
+
+# Compare using pixelmatch (Node.js)
+COMPARISON=$(node -e "
+const fs = require('fs');
+const PNG = require('pngjs').PNG;
+const pixelmatch = require('pixelmatch');
+
+try {
+  const baseline = PNG.sync.read(fs.readFileSync('${BASELINE_PATH}'));
+  const current = PNG.sync.read(fs.readFileSync('${CURRENT_PATH}'));
+
+  // Validate dimensions match
+  if (baseline.width !== current.width || baseline.height !== current.height) {
+    console.error(JSON.stringify({
+      status: 'error',
+      message: 'Screenshot dimensions do not match',
+      baseline_dimensions: { width: baseline.width, height: baseline.height },
+      current_dimensions: { width: current.width, height: current.height }
+    }));
+    process.exit(1);
+  }
+
+  const { width, height } = baseline;
+  const diff = new PNG({ width, height });
+
+  // Configure pixelmatch options
+  const options = {
+    threshold: 0.1,  // Sensitivity (0 = strict, 1 = lenient)
+    includeAA: true,  // Include anti-aliasing
+    alpha: 0.1,
+    aaColor: [255, 255, 0],
+    diffColor: [255, 0, 0]
+  };
+
+  ${IGNORE_REGIONS:+
+  // Apply ignore regions (mask pixels)
+  const ignoreRegions = ${IGNORE_REGIONS};
+  ignoreRegions.forEach(region => {
+    for (let y = region.y; y < region.y + region.height && y < height; y++) {
+      for (let x = region.x; x < region.x + region.width && x < width; x++) {
+        const idx = (width * y + x) * 4;
+        baseline.data[idx] = current.data[idx];
+        baseline.data[idx + 1] = current.data[idx + 1];
+        baseline.data[idx + 2] = current.data[idx + 2];
+      }
+    }
+  });
+  }
+
+  const numDiffPixels = pixelmatch(
+    baseline.data, current.data, diff.data, width, height, options
+  );
+
+  fs.writeFileSync('${DIFF_PATH}', PNG.sync.write(diff));
+
+  const totalPixels = width * height;
+  const diffPercentage = (numDiffPixels / totalPixels) * 100;
+  const similarityScore = 1 - (numDiffPixels / totalPixels);
+  const status = similarityScore >= ${THRESHOLD} ? 'passed' : 'failed';
+
+  console.log(JSON.stringify({
+    screenshot_key: '${SCREENSHOT_KEY}',
+    similarity_score: parseFloat(similarityScore.toFixed(4)),
+    diff_pixels: numDiffPixels,
+    total_pixels: totalPixels,
+    diff_percentage: parseFloat(diffPercentage.toFixed(2)),
+    threshold: ${THRESHOLD},
+    status: status,
+    diff_path: '${DIFF_PATH}',
+    baseline_path: '${BASELINE_PATH}',
+    current_path: '${CURRENT_PATH}',
+    compared_at: Math.floor(Date.now() / 1000)
+  }));
+} catch (error) {
+  console.error(JSON.stringify({
+    status: 'error',
+    message: error.message,
+    screenshot_key: '${SCREENSHOT_KEY}'
+  }));
+  process.exit(1);
+}
+" 2>&1)
+
+# Check if comparison succeeded
+if [ $? -ne 0 ]; then
+  echo "Error: Screenshot comparison failed" >&2
+  echo "$COMPARISON" >&2
+  exit 1
+fi
+
+# Extract JSON from output
+COMPARISON_JSON=$(echo "$COMPARISON" | grep -E '^\{.*\}$' | tail -n 1)
+
+if [ -z "$COMPARISON_JSON" ]; then
+  echo "Error: Failed to parse comparison result" >&2
+  echo "Output: $COMPARISON" >&2
+  exit 1
+fi
+
+# Store in Redis (TTL: 1 hour = 3600 seconds)
+redis-cli setex "screenshot:diff:${TASK_ID}:${SCREENSHOT_KEY}" 3600 "$COMPARISON_JSON" > /dev/null 2>&1 || \
+  echo "Warning: Failed to store comparison result in Redis" >&2
+
+# Output result (formatted JSON)
+echo "$COMPARISON_JSON" | jq '.'
+
+# Return appropriate exit code based on status
+STATUS=$(echo "$COMPARISON_JSON" | jq -r '.status')
+if [ "$STATUS" = "passed" ]; then
+  exit 0
+elif [ "$STATUS" = "failed" ]; then
+  echo "Visual regression detected: $(echo "$COMPARISON_JSON" | jq -r '.diff_percentage')% difference" >&2
+  exit 2  # Non-zero but distinct from error
+else
+  exit 1
+fi