snap_diff-capybara 2.0.0.beta1 → 2.0.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a063da3ec86978a0e66baaa0c64692c40f18db15ce66b40cab390df9a90be5a1
-  data.tar.gz: c34b6fe46a10353ed94d738832cd9dafca06ef0f7a53b2c678408010198f58d2
+  metadata.gz: 480337577271341982e3f8eef57cf123003092ba90833e4b4a497676920c0466
+  data.tar.gz: e844a383454976b32c46059e4593dd0c472133d22eac3e1d531b6bca35935f6e
 SHA512:
-  metadata.gz: '0828945cb79fbf911727deeac0b4cf868f34b5787c37720bc216a6d893115a2d9486a43284cf3f3467834951d1ae438f969a7ea5e1dcdd8ae387fb2cf9f263b9'
-  data.tar.gz: 3fc96895702aac83fa636bf8cfd1ac73953b4049b2629104ccbde592af150f3829c3eda7e73e8912b0342793cbf3e45d07056ffffb68c4f3b5594758406cd932
+  metadata.gz: b44e77a9e696cd8f326655ba6bd19d5b4275f7f2b86ea0961c913dc30d1ecb6eb0806fa89340359357049bf70c2c015ccaf4d22fc9f6d733c84788db358435f4
+  data.tar.gz: 322a1b64abd4bc2234dea9f6ffcda02f7dac5e9e09c640f1f6decc588b0715953add332a08a61e685bec944358b80b999f77a17b5524663e6c107f771ad7a2fb

data/CHANGELOG.md

@@ -5,6 +5,62 @@ 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).
 
+## [v2.0.0.beta2] - 2026-08-23
+
+Third prerelease of the 2.0 opt-in experiment. This one finishes the namespace
+move: `SnapDiff` no longer depends on the namespaces it deprecates. Legacy names
+keep working exactly as before — see the v2.0.0.alpha1 notes below for the
+opt-in and silencing basics, and [docs/snapdiff.md](docs/snapdiff.md) for the
+canonical API.
+
+### Changed
+- **Everything canonical now lives in `SnapDiff`** — configuration storage
+  (`SnapDiff::Config`, one storage behind every settings surface), error classes
+  (`SnapDiff::Error`, `ExpectationNotMet`, `UnstableImage`,
+  `WindowSizeMismatchError`), `SnapDiff::Region`, `SnapDiff::Reporters::Default`,
+  the driver registry (`SnapDiff::Drivers.loaded`/`.available`), the per-test
+  session (`SnapDiff.session`), and reporter registration
+  (`SnapDiff::Reporting.register`, mutex-guarded). Old constants remain
+  same-object aliases; `rescue`, `is_a?`, and `defined?` on them are unchanged
+  ([#224](https://github.com/snap-diff/snap_diff-capybara/pull/224)–[#230](https://github.com/snap-diff/snap_diff-capybara/pull/230))
+- **Error class names in failure output** now print as `SnapDiff::…` (the class
+  objects are identical, so `rescue CapybaraScreenshotDiff::ExpectationNotMet`
+  still catches them — only the printed name differs). CI jobs that
+  string-match on the old class name in output need updating.
+- The images-holder struct is now `SnapDiff::Comparison::Images`, ending the
+  two-classes-one-name collision with the comparator
+  ([#227](https://github.com/snap-diff/snap_diff-capybara/pull/227))
+
+### Added
+- **Deprecation warnings now name your call site** — `(called from
+  your_file.rb:42)`, so migration is warning-driven instead of grep-driven
+  ([#222](https://github.com/snap-diff/snap_diff-capybara/pull/222))
+- **Dual-install guard** — installing both `capybara-screenshot-diff` and
+  `snap_diff-capybara` now raises a clear error instead of silently loading
+  files from whichever gem activated first
+  ([#222](https://github.com/snap-diff/snap_diff-capybara/pull/222))
+- **[docs/snapdiff.md](docs/snapdiff.md)** — the SnapDiff-native guide: quick
+  start for all four integrations, configuration, custom drivers and reporters,
+  standalone comparison ([#231](https://github.com/snap-diff/snap_diff-capybara/pull/231))
+
+### Removed
+- The unused `anchor:` keyword on the internal viewport seam; v3's
+  scroll-preservation work will design its real contract
+  ([#229](https://github.com/snap-diff/snap_diff-capybara/pull/229))
+
+### Internal
+- A test now mechanically enforces that the legacy namespace trees contain only
+  requires, aliases, and one-line forwarders — no real logic — so removing them
+  in 3.0 is a deletion, not a refactor
+  ([#229](https://github.com/snap-diff/snap_diff-capybara/pull/229),
+  [#230](https://github.com/snap-diff/snap_diff-capybara/pull/230))
+- Release workflow is idempotent on re-run; config default-eval timing is
+  pinned by guards across every entry point
+  ([#222](https://github.com/snap-diff/snap_diff-capybara/pull/222),
+  [#223](https://github.com/snap-diff/snap_diff-capybara/pull/223))
+
+---
+
 ## [v2.0.0.beta1] - 2026-08-22
 
 Second prerelease of the 2.0 opt-in experiment (see the v2.0.0.alpha1 notes

data/docs/UPGRADING.md

@@ -6,10 +6,14 @@
 
 Version 2.0 introduces a new canonical namespace (`SnapDiff`) for cleaner, more discoverable code. The public DSL remains unchanged — your existing `screenshot` and `assert_matches_screenshot` calls work without modification. This guide covers the optional migration path for settings and the new namespace.
 
-**Status:** `2.0.0.alpha1` is an opt-in prerelease. RubyGems never installs prereleases by default resolution — normal `bundle update` keeps you on the 1.x line. The final 2.0.0 ships only after adopter feedback; please report anything surprising on [#166](https://github.com/snap-diff/snap_diff-capybara/issues/166).
+**Status:** `2.0.0.beta2` is an opt-in prerelease. RubyGems never installs prereleases by default resolution — normal `bundle update` keeps you on the 1.x line. The final 2.0.0 ships only after adopter feedback; please report anything surprising on [#166](https://github.com/snap-diff/snap_diff-capybara/issues/166).
 
 **Estimated upgrade time:** 5–15 minutes (most users need only the Gemfile pin)
 
+**Writing new code rather than migrating?** Skip this guide and read
+[SnapDiff — the canonical API](snapdiff.md): the same setup, configuration, and extension points
+with canonical names only, no legacy shapes to unlearn.
+
 **Breaking changes:** None for the DSL; deprecation warnings if you reference legacy constants (suppressible), plus two known alpha caveats (see below)
 
 ---
@@ -18,7 +22,7 @@ Version 2.0 introduces a new canonical namespace (`SnapDiff`) for cleaner, more
 
 ```ruby
 # In your Gemfile — the exact prerelease version is required to opt in
-gem "capybara-screenshot-diff", "2.0.0.alpha1"
+gem "capybara-screenshot-diff", "2.0.0.beta2" # or the latest 2.0.0 prerelease
 ```
 
 ```bash
@@ -43,6 +47,17 @@ The implementation now lives in `lib/snap_diff/` under the `SnapDiff` namespace.
 | `Capybara::Screenshot::Diff::Drivers::BaseDriver` | `SnapDiff::Driver` (now a mixin — see below) |
 | `CapybaraScreenshotDiff::SnapManager` / `::Snap` | `SnapDiff::SnapManager` / `SnapDiff::Snap` |
 | `CapybaraScreenshotDiff::RED_RGBA` / `::ORANGE_RGBA` | `SnapDiff::RED_RGBA` / `SnapDiff::ORANGE_RGBA` |
+| `CapybaraScreenshotDiff::Minitest::Assertions` | `SnapDiff::Minitest::Assertions` |
+| `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"` |
+| `require "capybara_screenshot_diff/reporters/html"` | `require "snap_diff/reporters/html"` |
+| `CapybaraScreenshotDiff.serve` (`…/static`) | `SnapDiff.serve` (`require "snap_diff/static"`) |
+| `CapybaraScreenshotDiff.reporters <<` | `SnapDiff::Reporting.register` |
+| `CapybaraScreenshotDiff.finalize_reporters!` | `SnapDiff::Reporting.finalize!` |
+
+Note the integration require paths gain an `integrations/` segment — `require "snap_diff/minitest"`
+is a `LoadError`.
 
 **What stays the same:**
 - `screenshot(name)` — still works
@@ -218,7 +233,7 @@ All settings and baselines are compatible with v1.x. Simply pin your Gemfile bac
 
 ### Summary Checklist
 
-- [ ] Pin `gem "capybara-screenshot-diff", "2.0.0.alpha1"` in your Gemfile
+- [ ] Pin `gem "capybara-screenshot-diff", "2.0.0.beta2"` (or the latest 2.0.0 prerelease) in your Gemfile
 - [ ] Run `bundle install`
 - [ ] Run your test suite to verify no regressions
 - [ ] (Optional) Migrate config to the `SnapDiff` namespace
@@ -679,7 +694,7 @@ All screenshot baselines are compatible — no data loss.
 
 ## Need Help?
 
-- **Documentation:** [README.md](README.md)
+- **Documentation:** [README.md](../README.md)
 - **Changelog:** [CHANGELOG.md](CHANGELOG.md)
 - **Issues:** [GitHub Issues](https://github.com/snap-diff/snap_diff-capybara/issues)
 - **DeepWiki:** [Code Documentation](https://deepwiki.com/snap-diff/snap_diff-capybara)

data/docs/architecture.md

@@ -2,7 +2,7 @@
 
 This document describes the internal architecture of `capybara-screenshot-diff` — how screenshots are captured, compared, and reported, and how the components fit together.
 
-Since the v2 namespace move (ADR-004), the implementation lives in `lib/snap_diff/` under the `SnapDiff` namespace. The old file paths (`lib/capybara/screenshot/diff/`, `lib/capybara_screenshot_diff/`) remain as thin forwarders, and the old constants resolve to the same objects via `lib/snap_diff/legacy_shims.rb` with a one-time deprecation warning. Class names below use the canonical `SnapDiff::` names, with legacy names noted where they differ.
+Since the v2 namespace move (ADR-004), the implementation lives in `lib/snap_diff/` under the `SnapDiff` namespace. The old file paths (`lib/capybara/screenshot/diff/`, `lib/capybara_screenshot_diff/`) remain as thin forwarders, and the old constants resolve to the same objects via `lib/snap_diff/legacy_shims.rb` with a one-time deprecation warning. Class names below use the canonical `SnapDiff::` names, with legacy names noted where they differ. For the user-facing view of the same surface, see [SnapDiff — the canonical API](snapdiff.md).
 
 ## Overview
 
@@ -14,8 +14,8 @@ Since the v2 namespace move (ADR-004), the implementation lives in `lib/snap_dif
                │                              │
                ▼                              ▼
 ┌──────────────────────────┐    ┌──────────────────────────┐
-│  CapybaraScreenshotDiff   │    │  CapybaraScreenshotDiff   │
-│  ::DSL (screenshot, etc)  │    │  ::AssertionRegistry       │
+│  SnapDiff::DSL            │    │  SnapDiff::AssertionRegistry│
+│  (screenshot, etc)        │    │  (SnapDiff.session)        │
 └──────────────┬───────────┘    └──────────────┬───────────┘
                │                               │
                ▼                               ▼
@@ -127,6 +127,8 @@ Drivers abstract image processing operations. Shared default behavior lives in t
 
 **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.
 
+**Registry (ADR-008 step 5b):** `SnapDiff::Drivers.loaded` is the canonical driver-class cache — a `name => class` hash filled lazily by `Utils.find_driver_class_for`, and the registration point for custom drivers (the legacy `Capybara::Screenshot::Diff::LOADED_DRIVERS` is an eager same-object alias, so registrations through either land in the same hash). `SnapDiff::Drivers.available` is the canonical read API for the detected list; the value itself still lives on `Capybara::Screenshot::Diff::AVAILABLE_DRIVERS`, which stays the published stubbing point. `SnapDiff::Drivers.for` resolves an options hash to a driver instance. See [Custom drivers](snapdiff.md#custom-drivers).
+
 ### 6. Difference Region Detection
 
 **VipsDriver** uses a **difference mask** approach:
@@ -158,7 +160,7 @@ Drivers abstract image processing operations. Shared default behavior lives in t
 
 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.rb`, `lib/snap_diff/reporters/html.rb`)
+### 9. Reporters (`lib/snap_diff/reporters/default.rb`, `lib/snap_diff/reporters/html.rb`)
 
 **Default reporter:** Generates annotated diff images:
 - `image.diff.png` — new screenshot with diff region outlined in red
@@ -173,7 +175,7 @@ Handles baseline retrieval from git. Uses `git show HEAD:<path>` to extract the
 - Keyboard navigation and shortcuts
 - Responsive layout for mobile
 
-**Custom reporters:** Implement `record(assertions)` and `finalize` methods, then add to `CapybaraScreenshotDiff.reporters`. The process-global reporter lifecycle (registration, notification, finalization) is owned by `SnapDiff::Reporting` (`lib/snap_diff/reporting.rb`); `CapybaraScreenshotDiff.reporters` / `.finalize_reporters!` are thin public shims over it.
+**Custom reporters:** Implement `record(assertions)`, `finalize` and `summary`, then register via `SnapDiff::Reporting.register(reporter)` — the canonical way in, because the append happens under the mutex. The process-global reporter lifecycle (registration, notification, finalization) is owned by `SnapDiff::Reporting` (`lib/snap_diff/reporting.rb`); `CapybaraScreenshotDiff.reporters` / `.finalize_reporters!` are thin public shims over it, and `reporters` stays a mutable array for compatibility (appending directly still works, it just skips the lock). See [Custom reporters](snapdiff.md#custom-reporters).
 
 ### 10. Assertion Lifecycle
 
@@ -189,16 +191,19 @@ Test begins
     │         └─ 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
+    │    ├─ SnapDiff.session.verify
+    │    │    ├─ iterates the fiber-local assertions
+    │    │    ├─ calls validate on each
+    │    │    └─ raises SnapDiff::ExpectationNotMet if any differed
+    │    │
+    │    └─ SnapDiff.reset (always, in an ensure)
+    │         ├─ SnapDiff::Reporting.notify — mutex-protected reporter snapshot
+    │         └─ clears the session
     │
-    └─ at_exit:
-         └─ CapybaraScreenshotDiff.finalize_reporters!
+    └─ end of suite (Minitest.after_run / RSpec after(:suite) / Cucumber AfterAll):
+         └─ SnapDiff::Reporting.finalize!
               ├─ Generates HTML report (if reporter registered)
-              └─ Prints summary
+              └─ Prints each reporter's summary
 ```
 
 ### 11. Thread Safety
@@ -209,12 +214,16 @@ Test begins
 | 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 |
+| Global configuration | One process-wide `SnapDiff::Config` instance — 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` (pure Ruby implementation in `lib/capybara/screenshot/diff/config_legacy.rb`, deliberately kept at the old path as the single source of truth for settings storage) and is organized into two namespaces:
+Since ADR-008 step 1 the storage ownership is inverted from the original v2 consolidation: **`SnapDiff::Config` (`lib/snap_diff/config.rb`) IS the storage** — one eagerly-created instance, reachable as `SnapDiff.config`, holding every setting as a plain `attr_accessor`. It is the leaf of the config require graph and requires nothing that leads back to either entry point.
+
+The legacy `Capybara::Screenshot.*` / `Capybara::Screenshot::Diff.*` accessors are thin delegators generated from `Config::MAPPING` (both singleton and instance methods, matching what `mattr_accessor` used to define) that forward to that one object. One storage, two views — a write through either surface is visible through the other structurally, not by synchronization. `lib/capybara/screenshot/diff/config_legacy.rb` remains at the old path, but it now installs the delegating surface rather than owning the state.
+
+The two legacy views are organized into two namespaces:
 
 **`Capybara::Screenshot`** — capture settings:
 - `window_size`, `stability_time_limit`, `blur_active_element`, `hide_caret`, `disable_animations`
@@ -225,7 +234,11 @@ Configuration uses Ruby's `mattr_accessor` (pure Ruby implementation in `lib/cap
 - `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. Since v2, `SnapDiff::Config` (`lib/snap_diff/config.rb`) additionally exposes all 27 settings as one flat object via `SnapDiff.config` / `SnapDiff.configure { |config| ... }` — it holds no state of its own, every accessor forwards to the legacy `mattr_accessor` storage, so both views stay consistent.
+The canonical way in is `SnapDiff.configure { |config| ... }` (all 27 settings flat on one object). `SnapDiff.start` and `Capybara::Screenshot::Diff.configure` are the two-holder block shape over the same storage — since ADR-008 step 7b, `Diff.configure` forwards to `SnapDiff.start` rather than the other way round.
+
+`Config` also owns the derived values that used to live on the legacy modules: `active?` (ex `Capybara::Screenshot.active?`), `screenshot_area` / `screenshot_area_abs`, and `default_options` (ex `Capybara::Screenshot::Diff.default_options`, the option hash handed to `SnapDiff::Comparison`). The legacy module methods one-line forward here.
+
+**Default timing contract:** every default is evaluated once, in `Config#initialize`, which runs at require time of `config.rb` — the same load moment the old `mattr_accessor` default blocks evaluated at. `fail_if_new` (from `ENV["CI"]`) and `root` (from `Rails.root`) must never become lazy read-time defaults. The one deliberately live value is `default_options[:wait]`, a method-body read of `Capybara.default_max_wait_time`.
 
 ## File Layout
 
@@ -234,7 +247,9 @@ lib/
   snap_diff.rb                                 # SnapDiff module: compare/start/configure/config
   snap_diff/                                   # Canonical implementation (v2)
     dsl.rb                                     # screenshot(), screenshot_group(), etc.
-    config.rb                                  # SnapDiff::Config — flat view over all 27 settings
+    config.rb                                  # SnapDiff::Config — THE storage for all 27 settings
+    errors.rb                                  # Error / ExpectationNotMet / UnstableImage / WindowSizeMismatchError
+    region.rb                                  # SnapDiff::Region — bounding box (+ eager top-level ::Region alias)
     deprecation.rb                             # Warn-once-per-constant machinery
     legacy_shims.rb                            # const_missing forwarders for the old namespaces
     comparison.rb                              # Layered comparison engine (ex-ImageCompare)
@@ -272,18 +287,19 @@ lib/
       minitest.rb                              # Minitest assertions integration
       rspec.rb                                 # RSpec matcher integration
       cucumber.rb                              # Cucumber World integration
-  capybara_screenshot_diff.rb                  # Umbrella entry point + error classes
+  capybara_screenshot_diff.rb                  # Umbrella entry point + eager error-class aliases
   capybara_screenshot_diff/                    # Legacy paths — mostly thin forwarders
     minitest.rb / rspec.rb / cucumber.rb       # Legacy entry points (load the full gem)
     screenshot_assertion.rb                    # CapybaraScreenshotDiff session/reporter shims
     ...                                        # Everything else forwards to snap_diff/
   capybara/screenshot/diff.rb                  # Convenience require (loads minitest)
   capybara/screenshot/diff/
-    config_legacy.rb                           # mattr_accessor settings storage (source of truth)
-    region.rb                                  # Bounding box region value object (top-level Region)
-    reporters/default.rb                       # Default annotated-image reporter
+    config_legacy.rb                           # Legacy accessor surface, delegating to SnapDiff::Config
+    region.rb                                  # Forwarder to snap_diff/region.rb
     version.rb                                 # Capybara::Screenshot::Diff::VERSION (gemspec reads it)
     ...                                        # Everything else forwards to snap_diff/
 ```
 
-The legacy `Capybara::Screenshot::Diff::*` and `CapybaraScreenshotDiff::*` constants resolve lazily via `snap_diff/legacy_shims.rb` (`const_missing`), pointing at the same objects with a one-time deprecation warning. See [UPGRADING.md](UPGRADING.md) for the migration guide.
+Most legacy `Capybara::Screenshot::Diff::*` and `CapybaraScreenshotDiff::*` constants resolve lazily via `snap_diff/legacy_shims.rb` (`const_missing`), pointing at the same objects with a one-time deprecation warning. The error classes are the deliberate exception: they are **eager** same-object aliases, because `rescue` clauses and `defined?` / `const_defined?` feature detection in adopter code must keep behaving exactly as before (`const_defined?` never triggers `const_missing`). Same for `LOADED_DRIVERS`, pinned as an eager alias of `SnapDiff::Drivers.loaded` so user registrations through the old constant are not silently dropped.
+
+See [SnapDiff — the canonical API](snapdiff.md) for the canonical surface, and [UPGRADING.md](UPGRADING.md) for the migration guide.

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)