snap_diff-capybara 2.0.0.alpha1 → 2.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 544c2e3414e9b616291b0cd0e843e72d1a41652017fc2b966926665285aaf49a
-  data.tar.gz: b2a226430eaeab196e297efc9c476eb4cf0d192334d1503ba29f330fb9bd81ed
+  metadata.gz: a063da3ec86978a0e66baaa0c64692c40f18db15ce66b40cab390df9a90be5a1
+  data.tar.gz: c34b6fe46a10353ed94d738832cd9dafca06ef0f7a53b2c678408010198f58d2
 SHA512:
-  metadata.gz: 91c3e8fd69a3f7e981f77ef8425ccc231e2b9617868f5278bb74c6865c82d59828ab708f7ecf7e57db0f891338f20704c277e8865e8f8444762ffc1b3929748d
-  data.tar.gz: 2651d17eaceca6a6b8f5c94136e8e221639ec5cf70d70d9178d9d30a630f5014e5eb240ace31233a45a456cf3918d0e70b324c998e2b4ab3531bac7d7d21ffe0
+  metadata.gz: '0828945cb79fbf911727deeac0b4cf868f34b5787c37720bc216a6d893115a2d9486a43284cf3f3467834951d1ae438f969a7ea5e1dcdd8ae387fb2cf9f263b9'
+  data.tar.gz: 3fc96895702aac83fa636bf8cfd1ac73953b4049b2629104ccbde592af150f3829c3eda7e73e8912b0342793cbf3e45d07056ffffb68c4f3b5594758406cd932

data/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.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,232 @@
 # 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.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).
+
+**Estimated upgrade time:** 5–15 minutes (most users need only the Gemfile pin)
+
+**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.alpha1"
+```
+
+```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` |
+
+**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.alpha1"` 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

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.
+
 ## Overview
 
 ```
@@ -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 |
 |-----------|-----------|-----------------|
@@ -135,7 +141,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 +154,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/capybara/screenshot/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 +173,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)` 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.
 
 ### 10. Assertion Lifecycle
 
@@ -208,7 +214,7 @@ Test begins
 
 ### 12. Configuration System
 
-Configuration uses Ruby's `mattr_accessor` (from ActiveSupport, or pure Ruby fallback) and is organized into two namespaces:
+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:
 
 **`Capybara::Screenshot`** — capture settings:
 - `window_size`, `stability_time_limit`, `blur_active_element`, `hide_caret`, `disable_animations`
@@ -219,49 +225,65 @@ 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 `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.
 
 ## 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 — flat view over all 27 settings
+    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 + error classes
+  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
+    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.

data/lib/snap_diff/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SnapDiff
-  VERSION = "2.0.0.alpha1"
+  VERSION = "2.0.0.beta1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: snap_diff-capybara
 version: !ruby/object:Gem::Version
-  version: 2.0.0.alpha1
+  version: 2.0.0.beta1
 platform: ruby
 authors:
 - Uwe Kubosch