ratatui_ruby 1.4.0-x86_64-linux

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

@@ -0,0 +1,400 @@
+// 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>;
+    fn frame_count(&self) -> usize;
+}
+
+/// 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>,
+    pub frame_count: usize,
+}
+
+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 frame = t.get_frame();
+                let viewport = frame.area();
+                let count = frame.count();
+                Self {
+                    size: Rect::new(0, 0, size.width, size.height),
+                    viewport_area: viewport,
+                    is_test_mode: false,
+                    cursor_position: None,
+                    buffer: None,
+                    frame_count: count,
+                }
+            }
+            super::wrapper::TerminalWrapper::Test(t) => {
+                let size = t.size().unwrap_or_default();
+                let frame = t.get_frame();
+                let viewport = frame.area();
+                let count = frame.count();
+                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),
+                    frame_count: count,
+                }
+            }
+        }
+    }
+}
+
+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()
+    }
+    fn frame_count(&self) -> usize {
+        self.frame_count
+    }
+}
+
+/// 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,
+        }
+    }
+    fn frame_count(&self) -> usize {
+        match *self.0.borrow_mut() {
+            super::wrapper::TerminalWrapper::Crossterm(ref mut t) => t.get_frame().count(),
+            super::wrapper::TerminalWrapper::Test(ref mut t) => t.get_frame().count(),
+        }
+    }
+}
+
+#[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
+        }
+        fn frame_count(&self) -> usize {
+            0
+        }
+    }
+
+    #[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,
+            frame_count: 0,
+        };
+        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,
+            frame_count: 0,
+        };
+        // 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,
+            frame_count: 0,
+        };
+        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,
+            frame_count: 0,
+        };
+        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),
+            frame_count: 0,
+        };
+
+        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);
+    }
+
+    #[test]
+    fn test_live_terminal_frame_count_increases_after_draw() {
+        use crate::terminal::TerminalWrapper;
+        use ratatui::{backend::TestBackend, Terminal};
+
+        let backend = TestBackend::new(80, 24);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        // Draw once to increment the counter
+        terminal.draw(|_frame| {}).unwrap();
+
+        let mut wrapper = TerminalWrapper::Test(terminal);
+        let live = super::LiveTerminal::new(&mut wrapper);
+
+        // Frame count should be 1 after one draw, NOT 0!
+        assert_eq!(live.frame_count(), 1);
+    }
+
+    #[test]
+    fn test_live_terminal_frame_count_increases_with_multiple_draws() {
+        use crate::terminal::TerminalWrapper;
+        use ratatui::{backend::TestBackend, Terminal};
+
+        let backend = TestBackend::new(80, 24);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        // Draw twice
+        terminal.draw(|_frame| {}).unwrap();
+        terminal.draw(|_frame| {}).unwrap();
+
+        let mut wrapper = TerminalWrapper::Test(terminal);
+        let live = super::LiveTerminal::new(&mut wrapper);
+
+        // Frame count should be 2 after two draws!
+        assert_eq!(live.frame_count(), 2);
+    }
+}

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>),
+}