snap_diff-capybara 2.0.0.alpha1 → 2.0.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 544c2e3414e9b616291b0cd0e843e72d1a41652017fc2b966926665285aaf49a
-  data.tar.gz: b2a226430eaeab196e297efc9c476eb4cf0d192334d1503ba29f330fb9bd81ed
+  metadata.gz: 480337577271341982e3f8eef57cf123003092ba90833e4b4a497676920c0466
+  data.tar.gz: e844a383454976b32c46059e4593dd0c472133d22eac3e1d531b6bca35935f6e
 SHA512:
-  metadata.gz: 91c3e8fd69a3f7e981f77ef8425ccc231e2b9617868f5278bb74c6865c82d59828ab708f7ecf7e57db0f891338f20704c277e8865e8f8444762ffc1b3929748d
-  data.tar.gz: 2651d17eaceca6a6b8f5c94136e8e221639ec5cf70d70d9178d9d30a630f5014e5eb240ace31233a45a456cf3918d0e70b324c998e2b4ab3531bac7d7d21ffe0
+  metadata.gz: b44e77a9e696cd8f326655ba6bd19d5b4275f7f2b86ea0961c913dc30d1ecb6eb0806fa89340359357049bf70c2c015ccaf4d22fc9f6d733c84788db358435f4
+  data.tar.gz: 322a1b64abd4bc2234dea9f6ffcda02f7dac5e9e09c640f1f6decc588b0715953add332a08a61e685bec944358b80b999f77a17b5524663e6c107f771ad7a2fb

data/CHANGELOG.md

@@ -5,6 +5,85 @@ 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
+below for the namespace change, deprecation warnings, and caveats). Final
+2.0.0 remains gated on adopter feedback — [#166](https://github.com/snap-diff/snap_diff-capybara/issues/166).
+
+### Added
+- **Dual gem names** — releases now also publish as
+  [`snap_diff-capybara`](https://rubygems.org/gems/snap_diff-capybara):
+  identical content and versions under the forward-looking name matching this
+  repository (the alpha1 mirror was backfilled). Install either, not both.
+- **Migration guide** — [docs/UPGRADING.md](docs/UPGRADING.md) covers the v2
+  namespace move, every renamed constant, silencing, and the alpha caveats
+  ([#220](https://github.com/snap-diff/snap_diff-capybara/pull/220))
+
+### Internal
+- Test suite exercises the canonical `SnapDiff` names; legacy names remain
+  covered by dedicated forwarding/deprecation tests, and a strict warning
+  guard now fails the suite on any accidental legacy-name use
+  ([#221](https://github.com/snap-diff/snap_diff-capybara/pull/221))
+
+---
+
 ## [v2.0.0.alpha1] - 2026-08-22
 
 **Opt-in experiment prerelease.** RubyGems never installs prereleases by default

data/docs/UPGRADING.md

@@ -1,5 +1,247 @@
 # Upgrading
 
+## Upgrading to v2.0 (alpha)
+
+### Overview
+
+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.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)
+
+---
+
+### The Short Version (Most Users)
+
+```ruby
+# In your Gemfile — the exact prerelease version is required to opt in
+gem "capybara-screenshot-diff", "2.0.0.beta2" # or the latest 2.0.0 prerelease
+```
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+**That's it.** Your existing code works unchanged. The old namespaces (`Capybara::Screenshot::Diff`, `CapybaraScreenshotDiff`) are shimmed with deprecation warnings; the new one (`SnapDiff`) is available if you want to modernize.
+
+---
+
+### What Changed
+
+#### 1. New Canonical Namespace: `SnapDiff`
+
+The implementation now lives in `lib/snap_diff/` under the `SnapDiff` namespace. Every legacy constant still resolves — lazily, to the *same object* — but emits a one-time-per-constant deprecation warning. The main renames:
+
+| Legacy name | v2 canonical name |
+|-------------|-------------------|
+| `Capybara::Screenshot::Diff::ImageCompare` | `SnapDiff::Comparison` |
+| `Capybara::Screenshot::Diff::Difference` | `SnapDiff::ComparisonResult` |
+| `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
+- `assert_matches_screenshot(name)` — still works, still the recommended form
+- `capture_screenshot(name)` — still works
+- All `compare: false/true` flags and overrides work identically
+
+**What's new (optional):**
+
+```ruby
+# Old (still works; constant access now warns once per process)
+Capybara::Screenshot::Diff.compare("baseline.png", "current.png")
+Capybara::Screenshot::Diff.configure { |screenshot, diff| ... }
+
+# New (recommended for new code)
+SnapDiff.compare("baseline.png", "current.png")
+SnapDiff.start { |screenshot, diff| ... }         # same shape as old configure
+SnapDiff.configure { |config| ... }               # consolidated config object
+```
+
+#### 2. Consolidated Configuration: `SnapDiff.config`
+
+Instead of scattering settings across `Capybara::Screenshot` and `Capybara::Screenshot::Diff`, v2.0 offers a single `SnapDiff::Config` object. Both the old and new paths read and write the same underlying storage — writes through either are visible through the other.
+
+**The DSL never changes.** `screenshot` and `assert_matches_screenshot` work exactly as before.
+
+---
+
+### Settings Migration Table
+
+The most commonly-used settings and how to update them:
+
+| Setting | v1.x (still works in v2) | v2.0 (recommended) | What it does |
+|---------|----------------------|------------------|------|
+| `blur_active_element` | `Capybara::Screenshot.blur_active_element = true` | `SnapDiff.config.blur_active_element = true` | Hide cursor/focus indicator in screenshots (default: `true`) |
+| `hide_caret` | `Capybara::Screenshot.hide_caret = true` | `SnapDiff.config.hide_caret = true` | Make input caret transparent for stable comparisons (default: `true`) |
+| `tolerance` | `Capybara::Screenshot::Diff.tolerance = 0.0005` | `SnapDiff.config.tolerance = 0.0005` | Pixel-level color difference threshold (higher = less strict) |
+| `save_path` | `Capybara::Screenshot.save_path = "doc/screenshots"` | `SnapDiff.config.save_path = "doc/screenshots"` | Where baseline screenshots are stored |
+| `window_size` | `Capybara::Screenshot.window_size = [1280, 1024]` | `SnapDiff.config.window_size = [1280, 1024]` | Browser viewport size for consistent screenshots |
+
+**All 27 settings** from both legacy namespaces are available via `SnapDiff.config.<attr_name>` — see the [Configuration Reference](configuration.md) for the full list. One rename to note: `Capybara::Screenshot.enabled` becomes `SnapDiff.config.screenshot_enabled` (it would otherwise collide with `Capybara::Screenshot::Diff.enabled`, which keeps the bare `enabled` name).
+
+---
+
+### Three Ways to Configure
+
+All three are equivalent and use the same underlying storage. Pick the one that fits your style.
+
+#### Option 1: Traditional block (v1 shape, still works)
+
+```ruby
+# In test_helper.rb or spec_helper.rb
+Capybara::Screenshot::Diff.configure do |screenshot, diff|
+  screenshot.window_size = [1280, 1024]
+  screenshot.blur_active_element = false
+  diff.tolerance = 0.0005
+  diff.driver = :vips
+end
+```
+
+#### Option 2: SnapDiff block with old shape (backward-compatible)
+
+```ruby
+SnapDiff.start do |screenshot, diff|
+  screenshot.window_size = [1280, 1024]
+  screenshot.blur_active_element = false
+  diff.tolerance = 0.0005
+  diff.driver = :vips
+end
+```
+
+#### Option 3: Consolidated config (cleanest)
+
+```ruby
+SnapDiff.configure do |config|
+  config.window_size = [1280, 1024]
+  config.blur_active_element = false
+  config.tolerance = 0.0005
+  config.driver = :vips
+end
+```
+
+---
+
+### Prepare Today on v1.x (Zero Risk)
+
+You don't have to wait for v2.0 to start using the new namespace. `SnapDiff.compare` and `SnapDiff.start` were added in v1.14; `SnapDiff.config` / `SnapDiff.configure` in v1.15. All of them work on the current 1.x line:
+
+```ruby
+# Works TODAY on v1.15+, zero risk
+SnapDiff.compare("baseline.png", "current.png")
+SnapDiff.start { |screenshot, diff| ... }
+SnapDiff.configure { |config| ... }
+```
+
+This means you can migrate your codebase incrementally **now**, before opting into 2.0.
+
+---
+
+### Deprecation Warnings
+
+In v2.0, resolving a legacy *constant* emits one deprecation warning per constant per process:
+
+```
+[snap_diff deprecation] `Capybara::Screenshot::Diff::ImageCompare` is deprecated (constant); use `SnapDiff::Comparison` instead.
+```
+
+**Warnings appear for:** legacy constant access — `Capybara::Screenshot::Diff::ImageCompare`, `::Difference`, `::Drivers`, `CapybaraScreenshotDiff::SnapManager`, etc.
+
+**Warnings do NOT appear for:**
+- Requiring the gem: `require "capybara_screenshot_diff/minitest"` etc. is not deprecated
+- The DSL: `screenshot`, `assert_matches_screenshot`, `capture_screenshot` are never deprecated
+- Settings access: `Capybara::Screenshot.blur_active_element`, `Capybara::Screenshot::Diff.tolerance=`, and the `Diff.configure` block stay silent — they remain the canonical storage that `SnapDiff.config` forwards to
+- A few advertised entry-point constants that stay eagerly defined by design: `Capybara::Screenshot::Os`, `CapybaraScreenshotDiff::DSL`, `Capybara::Screenshot::Diff::VERSION`, and the driver leaf classes (`Drivers::VipsDriver`, `Drivers::ChunkyPNGDriver`)
+
+Warnings go through `Kernel#warn`, so test suites that hook `Warning.warn` (e.g. raise-on-warning setups) see them like any other Ruby warning.
+
+#### Silencing Warnings
+
+If warnings appear in a test run and you're not ready to migrate yet:
+
+```ruby
+# In test_helper.rb, before running tests
+SnapDiff.silence_deprecations = true
+```
+
+```bash
+# Or as an environment variable
+export SNAP_DIFF_SILENCE_DEPRECATIONS=1
+```
+
+---
+
+### Known Alpha Caveats
+
+Two deliberate consequences of the lazy shim design — both flagged for feedback on [#166](https://github.com/snap-diff/snap_diff-capybara/issues/166):
+
+1. **`defined?` / `const_defined?` on lazily-shimmed legacy names returns `false`/`nil`.** The shims resolve via `const_missing`, which those checks never trigger. Feature detection like `defined?(Capybara::Screenshot::Diff::ImageCompare)` must move to the `SnapDiff::` name. Rescuing legacy *error classes* is unaffected — they remain eagerly defined.
+
+2. **Reopening `module Capybara::Screenshot::Diff::Drivers` shadows the shim.** The historical custom-driver monkey-patch pattern defines a fresh, empty `Drivers` module instead of reaching the real one. Define custom drivers under `SnapDiff::Drivers` instead — and note `BaseDriver` is gone as a superclass: `class MyDriver < BaseDriver` becomes `include SnapDiff::Driver` (it's a mixin now).
+
+---
+
+### FAQ
+
+#### "My tests pass but I see warnings. Should I worry?"
+
+No. Warnings are informational and fully suppressible. They're designed to catch legacy namespace references, not break existing CI. If silence is preferable for now, set `SNAP_DIFF_SILENCE_DEPRECATIONS=1` and migrate at your pace.
+
+#### "Does the DSL change at all?"
+
+No. `screenshot`, `assert_matches_screenshot`, and `capture_screenshot` are stable and unchanged. All overrides (`:compare`, `:tolerance`, etc.) work identically.
+
+#### "Can I mix old and new config in the same suite?"
+
+Yes. Both paths write to the same underlying storage:
+
+```ruby
+Capybara::Screenshot::Diff.configure do |screenshot, diff|
+  screenshot.window_size = [1280, 1024]
+end
+
+SnapDiff.configure do |config|
+  config.tolerance = 0.0005  # Same storage, visible to the old path too
+end
+```
+
+#### "What if I need to roll back?"
+
+All settings and baselines are compatible with v1.x. Simply pin your Gemfile back to `"~> 1.15"` and `bundle update capybara-screenshot-diff`.
+
+---
+
+### Summary Checklist
+
+- [ ] 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
+- [ ] (Optional) Silence deprecation warnings if not ready to migrate
+- [ ] Report anything surprising on [#166](https://github.com/snap-diff/snap_diff-capybara/issues/166)
+
+---
+
 ## Upgrading to v1.13.0
 
 ### Overview
@@ -452,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,6 +2,8 @@
 
 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. For the user-facing view of the same surface, see [SnapDiff — the canonical API](snapdiff.md).
+
 ## Overview
 
 ```
@@ -12,8 +14,8 @@ This document describes the internal architecture of `capybara-screenshot-diff`
                │                              │
                ▼                              ▼
 ┌──────────────────────────┐    ┌──────────────────────────┐
-│  CapybaraScreenshotDiff   │    │  CapybaraScreenshotDiff   │
-│  ::DSL (screenshot, etc)  │    │  ::AssertionRegistry       │
+│  SnapDiff::DSL            │    │  SnapDiff::AssertionRegistry│
+│  (screenshot, etc)        │    │  (SnapDiff.session)        │
 └──────────────┬───────────┘    └──────────────┬───────────┘
                │                               │
                ▼                               ▼
@@ -31,7 +33,7 @@ This document describes the internal architecture of `capybara-screenshot-diff`
       │
       ▼
 ┌──────────────────────────────────────────┐
-│  ImageCompare (layered comparison)       │
+│  SnapDiff::Comparison (layered compare)  │
 │  ┌──────────┐ ┌──────────┐ ┌──────────┐  │
 │  │1. Byte   │ │2. Pixel  │ │3. Region │  │
 │  │  compare │ │  compare │ │  analyze │  │
@@ -50,7 +52,9 @@ This document describes the internal architecture of `capybara-screenshot-diff`
 
 ## Component Breakdown
 
-### 1. DSL Layer (`lib/capybara_screenshot_diff/dsl.rb`)
+### 1. DSL Layer (`lib/snap_diff/dsl.rb`)
+
+`SnapDiff::DSL` — `CapybaraScreenshotDiff::DSL` remains an eager same-object alias.
 
 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.
 
@@ -60,20 +64,20 @@ The entry point for test code. `assert_matches_screenshot` is the primary assert
 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`)
+### 2. ScreenshotMatcher (`lib/snap_diff/screenshot_matcher.rb`)
 
 The orchestrator that coordinates capture and comparison:
 
-1. **Window size check** — verifies browser window is the expected size
+1. **Viewport preparation** — `SnapDiff::Capture::Viewport.prepare!` (`lib/snap_diff/capture/viewport.rb`) verifies the browser window is the expected size (raise-only, never resizes); runs once per capture, outside any stability retry loop
 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)
+5. **Comparison** — creates a `SnapDiff::Comparison` 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`)
+### 3. Screenshoter & StableScreenshoter (`lib/snap_diff/screenshoter.rb`, `lib/snap_diff/stable_screenshoter.rb`)
 
 **Screenshoter:** The basic capture flow:
 1. Prepares the page (blur active element, hide caret, disable animations, wait for images)
@@ -86,7 +90,9 @@ The orchestrator that coordinates capture and comparison:
 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`)
+### 4. Comparison (`lib/snap_diff/comparison.rb`)
+
+`SnapDiff::Comparison` (legacy name: `ImageCompare`); its result value object is `SnapDiff::ComparisonResult` (`lib/snap_diff/comparison_result.rb`, legacy name: `Difference`).
 
 The comparison engine uses a **layered optimization strategy** to balance speed and accuracy:
 
@@ -100,11 +106,11 @@ The comparison engine uses a **layered optimization strategy** to balance speed
 - `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
+- `Comparison#analyze_difference` handles the actual pixel analysis, delegating to the driver
 
-### 5. Drivers (`lib/capybara/screenshot/diff/drivers/`)
+### 5. Drivers (`lib/snap_diff/drivers/`)
 
-Drivers abstract image processing operations. Each driver implements:
+Drivers abstract image processing operations. Shared default behavior lives in the `SnapDiff::Driver` mixin (`lib/snap_diff/driver.rb`) — it replaced the old `Drivers::BaseDriver` superclass, so concrete drivers `include SnapDiff::Driver` instead of inheriting. Each driver implements:
 
 | Operation | VipsDriver | ChunkyPNGDriver |
 |-----------|-----------|-----------------|
@@ -121,6 +127,8 @@ Drivers abstract image processing operations. Each driver implements:
 
 **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:
@@ -135,7 +143,7 @@ Drivers abstract image processing operations. Each driver implements:
 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`)
+### 7. SnapManager & Snap (`lib/snap_diff/snap_manager.rb`, `lib/snap_diff/snap.rb`)
 
 **Snap** represents a single screenshot file with path management:
 - `path` — the actual screenshot file
@@ -148,11 +156,11 @@ Drivers abstract image processing operations. Each driver implements:
 - Handles VCS checkout of baselines
 - Manages file operations (copy, move, cleanup)
 
-### 8. VCS (`lib/capybara/screenshot/diff/vcs.rb`)
+### 8. VCS (`lib/snap_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/`)
+### 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
@@ -167,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`.
+**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
 
@@ -183,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
@@ -203,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` (from ActiveSupport, or pure Ruby fallback) 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`
@@ -219,49 +234,72 @@ Configuration uses Ruby's `mattr_accessor` (from ActiveSupport, or pure Ruby fal
 - `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.
+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
 
 ```
 lib/
-  capybara_screenshot_diff.rb                  # Core module, mattr_accessor definitions
-  capybara/screenshot/diff.rb                  # Convenience require (loads minitest)
-  capybara_screenshot_diff/
+  snap_diff.rb                                 # SnapDiff module: compare/start/configure/config
+  snap_diff/                                   # Canonical implementation (v2)
     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
-    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
+    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)
+    comparison_result.rb                       # Comparison result value object (ex-Difference)
+    driver.rb                                  # SnapDiff::Driver mixin (ex-BaseDriver superclass)
     drivers.rb                                 # Driver factory
     drivers/
-      base_driver.rb                           # Abstract base driver
       vips_driver.rb                           # VIPS image processing
       chunky_png_driver.rb                     # ChunkyPNG image processing
+    capture/
+      viewport.rb                              # Per-capture viewport preparation seam
     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
-    difference.rb                              # Difference result value object
+    screenshot_assertion.rb                    # Assertion + registry objects
+    screenshot_namer.rb                        # Name/path generation with sections/groups
+    snap_manager.rb                            # Screenshot file management
+    snap.rb                                    # Single screenshot file abstraction
+    reporting.rb                               # Process-global reporter lifecycle
+    reporters/
+      html.rb                                  # Interactive HTML report reporter
+      templates/report.html.erb                # HTML report template
+    annotation_service.rb                      # Diff-image annotation (RED_RGBA / ORANGE_RGBA)
     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
+    attempts_reporter.rb                       # Debug reporting for unstable captures
+    error_with_filtered_backtrace.rb           # Error with filtered stack
     vcs.rb                                     # Git baseline checkout
+    utils.rb                                   # Driver detection
     os.rb                                      # OS detection
-    cucumber.rb                                # Deprecated Cucumber entry point
-    reporters/
-      default.rb                               # Default annotated-image reporter
+    static.rb                                  # Non-Rails static site serving
+    version.rb                                 # Gem version
+    integrations/
+      minitest.rb                              # Minitest assertions integration
+      rspec.rb                                 # RSpec matcher integration
+      cucumber.rb                              # Cucumber World integration
+  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                           # 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/
 ```
+
+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.