feat: diff stats, screenshot tests, zoom & annotation improvements

Reporter:
- Add diff_level, area_size, max_color_distance to failure data
- Show percentage badge in topbar and sidebar (e.g. "2.34% diff")

Tests:
- Replace Struct stubs with real ImageCompare objects
- Add 5 screenshot integration tests for report views
- Add rake report:sample task (scripts/generate_sample_report.rb)

UI:
- Ctrl/Cmd/Alt + scroll wheel to zoom (3% smooth steps)
- Click image to toggle annotated mode
- Move cursor on zoomed images
- Fix search icon spacing

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: pftg

Rakefile

@@ -29,6 +29,11 @@ task :coverage do
   Rake::Task["test"].invoke
 end
 
+desc "Generate sample HTML report for manual testing"
+task "report:sample" do
+  ruby "scripts/generate_sample_report.rb"
+end
+
 task "clobber" do
   puts "Cleanup tmp/*.png"
   FileUtils.rm_rf(Dir["./tmp/*"])

lib/capybara_screenshot_diff/reporters/html.rb

@@ -49,14 +49,23 @@ def success_rate
       private
 
       def failure_entry_for(name, compare)
-        {
+        entry = {
           name: name,
           original: relative_path(compare.base_image_path),
           new: relative_path(compare.image_path),
           base_diff: relative_path(compare.reporter.annotated_base_image_path),
           diff: relative_path(compare.reporter.annotated_image_path),
           heatmap: relative_path(compare.reporter.heatmap_diff_path)
         }
+
+        if compare.difference
+          d = compare.difference
+          entry[:diff_level] = d.ratio ? (d.ratio * 100).round(2) : nil
+          entry[:area_size] = d.region_area_size
+          entry[:max_color_distance] = d.meta[:max_color_distance]&.round(1)
+        end
+
+        entry
       end
 
       def relative_path(path)

lib/capybara_screenshot_diff/reporters/templates/report.html.erb

@@ -64,8 +64,8 @@
     /* ── Sidebar ─────────────────────────────────────────────────────── */
     #sidebar { width: var(--sidebar-w); flex-shrink: 0; background: var(--bg2); border-right: 1px solid var(--border); display: flex; flex-direction: column; overflow: hidden; }
     #search-wrap { padding: .4rem .5rem; position: relative; }
-    .search-icon { position: absolute; left: .5rem; top: 50%; transform: translateY(-50%); color: var(--text3); pointer-events: none; }
-    #search { width: 100%; padding: .375rem .5rem .375rem 1.75rem; font-size: .6875rem; font-family: var(--font); background: var(--bg3); color: var(--text); border: 1px solid transparent; border-radius: var(--radius); outline: none; transition: border-color .15s; }
+    .search-icon { position: absolute; left: 1rem; top: 50%; transform: translateY(-50%); color: var(--text3); pointer-events: none; }
+    #search { width: 100%; padding: .375rem .5rem .375rem 2.125rem; font-size: .6875rem; font-family: var(--font); background: var(--bg3); color: var(--text); border: 1px solid transparent; border-radius: var(--radius); outline: none; transition: border-color .15s; }
     #search:focus { border-color: var(--accent); background: var(--bg); }
     #search::placeholder { color: var(--text3); }
     #sidebar-list { flex: 1; overflow-y: auto; padding: .375rem; display: flex; flex-direction: column; gap: .375rem; }
@@ -113,8 +113,9 @@
     .dot-new { width: 5px; height: 5px; border-radius: 50%; background: var(--orange); }
     .dot-heat { width: 5px; height: 5px; border-radius: 50%; background: #f59e0b; }
     /* img-box: scrollable container for per-image zoom+pan */
-    .img-box { background: var(--surface); border-radius: var(--radius); overflow: auto; flex: 1; position: relative; cursor: grab; }
-    .img-box.dragging { cursor: grabbing; }
+    .img-box { background: var(--surface); border-radius: var(--radius); overflow: hidden; flex: 1; position: relative; }
+    .img-box.pannable { overflow: auto; cursor: move; }
+    .img-box.dragging { cursor: move; }
     .img-box img { display: block; object-fit: contain; transform-origin: 0 0; }
     /* At 100% zoom, image fills the box */
     .img-box[data-zoom="100"] img { width: 100%; height: 100%; }
@@ -250,11 +251,14 @@
       /* Thumbnail: annotated mode → heatmap; normal → new image (no annotation) */
       var thumb = state.annotated ? (item.heatmap || item.new || item.original || '') : (item.new || item.original || '');
       var hasDiff = item.diff || item.heatmap;
+      var badgeText = hasDiff
+        ? (item.diff_level != null ? item.diff_level + '%' : 'changed')
+        : 'pass';
       btn.innerHTML =
         '<div class="thumb-img-wrap"><img src="' + esc(thumb) + '" alt="" loading="lazy"/></div>' +
         '<div class="thumb-footer">' +
           '<div class="thumb-name">' + esc(item.name) + '</div>' +
-          '<span class="thumb-badge ' + (hasDiff ? 'thumb-badge-fail' : 'thumb-badge-pass') + '">' + (hasDiff ? 'changed' : 'pass') + '</span>' +
+          '<span class="thumb-badge ' + (hasDiff ? 'thumb-badge-fail' : 'thumb-badge-pass') + '">' + badgeText + '</span>' +
         '</div>';
       btn.addEventListener('click', function() { selectItem(+this.dataset.idx); });
       sidebarList.appendChild(btn);
@@ -283,7 +287,11 @@
     var pos = filtered.indexOf(state.current);
     navCounter.textContent = (pos + 1) + '/' + filtered.length;
     var hasDiff = item.diff || item.heatmap;
-    topBadge.textContent = hasDiff ? 'changed' : 'pass';
+    if (hasDiff && item.diff_level != null) {
+      topBadge.textContent = item.diff_level + '% diff';
+    } else {
+      topBadge.textContent = hasDiff ? 'changed' : 'pass';
+    }
     topBadge.className = 'diff-badge ' + (hasDiff ? 'diff-badge-fail' : 'diff-badge-pass');
 
     /* Resolve image sources based on view + annotated toggle */
@@ -326,7 +334,19 @@
   viewBtns.forEach(function(btn) {
     btn.addEventListener('click', function() { state.view = this.dataset.view; render(); buildSidebar(); });
   });
-  annotateBtn.addEventListener('click', function() { state.annotated = !state.annotated; render(); buildSidebar(); });
+  function toggleAnnotated() { state.annotated = !state.annotated; render(); buildSidebar(); }
+  annotateBtn.addEventListener('click', toggleAnnotated);
+
+  /* Click on image toggles annotated mode (ignore drags) */
+  var clickStart = null;
+  viewArea.addEventListener('mousedown', function(e) { clickStart = { x: e.clientX, y: e.clientY }; });
+  viewArea.addEventListener('click', function(e) {
+    if (!clickStart) return;
+    var dx = Math.abs(e.clientX - clickStart.x), dy = Math.abs(e.clientY - clickStart.y);
+    clickStart = null;
+    if (dx > 3 || dy > 3) return; /* was a drag, not a click */
+    if (e.target.closest('.img-box')) toggleAnnotated();
+  });
 
   /* ── Per-image zoom ────────────────────────────────────────────────── */
   function applyZoom() {
@@ -339,22 +359,42 @@
         img.style.width = '100%';
         img.style.height = '100%';
         img.style.objectFit = 'contain';
-        box.style.overflow = 'hidden';
+        box.classList.remove('pannable');
       } else {
-        /* Scale image beyond container — enable scrolling */
         img.style.width = (s * 100) + '%';
         img.style.height = 'auto';
         img.style.objectFit = '';
-        box.style.overflow = 'auto';
+        box.classList.add('pannable');
       }
     });
     $('zoom-label').textContent = state.zoom + '%';
   }
 
-  /* ── Per-image drag-to-pan ─────────────────────────────────────────── */
+  /* ── Synchronized drag-to-pan across all img-boxes ───────────────── */
+  var syncing = false;
+
+  function syncScroll(source) {
+    if (syncing) return;
+    syncing = true;
+    var boxes = viewInner.querySelectorAll('.img-box');
+    boxes.forEach(function(box) {
+      if (box !== source) {
+        box.scrollLeft = source.scrollLeft;
+        box.scrollTop = source.scrollTop;
+      }
+    });
+    syncing = false;
+  }
+
   function initPan() {
-    viewInner.querySelectorAll('.img-box').forEach(function(box) {
+    var boxes = viewInner.querySelectorAll('.img-box');
+    boxes.forEach(function(box) {
       var drag = false, startX, startY, scrollL, scrollT;
+
+      /* Sync on any scroll (drag, wheel, trackpad) */
+      box.addEventListener('scroll', function() { syncScroll(box); });
+
+      /* Drag to pan */
       box.addEventListener('mousedown', function(e) {
         if (state.zoom <= 100) return;
         drag = true; box.classList.add('dragging');
@@ -371,12 +411,22 @@
     });
   }
 
-  function zoomTo(v) { state.zoom = Math.max(50, Math.min(400, v)); applyZoom(); }
+  function zoomTo(v) { state.zoom = Math.max(25, Math.min(500, v)); applyZoom(); }
 
   $('zoom-in').addEventListener('click', function() { zoomTo(state.zoom + 50); });
   $('zoom-out').addEventListener('click', function() { zoomTo(state.zoom - 50); });
   $('zoom-fit').addEventListener('click', function() { zoomTo(100); });
 
+  /* Ctrl/Cmd/Alt + scroll wheel to zoom (smooth, small steps) */
+  viewArea.addEventListener('wheel', function(e) {
+    if (!(e.ctrlKey || e.metaKey || e.altKey)) return;
+    e.preventDefault();
+    /* Use 5% steps for smooth zoom; clamp deltaY to avoid trackpad acceleration */
+    var step = 3;
+    var direction = e.deltaY < 0 ? 1 : -1;
+    zoomTo(state.zoom + direction * step);
+  }, { passive: false });
+
   /* ── Nav ───────────────────────────────────────────────────────────── */
   $('nav-prev').addEventListener('click', selectPrev);
   $('nav-next').addEventListener('click', selectNext);

scripts/generate_sample_report.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+# Generate a sample HTML report for manual testing
+require "erb"
+require "json"
+require "pathname"
+
+template_path = File.expand_path("../lib/capybara_screenshot_diff/reporters/templates/report.html.erb", __dir__)
+output_path = File.expand_path("../tmp/sample_report.html", __dir__)
+fixtures = Pathname.new(File.expand_path("../test/fixtures", __dir__))
+
+img = fixtures / "images"
+screenshots = fixtures / "app/doc/screenshots"
+mac_sel = screenshots / "macos/selenium_headless"
+mac_cup = screenshots / "macos/cuprite"
+
+# Use visually distinct base/new pairs so the difference is obvious
+failed_screenshots = [
+  {
+    name: "islands-map",
+    original: (img / "a.png").to_s,
+    new: (img / "b.png").to_s,
+    base_diff: (img / "b.diff.png").to_s,
+    diff: (img / "b.diff.png").to_s,
+    heatmap: (img / "b.heatmap.diff.png").to_s,
+    diff_level: 2.34,
+    area_size: 1250,
+    max_color_distance: 42.5
+  },
+  {
+    name: "islands-variant",
+    original: (img / "a.png").to_s,
+    new: (img / "c.png").to_s,
+    base_diff: nil,
+    diff: nil,
+    heatmap: (img / "a.heatmap.diff.png").to_s,
+    diff_level: 8.71,
+    area_size: 4820,
+    max_color_distance: 118.3
+  },
+  {
+    name: "index-page",
+    original: (mac_sel / "index.base.png").to_s,
+    new: (mac_sel / "index.png").to_s,
+    base_diff: (mac_sel / "record_screenshot/record_index_cropped/00_index-cropped.base.diff.png").to_s,
+    diff: (mac_sel / "record_screenshot/record_index_cropped/00_index-cropped.diff.png").to_s,
+    heatmap: (mac_cup / "index.heatmap.diff.png").to_s,
+    diff_level: 0.12,
+    area_size: 340,
+    max_color_distance: 15.2
+  },
+  {
+    name: "cropped-form",
+    original: (mac_sel / "index-cropped.base.png").to_s,
+    new: (mac_sel / "index-cropped.png").to_s,
+    base_diff: nil,
+    diff: nil,
+    heatmap: (mac_cup / "index-cropped.heatmap.diff.png").to_s,
+    diff_level: 0.05,
+    area_size: 42,
+    max_color_distance: 3.0
+  },
+  {
+    name: "blur-active-element",
+    original: (mac_sel / "index-blur_active_element-enabled.base.png").to_s,
+    new: (mac_sel / "index-blur_active_element-enabled.png").to_s,
+    base_diff: nil,
+    diff: nil,
+    heatmap: nil,
+    diff_level: nil,
+    area_size: nil,
+    max_color_distance: nil
+  },
+  {
+    name: "portrait-layout",
+    original: (img / "portrait.png").to_s,
+    new: (img / "portrait_b.png").to_s,
+    base_diff: nil,
+    diff: nil,
+    heatmap: nil,
+    diff_level: nil,
+    area_size: nil,
+    max_color_distance: nil
+  }
+]
+
+total = 10
+failed = failed_screenshots.size
+passed = total - failed
+success_rate = ((passed.to_f / total) * 100).round(1)
+
+template = ERB.new(File.read(template_path))
+html = template.result(binding)
+File.write(output_path, html)
+
+puts "Generated: #{output_path}"
+puts "Screenshots: #{failed} failed, #{passed} passed, #{total} total"

test/fixtures/app/doc/screenshots/macos/cuprite/report_annotated_both.png

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "system_test_case"
+require "capybara_screenshot_diff/reporters/html"
+
+class ReportScreenshotTest < SystemTestCase
+  setup do
+    @report_path = Pathname.new("test/fixtures/app/sample_report.html")
+    generate_sample_report
+  end
+
+  teardown do
+    @report_path.delete if @report_path.exist?
+    FileUtils.rm_rf(@img_dest) if @img_dest&.exist?
+  end
+
+  def test_report_both_view
+    visit "/sample_report.html"
+    screenshot "report_both"
+  end
+
+  def test_report_base_view
+    visit "/sample_report.html"
+    find("[data-view='base']").click
+    screenshot "report_base"
+  end
+
+  def test_report_new_view
+    visit "/sample_report.html"
+    find("[data-view='new']").click
+    screenshot "report_new"
+  end
+
+  def test_report_heatmap_view
+    visit "/sample_report.html"
+    find("[data-view='heatmap']").click
+    screenshot "report_heatmap"
+  end
+
+  def test_report_annotated_both
+    visit "/sample_report.html"
+    find("#annotate-toggle").click
+    screenshot "report_annotated_both"
+  end
+
+  private
+
+  def generate_sample_report
+    # Copy fixture images into the served app directory so Capybara can load them
+    img_dest = Pathname.new("test/fixtures/app/report_images")
+    img_dest.mkpath
+    img_src = Pathname.new("test/fixtures/images")
+
+    %w[a.png b.png c.png b.diff.png b.heatmap.diff.png a.heatmap.diff.png].each do |f|
+      FileUtils.cp(img_src / f, img_dest / f)
+    end
+
+    # Use relative paths from the report HTML location
+    img = Pathname.new("report_images")
+
+    failed_screenshots = [
+      {name: "islands-map", original: (img / "a.png").to_s, new: (img / "b.png").to_s,
+       base_diff: (img / "b.diff.png").to_s, diff: (img / "b.diff.png").to_s, heatmap: (img / "b.heatmap.diff.png").to_s},
+      {name: "islands-variant", original: (img / "a.png").to_s, new: (img / "c.png").to_s,
+       base_diff: nil, diff: nil, heatmap: (img / "a.heatmap.diff.png").to_s}
+    ]
+
+    total = 3
+    failed = failed_screenshots.size
+    passed = total - failed
+    success_rate = ((passed.to_f / total) * 100).round(1)
+
+    template = ERB.new(File.read(CapybaraScreenshotDiff::Reporters::HTML.new.send(:template_path)))
+    File.write(@report_path, template.result(binding))
+
+    @img_dest = img_dest
+  end
+end