tty-command-window 0.1.0

data/lib/tty/command/window/emulator.rb

@@ -0,0 +1,613 @@
+# frozen_string_literal: true
+
+require "unicode/display_width"
+
+module TTY
+  class Command
+    module Window
+      # A VT100-subset terminal emulator with a fixed-size screen.
+      #
+      # The emulator maintains a +rows+ x +cols+ grid of cells (character +
+      # SGR attributes), interprets the escape sequences commonly emitted by
+      # CLI tools (cursor movement, erase, scroll regions, insert/delete,
+      # colors, alternate screen) and keeps a plain-text scrollback of lines
+      # that scroll off the top of the main screen.
+      #
+      # It is not thread-safe on its own; callers synchronize access.
+      class Emulator
+        BLANK = [" ", nil].freeze
+        WIDE_PLACEHOLDER = ["", nil].freeze
+        MAX_SEQUENCE = 512
+        TAB_STOP = 8
+
+        # Pre-allocated frozen single-char strings for every printable ASCII
+        # codepoint. The ASCII fast path in +scan+ reuses these instead of
+        # allocating a new String per printable byte (see P0-3).
+        ASCII_CHARS = (0x20..0x7E).map { |b| b.chr(Encoding::UTF_8).freeze }.freeze
+
+        attr_reader :rows, :cols, :cursor_row, :cursor_col, :scrollback
+
+        # @param rows [Integer] screen height in lines
+        # @param cols [Integer] screen width in columns
+        # @param scrollback_limit [Integer] max plain-text history lines kept
+        # @param responder [#call, nil] receives strings the terminal would
+        #   send back to the child (cursor position reports etc.)
+        def initialize(rows:, cols:, scrollback_limit: DEFAULT_SCROLLBACK, responder: nil)
+          @rows = rows
+          @cols = [cols, 1].max
+          @scrollback_limit = scrollback_limit
+          @responder = responder
+          @scrollback = []
+          @partial_input = (+"").force_encoding(Encoding::BINARY)
+          full_reset
+        end
+
+        # Feed a chunk of raw child output into the emulator. Handles UTF-8
+        # characters and escape sequences split across chunk boundaries.
+        #
+        # @param data [String]
+        def feed(data)
+          buffer = @partial_input + data.dup.force_encoding(Encoding::BINARY)
+          @partial_input = (+"").force_encoding(Encoding::BINARY)
+
+          tail = incomplete_utf8_tail(buffer)
+          if tail.positive?
+            @partial_input = buffer.byteslice(-tail, tail)
+            buffer = buffer.byteslice(0, buffer.bytesize - tail)
+          end
+
+          buffer.force_encoding(Encoding::UTF_8)
+          buffer = buffer.scrub("\u{FFFD}") unless buffer.valid_encoding?
+          scan(buffer)
+          invalidate_render_cache
+          nil
+        end
+
+        # Resize the screen width. Rows are fixed for the window's lifetime.
+        #
+        # @param cols [Integer]
+        def resize(cols:)
+          cols = [cols, 1].max
+          return if cols == @cols
+
+          @cols = cols
+          [@main_grid, @alt_grid].each do |grid|
+            grid.each { |row| resize_row(row, cols) }
+          end
+          @cursor_col = [@cursor_col, cols - 1].min
+          @pending_wrap = false
+          invalidate_render_cache
+        end
+
+        # @return [Boolean] whether the child requested a visible cursor
+        def cursor_visible?
+          @cursor_visible
+        end
+
+        # Render one screen row as an ANSI string (no trailing newline, no
+        # clear-to-eol; trailing unstyled blanks are stripped).
+        #
+        # @param index [Integer]
+        # @return [String]
+        def render_line(index)
+          row = @grid[index] or return ""
+          last = row.rindex { |cell| cell[0] != " " || cell[1] } or return ""
+
+          out = +""
+          current = false
+          row[0..last].each do |(char, sgr)|
+            if sgr != current
+              out << (sgr ? "\e[0;#{sgr}m" : "\e[0m")
+              current = sgr
+            end
+            out << char
+          end
+          out << "\e[0m" if current
+          out
+        end
+
+        # @return [Array<String>] every screen row rendered with ANSI colors
+        def render_lines
+          @render_lines ||= Array.new(@rows) { |i| render_line(i) }
+        end
+
+        # @return [Array<String>] plain-text content of the visible screen
+        def screen_text
+          @grid.map { |row| plain_row(row) }
+        end
+
+        # @return [String] scrollback plus visible screen as plain text
+        def full_text
+          (@scrollback + screen_text).join("\n").rstrip
+        end
+
+        private
+
+        def invalidate_render_cache
+          @render_lines = nil
+        end
+
+        # Scan the decoded UTF-8 buffer, taking an ASCII fast path when the
+        # parser is in ground state and the incoming bytes are printable
+        # ASCII (0x20-0x7E). Non-ASCII bytes and control/escape bytes fall
+        # through to the existing per-character state machine.
+        def scan(buffer)
+          bytes = buffer.b
+          len = bytes.bytesize
+          i = 0
+          while i < len
+            if @state == :ground
+              start = i
+              while i < len
+                b = bytes.getbyte(i)
+                break if b < 0x20 || b > 0x7E
+
+                i += 1
+              end
+              if i > start
+                put_ascii_run(bytes, start, i - start)
+                next
+              end
+            end
+
+            b = bytes.getbyte(i)
+            char_bytes = b < 0x80 ? 1 : expected_utf8_length(b)
+            char_bytes = len - i if i + char_bytes > len
+            char = bytes.byteslice(i, char_bytes).force_encoding(Encoding::UTF_8)
+            process(char)
+            i += char_bytes
+          end
+        end
+
+        # Write a run of printable ASCII bytes into the grid at the current
+        # cursor. Every byte is width-1, so the wide-cell logic in +put_char+
+        # can be skipped entirely; SGR attrs are hoisted out of the inner
+        # loop and printable-char strings come from a frozen table.
+        def put_ascii_run(bytes, offset, length)
+          attr = @sgr.to_params
+          j = 0
+          while j < length
+            wrap_if_pending
+            row = @grid[@cursor_row]
+            b = bytes.getbyte(offset + j)
+            char = ASCII_CHARS[b - 0x20]
+            cell = [char, attr]
+            row[@cursor_col] = cell
+            @last_cell = cell
+            if @cursor_col + 1 >= @cols
+              @cursor_col = @cols - 1
+              @pending_wrap = @autowrap
+            else
+              @cursor_col += 1
+            end
+            j += 1
+          end
+        end
+
+        def full_reset
+          @main_grid = Array.new(@rows) { blank_row }
+          @alt_grid = Array.new(@rows) { blank_row }
+          @grid = @main_grid
+          @alt_screen = false
+          @cursor_row = 0
+          @cursor_col = 0
+          @saved_cursor = [0, 0]
+          @pending_wrap = false
+          @autowrap = true
+          @cursor_visible = true
+          @scroll_top = 0
+          @scroll_bottom = @rows - 1
+          @sgr = ANSI::SGRState.new
+          @state = :ground
+          @sequence = +""
+          @last_cell = nil
+        end
+
+        def blank_row
+          Array.new(@cols) { BLANK }
+        end
+
+        def resize_row(row, cols)
+          if row.length > cols
+            row.slice!(cols..)
+          else
+            row.concat(Array.new(cols - row.length) { BLANK })
+          end
+        end
+
+        def plain_row(row)
+          row.map { |cell| cell[0] }.join.rstrip
+        end
+
+        # Number of bytes at the end of +buffer+ forming an incomplete UTF-8
+        # character, or 0 when the buffer ends on a character boundary.
+        def incomplete_utf8_tail(buffer)
+          (1..3).each do |back|
+            break if back > buffer.bytesize
+
+            byte = buffer.getbyte(buffer.bytesize - back)
+            next if byte < 0x80 # ASCII: complete
+            next if byte >= 0xC0 && back >= expected_utf8_length(byte) # lead byte, sequence fits
+            return back if byte >= 0xC0 # lead byte, sequence cut short
+
+            # continuation byte: keep looking further back
+          end
+          0
+        end
+
+        def expected_utf8_length(lead)
+          return 2 if lead < 0xE0
+          return 3 if lead < 0xF0
+
+          4
+        end
+
+        def process(char)
+          case @state
+          when :ground then process_ground(char)
+          when :escape then process_escape(char)
+          when :csi then process_csi(char)
+          when :osc, :dcs then process_string_sequence(char)
+          when :charset then @state = :ground
+          end
+        end
+
+        def process_ground(char)
+          case char
+          when "\e" then start_sequence(:escape)
+          when "\r"
+            @cursor_col = 0
+            @pending_wrap = false
+          when "\n", "\v", "\f" then index
+          when "\b"
+            @cursor_col = [@cursor_col - 1, 0].max
+            @pending_wrap = false
+          when "\t"
+            @cursor_col = [((@cursor_col / TAB_STOP) + 1) * TAB_STOP, @cols - 1].min
+            @pending_wrap = false
+          when "\a", "\x00", "\x0e", "\x0f"
+            # BEL / NUL / shift-in/out: ignore
+          else
+            put_char(char) if char >= " " || char.ord > 0x9f
+          end
+        end
+
+        def start_sequence(state)
+          @state = state
+          @sequence = +""
+        end
+
+        def process_escape(char)
+          case char
+          when "[" then start_sequence(:csi)
+          when "]" then start_sequence(:osc)
+          when "P", "^", "_" then start_sequence(:dcs)
+          when "(", ")", "*", "+" then @state = :charset
+          when "7"
+            save_cursor
+            @state = :ground
+          when "8"
+            restore_cursor
+            @state = :ground
+          when "D"
+            index
+            @state = :ground
+          when "M"
+            reverse_index
+            @state = :ground
+          when "E"
+            @cursor_col = 0
+            index
+            @state = :ground
+          when "c"
+            scrollback = @scrollback
+            full_reset
+            @scrollback = scrollback
+            @state = :ground
+          else
+            @state = :ground
+          end
+        end
+
+        def process_csi(char)
+          if char.between?("@", "~")
+            dispatch_csi(char, @sequence)
+            @state = :ground
+          elsif @sequence.length > MAX_SEQUENCE
+            @state = :ground
+          else
+            @sequence << char
+          end
+        end
+
+        def process_string_sequence(char)
+          if char == "\a" || (@sequence.end_with?("\e") && char == "\\")
+            @state = :ground
+          elsif char == "\e" || @sequence.length <= MAX_SEQUENCE
+            @sequence << char
+          end
+        end
+
+        def dispatch_csi(final, sequence)
+          private_marker = sequence.start_with?("?")
+          params = sequence.delete("?<=>! ").split(/[;:]/).map { |p| p.empty? ? nil : p.to_i }
+
+          case final
+          when "A" then move_cursor(-count(params), 0)
+          when "B", "e" then move_cursor(count(params), 0)
+          when "C", "a" then move_cursor(0, count(params))
+          when "D" then move_cursor(0, -count(params))
+          when "E"
+            @cursor_col = 0
+            move_cursor(count(params), 0)
+          when "F"
+            @cursor_col = 0
+            move_cursor(-count(params), 0)
+          when "G", "`" then set_cursor(@cursor_row, count(params) - 1)
+          when "d" then set_cursor(count(params) - 1, @cursor_col)
+          when "H", "f" then set_cursor((params[0] || 1) - 1, (params[1] || 1) - 1)
+          when "J" then erase_display(params[0] || 0)
+          when "K" then erase_line(params[0] || 0)
+          when "L" then insert_lines(bounded_count(params, @scroll_bottom - @cursor_row + 1))
+          when "M" then delete_lines(bounded_count(params, @scroll_bottom - @cursor_row + 1))
+          when "P" then delete_chars(bounded_count(params, @cols - @cursor_col))
+          when "@" then insert_chars(bounded_count(params, @cols - @cursor_col))
+          when "X" then erase_chars(bounded_count(params, @cols - @cursor_col))
+          when "S" then scroll_up(bounded_count(params, @scroll_bottom - @scroll_top + 1))
+          when "T" then scroll_down(bounded_count(params, @scroll_bottom - @scroll_top + 1))
+          when "m" then @sgr.apply(params.map { |p| p || 0 })
+          when "r" then set_scroll_region(params[0] || 1, params[1] || @rows)
+          when "s" then save_cursor
+          when "u" then restore_cursor
+          when "h" then set_mode(params, private_marker, true)
+          when "l" then set_mode(params, private_marker, false)
+          when "n" then device_status_report(params[0] || 0)
+          when "c" then respond("\e[?6c")
+          end
+        end
+
+        def count(params)
+          value = params[0] || 1
+          [value, 1].max
+        end
+
+        # Like +count+ but also clamped to a caller-supplied ceiling
+        # (typically screen geometry). Prevents adversarial CSI like
+        # +\e[999...9P+ from turning into an unbounded +amount.times+ loop
+        # inside +delete_chars+ / +scroll_up+ / friends (review P0-4, H6).
+        def bounded_count(params, ceiling)
+          n = count(params)
+          ceiling = 1 if ceiling < 1
+          [n, ceiling].min
+        end
+
+        def respond(text)
+          @responder&.call(text)
+        end
+
+        # --- cursor -------------------------------------------------------
+
+        def move_cursor(d_row, d_col)
+          @cursor_row = (@cursor_row + d_row).clamp(0, @rows - 1)
+          @cursor_col = (@cursor_col + d_col).clamp(0, @cols - 1)
+          @pending_wrap = false
+        end
+
+        def set_cursor(row, col)
+          @cursor_row = row.clamp(0, @rows - 1)
+          @cursor_col = col.clamp(0, @cols - 1)
+          @pending_wrap = false
+        end
+
+        def save_cursor
+          @saved_cursor = [@cursor_row, @cursor_col]
+        end
+
+        def restore_cursor
+          @cursor_row, @cursor_col = @saved_cursor
+          @cursor_row = @cursor_row.clamp(0, @rows - 1)
+          @cursor_col = @cursor_col.clamp(0, @cols - 1)
+          @pending_wrap = false
+        end
+
+        def index
+          if @cursor_row == @scroll_bottom
+            scroll_up(1)
+          else
+            @cursor_row = [@cursor_row + 1, @rows - 1].min
+          end
+        end
+
+        def reverse_index
+          if @cursor_row == @scroll_top
+            scroll_down(1)
+          else
+            @cursor_row -= 1
+          end
+        end
+
+        # --- writing ------------------------------------------------------
+
+        def put_char(char)
+          width = Unicode::DisplayWidth.of(char)
+
+          if width.zero?
+            @last_cell[0] += char if @last_cell && !@last_cell.frozen?
+            return
+          end
+
+          wrap_if_pending
+          if width == 2 && @cursor_col >= @cols - 1
+            @grid[@cursor_row][@cursor_col] = BLANK
+            if @autowrap
+              @cursor_col = 0
+              index
+            end
+          end
+
+          row = @grid[@cursor_row]
+          cell = [char, @sgr.to_params]
+          row[@cursor_col] = cell
+          @last_cell = cell
+          row[@cursor_col + 1] = WIDE_PLACEHOLDER if width == 2 && @cursor_col + 1 < @cols
+
+          advance = width
+          if @cursor_col + advance >= @cols
+            @cursor_col = @cols - 1
+            @pending_wrap = @autowrap
+          else
+            @cursor_col += advance
+          end
+        end
+
+        def wrap_if_pending
+          return unless @pending_wrap
+
+          @pending_wrap = false
+          @cursor_col = 0
+          index
+        end
+
+        # --- scrolling ----------------------------------------------------
+
+        def scroll_up(amount)
+          amount.times do
+            removed = @grid.slice!(@scroll_top)
+            push_scrollback(removed) if !@alt_screen && @scroll_top.zero?
+            @grid.insert(@scroll_bottom, blank_row)
+          end
+        end
+
+        def scroll_down(amount)
+          amount.times do
+            @grid.slice!(@scroll_bottom)
+            @grid.insert(@scroll_top, blank_row)
+          end
+        end
+
+        def push_scrollback(row)
+          return if @scrollback_limit <= 0
+
+          @scrollback << plain_row(row)
+          @scrollback.shift(@scrollback.length - @scrollback_limit) if
+            @scrollback.length > @scrollback_limit
+        end
+
+        def set_scroll_region(top, bottom)
+          top = top.clamp(1, @rows)
+          bottom = bottom.clamp(1, @rows)
+          return unless top < bottom
+
+          @scroll_top = top - 1
+          @scroll_bottom = bottom - 1
+          set_cursor(0, 0)
+        end
+
+        # --- erase / insert / delete ---------------------------------------
+
+        def erase_display(mode)
+          case mode
+          when 0
+            erase_line(0)
+            ((@cursor_row + 1)...@rows).each { |i| @grid[i] = blank_row }
+          when 1
+            erase_line(1)
+            (0...@cursor_row).each { |i| @grid[i] = blank_row }
+          when 2, 3
+            (0...@rows).each { |i| @grid[i] = blank_row }
+            @scrollback.clear if mode == 3
+          end
+        end
+
+        def erase_line(mode)
+          row = @grid[@cursor_row]
+          range =
+            case mode
+            when 0 then (@cursor_col...@cols)
+            when 1 then (0..@cursor_col)
+            else (0...@cols)
+            end
+          range.each { |i| row[i] = BLANK }
+        end
+
+        def insert_lines(amount)
+          return unless @cursor_row.between?(@scroll_top, @scroll_bottom)
+
+          amount.times do
+            @grid.slice!(@scroll_bottom)
+            @grid.insert(@cursor_row, blank_row)
+          end
+          @cursor_col = 0
+        end
+
+        def delete_lines(amount)
+          return unless @cursor_row.between?(@scroll_top, @scroll_bottom)
+
+          amount.times do
+            @grid.slice!(@cursor_row)
+            @grid.insert(@scroll_bottom, blank_row)
+          end
+          @cursor_col = 0
+        end
+
+        def delete_chars(amount)
+          row = @grid[@cursor_row]
+          amount.times do
+            row.delete_at(@cursor_col)
+            row << BLANK
+          end
+        end
+
+        def insert_chars(amount)
+          row = @grid[@cursor_row]
+          amount.times do
+            row.insert(@cursor_col, BLANK)
+            row.pop
+          end
+        end
+
+        def erase_chars(amount)
+          row = @grid[@cursor_row]
+          (@cursor_col...[@cursor_col + amount, @cols].min).each { |i| row[i] = BLANK }
+        end
+
+        # --- modes ----------------------------------------------------------
+
+        def set_mode(params, private_marker, enabled)
+          return unless private_marker
+
+          params.compact.each do |param|
+            case param
+            when 25 then @cursor_visible = enabled
+            when 7 then @autowrap = enabled
+            when 47, 1047, 1049 then switch_screen(enabled, save_state: param == 1049)
+            end
+          end
+        end
+
+        def switch_screen(alt, save_state:)
+          return if alt == @alt_screen
+
+          @alt_screen = alt
+          if alt
+            save_cursor if save_state
+            @alt_grid = Array.new(@rows) { blank_row }
+            @grid = @alt_grid
+            set_cursor(0, 0)
+          else
+            @grid = @main_grid
+            restore_cursor if save_state
+          end
+          @pending_wrap = false
+        end
+
+        def device_status_report(param)
+          case param
+          when 5 then respond("\e[0n")
+          when 6 then respond("\e[#{@cursor_row + 1};#{@cursor_col + 1}R")
+          end
+        end
+      end
+    end
+  end
+end