ratatat 1.0.0

data/lib/ratatat/buffer.rb

@@ -0,0 +1,238 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module Ratatat
+  # A 2D grid of cells representing a terminal screen or region.
+  # Supports efficient diffing to minimize terminal I/O.
+  class Buffer
+    extend T::Sig
+
+    sig { returns(Integer) }
+    attr_reader :width, :height
+
+    sig { returns(T::Array[Cell]) }
+    attr_reader :cells
+
+    sig { params(width: Integer, height: Integer).void }
+    def initialize(width, height)
+      @width = width
+      @height = height
+      @cells = T.let(Array.new(width * height) { Cell::EMPTY }, T::Array[Cell])
+    end
+
+    # Get cell at (x, y) coordinates
+    sig { params(x: Integer, y: Integer).returns(T.nilable(Cell)) }
+    def get(x, y)
+      return nil unless in_bounds?(x, y)
+
+      @cells[index_of(x, y)]
+    end
+
+    # Alias for get
+    sig { params(x: Integer, y: Integer).returns(T.nilable(Cell)) }
+    def [](x, y)
+      get(x, y)
+    end
+
+    # Set cell at (x, y) coordinates
+    sig { params(x: Integer, y: Integer, cell: Cell).void }
+    def set(x, y, cell)
+      return unless in_bounds?(x, y)
+
+      @cells[index_of(x, y)] = cell
+    end
+
+    # Alias for set
+    sig { params(x: Integer, y: Integer, cell: Cell).void }
+    def []=(x, y, cell)
+      set(x, y, cell)
+    end
+
+    # Convert (x, y) to linear index
+    sig { params(x: Integer, y: Integer).returns(Integer) }
+    def index_of(x, y)
+      y * @width + x
+    end
+
+    # Convert linear index to (x, y)
+    sig { params(index: Integer).returns([Integer, Integer]) }
+    def pos_of(index)
+      [index % @width, index / @width]
+    end
+
+    # Check if coordinates are within bounds
+    sig { params(x: Integer, y: Integer).returns(T::Boolean) }
+    def in_bounds?(x, y)
+      x >= 0 && x < @width && y >= 0 && y < @height
+    end
+
+    # Write a string at position with optional styling
+    sig do
+      params(
+        x: Integer,
+        y: Integer,
+        text: String,
+        fg: Color::AnyColor,
+        bg: Color::AnyColor,
+        modifiers: T::Set[Modifier]
+      ).void
+    end
+    def put_string(x, y, text, fg: Color::Named::Reset, bg: Color::Named::Reset, modifiers: Set.new)
+      return unless in_bounds?(x, y)
+
+      col = x
+      text.each_grapheme_cluster do |grapheme|
+        break unless col < @width
+
+        cell = Cell.new(symbol: grapheme, fg: fg, bg: bg, modifiers: modifiers)
+        set(col, y, cell)
+
+        # Handle wide characters
+        char_width = cell.width
+        col += 1
+
+        # Mark continuation cells for wide chars
+        if char_width > 1 && col < @width
+          cont_cell = Cell.new(symbol: "", fg: fg, bg: bg, modifiers: modifiers)
+          set(col, y, cont_cell)
+          col += 1
+        end
+      end
+    end
+
+    # Clear buffer to empty cells
+    sig { void }
+    def clear
+      @cells = Array.new(@width * @height) { Cell::EMPTY }
+    end
+
+    # Resize buffer, preserving content where possible
+    sig { params(new_width: Integer, new_height: Integer).void }
+    def resize(new_width, new_height)
+      return if new_width == @width && new_height == @height
+
+      new_cells = Array.new(new_width * new_height) { Cell::EMPTY }
+
+      # Copy existing content
+      [height, new_height].min.times do |y|
+        [width, new_width].min.times do |x|
+          old_idx = y * @width + x
+          new_idx = y * new_width + x
+          new_cells[new_idx] = T.must(@cells[old_idx])
+        end
+      end
+
+      @width = new_width
+      @height = new_height
+      @cells = new_cells
+    end
+
+    # Compute diff between this buffer (previous) and another (current).
+    # Returns array of [x, y, cell] for cells that changed.
+    #
+    # This implements Ratatui's diffing algorithm with multi-width char handling.
+    # Optimized hot path - avoids method calls and type checks in inner loop.
+    sig { params(other: Buffer).returns(T::Array[[Integer, Integer, Cell]]) }
+    def diff(other)
+      raise ArgumentError, "Buffer size mismatch" unless @width == other.width && @height == other.height
+
+      updates = []
+      invalidated = 0  # Cells invalidated by previous wide char changing
+      to_skip = 0      # Cells to skip (continuation of current wide char)
+
+      # Cache for inner loop
+      prev_cells = @cells
+      curr_cells = other.cells
+      width = @width
+      total = prev_cells.length
+
+      x = 0
+      y = 0
+      i = 0
+
+      while i < total
+        prev_cell = prev_cells[i]
+        curr_cell = curr_cells[i]
+
+        # Fast path: check if we should emit this cell
+        # Skip if: marked to skip, is continuation cell, or unchanged and not invalidated
+        unless curr_cell.skip || to_skip > 0
+          # Inline visually_equal? check for speed
+          prev_sym = prev_cell.symbol
+          curr_sym = curr_cell.symbol
+          prev_sym = " " if prev_sym.empty?
+          curr_sym = " " if curr_sym.empty?
+
+          changed = invalidated > 0 ||
+                    prev_sym != curr_sym ||
+                    prev_cell.fg != curr_cell.fg ||
+                    prev_cell.bg != curr_cell.bg ||
+                    prev_cell.modifiers != curr_cell.modifiers
+
+          updates << [x, y, curr_cell] if changed
+        end
+
+        # Calculate widths for wide char tracking
+        # Fast path: ASCII chars (ord < 128) always have width 1
+        curr_sym = curr_cell.symbol
+        prev_sym = prev_cell.symbol
+        curr_ord = curr_sym.empty? ? 32 : curr_sym.ord
+        prev_ord = prev_sym.empty? ? 32 : prev_sym.ord
+
+        if curr_ord < 128 && prev_ord < 128
+          # ASCII fast path - both width 1, no wide char handling needed
+          to_skip = 0
+          invalidated = invalidated > 0 ? invalidated - 1 : 0
+        else
+          # Wide char path - need actual width calculation
+          curr_width = curr_cell.width
+          prev_width = prev_cell.width
+
+          # Track cells to skip (continuation of current wide char)
+          to_skip = curr_width > 1 ? curr_width - 1 : 0
+
+          # Track invalidated cells (when a wide char changes width)
+          affected = curr_width > prev_width ? curr_width : prev_width
+          invalidated = invalidated > affected ? invalidated - 1 : affected - 1
+          invalidated = 0 if invalidated < 0
+        end
+
+        # Update position (faster than pos_of)
+        x += 1
+        if x >= width
+          x = 0
+          y += 1
+        end
+
+        i += 1
+      end
+
+      updates
+    end
+
+    # Debug: render buffer to string (for testing)
+    sig { returns(String) }
+    def to_text
+      lines = T.let([], T::Array[String])
+      @height.times do |y|
+        line = +""
+        @width.times do |x|
+          cell = get(x, y)
+          next unless cell
+
+          sym = cell.normalized_symbol
+          line << (sym.empty? ? " " : sym)
+        end
+        lines << line.rstrip
+      end
+      lines.join("\n")
+    end
+
+    sig { returns(String) }
+    def to_s
+      "Buffer(#{@width}x#{@height})"
+    end
+  end
+end

data/lib/ratatat/cell.rb

@@ -0,0 +1,166 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module Ratatat
+  # Text modifiers as a T::Enum for type safety
+  class Modifier < T::Enum
+    extend T::Sig
+
+    enums do
+      None          = new
+      Bold          = new
+      Dim           = new
+      Italic        = new
+      Underline     = new
+      Blink         = new
+      Reverse       = new
+      Hidden        = new
+      Strikethrough = new
+    end
+
+    # ANSI codes for enabling modifiers
+    ENABLE_CODES = T.let({
+      Bold => 1,
+      Dim => 2,
+      Italic => 3,
+      Underline => 4,
+      Blink => 5,
+      Reverse => 7,
+      Hidden => 8,
+      Strikethrough => 9
+    }.freeze, T::Hash[Modifier, Integer])
+
+    # ANSI codes for disabling modifiers
+    DISABLE_CODES = T.let({
+      Bold => 22,
+      Dim => 22,
+      Italic => 23,
+      Underline => 24,
+      Blink => 25,
+      Reverse => 27,
+      Hidden => 28,
+      Strikethrough => 29
+    }.freeze, T::Hash[Modifier, Integer])
+
+    sig { returns(T.nilable(Integer)) }
+    def enable_code
+      ENABLE_CODES[self]
+    end
+
+    sig { returns(T.nilable(Integer)) }
+    def disable_code
+      DISABLE_CODES[self]
+    end
+  end
+
+  # A single cell in the terminal buffer.
+  # Immutable struct containing symbol, colors, and modifiers.
+  class Cell < T::Struct
+    extend T::Sig
+
+    const :symbol, String, default: " "
+    const :fg, Color::AnyColor, default: Color::Named::Reset
+    const :bg, Color::AnyColor, default: Color::Named::Reset
+    const :modifiers, T::Set[Modifier], default: Set.new
+    const :skip, T::Boolean, default: false
+
+    # Empty cell constant
+    EMPTY = T.let(new, Cell)
+
+    # Display width of this cell (1 for most chars, 2 for CJK/emoji)
+    # Cached for performance
+    sig { returns(Integer) }
+    def width
+      @_width ||= compute_width
+    end
+
+    private
+
+    sig { returns(Integer) }
+    def compute_width
+      return 1 if symbol.empty?
+
+      # Fast path for ASCII
+      ord = symbol.ord
+      return 1 if ord < 128
+
+      # Use unicode-display_width if available
+      if defined?(Unicode::DisplayWidth)
+        Unicode::DisplayWidth.of(symbol)
+      else
+        wide_char?(ord) ? 2 : 1
+      end
+    end
+
+    public
+
+    # Normalize symbol for comparison (empty -> space)
+    sig { returns(String) }
+    def normalized_symbol
+      symbol.empty? ? " " : symbol
+    end
+
+    # Check if cell has a modifier
+    sig { params(mod: Modifier).returns(T::Boolean) }
+    def has_modifier?(mod)
+      modifiers.include?(mod)
+    end
+
+    sig { returns(T::Boolean) }
+    def bold? = has_modifier?(Modifier::Bold)
+
+    sig { returns(T::Boolean) }
+    def italic? = has_modifier?(Modifier::Italic)
+
+    sig { returns(T::Boolean) }
+    def underline? = has_modifier?(Modifier::Underline)
+
+    sig { returns(T::Boolean) }
+    def dim? = has_modifier?(Modifier::Dim)
+
+    sig { returns(T::Boolean) }
+    def reverse? = has_modifier?(Modifier::Reverse)
+
+    # Create a new cell with updated attributes
+    sig { params(attrs: T.untyped).returns(Cell) }
+    def with(**attrs)
+      Cell.new(
+        symbol: attrs.fetch(:symbol, symbol),
+        fg: attrs.fetch(:fg, fg),
+        bg: attrs.fetch(:bg, bg),
+        modifiers: attrs.fetch(:modifiers, modifiers),
+        skip: attrs.fetch(:skip, skip)
+      )
+    end
+
+    # Visual equality (for diffing)
+    sig { params(other: T.untyped).returns(T::Boolean) }
+    def visually_equal?(other)
+      return false unless other.is_a?(Cell)
+
+      normalized_symbol == other.normalized_symbol &&
+        fg == other.fg &&
+        bg == other.bg &&
+        modifiers == other.modifiers
+    end
+
+    private
+
+    # Simple check for wide characters (CJK ranges, emoji)
+    sig { params(codepoint: Integer).returns(T::Boolean) }
+    def wide_char?(codepoint)
+      # CJK Unified Ideographs
+      (codepoint >= 0x4E00 && codepoint <= 0x9FFF) ||
+        # CJK Extension A
+        (codepoint >= 0x3400 && codepoint <= 0x4DBF) ||
+        # Hangul Syllables
+        (codepoint >= 0xAC00 && codepoint <= 0xD7AF) ||
+        # Fullwidth Forms
+        (codepoint >= 0xFF00 && codepoint <= 0xFFEF) ||
+        # Emoji
+        (codepoint >= 0x1F300 && codepoint <= 0x1F9FF)
+    end
+  end
+end

data/lib/ratatat/color.rb

@@ -0,0 +1,191 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module Ratatat
+  # Color types for terminal cells.
+  # Supports named ANSI colors, 256-color palette, and true color (RGB).
+  module Color
+    extend T::Sig
+
+    # Union type for any color
+    AnyColor = T.type_alias { T.any(Named, Indexed, Rgb) }
+
+    # Named ANSI colors (16 standard colors + reset)
+    class Named < T::Enum
+      extend T::Sig
+
+      enums do
+        # Reset to terminal default
+        Reset = new(:reset)
+
+        # Standard 8 colors (codes 0-7)
+        Black   = new(:black)
+        Red     = new(:red)
+        Green   = new(:green)
+        Yellow  = new(:yellow)
+        Blue    = new(:blue)
+        Magenta = new(:magenta)
+        Cyan    = new(:cyan)
+        White   = new(:white)
+
+        # Bright variants (codes 8-15)
+        BrightBlack   = new(:bright_black)
+        BrightRed     = new(:bright_red)
+        BrightGreen   = new(:bright_green)
+        BrightYellow  = new(:bright_yellow)
+        BrightBlue    = new(:bright_blue)
+        BrightMagenta = new(:bright_magenta)
+        BrightCyan    = new(:bright_cyan)
+        BrightWhite   = new(:bright_white)
+      end
+
+      # ANSI foreground code lookup
+      FG_CODES = T.let({
+        reset: 39,
+        black: 30, red: 31, green: 32, yellow: 33,
+        blue: 34, magenta: 35, cyan: 36, white: 37,
+        bright_black: 90, bright_red: 91, bright_green: 92, bright_yellow: 93,
+        bright_blue: 94, bright_magenta: 95, bright_cyan: 96, bright_white: 97
+      }.freeze, T::Hash[Symbol, Integer])
+
+      # ANSI background code lookup
+      BG_CODES = T.let({
+        reset: 49,
+        black: 40, red: 41, green: 42, yellow: 43,
+        blue: 44, magenta: 45, cyan: 46, white: 47,
+        bright_black: 100, bright_red: 101, bright_green: 102, bright_yellow: 103,
+        bright_blue: 104, bright_magenta: 105, bright_cyan: 106, bright_white: 107
+      }.freeze, T::Hash[Symbol, Integer])
+
+      sig { returns(Integer) }
+      def fg_code
+        T.must(FG_CODES[serialize])
+      end
+
+      sig { returns(Integer) }
+      def bg_code
+        T.must(BG_CODES[serialize])
+      end
+    end
+
+    # 256-color palette (0-255)
+    class Indexed
+      extend T::Sig
+
+      sig { returns(Integer) }
+      attr_reader :index
+
+      sig { params(index: Integer).void }
+      def initialize(index:)
+        raise ArgumentError, "Color index must be 0-255" unless index.between?(0, 255)
+
+        @index = index
+      end
+
+      sig { params(other: T.untyped).returns(T::Boolean) }
+      def ==(other)
+        other.is_a?(Indexed) && @index == other.index
+      end
+      alias eql? ==
+
+      sig { returns(Integer) }
+      def hash
+        @index.hash
+      end
+
+      sig { returns(String) }
+      def fg_code
+        "38;5;#{index}"
+      end
+
+      sig { returns(String) }
+      def bg_code
+        "48;5;#{index}"
+      end
+    end
+
+    # True color (24-bit RGB)
+    class Rgb
+      extend T::Sig
+
+      sig { returns(Integer) }
+      attr_reader :r, :g, :b
+
+      sig { params(r: Integer, g: Integer, b: Integer).void }
+      def initialize(r:, g:, b:)
+        raise ArgumentError, "Red must be 0-255" unless r.between?(0, 255)
+        raise ArgumentError, "Green must be 0-255" unless g.between?(0, 255)
+        raise ArgumentError, "Blue must be 0-255" unless b.between?(0, 255)
+
+        @r = r
+        @g = g
+        @b = b
+      end
+
+      sig { params(other: T.untyped).returns(T::Boolean) }
+      def ==(other)
+        other.is_a?(Rgb) && @r == other.r && @g == other.g && @b == other.b
+      end
+      alias eql? ==
+
+      sig { returns(Integer) }
+      def hash
+        [@r, @g, @b].hash
+      end
+
+      sig { returns(String) }
+      def fg_code
+        "38;2;#{r};#{g};#{b}"
+      end
+
+      sig { returns(String) }
+      def bg_code
+        "48;2;#{r};#{g};#{b}"
+      end
+    end
+
+    class << self
+      extend T::Sig
+
+      # Create RGB color from hex string
+      # Accepts: "#ff8000", "ff8000", "#f80", "f80"
+      sig { params(str: String).returns(Rgb) }
+      def hex(str)
+        str = str.delete_prefix("#")
+        r, g, b = case str.length
+        when 3
+          [str[0] * 2, str[1] * 2, str[2] * 2]
+        when 6
+          [str[0, 2], str[2, 2], str[4, 2]]
+        else
+          raise ArgumentError, "Invalid hex color: #{str}"
+        end
+        Rgb.new(r: T.must(r).to_i(16), g: T.must(g).to_i(16), b: T.must(b).to_i(16))
+      end
+
+      # Generate ANSI escape code for foreground
+      sig { params(color: AnyColor).returns(String) }
+      def fg_ansi(color)
+        case color
+        when Named then color.fg_code.to_s
+        when Indexed then color.fg_code
+        when Rgb then color.fg_code
+        else T.absurd(color)
+        end
+      end
+
+      # Generate ANSI escape code for background
+      sig { params(color: AnyColor).returns(String) }
+      def bg_ansi(color)
+        case color
+        when Named then color.bg_code.to_s
+        when Indexed then color.bg_code
+        when Rgb then color.bg_code
+        else T.absurd(color)
+        end
+      end
+    end
+  end
+end