ratatui_ruby 1.0.0 → 1.1.0

data/ext/ratatui_ruby/src/terminal/mod.rs

@@ -7,6 +7,7 @@
 //! during `draw()` callbacks return data from a pre-captured snapshot,
 //! avoiding reentrancy issues with the terminal lock.
 
+mod capabilities;
 mod init;
 mod mutations;
 mod queries;
@@ -21,13 +22,21 @@ pub use storage::{
 pub use wrapper::TerminalWrapper;
 
 // Init/restore functions
-pub use init::{init_terminal, init_test_terminal, restore_terminal};
+pub use init::{
+    get_terminal_size_instance, init_terminal, init_test_terminal, init_test_terminal_instance,
+    restore_terminal,
+};
 
 // Query functions
 pub use queries::{
-    get_buffer_content, get_cell_at, get_cursor_position, get_terminal_area, get_terminal_size,
-    get_viewport_type,
+    frame_count, get_buffer_content, get_cell_at, get_cursor_position, get_terminal_area,
+    get_terminal_size, get_viewport_type,
 };
 
 // Mutation functions
 pub use mutations::{insert_before, resize_terminal, set_cursor_position};
+
+// Capability detection
+pub use capabilities::{
+    available_color_count, force_color_output, supports_keyboard_enhancement, terminal_window_size,
+};

data/ext/ratatui_ruby/src/terminal/queries.rs

@@ -214,3 +214,18 @@ fn modifiers_to_value(modifier: ratatui::style::Modifier) -> Value {
 
     ary.as_value()
 }
+
+/// Returns the number of frames that have been drawn
+pub fn frame_count() -> Result<usize, Error> {
+    let ruby = magnus::Ruby::get().unwrap();
+
+    crate::terminal::with_query(|q| Ok(q.frame_count())).unwrap_or_else(|| {
+        let module = ruby.define_module("RatatuiRuby").unwrap();
+        let error_base = module.const_get::<_, magnus::RClass>("Error").unwrap();
+        let error_class = error_base.const_get("Invariant").unwrap();
+        Err(Error::new(
+            error_class,
+            "Cannot query frame_count: terminal not initialized. Use RatatuiRuby.run or call init_terminal first.",
+        ))
+    })
+}

data/ext/ratatui_ruby/src/terminal/query.rs

@@ -19,6 +19,7 @@ pub trait TerminalQuery {
     fn is_test_mode(&self) -> bool;
     fn cursor_position(&self) -> Option<(u16, u16)>;
     fn cell_at(&self, x: u16, y: u16) -> Option<Cell>;
+    fn frame_count(&self) -> usize;
 }
 
 /// Snapshot of terminal state captured before draw.
@@ -30,6 +31,7 @@ pub struct DrawSnapshot {
     pub is_test_mode: bool,
     pub cursor_position: Option<(u16, u16)>,
     pub buffer: Option<ratatui::buffer::Buffer>,
+    pub frame_count: usize,
 }
 
 impl DrawSnapshot {
@@ -38,18 +40,23 @@ impl DrawSnapshot {
         match wrapper {
             super::wrapper::TerminalWrapper::Crossterm(t) => {
                 let size = t.size().unwrap_or_default();
-                let viewport = t.get_frame().area();
+                let frame = t.get_frame();
+                let viewport = frame.area();
+                let count = frame.count();
                 Self {
                     size: Rect::new(0, 0, size.width, size.height),
                     viewport_area: viewport,
                     is_test_mode: false,
                     cursor_position: None,
                     buffer: None,
+                    frame_count: count,
                 }
             }
             super::wrapper::TerminalWrapper::Test(t) => {
                 let size = t.size().unwrap_or_default();
-                let viewport = t.get_frame().area();
+                let frame = t.get_frame();
+                let viewport = frame.area();
+                let count = frame.count();
                 let cursor = t.get_cursor_position().ok().map(Into::into);
                 let buffer = t.backend().buffer().clone();
                 Self {
@@ -58,6 +65,7 @@ impl DrawSnapshot {
                     is_test_mode: true,
                     cursor_position: cursor,
                     buffer: Some(buffer),
+                    frame_count: count,
                 }
             }
         }
@@ -80,6 +88,9 @@ impl TerminalQuery for DrawSnapshot {
     fn cell_at(&self, x: u16, y: u16) -> Option<Cell> {
         self.buffer.as_ref()?.cell((x, y)).cloned()
     }
+    fn frame_count(&self) -> usize {
+        self.frame_count
+    }
 }
 
 /// Live queries against actual terminal (outside draw).
@@ -129,6 +140,12 @@ impl TerminalQuery for LiveTerminal<'_> {
             super::wrapper::TerminalWrapper::Crossterm(_) => None,
         }
     }
+    fn frame_count(&self) -> usize {
+        match *self.0.borrow_mut() {
+            super::wrapper::TerminalWrapper::Crossterm(ref mut t) => t.get_frame().count(),
+            super::wrapper::TerminalWrapper::Test(ref mut t) => t.get_frame().count(),
+        }
+    }
 }
 
 #[cfg(test)]
@@ -156,6 +173,9 @@ mod tests {
         fn cell_at(&self, _x: u16, _y: u16) -> Option<Cell> {
             None
         }
+        fn frame_count(&self) -> usize {
+            0
+        }
     }
 
     #[test]
@@ -174,6 +194,7 @@ mod tests {
             is_test_mode: false,
             cursor_position: None,
             buffer: None,
+            frame_count: 0,
         };
         assert_eq!(snapshot.size(), Rect::new(0, 0, 120, 40));
     }
@@ -186,6 +207,7 @@ mod tests {
             is_test_mode: false,
             cursor_position: None,
             buffer: None,
+            frame_count: 0,
         };
         // This should return the stored viewport_area, not Rect::default()
         assert_eq!(snapshot.viewport_area(), Rect::new(5, 10, 80, 20));
@@ -199,6 +221,7 @@ mod tests {
             is_test_mode: true, // TRUE!
             cursor_position: None,
             buffer: None,
+            frame_count: 0,
         };
         assert!(snapshot.is_test_mode());
     }
@@ -211,6 +234,7 @@ mod tests {
             is_test_mode: false,
             cursor_position: Some((15, 20)), // Not None!
             buffer: None,
+            frame_count: 0,
         };
         assert_eq!(snapshot.cursor_position(), Some((15, 20)));
     }
@@ -229,6 +253,7 @@ mod tests {
             is_test_mode: true,
             cursor_position: None,
             buffer: Some(buffer),
+            frame_count: 0,
         };
 
         let cell = snapshot.cell_at(5, 5);
@@ -335,4 +360,41 @@ mod tests {
         assert_eq!(viewport.width, 80);
         assert_eq!(viewport.height, 5);
     }
+
+    #[test]
+    fn test_live_terminal_frame_count_increases_after_draw() {
+        use crate::terminal::TerminalWrapper;
+        use ratatui::{backend::TestBackend, Terminal};
+
+        let backend = TestBackend::new(80, 24);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        // Draw once to increment the counter
+        terminal.draw(|_frame| {}).unwrap();
+
+        let mut wrapper = TerminalWrapper::Test(terminal);
+        let live = super::LiveTerminal::new(&mut wrapper);
+
+        // Frame count should be 1 after one draw, NOT 0!
+        assert_eq!(live.frame_count(), 1);
+    }
+
+    #[test]
+    fn test_live_terminal_frame_count_increases_with_multiple_draws() {
+        use crate::terminal::TerminalWrapper;
+        use ratatui::{backend::TestBackend, Terminal};
+
+        let backend = TestBackend::new(80, 24);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        // Draw twice
+        terminal.draw(|_frame| {}).unwrap();
+        terminal.draw(|_frame| {}).unwrap();
+
+        let mut wrapper = TerminalWrapper::Test(terminal);
+        let live = super::LiveTerminal::new(&mut wrapper);
+
+        // Frame count should be 2 after two draws!
+        assert_eq!(live.frame_count(), 2);
+    }
 }

data/lib/ratatui_ruby/backend/window_size.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Backend
+    # Terminal window dimensions in characters and pixels.
+    #
+    # Some operations need both character grid size and pixel dimensions.
+    # Sixel graphics, image rendering, and precise layout calculations all
+    # benefit from knowing both measurements at once.
+    #
+    # This struct bundles both sizes together. It matches upstream Ratatui's
+    # <tt>backend::WindowSize</tt> struct exactly.
+    #
+    # Both fields are <tt>Layout::Size</tt> instances. This reuses the same
+    # type for character and pixel dimensions, matching upstream design.
+    #
+    # Note: Pixel dimensions may be zero on some systems. Unix marks these
+    # fields "unused" in TIOCGWINSZ. Windows does not implement them.
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   ws = RatatuiRuby::Terminal.window_size
+    #   if ws
+    #     puts "#{ws.columns_rows.width}x#{ws.columns_rows.height} chars"
+    #     puts "#{ws.pixels.width}x#{ws.pixels.height} pixels"
+    #   end
+    #--
+    # SPDX-SnippetEnd
+    #++
+    class WindowSize < Data.define(:columns_rows, :pixels)
+      ##
+      # :attr_reader: columns_rows
+      # Size of the window in characters (columns/rows) as <tt>Layout::Size</tt>.
+
+      ##
+      # :attr_reader: pixels
+      # Size of the window in pixels as <tt>Layout::Size</tt>.
+    end
+  end
+end

data/lib/ratatui_ruby/backend.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  # Backend abstractions for terminal rendering.
+  #
+  # This module contains types related to terminal backend operations.
+  # It mirrors upstream Ratatui's <tt>backend</tt> module structure.
+  module Backend
+    class << self
+      # Queries terminal window size in characters and pixels.
+      #
+      # Some operations need both the character grid and pixel dimensions.
+      # Querying them separately wastes syscalls. Most backends fetch both
+      # at once anyway.
+      #
+      # This method queries crossterm for window dimensions. It returns a
+      # <tt>Backend::WindowSize</tt> with <tt>columns_rows</tt> and
+      # <tt>pixels</tt> fields, each as <tt>Layout::Size</tt> instances.
+      # Returns <tt>nil</tt> if the query fails.
+      #
+      # Note: Pixel dimensions may be zero on some systems. Unix marks
+      # these fields "unused" in TIOCGWINSZ. Windows does not implement them.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   ws = RatatuiRuby::Backend.window_size
+      #   if ws
+      #     puts "#{ws.columns_rows.width}x#{ws.columns_rows.height} chars"
+      #     puts "#{ws.pixels.width}x#{ws.pixels.height} pixels"
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def window_size
+        window_size = Terminal._terminal_window_size
+        return nil unless window_size
+        columns, rows, px_width, px_height = window_size
+        WindowSize.new(
+          columns_rows: Layout::Size.new(width: columns, height: rows),
+          pixels: Layout::Size.new(width: px_width, height: px_height)
+        )
+      rescue
+        nil
+      end
+    end
+  end
+end
+
+require_relative "backend/window_size"

data/lib/ratatui_ruby/event/key/navigation.rb

@@ -39,9 +39,18 @@ module RatatuiRuby
             return true if @code == "back_tab"
             return true if @code == "tab" && @modifiers.include?("shift")
           end
-
           # DWIM: Check explicit aliases
           navigation_aliases = {
+            # Arrow key aliases (disambiguate from Mouse#up? and Mouse#down?)
+            arrow_up: "up",
+            up_arrow: "up",
+            arrow_down: "down",
+            down_arrow: "down",
+            arrow_left: "left",
+            left_arrow: "left",
+            arrow_right: "right",
+            right_arrow: "right",
+            # Other navigation aliases
             return: "enter",
             back: "backspace",
             del: "delete",

data/lib/ratatui_ruby/event/key.rb

@@ -327,6 +327,60 @@ module RatatuiRuby
       #++
       #   event.media_pause?  # => true ONLY for media pause
       #   event.code == "pause"  # => true ONLY for system pause
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # === Arrow Key Aliases
+      #
+      # Arrow keys respond to <tt>arrow_up?</tt> and <tt>up_arrow?</tt> variants.
+      # This disambiguates from Mouse events, which also respond to <tt>up?</tt>
+      # and <tt>down?</tt>:
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   event.arrow_up?     # => true for up arrow key
+      #   event.up_arrow?     # => true for up arrow key
+      #   event.arrow_down?   # => true for down arrow key
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # === Key Prefix and Suffix
+      #
+      # Predicates accept <tt>key_</tt> prefix or <tt>_key</tt> suffix for explicit
+      # key event matching in mixed event contexts:
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   event.key_up?       # => true for up arrow key
+      #   event.key_q?        # => true for "q" key
+      #   event.q_key?        # => true for "q" key
+      #   event.enter_key?    # => true for enter key
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # === Capital Letters and Shift
+      #
+      # Capital letter predicates match shifted keys naturally. The terminal reports
+      # the produced character with shift in the modifiers:
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   event.G?            # => true for code="G" modifiers=["shift"]
+      #   event.shift_g?      # => true for code="G" modifiers=["shift"]
+      #   event.alt_B?        # => true for code="B" modifiers=["alt", "shift"]
+      #
       #--
       # SPDX-SnippetEnd
       #++
@@ -345,6 +399,36 @@ module RatatuiRuby
           return true if match_navigation_dwim?(key_name, key_sym)
           return true if match_system_dwim?(key_name, key_sym)
 
+          # DWIM: key_ prefix and _key suffix (disambiguate from mouse events)
+          # key_up? → up?, q_key? → q?, etc.
+          key_name = key_name.delete_prefix("key_").delete_suffix("_key")
+
+          # Fast path after prefix/suffix stripping
+          return true if self == key_name.to_sym
+
+          # DWIM: Single character codes match even with shift modifier present
+          # G? matches code="G" modifiers=["shift"], B? matches code="B" modifiers=["alt","shift"]
+          # @? matches code="@" modifiers=["shift"]
+          # The terminal reports the produced character, shift is implicit for these
+          if key_name.length == 1 && @code == key_name && @modifiers.include?("shift")
+            return true
+          end
+
+          # DWIM: Uppercase in predicate implies shift, so alt_B? matches alt_shift_B
+          # Parse predicate to extract modifiers and final letter
+          if key_name.match?(/\A([a-z_]+_)?([A-Z])\z/)
+            pred_letter = key_name[-1]
+            pred_mods = key_name.chop.delete_suffix("_").split("_").reject(&:empty?)
+            expected_mods = (pred_mods + ["shift"]).sort
+            return true if @code == pred_letter && @modifiers == expected_mods
+          end
+
+          # DWIM: Case-insensitive letter matching with modifiers
+          # shift_g? matches code="G" modifiers=["shift"]
+          if @code.length == 1 && @code.match?(/[A-Za-z]/) && (to_sym.to_s.downcase == key_name.downcase)
+            return true
+          end
+
           # DWIM: Universal underscore-insensitivity
           # Normalize both predicate and code by stripping underscores
           normalized_predicate = key_name.delete("_")

data/lib/ratatui_ruby/event/mouse.rb

@@ -110,6 +110,9 @@ module RatatuiRuby
         @kind == "up"
       end
 
+      alias mouse_down? down?
+      alias mouse_up? up?
+
       # Returns true if mouse is being dragged.
       def drag?
         @kind == "drag"
@@ -137,6 +140,25 @@ module RatatuiRuby
         @kind == "scroll_down"
       end
 
+      # Returns true if event involves the left mouse button.
+      def left?
+        @button == "left"
+      end
+
+      # Returns true if event involves the right mouse button.
+      def right?
+        @button == "right"
+      end
+
+      # Returns true if event involves the middle mouse button.
+      def middle?
+        @button == "middle"
+      end
+
+      alias left_button? left?
+      alias right_button? right?
+      alias middle_button? middle?
+
       # Deconstructs the event for pattern matching.
       #
       #--
@@ -156,10 +178,80 @@ module RatatuiRuby
       end
 
       ##
-      # Compares this event with another for equality.
+      # Converts the event to a Symbol representation.
+      #
+      # The format varies by event type:
+      #
+      # [Left Button]
+      #   <tt>:mouse_left_down</tt>, <tt>:mouse_left_up</tt>, <tt>:mouse_left_drag</tt>
+      # [Right Button]
+      #   <tt>:mouse_right_down</tt>, <tt>:mouse_right_up</tt>, <tt>:mouse_right_drag</tt>
+      # [Middle Button]
+      #   <tt>:mouse_middle_down</tt>, <tt>:mouse_middle_up</tt>, <tt>:mouse_middle_drag</tt>
+      # [Scroll]
+      #   <tt>:scroll_up</tt>, <tt>:scroll_down</tt>
+      # [Move]
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   <tt>:mouse_moved</tt>
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   event = Event::Mouse.new(kind: "down", x: 10, y: 5, button: "left")
+      #   event.to_sym  # => :mouse_left_down
+      #
+      #   scroll = Event::Mouse.new(kind: "scroll_up", x: 0, y: 0, button: "none")
+      #   scroll.to_sym # => :scroll_up
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def to_sym
+        if @kind.start_with?("scroll")
+          @kind.to_sym
+        elsif @button == "none"
+          :"mouse_#{@kind}"
+        else
+          :"mouse_#{@button}_#{@kind}"
+        end
+      end
+
+      ##
+      # Compares the event with another object.
+      #
+      # - If +other+ is a +Symbol+, compares against #to_sym.
+      # - If +other+ is a +Mouse+, compares as a value object.
+      # - Otherwise, returns +false+.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   if event == :mouse_left_down
+      #     handle_click(event)
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
       def ==(other)
-        return false unless other.is_a?(Mouse)
-        kind == other.kind && x == other.x && y == other.y && button == other.button && modifiers == other.modifiers
+        case other
+        when Symbol then to_sym == other
+        when Mouse then kind == other.kind && x == other.x && y == other.y && button == other.button && modifiers == other.modifiers
+        else false
+        end
       end
     end
   end

data/lib/ratatui_ruby/event/resize.rb

@@ -104,10 +104,52 @@ module RatatuiRuby
       end
 
       ##
-      # Compares this event with another for equality.
+      # Converts the event to a Symbol representation.
+      #
+      # Always returns <tt>:resize</tt>.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   event = Event::Resize.new(width: 80, height: 24)
+      #   event.to_sym # => :resize
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def to_sym
+        :resize
+      end
+
+      ##
+      # Compares the event with another object.
+      #
+      # - If +other+ is a +Symbol+, compares against #to_sym.
+      # - If +other+ is a +Resize+, compares as a value object.
+      # - Otherwise, returns +false+.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   if event == :resize
+      #     handle_resize(event)
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
       def ==(other)
-        return false unless other.is_a?(Resize)
-        width == other.width && height == other.height
+        case other
+        when Symbol then to_sym == other
+        when Resize then width == other.width && height == other.height
+        else false
+        end
       end
     end
   end