ratatui_ruby 0.6.0 → 0.7.0

data/doc/contributors/v1.0.0_blockers.md

@@ -0,0 +1,1729 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# alignment_audit
+## alignment_audit
+- Colors
+  - Reset (1)
+- Enums and Constants
+  - LegendPosition (4)
+- Symbol Sets
+  - Marker::HalfBlock (1)
+  - line::Set, bar::Set, block::Set, scrollbar::Set
+- Layout
+  - Rect methods (~13)
+  - Constraint batch constructors (6)
+  - Layout margin, spacing (2)
+- Style
+  - sub_modifier, underline_color (2)
+- Text
+  - Span methods (4)
+  - Line methods (6)
+
+######  MISALIGNED (non-additive, breaking)
+
+**All items fixed in v0.7.0:**
+
+- ~~Text::Line missing `style:` field~~ ✅ Added
+- ~~Widgets::Table uses `highlight_style:`~~ ✅ Renamed to `row_highlight_style:`
+
+
+---
+
+
+### alignment_audit_colors
+##### v0.7.0 Alignment Audit: Colors
+
+Audit of color alignment between Ratatui/Crossterm and RatatuiRuby.
+
+> [!IMPORTANT]
+> **MISSING** = Can be added as new features, backwards-compatible.
+> **MISALIGNED** = Requires breaking changes before v1.0.0.
+
+---
+
+######  Summary
+
+| Color Type | Ratatui | RatatuiRuby | Status |
+|------------|---------|-------------|--------|
+| Named colors (8 base) | ✅ | ✅ Symbols | ✅ Aligned |
+| Named colors (8 light) | ✅ | ✅ Symbols | ✅ Aligned |
+| `Reset` | ✅ | ⚠️ Not documented | MISSING |
+| `Rgb(r, g, b)` | ✅ | `"#RRGGBB"` | ✅ Aligned |
+| `Indexed(u8)` | ✅ | Integer (0-255) | ✅ Aligned |
+
+---
+
+######  MISALIGNED (Breaking Changes Required)
+
+**None.** All exposed color types are correctly aligned.
+
+---
+
+######  MISSING — Reset Color
+
+| Ratatui | Ruby | Status |
+|---------|------|--------|
+| `Color::Reset` | ❌ Not documented | MISSING |
+
+**Impact**: Users cannot explicitly reset foreground/background to terminal default.
+
+**Recommendation**: Document `:reset` symbol support if already implemented in Rust backend, or add support if missing.
+
+---
+
+######  Aligned — Named Colors (Base)
+
+| Ratatui | Ruby Symbol |
+|---------|-------------|
+| `Color::Black` | `:black` |
+| `Color::Red` | `:red` |
+| `Color::Green` | `:green` |
+| `Color::Yellow` | `:yellow` |
+| `Color::Blue` | `:blue` |
+| `Color::Magenta` | `:magenta` |
+| `Color::Cyan` | `:cyan` |
+| `Color::Gray` | `:gray` |
+
+---
+
+######  Aligned — Named Colors (Light/Bright)
+
+| Ratatui | Ruby Symbol |
+|---------|-------------|
+| `Color::DarkGray` | `:dark_gray` |
+| `Color::LightRed` | `:light_red` |
+| `Color::LightGreen` | `:light_green` |
+| `Color::LightYellow` | `:light_yellow` |
+| `Color::LightBlue` | `:light_blue` |
+| `Color::LightMagenta` | `:light_magenta` |
+| `Color::LightCyan` | `:light_cyan` |
+| `Color::White` | `:white` |
+
+---
+
+######  Aligned — RGB Colors
+
+| Ratatui | Ruby |
+|---------|------|
+| `Color::Rgb(255, 0, 0)` | `"#FF0000"` |
+| `Color::Rgb(0, 255, 0)` | `"#00FF00"` |
+| `Color::Rgb(0, 0, 255)` | `"#0000FF"` |
+
+Ruby accepts hex strings in the format `"#RRGGBB"`.
+
+---
+
+######  Aligned — Indexed Colors (256-color palette)
+
+| Ratatui | Ruby |
+|---------|------|
+| `Color::Indexed(0)` | `0` |
+| `Color::Indexed(42)` | `42` |
+| `Color::Indexed(255)` | `255` |
+
+Ruby accepts integers 0-255 representing the Xterm 256-color palette:
+- 0-15: Standard and bright ANSI colors
+- 16-231: 6×6×6 color cube
+- 232-255: Grayscale ramp
+
+---
+
+######  Supported Modifiers
+
+Ruby supports all Ratatui style modifiers:
+
+| Ratatui | Ruby Symbol |
+|---------|-------------|
+| `Modifier::BOLD` | `:bold` |
+| `Modifier::DIM` | `:dim` |
+| `Modifier::ITALIC` | `:italic` |
+| `Modifier::UNDERLINED` | `:underlined` |
+| `Modifier::SLOW_BLINK` | `:slow_blink` |
+| `Modifier::RAPID_BLINK` | `:rapid_blink` |
+| `Modifier::REVERSED` | `:reversed` |
+| `Modifier::HIDDEN` | `:hidden` |
+| `Modifier::CROSSED_OUT` | `:crossed_out` |
+
+---
+
+######  Recommendations
+
+| Priority | Item | Notes |
+|----------|------|-------|
+| Low | Document `:reset` color | May already be supported |
+
+All missing items are **additive** and do not require breaking changes.
+
+
+---
+
+
+### alignment_audit_enums_constants
+##### v0.7.0 Alignment Audit: Enums and Constants
+
+Audit of enum and constant alignment between Ratatui/Crossterm and RatatuiRuby.
+
+> [!IMPORTANT]
+> **MISSING** = Can be added as new features, backwards-compatible.
+> **MISALIGNED** = Requires breaking changes before v1.0.0.
+
+---
+
+######  Summary
+
+| Enum | Ratatui Variants | Ruby Symbols | Status |
+|------|------------------|--------------|--------|
+| `Alignment` | 3 | 3 | ✅ Aligned |
+| `BorderType` | 6 | 6+ | ✅ Aligned (Ruby adds `:hidden`) |
+| `Flex` | 6 | 6 | ✅ Aligned |
+| `HighlightSpacing` | 3 | 3 | ✅ Aligned |
+| `Borders` | 6 flags | 5 symbols | ✅ Aligned |
+| `GraphType` | 2 | 2 | ✅ Aligned |
+| `LegendPosition` | 8 | 4 | ⚠️ MISSING 4 |
+| `ListDirection` | 2 | 2 | ✅ Aligned |
+| `RenderDirection` (Sparkline) | 2 | 2 | ✅ Aligned |
+
+---
+
+######  MISALIGNED (Breaking Changes Required)
+
+**None.** All exposed enum values are correctly aligned.
+
+---
+
+######  MISSING — LegendPosition Variants
+
+| Ratatui | Ruby | Status |
+|---------|------|--------|
+| `TopLeft` | `:top_left` | ✅ |
+| `TopRight` | `:top_right` | ✅ |
+| `BottomLeft` | `:bottom_left` | ✅ |
+| `BottomRight` | `:bottom_right` | ✅ |
+| `Top` | ❌ | MISSING |
+| `Bottom` | ❌ | MISSING |
+| `Left` | ❌ | MISSING |
+| `Right` | ❌ | MISSING |
+
+**Impact**: Users cannot place chart legends at edge-center positions.
+
+---
+
+######  Aligned Enums (Detail)
+
+######  `Alignment`
+
+| Ratatui | Ruby | Used By |
+|---------|------|---------|
+| `Left` | `:left` | Paragraph, Line, Block title |
+| `Center` | `:center` | Paragraph, Line, Block title |
+| `Right` | `:right` | Paragraph, Line, Block title |
+
+---
+
+######  `BorderType`
+
+| Ratatui | Ruby | Characters |
+|---------|------|------------|
+| `Plain` | `:plain` | `┌─┐│└┘` |
+| `Rounded` | `:rounded` | `╭─╮│╰╯` |
+| `Double` | `:double` | `╔═╗║╚╝` |
+| `Thick` | `:thick` | `┏━┓┃┗┛` |
+| `QuadrantInside` | `:quadrant_inside` | `▗▄▖▐▝▘` |
+| `QuadrantOutside` | `:quadrant_outside` | `▛▀▜▌▙▟` |
+| N/A | `:hidden` | Ruby extension (spaces) |
+
+---
+
+######  `Flex`
+
+| Ratatui | Ruby |
+|---------|------|
+| `Legacy` | `:legacy` |
+| `Start` | `:start` |
+| `End` | `:end` |
+| `Center` | `:center` |
+| `SpaceBetween` | `:space_between` |
+| `SpaceAround` | `:space_around` |
+
+---
+
+######  `HighlightSpacing`
+
+| Ratatui | Ruby | Used By |
+|---------|------|---------|
+| `Always` | `:always` | Table, List |
+| `WhenSelected` | `:when_selected` | Table, List |
+| `Never` | `:never` | Table, List |
+
+---
+
+######  `Borders` (Bitflags)
+
+| Ratatui | Ruby |
+|---------|------|
+| `NONE` | `[]` (empty array) |
+| `TOP` | `:top` |
+| `BOTTOM` | `:bottom` |
+| `LEFT` | `:left` |
+| `RIGHT` | `:right` |
+| `ALL` | `:all` |
+
+Ruby uses array of symbols: `borders: [:top, :bottom]` vs Ratatui's `Borders::TOP | Borders::BOTTOM`.
+
+---
+
+######  `GraphType`
+
+| Ratatui | Ruby |
+|---------|------|
+| `Scatter` | `:scatter` |
+| `Line` | `:line` |
+
+---
+
+######  `ListDirection`
+
+| Ratatui | Ruby |
+|---------|------|
+| `TopToBottom` | `:top_to_bottom` |
+| `BottomToTop` | `:bottom_to_top` |
+
+---
+
+######  `RenderDirection` (Sparkline)
+
+| Ratatui | Ruby |
+|---------|------|
+| `LeftToRight` | `:left_to_right` |
+| `RightToLeft` | `:right_to_left` |
+
+---
+
+######  Recommendations
+
+| Priority | Item | Notes |
+|----------|------|-------|
+| Low | Add `:top`, `:bottom`, `:left`, `:right` to `legend_position` | Edge-center legend positions |
+
+All missing items are **additive** and do not require breaking changes.
+
+
+---
+
+
+### alignment_audit_granular_level
+##### v0.7.0 Alignment Audit (Parameter-Level)
+
+This document audits alignment between RatatuiRuby v0.7.0 and the upstream Ratatui/Crossterm Rust libraries at the **parameter and enum value level**. Only gaps are listed.
+
+> [!IMPORTANT]
+> **MISSING** = Can be added as new features, backwards-compatible.
+> **MISALIGNED** = Requires breaking changes before v1.0.0 release.
+
+---
+
+######  MISALIGNED (Breaking Changes Required)
+
+These require breaking changes before v1.0.0.
+
+######  `Text::Line` — ~~Missing `style` Field~~ ✅ Fixed
+
+| Current Ruby API | Ratatui API | Status |
+|------------------|-------------|--------|
+| `Line.new(spans:, alignment:, style:)` | `Line { style, alignment, spans }` | ✅ Aligned |
+
+**Fixed in v0.7.0**: Added `style:` parameter.
+
+---
+
+######  `Widgets::Table` — ~~Deprecated Parameter Name~~ ✅ Fixed
+
+| Ruby Parameter | Ratatui Parameter | Status |
+|----------------|-------------------|--------|
+| `row_highlight_style:` | `row_highlight_style` | ✅ Aligned |
+
+**Fixed in v0.7.0**: Renamed `highlight_style:` → `row_highlight_style:`.
+
+---
+
+######  MISSING — Layout Module
+
+######  `Layout::Rect` — Missing Methods
+
+| Missing Method | Signature | Notes |
+|----------------|-----------|-------|
+| `area` | `rect.area` → `Integer` | Returns `width * height` |
+| `left` | `rect.left` → `Integer` | Returns `x` (alias) |
+| `right` | `rect.right` → `Integer` | Returns `x + width` |
+| `top` | `rect.top` → `Integer` | Returns `y` (alias) |
+| `bottom` | `rect.bottom` → `Integer` | Returns `y + height` |
+| `union` | `rect.union(other)` → `Rect` | Bounding box of both rects |
+| `inner` | `rect.inner(margin)` → `Rect` | Shrink by margin |
+| `offset` | `rect.offset(dx, dy)` → `Rect` | Translate position |
+| `clamp` | `rect.clamp(other)` → `Rect` | Clamp to bounds |
+| `rows` | `rect.rows` → `Iterator` | Iterate row positions |
+| `columns` | `rect.columns` → `Iterator` | Iterate column positions |
+| `positions` | `rect.positions` → `Iterator` | Iterate all positions |
+| `is_empty` | `rect.empty?` → `Boolean` | True if zero area |
+
+---
+
+######  `Layout::Constraint` — Missing Batch Constructors
+
+| Missing Method | Signature |
+|----------------|-----------|
+| `from_lengths` | `Constraint.from_lengths([10, 20, 30])` → `[Constraint]` |
+| `from_percentages` | `Constraint.from_percentages([25, 50, 25])` → `[Constraint]` |
+| `from_mins` | `Constraint.from_mins([5, 10, 15])` → `[Constraint]` |
+| `from_maxes` | `Constraint.from_maxes([20, 30, 40])` → `[Constraint]` |
+| `from_fills` | `Constraint.from_fills([1, 2, 1])` → `[Constraint]` |
+| `from_ratios` | `Constraint.from_ratios([[1,4], [2,4], [1,4]])` → `[Constraint]` |
+
+---
+
+######  `Layout::Layout` — Missing Parameters
+
+| Missing Parameter | Ratatui Type | Notes |
+|-------------------|--------------|-------|
+| `margin` | `Margin { horizontal, vertical }` | Edge margins |
+| `spacing` | `u16` | Gap between segments |
+
+---
+
+######  MISSING — Style Module
+
+######  `Style::Style` — Missing Parameters/Methods
+
+| Missing | Ratatui API | Notes |
+|---------|-------------|-------|
+| `sub_modifier` | `style.remove_modifier(Modifier::BOLD)` | Remove specific modifiers |
+| `underline_color` | `style.underline_color(Color::Red)` | Set underline color separately |
+
+---
+
+######  MISSING — Text Module
+
+######  `Text::Span` — Missing Methods
+
+| Missing Method | Signature | Notes |
+|----------------|-----------|-------|
+| `width` | `span.width` → `Integer` | Display width in terminal cells |
+| `raw` | `Span.raw(content)` → `Span` | Constructor without style (alias for `new(content:)`) |
+| `patch_style` | `span.patch_style(style)` → `Span` | Merge style on top of existing |
+| `reset_style` | `span.reset_style` → `Span` | Clear style |
+
+---
+
+######  `Text::Line` — Missing Methods
+
+| Missing Method | Signature | Notes |
+|----------------|-----------|-------|
+| `left_aligned` | `line.left_aligned` → `Line` | Fluent setter for `:left` alignment |
+| `centered` | `line.centered` → `Line` | Fluent setter for `:center` alignment |
+| `right_aligned` | `line.right_aligned` → `Line` | Fluent setter for `:right` alignment |
+| `push_span` | `line.push_span(span)` → `Line` | Append span |
+| `patch_style` | `line.patch_style(style)` → `Line` | Merge style on all spans |
+| `reset_style` | `line.reset_style` → `Line` | Clear style on all spans |
+
+---
+
+######  MISSING — Widgets Module
+
+######  `Widgets::List` — Missing Parameters
+
+| Missing Parameter | Ratatui Name | Notes |
+|-------------------|--------------|-------|
+| N/A | N/A | List is fully aligned |
+
+---
+
+######  `Widgets::Table` — Missing Row Methods (via `Widgets::Row`)
+
+| Missing | Ratatui API | Notes |
+|---------|-------------|-------|
+| `enable_strikethrough` | `row.enable_strikethrough()` | Enable strikethrough on row |
+
+---
+
+######  `Widgets::Gauge` — Widget Not Implemented
+
+Ratatui has `Gauge` and `LineGauge` widgets. These are not currently exposed in RatatuiRuby.
+
+---
+
+######  `Widgets::Sparkline` — Missing Parameters
+
+| Missing Parameter | Ratatui Name | Notes |
+|-------------------|--------------|-------|
+| `max` | `max` | Maximum value for scaling |
+| `bar_set` | `bar_set` | Custom bar symbols |
+
+---
+
+######  `Widgets::Tabs` — Missing Parameters
+
+| Missing Parameter | Ratatui Name | Notes |
+|-------------------|--------------|-------|
+| `padding` | `padding` | Padding between tabs |
+| `divider` | `divider` | Divider between tabs |
+
+---
+
+######  `Widgets::Chart` — Fully Aligned
+
+Chart, Axis, and Dataset parameters are all aligned with Ratatui equivalents.
+
+---
+
+######  MISSING — Event Module (Crossterm)
+
+######  `MediaKeyCode` — All Values Aligned
+
+Ruby exposes all crossterm `MediaKeyCode` variants with snake_case mapping:
+
+| Crossterm | Ruby |
+|-----------|------|
+| `Play` | `:play` / `"play"` |
+| `Pause` | `:media_pause` / `"media_pause"` |
+| `PlayPause` | `:play_pause` / `"play_pause"` |
+| `Reverse` | `:reverse` / `"reverse"` |
+| `Stop` | `:stop` / `"stop"` |
+| `FastForward` | `:fast_forward` / `"fast_forward"` |
+| `Rewind` | `:rewind` / `"rewind"` |
+| `TrackNext` | `:track_next` / `"track_next"` |
+| `TrackPrevious` | `:track_previous` / `"track_previous"` |
+| `Record` | `:record` / `"record"` |
+| `LowerVolume` | `:lower_volume` / `"lower_volume"` |
+| `RaiseVolume` | `:raise_volume` / `"raise_volume"` |
+| `MuteVolume` | `:mute_volume` / `"mute_volume"` |
+
+---
+
+######  `ModifierKeyCode` — All Values Aligned
+
+Ruby exposes all crossterm `ModifierKeyCode` variants:
+
+| Crossterm | Ruby |
+|-----------|------|
+| `LeftShift` | `:left_shift` |
+| `LeftControl` | `:left_control` |
+| `LeftAlt` | `:left_alt` |
+| `LeftSuper` | `:left_super` |
+| `LeftHyper` | `:left_hyper` |
+| `LeftMeta` | `:left_meta` |
+| `RightShift` | `:right_shift` |
+| `RightControl` | `:right_control` |
+| `RightAlt` | `:right_alt` |
+| `RightSuper` | `:right_super` |
+| `RightHyper` | `:right_hyper` |
+| `RightMeta` | `:right_meta` |
+| `IsoLevel3Shift` | `:iso_level3_shift` |
+| `IsoLevel5Shift` | `:iso_level5_shift` |
+
+---
+
+######  `KeyModifiers` — All Values Aligned
+
+| Crossterm | Ruby |
+|-----------|------|
+| `SHIFT` | `"shift"` |
+| `CONTROL` | `"ctrl"` |
+| `ALT` | `"alt"` |
+| `SUPER` | `"super"` |
+| `HYPER` | `"hyper"` |
+| `META` | `"meta"` |
+
+---
+
+######  Summary
+
+| Category | Count | Priority |
+|----------|-------|----------|
+| **MISALIGNED** (breaking) | ~~2~~ 0 | ✅ All fixed in v0.7.0 |
+| **MISSING methods** | ~25 | Low (additive) |
+| **MISSING parameters** | ~10 | Low (additive) |
+| **MISSING widgets** | Gauge, LineGauge | Medium (new features) |
+
+######  Pre-v1.0.0 Checklist
+
+- [x] Add `style:` parameter to `Text::Line`
+- [x] Rename `highlight_style:` → `row_highlight_style:` in `Widgets::Table`
+
+---
+
+
+### alignment_audit_high_level
+##### v0.7.0 Alignment Audit
+
+This document audits strict alignment between RatatuiRuby v0.7.0 and the upstream Ratatui/Crossterm Rust libraries. The audit covers modules, classes, static methods, and constructor arguments as specified in the [Ruby Frontend Design](../design/ruby_frontend.md#1-ratatui-alignment).
+
+> [!NOTE]
+> The TUI facade API is explicitly excluded from this audit. It provides ergonomic shortcuts that intentionally diverge from Ratatui naming.
+
+---
+
+######  Module Structure Alignment
+
+| Rust Module | Ruby Module | Status | Notes |
+|-------------|-------------|--------|-------|
+| `ratatui::layout` | `RatatuiRuby::Layout` | ✅ Aligned | Rect, Constraint, Layout |
+| `ratatui::widgets` | `RatatuiRuby::Widgets` | ✅ Aligned | All widgets |
+| `ratatui::widgets::table` | `RatatuiRuby::Widgets` | ✅ Aligned | Row, Cell in Widgets (Rust has table submodule) |
+| `ratatui::style` | `RatatuiRuby::Style` | ✅ Aligned | Style, Color support |
+| `ratatui::text` | `RatatuiRuby::Text` | ✅ Aligned | Span, Line |
+| `ratatui::buffer` | `RatatuiRuby::Buffer` | ✅ Aligned | Cell for inspection |
+
+---
+
+######  Class-by-Class Audit
+
+######  Layout Module
+
+######  `Layout::Rect`
+
+| Attribute | Ratatui | RatatuiRuby | Status |
+|-----------|---------|-------------|--------|
+| `x` | `u16` | `Integer` | ✅ |
+| `y` | `u16` | `Integer` | ✅ |
+| `width` | `u16` | `Integer` | ✅ |
+| `height` | `u16` | `Integer` | ✅ |
+
+| Method | Ratatui | RatatuiRuby | Status |
+|--------|---------|-------------|--------|
+| `new(x, y, width, height)` | ✅ | ✅ | ✅ Aligned |
+| `contains(position)` | ✅ | `contains?(px, py)` | ✅ Aligned (Ruby uses two args) |
+| `intersects(other)` | ✅ | `intersects?(other)` | ✅ Aligned |
+| `intersection(other)` | ✅ | ✅ | ✅ Aligned |
+| `area()` | ✅ | ❌ Missing | Gap |
+| `left()`, `right()`, `top()`, `bottom()` | ✅ | ❌ Missing | Gap (trivial: `x`, `x+width`, etc.) |
+| `union(other)` | ✅ | ❌ Missing | Gap |
+| `inner(margin)` | ✅ | ❌ Missing | Gap |
+| `offset(offset)` | ✅ | ❌ Missing | Gap |
+
+**Verdict**: Core constructor and hit-testing aligned. Additional geometric methods are gaps for future work.
+
+---
+
+######  `Layout::Constraint`
+
+| Constructor | Ratatui | RatatuiRuby | Status |
+|-------------|---------|-------------|--------|
+| `Length(u16)` | ✅ | `length(v)` | ✅ Aligned |
+| `Percentage(u16)` | ✅ | `percentage(v)` | ✅ Aligned |
+| `Min(u16)` | ✅ | `min(v)` | ✅ Aligned |
+| `Max(u16)` | ✅ | `max(v)` | ✅ Aligned |
+| `Fill(u16)` | ✅ | `fill(v=1)` | ✅ Aligned |
+| `Ratio(u32, u32)` | ✅ | `ratio(num, denom)` | ✅ Aligned |
+
+| Batch Constructor | Ratatui | RatatuiRuby | Status |
+|-------------------|---------|-------------|--------|
+| `from_lengths([...])` | ✅ | ❌ Missing | Gap |
+| `from_percentages([...])` | ✅ | ❌ Missing | Gap |
+| `from_mins([...])` | ✅ | ❌ Missing | Gap |
+| `from_maxes([...])` | ✅ | ❌ Missing | Gap |
+| `from_fills([...])` | ✅ | ❌ Missing | Gap |
+| `from_ratios([...])` | ✅ | ❌ Missing | Gap |
+
+**Verdict**: All constraint variants aligned. Batch constructors are convenience gaps.
+
+---
+
+######  `Layout::Layout`
+
+| Attribute | Ratatui | RatatuiRuby | Status |
+|-----------|---------|-------------|--------|
+| `direction` | `:horizontal` / `:vertical` | `:horizontal` / `:vertical` | ✅ Aligned |
+| `constraints` | `Vec<Constraint>` | `Array<Constraint>` | ✅ Aligned |
+| `flex` | `Flex` enum | Symbol (`:start`, `:center`, etc.) | ✅ Aligned |
+| `margin` | `Margin` | ❌ Missing | Gap |
+| `spacing` | `u16` | ❌ Missing | Gap |
+
+**Verdict**: Core layout aligned. Margin and spacing are gaps.
+
+---
+
+######  Widgets Module
+
+######  `Widgets::Row`
+
+| Attribute | Ratatui | RatatuiRuby | Status |
+|-----------|---------|-------------|--------|
+| `cells` | `Vec<Cell>` | `Array` | ✅ Aligned |
+| `style` | `Style` | `Style` | ✅ Aligned |
+| `height` | `u16` | `Integer` | ✅ Aligned |
+| `top_margin` | `u16` | `Integer` | ✅ Aligned |
+| `bottom_margin` | `u16` | `Integer` | ✅ Aligned |
+
+**Verdict**: ✅ Fully aligned.
+
+---
+
+######  `Widgets::Cell`
+
+| Attribute | Ratatui | RatatuiRuby | Status |
+|-----------|---------|-------------|--------|
+| `content` | `Text` | `String`/`Span`/`Line` | ✅ Aligned |
+| `style` | `Style` | `Style` | ✅ Aligned |
+
+**Verdict**: ✅ Fully aligned.
+
+---
+
+######  `Widgets::Table`
+
+| Attribute | Ratatui | RatatuiRuby | Status |
+|-----------|---------|-------------|--------|
+| `rows` | `Vec<Row>` | `Array` | ✅ Aligned |
+| `header` | `Option<Row>` | `Array` or `nil` | ✅ Aligned |
+| `footer` | `Option<Row>` | `Array` or `nil` | ✅ Aligned |
+| `widths` | `Vec<Constraint>` | `Array<Constraint>` | ✅ Aligned |
+| `column_spacing` | `u16` | `Integer` | ✅ Aligned |
+| `style` | `Style` | `Style` | ✅ Aligned |
+| `highlight_style` | `Style` | `Style` | ✅ Aligned |
+| `highlight_symbol` | `Option<Text>` | `String` | ✅ Aligned |
+| `selected_row` | via state | `selected_row` | ✅ Aligned |
+| `selected_column` | via state | `selected_column` | ✅ Aligned |
+| `highlight_spacing` | `HighlightSpacing` | Symbol | ✅ Aligned |
+| `flex` | `Flex` | Symbol | ✅ Aligned |
+| `offset` | via state | `offset` | ✅ Aligned |
+| `block` | `Option<Block>` | `Block` | ✅ Aligned |
+
+**Verdict**: ✅ Fully aligned.
+
+---
+
+######  Style Module
+
+######  `Style::Style`
+
+| Attribute | Ratatui | RatatuiRuby | Status |
+|-----------|---------|-------------|--------|
+| `fg` | `Option<Color>` | `Symbol`/`String`/`Integer` | ✅ Aligned |
+| `bg` | `Option<Color>` | `Symbol`/`String`/`Integer` | ✅ Aligned |
+| `add_modifier` | `Modifier` | `modifiers: Array` | ⚠️ Different API |
+| `sub_modifier` | `Modifier` | ❌ Missing | Gap |
+| `underline_color` | `Option<Color>` | ❌ Missing | Gap |
+
+**API Difference**: Ratatui uses `add_modifier(Modifier::BOLD)` and `sub_modifier()`. Ruby uses `modifiers: [:bold]` array. This is an intentional Rubyism for ergonomics while being functionally equivalent.
+
+**Verdict**: Functionally aligned with idiomatic Ruby API.
+
+---
+
+######  Text Module
+
+######  `Text::Span`
+
+| Attribute | Ratatui | RatatuiRuby | Status |
+|-----------|---------|-------------|--------|
+| `content` | `Cow<str>` | `String` | ✅ Aligned |
+| `style` | `Style` | `Style` | ✅ Aligned |
+
+| Constructor | Ratatui | RatatuiRuby | Status |
+|-------------|---------|-------------|--------|
+| `raw(content)` | ✅ | ❌ (use `new`) | Gap (trivial) |
+| `styled(content, style)` | ✅ | `styled(content, style)` | ✅ Aligned |
+
+| Method | Ratatui | RatatuiRuby | Status |
+|--------|---------|-------------|--------|
+| `width()` | ✅ | ❌ Missing | Gap |
+
+**Verdict**: Core aligned. Missing `width()` instance method and `raw()` constructor.
+
+---
+
+######  `Text::Line`
+
+| Attribute | Ratatui | RatatuiRuby | Status |
+|-----------|---------|-------------|--------|
+| `spans` | `Vec<Span>` | `Array<Span>` | ✅ Aligned |
+| `style` | `Style` | ❌ Missing | Gap |
+| `alignment` | `Option<Alignment>` | `alignment` | ✅ Aligned |
+
+| Method | Ratatui | RatatuiRuby | Status |
+|--------|---------|-------------|--------|
+| `width()` | ✅ | ✅ | ✅ Aligned |
+| `left_aligned()` | ✅ | ❌ (use constructor) | Gap |
+| `centered()` | ✅ | ❌ (use constructor) | Gap |
+| `right_aligned()` | ✅ | ❌ (use constructor) | Gap |
+
+**Verdict**: Core aligned. Missing `style` field on Line (Ratatui has line-level style separate from span styles).
+
+---
+
+######  Buffer Module
+
+######  `Buffer::Cell`
+
+| Attribute | Ratatui | RatatuiRuby | Status |
+|-----------|---------|-------------|--------|
+| `char` / `symbol` | `String` | `char` | ✅ Aligned |
+| `fg` | `Color` | `Symbol`/`String`/`Integer` | ✅ Aligned |
+| `bg` | `Color` | `Symbol`/`String`/`Integer` | ✅ Aligned |
+| `modifiers` | `Modifier` | `Array<Symbol>` | ⚠️ Ruby array vs Rust bitflags |
+
+**Verdict**: ✅ Aligned (read-only inspection).
+
+---
+
+######  Summary
+
+######  Fully Aligned ✅
+
+- **Module structure**: All 5 modules map correctly
+- **Widgets::Row**: All 5 attributes aligned
+- **Widgets::Cell**: Both attributes aligned  
+- **Widgets::Table**: All major attributes aligned
+- **Layout::Constraint**: All 6 variants aligned
+- **Layout::Rect**: Constructor and hit-testing aligned
+
+######  Intentional Ruby Idioms ⚠️
+
+These are **not misalignments**. They are deliberate API choices that provide functional equivalence with idiomatic Ruby patterns:
+
+- **Style modifiers**: Array `[:bold, :italic]` vs Rust's `add_modifier(BOLD | ITALIC)`
+- **Buffer::Cell modifiers**: Same array-based approach
+
+---
+
+######  Gaps Analysis: MISSING vs MISALIGNED
+
+> [!IMPORTANT]
+> **MISSING** = Can be added as new features without breaking backwards compatibility.  
+> **MISALIGNED** = Requires breaking changes before v1.0.0 to fix API shape.
+
+######  MISSING Features (Additive, Backwards-Compatible) ✅
+
+These are gaps that can be filled in future minor releases without breaking existing code:
+
+| Component | Missing Feature | Notes |
+|-----------|-----------------|-------|
+| `Rect` | `area()`, `left()`, `right()`, `top()`, `bottom()` | New instance methods |
+| `Rect` | `union(other)`, `inner(margin)`, `offset(offset)` | New instance methods |
+| `Constraint` | `from_lengths()`, `from_percentages()`, etc. | New class methods |
+| `Layout` | `margin`, `spacing` | New optional constructor args |
+| `Style` | `sub_modifier`, `underline_color` | New optional constructor args |
+| `Span` | `width()` instance method | New instance method |
+| `Span` | `raw()` constructor | New class method (alias for `new`) |
+| `Line` | `left_aligned()`, `centered()`, `right_aligned()` | New instance methods (fluent) |
+
+######  MISALIGNED Structure (Breaking Changes Required) ⚠️
+
+> [!CAUTION]
+> These gaps represent **structural misalignment** where the current API shape differs from Ratatui in a way that cannot be fixed without breaking changes. **Must be addressed before v1.0.0.**
+
+| Component | Current API | Ratatui API | Required Change |
+|-----------|-------------|-------------|-----------------|
+| `Text::Line` | No `style` field | Has `style: Style` | Add `style:` parameter to `Line.new()` |
+
+**Details:**
+
+######  `Text::Line` Missing `style` Field
+
+Ratatui's `Line` has three fields:
+```rust
+pub struct Line<'a> {
+    pub style: Style,        // ← Missing in Ruby
+    pub alignment: Option<Alignment>,
+    pub spans: Vec<Span<'a>>,
+}
+```
+
+Ruby's `Line` has only two:
+```ruby
+class Line < Data.define(:spans, :alignment)
+```
+
+**Impact**: Users cannot set a line-level style that applies uniformly across all spans. They must either:
+1. Apply the same style to every span manually, or
+2. Wrap the line in a styled container
+
+**Required Fix**: Add `style:` parameter to `Line.new()`. This is a **breaking change** because:
+- Positional argument order changes (if used positionally)
+- `Data.define` member list changes
+
+**Recommendation**: Fix in v0.8.0 or earlier, before v1.0.0 API freeze.
+
+---
+
+######  Conclusion
+
+The v0.7.0 namespace restructuring achieves **strict alignment** with Ratatui's module hierarchy as specified in the design principles. All new types (`Widgets::Row`, `Widgets::Cell`, `Buffer::Cell`) follow the established pattern.
+
+######  Release Guidance
+
+| Category | Count | Action |
+|----------|-------|--------|
+| **Fully Aligned** | 6 components | ✅ No action needed |
+| **Intentional Idioms** | 2 items | ✅ Document as Ruby conventions |
+| **MISSING (additive)** | 14 features | 📋 Add in future minor releases |
+| **MISALIGNED (breaking)** | 1 issue | ⚠️ **Must fix before v1.0.0** |
+
+The single misalignment (`Text::Line` missing `style` field) is the only blocking issue for v1.0.0 API stability. All other gaps are additive and can be addressed incrementally.
+
+---
+
+
+### alignment_audit_symbol_sets
+##### v0.7.0 Alignment Audit: Symbol Sets
+
+Audit of symbol set alignment between Ratatui's `symbols::` module and RatatuiRuby.
+
+> [!IMPORTANT]
+> **MISSING** = Can be added as new features, backwards-compatible.
+> **MISALIGNED** = Requires breaking changes before v1.0.0.
+
+---
+
+######  Summary
+
+| Symbol Category | Ratatui | RatatuiRuby | Status |
+|-----------------|---------|-------------|--------|
+| `Marker` enum | 5 variants | 4 exposed | ⚠️ MISSING 1 |
+| `border::Set` | 12 predefined sets | Via `border_type:` symbols | ✅ Aligned |
+| Custom `border::Set` | Custom struct | Via `border_set:` hash | ✅ Aligned |
+| `line::Set` | 4 predefined sets | ❌ Not exposed | MISSING |
+| `bar::Set` | 2 predefined sets | ❌ Not exposed | MISSING |
+| `block::Set` | 2 predefined sets | ❌ Not exposed | MISSING |
+| `scrollbar::Set` | 4 predefined sets | ❌ Not exposed | MISSING |
+| `shade` constants | 5 constants | ❌ Not exposed | MISSING |
+
+---
+
+######  MISALIGNED (Breaking Changes Required)
+
+**None.** All exposed symbol sets are correctly aligned.
+
+---
+
+######  MISSING — Marker Enum
+
+######  `Marker::HalfBlock`
+
+| Ratatui | RatatuiRuby | Status |
+|---------|-------------|--------|
+| `Marker::Dot` | `:dot` | ✅ |
+| `Marker::Block` | `:block` | ✅ |
+| `Marker::Bar` | `:bar` | ✅ |
+| `Marker::Braille` | `:braille` | ✅ |
+| `Marker::HalfBlock` | ❌ Not exposed | MISSING |
+
+**Impact**: Users cannot use the `HalfBlock` marker type, which provides double-resolution square pixels using `█`, `▄`, and `▀` characters.
+
+---
+
+######  MISSING — Line Set Customization
+
+Ratatui provides `symbols::line::Set` with predefined sets:
+- `NORMAL` — Standard box-drawing characters
+- `ROUNDED` — Rounded corners
+- `DOUBLE` — Double-line characters
+- `THICK` — Thick line characters
+
+**Ruby Status**: Not directly exposed. Users cannot customize line symbols for widgets that use them internally.
+
+---
+
+######  MISSING — Bar Set Customization
+
+Ratatui provides `symbols::bar::Set` with predefined sets:
+- `THREE_LEVELS` — 3 distinct fill levels
+- `NINE_LEVELS` — 9 distinct fill levels (default)
+
+**Ruby Status**: Not exposed. Used internally by widgets like `Sparkline` but not configurable.
+
+---
+
+######  MISSING — Block Set Customization
+
+Ratatui provides `symbols::block::Set` with predefined sets:
+- `THREE_LEVELS` — 3 distinct fill levels
+- `NINE_LEVELS` — 9 distinct fill levels (default)
+
+**Ruby Status**: Not exposed. Used internally by `Gauge` widget but not configurable.
+
+---
+
+######  MISSING — Scrollbar Set Customization
+
+Ratatui provides `symbols::scrollbar::Set` with predefined sets:
+- `DOUBLE_VERTICAL` — Double-line vertical scrollbar
+- `DOUBLE_HORIZONTAL` — Double-line horizontal scrollbar
+- `VERTICAL` — Single-line vertical scrollbar
+- `HORIZONTAL` — Single-line horizontal scrollbar
+
+**Ruby Status**: Not exposed. Scrollbar widget not currently implemented in RatatuiRuby.
+
+---
+
+######  MISSING — Shade Constants
+
+Ratatui provides `symbols::shade` constants:
+- `EMPTY` — ` ` (space)
+- `LIGHT` — `░`
+- `MEDIUM` — `▒`
+- `DARK` — `▓`
+- `FULL` — `█`
+
+**Ruby Status**: Not exposed as constants.
+
+---
+
+######  Currently Aligned
+
+######  `border_type:` Parameter
+
+Ruby's `Block.new(border_type:)` maps to Ratatui's `border::Set`:
+
+| Ruby Symbol | Ratatui Constant | Characters |
+|-------------|------------------|------------|
+| `:plain` | `border::PLAIN` | `┌─┐│└┘` |
+| `:rounded` | `border::ROUNDED` | `╭─╮│╰╯` |
+| `:double` | `border::DOUBLE` | `╔═╗║╚╝` |
+| `:thick` | `border::THICK` | `┏━┓┃┗┛` |
+| `:quadrant_outside` | `border::QUADRANT_OUTSIDE` | `▛▀▜▌▙▟` |
+| `:quadrant_inside` | `border::QUADRANT_INSIDE` | `▗▄▖▐▝▘` |
+| `:hidden` | ❌ Custom Ruby | Empty borders (spaces) |
+
+######  `border_set:` Parameter
+
+Ruby supports custom border characters via hash:
+
+```ruby
+Block.new(border_set: {
+  top_left: "╭",
+  top_right: "╮",
+  bottom_left: "╰",
+  bottom_right: "╯",
+  vertical_left: "│",
+  vertical_right: "│",
+  horizontal_top: "─",
+  horizontal_bottom: "─"
+})
+```
+
+This is functionally equivalent to Ratatui's custom `border::Set`.
+
+---
+
+######  Recommendations
+
+| Priority | Item | Notes |
+|----------|------|-------|
+| Low | Add `:half_block` marker | Single symbol addition |
+| Low | Expose `line::Set` customization | For LineGauge widget |
+| Low | Expose `bar::Set` customization | For Sparkline widget |
+| Low | Expose `block::Set` customization | For Gauge widget |
+| Medium | Implement Scrollbar widget | Would include scrollbar::Set |
+
+All missing items are **additive** and do not require breaking changes.
+
+
+---
+
+
+### alignment_audit_tui_final
+##### TUI API Alignment Audit
+
+This document audits the `RatatuiRuby::TUI` facade API for method and parameter naming, with a focus on **Developer Experience (DX)** before the v1.0.0 release.
+
+######  Design Philosophy
+
+The TUI API follows a "Mullet Architecture": structured namespaces in the library, flat ergonomic DSL for users.
+
+**Guiding Principles:**
+
+1. **Terseness** — Fewer keystrokes for common operations
+2. **DWIM** — Do What I Mean; intuitive defaults
+3. **TIMTOWTDI** — Multiple valid ways to express the same thing
+4. **Big Tent** — Aliases for CSS/frontend developers, Ratatui natives, and Ruby purists
+5. **Two Levels Max** — `tui.thing` and `tui.scope_thing`, never `tui.scope.thing`, never `tui.ascope_bscope_thing`
+
+**Breaking Changes:** Pre-1.0 with few external users. Rename aggressively for DX. Document in CHANGELOG.
+
+---
+
+######  Method Naming Recommendations
+
+######  Pattern: Base Methods + Aliases + Dispatchers
+
+Base methods align with Ratatui's module API names. Aliases provide ergonomic shortcuts.
+
+1. **Base method** (Ratatui-aligned): `tui.shape_circle(...)` — matches `Widgets::Shape::Circle`
+2. **Aliases** (ergonomic): `tui.circle(...)`, `tui.circle_shape(...)`
+3. **Dispatcher**: `tui.shape(:circle, ...)` — errors helpfully on missing type
+
+This pattern applies to: shapes, constraints, text elements.
+
+---
+
+######  Canvas Shapes
+
+| Base Method | Add Aliases | Dispatcher |
+|-------------|-------------|------------|
+| `shape_circle` | `circle`, `circle_shape` | `shape(:circle, ...)` |
+| `shape_line` | `line_shape` *(not bare `line` — conflicts with `Text::Line`)* | `shape(:line, ...)` |
+| `shape_point` | `point`, `point_shape` | `shape(:point, ...)` |
+| `shape_rectangle` | `rectangle`, `rectangle_shape` | `shape(:rectangle, ...)` |
+| `shape_map` | `map`, `map_shape` | `shape(:map, ...)` |
+| `shape_label` | `label`, `label_shape` | `shape(:label, ...)` |
+
+**Dispatcher signature:**
+```ruby
+def shape(type, **kwargs)
+  case type
+  when :circle then shape_circle(**kwargs)
+  when :line then shape_line(**kwargs)
+  # ...
+  else
+    raise ArgumentError, "Unknown shape type: #{type.inspect}. " \
+      "Valid types: :circle, :line, :point, :rectangle, :map, :label"
+  end
+end
+```
+
+---
+
+######  Layout Constraints
+
+Ratatui's constraints map well to CSS layout concepts. Offer aliases for both communities:
+
+| Base Method | Add Aliases (CSS-Friendly) | Dispatcher |
+|-------------|---------------------------|------------|
+| `constraint_length(n)` | `fixed(n)`, `length(n)` | `constraint(:length, n)` |
+| `constraint_percentage(n)` | `percent(n)`, `percentage(n)` | `constraint(:percentage, n)` |
+| `constraint_min(n)` | `min(n)`, `min_content(n)` | `constraint(:min, n)` |
+| `constraint_max(n)` | `max(n)`, `max_content(n)` | `constraint(:max, n)` |
+| `constraint_fill(n)` | `fill(n)`, `flex(n)`, `fr(n)` | `constraint(:fill, n)` |
+| `constraint_ratio(a,b)` | `ratio(a,b)`, `aspect(a,b)` | `constraint(:ratio, a, b)` |
+
+**CSS Flexbox/Grid parallels:**
+- `fill(1)` ≈ CSS `flex: 1` or `1fr`
+- `fixed(100)` ≈ CSS `width: 100px`
+- `min(50)` ≈ CSS `min-width: 50px`
+- `percent(25)` ≈ CSS `width: 25%`
+
+**Dispatcher signature:**
+```ruby
+def constraint(type, *args)
+  case type
+  when :length, :fixed then constraint_length(*args)
+  when :percentage, :percent then constraint_percentage(*args)
+  when :min then constraint_min(*args)
+  when :max then constraint_max(*args)
+  when :fill, :flex, :fr then constraint_fill(*args)
+  when :ratio, :aspect then constraint_ratio(*args)
+  else
+    raise ArgumentError, "Unknown constraint type: #{type.inspect}. " \
+      "Valid types: :length, :percentage, :min, :max, :fill, :ratio"
+  end
+end
+```
+
+---
+
+######  Layout Operations
+
+| Current | Add Alias | Rationale |
+|---------|-----------|-----------|
+| `layout_split` | `split` | 52 usages in examples; clear in context |
+
+---
+
+######  Text Factories
+
+| Current | Status | Notes |
+|---------|--------|-------|
+| `text_span` | ✓ Has alias `span` | |
+| `text_line` | ✓ Has alias `line` | |
+| `text_width` | Keep as-is | Distinct from `length` (constraint) |
+
+Add dispatcher:
+```ruby
+def text(type, **kwargs)
+  case type
+  when :span then text_span(**kwargs)
+  when :line then text_line(**kwargs)
+  else
+    raise ArgumentError, "Unknown text type: #{type.inspect}. Valid types: :span, :line"
+  end
+end
+```
+
+---
+
+######  Widget Factories
+
+| Current | Add Alias | Rationale |
+|---------|-----------|-----------|
+| `list_item` | `item` | Clear in list context |
+| `table_row` | Keep alongside `row` | DWIM — both valid mental models |
+| `table_cell` | Keep as-is | `cell` means `Buffer::Cell` |
+| `bar_chart_bar` | Keep alongside `bar` | DWIM — don't deprecate |
+| `bar_chart_bar_group` | Keep alongside `bar_group` | DWIM — don't deprecate |
+
+Add dispatcher:
+```ruby
+def widget(type, **kwargs)
+  case type
+  when :block then block(**kwargs)
+  when :paragraph then paragraph(**kwargs)
+  when :list then list(**kwargs)
+  when :table then table(**kwargs)
+  # ... all widgets
+  else
+    raise ArgumentError, "Unknown widget type: #{type.inspect}."
+  end
+end
+```
+
+---
+
+######  State Factories
+
+| Current | Status |
+|---------|--------|
+| `list_state` | Keep as-is |
+| `table_state` | Keep as-is |
+| `scrollbar_state` | Keep as-is |
+
+Add dispatcher:
+```ruby
+def state(type, **kwargs)
+  case type
+  when :list then list_state(**kwargs)
+  when :table then table_state(**kwargs)
+  when :scrollbar then scrollbar_state(**kwargs)
+  else
+    raise ArgumentError, "Unknown state type: #{type.inspect}."
+  end
+end
+```
+
+---
+
+######  Parameter Names
+
+All current parameter names are well-chosen. No changes recommended.
+
+| Widget | Parameter | Status |
+|--------|-----------|--------|
+| `List` | `selected_index`, `highlight_style`, etc. | ✓ |
+| `Table` | `row_highlight_style`, `selected_row`, etc. | ✓ |
+| `Scrollbar` | `content_length`, `position`, etc. | ✓ |
+| All | `block`, `style`, `offset` | ✓ Consistent |
+
+---
+
+######  Summary of Changes
+
+######  High Priority (Immediate DX Wins)
+
+1. **Add `split` alias** for `layout_split`
+2. **Add `item` alias** for `list_item`
+3. **Add terse shape aliases**: `circle`, `point`, `rectangle`, `map`, `label`
+4. **Add CSS-friendly constraint aliases**: `fixed`, `percent`, `fill`, `flex`, `fr`, `min`, `max`
+
+######  Medium Priority (Pattern Completion)
+
+5. **Add dispatcher methods**: `shape(type, ...)`, `constraint(type, ...)`, `text(type, ...)`, `widget(type, ...)`, `state(type, ...)`
+6. **Add bidirectional shape aliases**: `circle_shape`, `point_shape`, etc.
+
+######  Not Changing
+
+- Don't deprecate verbose forms (`table_row`, `bar_chart_bar`, etc.) — DWIM
+- Don't rename parameters — already optimal
+- Don't add third level aliases (`tui.widgets.paragraph`) — two levels max
+
+---
+
+######  Implementation Checklist
+
+- [ ] Add `split` alias to `LayoutFactories`
+- [ ] Add `item` alias to `WidgetFactories`
+- [ ] Add terse shape aliases to `CanvasFactories`
+- [ ] Add CSS-friendly constraint aliases to `LayoutFactories`
+- [ ] Add `shape(type, ...)` dispatcher
+- [ ] Add `constraint(type, ...)` dispatcher
+- [ ] Add bidirectional shape aliases (`*_shape`)
+- [ ] Add `text(type, ...)`, `widget(type, ...)`, `state(type, ...)` dispatchers
+- [ ] Update RBS signatures for all new methods
+- [ ] Update RDoc for all new methods
+- [ ] Update CHANGELOG.md
+
+---
+
+######  Breaking Changes Analysis
+
+If all recommendations in this audit are adopted, **none constitute breaking changes** under semver.
+
+| Recommendation | Breaking? | Rationale |
+|----------------|-----------|-----------|
+| Add `split` alias | No | Additive; `layout_split` unchanged |
+| Add `item` alias | No | Additive; `list_item` unchanged |
+| Add terse shape aliases (`circle`, etc.) | No | Additive; `shape_*` methods unchanged |
+| Add CSS-friendly constraint aliases | No | Additive; `constraint_*` methods unchanged |
+| Add bidirectional aliases (`*_shape`) | No | Additive; does not remove existing forms |
+| Add dispatcher methods | No | Additive; new methods only |
+| Keep verbose forms (`table_row`, etc.) | No | No removal or rename |
+
+**Conclusion:** This audit recommends only additive changes. All existing code will continue to work unchanged.
+
+> [!NOTE]
+> If we later decide to **remove** verbose forms like `bar_chart_bar` or `bar_chart_bar_group`, that would be a breaking change requiring a major version bump. This audit explicitly recommends **keeping** them (DWIM philosophy).
+
+
+
+---
+
+
+# dwim_dx
+## dwim_dx
+#### Problem Statement
+
+Ruby's philosophy of "Do What I Mean" (DWIM) and human-centric design should extend to ratatui_ruby's API. Currently, app developers encounter friction points that force them to remember non-obvious conventions, use overly verbose code, or pattern-match when simple predicates would suffice.
+
+This proposal identifies DX issues across the widget API and suggests improvements that maintain backward compatibility while providing ergonomic alternatives.
+
+#### DX Issues Identified
+
+##### 1. Confusing Event Method Names
+
+**Current problem**: `event.char` doesn't exist, but `event.code` returns things like `"enter"`, `"ctrl"`, not just characters.
+
+**What users expect**: 
+- `event.char` should return the printable character (matching the name)
+- `event.ctrl_c?`, `event.enter?`, etc. should work for all key combinations
+- `event.key?`, `event.mouse?` predicates exist but only for broad categories
+
+**Solution implemented**: Added `char` method and dynamic predicates via `method_missing`. See `lib/ratatui_ruby/event/key.rb`.
+
+##### 2. Dual Parameter APIs Without Predicates
+
+**Current problem**: Widgets accept both forms but no convenience methods to query the state:
+
+```ruby
+### Both work, but which one does the widget store?
+gauge1 = Gauge.new(ratio: 0.75)
+gauge2 = Gauge.new(percent: 75)
+gauge1.ratio  # Works
+gauge1.percent  # Does NOT exist
+```
+
+Similarly with List and Table:
+```ruby
+list.selected_index = 2  # Works
+list.selected?  # Does NOT exist
+list.is_selected?  # Does NOT exist
+```
+
+**Affected widgets**: 
+- `Gauge` (ratio vs percent)
+- `LineGauge` (ratio vs percent)
+- `List` (selected_index with no query methods)
+- `Table` (selected_row and selected_column with no query methods)
+
+**Suggested solutions**:
+
+For `Gauge` and `LineGauge`:
+```ruby
+### Add convenience predicates
+gauge.percent  # => 75 (coerced from ratio internally)
+gauge.percent = 50  # => Updates ratio to 0.5
+
+### Or provide explicit accessors
+gauge.as_percent  # => 75
+gauge.as_ratio   # => 0.75
+```
+
+For `List` and `Table`:
+```ruby
+list.selected?  # => true if selected_index is not nil
+list.selection  # => 2 (alias for selected_index)
+list.selected_item  # => "Item 3"
+
+table.selected_row?  # => true if selected_row is not nil
+table.selected_cell?  # => true if both row and column selected
+```
+
+##### 3. Symbol Constants for Enum Values
+
+**Current problem**: Magic symbol values scattered across code:
+
+```ruby
+list = List.new(
+  highlight_spacing: :when_selected,  # What are the other options?
+  direction: :top_to_bottom,          # Is :bottom_to_top valid?
+)
+
+layout = Layout.new(
+  flex: :legacy  # What does "legacy" mean?
+)
+
+gauge = Gauge.new(
+  use_unicode: true  # Unclear what ASCII fallback looks like
+)
+```
+
+Users must consult docs or source code to discover valid options.
+
+**Suggested solution**: Add constants to widget classes:
+
+```ruby
+class List < Data
+  # Highlight spacing modes
+  HIGHLIGHT_ALWAYS = :always
+  HIGHLIGHT_WHEN_SELECTED = :when_selected
+  HIGHLIGHT_NEVER = :never
+
+  # Direction modes
+  DIRECTION_TOP_TO_BOTTOM = :top_to_bottom
+  DIRECTION_BOTTOM_TO_TOP = :bottom_to_top
+end
+
+list = List.new(
+  highlight_spacing: List::HIGHLIGHT_WHEN_SELECTED,
+  direction: List::DIRECTION_TOP_TO_BOTTOM,
+)
+```
+
+Benefits:
+- IDE autocomplete shows valid options
+- Self-documenting code
+- Typos caught at runtime (symbol vs constant)
+- Easy to grep for where these modes are used
+
+Affected widgets and their enum values:
+- `List`: `highlight_spacing` (:always, :when_selected, :never), `direction` (:top_to_bottom, :bottom_to_top)
+- `Table`: `highlight_spacing` (same as List), `flex` (:legacy, :default, :fill)
+- `Layout`: `direction` (:vertical, :horizontal), `flex` (:legacy, :default, :fill)
+- `Gauge`/`LineGauge`: `use_unicode` (boolean, but could have MODE_UNICODE, MODE_ASCII)
+- `Paragraph`: `alignment` (:left, :center, :right)
+- `Block`: `border_type` (:plain, :rounded, :double, :thick)
+- `Canvas`: `marker` (:braille, :dots, :half_block, :sextant, :octant)
+
+##### 4. Inconsistent Style APIs
+
+**Current problem**: Different widgets accept styles differently:
+
+```ruby
+### Table accepts both
+table = Table.new(style: Style.new(fg: :blue))
+table = Table.new(style: { fg: :blue })  # Hash shorthand
+
+### But Paragraph doesn't
+paragraph = Paragraph.new(text: "hi", style: Style.new(fg: :blue))
+paragraph = Paragraph.new(text: "hi", style: { fg: :blue })  # Works but undocumented
+
+### And Gauge has separate properties
+gauge = Gauge.new(style: Style.new(fg: :blue), gauge_style: Style.new(fg: :green))
+```
+
+**Suggested solution**: Standardize style handling across all widgets:
+
+1. All widgets should accept `Style` objects and `Hash` shorthand
+2. Document this clearly in each widget
+3. Add a convenience constructor:
+
+```ruby
+class Style
+  def self.with(fg: nil, bg: nil, modifiers: [])
+    Style.new(fg: fg, bg: bg, modifiers: modifiers)
+  end
+end
+
+### Cleaner than always spelling out keyword args
+paragraph = Paragraph.new(text: "hi", style: Style.with(fg: :blue))
+```
+
+##### 5. Missing State Query Predicates
+
+**Current problem**: Widgets store state but provide no query methods:
+
+```ruby
+list.selected_index = 0
+
+### To check if something is selected, must do:
+if list.selected_index&.nonzero?  # Awkward
+if list.selected_index.nil? == false  # Confusing
+
+### Should be:
+list.selected?  # => true
+list.empty?  # => false (for items array)
+```
+
+**Suggested solution**: Add predicates to state-holding widgets:
+
+```ruby
+### List
+list.selected?      # => !selected_index.nil?
+list.empty?         # => items.empty?
+list.selection      # => selected_index (alias)
+list.selected_item  # => items[selected_index] (convenience)
+
+### Table
+table.selected_row?    # => !selected_row.nil?
+table.selected_cell?   # => !selected_row.nil? && !selected_column.nil?
+table.empty?           # => rows.empty?
+
+### Gauge
+gauge.filled?          # => ratio > 0
+gauge.complete?        # => ratio >= 1.0
+```
+
+##### 6. Magic Numeric Coercions
+
+**Current problem**: Widgets accept `Numeric` but silently coerce:
+
+```ruby
+### These all work, but behavior is undocumented
+list = List.new(selected_index: "2")    # Coerced to 2
+list = List.new(selected_index: 2.7)    # Coerced to 2
+list = List.new(selected_index: 2.0)    # Coerced to 2
+
+gauge = Gauge.new(percent: 150)  # Should clamp?
+gauge = Gauge.new(ratio: 1.5)    # Should clamp?
+```
+
+**Suggested solution**: 
+
+1. Document coercion rules explicitly in RDoc
+2. Add validation and raise on invalid inputs:
+
+```ruby
+def initialize(percent: nil, ...)
+  if percent
+    raise ArgumentError, "percent must be 0..100, got #{percent}" unless percent.between?(0, 100)
+    ratio = Float(percent) / 100.0
+  end
+end
+```
+
+3. Provide clear error messages:
+```ruby
+gauge = Gauge.new(percent: 150)
+### => ArgumentError: percent must be between 0 and 100 (got 150)
+```
+
+#### Implementation Strategy
+
+##### Phase 1: State Query Predicates
+- [ ] Add predicates to `List` (selected?, empty?, selected_item)
+- [ ] Add predicates to `Table` (selected_row?, selected_cell?, empty?)
+- [ ] Add predicates to `Gauge` (filled?, complete?)
+- [ ] Tests for all new predicates
+
+##### Phase 2: Symbol Constants
+- [ ] Add enum constants to `List`, `Table`, `Layout`
+- [ ] Add enum constants to `Gauge`, `LineGauge`, `Paragraph`, `Block`
+- [ ] Update all examples to use constants
+- [ ] Document constants in RDoc
+
+##### Phase 3: Style Consistency
+- [ ] Standardize `Hash` shorthand support across all widgets
+- [ ] Add `Style.with(fg:, bg:, modifiers:)` convenience constructor
+- [ ] Update `.rbs` files to reflect HashStyle support
+- [ ] Document in style guide
+
+##### Phase 4: Numeric Coercion Validation
+- [ ] Add validation to `Gauge`, `LineGauge`, `List`, `Table`
+- [ ] Raise `ArgumentError` on out-of-range values
+- [ ] Provide clear error messages
+- [ ] Update tests
+
+##### Phase 5: Convenience Accessors
+- [ ] Add `percent` to `Gauge` and `LineGauge`
+- [ ] Add `selection` alias to `List` and `Table`
+- [ ] Add `selected_item` to `List`
+- [ ] Tests and documentation
+
+#### Example: Before and After
+
+##### Before (Confusing)
+```ruby
+class GameApp
+  def initialize
+    @menu = List.new(
+      items: ["Start Game", "Load Game", "Options", "Quit"],
+      selected_index: 0,
+      highlight_spacing: :when_selected,  # What's valid here?
+      direction: :top_to_bottom
+    )
+  end
+
+  def handle_input(event)
+    case event
+    when :ctrl_c
+      exit
+    when :up
+      if @menu.selected_index && @menu.selected_index > 0
+        @menu = @menu.with(selected_index: @menu.selected_index - 1)
+      end
+    end
+  end
+
+  def render(tui)
+    tui.draw(@menu)
+  end
+end
+```
+
+##### After (DWIM)
+```ruby
+class GameApp
+  def initialize
+    @menu = List.new(
+      items: ["Start Game", "Load Game", "Options", "Quit"],
+      selected_index: 0,
+      highlight_spacing: List::HIGHLIGHT_WHEN_SELECTED,  # IDE autocomplete!
+      direction: List::DIRECTION_TOP_TO_BOTTOM
+    )
+  end
+
+  def handle_input(event)
+    return if event.ctrl_c?  # Dynamic predicate!
+    
+    if event.up?
+      move_menu_up if @menu.selected?  # State predicate!
+    end
+  end
+
+  def move_menu_up
+    index = @menu.selected_index
+    return if index == 0
+    @menu = @menu.with(selected_index: index - 1)
+  end
+
+  def render(tui)
+    tui.draw(@menu)
+  end
+end
+```
+
+#### Migration Path
+
+All changes are backward compatible (additive):
+- Existing code using symbols continues to work
+- New constants coexist with symbols
+- New predicates don't change existing behavior
+- New methods are additions, not replacements
+
+Apps can migrate at their own pace:
+```ruby
+### Old style still works
+list = List.new(highlight_spacing: :when_selected)
+
+### New style also works
+list = List.new(highlight_spacing: List::HIGHLIGHT_WHEN_SELECTED)
+
+### Mix and match
+if list.selected?  # New predicate
+  puts list.selected_index  # Old accessor
+end
+```
+
+#### Metrics for Success
+
+1. **Discoverability**: New developers can find valid options via IDE autocomplete
+2. **Clarity**: Code self-documents valid states and modes
+3. **Type safety**: Constants and predicates provide type checking
+4. **Error feedback**: Invalid inputs raise with helpful messages
+5. **Backward compatibility**: Zero breaking changes, all existing code works
+
+#### Related Issues
+
+- AGENTS.md requirement: All examples must have tests verifying behavior
+- Example improvements: Apply constants and predicates to all example code
+- Documentation: Update style guide with DWIM principles
+
+
+---
+
+
+# examples_audit
+## examples_audit
+##### [P1: Moderate (Quality)](#p2_moderate)
+
+1. **[Add RDoc Cross-Links](#1-add-rdoc-cross-links-examples--aliases)** (Documentation discoverability)
+   - Link library classes/methods to examples
+   - Link DWIM/TIMTOWTDI aliases
+   - Create consistent pattern across public APIs
+
+
+---
+
+
+### p2_moderate
+#### Priority 2: Moderate (Quality Gates)
+
+These are v1.0.0 quality improvements that refine the example suite after P0 is complete. Not blocking, but recommended for maintainability and API consistency.
+
+---
+
+##### 1. Add RDoc Cross-Links (Examples & Aliases)
+
+**Status:** Important for API discoverability — Documentation should link library and examples
+
+RDoc should cross-link between:
+- **Library classes/methods** ↔ **Examples that use them** (See also: examples/widget_foo_demo)
+- **Primary methods** ↔ **DWIM/TIMTOWTDI aliases** (See also: tui.foo_bar as alias for tui.foo(:bar))
+
+######  Current Practice
+
+Done for:
+- `RatatuiRuby::Frame#set_cursor_position` ↔ `RatatuiRuby::Cursor` (cross-linking)
+- Limited elsewhere
+
+######  Gaps
+
+- Most widget classes have no "See also: example_foo_demo" links
+- Aliases/TIMTOWTDI variants are not documented as such
+- Users can't easily find examples for a given class/method
+
+######  Action
+
+1. Add `# See also: examples/widget_foo_demo/app.rb` to class/method RDoc
+2. Link DWIM methods to TIMTOWTDI variants: `# Also available as: tui.constraint_length (DWIM) vs tui.constraint(:length) (TIMTOWTDI)`
+3. Create consistent pattern across all public APIs in `lib/ratatui_ruby/`
+
+######  Example Pattern
+
+```ruby
+#### Renders text with styling.
+#
+#### See also: examples/widget_paragraph_demo/app.rb (basic paragraph rendering)
+class Paragraph < Data.define(...)
+  # ...
+end
+
+#### DWIM version of constraint creation
+#### Also available as: constraint(type, value) for explicit control
+def constraint_length(length)
+  constraint(:length, length)
+end
+```
+
+---
+
+##### 2. Enhance Widget Examples with Functional Context
+
+**Status:** Recommended — Move beyond "parameter playgrounds" to "real-world patterns"
+
+Current `widget_*` examples mostly focus on interactive parameter turning (changing colors, borders, etc.). While useful for API discovery, they don't show *how* to use the widget in a real application logic flow.
+
+######  The Standard: widget_tabs_demo
+
+The `widget_tabs_demo` was enhanced to show **conditional rendering** of content based on the selected tab in git commit `38ceed39a011d557cc66e11a4598d3341dc7a0cc`. It doesn't just highlight the tab; it changes the screen content. This connects the widget (the tabs) to the problem it solves (view segregation).
+
+######  Action
+
+Identify other widget examples that could benefit from this "functional context" treatment:
+
+-   **widget_popup_demo:** Show a multi-step modal flow (e.g., Confirm -> Success) rather than just a static overlay.
+-   **widget_list_demo:** Show a master-detail view where selecting a list item updates a detail pane.
+-   **widget_input_demo:** (If created) Show specific validation logic (email vs number).
+
+**Goal:** Every widget example should answer "How do I build a feature with this?" not just "What does this parameter do?"