ratatui_ruby 1.0.0.pre.beta.2 → 1.0.0.pre.beta.3

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

@@ -0,0 +1,216 @@
+// SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+//! Terminal query functions (read-only access to terminal state).
+
+use magnus::value::ReprValue;
+use magnus::{Error, Module, Value};
+
+use super::TerminalWrapper;
+
+pub fn get_buffer_content() -> Result<String, Error> {
+    let ruby = magnus::Ruby::get().unwrap();
+
+    // This function builds a string from all cells - we need direct terminal access
+    crate::terminal::with_terminal_mut(|wrapper| {
+        if let TerminalWrapper::Test(terminal) = wrapper {
+            let buffer = terminal.backend().buffer();
+            let area = buffer.area;
+            let mut result = String::new();
+            for y in 0..area.height {
+                for x in 0..area.width {
+                    let cell = buffer.cell((x, y)).unwrap();
+                    result.push_str(cell.symbol());
+                }
+                result.push('\n');
+            }
+            Ok(result)
+        } else {
+            let module = ruby.define_module("RatatuiRuby").unwrap();
+            let error_base = module.const_get::<_, magnus::RClass>("Error").unwrap();
+            let error_class = error_base.const_get("Terminal").unwrap();
+            Err(Error::new(
+                error_class,
+                "Terminal is not initialized as TestBackend",
+            ))
+        }
+    })
+    .unwrap_or_else(|| {
+        let module = ruby.define_module("RatatuiRuby").unwrap();
+        let error_base = module.const_get::<_, magnus::RClass>("Error").unwrap();
+        let error_class = error_base.const_get("Terminal").unwrap();
+        Err(Error::new(error_class, "Terminal is not initialized"))
+    })
+}
+
+pub fn get_terminal_area() -> Result<magnus::RHash, Error> {
+    let ruby = magnus::Ruby::get().unwrap();
+
+    crate::terminal::with_query(|q| {
+        let area = q.viewport_area();
+        let hash = ruby.hash_new();
+        hash.aset("x", area.x).unwrap();
+        hash.aset("y", area.y).unwrap();
+        hash.aset("width", area.width).unwrap();
+        hash.aset("height", area.height).unwrap();
+        Ok(hash)
+    })
+    .unwrap_or_else(|| {
+        let module = ruby.define_module("RatatuiRuby").unwrap();
+        let error_base = module.const_get::<_, magnus::RClass>("Error").unwrap();
+        let error_class = error_base.const_get("Terminal").unwrap();
+        Err(Error::new(error_class, "Terminal is not initialized"))
+    })
+}
+
+/// Returns the full terminal backend size (not the viewport)
+pub fn get_terminal_size() -> Result<magnus::RHash, Error> {
+    let ruby = magnus::Ruby::get().unwrap();
+
+    crate::terminal::with_query(|q| {
+        let size = q.size();
+        let hash = ruby.hash_new();
+        hash.aset("x", 0).unwrap();
+        hash.aset("y", 0).unwrap();
+        hash.aset("width", size.width).unwrap();
+        hash.aset("height", size.height).unwrap();
+        Ok(hash)
+    })
+    .unwrap_or_else(|| {
+        let module = ruby.define_module("RatatuiRuby").unwrap();
+        let error_base = module.const_get::<_, magnus::RClass>("Error").unwrap();
+        let error_class = error_base.const_get("Terminal").unwrap();
+        Err(Error::new(error_class, "Terminal is not initialized"))
+    })
+}
+
+pub fn get_viewport_type() -> Result<String, Error> {
+    let ruby = magnus::Ruby::get().unwrap();
+
+    crate::terminal::with_query(|q| {
+        let viewport = q.viewport_area();
+        let size = q.size();
+        if viewport.height < size.height {
+            Ok("inline".to_string())
+        } else {
+            Ok("fullscreen".to_string())
+        }
+    })
+    .unwrap_or_else(|| {
+        let module = ruby.define_module("RatatuiRuby").unwrap();
+        let error_base = module.const_get::<_, magnus::RClass>("Error").unwrap();
+        let error_class = error_base.const_get("Terminal").unwrap();
+        Err(Error::new(error_class, "Terminal not initialized"))
+    })
+}
+
+pub fn get_cursor_position() -> Result<Option<(u16, u16)>, Error> {
+    let ruby = magnus::Ruby::get().unwrap();
+
+    crate::terminal::with_query(|q| Ok(q.cursor_position())).unwrap_or_else(|| {
+        let module = ruby.define_module("RatatuiRuby").unwrap();
+        let error_base = module.const_get::<_, magnus::RClass>("Error").unwrap();
+        let error_class = error_base.const_get("Terminal").unwrap();
+        Err(Error::new(
+            error_class,
+            "Terminal is not initialized as TestBackend",
+        ))
+    })
+}
+
+pub fn get_cell_at(x: u16, y: u16) -> Result<magnus::RHash, Error> {
+    let ruby = magnus::Ruby::get().unwrap();
+
+    crate::terminal::with_query(|q| {
+        if let Some(cell) = q.cell_at(x, y) {
+            let hash = ruby.hash_new();
+            hash.aset("char", cell.symbol()).unwrap();
+            hash.aset("fg", color_to_value(cell.fg)).unwrap();
+            hash.aset("bg", color_to_value(cell.bg)).unwrap();
+            hash.aset("underline_color", color_to_value(cell.underline_color))
+                .unwrap();
+            hash.aset("modifiers", modifiers_to_value(cell.modifier))
+                .unwrap();
+            Ok(hash)
+        } else {
+            let module = ruby.define_module("RatatuiRuby").unwrap();
+            let error_base = module.const_get::<_, magnus::RClass>("Error").unwrap();
+            let error_class = error_base.const_get("Terminal").unwrap();
+            Err(Error::new(
+                error_class,
+                format!("Coordinates ({x}, {y}) out of bounds"),
+            ))
+        }
+    })
+    .unwrap_or_else(|| {
+        let module = ruby.define_module("RatatuiRuby").unwrap();
+        let error_base = module.const_get::<_, magnus::RClass>("Error").unwrap();
+        let error_class = error_base.const_get("Terminal").unwrap();
+        Err(Error::new(
+            error_class,
+            "Terminal is not initialized as TestBackend",
+        ))
+    })
+}
+
+fn color_to_value(color: ratatui::style::Color) -> Value {
+    let ruby = magnus::Ruby::get().unwrap();
+    match color {
+        ratatui::style::Color::Reset => ruby.qnil().as_value(),
+        ratatui::style::Color::Black => ruby.to_symbol("black").as_value(),
+        ratatui::style::Color::Red => ruby.to_symbol("red").as_value(),
+        ratatui::style::Color::Green => ruby.to_symbol("green").as_value(),
+        ratatui::style::Color::Yellow => ruby.to_symbol("yellow").as_value(),
+        ratatui::style::Color::Blue => ruby.to_symbol("blue").as_value(),
+        ratatui::style::Color::Magenta => ruby.to_symbol("magenta").as_value(),
+        ratatui::style::Color::Cyan => ruby.to_symbol("cyan").as_value(),
+        ratatui::style::Color::Gray => ruby.to_symbol("gray").as_value(),
+        ratatui::style::Color::DarkGray => ruby.to_symbol("dark_gray").as_value(),
+        ratatui::style::Color::LightRed => ruby.to_symbol("light_red").as_value(),
+        ratatui::style::Color::LightGreen => ruby.to_symbol("light_green").as_value(),
+        ratatui::style::Color::LightYellow => ruby.to_symbol("light_yellow").as_value(),
+        ratatui::style::Color::LightBlue => ruby.to_symbol("light_blue").as_value(),
+        ratatui::style::Color::LightMagenta => ruby.to_symbol("light_magenta").as_value(),
+        ratatui::style::Color::LightCyan => ruby.to_symbol("light_cyan").as_value(),
+        ratatui::style::Color::White => ruby.to_symbol("white").as_value(),
+        ratatui::style::Color::Rgb(r, g, b) => ruby
+            .str_new(&(format!("#{r:02x}{g:02x}{b:02x}")))
+            .as_value(),
+        ratatui::style::Color::Indexed(i) => ruby.to_symbol(format!("indexed_{i}")).as_value(),
+    }
+}
+
+fn modifiers_to_value(modifier: ratatui::style::Modifier) -> Value {
+    let ruby = magnus::Ruby::get().unwrap();
+    let ary = ruby.ary_new();
+
+    if modifier.contains(ratatui::style::Modifier::BOLD) {
+        let _ = ary.push(ruby.to_symbol("bold"));
+    }
+    if modifier.contains(ratatui::style::Modifier::ITALIC) {
+        let _ = ary.push(ruby.to_symbol("italic"));
+    }
+    if modifier.contains(ratatui::style::Modifier::DIM) {
+        let _ = ary.push(ruby.to_symbol("dim"));
+    }
+    if modifier.contains(ratatui::style::Modifier::UNDERLINED) {
+        let _ = ary.push(ruby.to_symbol("underlined"));
+    }
+    if modifier.contains(ratatui::style::Modifier::REVERSED) {
+        let _ = ary.push(ruby.to_symbol("reversed"));
+    }
+    if modifier.contains(ratatui::style::Modifier::HIDDEN) {
+        let _ = ary.push(ruby.to_symbol("hidden"));
+    }
+    if modifier.contains(ratatui::style::Modifier::CROSSED_OUT) {
+        let _ = ary.push(ruby.to_symbol("crossed_out"));
+    }
+    if modifier.contains(ratatui::style::Modifier::SLOW_BLINK) {
+        let _ = ary.push(ruby.to_symbol("slow_blink"));
+    }
+    if modifier.contains(ratatui::style::Modifier::RAPID_BLINK) {
+        let _ = ary.push(ruby.to_symbol("rapid_blink"));
+    }
+
+    ary.as_value()
+}

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

@@ -0,0 +1,338 @@
+// SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+//! Terminal query trait and implementations.
+//!
+//! This module provides a compiler-enforced interface for querying terminal state.
+//! All queries go through `TerminalQuery` trait which has two implementations:
+//! - `LiveTerminal`: Used outside draw, queries actual terminal
+//! - `DrawSnapshot`: Used during draw, queries pre-captured snapshot
+
+use ratatui::buffer::Cell;
+use ratatui::layout::Rect;
+
+/// All terminal queries MUST go through this trait.
+/// Compiler enforces both implementations when adding new queries.
+pub trait TerminalQuery {
+    fn size(&self) -> Rect;
+    fn viewport_area(&self) -> Rect;
+    fn is_test_mode(&self) -> bool;
+    fn cursor_position(&self) -> Option<(u16, u16)>;
+    fn cell_at(&self, x: u16, y: u16) -> Option<Cell>;
+}
+
+/// Snapshot of terminal state captured before draw.
+/// Answers queries during draw without accessing terminal.
+#[derive(Clone)]
+pub struct DrawSnapshot {
+    pub size: Rect,
+    pub viewport_area: Rect,
+    pub is_test_mode: bool,
+    pub cursor_position: Option<(u16, u16)>,
+    pub buffer: Option<ratatui::buffer::Buffer>,
+}
+
+impl DrawSnapshot {
+    /// Capture snapshot from a `TerminalWrapper`.
+    pub fn capture(wrapper: &mut super::wrapper::TerminalWrapper) -> Self {
+        match wrapper {
+            super::wrapper::TerminalWrapper::Crossterm(t) => {
+                let size = t.size().unwrap_or_default();
+                let viewport = t.get_frame().area();
+                Self {
+                    size: Rect::new(0, 0, size.width, size.height),
+                    viewport_area: viewport,
+                    is_test_mode: false,
+                    cursor_position: None,
+                    buffer: None,
+                }
+            }
+            super::wrapper::TerminalWrapper::Test(t) => {
+                let size = t.size().unwrap_or_default();
+                let viewport = t.get_frame().area();
+                let cursor = t.get_cursor_position().ok().map(Into::into);
+                let buffer = t.backend().buffer().clone();
+                Self {
+                    size: Rect::new(0, 0, size.width, size.height),
+                    viewport_area: viewport,
+                    is_test_mode: true,
+                    cursor_position: cursor,
+                    buffer: Some(buffer),
+                }
+            }
+        }
+    }
+}
+
+impl TerminalQuery for DrawSnapshot {
+    fn size(&self) -> Rect {
+        self.size
+    }
+    fn viewport_area(&self) -> Rect {
+        self.viewport_area
+    }
+    fn is_test_mode(&self) -> bool {
+        self.is_test_mode
+    }
+    fn cursor_position(&self) -> Option<(u16, u16)> {
+        self.cursor_position
+    }
+    fn cell_at(&self, x: u16, y: u16) -> Option<Cell> {
+        self.buffer.as_ref()?.cell((x, y)).cloned()
+    }
+}
+
+/// Live queries against actual terminal (outside draw).
+/// Uses interior mutability since ratatui's API requires &mut for some queries.
+pub struct LiveTerminal<'a>(std::cell::RefCell<&'a mut super::wrapper::TerminalWrapper>);
+
+impl<'a> LiveTerminal<'a> {
+    pub fn new(wrapper: &'a mut super::wrapper::TerminalWrapper) -> Self {
+        Self(std::cell::RefCell::new(wrapper))
+    }
+}
+
+impl TerminalQuery for LiveTerminal<'_> {
+    fn size(&self) -> Rect {
+        match *self.0.borrow() {
+            super::wrapper::TerminalWrapper::Crossterm(ref t) => {
+                let s = t.size().unwrap_or_default();
+                Rect::new(0, 0, s.width, s.height)
+            }
+            super::wrapper::TerminalWrapper::Test(ref t) => {
+                let s = t.size().unwrap_or_default();
+                Rect::new(0, 0, s.width, s.height)
+            }
+        }
+    }
+
+    fn viewport_area(&self) -> Rect {
+        match *self.0.borrow_mut() {
+            super::wrapper::TerminalWrapper::Crossterm(ref mut t) => t.get_frame().area(),
+            super::wrapper::TerminalWrapper::Test(ref mut t) => t.get_frame().area(),
+        }
+    }
+    fn is_test_mode(&self) -> bool {
+        matches!(*self.0.borrow(), super::wrapper::TerminalWrapper::Test(_))
+    }
+    fn cursor_position(&self) -> Option<(u16, u16)> {
+        match *self.0.borrow_mut() {
+            super::wrapper::TerminalWrapper::Test(ref mut t) => {
+                t.get_cursor_position().ok().map(Into::into)
+            }
+            super::wrapper::TerminalWrapper::Crossterm(_) => None,
+        }
+    }
+    fn cell_at(&self, x: u16, y: u16) -> Option<Cell> {
+        match &*self.0.borrow() {
+            super::wrapper::TerminalWrapper::Test(t) => t.backend().buffer().cell((x, y)).cloned(),
+            super::wrapper::TerminalWrapper::Crossterm(_) => None,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // Test: TerminalQuery trait can be implemented by a simple struct
+    struct MockQuery {
+        size: Rect,
+    }
+
+    impl TerminalQuery for MockQuery {
+        fn size(&self) -> Rect {
+            self.size
+        }
+        fn viewport_area(&self) -> Rect {
+            Rect::default()
+        }
+        fn is_test_mode(&self) -> bool {
+            false
+        }
+        fn cursor_position(&self) -> Option<(u16, u16)> {
+            None
+        }
+        fn cell_at(&self, _x: u16, _y: u16) -> Option<Cell> {
+            None
+        }
+    }
+
+    #[test]
+    fn test_trait_can_be_implemented() {
+        let query = MockQuery {
+            size: Rect::new(0, 0, 80, 24),
+        };
+        assert_eq!(query.size(), Rect::new(0, 0, 80, 24));
+    }
+
+    #[test]
+    fn test_draw_snapshot_returns_size() {
+        let snapshot = super::DrawSnapshot {
+            size: Rect::new(0, 0, 120, 40),
+            viewport_area: Rect::new(0, 0, 120, 40),
+            is_test_mode: false,
+            cursor_position: None,
+            buffer: None,
+        };
+        assert_eq!(snapshot.size(), Rect::new(0, 0, 120, 40));
+    }
+
+    #[test]
+    fn test_draw_snapshot_returns_viewport_area() {
+        let snapshot = super::DrawSnapshot {
+            size: Rect::new(0, 0, 120, 40),
+            viewport_area: Rect::new(5, 10, 80, 20), // Different from size!
+            is_test_mode: false,
+            cursor_position: None,
+            buffer: None,
+        };
+        // This should return the stored viewport_area, not Rect::default()
+        assert_eq!(snapshot.viewport_area(), Rect::new(5, 10, 80, 20));
+    }
+
+    #[test]
+    fn test_draw_snapshot_returns_is_test_mode() {
+        let snapshot = super::DrawSnapshot {
+            size: Rect::default(),
+            viewport_area: Rect::default(),
+            is_test_mode: true, // TRUE!
+            cursor_position: None,
+            buffer: None,
+        };
+        assert!(snapshot.is_test_mode());
+    }
+
+    #[test]
+    fn test_draw_snapshot_returns_cursor_position() {
+        let snapshot = super::DrawSnapshot {
+            size: Rect::default(),
+            viewport_area: Rect::default(),
+            is_test_mode: false,
+            cursor_position: Some((15, 20)), // Not None!
+            buffer: None,
+        };
+        assert_eq!(snapshot.cursor_position(), Some((15, 20)));
+    }
+
+    #[test]
+    fn test_draw_snapshot_returns_cell_at() {
+        use ratatui::buffer::Buffer;
+
+        // Create a buffer with a known cell
+        let mut buffer = Buffer::empty(Rect::new(0, 0, 10, 10));
+        buffer[(5, 5)].set_char('X');
+
+        let snapshot = super::DrawSnapshot {
+            size: Rect::new(0, 0, 10, 10),
+            viewport_area: Rect::new(0, 0, 10, 10),
+            is_test_mode: true,
+            cursor_position: None,
+            buffer: Some(buffer),
+        };
+
+        let cell = snapshot.cell_at(5, 5);
+        assert!(cell.is_some());
+        assert_eq!(cell.unwrap().symbol(), "X");
+    }
+
+    #[test]
+    fn test_capture_from_terminal_wrapper() {
+        use crate::terminal::TerminalWrapper;
+        use ratatui::{backend::TestBackend, Terminal};
+
+        let backend = TestBackend::new(80, 24);
+        let terminal = Terminal::new(backend).unwrap();
+        let mut wrapper = TerminalWrapper::Test(terminal);
+
+        let snapshot = super::DrawSnapshot::capture(&mut wrapper);
+
+        assert_eq!(snapshot.size(), Rect::new(0, 0, 80, 24));
+        assert!(snapshot.is_test_mode());
+    }
+
+    #[test]
+    fn test_live_terminal_exists() {
+        use crate::terminal::TerminalWrapper;
+        use ratatui::{backend::TestBackend, Terminal};
+
+        let backend = TestBackend::new(80, 24);
+        let terminal = Terminal::new(backend).unwrap();
+        let mut wrapper = TerminalWrapper::Test(terminal);
+
+        // LiveTerminal should exist and wrap a TerminalWrapper reference
+        let _live = super::LiveTerminal::new(&mut wrapper);
+    }
+
+    #[test]
+    fn test_live_terminal_returns_size() {
+        use crate::terminal::TerminalWrapper;
+        use ratatui::{backend::TestBackend, Terminal};
+
+        let backend = TestBackend::new(100, 50);
+        let terminal = Terminal::new(backend).unwrap();
+        let mut wrapper = TerminalWrapper::Test(terminal);
+
+        let live = super::LiveTerminal::new(&mut wrapper);
+        // LiveTerminal must implement TerminalQuery
+        let size = live.size();
+        assert_eq!(size.width, 100);
+        assert_eq!(size.height, 50);
+    }
+
+    #[test]
+    fn test_live_terminal_returns_is_test_mode() {
+        use crate::terminal::TerminalWrapper;
+        use ratatui::{backend::TestBackend, Terminal};
+
+        let backend = TestBackend::new(80, 24);
+        let terminal = Terminal::new(backend).unwrap();
+        let mut wrapper = TerminalWrapper::Test(terminal);
+
+        let live = super::LiveTerminal::new(&mut wrapper);
+        // TestBackend should return true for is_test_mode
+        assert!(live.is_test_mode());
+    }
+
+    #[test]
+    fn test_live_terminal_returns_viewport_area() {
+        use crate::terminal::TerminalWrapper;
+        use ratatui::{backend::TestBackend, Terminal};
+
+        let backend = TestBackend::new(120, 40);
+        let terminal = Terminal::new(backend).unwrap();
+        let mut wrapper = TerminalWrapper::Test(terminal);
+
+        let live = super::LiveTerminal::new(&mut wrapper);
+        let viewport = live.viewport_area();
+        // Viewport should match the terminal size for fullscreen mode
+        assert_eq!(viewport.width, 120);
+        assert_eq!(viewport.height, 40);
+    }
+
+    #[test]
+    fn test_live_terminal_viewport_area_differs_from_size_for_inline() {
+        use crate::terminal::TerminalWrapper;
+        use ratatui::{backend::TestBackend, Terminal, Viewport};
+
+        // Create terminal with inline viewport of height 5 in a 40-line terminal
+        let backend = TestBackend::new(80, 40);
+        let options = ratatui::TerminalOptions {
+            viewport: Viewport::Inline(5),
+        };
+        let terminal = Terminal::with_options(backend, options).unwrap();
+        let mut wrapper = TerminalWrapper::Test(terminal);
+
+        let live = super::LiveTerminal::new(&mut wrapper);
+        let size = live.size();
+        let viewport = live.viewport_area();
+
+        // Terminal size is 80x40
+        assert_eq!(size.width, 80);
+        assert_eq!(size.height, 40);
+
+        // But viewport is only 5 lines high (inline mode)
+        assert_eq!(viewport.width, 80);
+        assert_eq!(viewport.height, 5);
+    }
+}

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

@@ -0,0 +1,109 @@
+// SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+//! Private terminal storage with safe accessor functions.
+//!
+//! This module provides thread-local storage for the terminal and draw snapshot,
+//! with functions that route queries correctly:
+//! - During draw: queries go to snapshot (no lock needed)
+//! - Outside draw: queries go to live terminal
+
+use super::query::{DrawSnapshot, LiveTerminal, TerminalQuery};
+use super::wrapper::TerminalWrapper;
+use std::cell::RefCell;
+
+thread_local! {
+    static TERMINAL: RefCell<Option<TerminalWrapper>> = const { RefCell::new(None) };
+    static DRAW_SNAPSHOT: RefCell<Option<DrawSnapshot>> = const { RefCell::new(None) };
+}
+
+/// Check if we're currently inside a draw operation.
+pub fn is_in_draw_mode() -> bool {
+    DRAW_SNAPSHOT.with(|cell| cell.borrow().is_some())
+}
+
+/// Execute a query. Routes to snapshot during draw, live terminal outside.
+pub fn with_query<R, F>(f: F) -> Option<R>
+where
+    F: Fn(&dyn TerminalQuery) -> R,
+{
+    // During draw: use snapshot
+    DRAW_SNAPSHOT
+        .with(|cell| cell.borrow().as_ref().map(|snapshot| f(snapshot)))
+        .or_else(|| {
+            // Outside draw: use live terminal from thread-local storage
+            TERMINAL.with(|cell| {
+                cell.borrow_mut().as_mut().map(|t| {
+                    let live = LiveTerminal::new(t);
+                    f(&live)
+                })
+            })
+        })
+}
+
+/// Mutable access to terminal. Only works OUTSIDE draw.
+pub fn with_terminal_mut<R, F>(f: F) -> Option<R>
+where
+    F: FnOnce(&mut TerminalWrapper) -> R,
+{
+    // During draw: reject
+    if is_in_draw_mode() {
+        return None;
+    }
+    TERMINAL.with(|cell| cell.borrow_mut().as_mut().map(f))
+}
+
+/// Execute draw with snapshot for queries.
+pub fn lend_for_draw<R, F>(f: F) -> Option<R>
+where
+    F: FnOnce(&mut TerminalWrapper) -> R,
+{
+    // Take terminal out of storage
+    let mut terminal = TERMINAL.with(|cell| cell.borrow_mut().take())?;
+
+    // Capture snapshot BEFORE draw (while we have &mut)
+    let snapshot = DrawSnapshot::capture(&mut terminal);
+    DRAW_SNAPSHOT.with(|cell| *cell.borrow_mut() = Some(snapshot));
+
+    let result = f(&mut terminal);
+
+    // Clear snapshot, restore terminal
+    DRAW_SNAPSHOT.with(|cell| *cell.borrow_mut() = None);
+    TERMINAL.with(|cell| *cell.borrow_mut() = Some(terminal));
+
+    Some(result)
+}
+
+/// Set the terminal (used during initialization).
+pub fn set_terminal(wrapper: TerminalWrapper) {
+    TERMINAL.with(|cell| {
+        *cell.borrow_mut() = Some(wrapper);
+    });
+}
+
+/// Take the terminal out of storage (used during cleanup).
+pub fn take_terminal() -> Option<TerminalWrapper> {
+    TERMINAL.with(|cell| cell.borrow_mut().take())
+}
+
+/// Check if terminal is initialized.
+pub fn is_initialized() -> bool {
+    TERMINAL.with(|cell| cell.borrow().is_some())
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::terminal::query::DrawSnapshot;
+    use ratatui::layout::Rect;
+
+    #[test]
+    fn test_is_in_draw_mode_false_by_default() {
+        assert!(!super::is_in_draw_mode());
+    }
+
+    #[test]
+    fn test_with_query_returns_none_when_not_initialized() {
+        let result = super::with_query(|q| q.size());
+        assert!(result.is_none());
+    }
+}

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

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+//! Terminal wrapper enum for different backend types.
+
+use ratatui::{
+    backend::{CrosstermBackend, TestBackend},
+    Terminal,
+};
+use std::io;
+
+/// Unified terminal type supporting different backends.
+pub enum TerminalWrapper {
+    Crossterm(Terminal<CrosstermBackend<io::Stdout>>),
+    Test(Terminal<TestBackend>),
+}

data/lib/ratatui_ruby/version.rb

@@ -8,5 +8,5 @@
 module RatatuiRuby
   # The version of the ratatui_ruby gem.
   # See https://semver.org/spec/v2.0.0.html
-  VERSION = "1.0.0-beta.2"
+  VERSION = "1.0.0-beta.3"
 end