ratatui_ruby 0.9.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c543e8590fa79c457dac22abc8c39fc2264026079196ff7d0afc1d083c9cf013
-  data.tar.gz: 8c044e43009f8ede9c66274809aacae1c7e66a503157afc6756c4890b50d899c
+  metadata.gz: 85b40cc89f8710bfc5ef356cbec12d29ed27d86bc900ad1f1a52795e95a0fcf0
+  data.tar.gz: e13aad32fdc6a644cb8b608279af690a0046a0c130e04d40e5f6ca21cfd8eaff
 SHA512:
-  metadata.gz: dfd4c34a23e0af4dcb47c9520bae94db94cb7587f37b11662668e8f6f7e7a3148aeb0fb66ed66cb47f51898fc42da496ce50cec46ea1b286c3bcfcbe5dc43e41
-  data.tar.gz: 19871c4b3ec78afc30fc004f019b6b0ff246654ffbbe6dafb7e92cd5d1b3c4b1294ed3e836c47b70fb094dad3f5aa7927dd2b23a6cf458d571f5248fa5b0b934
+  metadata.gz: 82955407e8f3df33109527392bc82168b0527b3325c799beffeb13551bf42926b582dcbe1798abc5ed47c7c645846a6b64669c8b83de75e85f8b142c7f14b43f
+  data.tar.gz: d48b7871e77d537c2fb22d8b49b616f570d6f33da024b904c81aed8e5e471d59c332d42fcf060a21ba22c6b832bc2465cda8d8e9774455ff44b3e9440927b9dc

data/.builds/ruby-3.2.yml

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

data/AGENTS.md

@@ -136,9 +136,10 @@ The project follows a standard Gem layout with an `ext/` directory for Rust code
 
 Before considering a task complete and returning control to the user, you **MUST** ensure:
 
+0. **Production Ready:** RBS types are complete and accurate (no `untyped`), errors are handled with good DX, documentation follows guidelines, high code quality (no "pre-existing debt" excuses).
 1.  **Default Rake Task Passes:** Run `bin/agent_rake` (no args). Confirm it passes with ZERO errors **or warnings**.
   - You will save time if you run `bin/agent_rake rubocop:autocorrect` first.
-  - If you think the build is looking for deleted files, it is not. Instead, explain to the user why staging is needed and use the `run_command` tool with `git add -A` so they get a Run button with context.
+  - If you think the rake is looking for deleted files, STOP EVERYTHING and tell the user.
 2.  **Documentation Updated:** If public APIs or observable behavior changed, update relevant RDoc, rustdoc, `doc/` files, `README.md`, and/or `ratatui_ruby-wiki` files.
 3.  **Changelog Updated:** If public APIs, observable behavior, or gemspec dependencies have changed, update [CHANGELOG.md](CHANGELOG.md)'s **Unreleased** section.
 4.  **Commit Message Suggested:** You **MUST** ensure the final message to the user includes a suggested commit message block. This is NOT optional.

data/CHANGELOG.md

@@ -18,6 +18,103 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Removed
 
+## [0.10.0] - 2026-01-10
+
+### Added
+
+- **Table Integer Width Shorthand**: `Table` `widths:` parameter now accepts plain integers as shorthand for `Constraint.length(n)`. This enables cleaner table definitions like `widths: [40, 16, 10]` instead of verbose constraint arrays. Constraints and integers can be mixed freely.
+- **Error Message Context**: Type errors from the Rust backend now include the `inspect` string of the value that caused the error, making debugging significantly easier. For example, "expected array for rows" now shows "expected array for rows, got {title: \"Processes\", ...}".
+- **Steep Type Checking**: Integrated Steep static type analyzer with a new `rake steep` task. The Steepfile covers `lib/` with comprehensive RBS type definitions for all widgets, layout primitives, events, and interfaces.
+- **RBS Type Definitions**: Added 50+ RBS signature files in `sig/ratatui_ruby/` covering all widget classes, core interfaces (`_RectLike`, `_ToS`), type aliases (`style_input`, `widget`), and a `Data.define` patch for `super()` call compatibility.
+- **Duck Typing Documentation**: New `test/test_duck_typing.rb` documents that `Layout.split` accepts any object responding to `x`, `y`, `width`, `height` (Struct, Data.define, custom classes), not just `Rect`.
+- **Debug Mode**: New `RatatuiRuby::Debug` module controls Rust backtrace visibility for easier debugging. Activate via:
+  - `RUST_BACKTRACE=1` — Rust backtraces only
+  - `RR_DEBUG=1` — full debug mode (backtraces + future Ruby-side features)
+  - `include RatatuiRuby::TestHelper` — auto-enables debug mode in tests
+  - `RatatuiRuby.debug_mode!` — programmatic activation
+- **Debug.test_panic!**: New method that intentionally triggers a Rust panic, allowing developers to verify their backtrace setup is working correctly before encountering a real bug.
+- **Deferred Panic Backtraces**: Rust backtraces during TUI sessions are now stored and printed after terminal restoration, preventing output from being lost on the alternate screen. Previously, panic output in raw terminal mode was invisible.
+- **Remote Debugging**: Debug mode now integrates with Ruby's `debug` gem for remote debugging. `RR_DEBUG=1` stops at startup and waits for debugger attachment. `RatatuiRuby.debug_mode!` continues running in nonstop mode. Attach from another terminal with `rdbg --attach`.
+- **Debug.suppress_debug_mode**: New block method temporarily suppresses Ruby-side debug checks within its block. Rust backtraces remain enabled. Useful for testing production behavior in debug mode environments.
+- **DWIM Hash Coercion**: All widget factory methods now accept both `tui.table(hash)` and `tui.table(**hash)` calling styles. When a bare Hash is passed as the first positional argument, it is automatically splatted into keyword arguments. Unknown keys are silently ignored in production mode; in debug mode (`RR_DEBUG=1`), they raise `ArgumentError` for early typo detection.
+- **Ratatui-Aligned Text Methods**: New methods on `Text::Span` and `Text::Line` matching Ratatui's API for style manipulation:
+  - `Span#width` — display width in terminal cells (unicode-aware)
+  - `Span.raw(content)` — factory for unstyled spans
+  - `Span#patch_style(style)` — merge style onto existing style
+  - `Span#reset_style` — clear all styling
+  - `Line#left_aligned`, `Line#centered`, `Line#right_aligned` — fluent alignment setters
+  - `Line#push_span(span)` — append span (returns new Line, immutable)
+  - `Line#patch_style(style)`, `Line#reset_style` — style manipulation for all spans
+- **List Query Methods**: New methods on `List` matching Ratatui's API:
+  - `List#len` — number of items (with Ruby aliases `length`, `size`)
+- **TableState Navigation Methods**: New methods on `TableState` matching Ratatui's API for column navigation:
+  - `selected_cell` — returns `[row, column]` tuple when both are selected
+  - `with_selected_cell(cell)` — constructor to create state with both row and column selected
+  - `select_next_column` — select the next column (or first if none selected)
+  - `select_previous_column` — select the previous column (saturates at 0)
+  - `select_first_column` — select column 0
+  - `select_last_column` — select the last column (clamped during rendering)
+- **Buffer Query Methods**: New module methods on `Buffer` matching Ratatui's API for buffer inspection:
+  - `Buffer.content` — returns all cells as an array
+  - `Buffer.get(x, y)` — returns the Cell at the specified position
+  - `Buffer.index_of(x, y)` — converts position to linear buffer index
+  - `Buffer.pos_of(index)` — converts linear index to position coordinates
+- **Rect Conversion Methods**: New methods on `Rect` for extracting geometry components:
+  - `Rect#as_position` — returns a `Position` object containing x and y coordinates
+  - `Rect#as_size` — returns a `Size` object containing width and height
+- **Position and Size Classes**: New layout primitives matching Ratatui's API:
+  - `Layout::Position` — represents terminal coordinates (x, y)
+  - `Layout::Size` — represents terminal dimensions (width, height)
+- **Constraint#apply**: Computes the constrained size for a given available space. For example, `Constraint.percentage(50).apply(100)` returns `50`. Also aliased as `call` for proc-like invocation (`constraint.(100)`).
+- **Color Module**: New `Style::Color` module with constructors matching Ratatui's API:
+  - `Color.from_u32(0xRRGGBB)` — creates a color from a hex integer (aliased as `Color.hex`)
+  - `Color.from_hsl(h, s, l)` — creates a color from HSL values (aliased as `Color.hsl`)
+- **Ruby-Idiomatic Aliases**: All new APIs include shorter, more Ruby-ish aliases following TIMTOWTDI:
+  - `Rect#position` (alias for `as_position`), `Rect#size` (alias for `as_size`)
+  - `Buffer[x, y]` (alias for `Buffer.get`)
+  - `Constraint#call` (alias for `apply`, enables `constraint.(n)` syntax)
+- **Layout Margin and Spacing**: `Layout` now supports `margin:` and `spacing:` parameters for edge insets and gaps between segments, matching Ratatui's Layout API.
+- **Layout.split_with_spacers**: New class method returns both content segments and spacer Rects, enabling custom rendering of dividers or separators between layout sections.
+- **Canvas#get_point**: Converts canvas coordinates to normalized [0.0, 1.0] grid coordinates for hit testing. Returns `nil` for out-of-bounds coordinates. Also aliased as `point` and `[]` for Ruby-idiomatic access.
+- **Row#enable_strikethrough**: Returns a new Row with `:crossed_out` modifier for indicating cancelled or deleted items. Also aliased as `strikethrough`. Note: Strikethrough (SGR 9) is not supported by all terminals; macOS Terminal.app notably lacks support while Kitty, iTerm2, Alacritty, and WezTerm render it correctly.
+- **Rect Geometry Methods**: New methods on `Rect` for geometry manipulation:
+  - `Rect#outer(margin)` — expands a rectangle by a margin (inverse of `inner`)
+  - `Rect#resize(size)` — changes dimensions while preserving top-left position
+  - `Rect#centered_horizontally(constraint)` — centers horizontally using Layout
+  - `Rect#centered_vertically(constraint)` — centers vertically using Layout
+  - `Rect#centered(h, v)` — centers on both axes
+- **TUI Shape Aliases (DWIM)**: Canvas shape factories now have terse and bidirectional aliases:
+  - Terse: `circle()`, `point()`, `map()`, `label()` (shorter forms of `shape_*`)
+  - Bidirectional: `circle_shape()`, `point_shape()`, `rectangle_shape()`, `map_shape()`, `label_shape()` (same as `shape_*`)
+  - Note: Terse `rectangle` is intentionally excluded to avoid confusion with `Layout::Rect`; use `shape_rectangle()` or `rectangle_shape()`.
+- **TUI `item` Alias**: `tui.item(...)` is now an alias for `tui.list_item(...)`, providing a terser API when building lists.
+- **Gauge and LineGauge `percent`**: Both widgets now have a `percent` reader that returns the ratio as an integer percentage (0-100). `LineGauge` also now accepts a `percent:` constructor parameter matching `Gauge`.
+- **List#selected_item**: Returns the item at the selected index (or nil if nothing is selected).
+- **Style `underline_color`**: New optional parameter for `Style` that sets a distinct underline color independent of the foreground color. Useful for styling like "white text with red underline". Terminals must support the underline color extension (SGR 58).
+- **Style `remove_modifiers`**: New optional parameter for `Style` that explicitly removes modifiers when styles are patched/inherited. Corresponds to Ratatui's `sub_modifier` field. Use it to prevent inherited bold, italic, or other modifiers from propagating.
+- **Symbols::Shade Constants**: New `RatatuiRuby::Symbols::Shade` module exposes Ratatui's shade block characters as named constants: `EMPTY` (" "), `LIGHT` ("░"), `MEDIUM` ("▒"), `DARK` ("▓"), `FULL` ("█"). Use them for gradients, density fills, or custom progress indicators.
+- **Symbols::Line Constants and Sets**: New `RatatuiRuby::Symbols::Line` module exposes Ratatui's box-drawing characters with 36 individual constants (VERTICAL, HORIZONTAL, corners, T-junctions, cross) and 4 predefined sets: `NORMAL` (standard corners), `ROUNDED` (rounded corners), `DOUBLE` (double-line), `THICK` (heavy lines). Use them for custom borders or drawing.
+- **Symbols::Bar Constants and Sets**: New `RatatuiRuby::Symbols::Bar` module exposes Ratatui's vertical bar characters (lower blocks) with 8 individual constants and 2 predefined sets: `NINE_LEVELS` (full resolution) and `THREE_LEVELS` (simplified). Used by Sparkline widget.
+- **Symbols::Block Constants and Sets**: New `RatatuiRuby::Symbols::Block` module exposes Ratatui's horizontal block characters (left blocks) with 8 individual constants and 2 predefined sets: `NINE_LEVELS` (full resolution) and `THREE_LEVELS` (simplified). Used by Gauge widget.
+- **Symbols::Scrollbar Sets**: New `RatatuiRuby::Symbols::Scrollbar` module exposes 4 predefined scrollbar symbol sets: `VERTICAL`, `DOUBLE_VERTICAL`, `HORIZONTAL`, `DOUBLE_HORIZONTAL`. Each set contains `track`, `thumb`, `begin_char`, and `end_char` symbols.
+- **Cell `underline_color`**: `Buffer::Cell` and top-level `Cell` now expose `underline_color` attribute for introspecting styled underline colors during testing.
+
+### Changed
+
+- **`tui.draw` Argument Validation (Breaking)**: `tui.draw` now validates its arguments. Calling `draw` with neither a tree nor a block raises `ArgumentError`, as does calling it with both. Previously this produced undefined behavior.
+- **`Layout.split` Stricter Type Checking (Breaking)**: `Layout.split` now rejects invalid `area` arguments with a clear `ArgumentError` instead of silently misbehaving. Objects must be a `Rect`, `Hash` with `:x/:y/:width/:height` keys, or respond to all four geometry methods.
+- **Schema Directory Removed (Breaking)**: The legacy `lib/ratatui_ruby/schema/` directory has been removed. All widget classes now live exclusively in their proper namespaces (`Widgets::`, `Layout::`, `Text::`, etc.). Direct usage like `RatatuiRuby::Paragraph` (without `Widgets::`) is no longer supported. Use `RatatuiRuby::Widgets::Paragraph` or the TUI facade (`tui.paragraph`).
+- **Buffer::Cell Modifiers (Breaking)**: `Buffer::Cell#modifiers` and `Cell#modifiers` now return an array of `Symbol`s (e.g., `[:bold, :italic]`) instead of `String`s. This unifies the API, as `Style` modifiers were already symbols. Code expecting strings (e.g. `cell.modifiers.include?("bold")`) must be updated to use symbols. This changes behavior established in v0.9.1.
+
+### Fixed
+
+- **Tabs Padding Coercion**: `Tabs` `padding_left` and `padding_right` now correctly coerce duck-typed integer values (objects responding to `to_int`/`to_i`) via `Integer()`. Previously these parameters were passed through without coercion, inconsistent with other integer parameters. `Text::Line` values are still accepted as-is for styled padding.
+
+### Removed
+
+- **NullIO Re-export (Breaking)**: Removed `RatatuiRuby::NullIO` constant. Use `RatatuiRuby::OutputGuard::NullIO` if you were relying on this internal class.
+- **Legacy Media Keys (Breaking)**: Removed support for legacy unprefixed media keys (e.g. `play`, `stop`) in event parsing. You must now use the canonical `media_`-prefixed keys (e.g. `media_play`, `media_stop`). The `play?`/`stop?` predicates still work for both, checking the correct canonical codes.
+
 ## [0.9.1] - 2026-01-08
 
 ### Added
@@ -515,6 +612,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.10.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.10.0
 [0.9.1]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.9.1
 [0.9.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.9.0
 [0.8.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.8.0

data/REUSE.toml

@@ -16,6 +16,11 @@ path = 'doc/images/*.png'
 SPDX-FileCopyrightText = "2025 Kerrick Long <me@kerricklong.com>"
 SPDX-License-Identifier = "CC-BY-SA-4.0"
 
+[[annotations]]
+path = 'doc/images/*.gif'
+SPDX-FileCopyrightText = "2025 Kerrick Long <me@kerricklong.com>"
+SPDX-License-Identifier = "CC-BY-SA-4.0"
+
 [[annotations]]
 path = 'test/fixtures/*.txt'
 SPDX-FileCopyrightText = "2025 Kerrick Long <me@kerricklong.com>"

data/Rakefile

@@ -8,4 +8,4 @@ require "bundler/gem_tasks"
 # Import all tasks from the tasks/ directory
 Dir.glob("tasks/*.rake").each { |r| import r }
 
-task default: %w[lint:fix sourcehut test lint license:new]
+task default: %w[lint:fix sourcehut test lint license:new steep]

data/Steepfile

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+target :lib do
+  signature "sig"
+  check "lib"
+
+  # Legacy schema/ files pending migration - exclude from checking
+  # Only schema/text.rb and schema/draw.rb are loaded by the main gem
+  # See doc/contributors/v1.0.0_blockers.md
+  ignore "lib/ratatui_ruby/schema/bar_chart.rb"
+  ignore "lib/ratatui_ruby/schema/bar_chart/"
+  ignore "lib/ratatui_ruby/schema/block.rb"
+  ignore "lib/ratatui_ruby/schema/calendar.rb"
+  ignore "lib/ratatui_ruby/schema/canvas.rb"
+  ignore "lib/ratatui_ruby/schema/center.rb"
+  ignore "lib/ratatui_ruby/schema/chart.rb"
+  ignore "lib/ratatui_ruby/schema/clear.rb"
+  ignore "lib/ratatui_ruby/schema/constraint.rb"
+  ignore "lib/ratatui_ruby/schema/cursor.rb"
+  ignore "lib/ratatui_ruby/schema/gauge.rb"
+  ignore "lib/ratatui_ruby/schema/layout.rb"
+  ignore "lib/ratatui_ruby/schema/line_gauge.rb"
+  ignore "lib/ratatui_ruby/schema/list.rb"
+  ignore "lib/ratatui_ruby/schema/list_item.rb"
+  ignore "lib/ratatui_ruby/schema/overlay.rb"
+  ignore "lib/ratatui_ruby/schema/paragraph.rb"
+  ignore "lib/ratatui_ruby/schema/ratatui_logo.rb"
+  ignore "lib/ratatui_ruby/schema/ratatui_mascot.rb"
+  ignore "lib/ratatui_ruby/schema/rect.rb"
+  ignore "lib/ratatui_ruby/schema/row.rb"
+  ignore "lib/ratatui_ruby/schema/scrollbar.rb"
+  ignore "lib/ratatui_ruby/schema/shape/"
+  ignore "lib/ratatui_ruby/schema/sparkline.rb"
+  ignore "lib/ratatui_ruby/schema/style.rb"
+  ignore "lib/ratatui_ruby/schema/table.rb"
+  ignore "lib/ratatui_ruby/schema/tabs.rb"
+
+  # ClassMethods mixin pattern cannot be typed in RBS
+  # (self in ClassMethods refers to the including Class)
+  ignore "lib/ratatui_ruby/widgets/coerceable_widget.rb"
+
+  library "pathname"
+  library "fileutils"
+  library "minitest"
+  library "date"
+end

data/doc/concepts/debugging.md

@@ -0,0 +1,401 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Debugging Guide
+
+TUI applications are harder to debug than typical Ruby programs. The terminal is in raw mode. Standard output corrupts the display. Debuggers that rely on REPL input conflict with the event loop. Rust panics produce cryptic stack traces without symbols.
+
+This guide covers what RatatuiRuby offers and what works (and what does not) when debugging TUI apps.
+
+## Debug Mode
+
+RatatuiRuby ships with debug symbols in release builds. Call `RatatuiRuby::Debug.enable!` to get Rust backtraces with meaningful stack frames.
+
+### Activation Methods
+
+You can turn on debug features in three ways.
+
+1. **Environment variable (Rust only):** `RUST_BACKTRACE=1` turns on Rust backtraces without Ruby-side debug features.
+
+2. **Environment variable (full):** `RR_DEBUG=1` turns on full debug mode at process startup.
+
+3. **Programmatic:** Call `RatatuiRuby.debug_mode!` or `RatatuiRuby::Debug.enable!`.
+
+> [!WARNING]
+> Debug mode opens a remote debugging socket. This is a **security vulnerability**. Do not use it in production. See [Remote Debugging](#remote-debugging) for details.
+
+Including `RatatuiRuby::TestHelper` auto-enables debug mode. Test authors get backtraces automatically.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+# Option 1: Environment variable
+# $ RR_DEBUG=1 ruby my_app.rb
+
+# Option 2: Programmatic
+RatatuiRuby.debug_mode!
+
+# Now Rust panics show meaningful stack traces
+```
+<!-- SPDX-SnippetEnd -->
+
+### Panics vs. Exceptions
+
+Rust backtraces only appear for **panics** (unrecoverable crashes). When Rust code raises a Ruby exception (like `TypeError`), Ruby handles the backtrace. Rust provides the error message.
+
+| Error Type | Backtrace | When It Happens |
+|------------|-----------|-----------------|
+| **Panic** | Rust stack trace | Internal Rust bug, `Debug.test_panic!` |
+| **Exception** | Ruby stack trace | Type mismatch, invalid arguments |
+
+The `RUST_BACKTRACE=1` environment variable and `Debug.enable!` affect panic backtraces. Exceptions always show Ruby backtraces, but RatatuiRuby includes **contextual error messages** showing the actual value that caused the error:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```
+# Without context (generic):
+expected array for rows
+
+# With context (RatatuiRuby):
+expected array for rows, got 42
+```
+<!-- SPDX-SnippetEnd -->
+
+## Inspecting the Buffer
+
+The following methods help you debug rendering issues from tests or scripts.
+
+### print_buffer
+
+Outputs the current terminal buffer to STDOUT with full ANSI colors. Call it inside `with_test_terminal` to see exactly what would render.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+with_test_terminal do
+  MyApp.new.render
+  print_buffer  # Outputs the screen with colors
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+### buffer_content
+
+Returns the terminal buffer as an array of strings (one per row). Use it for programmatic inspection.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+with_test_terminal do
+  MyApp.new.render
+  pp buffer_content  # ["Line 1: ...", "Line 2: ...", ...]
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+### get_cell
+
+Returns a `Buffer::Cell` with the character, foreground color, background color, and modifiers at specific coordinates.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+with_test_terminal do
+  MyApp.new.render
+  cell = get_cell(0, 0)
+  pp cell.symbol  # "H"
+  pp cell.fg      # :red
+  pp cell.bold?   # true
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+## Protecting Output
+
+During a TUI session, writes to `$stdout` or `$stderr` corrupt the display. Third-party gems often print warnings or debug output unexpectedly.
+
+Use `guard_io` to temporarily swallow output from chatty code.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+RatatuiRuby.run do |tui|
+  RatatuiRuby.guard_io do
+    SomeChattyGem.process  # Any puts/warn calls are swallowed
+  end
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+## Interactive Debuggers
+
+> [!WARNING]
+> This section has not been verified by a human.
+
+> [!CAUTION]
+> Traditional interactive debuggers (Pry, IRB, debug.gem) do not work inside an active TUI session. They require terminal input and output, which conflicts with raw mode.
+
+### Workarounds
+
+**Temporarily exit TUI mode.** Restore the terminal, run your debugger, then re-initialize.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+RatatuiRuby.restore_terminal
+binding.pry  # Now Pry works normally
+RatatuiRuby.init_terminal
+```
+<!-- SPDX-SnippetEnd -->
+
+**Use test mode.** Debug rendering logic inside `with_test_terminal` where there is no real terminal conflict.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+with_test_terminal do
+  binding.pry  # Works fine in test mode
+  MyApp.new.render
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+## Remote Debugging
+
+Debug mode uses [Ruby's `debug` gem](https://rubygems.org/gems/debug) for [remote debugging](https://github.com/ruby/debug?tab=readme-ov-file#readme). Attach from another terminal (or IDE or Chrome DevTools) while the TUI runs.
+
+![Debugging Showcase](../images/app_debugging_showcase.gif)
+
+For a hands-on demo, see the [Debugging Showcase](../../examples/app_debugging_showcase/README.md) example.
+
+Debug mode loads the `debug` gem and creates a UNIX domain socket. Debuggers attach from another terminal. This works well for TUI apps since the main terminal is in raw mode.
+
+### How It Works
+
+- **`RR_DEBUG=1`**: Loads `debug/open`. The app stops at startup and waits for a debugger to attach.
+- **`RatatuiRuby.debug_mode!`**: Loads `debug/open_nonstop`. The app continues running. Attach whenever you want.
+
+Attach from another terminal with `rdbg --attach`.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```sh
+$ rdbg --attach
+```
+<!-- SPDX-SnippetEnd -->
+
+> [!CAUTION]
+> Remote debugging opens a backdoor to your application. This is a **security vulnerability**. The `debug/open_nonstop` mode is particularly dangerous because it allows attachment at any time. Do not run debug mode in production. Anyone who can access the socket can execute arbitrary code.
+
+### Example: Debugging a Running TUI
+
+Terminal 1 (your app):
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```sh
+$ ruby my_tui_app.rb
+# App starts, TUI is running
+# In your code: RatatuiRuby.debug_mode!
+# Console shows: DEBUGGER: Debugger can attach via UNIX domain socket (...)
+```
+<!-- SPDX-SnippetEnd -->
+
+Terminal 2 (debugger):
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```sh
+$ rdbg --attach
+# Now you have a full debugger REPL
+(rdbg) info locals
+(rdbg) break MyApp#handle_key
+(rdbg) continue
+```
+<!-- SPDX-SnippetEnd -->
+
+### Requirements
+
+Add the `debug` gem to your Gemfile:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+gem "debug", ">= 1.0"
+```
+<!-- SPDX-SnippetEnd -->
+
+If `RR_DEBUG=1` is set but the debug gem is missing, RatatuiRuby raises a `LoadError` with installation instructions.
+
+## File Logging
+
+You can write debug output to a log file instead of stdout.
+
+### Basic Logging
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+DEBUG_LOG = File.open("debug.log", "a")
+
+def debug(msg)
+  DEBUG_LOG.puts("[#{Time.now}] #{msg}")
+  DEBUG_LOG.flush
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+Then tail the log in a separate terminal.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```bash
+tail -f debug.log
+```
+<!-- SPDX-SnippetEnd -->
+
+### Timestamped Logging
+
+For high-frequency logging (like inside a render loop), use timestamped files to avoid overwrites:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+FileUtils.mkdir_p(File.join(Dir.tmpdir, "my_debug"))
+timestamp = Time.now.strftime('%Y%m%d_%H%M%S_%N')
+File.write(
+  File.join(Dir.tmpdir, "my_debug", "#{timestamp}.log"),
+  "variable=#{value.inspect}\n"
+)
+```
+<!-- SPDX-SnippetEnd -->
+
+Then tail the directory.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```bash
+watch -n 0.5 'ls -la /tmp/my_debug/ && cat /tmp/my_debug/*.log'
+```
+<!-- SPDX-SnippetEnd -->
+
+## REPL Without the TUI
+
+Unit tests verify correctness, but sometimes you want to poke at objects interactively. Wrap your main execution in a guard:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+if __FILE__ == $PROGRAM_NAME
+  MyApp.new.run
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+Then load the file without entering raw mode.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```bash
+ruby -e 'load "./bin/my_tui"; obj = MyClass.new; puts obj.result'
+```
+<!-- SPDX-SnippetEnd -->
+
+This exercises domain logic without the terminal conflict. Use it for exploration. Write tests with [TestHelper](application_testing.md) for regression coverage.
+
+## Isolating Terminal Issues
+
+Sometimes code works in a `ruby -e` script but fails in the TUI. Here are common causes.
+
+1. **Thread context.** Ruby threads share the process's terminal state.
+2. **Raw mode.** External commands fail when stdin/stdout are reconfigured.
+3. **SSH/Git auth.** Commands that prompt for credentials hang or return empty.
+
+See [Async Operations](./async.md) for solutions.
+
+## Error Classes
+
+RatatuiRuby has semantic exception classes for different failure modes:
+
+| Class | Meaning |
+|-------|---------|
+| `RatatuiRuby::Error::Terminal` | I/O failure (backend crashed, terminal unavailable) |
+| `RatatuiRuby::Error::Safety` | Lifetime violation (using Frame after draw block exits) |
+| `RatatuiRuby::Error::Invariant` | Contract violation (double init, headless mode conflict) |
+
+Catch these specifically instead of rescuing `StandardError` broadly.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+begin
+  RatatuiRuby.run { |tui| ... }
+rescue RatatuiRuby::Error::Terminal => e
+  puts "Terminal I/O failed: #{e.message}"
+rescue RatatuiRuby::Error::Safety => e
+  puts "API misuse: #{e.message}"
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+## Further Reading
+
+- [Application Testing Guide](application_testing.md) — Test helpers, snapshots, event injection
+- [RatatuiRuby::Debug](../../lib/ratatui_ruby/debug.rb) — Debug module source