ratatui_ruby 1.0.0.pre.beta.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69c2adadc9306ebeb02ffefa11e56abe7db2f0ef1c361a2edaf1cf5a3f9b9fee
-  data.tar.gz: c8e07b3361a46597f957fa6a4ade8e9eef426fa85a0df8650f7188a306384d5a
+  metadata.gz: c8ee9b7928a67c0f332a1fdfd2870972ba9f37c6219879d427a5225f71a24b54
+  data.tar.gz: 42ef63b4ca0dafb3220034af83a1d5d0acab49123378e0c5909b21c9baf60f52
 SHA512:
-  metadata.gz: eb439fe49d032bf2d7221b4771b2b6b0156d9b5373d32fe6710ff0077046263fc5e719c1d91d1ed271b3cb58c18cf9f31ef6d366daed59b6f4413ac66db82447
-  data.tar.gz: dc395bd562a70d0bc8a9d6eafa4ca0b488ef3ce450a3f3d65b125550ed616c1516b2b5301bb0b634028433f90d4306885ba8f756542241fb9d5e0c4fa25d6644
+  metadata.gz: 68ec1dcf33fa00b9bb53852d5cc4c92c680f10924b13594854c34bc3e597db6214603c1513427cad35e31895d08cc7dd59e2ac1166dcd44f525043588b23407d
+  data.tar.gz: c9cfbe2d111ca45cfe003fc28dea7d23f12dac8c14424701a8532d964d905e80d2fbdd2fdb2a749a291a23ef4e168e2ab0fac14c55ef874b5e1b357d75f4b66f

data/.builds/ruby-3.2.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-1.0.0.pre.beta.2.gem
+  - ratatui_ruby/pkg/ratatui_ruby-1.0.0.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/.builds/ruby-3.3.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-1.0.0.pre.beta.2.gem
+  - ratatui_ruby/pkg/ratatui_ruby-1.0.0.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/.builds/ruby-3.4.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-1.0.0.pre.beta.2.gem
+  - ratatui_ruby/pkg/ratatui_ruby-1.0.0.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/.builds/ruby-4.0.0.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-1.0.0.pre.beta.2.gem
+  - ratatui_ruby/pkg/ratatui_ruby-1.0.0.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/CHANGELOG.md

@@ -18,21 +18,22 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Removed
 
-## [1.0.0-beta.2] - 2026-01-20
+## [1.0.0] - 2026-01-25
+This release is functionally equivalent to v0.10.3, with additional bug fixes.
+The version bump signals the beginning of the 1.0 release series.
 
 ### Added
 
 ### Changed
 
 ### Fixed
-
+- **back_tab? DWIM**: `back_tab?` and `backtab?` predicates now match events with code "back_tab" regardless of whether the shift modifier is explicitly present, since back_tab semantically implies shift.
+- **Terminal Queries During Draw (Deadlock)**: Calling `viewport_area`, `terminal_size`, `get_cell_at`, `poll_event`, `get_cursor_position`, or `get_viewport_type` from inside a `draw()` block previously caused the application to freeze forever. The thread blocked on a Mutex. Ruby's `Timeout` could not interrupt it. The only recovery was `kill -9`. These reads now work via a snapshot captured before rendering.
+- **Terminal Mutations During Draw (Deadlock)**: Calling `insert_before`, `set_cursor_position`, or `resize_terminal` from inside a `draw()` block previously caused the same silent freeze. These writes now raise `Error::Invariant` with a clear message.
+- **Nested Draw Calls (Deadlock)**: Calling `draw()` from inside another `draw()` block previously froze the application. Nested draws now raise `Error::Invariant`.
+- **Event Injection During Draw (Deadlock)**: Calling `inject_test_event` from inside a `draw()` block previously froze the application. Event injection now works correctly during draw.
 - **TableState Row Navigation Methods**: Added missing row navigation methods (`select_next`, `select_previous`, `select_first`, `select_last`) that should have been included alongside the column navigation methods added in v0.10.0. These methods match `ListState`'s navigation API and are used in the `app_stateful_interaction` example.
 
-### Removed
-
-## [1.0.0-beta.1] - 2026-01-20
-This release is functionally equivalent to v0.10.3. The version bump signals the beginning of the 1.0 release series.
-
 ## [0.10.3] - 2026-01-16
 
 ### Added
@@ -682,6 +683,8 @@ This release is functionally equivalent to v0.10.3. The version bump signals the
 - **Testing Support**: Included `RatatuiRuby::TestHelper` and RSpec integration to make testing your TUI applications possible.
 
 [Unreleased]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/HEAD
+[1.0.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v1.0.0
+[1.0.0-beta.3]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v1.0.0-beta.3
 [1.0.0-beta.2]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v1.0.0-beta.2
 [1.0.0-beta.1]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v1.0.0-beta.1
 [0.10.3]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.10.3

data/README.md

@@ -20,9 +20,6 @@ Mailing List: Announcements](https://img.shields.io/badge/mailing_list-announcem
 **ratatui_ruby** is a Ruby wrapper for [Ratatui](https://ratatui.rs). It allows you to cook up Terminal User Interfaces in Ruby.
 **ratatui_ruby** is a community wrapper that is not affiliated with [the Ratatui team](https://github.com/orgs/ratatui/people).
 
-> [!WARNING]
-> **ratatui_ruby** is currently in **BETA**. Please report any bugs you find!
-
 **[Why RatatuiRuby?](./doc/getting_started/why.md)** — Native Rust performance, zero runtime overhead, and Ruby's expressiveness. [See how we compare](./doc/getting_started/why.md) to CharmRuby, raw Rust, and Go.
 
 Please join the **announce** mailing list at https://lists.sr.ht/~kerrick/ratatui_ruby-announce to stay up-to-date on new releases and announcements. See the [`trunk` branch](https://git.sr.ht/~kerrick/ratatui_ruby/tree/trunk) for pre-release updates.
@@ -91,7 +88,7 @@ Or install it yourself with:
   SPDX-License-Identifier: MIT-0
 -->
 ```bash
-gem install ratatui_ruby --pre
+gem install ratatui_ruby
 ```
 <!-- SPDX-SnippetEnd -->
 

data/README.rdoc

@@ -5,7 +5,7 @@ RatatuiRuby[https://rubygems.org/gems/ratatui_ruby] is a RubyGem built on
 Ratatui[https://ratatui.rs], a leading TUI library written in
 Rust[https://rust-lang.org]. You get native performance with the joy of Ruby.
 
-  gem install ratatui_ruby --pre
+  gem install ratatui_ruby
 
 {rdoc-image:https://ratatui-ruby.dev/hero.gif}[https://www.ratatui-ruby.dev/docs/v0.10/examples/app_cli_rich_moments/README_md.html]
 

data/ext/ratatui_ruby/Cargo.lock

@@ -1059,7 +1059,7 @@ dependencies = [
 
 [[package]]
 name = "ratatui_ruby"
-version = "1.0.0-beta.2"
+version = "1.0.0"
 dependencies = [
  "bumpalo",
  "lazy_static",

data/ext/ratatui_ruby/Cargo.toml

@@ -3,7 +3,7 @@
 
 [package]
 name = "ratatui_ruby"
-version = "1.0.0-beta.2"
+version = "1.0.0"
 edition = "2021"
 
 [lib]

data/ext/ratatui_ruby/src/events.rs

@@ -2,9 +2,11 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
 use magnus::{Error, IntoValue, TryConvert, Value};
-use std::sync::Mutex;
+use std::cell::RefCell;
 
-static EVENT_QUEUE: Mutex<Vec<ratatui::crossterm::event::Event>> = Mutex::new(Vec::new());
+thread_local! {
+    static EVENT_QUEUE: RefCell<Vec<ratatui::crossterm::event::Event>> = const { RefCell::new(Vec::new()) };
+}
 
 #[allow(clippy::needless_pass_by_value)]
 pub fn inject_test_event(event_type: String, data: magnus::RHash) -> Result<(), Error> {
@@ -24,7 +26,7 @@ pub fn inject_test_event(event_type: String, data: magnus::RHash) -> Result<(),
         }
     };
 
-    EVENT_QUEUE.lock().unwrap().push(event);
+    EVENT_QUEUE.with(|q| q.borrow_mut().push(event));
     Ok(())
 }
 
@@ -271,30 +273,24 @@ fn parse_paste_event(
 }
 
 pub fn clear_events() {
-    EVENT_QUEUE.lock().unwrap().clear();
+    EVENT_QUEUE.with(|q| q.borrow_mut().clear());
 }
 
 pub fn poll_event(ruby: &magnus::Ruby, timeout_val: Option<f64>) -> Result<Value, Error> {
-    let event = {
-        let mut queue = EVENT_QUEUE.lock().unwrap();
+    let event = EVENT_QUEUE.with(|q| {
+        let mut queue = q.borrow_mut();
         if queue.is_empty() {
             None
         } else {
             Some(queue.remove(0))
         }
-    };
+    });
 
     if let Some(e) = event {
         return handle_event(e);
     }
 
-    let is_test_mode = {
-        let term_lock = crate::terminal::TERMINAL.lock().unwrap();
-        matches!(
-            term_lock.as_ref(),
-            Some(crate::terminal::TerminalWrapper::Test(_))
-        )
-    };
+    let is_test_mode = crate::terminal::with_query(|q| q.is_test_mode()).unwrap_or(false);
 
     if is_test_mode {
         return Ok(ruby.qnil().into_value_with(ruby));

data/ext/ratatui_ruby/src/lib.rs

@@ -17,13 +17,13 @@ mod frame;
 mod rendering;
 mod string_width;
 mod style;
-mod terminal;
+mod terminal; // New module with TerminalQuery trait
 mod text;
 mod widgets;
 
 use frame::RubyFrame;
 use magnus::{function, method, Error, Module, Object, Ruby, Value};
-use terminal::{init_terminal, restore_terminal, TERMINAL};
+use terminal::{init_terminal, restore_terminal};
 
 /// Draw to the terminal.
 ///
@@ -63,63 +63,78 @@ fn draw(args: &[Value]) -> Result<(), Error> {
         ));
     }
 
-    let mut term_lock = TERMINAL.lock().unwrap();
-    let mut render_error: Option<Error> = None;
-
-    // Helper closure to execute the draw callback logic for either terminal type
-    let mut draw_callback = |f: &mut ratatui::Frame<'_>| {
-        if block_given {
-            // New API: yield RubyFrame to block
-            // Create validity flag — set to true while the block is executing
-            let active = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(true));
+    // Nested draw() calls are not allowed - would deadlock
+    if terminal::is_in_draw_mode() {
+        let module = ruby.define_module("RatatuiRuby")?;
+        let error_base = module.const_get::<_, magnus::RClass>("Error")?;
+        let error_class = error_base.const_get("Invariant")?;
+        return Err(Error::new(
+            error_class,
+            "draw cannot be called during another draw (nested draws not allowed)",
+        ));
+    }
 
-            let ruby_frame = RubyFrame::new(f, active.clone());
-            if let Err(e) = ruby.yield_value::<_, Value>(ruby_frame) {
-                render_error = Some(e);
+    // Use lend_for_draw which handles snapshot capture/cleanup automatically
+    let result = terminal::lend_for_draw(|wrapper| {
+        let ruby = magnus::Ruby::get().expect("Ruby must be initialized");
+        let mut render_error: Option<Error> = None;
+
+        // Helper closure to execute the draw callback logic for either terminal type
+        let mut draw_callback = |f: &mut ratatui::Frame<'_>| {
+            if block_given {
+                // New API: yield RubyFrame to block
+                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
+                active.store(false, std::sync::atomic::Ordering::Relaxed);
+            } else if let Some(tree_value) = tree {
+                // Legacy API: render tree to full area
+                let area = f.area();
+                if let Err(e) = rendering::render_node(f.buffer_mut(), area, tree_value) {
+                    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
-            let area = f.area();
-            if let Err(e) = rendering::render_node(f.buffer_mut(), area, tree_value) {
-                render_error = Some(e);
-            }
-        }
-    };
-
-    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")?;
+                let module = ruby.define_module("RatatuiRuby").unwrap();
+                let error_base = module.const_get::<_, magnus::RClass>("Error").unwrap();
+                let error_class = error_base.const_get("Terminal").unwrap();
                 term.draw(&mut draw_callback)
                     .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")?;
+                let module = ruby.define_module("RatatuiRuby").unwrap();
+                let error_base = module.const_get::<_, magnus::RClass>("Error").unwrap();
+                let error_class = error_base.const_get("Terminal").unwrap();
                 term.draw(&mut draw_callback)
                     .map_err(|e| Error::new(error_class, e.to_string()))?;
             }
         }
-    } else {
-        eprintln!("Terminal is None!");
-    }
 
-    if let Some(e) = render_error {
-        return Err(e);
-    }
+        if let Some(e) = render_error {
+            return Err(e);
+        }
 
-    Ok(())
+        Ok(())
+    });
+
+    result.unwrap_or_else(|| {
+        eprintln!("Terminal is None!");
+        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);
+// Storage for the last panic info, to be retrieved and printed after terminal restore.
+thread_local! {
+    static LAST_PANIC: std::cell::RefCell<Option<String>> = const { std::cell::RefCell::new(None) };
+}
 
 /// Enables Rust backtraces and installs a custom panic hook.
 ///
@@ -131,9 +146,9 @@ fn enable_rust_backtrace(_ruby: &magnus::Ruby) {
     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);
-        }
+        LAST_PANIC.with(|p| {
+            *p.borrow_mut() = Some(message);
+        });
     }));
 }
 
@@ -141,11 +156,7 @@ fn enable_rust_backtrace(_ruby: &magnus::Ruby) {
 ///
 /// 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
-    }
+    LAST_PANIC.with(|p| p.borrow_mut().take())
 }
 
 /// Intentionally panics to test backtrace output.

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

@@ -0,0 +1,141 @@
+// SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+//! Terminal initialization and restoration functions.
+
+use magnus::{Error, Module};
+use ratatui::{
+    backend::{CrosstermBackend, TestBackend},
+    Terminal, TerminalOptions, Viewport,
+};
+use std::io;
+
+use super::TerminalWrapper;
+
+// Track whether we're using fullscreen viewport (for restore_terminal)
+thread_local! {
+    static IS_FULLSCREEN: std::cell::Cell<bool> = const { std::cell::Cell::new(false) };
+}
+
+#[allow(clippy::needless_pass_by_value)] // Magnus FFI requires owned String, not &str
+pub fn init_terminal(
+    focus_events: bool,
+    bracketed_paste: bool,
+    viewport_type: String,
+    viewport_height: Option<u16>,
+) -> Result<(), Error> {
+    let ruby = magnus::Ruby::get().unwrap();
+
+    // Check if already initialized
+    if super::is_initialized() {
+        return Ok(());
+    }
+
+    let module = ruby.define_module("RatatuiRuby")?;
+    let error_base = module.const_get::<_, magnus::RClass>("Error")?;
+    let error_class = error_base.const_get("Terminal")?;
+
+    // Parse viewport type
+    let viewport = match viewport_type.as_ref() {
+        "inline" => {
+            let height = viewport_height.unwrap_or(8);
+            Viewport::Inline(height)
+        }
+        _ => Viewport::Fullscreen,
+    };
+
+    ratatui::crossterm::terminal::enable_raw_mode()
+        .map_err(|e| Error::new(error_class, e.to_string()))?;
+    let mut stdout = io::stdout();
+
+    // Only enter alternate screen for fullscreen viewports
+    if matches!(viewport, Viewport::Fullscreen) {
+        ratatui::crossterm::execute!(stdout, ratatui::crossterm::terminal::EnterAlternateScreen)
+            .map_err(|e| Error::new(error_class, e.to_string()))?;
+    }
+
+    ratatui::crossterm::execute!(stdout, ratatui::crossterm::event::EnableMouseCapture)
+        .map_err(|e| Error::new(error_class, e.to_string()))?;
+
+    if focus_events {
+        ratatui::crossterm::execute!(stdout, ratatui::crossterm::event::EnableFocusChange)
+            .map_err(|e| Error::new(error_class, e.to_string()))?;
+    }
+    if bracketed_paste {
+        ratatui::crossterm::execute!(stdout, ratatui::crossterm::event::EnableBracketedPaste)
+            .map_err(|e| Error::new(error_class, e.to_string()))?;
+    }
+
+    let backend = CrosstermBackend::new(stdout);
+
+    // Store whether we're using fullscreen for restore_terminal (before moving viewport)
+    let is_fullscreen = matches!(viewport, Viewport::Fullscreen);
+    IS_FULLSCREEN.with(|f| f.set(is_fullscreen));
+
+    let options = TerminalOptions { viewport };
+    let terminal = Terminal::with_options(backend, options)
+        .map_err(|e| Error::new(error_class, e.to_string()))?;
+
+    super::set_terminal(TerminalWrapper::Crossterm(terminal));
+    Ok(())
+}
+
+#[allow(clippy::needless_pass_by_value)] // Magnus FFI requires owned String, not &str
+pub fn init_test_terminal(
+    width: u16,
+    height: u16,
+    viewport_type: String,
+    viewport_height: Option<u16>,
+) -> Result<(), Error> {
+    let ruby = magnus::Ruby::get().unwrap();
+    let backend = TestBackend::new(width, height);
+    let module = ruby.define_module("RatatuiRuby")?;
+    let error_base = module.const_get::<_, magnus::RClass>("Error")?;
+    let error_class = error_base.const_get("Terminal")?;
+
+    // Parse viewport type (same as init_terminal)
+    let viewport = match viewport_type.as_ref() {
+        "inline" => {
+            let vp_height = viewport_height.unwrap_or(height);
+            Viewport::Inline(vp_height)
+        }
+        _ => Viewport::Fullscreen,
+    };
+
+    let options = TerminalOptions { viewport };
+    let terminal = Terminal::with_options(backend, options)
+        .map_err(|e| Error::new(error_class, e.to_string()))?;
+
+    super::set_terminal(TerminalWrapper::Test(terminal));
+    Ok(())
+}
+
+pub fn restore_terminal() {
+    if let Some(wrapper) = super::take_terminal() {
+        match wrapper {
+            TerminalWrapper::Crossterm(mut t) => {
+                let _ = ratatui::crossterm::terminal::disable_raw_mode();
+
+                // Only leave alternate screen if we were in fullscreen mode
+                let is_fullscreen = IS_FULLSCREEN.with(std::cell::Cell::get);
+                if is_fullscreen {
+                    let _ = ratatui::crossterm::execute!(
+                        t.backend_mut(),
+                        ratatui::crossterm::terminal::LeaveAlternateScreen,
+                        ratatui::crossterm::event::DisableMouseCapture,
+                        ratatui::crossterm::event::DisableFocusChange,
+                        ratatui::crossterm::event::DisableBracketedPaste
+                    );
+                } else {
+                    let _ = ratatui::crossterm::execute!(
+                        t.backend_mut(),
+                        ratatui::crossterm::event::DisableMouseCapture,
+                        ratatui::crossterm::event::DisableFocusChange,
+                        ratatui::crossterm::event::DisableBracketedPaste
+                    );
+                }
+            }
+            TerminalWrapper::Test(_) => {}
+        }
+    }
+}

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

@@ -0,0 +1,33 @@
+// SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+//! Terminal management module.
+//!
+//! Provides thread-local terminal storage with safe accessors. Queries
+//! during `draw()` callbacks return data from a pre-captured snapshot,
+//! avoiding reentrancy issues with the terminal lock.
+
+mod init;
+mod mutations;
+mod queries;
+mod query;
+mod storage;
+mod wrapper;
+
+pub use storage::{
+    is_in_draw_mode, is_initialized, lend_for_draw, set_terminal, take_terminal, with_query,
+    with_terminal_mut,
+};
+pub use wrapper::TerminalWrapper;
+
+// Init/restore functions
+pub use init::{init_terminal, init_test_terminal, 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,
+};
+
+// Mutation functions
+pub use mutations::{insert_before, resize_terminal, set_cursor_position};