ratatui_ruby 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f566d7a4eb721ae0c356c7f19f60b5a91a2dd908d03b3711c655cbe61c6410b8
-  data.tar.gz: dd5fddbd898e842aef046aab8f58c85f507418edfccc6d7ff903b129329b3d3e
+  metadata.gz: c8e3aed93d74250af44d1b7169dcf7d31575b8b6a24c65d40b4067edb1cf46ea
+  data.tar.gz: e5f3d70e418bc9af98a1926838030aa934b13f64d617ed5c5a1809e91d17d72a
 SHA512:
-  metadata.gz: c24e93fb6fc88103b336eef4283c5d434f2625529e0a2aac8b5951fb8ae52c5ac05009beef8f72e6acd4a38534bb7b075bb21cc469c039d198b3f7fd87cfa8e7
-  data.tar.gz: 8ac6aaf12d96cba46f4ae9f6af3f7fb5e0ad9bdfacda6bef381d31a857c0f9d8c65cd7fb079f22e2961a31dad68f39744dfe7d3842b9e0e879ba568f0e820d3a
+  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.4.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.4.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.4.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.4.0.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.6.0.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/AGENTS.md

@@ -13,203 +13,125 @@ Description: A high-performance Ruby wrapper for the Ratatui TUI library.
 
 Architecture:
 
--   **Frontend (Ruby):** Pure `Data` objects (Ruby 3.2+) defining the View Tree. Immediate mode.
--   **Backend (Rust):** A generic renderer using `ratatui` and `magnus` that traverses the Ruby `Data` tree and renders to the terminal buffer.
+- **Frontend (Ruby):** Pure `Data` objects (Ruby 3.2+) used in Frames and/or defining the View Tree. Immediate mode.
+- **Backend (Rust):** A generic renderer using `ratatui` and `magnus` that traverses the Ruby `Data` tree and renders to the terminal buffer.
 
 ## 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.
-
-## 1. File & Coding Standards
-
-### Licensing & Copyright (Strict)
-
-Every file must begin with an SPDX-compliant header. Use the following format:
-
-```ruby
-# frozen_string_literal: true
-
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
-```
-
--   **Ruby/Rust/Config files:** Use comments appropriate for the language (`#` or `//`).
--   **Markdown:** Use HTML comment style `<!-- -->`.
--   **Exceptions:** `REUSE.toml` manages exceptions (e.g., binary files or `.gitignore`).
+- **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.
+
+## 1. Standards
+
+### STRICT REQUIREMENTS
+
+- Every file MUST begin with an SPDX-compliant header. Use `AGPL-3.0-or-later` for code; `CC-BY-SA-4.0` for documentation. `reuse annotate` can help you generate the header.
+- Every line of Ruby MUST be covered by tests that would stand up to mutation testing.
+  - Tests must be meaningful and verify specific behavior or rendering output; simply verifying that code "doesn't crash" is insufficient and unacceptable.
+  - For UI widgets, this means using `with_test_terminal` to verify EVERY character of the terminal buffer's content.
+- Every line of Rust MUST be covered by tests that would stand up to mutation testing.
+  - Tests must be meaningful; simply verifying that code "doesn't crash" or "compiles" is insufficient and unacceptable.
+  - Each widget implementation must have a `tests` module with unit tests verifying basic rendering.
+- **Pre-commit:** Use `bin/agent_rake` to ensure commit-readiness. See Tools for detailed instructions.
+- **Git Pager:** ALWAYS set `PAGER=cat` for ALL `git` commands (e.g., `PAGER=cat git diff`). This is mandatory.
+
+### Tools
+
+- **NEVER** run `bundle exec rake` directly. **NEVER** run `bundle exec ruby -Ilib:test ...` directly.
+- **ALWAYS use `bin/agent_rake`** for running tests, linting, or checking compilation.
+  - **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.
 
 ### Ruby Standards
 
--   **Version:** Tested against the latest releases of Ruby 3.2, 3.3, 3.4, and 4.0, and must work on all of them. Local development happens on the latest stable release.
--   **Linter & Testing (CRITICAL):**
-    -   **ALWAYS use `bin/agent_rake`** for running tests, linting, or checking compilation.
-    -   **NEVER** run `bundle exec rake` directly. **NEVER** run `bundle exec ruby -Ilib:test ...` directly.
-    -   **VIOLATION OF THIS RULE IS A CRITICAL ERROR.**
-    -   **Why?**
-        1.  **Noise Reduction:** Standard `rake` output includes massive amounts of Rust compilation noise that floods your context window, truncating the actual error message. `bin/agent_rake` captures this silently.
-        2.  **Atomic Dump:** Agents work best with a single "Atomic Dump" of the failure. `bin/agent_rake` provides this by swallowing successful output and only printing the failure log if something goes wrong.
-        3.  **Merged Output:** It correctly merges stdout (Minitest failures) and stderr (Rust warnings) so you see them in temporal order.
-    -   **Usage:**
-        -   Runs default task (compile + test + lint): `bin/agent_rake`
-        -   Runs specific task: `bin/agent_rake test:ruby` (for example)
-    -   **Interpretation:** If the User says "rake test fails" or "fix the build" or "bin/agent_rake fails", they IMPLICITLY mean "run `bin/agent_rake` and fix the reported errors". Do not ask for clarification; just use `bin/agent_rake`.
--   **Style:**
-    -   Use `Data.define` for all value objects (UI Nodes). (Prefer `class Foo < Data.define()` over `Foo = Data.define() do`).
-    -   Prefer `frozen_string_literal: true`.
-    -   Use `Minitest` for testing.
-    -   Define types in `.rbs` files. Don't use `untyped` just because it's easy; be comprehensive and accurate. Do not include `initialize` in `.rbs` files; use `self.new` for constructors instead.
-    -   Every line of Ruby must be covered by tests that would stand up to mutation testing. This includes all examples in the `examples/` directory; they should have corresponding tests in `examples/` to ensure they continue to work as intended and serve as reliable documentation. Tests must be meaningful and verify specific behavior or rendering output; simply verifying that code "doesn't crash" is insufficient and unacceptable. For UI widgets, this means using `with_test_terminal` to verify every character of the terminal buffer's content.
-    -   Every public Ruby class/method must be documented for humans in RDoc (preferred)--**not** YARD--or markdown files (fallback), and must have `*.rbs` types defined.
-    -   Every significant architectural and design decision must be documented for contributors in markdown files. Mermaid is allowed.
+- Use `Data.define` for all value objects (UI Nodes). (Prefer `class Foo < Data.define()` over `Foo = Data.define() do`).
+- Define types in `.rbs` files. Don't use `untyped` just because it's easy; be comprehensive and accurate. Do not include `initialize` in `.rbs` files; use `self.new` for constructors instead.
+- Every public Ruby class/method must be documented for humans in RDoc (preferred)--**not** YARD--or markdown files (fallback), and must have `*.rbs` types defined.
+- Every significant architectural and design decision must be documented for contributors in markdown files. Mermaid is allowed.
+- **Rust-backed methods:** For methods implemented in Rust (magnus bindings), use RDoc directives instead of empty method bodies. Use `##` followed by `:method:`, `:call-seq:`, and prose. End with `(Native method implemented in Rust)`. See `lib/ratatui_ruby.rb` for examples.
+- Refer to [docs/contributors/design/ruby_frontend.md](docs/contributors/design/ruby_frontend.md) for detailed design philosophy regarding the Immediate Mode paradigm including Data-Driven UI and Frames.
 
 ### Rust Standards
 
--   **Crate Type:** `cdylib`.
--   **Linter:** `clippy` and `rustfmt`.
--   **Bindings:** Use [magnus](https://github.com/matsadler/magnus).
--   **Platform:** Support macOS (Apple Silicon), Linux, and Windows.
--   **Linker Flags:** Must handle macOS `-undefined dynamic_lookup`.
--   Every line of Rust must be covered by tests that would stand up to mutation testing. This includes every widget implementation in `ext/ratatui_ruby/src/widgets/`; each must have a `tests` module with unit tests verifying basic rendering. Tests must be meaningful; simply verifying that code "doesn't crash" or "compiles" is insufficient.
+- **Crate Type:** `cdylib`.
+- **Bindings:** Use [magnus](https://github.com/matsadler/magnus).
+- **Platform:** Support macOS (Apple Silicon), Linux, and Windows.
+- Refer to [docs/contributors/design/rust_backend.md](docs/contributors/design/rust_backend.md) for detailed implementation guidelines, module structure, and rendering logic.
 
 ## 2. Directory Structure Convention
 
-The project follows a standard Gem layout with an `ext/` directory for Rust code.
-
-```plaintext
-/
-├── .cargo/                 # Cargo configuration (linker flags)
-├── .github/                # CI/CD workflows
-├── bin/                    # Executables (console, setup)
-├── doc/                    # Documentation source (markdown for RDoc)
-│   ├── contributors/       # Design docs, ecosystem notes
-│   └── index.md
-├── ext/
-│   └── ratatui_ruby/       # RUST SOURCE CODE GOES HERE
-│       ├── src/
-│       │   └── lib.rs      # Entry point
-│       ├── Cargo.toml
-│       └── extconf.rb      # Makefile generator
-├── lib/
-│   ├── ratatui_ruby/
-│   │   ├── schema/         # Ruby Data definitions
-│   │   └── version.rb
-│   └── ratatui_ruby.rb     # Main loader
-├── test/
-│   ├── data/               # Data-driven test files
-│   └── ratatui_ruby/       # Unit tests
-├── vendor/                 # Vendorized style configs (goodcop)
-├── AGENTS.md               # Context for AI agents
-├── Gemfile
-├── Rakefile
-├── REUSE.toml              # Compliance definition
-└── ratatui_ruby.gemspec
-```
+The project follows a standard Gem layout with an `ext/` directory for Rust code and `examples/` for example application-level code.
 
 ## 3. Configuration & Tooling
 
 ### Development Environment
 
--   **Setup:** `bin/setup` must handle both Bundler and Cargo dependencies.
--   **Pre-commit:** Use `bin/agent_rake` to ensure commit-readiness. See Ruby Standards for detailed instructions.
 
 ### Documentation
 
--   **The `doc/` folder contains source markdown files** that are included in RDoc output. Follow the structure: `index.md` -> `contributors/` | `quickstart.md`.
--   **The `tmp/rdoc/` folder is auto-generated** by `bundle exec rake rerdoc`. Never edit files in `tmp/rdoc/` directly.
--   Documentation should separate "User Guide" (Ruby API for TUI developers) from "Contributor Guide" (Ruby/Rust/Magnus internals).
--   **Style Guide:** You **MUST** follow the [Documentation Style Guide](doc/contributors/documentation_style.md). This dictates the Alexandrian/Zinsser prose style and strict RDoc formatting required for all public API documentation.
--   Don't write .md files for something RDoc (Ruby) or rustdoc (Rust) can generate.
-
-## 4. The Ruby <-> Rust Bridge Contract
-
-### The Ruby Side (`lib/`)
-
--   Refer to [docs/contributors/design/ruby_frontend.md](docs/contributors/design/ruby_frontend.md) for detailed design philosophy regarding the Data-Driven UI and Immediate Mode paradigm.
-
-### The Rust Side (`ext/`)
-
--   Refer to [docs/contributors/design/rust_backend.md](docs/contributors/design/rust_backend.md) for detailed implementation guidelines, module structure, and rendering logic.
-
-## 5. Deployment / Release
-
--   The gem builds a native extension.
--   Artifact naming: Ensure the output shared library matches Ruby's expectation on macOS (rename `.dylib`to `.bundle` if necessary during the build process in `extconf.rb` or `Rakefile`).
-
-## 6. Commit Message
-
--   **Commits:**
-    -   Who commits: Only humans should affect the git index and history. Do not stage (do not `git add`). Do not commit. Just suggest a commit message.
-    -   When: At the end of each task, before reporting the task as complete to the user, suggest the commit message.
-    -   What: Consider not just what you remember, but also everything in the `git diff` and `git diff --cached`.
--   **Format:**
-    -   Format: Use [Conventional Commits](https://www.conventionalcommits.org/).
-        -   Structure: `type(scope): description` (e.g., `feat(widget): add Gauge widget`).
-        -   Subject line: Concise summary (50 chars or less).
-    -   Body: Explanation if necessary (wrap at 72 chars).
-        -   Explain why this is the implementation, as opposed to other possible implementations.
-        -   Skip the body entirely if it's rote, a duplication of the diff, or otherwise unhelpful.
-        -   **DO NOT list the files changed or the edits made in the body.** Do not provide a bulleted list of changes. Use prose to explain the problem and the solution.
-        -   **Do not use markdown syntax** (no backticks, no bolding, no lists, no links), except as required in AI Attribution. The commit message must be plain text.
-    -   Footer: AI attribution if generated by an agent, sourcehut ticket if implemented by a ticket, or both.
--   **AI Attribution:**
-     -   **Always include AI attribution** in the footer if the commit was generated or significantly assisted by an AI agent. This is mandatory for transparency and compliance. **This is NOT optional.**
-     -   **Amp:**
-         ```
-         Generated with [Amp](https://ampcode.com)
-
-         Co-Authored-By: Amp <noreply@ampcode.com>
-         ```
-     -   **Antigravity:**
-         Specify the model used in the footer. Examples:
-         ```
-         Generated with [Antigravity](https://antigravity.google)
-
-         Co-Authored-By: Gemini 3 Pro (High) <noreply@google.com>
-         ```
-         ```
-         Generated with [Antigravity](https://antigravity.google)
-
-         Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
-         ```
-     -   **Gemini 3:**
-         ```
-         Generated with [Gemini 3 Pro](https://gemini.google.com/)
-
-         Co-Authored-By: Gemini 3 Pro <noreply@google.com>
-         ```
-     -   **JetBrains Junie:**
-         ```
-         Generated with [JetBrains Junie](https://www.jetbrains.com/ai/)
-
-         Co-Authored-By: Junie <junie@jetbrains.com>
-         ```
--   **Sourcehut Tickets:**
-    - If the commit implements a specific ticket, include a footer: `Implements: https://todo.sr.ht/~kerrick/ratatui_ruby/<id>`
-    - **Do NOT** include this footer if you were not given a specific ticket ID or URL. Do not hallucinate or guess ticket URLs.
-    - This must be the **last** item in the footer, if present.
-
-## 7. Definition of Done
+- **The `doc/` folder contains source markdown files** that are included in RDoc output.
+- Documentation should separate "User Guide" (Ruby API for TUI developers) from "Contributor Guide" (Ruby/Rust/Magnus internals).
+  - Files within `doc/contributors/` are for library developers.
+  - Files within `doc/` outside of `conttributors/` are for application developers and users of this RubyGEm.
+- **Style Guide:** You **MUST** follow the [Documentation Style Guide](doc/contributors/documentation_style.md). This dictates the Alexandrian/Zinsser prose style and strict RDoc formatting required for all public API documentation.
+- DON'T write .md files for something RDoc (Ruby) or rustdoc (Rust) can generate. DO use RDoc and rustdoc for documentation.
+
+
+## 4. Committing
+
+- Who commits: DON'T stage (DON'T `git add`). DON'T commit. DO suggest a commit message.
+- 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:**
+    - Format: Use [Conventional Commits](https://www.conventionalcommits.org/).
+    - Body: Explanation if necessary (wrap at 72 chars).
+        - Explain why this is the implementation, as opposed to other possible implementations.
+        - Skip the body entirely if it's rote, a duplication of the diff, or otherwise unhelpful.
+        - **DON'T list the files changed or the edits made in the body.** Don't provide a bulleted list of changes. Use prose to explain the problem and the solution.
+        - **DON'T use markdown syntax** (no backticks, no bolding, no lists, no links). The commit message must be plain text.
+  
+### 5. Changelog
+
+- Follow [Semantic Versioning](https://semver.org/)
+- Follow the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) specification.
+- **What belongs in CHANGELOG:** Only changes that affect **application developers** or **higher-level library developers** who use or depend on `ratatui_ruby`:
+    - New public APIs or widget parameters
+    - Backwards-incompatible type signature changes, or behavioral additions to type signature changes
+    - Observable behavior changes (rendering, styling, layout)
+    - Deprecations and removals
+    - Breaking changes
+- **What does NOT belong in CHANGELOG:** Internal or non-behavioral changes that don't affect downstream users:
+    - Test additions or improvements
+    - Documentation updates, RDoc fixes, markdown clarifications
+    - Refactors of internal code
+    - New or modified example code
+    - Internal tooling, CI/CD, or build configuration changes
+    - Code style or linting changes
+    - Performance improvements that affect applications
+- Changelogs should be useful to downstream developers (both app and library developers), not simple restatements of diffs or commit messages.
+- The Unreleased section MUST be considered "since the last git tag". Therefore, if a change was done in one commit and undone in another (both since the last tag), the second commit should remove its changelog entry.
+- **Location:** New entries ALWAYS go in `## [Unreleased]`. Never edit past version sections (e.g., `## [0.4.0]`)—those are frozen history.
+
+## 6. Definition of Done (DoD)
 
 Before considering a task complete and returning control to the user, you **MUST** ensure:
 
-1.  **Default Rake Task Passes:** Run `bin/agent_rake` to execute **ALL** tests and linting. Do not rely on partial test runs, or `rake test`, or `rake lint` alone. Confirm it passes with no new errors **or warnings**.
-2.  **Documentation Updated:** If public APIs or observable behavior changed, update relevant `doc/` files, `README.md`, and/or `ratatui_ruby-wiki` files,.
-3.  **Changelog Updated:** If public APIs, observable behavior, or gemspec dependencies changed, update [CHANGELOG.md](CHANGELOG.md)'s **Unreleased** section according to the [Semantic Versioning](https://semver.org/) and [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) specifications. 
-    - **What belongs in CHANGELOG:** Only changes that affect **application developers** or **library developers** who use or depend on ratatui_ruby:
-      - New public APIs or widget parameters
-      - Observable behavior changes (rendering, styling, layout)
-      - Deprecations and removals
-      - Breaking changes
-      - New public examples (if they demonstrate significant features)
-      - Performance improvements that affect applications
-    - **What does NOT belong in CHANGELOG:** Internal changes that don't affect downstream users:
-      - Test additions or improvements
-      - Documentation updates, RDoc fixes, markdown clarifications
-      - Refactors of internal code
-      - New or modified example code (unless the example itself is a major feature)
-      - Internal tooling, CI/CD, or build configuration changes
-      - Code style, linting, or type signature changes
-    - Changelogs should be useful to downstream developers (both app and library developers), not simple restatements of diffs or commit messages.
+1.  **Default Rake Task Passes:** Run `bin/agent_rake` (no args). Confirm it passes with ZERO errors **or warnings**.
+  - You will save time if you run `bin/agent_rake rubocop:autocorrect` first.
+  - If you think the build is looking for deleted files, it is not. Instead, tell the user and **ask them to stage changes**.
+2.  **Documentation Updated:** If public APIs or observable behavior changed, update relevant RDoc, rustdoc, `doc/` files, `README.md`, and/or `ratatui_ruby-wiki` files.
+3.  **Changelog Updated:** If public APIs, observable behavior, or gemspec dependencies have changed, update [CHANGELOG.md](CHANGELOG.md)'s **Unreleased** section.
 4.  **Commit Message Suggested:** You **MUST** ensure the final message to the user includes a suggested commit message block. This is NOT optional.
+  - You MUST also remind the user to add an AI attribution footer.

data/CHANGELOG.md

@@ -18,6 +18,78 @@ 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
+
+#### 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
@@ -249,9 +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.4.0...HEAD
-[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

@@ -20,10 +20,10 @@ 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]  
+> [!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,12 +63,13 @@ 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 \
-      tui.paragraph \
+    tui.draw do |frame|
+      frame.render_widget(
+        tui.paragraph(
           text: "Hello, Ratatui! Press 'q' to quit.",
           alignment: :center,
           block: tui.block(
@@ -76,11 +77,20 @@ RatatuiRuby.run do |tui|
             borders: [:all],
             border_color: "cyan"
           )
-    event = tui.poll_event
-    break if event == "q" || event == :ctrl_c
+        ),
+        frame.area
+      )
+    end
+    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).
 
@@ -98,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

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