ratatui_ruby 0.10.1 → 0.10.2

data/lib/ratatui_ruby/terminal/viewport.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  ##
+  # Terminal configuration and viewport settings.
+  #
+  # Your app needs to choose how it occupies the terminal.
+  # Fullscreen apps take over the whole screen and clear on exit.
+  # Inline apps run in a fixed region and persist in scrollback.
+  # Configuring this manually is error-prone.
+  #
+  # This module handles the choice. It defines viewport modes and their parameters.
+  #
+  # @see Terminal::Viewport
+  module Terminal
+    ##
+    # Viewport configuration for terminal initialization.
+    #
+    # Determines how RatatuiRuby interacts with the terminal:
+    # - **Fullscreen**: Uses alternate screen, clears on exit (default)
+    # - **Inline**: Fixed-height region, persists in scrollback after exit
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   # Fullscreen (default behavior)
+    #   RatatuiRuby.run { |tui| ... }
+    #
+    #   # Inline with 8 lines
+    #   RatatuiRuby.run(viewport: :inline, height: 8) { |tui| ... }
+    #--
+    # SPDX-SnippetEnd
+    #++
+    class Viewport < Data.define(:type, :height)
+      ##
+      # Creates a fullscreen viewport (alternate screen).
+      def self.fullscreen
+        new(type: :fullscreen)
+      end
+
+      ##
+      # Creates an inline viewport with the given height.
+      def self.inline(height)
+        new(type: :inline, height:)
+      end
+
+      ##
+      # Creates a new viewport configuration.
+      #
+      # [type] Symbol representing viewport type (:fullscreen or :inline).
+      # [height] Integer height in lines (required for :inline, ignored for :fullscreen).
+      #
+      # Most developers use {.fullscreen} or {.inline} factory methods instead.
+      def initialize(type:, height: nil)
+        super
+      end
+
+      ##
+      # Returns true if this is a fullscreen viewport.
+      def fullscreen?
+        type == :fullscreen
+      end
+
+      ##
+      # Returns true if this is an inline viewport.
+      def inline?
+        type == :inline
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/terminal_lifecycle.rb

@@ -57,15 +57,24 @@ module RatatuiRuby
     #
     # @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)
+    def init_terminal(focus_events: true, bracketed_paste: true, viewport: nil, height: nil)
       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
+
+      # Show A11Y lab prompt before launching TUI (stdout visible now, not after)
+      if Labs.enabled?(:a11y)
+        puts Labs::A11y.startup_message
+        $stdin.gets
+      end
+
       @tui_session_active = true
-      _init_terminal(focus_events, bracketed_paste)
+
+      viewport_obj = resolve_viewport(viewport, height)
+      _init_terminal(focus_events, bracketed_paste, viewport_obj.type.to_s, viewport_obj.height)
     end
 
     ##
@@ -76,7 +85,7 @@ module RatatuiRuby
     # [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)
+    def init_test_terminal(width, height, viewport_type = "fullscreen", viewport_height = nil)
       if @headless_mode
         raise Error::Invariant, "Cannot initialize terminal: headless mode is enabled"
       end
@@ -84,7 +93,7 @@ module RatatuiRuby
         raise Error::Invariant, "Cannot initialize terminal: TUI session already active"
       end
       @tui_session_active = true
-      _init_test_terminal(width, height)
+      _init_test_terminal(width, height, viewport_type, viewport_height)
     end
 
     ##
@@ -135,11 +144,160 @@ module RatatuiRuby
     #++
     # @raise [Error::Invariant] if headless mode is enabled
     # @see headless!
-    def run(focus_events: true, bracketed_paste: true)
-      init_terminal(focus_events:, bracketed_paste:)
+    def run(focus_events: true, bracketed_paste: true, viewport: nil, height: nil)
+      init_terminal(focus_events:, bracketed_paste:, viewport:, height:)
       yield TUI.new
     ensure
       restore_terminal
     end
+
+    ##
+    # Inserts content above an inline viewport into scrollback.
+    #
+    # Your inline TUI runs at the bottom of the terminal. Users scroll back
+    # to see earlier CLI output. You want to add new content to that scrollback
+    # without disrupting the running TUI viewport.
+    #
+    # Calling <tt>draw</tt> only updates the viewport itself. Content drawn there
+    # disappears into scrollback when the viewport moves. You have no way to insert
+    # historical content directly into the scrollback buffer above your running TUI.
+    #
+    # This method inserts content above the viewport. The viewport stays live and interactive.
+    # New content appears above it in scrollback history. If the viewport isn't yet at the
+    # bottom of the screen, it shifts down. Once at the bottom, inserted content scrolls
+    # the scrollback buffer upward.
+    #
+    # Use it to log status updates, progress messages, or diagnostic output while your
+    # inline TUI continues running.
+    #
+    # === Behavior
+    #
+    # The method renders a widget into a temporary buffer of <tt>height</tt> lines,
+    # then inserts that buffer above the viewport. The viewport may shift position
+    # on screen to accommodate the new lines.
+    #
+    # When the viewport has room to move down (not yet at screen bottom):
+    # - Inserted lines appear above the viewport
+    # - The viewport shifts down by <tt>height</tt> lines
+    # - The viewport's visual position changes
+    #
+    # When the viewport is already at the screen bottom:
+    # - Inserted lines push existing scrollback upward
+    # - The viewport stays at the bottom
+    # - The viewport's content may be disturbed by scrolling
+    #
+    # After calling this method, you should call <tt>draw</tt> to redraw the viewport's
+    # content over its new position. The viewport area may have been clobbered by
+    # the insertion or scrolling.
+    #
+    # This method has no effect when called on a fullscreen viewport. Fullscreen
+    # viewports have no scrollback buffer.
+    #
+    # [height] Number of lines to insert (Integer). Must be positive.
+    # [widget] Widget to render into the inserted buffer, or <tt>nil</tt> if using block.
+    # [block] Optional block that returns a widget to render.
+    #
+    # === Examples
+    #
+    # ==== Insert a status line while TUI runs
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   RatatuiRuby.run(viewport: :inline, height: 3) do |tui|
+    #     loop do
+    #       tui.draw { |f| f.render_widget(tui.paragraph(text: "TUI Running"), f.area) }
+    #
+    #       event = tui.poll_event
+    #       if event[:type] == :key && event[:code] == "l"
+    #         # Insert a log line above the running TUI
+    #         tui.insert_before(1, tui.paragraph(text: "[#{Time.now}] User pressed 'l'"))
+    #         # Redraw viewport to restore its content
+    #         tui.draw { |f| f.render_widget(tui.paragraph(text: "TUI Running"), f.area) }
+    #       end
+    #     end
+    #   end
+    #--
+    # SPDX-SnippetEnd
+    #++
+    #
+    # @raise [Error::Invariant] if the current viewport is not inline
+    def insert_before(height, widget = nil, &block)
+      # Validate we're in an inline viewport
+      viewport_type = RatatuiRuby._get_viewport_type
+      unless viewport_type == "inline"
+        raise Error::Invariant, "insert_before requires an inline viewport"
+      end
+
+      content = widget || block&.call
+      _insert_before(height, content)
+    end
+
+    private def resolve_viewport(viewport, height)
+      case viewport
+      when nil, :fullscreen then Terminal::Viewport.fullscreen
+      when :inline then Terminal::Viewport.inline(height || 8)
+      when Terminal::Viewport then viewport
+      else raise ArgumentError, "Unknown viewport: #{viewport.inspect}"
+      end
+    end
+
+    # Sets the cursor position using a Position object or coordinates.
+    #
+    # This is a convenience alias for +set_cursor_position+ that works with
+    # Position objects or raw arrays rather than separate x/y arguments.
+    #
+    # [position] A Layout::Position, Array of [x, y], or anything that responds to +x+ and +y+.
+    #
+    # === Examples
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   # With Position object
+    #   pos = RatatuiRuby::Layout::Position.new(x: 10, y: 5)
+    #   RatatuiRuby.cursor_position = pos
+    #
+    #   # With array shorthand
+    #   RatatuiRuby.cursor_position = 10, 5
+    #--
+    # SPDX-SnippetEnd
+    #++
+    def cursor_position=(position)
+      if position.is_a?(Array)
+        x, y = position
+        set_cursor_position(x, y)
+      else
+        set_cursor_position(position.x, position.y)
+      end
+    end
+
+    # Gets the cursor position as a Position object.
+    #
+    # This is a convenience alias for +get_cursor_position+ that returns
+    # a Position object rather than raw coordinates.
+    #
+    # Returns:: A Layout::Position with the current cursor coordinates.
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   pos = RatatuiRuby.cursor_position
+    #   puts "Cursor at #{pos.x}, #{pos.y}"
+    #--
+    # SPDX-SnippetEnd
+    #++
+    def cursor_position
+      x, y = get_cursor_position
+      Layout::Position.new(x:, y:)
+    end
   end
 end

data/lib/ratatui_ruby/terminal_lifecycle.rb.bak

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-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
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   def log(message)
+    #     if RatatuiRuby.terminal_active?
+    #       @deferred_logs << message
+    #     else
+    #       puts message
+    #     end
+    #   end
+    #--
+    # SPDX-SnippetEnd
+    #++
+    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, viewport: nil, height: nil)
+      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
+
+      # Show A11Y lab prompt before launching TUI (stdout visible now, not after)
+      if Labs.enabled?(:a11y)
+        puts Labs::A11y.startup_message
+        $stdin.gets
+      end
+
+      @tui_session_active = true
+
+      viewport_obj = resolve_viewport(viewport, height)
+      _init_terminal(focus_events, bracketed_paste, viewport_obj.type.to_s, viewport_obj.height)
+    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, viewport_type = "fullscreen", viewport_height = nil)
+      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, viewport_type, viewport_height)
+    end
+
+    ##
+    # Restores the terminal to its original state.
+    # Leaves alternate screen and disables raw mode.
+    # Also flushes any deferred warnings and panic info 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
+      flush_panic_info
+    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
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   RatatuiRuby.run(focus_events: false) do |tui|
+    #     tui.draw(tui.paragraph(text: "Hi"))
+    #     sleep 1
+    #   end
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # @raise [Error::Invariant] if headless mode is enabled
+    # @see headless!
+    def run(focus_events: true, bracketed_paste: true, viewport: nil, height: nil)
+      init_terminal(focus_events:, bracketed_paste:, viewport:, height:)
+      yield TUI.new
+    ensure
+      restore_terminal
+    end
+
+    ##
+    # Inserts content above an inline viewport.
+    #
+    # Only works with inline viewports. Content is rendered above the TUI
+    # and becomes part of terminal scrollback history.
+    #
+    # [height] Number of lines to insert (Integer)
+    # [widget] Widget to render, or nil if using block
+    # [block] Optional block that returns a widget
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   RatatuiRuby.insert_before(1, Widgets::Paragraph.new(text: "Status: Done"))
+    #--
+    # SPDX-SnippetEnd
+    #++
+    def insert_before(height, widget = nil, &block)
+      # Validate we're in an inline viewport
+      viewport_type = _get_viewport_type
+      unless viewport_type == "inline"
+        raise Error::Invariant, "insert_before requires an inline viewport"
+      end
+      
+      content = widget || block&.call
+      _insert_before(height, content)
+    end
+
+    private
+
+    def resolve_viewport(viewport, height)
+      case viewport
+      when nil, :fullscreen then Terminal::Viewport.fullscreen
+      when :inline then Terminal::Viewport.inline(height || 8)
+      when Terminal::Viewport then viewport
+      else raise ArgumentError, "Unknown viewport: #{viewport.inspect}"
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/test_helper/terminal.rb

@@ -67,7 +67,14 @@ module RatatuiRuby
         # Defensive cleanup: reset any stale session state from previous test failures
         RatatuiRuby.instance_variable_set(:@tui_session_active, false)
 
-        RatatuiRuby.init_test_terminal(width, height)
+        # Extract and resolve viewport
+        viewport_param = opts[:viewport]
+        viewport = case viewport_param
+        when nil then RatatuiRuby::Terminal::Viewport.fullscreen
+        when RatatuiRuby::Terminal::Viewport then viewport_param
+        end
+
+        RatatuiRuby.init_test_terminal(width, height, viewport.type.to_s, viewport.height)
         # Flush any lingering events from previous tests
         while (event = RatatuiRuby.poll_event) && !event.none?; end
 

data/lib/ratatui_ruby/tui/core.rb

@@ -46,6 +46,22 @@ module RatatuiRuby
       def draw_cell(x, y, cell)
         Draw.cell(x, y, cell)
       end
+
+      # Inserts content above an inline viewport.
+      # @see RatatuiRuby.insert_before
+      def insert_before(height, widget = nil, &)
+        RatatuiRuby.insert_before(height, widget, &)
+      end
+
+      # Gets the Rect of the entire terminal, regardless of viewport
+      def terminal_area
+        RatatuiRuby.terminal_area
+      end
+
+      # Gets the Rect of the viewport
+      def viewport_area
+        RatatuiRuby.viewport_area
+      end
     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.10.1"
+  VERSION = "0.10.2"
 end

data/lib/ratatui_ruby.rb

@@ -15,6 +15,7 @@ require_relative "ratatui_ruby/buffer"   # Buffer::Cell (for inspection)
 require_relative "ratatui_ruby/text"    # Text::Span, Text::Line, Text.width
 require_relative "ratatui_ruby/draw"    # Draw commands
 require_relative "ratatui_ruby/symbols" # Symbols::Shade, etc.
+require_relative "ratatui_ruby/terminal/viewport" # Terminal::Viewport
 
 # Event types
 require_relative "ratatui_ruby/event"
@@ -46,6 +47,9 @@ end
 # Loaded after native extension so _enable_rust_backtrace is defined
 require_relative "ratatui_ruby/debug"
 
+# Experimental lab features (RR_LABS env var)
+require_relative "ratatui_ruby/labs"
+
 # Main entry point for the library.
 #
 # Terminal UIs require low-level control using C/Rust and high-level abstraction in Ruby.
@@ -153,6 +157,15 @@ module RatatuiRuby
     # SPDX-SnippetEnd
     #++
     class Invariant < Error; end
+
+    # Framework bug.
+    #
+    # This error indicates a bug within the RatatuiRuby framework itself.
+    # If you encounter this, the framework is broken — please report it.
+    #
+    # Normal application errors use standard exceptions like ArgumentError.
+    # This exception class distinguishes "our bug" from "your bug".
+    class Internal < Error; end
   end
 
   # Mix in terminal lifecycle and output protection methods
@@ -312,7 +325,15 @@ module RatatuiRuby
     if tree
       _draw(tree)
     elsif block
-      _draw(&block)
+      # Wrap user block to flush A11Y capture after user code
+      if Labs.enabled?(:a11y)
+        _draw do |frame|
+          block.call(frame)
+          frame.flush_a11y_capture
+        end
+      else
+        _draw(&block)
+      end
     end
   end
 
@@ -431,8 +452,66 @@ module RatatuiRuby
     )
   end
 
-  # (Native method _get_cell_at implemented in Rust)
-  private_class_method :_get_cell_at
+  ##
+  # Returns the current terminal viewport area.
+  #
+  # In inline viewports, this returns the viewport dimensions.
+  # In fullscreen mode, this returns the full terminal size.
+  #
+  # @return [Layout::Rect] The rendering viewport area
+  def self.get_viewport_area
+    raw = _get_terminal_area
+    Layout::Rect.new(
+      x: raw["x"],
+      y: raw["y"],
+      width: raw["width"],
+      height: raw["height"]
+    )
+  end
+
+  ##
+  # Returns the full terminal backend size.
+  #
+  # This is always the full terminal dimensions, regardless of viewport mode.
+  #
+  # === Example
+  #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
+  #   size = RatatuiRuby.get_terminal_size
+  #   puts "Terminal: #{size.width}x#{size.height}"
+  #
+  #--
+  # SPDX-SnippetEnd
+  #++
+  # @return [Layout::Rect] The full terminal size
+  def self.get_terminal_size
+    raw = _get_terminal_size
+    Layout::Rect.new(
+      x: raw["x"],
+      y: raw["y"],
+      width: raw["width"],
+      height: raw["height"]
+    )
+  end
+
+  # Ruby-idiomatic aliases (TIMTOWTDI)
+  class << self
+    # Aliases for get_terminal_size (full backend size)
+    alias get_terminal_area get_terminal_size
+    alias terminal_area get_terminal_size
+    alias terminal_size get_terminal_size
+    # Aliases for get_viewport_area (viewport rendering area)
+    alias get_viewport_size get_viewport_area
+    alias viewport_area get_viewport_area
+    alias viewport_size get_viewport_area
+  end
+
+  # (Native methods _get_cell_at and _get_terminal_size implemented in Rust)
+  private_class_method :_get_cell_at, :_get_terminal_size
 
   # Hide native Layout._split helper
   Layout::Layout.singleton_class.__send__(:private, :_split)