shoko 0.1.0

data/lib/shoko/adapters/output/terminal/buffer.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+require_relative 'output'
+require_relative 'text_metrics.rb'
+
+module Shoko
+  module Adapters::Output::Terminal
+    # TerminalBuffer manages buffered writes and differential screen updates.
+    class TerminalBuffer
+    # In-memory frame buffer storing characters and style runs.
+    class Frame
+      CONTINUATION = :_wide_continuation
+
+      def initialize(width, height)
+        @width = width.to_i
+        @height = height.to_i
+        @chars = Array.new(@height) { Array.new(@width, ' ') }
+        @styles = Array.new(@height) { Array.new(@width, nil) }
+      end
+
+      def write(row, col, text)
+        return if @width <= 0 || @height <= 0
+
+        row_i = row.to_i - 1
+        col_i = col.to_i - 1
+        return if row_i.negative? || row_i >= @height
+        return if col_i.negative?
+        return if col_i >= @width
+
+        current_style = ''
+        col_pos = col_i
+
+        String(text).scan(Shoko::Adapters::Output::Terminal::TextMetrics::TOKEN_REGEX).each do |token|
+          if token.start_with?("\e[")
+            if token.end_with?('m')
+              current_style = '' if token == TerminalOutput::ANSI::RESET
+              current_style += token unless token == TerminalOutput::ANSI::RESET
+            end
+            next
+          end
+
+          break if col_pos >= @width
+
+          if token == "\t"
+            tab_size = Shoko::Adapters::Output::Terminal::TextMetrics::TAB_SIZE
+            spaces = tab_size - (col_pos % tab_size)
+            spaces.times do
+              break if col_pos >= @width
+
+              clear_wide_overlap(row_i, col_pos)
+              @chars[row_i][col_pos] = ' '
+              @styles[row_i][col_pos] = current_style.empty? ? nil : current_style
+              col_pos += 1
+            end
+            next
+          end
+
+          next if token == "\e"
+
+          if ["\n", "\r"].include?(token)
+            cluster = ' '
+          else
+            # Defense-in-depth: never render C0/C1 control characters from content.
+            next if token.match?(/[\u0000-\u001F\u007F-\u009F]/)
+
+            cluster = token
+          end
+          width = Shoko::Adapters::Output::Terminal::TextMetrics.display_width_for(cluster)
+          next if width <= 0
+
+          remaining = @width - col_pos
+          break if width > remaining
+
+          clear_wide_overlap(row_i, col_pos)
+
+          @chars[row_i][col_pos] = cluster
+          @styles[row_i][col_pos] = current_style.empty? ? nil : current_style
+
+          if width > 1
+            (1...width).each do |delta|
+              break if col_pos + delta >= @width
+
+              clear_wide_overlap(row_i, col_pos + delta)
+              @chars[row_i][col_pos + delta] = CONTINUATION
+              @styles[row_i][col_pos + delta] = nil
+            end
+          end
+
+          col_pos += width
+        end
+      rescue StandardError
+        nil
+      end
+
+      def rendered_rows
+        (0...@height).map { |row_i| render_row(row_i) }
+      end
+
+      private
+
+      def clear_wide_overlap(row_i, col_i)
+        cell = @chars[row_i][col_i]
+        if cell == CONTINUATION && col_i.positive?
+          @chars[row_i][col_i - 1] = ' '
+          @styles[row_i][col_i - 1] = nil
+        elsif col_i + 1 < @width && @chars[row_i][col_i + 1] == CONTINUATION
+          @chars[row_i][col_i + 1] = ' '
+          @styles[row_i][col_i + 1] = nil
+        end
+        @chars[row_i][col_i] = ' '
+        @styles[row_i][col_i] = nil
+      end
+
+      def render_row(row_i)
+        chars = @chars[row_i]
+        styles = @styles[row_i]
+        last_col = last_non_blank_col(chars, styles)
+        return '' if last_col.negative?
+
+        out = +''
+        active_style = nil
+        run = +''
+
+        col = 0
+        while col <= last_col
+          ch = chars[col]
+          if ch == CONTINUATION
+            col += 1
+            next
+          end
+
+          style = styles[col]
+          style = nil if style.nil? || style.empty?
+
+          if style != active_style
+            flush_run(out, run, active_style)
+            run = +''
+            active_style = style
+          end
+
+          run << (ch || ' ')
+          col += 1
+        end
+
+        flush_run(out, run, active_style)
+        out
+      end
+
+      def last_non_blank_col(chars, styles)
+        idx = chars.length - 1
+        while idx >= 0
+          ch = chars[idx]
+          style = styles[idx]
+          return idx if ch == CONTINUATION
+          return idx if style && !style.empty?
+          return idx if ch && ch != ' '
+
+          idx -= 1
+        end
+        -1
+      end
+
+      def flush_run(out, run, style)
+        return if run.empty?
+
+        if style
+          out << style << run << TerminalOutput::ANSI::RESET
+        else
+          out << run
+        end
+      end
+    end
+
+    attr_reader :buffer
+
+    def initialize(output = TerminalOutput.new)
+      @output = output
+      @buffer = []
+      @batch_mode = false
+      @batch_buffer = nil
+      @frame = nil
+      @previous_rows = []
+      @raw_sequences = []
+      @width = 0
+      @height = 0
+    end
+
+    def start_frame(width:, height:)
+      @raw_sequences = []
+      @buffer = []
+
+      width_i = width.to_i
+      height_i = height.to_i
+      width_i = 0 if width_i.negative?
+      height_i = 0 if height_i.negative?
+
+      size_changed = (width_i != @width) || (height_i != @height)
+      @width = width_i
+      @height = height_i
+      @previous_rows = Array.new(@height) if size_changed
+      @frame = Frame.new(@width, @height)
+    end
+
+    def end_frame
+      flush_frame
+      @output.flush
+    end
+
+    def raw(text)
+      return unless text
+
+      if @batch_mode
+        @batch_buffer << text.to_s
+      else
+        @raw_sequences << text.to_s
+      end
+    end
+
+    def write(row, col, text)
+      if @frame
+        @frame.write(row, col, text)
+        return
+      end
+
+      content = TerminalOutput::ANSI.move(row, col) + text.to_s
+      @output.print(content)
+    end
+
+    def write_differential(row, col, text)
+      write(row, col, text)
+    end
+
+    def clear_buffer_cache
+      @previous_rows = Array.new(@height)
+    end
+
+    def batch_write
+      @batch_mode = true
+      @batch_buffer = []
+      yield
+      @output.print(@batch_buffer.join)
+      @output.flush
+    ensure
+      @batch_mode = false
+      @batch_buffer = nil
+    end
+
+    private
+
+    def flush_frame
+      return unless @frame
+
+      rendered = @frame.rendered_rows
+      out = +''
+      @raw_sequences.each { |seq| out << seq }
+
+      rendered.each_with_index do |row_text, idx|
+        prev = @previous_rows[idx]
+        next if prev == row_text
+
+        row_number = idx + 1
+        out << TerminalOutput::ANSI.move(row_number, 1)
+        out << TerminalOutput::ANSI.clear_line
+        out << row_text unless row_text.empty?
+        @previous_rows[idx] = row_text
+      end
+
+      @output.print(out) unless out.empty?
+    ensure
+      @frame = nil
+      @raw_sequences = []
+    end
+    end
+  end
+end

data/lib/shoko/adapters/output/terminal/constants/terminal_defaults.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters::Output::Terminal
+    # Default terminal dimensions used when IO.console is unavailable.
+    module TerminalDefaults
+      DEFAULT_ROWS = 24
+      DEFAULT_COLUMNS = 80
+    end
+  end
+end

data/lib/shoko/adapters/output/terminal/input/decoder.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters::Output::Terminal
+    class TerminalInput
+    # Utility helpers for timeouts and CSI formatting.
+    module DecoderUtils
+      module_function
+
+      def normalize_timeout(value, default)
+        seconds = value.to_f
+        seconds.positive? ? seconds : default
+      rescue StandardError
+        default
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      rescue StandardError
+        Time.now.to_f
+      end
+
+      def format_csi_output(raw, prefix_bytes, output_prefix)
+        return raw.force_encoding(Encoding::UTF_8) unless output_prefix
+
+        remainder = raw.byteslice(prefix_bytes..) || ''.b
+        (output_prefix + remainder.force_encoding(Encoding::UTF_8)).freeze
+      end
+    end
+
+    # UTF-8 decoder for buffered terminal input.
+    class Utf8Decoder
+      def initialize(buffer)
+        @buffer = buffer
+      end
+
+      def decode_at(offset)
+        lead_byte = @buffer.getbyte(offset)
+        return nil unless lead_byte
+        return [@buffer.byteslice(offset, 1).force_encoding(Encoding::UTF_8), 1] if lead_byte < 0x80
+
+        decode_multibyte_at(offset, lead_byte)
+      rescue StandardError
+        invalid_utf8_token
+      end
+
+      private
+
+      def decode_multibyte_at(offset, lead_byte)
+        byte_length =
+          (2 if lead_byte.between?(0xC2, 0xDF)) ||
+          (3 if lead_byte.between?(0xE0, 0xEF)) ||
+          (4 if lead_byte.between?(0xF0, 0xF4))
+        return invalid_utf8_token unless byte_length
+        return nil if @buffer.bytesize < offset + byte_length
+
+        decode_multibyte(offset, byte_length)
+      end
+
+      def decode_multibyte(offset, byte_length)
+        bytes = @buffer.byteslice(offset, byte_length)
+        Utf8Validator.new(bytes).valid? ? utf8_token(bytes, byte_length) : invalid_utf8_token
+      end
+
+      def utf8_token(bytes, byte_length)
+        char = bytes.dup.force_encoding(Encoding::UTF_8)
+        char.valid_encoding? ? [char, byte_length] : invalid_utf8_token
+      end
+
+      def invalid_utf8_token
+        ["\uFFFD", 1]
+      end
+    end
+
+    # Validates UTF-8 byte sequences.
+    class Utf8Validator
+      def initialize(bytes)
+        @bytes = bytes
+      end
+
+      def valid?
+        case @bytes.bytesize
+        when 2
+          valid_2_bytes?
+        when 3
+          valid_3_bytes?
+        when 4
+          valid_4_bytes?
+        else
+          false
+        end
+      end
+
+      private
+
+      def valid_2_bytes?
+        byte_at(1).between?(0x80, 0xBF)
+      end
+
+      def valid_3_bytes?
+        lead_byte = byte_at(0)
+        first_continuation = byte_at(1)
+        second_continuation = byte_at(2)
+        first_continuation.between?(0x80, 0xBF) &&
+          second_continuation.between?(0x80, 0xBF) &&
+          !(lead_byte == 0xE0 && first_continuation < 0xA0) &&
+          !(lead_byte == 0xED && first_continuation > 0x9F)
+      end
+
+      def valid_4_bytes?
+        lead_byte = byte_at(0)
+        first_continuation = byte_at(1)
+        second_continuation = byte_at(2)
+        third_continuation = byte_at(3)
+        first_continuation.between?(0x80, 0xBF) &&
+          second_continuation.between?(0x80, 0xBF) &&
+          third_continuation.between?(0x80, 0xBF) &&
+          !(lead_byte == 0xF0 && first_continuation < 0x90) &&
+          !(lead_byte == 0xF4 && first_continuation > 0x8F)
+      end
+
+      def byte_at(index)
+        @bytes.getbyte(index)
+      end
+    end
+
+    # Scanning helpers for CSI and string terminators.
+    class DecoderScanner
+      def initialize(buffer)
+        @buffer = buffer
+      end
+
+      def csi_final_index(start_offset)
+        index = start_offset
+        while index < @buffer.bytesize
+          return index if @buffer.getbyte(index).between?(0x40, 0x7E)
+
+          index += 1
+        end
+      end
+
+      def string_terminator_index(start_offset)
+        start_offset.upto(@buffer.bytesize - 1) do |index|
+          length = string_terminator_length(index)
+          return index + length if length
+        end
+      end
+
+      def osc_terminator_index(start_offset)
+        start_offset.upto(@buffer.bytesize - 1) do |index|
+          length = osc_terminator_length(index)
+          return index + length if length
+        end
+      end
+
+      private
+
+      def string_terminator_length(index)
+        case @buffer.getbyte(index)
+        when 0x9C
+          1
+        when 0x1B
+          2 if @buffer.getbyte(index + 1) == 0x5C
+        end
+      end
+
+      def osc_terminator_length(index)
+        case @buffer.getbyte(index)
+        when 0x07, 0x9C
+          1
+        when 0x1B
+          2 if @buffer.getbyte(index + 1) == 0x5C
+        end
+      end
+    end
+
+    # Dispatches ESC-prefixed sequences to decoder actions.
+    class EscSequenceParser
+      HANDLERS = {
+        0x1B => :escape,
+        0x5B => :csi,
+        0x4F => :ss3,
+        0x5D => :osc,
+        0x50 => :string,
+        0x58 => :string,
+        0x5E => :string,
+        0x5F => :string,
+      }.freeze
+
+      ACTIONS = {
+        escape: lambda do |_scanner|
+          consume_and_clear(1)
+          "\e"
+        end,
+        csi: ->(_scanner) { parse_csi_sequence(prefix_bytes: 2, output_prefix: nil) },
+        ss3: ->(_scanner) { parse_ss3_sequence },
+        osc: ->(scanner) { parse_string_sequence(scanner.osc_terminator_index(2)) },
+        string: ->(scanner) { parse_string_sequence(scanner.string_terminator_index(2)) },
+        alt: ->(_scanner) { parse_decoded_character(1, prefix: "\e") },
+      }.freeze
+
+      def initialize(buffer, decoder)
+        @buffer = buffer
+        @decoder = decoder
+        @scanner = DecoderScanner.new(buffer)
+      end
+
+      def parse
+        action = HANDLERS.fetch(@buffer.getbyte(1), :alt)
+        @decoder.instance_exec(@scanner, &ACTIONS.fetch(action))
+      end
+    end
+
+    # Stateful tokenizer for raw terminal input.
+    #
+    # Converts a stream of bytes into:
+    # - Full CSI sequences (e.g. "\e[1;5D", mouse "\e[<...M")
+    # - Full SS3 sequences (e.g. "\eOA")
+    # - UTF-8 characters (including multibyte)
+    # - A lone ESC ("\e") after a small timeout (to disambiguate from escapes)
+    class Decoder
+      DEFAULT_ESC_TIMEOUT = 0.05
+      DEFAULT_SEQUENCE_TIMEOUT = 0.5
+
+      ESC = 0x1B
+      CSI_8BIT = 0x9B
+
+      def initialize(esc_timeout: DEFAULT_ESC_TIMEOUT, sequence_timeout: DEFAULT_SEQUENCE_TIMEOUT)
+        @esc_timeout = DecoderUtils.normalize_timeout(esc_timeout, DEFAULT_ESC_TIMEOUT)
+        @sequence_timeout = DecoderUtils.normalize_timeout(sequence_timeout, DEFAULT_SEQUENCE_TIMEOUT)
+        @buffer = +''.b
+        @pending_started_at = nil
+      end
+
+      def feed(bytes)
+        chunk = bytes.to_s
+        return if chunk.empty?
+
+        chunk = String(chunk).dup.force_encoding(Encoding::BINARY)
+        @buffer << chunk
+      rescue StandardError
+        nil
+      end
+
+      # Returns the next decoded token, or nil if not enough bytes are available.
+      def next_token(now: DecoderUtils.monotonic_now)
+        return nil if @buffer.empty?
+
+        token = parse_token
+        return token if token
+
+        now < pending_deadline(now) ? nil : degrade_pending_token
+      end
+
+      # When a partial token is buffered, returns seconds to wait before a token
+      # should be emitted even if no further bytes arrive.
+      def pending_timeout(now: DecoderUtils.monotonic_now)
+        return nil if @buffer.empty?
+        return nil unless @pending_started_at
+
+        remaining = pending_deadline(now) - now
+        remaining.positive? ? remaining : 0
+      end
+
+      private
+
+      def consume_and_clear(byte_count)
+        consume_bytes(byte_count)
+        @pending_started_at = nil
+      end
+
+      def pending_deadline(now)
+        started = @pending_started_at || now
+        @pending_started_at = started
+        if @buffer.bytesize == 1 && @buffer.getbyte(0) == ESC
+          started + @esc_timeout
+        else
+          started + @sequence_timeout
+        end
+      end
+
+      def parse_token
+        first = @buffer.getbyte(0)
+        case first
+        when ESC
+          return nil if @buffer.bytesize < 2
+
+          EscSequenceParser.new(@buffer, self).parse
+        when CSI_8BIT
+          parse_csi_sequence(prefix_bytes: 1, output_prefix: "\e[")
+        else
+          parse_decoded_character(0)
+        end
+      end
+
+      def parse_ss3_sequence
+        return nil if @buffer.bytesize < 3
+
+        token = @buffer.byteslice(0, 3)
+        consume_and_clear(3)
+        token.force_encoding(Encoding::UTF_8)
+      end
+
+      def parse_csi_sequence(prefix_bytes:, output_prefix:)
+        return nil unless (final_index = DecoderScanner.new(@buffer).csi_final_index(prefix_bytes))
+
+        end_index = final_index + 1
+        raw = @buffer.byteslice(0, end_index)
+        consume_and_clear(end_index)
+        DecoderUtils.format_csi_output(raw, prefix_bytes, output_prefix)
+      end
+
+      def parse_string_sequence(end_index)
+        return nil unless end_index
+
+        raw = @buffer.byteslice(0, end_index)
+        consume_and_clear(end_index)
+        raw.force_encoding(Encoding::UTF_8)
+      end
+
+      def parse_decoded_character(offset, prefix: nil)
+        return nil unless (decoded = Utf8Decoder.new(@buffer).decode_at(offset))
+
+        char, consumed = decoded
+        consume_and_clear(offset + consumed)
+        prefix ? "#{prefix}#{char}" : char
+      end
+
+      def degrade_pending_token
+        lead_byte = @buffer.getbyte(0)
+        consume_and_clear(1)
+
+        { ESC => "\e", CSI_8BIT => "\e[" }.fetch(lead_byte, "\uFFFD")
+      end
+
+      def consume_bytes(byte_count)
+        count = byte_count.to_i
+        return if count <= 0
+
+        @buffer.slice!(0, count)
+      rescue StandardError
+        @buffer = +''.b
+      end
+    end
+    end
+  end
+end