capybara-screenshot-diff 1.12.0 → 1.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 163b89646e7610ebde81e77fb9f6ed8e81bb2fb74dce234846efcfbe9479ed2c
-  data.tar.gz: 30e46f9caecc9c705ed19309a246c7ea9353c179635e5be38be5513e187c5fc7
+  metadata.gz: dba172cde687794eeedbffe4c4112d58ed5c4e2fcac5cdaf93b84827396e832d
+  data.tar.gz: a6b45b9bfc4ff349b506c7045f54392101c1bbfecda7b51475758fd2ee1536c0
 SHA512:
-  metadata.gz: 7c58c2d084f4d052591d2f4bd1b4b983a9a933f5e4f4be8d1ef7683c8bc060ae9bf3d3deaaf381bb344ae6c21de723ee61e1fd54e30b825b5741b1f903509da2
-  data.tar.gz: e879a7f5f9bc06ca083157fc7cc24a08a38b5419ddfd6ab2e0ef63f5e4379ca6f9e864bb21f869f7d9617b3514ca691d4f3af090a00ec3cc4adec3de5215e095
+  metadata.gz: afc332553b0bdafe8a47d82376b83b866bcd25144132f6e6ba481e41b03fd113ea74cf25f1decfcff8397664b1d4e2469abbfd21bebfde2a2c42f332ca0220dc
+  data.tar.gz: 1bd843fa71d17a0eac95bf1674a8d76352a8fe8c93c581840f9a50f63106edd40c5964b25ac36add805c6baf4129138e01aca5f73df30b34646fb1c2814adacd

data/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [v1.14.0] - 2026-08-22
+
+### Added
+- **`SnapDiff` namespace aliases** — `SnapDiff::Comparison`, `SnapDiff.compare`, and `SnapDiff.start` provide a forward-looking entry point onto the existing `Capybara::Screenshot::Diff` API, no behavior changes ([#166](https://github.com/snap-diff/snap_diff-capybara/issues/166))
+
+### Fixed
+- **Standalone require path** — `require "capybara_screenshot_diff"` (or `require "snap_diff"`) followed by `Diff.compare` no longer raises `NameError` for the missing drivers require ([#194](https://github.com/snap-diff/snap_diff-capybara/pull/194))
+
+### Internal
+- Merged `DifferenceFinder` into `ImageCompare` (ADR-004 step) ([#192](https://github.com/snap-diff/snap_diff-capybara/pull/192))
+- Extracted `AnnotationService` from `Reporters::Default`; full public surface preserved via delegation ([#193](https://github.com/snap-diff/snap_diff-capybara/pull/193))
+- Consolidated `pending_if_new` teardown logic into one shared helper across Minitest/RSpec/Cucumber adapters ([#197](https://github.com/snap-diff/snap_diff-capybara/pull/197))
+- Test-suite driver-coverage banner and CI guard against silently missing drivers ([#198](https://github.com/snap-diff/snap_diff-capybara/pull/198))
+
+---
+
+## [v1.13.0] - 2026-08-22
+
+### Added
+- **`capture_screenshot` DSL method** — take a screenshot without ever comparing or asserting ([#191](https://github.com/snap-diff/snap_diff-capybara/issues/191))
+- **`compare:` option on `screenshot`** — pass `compare: true` (default) to assert, or `compare: false` to capture only ([#191](https://github.com/snap-diff/snap_diff-capybara/issues/191))
+- **`Capybara::Screenshot::Diff.pending_if_new` config** — mark tests as skipped in teardown when a baseline does not exist, complementing `fail_if_new` ([#191](https://github.com/snap-diff/snap_diff-capybara/issues/191))
+
+### Changed
+- **`assert_matches_screenshot` is now the primary assertion method** — captures a screenshot and compares against baseline ([#191](https://github.com/snap-diff/snap_diff-capybara/issues/191))
+- **`screenshot` is now a convenience wrapper** — safe to override in user test classes; the gem no longer calls it internally ([#191](https://github.com/snap-diff/snap_diff-capybara/issues/191))
+
+---
+
 ## [v1.12.0] - 2026-04-12
 
 ### Added

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,129 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement by
+[opening a GitHub Issue](https://github.com/snap-diff/snap_diff-capybara/issues).
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact:** Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence:** A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact:** A violation through a single incident or series
+of actions.
+
+**Consequence:** A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact:** A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence:** A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact:** Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence:** A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

data/docs/RELEASE_PREP.md

@@ -1,23 +1,23 @@
-# Release Preparation — v1.12.0
+# Release Preparation — v1.14.0
 
 ## Summary
 
-71 commits since v1.11.0 with new features, performance improvements, and default behavior changes.
+SnapDiff namespace aliases (ADR-004 PR 9), standalone-require fix, and three
+internal consolidation refactors (ADR-004 PR 2/PR 7, teardown logic).
 
 ## Release Checklist
 
 ### Pre-Release
 
-- [x] Update version to `1.12.0`
-- [x] Run tests: `bundle exec rake test` (218 runs, 0 failures)
-- [x] Add CHANGELOG.md
-- [x] Add docs/UPGRADING.md
+- [x] Update version to `1.14.0`
+- [x] Run tests: `bundle exec rake test:unit` (green)
+- [x] Update CHANGELOG.md
 
 ### Release (One Click)
 
 1. Push to GitHub
 2. Go to [Actions → Release](https://github.com/snap-diff/snap_diff-capybara/actions/workflows/release.yml)
-3. Click **Run workflow**, enter `1.12.0`
+3. Click **Run workflow**, enter `1.14.0`
 4. Workflow will: test → tag → publish to RubyGems → create GitHub Release
 
 ### Post-Release
@@ -27,32 +27,18 @@
 
 ## What Changed
 
-### New Features
-- HTML reporter with premium UI, 4 comparison modes, zoom, keyboard navigation
-- GitHub Actions artifact integration with inline preview + reusable composite action
-- `disable_animations` helper for stable screenshots
-- `snap_diff:clean` rake task for diff artifact cleanup
-- `Diff.compare` for standalone image comparison
-- Perceptual color distance (dE00) for anti-aliasing
-- `assert_no_screenshot_changes` DSL method
-- `Diff.configure` block helper
-- Ruby 3.5 & 4.0 support
-
-### Behavior Changes
-- `blur_active_element` defaults to `true`
-- `hide_caret` defaults to `true`
-- `fail_if_new` defaults to `true` in CI
-- Thread-safe reporter notification with mutex
-- SVN support removed
-- ActiveSupport no longer required
-
-### Performance
-- Faster ChunkyPNG shift-detection (eliminated allocations)
-- Cached computations in VIPS driver
-- Memoized region area size
-
-### Documentation
-- README restructured (970→149 lines) with 7 dedicated docs/ files
-- CI integration guide, upgrade guide, color comparison guide
+### Added
+- `SnapDiff` namespace aliases — `SnapDiff::Comparison`, `SnapDiff.compare`,
+  `SnapDiff.start` (additive; deprecations deferred to v2.0)
+
+### Fixed
+- Standalone `require "capybara_screenshot_diff"` + `Diff.compare` no longer
+  raises `NameError` (missing drivers require)
+
+### Internal
+- `DifferenceFinder` merged into `ImageCompare`; `AnnotationService` extracted
+  from `Reporters::Default` (public surface preserved); `pending_if_new`
+  teardown consolidated across the three framework adapters; driver-coverage
+  banner + CI guard in the test suite
 
 See [CHANGELOG.md](../CHANGELOG.md) for full details.

data/docs/UPGRADING.md

@@ -1,6 +1,91 @@
-# Upgrading to v1.12.0
+# Upgrading
 
-## Overview
+## Upgrading to v1.13.0
+
+### Overview
+
+Version 1.13.0 is a **minor release** clarifying API terminology and adding new capture methods. No breaking changes — your existing code continues to work.
+
+**Estimated upgrade time:** 0 minutes (no action required for most users)
+
+---
+
+### Quick Upgrade Path (Most Users)
+
+```ruby
+# In your Gemfile
+gem 'capybara-screenshot-diff', '~> 1.13.0'
+```
+
+```bash
+bundle update capybara-screenshot-diff
+bundle exec rake test
+```
+
+**That's it!** Existing `screenshot` calls work unchanged. New methods available if needed.
+
+---
+
+### What Changed
+
+#### API Clarification: Primary Method is `assert_matches_screenshot`
+
+**v1.12.0 and earlier:** `screenshot` was the primary method  
+**v1.13.0+:** `assert_matches_screenshot` is the primary method
+
+**Action required:** None. `screenshot` continues to work as-is.
+
+The method names now better reflect their behavior:
+- `assert_matches_screenshot(name)` — takes screenshot and asserts it matches baseline
+- `screenshot(name, compare: true)` — convenience wrapper (same behavior as above when `compare: true`)
+- `capture_screenshot(name)` — new: captures without asserting
+
+```ruby
+# All three work and are safe to use:
+assert_matches_screenshot "homepage"                # Primary: explicit intent
+screenshot "homepage"                               # Shorthand (familiar)
+screenshot "homepage", compare: false               # Capture only
+capture_screenshot "homepage"                       # Also capture only
+```
+
+**Safe to override:** You can safely define your own `screenshot` method in your test base class — the gem's implementation won't interfere.
+
+---
+
+### New: `capture_screenshot` Method
+
+Capture without comparing to baseline:
+
+```ruby
+capture_screenshot "dynamic_page"  # No assertion
+```
+
+Equivalent to: `screenshot "dynamic_page", compare: false`
+
+---
+
+### New: `Diff.pending_if_new` Helper
+
+Mark baseline-less tests pending instead of failing during initial CI runs:
+
+```ruby
+# In test_helper.rb — before running tests
+Capybara::Screenshot::Diff.pending_if_new = true
+```
+
+**CI requirement:** When using `pending_if_new`, ensure CI is configured with `fail_if_new: false` (see [Configuration Reference](configuration.md#quick-setup)):
+
+```ruby
+Capybara::Screenshot::Diff.configure do |screenshot, diff|
+  diff.fail_if_new = false  # Allow baselines to be added
+end
+```
+
+---
+
+## Upgrading to v1.12.0
+
+### Overview
 
 Version 1.12.0 is a **minor release** with new features, performance improvements, and default behavior changes. This guide will help you upgrade smoothly.
 

data/docs/architecture.md

@@ -0,0 +1,269 @@
+# Architecture
+
+This document describes the internal architecture of `capybara-screenshot-diff` — how screenshots are captured, compared, and reported, and how the components fit together.
+
+## Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Test Framework                         │
+│  (Minitest / RSpec / Cucumber / Custom)                  │
+└──────────────┬──────────────────────────────┬────────────┘
+               │                              │
+               ▼                              ▼
+┌──────────────────────────┐    ┌──────────────────────────┐
+│  CapybaraScreenshotDiff   │    │  CapybaraScreenshotDiff   │
+│  ::DSL (screenshot, etc)  │    │  ::AssertionRegistry       │
+└──────────────┬───────────┘    └──────────────┬───────────┘
+               │                               │
+               ▼                               ▼
+┌──────────────────────────┐    ┌──────────────────────────┐
+│  ScreenshotMatcher        │    │  ScreenshotAssertion     │
+│  (capture + compare)      │    │  (validate results)      │
+└──────┬───────────┬────────┘    └──────────────┬───────────┘
+       │           │                            │
+       ▼           ▼                            ▼
+┌──────────┐ ┌──────────┐           ┌──────────────────────┐
+│Screenshot│ │Stable    │           │   Reporters           │
+│er        │ │Screenshot│           │  (Default / HTML /    │
+│          │ │er        │           │   Custom)             │
+└─────┬────┘ └──────────┘           └──────────────────────┘
+      │
+      ▼
+┌──────────────────────────────────────────┐
+│  ImageCompare (layered comparison)       │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐  │
+│  │1. Byte   │ │2. Pixel  │ │3. Region │  │
+│  │  compare │ │  compare │ │  analyze │  │
+│  └──────────┘ └──────────┘ └──────────┘  │
+└─────────────────────┬────────────────────┘
+                      │
+                      ▼
+┌──────────────────────────────────────────┐
+│  Drivers (image processing backends)     │
+│  ┌──────────┐ ┌──────────────────────┐   │
+│  │ Vips     │ │ ChunkyPNG            │   │
+│  │ (fast)   │ │ (no native deps)     │   │
+│  └──────────┘ └──────────────────────┘   │
+└──────────────────────────────────────────┘
+```
+
+## Component Breakdown
+
+### 1. DSL Layer (`lib/capybara_screenshot_diff/dsl.rb`)
+
+The entry point for test code. `assert_matches_screenshot` is the primary assertion method (captures and compares). `screenshot` is a convenience wrapper with a `compare:` option — `compare: true` (default) delegates to `assert_matches_screenshot`, while `compare: false` delegates to the new `capture_screenshot` method. `capture_screenshot` takes screenshots without assertions. `assert_no_screenshot_changes` keeps its behavior but now delegates to `assert_matches_screenshot` (that redirect is part of the #191 fix). Users can safely override `screenshot` in their test classes without affecting internal gem flow.
+
+**Flow:**
+1. Checks if screenshots are `active?` (returns `false` if disabled)
+2. Builds a full screenshot name via `ScreenshotNamer` (handles sections, groups, counters)
+3. Delegates to `ScreenshotMatcher` to capture and prepare comparison
+4. Creates a `ScreenshotAssertion` — either adds it to the thread-local registry (delayed validation) or validates immediately
+
+### 2. ScreenshotMatcher (`lib/capybara/screenshot/diff/screenshot_matcher.rb`)
+
+The orchestrator that coordinates capture and comparison:
+
+1. **Window size check** — verifies browser window is the expected size
+2. **Area calculation** — resolves crop regions and skip areas (supports CSS selectors and coordinates)
+3. **Base screenshot checkout** — retrieves the committed baseline from git via `Vcs.checkout_vcs`
+4. **Capture** — delegates to `Screenshoter` or `StableScreenshoter` depending on `stability_time_limit`
+5. **Comparison** — creates an `ImageCompare` object (lazy — actual comparison happens on first access)
+6. **Assertion** — returns a `ScreenshotAssertion` with the comparison attached
+
+**Key design decision:** The "new" screenshot is taken *first*, then compared against the baseline. This means if no baseline exists (first run), we skip comparison entirely and the test passes.
+
+### 3. Screenshoter & StableScreenshoter (`lib/capybara/screenshot/diff/screenshoter.rb`, `lib/capybara/screenshot/diff/stable_screenshoter.rb`)
+
+**Screenshoter:** The basic capture flow:
+1. Prepares the page (blur active element, hide caret, disable animations, wait for images)
+2. Takes a browser screenshot via `Capybara.current_session.save_screenshot`
+3. Processes the screenshot (resize for retina, apply crop)
+
+**StableScreenshoter:** Wraps `Screenshoter` with stability detection:
+1. Takes sequential screenshots at `stability_time_limit` intervals
+2. Compares consecutive attempts for byte-level equality
+3. Returns once two consecutive screenshots are identical
+4. Fails with `UnstableImage` if timeout (`wait`) is reached, generating annotated attempt images for debugging
+
+### 4. ImageCompare (`lib/capybara/screenshot/diff/image_compare.rb`)
+
+The comparison engine uses a **layered optimization strategy** to balance speed and accuracy:
+
+| Layer | Method | What it checks | Speed | When it returns |
+|-------|--------|----------------|-------|-----------------|
+| 1 | `quick_equal?` | File size + byte-level comparison | Fastest | Equal → `true`, Different → Layer 2 |
+| 2 | `quick_equal?` continues | Dimension check + pixel comparison | Fast | Different dimensions → `false`, Same pixels → `true` |
+| 3 | `processed` / `different?` | Full region analysis with tolerance | Slower | Detailed diff with region, heatmap, annotations |
+
+**Key details:**
+- `quick_equal?` is designed for fast rejection — it early-returns as soon as a difference is found
+- `different?` triggers the full comparison if not already processed
+- `processed` guarantees the comparison is complete and returns the result with all metadata
+- `ImageCompare#analyze_difference` handles the actual pixel analysis, delegating to the driver
+
+### 5. Drivers (`lib/capybara/screenshot/diff/drivers/`)
+
+Drivers abstract image processing operations. Each driver implements:
+
+| Operation | VipsDriver | ChunkyPNGDriver |
+|-----------|-----------|-----------------|
+| `load_images` | Vips::Image from file | ChunkyPNG::Image from blob |
+| `same_dimension?` | Compare width × height | Same |
+| `same_pixels?` | Pixel-level equality | Same |
+| `find_difference_region` | Difference mask → Region | Row-by-row scan → Region |
+| `crop` | Vips image crop | ChunkyPNG crop |
+| `save_image_to` | Vips write_to_file | PNG save |
+| `filter_image_with_median` | Vips median filter | Not supported |
+| `add_black_box` | Draw filled rect | No-op (handled differently) |
+| `merge` | Composite images | Not applicable |
+| `highlight_mask` | Conditional color overlay | Not applicable |
+
+**Auto-detection:** `Utils.detect_available_drivers` tries to load `:vips` first (via `ruby-vips` gem), then `:chunky_png`. The `:auto` driver mode picks the first available.
+
+### 6. Difference Region Detection
+
+**VipsDriver** uses a **difference mask** approach:
+1. Compute absolute difference between images: `(new - base).abs`
+2. Optional: apply perceptual color distance (CIE dE00) instead of raw RGB
+3. Project the mask to find the bounding region of non-zero pixels
+4. Return the tight bounding box of all differences
+
+**ChunkyPNGDriver** uses **row-by-row scanning**:
+1. Scan top-to-bottom, left-to-right for first differing pixel
+2. Expand left/right boundaries within each differing row
+3. Extend bottom boundary to cover all differing rows
+4. Supports shift detection (expensive neighbor pixel search)
+
+### 7. SnapManager & Snap (`lib/capybara_screenshot_diff/snap_manager.rb`, `lib/capybara_screenshot_diff/snap.rb`)
+
+**Snap** represents a single screenshot file with path management:
+- `path` — the actual screenshot file
+- `base_path` — the `.base.ext` VCS checkout
+- `attempt_path` — stability attempt files (`.attempt_00.png`, etc.)
+- Provides cleanup of diff artifacts (`.diff.png`, `.heatmap.diff.png`)
+
+**SnapManager** is the factory and path manager:
+- Creates `Snap` instances
+- Handles VCS checkout of baselines
+- Manages file operations (copy, move, cleanup)
+
+### 8. VCS (`lib/capybara/screenshot/diff/vcs.rb`)
+
+Handles baseline retrieval from git. Uses `git show HEAD:<path>` to extract the committed version. Supports Git LFS via `git lfs smudge`. Returns `false` if the file doesn't exist in VCS (first-run scenario).
+
+### 9. Reporters (`lib/capybara/screenshot/diff/reporters/`)
+
+**Default reporter:** Generates annotated diff images:
+- `image.diff.png` — new screenshot with diff region outlined in red
+- `image.base.diff.png` — baseline with diff region outlined in red
+- `image.heatmap.diff.png` — heatmap overlay of pixel differences
+
+**HTML reporter:** Generates an interactive dashboard (`snap_diff_report.html`) with:
+- Sidebar with thumbnails and search
+- 4 view modes (both/base/new/heatmap)
+- Annotated toggle for showing diff outlines
+- Per-image zoom with synchronized panning across side-by-side views
+- Keyboard navigation and shortcuts
+- Responsive layout for mobile
+
+**Custom reporters:** Implement `record(assertions)` and `finalize` methods, then add to `CapybaraScreenshotDiff.reporters`.
+
+### 10. Assertion Lifecycle
+
+```
+Test begins
+    │
+    ├─ setup: resize_window_if_needed
+    │
+    ├─ test body:
+    │    └─ screenshot("name")
+    │         ├─ ScreenshotMatcher builds assertion
+    │         ├─ delayed=true → add to Thread-local registry
+    │         └─ delayed=false → validate immediately
+    │
+    ├─ teardown:
+    │    └─ CapybaraScreenshotDiff.verify
+    │         ├─ iterates thread-local assertions
+    │         ├─ calls validate on each
+    │         ├─ raises ExpectationNotMet on first failure
+    │         └─ notifies reporters via mutex-protected snapshot
+    │
+    └─ at_exit:
+         └─ CapybaraScreenshotDiff.finalize_reporters!
+              ├─ Generates HTML report (if reporter registered)
+              └─ Prints summary
+```
+
+### 11. Thread Safety
+
+| Concern | Mechanism |
+|---------|-----------|
+| Assertion registry | Thread-local storage (`Thread.current[:capybara_screenshot_diff_registry]`) |
+| Reporter notification | Mutex-protected snapshot of reporter list before iteration |
+| HTML reporter internals | Mutex protecting `@failures`, `@total`, `@finalized` |
+| Screenshot naming | Per-thread `ScreenshotNamer` instance |
+| Global configuration | `mattr_accessor` — must be set before tests run, not mutated during parallel execution |
+| File system | Atomic `FileUtils.mv`, unique paths per screenshot name + counter, thread-safe `mkpath` |
+
+### 12. Configuration System
+
+Configuration uses Ruby's `mattr_accessor` (from ActiveSupport, or pure Ruby fallback) and is organized into two namespaces:
+
+**`Capybara::Screenshot`** — capture settings:
+- `window_size`, `stability_time_limit`, `blur_active_element`, `hide_caret`, `disable_animations`
+- `save_path`, `root`, `screenshot_format`, `add_driver_path`, `add_os_path`
+- `enabled`, `capybara_screenshot_options`
+
+**`Capybara::Screenshot::Diff`** — comparison settings:
+- `driver`, `tolerance`, `color_distance_limit`, `perceptual_threshold`, `shift_distance_limit`
+- `area_size_limit`, `skip_area`, `fail_if_new`, `fail_on_difference`, `delayed`
+
+The `Diff.configure` block helper provides a convenient way to set both namespaces at once.
+
+## File Layout
+
+```
+lib/
+  capybara_screenshot_diff.rb                  # Core module, mattr_accessor definitions
+  capybara/screenshot/diff.rb                  # Convenience require (loads minitest)
+  capybara_screenshot_diff/
+    dsl.rb                                     # screenshot(), screenshot_group(), etc.
+    minitest.rb                                # Minitest assertions integration
+    rspec.rb                                   # RSpec matcher integration
+    cucumber.rb                                # Cucumber World integration
+    static.rb                                  # Non-Rails static site serving
+    snap_manager.rb                            # Screenshot file management
+    snap.rb                                    # Single screenshot file abstraction
+    screenshot_namer.rb                        # Name/path generation with sections/groups
+    screenshot_assertion.rb                    # Assertion + registry objects
+    attempts_reporter.rb                       # Debug reporting for unstable captures
+    error_with_filtered_backtrace.rb           # Error with filtered stack
+    backtrace_filter.rb                        # Library/gem frame filtering
+    reporters/
+      html.rb                                  # Interactive HTML report reporter
+      templates/report.html.erb                # HTML report template
+  capybara/screenshot/diff/
+    version.rb                                 # VERSION constant
+    utils.rb                                   # Driver detection
+    drivers.rb                                 # Driver factory
+    drivers/
+      base_driver.rb                           # Abstract base driver
+      vips_driver.rb                           # VIPS image processing
+      chunky_png_driver.rb                     # ChunkyPNG image processing
+    screenshoter.rb                            # Basic browser screenshot capture
+    stable_screenshoter.rb                     # Stability detection wrapper
+    screenshot_matcher.rb                      # Orchestrator for capture + compare
+    image_compare.rb                           # Layered comparison engine
+    comparison.rb                              # Comparison value object
+    difference.rb                              # Difference result value object
+    image_preprocessor.rb                      # Pre-processing (skip areas, median filter)
+    area_calculator.rb                         # Crop/skip area coordinate resolution
+    region.rb                                  # Bounding box region value object
+    browser_helpers.rb                         # DOM manipulation helpers
+    vcs.rb                                     # Git baseline checkout
+    os.rb                                      # OS detection
+    cucumber.rb                                # Deprecated Cucumber entry point
+    reporters/
+      default.rb                               # Default annotated-image reporter
+```