tui-td 0.2.4 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97ed62eebe255ca568235b0ffe8bb428812d0dbc0408e24e768d76e8b11beb8a
-  data.tar.gz: 8b66334f5408398dab8dcf02535e8473c2d9af7357f4fc1db45bc67ca792706c
+  metadata.gz: 2716bc85090a6430068ad8820f9736657a3f122571999e34c39529060f59d487
+  data.tar.gz: b73ff229c0396a87a5121b43ff81edf65be1f13de1aed58a7404cd263a0ba84e
 SHA512:
-  metadata.gz: 404c5b2c0c411b25846855d0d5ad297493be90672ee3eba53980df429ec1263170b605d023983a4fbc17c2b4563b10ff91c98324a08651cf0997d4a9cde21667
-  data.tar.gz: 5b73ca7cccaa81b434ca418e5f246573033ac5abd6c18b7094adad6f65d8fa453be2e8c84d842f2ba82e182a9189989a2389599874e1ab9448606db30677d901
+  metadata.gz: be25c3cfca1b280dacc7a2b968c887de55fce953e1c9903dd725d1291b34918375771eec7324522407ef783c2fc9010f0ef69b2e7c5fccc142bf6b2bd1396f40
+  data.tar.gz: 0ee80ad5882c21763241f39c781a03a30180baf04707f7af5652bd913254b69c647efa59b06c57ff534b8b797a188adfaf40068f37956cad08b33a4cbc28cae0

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # CHANGELOG
 
+## 0.2.6
+
+- ISO-2022 charset switching support (G0/G1 designators, Shift Out/In) with DEC Special Character & Line Drawing mapping
+- SGR mouse reporting mode parsing (1000, 1002, 1003, 1006)
+- Mouse reporting and cursor visibility/style reconstruction in build_frame
+- Fixed `state_data` in `driver.rb` to unconditionally refresh terminal state instead of returning stale cache
+- New `cursor_visible`, `cursor_style`, `mouse_mode`, `mouse_format` attributes on `State`
+- HTML and screenshot styling for new cursor/mouse attributes
+
+## 0.2.5
+
+- MCP smoke test expanded: 20 → 54 assertions, covers all 10 tools plus error paths (88% server coverage)
+- Extracted `ansi_utils.rb` — shared ANSI helpers used by parser, renderer, and screenshot
+- New RSpec specs for `ansi_utils`, enhanced specs for `test_runner`, `html_renderer`, `matchers`, `state`, `ansi_parser`
+
 ## 0.2.4
 
 - `assert_regex` JSON test step — match terminal output against a Ruby regex

data/README.md

@@ -1,57 +1,23 @@
 # TUI Test Drive
 
-*Like Playwright or Puppeteer, but built specifically for Terminal UIs and optimized for AI Coding Agents.*
-
 Testing framework for Terminal User Interfaces (TUIs) with MCP support.
 
-A Ruby library, but language-agnostic through its JSON test format and MCP server — use it from Python, JavaScript, Go, or any other programming language on Linux and macOS.
-
 **tui-td** lets you:
 1. Start a TUI application in a virtual terminal (PTY)
 2. See the output — as structured JSON, plain text, PNG screenshots, or HTML renders
 3. Send input — keystrokes, text, control sequences
 4. Analyze output — find text, check colors, detect cursor position
 5. Loop — adjust and retest without manual intervention
-6. Integrate — works with any language via JSON test files or MCP
 
 ## Installation
 
-### 1. Install Ruby
-
-**rbenv (recommended):**
-
-```bash
-# macOS
-brew install rbenv ruby-build
-echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
-
-# Linux
-git clone https://github.com/rbenv/rbenv.git ~/.rbenv
-git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
-echo 'eval "$(~/.rbenv/bin/rbenv init - bash)"' >> ~/.bashrc
-```
-
-Then install Ruby 3 and activate it:
-
-```bash
-rbenv install 3.4.1
-rbenv global 3.4.1
-ruby --version  # must show 3.0+
-```
-
-**Alternative — Homebrew (macOS):**
-
-```bash
-brew install ruby
-```
-
-### 2. Install tui-td
+Ruby 3.0+ is required. Install via [rbenv](https://github.com/rbenv/rbenv#installation) or `brew install ruby`.
 
 ```bash
 gem install tui-td
 ```
 
-### 3. Test
+Quick test:
 
 ```bash
 tui-td capture "echo Hello World"
@@ -124,20 +90,20 @@ Interactive commands (drive mode):
   exit               Quit drive mode
 
 Global options:
-  -r, --rows N          Terminal rows (default: 40)
-  -c, --cols N          Terminal cols (default: 120)
-  -t, --timeout N       Timeout in seconds (default: 30)
-  -C, --chdir PATH      Working directory for the command
-  --screenshot PATH     Save PNG screenshot
-  --html PATH           Save HTML render for browser viewing
-  --json                Output state as compact JSON (includes raw ANSI)
-  --pretty              Output state as pretty JSON
-  --text                Output state as plain text table
-  -v, --verbose         Show each test step as it runs
-  -l, --live            Show terminal state after each test step (screen-refresh)
-  -s, --step            Pause after each test step for confirmation
-  --version             Show version
-  -h, --help            Show complete reference
+    -r, --rows N                     Terminal rows (default: 40)
+    -c, --cols N                     Terminal cols (default: 120)
+    -t, --timeout SECONDS            Timeout in seconds (default: 30)
+    -C, --chdir PATH                 Working directory for the command
+        --screenshot PATH            Save screenshot (e.g., output.png)
+        --html PATH                  Save HTML render (e.g., output.html)
+        --json                       Output state as compact JSON
+        --pretty                     Output state as pretty JSON
+        --text                       Output state as plain text table
+    -v, --verbose                    Show each test step as it runs
+    -l, --live                       Show terminal state after each step (screen-refresh)
+    -s, --step                       Pause after each test step for confirmation
+        --version                    Show version
+    -h, --help                       Show help
 ```
 
 `tui-td --help` serves as the full CLI reference. `tui-td help test` shows all JSON test
@@ -271,12 +237,18 @@ tui-td test examples/echo_test.json
   "rows": 24,
   "cols": 80,
   "timeout": 10,
+  "chdir": "/path/to/project",
+  "before_all": [
+    { "start": "my_tui_app", "env": { "DATABASE_URL": "test://" } }
+  ],
   "steps": [
-    { "start": "my_tui_app" },
     { "wait_for_text": "> " },
     { "send": "hello\n" },
     { "assert_text": "hello" },
-    { "assert_fg": [0, 0], "is": "cyan" },
+    { "assert_regex": "hello|world" },
+    { "assert_fg": [0, 0], "is": "cyan" }
+  ],
+  "after_all": [
     { "close": true }
   ]
 }
@@ -371,9 +343,11 @@ end
 | Matcher | Usage |
 |---------|-------|
 | `have_text("...")` | Assert text is present on screen |
+| `have_regex(/pattern/)` | Assert regex pattern matches anywhere |
 | `have_fg("color").at(row, col)` | Assert foreground color at position |
 | `have_bg("color").at(row, col)` | Assert background color at position |
 | `have_style.at(row, col).with(bold: true, ...)` | Assert cell style |
+| `have_exit_status(N)` | Assert the driver process exit status equals N |
 
 ## MCP Server — AI Integration
 

data/lib/tui_td/ansi_parser.rb

@@ -80,20 +80,73 @@ module TUITD
       15 => "bright_white",
     }.freeze
 
+    DEC_MAP = {
+      '`' => '◆',
+      'a' => '▒',
+      'b' => "\u2409",
+      'c' => "\u240C",
+      'd' => "\u240D",
+      'e' => "\u240A",
+      'f' => '°',
+      'g' => '±',
+      'h' => "\u2424",
+      'i' => "\u240B",
+      'j' => '┘',
+      'k' => '┐',
+      'l' => '┌',
+      'm' => '└',
+      'n' => '┼',
+      'o' => '⎺',
+      'p' => '⎻',
+      'q' => '─',
+      'r' => '⎼',
+      's' => '⎽',
+      't' => '├',
+      'u' => '┤',
+      'v' => '┴',
+      'w' => '┬',
+      'x' => '│',
+      'y' => '≤',
+      'z' => '≥',
+      '{' => 'π',
+      '|' => '≠',
+      '}' => '£',
+      '~' => '·'
+    }.freeze
+
     # Parse raw terminal output into a structured state Hash
     def self.parse(raw, rows = 40, cols = 120)
       grid = Array.new(rows) do
-        Array.new(cols) do
-          { char: " ", fg: "default", bg: "default", bold: false, italic: false, underline: false }
-        end
+        Array.new(cols) { default_cell.dup }
       end
 
       cursor = { row: 0, col: 0 }
-      attrs = { fg: "default", bg: "default", bold: false, italic: false, underline: false }
+      attrs = { fg: "default", bg: "default", bold: false, italic: false, underline: false, blink: false }
       saved_cursor = nil
-      scroll_region = nil
+      scroll_region = { top: 0, bottom: rows - 1 }
       pending_dsr = false
 
+      normal_grid = grid
+      alt_grid = nil
+
+      normal_cursor = cursor
+      alt_cursor = { row: 0, col: 0 }
+
+      normal_saved_cursor = nil
+      alt_saved_cursor = nil
+
+      use_alt_screen = false
+
+      cursor_visible = true
+      cursor_style = 1 # 1 = blinking block (default)
+
+      g0_charset = :ascii
+      g1_charset = :dec
+      active_charset = :g0
+
+      mouse_mode = :none
+      mouse_format = :normal
+
       # Strip everything before the last full clear (if any)
       # to avoid accumulated garbage
       processed = raw
@@ -103,12 +156,77 @@ module TUITD
         if processed[i] == "\e" && processed[i + 1] == "["
           # Find end of CSI sequence
           j = i + 2
-          j += 1 while j < processed.length && !processed[j].match?(/[A-HJ-KP-SX@`fhlmnR]/)
+          j += 1 while j < processed.length && !processed[j].match?(/[A-HJ-KP-SX@\`fhlmnRrsuq]/)
           seq = processed[i..j]
 
-          dsr = _apply_csi(seq, cursor, attrs, grid, rows, cols)
+          dsr, new_saved, action = _apply_csi(seq, cursor, attrs, grid, rows, cols, saved_cursor, scroll_region)
           pending_dsr ||= dsr
 
+          if new_saved
+            if use_alt_screen
+              alt_saved_cursor = new_saved
+              saved_cursor = alt_saved_cursor
+            else
+              normal_saved_cursor = new_saved
+              saved_cursor = normal_saved_cursor
+            end
+          end
+
+          if action.key?(:alt_screen)
+            new_alt = action[:alt_screen]
+            code = action[:alt_screen_code]
+            if new_alt != use_alt_screen
+              if new_alt
+                # Switch to Alternate Screen
+                # Save normal cursor
+                normal_cursor = { row: cursor[:row], col: cursor[:col] }
+
+                # Lazy initialize alt grid
+                alt_grid ||= Array.new(rows) do
+                  Array.new(cols) { default_cell.dup }
+                end
+
+                # For \e[?1049h, clear alternate screen and reset cursor to 0,0
+                if code == 1049
+                  alt_grid = Array.new(rows) do
+                    Array.new(cols) { default_cell.dup }
+                  end
+                  alt_cursor = { row: 0, col: 0 }
+                end
+
+                grid = alt_grid
+                cursor = alt_cursor
+                saved_cursor = alt_saved_cursor
+                use_alt_screen = true
+              else
+                # Switch to Normal Screen
+                # Save alt cursor
+                alt_cursor = { row: cursor[:row], col: cursor[:col] }
+
+                grid = normal_grid
+                cursor = normal_cursor
+                saved_cursor = normal_saved_cursor
+                use_alt_screen = false
+              end
+            end
+          end
+
+          if action.key?(:cursor_visible)
+            cursor_visible = action[:cursor_visible]
+          end
+
+          if action.key?(:cursor_style)
+            cursor_style = action[:cursor_style]
+          end
+
+          if action.key?(:mouse_mode)
+            mouse_mode = action[:mouse_mode]
+          end
+
+          if action.key?(:mouse_format)
+            mouse_format = action[:mouse_format]
+          end
+
           i = j + 1
         elsif processed[i] == "\n" || processed[i] == "\r\n"
           cursor[:row] += 1
@@ -127,12 +245,39 @@ module TUITD
         elsif processed[i] == "\a"
           # Bell — ignore
           i += 1
+        elsif processed[i] == "\x0e"
+          active_charset = :g1
+          i += 1
+        elsif processed[i] == "\x0f"
+          active_charset = :g0
+          i += 1
         elsif processed[i] == "\e"
-          # Skip escape sequences:
-          #   CSI: \e[... (already handled above)
-          #   ISO 2022 charset: \e( B  \e) 0  etc. (3 chars total)
-          #   Other: just the ESC
-          if processed[i + 1] && processed[i + 1].match?(/[()*+\-.\/]/)
+          # Handle non-CSI escape sequences
+          if processed[i + 1] == "7"
+            # DECSC — Save Cursor
+            if use_alt_screen
+              alt_saved_cursor = { row: cursor[:row], col: cursor[:col] }
+              saved_cursor = alt_saved_cursor
+            else
+              normal_saved_cursor = { row: cursor[:row], col: cursor[:col] }
+              saved_cursor = normal_saved_cursor
+            end
+            i += 2
+          elsif processed[i + 1] == "8"
+            # DECRC — Restore Cursor
+            if saved_cursor
+              cursor[:row] = saved_cursor[:row]
+              cursor[:col] = saved_cursor[:col]
+            end
+            i += 2
+          elsif processed[i + 1] == "(" && (processed[i + 2] == "0" || processed[i + 2] == "B")
+            g0_charset = (processed[i + 2] == "0" ? :dec : :ascii)
+            i += 3
+          elsif processed[i + 1] == ")" && (processed[i + 2] == "0" || processed[i + 2] == "B")
+            g1_charset = (processed[i + 2] == "0" ? :dec : :ascii)
+            i += 3
+          elsif processed[i + 1] && processed[i + 1].match?(/[()*+\-.\/]/)
+            # Other ISO 2022 charset sequences (e.g. G2/G3 or other charsets)
             i += 3
           else
             i += 1
@@ -141,7 +286,12 @@ module TUITD
           # Printable character (including multi-byte UTF-8)
           if cursor[:row] < rows && cursor[:col] < cols
             cell = grid[cursor[:row]][cursor[:col]]
-            cell[:char] = char
+            current_charset = (active_charset == :g1 ? g1_charset : g0_charset)
+            mapped_char = char
+            if current_charset == :dec && DEC_MAP.key?(char)
+              mapped_char = DEC_MAP[char]
+            end
+            cell[:char] = mapped_char
             cell.merge!(attrs)
             cursor[:col] += 1
             cursor[:col] = cols - 1 if cursor[:col] >= cols
@@ -151,22 +301,39 @@ module TUITD
           i += 1
         end
 
-        # Handle scrolling
-        if cursor[:row] >= rows
-          scroll_lines = cursor[:row] - rows + 1
-          grid.shift(scroll_lines)
-          scroll_lines.times do
-            grid << Array.new(cols) { { char: " ", fg: "default", bg: "default", bold: false, italic: false, underline: false } }
+        # Handle scrolling within the defined scroll region
+        region_top = scroll_region[:top]
+        region_bottom = scroll_region[:bottom]
+
+        if cursor[:row] > region_bottom
+          scroll_lines = [cursor[:row] - region_bottom, rows].min
+          # Shift lines within the scroll region up
+          (region_top..(region_bottom - scroll_lines)).each do |ri|
+            src = ri + scroll_lines
+            grid[ri] = src <= region_bottom ? grid[src] : Array.new(cols) { default_cell.dup }
+          end
+          # Fill bottom of scroll region with blank lines
+          ((region_bottom - scroll_lines + 1)..region_bottom).each do |ri|
+            grid[ri] = Array.new(cols) { default_cell.dup }
           end
-          cursor[:row] = rows - 1
+          cursor[:row] = region_bottom
         end
       end
 
       {
         size: { rows: rows, cols: cols },
-        cursor: cursor,
+        cursor: {
+          row: cursor[:row],
+          col: cursor[:col],
+          visible: cursor_visible,
+          style: cursor_style
+        },
         rows: grid,
         pending_dsr: pending_dsr,
+        cursor_visible: cursor_visible,
+        cursor_style: cursor_style,
+        mouse_mode: mouse_mode,
+        mouse_format: mouse_format
       }
     end
 
@@ -176,6 +343,8 @@ module TUITD
       cols = state.dig(:size, :cols) || state["size"]["cols"]
       grid = state[:rows] || state["rows"]
       cursor = state[:cursor] || state["cursor"]
+      mouse_mode = state[:mouse_mode] || state["mouse_mode"] || :none
+      mouse_format = state[:mouse_format] || state["mouse_format"] || :normal
 
       out = +""
       out << "\e[0m"
@@ -189,11 +358,13 @@ module TUITD
           bold = cell[:bold] || cell["bold"] || false
           italic = cell[:italic] || cell["italic"] || false
           underline = cell[:underline] || cell["underline"] || false
+          blink = cell[:blink] || cell["blink"] || false
 
           codes = []
           codes << "1" if bold
           codes << "3" if italic
           codes << "4" if underline
+          codes << "5" if blink
 
           fg_code = _color_code(fg, "38")
           bg_code = _color_code(bg, "48")
@@ -207,18 +378,53 @@ module TUITD
         out << "\n" if ri < rows - 1
       end
 
+      # Reconstruct cursor visibility
+      cursor_vis = true
+      if cursor.is_a?(Hash)
+        cursor_vis = cursor[:visible] != false && cursor["visible"] != false
+      end
+      out << (cursor_vis ? "\e[?25h" : "\e[?25l")
+
+      # Reconstruct cursor style
+      if cursor.is_a?(Hash)
+        style = cursor[:style] || cursor["style"]
+        out << "\e[#{style} q" if style
+      end
+
+      # Reconstruct mouse mode and format
+      if mouse_mode == :normal
+        out << "\e[?1000h"
+      elsif mouse_mode == :drag
+        out << "\e[?1002h"
+      elsif mouse_mode == :all
+        out << "\e[?1003h"
+      else
+        out << "\e[?1000l\e[?1002l\e[?1003l"
+      end
+
+      if mouse_format == :sgr
+        out << "\e[?1006h"
+      else
+        out << "\e[?1006l"
+      end
+
       out << "\e[0m"
       out
     end
 
-    def self._apply_csi(seq, cursor, attrs, grid, rows, cols)
+    def self._apply_csi(seq, cursor, attrs, grid, rows, cols, saved_cursor, scroll_region)
       # Strip leading escape char if present
       cleaned = seq.sub(/^\e/, "")
-      match = cleaned.match(/^\[([\d;]*)([A-HJ-KP-SX@`fhlmnR])$/)
-      return unless match
+      match = cleaned.match(/^\[(\??)([\d;]*)( ?)([A-HJ-KP-SX@\`fhlmnRrsuq])$/)
+      return [false, nil, {}] unless match
 
-      params = match[1].split(";").map(&:to_i)
-      command = match[2]
+      is_private = (match[1] == "?")
+      params = match[2].split(";").map(&:to_i)
+      space = match[3]
+      command = match[4]
+
+      new_saved = nil
+      action = {}
 
       case command
       when "m"
@@ -270,37 +476,102 @@ module TUITD
           next unless cursor[:row] < rows && cursor[:col] + i < cols
           grid[cursor[:row]][cursor[:col] + i][:char] = " "
         end
-      when "h", "l" # DEC private mode set/reset — skip (alternate screen, cursor show/hide, etc.)
-        nil
+      when "s" # DECSC — Save Cursor (CSI variant)
+        new_saved = { row: cursor[:row], col: cursor[:col] }
+      when "u" # DECRC — Restore Cursor (CSI variant)
+        if saved_cursor
+          cursor[:row] = saved_cursor[:row]
+          cursor[:col] = saved_cursor[:col]
+        end
+      when "r" # DECSTBM — Set Scroll Region
+        top = (params[0] || 1) - 1
+        bottom = (params[1] || rows) - 1
+        top = top.clamp(0, rows - 1)
+        bottom = bottom.clamp(0, rows - 1)
+        if top < bottom
+          scroll_region[:top] = top
+          scroll_region[:bottom] = bottom
+        else
+          scroll_region[:top] = 0
+          scroll_region[:bottom] = rows - 1
+        end
+        cursor[:row] = 0
+        cursor[:col] = 0
+      when "h"
+        if is_private
+          params.each do |p|
+            case p
+            when 47, 1047, 1049
+              action[:alt_screen] = true
+              action[:alt_screen_code] = p
+            when 25
+              action[:cursor_visible] = true
+            when 1000
+              action[:mouse_mode] = :normal
+            when 1002
+              action[:mouse_mode] = :drag
+            when 1003
+              action[:mouse_mode] = :all
+            when 1006
+              action[:mouse_format] = :sgr
+            end
+          end
+        end
+      when "l"
+        if is_private
+          params.each do |p|
+            case p
+            when 47, 1047, 1049
+              action[:alt_screen] = false
+              action[:alt_screen_code] = p
+            when 25
+              action[:cursor_visible] = false
+            when 1000, 1002, 1003
+              action[:mouse_mode] = :none
+            when 1006
+              action[:mouse_format] = :normal
+            end
+          end
+        end
+      when "q"
+        if space == " "
+          style_val = params[0] || 0
+          action[:cursor_style] = style_val
+        end
       when "n" # DSR — Device Status Report request
-        # \e[6n = request cursor position → caller must respond with \e[row;colR
-        return params[0] == 6
+        return [params[0] == 6, nil, {}]
       when "R" # DSR response (from terminal side) or CPR — ignore
         nil
       end
+
+      [false, new_saved, action]
     end
 
     def self._apply_sgr(params, attrs)
-      return attrs.merge!(fg: "default", bg: "default", bold: false, italic: false, underline: false) if params.empty? || params == [0]
+      return attrs.merge!(fg: "default", bg: "default", bold: false, italic: false, underline: false, blink: false) if params.empty? || params == [0]
 
       i = 0
       while i < params.length
         p = params[i]
         case p
         when 0
-          attrs.merge!(fg: "default", bg: "default", bold: false, italic: false, underline: false)
+          attrs.merge!(fg: "default", bg: "default", bold: false, italic: false, underline: false, blink: false)
         when 1
           attrs[:bold] = true
         when 3
           attrs[:italic] = true
         when 4
           attrs[:underline] = true
+        when 5, 6
+          attrs[:blink] = true
         when 22
           attrs[:bold] = false
         when 23
           attrs[:italic] = false
         when 24
           attrs[:underline] = false
+        when 25
+          attrs[:blink] = false
         when 7
           # Reverse — swap fg and bg
           attrs[:fg], attrs[:bg] = attrs[:bg], attrs[:fg]
@@ -397,21 +668,25 @@ module TUITD
     def self._color_code(name, prefix)
       case name
       when "default" then nil
-      when /^(bright_)?(.+)$/
-        base_name = $2
-        index = SGR_16_TO_NAME.key(base_name)
-        index += 8 if $1 && index && index < 8
-        index ? "#{prefix};5;#{index}" : nil
       when /^#([0-9a-fA-F]{6})$/
         r = $1[0..1].to_i(16)
         g = $1[2..3].to_i(16)
         b = $1[4..5].to_i(16)
         "#{prefix};2;#{r};#{g};#{b}"
+      when /^(bright_)?(.+)$/
+        base_name = $2
+        index = SGR_16_TO_NAME.key(base_name)
+        index += 8 if $1 && index && index < 8
+        index ? "#{prefix};5;#{index}" : nil
       else
         nil
       end
     end
 
+    def self.default_cell
+      { char: " ", fg: "default", bg: "default", bold: false, italic: false, underline: false, blink: false }
+    end
+
     # Extract a single UTF-8 character at position i in a binary string.
     # Returns [char_string, byte_length] or nil if the byte is not printable/valid.
     def self._utf8_char_at(str, i)