ratatui_ruby 0.7.4 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8c89b519ce8bf221f4f21ad0b1032e2d7e11214e9df530fc37cdd456f908889
-  data.tar.gz: f188fbed117ef8758f2dcdca0c56b837e424de84fea2a2a9ee4027685ccad41e
+  metadata.gz: 1205d0ba5eb21c14b6639926e910764600c34a21f79d39a9e471c2e4902999b4
+  data.tar.gz: 3ca7b062a7320aadc1a0296b9d529adbbd449d17d1caf144d535e02b325f15c5
 SHA512:
-  metadata.gz: 9955835cd59fd2c8e13f3d0f8f9b284b140f1887d529fb1e1bbb4b39941a37259fff0159791a0fac87c105797ba0dc31b17ddfe0582a71a4efe7461e1c6a0a12
-  data.tar.gz: ff2b0011104b3edf8dd20ee7dcce5c622772f2d9820e70d66f27738aee20a71f3eff29129a1c9feb4e6c81beeab75d724cc7b7fbe3214f28430458861a15206a
+  metadata.gz: 6311c2fabd0e5e379e41f5dc11a10e41729d5c6e3ef825706b757fb4cd35ce716e5f471a80228a5bc6120af2c6926969b5657209398d1029cf47b745fe8bc16f
+  data.tar.gz: 643c1c4b1782131bebac43bed1b3e61af125d560ea88a16018bb76754b71aa31a32fe8438f71364f48cbd55e028a2821ff545468d9b61973f4c22b7c6d53c614

data/.builds/ruby-3.2.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.7.4.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.8.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-0.7.4.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.8.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-0.7.4.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.8.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-0.7.4.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.8.0.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/CHANGELOG.md

@@ -18,6 +18,21 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Removed
 
+## [0.8.0] - 2026-01-05
+
+### Added
+- **Output Guard**: `RatatuiRuby.guard_io { }` temporarily replaces `$stdout` and `$stderr` with a null sink, preventing screen corruption from chatty gems. Active when `terminal_active?` is true; warns if called outside a session (to catch mistakes); silent no-op in headless mode.
+- **Headless Mode**: `RatatuiRuby.headless!` enables batch/CLI mode for apps with `--no-tui` flags. When headless, `guard_io` becomes a silent no-op and `init_terminal`/`run` raise `Error::Invariant`. This allows the same code to work in both TUI and non-TUI modes.
+- **Terminal Safety Hooks**: `at_exit` and `Signal.trap` handlers for `INT` and `TERM` automatically restore the terminal if a session is active on unexpected exit. This prevents leaving the terminal in raw mode after Ctrl+C or process termination.
+
+### Changed
+
+- **Double `init_terminal` Now Raises `Error::Invariant` (Breaking)** Calling `init_terminal`, `init_test_terminal`, or `run` while a TUI session is already active now raises `Error::Invariant`. Previously, this was undefined but silently "working" behavior that could cause terminal state corruption. If your code intentionally double-inits, call `restore_terminal` first.
+
+### Fixed
+
+### Removed
+
 ## [0.7.4] - 2026-01-05
 
 ### Added
@@ -26,6 +41,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - **Deferred Warnings During TUI Sessions**: Experimental feature warnings (like `Paragraph#line_count`) are now automatically queued during active TUI sessions and flushed to stderr after `restore_terminal`. This prevents warnings from corrupting the TUI display. See `doc/troubleshooting/tui_output.md` for details on handling terminal output during TUI sessions.
 - **Session State Tracking**: `RatatuiRuby.terminal_active?` indicates whether a TUI session is active. Calling `init_terminal` or `init_test_terminal` while a session is already active now raises `Error::Invariant`.
 - **Error::Invariant**: New error class for state invariant violations (e.g., double-init). Distinct from `Error::Safety` (lifetime violations) and `Error::Terminal` (operational I/O failures).
+
 ### Changed
 
 ### Fixed
@@ -425,6 +441,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - **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
+[0.8.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.8.0
 [0.7.4]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.7.4
 [0.7.3]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.7.3
 [0.7.2]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.7.2

data/doc/getting_started/quickstart.md

@@ -17,7 +17,7 @@ See [Installation in the README](../README.md#installation) for setup instructio
 
 Here is a "Hello World" application that demonstrates the core lifecycle of a **ratatui_ruby** app.
 
-<!-- SYNC:START:../examples/verify_quickstart_lifecycle/app.rb:main -->
+<!-- SYNC:START:examples/verify_quickstart_lifecycle/app.rb:main -->
 ```ruby
 # 1. Initialize the terminal
 RatatuiRuby.init_terminal
@@ -51,9 +51,15 @@ begin
     else
       nil
     end
+
+    # 5. Guard against accidental output (optional but recommended)
+    # Wrap any code that might puts/warn to prevent screen corruption.
+    RatatuiRuby.guard_io do
+      # SomeChattyGem.do_something
+    end
   end
 ensure
-  # 5. Restore the terminal to its original state
+  # 6. Restore the terminal to its original state
   RatatuiRuby.restore_terminal
 end
 ```
@@ -67,13 +73,14 @@ end
 2.  **Immediate Mode UI**: On every iteration, describe your UI by creating `Data` objects (e.g., `Paragraph`, `Block`).
 3.  **`RatatuiRuby.draw { |frame| ... }`**: The block receives a `Frame` object as a canvas. Render widgets onto specific areas. Nothing is drawn until the block finishes, ensuring flicker-free updates.
 4.  **`RatatuiRuby.poll_event`**: Returns a typed `Event` object with predicates like `key?`, `mouse?`, `resize?`, etc. Returns `RatatuiRuby::Event::None` if no events are pending. Use predicates to check event type without pattern matching.
-5.  **`RatatuiRuby.restore_terminal`**: Essential for leaving raw mode and returning to the shell. Always wrap your loop in `begin...ensure` to guarantee this runs.
+5.  **`RatatuiRuby.guard_io { }`**: Wraps code that might write to stdout/stderr (e.g., chatty gems). Output is swallowed to prevent screen corruption. Optional but recommended for production apps.
+6.  **`RatatuiRuby.restore_terminal`**: Essential for leaving raw mode and returning to the shell. Always wrap your loop in `begin...ensure` to guarantee this runs.
 
 ### Simplified API
 
 You can simplify your code by using `RatatuiRuby.run`. This method handles the terminal lifecycle for you, yielding a `TUI` object with factory methods for widgets.
 
-<!-- SYNC:START:../examples/verify_quickstart_dsl/app.rb:main -->
+<!-- SYNC:START:examples/verify_quickstart_dsl/app.rb:main -->
 ```ruby
 # 1. Initialize the terminal, start the run loop, and ensure the terminal is restored.
 RatatuiRuby.run do |tui|
@@ -121,7 +128,7 @@ For a deeper dive into the available application architectures (Manual vs Manage
 
 Real-world applications often need to split the screen into multiple areas. `RatatuiRuby::Layout` lets you do this easily.
 
-<!-- SYNC:START:../examples/verify_quickstart_layout/app.rb:main -->
+<!-- SYNC:START:examples/verify_quickstart_layout/app.rb:main -->
 ```ruby
 loop do
   tui.draw do |frame|
@@ -255,6 +262,7 @@ Now that you've seen what **ratatui_ruby** can do:
 
 - **Deep dive**: Read the [Application Architecture](../concepts/application_architecture.md) guide for scaling patterns
 - **Test your TUI**: See the [Testing Guide](../concepts/application_testing.md) for snapshot and style assertions
+- **Avoid common mistakes**: See [Terminal Output During TUI Sessions](../troubleshooting/tui_output.md) to prevent screen corruption
 - **Explore the API**: Browse the [full RDoc documentation](../index.md)
 - **Learn the philosophy**: Read [Why RatatuiRuby?](./why.md) for comparisons and design decisions
 - **Get help**: Join the [discussion mailing list](https://lists.sr.ht/~kerrick/ratatui_ruby-discuss)

data/doc/troubleshooting/tui_output.md

@@ -9,7 +9,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 
 Writing to stdout or stderr during a TUI session **corrupts the display**.
 
-When your application is running inside `RatatuiRuby.run`, the terminal is in "raw mode" and RatatuiRuby has taken control of the display buffer. Any output via `puts`, `warn`, `p`, `print`, or direct writes to `STDOUT`/`STDERR` will:
+When your application is running inside `RatatuiRuby.run`, the terminal is in "raw mode" and RatatuiRuby has taken control of the display buffer. Any output via `puts`, `warn`, `p`, `print`, or direct writes to `$stdout`/`$stderr` will:
 
 1. **Corrupt the screen layout** - Characters appear in random positions
 2. **Mix with TUI output** - Text interleaves with your widgets unpredictably
@@ -24,6 +24,21 @@ In raw mode:
 
 ## Safe Patterns
 
+### Use `guard_io` to swallow output from gems
+
+If you're using a gem that might write to stdout/stderr, wrap its calls:
+
+```ruby
+RatatuiRuby.run do |tui|
+  RatatuiRuby.guard_io do
+    SomeChattyGem.do_something  # Any puts/warn calls are swallowed
+  end
+
+  # Outside guard_io, you can still debug intentionally:
+  # Object::STDERR.puts "debug: something"  # Escape hatch (corrupts display!)
+end
+```
+
 ### Defer output until after the TUI exits
 
 ```ruby
@@ -40,15 +55,21 @@ end
 messages.each { |msg| puts msg }
 ```
 
-### Use debug logging to a file
+### Use Logger to write to a file
+
+The `Logger` class from Ruby's standard library is the idiomatic solution:
 
 ```ruby
-DEBUG_LOG = File.open("/tmp/my_app_debug.log", "a")
+require "logger"
+require "tmpdir"
+
+LOG = Logger.new(File.join(Dir.tmpdir, "my_app.log"))
+LOG.level = Logger::DEBUG
 
 RatatuiRuby.run do |tui|
-  DEBUG_LOG.puts "Debug: something happened"
-  DEBUG_LOG.flush
-  
+  LOG.info "Application started"
+  LOG.debug "Processing event: #{event.inspect}"
+
   # ... TUI logic ...
 end
 ```
@@ -74,3 +95,61 @@ end
 RatatuiRuby automatically defers its own warnings (like experimental feature notices) during TUI sessions. They are queued and printed after `restore_terminal` is called.
 
 You don't need to do anything special for library warnings—they're handled automatically.
+
+## Bypassing guard_io
+
+If you need to write to stdout/stderr even when `guard_io` is active (e.g., for [pipeline integration](#headless-mode-batchpipelinecli) or IPC), use the original IO constants:
+
+```ruby
+RatatuiRuby.guard_io do
+  SomeChattyGem.do_something  # This is swallowed
+
+  # But this gets through:
+  Object::STDOUT.puts "structured output for downstream tools"
+end
+```
+
+This works regardless of whether `guard_io` is active. During a TUI session, the display will be corrupted—but the output will reach its destination.
+
+## Headless Mode (Batch/Pipeline/CLI)
+
+If your app supports both TUI and non-TUI modes (e.g., `my_app --no-tui`), call `headless!` at startup to silence `guard_io` warnings:
+
+```ruby
+if ARGV.include?("--no-tui")
+  RatatuiRuby.headless!
+  # guard_io calls are now silent no-ops
+  process_batch_work
+else
+  RatatuiRuby.run do |tui|
+    # TUI mode - guard_io works normally
+  end
+end
+```
+
+When headless, `guard_io` becomes a no-op (output flows normally), and calling `run` or `init_terminal` raises an error.
+
+## Temporarily Exiting TUI Mode
+
+Some apps need to temporarily leave TUI mode for user interaction—like lazygit does when opening an external editor for commit messages. Use `restore_terminal` and `init_terminal`:
+
+```ruby
+RatatuiRuby.run do |tui|
+  # ... TUI is active ...
+  
+  if user_wants_external_editor
+    RatatuiRuby.restore_terminal
+    
+    # Now in normal terminal mode
+    system("$EDITOR", filename)
+    puts "Press Enter to return to the TUI..."
+    gets
+    
+    RatatuiRuby.init_terminal
+  end
+  
+  # ... TUI is active again ...
+end
+```
+
+This pattern lets you hand control back to the user or spawn external processes that need normal terminal access.

data/examples/verify_quickstart_lifecycle/README.md

@@ -45,9 +45,15 @@ begin
     else
       nil
     end
+
+    # 5. Guard against accidental output (optional but recommended)
+    # Wrap any code that might puts/warn to prevent screen corruption.
+    RatatuiRuby.guard_io do
+      # SomeChattyGem.do_something
+    end
   end
 ensure
-  # 5. Restore the terminal to its original state
+  # 6. Restore the terminal to its original state
   RatatuiRuby.restore_terminal
 end
 ```

data/examples/verify_quickstart_lifecycle/app.rb

@@ -44,9 +44,15 @@ class VerifyQuickstartLifecycle
         else
           nil
         end
+
+        # 5. Guard against accidental output (optional but recommended)
+        # Wrap any code that might puts/warn to prevent screen corruption.
+        RatatuiRuby.guard_io do
+          # SomeChattyGem.do_something
+        end
       end
     ensure
-      # 5. Restore the terminal to its original state
+      # 6. Restore the terminal to its original state
       RatatuiRuby.restore_terminal
     end
     # [SYNC:END:main]

data/ext/ratatui_ruby/Cargo.lock

@@ -1012,7 +1012,7 @@ dependencies = [
 
 [[package]]
 name = "ratatui_ruby"
-version = "0.7.4"
+version = "0.8.0"
 dependencies = [
  "bumpalo",
  "lazy_static",

data/ext/ratatui_ruby/Cargo.toml

@@ -3,7 +3,7 @@
 
 [package]
 name = "ratatui_ruby"
-version = "0.7.4"
+version = "0.8.0"
 edition = "2021"
 
 [lib]

data/lib/ratatui_ruby/output_guard.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  ##
+  # Output protection for TUI sessions and batch/CLI mode.
+  #
+  # This module provides mechanisms to prevent accidental output to stdout/stderr
+  # during TUI sessions and to support headless (batch/CLI) mode for applications
+  # that can run with or without a TUI.
+  #
+  # @see guard_io
+  # @see headless!
+  module OutputGuard
+    # A null IO object that swallows all output.
+    #
+    # Used by {guard_io} to temporarily replace $stdout and $stderr.
+    # Implements method_missing to accept any IO method and discard output.
+    #
+    # Returns self for method chaining (e.g., puts.flush).
+    class NullIO
+      # Accepts any method call and returns self, discarding all output.
+      def method_missing(name, *args, &block)
+        self
+      end
+
+      # Reports that all methods are supported.
+      def respond_to_missing?(name, include_private = false)
+        true
+      end
+    end
+
+    ##
+    # Whether headless (batch/pipeline/CLI) mode is enabled.
+    #
+    # When headless mode is active:
+    # - {guard_io} becomes a silent no-op (output is not swallowed)
+    # - {init_terminal} and {run} raise {Error::Invariant}
+    #
+    # Use this when your app has a `--no-tui` or `--batch` flag and you want
+    # the same code to work in both TUI and non-TUI modes.
+    #
+    # @see headless!
+    def is_headless?
+      @headless_mode
+    end
+
+    ##
+    # Enables headless (batch/CLI) mode.
+    #
+    # Call this at app startup when running in batch/CLI mode (e.g., `--no-tui`).
+    # This tells RatatuiRuby that you intentionally don't want a TUI session.
+    #
+    # When headless mode is active:
+    # - {guard_io} becomes a silent no-op (output flows normally)
+    # - {init_terminal} and {run} raise {Error::Invariant}
+    #
+    # Headless mode and TUI sessions are mutually exclusive. Calling this
+    # while a TUI session is active raises {Error::Invariant}.
+    #
+    # === Why there is no exit_headless!
+    #
+    # Headless mode is a startup-time decision for the entire app run.
+    # If you need to temporarily exit TUI mode for user interaction
+    # (like lazygit does when editing a commit message), use
+    # {restore_terminal} and {init_terminal} instead:
+    #
+    #   RatatuiRuby.restore_terminal
+    #   puts "Press enter to continue..."
+    #   gets
+    #   RatatuiRuby.init_terminal
+    #
+    # === Example
+    #
+    #   if ARGV.include?("--no-tui")
+    #     RatatuiRuby.headless!
+    #     process_batch_work  # guard_io calls are silent no-ops
+    #   else
+    #     RatatuiRuby.run do |tui|  # This branch only runs in TUI mode
+    #       # ... TUI code ...
+    #     end
+    #   end
+    #
+    # Note: Calling {run} or {init_terminal} after {headless!} raises
+    # {Error::Invariant}. The block is never executed.
+    #
+    # @raise [Error::Invariant] if a TUI session is already active
+    # @see is_headless?
+    # @see restore_terminal
+    def headless!
+      if @tui_session_active
+        raise Error::Invariant, "Cannot enable headless mode: TUI session already active"
+      end
+      @headless_mode = true
+    end
+
+    ##
+    # Guards a block from stdout/stderr output.
+    #
+    # During a TUI session, writes to $stdout or $stderr corrupt the display.
+    # Wrap code that might produce output (e.g., chatty gems) in this block.
+    #
+    # This temporarily replaces $stdout and $stderr with a {NullIO} object
+    # that discards all output. The original streams are restored when the
+    # block exits, even if an exception occurs.
+    #
+    # === Behavior by mode
+    #
+    # - **TUI session active**: Output is swallowed (guarded)
+    # - **Headless mode**: Silent no-op (output flows normally)
+    # - **Neither**: Warns and yields (catches potential mistakes)
+    #
+    # === Example
+    #
+    #   RatatuiRuby.run do |tui|
+    #     RatatuiRuby.guard_io do
+    #       SomeChattyGem.do_something  # Any puts/warn calls are swallowed
+    #     end
+    #   end
+    #
+    # @see headless!
+    def guard_io
+      # TUI active: guard the output
+      if terminal_active?
+        $stdout = NullIO.new
+        $stderr = NullIO.new
+        begin
+          return yield
+        ensure
+          $stdout = Object::STDOUT
+          $stderr = Object::STDERR
+        end
+      end
+
+      # Headless mode: silent no-op
+      return yield if is_headless?
+
+      # Neither: warn about potential mistake
+      warn "guard_io called outside TUI session. If this is intentional (batch/CLI mode), call RatatuiRuby.headless! at startup to silence this warning."
+      yield
+    end
+  end
+end

data/lib/ratatui_ruby/terminal_lifecycle.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  ##
+  # Terminal lifecycle management for TUI sessions.
+  #
+  # This module provides methods to initialize, restore, and manage the terminal
+  # state for TUI applications. It handles raw mode, alternate screen, and ensures
+  # proper cleanup on exit.
+  #
+  # @see init_terminal
+  # @see restore_terminal
+  # @see run
+  module TerminalLifecycle
+    ##
+    # Whether a TUI session is currently active.
+    #
+    # Writing to stdout/stderr during a TUI session corrupts the display.
+    # Use this to defer logging, warnings, or debug output until
+    # after the session ends.
+    #
+    # === Example
+    #
+    #   def log(message)
+    #     if RatatuiRuby.terminal_active?
+    #       @deferred_logs << message
+    #     else
+    #       puts message
+    #     end
+    #   end
+    def terminal_active?
+      @tui_session_active
+    end
+
+    ##
+    # Initializes the terminal for TUI mode.
+    # Enters alternate screen and enables raw mode.
+    #
+    # In headless mode ({headless!}), this method raises {Error::Invariant}.
+    # Use headless mode for batch/CLI apps.
+    #
+    # [focus_events] whether to enable focus gain/loss events (default: true).
+    # [bracketed_paste] whether to enable bracketed paste mode (default: true).
+    #
+    # @raise [Error::Invariant] if headless mode is enabled or a session is already active
+    # @see headless!
+    def init_terminal(focus_events: true, bracketed_paste: true)
+      if @headless_mode
+        raise Error::Invariant, "Cannot initialize terminal: headless mode is enabled"
+      end
+      if @tui_session_active
+        raise Error::Invariant, "Cannot initialize terminal: TUI session already active"
+      end
+      @tui_session_active = true
+      _init_terminal(focus_events, bracketed_paste)
+    end
+
+    ##
+    # Initializes a test terminal for unit testing.
+    # Sets session active state like init_terminal.
+    #
+    # [width] Integer width of the test terminal.
+    # [height] Integer height of the test terminal.
+    #
+    # @raise [Error::Invariant] if headless mode is enabled or a session is already active
+    def init_test_terminal(width, height)
+      if @headless_mode
+        raise Error::Invariant, "Cannot initialize terminal: headless mode is enabled"
+      end
+      if @tui_session_active
+        raise Error::Invariant, "Cannot initialize terminal: TUI session already active"
+      end
+      @tui_session_active = true
+      _init_test_terminal(width, height)
+    end
+
+    ##
+    # Restores the terminal to its original state.
+    # Leaves alternate screen and disables raw mode.
+    # Also flushes any deferred warnings that were queued during the session.
+    #
+    # In headless mode ({headless!}), this method is a silent no-op since
+    # no terminal was ever initialized.
+    #
+    # @see headless!
+    def restore_terminal
+      return if @headless_mode
+
+      _restore_terminal
+    ensure
+      @tui_session_active = false
+      flush_warnings
+    end
+
+    ##
+    # Starts the TUI application lifecycle.
+    #
+    # Managing generic setup/teardown (raw mode, alternate screen) manually is error-prone.
+    # If your app crashes, the terminal might be left in a broken state.
+    #
+    # This method handles the safety net. It initializes the terminal, yields a {TUI},
+    # and ensures the terminal state is restored even if exceptions occur.
+    #
+    # In headless mode ({headless!}), this method raises {Error::Invariant} immediately
+    # and the block is never executed. Use headless mode for batch/CLI apps.
+    #
+    # === Example
+    #
+    #   RatatuiRuby.run(focus_events: false) do |tui|
+    #     tui.draw(tui.paragraph(text: "Hi"))
+    #     sleep 1
+    #   end
+    #
+    # @raise [Error::Invariant] if headless mode is enabled
+    # @see headless!
+    def run(focus_events: true, bracketed_paste: true)
+      init_terminal(focus_events:, bracketed_paste:)
+      yield TUI.new
+    ensure
+      restore_terminal
+    end
+  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 = "0.7.4"
+  VERSION = "0.8.0"
 end

data/lib/ratatui_ruby.rb

@@ -7,7 +7,7 @@
 
 require_relative "ratatui_ruby/version"
 
-# New modularized structure (mirrors ratatui Rust crate)
+# Core types (mirrors ratatui Rust crate)
 require_relative "ratatui_ruby/layout"   # Layout::Rect, Layout::Constraint, Layout::Layout
 require_relative "ratatui_ruby/style"    # Style::Style
 require_relative "ratatui_ruby/widgets"  # Widgets::Block, Widgets::Paragraph, etc.
@@ -24,6 +24,10 @@ require_relative "ratatui_ruby/list_state"
 require_relative "ratatui_ruby/table_state"
 require_relative "ratatui_ruby/scrollbar_state"
 
+# Behavioral mixins
+require_relative "ratatui_ruby/output_guard"
+require_relative "ratatui_ruby/terminal_lifecycle"
+
 # TUI facade (for external instantiation and caching)
 require_relative "ratatui_ruby/tui"
 
@@ -110,44 +114,18 @@ module RatatuiRuby
     class Invariant < Error; end
   end
 
-  ##
-  # Initializes the terminal for TUI mode.
-  # Enters alternate screen and enables raw mode.
-  #
-  # [focus_events] whether to enable focus gain/loss events (default: true).
-  # [bracketed_paste] whether to enable bracketed paste mode (default: true).
-  def self.init_terminal(focus_events: true, bracketed_paste: true)
-    if @tui_session_active
-      raise Error::Invariant, "Cannot initialize terminal: TUI session already active"
-    end
-    @tui_session_active = true
-    _init_terminal(focus_events, bracketed_paste)
-  end
+  # Mix in terminal lifecycle and output protection methods
+  extend OutputGuard
+  extend TerminalLifecycle
+
+  # Re-export NullIO at module root for backward compatibility
+  NullIO = OutputGuard::NullIO
 
   @experimental_warnings = true
   @tui_session_active = false
+  @headless_mode = false
   @deferred_warnings = []
 
-  ##
-  # Whether a TUI session is currently active.
-  #
-  # Writing to stdout/stderr during a TUI session corrupts the display.
-  # Use this to defer logging, warnings, or debug output until
-  # after the session ends.
-  #
-  # === Example
-  #
-  #   def log(message)
-  #     if RatatuiRuby.terminal_active?
-  #       @deferred_logs << message
-  #     else
-  #       puts message
-  #     end
-  #   end
-  def self.terminal_active?
-    @tui_session_active
-  end
-
   class << self
     ##
     # :attr_accessor: experimental_warnings
@@ -165,17 +143,6 @@ module RatatuiRuby
     end
   end
 
-  ##
-  # Restores the terminal to its original state.
-  # Leaves alternate screen and disables raw mode.
-  # Also flushes any deferred warnings that were queued during the session.
-  def self.restore_terminal
-    _restore_terminal
-  ensure
-    @tui_session_active = false
-    flush_warnings
-  end
-
   ##
   # :singleton-method: inject_test_event
   # Injects a mock event into the event queue for testing purposes.
@@ -207,20 +174,6 @@ module RatatuiRuby
     @warned_features[feature_name] = true
   end
 
-  ##
-  # Initializes a test terminal for unit testing.
-  # Sets session active state like init_terminal.
-  #
-  # [width] Integer width of the test terminal.
-  # [height] Integer height of the test terminal.
-  def self.init_test_terminal(width, height)
-    if @tui_session_active
-      raise Error::Invariant, "Cannot initialize terminal: TUI session already active"
-    end
-    @tui_session_active = true
-    _init_test_terminal(width, height)
-  end
-
   # (Native methods implemented in Rust)
   private_class_method :_init_terminal, :_restore_terminal, :_init_test_terminal
 
@@ -328,26 +281,6 @@ module RatatuiRuby
   # (Native method _poll_event implemented in Rust)
   private_class_method :_poll_event
 
-  ##
-  # Starts the TUI application lifecycle.
-  #
-  # Managing generic setup/teardown (raw mode, alternate screen) manualy is error-prone. If your app crashes, the terminal might be left in a broken state.
-  #
-  # This method handles the safety net. It initializes the terminal, yields a {TUI}, and ensures the terminal state is restored even if exceptions occur.
-  #
-  # === Example
-  #
-  #   RatatuiRuby.run(focus_events: false) do |tui|
-  #     tui.draw(tui.paragraph(text: "Hi"))
-  #     sleep 1
-  #   end
-  def self.run(focus_events: true, bracketed_paste: true)
-    init_terminal(focus_events:, bracketed_paste:)
-    yield TUI.new
-  ensure
-    restore_terminal
-  end
-
   ##
   # Inspects the terminal buffer at specific coordinates.
   #
@@ -380,4 +313,18 @@ module RatatuiRuby
 
   # Hide native Layout._split helper
   Layout::Layout.singleton_class.__send__(:private, :_split)
+
+  # --- Terminal Safety Hooks ---
+  # These ensure the terminal is restored even on unexpected exits.
+
+  at_exit do
+    restore_terminal if terminal_active?
+  end
+
+  %i[INT TERM].each do |signal|
+    trap(signal) do
+      restore_terminal if terminal_active?
+      exit(128 + Signal.list[signal.to_s])
+    end
+  end
 end

data/tasks/autodoc/examples.rb

@@ -12,7 +12,7 @@ module Autodoc
     end
 
     def sync
-      Dir.glob("{README.md,doc/*.md,examples/*/README.md}").each do |readme_path|
+      Dir.glob("{README.md,doc/**/*.md,examples/*/README.md}").each do |readme_path|
         sync_readme(readme_path)
       end
     end
@@ -24,7 +24,13 @@ module Autodoc
       new_content = content.gsub(/<!-- SYNC:START:([^ ]+) -->.*?<!-- SYNC:END -->/m) do
         marker_info = $1
         source_rel_path, segment_id = marker_info.split(":")
-        source_path = File.join(dir, source_rel_path)
+
+        # Support both repo-root-relative paths (no leading ./) and file-relative paths
+        source_path = if source_rel_path.start_with?("./", "../")
+          File.join(dir, source_rel_path)
+        else
+          source_rel_path # Already relative to repo root
+        end
 
         unless File.exist?(source_path)
           warn "Warning: Source file not found: #{source_path}"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ratatui_ruby
 version: !ruby/object:Gem::Version
-  version: 0.7.4
+  version: 0.8.0
 platform: ruby
 authors:
 - Kerrick Long
@@ -317,6 +317,7 @@ files:
 - lib/ratatui_ruby/layout/layout.rb
 - lib/ratatui_ruby/layout/rect.rb
 - lib/ratatui_ruby/list_state.rb
+- lib/ratatui_ruby/output_guard.rb
 - lib/ratatui_ruby/schema/bar_chart.rb
 - lib/ratatui_ruby/schema/bar_chart/bar.rb
 - lib/ratatui_ruby/schema/bar_chart/bar_group.rb
@@ -351,6 +352,7 @@ files:
 - lib/ratatui_ruby/style.rb
 - lib/ratatui_ruby/style/style.rb
 - lib/ratatui_ruby/table_state.rb
+- lib/ratatui_ruby/terminal_lifecycle.rb
 - lib/ratatui_ruby/test_helper.rb
 - lib/ratatui_ruby/test_helper/event_injection.rb
 - lib/ratatui_ruby/test_helper/snapshot.rb