ratatui_ruby 0.7.1 → 0.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4fc5e88c5e6146ec1aeae7816aeb8bea73926aaf90d5b2df75fa58d5c6490ab0
-  data.tar.gz: 90ec60b887d797c1cd8b8f06ca41506dbf8a463abc554c20b7caab8ec537b496
+  metadata.gz: f76aaa4da70206d5855ab0d4d7a9356bd57117c1d4ff6d243e86db8bb6e53be9
+  data.tar.gz: 88b96b0a71f595d7ca4b255d90f29b3aac3e2fcc02f323d2db9adfaa233bf4a0
 SHA512:
-  metadata.gz: 3d6fdbb5c4c2970210f70cb0f16c0f40eca871afd6cc115cc5e744e9b85aed01b2c7209baabbb4b2e7129f6ddf460f1add31a6612070a8ef239fbb1e5e2893bd
-  data.tar.gz: ffef16474856ead4d0754dcd6f26104b795a6c2d8aac962df73d7f6c468d4fc6ad7c769a68bb97c1ad3fecc487973afbb50764c555f0a8385addf14864d5c22c
+  metadata.gz: 9d8bc1bc8aa2ae2625302e0024f83c6b30459551377f111e9703e9ed9f70fe0c79cc5cd6af57d9770bd5cc7ecfc93e9e8472f7ebde314b1c989a9cff87110bba
+  data.tar.gz: b0d285b610e38669c9c764b492e384ae2e9f84739b5572096d70a74818b4ce87f2025c06d9055e55e3e7966c8f0ba9768533ba683ea232a3a77a224ac716f8ed

data/.builds/ruby-3.2.yml

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

data/AGENTS.md

@@ -27,10 +27,11 @@ Architecture:
 
 ### 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 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. **For Ruby files**, wrap SPDX comments in `#--` / `#++` to hide them from RDoc output.
 - 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.
+  - **Prefer snapshot tests** (`assert_snapshots`, plural) over manual `buffer_content` assertions for UI widgets. Snapshots are self-documenting and easier to maintain.
+  - For UI widgets, use `with_test_terminal` and snapshot assertions to verify terminal buffer 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.
@@ -78,6 +79,7 @@ The project follows a standard Gem layout with an `ext/` directory for Rust code
 
 ### Development Environment
 
+- **Scripting Preference:** Simple `sed` or shell one-liners are fine. When a one-off script grows to multiple lines of logic, prefer a temporary rake task or `ruby -e '...'` over a multi-line shell script in a string. Ruby's `File.read`/`File.write`, `Dir.glob`, and regex handle complex transformations more cleanly.
 
 ### Documentation
 
@@ -101,6 +103,12 @@ The project follows a standard Gem layout with an `ext/` directory for Rust code
         - 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.
+- **Type conventions by directory:**
+    - `lib/`, `ext/`, `sig/`: Use `feat`, `fix`, `refactor`, `perf` as appropriate.
+    - `bin/`, `tasks/`, `.builds/`, CI/CD: Always `chore` (internal tooling).
+    - `examples/`: Always `docs` (documentation by example).
+    - `test/`: Use `test` for new/changed tests, or match the type of the code being tested.
+    - `doc/`: Always `docs`.
   
 ### 5. Changelog
 
@@ -130,8 +138,8 @@ Before considering a task complete and returning control to the user, you **MUST
 
 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**.
+  - If you think the build is looking for deleted files, it is not. Instead, explain to the user why staging is needed and use the `run_command` tool with `git add -A` so they get a Run button with context.
 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.
+  - You MUST also check `git log -n1` to see the current standard AI footer ("Generated  with" and "Co-Authored-By") and include it in your suggested message.

data/CHANGELOG.md

@@ -12,10 +12,57 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Added
 
+- **Block Inner Area Calculation**: `Block#inner(area)` method computes the inner content area given an outer `Rect`, accounting for borders and padding. Essential for layout calculations when you need to know usable space inside a block.
+- **Deferred Warnings During TUI Sessions**: Experimental feature warnings (like `Paragraph#line_count`) are now automatically queued during active TUI sessions and flushed to stderr after `restore_terminal`. This prevents warnings from corrupting the TUI display. See `doc/troubleshooting/tui_output.md` for details on handling terminal output during TUI sessions.
+- **Session State Tracking**: `RatatuiRuby.terminal_active?` indicates whether a TUI session is active. Calling `init_terminal` or `init_test_terminal` while a session is already active now raises `Error::Invariant`.
+- **Error::Invariant**: New error class for state invariant violations (e.g., double-init). Distinct from `Error::Safety` (lifetime violations) and `Error::Terminal` (operational I/O failures).
 ### Changed
 
 ### Fixed
 
+- **Direct Text Rendering**: `Text::Line` and `Text::Span` can now be rendered directly as widgets via `frame.render_widget(line, area)` without wrapping in a `Paragraph`. Previously, these text primitives were silently ignored when passed to `render_widget`.
+- **Text Line Alignment**: `Text::Line` `alignment:` parameter is now respected during rendering. Previously, the alignment was ignored and text always rendered left-aligned.
+
+### Removed
+
+## [0.7.3] - 2026-01-04
+
+### Added
+
+- **Symbol Shortcuts for `bar_set`**: `Sparkline` and `BarChart` now accept `:nine_levels` (full 9-character gradient) and `:three_levels` (simplified empty/half/full) as intuitive shortcuts instead of requiring custom character hashes.
+- **`:half_block` Marker**: `Chart` `Dataset` now supports `:half_block` marker for higher resolution rendering using ▀ and ▄ characters.
+- **`assert_snapshots` Method**: `RatatuiRuby::TestHelper#assert_snapshots` (plural) calls both `assert_plain_snapshot` and `assert_rich_snapshot` with the same name, generating both `.txt` and `.ansi` files for documentation and display purposes.
+- **Edge-Center Legend Positions**: `Chart` `legend_position` now accepts `:top`, `:bottom`, `:left`, and `:right` in addition to the existing corner positions (`:top_left`, `:top_right`, `:bottom_left`, `:bottom_right`).
+- **`:reset` Color**: `Style` `fg` and `bg` now accept `:reset` to explicitly clear any inherited foreground or background color, restoring the terminal's default.
+
+### Changed
+
+### Deprecated
+
+- **`assert_snapshot`**: Use `assert_snapshots` (plural) instead, or `assert_plain_snapshot` if you only need plain text. The old method name lacked clarity about whether it captured plain text or styled ANSI output.
+
+### Fixed
+
+### Removed
+
+## [0.7.2] - 2026-01-04
+
+### Added
+
+- **Tabs `padding_left` and `padding_right`**: Now accept `Integer` (for spaces), `String`, or `Text::Line` for styled padding content. Previously only accepted `Integer`. Passing a `Line` object allows colored or decorated padding.
+
+### Changed
+
+### Fixed
+
+- **Styled Text Parsing**: Fixed multiple widgets incorrectly rendering styled text objects as Ruby inspect strings (e.g., `#<data RatatuiRuby::Text::Span...>`) instead of their styled content:
+  - `Tabs` `divider`: Now correctly renders `Text::Span` objects.
+  - `Table` `highlight_symbol`: Now correctly renders `Text::Span` objects.
+  - `BarChart` `BarGroup` `label`: Now correctly renders `Text::Line` objects.
+  - `Chart` `Axis` `title`: Now correctly renders `Text::Line` objects.
+  - `Chart` `Axis` `labels`: Now correctly renders `Text::Line` objects.
+  - `Chart` `Dataset` `name`: Now correctly renders `Text::Line` objects.
+
 ### Removed
 
 ## [0.7.1] - 2026-01-03
@@ -368,6 +415,8 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - **Testing Support**: Included `RatatuiRuby::TestHelper` and RSpec integration to make testing your TUI applications possible.
 
 [Unreleased]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/HEAD
+[0.7.3]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.7.3
+[0.7.2]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.7.2
 [0.7.1]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.7.1
 [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

data/README.md

@@ -6,10 +6,10 @@
 
 [![
 builds.sr.ht status](https://builds.sr.ht/~kerrick/ratatui_ruby.svg)](https://builds.sr.ht/~kerrick/ratatui_ruby?) [![
-License](https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fgit.sr.ht%2F~kerrick%2Fratatui_ruby%2Fblob%2Fmain%2Fratatui_ruby.gemspec&search=spec%5C.license%20%3D%20%22(.*)%22&replace=%241&label=License&color=a2c93e)](https://spdx.org/licenses/AGPL-3.0-or-later.html) [![
+License](https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fgit.sr.ht%2F~kerrick%2Fratatui_ruby%2Fblob%2Fstable%2Fratatui_ruby.gemspec&search=spec%5C.license%20%3D%20%22(.*)%22&replace=%241&label=License&color=a2c93e)](https://spdx.org/licenses/AGPL-3.0-or-later.html) [![
 Gem Total Downloads](https://img.shields.io/gem/dt/ratatui_ruby)](https://rubygems.org/gems/ratatui_ruby) [![
 Gem Version](https://img.shields.io/gem/v/ratatui_ruby)](https://rubygems.org/gems/ratatui_ruby) [![
-Ratatui Version](https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fgit.sr.ht%2F~kerrick%2Fratatui_ruby%2Fblob%2Fmain%2Fext%2Fratatui_ruby%2FCargo.toml&query=%24.dependencies.ratatui.version&prefix=v&logo=ratatui&label=Ratatui)](https://crates.io/crates/ratatui/0.30) [![
+Ratatui Version](https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fgit.sr.ht%2F~kerrick%2Fratatui_ruby%2Fblob%2Fstable%2Fext%2Fratatui_ruby%2FCargo.toml&query=%24.dependencies.ratatui.version&prefix=v&logo=ratatui&label=Ratatui)](https://crates.io/crates/ratatui/0.30) [![
 Mailing List: Discussion](https://img.shields.io/badge/mailing_list-discussion-5865F2.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://lists.sr.ht/~kerrick/ratatui_ruby-discuss) [![
 Mailing List: Development](https://img.shields.io/badge/mailing_list-development-4954d5.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://lists.sr.ht/~kerrick/ratatui_ruby-devel) [![
 Mailing List: Announcements](https://img.shields.io/badge/mailing_list-announcements-3b44ac.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://lists.sr.ht/~kerrick/ratatui_ruby-announce)
@@ -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.
 
-**[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.
+**[Why RatatuiRuby?](./doc/getting_started/why.md)** — Native Rust performance, zero runtime overhead, and Ruby's expressiveness. [See how we compare](./doc/getting_started/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.
 
@@ -96,7 +96,7 @@ 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).
+For a full tutorial, see [the Quickstart](./doc/getting_started/quickstart.md). For an explanation of the application architecture, see [Application Architecture](./doc/concepts/application_architecture.md).
 
 
 ## Features
@@ -118,9 +118,9 @@ Plus: flexible layouts with constraints, full keyboard/mouse/paste/resize events
 
 | 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 |
+| [Quickstart](./doc/getting_started/quickstart.md) | Get running in 5 minutes |
+| [Widget Gallery](./doc/getting_started/quickstart.md#widget-demos) | Every widget with examples |
+| [Application Architecture](./doc/concepts/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 |
 

data/Rakefile

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

data/doc/{application_architecture.md → concepts/application_architecture.md}

@@ -52,6 +52,36 @@ ensure
 end
 ```
 
+#### Signal Handling
+
+External processes send signals. Your TUI must handle them gracefully.
+
+**The Problem:** If a signal terminates your process before `restore_terminal` runs, the terminal stays in raw mode. Your shell becomes unusable until you type `reset` and press Enter (the text won't echo, but it works).
+
+**The Solution:** Ruby's default signal handlers work correctly with `ensure` blocks. Most signals unwind the stack, which triggers cleanup.
+
+| Signal | Source | Terminal Restored? |
+|--------|--------|--------------------|
+| SIGTERM | `kill -15` | ✓ Yes — ensure runs |
+| SIGINT | `kill -2` (not Ctrl+C) | ✓ Yes — ensure runs |
+| SIGKILL | `kill -9` | ✗ No — cannot be caught |
+
+> [!IMPORTANT]
+> **Ctrl+C in Raw Mode:** When your app is in raw mode, pressing Ctrl+C does *not* send SIGINT. It's captured as a `:ctrl_c` key event. Handle this in your event loop—don't use `trap("INT")`.
+
+```ruby
+RatatuiRuby.run do |tui|
+  loop do
+    # ...
+    event = tui.poll_event
+    break if event == :ctrl_c  # Handle Ctrl+C yourself
+  end
+end
+```
+
+**Recovery:** If a TUI app leaves your terminal broken, run `reset` in the shell to restore normal behavior.
+
+
 ### 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).

data/doc/{application_testing.md → concepts/application_testing.md}

@@ -103,15 +103,17 @@ See [RatatuiRuby::TestHelper::EventInjection](../lib/ratatui_ruby/test_helper/ev
 
 Snapshots let you verify complex layouts without manually asserting every line.
 
-Use `assert_snapshot` to compare the current screen against a stored reference file.
+Use `assert_snapshots` to compare the current screen against stored reference files.
 
 ```ruby
 with_test_terminal do
   MyApp.new.run
-  assert_snapshot("dashboard_view")
+  assert_snapshots("dashboard_view")
 end
 ```
 
+This generates both `.txt` (plain text) and `.ansi` (styled) snapshot files. The `.ansi` files contain ANSI escape codes—`cat` them in a terminal to see exactly what the screen looked like. For a visual tour of your test suite, try `cat **/*.ansi` in any shell that supports globbing.
+
 ### Handling Non-Determinism
 
 Snapshots must be deterministic. Random data or current timestamps will cause test failures ("flakes").

data/doc/{event_handling.md → concepts/event_handling.md}

@@ -4,7 +4,7 @@ SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 SPDX-License-Identifier: AGPL-3.0-or-later
 -->
 
-# Event Handling in RatatuiRuby
+# Event Handling
 
 `ratatui_ruby` provides a rich, object-oriented event system that supports multiple coding styles, from simple boolean predicates to modern Ruby pattern matching.
 

data/doc/contributors/auditing/parity.md

@@ -0,0 +1,233 @@
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Parity Auditing Process
+
+This guide describes the **process** for auditing RatatuiRuby against upstream Rust Ratatui to find API parity gaps of any kind.
+
+## Philosophy
+
+RatatuiRuby should behave identically to Rust Ratatui. When a Rust user can do something with a widget, a Ruby user should be able to do the equivalent. Deviations are bugs.
+
+## The Audit Mindset
+
+### Ask the Right Questions
+
+Every audit begins with a question:
+
+- "Does RatatuiRuby support everything upstream supports for widget X?"
+- "When I pass type Y to parameter Z, does Ruby do what Rust does?"
+- "Are there features in upstream that we haven't exposed at all?"
+
+### Symptoms That Trigger Audits
+
+- **Inspect strings in output** (`#<data RatatuiRuby::...>`) — type conversion failure
+- **Missing methods** — user can't access upstream functionality
+- **Wrong behavior** — code runs but produces different results than Rust
+- **Type mismatches** — Ruby API accepts different types than Rust API
+
+## The Three-Layer Model
+
+Every RatatuiRuby feature has three layers. Gaps can occur at any layer:
+
+```
+┌─────────────────────────────┐
+│  Ruby API (lib/**/*.rb)    │  ← What users see
+├─────────────────────────────┤
+│  Rust Bindings (ext/**/*.rs)│  ← Bridge layer
+├─────────────────────────────┤
+│  Upstream Ratatui          │  ← Source of truth
+└─────────────────────────────┘
+```
+
+### Layer 1: Ruby API Gaps
+Ruby doesn't expose a parameter that upstream supports.
+
+### Layer 2: Binding Gaps  
+Ruby exposes a parameter, but the Rust binding converts it incorrectly.
+
+### Layer 3: Upstream Changes
+New upstream features we haven't implemented yet.
+
+## Audit Process
+
+### 1. Choose an Audit Scope
+
+Define what you're auditing:
+- **Single widget**: All parameters of `Tabs`
+- **Single feature**: All places that accept styled text
+- **Version delta**: Everything new in Ratatui 0.29
+
+### 2. Establish Source of Truth
+
+For any scope, identify the authoritative upstream source:
+- **Method signatures** → Rust source files
+- **Type constraints** → Generic bounds (`Into<Line>`, `&str`, etc.)
+- **Behavior** → Upstream documentation and tests
+
+### 3. Inventory Our Implementation
+
+List everything in our codebase related to the scope:
+- Ruby classes and methods
+- Rust binding functions
+- Conversion/parsing logic
+
+### 4. Compare Systematically
+
+For each item in the upstream source of truth, ask:
+1. Do we expose this at all?
+2. If yes, does our implementation match the type signature?
+3. If yes, does our behavior match?
+
+### 5. Document Findings
+
+For each gap found, record:
+- What the gap is
+- Where it occurs (files, lines)
+- What upstream expects
+- What we currently do
+
+### 6. Fix and Verify
+
+Apply fixes, then verify:
+- Compiles without errors
+- Tests pass
+- Visual/manual verification if applicable
+
+## Verifying Completeness
+
+Finding gaps is not enough. You must verify you've found **all** gaps within your scope.
+
+### The Completeness Mindset
+
+An initial audit pass often finds the obvious issues. But "obvious" means "incomplete." After your first pass, stop and ask:
+
+- Did I search for **every variation** of the pattern I was looking for?
+- Are there **synonyms or related terms** I should also search?
+- Did I check **all code paths**, not just the happy path?
+- Are there **duplicate implementations** (e.g., `render` vs `render_stateful`)?
+
+### Broaden Your Search Terms
+
+Your first search term won't catch everything. For each pattern, think of variations:
+
+| If you searched for... | Also search for... |
+|------------------------|-------------------|
+| `funcall("to_s"` | `String::try_convert` |
+| `Into<Line>` | `Into<Span>`, `Into<Text>` |
+| One widget's file | All widget files |
+| The method you're fixing | Related methods in the same file |
+
+### Work From the Complete List
+
+Don't spot-check. Generate the **complete list** of potential issues, then classify each one:
+
+1. Run a search that catches all possible instances
+2. Count them (e.g., "31 `to_s` call sites")
+3. Review **every single one**, marking each as "gap" or "correct"
+
+Half-measures lead to half-fixes.
+
+### Verify Against Upstream Exhaustively
+
+For type-related gaps, don't just check the methods you already know about. Search upstream for **all uses of the pattern**:
+
+- `grep -rn 'Into<Line' /path/to/ratatui/src/widgets` finds EVERY place upstream accepts `Line`
+- Then verify we handle EACH of those correctly
+
+### Question Your Assumptions
+
+After completing your audit, challenge yourself:
+
+- "Is there anywhere I should look that I haven't?"
+- "Is there any term I should search that I haven't?"
+- "Am I sure I didn't miss anything?"
+
+If you can't answer confidently, keep searching.
+
+### The "One More Pass" Rule
+
+When you think you're done, do one more verification pass with a different approach:
+
+- If you searched our code first, now search upstream first
+- If you searched for method names, now search for type signatures
+- If you audited file-by-file, now audit feature-by-feature
+
+This catches gaps your initial framing missed.
+
+
+## Search Strategies
+
+Different gap types require different search approaches:
+
+### Finding Type Conversion Gaps
+
+Look for places where we convert Ruby objects to simpler types:
+- `funcall("to_s", ...)` — converting to string
+- `String::try_convert(...)` — same
+- `u16::try_convert(...)` — numeric conversion
+
+Then check: does upstream accept richer types?
+
+### Finding Missing Features
+
+Compare file structure:
+- What files/modules exist upstream?
+- What methods exist in each upstream struct?
+- What parameters does each upstream method accept?
+
+### Finding Behavioral Differences
+
+Run equivalent code in both environments and compare output.
+
+## Red Flags in Our Code
+
+When reviewing RatatuiRuby code, these patterns suggest potential gaps:
+
+| Pattern | Potential Gap |
+|---------|---------------|
+| `funcall("to_s", ...)` | Upstream may accept styled types |
+| `usize` or `u16` for padding | Upstream may accept content types |
+| Missing `parse_*` call before using a value | Type not being converted properly |
+| Widget with fewer Ruby methods than Rust methods | Missing functionality |
+| `// TODO` or `// FIXME` comments | Known gaps |
+
+## Upstream Patterns to Watch For
+
+When reading upstream Rust code, these signatures indicate rich type support:
+
+| Rust Signature | Meaning | Ruby Should Accept |
+|----------------|---------|-------------------|
+| `Into<Span<'a>>` | Styled single fragment | `Text::Span` or `String` |
+| `Into<Line<'a>>` | Styled line | `Text::Line`, `Text::Span`, or `String` |
+| `Into<Text<'a>>` | Multi-line styled | `Text::Text`, `Text::Line`, or `String` |
+| `T: AsRef<str>` | Any string-like | `String` (OK) |
+| `&'a str` | String slice | `String` (OK) |
+
+## Keeping Audits Maintainable
+
+### Create Checklists
+
+For each widget or feature area, maintain a checklist of all parameters with their expected types.
+
+### Track Upstream Changes
+
+When upgrading Ratatui versions:
+1. Read the changelog
+2. Search for new `pub fn` in widget files
+3. Audit new functionality before exposing it
+
+### Automate Where Possible
+
+Consider tooling that:
+- Compares upstream method counts to ours
+- Flags new `to_s` calls in code review
+- Tests styled content rendering
+
+## Example Audit Narrative
+
+> "I noticed inspect strings appearing in my tabs. I asked: 'What types does upstream accept for the divider parameter?' I found `Into<Span>`. I then asked: 'What does our binding do?' I found we call `to_s`. Gap identified."
+
+This narrative approach—asking questions, finding answers, comparing—works for any parity issue.

data/doc/contributors/developing_examples.md

@@ -62,7 +62,7 @@ MyExampleApp.new.run if __FILE__ == $PROGRAM_NAME
 
 Example directories **must** follow a prefixing convention to categorize them alphabetically:
 - `app_`: Application showcases (e.g., `app_analytics`). Class name: `AppAnalytics`.
-- `widget_`: Widget-focused demonstrations (e.g., `widget_gauge_demo`). Class name: `WidgetGaugeDemo`.
+- `widget_`: Widget-focused demonstrations (e.g., `widget_gauge`). Class name: `WidgetGaugeDemo`.
 - `verify_`: Documentation verification examples (e.g., `verify_readme_usage`). Class name: `VerifyReadmeUsage`.
 
 The directory and class names must match (snake_case directory maps to PascalCase class).
@@ -112,7 +112,7 @@ examples/
 test/examples/
   my_example/
     test_app.rb         ← REQUIRED: Tests (centralized, not local to example)
-    snapshots/          ← Auto-created by assert_snapshot
+    snapshots/          ← Auto-created by snapshot assertions
       initial_render.txt
 
 sig/examples/
@@ -223,7 +223,7 @@ class TestMyExampleApp < Minitest::Test
     with_test_terminal do
       inject_key(:q)
       @app.run
-      assert_snapshot("initial_render")
+      assert_snapshots("initial_render")
     end
   end
 end
@@ -231,7 +231,7 @@ end
 
 ## Snapshot Testing Pattern (REQUIRED)
 
-All example tests MUST use snapshot testing via the `assert_snapshot` API, not manual content assertions.
+All example tests MUST use snapshot testing via the `assert_snapshots` API, not manual content assertions.
 
 ### Why Snapshots
 
@@ -249,20 +249,20 @@ def test_initial_render
     inject_key(:q)
     @app.run
     
-    assert_snapshot("initial_render")
+    assert_snapshots("initial_render")
   end
 end
 ```
 
-Snapshot auto-saved to: `test/examples/widget_foo_demo/snapshots/initial_render.txt`
+Snapshot auto-saved to: `test/examples/widget_foo/snapshots/initial_render.txt`
 
 ### With Normalization (for dynamic content)
 
 For examples with timestamps, random data, or other non-deterministic output:
 
 ```ruby
-private def assert_normalized_snapshot(snapshot_name)
-  assert_snapshot(snapshot_name) do |actual|
+private def assert_normalized_snapshots(snapshot_name)
+  assert_plain_snapshot(snapshot_name) do |actual|
     actual.map do |line|
       line.gsub(/\d{2}:\d{2}:\d{2}/, "XX:XX:XX")  # Mask timestamps
            .gsub(/Random ID: \d+/, "Random ID: XXX")  # Mask random values
@@ -276,7 +276,7 @@ def test_after_event
     inject_key(:q)
     @app.run
     
-    assert_normalized_snapshot("after_event")
+    assert_normalized_snapshots("after_event")
   end
 end
 ```
@@ -320,7 +320,7 @@ Examples must use **realistic, meaningful data**—not dummy placeholder text. T
 
 **For small datasets (< 10 items):**
 Use hardcoded realistic data. Examples:
-- Geographic coordinates with city names (see `widget_map_demo/app.rb`)
+- Geographic coordinates with city names (see `widget_map/app.rb`)
 - Real product names or person names
 - Meaningful status values ("Completed", "Pending", "Failed")