snap_diff-capybara 2.0.0.alpha1 → 2.0.0.beta2

data/docs/ci-integration.md

@@ -4,10 +4,19 @@
 
 ```ruby
 # test/test_helper.rb
-require 'capybara_screenshot_diff/static'
+require 'snap_diff/static'
+
+SnapDiff.serve("_site")  # or "public", "build", "dist"
+```
+
+<details>
+<summary>Legacy names (still supported)</summary>
 
-CapybaraScreenshotDiff.serve("_site")  # or "public", "build", "dist"
+```ruby
+require 'capybara_screenshot_diff/static'
+CapybaraScreenshotDiff.serve("_site")
 ```
+</details>
 
 This sets up Capybara to serve static files and configures screenshot paths automatically.
 
@@ -24,7 +33,8 @@ Only commit the baseline screenshots (e.g., `homepage.png`). The `.base.png`, `.
 Add to your test helper:
 
 ```ruby
-require 'capybara_screenshot_diff/reporters/html'
+require 'snap_diff/reporters/html'            # canonical
+# require 'capybara_screenshot_diff/reporters/html'   # legacy, same thing
 ```
 
 ### 2. Reusable composite action (recommended)

data/docs/configuration.md

@@ -2,10 +2,25 @@
 
 ## Quick Setup
 
-Configure all settings in one place using the `configure` helper:
+**Canonical (v2):** every setting lives on one flat object, `SnapDiff.config`.
 
 ```ruby
 # In test_helper.rb or rails_helper.rb
+SnapDiff.configure do |config|
+  config.window_size = [1280, 1024]
+  config.stability_time_limit = 1
+  config.blur_active_element = true
+  config.hide_caret = true
+  config.driver = :vips
+  config.tolerance = 0.0005
+  config.color_distance_limit = 15
+end
+```
+
+**Legacy (still supported):** the two-holder block, split across `Capybara::Screenshot` and
+`Capybara::Screenshot::Diff`.
+
+```ruby
 Capybara::Screenshot::Diff.configure do |screenshot, diff|
   screenshot.window_size = [1280, 1024]
   screenshot.stability_time_limit = 1
@@ -17,6 +32,20 @@ Capybara::Screenshot::Diff.configure do |screenshot, diff|
 end
 ```
 
+`SnapDiff::Config` **is** the storage; the legacy accessors are thin delegators onto it. There is
+one source of truth, so a write through either surface is visible through the other — mixing them
+is safe, and you can migrate a suite one line at a time:
+
+```ruby
+SnapDiff.config.window_size = [1280, 1024]
+Capybara::Screenshot.window_size    # => [1280, 1024]
+```
+
+Every option name below is identical on both surfaces — only the receiver changes. The one
+exception: `Capybara::Screenshot.enabled` is `SnapDiff.config.screenshot_enabled`, because
+`SnapDiff.config.enabled` is taken by `Capybara::Screenshot::Diff.enabled`. See
+[SnapDiff — the canonical API](snapdiff.md) for the full SnapDiff-native surface.
+
 **Note:** `fail_if_new` defaults to `true` in CI environments (when `ENV['CI']` is set). New screenshots are allowed locally but rejected in CI — no configuration needed.
 
 **Note:** Setting `Capybara::Screenshot.enabled = false` is sufficient to disable all screenshots. There is no need to define no-op modules or monkey-patch the gem.
@@ -77,7 +106,7 @@ screenshot 'dashboard', color_distance_limit: 15
 
 **Tier 1 — Zero config (works immediately):**
 `blur_active_element`, `hide_caret`, and `fail_if_new` (in CI) are enabled by default.
-Just `require 'capybara_screenshot_diff/minitest'` and call `screenshot`.
+Just `require 'snap_diff/integrations/minitest'` (legacy: `capybara_screenshot_diff/minitest`) and call `screenshot`.
 
 **Tier 2 — Set when tests are flaky:**
 

data/docs/drivers.md

@@ -1,5 +1,11 @@
 # Image Processing Drivers
 
+> **Canonical equivalents.** Global settings shown here as
+> `Capybara::Screenshot::Diff.<option> = …` are also `SnapDiff.config.<option> = …` — same
+> option names, same storage, either surface works. Writing your own driver? See
+> [Custom drivers](snapdiff.md#custom-drivers) for the `SnapDiff::Driver` mixin and how
+> registration in `SnapDiff::Drivers.loaded` works.
+
 ## Perceptual color comparison (VIPS only)
 
 By default, color differences are measured using raw RGB channel distance. This can produce

data/docs/framework-setup.md

@@ -1,5 +1,19 @@
 # Framework Setup
 
+> **Canonical equivalents.** This page uses the legacy `CapybaraScreenshotDiff` names, which keep
+> working. Each has a `SnapDiff` home:
+>
+> | This page | Canonical |
+> |-----------|-----------|
+> | `require "capybara_screenshot_diff/minitest"` | `require "snap_diff/integrations/minitest"` |
+> | `require "capybara_screenshot_diff/rspec"` | `require "snap_diff/integrations/rspec"` |
+> | `require "capybara_screenshot_diff/cucumber"` | `require "snap_diff/integrations/cucumber"` |
+> | `CapybaraScreenshotDiff::DSL` | `SnapDiff::DSL` |
+> | `CapybaraScreenshotDiff::Minitest::Assertions` | `SnapDiff::Minitest::Assertions` |
+> | `CapybaraScreenshotDiff.finalize_reporters!` | `SnapDiff::Reporting.finalize!` |
+>
+> The canonical setup, written out in full, is in [SnapDiff — the canonical API](snapdiff.md).
+
 ## Including DSL
 
 To use the screenshot capturing and change detection features in your tests, include the `CapybaraScreenshotDiff::DSL` in your test classes. It provides the `screenshot` method to capture and compare screenshots.
@@ -76,12 +90,16 @@ end
 
 ## Custom Test Frameworks
 
-Minitest, RSpec, and Cucumber are supported out of the box. For other frameworks, call `finalize_reporters!` in your framework's "after suite" hook:
+Minitest, RSpec, and Cucumber are supported out of the box. For other frameworks, call the
+end-of-suite hook yourself:
 
 ```ruby
-CapybaraScreenshotDiff.finalize_reporters!
+SnapDiff::Reporting.finalize!            # canonical
+CapybaraScreenshotDiff.finalize_reporters!   # legacy, same thing
 ```
 
-This generates the HTML report and prints the summary.
+This generates the HTML report and prints the summary. A framework also needs the per-test
+lifecycle wired up — see
+[Frameworks other than Minitest/RSpec/Cucumber](snapdiff.md#frameworks-other-than-minitestrspeccucumber).
 
 [← Back to README](../README.md)

data/docs/reporters.md

@@ -6,7 +6,8 @@ Generate an interactive Web UI report of screenshot differences:
 
 ```ruby
 # Add to test_helper.rb — one line, that's it
-require 'capybara_screenshot_diff/reporters/html'
+require 'snap_diff/reporters/html'            # canonical
+# require 'capybara_screenshot_diff/reporters/html'   # legacy, same thing
 ```
 
 After running tests, open the report (generated only when there are failures):
@@ -21,7 +22,7 @@ The report includes a sidebar with thumbnails, side-by-side comparison with diff
 
 ## Custom Reporters
 
-Build your own reporter by implementing `record` and `finalize`:
+Build your own reporter by implementing `record`, `finalize` and `summary`:
 
 ```ruby
 class MyReporter
@@ -33,14 +34,28 @@ class MyReporter
   end
 
   def finalize
-    # called once at process exit — write summary, upload report, etc.
+    # called once at end of suite — write summary, upload report, etc.
+  end
+
+  def summary
+    # printed to stdout after finalize; return nil to print nothing
+    nil
   end
 end
 
 # Register in test_helper.rb
-CapybaraScreenshotDiff.reporters << MyReporter.new
+SnapDiff::Reporting.register(MyReporter.new)   # canonical — appends under the mutex
+# CapybaraScreenshotDiff.reporters << MyReporter.new   # legacy, same list, skips the lock
 ```
 
-Reporters are notified before assertions are cleared on each test teardown. `finalize` is called via `at_exit`.
+Reporters are notified before assertions are cleared on each test teardown. `finalize` runs from
+the framework's end-of-suite hook (`Minitest.after_run`, RSpec `after(:suite)`, Cucumber
+`AfterAll`), which calls `SnapDiff::Reporting.finalize!`.
+
+**Do implement `summary`.** `finalize!` calls it unconditionally, so a reporter without it is
+finalized and then warned about. A reporter that raises is warned about and skipped — the others
+still run.
+
+Full details in [Custom reporters](snapdiff.md#custom-reporters).
 
 [← Back to README](../README.md)

data/docs/snapdiff.md

@@ -0,0 +1,326 @@
+# SnapDiff — the canonical API
+
+Everything in this gem lives under `SnapDiff` since v2. This page is the SnapDiff-native
+reference: setup, configuration, the object map, and the extension points — all using canonical
+names only.
+
+The legacy `Capybara::Screenshot::Diff` / `CapybaraScreenshotDiff` names still work (they resolve
+to the same objects, with a one-time deprecation warning per constant), and the rest of the docs
+still teach them. Nothing here replaces a working setup — it is what you write for **new** code.
+For migrating an existing suite, see [UPGRADING.md](UPGRADING.md).
+
+## Quick start
+
+### Minitest
+
+```ruby
+# test/test_helper.rb
+require "snap_diff/integrations/minitest"
+```
+
+```ruby
+# test/application_system_test_case.rb
+class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
+  include SnapDiff::Minitest::Assertions   # brings in SnapDiff::DSL too
+end
+```
+
+```ruby
+class HomepageTest < ApplicationSystemTestCase
+  test "homepage" do
+    visit "/"
+    assert_matches_screenshot "homepage"
+  end
+end
+```
+
+`SnapDiff::Minitest::Assertions` already includes `SnapDiff::DSL`, so a separate
+`include SnapDiff::DSL` is not needed (it is harmless if you have it).
+
+> **The require path is `snap_diff/integrations/…`, not `snap_diff/…`.**
+> `require "snap_diff/minitest"` raises `LoadError` — there is no such file. The integrations
+> live one level down, mirroring `lib/snap_diff/integrations/`.
+
+### RSpec
+
+```ruby
+# spec/rails_helper.rb
+require "snap_diff/integrations/rspec"
+```
+
+This registers the `match_screenshot` matcher and includes `SnapDiff::DSL` into
+`type: :feature` and `type: :system` examples automatically:
+
+```ruby
+RSpec.describe "Homepage", type: :system do
+  it "looks right" do
+    visit "/"
+    expect(page).to match_screenshot("homepage")
+  end
+end
+```
+
+For other example types, include the DSL yourself:
+
+```ruby
+RSpec.describe "Admin", type: :request do
+  include SnapDiff::DSL
+end
+```
+
+### Cucumber
+
+```ruby
+# features/support/env.rb
+require "snap_diff/integrations/cucumber"
+```
+
+The DSL is added to the Cucumber `World`, so steps can call `screenshot` /
+`assert_matches_screenshot` directly. This file must be loaded from inside a Cucumber run — it
+calls `World`, `Before`, `After` and `AfterAll` at load time and raises `NoMethodError` if
+required outside one.
+
+### Static sites (Hugo, Jekyll, plain HTML)
+
+```ruby
+require "snap_diff/static"
+
+SnapDiff.serve("_site")             # or "public", "build", "dist"
+SnapDiff.serve("_site", root: Dir.pwd)   # root defaults to Dir.pwd
+```
+
+`SnapDiff.serve` points Capybara at the built directory and sets the screenshot root. It also
+loads the Minitest integration. See
+[CI & Non-Rails Integration](ci-integration.md#non-rails-projects-hugo-jekyll-static-sites).
+
+## Configuration
+
+All 27 settings live on one flat object, `SnapDiff.config` (a `SnapDiff::Config`).
+
+```ruby
+# test_helper.rb / rails_helper.rb
+SnapDiff.configure do |config|
+  config.window_size = [1280, 1024]
+  config.tolerance = 0.0005
+  config.driver = :vips
+  config.save_path = "doc/screenshots"
+end
+
+# Or set them one at a time
+SnapDiff.config.hide_caret = true
+SnapDiff.config.tolerance          # => 0.0005
+```
+
+`SnapDiff::Config` **is** the storage. The legacy `Capybara::Screenshot.*` and
+`Capybara::Screenshot::Diff.*` accessors are thin delegators onto it — one storage, two views —
+so a write through either surface is immediately visible through the other:
+
+```ruby
+SnapDiff.config.window_size = [1280, 1024]
+Capybara::Screenshot.window_size    # => [1280, 1024]
+```
+
+`SnapDiff.start` is the same call shape as the old `Capybara::Screenshot::Diff.configure`, if
+you prefer the two-holder form:
+
+```ruby
+SnapDiff.start do |screenshot, diff|
+  screenshot.window_size = [1280, 1024]
+  diff.tolerance = 0.0005
+end
+```
+
+Three derived, read-only values are computed from the settings above:
+
+| Method | What it returns |
+|--------|-----------------|
+| `SnapDiff.config.active?` | Whether screenshots are taken at all (ex `Capybara::Screenshot.active?`) |
+| `SnapDiff.config.screenshot_area` | `save_path`, optionally segmented per OS and per Capybara driver |
+| `SnapDiff.config.default_options` | The capture/compare defaults handed to `SnapDiff::Comparison` |
+
+Every option's meaning is documented in the
+[Configuration Reference](configuration.md) — the names are identical, only the receiver differs.
+The one rename: `Capybara::Screenshot.enabled` is `SnapDiff.config.screenshot_enabled`, because
+`SnapDiff.config.enabled` is taken by `Capybara::Screenshot::Diff.enabled`.
+
+## Object map
+
+`require "snap_diff"` gives you the compare/configure core. The test-suite pieces come with the
+integration require; a few objects need their own require, noted below.
+
+| Object | What it is for |
+|--------|----------------|
+| `SnapDiff.config`, `SnapDiff::Config` | Every setting, one flat object. The storage. |
+| `SnapDiff.configure`, `SnapDiff.start` | Config block helpers (consolidated / v1 shape) |
+| `SnapDiff.compare` | Compare two image files directly, no browser |
+| `SnapDiff::Comparison` | The layered comparison engine (ex `ImageCompare`) |
+| `SnapDiff::Comparison::Images` | Frozen bundle a comparison operates on: both images, their paths, the driver and the options |
+| `SnapDiff::ComparisonResult` | Result value object: `different?`, region, metadata (ex `Difference`) |
+| `SnapDiff::Region` | Bounding box value object — `from_edge_coordinates`, `to_edge_coordinates` |
+| `SnapDiff::DSL` | `screenshot`, `assert_matches_screenshot`, `capture_screenshot`, groups/sections |
+| `SnapDiff::Minitest::Assertions` | Minitest wiring (`snap_diff/integrations/minitest`) |
+| `SnapDiff::Error` | Base class for every error this gem raises |
+| `SnapDiff::ExpectationNotMet` | A screenshot did not match its baseline |
+| `SnapDiff::UnstableImage` | No stable capture within `stability_time_limit` / `wait` |
+| `SnapDiff::WindowSizeMismatchError` | Browser window is not the configured `window_size` |
+| `SnapDiff::Driver` | Mixin with the shared driver defaults (`require "snap_diff/driver"`) |
+| `SnapDiff::Drivers` | Driver factory and registry — `.for`, `.loaded`, `.available` |
+| `SnapDiff::Reporting` | Process-global reporter lifecycle (`require "snap_diff/reporting"`) |
+| `SnapDiff::Reporters::HTML` | The interactive HTML report (`require "snap_diff/reporters/html"`) |
+| `SnapDiff::Reporters::Default` | Builds the annotated diff images and the failure message |
+| `SnapDiff.session` | The per-test assertion registry (fiber-local) |
+| `SnapDiff.reset` | Ends a test: notifies reporters, clears the session |
+| `SnapDiff.pending_screenshots_message` | Skip message when a new screenshot has no baseline |
+| `SnapDiff::Capture::Viewport` | Per-capture viewport check seam (`require "snap_diff/capture/viewport"`) |
+| `SnapDiff.serve` | Point Capybara at a static site directory (`require "snap_diff/static"`) |
+
+## Compare two images without a browser
+
+Works on anything on disk — rendered PDFs, generated charts, CI artifacts:
+
+```ruby
+require "snap_diff"
+
+result = SnapDiff.compare("baseline.png", "current.png")
+result.quick_equal?   # => true when byte-identical / pixel-identical
+result.different?     # => true when the difference exceeds the configured thresholds
+result.difference     # => SnapDiff::ComparisonResult with region and metadata
+
+# Per-call option overrides, merged over SnapDiff.config.default_options
+SnapDiff.compare("baseline.png", "current.png", tolerance: 0.5)
+```
+
+Note the argument order: baseline first, current second ("compare baseline against current").
+
+## Custom reporters
+
+A reporter is any object answering `record(assertions)`, `finalize`, and `summary`. Register it
+once, for the rest of the process:
+
+```ruby
+require "snap_diff/reporting"
+
+class SlackReporter
+  def initialize = @failures = []
+
+  # Called once per finished test, with that test's assertions.
+  def record(assertions)
+    assertions.each do |assertion|
+      next unless assertion.compare&.difference&.different?
+      @failures << assertion.name
+    end
+  end
+
+  # Called once at end of suite.
+  def finalize
+    post_to_slack(@failures) unless @failures.empty?
+  end
+
+  # Printed to stdout after finalize. Return nil to print nothing.
+  def summary
+    @failures.empty? ? nil : "#{@failures.size} screenshot(s) changed"
+  end
+end
+
+SnapDiff::Reporting.register(SlackReporter.new)
+```
+
+`register` appends under a mutex, so concurrent registrations cannot lose one — prefer it over
+mutating `SnapDiff::Reporting.reporters` directly.
+
+Do implement `summary`. `finalize!` calls it unconditionally; a reporter without it is finalized
+and then warned about (`[snap_diff] Reporter … failed (NoMethodError: undefined method 'summary')`).
+
+A reporter that raises is warned about and skipped — the other reporters still run.
+
+The bundled HTML report is just a pre-registered reporter of this kind:
+
+```ruby
+require "snap_diff/reporters/html"   # registers SnapDiff::Reporters::HTML itself
+```
+
+### Frameworks other than Minitest/RSpec/Cucumber
+
+The three bundled integrations call the lifecycle for you. Wiring another framework means calling
+three things:
+
+```ruby
+require "snap_diff/dsl"        # SnapDiff::DSL, BrowserHelpers, the session accessors
+require "snap_diff/reporting"  # SnapDiff::Reporting
+
+# before each test
+SnapDiff::BrowserHelpers.resize_window_if_needed
+
+# after each test
+SnapDiff.session.verify                  # raises SnapDiff::ExpectationNotMet on a mismatch
+msg = SnapDiff.pending_screenshots_message  # non-nil => skip the test with this message
+SnapDiff.reset                           # always: notifies reporters, clears the session
+
+# after the suite
+SnapDiff::Reporting.finalize!
+```
+
+## Custom drivers
+
+A driver is a plain object that does the image work. Include `SnapDiff::Driver` for the shared
+defaults, then implement the operations the comparison engine calls:
+
+```ruby
+require "snap_diff/driver"
+
+class MyDriver
+  include SnapDiff::Driver
+
+  # Provided by the mixin, override only if your image objects differ:
+  #   width_for(image), height_for(image), dimension(image),
+  #   image_area_size(image), same_dimension?(comparison), supports?(feature)
+
+  # Implement (this is what both bundled drivers implement):
+  #   from_file(path), load_images(base_path, new_path), save_image_to(image, path)
+  #   same_pixels?(comparison), find_difference_region(comparison)
+  #   crop(region, image), resize_image_to(image, w, h)
+  #   add_black_box(image, region), draw_rectangles(images, region, ...)
+end
+```
+
+`supports?(feature)` is just `respond_to?(feature)` — the engine uses it to skip optional
+operations. The VIPS driver additionally implements `filter_image_with_median`, `merge`,
+`highlight_mask` and `difference_level`; ChunkyPNG does not, and `supports?` is how that is
+detected. Look at `lib/snap_diff/drivers/chunky_png_driver.rb` for the smaller of the two
+reference implementations.
+
+### Registration
+
+`SnapDiff::Drivers.loaded` is the registry: a mutable `name => driver class` hash. Register by
+writing into it, then select the driver by that name:
+
+```ruby
+SnapDiff::Drivers.loaded[:my_driver] = MyDriver
+
+SnapDiff.config.driver = :my_driver          # globally
+screenshot "index", driver: :my_driver       # or per screenshot
+```
+
+Resolution goes through `SnapDiff::Drivers.for`, which looks the symbol up in `loaded` and calls
+`.new` on the class — **your driver class must be instantiable with no arguments**. A pre-built
+instance skips the registry entirely:
+
+```ruby
+screenshot "index", driver: MyDriver.new     # any non-Symbol is used as-is
+```
+
+`SnapDiff::Drivers.available` is the *detected* list (`[:vips, :chunky_png]`, filled at load time
+by probing for the `ruby-vips` and `chunky_png` gems). It is a read-only view of detection, not
+the registry — registering a custom driver does not add it there, and `driver: :auto` picks
+`available.first`. Custom drivers must always be named explicitly.
+
+## Related
+
+- [Framework Setup](framework-setup.md) — the same three integrations under their legacy names
+- [Configuration Reference](configuration.md) — what every option does
+- [Image Processing Drivers](drivers.md) — VIPS vs ChunkyPNG, perceptual threshold
+- [Web UI & Custom Reporters](reporters.md) — the HTML report in detail
+- [Architecture](architecture.md) — how the pieces fit together internally
+- [UPGRADING.md](UPGRADING.md) — migrating an existing suite off the legacy names
+
+[← Back to README](../README.md)

data/docs/thread_safety.md

@@ -100,9 +100,10 @@ Do not:
 
 Runtime state is thread-local (above), but *loading* the gem is a separate
 concern. The require graph is deliberately acyclic: `lib/snap_diff/*` units
-depend only on the legacy-config leaf
-(`capybara/screenshot/diff/config_legacy`) and specific sibling units, the
-umbrella files depend on the units, and nothing requires back up the chain.
+depend only on the config-storage leaf (`snap_diff/config`, which the legacy
+view `capybara/screenshot/diff/config_legacy` requires) and specific sibling
+units, the umbrella files depend on the units, and nothing requires back up
+the chain.
 
 Eager mutual requires between entry points are forbidden, even guarded ones:
 per-thread "loading" flags cannot serialize Ruby's process-global per-file

data/lib/capybara/screenshot/diff/config_legacy.rb

@@ -1,80 +1,44 @@
 # frozen_string_literal: true
 
-# Legacy Capybara::Screenshot / Capybara::Screenshot::Diff mattr_accessor
-# config module, extracted out of capybara_screenshot_diff.rb so it is a
-# leaf: it can be required by both capybara_screenshot_diff.rb (the old
-# umbrella entry point) and snap_diff.rb (the canonical entry point)
-# without either of *those* requiring the other back.
+# Legacy Capybara::Screenshot / Capybara::Screenshot::Diff config surface.
 #
-# Why this file has to exist at all: several lib/snap_diff/* units
-# (Screenshoter, SnapManager, Utils) are referenced here at class-body
-# eval time (mattr_accessor default blocks, AVAILABLE_DRIVERS) rather
-# than at call time, so they must be real, already-loaded classes before
-# this module body runs. Since v2 step 6 they are pulled in and referenced
-# under their canonical SnapDiff names: the old-name aliases are lazy
-# const_missing shims that emit deprecation warnings, and the gem's own
-# code must stay warning-free. Everything else this module references
-# (Os, Comparison) is referenced only inside method bodies, resolved
-# lazily at call time by whichever entry point loaded them.
-require "snap_diff/screenshoter"
-require "snap_diff/snap_manager"
+# Since ADR-008 step 1 the storage lives in SnapDiff::Config -- the require
+# leaf of the config graph (see its own header) -- and since step 7b the
+# DERIVED values (active?, screenshot_area, default_options) live there
+# too. snap_diff/config.rb also generates the old accessor names as thin
+# delegators from SnapDiff::Config::MAPPING, so nothing but forwarders is
+# left here. The v1 surface (Capybara::Screenshot.window_size = ...,
+# Diff.configure { ... }, Diff.compare) keeps working unchanged: one
+# storage, two views.
+#
+# Load order: requiring snap_diff/config first also eagerly evaluates the
+# require-time defaults (ENV["CI"] for fail_if_new, Rails.root/pwd for
+# root) at this same load moment, exactly when the old mattr_accessor
+# default blocks used to run. snap_diff/config never requires back here,
+# so the graph stays acyclic.
+require "snap_diff/config"
+# AVAILABLE_DRIVERS below is evaluated at class-body eval time, so Utils
+# must be a real, already-loaded module before this module body runs.
 require "snap_diff/utils"
 
 module Capybara
   module Screenshot
-    mattr_accessor :add_driver_path
-    mattr_accessor :add_os_path
-    mattr_accessor(:blur_active_element) { true }
-    mattr_accessor :enabled
-    mattr_accessor(:hide_caret) { true }
-    mattr_accessor :disable_animations
-    mattr_reader(:root) { (defined?(Rails) && defined?(Rails.root) && Rails.root) || Pathname(".").expand_path }
-    mattr_accessor :stability_time_limit
-    mattr_accessor :window_size
-    mattr_accessor(:save_path) { "doc/screenshots" }
-    mattr_accessor(:use_lfs)
-    mattr_accessor(:screenshot_format) { "png" }
-    mattr_accessor(:capybara_screenshot_options) { {} }
-
     class << self
-      def root=(path)
-        @@root = Pathname(path).expand_path
-      end
-
       def active?
-        enabled || (enabled.nil? && Diff.enabled)
+        SnapDiff.config.active?
       end
 
       def screenshot_area
-        parts = [Screenshot.save_path]
-        parts << SnapDiff::Os.name if Screenshot.add_os_path
-        parts << Capybara.current_driver.to_s if Screenshot.add_driver_path
-        File.join(*parts)
+        SnapDiff.config.screenshot_area
       end
 
       def screenshot_area_abs
-        root / screenshot_area
+        SnapDiff.config.screenshot_area_abs
       end
     end
 
     # Module to track screenshot changes
     module Diff
-      mattr_accessor(:delayed) { true }
-      mattr_accessor :area_size_limit
-      mattr_accessor(:fail_if_new) { !ENV["CI"].nil? && !ENV["CI"].empty? }
-      mattr_accessor(:pending_if_new) { false }
-      mattr_accessor(:fail_on_difference) { true }
-      mattr_accessor :color_distance_limit
-      mattr_accessor(:enabled) { true }
-      mattr_accessor :shift_distance_limit
-      mattr_accessor :skip_area
-      mattr_accessor(:driver) { :auto }
-      mattr_accessor :tolerance
-      mattr_accessor :perceptual_threshold
-
-      mattr_accessor(:screenshoter) { SnapDiff::Screenshoter }
-      mattr_accessor(:manager) { SnapDiff::SnapManager }
-
       AVAILABLE_DRIVERS = SnapDiff::Utils.detect_available_drivers.freeze
 
       # Configure screenshot and diff settings in one block.
@@ -85,28 +49,18 @@ module Capybara
       #     diff.driver = :vips
       #     diff.tolerance = 0.0005
       #   end
+      # The bare `yield` (rather than an explicit &block) keeps this
+      # method's published arity byte-identical to what it always had.
       def self.configure
-        yield Screenshot, self
+        SnapDiff.start { |screenshot, diff| yield screenshot, diff }
       end
 
       def self.compare(baseline_path, current_path, **options)
-        SnapDiff::Comparison.new(current_path, baseline_path, default_options.merge(options))
+        SnapDiff.compare(baseline_path, current_path, **options)
       end
 
       def self.default_options
-        {
-          area_size_limit: area_size_limit,
-          color_distance_limit: color_distance_limit,
-          driver: driver,
-          screenshot_format: Screenshot.screenshot_format,
-          capybara_screenshot_options: Screenshot.capybara_screenshot_options,
-          perceptual_threshold: perceptual_threshold,
-          shift_distance_limit: shift_distance_limit,
-          skip_area: skip_area,
-          stability_time_limit: Screenshot.stability_time_limit,
-          tolerance: tolerance || ((driver == :vips) ? 0.001 : nil),
-          wait: Capybara.default_max_wait_time
-        }
+        SnapDiff.config.default_options
       end
     end
   end