rubytui 1.2.3

data/lib/rubytui/backends/ansi_backend.rb

@@ -0,0 +1,391 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module RubyTUI
+  # {Backend} that drives a real terminal with ANSI escape sequences.
+  #
+  # Output accumulates in an internal string buffer and is written to the
+  # output IO only by {#flush}. {#enter_alternate_screen},
+  # {#leave_alternate_screen}, {#enable_mouse}, {#disable_mouse} and
+  # {#clear_all_images!} flush immediately.
+  #
+  # @see RubyTUI.init
+  class AnsiBackend
+    include Backend
+
+    # Control Sequence Introducer (<tt>ESC [</tt>) that prefixes escape sequences.
+    CSI = "\e["
+
+    # @param output [IO] stream escape sequences are written to (default: $stdout)
+    # @param input [IO] terminal input used for raw mode and cell-size queries
+    #   (default: $stdin)
+    def initialize(output: $stdout, input: $stdin)
+      @output = output
+      @input = input
+      @buffer = String.new(capacity: 4096)
+      @prev_style = nil
+      @original_state = nil
+      @next_image_id = 1
+      @image_id_map = {}
+      @cell_pixel_size = nil
+    end
+
+    # Append escape sequences for the changed cells to the output buffer.
+    #
+    # Emits a cursor move only where a cell does not directly follow the
+    # previous one, skips wide-character spacer cells (empty symbol), and
+    # appends an SGR reset at the end. Does nothing if +changes+ is empty.
+    # Does not flush.
+    #
+    # @param changes [Array<Array(Integer, Integer, Cell)>] changed cells as [x, y, cell]
+    # @return [void]
+    def draw(changes)
+      return if changes.empty?
+
+      last_x = -1
+      last_y = -1
+
+      changes.each do |x, y, cell|
+        # Skip spacer cells from wide characters
+        if cell.symbol.empty?
+          next
+        end
+
+        # Move cursor if not at expected position
+        unless x == last_x + 1 && y == last_y
+          @buffer << "#{CSI}#{y + 1};#{x + 1}H"
+        end
+
+        # Apply style
+        apply_style(cell.style)
+
+        # Write character
+        @buffer << cell.symbol
+
+        # Wide characters advance terminal cursor by 2
+        w = cell.symbol.length == 1 ? Buffer.char_width(cell.symbol) : 1
+        last_x = x + w - 1
+        last_y = y
+      end
+
+      # Reset style at end
+      @buffer << "#{CSI}0m"
+      @prev_style = nil
+    end
+
+    # Append the hide-cursor sequence (<tt>CSI ?25l</tt>) to the output buffer.
+    #
+    # @return [void]
+    def hide_cursor
+      @buffer << "#{CSI}?25l"
+    end
+
+    # Append the show-cursor sequence (<tt>CSI ?25h</tt>) to the output buffer.
+    #
+    # @return [void]
+    def show_cursor
+      @buffer << "#{CSI}?25h"
+    end
+
+    # Append a cursor-position sequence to the output buffer.
+    #
+    # @param x [Integer] zero-based column
+    # @param y [Integer] zero-based row
+    # @return [void]
+    def move_cursor(x, y)
+      @buffer << "#{CSI}#{y + 1};#{x + 1}H"
+    end
+
+    # Append the clear-screen sequence (<tt>CSI 2J</tt>) to the output buffer.
+    #
+    # @return [void]
+    def clear
+      @buffer << "#{CSI}2J"
+    end
+
+    # Switch to the alternate screen buffer (<tt>CSI ?1049h</tt>) and flush.
+    #
+    # @return [void]
+    def enter_alternate_screen
+      @buffer << "#{CSI}?1049h"
+      flush
+    end
+
+    # Switch back from the alternate screen buffer (<tt>CSI ?1049l</tt>) and flush.
+    #
+    # @return [void]
+    def leave_alternate_screen
+      @buffer << "#{CSI}?1049l"
+      flush
+    end
+
+    # Enable SGR extended mouse mode (button events + drag + scroll)
+    #
+    # Turns on modes 1000, 1002 and 1006, then flushes.
+    #
+    # @return [void]
+    def enable_mouse
+      @buffer << "#{CSI}?1000h"  # Enable button event tracking
+      @buffer << "#{CSI}?1002h"  # Enable button-event tracking with drag
+      @buffer << "#{CSI}?1006h"  # Enable SGR extended mode (for coords > 223)
+      flush
+    end
+
+    # Disable mouse event reporting
+    #
+    # Turns off modes 1006, 1002 and 1000, then flushes.
+    #
+    # @return [void]
+    def disable_mouse
+      @buffer << "#{CSI}?1006l"
+      @buffer << "#{CSI}?1002l"
+      @buffer << "#{CSI}?1000l"
+      flush
+    end
+
+    # Put the input into raw mode, saving its terminal state for {#disable_raw_mode}.
+    #
+    # Save the termios state of the SAME fd we are about to raw! — a backtick
+    # <tt>stty -g</tt> reads the process's stdin, which is the wrong fd (and often
+    # not a tty at all) when a custom input: IO such as File.open("/dev/tty")
+    # is used, e.g. a TUI launched from fzf execute() with output captured.
+    # A failed stty yields "" which is truthy, so it must collapse to nil or
+    # restore would run <tt>stty ""</tt> and leave the terminal stuck in raw mode.
+    #
+    # @return [void]
+    def enable_raw_mode
+      @original_state = begin
+        state = IO.popen(["stty", "-g"], in: @input, err: File::NULL, &:read).chomp
+        state.empty? ? nil : state
+      rescue StandardError
+        nil
+      end
+      @input.raw! if @input.respond_to?(:raw!)
+    end
+
+    # Restore the input's terminal state saved by {#enable_raw_mode}.
+    #
+    # Runs +stty+ with the saved state on the input. Falls back to
+    # +cooked!+ (when the input supports it) if no state was saved or
+    # +stty+ raises.
+    #
+    # @return [void]
+    def disable_raw_mode
+      if @original_state
+        begin
+          system("stty", @original_state, in: @input, err: File::NULL)
+        rescue StandardError
+          @input.cooked! if @input.respond_to?(:cooked!)
+        end
+        @original_state = nil
+      elsif @input.respond_to?(:cooked!)
+        @input.cooked!
+      end
+    end
+
+    # Get the output terminal size.
+    #
+    # @return [Array(Integer, Integer)] [width, height] in cells, or [80, 24]
+    #   if the size cannot be read from the output
+    def size
+      rows, cols = @output.winsize
+      [cols, rows]
+    rescue Errno::ENOTTY, Errno::ENODEV, NoMethodError
+      [80, 24]
+    end
+
+    # Query the terminal for cell pixel dimensions.
+    #
+    # Sends CSI 16 t and parses the response. Must be called before
+    # entering raw mode or while in raw mode with careful stdin handling.
+    # Falls back to [9, 18] when the terminal does not answer within 100 ms
+    # or the query raises +IOError+, +Errno::EIO+ or +Errno::ENOTTY+; the
+    # result, including the fallback, is cached.
+    #
+    # @return [Array(Integer, Integer)] cell dimensions [width_px, height_px]
+    def query_cell_pixel_size
+      return @cell_pixel_size if @cell_pixel_size
+
+      begin
+        @input.raw do
+          @output.write("\e[16t")
+          @output.flush
+
+          response = +""
+          deadline = Time.now + 0.1
+
+          while Time.now < deadline
+            if IO.select([@input], nil, nil, 0.01)
+              char = @input.read_nonblock(1, exception: false)
+              break if char == :wait_readable || char.nil?
+              response << char
+              break if char == "t"
+            end
+          end
+
+          if response =~ /\e\[6;(\d+);(\d+)t/
+            @cell_pixel_size = [$2.to_i, $1.to_i]
+          end
+        end
+      rescue IOError, Errno::EIO, Errno::ENOTTY
+        # Terminal doesn't support query
+      end
+
+      @cell_pixel_size ||= [9, 18]
+    end
+
+    # @return [Array(Integer, Integer), nil] cached cell dimensions [width_px, height_px],
+    #   or nil until {#query_cell_pixel_size} has run
+    attr_reader :cell_pixel_size
+
+    # Emit a Kitty graphics protocol image at the given placement.
+    #
+    # Transmits the image data as chunked base64 in APC escape sequences.
+    # The terminal decodes and renders the image at the cursor position.
+    # Each image gets a unique ID for precise deletion.
+    # Appends to the output buffer; does not flush.
+    #
+    # @param placement [Hash{Symbol => Object}] image placement from {Buffer#image_placements}
+    # @return [void]
+    def draw_kitty_image(placement)
+      # Generate a unique image ID for this placement
+      placement_key = [placement[:x], placement[:y], placement[:content_hash]]
+      image_id = @image_id_map[placement_key] ||= (@next_image_id += 1)
+
+      # Position cursor at image origin
+      @buffer << "#{CSI}#{placement[:y] + 1};#{placement[:x] + 1}H"
+
+      encoded = [placement[:data]].pack("m0") # strict base64, no newlines
+      format_code = placement[:format] == :png ? 100 : 32
+
+      # Chunk into 4096-byte pieces (safe for all Kitty-compatible terminals)
+      chunks = encoded.scan(/.{1,4096}/m)
+
+      chunks.each_with_index do |chunk, i|
+        more = i < chunks.length - 1 ? 1 : 0
+
+        if i == 0
+          # C=1: do not move the cursor after displaying — keeps the
+          # terminal's cursor position in sync with the backend's model
+          params = +"a=T,f=#{format_code},i=#{image_id},C=1"
+          params << ",s=#{placement[:pixel_width]},v=#{placement[:pixel_height]}" if format_code == 32
+
+          # Source rectangle for cropping/scrolling (pixel coordinates within image)
+          if placement[:src_x] && placement[:src_y]
+            params << ",x=#{placement[:src_x]},y=#{placement[:src_y]}"
+            params << ",w=#{placement[:src_w]},h=#{placement[:src_h]}" if placement[:src_w] && placement[:src_h]
+          end
+
+          params << ",c=#{placement[:cols]},r=#{placement[:rows]},m=#{more}"
+          @buffer << "\e_G#{params};#{chunk}\e\\"
+        else
+          @buffer << "\e_Gm=#{more};#{chunk}\e\\"
+        end
+      end
+    end
+
+    # Delete a Kitty graphics protocol image by ID.
+    #
+    # Sends a delete command targeting the specific image ID, ensuring
+    # precise removal without affecting other images.
+    # Appends to the output buffer; does not flush.
+    #
+    # @param placement [Hash{Symbol => Object}] the image placement to delete
+    # @return [void]
+    def delete_kitty_image(placement)
+      placement_key = [placement[:x], placement[:y], placement[:content_hash]]
+      image_id = @image_id_map.delete(placement_key)
+
+      if image_id
+        # Delete by image ID — precise and reliable
+        @buffer << "\e_Ga=d,d=i,i=#{image_id}\e\\"
+      else
+        # Fallback: delete images whose cells were overwritten
+        @buffer << "\e_Ga=d,d=C\e\\"
+      end
+    end
+
+    # Delete all Kitty graphics protocol images.
+    #
+    # Nuclear option for clearing all image overlays. Useful during
+    # transitions or when precise tracking isn't possible.
+    # Forgets all tracked image IDs and flushes immediately.
+    #
+    # @return [void]
+    def clear_all_images!
+      @buffer << "\e_Ga=d,d=A\e\\"
+      @image_id_map.clear
+      flush
+    end
+
+    # Write the buffered output to the output IO and flush it.
+    #
+    # Does nothing if the buffer is empty.
+    #
+    # @return [void]
+    def flush
+      return if @buffer.empty?
+
+      @output.write(@buffer)
+      @output.flush
+      @buffer.clear
+    end
+
+    private
+
+    def apply_style(style)
+      return if style == @prev_style
+
+      codes = []
+
+      # Reset if transitioning from a styled state
+      if @prev_style && needs_reset?(style)
+        codes << "0"
+        @prev_style = nil
+      end
+
+      prev = @prev_style || Style::DEFAULT
+
+      # Foreground
+      if style.fg != prev.fg
+        codes << (style.fg ? style.fg.to_fg_ansi : "39")
+      end
+
+      # Background
+      if style.bg != prev.bg
+        codes << (style.bg ? style.bg.to_bg_ansi : "49")
+      end
+
+      # Modifiers added
+      added = style.modifiers & ~prev.modifiers
+      Modifier::SGR_ON.each do |flag, code|
+        codes << code if Modifier.contains?(added, flag)
+      end
+
+      # Modifiers removed
+      removed = prev.modifiers & ~style.modifiers
+      Modifier::SGR_OFF.each do |flag, code|
+        codes << code if Modifier.contains?(removed, flag)
+      end
+
+      @buffer << "#{CSI}#{codes.join(";")}m" unless codes.empty?
+      @prev_style = style
+    end
+
+    # Determine if we need a full reset (simpler than tracking individual removals)
+    def needs_reset?(style)
+      return false unless @prev_style
+
+      # If modifiers were removed and we can't undo them individually
+      removed = @prev_style.modifiers & ~style.modifiers
+      # BOLD and DIM share the same off code (22), so reset if either changes
+      if Modifier.contains?(removed, Modifier::BOLD) || Modifier.contains?(removed, Modifier::DIM)
+        return true if Modifier.contains?(@prev_style.modifiers, Modifier::BOLD) &&
+                       Modifier.contains?(@prev_style.modifiers, Modifier::DIM)
+      end
+
+      false
+    end
+  end
+end

data/lib/rubytui/backends/test_backend.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # In-memory {Backend} for tests.
+  #
+  # Records drawn cells in a grid and tracks cursor, alternate-screen,
+  # raw-mode and mouse state as plain values; nothing is written to a
+  # terminal. {#width}, {#height}, {#cursor_visible}, {#alternate_screen},
+  # {#raw_mode}, {#cursor_x}, {#cursor_y} and {#draw_history} expose that
+  # state for assertions.
+  #
+  # @example
+  #   backend = TestBackend.new(width: 20, height: 5)
+  #   terminal = Terminal.new(backend: backend)
+  #   terminal.draw { |frame| frame.buffer.set_string(0, 0, "Hi") }
+  #   backend.row_text(0)  # => "Hi"
+  class TestBackend
+    include Backend
+
+    attr_reader :width, :height, :cursor_visible, :alternate_screen, :raw_mode
+    attr_reader :cursor_x, :cursor_y, :draw_history
+
+    # @param width [Integer] grid width in columns (default: 80)
+    # @param height [Integer] grid height in rows (default: 24)
+    def initialize(width: 80, height: 24)
+      @width = width
+      @height = height
+      @cells = Array.new(width * height) { Cell.new }
+      @cursor_visible = true
+      @alternate_screen = false
+      @raw_mode = false
+      @cursor_x = 0
+      @cursor_y = 0
+      @draw_history = []
+    end
+
+    # Record the changes and copy each cell into the in-memory grid.
+    #
+    # A copy of +changes+ is appended to {#draw_history}. Changes whose grid
+    # index (<tt>y * width + x</tt>) falls outside the grid are skipped.
+    #
+    # @param changes [Array<Array(Integer, Integer, Cell)>] changed cells as [x, y, cell]
+    # @return [void]
+    def draw(changes)
+      @draw_history << changes.dup
+      changes.each do |x, y, cell|
+        idx = y * @width + x
+        next if idx < 0 || idx >= @cells.length
+
+        @cells[idx] = Cell.new(cell.symbol, cell.style)
+      end
+    end
+
+    # Mark the cursor as hidden ({#cursor_visible} becomes false).
+    #
+    # @return [void]
+    def hide_cursor
+      @cursor_visible = false
+    end
+
+    # Mark the cursor as visible ({#cursor_visible} becomes true).
+    #
+    # @return [void]
+    def show_cursor
+      @cursor_visible = true
+    end
+
+    # Record the cursor position in {#cursor_x} and {#cursor_y}.
+    #
+    # @param x [Integer] zero-based column
+    # @param y [Integer] zero-based row
+    # @return [void]
+    def move_cursor(x, y)
+      @cursor_x = x
+      @cursor_y = y
+    end
+
+    # Reset every grid cell to empty.
+    #
+    # @return [void]
+    def clear
+      @cells.each(&:reset!)
+    end
+
+    # Set {#alternate_screen} to true.
+    #
+    # @return [void]
+    def enter_alternate_screen
+      @alternate_screen = true
+    end
+
+    # Set {#alternate_screen} to false.
+    #
+    # @return [void]
+    def leave_alternate_screen
+      @alternate_screen = false
+    end
+
+    # Set {#raw_mode} to true.
+    #
+    # @return [void]
+    def enable_raw_mode
+      @raw_mode = true
+    end
+
+    # Set {#raw_mode} to false.
+    #
+    # @return [void]
+    def disable_raw_mode
+      @raw_mode = false
+    end
+
+    # @return [Array(Integer, Integer)] the grid size as [width, height]
+    def size = [@width, @height]
+
+    # No-op; the test backend has no output stream.
+    #
+    # @return [void]
+    def flush
+      # no-op for test backend
+    end
+
+    # Record that mouse reporting is enabled (see {#mouse_enabled?}).
+    #
+    # @return [void]
+    def enable_mouse
+      @mouse_enabled = true
+    end
+
+    # Record that mouse reporting is disabled (see {#mouse_enabled?}).
+    #
+    # @return [void]
+    def disable_mouse
+      @mouse_enabled = false
+    end
+
+    # @return [Boolean] true if {#enable_mouse} was called more recently than {#disable_mouse}
+    def mouse_enabled? = @mouse_enabled == true
+
+    # Record an image placement (Kitty graphics protocol).
+    # @param placement [Hash{Symbol => Object}] placement data from {Buffer#set_image}
+    # @return [void]
+    def draw_kitty_image(placement)
+      @image_history ||= []
+      @image_history << placement.dup
+    end
+
+    # Record an image deletion.
+    # @param key [Hash{Symbol => Object}] the placement being deleted, as passed by {Terminal#draw}
+    # @return [void]
+    def delete_kitty_image(key)
+      @image_deletes ||= []
+      @image_deletes << key
+    end
+
+    # @return [Array<Hash{Symbol => Object}>] history of image placements drawn via {#draw_kitty_image}
+    def image_history = (@image_history ||= [])
+
+    # @return [Array<Hash{Symbol => Object}>] history of placements passed to {#delete_kitty_image}
+    def image_deletes = (@image_deletes ||= [])
+
+    # @!group Test Assertion Helpers
+
+    # Get the grid cell at (x, y).
+    #
+    # Looks up the flat index <tt>y * width + x</tt> without per-axis bounds
+    # checks, so an out-of-range +x+ wraps into an adjacent row and a
+    # negative index counts from the end of the grid.
+    #
+    # @param x [Integer] zero-based column
+    # @param y [Integer] zero-based row
+    # @return [Cell, nil] the cell, or nil if the index is outside the grid
+    def cell_at(x, y)
+      idx = y * @width + x
+      @cells[idx]
+    end
+
+    # Read text from a row starting at (x, y) for the given length
+    #
+    # @param x [Integer] starting column
+    # @param y [Integer] row
+    # @param length [Integer] number of cells to read
+    # @return [String] the cell symbols joined; missing cells read as a space
+    def text_at(x, y, length)
+      (0...length).map { |i| cell_at(x + i, y)&.symbol || " " }.join
+    end
+
+    # Read an entire row as text
+    #
+    # @param y [Integer] row
+    # @return [String] the row's text with trailing whitespace removed
+    def row_text(y)
+      text_at(0, y, @width).rstrip
+    end
+
+    # Number of draw calls made
+    #
+    # @return [Integer] number of {#draw} calls recorded in {#draw_history}
+    def draw_count = @draw_history.length
+
+    # Total cells changed across all draws
+    #
+    # @return [Integer] sum of the change counts in {#draw_history}
+    def total_changes = @draw_history.sum(&:length)
+
+    # Reset for a fresh test
+    #
+    # Clears the grid and {#draw_history}, marks the cursor visible and moves
+    # it to (0, 0). Alternate-screen, raw-mode and mouse state and the image
+    # histories are left unchanged.
+    #
+    # @return [void]
+    def reset!
+      @cells.each(&:reset!)
+      @draw_history.clear
+      @cursor_visible = true
+      @cursor_x = 0
+      @cursor_y = 0
+    end
+
+    # @!endgroup
+  end
+end