ratatui_ruby 0.5.0 → 0.7.0

data/doc/contributors/design/rust_backend.md

@@ -5,57 +5,352 @@
 
 # Rust Backend Design (`ratatui_ruby` extension)
 
-This document describes the internal architecture of the `ratatui_ruby` Rust extension.
-
-## Architecture Guidelines
-
-The project follows a **Structured Design** approach, separating concerns into modules to improve cohesiveness and testability.
-
-### Core Principles
-
-1.  **Single Generic Renderer**: The backend implements a single generic renderer that accepts a Ruby `Value` representing the root of the view tree.
-2.  **No Custom Rust Structs for UI**: Do not define custom Rust structs that mirror Ruby UI components. Instead, extract data directly from Ruby objects using `funcall`.
-3.  **Dynamic Dispatch**: Use `value.class().name()` (e.g., `"RatatuiRuby::Paragraph"`) to dynamically dispatch rendering logic to the appropriate widget module.
-4.  **Immediate Mode**: The renderer traverses the Ruby object tree every frame and rebuilds the Ratatui widget tree on the fly.
-
-### Module Structure
-
-The Rust extension is located in `ext/ratatui_ruby/src/` and is organized as follows:
-
-*   **`lib.rs`**: The entry point for the compiled extension. It defines the Ruby module structure using `magnus` and exports public functions (`init_terminal`, `draw`, `poll_event`). It wires together the submodules.
-*   **`terminal.rs`**: Encapsulates the global `TERMINAL` state (mutex-wrapped `CrosstermBackend`). It provides functions to initialize and restore the terminal to raw mode.
-*   **`events.rs`**: Handles keyboard input polling and mapping Crossterm events to Ruby hashes.
-*   **`style.rs`**: Provides pure functions for parsing styling information (Colors, Styles, Blocks) from Ruby values.
-*   **`rendering.rs`**: The central dispatcher for the render loop. It takes the top-level Ruby View Tree node and recursively delegates to specific widget implementations based on the Ruby class name.
-*   **`widgets/`**: A directory containing individual modules for each Ratatui widget (e.g., `paragraph.rs`, `list.rs`).
-
-### Adding a New Widget
-
-To add a new widget:
-
-1.  Create a new file `src/widgets/my_widget.rs`.
-2.  Implement a public `render` function:
-    ```rust
-    /// Renders the widget to the given area.
-    ///
-    /// # Arguments
-    ///
-    /// * `frame` - The Ratatui frame to render to.
-    /// * `area` - The rectangular area within the frame to draw the widget.
-    /// * `node` - The Ruby object (Value) containing the widget's properties.
-    pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error>
-    ```
-3.  Inside `render`:
-    *   Extract properties from the `node` (Ruby value) using `.funcall("method_name", ())?`.
-    *   Construct the Ratatui widget.
-    *   Render it using `frame.render_widget`.
-4.  Register the module in `src/widgets/mod.rs`.
-5.  Add a dispatch arm in `src/rendering.rs` matching the Ruby class name (e.g., `RatatuiRuby::MyWidget`).
-
-### Testing Strategy
-
-*   **Unit Tests (`cargo test`)**:
-    *   **Logic**: Test pure logic like `parse_color` in `style.rs` without needing a terminal or Ruby VM if possible (though `magnus::Value` usually requires it).
-    *   **Rendering**: Verify that widgets render *something* to a buffer. Ratatui's `TestBackend` or `Buffer` can be used to assert that cells are filled.
-*   **Integration Tests (`rake test`)**:
-    *   Run Ruby scripts that exercise the full stack. Verify no crashes and expected return values.
+This document describes the internal architecture of the `ratatui_ruby` Rust extension. It is intended for contributors, architects, and AI agents working on the codebase.
+
+This is the companion document to [Ruby Frontend Design](./ruby_frontend.md). The Ruby layer defines data structures; the Rust layer renders them.
+
+## Key Dependencies
+
+| Crate | Purpose |
+|-------|---------|
+| `ratatui` | TUI framework providing widgets, layout, and rendering |
+| `crossterm` | Cross-platform terminal manipulation (raw mode, events, colors) |
+| `magnus` | Ruby FFI bindings for Rust (value extraction, exception handling) |
+
+**Why `ratatui` vs `ratatui-crossterm`?**
+
+Ratatui's workspace includes modular crates (`ratatui-crossterm`, `ratatui-core`, etc.) for library authors who need fine-grained dependency control. We use the main `ratatui` crate because:
+
+1. We're building an application extension, not a widget library
+2. The main crate includes crossterm backend by default
+3. It provides the complete API surface we need
+
+## Guiding Design Principles
+
+### 1. Ruby Defines, Rust Renders
+
+The Rust backend is a pure rendering engine. It receives Ruby objects representing the desired UI state and converts them to Ratatui primitives. It does not own or manage UI state—that responsibility belongs to Ruby.
+
+**The Contract:**
+- Ruby constructs a tree of `Data.define` objects describing the UI
+- Ruby calls `RatatuiRuby.draw { |frame| ... }` or passes a widget to `frame.render_widget`
+- Rust walks the Ruby object tree via `magnus::Value` and `funcall`
+- Rust builds Ratatui widgets and renders them to the terminal buffer
+
+### 2. Single Generic Renderer
+
+The backend implements one generic rendering function that accepts any Ruby `Value` and dispatches based on class name. There is no compile-time knowledge of Ruby types—everything is runtime reflection.
+
+```rust
+// rendering.rs
+pub fn render_widget(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+    let class_name: String = node.class().name()?.into_owned();
+    
+    match class_name.as_str() {
+        "RatatuiRuby::Widgets::Paragraph" => paragraph::render(frame, area, node),
+        "RatatuiRuby::Widgets::Block" => block::render(frame, area, node),
+        "RatatuiRuby::Widgets::Table" => table::render(frame, area, node),
+        // ... etc
+        _ => Err(Error::new(
+            magnus::exception::type_error(),
+            format!("Unknown widget type: {}", class_name)
+        ))
+    }
+}
+```
+
+### 3. No Custom Rust Structs for UI
+
+Do not define Rust structs that mirror Ruby UI components. This would create synchronization problems when Ruby classes change.
+
+**What We Do:**
+```rust
+// Extract directly from Ruby object
+let text: String = node.funcall("text", ())?;
+let style_val: Value = node.funcall("style", ())?;
+let style = parse_style(style_val)?;
+```
+
+**What We Don't Do:**
+```rust
+// NO: Rust struct mirroring Ruby
+struct Paragraph {
+    text: String,
+    style: Option<Style>,
+    block: Option<Block>,
+}
+```
+
+### 4. Immediate Mode Rendering
+
+The renderer traverses the Ruby object tree every frame and rebuilds the Ratatui widget tree from scratch. No widget state persists between frames in Rust.
+
+This mirrors Ratatui's own immediate mode paradigm. The Rust backend is stateless (except for terminal state).
+
+### 5. Memory Safety via Value Extraction
+
+Ruby's GC can move or collect objects at any time. All data extracted from Ruby must be owned (copied) before use, never borrowed.
+
+```rust
+// SAFE: Convert to owned String immediately
+let text: String = node.funcall::<_, String>("text", ())?.into_owned();
+
+// UNSAFE: Holding reference across GC-safe point
+let text_ref: &str = node.funcall("text", ())?;  // DON'T
+do_something_that_might_gc();
+use(text_ref);  // CRASH: text_ref may be invalid
+```
+
+---
+
+## Directory Structure
+
+```
+ext/ratatui_ruby/src/
+├── lib.rs              # Entry point, Ruby module registration
+├── terminal.rs         # Global TERMINAL state, init/restore
+├── frame.rs            # Frame wrapper for render_widget, area access
+├── events.rs           # Event polling, crossterm -> Ruby conversion
+├── style.rs            # Style/Color parsing from Ruby values
+├── text.rs             # Span/Line parsing
+├── rendering.rs        # Central dispatcher, class name -> widget module
+└── widgets/            # Per-widget rendering modules
+    ├── mod.rs          # Re-exports all widget modules
+    ├── paragraph.rs
+    ├── block.rs
+    ├── table.rs
+    ├── list.rs
+    ├── canvas.rs
+    └── ...
+```
+
+---
+
+## Module Responsibilities
+
+### `lib.rs` — Entry Point
+
+Defines the Ruby module hierarchy using `magnus` and exports public functions (`init_terminal`, `restore_terminal`, `draw`, `poll_event`, `get_cell_at`).
+
+### `terminal.rs` — Terminal State
+
+Manages the global `TERMINAL` singleton (mutex-wrapped `CrosstermBackend<Stdout>`).
+
+Key functions:
+- `init()` — Enter raw mode, enable mouse capture, switch to alternate screen
+- `restore()` — Disable raw mode, restore main screen
+- `get_cell_at(x, y)` — Return buffer cell as Ruby `Buffer::Cell` object
+
+**Safety Note:** The terminal is a global mutable resource. All access goes through a mutex. Holding the lock across Ruby calls risks deadlock—release the lock before calling back into Ruby.
+
+### `frame.rs` — Frame Wrapper
+
+Wraps Ratatui's `Frame` struct for safe Ruby access. The `Frame` reference is only valid inside the `draw` closure. The `FrameWrapper` tracks validity and raises `Safety` error if used after the closure returns.
+
+### `events.rs` — Event Conversion
+
+Polls crossterm events and converts them to Ruby `Event::*` objects. Handles key, mouse, resize, paste, and focus events.
+
+### `style.rs` — Style Parsing
+
+Pure functions for extracting style information from Ruby values. Handles `parse_style`, `parse_color` (symbols, integers 0-255, hex strings), and `parse_modifiers`.
+
+### `rendering.rs` — Central Dispatcher
+
+The routing layer that maps Ruby class names to widget renderers:
+
+```rust
+pub fn render_widget(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+    let class_name: String = node.class().name()?.into_owned();
+    
+    match class_name.as_str() {
+        // Widgets module
+        "RatatuiRuby::Widgets::Paragraph" => widgets::paragraph::render(frame, area, node),
+        "RatatuiRuby::Widgets::Block" => widgets::block::render(frame, area, node),
+        "RatatuiRuby::Widgets::Table" => widgets::table::render(frame, area, node),
+        "RatatuiRuby::Widgets::List" => widgets::list::render(frame, area, node),
+        "RatatuiRuby::Widgets::Tabs" => widgets::tabs::render(frame, area, node),
+        "RatatuiRuby::Widgets::Gauge" => widgets::gauge::render(frame, area, node),
+        "RatatuiRuby::Widgets::Chart" => widgets::chart::render(frame, area, node),
+        "RatatuiRuby::Widgets::Canvas" => widgets::canvas::render(frame, area, node),
+        "RatatuiRuby::Widgets::Scrollbar" => widgets::scrollbar::render(frame, area, node),
+        "RatatuiRuby::Widgets::Calendar" => widgets::calendar::render(frame, area, node),
+        // ... all widgets
+        
+        // Special widgets
+        "RatatuiRuby::Widgets::Clear" => widgets::clear::render(frame, area, node),
+        "RatatuiRuby::Widgets::Cursor" => widgets::cursor::render(frame, area, node),
+        
+        // Custom widgets (Ruby escape hatch)
+        _ if has_render_method(node) => widgets::custom::render(frame, area, node),
+        
+        _ => Err(Error::new(
+            magnus::exception::type_error(),
+            format!("Unknown widget type: {}", class_name)
+        ))
+    }
+}
+```
+
+**Namespace Pattern:** All built-in widgets use the `RatatuiRuby::Widgets::*` namespace. The dispatcher matches on full class names, not prefixes.
+
+### `widgets/*.rs` — Widget Renderers
+
+Each widget has its own module with a standard interface:
+
+```rust
+// widgets/paragraph.rs
+pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+    // 1. Extract properties from Ruby object
+    let text = parse_text(node.funcall("text", ())?)?;
+    let style = parse_style(node.funcall("style", ())?)?;
+    let alignment = parse_alignment(node.funcall("alignment", ())?)?;
+    let block_val: Value = node.funcall("block", ())?;
+    
+    // 2. Build Ratatui widget
+    let mut paragraph = Paragraph::new(text)
+        .style(style)
+        .alignment(alignment);
+    
+    // 3. Handle optional block wrapper
+    if !block_val.is_nil() {
+        paragraph = paragraph.block(parse_block(block_val)?);
+    }
+    
+    // 4. Render
+    frame.render_widget(paragraph, area);
+    Ok(())
+}
+```
+
+---
+
+## Adding a New Widget
+
+### Step 1: Create the Widget Module
+
+```rust
+// src/widgets/my_widget.rs
+
+use magnus::{Error, Value};
+use ratatui::prelude::*;
+
+use crate::style::parse_style;
+
+pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+    // Extract properties
+    let content: String = node.funcall::<_, String>("content", ())?.into_owned();
+    let style = parse_style(node.funcall("style", ())?)?;
+    
+    // Build and render
+    let widget = MyWidget::new(content).style(style);
+    frame.render_widget(widget, area);
+    
+    Ok(())
+}
+```
+
+### Step 2: Register in `widgets/mod.rs`
+
+```rust
+pub mod my_widget;
+```
+
+### Step 3: Add Dispatch Arm in `rendering.rs`
+
+```rust
+"RatatuiRuby::Widgets::MyWidget" => widgets::my_widget::render(frame, area, node),
+```
+
+### Step 4: Test
+
+Run `cargo test` for Rust unit tests, then `rake test` for Ruby integration tests.
+
+---
+
+## Stateful Widget Rendering
+
+Some widgets (List, Table, Scrollbar) support stateful rendering where a mutable State object tracks scroll position and selection.
+
+### The Pattern
+
+```rust
+pub fn render_stateful_widget(
+    frame: &mut Frame,
+    area: Rect,
+    widget_node: Value,
+    state_node: Value
+) -> Result<(), Error> {
+    // 1. Build the widget (immutable configuration)
+    let list = build_list(widget_node)?;
+    
+    // 2. Extract mutable state
+    let mut state = ListState::default();
+    if let Ok(selected) = state_node.funcall::<_, Option<i64>>("selected", ()) {
+        state.select(selected.map(|i| i as usize));
+    }
+    
+    // 3. Render with state (Ratatui may mutate offset)
+    frame.render_stateful_widget(list, area, &mut state);
+    
+    // 4. Write computed values back to Ruby state object
+    state_node.funcall::<_, Value>("set_offset", (state.offset() as i64,))?;
+    
+    Ok(())
+}
+```
+
+**State Precedence:** When using stateful rendering, the State object's values take precedence over Widget properties. This is documented in Ruby.
+
+---
+
+## Custom Widget Escape Hatch
+
+Ruby users can define custom widgets that implement a `render(area)` method returning an array of `Draw` commands. The dispatcher detects a `render` method and calls it, processing the returned commands to manipulate the buffer directly. This is the "escape hatch" for functionality not yet wrapped by built-in widgets.
+
+---
+
+## Error Handling
+
+All Rust functions that can fail return `Result<T, magnus::Error>`. Magnus automatically converts these to Ruby exceptions.
+
+**Error Types:**
+
+| Scenario | Ruby Exception | Notes |
+|----------|---------------|-------|
+| Invalid argument | `ArgumentError` | Wrong type, out of range |
+| Unknown widget | `TypeError` | Class name not in dispatch table |
+| Terminal not initialized | `RatatuiRuby::Error::Terminal` | Custom exception class |
+| Frame used after draw block | `RatatuiRuby::Error::Safety` | Memory safety violation |
+
+---
+
+## Testing Strategy
+
+### Rust Unit Tests (`cargo test`)
+
+Test pure parsing functions that don't require Ruby VM. Most tests require Ruby VM via magnus, which means they run in integration test style.
+
+### Ruby Integration Tests (`rake test`)
+
+The primary testing strategy. Ruby tests exercise the full stack and verify end-to-end behavior without testing Rust internals.
+
+### Buffer Verification
+
+For Rust-level rendering tests, use Ratatui's `TestBackend` or `Buffer` to assert cells are filled correctly.
+
+---
+
+## Performance Considerations
+
+### Avoid Repeated `funcall`
+
+Each `funcall` crosses the Ruby/Rust boundary. Cache results when accessing the same property multiple times rather than calling `funcall` repeatedly.
+
+### String Ownership
+
+Always convert to owned `String` immediately via `into_owned()` to avoid GC-related memory safety issues.
+
+### Batch Collection Iteration
+
+When processing Ruby arrays, collect all values into a `Vec<Value>` before processing to avoid holding references across iterations.

data/doc/contributors/developing_examples.md

@@ -84,9 +84,11 @@ All interactive examples must fit within an **80×24 terminal** (standard VT100
 - **Style hotkeys visually:** Use `modifiers: [:bold, :underlined]` on hotkey letters to make them stand out from descriptions. Example: `i` (bold, underlined) followed by `Items`.
 - Test early by running the example at 80×24 and verifying all content is visible without wrapping, scrolling, or clipping.
 
-Every example must also have an RBS file documenting its public methods:
+## Type Signatures
 
-`examples/my_example/app.rbs`:
+Every example must also have an RBS file documenting its public methods. Type signatures live in a centralized location:
+
+`sig/examples/my_example/app.rbs`:
 ```rbs
 class MyExampleApp
   # @public
@@ -97,20 +99,41 @@ class MyExampleApp
 end
 ```
 
+## Directory Structure
+
+Examples are organized across three locations:
+
+```
+examples/
+  my_example/
+    app.rb              ← REQUIRED: The runnable example code
+    README.md           ← REQUIRED: Purpose, architecture, hotkeys, usage
+
+test/examples/
+  my_example/
+    test_app.rb         ← REQUIRED: Tests (centralized, not local to example)
+    snapshots/          ← Auto-created by assert_snapshot
+      initial_render.txt
+
+sig/examples/
+  my_example/
+    app.rbs             ← REQUIRED: Type signatures (centralized, not local to example)
+```
+
 ### Key Requirements
 
 1. **Only `run` should be public.** All other methods (`render`, `handle_input`, helper methods) must be private. This prevents tests from calling internal methods directly.
 
 2. **Use `RatatuiRuby.run` for terminal management.** Never call `init_terminal` or `restore_terminal` directly. The `run` block handles terminal setup/teardown automatically and safely, even if an exception occurs.
 
-3. **Use the Session API (`tui`) for cleaner code.** Accept the `tui` block parameter from `RatatuiRuby.run` and use it throughout your app:
+3. **Use the TUI API (`tui`) for cleaner code.** Accept the `tui` block parameter from `RatatuiRuby.run` and use it throughout your app:
    - `@tui.draw { |frame| ... }` instead of `RatatuiRuby.draw`
    - `@tui.poll_event` instead of `RatatuiRuby.poll_event`
-   - `@tui.style(...)` instead of `RatatuiRuby::Style.new(...)`
-   - `@tui.paragraph(...)` instead of `RatatuiRuby::Paragraph.new(...)`
-   - `@tui.block(...)` instead of `RatatuiRuby::Block.new(...)`
+   - `@tui.style(...)` instead of `RatatuiRuby::Style::Style.new(...)`
+   - `@tui.paragraph(...)` instead of `RatatuiRuby::Widgets::Paragraph.new(...)`
+   - `@tui.block(...)` instead of `RatatuiRuby::Widgets::Block.new(...)`
    - `@tui.layout_split(...)` instead of `RatatuiRuby::Layout.split(...)`
-   - `@tui.constraint_fill(...)` instead of `RatatuiRuby::Constraint.fill(...)`
+   - `@tui.constraint_fill(...)` instead of `RatatuiRuby::Layout::Constraint.fill(...)`
    - `@tui.text_line(...)` instead of `RatatuiRuby::Text::Line.new(...)`
    - `@tui.text_span(...)` instead of `RatatuiRuby::Text::Span.new(...)`
 
@@ -127,7 +150,6 @@ end
        # Ignore other events
      end
    end
-   ```
 
 5. **Use keyboard keys to cycle through widget attributes.** Users should be able to interactively explore all widget options. Common patterns:
     - Arrow keys: Navigate or adjust values
@@ -135,7 +157,17 @@ end
     - Space: Toggle or select
     - `q` or Ctrl+C: Quit
 
-5. **Naming Conventions for Controls**
+6. **All examples must include a README.md** explaining:
+   - What problem the example solves
+   - Architecture (if applicable)
+   - Hotkeys (if interactive): Document all keyboard/mouse controls
+   - Key concepts demonstrated
+   - Usage instructions
+   - Learning outcomes
+
+   See examples/app_color_picker/README.md and examples/app_all_events/README.md for patterns. Adhere to docs/contributors/documentation_style.md.
+
+7. **Naming Conventions for Controls**
 
 When documenting hotkeys and cycling options in the UI, use consistent naming:
 
@@ -158,7 +190,7 @@ When documenting hotkeys and cycling options in the UI, use consistent naming:
 
 This keeps the UI self-documenting and users can see exact parameter names when they read the hotkey help.
 
-7. **Hit Testing**
+8. **Hit Testing**
 
 Examples with mouse interaction should use the **Frame API**. By calling `@tui.layout_split` inside `@tui.draw`, you obtain the exact `Rect`s used for rendering. Store these rects in instance variables (e.g., `@sidebar_rect`) to use them in your `handle_input` method for hit testing:
 
@@ -170,11 +202,9 @@ end
 
 ## Testing Examples
 
-Example tests live alongside examples as `test_app.rb` files in the same directory.
-
-### Testing Pattern
+Example tests live in a centralized test tree:
 
-`examples/my_example/test_app.rb`:
+`test/examples/my_example/test_app.rb`:
 ```ruby
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 require "ratatui_ruby"
@@ -191,56 +221,75 @@ class TestMyExampleApp < Minitest::Test
 
   def test_initial_render
     with_test_terminal do
-      inject_key(:q)  # Queue quit event
-      @app.run        # Run the app loop
-      
-      content = buffer_content.join("\n")
-      assert_includes content, "Expected Text"
+      inject_key(:q)
+      @app.run
+      assert_snapshot("initial_render")
     end
   end
+end
+```
 
-  def test_keyboard_interaction
-    with_test_terminal do
-      inject_key("s")  # Press 's' to cycle something
-      inject_key(:q)   # Then quit
-      @app.run
+## Snapshot Testing Pattern (REQUIRED)
 
-      content = buffer_content.join("\n")
-      assert_includes content, "Changed State"
-    end
-  end
+All example tests MUST use snapshot testing via the `assert_snapshot` API, not manual content assertions.
 
-  def test_mouse_interaction
-    with_test_terminal do
-      # Click at (10, 5)
-      inject_click(x: 10, y: 5)
-      inject_key(:q)
-      @app.run
+### Why Snapshots
 
-      content = buffer_content.join("\n")
-      assert_includes content, "Clicked at (10, 5)"
-    end
+- **Exact verification:** Captures complete screen state, character-by-character
+- **Auto-update:** `UPDATE_SNAPSHOTS=1 bin/agent_rake test` regenerates all snapshots
+- **Auto-managed:** Snapshots live in `test/examples/{name}/snapshots/{test_name}.txt`
+- **Maintainable:** No tedious manual string checks
+- **Self-documenting:** Snapshots show exactly what output is expected
+
+### Basic Pattern
+
+```ruby
+def test_initial_render
+  with_test_terminal do
+    inject_key(:q)
+    @app.run
+    
+    assert_snapshot("initial_render")
   end
 end
 ```
 
-### Testing Guidelines
+Snapshot auto-saved to: `test/examples/widget_foo_demo/snapshots/initial_render.txt`
 
-1. **Inject events, observe buffer.** Tests should only interact through:
-   - `inject_key`, `inject_click`, `inject_event`, etc. for input
-   - `buffer_content` for output verification
+### With Normalization (for dynamic content)
 
-2. **Never call internal methods.** Don't call `render`, `handle_input`, `__send__`, or access instance variables with `instance_variable_get`. Tests verify behavior through the public `run` method.
+For examples with timestamps, random data, or other non-deterministic output:
 
-3. **Use `inject_key(:q)` to exit.** All examples should support quitting with `q`, so inject this as the final event to terminate the loop.
+```ruby
+private def assert_normalized_snapshot(snapshot_name)
+  assert_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
+    end
+  end
+end
 
-4. **Assert and refute.** When testing which item was clicked/selected, also verify the opposite didn't happen:
-   ```ruby
-   assert_includes content, "Left Panel clicked"
-   refute_includes content, "Right Panel clicked"
-   ```
+def test_after_event
+  with_test_terminal do
+    inject_key("a")
+    inject_key(:q)
+    @app.run
+    
+    assert_normalized_snapshot("after_event")
+  end
+end
+```
+
+See `test/examples/app_all_events/test_app.rb` for a complete example.
 
-5. **Test state cycling.** If an example cycles through options (styles, modes, etc.), test that pressing the key actually changes the rendered output.
+### Regenerating Snapshots
+
+When UI changes are intentional, regenerate all snapshots:
+
+```bash
+UPDATE_SNAPSHOTS=1 bin/agent_rake test
+```
 
 ## Widget Attribute Cycling
 
@@ -259,3 +308,39 @@ Examples should demonstrate widget configurability by allowing interactive cycli
 | Scrollbar | theme | s |
 
 Display the current state in the UI (e.g., in a title or status bar or paragraph) so users can see what changed. Display the hotkey in the UI as well, so users can see how to change it; the hotkey should not disappear as app state changes.
+
+## Data Quality
+
+Examples must use **realistic, meaningful data**—not dummy placeholder text. This ensures examples:
+- Demonstrate the widget's real-world usage
+- Provide educational value to users reading the code
+- Look professional and polished
+
+### Guidelines
+
+**For small datasets (< 10 items):**
+Use hardcoded realistic data. Examples:
+- Geographic coordinates with city names (see `widget_map_demo/app.rb`)
+- Real product names or person names
+- Meaningful status values ("Completed", "Pending", "Failed")
+
+**For large datasets (≥ 10 items):**
+Use the [Faker](https://github.com/faker-ruby/faker) gem with **deterministic seeding** so data is consistent across runs:
+
+```ruby
+require "faker"
+
+# Seed Faker for reproducible output
+Faker::Config.random = Random.new(12345)
+
+# Generate realistic data
+users = Array.new(50) { Faker::Name.name }
+emails = Array.new(50) { Faker::Internet.email }
+```
+
+In tests, set the same seed before each test to ensure snapshot consistency.
+
+**Avoid:**
+- Repeated placeholder text like "Lorem ipsum" or "Background Layer" × 20
+- Generic numbered items like "Item 1", "Item 2" (unless the context demands it)
+- Nonsensical or visually jarring content