tui-td 0.2.13 → 0.2.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88f553e060b5f2836421a48eadf8aa6b0341974e7081f7e9dd98e024b0665a59
-  data.tar.gz: ddd0b1fd0f0666382b8f8d1fb9cb8b170cef2829299685da4a56d51d4cfc7945
+  metadata.gz: cadf6d0ad5e362e3704a7a87673e0ad7254573eba2f53575aea38fc45f949877
+  data.tar.gz: fbfd589b84e911d6c46b16976b34dc46943019c52bd7519b04ffc6422a71b659
 SHA512:
-  metadata.gz: 5d478553f03b514f380d46c6aff519d3f6aec2f44dcd790ab51a162eca9cba8e73b136f79ebdf72cecaa7f66c9939fcb028edf80c1d904c00efb026ec0b92fa2
-  data.tar.gz: d16aef5de09e4be72370113d5ec06ecebc6a3ec2ceda55837bf61ade4953906ec500513f24d3eef0127a8aa6a2919339660b922615f26c4b01848c496c6ff359
+  metadata.gz: c0e8f58b7f193a556d2dee0e1f8c15f005b669fe3823d31763e57efd8c35d511f5e2e5dbb9ff03a61abe534030c1673cc1de437bcbe705b8c008c1ff9af8878a
+  data.tar.gz: 520f31800ee26803d9ec56b9128b729f59a057246a11e2b70c1647f253b76bb95e06f99631fb4d6c23597415e8a48a92725e22c36b99faca932cb75d00c84d8c

data/CHANGELOG.md

@@ -1,5 +1,68 @@
 # CHANGELOG
 
+## 0.2.16
+
+### Added
+
+- Driver#find_text: convenience delegation to State#find_text with match: modes
+- Driver#snapshot: return a State snapshot for later diff comparison
+- match_snapshot RSpec matcher: compare current state against saved snapshot,
+  supports chars_only: true to ignore color/style changes
+- MCP tui_diff tool: compare current terminal state against a previous snapshot,
+  returns cell-level differences
+- MCP tui_annotate_element tool: manually register UI element annotations that
+  are picked up by tui_find_elements
+- Drive mode: snapshot and diff commands for interactive state comparison
+
+### Changed
+
+- Tighten tans-parser dependency to ~> 0.1.3 (includes State#diff,
+  State#annotate_role, improved dialog/statusbar detection)
+
+## 0.2.15
+
+### Added
+
+- Integration with tans-parser 0.1.2: new UI element roles (:input, :label, :menu, :tab)
+- Filter kwargs on get_by_role: text:, checked:, disabled:
+- Singular convenience methods: button(), checkbox(), input(), label(), menu(), tab(),
+  dialog(), statusbar(), progress_bar()
+- Element action methods: click, type(text), press_key(key)
+- Element predicates: checked?, disabled?
+- Element bounds accessor
+- disabled field on Element
+- ScopedSelector via Selector#within(element, &block) with full query API
+- State#find_text match modes: :partial (default), :exact, :regex
+- RSpec matchers: have_input, have_label, have_menu, have_tab, have_statusbar,
+  have_progress_bar
+- JSON test steps: assert_input, assert_label, assert_menu, assert_tab,
+  assert_statusbar, assert_progress_bar
+- MCP tool: tui_element_actions — returns click/type/press_key action hashes
+- Enhanced MCP tui_find_elements: checked/disabled filters, new roles, (disabled)/
+  (focused) output
+- Enhanced MCP tui_find_text: match: parameter for exact/regex mode
+- CLI drive mode: elements command now shows inputs, labels, menus, tabs
+- Updated help texts (tui-td help test, tui-td help rspec) with new steps and matchers
+
+### Changed
+
+- RSpec matchers (have_button, have_checkbox, have_role) now use tans-parser filter
+  kwargs instead of manual .select post-filtering
+- JSON test runner check_role helper uses tans-parser filter kwargs
+- have_checkbox now supports .unchecked chain
+
+### Removed
+
+- Custom coordinate-based Selector#within (replaced by tans-parser's element-based
+  within with ScopedSelector)
+
+## 0.2.14
+
+### Fixed
+
+- Tighten tans-parser dependency from `~> 0.1` to `~> 0.1.1` to ensure the required
+  Selector/Element classes are present (0.1.0 lacks them)
+
 ## 0.2.13
 
 ### Added

data/README.md

@@ -286,7 +286,13 @@ tui-td test examples/echo_test.json
 | `assert_button` | `"text"` | Assert a button with given text is visible (`[ OK ]`, `(Cancel)`, `<Submit>`) |
 | `assert_dialog` | — | Assert a dialog (box-drawing region) is visible |
 | `assert_checkbox` | `"label", "checked": true` | Assert a checkbox with given label (and optionally checked state) |
-| `assert_role` | `":button", "text": "OK"` | Generic role assertion (`:button`, `:checkbox`, `:dialog`, `:statusbar`, `:progress`) |
+| `assert_role` | `":button", "text": "OK"` | Generic role assertion (`:button`, `:checkbox`, `:dialog`, `:statusbar`, `:progress`, `:input`, `:label`, `:menu`, `:tab`) |
+| `assert_input` | `"text"` (optional) | Assert an input field (`[____]`) is visible |
+| `assert_label` | `"text"` | Assert a label (text ending with colon) is visible |
+| `assert_menu` | `"text"` (optional) | Assert a menu bar or dropdown item is visible |
+| `assert_tab` | `"text"` | Assert a tab (`[Tab1]`) is visible |
+| `assert_statusbar` | — | Assert a status bar (bottom row with background) is visible |
+| `assert_progress_bar` | `"text"` (optional) | Assert a progress bar (`[####]`) is visible |
 | `close` | — | Close the TUI |
 
 Example with `html` step for before/after snapshots:
@@ -364,7 +370,13 @@ end
 | `have_button("OK")` | Assert a button with given text is visible |
 | `have_dialog` | Assert a dialog (box-drawing region) is visible |
 | `have_checkbox("Label").checked` | Assert a checkbox with given label (chain `.checked`) |
-| `have_role(:button, text: "OK")` | Generic role assertion with optional text filter |
+| `have_role(:button, text: "OK", checked: true, disabled: false)` | Generic role assertion with optional text, checked, disabled filters |
+| `have_input` | Assert an input field (`[____]`) is visible |
+| `have_label("Name")` | Assert a label (text ending with colon) is visible |
+| `have_menu` | Assert a menu bar or dropdown item is visible |
+| `have_tab("File")` | Assert a tab is visible |
+| `have_statusbar` | Assert a status bar (bottom row with background) is visible |
+| `have_progress_bar("50%")` | Assert a progress bar (`[####]`) is visible |
 | `have_exit_status(N)` | Assert the driver process exit status equals N |
 
 ## MCP Server — AI Integration
@@ -390,8 +402,11 @@ tui-td serve
 | `tui_html_render` | Render terminal state as a self-contained HTML document. Returns HTML inline or saves to file. |
 | `tui_wait_for_exit` | Wait until the TUI process exits. Returns exit status. |
 | `tui_exit_status` | Get the exit status code (nil if still running). |
-| `tui_find_text` | Search for text or regex in terminal state. Returns positions of all matches. |
-| `tui_find_elements` | Detect UI elements (buttons, checkboxes, dialogs, etc.) with optional role/text filters. |
+| `tui_find_text` | Search for text or regex in terminal state. Supports match modes: `partial` (default), `exact`, `regex`. |
+| `tui_find_elements` | Detect UI elements (buttons, checkboxes, dialogs, inputs, labels, menus, tabs, etc.) with optional role, text, checked, and disabled filters. |
+| `tui_element_actions` | Get click/type/press_key action hashes for a detected UI element. For AI-driven interaction. |
+| `tui_diff` | Compare current state against a previous snapshot. Returns cell-level differences. |
+| `tui_annotate_element` | Manually register a UI element annotation. Picked up by tui_find_elements. |
 | `tui_close` | Close the TUI and clean up. |
 
 ### MCP configuration
@@ -441,10 +456,13 @@ Add to your MCP client configuration:
 // 9. Find UI elements by role
 {"method": "tools/call", "params": {"name": "tui_find_elements", "arguments": {"role": "button"}}}
 
-// 10. Check exit status (or wait for exit)
+// 10. Get actions for an element
+{"method": "tools/call", "params": {"name": "tui_element_actions", "arguments": {"role": "button", "text": "OK"}}}
+
+// 11. Check exit status (or wait for exit)
 {"method": "tools/call", "params": {"name": "tui_exit_status", "arguments": {}}}
 
-// 11. Clean up
+// 12. Clean up
 {"method": "tools/call", "params": {"name": "tui_close", "arguments": {}}}
 ```
 

data/lib/tui_td/cli.rb

@@ -41,6 +41,10 @@ module TUITD
         opts.separator "  state              Show terminal state as pretty JSON"
         opts.separator "  raw                Show raw ANSI output"
         opts.separator "  elements           Show detected UI elements (buttons, dialogs, etc.)"
+        opts.separator "  snapshot <name>    Save current state as named snapshot to disk"
+        opts.separator "  snapshot           Save current state in-memory (legacy)"
+        opts.separator "  diff <name>        Compare current state against named snapshot on disk"
+        opts.separator "  diff               Compare against in-memory snapshot (legacy)"
         opts.separator "  key <name>         Send keystroke (enter, tab, escape, up, down, left, right,"
         opts.separator "                     backspace, ctrl_c, ctrl_d)"
         opts.separator "  <text>             Send text to the TUI"
@@ -202,8 +206,53 @@ module TUITD
             puts "Buttons:    #{selector.buttons.map { |e| "#{e.text}@[#{e.row},#{e.col}]" }.join(", ")}"
             puts "Checkboxes: #{selector.checkboxes.map { |e| "#{e.text} (#{e.checked ? "✓" : "☐"})" }.join(", ")}"
             puts "Dialogs:    #{selector.dialogs.map { |e| "\"#{e.text}\" #{e.width}x#{e.height}" }.join(", ")}"
+            puts "Inputs:     #{selector.inputs.map { |e| "[__]@[#{e.row},#{e.col}]" }.join(", ")}"
+            puts "Labels:     #{selector.labels.map(&:text).join(", ")}"
+            puts "Menus:      #{selector.menus.map(&:text).join(", ")}"
+            puts "Tabs:       #{selector.tabs.map { |e| "#{e.text}#{" (focused)" if e.focused}" }.join(", ")}"
             puts "Statusbars: #{selector.statusbars.map(&:text).join(", ")}"
             puts "Progress:   #{selector.progress_bars.map(&:text).join(", ")}"
+          elsif input.start_with?("snapshot ")
+            name = input.split(" ", 2).last.strip
+            unless name.empty?
+              snap = Snapshot.new(name)
+              snap.save(driver.state_data)
+              puts "Snapshot '#{name}' saved to #{snap.path}."
+            end
+          elsif input == "snapshot"
+            @last_snapshot = State.new(driver.state_data)
+            puts "In-memory snapshot saved."
+          elsif input.start_with?("diff ")
+            name = input.split(" ", 2).last.strip
+            unless name.empty?
+              snap = Snapshot.new(name)
+              unless snap.exists?
+                puts "No snapshot '#{name}' found at #{snap.path}."
+                next
+              end
+              result = snap.compare(driver.state_data)
+              if result.passed?
+                puts "No differences. Snapshot '#{name}' matches."
+              else
+                puts result.message
+              end
+            end
+          elsif input == "diff"
+            if @last_snapshot
+              current = State.new(driver.state_data)
+              diffs = current.diff(@last_snapshot)
+              if diffs.empty?
+                puts "No differences."
+              else
+                puts "#{diffs.size} difference(s):"
+                diffs.first(10).each do |d|
+                  puts "  [#{d[:row]},#{d[:col]}] #{d[:before][:char].inspect} -> #{d[:after][:char].inspect}"
+                end
+                puts "  ..." if diffs.size > 10
+              end
+            else
+              puts "No snapshot saved. Use 'snapshot <name>' or 'snapshot' first."
+            end
           elsif input.start_with?("key ")
             driver.send_keys(input.split(" ", 2).last.to_sym)
           else
@@ -433,7 +482,27 @@ module TUITD
 
           {"assert_role": ":button", "text": "OK"}
               Generic role assertion. Accepts :button, :checkbox, :dialog,
-              :statusbar, :progress. Optional "text" filter.
+              :statusbar, :progress, :input, :label, :menu, :tab.
+              Optional "text", "checked", and "disabled" filters.
+
+          {"assert_input": true} or {"assert_input": "text"}
+              Assert that an input field ([____]) is visible. Optional text
+              filter to match adjacent label.
+
+          {"assert_label": "Name"}
+              Assert that a label (text ending with colon) is visible.
+
+          {"assert_menu": true} or {"assert_menu": "File | Edit"}
+              Assert that a menu bar or dropdown item is visible.
+
+          {"assert_tab": "File"}
+              Assert that a tab ([Tab1]) is visible.
+
+          {"assert_statusbar": true}
+              Assert that a status bar (bottom row with background) is visible.
+
+          {"assert_progress_bar": true} or {"assert_progress_bar": "50%"}
+              Assert that a progress bar ([####   ]) is visible.
 
         Example test file: examples/echo_test.json
       HELP
@@ -518,9 +587,41 @@ module TUITD
 
         have_role(:button, text: "OK")
             Generic role matcher. Accepts :button, :checkbox, :dialog,
-            :statusbar, :progress. Optional text: filter.
+            :statusbar, :progress, :input, :label, :menu, :tab.
+            Optional text:, checked:, disabled: filters.
             Usage: expect(state).to have_role(:statusbar)
 
+        have_input
+            Passes if an input field ([____]) is visible.
+            Usage: expect(state).to have_input
+            Usage: expect(state).to have_input("Name")
+
+        have_label("Name")
+            Passes if a label (text ending with colon) is visible.
+            Usage: expect(state).to have_label("Name")
+
+        have_menu
+            Passes if a menu bar or dropdown item is visible.
+            Usage: expect(state).to have_menu
+
+        have_tab("File")
+            Passes if a tab is visible.
+            Usage: expect(state).to have_tab("File")
+
+        have_statusbar
+            Passes if a status bar (bottom row with background) is visible.
+            Usage: expect(state).to have_statusbar
+
+        have_progress_bar
+            Passes if a progress bar ([####   ]) is visible.
+            Usage: expect(state).to have_progress_bar
+
+        match_snapshot(snapshot, chars_only: false)
+            Passes if the current state matches a previously saved snapshot.
+            Use chars_only: true to ignore color/style changes.
+            Usage: pre = driver.snapshot; ... ; expect(driver).to match_snapshot(pre)
+            Usage: expect(state).to match_snapshot(snap, chars_only: true)
+
         Driver matchers (work on TUITD::Driver, not State)
         --------------------------------------------------
 

data/lib/tui_td/configuration.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module TUITD
+  # Global configuration for tui-td.
+  #
+  # Usage:
+  #   TUITD.configure do |c|
+  #     c.snapshot_dir = "spec/snapshots"
+  #   end
+  #
+  class Configuration
+    attr_accessor :snapshot_dir
+
+    def initialize
+      @snapshot_dir = nil
+    end
+
+    # Check if UPDATE_SNAPSHOTS env var is set to update mode.
+    def update_snapshots?
+      %w[1 true].include?(ENV["UPDATE_SNAPSHOTS"].to_s)
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+  end
+end

data/lib/tui_td/driver.rb

@@ -211,6 +211,19 @@ module TUITD
       Screenshot.new(@state).render(output_path)
     end
 
+    # Search for text or regex pattern in the current terminal state.
+    # Delegates to TansParser::State#find_text.
+    # Supports match modes: :partial (default, substring), :exact, :regex.
+    def find_text(pattern, match: :partial)
+      TUITD::State.new(state_data).find_text(pattern, match: match)
+    end
+
+    # Return a snapshot of the current terminal state as a TUITD::State object.
+    # Can be compared later with match_snapshot or State#diff.
+    def snapshot
+      TUITD::State.new(state_data)
+    end
+
     # Close the driver and clean up
     def close
       _stop_reader_thread

data/lib/tui_td/matchers.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rubocop:disable Metrics/ModuleLength, Metrics/BlockLength, Metrics/ParameterLists, Layout/LineLength
+
 require "rspec/expectations"
 
 # RSpec matchers for TUITD::State and TUITD::Driver objects.
@@ -137,7 +139,7 @@ module TUITD
     RSpec::Matchers.define :have_button do |expected|
       match do |actual|
         Matchers.auto_wait(actual) do |s|
-          Selector.new(s).get_by_text(expected).any? { |e| e.role == :button }
+          Selector.new(s).button(text: expected)
         end
       end
 
@@ -158,50 +160,59 @@ module TUITD
 
     RSpec::Matchers.define :have_checkbox do |expected|
       chain(:checked) { @checked = true }
+      chain(:unchecked) { @checked = false }
 
       match do |actual|
         Matchers.auto_wait(actual) do |s|
-          checkboxes = Selector.new(s).checkboxes
-          found = checkboxes.select { |e| e.text&.include?(expected) }
-          found = found.select(&:checked) if @checked
-          found.any?
+          filters = { text: expected }
+          filters[:checked] = @checked unless @checked.nil?
+          Selector.new(s).checkbox(**filters)
         end
       end
 
       description do
         desc = "have checkbox #{expected.inspect}"
-        desc += " (checked)" if @checked
+        desc += " (checked)" if @checked == true
+        desc += " (unchecked)" if @checked == false
         desc
       end
       failure_message do |_actual|
         desc = "expected terminal to have checkbox #{expected.inspect}"
-        desc += " (checked)" if @checked
+        desc += " (checked)" if @checked == true
+        desc += " (unchecked)" if @checked == false
         desc
       end
       failure_message_when_negated do |_actual|
         desc = "expected terminal NOT to have checkbox #{expected.inspect}"
-        desc += " (checked)" if @checked
+        desc += " (checked)" if @checked == true
+        desc += " (unchecked)" if @checked == false
         desc
       end
     end
 
-    RSpec::Matchers.define :have_role do |role, text: nil|
+    RSpec::Matchers.define :have_role do |role, text: nil, checked: nil, disabled: nil|
       match do |actual|
         Matchers.auto_wait(actual) do |s|
-          elements = Selector.new(s).get_by_role(role)
-          elements = elements.select { |e| e.text&.include?(text) } if text
-          elements.any?
+          filters = {}
+          filters[:text] = text if text
+          filters[:checked] = checked unless checked.nil?
+          filters[:disabled] = disabled unless disabled.nil?
+          Selector.new(s).get_by_role(role, **filters).any?
         end
       end
 
       description do
         desc = "have role :#{role}"
         desc += " with text #{text.inspect}" if text
+        desc += " (checked)" if checked == true
+        desc += " (disabled)" if disabled == true
         desc
       end
       failure_message do |_actual|
         desc = "expected terminal to have a :#{role}"
         desc += " with text #{text.inspect}" if text
+        desc += " (checked)" if checked == true
+        desc += " (disabled)" if disabled == true
         desc
       end
       failure_message_when_negated do |_actual|
@@ -210,5 +221,240 @@ module TUITD
         desc
       end
     end
+
+    # New role matchers (tans-parser 0.1.2)
+
+    RSpec::Matchers.define :have_input do |expected = nil|
+      match do |actual|
+        Matchers.auto_wait(actual) do |s|
+          if expected
+            Selector.new(s).input(text: expected)
+          else
+            Selector.new(s).inputs.any?
+          end
+        end
+      end
+
+      description do
+        expected ? "have input #{expected.inspect}" : "have an input field"
+      end
+      failure_message do |_actual|
+        expected ? "expected terminal to have an input #{expected.inspect}" : "expected terminal to have an input field"
+      end
+      failure_message_when_negated do |_actual|
+        expected ? "expected terminal NOT to have an input #{expected.inspect}" : "expected terminal NOT to have an input field"
+      end
+    end
+
+    RSpec::Matchers.define :have_label do |expected = nil|
+      match do |actual|
+        Matchers.auto_wait(actual) do |s|
+          if expected
+            Selector.new(s).label(text: expected)
+          else
+            Selector.new(s).labels.any?
+          end
+        end
+      end
+
+      description do
+        expected ? "have label #{expected.inspect}" : "have a label"
+      end
+      failure_message do |_actual|
+        expected ? "expected terminal to have a label #{expected.inspect}" : "expected terminal to have a label"
+      end
+      failure_message_when_negated do |_actual|
+        expected ? "expected terminal NOT to have a label #{expected.inspect}" : "expected terminal NOT to have a label"
+      end
+    end
+
+    RSpec::Matchers.define :have_menu do |expected = nil|
+      match do |actual|
+        Matchers.auto_wait(actual) do |s|
+          if expected
+            Selector.new(s).menu(text: expected)
+          else
+            Selector.new(s).menus.any?
+          end
+        end
+      end
+
+      description do
+        expected ? "have menu #{expected.inspect}" : "have a menu"
+      end
+      failure_message do |_actual|
+        expected ? "expected terminal to have a menu #{expected.inspect}" : "expected terminal to have a menu"
+      end
+      failure_message_when_negated do |_actual|
+        expected ? "expected terminal NOT to have a menu #{expected.inspect}" : "expected terminal NOT to have a menu"
+      end
+    end
+
+    RSpec::Matchers.define :have_tab do |expected = nil|
+      match do |actual|
+        Matchers.auto_wait(actual) do |s|
+          if expected
+            Selector.new(s).tab(text: expected)
+          else
+            Selector.new(s).tabs.any?
+          end
+        end
+      end
+
+      description do
+        expected ? "have tab #{expected.inspect}" : "have a tab"
+      end
+      failure_message do |_actual|
+        expected ? "expected terminal to have a tab #{expected.inspect}" : "expected terminal to have a tab"
+      end
+      failure_message_when_negated do |_actual|
+        expected ? "expected terminal NOT to have a tab #{expected.inspect}" : "expected terminal NOT to have a tab"
+      end
+    end
+
+    RSpec::Matchers.define :have_statusbar do |expected = nil|
+      match do |actual|
+        Matchers.auto_wait(actual) do |s|
+          if expected
+            Selector.new(s).statusbar(text: expected)
+          else
+            Selector.new(s).statusbars.any?
+          end
+        end
+      end
+
+      description do
+        expected ? "have status bar #{expected.inspect}" : "have a status bar"
+      end
+      failure_message do |_actual|
+        expected ? "expected terminal to have a status bar #{expected.inspect}" : "expected terminal to have a status bar"
+      end
+      failure_message_when_negated do |_actual|
+        expected ? "expected terminal NOT to have a status bar #{expected.inspect}" : "expected terminal NOT to have a status bar"
+      end
+    end
+
+    RSpec::Matchers.define :have_progress_bar do |expected = nil|
+      match do |actual|
+        Matchers.auto_wait(actual) do |s|
+          if expected
+            Selector.new(s).progress_bar(text: expected)
+          else
+            Selector.new(s).progress_bars.any?
+          end
+        end
+      end
+
+      description do
+        expected ? "have progress bar #{expected.inspect}" : "have a progress bar"
+      end
+      failure_message do |_actual|
+        expected ? "expected terminal to have a progress bar #{expected.inspect}" : "expected terminal to have a progress bar"
+      end
+      failure_message_when_negated do |_actual|
+        expected ? "expected terminal NOT to have a progress bar #{expected.inspect}" : "expected terminal NOT to have a progress bar"
+      end
+    end
+
+    # Snapshot comparison matcher — works with both State and Driver (auto-wait).
+    # Snapshot comparison matcher — supports both named (disk-based) and
+    # legacy in-memory State objects.
+    #
+    # Named snapshots (recommended):
+    #   expect(driver).to match_snapshot("login_screen")
+    #   expect(driver).to match_snapshot("login", type: :all, wait: true)
+    #
+    # First run creates the snapshot, subsequent runs compare.
+    # UPDATE_SNAPSHOTS=1 overwrites all snapshots.
+    #
+    # Legacy (backward compatible):
+    #   pre = driver.snapshot
+    #   expect(driver).to match_snapshot(pre, chars_only: true)
+    #
+    RSpec::Matchers.define :match_snapshot do |ref, type: nil, wait: false, chars_only: nil, ignore_rows: nil, region: nil|
+      match do |actual|
+        # Normalize type: backward compat for chars_only parameter
+        effective_type = type
+        if effective_type.nil? && !chars_only.nil?
+          effective_type = chars_only ? :text : :full
+        end
+        effective_type ||= :text
+
+        @snapshot_name = nil
+        @diff_result = nil
+
+        # Legacy path: snapshot_ref is a State object (responds to diff)
+        if ref.respond_to?(:diff)
+          Matchers.auto_wait(actual) do |s|
+            chars = effective_type == :text
+            diffs = ref.diff(s, chars_only: chars)
+            diffs.select! { |d| Array(region).include?(d[:row]) } if region
+            diffs.reject! { |d| Array(ignore_rows).include?(d[:row]) } if ignore_rows
+            @diff_result = diffs
+            @diff_result.empty?
+          end
+        else
+          # Named snapshot path
+          @snapshot_name = ref.to_s
+          snap = Snapshot.new(@snapshot_name, type: effective_type)
+
+          # Get state_data from actual
+          if wait && actual.respond_to?(:wait_for_stable)
+            begin
+              actual.wait_for_stable
+            rescue StandardError
+              nil
+            end
+          end
+          state_data = if actual.respond_to?(:state_data)
+                         actual.state_data
+                       elsif actual.respond_to?(:to_h)
+                         actual.to_h
+                       else
+                         actual
+                       end
+
+          if TUITD.configuration.update_snapshots?
+            snap.save(state_data)
+            true
+          elsif !snap.exists?
+            snap.save(state_data)
+            @diff_result = TUITD::Snapshot::ComparisonResult.new(passed: true, diff_count: 0, type: effective_type,
+                                                                 message: "Snapshot '#{@snapshot_name}' created (#{effective_type})",)
+            true
+          else
+            @diff_result = snap.compare(state_data, ignore_rows: ignore_rows, region: region)
+            @diff_result.passed?
+          end
+        end
+      end
+
+      description do
+        if @snapshot_name
+          "match snapshot #{@snapshot_name.inspect} (type: #{effective_type})"
+        else
+          desc = "match snapshot"
+          desc << " (chars only)" if effective_type == :text
+          desc
+        end
+      end
+
+      failure_message do |_actual|
+        if @snapshot_name
+          "Snapshot #{@snapshot_name.inspect} does not match.\n#{@diff_result&.message}"
+        else
+          "expected terminal to match snapshot"
+        end
+      end
+
+      failure_message_when_negated do |_actual|
+        if @snapshot_name
+          "expected snapshot #{@snapshot_name.inspect} NOT to match, but it did."
+        else
+          "expected terminal NOT to match snapshot, but it did."
+        end
+      end
+    end
   end
 end
+# rubocop:enable Metrics/ModuleLength, Metrics/BlockLength, Metrics/ParameterLists, Layout/LineLength