ratatui_ruby 0.7.0 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9da9703e1573d331115fd1635c1bf0564a6482c8d3d140c7b68230b56da8311
-  data.tar.gz: 41efa864847825eed6d28ee3b9292e923b3f3c97ce28841892a65123df72c16e
+  metadata.gz: 52112877db56e3edf7a4baa4c542b55570e8b1172a172934e229c0730d33ca2c
+  data.tar.gz: 1f46e0c790f33828dba5ed4cfa6ea6d56d5525634cc587d0986005e287c6b876
 SHA512:
-  metadata.gz: efc0e59765a7cfea0108fa79335ae79d4b0bcdb2c9eff93f6e1f5d83dca04724484ce322b45a6d3e6d6cf45f80868a998c9684a8362c3e11b9e1ff02e30eade1
-  data.tar.gz: be4afb8fe1b4bf7ed1ed4757521f8b90f68ca11c101aa69b184eae2de6807a2efa8a59fc2c19d0c47d3ed28f6afd89c906ba6480e824146b2b4ea8e7bc7211fa
+  metadata.gz: 5ee6665ca41a8029b67f9d99ac4908ad5ab124cc8d21952d7a42e3eb3bce0dfd2ef77e19b69294a7c5e2bb1a8bb745047a8f7599712e497ba0c66d3e8607e351
+  data.tar.gz: '085180a5bab1b831521750b42398087109129fda7d20fe369b7aa4ff5c746e691e09f82a4251bc62ca964508ed21d9276ace9970ed91fec3fd979923ea2937a5'

data/.builds/ruby-3.2.yml

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

data/AGENTS.md

@@ -27,7 +27,7 @@ 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.
@@ -78,6 +78,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 +102,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
 

data/CHANGELOG.md

@@ -18,6 +18,38 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### 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
+
+### Added
+
+### Changed
+
+### Fixed
+
+- **Block Title Styling**: `Block` title `content` now correctly renders `Text::Line` objects with styled spans. Previously, passing a styled `Line` as title content displayed its Ruby inspect representation (e.g., `#<data RatatuiRuby::Text::Line...>`) instead of the styled text.
+
+### Removed
+
 ## [0.7.0] - 2026-01-03
 
 > [!WARNING]
@@ -356,6 +388,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.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
 [0.5.0]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.5.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.
 
-**[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/concepts/async.md

@@ -0,0 +1,160 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Async Operations in TUI Applications
+
+TUI applications fetch data from APIs, run shell commands, and query databases. These operations take time. Blocking the render loop freezes the interface.
+
+You want responsive UIs. The checklist shows "Loading..." while data arrives. The interface never hangs.
+
+This guide explains async patterns that work with raw terminal mode.
+
+## The Raw Terminal Problem
+
+`RatatuiRuby.run` enters raw terminal mode:
+
+- stdin reconfigures for character-by-character input
+- stdout carries terminal escape sequences
+- External commands expecting normal terminal I/O fail
+
+### What Breaks
+
+```ruby
+# These fail inside a Thread during raw mode:
+`git ls-remote --tags origin`           # Returns empty or hangs
+IO.popen(["git", "ls-remote", ...])     # Same
+Open3.capture2("git", "ls-remote", ...) # Same
+```
+
+The commands succeed synchronously. They fail asynchronously. The difference: thread context inherits the parent's raw terminal state.
+
+### Why Threads Fail
+
+Ruby's GIL releases during I/O. But:
+
+1. Subprocesses inherit the parent's terminal state.
+2. Git/SSH try to read credentials from raw-mode stdin.
+3. The read blocks forever. Or returns empty.
+
+`GIT_TERMINAL_PROMPT=0` prevents prompts. Auth fails silently instead of hanging.
+
+## Solutions
+
+### Pre-Check Before Raw Mode
+
+Run slow operations before entering the TUI:
+
+```ruby
+def initialize
+  @data = fetch_data  # Runs before RatatuiRuby.run
+end
+```
+
+**Trade-off**: Delays startup.
+
+### Process.spawn with File Output
+
+Spawn a separate process before entering raw mode. Write results to a temp file. Poll for completion:
+
+```ruby
+class AsyncChecker
+  CACHE_FILE = File.join(Dir.tmpdir, "my_check_result.txt")
+
+  def initialize
+    @loading = true
+    @result = nil
+    @pid = Process.spawn("my-command > #{CACHE_FILE}")
+  end
+
+  def loading?
+    return false unless @loading
+
+    # Non-blocking poll
+    _pid, status = Process.waitpid2(@pid, Process::WNOHANG)
+    if status
+      @result = File.read(CACHE_FILE).strip
+      @loading = false
+    end
+    @loading
+  end
+end
+```
+
+**Key points**:
+
+- `Process.spawn` returns immediately.
+- The command runs in a separate process, not a thread.
+- Results pass through a temp file. Avoids pipe/terminal issues.
+- `Process::WNOHANG` polls without blocking.
+
+### Thread for CPU-Bound Work
+
+Ruby threads work for pure computation:
+
+```ruby
+Thread.new { @result = expensive_calculation }
+```
+
+Avoid threads for shell commands.
+
+## Ractors
+
+Ractors provide true parallelism. Trade-offs:
+
+- No mutable shared state.
+- Limited to Ractor-safe values.
+- Terminal I/O issues remain.
+
+For TUI async, `Process.spawn` solves the problem cleanly.
+
+## Pattern Summary
+
+| Approach | Use Case | Raw Mode Safe? |
+|----------|----------|----------------|
+| Sync before TUI | Fast checks (<100ms) | Yes |
+| Process.spawn + file | Shell commands, network | Yes |
+| Thread | CPU-bound Ruby code | Yes |
+| Thread + shell | Shell commands | **No** |
+
+## Real Example: Git Tag Check
+
+Check if a tag exists on the remote:
+
+```ruby
+class GitRepo
+  CACHE_FILE = File.join(Dir.tmpdir, "git_tag_pushed.txt")
+
+  def initialize
+    @version = `git describe --tags --abbrev=0`.strip
+    @tag_pushed = nil
+    @loading = true
+    @pid = Process.spawn(
+      "git ls-remote --tags origin | grep -q '#{@version}' " \
+      "&& echo true > #{CACHE_FILE} || echo false > #{CACHE_FILE}"
+    )
+  end
+
+  def loading?
+    return false unless @loading
+
+    _pid, status = Process.waitpid2(@pid, Process::WNOHANG)
+    if status
+      @tag_pushed = File.read(CACHE_FILE).strip == "true"
+      @loading = false
+    end
+    @loading
+  end
+
+  def refresh
+    # Sync version for manual refresh (user presses 'r')
+    @loading = true
+    remote_tags = `git ls-remote --tags origin`.strip
+    @tag_pushed = remote_tags.include?(@version)
+    @loading = false
+  end
+end
+```
+
+The TUI starts instantly. The tag check runs in the background. The checklist updates when the result arrives.

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).
@@ -254,7 +254,7 @@ def test_initial_render
 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)
 
@@ -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")