ratatui_ruby 0.5.0 → 0.6.0

data/ext/ratatui_ruby/src/events.rs

@@ -28,25 +28,120 @@ pub fn inject_test_event(event_type: String, data: magnus::RHash) -> Result<(),
     Ok(())
 }
 
+/// Parses a `snake_case` string to `MediaKeyCode`.
+///
+/// Accepts both the new `media_`-prefixed codes (canonical) and the legacy
+/// unprefixed codes for backward compatibility with existing tests.
+fn parse_media_key(s: &str) -> Option<ratatui::crossterm::event::MediaKeyCode> {
+    use ratatui::crossterm::event::MediaKeyCode;
+    match s {
+        // New canonical codes (media_ prefix)
+        "media_play" | "play" => Some(MediaKeyCode::Play),
+        "media_pause" => Some(MediaKeyCode::Pause),
+        "media_play_pause" | "play_pause" => Some(MediaKeyCode::PlayPause),
+        "media_reverse" | "reverse" => Some(MediaKeyCode::Reverse),
+        "media_stop" | "stop" => Some(MediaKeyCode::Stop),
+        "media_fast_forward" | "fast_forward" => Some(MediaKeyCode::FastForward),
+        "media_rewind" | "rewind" => Some(MediaKeyCode::Rewind),
+        "media_track_next" | "track_next" => Some(MediaKeyCode::TrackNext),
+        "media_track_previous" | "track_previous" => Some(MediaKeyCode::TrackPrevious),
+        "media_record" | "record" => Some(MediaKeyCode::Record),
+        "media_lower_volume" | "lower_volume" => Some(MediaKeyCode::LowerVolume),
+        "media_raise_volume" | "raise_volume" => Some(MediaKeyCode::RaiseVolume),
+        "media_mute_volume" | "mute_volume" => Some(MediaKeyCode::MuteVolume),
+        _ => None,
+    }
+}
+
+/// Parses a `snake_case` string to `ModifierKeyCode`.
+fn parse_modifier_key(s: &str) -> Option<ratatui::crossterm::event::ModifierKeyCode> {
+    use ratatui::crossterm::event::ModifierKeyCode;
+    match s {
+        "left_shift" => Some(ModifierKeyCode::LeftShift),
+        "left_control" => Some(ModifierKeyCode::LeftControl),
+        "left_alt" => Some(ModifierKeyCode::LeftAlt),
+        "left_super" => Some(ModifierKeyCode::LeftSuper),
+        "left_hyper" => Some(ModifierKeyCode::LeftHyper),
+        "left_meta" => Some(ModifierKeyCode::LeftMeta),
+        "right_shift" => Some(ModifierKeyCode::RightShift),
+        "right_control" => Some(ModifierKeyCode::RightControl),
+        "right_alt" => Some(ModifierKeyCode::RightAlt),
+        "right_super" => Some(ModifierKeyCode::RightSuper),
+        "right_hyper" => Some(ModifierKeyCode::RightHyper),
+        "right_meta" => Some(ModifierKeyCode::RightMeta),
+        "iso_level3_shift" => Some(ModifierKeyCode::IsoLevel3Shift),
+        "iso_level5_shift" => Some(ModifierKeyCode::IsoLevel5Shift),
+        _ => None,
+    }
+}
+
 fn parse_key_event(
     data: magnus::RHash,
     ruby: &magnus::Ruby,
 ) -> Result<ratatui::crossterm::event::Event, Error> {
+    use ratatui::crossterm::event::KeyCode;
+
     let code_val: Value = data
         .get(ruby.to_symbol("code"))
         .ok_or_else(|| Error::new(ruby.exception_arg_error(), "Missing 'code' in key event"))?;
     let code_str: String = String::try_convert(code_val)?;
     let code = match code_str.as_str() {
-        "up" => ratatui::crossterm::event::KeyCode::Up,
-        "down" => ratatui::crossterm::event::KeyCode::Down,
-        "left" => ratatui::crossterm::event::KeyCode::Left,
-        "right" => ratatui::crossterm::event::KeyCode::Right,
-        "enter" => ratatui::crossterm::event::KeyCode::Enter,
-        "esc" => ratatui::crossterm::event::KeyCode::Esc,
-        "backspace" => ratatui::crossterm::event::KeyCode::Backspace,
-        "tab" => ratatui::crossterm::event::KeyCode::Tab,
-        c if c.len() == 1 => ratatui::crossterm::event::KeyCode::Char(c.chars().next().unwrap()),
-        _ => ratatui::crossterm::event::KeyCode::Null,
+        // Arrow keys
+        "up" => KeyCode::Up,
+        "down" => KeyCode::Down,
+        "left" => KeyCode::Left,
+        "right" => KeyCode::Right,
+        // Common keys
+        "enter" => KeyCode::Enter,
+        "esc" => KeyCode::Esc,
+        "backspace" => KeyCode::Backspace,
+        "tab" => KeyCode::Tab,
+        "back_tab" => KeyCode::BackTab,
+        // Navigation keys
+        "home" => KeyCode::Home,
+        "end" => KeyCode::End,
+        "page_up" => KeyCode::PageUp,
+        "page_down" => KeyCode::PageDown,
+        "insert" => KeyCode::Insert,
+        "delete" => KeyCode::Delete,
+        // Lock keys
+        "caps_lock" => KeyCode::CapsLock,
+        "scroll_lock" => KeyCode::ScrollLock,
+        "num_lock" => KeyCode::NumLock,
+        // System keys
+        "print_screen" => KeyCode::PrintScreen,
+        "pause" => KeyCode::Pause,
+        "menu" => KeyCode::Menu,
+        "keypad_begin" => KeyCode::KeypadBegin,
+        "null" => KeyCode::Null,
+        // Dynamic parsing for media, modifiers, function keys, and characters
+        s => {
+            // Media keys (check first - "fast_forward" starts with 'f' but isn't F-key)
+            if let Some(m) = parse_media_key(s) {
+                KeyCode::Media(m)
+            }
+            // Modifier keys
+            else if let Some(m) = parse_modifier_key(s) {
+                KeyCode::Modifier(m)
+            }
+            // Function keys: f1, f2, ..., f12, etc.
+            else if let Some(num_str) = s.strip_prefix('f') {
+                if let Ok(n) = num_str.parse::<u8>() {
+                    KeyCode::F(n)
+                } else {
+                    // "f" alone or invalid suffix - treat as character
+                    KeyCode::Char(s.chars().next().unwrap_or('\0'))
+                }
+            }
+            // Single character
+            else if s.len() == 1 {
+                KeyCode::Char(s.chars().next().unwrap())
+            }
+            // Unknown - default to Null
+            else {
+                KeyCode::Null
+            }
+        }
     };
 
     let mut modifiers = ratatui::crossterm::event::KeyModifiers::empty();
@@ -178,7 +273,7 @@ pub fn clear_events() {
     EVENT_QUEUE.lock().unwrap().clear();
 }
 
-pub fn poll_event(ruby: &magnus::Ruby) -> Result<Value, Error> {
+pub fn poll_event(ruby: &magnus::Ruby, timeout_val: Option<f64>) -> Result<Value, Error> {
     let event = {
         let mut queue = EVENT_QUEUE.lock().unwrap();
         if queue.is_empty() {
@@ -204,14 +299,23 @@ pub fn poll_event(ruby: &magnus::Ruby) -> Result<Value, Error> {
         return Ok(ruby.qnil().into_value_with(ruby));
     }
 
-    if ratatui::crossterm::event::poll(std::time::Duration::from_millis(16))
-        .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?
-    {
+    if let Some(secs) = timeout_val {
+        // Timed poll: wait up to the specified duration
+        let duration = std::time::Duration::from_secs_f64(secs);
+        if ratatui::crossterm::event::poll(duration)
+            .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?
+        {
+            let event = ratatui::crossterm::event::read()
+                .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
+            handle_event(event)
+        } else {
+            Ok(ruby.qnil().into_value_with(ruby))
+        }
+    } else {
+        // Blocking: wait indefinitely for an event
         let event = ratatui::crossterm::event::read()
             .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
         handle_event(event)
-    } else {
-        Ok(ruby.qnil().into_value_with(ruby))
     }
 }
 
@@ -226,26 +330,134 @@ fn handle_event(event: ratatui::crossterm::event::Event) -> Result<Value, Error>
     }
 }
 
+/// Converts `MediaKeyCode` to `snake_case` string.
+///
+/// All media keys are consistently prefixed with `media_` to reflect that they
+/// belong to the `KeyCode::Media(_)` variant in Crossterm. This allows Ruby's
+/// "Smart Predicates" to provide DWIM behavior (e.g., `pause?` matching both
+/// system and media pause).
+fn media_key_to_string(m: ratatui::crossterm::event::MediaKeyCode) -> &'static str {
+    use ratatui::crossterm::event::MediaKeyCode;
+    match m {
+        MediaKeyCode::Play => "media_play",
+        MediaKeyCode::Pause => "media_pause",
+        MediaKeyCode::PlayPause => "media_play_pause",
+        MediaKeyCode::Reverse => "media_reverse",
+        MediaKeyCode::Stop => "media_stop",
+        MediaKeyCode::FastForward => "media_fast_forward",
+        MediaKeyCode::Rewind => "media_rewind",
+        MediaKeyCode::TrackNext => "media_track_next",
+        MediaKeyCode::TrackPrevious => "media_track_previous",
+        MediaKeyCode::Record => "media_record",
+        MediaKeyCode::LowerVolume => "media_lower_volume",
+        MediaKeyCode::RaiseVolume => "media_raise_volume",
+        MediaKeyCode::MuteVolume => "media_mute_volume",
+    }
+}
+
+/// Converts `ModifierKeyCode` to `snake_case` string.
+fn modifier_key_to_string(m: ratatui::crossterm::event::ModifierKeyCode) -> &'static str {
+    use ratatui::crossterm::event::ModifierKeyCode;
+    match m {
+        ModifierKeyCode::LeftShift => "left_shift",
+        ModifierKeyCode::LeftControl => "left_control",
+        ModifierKeyCode::LeftAlt => "left_alt",
+        ModifierKeyCode::LeftSuper => "left_super",
+        ModifierKeyCode::LeftHyper => "left_hyper",
+        ModifierKeyCode::LeftMeta => "left_meta",
+        ModifierKeyCode::RightShift => "right_shift",
+        ModifierKeyCode::RightControl => "right_control",
+        ModifierKeyCode::RightAlt => "right_alt",
+        ModifierKeyCode::RightSuper => "right_super",
+        ModifierKeyCode::RightHyper => "right_hyper",
+        ModifierKeyCode::RightMeta => "right_meta",
+        ModifierKeyCode::IsoLevel3Shift => "iso_level3_shift",
+        ModifierKeyCode::IsoLevel5Shift => "iso_level5_shift",
+    }
+}
+
 fn handle_key_event(key: ratatui::crossterm::event::KeyEvent) -> Result<Value, Error> {
+    use ratatui::crossterm::event::KeyCode;
+
     let ruby = magnus::Ruby::get().unwrap();
     if key.kind != ratatui::crossterm::event::KeyEventKind::Press {
         return Ok(ruby.qnil().into_value_with(&ruby));
     }
     let hash = ruby.hash_new();
     hash.aset(ruby.to_symbol("type"), ruby.to_symbol("key"))?;
+
+    // Determine the kind (category) of the key
+    let kind = match key.code {
+        KeyCode::Char(_)
+        | KeyCode::Enter
+        | KeyCode::Tab
+        | KeyCode::Backspace
+        | KeyCode::BackTab
+        | KeyCode::Up
+        | KeyCode::Down
+        | KeyCode::Left
+        | KeyCode::Right
+        | KeyCode::Home
+        | KeyCode::End
+        | KeyCode::PageUp
+        | KeyCode::PageDown
+        | KeyCode::Insert
+        | KeyCode::Delete
+        | KeyCode::Null => "standard",
+        KeyCode::F(_) => "function",
+        KeyCode::Media(_) => "media",
+        KeyCode::Modifier(_) => "modifier",
+        KeyCode::Esc
+        | KeyCode::CapsLock
+        | KeyCode::ScrollLock
+        | KeyCode::NumLock
+        | KeyCode::PrintScreen
+        | KeyCode::Pause
+        | KeyCode::Menu
+        | KeyCode::KeypadBegin => "system",
+    };
+
     let code = match key.code {
-        ratatui::crossterm::event::KeyCode::Char(c) => c.to_string(),
-        ratatui::crossterm::event::KeyCode::Up => "up".to_string(),
-        ratatui::crossterm::event::KeyCode::Down => "down".to_string(),
-        ratatui::crossterm::event::KeyCode::Left => "left".to_string(),
-        ratatui::crossterm::event::KeyCode::Right => "right".to_string(),
-        ratatui::crossterm::event::KeyCode::Enter => "enter".to_string(),
-        ratatui::crossterm::event::KeyCode::Esc => "esc".to_string(),
-        ratatui::crossterm::event::KeyCode::Backspace => "backspace".to_string(),
-        ratatui::crossterm::event::KeyCode::Tab => "tab".to_string(),
-        _ => "unknown".to_string(),
+        // Characters
+        KeyCode::Char(c) => c.to_string(),
+        // Arrow keys
+        KeyCode::Up => "up".to_string(),
+        KeyCode::Down => "down".to_string(),
+        KeyCode::Left => "left".to_string(),
+        KeyCode::Right => "right".to_string(),
+        // Common keys
+        KeyCode::Enter => "enter".to_string(),
+        KeyCode::Esc => "esc".to_string(),
+        KeyCode::Backspace => "backspace".to_string(),
+        KeyCode::Tab => "tab".to_string(),
+        KeyCode::BackTab => "back_tab".to_string(),
+        // Navigation keys
+        KeyCode::Home => "home".to_string(),
+        KeyCode::End => "end".to_string(),
+        KeyCode::PageUp => "page_up".to_string(),
+        KeyCode::PageDown => "page_down".to_string(),
+        KeyCode::Insert => "insert".to_string(),
+        KeyCode::Delete => "delete".to_string(),
+        // Function keys
+        KeyCode::F(n) => format!("f{n}"),
+        // Lock keys
+        KeyCode::CapsLock => "caps_lock".to_string(),
+        KeyCode::ScrollLock => "scroll_lock".to_string(),
+        KeyCode::NumLock => "num_lock".to_string(),
+        // System keys
+        KeyCode::PrintScreen => "print_screen".to_string(),
+        KeyCode::Pause => "pause".to_string(),
+        KeyCode::Menu => "menu".to_string(),
+        KeyCode::KeypadBegin => "keypad_begin".to_string(),
+        KeyCode::Null => "null".to_string(),
+        // Compound variants
+        KeyCode::Media(m) => media_key_to_string(m).to_string(),
+        KeyCode::Modifier(m) => modifier_key_to_string(m).to_string(),
     };
+
     hash.aset(ruby.to_symbol("code"), code)?;
+    hash.aset(ruby.to_symbol("kind"), ruby.to_symbol(kind))?;
+
     let mut modifiers = Vec::new();
     if key
         .modifiers

data/ext/ratatui_ruby/src/frame.rs

@@ -18,11 +18,14 @@
 //! The `'static` lifetime is a lie, but a safe one within these constraints.
 
 use crate::rendering;
+use crate::widgets;
 use magnus::{prelude::*, Error, Value};
 use ratatui::layout::Rect;
 use ratatui::Frame;
 use std::cell::UnsafeCell;
 use std::ptr::NonNull;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
 
 /// A wrapper around Ratatui's `Frame` that can be exposed to Ruby.
 ///
@@ -36,10 +39,17 @@ use std::ptr::NonNull;
 /// 2. The Ruby VM is single-threaded (GVL), so the frame pointer is never accessed
 ///    from multiple threads simultaneously
 /// 3. `RubyFrame` never escapes the draw callback scope
+///
+/// The `active` flag provides runtime safety by preventing use after the draw
+/// callback completes. Without this, a user could store the frame and cause
+/// undefined behavior by accessing it after the underlying pointer is invalid.
 #[magnus::wrap(class = "RatatuiRuby::Frame")]
 pub struct RubyFrame {
     /// Pointer to the underlying frame. Valid only during the draw callback.
     inner: UnsafeCell<NonNull<Frame<'static>>>,
+    /// Shared flag to invalidate the frame when the block finishes.
+    /// Set to `true` during draw, `false` immediately after yield returns.
+    active: Arc<AtomicBool>,
 }
 
 // SAFETY: RubyFrame is only used within Terminal::draw() callbacks, which are
@@ -49,12 +59,18 @@ unsafe impl Send for RubyFrame {}
 impl RubyFrame {
     /// Creates a new `RubyFrame` wrapping the given frame reference.
     ///
+    /// # Arguments
+    ///
+    /// * `frame` - Mutable reference to the underlying Ratatui frame
+    /// * `active` - Shared atomic flag that controls frame validity
+    ///
     /// # Safety
     ///
     /// The caller must ensure that:
     /// 1. The `RubyFrame` does not outlive the frame reference
     /// 2. No other mutable references to the frame exist while `RubyFrame` is in use
-    pub fn new(frame: &mut Frame<'_>) -> Self {
+    /// 3. The `active` flag is set to `false` after the draw callback completes
+    pub fn new(frame: &mut Frame<'_>, active: Arc<AtomicBool>) -> Self {
         // SAFETY: We cast the frame pointer to 'static lifetime. This is safe because:
         // - RubyFrame is only used within Terminal::draw() callbacks
         // - The Ruby block completes before the callback returns
@@ -67,6 +83,26 @@ impl RubyFrame {
 
         Self {
             inner: UnsafeCell::new(static_ptr),
+            active,
+        }
+    }
+
+    /// Checks that the frame is still valid for use.
+    ///
+    /// Returns `Ok(())` if the frame can be used, or an error if the draw
+    /// callback has already completed.
+    fn ensure_active(&self) -> Result<(), Error> {
+        if self.active.load(Ordering::Relaxed) {
+            Ok(())
+        } else {
+            let ruby = magnus::Ruby::get().unwrap();
+            let module = ruby.define_module("RatatuiRuby")?;
+            let error_base = module.const_get::<_, magnus::RClass>("Error")?;
+            let error_class = error_base.const_get("Safety")?;
+            Err(Error::new(
+                error_class,
+                "Frame cannot be used outside of the draw block",
+            ))
         }
     }
 
@@ -74,10 +110,12 @@ impl RubyFrame {
     ///
     /// This mirrors `frame.area()` in Rust Ratatui.
     pub fn area(&self) -> Result<Value, Error> {
+        self.ensure_active()?;
         let ruby = magnus::Ruby::get().unwrap();
 
         // SAFETY: The frame pointer is valid for the duration of the draw callback.
         // We only read from the frame, which is safe with an immutable reference.
+        // The ensure_active() check above guarantees we're still in the callback.
         let area = unsafe { (*self.inner.get()).as_ref().area() };
 
         // Create a Ruby Rect object
@@ -95,6 +133,8 @@ impl RubyFrame {
     /// * `widget` - A Ruby widget object (e.g., `RatatuiRuby::Paragraph`)
     /// * `area` - A Ruby `Rect` or hash-like object with `x`, `y`, `width`, `height`
     pub fn render_widget(&self, widget: Value, area: Value) -> Result<(), Error> {
+        self.ensure_active()?;
+
         // Parse the Ruby area into a Rust Rect
         let x: u16 = area.funcall("x", ())?;
         let y: u16 = area.funcall("y", ())?;
@@ -107,9 +147,81 @@ impl RubyFrame {
         // 1. RubyFrame is only used within Terminal::draw() callbacks
         // 2. Ruby's GVL ensures single-threaded access
         // 3. No other code holds a reference to the frame during this call
+        // 4. ensure_active() above guarantees we're still in the callback
         let frame = unsafe { (*self.inner.get()).as_mut() };
 
         // Delegate to the existing render_node function
         rendering::render_node(frame, rect, widget)
     }
+
+    /// Renders a stateful widget at the specified area.
+    ///
+    /// This mirrors `frame.render_stateful_widget(widget, area, &mut state)` in Rust Ratatui.
+    /// The State object is the single source of truth for selection and offset.
+    /// Widget properties (`selected_index`, `selected_row`, `offset`) are ignored.
+    ///
+    /// # Arguments
+    ///
+    /// * `widget` - A Ruby widget object (e.g., `RatatuiRuby::List`)
+    /// * `area` - A Ruby `Rect`
+    /// * `state` - A Ruby state object (e.g., `RatatuiRuby::ListState`)
+    pub fn render_stateful_widget(
+        &self,
+        widget: Value,
+        area: Value,
+        state: Value,
+    ) -> Result<(), Error> {
+        self.ensure_active()?;
+        let ruby = magnus::Ruby::get().unwrap();
+
+        // Parse the Ruby area into a Rust Rect
+        let x: u16 = area.funcall("x", ())?;
+        let y: u16 = area.funcall("y", ())?;
+        let width: u16 = area.funcall("width", ())?;
+        let height: u16 = area.funcall("height", ())?;
+        let rect = Rect::new(x, y, width, height);
+
+        // SAFETY: The frame pointer is valid for the duration of the draw callback.
+        let frame = unsafe { (*self.inner.get()).as_mut() };
+
+        // SAFETY: Immediate conversion to owned string avoids GC-unsafe borrowed reference.
+        let widget_class = unsafe { widget.class().name() }.into_owned();
+        // SAFETY: Immediate conversion to owned string avoids GC-unsafe borrowed reference.
+        let state_class = unsafe { state.class().name() }.into_owned();
+
+        match (widget_class.as_str(), state_class.as_str()) {
+            ("RatatuiRuby::List", "RatatuiRuby::ListState") => {
+                widgets::list::render_stateful(frame, rect, widget, state)
+            }
+            ("RatatuiRuby::Table", "RatatuiRuby::TableState") => {
+                widgets::table::render_stateful(frame, rect, widget, state)
+            }
+            ("RatatuiRuby::Scrollbar", "RatatuiRuby::ScrollbarState") => {
+                widgets::scrollbar::render_stateful(frame, rect, widget, state)
+            }
+            _ => Err(Error::new(
+                ruby.exception_arg_error(),
+                format!("Unsupported widget/state combination: {widget_class} with {state_class}"),
+            )),
+        }
+    }
+
+    /// Sets the cursor position in the terminal.
+    ///
+    /// This mirrors `frame.set_cursor_position((x, y))` in Rust Ratatui.
+    /// Use this for text input fields to show the cursor at the correct location.
+    ///
+    /// # Arguments
+    ///
+    /// * `x` - Column position (0-indexed from left)
+    /// * `y` - Row position (0-indexed from top)
+    pub fn set_cursor_position(&self, x: u16, y: u16) -> Result<(), Error> {
+        self.ensure_active()?;
+
+        // SAFETY: The frame pointer is valid for the duration of the draw callback.
+        // ensure_active() above guarantees we're still in the callback.
+        let frame = unsafe { (*self.inner.get()).as_mut() };
+        frame.set_cursor_position((x, y));
+        Ok(())
+    }
 }

data/ext/ratatui_ruby/src/lib.rs

@@ -13,6 +13,7 @@
 mod events;
 mod frame;
 mod rendering;
+mod string_width;
 mod style;
 mod terminal;
 mod text;
@@ -67,10 +68,17 @@ fn draw(args: &[Value]) -> Result<(), Error> {
     let mut draw_callback = |f: &mut ratatui::Frame<'_>| {
         if block_given {
             // New API: yield RubyFrame to block
-            let ruby_frame = RubyFrame::new(f);
+            // Create validity flag — set to true while the block is executing
+            let active = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(true));
+
+            let ruby_frame = RubyFrame::new(f, active.clone());
             if let Err(e) = ruby.yield_value::<_, Value>(ruby_frame) {
                 render_error = Some(e);
             }
+
+            // Invalidate frame immediately after block returns
+            // This prevents use-after-free if user stored the frame object
+            active.store(false, std::sync::atomic::Ordering::Relaxed);
         } else if let Some(tree_value) = tree {
             // Legacy API: render tree to full area
             if let Err(e) = rendering::render_node(f, f.area(), tree_value) {
@@ -82,12 +90,18 @@ fn draw(args: &[Value]) -> Result<(), Error> {
     if let Some(wrapper) = term_lock.as_mut() {
         match wrapper {
             terminal::TerminalWrapper::Crossterm(term) => {
+                let module = ruby.define_module("RatatuiRuby")?;
+                let error_base = module.const_get::<_, magnus::RClass>("Error")?;
+                let error_class = error_base.const_get("Terminal")?;
                 term.draw(&mut draw_callback)
-                    .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
+                    .map_err(|e| Error::new(error_class, e.to_string()))?;
             }
             terminal::TerminalWrapper::Test(term) => {
+                let module = ruby.define_module("RatatuiRuby")?;
+                let error_base = module.const_get::<_, magnus::RClass>("Error")?;
+                let error_class = error_base.const_get("Terminal")?;
                 term.draw(&mut draw_callback)
-                    .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
+                    .map_err(|e| Error::new(error_class, e.to_string()))?;
             }
         }
     } else {
@@ -114,10 +128,23 @@ fn init() -> Result<(), Error> {
     let frame_class = m.define_class("Frame", ruby.class_object())?;
     frame_class.define_method("area", method!(RubyFrame::area, 0))?;
     frame_class.define_method("render_widget", method!(RubyFrame::render_widget, 2))?;
-    m.define_module_function("_poll_event", function!(events::poll_event, 0))?;
+    frame_class.define_method(
+        "render_stateful_widget",
+        method!(RubyFrame::render_stateful_widget, 3),
+    )?;
+    frame_class.define_method(
+        "set_cursor_position",
+        method!(RubyFrame::set_cursor_position, 2),
+    )?;
+    m.define_module_function("_poll_event", function!(events::poll_event, 1))?;
     m.define_module_function("inject_test_event", function!(events::inject_test_event, 2))?;
     m.define_module_function("clear_events", function!(events::clear_events, 0))?;
 
+    // Register State classes
+    widgets::list_state::register(&ruby, m)?;
+    widgets::table_state::register(&ruby, m)?;
+    widgets::scrollbar_state::register(&ruby, m)?;
+
     // Test backend helpers
     m.define_module_function(
         "init_test_terminal",
@@ -151,6 +178,9 @@ fn init() -> Result<(), Error> {
     // Tabs metrics
     m.define_module_function("_tabs_width", function!(widgets::tabs::width, 1))?;
 
+    // Text measurement
+    m.define_module_function("_text_width", function!(string_width::text_width, 1))?;
+
     Ok(())
 }
 

data/ext/ratatui_ruby/src/string_width.rs

@@ -0,0 +1,101 @@
+// SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+use magnus::{prelude::*, Error, Value};
+
+/// Calculate the display width of a string in terminal cells.
+///
+/// Handles unicode correctly, including:
+/// - Regular ASCII characters: 1 cell each
+/// - CJK characters: 2 cells each (full-width)
+/// - Emoji: typically 2 cells each (varies by terminal)
+/// - Combining marks and zero-width characters: 0 cells
+///
+/// This uses the same `unicode-width` crate that Ratatui uses internally.
+///
+/// Returns the total display width in cells (not bytes or characters).
+pub fn text_width(string: Value) -> Result<usize, Error> {
+    let ruby = magnus::Ruby::get().unwrap();
+
+    let s: String = String::try_convert(string).map_err(|_| {
+        Error::new(
+            ruby.exception_type_error(),
+            "expected a String or object that converts to String",
+        )
+    })?;
+
+    // Use unicode_width's width calculation.
+    // This is the same mechanism Ratatui uses internally for Paragraph.line_width().
+    let width = s
+        .chars()
+        .map(|c| unicode_width::UnicodeWidthChar::width(c).unwrap_or(0))
+        .sum();
+
+    Ok(width)
+}
+
+#[cfg(test)]
+mod tests {
+    use unicode_width::UnicodeWidthChar;
+
+    fn measure_width(s: &str) -> usize {
+        s.chars()
+            .map(|c| UnicodeWidthChar::width(c).unwrap_or(0))
+            .sum()
+    }
+
+    #[test]
+    fn test_ascii_width() {
+        // ASCII is 1 cell per character
+        assert_eq!(measure_width("hello"), 5);
+        assert_eq!(measure_width("Hello, World!"), 13);
+    }
+
+    #[test]
+    fn test_emoji_width() {
+        // Emoji typically take 2 cells
+        // 👍 is U+1F44D THUMBS UP SIGN, width 2
+        assert_eq!(measure_width("👍"), 2);
+        // 🌍 is U+1F30D EARTH GLOBE EUROPE-AFRICA, width 2
+        assert_eq!(measure_width("🌍"), 2);
+        // "Hello 👍" = 5 + 1 + 2 = 8
+        assert_eq!(measure_width("Hello 👍"), 8);
+    }
+
+    #[test]
+    fn test_cjk_width() {
+        // CJK characters are full-width, 2 cells each
+        // 你 (U+4F60) is width 2
+        assert_eq!(measure_width("你"), 2);
+        // 好 (U+597D) is width 2
+        assert_eq!(measure_width("好"), 2);
+        // "你好" should be 4
+        assert_eq!(measure_width("你好"), 4);
+    }
+
+    #[test]
+    fn test_mixed_width() {
+        // "a你b好" = 1 + 2 + 1 + 2 = 6
+        assert_eq!(measure_width("a你b好"), 6);
+    }
+
+    #[test]
+    fn test_empty_string() {
+        assert_eq!(measure_width(""), 0);
+    }
+
+    #[test]
+    fn test_spaces_and_punctuation() {
+        // Regular ASCII space and punctuation are 1 cell each
+        assert_eq!(measure_width("a b c"), 5);
+        assert_eq!(measure_width("!!!"), 3);
+    }
+
+    #[test]
+    fn test_combining_marks() {
+        // Zero-width marks don't add to width
+        // "a" + combining acute accent (U+0301)
+        let combining = "a\u{0301}";
+        assert_eq!(measure_width(combining), 1);
+    }
+}