ratatui_ruby 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 706f0da7ece6637bedb71da9ce2c3bd2b94c357f121fcfd305caa468a2e74637
-  data.tar.gz: 8f0e05bc53177c92a972f7badd9db952e3eb5856413b6b16bc7e41d106ba2652
+  metadata.gz: e9da9703e1573d331115fd1635c1bf0564a6482c8d3d140c7b68230b56da8311
+  data.tar.gz: 41efa864847825eed6d28ee3b9292e923b3f3c97ce28841892a65123df72c16e
 SHA512:
-  metadata.gz: abea59dfb0c71cff7779eee2af7766796a75d1e2499eac3cce40cf901f78ababa453caa1812c70ef44acb88c25a5bb02c9f4e8983d338b79c3b38946f624fd80
-  data.tar.gz: eb01c6a74f469487e782372a86911ae23b7841df1bd42b0820e5e7a9577d891ce3084ae1fb31b7cf3c35d5898e89c37d5fdb8d581b7fabedf52254fc21627be8
+  metadata.gz: efc0e59765a7cfea0108fa79335ae79d4b0bcdb2c9eff93f6e1f5d83dca04724484ce322b45a6d3e6d6cf45f80868a998c9684a8362c3e11b9e1ff02e30eade1
+  data.tar.gz: be4afb8fe1b4bf7ed1ed4757521f8b90f68ca11c101aa69b184eae2de6807a2efa8a59fc2c19d0c47d3ed28f6afd89c906ba6480e824146b2b4ea8e7bc7211fa

data/.builds/ruby-3.2.yml

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

data/AGENTS.md

@@ -19,9 +19,9 @@ Architecture:
 ## Stability & Compatibility
 
 - **Project Status:** Pre-1.0. 
-- **User Base:** 0 users (internal/experimental).
-- **Breaking Changes:** Backward compatibility is **NOT** a priority at this stage. Since there are no external users, you are encouraged to refactor APIs for better ergonomics and performance even if it breaks existing code.
-- **Requirement:** All breaking changes **MUST** be explicitly documented in the [CHANGELOG.md](CHANGELOG.md)'s **Unreleased** section to ensure transparency as the project evolves toward 1.0.
+- **User Base:** First external users (as of 2026-01-03).
+- **Breaking Changes:** Backward compatibility is **NOT YET** a priority. Since there are few external users, you are encouraged to refactor APIs for better ergonomics and performance even if it breaks existing code. This will when we ship v1.0.0.
+- **Requirement:** All breaking changes **MUST** be explicitly documented in the [CHANGELOG.md](CHANGELOG.md)'s **Unreleased** section to ensure transparency as the project evolves toward 1.0. Migration guides **MUST** be included in `doc/` when we release a new minor version.
 
 ## 1. Standards
 
@@ -44,6 +44,12 @@ Architecture:
   - **Usage:**
     - Runs default task (compile + test + lint): `bin/agent_rake`
     - Runs specific task: `bin/agent_rake test:ruby` (for example)
+- **Snapshot Testing:** When tests fail due to intentional behavior changes (not bugs), update snapshots:
+  - **Command:** `UPDATE_SNAPSHOTS=1 bin/agent_rake test:ruby`
+  - This regenerates all `snapshot/*{txt,ansi}` files to match current output
+  - **When to use:** After modifying widget rendering, changing default values, or updating UI behavior
+  - **When NOT to use:** For actual test failures that indicate bugs in your code
+  - After updating, verify the changes make sense by reviewing the diff of `.snapshot` files
 - **Setup:** `bin/setup` must handle both Bundler and Cargo dependencies.
 - **Git:** ALWAYS set `PAGER=cat` with `git`, `git`, etc.. **THIS IS CRITICAL!**
 - **Rake:** Our rake tasks use `git ls-files`, so errors happen when you move or delete files. In this case, ask the user to stage changes for you.
@@ -85,7 +91,7 @@ The project follows a standard Gem layout with an `ext/` directory for Rust code
 
 ## 4. Committing
 
-- Who commits: DON'T stage (DON'T `git add`). DON'T commit. DO suggest a commit message.
+- Who commits: DON'T stage (DON'T `git add`) unless explicitly instructed. DON'T commit unless explicitly instructed. DO suggest a commit message when you finish, even if not instructed..
 - When: Before reporting the task as complete to the user, suggest the commit message.
 - What: Consider not what you remember, but EVERYTHING in the `git diff` and `git diff --cached`.
 - **Format:**

data/CHANGELOG.md

@@ -18,6 +18,76 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Removed
 
+## [0.7.0] - 2026-01-03
+
+> [!WARNING]
+> v0.7.0 contains significant breaking changes. See the [Migration Guide](doc/v0.7.0_migration.md) for upgrade instructions.
+
+### Added
+
+- **Rich Text in Table Cells**: `Table` cells (rows, header, footer) now accept `Text::Span` and `Text::Line` objects for per-character styling, matching List widget capabilities.
+- **Row Wrapper**: New `Widgets::Row` class allows applying row-level styling (background color, style) and layout properties (height, top_margin, bottom_margin) to Table rows. Table rows can now be plain arrays or `Widgets::Row` objects.
+- **Cell Wrapper**: New `Widgets::Cell` class wraps table cell content with optional cell-level styling. Distinct from `Buffer::Cell` which is for buffer inspection.
+- **Line#width Method**: `Text::Line` now has a `width` instance method that calculates the display width in terminal cells using unicode-aware measurement. Useful for layout calculations with rich text.
+- **render_rich_buffer**: New `TestHelper::Snapshot#render_rich_buffer` method returns the terminal buffer as an ANSI-encoded string with escape codes for colors and modifiers. Useful for debugging, custom assertions, or programmatic inspection beyond `assert_rich_snapshot`.
+
+### Changed
+
+- **Namespace Restructure (Breaking)**: Classes reorganized to match Ratatui's module hierarchy. See [Migration Guide](doc/v0.7.0_migration.md) for details:
+  - `RatatuiRuby::Rect` → `RatatuiRuby::Layout::Rect`
+  - `RatatuiRuby::Constraint` → `RatatuiRuby::Layout::Constraint`
+  - `RatatuiRuby::Layout` → `RatatuiRuby::Layout::Layout`
+  - `RatatuiRuby::Style` → `RatatuiRuby::Style::Style`
+  - `RatatuiRuby::Paragraph` → `RatatuiRuby::Widgets::Paragraph`
+  - `RatatuiRuby::Block` → `RatatuiRuby::Widgets::Block`
+  - `RatatuiRuby::Table` → `RatatuiRuby::Widgets::Table`
+  - `RatatuiRuby::List` → `RatatuiRuby::Widgets::List`
+  - *(and all other widgets)*
+- **Session → TUI Rename (Breaking)**: `RatatuiRuby::Session` renamed to `RatatuiRuby::TUI` to better reflect its role as a facade/DSL. The `TUI` class now uses explicit factory methods (no metaprogramming) for improved IDE autocomplete support.
+- **Buffer::Cell vs Widgets::Cell (Breaking)**: `RatatuiRuby::Cell` (buffer inspection) renamed to `RatatuiRuby::Buffer::Cell`. New `RatatuiRuby::Widgets::Cell` added for table cell construction.
+- **Text::Line style field (Breaking)**: `Text::Line` now accepts a `style:` parameter for line-level styling, matching Ratatui's `Line` struct which has `style`, `alignment`, and `spans` fields.
+- **Table highlight_style → row_highlight_style (Breaking)**: `Table` parameter `highlight_style:` renamed to `row_highlight_style:` to match Ratatui's API naming convention.
+
+### Fixed
+
+### Removed
+
+## [0.6.0] - 2026-01-03
+
+### Added
+
+- **Rich Text Support**: `List`, `Gauge`, `LineGauge`, and `BarChart` widgets now accept rich text objects (`Text::Span`, `Text::Line`) in addition to plain strings. This enables per-character styling, multi-colored labels, and complex text formatting matching Ratatui 0.30.0 capabilities.
+- **ListItem Wrapper**: New `ListItem` data class allows applying row-level styling (background color) independent of text content. `List` items can now be `String`, `Text::Span`, `Text::Line`, or `ListItem` objects.
+- **Non-Blocking Event Polling**: `RatatuiRuby.poll_event` now accepts an optional `timeout:` parameter (Float seconds). Use `timeout: 0.0` for non-blocking checks, or `timeout: 0.1` for fixed timesteps. Defaults to `0.016` (16ms) to preserve existing behavior.
+- **Cursor Positioning**: `Frame#set_cursor_position(x, y)` sets the terminal's hardware cursor position. Using this method is essential for input fields where the user expects visual feedback on their cursor location.
+- **Text Measurement**: `RatatuiRuby::Text.width(string)` calculates the display width of a string in terminal cells, correctly handling unicode including ASCII (1 cell), CJK full-width characters (2 cells), emoji (typically 2 cells), and zero-width combining marks (0 cells). This is essential for auto-sizing widgets and responsive layouts. Delegates to the same unicode-width logic that Ratatui uses internally.
+- **Scroll Offset Control**: `List` and `Table` widgets now accept an optional `offset` parameter to control the viewport's scroll position. Use this for passive scrolling (viewing without selection) or calculating click-to-item mappings. When combined with a selection, Ratatui's natural scrolling may still adjust the viewport to keep the selection visible; set selection to `nil` for fully manual scroll control.
+- **Rect Geometry Helpers**: `Rect#intersects?(other)` tests whether two rectangles overlap. `Rect#intersection(other)` returns the overlapping area as a new `Rect`, or `nil` if disjoint. Essential for viewport clipping and hit testing in component architectures.
+- **Stateful Rendering**: `Frame#render_stateful_widget(widget, area, state)` renders widgets with mutable state objects (`ListState`, `TableState`, `ScrollbarState`). State objects persist across frames, enabling scroll offset read-back and selection tracking. Essential for mouse click-to-row hit testing. **Precedence rule:** State object properties override widget properties (`selected_index`, `offset`).
+- **Full Keyboard Support**: Key events now recognize all keys supported by crossterm: function keys (`f1`–`f24`), navigation (`home`, `end`, `page_up`, `page_down`, `insert`, `delete`), locks (`caps_lock`, `scroll_lock`, `num_lock`), system (`print_screen`, `pause`, `menu`), media controls (`play`, `play_pause`, `track_next`, etc.), and individual modifier keys (`left_shift`, `right_control`, etc.). Previously unmapped keys returned `"unknown"`; they now return proper `snake_case` strings.
+- **Key Categories**: `Event::Key` now has a `kind` attribute (`:standard`, `:function`, `:media`, `:modifier`, `:system`) for logical grouping. Category predicates (`media?`, `system?`, `function?`, `modifier?`, `standard?`) enable clean event routing without string parsing. The `unmodified?` method is an alias for `standard?`.
+- **Smart Predicates (DWIM)**: Key predicates now "Do What I Mean" for media keys. `pause?` returns `true` for both system `pause` and `media_pause` keys. For strict matching, use `media_pause?` or compare `event.code` directly. This reduces boilerplate when responding to conceptual actions regardless of input method.
+- **Modifier Key Predicates**: New methods `super?`, `hyper?`, and `meta?` check for these modifier keys. Platform aliases are provided for `super?`: `command?`/`cmd?` (macOS), `win?` (Windows), and `tux?` (Linux). These work for both modifier flags AND individual modifier key events (e.g., `left_super`). Additionally, `control?` aliases `ctrl?` and `option?` aliases `alt?`.
+- **Navigation Aliases**: Convenient predicate aliases for common keys: `return?` for Enter, `back?` for Backspace, `del?` for Delete, `ins?` for Insert, `escape?` for Esc, `pgup?`/`pageup?` for Page Up, `pgdn?`/`pagedown?` for Page Down. The special `reverse_tab?` predicate matches both the `back_tab` key and `shift+tab` combinations.
+- **Indexed Color Support**: `Style` now supports `Integer` values for `fg` and `bg`, allowing use of the Xterm 256-color palette (0-255). This includes standard ANSI colors (0-15), the 6x6x6 color cube (16-231), and the grayscale ramp (232-255).
+- **Rich Snapshots**: `RatatuiRuby::TestHelper#assert_rich_snapshot` validates both content and styling by comparing against stored ANSI snapshots. This allows for visual regression testing that respects colors, bold, italics, and other terminal modifiers.
+- **Semantic Style Assertions**: New testing helpers `assert_color(expected, x:, y:)`, `assert_cell_style(x, y, **style)`, and `assert_area_style(area, **style)` allow precise verification of terminal cell attributes without full-screen snapshots. Punchy convenience aliases like `assert_fg`/`assert_bg`, `assert_bold`, `assert_italic`, `assert_underlined`, and color-specific assertions (e.g., `assert_red`, `assert_bg_blue`) provide a more natural API for common testing patterns.
+- **Buffer Debugging**: `RatatuiRuby::TestHelper#print_buffer` outputs the current terminal state to STDOUT with full ANSI color support, making it easier to debug rendering issues during test execution.
+
+
+### Changed
+
+- **Frozen Data Objects (Breaking)**: Events returned by `RatatuiRuby.poll_event` and `Cell` objects from `RatatuiRuby.get_cell_at` are now deeply frozen for Ractor compatibility. Code that mutates these objects (e.g., `event.modifiers << "custom"`) must copy the data before modifying. `Rect` was already frozen. Note: `Frame` and `Session` are *I/O handles* with side effects and remain intentionally non-shareable.
+- **Semantic Exceptions (Breaking)**: Replaced generic `RuntimeError` with `RatatuiRuby::Error::Terminal` for backend/terminal failures and `RatatuiRuby::Error::Safety` for API contract violations (like using `Frame` outside `draw`). This allows finer-grained error handling but breaks code explicitly rescuing `RuntimeError`. `ArgumentError` works as before.
+- **Media Key Codes (Breaking)**: All media key codes now use a consistent `media_` prefix: `play` → `media_play`, `stop` → `media_stop`, `play_pause` → `media_play_pause`, etc. Code comparing against literal media key strings must be updated. Use the Smart Predicates (`play?`, `stop?`) for backward-compatible behavior.
+- **`Key#char` Return Value (Breaking)**: `char` now returns `nil` for non-printable keys (previously returned `""`). Code relying on `event.char.empty?` must change to `event.char.nil?` or use `event.text?` instead.
+
+### Fixed
+
+- **Frame Safety**: Calling methods on a `Frame` stored outside of a `draw` block now correctly raises a `RatatuiRuby::Error::Safety` (subclass of `RatatuiRuby::Error`) instead instead of causing undefined behavior or crashes. This ensures memory safety by preventing use-after-free scenarios with the underlying Rust frame.
+
+### Removed
+
 ## [0.5.0] - 2026-01-01
 
 ### Added
@@ -285,10 +355,12 @@ 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.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
-[0.1.0]: https://git.sr.ht/~kerrick/ratatui_ruby/tree/v0.1.0
+[Unreleased]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/HEAD
+[0.7.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.7.0
+[0.6.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.6.0
+[0.5.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.5.0
+[0.4.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.4.0
+[0.3.1]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.3.1
+[0.3.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.3.0
+[0.2.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.2.0
+[0.1.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.1.0

data/README.md

@@ -23,7 +23,9 @@ Mailing List: Announcements](https://img.shields.io/badge/mailing_list-announcem
 > [!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.
+**[Why RatatuiRuby?](./doc/why.md)** — Native Rust performance, zero runtime overhead, and Ruby's expressiveness. [See how we compare](./doc/why.md) to CharmRuby, raw Rust, and Go.
+
+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. See the [`trunk` branch](https://git.sr.ht/~kerrick/ratatui_ruby/tree/trunk) for pre-release updates.
 
 
 ## Compatibility
@@ -63,8 +65,8 @@ gem install ratatui_ruby
 
 **ratatui_ruby** uses an immediate-mode API. You describe your UI using Ruby objects and call `draw` in a loop.
 
+<!-- SYNC:START:examples/verify_readme_usage/app.rb:main -->
 ```ruby
-require "ratatui_ruby"
 RatatuiRuby.run do |tui|
   loop do
     tui.draw do |frame|
@@ -81,18 +83,46 @@ RatatuiRuby.run do |tui|
         frame.area
       )
     end
-    event = tui.poll_event
-    break if event == "q" || event == :ctrl_c
+    case tui.poll_event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      break
+    else
+      nil
+    end
   end
 end
 ```
+<!-- SYNC:END -->
+
+![Hello Ratatui](./doc/images/verify_readme_usage.png)
 
 For a full tutorial, see [the Quickstart](./doc/quickstart.md). For an explanation of the application architecture, see [Application Architecture](./doc/application_architecture.md).
 
 
+## Features
+
+**ratatui_ruby** gives you 20+ widgets out of the box:
+
+| Category | Widgets |
+|----------|---------|
+| **Data Display** | Table, List, Chart, Bar Chart, Sparkline, Calendar |
+| **Layout** | Block, Tabs, Scrollbar, Center, Overlay, Clear |
+| **Input** | Gauge, Line Gauge |
+| **Text** | Paragraph, Rich Text (Spans + Lines), Cursor |
+| **Canvas** | Shapes (Line, Circle, Rectangle, Map), Custom Drawing |
+
+Plus: flexible layouts with constraints, full keyboard/mouse/paste/resize events, snapshot testing, and hex/RGB/256-color support.
+
+
 ## Documentation
 
-For the full documentation on how to use **ratatui_ruby**, see the [documentation](./doc/index.md).  For other information, see the [wiki](https://man.sr.ht/~kerrick/ratatui_ruby).
+| Resource | Description |
+|----------|-------------|
+| [Quickstart](./doc/quickstart.md) | Get running in 5 minutes |
+| [Widget Gallery](./doc/quickstart.md#widget-demos) | Every widget with examples |
+| [Application Architecture](./doc/application_architecture.md) | Patterns for scaling your app |
+| [API Reference](./doc/index.md) | Full RDoc documentation |
+| [Wiki](https://man.sr.ht/~kerrick/ratatui_ruby) | Guides and community resources |
 
 
 ## Contributing
@@ -103,6 +133,8 @@ Issues for the underlying Rust library should be filed at [ratatui/ratatui](http
 
 Want to help develop **ratatui_ruby**? Check out the [contribution guide on the wiki](https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md).
 
+**Note**: Active development happens on the `trunk` branch. Use `trunk` if you are a contributor or want the latest cutting-edge features. `stable` is for stable releases only.
+
 
 ## Copyright & License
 

data/REUSE.toml

@@ -22,16 +22,11 @@ SPDX-FileCopyrightText = "2025 Kerrick Long <me@kerricklong.com>"
 SPDX-License-Identifier = "AGPL-3.0-or-later"
 
 [[annotations]]
-path = 'test/snapshots/*.txt'
+path = '**/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'
+path = '**/snapshots/*.ansi'
 SPDX-FileCopyrightText = "2025 Kerrick Long <me@kerricklong.com>"
 SPDX-License-Identifier = "AGPL-3.0-or-later"

data/doc/application_architecture.md

@@ -44,7 +44,7 @@ Need granular control? You can initialize and restore the terminal yourself. Use
 RatatuiRuby.init_terminal
 begin
   RatatuiRuby.draw do |frame|
-    frame.render_widget(RatatuiRuby::Paragraph.new(text: "Hello"), frame.area)
+    frame.render_widget(RatatuiRuby::Widgets::Paragraph.new(text: "Hello"), frame.area)
   end
 ensure
   RatatuiRuby.restore_terminal
@@ -52,13 +52,48 @@ ensure
 end
 ```
 
+### Stateful Widgets
+
+Most widgets are stateless configuration. You create them, render them, and they are gone. However, the **runtime status** of some widgets (like Lists and Tables) must persist across frames (e.g., scroll offsets or selection).
+
+**The Problem:** If you re-create a List configuration every frame, you lose the context of where it was scrolled or what was selected. If Ratatui auto-scrolls to a selection, you can't read that new offset back from an immutable input widget.
+
+**The Solution:** Use "Stateful Rendering". You create a mutable State object (Output/Status) once and pass it to `render_stateful_widget`. **The Widget configuration (Input) is still mandatory**, but the State object (passed separately) captures the runtime changes.
+
+> [!IMPORTANT]
+> **Precedence Rule:** When using `render_stateful_widget`, the **State object is the single source of truth** for selection and offset. Widget properties (`selected_index`, `selected_row`, `offset`) are **ignored**.
+>
+> For example: `list(selected_index: 0)` with `state.select(5)` → Item 5 is highlighted, not Item 0.
+
+**Use Case:** When you need to read back the scroll offset (e.g., for mouse hit testing) or persist selection without managing indexes manually.
+
+```ruby
+# Initialize state once
+@list_state = RatatuiRuby::ListState.new
+
+RatatuiRuby.run do |tui|
+  loop do
+    tui.draw do |frame|
+      # Create immutable widget (selected_index is ignored in stateful mode)
+      list = tui.list(items: ["A", "B", "C"])
+      
+      # Render with state — state takes precedence
+      frame.render_stateful_widget(list, frame.area, @list_state)
+    end
+    
+    # Read back offset calculated by Ratatui
+    puts "Current Scroll Offset: #{@list_state.offset}"
+  end
+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 Problem:** Explicitly namespacing `RatatuiRuby::` for every widget (e.g., `RatatuiRuby::Widgets::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.
+**The Solution:** The TUI API (`tui`) provides shorthand factories for every widget. It yields a TUI object to your block.
 
 ```ruby
 RatatuiRuby.run do |tui|
@@ -112,31 +147,31 @@ RatatuiRuby.run do
   loop do
     RatatuiRuby.draw do |frame|
       # Manual split
-      rects = RatatuiRuby::Layout.split(
+      rects = RatatuiRuby::Layout::Layout.split(
         frame.area,
         direction: :horizontal,
         constraints: [
-          RatatuiRuby::Constraint.length(20),
-          RatatuiRuby::Constraint.min(0)
+          RatatuiRuby::Layout::Constraint.length(20),
+          RatatuiRuby::Layout::Constraint.min(0)
         ]
       )
 
       frame.render_widget(
-        RatatuiRuby::Paragraph.new(
+        RatatuiRuby::Widgets::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: "Side", style: RatatuiRuby::Style::Style.new(fg: :blue)),
             RatatuiRuby::Text::Span.new(content: "bar")
           ]),
-          block: RatatuiRuby::Block.new(borders: [:all], title: "Nav")
+          block: RatatuiRuby::Widgets::Block.new(borders: [:all], title: "Nav")
         ),
         rects[0]
       )
 
       frame.render_widget(
-        RatatuiRuby::Paragraph.new(
+        RatatuiRuby::Widgets::Paragraph.new(
           text: "Main Content",
-          style: RatatuiRuby::Style.new(fg: :green),
-          block: RatatuiRuby::Block.new(borders: [:all], title: "Content")
+          style: RatatuiRuby::Style::Style.new(fg: :green),
+          block: RatatuiRuby::Widgets::Block.new(borders: [:all], title: "Content")
         ),
         rects[1]
       )
@@ -148,29 +183,68 @@ RatatuiRuby.run do
 end
 ```
 
+## Thread and Ractor Safety
+
+Building for Ruby 4.0's parallel future? Know which objects can travel between Ractors.
+
+### Data Objects (Shareable)
+
+These are deeply frozen and `Ractor.shareable?`. Include them in immutable Models/Messages freely:
+
+| Object | Source |
+|--------|--------|
+| `Event::*` | `poll_event` |
+| `Cell` | `get_cell_at` |
+| `Rect` | `Layout.split`, `Frame#area` |
+
+### I/O Handles (Not Shareable)
+
+These have side effects and are intentionally not shareable:
+
+| Object | Valid Usage |
+|--------|-------------|
+| `TUI` | Cache in `@tui` during run loop. Don't include in Models. |
+| `Frame` | Pass to helpers during draw block. Invalid after block returns. |
+
+```ruby
+# Good: Cache session in instance variable
+RatatuiRuby.run do |tui|
+  @tui = tui
+  loop { render; handle_input }
+end
+
+# Bad: Include in immutable Model (won't work with Ractors)
+Model = Data.define(:tui, :count)  # Don't do this
+```
+
+
 ## 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)
+### Model-View-Update
 
 **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.
+This pattern implements unidirectional data flow inspired by The Elm Architecture:
+*   **Model:** A single immutable `Data.define` object holding all application state.
+*   **Msg:** Semantic value objects that decouple raw events from business logic.
+*   **Update:** A pure function that computes the next state: `Update.call(msg, model) -> Model`.
+*   **View:** Pure rendering logic that accepts the immutable Model.
 
-Use this when your app has complex state rules that clutter your rendering code.
+Use this when you want predictable state management and easy-to-test logic.
 
-### Scene-Orchestrated MVC
+### Component-Based
 
 **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)`).
+This pattern addresses the difficulty of mouse interaction and complex UI orchestration:
+*   **Component Contract:** Every UI element implements `render(tui, frame, area)` and `handle_event(event)`.
+*   **Encapsulated Hit Testing:** Components cache their render area and check `contains?` internally.
+*   **Symbolic Signals:** `handle_event` returns semantic symbols (`:consumed`, `:submitted`) instead of just booleans.
+*   **Container (Mediator):** A parent container routes events via Chain of Responsibility and coordinates cross-component effects.
 
 Use this when you need rich interactivity (mouse clicks, drag-and-drop) or complex dynamic layouts.
+

data/doc/application_testing.md

@@ -8,15 +8,11 @@ This guide explains how to test your RatatuiRuby applications using the provided
 
 ## Overview
 
-RatatuiRuby includes a `TestHelper` module designed to simplify unit testing of TUI applications. It allows you to:
+You need to verify that your application looks and behaves correctly. Manually checking every character on a terminal screen is tedious. Dealing with race conditions and complex state management in tests creates friction.
 
-- Initialize a virtual "test terminal" with specific dimensions.
+The `TestHelper` module solves this. It provides a headless "test terminal" to capture output and a suite of robust assertions to verify state.
 
-- Capture the rendered output (the "buffer") to assert against expected text.
-
-- Inspect the cursor position.
-
-- Simulate user input (using `inject_event`).
+Use it to write fast, deterministic tests for your TUI applications.
 
 ## Setup
 
@@ -36,18 +32,20 @@ class MyApplicationTest < Minitest::Test
 end
 ```
 
-## Basic Usage
+## Writing a View Test
 
-### `with_test_terminal`
+To test a view or widget, wrap your assertions in `with_test_terminal`. This sets up a temporary, in-memory backend for Ratatui to draw to.
 
-Wrap your test assertions in `with_test_terminal`. This sets up a temporary, in-memory backend for Ratatui to draw to, instead of the real terminal. It automatically cleans up afterwards.
+1.  **Initialize the terminal:** Call `with_test_terminal`.
+2.  **Render your code:** Instantiate your widget and draw it to a frame.
+3.  **Assert output:** Check the `buffer_content` against your expectations.
 
 ```ruby
 def test_rendering
   # Uses default 80x24 terminal
   with_test_terminal do
     # 1. Instantiate your widget
-    widget = RatatuiRuby::Paragraph.new(text: "Hello World")
+    widget = RatatuiRuby::Widgets::Paragraph.new(text: "Hello World")
     
     # 2. Render it using the Frame API
     RatatuiRuby.draw do |frame|
@@ -55,49 +53,97 @@ def test_rendering
     end
     
     # 3. Assert on the output
-    assert_includes buffer_content[0], "Hello World"
+    assert_includes buffer_content.first, "Hello World"
   end
 end
 ```
 
-### `buffer_content`
+For the full API list, including `buffer_content` and `cursor_position`, see [RatatuiRuby::TestHelper::Terminal](../lib/ratatui_ruby/test_helper/terminal.rb).
 
-Returns the current state of the terminal as an Array of Strings. Useful for verifying that specific text appears where you expect it.
-
-```ruby
-rows = buffer_content
-assert_equal "Title", rows[0].strip
-assert_match /Results: \d+/, rows[2]
-```
+## Verifying Styles
 
-### `cursor_position`
+You often need to check colors and modifiers (bold, italic) to ensure your highlighting logic works.
 
-Returns the current cursor coordinates as `{ x: Integer, y: Integer }`. Useful for forms or ensuring focus is correct.
+Use `assert_fg_color`, `assert_bg_color`, and modifier helpers like `assert_bold`.
 
 ```ruby
-pos = cursor_position
-assert_equal 5, pos[:x]
-assert_equal 2, pos[:y]
+# Assert specific cell style
+assert_fg_color(:red, 0, 0)
+assert_bold(0, 0)
+
+# Or check a whole area
+assert_area_style({ x: 0, y: 0, w: 10, h: 1 }, bg: :blue)
 ```
 
-### `inject_event`
+See [RatatuiRuby::TestHelper::StyleAssertions](../lib/ratatui_ruby/test_helper/style_assertions.rb) for the comprehensive list of style helpers.
+
+## Simulating Input
+
+You need to test user interactions like typing or clicking. Stubbing `poll_event` directly is brittle.
 
-Injects a mock event into the event queue. This is the preferred way to simulate user input instead of stubbing `poll_event`.
+Use `inject_event` to push mock events into the queue. This ensures safe, deterministic handling of input.
 
 > [!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.
+> Call `inject_event` inside a `with_test_terminal` block to avoid race conditions.
 
 ```ruby
 with_test_terminal do
   # Simulate 'q' key press
   inject_event("key", { code: "q" })
 
-  # Now poll_event will return the 'q' key event
+  # The application receives the 'q' event
   event = RatatuiRuby.poll_event
   assert_equal "q", event.code
 end
 ```
 
+See [RatatuiRuby::TestHelper::EventInjection](../lib/ratatui_ruby/test_helper/event_injection.rb) for helper methods like `inject_keys` and `inject_click`.
+
+## Snapshot Testing
+
+Snapshots let you verify complex layouts without manually asserting every line.
+
+Use `assert_snapshot` to compare the current screen against a stored reference file.
+
+```ruby
+with_test_terminal do
+  MyApp.new.run
+  assert_snapshot("dashboard_view")
+end
+```
+
+### Handling Non-Determinism
+
+Snapshots must be deterministic. Random data or current timestamps will cause test failures ("flakes").
+
+To prevent this:
+1.  **Seed Randomness:** Use a fixed seed for any RNG.
+2.  **Stub Time:** Force the application to use a static time.
+
+For detailed strategies and code examples, see [RatatuiRuby::TestHelper::Snapshot](../lib/ratatui_ruby/test_helper/snapshot.rb).
+
+## Isolated View Testing
+
+Sometimes you want to test a single view component without spinning up the full `TestTerminal` engine.
+
+Use `MockFrame` and `StubRect` to test render logic in isolation.
+
+```ruby
+def test_logs_view
+  frame = RatatuiRuby::TestHelper::TestDoubles::MockFrame.new
+  area = RatatuiRuby::TestHelper::TestDoubles::StubRect.new(width: 40, height: 10)
+  
+  # Call your view directly
+  MyView.new.render(frame, area)
+  
+  # Inspect what was rendered
+  rendered = frame.rendered_widgets.first
+  assert_equal "Logs", rendered[:widget].block.title
+end
+```
+
+See [RatatuiRuby::TestHelper::TestDoubles](../lib/ratatui_ruby/test_helper/test_doubles.rb).
+
 ## Example
 
-Be sure to check out the [examples directory](../examples/) in the repository, which contains several fully tested example applications showcasing these patterns.
+Check out the [examples directory](../examples/) for fully tested applications showcasing these patterns.