ratatui_ruby 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 706f0da7ece6637bedb71da9ce2c3bd2b94c357f121fcfd305caa468a2e74637
-  data.tar.gz: 8f0e05bc53177c92a972f7badd9db952e3eb5856413b6b16bc7e41d106ba2652
+  metadata.gz: c8e3aed93d74250af44d1b7169dcf7d31575b8b6a24c65d40b4067edb1cf46ea
+  data.tar.gz: e5f3d70e418bc9af98a1926838030aa934b13f64d617ed5c5a1809e91d17d72a
 SHA512:
-  metadata.gz: abea59dfb0c71cff7779eee2af7766796a75d1e2499eac3cce40cf901f78ababa453caa1812c70ef44acb88c25a5bb02c9f4e8983d338b79c3b38946f624fd80
-  data.tar.gz: eb01c6a74f469487e782372a86911ae23b7841df1bd42b0820e5e7a9577d891ce3084ae1fb31b7cf3c35d5898e89c37d5fdb8d581b7fabedf52254fc21627be8
+  metadata.gz: c1742d63643a1ebef6063097e3755e819da39354b631d70ba72ead21d48d8a9199a5421184698fb41a56ee0991a7411adfbcf125f6ec9e18aa980eeb6d4e03fe
+  data.tar.gz: 995f166470814f6ec2a0e073bc658eb52b5a5381a5c19539d4b6ef575e601eb3ac8c3b000a23b4c226b6708a5387024b71a84c43cd69a5240f538aca261a815b

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.6.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.6.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.6.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.6.0.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/AGENTS.md

@@ -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.

data/CHANGELOG.md

@@ -18,6 +18,42 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### 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 +321,11 @@ 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.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,7 @@ 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.
+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 +63,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,11 +81,16 @@ 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 -->
 
 For a full tutorial, see [the Quickstart](./doc/quickstart.md). For an explanation of the application architecture, see [Application Architecture](./doc/application_architecture.md).
 
@@ -103,6 +108,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

@@ -52,6 +52,41 @@ 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.
@@ -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 TEA 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 |
+|--------|-------------|
+| `Session` | 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)
+### Proto-TEA (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
+### Proto-Kit (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,11 +32,13 @@ 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
@@ -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.

data/doc/contributors/design/ruby_frontend.md

@@ -13,13 +13,16 @@ This document describes the design philosophy and structure of the Ruby layer in
 
 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
+### 1. Separation of Configuration and Status
 
-Unlike traditional OO GUI toolkits (like Qt or Swing) where widgets are retained objects with internal state, `ratatui_ruby` widgets are immutable value objects.
+`ratatui_ruby` strictly separates **what** a widget is (Configuration) from **where** it is (Status).
+
+#### Configuration (Input)
+Widgets (e.g., `RatatuiRuby::List`) are immutable value objects defining the *desired appearance* for the current frame. They are pure inputs to the renderer.
 
 *   Implemented using Ruby 3.2+ `Data` classes.
 *   Located in `lib/ratatui_ruby/schema/`.
-*   These objects act as a Schema or Interface Definition Language (IDL) between Ruby and Rust.
+*   Act as a Schema/IDL between Ruby and Rust.
 
 **Example:**
 ```ruby
@@ -31,6 +34,39 @@ paragraph = RatatuiRuby::Paragraph.new(
 )
 ```
 
+#### Status (Output)
+**Optional.** Only specific widgets (like `List` and `Table`) rely on runtime status. State objects (e.g., `RatatuiRuby::ListState`) track metrics calculated by the backend, such as scroll offsets.
+
+*   passed as a *secondary argument* to `render_stateful_widget`.
+*   **The Widget Configuration is still required.** You cannot render a State without its corresponding Widget.
+*   Updated in-place by the Rust backend to reflect the actual rendered state.
+
+**Example:**
+```ruby
+# 1. Initialize State once (Input/Output)
+list_state = RatatuiRuby::ListState.new
+list_state.select(3)
+
+RatatuiRuby.run do |tui|
+  loop do
+    tui.draw do |frame|
+      # 2. Define Configuration (Input)
+      # (Note: In a real app, you'd probably use `tui.list(...)` helper)
+      list = RatatuiRuby::List.new(items: ["A", "B", "C", "D"])
+      
+      # 3. Render with both (Side Effect: updates list_state)
+      frame.render_stateful_widget(list, frame.area, list_state)
+    end
+    
+    # 4. Read back Status (Output)
+    # If the backend auto-scrolled to keep index 3 visible:
+    puts "Scroll Offset: #{list_state.offset}"
+    
+    break if tui.poll_event == "q"
+  end
+end
+```
+
 ### 2. Immediate Mode Rendering
 
 The application loop typically looks like this:

data/doc/contributors/design/rust_backend.md

@@ -16,6 +16,7 @@ The project follows a **Structured Design** approach, separating concerns into m
 1.  **Single Generic Renderer**: The backend implements a single generic renderer that accepts a Ruby `Value` representing the root of the view tree.
 2.  **No Custom Rust Structs for UI**: Do not define custom Rust structs that mirror Ruby UI components. Instead, extract data directly from Ruby objects using `funcall`.
 3.  **Dynamic Dispatch**: Use `value.class().name()` (e.g., `"RatatuiRuby::Paragraph"`) to dynamically dispatch rendering logic to the appropriate widget module.
+    *   *Exception:* `render_stateful_widget` bypasses generic dispatch for specific Widget/State pairs (e.g., List + ListState) to allow mutating the State object.
 4.  **Immediate Mode**: The renderer traverses the Ruby object tree every frame and rebuilds the Ratatui widget tree on the fly.
 
 ### Module Structure