rubytui 1.2.4 → 1.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac917512f05261231e65601213ab71f6205cd68818e3da3adb1f867c66759719
-  data.tar.gz: bbad14e5928bde95d26c6cfcf2143f68f228f51559519b68f1c83eae5dec1ced
+  metadata.gz: 3422d29230acde2c0e9da429cf3ddf83a355706183039778574e3e3d9b5875b9
+  data.tar.gz: '059ab8b520b2d61ca15a0ba129b211ea4c44a52cb4dd826e5401172bb8ed9c1c'
 SHA512:
-  metadata.gz: 11827373b3850a674cf837353c4a60c8927abe4da423e0dfff1c2b3ee39b1c733f211f209151446140b3a257a5033d9bfe50e69b9daa8eeb211db34a4d6496e1
-  data.tar.gz: a887bd14dbb30d02e9fd0801b2acbe56acb543dcf25e216a4cb7f23e580ae69dabc6d5d15e420b708c107d7b28ec00683a6efeeaef9a266cd57f005f8a317f24
+  metadata.gz: 388a89d892b0f28d9ebbd9e0dd57f9dea31a65bca3d1d9da2f7af2c446fd9ddaddf05cc1d6cc5e3364860dd80225137573272230bf9dbed727c1edb075f750ae
+  data.tar.gz: 3c74612dc4bd6540af8b37cfdbec084ce5b6c292c9e2a64f9256b41ced9bca5855685930840adf199525a45de2b753a8b9bd099cf6ba0b26528db239de3c59e9

data/README.md

@@ -411,7 +411,8 @@ puts buf.to_ansi
 
 - PNG is sent to the terminal as is; its dimensions are read from the file header.
 - Raw 8-bit RGBA pixel data requires `format: :rgba` together with `pixel_width:` and `pixel_height:`.
-- JPEG, WebP, GIF and BMP data is detected and raises `RubyTUI::UnsupportedImageFormat`. Convert such images to PNG first, for example with ImageMagick: `system("magick", "input.jpg", "output.png")`.
+- GIF is decoded by RubyTUI (no external tools). An animated GIF plays in the terminal using the protocol's animation support, with its own frame timing and loop count; `animate: false` shows only the first frame. A terminal without animation support is expected to show the first frame. Decoding is CPU-bound (roughly 30 ms per 480×270 frame), so load large GIFs with `AsyncImage`.
+- JPEG, WebP and BMP data is detected and raises `RubyTUI::UnsupportedImageFormat`. Convert such images to PNG first, for example with ImageMagick: `system("magick", "input.jpg", "output.png")`.
 - Any other `format:` value raises `ArgumentError`.
 
 ```ruby
@@ -419,6 +420,9 @@ puts buf.to_ansi
 image = RubyTUI::Widgets::Image.new(path: "photo.png")
 frame.render_widget(image, area)
 
+# An animated GIF (plays in the terminal; animate: false shows the first frame)
+image = RubyTUI::Widgets::Image.new(path: "spinner.gif")
+
 # With a border and title
 image = RubyTUI::Widgets::Image.new(
   path: "photo.png",
@@ -467,7 +471,7 @@ Images are tracked by position and content. When an image disappears, moves or c
 
 ### AsyncImage
 
-`RubyTUI::Widgets::AsyncImage` runs a loader on a background thread and renders the image once the loader returns PNG data. Create it once and keep it across frames.
+`RubyTUI::Widgets::AsyncImage` runs a loader on a background thread and renders the image once the loader returns PNG or GIF data. Create it once and keep it across frames.
 
 ```ruby
 image = RubyTUI::Widgets::AsyncImage.new(

data/lib/rubytui/backends/ansi_backend.rb

@@ -249,7 +249,16 @@ module RubyTUI
     # 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.
+    #
+    # An animated placement (with an +:animation+ entry, see {Buffer#set_image})
+    # is sent as the root frame followed by one <tt>a=f</tt> transmission per extra
+    # frame, the root frame's gap (<tt>a=a,r=1,z=</tt>), and a play command: with
+    # no loop count it runs once and stops on the last frame (<tt>s=2</tt>); a loop
+    # count of 0 loops forever (<tt>s=3,v=1</tt>); a loop count of +n+ repeats it
+    # +n+ more times (<tt>s=3,v=n+1</tt>). With +:compressed+, the pixel data
+    # (and every frame) is already zlib-deflated and is sent with <tt>o=z</tt>.
+    # Terminals without animation support show the root frame. Appends to the
+    # output buffer; does not flush.
     #
     # @param placement [Hash{Symbol => Object}] image placement from {Buffer#image_placements}
     # @return [void]
@@ -261,33 +270,39 @@ module RubyTUI
       # 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
+      compressed = placement[:compressed]
+
+      # 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
+      params << ",o=z" if compressed
+
+      # 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
 
-      # 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
+      params << ",c=#{placement[:cols]},r=#{placement[:rows]}"
+      send_chunked(params, "", placement[:data])
 
-          # 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
+      anim = placement[:animation]
+      return unless anim
 
-          params << ",c=#{placement[:cols]},r=#{placement[:rows]},m=#{more}"
-          @buffer << "\e_G#{params};#{chunk}\e\\"
-        else
-          @buffer << "\e_Gm=#{more};#{chunk}\e\\"
-        end
+      size = +"f=32,s=#{placement[:pixel_width]},v=#{placement[:pixel_height]}"
+      size << ",o=z" if compressed
+      anim[:frames].each_with_index do |frame, i|
+        send_chunked("a=f,i=#{image_id},#{size},z=#{anim[:delays][i + 1]}", "a=f,", frame)
       end
+      @buffer << "\e_Ga=a,i=#{image_id},r=1,z=#{anim[:delays][0]}\e\\"
+      play = case anim[:loops]
+             when nil then "s=2"
+             when 0 then "s=3,v=1"
+             else "s=3,v=#{anim[:loops] + 1}"
+             end
+      @buffer << "\e_Ga=a,i=#{image_id},#{play}\e\\"
     end
 
     # Delete a Kitty graphics protocol image by ID.
@@ -339,6 +354,19 @@ module RubyTUI
 
     private
 
+    # Base64-encode +payload+ and emit it as Kitty graphics APC sequences in
+    # 4096-byte chunks (safe for all Kitty-compatible terminals). The first
+    # chunk carries +first+; later chunks carry +cont+ (empty, or <tt>a=f,</tt>
+    # for animation frames, which the protocol requires on every chunk).
+    def send_chunked(first, cont, payload)
+      chunks = [payload].pack("m0").scan(/.{1,4096}/m) # strict base64, no newlines
+      chunks.each_with_index do |chunk, i|
+        more = i < chunks.length - 1 ? 1 : 0
+        params = i.zero? ? "#{first},m=#{more}" : "#{cont}m=#{more}"
+        @buffer << "\e_G#{params};#{chunk}\e\\"
+      end
+    end
+
     def apply_style(style)
       return if style == @prev_style
 

data/lib/rubytui/buffer.rb

@@ -203,9 +203,15 @@ module RubyTUI
     # @param src_y [Integer, nil] source rectangle Y offset in pixels
     # @param src_w [Integer, nil] source rectangle width in pixels
     # @param src_h [Integer, nil] source rectangle height in pixels
+    # @param animation [Hash, nil] extra frames for an animated image:
+    #   <tt>{frames: [rgba, ...], delays: [ms, ...], loops: Integer or nil}</tt>,
+    #   where +data+ is the first frame and +delays+ covers every frame
+    # @param compressed [Boolean] +data+ and the animation frames are already
+    #   zlib-deflated and are sent with the protocol's <tt>o=z</tt> (default: false)
     # @return [void]
     def set_image(x:, y:, cols:, rows:, data:, pixel_width:, pixel_height:, format:,
-                  content_hash: nil, src_x: nil, src_y: nil, src_w: nil, src_h: nil)
+                  content_hash: nil, src_x: nil, src_y: nil, src_w: nil, src_h: nil,
+                  animation: nil, compressed: false)
       # Key by position + content hash to detect when image changes at same position
       key = content_hash ? [x, y, content_hash] : [x, y]
 
@@ -223,6 +229,9 @@ module RubyTUI
         placement[:src_h] = src_h
       end
 
+      placement[:animation] = animation if animation
+      placement[:compressed] = true if compressed
+
       @image_placements[key] = placement
     end
 

data/lib/rubytui/gif.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # Pure-Ruby GIF decoder (GIF87a / GIF89a).
+  #
+  # Decodes every frame and composites it onto the logical screen, following
+  # each frame's disposal method, so every returned frame is a complete image.
+  # The canvas starts fully transparent (the logical-screen background colour
+  # is ignored), "restore to background" clears to transparent, and "restore to
+  # previous" restores the canvas as it was before the frame was drawn.
+  # Used by {Widgets::Image} to display GIFs through the Kitty graphics
+  # protocol, which only accepts RGB, RGBA or PNG data.
+  #
+  # @example
+  #   anim = RubyTUI::GIF.decode(File.binread("spinner.gif"))
+  #   anim.width        # => 32
+  #   anim.frames.size  # => 12
+  #   anim.delays       # => [100, 100, ...]  (milliseconds)
+  #   anim.loops        # => 0  (loop forever)
+  module GIF
+    # Decoded GIF.
+    #
+    # @!attribute [r] width
+    #   @return [Integer] logical screen width in pixels
+    # @!attribute [r] height
+    #   @return [Integer] logical screen height in pixels
+    # @!attribute [r] frames
+    #   @return [Array<String>] one RGBA string (4 bytes per pixel) per frame
+    # @!attribute [r] delays
+    #   @return [Array<Integer>] display time of each frame in milliseconds
+    # @!attribute [r] loops
+    #   @return [Integer, nil] NETSCAPE2.0 loop count: +0+ loops forever, +n+
+    #     repeats the animation +n+ more times, +nil+ (no loop extension) plays once
+    Animation = Struct.new(:width, :height, :frames, :delays, :loops)
+
+    # Largest accepted logical screen width or height, in pixels.
+    MAX_DIMENSION = 4096
+
+    # Largest accepted total decoded size (all frames, RGBA), in bytes.
+    MAX_DECODED_BYTES = 256 * 1024 * 1024
+
+    # Delay used for frames that declare less than 20 ms (the common browser convention).
+    MIN_DELAY_FALLBACK_MS = 100
+
+    # Rows of an interlaced image, in the order they are stored: every 8th row
+    # from 0, every 8th from 4, every 4th from 2, every 2nd from 1.
+    INTERLACE_PASSES = [[0, 8], [4, 8], [2, 4], [1, 2]].freeze
+    private_constant :INTERLACE_PASSES
+
+    # Fully transparent RGBA pixel.
+    TRANSPARENT = "\x00\x00\x00\x00".b.freeze
+    private_constant :TRANSPARENT
+
+    class << self
+      # Decode GIF data.
+      #
+      # @param data [String] raw GIF bytes
+      # @return [Animation]
+      # @raise [ArgumentError] if the data is not a GIF, is truncated or corrupt,
+      #   or exceeds {MAX_DIMENSION} / {MAX_DECODED_BYTES}
+      def decode(data)
+        Decoder.new(data.b).decode
+      end
+    end
+
+    # Stateful single-use decoder behind {GIF.decode}.
+    # @api private
+    class Decoder
+      # @param data [String] raw GIF bytes (binary)
+      def initialize(data)
+        @data = data
+        @pos = 0
+      end
+
+      # @return [Animation]
+      # @raise [ArgumentError] on invalid or oversized data
+      def decode
+        signature = read(6)
+        raise ArgumentError, "Invalid GIF data: bad signature" unless %w[GIF87a GIF89a].include?(signature)
+
+        @width, @height, packed, _bg, _aspect = read(7).unpack("vvCCC")
+        if @width.zero? || @height.zero? || @width > MAX_DIMENSION || @height > MAX_DIMENSION
+          raise ArgumentError, "Invalid GIF data: unsupported size #{@width}x#{@height} " \
+                               "(1..#{MAX_DIMENSION} pixels per side)"
+        end
+        @global_palette = packed & 0x80 != 0 ? read_palette(packed & 0x07) : nil
+
+        @canvas = TRANSPARENT * (@width * @height)
+        @frames = []
+        @delays = []
+        @loops = nil
+        @gce = nil
+
+        loop do
+          case read_byte
+          when 0x21 then read_extension
+          when 0x2C then read_image
+          when 0x3B then break
+          else raise ArgumentError, "Invalid GIF data: unexpected block at byte #{@pos - 1}"
+          end
+        end
+
+        raise ArgumentError, "Invalid GIF data: no image frames" if @frames.empty?
+
+        Animation.new(@width, @height, @frames, @delays, @loops)
+      end
+
+      private
+
+      def read(n)
+        bytes = @data.byteslice(@pos, n)
+        raise ArgumentError, "Invalid GIF data: truncated" if bytes.nil? || bytes.bytesize < n
+
+        @pos += n
+        bytes
+      end
+
+      def read_byte
+        read(1).getbyte(0)
+      end
+
+      # Concatenated data sub-blocks up to the block terminator.
+      def read_sub_blocks
+        out = String.new(encoding: Encoding::BINARY)
+        while (size = read_byte) != 0
+          out << read(size)
+        end
+        out
+      end
+
+      # Palette of 2**(bits + 1) entries, each a 4-byte opaque RGBA string.
+      def read_palette(bits)
+        read(3 * (2 << bits)).unpack("C*").each_slice(3).map { |r, g, b| [r, g, b, 255].pack("C4") }
+      end
+
+      def read_extension
+        label = read_byte
+        body = read_sub_blocks
+        case label
+        when 0xF9 # Graphic Control Extension
+          packed, delay, transparent = body.unpack("CvC")
+          @gce = {
+            disposal: (packed >> 2) & 0x07,
+            delay: delay,
+            transparent: packed & 0x01 != 0 ? transparent : nil
+          }
+        when 0xFF # Application Extension: NETSCAPE2.0 loop count
+          if body.start_with?("NETSCAPE2.0", "ANIMEXTS1.0") && body.getbyte(11) == 1
+            @loops = body.byteslice(12, 2).unpack1("v")
+          end
+        end
+      end
+
+      def read_image
+        left, top, w, h, packed = read(9).unpack("vvvvC")
+        palette = packed & 0x80 != 0 ? read_palette(packed & 0x07) : @global_palette
+        raise ArgumentError, "Invalid GIF data: frame has no colour table" unless palette
+
+        interlaced = packed & 0x40 != 0
+        min_code_size = read_byte
+        raise ArgumentError, "Invalid GIF data: bad LZW code size #{min_code_size}" unless (1..8).cover?(min_code_size)
+
+        indices = lzw_decode(read_sub_blocks, min_code_size, w * h)
+        indices = deinterlace(indices, w, h) if interlaced
+
+        if (@frames.size + 1) * @canvas.bytesize > MAX_DECODED_BYTES
+          raise ArgumentError, "GIF too large: decoded frames exceed #{MAX_DECODED_BYTES / (1024 * 1024)} MB"
+        end
+
+        gce = @gce || {}
+        @gce = nil
+        disposal = gce[:disposal] || 0
+        saved = @canvas.dup if disposal == 3
+
+        draw(indices, palette, gce[:transparent], left, top, w, h)
+        @frames << @canvas.dup
+        delay_ms = (gce[:delay] || 0) * 10
+        @delays << (delay_ms < 20 ? MIN_DELAY_FALLBACK_MS : delay_ms)
+
+        case disposal
+        when 2 then clear_rect(left, top, w, h)
+        when 3 then @canvas = saved
+        end
+      end
+
+      # LZW decompression (variable code size, max 12 bits) into palette indices.
+      def lzw_decode(data, min_code_size, pixel_count)
+        clear = 1 << min_code_size
+        eoi = clear + 1
+        base = Array.new(clear) { |i| i.chr(Encoding::BINARY) } + [nil, nil]
+        dict = base.dup
+        code_size = min_code_size + 1
+        out = String.new(capacity: pixel_count, encoding: Encoding::BINARY)
+        prev = nil
+        bits = 0
+        nbits = 0
+
+        data.each_byte do |byte|
+          bits |= byte << nbits
+          nbits += 8
+          while nbits >= code_size
+            code = bits & ((1 << code_size) - 1)
+            bits >>= code_size
+            nbits -= code_size
+
+            if code == clear
+              dict = base.dup
+              code_size = min_code_size + 1
+              prev = nil
+              next
+            end
+            return out if code == eoi
+
+            if prev.nil?
+              entry = dict[code]
+              raise ArgumentError, "Invalid GIF data: bad LZW code" unless entry
+            elsif code < dict.size
+              entry = dict[code]
+              dict << prev + entry[0] if dict.size < 4096
+            elsif code == dict.size
+              entry = prev + prev[0]
+              dict << entry if dict.size < 4096
+            else
+              raise ArgumentError, "Invalid GIF data: bad LZW code"
+            end
+
+            out << entry
+            return out if out.bytesize >= pixel_count
+
+            prev = entry
+            code_size += 1 if dict.size == (1 << code_size) && code_size < 12
+          end
+        end
+        out
+      end
+
+      # Reorder interlaced rows into top-to-bottom order.
+      def deinterlace(indices, w, h)
+        rows = Array.new(h)
+        n = 0
+        INTERLACE_PASSES.each do |start, step|
+          start.step(h - 1, step) do |y|
+            rows[y] = indices.byteslice(n * w, w)
+            n += 1
+          end
+        end
+        rows.join
+      end
+
+      # Composite one frame's pixels onto the canvas, clipped to the screen.
+      def draw(indices, palette, transparent, left, top, w, h)
+        x_end = [left + w, @width].min
+        return if left >= x_end
+
+        visible = x_end - left
+        h.times do |row|
+          y = top + row
+          break if y >= @height
+
+          src = indices.byteslice(row * w, visible) || ""
+          offset = (y * @width + left) * 4
+          if transparent.nil? || !src.include?(transparent.chr(Encoding::BINARY))
+            pixels = src.unpack("C*").map! { |i| palette[i] || TRANSPARENT }.join
+            @canvas[offset, pixels.bytesize] = pixels
+          else
+            src.each_byte.with_index do |i, x|
+              next if i == transparent
+
+              @canvas[offset + x * 4, 4] = palette[i] || TRANSPARENT
+            end
+          end
+        end
+      end
+
+      # Disposal method 2: restore the frame's area to transparent.
+      def clear_rect(left, top, w, h)
+        x_end = [left + w, @width].min
+        return if left >= x_end
+
+        blank = TRANSPARENT * (x_end - left)
+        h.times do |row|
+          y = top + row
+          break if y >= @height
+
+          @canvas[(y * @width + left) * 4, blank.bytesize] = blank
+        end
+      end
+    end
+  end
+end

data/lib/rubytui/version.rb

@@ -2,5 +2,5 @@
 
 module RubyTUI
   # Gem version string.
-  VERSION = "1.2.4"
+  VERSION = "1.2.5"
 end

data/lib/rubytui/widgets/image.rb

@@ -1,18 +1,23 @@
 # frozen_string_literal: true
 
 require "digest"
+require "zlib"
 
 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.
+    # Supports PNG files natively (sent directly to terminal, no decoding needed),
+    # raw RGBA pixel data, and GIF (decoded by {GIF}; animated GIFs play in the
+    # terminal). Works on terminals that implement the Kitty graphics protocol.
     #
-    # JPEG, WebP, GIF, and BMP are NOT supported — convert to PNG first:
+    # JPEG, WebP and BMP are NOT supported — convert to PNG first:
     #   system("magick", "input.jpg", "-resize", "800x600>", "output.png")
     #
+    # @example Animated GIF (plays in the terminal; animate: false shows the first frame)
+    #   image = RubyTUI::Widgets::Image.new(path: "spinner.gif")
+    #   frame.render_widget(image, area)
+    #
     # @example From a PNG file
     #   image = RubyTUI::Widgets::Image.new(path: "photo.png")
     #   frame.render_widget(image, area)
@@ -74,15 +79,17 @@ module RubyTUI
       # @return [Integer] image height in pixels
       attr_reader :pixel_height
 
-      # @return [Symbol] image format (:png or :rgba)
+      # @return [Symbol] image format (+:png+, +:rgba+ or +:gif+)
       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).
+      # @param path [String, nil] path to a PNG or GIF image file
+      # @param data [String, nil] raw image bytes (PNG, GIF or RGBA)
+      # @param pixel_width [Integer, nil] image width in pixels (required for :rgba, auto-detected for :png and :gif)
+      # @param pixel_height [Integer, nil] image height in pixels (required for :rgba, auto-detected for :png and :gif)
+      # @param format [Symbol] image format — +:png+, +:rgba+ or +:gif+. Auto-detected when +:png+ (default).
       #   Ignored when +path+ is given (the format is always detected).
+      # @param animate [Boolean] play animated GIFs in the terminal; +false+ shows
+      #   the first frame only (default: true). Ignored for other formats.
       # @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+
@@ -91,15 +98,16 @@ module RubyTUI
       # @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 +data+ is
-      #   given with a +format+ other than +:png+ or +:rgba+ (e.g. +:tiff+, a String
-      #   or +nil+), 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 (detected,
+      #   given with a +format+ other than +:png+, +:rgba+ or +:gif+ (e.g. +:tiff+, a
+      #   String or +nil+), if PNG or GIF data is truncated or corrupt (see
+      #   {GIF.decode}), 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 or BMP (detected,
       #   or given as +format+ with +data+)
       # @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)
+                     fit: nil, src_rect: nil, clip: true, cell_size: nil, animate: true)
         @style = style
         @block = block
         @fit = fit
@@ -125,6 +133,16 @@ module RubyTUI
 
           @pixel_width = pixel_width || dims[0]
           @pixel_height = pixel_height || dims[1]
+        elsif @format == :gif
+          # Decode and compress once; every (re)transmission reuses the result
+          gif = GIF.decode(@image_data)
+          @pixel_width = gif.width
+          @pixel_height = gif.height
+          frames = (animate ? gif.frames : gif.frames.first(1)).map { |f| Zlib::Deflate.deflate(f) }
+          @gif_root = frames.first
+          if frames.size > 1
+            @gif_animation = { frames: frames.drop(1), delays: gif.delays, loops: gif.loops }.freeze
+          end
         else
           raise ArgumentError, "pixel_width and pixel_height required for :rgba format" unless pixel_width && pixel_height
 
@@ -187,6 +205,15 @@ module RubyTUI
           content_hash: @content_hash
         }
 
+        # GIF: send the decoded first frame as compressed RGBA, plus the remaining
+        # frames when animating
+        if @gif_root
+          placement[:data] = @gif_root
+          placement[:format] = :rgba
+          placement[:compressed] = true
+          placement[:animation] = @gif_animation if @gif_animation
+        end
+
         # Add source rectangle if specified (for cropping/scrolling)
         if @src_rect
           placement[:src_x] = @src_rect.x
@@ -290,7 +317,7 @@ module RubyTUI
 
       def validate_format!(fmt)
         case fmt
-        when :png, :rgba
+        when :png, :rgba, :gif
           # OK
         when :jpeg
           raise UnsupportedImageFormat,
@@ -300,16 +327,12 @@ module RubyTUI
           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\")"
         else
-          raise ArgumentError, "Unknown image format #{fmt.inspect}; expected :png or :rgba"
+          raise ArgumentError, "Unknown image format #{fmt.inspect}; expected :png, :rgba or :gif"
         end
       end
 

data/lib/rubytui.rb

@@ -10,6 +10,7 @@ require_relative "rubytui/rect"
 require_relative "rubytui/style"
 require_relative "rubytui/cell"
 require_relative "rubytui/unicode"
+require_relative "rubytui/gif"
 require_relative "rubytui/buffer"
 require_relative "rubytui/symbols"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubytui
 version: !ruby/object:Gem::Version
-  version: 1.2.4
+  version: 1.2.5
 platform: ruby
 authors:
 - CoCL
@@ -34,6 +34,7 @@ files:
 - lib/rubytui/errors.rb
 - lib/rubytui/event.rb
 - lib/rubytui/frame.rb
+- lib/rubytui/gif.rb
 - lib/rubytui/input/key.rb
 - lib/rubytui/input/parser.rb
 - lib/rubytui/input/reader.rb