rubytui 1.2.3

data/lib/rubytui/widgets/chart.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  module Widgets
+    # Dataset represents a series of data points for the Chart widget.
+    Dataset = Data.define(:name, :data, :style) do
+      # @param name [String] dataset name; not rendered, as {Chart} draws no legend
+      #   (default: "")
+      # @param data [Array<Array(Numeric, Numeric)>] <tt>[x, y]</tt> points, joined by
+      #   lines in the given order (default: [])
+      # @param style [Style] line style (default: {Style::DEFAULT})
+      def initialize(name: "", data: [], style: Style::DEFAULT)
+        super
+      end
+    end
+
+    # Chart renders line charts using Canvas (Braille) for high-resolution plotting.
+    # Supports multiple datasets, labeled axes, and automatic scaling.
+    #
+    # @example
+    #   ds = RubyTUI::Widgets::Dataset.new(name: "load", data: [[0, 1], [1, 3], [2, 2]])
+    #   chart = RubyTUI::Widgets::Chart.new(datasets: [ds], x_axis: ["t", 0, 2], y_axis: ["y", 0, 4])
+    #   frame.render_widget(chart, area)
+    #
+    # @see Dataset
+    class Chart
+      include Widget
+
+      # @param datasets [Array<Dataset>] series to plot; datasets with fewer than
+      #   2 points are skipped (default: [])
+      # @param x_axis [Array(String, Numeric, Numeric), nil] <tt>[label, min, max]</tt>;
+      #   +min+/+max+ may be nil for bounds computed from the data. When set, one row
+      #   is reserved for the axis and the label is drawn centered on it (default: nil,
+      #   bounds computed from the data and no row reserved)
+      # @param y_axis [Array(String, Numeric, Numeric), nil] <tt>[label, min, max]</tt>;
+      #   +min+/+max+ may be nil for bounds computed from the data. When set, the
+      #   min/max values are drawn left of a vertical axis line and the label's first
+      #   character at mid-height (default: nil, no y axis; bounds computed from the data)
+      # @param style [Style] currently unused by rendering (default: {Style::DEFAULT})
+      # @param axis_style [Style, nil] axis line style (default: bright black foreground)
+      # @param label_style [Style, nil] style of axis labels and min/max values
+      #   (default: white foreground)
+      # @param block [Widgets::Block, nil] optional wrapping block
+      def initialize(
+        datasets: [],
+        x_axis: nil,        # [label, min, max] or nil for auto
+        y_axis: nil,        # [label, min, max] or nil for auto
+        style: Style::DEFAULT,
+        axis_style: nil,
+        label_style: nil,
+        block: nil
+      )
+        @datasets = datasets
+        @x_axis = x_axis
+        @y_axis = y_axis
+        @style = style
+        @axis_style = axis_style || Style.new.fg(Color::BRIGHT_BLACK)
+        @label_style = label_style || Style.new.fg(Color::WHITE)
+        @block = block
+      end
+
+      # Render the axes and draw each dataset as connected line segments on a {Canvas}.
+      #
+      # Nothing is drawn, not even +block+, when there are no datasets.
+      #
+      # @param area [Rect] the rectangular area to render into
+      # @param buf [Buffer] the buffer to write cells into
+      # @return [void]
+      def render(area, buf)
+        return if area.empty? || @datasets.empty?
+
+        render_area = area
+        if @block
+          @block.render(area, buf)
+          render_area = @block.inner(area)
+        end
+
+        return if render_area.empty?
+
+        # Reserve space for axes
+        y_label_width = compute_y_label_width
+        x_label_height = @x_axis ? 1 : 0
+        y_label_area_width = y_label_width > 0 ? y_label_width + 1 : 0
+
+        chart_area = Rect.new(
+          x: render_area.x + y_label_area_width,
+          y: render_area.y,
+          width: [render_area.width - y_label_area_width, 0].max,
+          height: [render_area.height - x_label_height, 0].max
+        )
+
+        return if chart_area.empty?
+
+        # Compute data bounds
+        x_min, x_max = compute_x_bounds
+        y_min, y_max = compute_y_bounds
+
+        # Draw axes
+        render_y_axis(render_area, chart_area, buf, y_min, y_max)
+        render_x_axis(render_area, chart_area, buf, x_min, x_max)
+
+        # Draw data using Canvas
+        canvas = Canvas.new(
+          x_bounds: [x_min, x_max],
+          y_bounds: [y_min, y_max]
+        )
+
+        @datasets.each do |ds|
+          points = ds.data
+          next if points.length < 2
+
+          # Draw lines between consecutive points
+          points.each_cons(2) do |(x1, y1), (x2, y2)|
+            canvas.line(x1, y1, x2, y2, style: ds.style)
+          end
+        end
+
+        canvas.render(chart_area, buf)
+      end
+
+      private
+
+      def compute_y_label_width
+        return 0 unless @y_axis
+
+        _, y_min, y_max = @y_axis
+        if y_min && y_max
+          [format_num(y_min).length, format_num(y_max).length].max
+        else
+          all_y = @datasets.flat_map { |ds| ds.data.map { |_, y| y } }
+          return 0 if all_y.empty?
+
+          [format_num(all_y.min).length, format_num(all_y.max).length].max
+        end
+      end
+
+      def compute_x_bounds
+        if @x_axis
+          _, mn, mx = @x_axis
+          return [mn, mx] if mn && mx
+        end
+
+        all_x = @datasets.flat_map { |ds| ds.data.map { |x, _| x } }
+        return [0.0, 1.0] if all_x.empty?
+
+        mn = all_x.min.to_f
+        mx = all_x.max.to_f
+        mx = mn + 1 if mx == mn
+        [mn, mx]
+      end
+
+      def compute_y_bounds
+        if @y_axis
+          _, mn, mx = @y_axis
+          return [mn, mx] if mn && mx
+        end
+
+        all_y = @datasets.flat_map { |ds| ds.data.map { |_, y| y } }
+        return [0.0, 1.0] if all_y.empty?
+
+        mn = all_y.min.to_f
+        mx = all_y.max.to_f
+        mx = mn + 1 if mx == mn
+        [mn, mx]
+      end
+
+      def render_y_axis(render_area, chart_area, buf, y_min, y_max)
+        return unless @y_axis
+
+        label = @y_axis[0]
+
+        # Draw vertical axis line
+        (chart_area.y...chart_area.bottom).each do |y|
+          buf[chart_area.x - 1, y]&.set("\u2502", @axis_style) if chart_area.x > render_area.x
+        end
+
+        # Y labels at top and bottom
+        y_label_x = render_area.x
+        buf.set_string(y_label_x, chart_area.y, format_num(y_max), @label_style)
+        buf.set_string(y_label_x, chart_area.bottom - 1, format_num(y_min), @label_style)
+
+        # Y axis label (vertically centered, first char)
+        if label && !label.empty?
+          mid_y = chart_area.y + chart_area.height / 2
+          buf.set_string(render_area.x, mid_y, label[0], @label_style)
+        end
+      end
+
+      def render_x_axis(render_area, chart_area, buf, x_min, x_max)
+        x_axis_y = chart_area.bottom
+
+        # Draw horizontal axis line
+        (chart_area.x...chart_area.right).each do |x|
+          buf[x, x_axis_y]&.set("\u2500", @axis_style)
+        end
+
+        # Corner
+        if chart_area.x > render_area.x
+          buf[chart_area.x - 1, x_axis_y]&.set("\u2514", @axis_style)
+        end
+
+        # X labels at left and right
+        min_str = format_num(x_min)
+        max_str = format_num(x_max)
+        buf.set_string(chart_area.x, x_axis_y, min_str, @label_style)
+        max_x = chart_area.right - Buffer.string_width(max_str)
+        buf.set_string([max_x, chart_area.x].max, x_axis_y, max_str, @label_style)
+
+        # X axis label (centered)
+        if @x_axis
+          label = @x_axis[0]
+          if label && !label.empty?
+            lx = chart_area.x + (chart_area.width - Buffer.string_width(label)) / 2
+            buf.set_string(lx, x_axis_y, label, @label_style)
+          end
+        end
+      end
+
+      def format_num(n)
+        n == n.to_i ? n.to_i.to_s : format("%.1f", n)
+      end
+    end
+  end
+end

data/lib/rubytui/widgets/gauge.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  module Widgets
+    # Gauge renders a horizontal progress bar with an optional label.
+    #
+    # @example
+    #   gauge = RubyTUI::Widgets::Gauge.new(ratio: 0.42)  # label "42%"
+    #   frame.render_widget(gauge, area)
+    class Gauge
+      include Widget
+
+      # Block characters for smooth progress rendering
+
+      # Full block (8/8).
+      FULL  = "\u2588"  # █
+      # Left seven-eighths block (7/8).
+      SEVEN = "\u2589"  # ▉
+      # Left three-quarters block (6/8).
+      SIX   = "\u258A"  # ▊
+      # Left five-eighths block (5/8).
+      FIVE  = "\u258B"  # ▋
+      # Left half block (4/8).
+      FOUR  = "\u258C"  # ▌
+      # Left three-eighths block (3/8).
+      THREE = "\u258D"  # ▍
+      # Left one-quarter block (2/8).
+      TWO   = "\u258E"  # ▎
+      # Left one-eighth block (1/8).
+      ONE   = "\u258F"  # ▏
+      # Empty cell (0/8).
+      EMPTY = " "
+
+      # Bar characters indexed by filled eighths, from {EMPTY} (0) to {FULL} (8).
+      EIGHTHS = [EMPTY, ONE, TWO, THREE, FOUR, FIVE, SIX, SEVEN, FULL].freeze
+
+      # @param ratio [Numeric] fill ratio, clamped to 0.0..1.0 (default: 0.0)
+      # @param label [String, nil] text centered on the middle row, drawn only if it
+      #   fits the width (default: nil, the rounded percentage, e.g. <tt>"42%"</tt>)
+      # @param label_style [Style, nil] style for every label character (default: nil,
+      #   bold black on the gauge color over the filled part and bold gauge-colored
+      #   text over the unfilled part)
+      # @param style [Style] style of the unfilled cells (default: {Style::DEFAULT})
+      # @param gauge_style [Style, nil] style of the filled blocks; its foreground color
+      #   is also used by the default label styles (default: green foreground)
+      # @param block [Widgets::Block, nil] optional wrapping block
+      def initialize(
+        ratio: 0.0,
+        label: nil,
+        label_style: nil,
+        style: Style::DEFAULT,
+        gauge_style: nil,
+        block: nil
+      )
+        @ratio = ratio.clamp(0.0, 1.0)
+        @label = label
+        @label_style = label_style
+        @style = style
+        @gauge_style = gauge_style || Style.new.fg(Color::GREEN)
+        @block = block
+      end
+
+      # Render the bar on every row of the area with eighth-cell precision, then the
+      # label centered on the middle row.
+      #
+      # @param area [Rect] the rectangular area to render into
+      # @param buf [Buffer] the buffer to write cells into
+      # @return [void]
+      def render(area, buf)
+        return if area.empty?
+
+        render_area = area
+        if @block
+          @block.render(area, buf)
+          render_area = @block.inner(area)
+        end
+
+        return if render_area.empty?
+
+        width = render_area.width
+        filled_exact = width * @ratio * 8.0
+        filled_full = (filled_exact / 8).floor
+        partial_eighth = (filled_exact % 8).round
+        # The boundary column (first non-full cell)
+        boundary = filled_full + (partial_eighth > 0 ? 1 : 0)
+
+        # Render on each row of the gauge area
+        (0...render_area.height).each do |row|
+          y = render_area.y + row
+          x = render_area.x
+
+          # Full blocks
+          filled_full.times do |i|
+            break if x + i >= render_area.right
+            buf[x + i, y]&.set(FULL, @gauge_style)
+          end
+
+          # Partial block
+          if partial_eighth > 0 && filled_full < width
+            buf[x + filled_full, y]&.set(EIGHTHS[partial_eighth], @gauge_style)
+          end
+
+          # Empty space
+          (boundary...width).each do |i|
+            buf[x + i, y]&.set(EMPTY, @style)
+          end
+        end
+
+        # Render label centered, with per-character style blending
+        label_text = @label || "#{(@ratio * 100).round}%"
+        label_width = Buffer.string_width(label_text)
+        if label_width <= width
+          label_x = render_area.x + (width - label_width) / 2
+          label_y = render_area.y + render_area.height / 2
+
+          # Compute styles for label chars on filled vs empty portions
+          # On filled portion: gauge color as bg, contrasting fg
+          gauge_fg = @gauge_style.fg
+          filled_label_style = @label_style || Style.new.fg(Color::BLACK).bg(gauge_fg).bold
+          # On empty portion: gauge color as fg, default bg
+          empty_label_style = @label_style || Style.new.fg(gauge_fg).bold
+
+          cx = label_x
+          label_text.each_char do |ch|
+            ch_w = Buffer.char_width(ch)
+            col_offset = cx - render_area.x
+            char_style = col_offset < boundary ? filled_label_style : empty_label_style
+            buf[cx, label_y]&.set(ch, char_style)
+            # Mark spacer for wide chars
+            if ch_w == 2 && cx + 1 < render_area.right
+              buf[cx + 1, label_y]&.set("", char_style)
+            end
+            cx += ch_w
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubytui/widgets/image.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module RubyTUI
+  module Widgets
+    # Renders an image in the terminal using the Kitty graphics protocol.
+    #
+    # Supports PNG files natively (sent directly to terminal, no decoding needed)
+    # and raw RGBA pixel data. Works on terminals that support the Kitty graphics
+    # protocol: Kitty, Ghostty, WezTerm. Note: iTerm2 uses a different protocol.
+    #
+    # JPEG, WebP, GIF, and BMP are NOT supported — convert to PNG first:
+    #   system("magick", "input.jpg", "-resize", "800x600>", "output.png")
+    #
+    # @example From a PNG file
+    #   image = RubyTUI::Widgets::Image.new(path: "photo.png")
+    #   frame.render_widget(image, area)
+    #
+    # @example From a PNG file with border
+    #   block = RubyTUI::Widgets::Block.new(title: " Photo ", borders: :all)
+    #   image = RubyTUI::Widgets::Image.new(path: "photo.png", block: block)
+    #   frame.render_widget(image, area)
+    #
+    # @example From raw RGBA pixel data
+    #   image = RubyTUI::Widgets::Image.new(
+    #     data: rgba_bytes,
+    #     pixel_width: 800,
+    #     pixel_height: 600,
+    #     format: :rgba
+    #   )
+    #
+    # @example Aspect-ratio-preserving fit
+    #   image = RubyTUI::Widgets::Image.new(path: "photo.png", fit: :contain)
+    #   frame.render_widget(image, area)  # Image computes sub-rect
+    #
+    # @example Source-rect cropping (scrollable image)
+    #   image = RubyTUI::Widgets::Image.new(
+    #     path: "tall_image.png",
+    #     src_rect: Rect.new(0, scroll_offset, pixel_width, visible_height)
+    #   )
+    class Image
+      include Widget
+
+      # PNG file signature (first 8 bytes)
+      PNG_SIGNATURE = "\x89PNG\r\n\x1a\n".b.freeze
+
+      # JPEG signatures (SOI marker)
+      JPEG_SIGNATURE = "\xFF\xD8\xFF".b.freeze
+
+      # WebP signature (RIFF....WEBP)
+
+      # RIFF container tag at byte offset 0 of a WebP file.
+      WEBP_RIFF = "RIFF".b.freeze
+      # WebP form type at byte offset 8 of a WebP file.
+      WEBP_MARKER = "WEBP".b.freeze
+
+      # GIF signatures
+
+      # GIF87a signature.
+      GIF87A_SIGNATURE = "GIF87a".b.freeze
+      # GIF89a signature.
+      GIF89A_SIGNATURE = "GIF89a".b.freeze
+
+      # BMP signature
+      BMP_SIGNATURE = "BM".b.freeze
+
+      # Fit modes for aspect-ratio-preserving sizing
+      FIT_MODES = %i[stretch contain cover].freeze
+
+      # @return [Integer] image width in pixels
+      attr_reader :pixel_width
+
+      # @return [Integer] image height in pixels
+      attr_reader :pixel_height
+
+      # @return [Symbol] image format (:png or :rgba)
+      attr_reader :format
+
+      # @param path [String, nil] path to a PNG image file
+      # @param data [String, nil] raw image bytes (PNG or RGBA)
+      # @param pixel_width [Integer, nil] image width in pixels (required for :rgba, auto-detected for :png)
+      # @param pixel_height [Integer, nil] image height in pixels (required for :rgba, auto-detected for :png)
+      # @param format [Symbol] image format — +:png+ or +:rgba+. Auto-detected when +:png+ (default).
+      #   Ignored when +path+ is given (the format is always detected).
+      # @param style [Style] background style for the image area (default: {Style::DEFAULT})
+      # @param block [Widgets::Block, nil] optional wrapping block for borders/title
+      # @param fit [Symbol, nil] aspect-ratio mode — +:stretch+ (default), +:contain+, +:cover+
+      # @param src_rect [Rect, nil] source rectangle for cropping (pixel coordinates within the image)
+      # @param clip [Boolean] if true, clamp rendering to the available area (default: true)
+      # @param cell_size [Array(Integer, Integer), nil] cell pixel dimensions [width, height] for aspect calculations
+      #   (default: nil, uses <tt>[9, 18]</tt>)
+      # @raise [ArgumentError] if neither +path+ nor +data+ is given, if PNG data is
+      #   truncated, or if +pixel_width+/+pixel_height+ are missing for +:rgba+ data
+      #   (including data whose format is not recognized)
+      # @raise [UnsupportedImageFormat] if the image is JPEG, WebP, GIF or BMP
+      # @raise [SystemCallError] if +path+ cannot be read
+      def initialize(path: nil, data: nil, pixel_width: nil, pixel_height: nil,
+                     format: :png, style: Style::DEFAULT, block: nil,
+                     fit: nil, src_rect: nil, clip: true, cell_size: nil)
+        @style = style
+        @block = block
+        @fit = fit
+        @src_rect = src_rect
+        @clip = clip
+        @cell_size = cell_size
+
+        if path
+          @image_data = File.binread(path)
+          @format = self.class.detect_format(@image_data)
+        elsif data
+          @image_data = data
+          @format = format == :png ? self.class.detect_format(data) : format
+        else
+          raise ArgumentError, "Image requires either path: or data:"
+        end
+
+        validate_format!(@format)
+
+        if @format == :png
+          dims = self.class.png_dimensions(@image_data)
+          raise ArgumentError, "Invalid PNG data" unless dims
+
+          @pixel_width = pixel_width || dims[0]
+          @pixel_height = pixel_height || dims[1]
+        else
+          raise ArgumentError, "pixel_width and pixel_height required for :rgba format" unless pixel_width && pixel_height
+
+          @pixel_width = pixel_width
+          @pixel_height = pixel_height
+        end
+
+        @content_hash = Digest::MD5.hexdigest(@image_data)[0, 8]
+      end
+
+      # Render this image into the buffer.
+      #
+      # Fills the area with placeholder cells and registers an image placement
+      # via {::RubyTUI::Buffer#set_image}. The backend emits the Kitty graphics protocol
+      # sequences during {::RubyTUI::Terminal#draw}.
+      #
+      # @param area [Rect] the rectangular area to render into
+      # @param buf [Buffer] the buffer to write cells into
+      # @return [void]
+      def render(area, buf)
+        return if area.empty?
+
+        render_area = area
+        if @block
+          @block.render(area, buf)
+          render_area = @block.inner(area)
+        end
+
+        return if render_area.empty?
+
+        # Apply fit mode to compute actual image placement
+        if @fit && @fit != :stretch
+          render_area = compute_fit_area(render_area)
+        end
+
+        # Clip to buffer bounds if requested
+        if @clip
+          render_area = clip_to_buffer(render_area, buf.area)
+        end
+
+        return if render_area.empty?
+
+        # Fill the area with spaces to claim it in the buffer
+        render_area.height.times do |row|
+          render_area.width.times do |col|
+            buf[render_area.x + col, render_area.y + row]&.set(" ", @style)
+          end
+        end
+
+        # Build placement hash
+        placement = {
+          x: render_area.x,
+          y: render_area.y,
+          cols: render_area.width,
+          rows: render_area.height,
+          data: @image_data,
+          pixel_width: @pixel_width,
+          pixel_height: @pixel_height,
+          format: @format,
+          content_hash: @content_hash
+        }
+
+        # Add source rectangle if specified (for cropping/scrolling)
+        if @src_rect
+          placement[:src_x] = @src_rect.x
+          placement[:src_y] = @src_rect.y
+          placement[:src_w] = @src_rect.width
+          placement[:src_h] = @src_rect.height
+        end
+
+        # Register the image placement on the buffer
+        buf.set_image(**placement)
+      end
+
+      # Read width and height from a PNG file's IHDR chunk.
+      #
+      # @param data [String] raw PNG file bytes
+      # @return [Array(Integer, Integer), nil] [width, height] or nil if not valid PNG
+      def self.png_dimensions(data)
+        return nil unless data.bytesize >= 24
+        return nil unless data.byteslice(0, 8) == PNG_SIGNATURE
+
+        width = data.byteslice(16, 4).unpack1("N")
+        height = data.byteslice(20, 4).unpack1("N")
+        [width, height]
+      end
+
+      # Detect image format from magic bytes.
+      #
+      # @param data [String] raw image bytes
+      # @return [Symbol] detected format — +:png+, +:jpeg+, +:webp+, +:gif+, +:bmp+, or +:rgba+ (unknown)
+      def self.detect_format(data)
+        return :rgba if data.nil? || data.bytesize < 8
+
+        # Force binary encoding for comparison
+        header = data.byteslice(0, 12).b
+
+        if header.start_with?(PNG_SIGNATURE)
+          :png
+        elsif header.start_with?(JPEG_SIGNATURE)
+          :jpeg
+        elsif header.start_with?(WEBP_RIFF) && data.byteslice(8, 4).b == WEBP_MARKER
+          :webp
+        elsif header.start_with?(GIF87A_SIGNATURE) || header.start_with?(GIF89A_SIGNATURE)
+          :gif
+        elsif header.start_with?(BMP_SIGNATURE)
+          :bmp
+        else
+          :rgba
+        end
+      end
+
+      # Compute area that preserves aspect ratio.
+      #
+      # @param area [Rect] available area in terminal cells
+      # @param pixel_width [Integer] image width in pixels
+      # @param pixel_height [Integer] image height in pixels
+      # @param cell_size [Array(Integer, Integer)] cell dimensions [width_px, height_px]
+      # @param mode [Symbol] +:contain+ (fit inside, preserving aspect ratio) or
+      #   +:cover+ (computes an overflowing size, then clamps it to +area+; nothing
+      #   is cropped, so the result is the whole area, as with +:stretch+)
+      # @return [Rect] computed placement within +area+
+      def self.fit_area(area, pixel_width, pixel_height, cell_size: [9, 18], mode: :contain)
+        cell_w, cell_h = cell_size
+        cell_ratio = cell_h.to_f / cell_w
+
+        image_aspect = pixel_width.to_f / pixel_height
+        area_aspect = (area.width * cell_w).to_f / (area.height * cell_h)
+
+        if mode == :contain
+          if image_aspect > area_aspect
+            # Image is wider — constrain by width
+            cols = area.width
+            rows = (cols / image_aspect / cell_ratio).round
+          else
+            # Image is taller — constrain by height
+            rows = area.height
+            cols = (rows * image_aspect * cell_ratio).round
+          end
+        else # :cover
+          if image_aspect > area_aspect
+            # Image is wider — constrain by height (will overflow width)
+            rows = area.height
+            cols = (rows * image_aspect * cell_ratio).round
+          else
+            # Image is taller — constrain by width (will overflow height)
+            cols = area.width
+            rows = (cols / image_aspect / cell_ratio).round
+          end
+        end
+
+        cols = [[cols, 1].max, area.width].min
+        rows = [[rows, 1].max, area.height].min
+
+        # Center within area
+        x = area.x + (area.width - cols) / 2
+        y = area.y + (area.height - rows) / 2
+
+        Rect.new(x, y, cols, rows)
+      end
+
+      private
+
+      def validate_format!(fmt)
+        case fmt
+        when :png, :rgba
+          # OK
+        when :jpeg
+          raise UnsupportedImageFormat,
+            "JPEG format not supported by Kitty graphics protocol. Convert to PNG first:\n" \
+            "  system(\"magick\", \"input.jpg\", \"output.png\")"
+        when :webp
+          raise UnsupportedImageFormat,
+            "WebP format not supported by Kitty graphics protocol. Convert to PNG first:\n" \
+            "  system(\"magick\", \"input.webp\", \"output.png\")"
+        when :gif
+          raise UnsupportedImageFormat,
+            "GIF format not supported by Kitty graphics protocol. Convert to PNG first:\n" \
+            "  system(\"magick\", \"input.gif[0]\", \"output.png\")  # [0] = first frame"
+        when :bmp
+          raise UnsupportedImageFormat,
+            "BMP format not supported by Kitty graphics protocol. Convert to PNG first:\n" \
+            "  system(\"magick\", \"input.bmp\", \"output.png\")"
+        end
+      end
+
+      def compute_fit_area(area)
+        cell_size = @cell_size || [9, 18]
+        self.class.fit_area(area, @pixel_width, @pixel_height, cell_size: cell_size, mode: @fit)
+      end
+
+      def clip_to_buffer(area, buf_area)
+        x1 = [area.x, buf_area.x].max
+        y1 = [area.y, buf_area.y].max
+        x2 = [area.right, buf_area.right].min
+        y2 = [area.bottom, buf_area.bottom].min
+
+        width = [x2 - x1, 0].max
+        height = [y2 - y1, 0].max
+
+        Rect.new(x1, y1, width, height)
+      end
+    end
+  end
+end