ratatui_ruby 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65cec825c4cedc983b69cfa150cf30bfc295b1aff70c4866dc18161e97207da0
-  data.tar.gz: '085eef207a3cb0d29e0992c1885ff788867387a725925d596bba309086ce6c2d'
+  metadata.gz: 3e12c46f758cf25eb436da52bbdcbf46f5cd256b804cb3f67a2d6edeeb8d4062
+  data.tar.gz: c4aa2e4c6251a6a75b8ac57e3c7f6133c88066185ee5e9cd1633fbc459edf612
 SHA512:
-  metadata.gz: c3e69e5096a3d8790d6b81ec6a3fa0589565d5cbf3661f6bc78070c2ee91d29bd068fb5a31fe84e81364544e127e629f080faf6cb533d729fda58a18ed862ba1
-  data.tar.gz: 5deeb497d1c9663d7c35efee84f8d2ca8b501810772eaf57750f2d452939e0d45c7847b13d18f59943872e3c46f649141b1e9cce09fa2242f6593168c83d3922
+  metadata.gz: dca9adc8ecef9e432c163b5b7b9e2488d42f9f1db98212a5c140a70bf21dc6c19fa687a97fb30d52ef9cadf8c5dd34a3aecbe471562ba5d9bfdb8c1ff85b99bf
+  data.tar.gz: 5f1e347a863736fae0ea9854a37402bd3115c311a228c23b24848113c23a21beeb97b5a33a9177611cd83c7e9d61ed6b4c4c9cf85c110e89f358e805f456465c

data/ext/ratatui_ruby/Cargo.lock

@@ -1059,12 +1059,13 @@ dependencies = [
 
 [[package]]
 name = "ratatui_ruby"
-version = "1.3.0"
+version = "1.4.0"
 dependencies = [
  "bumpalo",
  "lazy_static",
  "magnus",
  "ratatui",
+ "rb-sys",
  "time",
  "unicode-width 0.1.14",
 ]

data/ext/ratatui_ruby/Cargo.toml

@@ -3,7 +3,7 @@
 
 [package]
 name = "ratatui_ruby"
-version = "1.3.0"
+version = "1.4.0"
 edition = "2021"
 
 [lib]
@@ -11,6 +11,7 @@ crate-type = ["cdylib", "staticlib"]
 
 [dependencies]
 magnus = "0.8.2"
+rb-sys = "*"
 ratatui = { version = "0.30", features = ["widget-calendar", "layout-cache", "unstable-rendered-line-info", "palette"] }
 unicode-width = "0.1"
 

data/ext/ratatui_ruby/src/events.rs

@@ -2,7 +2,9 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
 use magnus::{Error, IntoValue, TryConvert, Value};
+use rb_sys::rb_thread_call_without_gvl;
 use std::cell::RefCell;
+use std::os::raw::c_void;
 
 /// Wrapper enum for test events - includes crossterm events and our Sync event.
 #[derive(Debug, Clone)]
@@ -314,6 +316,92 @@ pub fn clear_events() {
     EVENT_QUEUE.with(|q| q.borrow_mut().clear());
 }
 
+/// Result of polling crossterm from outside the GVL.
+///
+/// The blocking I/O (poll + read) happens without the Ruby GVL held,
+/// so other Ruby threads can run concurrently. This enum carries the
+/// result back across the GVL boundary for Ruby object construction.
+#[derive(Debug)]
+enum PollResult {
+    /// A crossterm event was read successfully.
+    Event(ratatui::crossterm::event::Event),
+    /// The timeout expired with no event available.
+    NoEvent,
+    /// An I/O error occurred during poll or read.
+    Error(String),
+}
+
+/// Data passed to the GVL-free polling callback.
+///
+/// The `timeout` field controls the poll behavior:
+/// - `Some(duration)`: poll with a timeout, return `NoEvent` if it expires.
+/// - `None`: block indefinitely until an event arrives.
+struct PollData {
+    timeout: Option<std::time::Duration>,
+    result: PollResult,
+}
+
+/// Polls crossterm for events without the Ruby GVL held.
+///
+/// This is the work function passed to `rb_thread_call_without_gvl`.
+/// It performs blocking I/O that would otherwise starve Ruby threads.
+extern "C" fn poll_without_gvl(data: *mut c_void) -> *mut c_void {
+    // SAFETY: `data` is a valid pointer to `PollData`, passed by
+    // `poll_crossterm_without_gvl` via `rb_thread_call_without_gvl`. The
+    // pointer remains valid for the duration of this callback because the
+    // caller owns the `PollData` on the stack and waits for us to return.
+    let data = unsafe { &mut *data.cast::<PollData>() };
+
+    data.result = match data.timeout {
+        Some(duration) => match ratatui::crossterm::event::poll(duration) {
+            Ok(true) => match ratatui::crossterm::event::read() {
+                Ok(event) => PollResult::Event(event),
+                Err(e) => PollResult::Error(e.to_string()),
+            },
+            Ok(false) => PollResult::NoEvent,
+            Err(e) => PollResult::Error(e.to_string()),
+        },
+        None => match ratatui::crossterm::event::read() {
+            Ok(event) => PollResult::Event(event),
+            Err(e) => PollResult::Error(e.to_string()),
+        },
+    };
+
+    std::ptr::null_mut()
+}
+
+/// Polls crossterm with the GVL released, then converts the result
+/// to a Ruby value after reacquiring the GVL.
+fn poll_crossterm_without_gvl(
+    ruby: &magnus::Ruby,
+    timeout: Option<std::time::Duration>,
+) -> Result<Value, Error> {
+    let mut data = PollData {
+        timeout,
+        result: PollResult::NoEvent,
+    };
+
+    // SAFETY: `data` is a valid stack-local `PollData` whose lifetime
+    // spans this entire call. `poll_without_gvl` only reads/writes
+    // through the pointer while `rb_thread_call_without_gvl` blocks,
+    // and we don't access `data` again until that function returns.
+    unsafe {
+        rb_thread_call_without_gvl(
+            Some(poll_without_gvl),
+            (&raw mut data).cast::<c_void>(),
+            None,
+            std::ptr::null_mut(),
+        );
+    }
+
+    // GVL is now re-held — safe to create Ruby objects.
+    match data.result {
+        PollResult::Event(event) => handle_crossterm_event(event),
+        PollResult::NoEvent => Ok(ruby.qnil().into_value_with(ruby)),
+        PollResult::Error(msg) => Err(Error::new(ruby.exception_runtime_error(), msg)),
+    }
+}
+
 pub fn poll_event(ruby: &magnus::Ruby, timeout_val: Option<f64>) -> Result<Value, Error> {
     let event = EVENT_QUEUE.with(|q| {
         let mut queue = q.borrow_mut();
@@ -334,24 +422,8 @@ pub fn poll_event(ruby: &magnus::Ruby, timeout_val: Option<f64>) -> Result<Value
         return Ok(ruby.qnil().into_value_with(ruby));
     }
 
-    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_crossterm_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_crossterm_event(event)
-    }
+    let timeout = timeout_val.map(std::time::Duration::from_secs_f64);
+    poll_crossterm_without_gvl(ruby, timeout)
 }
 
 fn handle_test_event(event: TestEvent) -> Result<Value, Error> {
@@ -559,3 +631,70 @@ fn handle_focus_event(event_type: &str) -> Result<Value, Error> {
     hash.aset(ruby.to_symbol("type"), ruby.to_symbol(event_type))?;
     Ok(hash.into_value_with(&ruby))
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn poll_data_defaults_to_no_event() {
+        let data = PollData {
+            timeout: Some(std::time::Duration::from_millis(0)),
+            result: PollResult::NoEvent,
+        };
+        assert!(matches!(data.result, PollResult::NoEvent));
+    }
+
+    #[test]
+    fn poll_data_accepts_none_timeout_for_indefinite_blocking() {
+        let data = PollData {
+            timeout: None,
+            result: PollResult::NoEvent,
+        };
+        assert!(data.timeout.is_none());
+    }
+
+    #[test]
+    fn poll_result_error_preserves_message() {
+        let result = PollResult::Error("connection reset".to_string());
+        match result {
+            PollResult::Error(msg) => assert_eq!(msg, "connection reset"),
+            _ => panic!("Expected PollResult::Error"),
+        }
+    }
+
+    #[test]
+    fn poll_result_event_wraps_crossterm_event() {
+        let key_event =
+            ratatui::crossterm::event::Event::Key(ratatui::crossterm::event::KeyEvent::new(
+                ratatui::crossterm::event::KeyCode::Char('q'),
+                ratatui::crossterm::event::KeyModifiers::empty(),
+            ));
+        let result = PollResult::Event(key_event.clone());
+        match result {
+            PollResult::Event(e) => assert_eq!(format!("{e:?}"), format!("{key_event:?}")),
+            _ => panic!("Expected PollResult::Event"),
+        }
+    }
+
+    #[test]
+    fn poll_without_gvl_returns_no_event_on_zero_timeout() {
+        // With a zero-duration timeout, poll returns immediately with no event.
+        // In headless environments (CI), crossterm may return an Error because
+        // there is no terminal to read from — that's also a valid outcome.
+        let mut data = PollData {
+            timeout: Some(std::time::Duration::from_millis(0)),
+            result: PollResult::Error("sentinel — should be overwritten".to_string()),
+        };
+
+        poll_without_gvl(&mut data as *mut PollData as *mut c_void);
+
+        // The callback must have overwritten the sentinel value.
+        match &data.result {
+            PollResult::Error(msg) if msg == "sentinel — should be overwritten" => {
+                panic!("poll_without_gvl did not write to data.result")
+            }
+            _ => {} // NoEvent, Event, or a *different* Error are all fine.
+        }
+    }
+}

data/lib/ratatui_ruby/test_helper/snapshot.rb

@@ -99,7 +99,62 @@ module RatatuiRuby
     #--
     # SPDX-SnippetEnd
     #++
+    #
+    # === Class-Wide Normalization
+    #
+    # When every test in a class faces the same dynamic content, override
+    # <tt>normalize_snapshots</tt> instead of repeating the block. Return a callable
+    # (or Array of callables) that transforms lines. The hook runs before any per-call
+    # block, so the two compose naturally. See <tt>normalize_snapshots</tt> for details.
     module Snapshot
+      # Override this method to normalize all snapshots in a test class.
+      #
+      # Snapshot assertions compare screen content against stored files. Dynamic content
+      # (timestamps, temp paths, random IDs) breaks those comparisons. Passing a normalization
+      # block to each assertion fixes one test but creates duplication when every test in a
+      # class faces the same dynamic content.
+      #
+      # Override <tt>normalize_snapshots</tt> in your test class to define class-wide
+      # normalization. Accept an Array of Strings (lines) and return the transformed Array.
+      #
+      # The hook runs before any per-call normalization block, so the two compose naturally:
+      # the hook handles class-wide concerns and the block handles one-off masking.
+      #
+      # Returns <tt>lines</tt> unchanged by default (no normalization).
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   class TestFileExplorer < Minitest::Test
+      #     include RatatuiRuby::TestHelper
+      #
+      #     private def normalize_snapshots(lines)
+      #       lines.map { |l| l.gsub(Dir.pwd, "STABLE_PATH") }
+      #     end
+      #
+      #     def test_initial_render
+      #       # normalize_snapshots runs automatically — no block needed
+      #       assert_snapshots("initial_render")
+      #     end
+      #
+      #     def test_after_scroll
+      #       # Per-call block composes with the hook (hook runs first)
+      #       assert_snapshots("after_scroll") do |lines|
+      #         lines.map { |l| l.gsub(/\d{2}:\d{2}/, "XX:XX") }
+      #       end
+      #     end
+      #   end
+      #
+      #--
+      # SPDX-SnippetEnd
+      #++
+      private def normalize_snapshots(lines)
+        lines
+      end
       ##
       # Asserts that the current screen content matches a stored plain text snapshot.
       #
@@ -181,7 +236,7 @@ module RatatuiRuby
       # Ensure your render logic is deterministic by seeding random number generators and stubbing
       # time where necessary.
       def assert_screen_matches(expected, msg = nil)
-        actual_lines = buffer_content
+        actual_lines = normalize_snapshots(buffer_content)
 
         if block_given?
           actual_lines = yield(actual_lines)
@@ -203,9 +258,6 @@ module RatatuiRuby
 
               # Write with explicit mode to ensure clean write
               File.write(snapshot_path, content_to_write, mode: "w")
-
-              # Flush filesystem buffers to ensure durability
-              File.open(snapshot_path, "r", &:fsync) if File.exist?(snapshot_path)
             rescue => e
               warn "Failed to write snapshot #{snapshot_path}: #{e.message}"
               raise
@@ -269,12 +321,11 @@ module RatatuiRuby
 
         actual_content = _render_buffer_with_ansi
 
+        lines = normalize_snapshots(actual_content.split("\n"))
         if block_given?
-          lines = actual_content.split("\n")
-          # Yield lines to user block for modification (e.g. masking IDs/Times)
           lines = yield(lines)
-          actual_content = "#{lines.join("\n")}\n"
         end
+        actual_content = "#{lines.join("\n")}\n"
 
         update_snapshots = ENV["UPDATE_SNAPSHOTS"] == "1" || ENV["UPDATE_SNAPSHOTS"] == "true"
 
@@ -287,9 +338,6 @@ module RatatuiRuby
 
             # Write with explicit mode to ensure clean write
             File.write(snapshot_path, actual_content, mode: "w")
-
-            # Flush filesystem buffers to ensure durability
-            File.open(snapshot_path, "r", &:fsync) if File.exist?(snapshot_path)
           rescue => e
             warn "Failed to write rich snapshot #{snapshot_path}: #{e.message}"
             raise

data/lib/ratatui_ruby/test_helper/subprocess_timeout.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require "timeout"
+
+module RatatuiRuby
+  module TestHelper
+    ##
+    # Portable subprocess timeout helper.
+    module SubprocessTimeout
+      private def popen_with_timeout(env, cmd, timeout: 2)
+        output = +""
+        IO.popen(env, cmd, err: [:child, :out]) do |io|
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+          loop do
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            break if remaining <= 0
+            break unless io.wait_readable(remaining)
+
+            chunk = io.read_nonblock(4096, exception: false)
+            break if chunk.nil? || chunk == :wait_readable
+
+            output << chunk
+          end
+          Process.kill("KILL", io.pid) rescue nil # rubocop:disable Style/RescueModifier
+        end
+        output.strip
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/test_helper.rb

@@ -12,6 +12,7 @@ require_relative "test_helper/event_injection"
 require_relative "test_helper/style_assertions"
 require_relative "test_helper/test_doubles"
 require_relative "test_helper/global_state"
+require_relative "test_helper/subprocess_timeout"
 
 module RatatuiRuby
   ##
@@ -109,5 +110,6 @@ module RatatuiRuby
     include StyleAssertions
     include TestDoubles
     include GlobalState
+    include SubprocessTimeout
   end
 end

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.3.0"
+  VERSION = "1.4.0"
 end