ratatui_ruby 0.6.0 → 0.7.0

data/doc/index.md

@@ -7,13 +7,18 @@
 
 ## Documentation for Users
 
-- [README](../README.md)
-- [Quickstart](./quickstart.md)
-- [Application Architecture](./application_architecture.md)
-- [Testing Your Application](./application_testing.md)
+- [README](../README.md): Project overview and installation
+- [Why RatatuiRuby?](./why.md): Philosophy, comparisons, and what makes us different
+- [Quickstart](./quickstart.md): Build your first TUI app
+- [Application Architecture](./application_architecture.md): Lifecycle patterns and API choices
+- [Event Handling](./event_handling.md): Keyboard, mouse, and terminal events
+- [Interactive Design](./interactive_design.md): Cached layout pattern for hit testing
+- [Terminal Limitations](./terminal_limitations.md): Platform quirks and workarounds
+- [Testing Your Application](./application_testing.md): Snapshot testing and style assertions
+- [Migrating to v0.7.0](./v0.7.0_migration.md): Namespace changes and upgrade guide
 
 
 ## Documentation for Contributors
 
-- [Contributing Guidelines](https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md)
-- [More Documentation for Contributors](./contributors/index.md)
+- [Contributing Guidelines](https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md): How to contribute patches and features
+- [More Documentation for Contributors](./contributors/index.md): Internal design docs and style guides

data/doc/interactive_design.md

@@ -103,10 +103,10 @@ end
 
 ## Layout.split
 
-`Layout.split` computes layout geometry without rendering. It returns an array of `Rect` objects. While you can call `RatatuiRuby::Layout.split` directly, we recommend using the `Session` helper (`tui.layout_split`) for cleaner application code.
+`Layout.split` computes layout geometry without rendering. It returns an array of `Rect` objects. While you can call `RatatuiRuby::Layout.split` directly, we recommend using the `TUI` helper (`tui.layout_split`) for cleaner application code.
 
 ```ruby
-# Preferred (Session API)
+# Preferred (TUI API)
 left, right = tui.layout_split(area, constraints: [...])
 
 # Manual (Core API)

data/doc/quickstart.md

@@ -8,25 +8,7 @@ Welcome to **ratatui_ruby**! This guide will help you get up and running with yo
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
-```ruby
-gem "ratatui_ruby"
-```
-
-
-And then execute:
-
-```bash
-bundle install
-```
-
-
-Or install it yourself as:
-
-```bash
-gem install ratatui_ruby
-```
+See [Installation in the README](../README.md#installation) for setup instructions.
 
 
 ## Tutorials
@@ -45,10 +27,10 @@ begin
   loop do
     # 2. Create your UI (Immediate Mode)
     # We define a Paragraph widget inside a Block with a title and borders.
-    view = RatatuiRuby::Paragraph.new(
+    view = RatatuiRuby::Widgets::Paragraph.new(
       text: "Hello, Ratatui! Press 'q' to quit.",
       alignment: :center,
-      block: RatatuiRuby::Block.new(
+      block: RatatuiRuby::Widgets::Block.new(
         title: "My Ruby TUI App",
         title_alignment: :center,
         borders: [:all],
@@ -77,7 +59,7 @@ end
 ```
 <!-- SYNC:END -->
 
-![quickstart_lifecycle](./images/verify_quickstart_lifecycle.png)
+[![quickstart_lifecycle](./images/verify_quickstart_lifecycle.png)](../examples/verify_quickstart_lifecycle/README.md)
 
 #### How it works
 
@@ -87,12 +69,13 @@ end
 4.  **`RatatuiRuby.poll_event`**: Returns a typed `Event` object with predicates like `key?`, `mouse?`, `resize?`, etc. Returns `RatatuiRuby::Event::None` if no events are pending. Use predicates to check event type without pattern matching.
 5.  **`RatatuiRuby.restore_terminal`**: Essential for leaving raw mode and returning to the shell. Always wrap your loop in `begin...ensure` to guarantee this runs.
 
-### Idiomatic Session
+### Simplified API
 
-You can simplify your code by using `RatatuiRuby.run`. This method handles the terminal lifecycle for you, yielding a `Session` object with factory methods for widgets.
+You can simplify your code by using `RatatuiRuby.run`. This method handles the terminal lifecycle for you, yielding a `TUI` object with factory methods for widgets.
 
 <!-- SYNC:START:../examples/verify_quickstart_dsl/app.rb:main -->
 ```ruby
+# 1. Initialize the terminal, start the run loop, and ensure the terminal is restored.
 RatatuiRuby.run do |tui|
   loop do
     # 2. Create your UI with methods instead of classes.
@@ -128,8 +111,8 @@ end
 #### How it works
 
 1.  **`RatatuiRuby.run`**: This context manager initializes the terminal before the block starts and ensures `restore_terminal` is called when the block exits (even if an error occurs).
-2.  **Widget Shorthand**: The block yields a `Session` object (here named `tui`). This object provides factory methods for every widget, allowing you to write `tui.paragraph(...)` instead of the more verbose `RatatuiRuby::Paragraph.new(...)`.
-3.  **Method Shorthand**: The session object also provides aliases for module functions of `RatatuiRuby`, allowing you to write `tui.draw(...)` instead of the more verbose `RatatuiRuby.draw(...)`.
+2.  **Widget Shorthand**: The block yields a `TUI` object (here named `tui`). This object provides factory methods for every widget, allowing you to write `tui.paragraph(...)` instead of the more verbose `RatatuiRuby::Widgets::Paragraph.new(...)`.
+3.  **Method Shorthand**: The `TUI` object also provides aliases for module functions of `RatatuiRuby`, allowing you to write `tui.draw(...)` instead of the more verbose `RatatuiRuby.draw(...)`.
 4.  **Pattern Matching for Events**: Use `case...in` with pattern matching for elegant event dispatch. Always include an `else` clause at the end to catch unmatched event types (mouse, resize, paste, focus, etc.), otherwise Ruby raises `NoMatchingPatternError`.
 
 For a deeper dive into the available application architectures (Manual vs Managed), see [Application Architecture](./application_architecture.md).
@@ -197,95 +180,81 @@ end
 
 #### How it works
 
-1.  **`tui.layout_split` (`RatatuiRuby::Layout.split`)**: Takes an area (like `frame.area`) and splits it into multiple sub-areas based on constraints.
-2.  **`tui.constraint_*` (`RatatuiRuby::Constraint`)**: Defines how space is distributed (e.g., `percentage`, `length`, `min`, `max`).
+1.  **`tui.layout_split` (`RatatuiRuby::Layout::Layout.split`)**: Takes an area (like `frame.area`) and splits it into multiple sub-areas based on constraints.
+2.  **`tui.constraint_*` (`RatatuiRuby::Layout::Constraint`)**: Defines how space is distributed (e.g., `percentage`, `length`, `min`, `max`).
 3.  **`Frame#render_widget(widget, rect)`**: You pass the specific area (like `top` or `bottom`) to render the widget into that exact region.
 4.  **`tui.text_span` (`RatatuiRuby::Text::Span`)**: Allows for rich styling within a single line of text.
 
+[![quickstart_layout](./images/verify_quickstart_layout.png)](../examples/verify_quickstart_layout/README.md)
+
 ## Examples
 
 These examples showcase the full power of **ratatui_ruby**. You can find their source code in the [examples directory](../examples).
 
-### Sample Applications
-
-Full-featured examples demonstrating complex layouts and real-world TUI patterns.
-
-
-
-#### [All Events](../examples/app_all_events/app.rb)
-
-Handling terminal events is unpredictable. Developers need to know exactly what the terminal sends for `Ctrl+C` or a mouse drag.
-
-This app captures and visualizes every event—keys, mouse, resize, paste, and focus.
-
-Use it to debug your input handling or verify terminal behavior.
-
-**What you'll learn:**
-
-*   **Proto-TEA Architecture**: Implements unidirectional data flow (Model-View-Update) with immutable state and pure functions.
-*   **Event Handling**: Captures and distinguishes all input types, including modifiers (`Ctrl+C`) and focus changes.
-*   **Scalable Structure**: Organizes a non-trivial application into small, focused classes instead of a monolithic script.
-
-![all_events](./images/app_all_events.png)
-
-#### [Color Picker](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/app_color_picker/app.rb)
-
-Interactive tools require complex state. Mapping mouse clicks to widgets and handling modal dialogs creates messy code if handled in the main loop.
-
-This app implements a full Color Picker using a "Proto-Kit (Component-Based)" pattern. Each component encapsulates its own rendering, state, and event handling.
-
-Use it to build forms, editors, and mouse-driven tools.
-
-**What you'll learn:**
-
-*   **Proto-Kit Architecture**: Self-contained components with `render(tui, frame, area)` and `handle_event(event)`.
-*   **Encapsulated Hit Testing**: Components cache their render area and check `contains?` internally.
-*   **Modal Dialogs**: Implements overlay patterns that intercept input via Chain of Responsibility.
-
-#### [Custom Widget (Escape Hatch)](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/app_custom_widget/app.rb)
-
-Demonstrates how to define a custom widget in pure Ruby using the `render(area, buffer)` escape hatch for low-level drawing.
+### Widget Demos
 
-![custom_widget](./images/app_custom_widget.png)
+Focused examples for individual widgets. Each demonstrates a single widget and its configuration options.
+
+| Widget | What it demonstrates |
+|--------|---------------------|
+| [Bar Chart](../examples/widget_barchart_demo/app.rb) | Grouped bars, data visualization, custom bar styling |
+| [Block](../examples/widget_block_demo/app.rb) | Borders, titles, padding, nested widgets |
+| [Box](../examples/widget_box_demo/app.rb) | Block + Paragraph composition, text wrapping |
+| [Calendar](../examples/widget_calendar_demo/app.rb) | Date highlighting, month display, event markers |
+| [Chart](../examples/widget_chart_demo/app.rb) | Line/scatter plots, axes, legends, datasets |
+| [Gauge](../examples/widget_gauge_demo/app.rb) | Progress bars, percentage display, unicode blocks |
+| [Layout Split](../examples/widget_layout_split/app.rb) | Constraint types, flex modes, responsive layouts |
+| [Line Gauge](../examples/widget_line_gauge_demo/app.rb) | Horizontal progress, labels, thin-style gauges |
+| [List](../examples/widget_list_demo/app.rb) | Selection, scrolling, highlight styles, rich text items |
+| [Map](../examples/widget_map_demo/app.rb) | Canvas widget, world map rendering, coordinates |
+| [Popup](../examples/widget_popup_demo/app.rb) | Clear widget, modal dialogs, overlay composition |
+| [Ratatui Logo](../examples/widget_ratatui_logo_demo/app.rb) | Decorative branding widget |
+| [Ratatui Mascot](../examples/widget_ratatui_mascot_demo/app.rb) | ASCII art Ferris mascot |
+| [Rect](../examples/widget_rect/app.rb) | Geometry helpers, area calculations, contains/intersection |
+| [Rich Text](../examples/widget_rich_text/app.rb) | Spans, lines, inline styling, mixed colors |
+| [Scrollbar](../examples/widget_scrollbar_demo/app.rb) | Orientations, thumb/track styling, scroll state |
+| [Scroll Text](../examples/widget_scroll_text/app.rb) | Paragraph scrolling, viewport control, long content |
+| [Sparkline](../examples/widget_sparkline_demo/app.rb) | Mini charts, time series, bar sets |
+| [Style Colors](../examples/widget_style_colors/app.rb) | Named colors, RGB, indexed 256-color palette |
+| [Table](../examples/widget_table_demo/app.rb) | Row selection, column widths, per-cell styling |
+| [Tabs](../examples/widget_tabs_demo/app.rb) | Tab navigation, highlighting, dividers |
+| [Text Width](../examples/widget_text_width/app.rb) | Unicode-aware width measurement, CJK support |
+| [Canvas](../examples/widget_canvas_demo/app.rb) | Drawing shapes, markers, custom graphics |
+| [Cell](../examples/widget_cell_demo/app.rb) | Buffer cell inspection, styling attributes |
+| [Center](../examples/widget_center_demo/app.rb) | Centering content, horizontal/vertical alignment |
+| [Overlay](../examples/widget_overlay_demo/app.rb) | Layering widgets, modal backgrounds |
+| [Custom Render](../examples/widget_render/app.rb) | Low-level Draw API, escape hatch for custom widgets |
 
-#### [Layout Split Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/widget_layout_split/app.rb)
+### Sample Applications
 
-Demonstrates `Layout.split` with interactive attribute cycling. Features hotkey controls For direction (vertical/horizontal), all 7 flex modes (legacy, start, center, end, space_between, space_around, space_evenly), and constraint types (fill, length, percentage, min, ratio).
+These larger examples combine widgets into complete applications, demonstrating real-world TUI patterns and architectures.
 
-![widget_layout_split](./images/widget_layout_split.png)
+| Application | Architecture | What you'll learn |
+|-------------|--------------|-------------------|
+| [All Events](../examples/app_all_events/app.rb) | Model-View-Update | Event handling, unidirectional data flow, scalable structure |
+| [Color Picker](../examples/app_color_picker/app.rb) | Component-Based | Hit testing, modal dialogs, encapsulated state |
+| [Login Form](../examples/app_login_form/app.rb) | Overlay + Center | Modal forms, cursor positioning, text input |
+| [Stateful Interaction](../examples/app_stateful_interaction/app.rb) | State Objects | ListState/TableState, offset read-back, mouse click-to-row |
 
-#### [Login Form](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/app_login_form/app.rb)
+#### All Events
 
-Shows how to use `Overlay`, `Center`, and `Cursor` to build a modal login form with text input.
+[![all_events](./images/app_all_events.png)](../examples/app_all_events/README.md)
 
-![login_form](./images/app_login_form.png)
+#### Color Picker
 
+[![color_picker](./images/app_color_picker.png)](../examples/app_color_picker/README.md)
 
+#### Login Form
 
+[![login_form](./images/app_login_form.png)](../examples/app_login_form/README.md)
 
 
+## Next Steps
 
-### Widget Demos
+Now that you've seen what **ratatui_ruby** can do:
 
-These smaller, focused examples demonstrate specific widgets and their configuration options.
-
-*   [Bar Chart](../examples/widget_barchart_demo/app.rb)
-*   [Block (Interactive Demo)](../examples/widget_block_demo/app.rb)
-*   [Box (Block/Paragraph)](../examples/widget_box_demo/app.rb)
-*   [Calendar](../examples/widget_calendar_demo/app.rb)
-*   [Chart](../examples/widget_chart_demo/app.rb)
-*   [Gauge](../examples/widget_gauge_demo/app.rb)
-*   [Line Gauge](../examples/widget_line_gauge_demo/app.rb)
-*   [List](../examples/widget_list_demo/app.rb)
-*   [Map (Canvas)](../examples/widget_map_demo/app.rb)
-*   [Popup (Clear)](../examples/widget_popup_demo/app.rb)
-*   [Rect](../examples/widget_rect/app.rb)
-*   [Ratatui Logo](../examples/widget_ratatui_logo_demo/app.rb)
-*   [Ratatui Mascot](../examples/widget_ratatui_mascot_demo/app.rb)
-*   [Rich Text](../examples/widget_rich_text/app.rb)
-*   [Scrollbar](../examples/widget_scrollbar_demo/app.rb)
-*   [Scroll Text](../examples/widget_scroll_text/app.rb)
-*   [Sparkline](../examples/widget_sparkline_demo/app.rb)
-*   [Table (Selection)](../examples/widget_table_demo/app.rb)
-*   [Tabs](../examples/widget_tabs_demo/app.rb)
-*   [Widget Style Colors](../examples/widget_style_colors/app.rb)
+- **Deep dive**: Read the [Application Architecture](./application_architecture.md) guide for scaling patterns
+- **Test your TUI**: See the [Testing Guide](./application_testing.md) for snapshot and style assertions
+- **Explore the API**: Browse the [full RDoc documentation](./index.md)
+- **Learn the philosophy**: Read [Why RatatuiRuby?](./why.md) for comparisons and design decisions
+- **Get help**: Join the [discussion mailing list](https://lists.sr.ht/~kerrick/ratatui_ruby-discuss)

data/doc/v0.7.0_migration.md

@@ -0,0 +1,236 @@
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Migrating to v0.7.0
+
+v0.7.0 restructures the library to align with upstream Ratatui. For most users, this is a non-breaking change. For some, it is breaking.
+
+## Are You Affected?
+
+**If your code looks like this, you're fine:**
+
+```ruby
+RatatuiRuby.run do |tui|
+  tui.draw tui.paragraph(text: "Hello", block: tui.block(title: "Title"))
+  event = tui.poll_event
+end
+```
+
+The TUI API method names are unchanged. Your application works without modification.
+
+**If your code uses `highlight_style:` on Tables, rename it:**
+
+```ruby
+# Before (v0.6.0)
+tui.table(rows: [...], highlight_style: tui.style(fg: :yellow))
+
+# After (v0.7.0)
+tui.table(rows: [...], row_highlight_style: tui.style(fg: :yellow))
+```
+
+This change aligns with Ratatui's API naming convention.
+
+**If your code instantiates classes directly, you have work to do:**
+
+```ruby
+# These lines break in v0.7.0
+paragraph = RatatuiRuby::Paragraph.new(text: "Hello")
+style = RatatuiRuby::Style.new(fg: :red)
+rect = RatatuiRuby::Rect.new(x: 0, y: 0, width: 10, height: 5)
+```
+
+The old flat namespace no longer exists. Classes moved into modules.
+
+## Option 1: Use the TUI API (Recommended)
+
+Switch to the TUI API. It hides namespace verbosity and provides IDE autocomplete.
+
+```ruby
+RatatuiRuby.run do |tui|
+  # All these work exactly as before
+  paragraph = tui.paragraph(text: "Hello")
+  style = tui.style(fg: :red)
+  rect = tui.rect(x: 0, y: 0, width: 10, height: 5)
+  constraint = tui.constraint_length(20)
+  
+  # New in v0.7.0
+  cell = tui.table_cell(content: "Error", style: tui.style(bg: :red))
+  row = tui.table_row(cells: ["A", "B", "C"], style: tui.style(bg: :dark_gray))
+end
+```
+
+## Option 2: Update to New Namespaces
+
+If you prefer direct class instantiation, update to the new paths:
+
+| Before | After |
+|--------|-------|
+| `RatatuiRuby::Rect` | `RatatuiRuby::Layout::Rect` |
+| `RatatuiRuby::Constraint` | `RatatuiRuby::Layout::Constraint` |
+| `RatatuiRuby::Layout` | `RatatuiRuby::Layout::Layout` |
+| `RatatuiRuby::Style` | `RatatuiRuby::Style::Style` |
+| `RatatuiRuby::Paragraph` | `RatatuiRuby::Widgets::Paragraph` |
+| `RatatuiRuby::Block` | `RatatuiRuby::Widgets::Block` |
+| `RatatuiRuby::Table` | `RatatuiRuby::Widgets::Table` |
+| `RatatuiRuby::List` | `RatatuiRuby::Widgets::List` |
+| `RatatuiRuby::Cell` | `RatatuiRuby::Buffer::Cell` |
+| *(all other widgets)* | `RatatuiRuby::Widgets::*` |
+
+### Bulk Migration
+
+```bash
+find . -name "*.rb" -exec sed -i '' \
+  's/RatatuiRuby::Rect/RatatuiRuby::Layout::Rect/g; \
+   s/RatatuiRuby::Constraint\./RatatuiRuby::Layout::Constraint./g; \
+   s/RatatuiRuby::Paragraph\.new/RatatuiRuby::Widgets::Paragraph.new/g; \
+   s/RatatuiRuby::Block\.new/RatatuiRuby::Widgets::Block.new/g; \
+   s/RatatuiRuby::List\.new/RatatuiRuby::Widgets::List.new/g; \
+   s/RatatuiRuby::Table\.new/RatatuiRuby::Widgets::Table.new/g; \
+   s/RatatuiRuby::Style\.new/RatatuiRuby::Style::Style.new/g; \
+   s/RatatuiRuby::Session/RatatuiRuby::TUI/g; \
+   s/highlight_style:/row_highlight_style:/g' {} \;
+```
+
+## Session → TUI Rename
+
+The `Session` class is now `TUI`. If you reference it directly:
+
+```ruby
+# Before
+tui = RatatuiRuby::Session.new
+
+# After
+tui = RatatuiRuby::TUI.new
+```
+
+Most users never reference the class directly. The `|tui|` block parameter works unchanged.
+
+## Table: highlight_style → row_highlight_style
+
+The `highlight_style:` parameter on Table is now `row_highlight_style:`. This aligns with Ratatui's naming convention where `row_highlight_style`, `column_highlight_style`, and `cell_highlight_style` form a consistent trio.
+
+```ruby
+# Before (v0.6.0)
+tui.table(
+  rows: data,
+  highlight_style: tui.style(fg: :yellow)
+)
+
+# After (v0.7.0)
+tui.table(
+  rows: data,
+  row_highlight_style: tui.style(fg: :yellow)
+)
+```
+
+## Text::Line style Field
+
+`Text::Line` now accepts a `style:` parameter for line-level styling. This matches Ratatui's `Line` struct.
+
+```ruby
+# New in v0.7.0: Line-level styling
+line = tui.text_line(
+  spans: [tui.text_span(content: "Hello")],
+  style: tui.style(bg: :dark_gray)  # Applied to entire line
+)
+```
+
+Existing code without `style:` continues to work unchanged.
+
+## New Table Cell and Row Classes
+
+v0.7.0 adds `Widgets::Cell` and `Widgets::Row` for table construction with per-cell styling:
+
+```ruby
+table = tui.table(
+  rows: [
+    tui.table_row(
+      cells: [
+        tui.table_cell(content: "Name", style: tui.style(fg: :blue)),
+        "Value"
+      ],
+      style: tui.style(bg: :dark_gray)
+    )
+  ],
+  widths: [tui.constraint_length(20), tui.constraint_fill]
+)
+```
+
+## Buffer::Cell vs Widgets::Cell
+
+Two `Cell` classes now exist:
+
+- **`Buffer::Cell`** — Terminal cell for inspection (returned by `get_cell_at`)
+- **`Widgets::Cell`** — Table cell for construction (content + style wrapper)
+
+```ruby
+# Buffer inspection (unchanged)
+cell = RatatuiRuby.get_cell_at(0, 0)  # Returns Buffer::Cell
+cell.char  # => "X"
+cell.fg    # => :red
+
+# Table cell construction (new)
+cell = tui.table_cell(content: "Error", style: tui.style(bg: :red))
+```
+
+## Why This Change?
+
+The old flat namespace caused name collisions (`Cell` for buffers vs. tables) and diverged from Ratatui's module structure. The new hierarchy:
+
+- Maps 1:1 to Ratatui documentation
+- Prevents future collisions
+- Enables IDE autocomplete via explicit TUI methods
+
+---
+
+## For LLMs
+
+Copy the following prompt to your AI assistant to help migrate your `ratatui_ruby` application from v0.6.0 to v0.7.0.
+
+````markdown
+I'm migrating a Ruby TUI application from `ratatui_ruby` v0.6.0 to v0.7.0. The library restructured its namespaces. Apply these transformations:
+
+**Namespace Changes:**
+- `RatatuiRuby::Rect` → `RatatuiRuby::Layout::Rect`
+- `RatatuiRuby::Constraint` → `RatatuiRuby::Layout::Constraint`
+- `RatatuiRuby::Layout` → `RatatuiRuby::Layout::Layout`
+- `RatatuiRuby::Style` → `RatatuiRuby::Style::Style`
+- `RatatuiRuby::Paragraph` → `RatatuiRuby::Widgets::Paragraph`
+- `RatatuiRuby::Block` → `RatatuiRuby::Widgets::Block`
+- `RatatuiRuby::Table` → `RatatuiRuby::Widgets::Table`
+- `RatatuiRuby::List` → `RatatuiRuby::Widgets::List`
+- `RatatuiRuby::Cell` → `RatatuiRuby::Buffer::Cell`
+- All other widgets: `RatatuiRuby::X` → `RatatuiRuby::Widgets::X`
+
+**Class Rename:**
+- `RatatuiRuby::Session` → `RatatuiRuby::TUI`
+
+**Parameter Rename:**
+- `Table` `highlight_style:` → `row_highlight_style:`
+
+**Preferred Approach:** Convert direct class instantiation to TUI API:
+```ruby
+# Instead of:
+RatatuiRuby::Widgets::Paragraph.new(text: "Hello")
+
+# Use:
+tui.paragraph(text: "Hello")
+```
+
+**TUI API method names are unchanged.** Code using `tui.paragraph(...)`, `tui.block(...)`, `tui.style(...)` etc. works without modification.
+
+**Cell Disambiguation:**
+- `Buffer::Cell` — Terminal cell for inspection (returned by `get_cell_at`)
+- `Widgets::Cell` — Table cell for construction (use `tui.table_cell`)
+- The old `RatatuiRuby::Cell` is now `RatatuiRuby::Buffer::Cell`
+
+**New in v0.7.0:**
+- `tui.table_cell(content:, style:)` — styled table cells
+- `tui.table_row(cells:, style:, height:)` — styled table rows
+- `Text::Line` now accepts `style:` parameter
+
+Please update my code following these rules.
+````
+

data/doc/why.md

@@ -0,0 +1,93 @@
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# Why RatatuiRuby?
+
+The terminal is having a renaissance. Ruby deserves to be at the forefront.
+
+**RatatuiRuby** is a high-performance, immediate-mode TUI engine that brings the power of Rust's [Ratatui](https://ratatui.rs) library directly into Ruby. No ports. No emulations. A native bridge to the industry-standard Rust crate.
+
+
+## The Pitch
+
+You want to build a terminal UI. You love Ruby. Your options were:
+
+1. **Learn Go** for Bubble Tea
+2. **Learn Rust** for Ratatui
+3. **Use a pure-Ruby library** with limited performance
+
+We built a fourth option: **Write Ruby. Run Rust.**
+
+RatatuiRuby gives you Rust's layout engine, rendering speed, and battle-tested widgets — with Ruby's expressiveness, ecosystem, and joy.
+
+
+## RatatuiRuby vs. CharmRuby
+
+[CharmRuby](https://github.com/marcoroth/charm_ruby) is an excellent project by Marco Roth. It provides Ruby bindings to Charm's Go libraries (Bubble Tea, Lipgloss). The Ruby ecosystem is better because both projects exist.
+
+So which one should you choose?
+
+| | CharmRuby | RatatuiRuby |
+|---|-----------|-------------|
+| **Backend** | Go runtime | Rust (no runtime) |
+| **Architecture** | Elm Architecture (MVU) | Immediate-mode + your choice |
+| **GC Behavior** | Two GCs (Ruby + Go) | One GC (Ruby only) |
+| **Rendering** | String manipulation | Constraint-based layout tree |
+| **Best for** | Fans of Bubble Tea, MVU | Native performance, heavy-duty apps |
+
+**What's a runtime?** A runtime is background machinery that a language needs to run. Go has one (for goroutines and garbage collection). Rust doesn't — it compiles to plain machine code. When you use Go bindings, you're running *two* runtimes in the same process (Ruby's and Go's), which adds complexity and memory overhead. With Rust bindings, there's only Ruby.
+
+**Choose CharmRuby** if you prefer Charm's aesthetics or are migrating existing Bubble Tea code.
+
+**Choose RatatuiRuby** if you want zero-overhead native performance and architectural freedom. RatatuiRuby doesn't force a framework — you can build MVU, component-based, or any pattern you prefer.
+
+
+## Why Not Just Write Rust?
+
+Rust is amazing. It's also strict.
+
+The borrow checker enforces memory safety. That's great for systems programming. It's painful for UI iteration. Moving a sidebar, changing a color, or swapping a widget often requires refactoring ownership chains.
+
+With RatatuiRuby, you just change the object. You get Rust's performance where it matters — rendering — and Ruby's flexibility where it counts — designing.
+
+
+## Why Not Just Write Go?
+
+Go is pragmatic. But using Go bindings means running *two* runtimes in the same process: Ruby's and Go's. That adds complexity and memory overhead.
+
+With RatatuiRuby, there's only Ruby. Rust compiles to plain machine code with no runtime — it integrates seamlessly.
+
+
+## Why Ruby?
+
+[Ruby isn't just another language](https://www.ruby-lang.org/en/). It's an ecosystem:
+
+- **[ActiveRecord](https://guides.rubyonrails.org/active_record_basics.html)** — Query your database with elegant, chainable methods
+- **[RSpec](https://rspec.info/)** — Write expressive, readable tests with `describe`, `it`, and `expect`
+- **[Blocks](https://ruby-doc.org/docs/ruby-doc-bundle/UsersGuide/rg/blocks.html)** — Pass behavior to methods with `do...end`, the heart of Ruby's expressiveness
+- **[Metaprogramming](https://ruby-doc.org/docs/ruby-doc-bundle/UsersGuide/rg/objinitialization.html)** — Define methods dynamically, build DSLs, and write code that writes code
+- **[Bundler](https://bundler.io/)** — Access 180,000+ gems with a single `bundle add`
+
+Build a dashboard for your Rails app. Monitor your Sidekiq jobs. Create developer tools in the same language as the code they inspect.
+
+
+## The Philosophy: A Solid Foundation
+
+RatatuiRuby is a **low-level engine**. It provides raw primitives — Layouts, Blocks, Text, Tables, Charts — to build anything.
+
+It doesn't force a framework on you. You can use:
+- **Model-View-Update** for dashboards and data displays
+- **Component-based** patterns for interactive tools
+- **Your own architecture** for everything else
+
+This is the foundation for Ruby's next generation of TUI tools, dashboards, and interactive scripts.
+
+
+## Get Started
+
+Ready to build?
+
+- [Quickstart Guide](./quickstart.md) — Your first app in 5 minutes
+- [Widget Gallery](./quickstart.md#widget-demos) — See what's possible
+- [Application Architecture](./application_architecture.md) — Patterns for scaling

data/examples/app_all_events/README.md

@@ -5,9 +5,11 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 
 # App All Events Example
 
-This example application captures and visualizes every event supported by `ratatui_ruby`. It serves as a comprehensive reference for event handling and a demonstration of the Proto-TEA architectural pattern.
+[![App All Events](../../doc/images/app_all_events.png)](app.rb)
 
-## Architecture: Proto-TEA (Model-View-Update)
+This example application captures and visualizes every event supported by `ratatui_ruby`. It serves as a comprehensive reference for event handling and a demonstration of the Model-View-Update architectural pattern.
+
+## Architecture: Model-View-Update
 
 This application demonstrates **unidirectional data flow** inspired by The Elm Architecture. This separation ensures that state management is predictable and easy to test.
 
@@ -85,7 +87,7 @@ Complex applications require structured state habits. `AppAllEvents` and the [Co
 
 ### The Dashboard Approach (AppAllEvents)
 
-Dashboards display data. They rarely require complex mouse interaction. Proto-TEA works best here. State is immutable. Logic is pure. Updates are predictable. This simplifies testing.
+Dashboards display data. They rarely require complex mouse interaction. Model-View-Update works best here. State is immutable. Logic is pure. Updates are predictable. This simplifies testing.
 
 Use this pattern for logs, monitors, and data viewers.
 
@@ -93,7 +95,7 @@ Use this pattern for logs, monitors, and data viewers.
 
 Tools require interaction. Users click buttons and drag sliders. Each UI component needs to know where it exists on screen for hit testing.
 
-The Color Picker uses a "Proto-Kit (Component-Based)" pattern. Each component encapsulates its own rendering, state, and event handling. The Container routes events and coordinates cross-component effects.
+The Color Picker uses a Component-Based pattern. Each component encapsulates its own rendering, state, and event handling. The Container routes events and coordinates cross-component effects.
 
 Use this pattern for forms, editors, and mouse-driven tools.
 

data/examples/app_all_events/app.rb

@@ -23,7 +23,7 @@ require_relative "view/app_view"
 #
 # === Architecture
 #
-# This example uses the Proto-TEA (Model-View-Update) pattern:
+# This example uses the Model-View-Update pattern:
 # - **Model**: Immutable AppModel holds all state
 # - **Msg**: Semantic message types decouple events from logic
 # - **Update**: Pure function computes next state

data/examples/app_all_events/model/app_model.rb

@@ -7,7 +7,7 @@ require_relative "timestamp"
 require_relative "event_entry"
 require_relative "event_color_cycle"
 
-# Immutable application state for the Proto-TEA architecture.
+# Immutable application state for the Model-View-Update architecture.
 #
 # The Elm Architecture requires a single immutable Model. State changes return
 # a new Model instance. This consolidates all app state into one place.

data/examples/app_all_events/model/msg.rb

@@ -3,7 +3,7 @@
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-# Semantic message types for the Proto-TEA architecture.
+# Semantic message types for the Model-View-Update architecture.
 #
 # Raw events from the terminal are converted to semantic Msg types. This
 # decouples the Update function from the event system, making it easier