ratatui_ruby 0.3.1 → 0.5.0

data/CHANGELOG.md

@@ -18,6 +18,224 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Removed
 
+## [0.5.0] - 2026-01-01
+
+### Added
+
+#### Frame API
+
+- **`RatatuiRuby.draw { |frame| ... }`**: New block-based drawing API that yields a `Frame` object for explicit widget placement. Enables hit testing without duplicating layout calculations.
+- **`Frame#area`**: Returns the terminal area as a `Rect`.
+- **`Frame#render_widget(widget, rect)`**: Renders a widget at a specific position. Works with all existing widgets and `Rect` objects.
+
+#### Testing
+
+- **`RatatuiRuby::TestHelper#inject_mouse`**: comprehensive mouse event injection helper supporting coordinates, buttons, and modifiers.
+- **`RatatuiRuby::TestHelper#inject_click`**: Helper for left-click events.
+- **`RatatuiRuby::TestHelper#inject_right_click`**: Helper for right-click events.
+- **`RatatuiRuby::TestHelper#inject_drag`**: Helper for mouse drag events.
+- **`RatatuiRuby::TestHelper#assert_screen_matches`**: Assert that the current terminal content matches a stored golden snapshot.
+
+#### Session API
+
+- **Convenience Methods**: `Session` now wraps class methods from `Layout`, `Constraint`, and other schema classes as instance methods (e.g., `layout_split` delegates to `Layout.split`, `constraint_percentage` to `Constraint.percentage`). This enables a more fluent API in `RatatuiRuby.run` blocks.
+
+### Changed
+
+#### Event System
+
+- **`Event::None` (Breaking)**: `RatatuiRuby.poll_event` now returns `Event::None` instead of `nil` when no event is available. This null-object responds safely to all event predicates with `false`. Use `event.none?` or pattern-match on `type: :none`. Code using `while (event = poll_event)` must change to `while (event = poll_event) && !event.none?`.
+
+### Fixed
+
+#### Session API
+
+- **Missing Convenience Methods**: Fixed `Session` convenience methods (e.g., `bar_chart`) being missed by replacing the manual list with automatic runtime introspection of the `RatatuiRuby` module.
+
+### Removed
+
+## [0.4.0] - 2025-12-30
+
+### Added
+
+#### Hex Color Support
+
+- **Style**: `fg` and `bg` parameters now accept hex color strings (e.g., `"#ff0000"` for red). Requires a 24-bit true color capable terminal (Kitty, iTerm2, modern Terminal.app). Terminals without true color support will gracefully fall back to the closest ANSI color.
+
+#### RatatuiMascot Widget
+
+- **RatatuiMascot**: New widget to display the Ratatui mascot (Ferris).
+
+#### RatatuiLogo Widget
+
+- **RatatuiLogo**: New widget to display the Ratatui logo.
+
+
+#### Duck-Typed Numeric Coercion
+
+- All numeric parameters now accept any object that responds to `to_f` (for floats) or `to_int`/`to_i` (for integers). This provides idiomatic Ruby interoperability with `BigDecimal`, `Rational`, and custom numeric types. Uses Ruby's built-in `Float()` and `Integer()` Kernel methods for proper duck-type handling.
+
+#### Paragraph Widget
+
+- `alignment`: **Breaking Change**: Renamed `align` to `alignment` to match Ratatui 0.30 API.
+
+#### Custom Widgets
+
+- **Draw Command API**: Custom widgets now return an array of `Draw` commands instead of writing to a buffer. Use `RatatuiRuby::Draw.string(x, y, string, style)` and `RatatuiRuby::Draw.cell(x, y, cell)` to create draw commands. This eliminates use-after-free bugs by keeping all pointers inside Rust while Ruby works with pure data objects. **Breaking:** The `render` method signature changed from `render(area, buffer)` to `render(area)`.
+
+#### BarChart Widget
+
+- `bar_set`: Customize bar characters (digits, symbols, blocks).
+- `group_gap`: Control spacing between groups in grouped bar charts.
+- `data`: Now accepts an Array of `BarGroup` objects, enabling grouped bar charts.
+- `Bar` and `BarGroup`: New schema classes for defining grouped bar data.
+
+#### Block Widget
+
+- `border_type`: Customize border style (`:plain`, `:rounded`, `:double`, `:thick`, `:quadrant_inside`, `:quadrant_outside`).
+- `border_set`: Customize border characters (e.g., digits, symbols).
+- `border_style`: Apply full style support (colors and modifiers) to borders. Takes precedence over `border_color`.
+- `children`: Declare child widgets within the block's area for composable UI structures.
+- Multiple `titles`: Display multiple titles with individual alignment (`:left`, `:center`, `:right`) and vertical positioning (`:top`, `:bottom`). Each title supports its own `style`.
+- `title_style`: Base style applied to all titles.
+- `style`: Base style applied to the entire block.
+- `padding`: Directional padding via a single integer (uniform) or array of 4 integers (`[left, right, top, bottom]`).
+- `line_count(width)`: **(Experimental)** Calculate rendered lines (including borders/padding) for a given width. Delegates to Ratatui's underlying unstable `line_count`.
+- `line_width`: **(Experimental)** Calculate minimum width to avoid wrapping (including borders/padding). Delegates to Ratatui's underlying unstable `line_width`.
+
+#### Calendar Widget
+
+- `events`: Hash mapping `Date` objects to `Style` objects for highlighting specific dates.
+- `show_month_header`: Toggle month header visibility (defaults to `false`). **Breaking:** Previously always shown.
+- `show_weekdays_header`: Toggle weekday names (Mon, Tue, etc.) visibility (defaults to `true`).
+- `show_surrounding`: Optional `Style` to display dates from adjacent months, or `nil` to hide them.
+
+#### Chart Widget
+
+- `legend_position`: Position legend at `:top_left`, `:top_right`, `:bottom_left`, or `:bottom_right` (defaults to `:top_right`).
+- `hidden_legend_constraints`: Array of two `Constraint` objects to hide the legend when chart area is too small.
+- **Axis**: `labels_alignment` to control horizontal alignment (`:left`, `:center`, `:right`) of axis labels.
+- `Dataset`: `style` parameter replaces `color`, enabling full styling (fg, bg, modifiers) for chart datasets. **Breaking**: `color` parameter removed.
+
+#### Gauge Widget
+
+- `style`: Base style applied to the entire gauge background.
+- `gauge_style`: Style applied specifically to the filled bar. **Breaking:** Use this instead of `style` if you want bar coloring; `style` no longer defaults to `Style.default`.
+- `percent`: Convenience parameter alternative to `ratio` for initialization.
+- `use_unicode`: Explicitly toggle between unicode blocks and ASCII rendering (defaults to `true`).
+
+#### LineGauge Widget
+
+- `style`: Base style applied to the entire gauge area.
+
+#### List Widget
+
+- `scroll_padding`: Number of items to keep visible above and below the selected item during scrolling.
+- `repeat_highlight_symbol`: When `true`, repeat highlight symbol on each line of multi-line selections.
+- `highlight_spacing`: Control selection column reservation (`:always`, `:when_selected`, `:never`).
+- `direction`: List orientation (`:top_to_bottom` or `:bottom_to_top`).
+
+#### Sparkline Widget
+
+- `absent_value_symbol` and `absent_value_style`: Customize rendering of `nil` values (distinct from `0`).
+- `direction`: Rendering direction (`:left_to_right` or `:right_to_left`).
+- `bar_set`: Customize bar characters.
+
+#### Table Widget
+
+- `style`: Base style applied to the entire table.
+- `column_spacing`: Horizontal spacing between columns.
+- `footer`: Summary rows at the bottom of the table.
+- `flex`: Layout distribution mode (`:legacy`, `:start`, `:center`, `:end`, `:space_between`, `:space_around`, `:space_evenly`).
+- `highlight_spacing`: Control selection column reservation (`:always`, `:when_selected`, `:never`).
+- `column_highlight_style`: Style applied to the selected column.
+- `cell_highlight_style`: Style applied to the selected cell (intersection of row and column).
+- `selected_column`: Index of the selected column (Integer or nil).
+- `widths`: Now support all constraint types (`:max`, `:fill`, `:ratio`) with full flexibility.
+
+#### Tabs Widget
+
+- `style`: Base style applied to the entire tabs area.
+- `padding_left` and `padding_right`: Horizontal padding around tab titles.
+- `width`: Calculate total width of the tabs (including dividers/padding).
+
+#### Canvas Widget
+
+- `background_color`: Set canvas background color.
+- `:half_block` marker: Block-based rendering using half-height blocks.
+- `:quadrant`, `:sextant`, `:octant` markers: High-resolution pseudo-pixel rendering.
+- `Shape::Label`: Text labels at canvas coordinates with optional styling.
+
+#### Scrollbar Widget
+
+- Full styling support: `thumb_style`, `track_symbol`, `track_style`, `begin_symbol`, `begin_style`, `end_symbol`, `end_style`, `style`.
+- All orientation variants: `:vertical_left`, `:vertical_right`, `:horizontal_top`, `:horizontal_bottom` (`:vertical` and `:horizontal` remain as aliases).
+
+#### Layout & Constraints
+
+- `Constraint.ratio(numerator, denominator)`: Proportional constraints with explicit ratio.
+- `Constraint.fill(weight)`: Distribute remaining space proportionally. Use multiple `Fill` to split space (e.g., `Fill(1)` and `Fill(3)` split 1:3).
+- `Constraint.max(value)`: Cap maximum size of a section.
+- `Layout.split(area, direction:, constraints:, flex:)`: Compute layout rectangles without rendering, enabling hit testing.
+- `Flex::SpaceEvenly`: New layout mode for `Layout` widget.
+- `flex` parameter: All layout options (`:legacy`, `:start`, `:center`, `:end`, `:space_between`, `:space_around`, `:space_evenly`).
+
+#### Rich Text & Text Components
+
+- `Text::Span` and `Text::Line`: Styled text with inline formatting. Combine spans into lines with optional alignment.
+- `Shape` module: Canvas shape primitives (`Shape::Line`, `Shape::Circle`, `Shape::Rectangle`, `Shape::Point`, `Shape::Map`) to avoid naming conflicts with `Text::Line`.
+
+#### Event System
+
+- Typed `Event` API: `RatatuiRuby.poll_event` returns typed objects (`Event::Key`, `Event::Mouse`, `Event::Resize`, `Event::Paste`, `Event::FocusGained`, `Event::FocusLost`).
+- Predicate methods: `key?`, `mouse?`, `ctrl?`, etc. for cleaner event handling.
+- Pattern matching support and discriminator pattern via `type:` key in `#deconstruct_keys`.
+- `Event::Resize`: Terminal resize events with `width` and `height` attributes.
+- `Event::Paste`: Bracketed paste as atomic event with `content:`.
+- `Event::FocusGained` and `Event::FocusLost`: Terminal focus changes.
+- `Event::Mouse.new` accepts `nil` for `button` parameter (treated as `"none"`).
+
+#### Geometry & Hit Testing
+
+- `Rect#contains?(x, y)`: Test whether a point is inside a rectangle. Essential for mouse click handlers.
+- `Layout.split`: Enables calculating widget positions before rendering.
+
+#### Testing
+
+- `RatatuiRuby::TestHelper#inject_keys`: Concise event injection helper.
+- `RatatuiRuby::TestHelper#get_cell` and `#assert_cell_style`: Inspect terminal cell attributes (colors, characters).
+- `with_test_terminal`: Default timeout of 2 seconds to prevent hanging tests. **Breaking:** Default size is now 80×24 (VT100 standard) instead of 20×10.
+- Error on `inject_event`/`inject_keys` outside `with_test_terminal`: Prevents test hangs from race conditions.
+- Value equality (`==`) for `Event` objects: Simplify assertions.
+
+#### Lifecycle & Application Structure
+
+- `RatatuiRuby.run`: New context manager that initializes terminal, yields session, and restores on exit. Allows custom event loop control.
+- **Session** class: Renamed from `DSL` to better reflect its purpose as a managed terminal session with convenience methods.
+- Focus and Bracketed Paste events: Enabled by default in `RatatuiRuby.run` and `RatatuiRuby.init_terminal` (disable with `focus_events: false` or `bracketed_paste: false`).
+
+#### Documentation & Examples
+
+- **Cached Layout Pattern**: Documented in `doc/interactive_design.md`. Three-phase lifecycle pattern (`calculate_layout`, `render`, `handle_input`) solves layout duplication in immediate-mode UI. Foundation for Component architecture in Gem 1.5.
+
+### Changed
+
+- **Calendar:** Renamed `day_style` to `default_style` to match Ratatui 0.30 API. This is a breaking change. [Kerrick Long]
+
+- **Custom Widget `render` Method (Breaking)**: Changed signature from `render(area, buffer)` to `render(area)`, with render methods now returning an array of `Draw` commands instead of writing directly to a buffer. This change improves memory safety by eliminating use-after-free risks.
+- **Ratatui Upgraded to 0.30.0**: Underlying `ratatui` library upgraded from 0.29, bringing modularized crates, `no_std` support for embedded targets, and major widget/layout enhancements. Layout cache explicitly enabled for performance.
+- **Event API (Breaking)**: `RatatuiRuby.poll_event` returns typed `Event` objects instead of raw Hashes. Code using `event[:type]` must change to `event.key?`, `event.code`, etc.
+- **RatatuiRuby.main_loop Removed (Breaking)**: Removed in favor of `RatatuiRuby.run` for more explicit lifecycle control.
+- **TestHelper Terminal Size (Breaking)**: `with_test_terminal` defaults to 80×24 instead of 20×10.
+- **Calendar Month Header Default (Breaking)**: `show_month_header` defaults to `false` (previously always shown). Set `show_month_header: true` if relying on the old behavior.
+- **Gauge `style` Default (Breaking)**: No longer defaults to `Style.default`. Use `gauge_style` for bar coloring instead.
+
+### Fixed
+
+- **Alpine Linux Support**: Fixed gem installation failures on Alpine Linux (musl targets) by properly configuring `crate-type` to support static linking where dynamic linking is unsupported.
+- **Rust Safety**: Convert `class.name()` results to owned strings for proper GC safety with Magnus 0.8.
+- **Terminal Preview Detection**: Detect staged changes correctly in preview generation.
+
 ## [0.3.1] - 2025-12-28
 
 ### Added
@@ -28,10 +246,12 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Added
 
+- **Custom Widget API (Breaking)**: Custom widgets that define a `render` method now receive only `area` (not `buffer`) and must return an array of `Draw` commands. Use `RatatuiRuby::Draw.string(x, y, string, style)` and `RatatuiRuby::Draw.cell(x, y, cell)` instead of `buffer.set_string` and `buffer.set_cell`. This eliminates a class of use-after-free bugs by ensuring Ruby never holds pointers to Rust-owned memory. Widgets can now be unit tested by asserting on the returned array.
 - **The Escape Hatch (Ruby Render Callback)**: Added the ability to define custom widgets in pure Ruby by implementing a `render(area, buffer)` method. The `Buffer` object provides low-level drawing primitives like `set_string`, allowing developers to create custom TUI components without writing Rust code.
 - **Clear Widget**: Added the `Clear` widget, which resets the terminal buffer in the area it is rendered. This is essential for creating opaque popups and modals that prevent background styles from "bleeding" through transparent widgets.
 - **Interactive Table Selection**: The `Table` widget now supports row selection with `selected_row`, `highlight_style`, and `highlight_symbol` parameters. This enables building interactive data grids and file explorers where users can navigate through rows using keyboard input.
 - **Scrollable Paragraphs**: The `Paragraph` widget now supports a `scroll` parameter that accepts a `(y, x)` array to scroll content vertically and horizontally. This enables viewing long text content that exceeds the visible area, such as logs or documents. The parameter order matches ratatui's convention.
+- **Enhanced Tabs Customization**: The `Tabs` widget now supports `highlight_style` for the selected tab and a customizable `divider` string (defaulting to the standard pipe `|`). This allows for richer visual feedback in tabbed interfaces.
 
 ### Changed
 
@@ -65,7 +285,9 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - **Input Handling**: Robust handling for both Keyboard and Mouse events.
 - **Testing Support**: Included `RatatuiRuby::TestHelper` and RSpec integration to make testing your TUI applications possible.
 
-[Unreleased]: https://git.sr.ht/~kerrick/ratatui_ruby/compare/v0.3.1...HEAD
+[Unreleased]: https://git.sr.ht/~kerrick/ratatui_ruby/compare/v0.5.0...HEAD
+[0.5.0]: https://git.sr.ht/~kerrick/ratatui_ruby/compare/v0.4.0...v0.5.0
+[0.4.0]: https://git.sr.ht/~kerrick/ratatui_ruby/compare/v0.3.1...v0.4.0
 [0.3.1]: https://git.sr.ht/~kerrick/ratatui_ruby/compare/v0.3.0...v0.3.1
 [0.3.0]: https://git.sr.ht/~kerrick/ratatui_ruby/compare/v0.2.0...v0.3.0
 [0.2.0]: https://git.sr.ht/~kerrick/ratatui_ruby/compare/v0.1.0...v0.2.0

data/README.md

@@ -9,7 +9,7 @@ builds.sr.ht status](https://builds.sr.ht/~kerrick/ratatui_ruby.svg)](https://bu
 License](https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fgit.sr.ht%2F~kerrick%2Fratatui_ruby%2Fblob%2Fmain%2Fratatui_ruby.gemspec&search=spec%5C.license%20%3D%20%22(.*)%22&replace=%241&label=License&color=a2c93e)](https://spdx.org/licenses/AGPL-3.0-or-later.html) [![
 Gem Total Downloads](https://img.shields.io/gem/dt/ratatui_ruby)](https://rubygems.org/gems/ratatui_ruby) [![
 Gem Version](https://img.shields.io/gem/v/ratatui_ruby)](https://rubygems.org/gems/ratatui_ruby) [![
-Ratatui Version](https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fgit.sr.ht%2F~kerrick%2Fratatui_ruby%2Fblob%2Fmain%2Fext%2Fratatui_ruby%2FCargo.toml&query=%24.dependencies.ratatui.version&prefix=v&logo=ratatui&label=Ratatui)](https://crates.io/crates/ratatui/0.26.3) [![
+Ratatui Version](https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fgit.sr.ht%2F~kerrick%2Fratatui_ruby%2Fblob%2Fmain%2Fext%2Fratatui_ruby%2FCargo.toml&query=%24.dependencies.ratatui.version&prefix=v&logo=ratatui&label=Ratatui)](https://crates.io/crates/ratatui/0.30) [![
 Mailing List: Discussion](https://img.shields.io/badge/mailing_list-discussion-5865F2.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://lists.sr.ht/~kerrick/ratatui_ruby-discuss) [![
 Mailing List: Development](https://img.shields.io/badge/mailing_list-development-4954d5.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://lists.sr.ht/~kerrick/ratatui_ruby-devel) [![
 Mailing List: Announcements](https://img.shields.io/badge/mailing_list-announcements-3b44ac.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://lists.sr.ht/~kerrick/ratatui_ruby-announce)
@@ -20,8 +20,8 @@ Mailing List: Announcements](https://img.shields.io/badge/mailing_list-announcem
 **ratatui_ruby** is a Ruby wrapper for [Ratatui](https://ratatui.rs). It allows you to cook up Terminal User Interfaces in Ruby.
 **ratatui_ruby** is a community wrapper that is not affiliated with [the Ratatui team](https://github.com/orgs/ratatui/people).
 
-> [!WARNING]  
-> **ratatui_ruby** is currently in an early stage of development. Use at your own risk.
+> [!WARNING]
+> **ratatui_ruby** is currently in **BETA**. The API may change between minor versions.
 
 Please join the **announce** mailing list at https://lists.sr.ht/~kerrick/ratatui_ruby-announce to stay up-to-date on new releases and announcements.
 
@@ -65,22 +65,29 @@ gem install ratatui_ruby
 
 ```ruby
 require "ratatui_ruby"
-RatatuiRuby.main_loop do |tui|
-  tui.draw \
-    tui.paragraph \
-        text: "Hello, Ratatui! Press 'q' to quit.",
-        align: :center,
-        block: tui.block(
-          title: "My Ruby TUI App",
-          borders: [:all],
-          border_color: "cyan"
-        )
-  event = tui.poll_event
-  break if event && event[:type] == :key && event[:code] == "q"
+RatatuiRuby.run do |tui|
+  loop do
+    tui.draw do |frame|
+      frame.render_widget(
+        tui.paragraph(
+          text: "Hello, Ratatui! Press 'q' to quit.",
+          alignment: :center,
+          block: tui.block(
+            title: "My Ruby TUI App",
+            borders: [:all],
+            border_color: "cyan"
+          )
+        ),
+        frame.area
+      )
+    end
+    event = tui.poll_event
+    break if event == "q" || event == :ctrl_c
+  end
 end
 ```
 
-For a full tutorial, see [the Quickstart](./doc/quickstart.md).
+For a full tutorial, see [the Quickstart](./doc/quickstart.md). For an explanation of the application architecture, see [Application Architecture](./doc/application_architecture.md).
 
 
 ## Documentation

data/REUSE.toml

@@ -15,3 +15,23 @@ SPDX-License-Identifier = "CC0-1.0"
 path = 'doc/images/*.png'
 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>"
+SPDX-License-Identifier = "AGPL-3.0-or-later"
+
+[[annotations]]
+path = 'test/snapshots/*.txt'
+SPDX-FileCopyrightText = "2025 Kerrick Long <me@kerricklong.com>"
+SPDX-License-Identifier = "AGPL-3.0-or-later"
+
+[[annotations]]
+path = 'examples/app_all_events/test/snapshots/*.txt'
+SPDX-FileCopyrightText = "2025 Kerrick Long <me@kerricklong.com>"
+SPDX-License-Identifier = "AGPL-3.0-or-later"
+
+[[annotations]]
+path = 'test/examples/app_all_events/snapshots/*.txt'
+SPDX-FileCopyrightText = "2025 Kerrick Long <me@kerricklong.com>"
+SPDX-License-Identifier = "AGPL-3.0-or-later"

data/doc/application_architecture.md

@@ -0,0 +1,176 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Application Architecture
+
+Architect robust TUI applications using core lifecycle patterns and API best practices.
+
+## Core Concepts
+
+Your app lives inside a terminal. You need to respect its rules.
+
+### Lifecycle Management
+
+Terminals have state. They remember cursor positions, input modes, and screen buffers.
+
+**The Problem:** If your app crashes or exits without cleaning up, it "breaks" the user's terminal. The cursor vanishes. Input echoes constantly. The alternate screen doesn't clear.
+
+**The Solution:** The library's lifecycle manager handles this for you. It enters "raw mode" on startup and guarantees restoration on exit.
+
+#### Use `RatatuiRuby.run`
+
+This method acts as a safety net. It initializes the terminal, yields control to your block, and restores the terminal afterwards—even if your code raises an exception.
+
+```ruby
+RatatuiRuby.run do |tui|
+  loop do
+    tui.draw do |frame|
+      frame.render_widget(tui.paragraph(text: "Hello"), frame.area)
+    end
+    break if tui.poll_event == "q"
+  end
+end
+# Terminal is restored here
+```
+
+#### Manual Management
+
+Need granular control? You can initialize and restore the terminal yourself. Use `ensure` blocks to guarantee cleanup.
+
+```ruby
+RatatuiRuby.init_terminal
+begin
+  RatatuiRuby.draw do |frame|
+    frame.render_widget(RatatuiRuby::Paragraph.new(text: "Hello"), frame.area)
+  end
+ensure
+  RatatuiRuby.restore_terminal
+  # Terminal is restored here
+end
+```
+
+### API Convenience
+
+Writing UI trees involves nesting many widgets.
+
+**The Problem:** Explicitly namespacing `RatatuiRuby::` for every widget (e.g., `RatatuiRuby::Paragraph.new`) is tedious. It creates visual noise that hides your layout structure.
+
+**The Solution:** The Session API (`tui`) provides shorthand factories for every widget. It yields a session object to your block.
+
+```ruby
+RatatuiRuby.run do |tui|
+  loop do
+    tui.draw do |frame|
+      # Split layout using Session helpes
+      sidebar_area, content_area = tui.layout_split(
+        frame.area,
+        direction: :horizontal,
+        constraints: [
+          tui.constraint_length(20),
+          tui.constraint_min(0)
+        ]
+      )
+
+      # Render sidebar
+      frame.render_widget(
+        tui.paragraph(
+          text: tui.text_line(spans: [
+            tui.text_span(content: "Side", style: tui.style(fg: :blue)),
+            tui.text_span(content: "bar")
+          ]),
+          block: tui.block(borders: [:all], title: "Nav")
+        ),
+        sidebar_area
+      )
+
+      # Render main content
+      frame.render_widget(
+        tui.paragraph(
+          text: "Main Content",
+          style: tui.style(fg: :green),
+          block: tui.block(borders: [:all], title: "Content")
+        ),
+        content_area
+      )
+    end
+    
+    event = tui.poll_event
+    break if event == "q" || event == :ctrl_c
+  end
+end
+```
+
+#### Raw API
+
+Building your own abstractions? You might prefer explicit class instantiation. The raw constants are always available.
+
+```ruby
+RatatuiRuby.run do
+  loop do
+    RatatuiRuby.draw do |frame|
+      # Manual split
+      rects = RatatuiRuby::Layout.split(
+        frame.area,
+        direction: :horizontal,
+        constraints: [
+          RatatuiRuby::Constraint.length(20),
+          RatatuiRuby::Constraint.min(0)
+        ]
+      )
+
+      frame.render_widget(
+        RatatuiRuby::Paragraph.new(
+          text: RatatuiRuby::Text::Line.new(spans: [
+            RatatuiRuby::Text::Span.new(content: "Side", style: RatatuiRuby::Style.new(fg: :blue)),
+            RatatuiRuby::Text::Span.new(content: "bar")
+          ]),
+          block: RatatuiRuby::Block.new(borders: [:all], title: "Nav")
+        ),
+        rects[0]
+      )
+
+      frame.render_widget(
+        RatatuiRuby::Paragraph.new(
+          text: "Main Content",
+          style: RatatuiRuby::Style.new(fg: :green),
+          block: RatatuiRuby::Block.new(borders: [:all], title: "Content")
+        ),
+        rects[1]
+      )
+    end
+
+    event = RatatuiRuby.poll_event
+    break if event == "q" || event == :ctrl_c
+  end
+end
+```
+
+## Reference Architectures
+
+Simple scripts work well with valid linear code. Complex apps need structure.
+
+We provide these reference architectures to inspire you:
+
+### MVVM (Model-View-ViewModel)
+
+**Source:** [examples/app_all_events](../examples/app_all_events/README.md)
+
+This pattern strictly separates concerns:
+*   **Model:** Pure business logic. It handles data and events.
+*   **View State (ViewModel):** An immutable data structure built fresh every frame. It calculates logic-dependent properties (like `border_color`) so the View doesn't have to.
+*   **View:** Pure rendering logic. It takes the View State and draws it.
+
+Use this when your app has complex state rules that clutter your rendering code.
+
+### Scene-Orchestrated MVC
+
+**Source:** [examples/app_color_picker](../examples/app_color_picker/README.md)
+
+This pattern addresses the difficulty of mouse interaction and layout management:
+*   **Scene:** A specialized View that owns the layout *and* hit testing. It caches the screen coordinates of widgets during the draw phase.
+*   **App (Controller):** Handles events by querying the Scene (e.g., `scene.rect_at(x, y)`).
+
+Use this when you need rich interactivity (mouse clicks, drag-and-drop) or complex dynamic layouts.

data/doc/application_testing.md

@@ -44,13 +44,15 @@ Wrap your test assertions in `with_test_terminal`. This sets up a temporary, in-
 
 ```ruby
 def test_rendering
-  # Create a 80x24 terminal
-  with_test_terminal(80, 24) do
-    # 1. Instantiate your app/component
+  # Uses default 80x24 terminal
+  with_test_terminal do
+    # 1. Instantiate your widget
     widget = RatatuiRuby::Paragraph.new(text: "Hello World")
     
-    # 2. Render it
-    RatatuiRuby.draw(widget)
+    # 2. Render it using the Frame API
+    RatatuiRuby.draw do |frame|
+      frame.render_widget(widget, frame.area)
+    end
     
     # 3. Assert on the output
     assert_includes buffer_content[0], "Hello World"
@@ -82,13 +84,18 @@ assert_equal 2, pos[:y]
 
 Injects a mock event into the event queue. This is the preferred way to simulate user input instead of stubbing `poll_event`.
 
+> [!IMPORTANT]
+> You must call `inject_event` inside a `with_test_terminal` block. Calling it outside leads to race conditions where events are flushed before the application starts.
+
 ```ruby
-# Simulate 'q' key press
-inject_event("key", { code: "q" })
+with_test_terminal do
+  # Simulate 'q' key press
+  inject_event("key", { code: "q" })
 
-# Now poll_event will return the 'q' key event
-event = RatatuiRuby.poll_event
-assert_equal "q", event[:code]
+  # Now poll_event will return the 'q' key event
+  event = RatatuiRuby.poll_event
+  assert_equal "q", event.code
+end
 ```
 
 ## Example

data/doc/contributors/design/ruby_frontend.md

@@ -9,6 +9,8 @@ This document describes the design philosophy and structure of the Ruby layer in
 
 ## Core Philosophy: Data-Driven UI
 
+
+
 The Ruby frontend is designed as a **thin, declarative layer** over the Rust backend. It uses an **Immediate Mode** paradigm where the user constructs a tree of pure data objects every frame to represent the desired UI state.
 
 ### 1. View Tree as Data
@@ -41,13 +43,15 @@ The application loop typically looks like this:
 loop do
   # 1. & 2. Handle events and update state
   event = RatatuiRuby.poll_event
-  break if event[:type] == :key && event[:code] == "esc"
-
-  # 3. Construct View Tree
-  ui = RatatuiRuby::Paragraph.new(text: "Time: #{Time.now}")
-
-  # 4. Draw
-  RatatuiRuby.draw(ui)
+  break if event == :esc
+
+  # 3. Construct View Tree & Draw
+  RatatuiRuby.draw do |frame|
+    frame.render_widget(
+      RatatuiRuby::Paragraph.new(text: "Time: #{Time.now}"),
+      frame.area
+    )
+  end
 end
 ```