tans-parser 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c7b3233b668eeef9d7240a8cddd5f8389cc62fdf3c641103472696daab956f4
-  data.tar.gz: 39391122997e84cde9b4313542a1f2071cc752f66d9577e1c008133359064223
+  metadata.gz: fc3b07fbdd59e595af3d07d3091cdb75b9faa0c4daeaaaf3232f7787d35406e4
+  data.tar.gz: 75f354d01a6881cc8bb702bb900b41b2f654ecae8b7d5033bc439ad876eeb97a
 SHA512:
-  metadata.gz: 6489e45f59dbb4f7e7375108bc4f6f881fab6989415b5d44d09337bbaa166edb43974c1f6ebf8f1af068637dc7ee8bd604e0e6f55c8ffc0268f5fe610a23ec3e
-  data.tar.gz: e485259b38989cc3f1953691113bc6f92ee6da125c9a0502f38f5550ca75703e0ec3919043f9297b9ee0611044701086b937cb88d2e32a8c5d7047ae6267c461
+  metadata.gz: 7d79356c65433991718c0c1854faa58f5a077a906ec653f13202d241b37fc01bb3fe253de8ba4fa9deb3b7bdee17965a1b2d2476a3b782c0a849c8b0696c4a65
+  data.tar.gz: 05045d158716d7e4ef9f87ecd2d4936735d1de681fb17cb97835a078b31654c9d0ed47022b610db7824d2a7408e82b66c34df738f1bc3b0ad7e67e40bfb4e111

data/CHANGELOG.md

@@ -1,5 +1,60 @@
 # CHANGELOG
 
+## 0.1.3
+
+- **Dialog recognition** — added support for rounded corners (`╭╮╰╯`) and double-line (`╔╗╚╝`) box-drawing characters
+  - `TOP_LEFT_CORNERS` extended with `╭╔╓╒`
+  - `dialog_top_width` extended with `╮╗╖╕` (top-right) and `═` (double horizontal)
+- **Statusbar recognition** — more flexible detection:
+  - Now checks last 2 rows instead of only the last row
+  - Fallback: detects last row as statusbar if it has ≥30 characters of content, even without background color info
+  - Handles Karat-style footers (`? for shortcuts | mock ctx ░░░░░░░░░░ 0%`)
+- **Custom role registration** — `State#annotate_role(role, row:, col:, width:, height:, text:, **extra)`:
+  - Manually annotate grid regions with semantic roles
+  - `Selector#detect_annotations` picks them up during `scan` alongside auto-detected elements
+  - Annotations support filters (text, checked, disabled) and all convenience methods
+- **State#diff** — cell-level comparison between two State instances:
+  - `diff(other_state)` — compares all 7 cell keys (`char`, `fg`, `bg`, `bold`, `italic`, `underline`, `blink`)
+  - `diff(other_state, chars_only: true)` — compares only `:char`, ignores style/color changes
+  - Handles different grid sizes (fills missing cells with `DEFAULT_CELL`)
+  - Accepts raw hash or State object
+- 19 new tests, 319 total, 100% line and branch coverage maintained
+
+## 0.1.2
+
+- **Flexible text search** — `State#find_text(pattern, match: :partial)` with three modes:
+  - `:partial` (default) — substring match (unchanged)
+  - `:exact` — row text must equal pattern (ignoring trailing whitespace)
+  - `:regex` — compile String to Regexp for matching
+  - Regexp objects now return the actual matched substring in `result[:text]`
+- **Enhanced `get_by_role`** — filter keyword arguments:
+  - `text:` — partial match on element text
+  - `checked:` — filter by checked state (`true`/`false`)
+  - `disabled:` — filter by disabled state (`true`/`false`)
+  - All plural convenience methods (`buttons`, `checkboxes`, etc.) accept the same filters
+- **New UI element roles**:
+  - `:input` — `[________]` underscore-filled brackets (text input fields)
+  - `:label` — `Word:` or `Multiple Words:` patterns
+  - `:menu` — menu bars (row 0–1, spaced words) and `> Item` dropdown items
+  - `:tab` — closely-spaced `[Tab1] [Tab2]` brackets, with `focused` detection via underline/background
+- **Singular convenience methods** — return first matching Element or `nil`:
+  - `button`, `checkbox`, `input`, `dialog`, `label`, `menu`, `tab`, `statusbar`, `progress_bar`
+  - All accept the same filter kwargs (`text:`, `checked:`, `disabled:`)
+  - Existing plural methods (`buttons`, `checkboxes`, etc.) unchanged
+- **Element actions** — `Element` now has action methods returning descriptive hashes:
+  - `click` → `{action: :click, target:, row:, col:}`
+  - `type(text)` → `{action: :type, target:, row:, col:, text:}`
+  - `press_key(key)` → `{action: :press_key, target:, key:}`
+- **Element predicates** — `checked?` and `disabled?` (always return boolean)
+- **Element `bounds`** — returns `{row:, col:, width:, height:}`
+- **`disabled` field** — added to Element struct
+- **Scoping (`within`)** — `Selector#within(element, &block)` with `TansParser::ScopedSelector`:
+  - `get_by_role`, `get_by_text`, `find_text` restricted to element's bounding box
+  - All convenience methods (singular + plural) available inside scope
+  - Works with or without block
+- **Button detection** — now skips checkbox markers (`[x]`, `[X]`, `[*]`, `[ ]`) and underscore-only brackets
+- 105 new tests, 100% line and branch coverage maintained (300 total)
+
 ## 0.1.1
 
 - `TansParser::Element` — value object for recognized UI elements (role, text, position, size, colors)

data/README.md

@@ -1,6 +1,7 @@
 # tans-parser
 
 Parse raw terminal output with ANSI escape sequences into structured, queryable data.
+Recognizes UI elements heuristically for AI-driven terminal interaction.
 
 ## Installation
 
@@ -36,9 +37,12 @@ state = TansParser::State.new(state_data)
 state.plain_text
 # => "ERROR: Something went wrong\nOK: All good"
 
-# Search for text
-state.find_text("ERROR")
-# => [{row: 0, col: 0, text: "ERROR", full_line: "ERROR: Something went wrong"}]
+# Text search — three match modes
+state.find_text("ERROR")                        # :partial (default) — substring
+state.find_text("ERROR", match: :exact)         # :exact — row text must equal
+state.find_text("\\d+", match: :regex)          # :regex — compile string to Regexp
+state.find_text(/\d{3}/)                        # Regexp object also supported
+# => [{row:, col:, text:, full_line:}, ...]
 
 # Cell-level queries
 state.foreground_at(0, 0)  # => "red"
@@ -74,34 +78,153 @@ xterm_256(16)                   # => [0x00, 0x00, 0x00]
 state = TansParser::State.new(state_data)
 selector = TansParser::Selector.new(state)
 
-# Find UI elements by role
-selector.buttons      # => [Element, ...] — [ OK ], (Cancel), <Submit>
-selector.checkboxes   # => [Element, ...] — [x], [*], [ ] at line starts
-selector.dialogs      # => [Element, ...] — box-drawing character regions (┌─┐│└┘)
-selector.statusbars   # => [Element, ...] — bottom row with non-default background
-selector.progress_bars # => [Element, ...] — [####   ], [====>  ] patterns
+# Find UI elements by role (plural — returns Array)
+selector.buttons       # [ OK ], (Cancel), <Submit>
+selector.checkboxes    # [x], [*], [ ] at line starts
+selector.inputs        # [________] underscore-filled brackets
+selector.labels        # Name: patterns (text followed by colon)
+selector.menus         # Menu bars (row 0–1) and > dropdown items
+selector.tabs          # Closely-spaced [Tab1] [Tab2] brackets
+selector.dialogs       # Box-drawing character regions (┌─┐│└┘)
+selector.statusbars    # Bottom row with non-default background
+selector.progress_bars # [####   ], [====>  ] patterns
+
+# Singular convenience methods — return Element or nil
+selector.button                   # first button
+selector.checkbox(text: "Save")   # first matching checkbox
+selector.input                    # first input
+selector.dialog                   # first dialog
+selector.tab                      # first tab
+# ... label, menu, statusbar, progress_bar
+```
+
+### Element filtering
+
+```ruby
+# get_by_role with optional filters
+selector.get_by_role(:button, text: "OK")          # text filter (partial match)
+selector.get_by_role(:checkbox, checked: true)     # checked state filter
+selector.get_by_role(:button, disabled: false)     # disabled state filter
+
+# Combined filters
+selector.get_by_role(:checkbox, checked: true, text: "auto-save")
+
+# Plural methods also accept filters
+selector.checkboxes(checked: false)   # unchecked only
+selector.buttons(text: "Save")        # buttons with matching text
+```
+
+### Scoping (within)
 
-# Find by text or role
-selector.get_by_text("OK")       # partial match
-selector.get_by_role(:button)    # also accepts "button" (String)
+Restrict searches to an element's bounding box:
+
+```ruby
+dialog = selector.dialog
+
+# With block
+selector.within(dialog) do |scope|
+  scope.buttons       # only buttons inside the dialog
+  scope.find_text("OK")
+  scope.button        # singular — first button inside dialog
+end
+
+# Without block — returns ScopedSelector
+scoped = selector.within(dialog)
+scoped.get_by_role(:button)
+scoped.find_text("Retry", match: :exact)
 ```
 
-Each `TansParser::Element` is a Struct:
+### Custom role registration
+
+When heuristic detection fails, annotate grid regions manually:
+
+```ruby
+state = TansParser::State.new(state_data)
+
+# Annotate a dialog that heuristics didn't recognize
+state.annotate_role(:dialog, row: 5, col: 20, width: 28, height: 5, text: "Help")
+state.annotate_role(:statusbar, row: 24, col: 0, width: 80, height: 1)
+
+# Selector picks up annotations alongside auto-detected elements
+selector = TansParser::Selector.new(state)
+selector.dialogs     # => includes annotated dialog
+selector.statusbars  # => includes annotated statusbar
+
+# Annotations accept extra attributes
+state.annotate_role(:button, row: 0, col: 0, width: 6, height: 1,
+                    text: "Submit", fg: "green", disabled: false)
+```
+
+### State comparison (diff)
+
+Compare two terminal states cell-by-cell:
+
+```ruby
+before = TansParser::State.new(state_data)
+# ... some action changes the screen ...
+after = TansParser::State.new(new_state_data)
+
+# Full diff — compares all cell keys
+diff = before.diff(after)
+# => [{row: 3, col: 2, before: {char: "T", fg: "default", ...},
+#                        after:  {char: "X", fg: "default", ...}}]
+
+# Chars-only diff — ignores color/style changes
+diff = before.diff(after, chars_only: true)
+# Only reports actual character differences
+
+# Accepts raw hash as argument
+diff = before.diff({size: {rows: 5, cols: 10}, cursor: {...}, rows: [...]})
+```
+
+### Element actions & attributes
+
+Each `TansParser::Element` is a Struct with data and action methods:
 
 ```ruby
 el = selector.buttons.first
-el.role    # => :button
-el.text    # => "OK"
-el.row     # => 1
-el.col     # => 2
-el.width   # => 4
-el.height  # => 1
-el.checked # => nil (für Checkboxen: true/false)
-el.fg      # => "default"
-el.bg      # => "default"
-el.to_h    # => {role: :button, text: "OK", row: 1, col: 2, ...}
+
+# Data attributes
+el.role      # => :button
+el.text      # => "OK"
+el.row       # => 1
+el.col       # => 2
+el.width     # => 4
+el.height    # => 1
+el.checked   # => true/false/nil
+el.focused   # => true/false/nil
+el.disabled  # => true/false/nil
+el.fg        # => "default"
+el.bg        # => "default"
+el.to_h      # => {role: :button, text: "OK", row: 1, col: 2, ...}
+
+# Predicates
+el.checked?   # => false (always boolean)
+el.disabled?  # => false (always boolean)
+
+# Geometry
+el.bounds     # => {row: 1, col: 2, width: 4, height: 1}
+
+# Actions — return descriptive hashes for AI consumption
+el.click            # => {action: :click, target: el, row: 1, col: 4}
+el.type("hello")    # => {action: :type, target: el, row: 1, col: 4, text: "hello"}
+el.press_key(:tab)  # => {action: :press_key, target: el, key: :tab}
 ```
 
+### Recognized element patterns
+
+| Role | Pattern | Example |
+|------|---------|---------|
+| `:button` | `[...]`, `(...)`, `<...>` | `[ OK ]`, `(Cancel)`, `<Submit>` |
+| `:checkbox` | `[x]`, `[*]`, `[X]`, `[ ]` + label | `[x] Enable logging` |
+| `:input` | `[_+]` inside brackets | `[________]` |
+| `:label` | `Word:` or `Multiple Words:` | `Project Name:` |
+| `:menu` | Menu bar (row 0–1, spaced words) or `> Item` | `File  Edit  Help`, `> New File` |
+| `:tab` | ≥2 closely-spaced `[...]` on one row | `[Tab1] [Tab2] [Tab3]` |
+| `:dialog` | Unicode box-drawing borders | `┌──┐` `│  │` `└──┘` |
+| `:statusbar` | Last row with ≥3 non-default-bg cells | Inverse status line |
+| `:progress` | `[###...]` with `#`, `>`, `=`, `-` fill | `[#####     ]  50%` |
+
 ## Cell format
 
 Each cell is a Hash with these keys:

data/lib/tans-parser.rb

@@ -9,4 +9,5 @@ require_relative "tans_parser/ansi_parser"
 require_relative "tans_parser/ansi_utils"
 require_relative "tans_parser/element"
 require_relative "tans_parser/selector"
+require_relative "tans_parser/scoped_selector"
 require_relative "tans_parser/state"

data/lib/tans_parser/element.rb

@@ -10,8 +10,33 @@ module TansParser
     :checked,
     :focused,
     :fg, :bg,
+    :disabled,
     keyword_init: true,
   ) do
+    def checked?
+      !!checked
+    end
+
+    def disabled?
+      !!disabled
+    end
+
+    def bounds
+      { row: row, col: col, width: width, height: height }
+    end
+
+    def click
+      { action: :click, target: self, row: row, col: col + (width / 2) }
+    end
+
+    def type(text)
+      { action: :type, target: self, row: row, col: col + (width / 2), text: text }
+    end
+
+    def press_key(key)
+      { action: :press_key, target: self, key: key }
+    end
+
     def to_h
       {
         role: role,
@@ -21,6 +46,7 @@ module TansParser
         checked: checked,
         focused: focused,
         fg: fg, bg: bg,
+        disabled: disabled,
       }.compact
     end
   end

data/lib/tans_parser/scoped_selector.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module TansParser
+  # Scoped view of a terminal screen restricted to an element's bounding box.
+  # Created by Selector#within(element).
+  #
+  #   selector.within(dialog) do |scope|
+  #     scope.buttons       # only buttons inside the dialog
+  #     scope.find_text("OK")
+  #   end
+  class ScopedSelector
+    attr_reader :element
+
+    def initialize(selector, element)
+      @selector = selector
+      @element = element
+      @state = selector.state
+      @row_start = element.row
+      @row_end = element.row + element.height - 1
+      @col_start = element.col
+      @col_end = element.col + element.width - 1
+    end
+
+    # Find elements by role, scoped to the bounding box.
+    def get_by_role(role, text: nil, checked: nil, disabled: nil)
+      @selector.get_by_role(role, text: text, checked: checked, disabled: disabled)
+               .select { |e| fully_within?(e) }
+    end
+
+    # Find elements by visible text, scoped to the bounding box.
+    def get_by_text(text)
+      @selector.get_by_text(text)
+               .select { |e| fully_within?(e) }
+    end
+
+    # Search for text, scoped to the bounding box.
+    def find_text(pattern, match: :partial)
+      results = []
+      grid = @state.grid
+      max_row = [@row_end, grid.length - 1].min
+      max_col = [@col_end, grid[0].length - 1, 0].max
+
+      (@row_start..max_row).each do |r|
+        row = grid[r]
+        slice = row[@col_start..max_col]
+
+        row_text = slice.map { |c| c[:char] }.join
+        find_in_row(pattern, match, r, row_text, results)
+      end
+      results
+    end
+
+    # Convenience plural accessors
+    def buttons(**filters)    = get_by_role(:button, **filters)
+    def checkboxes(**filters) = get_by_role(:checkbox, **filters)
+    def dialogs(**filters)    = get_by_role(:dialog, **filters)
+    def inputs(**filters)     = get_by_role(:input, **filters)
+    def labels(**filters)     = get_by_role(:label, **filters)
+    def menus(**filters)      = get_by_role(:menu, **filters)
+    def tabs(**filters)       = get_by_role(:tab, **filters)
+    def statusbars(**filters) = get_by_role(:statusbar, **filters)
+    def progress_bars(**filters) = get_by_role(:progress, **filters)
+
+    # Convenience singular accessors
+    def button(**filters)    = buttons(**filters).first
+    def checkbox(**filters)  = checkboxes(**filters).first
+    def dialog(**filters)    = dialogs(**filters).first
+    def input(**filters)     = inputs(**filters).first
+    def label(**filters)     = labels(**filters).first
+    def menu(**filters)      = menus(**filters).first
+    def tab(**filters)       = tabs(**filters).first
+    def statusbar(**filters) = statusbars(**filters).first
+    def progress_bar(**filters) = progress_bars(**filters).first
+
+    private
+
+    def fully_within?(elem)
+      elem.row.between?(@row_start, @row_end) &&
+        elem.col >= @col_start &&
+        elem.col <= @col_end
+    end
+
+    # rubocop:disable Metrics/CyclomaticComplexity
+    def find_in_row(pattern, match, row_idx, row_text, results)
+      case match
+      when :partial
+        compiled = pattern.is_a?(Regexp) ? pattern : Regexp.new(Regexp.escape(pattern.to_s))
+        find_regex_in_text(compiled, row_idx, row_text, results)
+      when :exact
+        pattern_str = pattern.is_a?(Regexp) ? pattern.source : pattern.to_s
+        return unless row_text.strip == pattern_str
+
+        results << { row: row_idx, col: @col_start, text: row_text.rstrip, full_line: row_text }
+      when :regex
+        compiled = pattern.is_a?(Regexp) ? pattern : Regexp.new(pattern.to_s)
+        find_regex_in_text(compiled, row_idx, row_text, results)
+      else
+        raise ArgumentError, "unknown match mode: #{match.inspect}. Use :partial, :exact, or :regex"
+      end
+    end
+    # rubocop:enable Metrics/CyclomaticComplexity
+
+    def find_regex_in_text(compiled, row_idx, text, results)
+      pos = 0
+      begin
+        Timeout.timeout(State::TEXT_SEARCH_TIMEOUT) do
+          while (m = text.match(compiled, pos))
+            results << { row: row_idx, col: @col_start + m.begin(0), text: m[0], full_line: text }
+            pos = m.begin(0) + 1
+          end
+        end
+      rescue Timeout::Error
+        # Stop processing on timeout — return partial results
+      end
+    end
+  end
+end

data/lib/tans_parser/selector.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rubocop:disable Metrics/AbcSize, Metrics/ClassLength
+
 module TansParser
   # Scans terminal state for recognized UI elements.
   #
@@ -8,9 +10,10 @@ module TansParser
   #   selector.get_by_role(:button)    # => [Element, ...]
   #   selector.buttons                 # => [Element, ...]
   #   selector.dialogs                 # => [Element, ...]
+  #   selector.button(text: "OK")      # => Element or nil
   #
   class Selector
-    TOP_LEFT_CORNERS = /[┌┏┎┍]/
+    TOP_LEFT_CORNERS = /[┌┏┎┍╭╔╓╒]/
     BOTTOM_LEFT_CORNERS = %w[└ ┗ ┖ ┕ ╰ ╚].freeze
     BOTTOM_RIGHT_CORNERS = %w[┘ ┛ ┚ ┙ ╯ ╝].freeze
 
@@ -26,30 +29,99 @@ module TansParser
       @elements.select { |e| e.text&.include?(text) }
     end
 
-    # Find elements by role.
-    def get_by_role(role)
-      @elements.select { |e| e.role == role.to_sym }
+    # Find elements by role with optional filters.
+    # rubocop:disable Metrics/CyclomaticComplexity
+    def get_by_role(role, text: nil, checked: nil, disabled: nil)
+      results = @elements.select { |e| e.role == role.to_sym }
+      results = results.select { |e| e.text.to_s.include?(text.to_s) } if text
+      results = results.select { |e| e.checked == checked } unless checked.nil?
+      results = results.select { |e| e.disabled == disabled } unless disabled.nil?
+      results
+    end
+    # rubocop:enable Metrics/CyclomaticComplexity
+
+    # Convenience accessors (plural — return arrays)
+    def buttons(**filters)
+      get_by_role(:button, **filters)
+    end
+
+    def checkboxes(**filters)
+      get_by_role(:checkbox, **filters)
+    end
+
+    def dialogs(**filters)
+      get_by_role(:dialog, **filters)
+    end
+
+    def inputs(**filters)
+      get_by_role(:input, **filters)
+    end
+
+    def labels(**filters)
+      get_by_role(:label, **filters)
     end
 
-    # Convenience accessors
-    def buttons
-      get_by_role(:button)
+    def menus(**filters)
+      get_by_role(:menu, **filters)
     end
 
-    def checkboxes
-      get_by_role(:checkbox)
+    def tabs(**filters)
+      get_by_role(:tab, **filters)
     end
 
-    def dialogs
-      get_by_role(:dialog)
+    def statusbars(**filters)
+      get_by_role(:statusbar, **filters)
     end
 
-    def statusbars
-      get_by_role(:statusbar)
+    def progress_bars(**filters)
+      get_by_role(:progress, **filters)
     end
 
-    def progress_bars
-      get_by_role(:progress)
+    # Convenience accessors (singular — return first element or nil)
+    def button(**filters)
+      buttons(**filters).first
+    end
+
+    def checkbox(**filters)
+      checkboxes(**filters).first
+    end
+
+    def dialog(**filters)
+      dialogs(**filters).first
+    end
+
+    def input(**filters)
+      inputs(**filters).first
+    end
+
+    def label(**filters)
+      labels(**filters).first
+    end
+
+    def menu(**filters)
+      menus(**filters).first
+    end
+
+    def tab(**filters)
+      tabs(**filters).first
+    end
+
+    def statusbar(**filters)
+      statusbars(**filters).first
+    end
+
+    def progress_bar(**filters)
+      progress_bars(**filters).first
+    end
+
+    # Scope subsequent searches to a specific element's bounding box.
+    def within(element, &block)
+      scoped = ScopedSelector.new(self, element)
+      if block
+        yield scoped
+      else
+        scoped
+      end
     end
 
     private
@@ -60,16 +132,27 @@ module TansParser
 
     def scan
       results = []
+      results.concat(detect_tabs)
+      results.concat(detect_inputs)
       results.concat(detect_buttons)
       results.concat(detect_checkboxes)
       results.concat(detect_dialogs)
+      results.concat(detect_labels)
+      results.concat(detect_menus)
       results.concat(detect_statusbars)
       results.concat(detect_progress_bars)
+      results.concat(detect_annotations)
       results
     end
 
+    # Detects annotations: manually annotated roles from State#annotate_role
+    def detect_annotations
+      @state.annotations.map { |a| Element.new(a) }
+    end
+
     # Detects buttons: [ OK ], (Cancel), <Submit>
-    # rubocop:disable Metrics/AbcSize
+    # Skips underscore-only brackets (those are inputs).
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     def detect_buttons
       buttons = []
       grid.each_with_index do |row, r|
@@ -78,6 +161,8 @@ module TansParser
         scan_match.each do
           text = (::Regexp.last_match(1) || ::Regexp.last_match(2) || ::Regexp.last_match(3)).to_s.strip
           next if text.empty?
+          next if text.match?(/^_+$/)
+          next if text.match?(/^[ xX*]$/) # skip checkbox markers
 
           col = ::Regexp.last_match.begin(0)
           buttons << Element.new(
@@ -92,7 +177,7 @@ module TansParser
       end
       buttons
     end
-    # rubocop:enable Metrics/AbcSize
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
     # Detects checkboxes: [x], [*], [ ] at start of lines
     def detect_checkboxes
@@ -103,13 +188,13 @@ module TansParser
         next unless match
 
         checked = match[2] != " "
-        label = match[3].strip
+        label_text = match[3].strip
         col = match.begin(3)
         checkboxes << Element.new(
           role: :checkbox,
-          text: label,
+          text: label_text,
           row: r, col: col,
-          width: label.length, height: 1,
+          width: label_text.length, height: 1,
           checked: checked,
         )
       end
@@ -149,10 +234,13 @@ module TansParser
     # Returns the width of a dialog top border if valid, nil otherwise
     def dialog_top_width(line, tl_idx)
       top_row = line[tl_idx..]
-      tr_match = top_row.match(/^[┌┏┎┍]([─━]*)([┐┓┒┑])/)
-      return nil unless tr_match
+      # Find first top-right corner anywhere after the top-left corner.
+      # Allows text/titles in the top border (e.g. ╭─ Commands ─╮).
+      tr_idx = top_row.index(/[┐┓┒┑╮╗╖╕]/)
+      return nil unless tr_idx
+      return nil if tr_idx < 2 # minimum dialog width (corner + at least 1 char + corner)
 
-      tr_match[0].length
+      tr_idx + 1
     end
 
     # Returns the row index of a matching bottom border, nil if not found
@@ -182,29 +270,69 @@ module TansParser
       lines.join(" ").strip
     end
 
-    # Detects statusbar: bottom row with reversed/inverse colors
+    # Detects statusbar: bottom rows with reversed/inverse colors,
+    # or last row with substantial content even without background info.
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     def detect_statusbars
       bars = []
       return bars if grid.empty?
 
-      last_row_idx = grid.length - 1
-      last_row = grid[last_row_idx]
+      # Check last 2 rows for non-default background
+      [grid.length - 1, grid.length - 2].uniq.each do |row_idx|
+        next if row_idx.negative?
+
+        row = grid[row_idx]
+        non_default = row.reject { |c| c[:bg] == "default" }
+        text = row.map { |c| c[:char] }.join.strip
+        next if non_default.length < 3 || text.empty?
 
-      non_default = last_row.reject { |c| c[:bg] == "default" }
-      return bars if non_default.length < 3
+        bars << Element.new(
+          role: :statusbar, text: text,
+          row: row_idx, col: 0,
+          width: row.length, height: 1,
+          bg: non_default.first[:bg],
+        )
+        return bars
+      end
 
+      # Fallback: last row with substantial content (≥30 chars) but no bg info
+      last_row = grid[-1]
       text = last_row.map { |c| c[:char] }.join.strip
-      return bars if text.empty?
-
-      bars << Element.new(
-        role: :statusbar,
-        text: text,
-        row: last_row_idx, col: 0,
-        width: last_row.length, height: 1,
-        bg: non_default.first[:bg],
-      )
+      if text.length >= 30
+        bars << Element.new(
+          role: :statusbar, text: text,
+          row: grid.length - 1, col: 0,
+          width: last_row.length, height: 1,
+        )
+        return bars
+      end
+
+      # Scan all rows for separator-preceded footers (Karat-style)
+      # Footer row follows a row of mostly ─/━/═ characters
+      grid.each_with_index do |row, r|
+        next if r.zero?
+
+        prev_chars = grid[r - 1].map { |c| c[:char] }.join
+        non_space = prev_chars.gsub(" ", "")
+        next if non_space.empty?
+
+        sep_ratio = non_space.count("─━═").to_f / non_space.length
+        next if sep_ratio < 0.8
+
+        text = row.map { |c| c[:char] }.join.strip
+        next if text.empty?
+
+        bars << Element.new(
+          role: :statusbar, text: text,
+          row: r, col: 0,
+          width: row.length, height: 1,
+        )
+        return bars
+      end
+
       bars
     end
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
     # Detects progress bars: [####   ] or [=====>  ] patterns
     def detect_progress_bars
@@ -227,5 +355,116 @@ module TansParser
       end
       bars
     end
+
+    # Detects text inputs: [____] underscore-filled brackets
+    def detect_inputs
+      inputs = []
+      grid.each_with_index do |row, r|
+        line = row.map { |c| c[:char] }.join
+        line.enum_for(:scan, /\[(_+)\]/).each do
+          m = ::Regexp.last_match
+          col = m.begin(0)
+          inputs << Element.new(
+            role: :input,
+            text: "",
+            row: r, col: col,
+            width: m[0].length, height: 1,
+          )
+        end
+      end
+      inputs
+    end
+
+    # Detects labels: text followed by colon separator
+    def detect_labels
+      labels = []
+      grid.each_with_index do |row, r|
+        line = row.map { |c| c[:char] }.join
+        match = line.match(/\b([A-Za-z]\w*(?:\s+\w+)*\s*:)/)
+        next unless match
+
+        label_text = match[1].strip.sub(/:$/, "").strip
+        next if label_text.empty? || label_text.length < 2
+
+        col = match.begin(1)
+        labels << Element.new(
+          role: :label,
+          text: label_text,
+          row: r, col: col,
+          width: match[1].length, height: 1,
+        )
+      end
+      labels
+    end
+
+    # Detects menus: top-row menu bars and > dropdown items
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+    def detect_menus
+      menus = []
+      grid.each_with_index do |row, r|
+        line = row.map { |c| c[:char] }.join
+        stripped = line.strip
+        next if stripped.empty?
+
+        # Menu bar on first two rows: words separated by 2+ spaces
+        if r <= 1
+          items = stripped.split(/\s{2,}/)
+          if items.length >= 2 && items.all? { |i| i.match?(/^[A-Za-z]/) }
+            col = line.index(stripped)
+            menus << Element.new(
+              role: :menu,
+              text: items.join(" | "),
+              row: r, col: col || 0,
+              width: line.length, height: 1,
+            )
+          end
+        end
+
+        # Dropdown item: > prefix
+        line.enum_for(:scan, /(>\s*[A-Za-z][\w\s]*)/).each do
+          m = ::Regexp.last_match
+          menus << Element.new(
+            role: :menu,
+            text: m[0].sub(/^>\s*/, "").strip,
+            row: r, col: m.begin(0),
+            width: m[0].length, height: 1,
+          )
+        end
+      end
+      menus
+    end
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+    # Detects tabs: multiple closely-spaced [bracketed] items on one row
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    def detect_tabs
+      tabs = []
+      grid.each_with_index do |row, r|
+        line = row.map { |c| c[:char] }.join
+        matches = line.enum_for(:scan, /\[([^\]]+)\]/).map { ::Regexp.last_match }
+        next if matches.length < 2
+
+        gaps_close = matches.each_cons(2).all? { |a, b| b.begin(0) - a.end(0) <= 3 }
+        next unless gaps_close
+
+        matches.each do |m|
+          tab_text = m[1].strip
+          next if tab_text.empty? || tab_text.match?(/^_+$/)
+
+          cell = row[m.begin(0)]
+          focused = cell[:underline] || cell[:bg] != "default"
+          tabs << Element.new(
+            role: :tab,
+            text: tab_text,
+            row: r, col: m.begin(0),
+            width: m[0].length, height: 1,
+            focused: focused,
+          )
+        end
+      end
+      tabs
+    end
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
   end
 end
+# rubocop:enable Metrics/AbcSize, Metrics/ClassLength

data/lib/tans_parser/state.rb

@@ -8,7 +8,7 @@ module TansParser
   # Represents the parsed state of a terminal screen.
   # Provides high-level query methods for AI consumption.
   class State
-    attr_reader :rows, :cols, :grid, :cursor, :cursor_visible, :cursor_style, :mouse_mode, :mouse_format
+    attr_reader :rows, :cols, :grid, :cursor, :cursor_visible, :cursor_style, :mouse_mode, :mouse_format, :annotations
 
     def initialize(data)
       raise ArgumentError, "State data must include :size key" unless data[:size]
@@ -25,7 +25,18 @@ module TansParser
 
       @mouse_mode = data[:mouse_mode] || :none
       @mouse_format = data[:mouse_format] || :normal
+
+      @annotations = data[:annotations] || []
+    end
+
+    # Annotate a region of the terminal with a semantic role.
+    # These annotations are picked up by Selector during element recognition.
+    # rubocop:disable Metrics/ParameterLists
+    def annotate_role(role, row:, col:, width: 1, height: 1, text: nil, **extra)
+      @annotations << { role: role.to_sym, row: row, col: col,
+                        width: width, height: height, text: text, }.merge(extra)
     end
+    # rubocop:enable Metrics/ParameterLists
 
     # Get plain text of the entire terminal (no ANSI)
     def plain_text
@@ -41,32 +52,29 @@ module TansParser
 
     # Search for text across the entire terminal.
     # For regex patterns, matching is bounded by a timeout to prevent ReDoS.
+    #
+    #   state.find_text("hello")                  # partial match (default)
+    #   state.find_text("hello", match: :exact)   # exact row match
+    #   state.find_text("\\d+", match: :regex)    # regex from string
+    #   state.find_text(/\\d{3}/)                 # Regexp object (partial mode)
+    #
+    # Returns [{ row:, col:, text:, full_line: }, ...].
+    # +text+ is the actual matched substring (for Regexp/:regex mode)
+    # or the pattern string (for :partial/:exact with String).
     TEXT_SEARCH_TIMEOUT = 5
 
-    def find_text(pattern)
-      results = []
-      is_regex = pattern.is_a?(Regexp)
+    def find_text(pattern, match: :partial)
+      unless %i[partial exact regex].include?(match)
+        raise ArgumentError, "unknown match mode: #{match.inspect}. Use :partial, :exact, or :regex"
+      end
 
-      @grid.each_with_index do |row, ri|
-        text = row.map { |c| c[:char] }.join
-        pos = 0
-        begin
-          if is_regex
-            Timeout.timeout(TEXT_SEARCH_TIMEOUT) do
-              while (match = text.index(pattern, pos))
-                results << { row: ri, col: match, text: pattern.to_s, full_line: text }
-                pos = match + 1
-              end
-            end
-          else
-            while (match = text.index(pattern, pos))
-              results << { row: ri, col: match, text: pattern, full_line: text }
-              pos = match + 1
-            end
-          end
-        rescue Timeout::Error
-          # Stop processing on timeout — return partial results
-        end
+      results = []
+      case match
+      when :exact
+        find_text_exact(pattern, results)
+      else
+        compiled = compile_pattern(pattern, match)
+        find_text_with_regex(compiled, results)
       end
       results
     end
@@ -115,6 +123,32 @@ module TansParser
       }
     end
 
+    DEFAULT_CELL = { char: " ", fg: "default", bg: "default",
+                     bold: false, italic: false, underline: false, blink: false, }.freeze
+
+    # Compare this state with another State and return cell-level differences.
+    # With chars_only: true, only differences in the :char key are reported.
+    # Use ignore_rows: to skip specific rows (e.g. cursor/prompt lines).
+    def diff(other_state, chars_only: false, ignore_rows: [])
+      other = other_state.is_a?(State) ? other_state : State.new(other_state)
+      max_rows = [@rows, other.rows].max
+      max_cols = [@cols, other.cols].max
+      results = []
+
+      (0...max_rows).each do |r|
+        next if ignore_rows.include?(r)
+
+        (0...max_cols).each do |c|
+          a = cell_at(r, c)
+          b = other.send(:cell_at, r, c)
+          next if chars_only ? a[:char] == b[:char] : a == b
+
+          results << { row: r, col: c, before: a, after: b }
+        end
+      end
+      results
+    end
+
     private
 
     def extract_highlights
@@ -143,6 +177,48 @@ module TansParser
       end
       highlights
     end
+
+    def compile_pattern(pattern, match)
+      return pattern if pattern.is_a?(Regexp)
+
+      source = match == :regex ? pattern.to_s : Regexp.escape(pattern.to_s)
+      Regexp.new(source)
+    end
+
+    def find_text_exact(pattern, results)
+      pattern_str = pattern.is_a?(Regexp) ? pattern.source : pattern.to_s
+      @grid.each_with_index do |row, ri|
+        row_text = row.map { |c| c[:char] }.join.rstrip
+        next unless row_text == pattern_str
+
+        results << { row: ri, col: 0, text: row_text, full_line: row_text }
+      end
+    end
+
+    def find_text_with_regex(compiled, results)
+      @grid.each_with_index do |row, ri|
+        text = row.map { |c| c[:char] }.join
+        pos = 0
+        begin
+          Timeout.timeout(TEXT_SEARCH_TIMEOUT) do
+            while (m = text.match(compiled, pos))
+              results << { row: ri, col: m.begin(0), text: m[0], full_line: text }
+              pos = m.begin(0) + 1
+            end
+          end
+        rescue Timeout::Error
+          # Stop processing on timeout — return partial results
+        end
+      end
+    end
+
+    def cell_at(row, col)
+      if row < @rows && col < @cols
+        @grid[row][col]
+      else
+        DEFAULT_CELL
+      end
+    end
   end
 end
 # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity

data/lib/tans_parser/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TansParser
-  VERSION = "0.1.1"
+  VERSION = "0.1.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tans-parser
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Haluk Durmus
@@ -139,6 +139,7 @@ files:
 - lib/tans_parser/ansi_parser.rb
 - lib/tans_parser/ansi_utils.rb
 - lib/tans_parser/element.rb
+- lib/tans_parser/scoped_selector.rb
 - lib/tans_parser/selector.rb
 - lib/tans_parser/state.rb
 - lib/tans_parser/version.rb