rubytui 1.2.3 → 1.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ec32a08aa7695cdc9b1db38895f10df4e37ff057dec2799b924fc2a6d8df860
-  data.tar.gz: 5a8a38833a21651b6372a420aea4be5e17b6f214653818b198c81303c45bf29d
+  metadata.gz: 3422d29230acde2c0e9da429cf3ddf83a355706183039778574e3e3d9b5875b9
+  data.tar.gz: '059ab8b520b2d61ca15a0ba129b211ea4c44a52cb4dd826e5401172bb8ed9c1c'
 SHA512:
-  metadata.gz: b0c26618a8ab168de7278fb24d0234b332983e0426ec945c2bb92ddc69da270788fd6d20ac578d792e9ac2d04398f374912ac118ebb316fdcb85aeb517197f97
-  data.tar.gz: 00a6150cc97eca7ca31eead19b04c1bbb0426a2c794dbf5208657199cc0e298a8d445c29aaf015519d41793d93890862cad04755b4bc182dfd98bdfa633c09dd
+  metadata.gz: 388a89d892b0f28d9ebbd9e0dd57f9dea31a65bca3d1d9da2f7af2c446fd9ddaddf05cc1d6cc5e3364860dd80225137573272230bf9dbed727c1edb075f750ae
+  data.tar.gz: 3c74612dc4bd6540af8b37cfdbec084ce5b6c292c9e2a64f9256b41ced9bca5855685930840adf199525a45de2b753a8b9bd099cf6ba0b26528db239de3c59e9

data/README.md

@@ -1,6 +1,6 @@
 # RubyTUI
 
-RubyTUI is a terminal user interface library written in pure Ruby with no runtime dependencies. It provides immediate-mode rendering with double buffering, constraint-based layouts, built-in widgets, keyboard and mouse input, an optional Model-View-Update application framework, and inline images through the Kitty graphics protocol.
+RubyTUI is a terminal user interface library for Ruby with no runtime dependencies. It provides immediate-mode rendering with double buffering, constraint-based layouts, built-in widgets, keyboard and mouse input, an optional Model-View-Update application framework, and inline images through the Kitty graphics protocol.
 
 It is suited both to full-screen interactive applications and to command-line tools that only need styled, one-shot output such as tables, boxes and progress bars.
 
@@ -82,6 +82,8 @@ line = RubyTUI::Line.new([
 paragraph = RubyTUI::Widgets::Paragraph.new(text: line)
 ```
 
+Paragraph layers styles from the outside in: the paragraph's `style:`, then the `Text`'s style, then each `Line`'s, then each `Span`'s, with later ones winning.
+
 Colors are sent to the terminal exactly as specified. To support terminals with fewer colors, use `RubyTUI::ColorMode` to detect the capability and convert colors yourself:
 
 ```ruby
@@ -131,14 +133,14 @@ All built-in widgets live in `RubyTUI::Widgets`. Most accept a `block:` argument
 |--------|------|-------------|
 | `Block` | stateless | Borders on all or selected sides, title aligned left, center or right, padding, background style. `block.inner(area)` returns the area inside the borders and padding. |
 | `Paragraph` | stateless | Multi-line styled text with word, character or no wrapping, aligned left, center or right. |
-| `List` + `ListState` | stateful | Scrollable, selectable list with a highlight symbol and style; scrolls to keep the selection visible. |
-| `Table` + `TableState` | stateful | Rows with an optional header and separator, row selection, and fixed or equally divided column widths. |
+| `List` + `ListState` | stateful | Scrollable, selectable list with a highlight symbol and style; scrolls to keep the selection visible. `ListState.new(selected: nil)` shows no selection. |
+| `Table` + `TableState` | stateful | Rows with an optional header and separator, row selection, and fixed or equally divided column widths. `TableState.new(selected: nil)` shows no selection. |
 | `Gauge` | stateless | Horizontal progress bar with eighth-of-a-cell precision and a centered label (the percentage by default). |
 | `Sparkline` | stateless | Compact bar chart, one column per value, showing the most recent values that fit. |
-| `Scrollbar` | stateless | Vertical or horizontal scroll indicator with a proportional thumb and optional arrows. |
-| `Tabs` | stateless | Horizontal tab bar with active and inactive styles and a configurable divider. |
+| `Scrollbar` | stateless | Vertical or horizontal scroll indicator with a proportional thumb and optional arrows. `style:` is the base style; `track_style:` and `thumb_style:` are applied on top. |
+| `Tabs` | stateless | Horizontal tab bar with active and inactive styles, an optional `highlight_style:` applied on top of the active tab, and a configurable divider. |
 | `Canvas` | stateless | Points, lines and text labels in data coordinates, drawn with Braille characters (2x4 dots per cell). |
-| `Chart` + `Dataset` | stateless | Line chart of one or more datasets with optional labeled axes and fixed or data-derived bounds. Dataset names are not displayed. |
+| `Chart` + `Dataset` | stateless | Line chart of one or more datasets with optional labeled axes and fixed or data-derived bounds; `style:` sets the base style (e.g. background) of the whole chart. Dataset names are not displayed. |
 | `Popup` | stateless | Overlay that clears its area and draws a block and an optional shadow; sized in cells or as a percentage of the parent, centered or placed at a fixed position. `popup.inner(area)` returns its content area. |
 | `InputField` + `InputState` | stateful | Single-line text input with a cursor, horizontal scrolling and a placeholder. |
 | `Image` | stateless | PNG or raw RGBA image drawn with the Kitty graphics protocol. See [Images](#images). |
@@ -192,7 +194,7 @@ end
 
 ## Input
 
-`reader.poll(timeout_ms: 100)` waits up to the given time and returns a `RubyTUI::KeyEvent`, a `RubyTUI::MouseEvent`, or `nil` when no recognized input arrived. `reader.read` blocks until an event arrives.
+`reader.poll(timeout_ms: 100)` waits up to the given time and returns a `RubyTUI::KeyEvent`, a `RubyTUI::MouseEvent`, a `RubyTUI::ResizeEvent` (the terminal size changed since the previous call; it has `width` and `height`), or `nil` when no recognized input arrived. Replies that the terminal writes to the input, such as image acknowledgements, are ignored. `reader.read` blocks until an event arrives and raises `EOFError` once the input is closed; `reader.eof?` reports whether that has happened. At end of input, `poll` waits out its timeout and returns `nil`.
 
 ### Keyboard
 
@@ -265,8 +267,8 @@ end
 
 `RubyTUI.run(mouse: true)` enables reporting of button presses, releases, drags and the scroll wheel. A `MouseEvent` has:
 
-- `button`: `:left`, `:middle`, `:right`, `:scroll_up`, `:scroll_down` or `:none` (constants `RubyTUI::MouseEvent::LEFT` and so on)
-- `action`: `:press`, `:release` or `:drag` (scroll-wheel events are reported as `:press`)
+- `button`: `:left`, `:middle`, `:right`, `:scroll_up`, `:scroll_down`, `:scroll_left`, `:scroll_right` or `:none` (constants `RubyTUI::MouseEvent::LEFT` and so on)
+- `action`: `:press`, `:release` or `:drag` (scroll-wheel events are reported as `:press`). `:move`, pointer motion with no button held, is only reported if the terminal is switched to any-motion mode (1003), which `RubyTUI.run(mouse: true)` does not do.
 - `x`, `y`: zero-based cell coordinates
 - `ctrl?`, `alt?`, `shift?`
 
@@ -296,12 +298,12 @@ For structured applications, include `RubyTUI::App` and implement the hooks belo
 | Hook | Purpose |
 |------|---------|
 | `init` | Returns the initial model (any object; a Hash by default). |
-| `handle_event(event)` | Converts an input event into a message, or returns `nil` to ignore it. |
+| `handle_event(event)` | Converts an input event (`KeyEvent`, `MouseEvent` or `ResizeEvent`) into a message, or returns `nil` to ignore it. |
 | `handle_tick(model)` | Called after every poll, whether or not an event arrived; returns a message or `nil`. Use it for animations and periodic work. |
 | `update(model, msg)` | Returns the next model. Call `throw(:quit)` or `throw(:quit, value)` to leave the loop. |
 | `view(model, frame)` | Draws the model into the frame. |
 | `on_start(terminal, reader)` | Called once after `init`, before the loop starts. |
-| `on_stop(value)` | Called once after the loop ends and before the terminal is restored, with the value given to `throw(:quit, value)` (or `nil`). |
+| `on_stop(value)` | Called once after the loop ends and before the terminal is restored, with the value given to `throw(:quit, value)`, or the last model after a bare `throw(:quit)`. |
 
 ```ruby
 require "rubytui"
@@ -384,7 +386,7 @@ RubyTUI.print_gauge(ratio: 0.75, title: " Progress ", width: 40)
 ```
 
 - `print_table(header:, rows:, title:, border:, width:, ...)` also accepts `widths:`, `column_spacing:`, `header_style:`, `style:` and `border_style:`. The border is drawn only when `title:` is given.
-- `print_box(title:, content:, border:, width:, ...)` takes a string (split on newlines) or an array of lines, and also accepts `alignment:`, `text_style:`, `style:` and `border_style:`.
+- `print_box(title:, content:, border:, width:, ...)` takes a String (split on newlines), an Array of lines, or a `Text`, `Line` or `Span`; the box is as tall as the content after wrapping to the box width. It also accepts `alignment:`, `text_style:`, `style:` and `border_style:`.
 - `print_gauge(ratio:, label:, title:, width:, ...)` also accepts `gauge_style:`, `border:` and `border_style:`. The border is drawn only when `title:` is given.
 
 `border:` is one of `:rounded` (the default), `:light`, `:double`, `:thick` or `:plain`, or a `RubyTUI::Symbols` border set.
@@ -409,13 +411,18 @@ 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
 # From a PNG file
 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",
@@ -464,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(
@@ -481,9 +488,8 @@ image.ready?    # => true once the image can be drawn
 image.error?    # => true if the loader raised or returned unsupported data; see image.error
 ```
 
-- While loading, `Loading...` is drawn centered in the area; after a failure, `error_placeholder:` (default `[Error]`) is drawn.
-- `placeholder:` accepts a widget that includes `RubyTUI::Widget` (all built-in widgets do), which is drawn instead until the image is ready, or a string, which is shown before loading starts when `auto_start: false` is given. With `auto_start: false`, call `start_loading` to begin; `cancel` stops the loader thread.
-- `on_ready:` is called on the loader thread when the loader has returned (not on a cache hit); `on_error:` receives the exception raised by the loader.
+- Until the image is ready, `placeholder:` is drawn: a string is shown centered (`Loading...` if no placeholder is given), and a widget that includes `RubyTUI::Widget` (all built-in widgets do) is rendered in the area. After a failure, `error_placeholder:` (default `[Error]`) is drawn. With `auto_start: false`, call `start_loading` to begin; `cancel` stops the loader thread.
+- `on_ready:` is called on the loader thread once the image is ready (not on a cache hit); an exception it raises does not change the widget's state. `on_error:` receives the exception when the loader raises or returns data that is not a supported image (including `nil`); such data is not cached.
 - `cache:` (a Hash shared between instances) and `key:` reuse loaded data: when the cache already holds the key, the widget is ready immediately and the loader is not called.
 - `block:`, `style:` and `cell_size:` work as for `Image`.
 

data/lib/rubytui/app.rb

@@ -109,9 +109,9 @@ module RubyTUI
     #
     # Called before the terminal is restored.
     #
-    # @param model [Object, nil] the result of the <tt>catch(:quit)</tt> block:
-    #   the value passed as <tt>throw(:quit, value)</tt>, or nil for a bare
-    #   <tt>throw(:quit)</tt>
+    # @param model [Object] the value passed as <tt>throw(:quit, value)</tt>,
+    #   or the last model returned by {#init} or {#update} for a bare
+    #   <tt>throw(:quit)</tt> or <tt>throw(:quit, nil)</tt>
     # @return [void]
     def on_stop(model)
     end
@@ -119,7 +119,9 @@ module RubyTUI
     # Run the application.
     #
     # The main loop renders, polls for events, and dispatches messages.
-    # Call <tt>throw(:quit)</tt> from {#update} to exit the loop cleanly.
+    # Call <tt>throw(:quit)</tt> from {#update} to exit the loop cleanly;
+    # {#on_stop} then receives the last model, or +value+ for
+    # <tt>throw(:quit, value)</tt>.
     #
     # Wraps {RubyTUI.run} (raw mode, hidden cursor, alternate screen), so
     # the terminal is restored when the loop exits or raises. Each
@@ -138,7 +140,7 @@ module RubyTUI
         model = init
         on_start(terminal, reader)
 
-        model = catch(:quit) do
+        quit_value = catch(:quit) do
           loop do
             terminal.draw do |frame|
               view(model, frame)
@@ -156,7 +158,7 @@ module RubyTUI
           end
         end
 
-        on_stop(model)
+        on_stop(quit_value.nil? ? model : quit_value)
       end
     end
 

data/lib/rubytui/backends/ansi_backend.rb

@@ -64,7 +64,7 @@ module RubyTUI
         @buffer << cell.symbol
 
         # Wide characters advance terminal cursor by 2
-        w = cell.symbol.length == 1 ? Buffer.char_width(cell.symbol) : 1
+        w = cell.symbol.length == 1 ? Unicode.char_width(cell.symbol) : 1
         last_x = x + w - 1
         last_y = y
       end
@@ -167,17 +167,18 @@ module RubyTUI
     # 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.
+    # +cooked!+ (when the input supports it) if no state was saved, or
+    # +stty+ raises, exits non-zero or cannot be run.
     #
     # @return [void]
     def disable_raw_mode
       if @original_state
-        begin
+        restored = begin
           system("stty", @original_state, in: @input, err: File::NULL)
         rescue StandardError
-          @input.cooked! if @input.respond_to?(:cooked!)
+          false
         end
+        @input.cooked! if !restored && @input.respond_to?(:cooked!)
         @original_state = nil
       elsif @input.respond_to?(:cooked!)
         @input.cooked!
@@ -199,37 +200,41 @@ module RubyTUI
     #
     # 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.
+    # Falls back to [9, 18] when the terminal does not answer within 100 ms,
+    # the query raises +IOError+, +Errno::EIO+ or +Errno::ENOTTY+, or the
+    # input does not support raw mode (e.g. a StringIO; no query is sent);
+    # 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"
+      # Inputs without raw mode (e.g. StringIO) cannot read the reply
+      if @input.respond_to?(:raw)
+        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
-          end
 
-          if response =~ /\e\[6;(\d+);(\d+)t/
-            @cell_pixel_size = [$2.to_i, $1.to_i]
+            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
-      rescue IOError, Errno::EIO, Errno::ENOTTY
-        # Terminal doesn't support query
       end
 
       @cell_pixel_size ||= [9, 18]
@@ -244,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]
@@ -256,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.
@@ -334,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
 
@@ -273,9 +282,8 @@ module RubyTUI
       prev_style = nil
 
       @area.height.times do |row|
-        # Build the row content and track the last non-empty column
+        # Build the row content
         row_buf = String.new(capacity: @area.width * 2)
-        last_styled_col = -1
         col = 0
         display_col = 0  # track actual terminal column for cursor correction
 
@@ -298,11 +306,6 @@ module RubyTUI
 
           row_buf << cell.symbol
 
-          # Track last non-default cell for trimming
-          unless cell.empty?
-            last_styled_col = col
-          end
-
           w = Unicode.string_width(cell.symbol)
           display_col += w
           col += [w, 1].max

data/lib/rubytui/errors.rb

@@ -4,8 +4,10 @@ module RubyTUI
   # Base class for all RubyTUI-specific errors.
   class Error < StandardError; end
   # Error category for terminal-related failures.
+  # @deprecated Never raised by RubyTUI; will be removed in 2.0.
   class TerminalError < Error; end
   # Error category for layout-related failures.
+  # @deprecated Never raised by RubyTUI; will be removed in 2.0.
   class LayoutError < Error; end
   # Raised by {Widgets::Image} when given image data in a format the Kitty
   # graphics protocol path does not accept (JPEG, WebP, GIF or BMP).

data/lib/rubytui/event.rb

@@ -17,7 +17,8 @@ module RubyTUI
 
     # @param code [Symbol] key code, one of the {Input::Key} key-code constants
     #   (e.g. {Input::Key::ENTER}, {Input::Key::CHAR})
-    # @param char [String, nil] the character, for {Input::Key::CHAR} events (default: nil)
+    # @param char [String, nil] the character, for {Input::Key::CHAR} events; a
+    #   UTF-8 String when produced by {Input::Parser} (default: nil)
     # @param modifiers [Integer] bitmask of {Input::Key::SHIFT}, {Input::Key::ALT} and
     #   {Input::Key::CTRL} (default: {Input::Key::NONE})
     def initialize(code:, char: nil, modifiers: Input::Key::NONE)
@@ -75,6 +76,10 @@ module RubyTUI
     SCROLL_UP   = :scroll_up
     # Scroll wheel down (reported with action {PRESS}).
     SCROLL_DOWN = :scroll_down
+    # Horizontal scroll left, wheel button 6 (reported with action {PRESS}).
+    SCROLL_LEFT = :scroll_left
+    # Horizontal scroll right, wheel button 7 (reported with action {PRESS}).
+    SCROLL_RIGHT = :scroll_right
     # No specific button (legacy-protocol release, or motion with no button held).
     NONE      = :none
 
@@ -86,9 +91,11 @@ module RubyTUI
     PRESS   = :press
     # Button released.
     RELEASE = :release
-    # Pointer motion reported by the terminal (motion flag set).
+    # Pointer motion with a button held.
     DRAG    = :drag
-    # Pointer motion with no button held. Currently never emitted by {Input::Parser}.
+    # Pointer motion with no button held (button {NONE}). Terminals report it
+    # only in any-event tracking (mode 1003), which
+    # {AnsiBackend#enable_mouse} does not turn on.
     MOVE    = :move
 
     # @!endgroup
@@ -96,7 +103,7 @@ module RubyTUI
     attr_reader :button, :action, :x, :y, :modifiers
 
     # @param button [Symbol] button constant ({LEFT}, {MIDDLE}, {RIGHT},
-    #   {SCROLL_UP}, {SCROLL_DOWN} or {NONE})
+    #   {SCROLL_UP}, {SCROLL_DOWN}, {SCROLL_LEFT}, {SCROLL_RIGHT} or {NONE})
     # @param action [Symbol] action constant ({PRESS}, {RELEASE}, {DRAG} or {MOVE})
     # @param x [Integer] column (0-based cell coordinate)
     # @param y [Integer] row (0-based cell coordinate)
@@ -144,6 +151,9 @@ module RubyTUI
   end
 
   # A terminal resize event carrying the new size in cells.
+  #
+  # {Input::Reader#poll} and {Input::Reader#read} return one when the size of
+  # the input terminal has changed since the previous call.
   class ResizeEvent < Event
     attr_reader :width, :height