ratatui_ruby 0.9.1 → 0.10.0

data/ext/ratatui_ruby/src/color.rs

@@ -0,0 +1,82 @@
+// SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+//! Color conversion functions exposed to Ruby.
+//!
+//! These functions wrap Ratatui's color conversion methods that require the `palette` feature.
+
+use magnus::{Error, Ruby};
+use ratatui::palette::{Hsl, Hsluv};
+use ratatui::style::Color;
+
+/// Formats an RGB color as a hex string.
+fn rgb_to_hex(red: u8, green: u8, blue: u8) -> String {
+    format!("#{red:02x}{green:02x}{blue:02x}")
+}
+
+/// Convert HSL values to a hex color string.
+///
+/// # Arguments
+/// * `hue` - Hue in degrees (0-360, wraps)
+/// * `saturation` - Saturation as percentage (0-100)
+/// * `lightness` - Lightness as percentage (0-100)
+///
+/// # Returns
+/// A hex color string like "#rrggbb"
+pub fn from_hsl(_ruby: &Ruby, hue: f32, saturation: f32, lightness: f32) -> String {
+    // Normalize: h wraps, s and l are percentages (0-100) that need to be 0-1
+    let hsl = Hsl::new(hue, saturation / 100.0, lightness / 100.0);
+    let color = Color::from_hsl(hsl);
+
+    match color {
+        Color::Rgb(red, green, blue) => rgb_to_hex(red, green, blue),
+        _ => "#000000".to_string(),
+    }
+}
+
+/// Convert `HSLuv` values to a hex color string.
+///
+/// `HSLuv` is a perceptually uniform color space where colors at the same
+/// lightness appear equally bright regardless of hue.
+///
+/// # Arguments
+/// * `hue` - Hue in degrees (-180 to 360, wraps)
+/// * `saturation` - Saturation as percentage (0-100)
+/// * `lightness` - Lightness as percentage (0-100)
+///
+/// # Returns
+/// A hex color string like "#rrggbb"
+pub fn from_hsluv(_ruby: &Ruby, hue: f32, saturation: f32, lightness: f32) -> String {
+    // Hsluv expects h in degrees, s and l as percentages (0-100)
+    let hsluv = Hsluv::new(hue, saturation, lightness);
+    let color = Color::from_hsluv(hsluv);
+
+    match color {
+        Color::Rgb(red, green, blue) => rgb_to_hex(red, green, blue),
+        _ => "#000000".to_string(),
+    }
+}
+
+/// Convert a u32 to a hex color string.
+///
+/// # Arguments
+/// * `val` - A u32 in the format 0x00RRGGBB
+///
+/// # Returns
+/// A hex color string like "#rrggbb"
+pub fn from_u32(_ruby: &Ruby, val: u32) -> String {
+    let color = Color::from_u32(val);
+
+    match color {
+        Color::Rgb(red, green, blue) => rgb_to_hex(red, green, blue),
+        _ => "#000000".to_string(),
+    }
+}
+
+/// Register color module functions in the `RatatuiRuby` module.
+pub fn register(_ruby: &Ruby, module: magnus::RModule) -> Result<(), Error> {
+    module.define_module_function("_color_from_hsl", magnus::function!(from_hsl, 3))?;
+    module.define_module_function("_color_from_hsluv", magnus::function!(from_hsluv, 3))?;
+    module.define_module_function("_color_from_u32", magnus::function!(from_u32, 1))?;
+    Ok(())
+}

data/ext/ratatui_ruby/src/errors.rs

@@ -0,0 +1,28 @@
+// SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+use magnus::{prelude::*, Error, Value};
+
+/// Creates a `TypeError` with context showing the actual value received.
+///
+/// Calls `inspect` on the Ruby value and includes it in the error message.
+/// Long inspect strings (>200 chars) are truncated.
+///
+/// # Example error message
+/// ```text
+/// expected array for rows, got {:title=>"Processes", :header=>["Name", ...]}
+/// ```
+pub fn type_error_with_context(ruby: &magnus::Ruby, expected: &str, got: Value) -> Error {
+    let inspect: String = got
+        .funcall("inspect", ())
+        .unwrap_or_else(|_| "<uninspectable>".to_string());
+    let truncated = if inspect.len() > 200 {
+        format!("{}...", &inspect[..200])
+    } else {
+        inspect
+    };
+    Error::new(
+        ruby.exception_type_error(),
+        format!("{expected}, got {truncated}"),
+    )
+}

data/ext/ratatui_ruby/src/events.rs

@@ -30,25 +30,26 @@ pub fn inject_test_event(event_type: String, data: magnus::RHash) -> Result<(),
 
 /// 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.
+/// Parses a `snake_case` string to `MediaKeyCode`.
+///
+/// Only accepts the `media_`-prefixed codes (canonical). Legacy unprefixed codes are no longer supported.
 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_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),
+        "media_play_pause" => Some(MediaKeyCode::PlayPause),
+        "media_reverse" => Some(MediaKeyCode::Reverse),
+        "media_stop" => Some(MediaKeyCode::Stop),
+        "media_fast_forward" => Some(MediaKeyCode::FastForward),
+        "media_rewind" => Some(MediaKeyCode::Rewind),
+        "media_track_next" => Some(MediaKeyCode::TrackNext),
+        "media_track_previous" => Some(MediaKeyCode::TrackPrevious),
+        "media_record" => Some(MediaKeyCode::Record),
+        "media_lower_volume" => Some(MediaKeyCode::LowerVolume),
+        "media_raise_volume" => Some(MediaKeyCode::RaiseVolume),
+        "media_mute_volume" => Some(MediaKeyCode::MuteVolume),
         _ => None,
     }
 }

data/ext/ratatui_ruby/src/lib.rs

@@ -10,6 +10,8 @@
 #![allow(clippy::missing_panics_doc)]
 #![allow(clippy::module_name_repetitions)]
 
+mod color;
+mod errors;
 mod events;
 mod frame;
 mod rendering;
@@ -115,6 +117,43 @@ fn draw(args: &[Value]) -> Result<(), Error> {
     Ok(())
 }
 
+/// Storage for the last panic info, to be retrieved and printed after terminal restore.
+static LAST_PANIC: std::sync::Mutex<Option<String>> = std::sync::Mutex::new(None);
+
+/// Enables Rust backtraces and installs a custom panic hook.
+///
+/// The panic hook stores the backtrace info instead of printing immediately.
+/// This allows Ruby to retrieve and print it after terminal restoration,
+/// preventing output from being lost on the alternate screen.
+fn enable_rust_backtrace(_ruby: &magnus::Ruby) {
+    std::env::set_var("RUST_BACKTRACE", "1");
+    std::panic::set_hook(Box::new(|info| {
+        let backtrace = std::backtrace::Backtrace::force_capture();
+        let message = format!("Rust panic: {info}\n{backtrace}");
+        if let Ok(mut guard) = LAST_PANIC.lock() {
+            *guard = Some(message);
+        }
+    }));
+}
+
+/// Returns the last panic info (if any) and clears it.
+///
+/// Call this after terminal restoration to get deferred panic output.
+fn get_last_panic(_ruby: &magnus::Ruby) -> Option<String> {
+    if let Ok(mut guard) = LAST_PANIC.lock() {
+        guard.take()
+    } else {
+        None
+    }
+}
+
+/// Intentionally panics to test backtrace output.
+///
+/// Only use this for debugging/testing the backtrace feature.
+fn test_panic(_ruby: &magnus::Ruby) {
+    panic!("Test panic triggered by RatatuiRuby._test_panic");
+}
+
 #[magnus::init]
 fn init() -> Result<(), Error> {
     let ruby = magnus::Ruby::get().unwrap();
@@ -123,6 +162,12 @@ fn init() -> Result<(), Error> {
     m.define_module_function("_init_terminal", function!(init_terminal, 2))?;
     m.define_module_function("_restore_terminal", function!(restore_terminal, 0))?;
     m.define_module_function("_draw", function!(draw, -1))?;
+    m.define_module_function(
+        "_enable_rust_backtrace",
+        function!(enable_rust_backtrace, 0),
+    )?;
+    m.define_module_function("_test_panic", function!(test_panic, 0))?;
+    m.define_module_function("_get_last_panic", function!(get_last_panic, 0))?;
 
     // Register Frame class
     let frame_class = m.define_class("Frame", ruby.class_object())?;
@@ -160,11 +205,19 @@ fn init() -> Result<(), Error> {
     )?;
     m.define_module_function("_get_cell_at", function!(terminal::get_cell_at, 2))?;
     m.define_module_function("resize_terminal", function!(terminal::resize_terminal, 2))?;
+    m.define_module_function(
+        "_get_terminal_area",
+        function!(terminal::get_terminal_area, 0),
+    )?;
 
     // Register Layout.split on the Layout::Layout class (inside the Layout module)
     let layout_mod = m.const_get::<_, magnus::RModule>("Layout")?;
     let layout_class = layout_mod.const_get::<_, magnus::RClass>("Layout")?;
     layout_class.define_singleton_method("_split", function!(widgets::layout::split_layout, 4))?;
+    layout_class.define_singleton_method(
+        "_split_with_spacers",
+        function!(widgets::layout::split_with_spacers_layout, 4),
+    )?;
 
     // Paragraph metrics
     m.define_module_function(
@@ -182,6 +235,9 @@ fn init() -> Result<(), Error> {
     // Text measurement
     m.define_module_function("_text_width", function!(string_width::text_width, 1))?;
 
+    // Color conversion
+    color::register(&ruby, m)?;
+
     Ok(())
 }
 

data/ext/ratatui_ruby/src/rendering.rs

@@ -120,7 +120,9 @@ fn process_draw_command(buffer: &mut Buffer, cmd: Value) -> Result<(), Error> {
                 for i in 0..mods_array.len() {
                     let index = isize::try_from(i)
                         .map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
-                    let mod_str: String = mods_array.entry::<String>(index)?;
+                    let mod_val: Value = mods_array.entry(index)?;
+                    // Accept both symbols and strings (DWIM)
+                    let mod_str: String = mod_val.funcall("to_s", ())?;
                     if let Some(modifier) = parse_modifier_str(&mod_str) {
                         style = style.add_modifier(modifier);
                     }

data/ext/ratatui_ruby/src/style.rs

@@ -2,6 +2,7 @@
 //
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
+use crate::errors::type_error_with_context;
 use bumpalo::Bump;
 use magnus::{prelude::*, Error, Symbol, Value};
 use ratatui::{
@@ -65,22 +66,29 @@ pub fn parse_style(style_val: Value) -> Result<Style, Error> {
 
     let mut style = Style::default();
 
-    let (fg, bg, modifiers_val) = if let Some(hash) = magnus::RHash::from_value(style_val) {
-        (
-            hash.lookup(ruby.to_symbol("fg"))
-                .unwrap_or_else(|_| ruby.qnil().as_value()),
-            hash.lookup(ruby.to_symbol("bg"))
-                .unwrap_or_else(|_| ruby.qnil().as_value()),
-            hash.lookup(ruby.to_symbol("modifiers"))
-                .unwrap_or_else(|_| ruby.qnil().as_value()),
-        )
-    } else {
-        (
-            style_val.funcall("fg", ())?,
-            style_val.funcall("bg", ())?,
-            style_val.funcall("modifiers", ())?,
-        )
-    };
+    let (fg, bg, underline_color, modifiers_val, remove_modifiers_val) =
+        if let Some(hash) = magnus::RHash::from_value(style_val) {
+            (
+                hash.lookup(ruby.to_symbol("fg"))
+                    .unwrap_or_else(|_| ruby.qnil().as_value()),
+                hash.lookup(ruby.to_symbol("bg"))
+                    .unwrap_or_else(|_| ruby.qnil().as_value()),
+                hash.lookup(ruby.to_symbol("underline_color"))
+                    .unwrap_or_else(|_| ruby.qnil().as_value()),
+                hash.lookup(ruby.to_symbol("modifiers"))
+                    .unwrap_or_else(|_| ruby.qnil().as_value()),
+                hash.lookup(ruby.to_symbol("remove_modifiers"))
+                    .unwrap_or_else(|_| ruby.qnil().as_value()),
+            )
+        } else {
+            (
+                style_val.funcall("fg", ())?,
+                style_val.funcall("bg", ())?,
+                style_val.funcall("underline_color", ())?,
+                style_val.funcall("modifiers", ())?,
+                style_val.funcall("remove_modifiers", ())?,
+            )
+        };
 
     if !fg.is_nil() {
         if let Ok(fg_str) = fg.funcall::<_, _, String>("to_s", ()) {
@@ -98,6 +106,14 @@ pub fn parse_style(style_val: Value) -> Result<Style, Error> {
         }
     }
 
+    if !underline_color.is_nil() {
+        if let Ok(uc_str) = underline_color.funcall::<_, _, String>("to_s", ()) {
+            if let Some(color) = parse_color(&uc_str) {
+                style = style.underline_color(color);
+            }
+        }
+    }
+
     if !modifiers_val.is_nil() {
         if let Some(modifiers_array) = magnus::RArray::from_value(modifiers_val) {
             for i in 0..modifiers_array.len() {
@@ -112,6 +128,20 @@ pub fn parse_style(style_val: Value) -> Result<Style, Error> {
         }
     }
 
+    if !remove_modifiers_val.is_nil() {
+        if let Some(remove_modifiers_array) = magnus::RArray::from_value(remove_modifiers_val) {
+            for i in 0..remove_modifiers_array.len() {
+                let index = isize::try_from(i)
+                    .map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
+                if let Ok(sym) = remove_modifiers_array.entry::<Symbol>(index) {
+                    if let Some(m) = parse_modifier_str(&sym.to_string()) {
+                        style = style.remove_modifier(m);
+                    }
+                }
+            }
+        }
+    }
+
     Ok(style)
 }
 
@@ -121,7 +151,7 @@ pub fn parse_border_set<'a>(
 ) -> Result<symbols::border::Set<'a>, Error> {
     let ruby = magnus::Ruby::get().unwrap();
     let hash = magnus::RHash::from_value(set_val)
-        .ok_or_else(|| Error::new(ruby.exception_type_error(), "expected hash for border_set"))?;
+        .ok_or_else(|| type_error_with_context(&ruby, "expected hash for border_set", set_val))?;
 
     let get_char = |key: &str| -> Result<Option<&'a str>, Error> {
         let mut val: Value = hash
@@ -188,10 +218,7 @@ pub fn parse_bar_set<'a>(set_val: Value, bump: &'a Bump) -> Result<symbols::bar:
     }
 
     let hash = magnus::RHash::from_value(set_val).ok_or_else(|| {
-        Error::new(
-            ruby.exception_type_error(),
-            "expected symbol or hash for bar_set",
-        )
+        type_error_with_context(&ruby, "expected symbol or hash for bar_set", set_val)
     })?;
 
     let get_char = |key: &str| -> Result<Option<&'a str>, Error> {

data/ext/ratatui_ruby/src/terminal.rs

@@ -109,6 +109,36 @@ pub fn get_buffer_content() -> Result<String, Error> {
     }
 }
 
+pub fn get_terminal_area() -> Result<magnus::RHash, Error> {
+    let ruby = magnus::Ruby::get().unwrap();
+    let term_lock = TERMINAL.lock().unwrap();
+    if let Some(wrapper) = term_lock.as_ref() {
+        let hash = ruby.hash_new();
+        match wrapper {
+            TerminalWrapper::Crossterm(term) => {
+                let size = term.size().unwrap_or_default();
+                hash.aset("x", 0u16)?;
+                hash.aset("y", 0u16)?;
+                hash.aset("width", size.width)?;
+                hash.aset("height", size.height)?;
+            }
+            TerminalWrapper::Test(term) => {
+                let area = term.backend().buffer().area;
+                hash.aset("x", area.x)?;
+                hash.aset("y", area.y)?;
+                hash.aset("width", area.width)?;
+                hash.aset("height", area.height)?;
+            }
+        }
+        Ok(hash)
+    } else {
+        let module = ruby.define_module("RatatuiRuby")?;
+        let error_base = module.const_get::<_, magnus::RClass>("Error")?;
+        let error_class = error_base.const_get("Terminal")?;
+        Err(Error::new(error_class, "Terminal is not initialized"))
+    }
+}
+
 pub fn get_cursor_position() -> Result<Option<(u16, u16)>, Error> {
     let ruby = magnus::Ruby::get().unwrap();
     let mut term_lock = TERMINAL.lock().unwrap();
@@ -163,6 +193,7 @@ pub fn get_cell_at(x: u16, y: u16) -> Result<magnus::RHash, Error> {
             hash.aset("char", cell.symbol())?;
             hash.aset("fg", color_to_value(cell.fg))?;
             hash.aset("bg", color_to_value(cell.bg))?;
+            hash.aset("underline_color", color_to_value(cell.underline_color))?;
             hash.aset("modifiers", modifiers_to_value(cell.modifier))?;
             Ok(hash)
         } else {
@@ -217,31 +248,31 @@ fn modifiers_to_value(modifier: ratatui::style::Modifier) -> Value {
     let ary = ruby.ary_new();
 
     if modifier.contains(ratatui::style::Modifier::BOLD) {
-        let _ = ary.push(ruby.str_new("bold"));
+        let _ = ary.push(ruby.to_symbol("bold"));
     }
     if modifier.contains(ratatui::style::Modifier::ITALIC) {
-        let _ = ary.push(ruby.str_new("italic"));
+        let _ = ary.push(ruby.to_symbol("italic"));
     }
     if modifier.contains(ratatui::style::Modifier::DIM) {
-        let _ = ary.push(ruby.str_new("dim"));
+        let _ = ary.push(ruby.to_symbol("dim"));
     }
     if modifier.contains(ratatui::style::Modifier::UNDERLINED) {
-        let _ = ary.push(ruby.str_new("underlined"));
+        let _ = ary.push(ruby.to_symbol("underlined"));
     }
     if modifier.contains(ratatui::style::Modifier::REVERSED) {
-        let _ = ary.push(ruby.str_new("reversed"));
+        let _ = ary.push(ruby.to_symbol("reversed"));
     }
     if modifier.contains(ratatui::style::Modifier::HIDDEN) {
-        let _ = ary.push(ruby.str_new("hidden"));
+        let _ = ary.push(ruby.to_symbol("hidden"));
     }
     if modifier.contains(ratatui::style::Modifier::CROSSED_OUT) {
-        let _ = ary.push(ruby.str_new("crossed_out"));
+        let _ = ary.push(ruby.to_symbol("crossed_out"));
     }
     if modifier.contains(ratatui::style::Modifier::SLOW_BLINK) {
-        let _ = ary.push(ruby.str_new("slow_blink"));
+        let _ = ary.push(ruby.to_symbol("slow_blink"));
     }
     if modifier.contains(ratatui::style::Modifier::RAPID_BLINK) {
-        let _ = ary.push(ruby.str_new("rapid_blink"));
+        let _ = ary.push(ruby.to_symbol("rapid_blink"));
     }
 
     ary.as_value()

data/ext/ratatui_ruby/src/text.rs

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
+use crate::errors::type_error_with_context;
 use crate::style::parse_style;
 use magnus::{prelude::*, Error, Value};
 use ratatui::text::{Line, Span};
@@ -82,9 +83,10 @@ pub fn parse_text(value: Value) -> Result<Vec<Line<'static>>, Error> {
                 Ok(lines)
             }
         }
-        Err(_) => Err(Error::new(
-            ruby.exception_type_error(),
+        Err(_) => Err(type_error_with_context(
+            &ruby,
             "expected String, Text::Span, Text::Line, or Array of Text::Lines/Spans",
+            value,
         )),
     }
 }
@@ -98,9 +100,10 @@ pub fn parse_span(value: Value) -> Result<Span<'static>, Error> {
     let class_name: String = class_obj.funcall("name", ())?;
 
     if !class_name.contains("Span") {
-        return Err(Error::new(
-            ruby.exception_type_error(),
+        return Err(type_error_with_context(
+            &ruby,
             "expected a Text::Span object",
+            value,
         ));
     }
 
@@ -115,6 +118,7 @@ pub fn parse_span(value: Value) -> Result<Span<'static>, Error> {
 }
 
 /// Parses a Ruby `Text::Line` object into a ratatui Line.
+/// Also accepts `Text::Span` objects and auto-coerces them to a Line.
 pub fn parse_line(value: Value) -> Result<Line<'static>, Error> {
     let ruby = magnus::Ruby::get().unwrap();
 
@@ -122,10 +126,17 @@ pub fn parse_line(value: Value) -> Result<Line<'static>, Error> {
     let class_obj: Value = value.funcall("class", ())?;
     let class_name: String = class_obj.funcall("name", ())?;
 
+    // Auto-coerce Span to Line: wrap a single Span in a Line
+    if class_name.contains("Span") {
+        let span = parse_span(value)?;
+        return Ok(Line::from(vec![span]));
+    }
+
     if !class_name.contains("Line") {
-        return Err(Error::new(
-            ruby.exception_type_error(),
-            "expected a Text::Line object",
+        return Err(type_error_with_context(
+            &ruby,
+            "expected a Text::Line or Text::Span object",
+            value,
         ));
     }
 
@@ -141,9 +152,10 @@ pub fn parse_line(value: Value) -> Result<Line<'static>, Error> {
     }
 
     let spans_array = magnus::RArray::from_value(spans_val).ok_or_else(|| {
-        Error::new(
-            ruby.exception_type_error(),
+        type_error_with_context(
+            &ruby,
             "expected array of Spans in Text::Line.spans",
+            spans_val,
         )
     })?;
 

data/ext/ratatui_ruby/src/widgets/chart.rs

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
+use crate::errors::type_error_with_context;
 use crate::style::{parse_block, parse_style};
 use crate::text::parse_line;
 use bumpalo::Bump;
@@ -41,7 +42,7 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
                 .map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
             let point_array_val: Value = data_array.entry(index)?;
             let point_array = magnus::RArray::from_value(point_array_val).ok_or_else(|| {
-                Error::new(ruby.exception_type_error(), "expected array for point")
+                type_error_with_context(&ruby, "expected array for point", point_array_val)
             })?;
             let x: f64 = point_array.entry(0)?;
             let y: f64 = point_array.entry(1)?;

data/ext/ratatui_ruby/src/widgets/layout.rs

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
+use crate::errors::type_error_with_context;
 use crate::rendering::render_node;
 use magnus::{prelude::*, Error, Symbol, Value};
 use ratatui::{
@@ -12,8 +13,9 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
     let ruby = magnus::Ruby::get().unwrap();
     let direction_sym: Symbol = node.funcall("direction", ())?;
     let children_val: Value = node.funcall("children", ())?;
-    let children_array = magnus::RArray::from_value(children_val)
-        .ok_or_else(|| Error::new(ruby.exception_type_error(), "expected array"))?;
+    let children_array = magnus::RArray::from_value(children_val).ok_or_else(|| {
+        type_error_with_context(&ruby, "expected array for children", children_val)
+    })?;
 
     let constraints_val: Value = node.funcall("constraints", ())?;
     let constraints_array = magnus::RArray::from_value(constraints_val);
@@ -201,6 +203,92 @@ pub fn split_layout(
     Ok(result)
 }
 
+/// Splits an area into multiple rectangles, returning both segments and spacers.
+/// This is the Ratatui `split_with_spacers` equivalent.
+///
+/// # Arguments
+/// * `area` - A Ruby Hash or Rect with :x, :y, :width, :height keys
+/// * `direction` - Symbol :vertical or :horizontal
+/// * `constraints` - Array of Constraint objects
+/// * `flex` - Symbol for flex mode
+///
+/// # Returns
+/// An array containing two arrays: [segments, spacers], each containing Ruby Hashes representing Rect objects
+pub fn split_with_spacers_layout(
+    area: Value,
+    direction: Symbol,
+    constraints: magnus::RArray,
+    flex: Symbol,
+) -> Result<magnus::RArray, Error> {
+    let ruby = magnus::Ruby::get().unwrap();
+
+    // Parse area from Hash or Rect-like object
+    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);
+
+    // Parse direction
+    let dir = if direction.to_string() == "vertical" {
+        Direction::Vertical
+    } else {
+        Direction::Horizontal
+    };
+
+    // Parse flex
+    let flex_mode = match flex.to_string().as_str() {
+        "start" => Flex::Start,
+        "center" => Flex::Center,
+        "end" => Flex::End,
+        "space_between" => Flex::SpaceBetween,
+        "space_around" => Flex::SpaceAround,
+        "space_evenly" => Flex::SpaceEvenly,
+        _ => Flex::Legacy,
+    };
+
+    // Parse constraints
+    let mut ratatui_constraints = Vec::new();
+    for i in 0..constraints.len() {
+        let index = isize::try_from(i)
+            .map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
+        let constraint_obj: Value = constraints.entry(index)?;
+        if let Ok(constraint) = parse_constraint(constraint_obj) {
+            ratatui_constraints.push(constraint);
+        }
+    }
+
+    // Compute layout with spacers
+    let (segments, spacers) = Layout::default()
+        .direction(dir)
+        .flex(flex_mode)
+        .constraints(ratatui_constraints)
+        .split_with_spacers(rect);
+
+    // Helper to convert Rc<[Rect]> to Ruby array
+    let rects_to_ruby_array = |rects: &[Rect]| -> Result<magnus::RArray, Error> {
+        let arr = ruby.ary_new_capa(rects.len());
+        for chunk in rects {
+            let hash = ruby.hash_new();
+            hash.aset(ruby.sym_new("x"), chunk.x)?;
+            hash.aset(ruby.sym_new("y"), chunk.y)?;
+            hash.aset(ruby.sym_new("width"), chunk.width)?;
+            hash.aset(ruby.sym_new("height"), chunk.height)?;
+            arr.push(hash)?;
+        }
+        Ok(arr)
+    };
+
+    let segments_arr = rects_to_ruby_array(&segments)?;
+    let spacers_arr = rects_to_ruby_array(&spacers)?;
+
+    // Return [segments, spacers]
+    let result = ruby.ary_new_capa(2);
+    result.push(segments_arr)?;
+    result.push(spacers_arr)?;
+
+    Ok(result)
+}
 #[cfg(test)]
 mod tests {
     use ratatui::layout::{Constraint, Direction, Flex, Layout, Rect};