ratatui_ruby 0.9.0 → 0.10.0

data/lib/ratatui_ruby/widgets/sparkline.rb

@@ -24,6 +24,8 @@ module RatatuiRuby
     #
     #   ruby examples/widget_sparkline/app.rb
     class Sparkline < Data.define(:data, :max, :style, :block, :direction, :absent_value_symbol, :absent_value_style, :bar_set)
+      include CoerceableWidget
+
       ##
       # :attr_reader: data
       # Array of integer values to plot.
@@ -114,19 +116,25 @@ module RatatuiRuby
       # [bar_set] Symbol, Hash, or Array of custom characters (optional).
       #   Symbols: <tt>:nine_levels</tt> (default gradient), <tt>:three_levels</tt> (simplified).
       def initialize(data:, max: nil, style: nil, block: nil, direction: :left_to_right, absent_value_symbol: nil, absent_value_style: nil, bar_set: nil)
-        if bar_set && !bar_set.is_a?(Symbol)
-          if bar_set.is_a?(Array) && bar_set.size == 9
-            # Convert Array to Hash using BAR_KEYS order
-            bar_set = BAR_KEYS.zip(bar_set).to_h
-          else
-            bar_set = bar_set.dup
-            # Normalize numeric keys (0-8) to symbolic keys
-            BAR_KEYS.each_with_index do |key, i|
-              if (val = bar_set.delete(i) || bar_set.delete(i.to_s))
-                bar_set[key] = val
-              end
-            end
-          end
+        # Normalize bar_set to Hash[Symbol, String] if provided as Array or Hash
+        bar_set = case bar_set
+                  when Symbol, nil
+                    bar_set
+                  when Array
+                    # Convert Array to Hash using BAR_KEYS order
+                    BAR_KEYS.zip(bar_set).to_h
+                  when Hash
+                    # @type var raw_hash: Hash[untyped, untyped]
+                    raw_hash = bar_set.dup
+                    normalized = {} #: Hash[Symbol, String]
+                    # Normalize numeric keys (0-8) to symbolic keys
+                    BAR_KEYS.each_with_index do |key, i|
+                      val = raw_hash.delete(i) || raw_hash.delete(i.to_s) || raw_hash.delete(key)
+                      normalized[key] = val.to_s if val
+                    end
+                    normalized
+                  else
+                    bar_set
         end
         coerced_data = data.map { |v| v.nil? ? nil : Integer(v) }
         super(

data/lib/ratatui_ruby/widgets/table.rb

@@ -24,6 +24,8 @@ module RatatuiRuby
     #
     #   ruby examples/widget_table_flex/app.rb
     class Table < Data.define(:header, :rows, :widths, :row_highlight_style, :highlight_symbol, :highlight_spacing, :column_highlight_style, :cell_highlight_style, :selected_row, :selected_column, :offset, :block, :footer, :flex, :style, :column_spacing)
+      include CoerceableWidget
+
       ##
       # Highlight spacing: always show the spacing column.
       HIGHLIGHT_ALWAYS = :always
@@ -66,7 +68,8 @@ module RatatuiRuby
 
       ##
       # :attr_reader: widths
-      # Column width constraints (Array of Constraint).
+      # Column width constraints (Array of Constraint or Integer).
+      # Integers are automatically coerced to Constraint.length.
 
       ##
       # :attr_reader: row_highlight_style
@@ -136,7 +139,7 @@ module RatatuiRuby
       #
       # [header] Array of strings, Text::Spans, Text::Lines, or paragraphs.
       # [rows] 2D Array where each cell is String, Text::Span, Text::Line, Paragraph, or Cell.
-      # [widths] Array of Constraints.
+      # [widths] Array of Constraints or Integers (integers coerce to Constraint.length).
       # [row_highlight_style] Style object.
       # [highlight_symbol] String.
       # [highlight_spacing] Symbol (optional, default: <tt>:when_selected</tt>).
@@ -151,10 +154,14 @@ module RatatuiRuby
       # [style] Style object or Hash (optional).
       # [column_spacing] Integer (optional, default: 1).
       def initialize(header: nil, rows: [], widths: [], row_highlight_style: nil, highlight_symbol: "> ", highlight_spacing: :when_selected, column_highlight_style: nil, cell_highlight_style: nil, selected_row: nil, selected_column: nil, offset: nil, block: nil, footer: nil, flex: :legacy, style: nil, column_spacing: 1)
+        coerced_widths = widths.map do |w|
+          w.is_a?(Integer) ? Layout::Constraint.length(w) : w
+        end
+
         super(
           header:,
           rows:,
-          widths:,
+          widths: coerced_widths,
           row_highlight_style:,
           highlight_symbol:,
           highlight_spacing:,
@@ -198,6 +205,9 @@ module RatatuiRuby
       def empty?
         rows.empty?
       end
+
+      # NOTE: No 'selection' alias - it's ambiguous whether it returns a row or index.
+      # Use selected_row for the row index, selected_column for the column index.
     end
   end
 end

data/lib/ratatui_ruby/widgets/tabs.rb

@@ -23,6 +23,8 @@ module RatatuiRuby
     #
     #   ruby examples/widget_tabs/app.rb
     class Tabs < Data.define(:titles, :selected_index, :block, :divider, :highlight_style, :style, :padding_left, :padding_right)
+      include CoerceableWidget
+
       ##
       # :attr_reader: titles
       # Tab titles (Array of Strings).
@@ -65,8 +67,8 @@ module RatatuiRuby
       # [divider] String (optional).
       # [highlight_style] Style (optional).
       # [style] Style (optional).
-      # [padding_left] Integer, String, or Line (default: 0).
-      # [padding_right] Integer, String, or Line (default: 0).
+      # [padding_left] String, Line, or anything that responds to <tt>to_i</tt> (default: 0).
+      # [padding_right] String, Line, or anything that responds to <tt>to_i</tt> (default: 0).
       def initialize(titles: [], selected_index: 0, block: nil, divider: nil, highlight_style: nil, style: nil, padding_left: 0, padding_right: 0)
         super(
           titles:,
@@ -75,8 +77,8 @@ module RatatuiRuby
           divider:,
           highlight_style:,
           style:,
-          padding_left:,
-          padding_right:
+          padding_left: (padding_left.is_a?(Text::Line) || padding_left.is_a?(String)) ? padding_left : Integer(padding_left),
+          padding_right: (padding_right.is_a?(Text::Line) || padding_right.is_a?(String)) ? padding_right : Integer(padding_right)
         )
       end
 

data/lib/ratatui_ruby/widgets.rb

@@ -15,6 +15,7 @@ module RatatuiRuby
 end
 
 # Core widgets
+require_relative "widgets/coerceable_widget"
 require_relative "widgets/block"
 require_relative "widgets/paragraph"
 require_relative "widgets/list"

data/lib/ratatui_ruby.rb

@@ -12,8 +12,9 @@ require_relative "ratatui_ruby/layout"   # Layout::Rect, Layout::Constraint, Lay
 require_relative "ratatui_ruby/style"    # Style::Style
 require_relative "ratatui_ruby/widgets"  # Widgets::Block, Widgets::Paragraph, etc.
 require_relative "ratatui_ruby/buffer"   # Buffer::Cell (for inspection)
-require_relative "ratatui_ruby/schema/text"  # Text::Span, Text::Line
-require_relative "ratatui_ruby/schema/draw"  # Draw commands
+require_relative "ratatui_ruby/text"    # Text::Span, Text::Line, Text.width
+require_relative "ratatui_ruby/draw"    # Draw commands
+require_relative "ratatui_ruby/symbols" # Symbols::Shade, etc.
 
 # Event types
 require_relative "ratatui_ruby/event"
@@ -31,6 +32,9 @@ require_relative "ratatui_ruby/terminal_lifecycle"
 # TUI facade (for external instantiation and caching)
 require_relative "ratatui_ruby/tui"
 
+# Synthetic events queue (for async synchronization)
+require_relative "ratatui_ruby/synthetic_events"
+
 begin
   require "ratatui_ruby/ratatui_ruby"
 rescue LoadError
@@ -38,6 +42,10 @@ rescue LoadError
   require_relative "ratatui_ruby/ratatui_ruby"
 end
 
+# Debug mode (for Rust backtraces and diagnostic features)
+# Loaded after native extension so _enable_rust_backtrace is defined
+require_relative "ratatui_ruby/debug"
+
 # Main entry point for the library.
 #
 # Terminal UIs require low-level control using C/Rust and high-level abstraction in Ruby.
@@ -120,16 +128,17 @@ module RatatuiRuby
     #++
     class Safety < Error; end
 
-    # State invariant violation.
+    # Invariant violation.
     #
-    # The library has rules about valid state transitions.
-    # Calling methods in the wrong order or state breaks invariants.
+    # The library enforces rules about valid states and contracts.
+    # Breaking these rules raises this error.
     #
-    # This error signals you violated a state machine contract.
-    # The program state doesn't allow this operation right now.
+    # Common causes:
+    # - Calling methods in the wrong order (e.g., \`init_terminal\` twice)
+    # - Callable return type mismatch (e.g., view returns \`nil\` instead of a widget)
     #
-    # To resolve, check `terminal_active?` or restructure the
-    # code to ensure methods are called in the expected order.
+    # To resolve, check the method's documented contract. Ensure
+    # state preconditions are met and return types are correct.
     #
     # === Example
     #
@@ -150,13 +159,10 @@ module RatatuiRuby
   extend OutputGuard
   extend TerminalLifecycle
 
-  # Re-export NullIO at module root for backward compatibility
-  NullIO = OutputGuard::NullIO
-
   @experimental_warnings = true
   @tui_session_active = false
   @headless_mode = false
-  @deferred_warnings = []
+  @deferred_warnings = [] #: Array[String]
 
   class << self
     ##
@@ -173,6 +179,13 @@ module RatatuiRuby
       @deferred_warnings.each { |msg| warn msg }
       @deferred_warnings.clear
     end
+
+    private def flush_panic_info
+      return unless Debug.rust_backtrace_enabled?
+      panic_info = _get_last_panic
+      return unless panic_info
+      warn panic_info
+    end
   end
 
   ##
@@ -202,7 +215,7 @@ module RatatuiRuby
   def self.warn_experimental_feature(feature_name)
     return unless experimental_warnings
 
-    @warned_features ||= {}
+    @warned_features ||= {} #: Hash[String, bool]
     return if @warned_features[feature_name]
 
     message = "WARNING: #{feature_name} is an experimental feature and may change in future versions. Disable this warning with RatatuiRuby.experimental_warnings = false."
@@ -215,7 +228,28 @@ module RatatuiRuby
   end
 
   # (Native methods implemented in Rust)
-  private_class_method :_init_terminal, :_restore_terminal, :_init_test_terminal
+  private_class_method :_init_terminal, :_restore_terminal, :_init_test_terminal, :_enable_rust_backtrace, :_get_last_panic
+
+  ##
+  # Enables full debug mode.
+  #
+  # Convenience alias for Debug.enable!.
+  #
+  # === Example
+  #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
+  #   RatatuiRuby.debug_mode!
+  #
+  #--
+  # SPDX-SnippetEnd
+  #++
+  def self.debug_mode!
+    Debug.enable!
+  end
 
   ##
   # Draws the given UI node tree to the terminal.
@@ -277,7 +311,7 @@ module RatatuiRuby
 
     if tree
       _draw(tree)
-    else
+    elsif block
       _draw(&block)
     end
   end
@@ -392,6 +426,7 @@ module RatatuiRuby
       char: raw["char"],
       fg: raw["fg"],
       bg: raw["bg"],
+      underline_color: raw["underline_color"],
       modifiers: raw["modifiers"] || []
     )
   end

data/sig/examples/app_all_events/model/app_model.rbs

@@ -0,0 +1,23 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# MVU application model for the All Events example.
+class AppModel < Data
+  HIGHLIGHT_DURATION_MS: Integer
+
+  attr_reader entries: Array[EventEntry]
+  attr_reader focused: bool
+  attr_reader window_size: [Integer, Integer]
+  attr_reader lit_types: Hash[Symbol, Timestamp]
+  attr_reader none_count: Integer
+  attr_reader color_cycle_index: Integer
+
+  def self.initial: () -> instance
+  def count: (Symbol type) -> Integer
+  def sub_counts: (Symbol type) -> Hash[String, Integer]
+  def lit?: (Symbol type) -> bool
+  def visible: (Integer max_entries) -> Array[EventEntry]
+  def empty?: () -> bool
+  def live_event: (Symbol type) -> { time: Time, description: String }?
+  def next_color: () -> Symbol
+end

data/sig/examples/app_all_events/model/event_entry.rbs

@@ -1,16 +1,23 @@
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+# Type alias for any Event subtype.
+type event_type = RatatuiRuby::Event::Key
+               | RatatuiRuby::Event::Mouse
+               | RatatuiRuby::Event::Resize
+               | RatatuiRuby::Event::Paste
+               | RatatuiRuby::Event::FocusGained
+               | RatatuiRuby::Event::FocusLost
+               | RatatuiRuby::Event::None
+
 class EventEntry < Data
-  attr_reader type: Symbol
-  attr_reader sub_key: Symbol | String | nil
+  attr_reader event: event_type
   attr_reader color: Symbol
   attr_reader timestamp: Timestamp
-  attr_reader data: Hash[Symbol, untyped]
 
-  def self.from_event(type: Symbol, sub_key: Symbol | String | nil, color: Symbol, timestamp: Timestamp, data: Hash[Symbol, untyped]) -> instance
+  def self.create: (event_type event, Symbol color, Timestamp timestamp) -> instance
+  def type: () -> Symbol
+  def description: () -> String
   def matches_type?: (Symbol check_type) -> bool
-  def matches_sub_type?: (Symbol check_type, Symbol | String check_sub_key) -> bool
-  def matches_kind?: (String kind) -> bool
-  def self.new: (?type: Symbol, ?sub_key: Symbol | String | nil, ?color: Symbol, ?timestamp: Timestamp, ?data: Hash[Symbol, untyped]) -> instance
+  def live_type: () -> Symbol
 end

data/sig/examples/app_all_events/model/timestamp.rbs

@@ -7,5 +7,5 @@ class Timestamp < Data
   def self.now: () -> instance
   def self.current: () -> Integer
   def elapsed?: (Integer duration_ms) -> bool
-  def self.new: (?milliseconds: Numeric) -> instance
+  def self.new: (?milliseconds: _ToI) -> instance
 end

data/sig/examples/app_all_events/view.rbs

@@ -9,6 +9,6 @@
 
 module View
   interface _View
-    def call(state: ViewState, tui: RatatuiRuby::TUI, frame: RatatuiRuby::Frame, area: RatatuiRuby::Rect) -> void
+    def call: (AppModel model, RatatuiRuby::TUI tui, RatatuiRuby::Frame frame, RatatuiRuby::Layout::Rect area) -> void
   end
 end

data/sig/examples/app_stateful_interaction/app.rbs

@@ -13,12 +13,12 @@ class AppStatefulInteraction
   @list_state: RatatuiRuby::ListState
   @table_state: RatatuiRuby::TableState
   @active_pane: :list | :table
-  @tui: untyped
+  @tui: RatatuiRuby::TUI
   @style_active: RatatuiRuby::Style
   @style_inactive: RatatuiRuby::Style
   @style_highlight: RatatuiRuby::Style
-  @list_area: RatatuiRuby::Rect
-  @table_area: RatatuiRuby::Rect
+  @list_area: RatatuiRuby::Layout::Rect
+  @table_area: RatatuiRuby::Layout::Rect
 
   # @public
   def self.new: () -> AppStatefulInteraction
@@ -29,8 +29,8 @@ class AppStatefulInteraction
   private
 
   def render: () -> void
-  def render_list: (untyped frame, RatatuiRuby::Rect area) -> void
-  def render_table: (untyped frame, RatatuiRuby::Rect area) -> void
+  def render_list: (RatatuiRuby::Frame frame, RatatuiRuby::Layout::Rect area) -> void
+  def render_table: (RatatuiRuby::Frame frame, RatatuiRuby::Layout::Rect area) -> void
   def handle_input: () -> (:quit | nil)
   def scroll_active: (Integer delta) -> void
   def handle_click: (Integer x, Integer y) -> void

data/sig/examples/widget_block_demo/app.rbs

@@ -10,25 +10,25 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 class WidgetBlockDemo
-  @tui: RatatuiRuby::Tui
+  @tui: RatatuiRuby::TUI
   @hotkey_style: RatatuiRuby::Style
   @title_configs: Array[{name: String, title: String?}]
   @title_index: Integer
-  @titles_configs: Array[{name: String, titles: Array[RatatuiRuby::Block::title_input]}]
+  @titles_configs: Array[{name: String, titles: Array[untyped]}]
   @titles_index: Integer
-  @alignment_configs: Array[{name: String, alignment: RatatuiRuby::Alignment}]
+  @alignment_configs: Array[{name: String, alignment: Symbol}]
   @alignment_index: Integer
   @title_styles: Array[{name: String, style: RatatuiRuby::Style?}]
   @title_style_index: Integer
-  @border_configs: Array[{name: String, borders: Array[RatatuiRuby::Block::border_option]}]
+  @border_configs: Array[{name: String, borders: Array[Symbol]}]
   @border_index: Integer
-  @border_type_configs: Array[{name: String, type: RatatuiRuby::Block::border_type?, set: Hash[Symbol, String]?}]
+  @border_type_configs: Array[{name: String, type: Symbol?, set: Hash[Symbol, String]?}]
   @border_type_index: Integer
   @border_styles: Array[{name: String, style: RatatuiRuby::Style?}]
   @border_style_index: Integer
   @base_styles: Array[{name: String, style: RatatuiRuby::Style?}]
   @base_style_index: Integer
-  @padding_configs: Array[{name: String, padding: RatatuiRuby::Block::padding_input}]
+  @padding_configs: Array[{name: String, padding: (Integer | Array[Integer])}]
   @padding_index: Integer
 
   def self.new: () -> WidgetBlockDemo

data/sig/manifest.yaml

@@ -0,0 +1,5 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+dependencies:

data/sig/patches/data.rbs

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# Patch for Data class to support super() calls in Data.define subclasses.
+#
+# The core RBS Data class defines `self.new: (**untyped) -> Data` but not `initialize`.
+# When Steep type-checks `super(items:, ...)` in a Data.define subclass, it looks for
+# the parent's `initialize` method. Since Data has no `initialize` signature in core RBS,
+# Steep can't match arguments and raises errors.
+#
+# This patch adds the missing `initialize` signatures that Data.define generates dynamically.
+class Data
+  # Accept both positional and keyword arguments for the dynamically-generated initialize.
+  # This allows subclasses to call super(foo, bar, ...) or super(foo:, bar:, ...) without type errors.
+  def initialize: (*untyped) -> void
+                | (**untyped) -> void
+  # Allow super() calls from overridden self.new methods to work with any keyword args
+  def self.new: (**untyped) -> instance
+end
+

data/sig/patches/debugger__.rbs

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+# Minimal stub for debug gem's DEBUGGER__ constant
+# Full library causes Steep deadlock on Ruby 4.0 (Steep 1.10.0 threading issue)
+module DEBUGGER__
+  def self.create_unix_domain_socket_name: () -> String?
+end

data/sig/ratatui_ruby/buffer/cell.rbs

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Buffer
+    class Cell
+      type color = Symbol | String | nil
+
+      attr_reader symbol: String
+      attr_reader fg: color
+      attr_reader bg: color
+      attr_reader underline_color: color
+      attr_reader modifiers: Array[Symbol]
+
+      alias char symbol
+
+      def self.new: (?symbol: String?, ?char: String?, ?fg: color, ?bg: color, ?underline_color: color, ?modifiers: Array[String | Symbol]) -> Cell
+      def self.empty: () -> Cell
+      def self.default: () -> Cell
+      def self.symbol: (String symbol) -> Cell
+      def self.char: (String char) -> Cell
+
+      def initialize: (?symbol: String?, ?char: String?, ?fg: color, ?bg: color, ?underline_color: color, ?modifiers: Array[String | Symbol]) -> void
+
+      # Modifier predicates
+      def bold?: () -> bool
+      def dim?: () -> bool
+      def italic?: () -> bool
+      def underlined?: () -> bool
+      def slow_blink?: () -> bool
+      def rapid_blink?: () -> bool
+      def reversed?: () -> bool
+      def hidden?: () -> bool
+      def crossed_out?: () -> bool
+
+      def ==: (untyped other) -> bool
+      def inspect: () -> String
+      def to_s: () -> String
+      def deconstruct_keys: (Array[Symbol]? keys) -> { symbol: String, char: String, fg: color, bg: color, underline_color: color, modifiers: Array[Symbol] }
+    end
+  end
+end

data/sig/ratatui_ruby/buffer.rbs

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Buffer
+    def self.index_of: (Integer x, Integer y) -> Integer
+    def self.pos_of: (Integer index) -> [Integer, Integer]
+    def self.get: (Integer x, Integer y) -> Cell
+    def self.content: () -> Array[Cell]
+
+    # Ruby-idiomatic alias
+    alias self.[] self.get
+  end
+end

data/sig/ratatui_ruby/cell.rbs

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  class Cell
+    type color = Symbol | String | nil
+
+    attr_reader symbol: String
+    attr_reader fg: color
+    attr_reader bg: color
+    attr_reader underline_color: color
+    attr_reader modifiers: Array[String]
+
+    alias char symbol
+
+    def self.new: (?symbol: String?, ?char: String?, ?fg: color, ?bg: color, ?underline_color: color, ?modifiers: Array[String]) -> Cell
+    def self.empty: () -> Cell
+    def self.default: () -> Cell
+    def self.symbol: (String symbol) -> Cell
+    def self.char: (String char) -> Cell
+
+    def initialize: (?symbol: String?, ?char: String?, ?fg: color, ?bg: color, ?underline_color: color, ?modifiers: Array[String]) -> void
+
+    # Modifier predicates
+    def bold?: () -> bool
+    def dim?: () -> bool
+    def italic?: () -> bool
+    def underlined?: () -> bool
+    def slow_blink?: () -> bool
+    def rapid_blink?: () -> bool
+    def reversed?: () -> bool
+    def hidden?: () -> bool
+    def crossed_out?: () -> bool
+
+    def ==: (untyped other) -> bool
+    def inspect: () -> String
+    def to_s: () -> String
+    def deconstruct_keys: (Array[Symbol]? keys) -> { symbol: String, char: String, fg: color, bg: color, underline_color: color, modifiers: Array[String] }
+  end
+end

data/sig/ratatui_ruby/clear.rbs

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Widget to clear/reset a terminal area before rendering.
+  class Clear < Data
+    attr_reader block: Widgets::Block?
+
+    def self.new: (?block: Widgets::Block?) -> Clear
+    def initialize: (?block: Widgets::Block?) -> void
+  end
+end

data/sig/ratatui_ruby/constraint.rbs

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Schema Constraint - defined directly under RatatuiRuby namespace.
+  class Constraint < Data
+    attr_reader type: Symbol
+    attr_reader value: (Integer | Array[Integer])
+
+    def self.new: (type: Symbol, value: (Integer | Array[Integer])) -> Constraint
+    def initialize: (type: Symbol, value: (Integer | Array[Integer])) -> void
+
+    def self.length: (_ToI) -> Constraint
+    def self.percentage: (_ToI) -> Constraint
+    def self.min: (_ToI) -> Constraint
+    def self.max: (_ToI) -> Constraint
+    def self.fill: (?_ToI) -> Constraint
+    def self.ratio: (_ToI, _ToI) -> Constraint
+  end
+end

data/sig/ratatui_ruby/debug.rbs

@@ -0,0 +1,45 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+module RatatuiRuby
+  # Debug mode control for RatatuiRuby.
+  #
+  # Manages Rust backtrace visibility and Ruby-side debug features.
+  module Debug
+    @rust_backtrace_enabled: bool
+    @debug_mode_enabled: bool
+    @remote_debugging_mode: (:open | :open_nonstop)?
+    @socket_path: String?
+
+    type source = :env | :test | :programmatic
+
+    # Enables Rust backtraces only.
+    def self.enable_rust_backtrace!: () -> void
+
+    # Enables full debug mode (Rust backtraces + Ruby-side features).
+    # Returns the socket path for remote debugging (nil on Windows or in test mode).
+    # source: :env (from RR_DEBUG), :test (from TestHelper), :programmatic (default)
+    def self.enable!: (?source: source) -> String?
+
+    # Returns whether full debug mode is enabled.
+    def self.enabled?: () -> bool
+
+    # Returns whether Rust backtraces are enabled.
+    def self.rust_backtrace_enabled?: () -> bool
+
+    # Returns the remote debugging mode for debug gem integration.
+    def self.remote_debugging_mode: () -> (:open | :open_nonstop)?
+
+    # Triggers a Rust panic for backtrace verification.
+    # WARNING: Crashes your process. Use only for debugging.
+    def self.test_panic!: () -> bot
+
+    # Temporarily suppresses Ruby-side debug mode checks within the block.
+    def self.suppress_debug_mode: [T] () { () -> T } -> T
+
+    private
+
+    # Enables remote debugging via the debug gem. Returns socket path.
+    def self.enable_remote_debugging!: () -> String?
+  end
+end