ratatui_ruby 0.8.0 → 0.9.0

data/doc/contributors/developing_examples.md

@@ -1,6 +1,6 @@
 <!--
-SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
 # Developing Examples
@@ -12,6 +12,11 @@ Guidelines for creating and testing examples in the `examples/` directory.
 Every interactive example should follow this pattern, living in its own directory:
 
 `examples/my_example/app.rb`:
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 require "ratatui_ruby"
@@ -57,6 +62,7 @@ end
 
 MyExampleApp.new.run if __FILE__ == $PROGRAM_NAME
 ```
+<!-- SPDX-SnippetEnd -->
 
 ### Naming Convention (Required)
 
@@ -89,6 +95,11 @@ All interactive examples must fit within an **80×24 terminal** (standard VT100
 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`:
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```rbs
 class MyExampleApp
   # @public
@@ -98,11 +109,17 @@ class MyExampleApp
   def run: () -> void
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ## Directory Structure
 
 Examples are organized across three locations:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```
 examples/
   my_example/
@@ -119,6 +136,7 @@ sig/examples/
   my_example/
     app.rbs             ← REQUIRED: Type signatures (centralized, not local to example)
 ```
+<!-- SPDX-SnippetEnd -->
 
 ### Key Requirements
 
@@ -194,17 +212,28 @@ This keeps the UI self-documenting and users can see exact parameter names when
 
 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:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 if @sidebar_rect&.contains?(event.x, event.y)
   # Handle click
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ## Testing Examples
 
 Example tests live in a centralized test tree:
 
 `test/examples/my_example/test_app.rb`:
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 require "ratatui_ruby"
@@ -228,6 +257,7 @@ class TestMyExampleApp < Minitest::Test
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ## Snapshot Testing Pattern (REQUIRED)
 
@@ -243,6 +273,11 @@ All example tests MUST use snapshot testing via the `assert_snapshots` API, not
 
 ### Basic Pattern
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 def test_initial_render
   with_test_terminal do
@@ -253,6 +288,7 @@ def test_initial_render
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 Snapshot auto-saved to: `test/examples/widget_foo/snapshots/initial_render.txt`
 
@@ -260,6 +296,11 @@ Snapshot auto-saved to: `test/examples/widget_foo/snapshots/initial_render.txt`
 
 For examples with timestamps, random data, or other non-deterministic output:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 private def assert_normalized_snapshots(snapshot_name)
   assert_plain_snapshot(snapshot_name) do |actual|
@@ -280,6 +321,7 @@ def test_after_event
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 See `test/examples/app_all_events/test_app.rb` for a complete example.
 
@@ -287,9 +329,15 @@ See `test/examples/app_all_events/test_app.rb` for a complete example.
 
 When UI changes are intentional, regenerate all snapshots:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```bash
 UPDATE_SNAPSHOTS=1 bin/agent_rake test
 ```
+<!-- SPDX-SnippetEnd -->
 
 ## Widget Attribute Cycling
 
@@ -327,6 +375,11 @@ Use hardcoded realistic data. Examples:
 **For large datasets (≥ 10 items):**
 Use the [Faker](https://github.com/faker-ruby/faker) gem with **deterministic seeding** so data is consistent across runs:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 require "faker"
 
@@ -337,6 +390,7 @@ Faker::Config.random = Random.new(12345)
 users = Array.new(50) { Faker::Name.name }
 emails = Array.new(50) { Faker::Internet.email }
 ```
+<!-- SPDX-SnippetEnd -->
 
 In tests, set the same seed before each test to ensure snapshot consistency.
 

data/doc/contributors/documentation_style.md

@@ -1,7 +1,6 @@
 <!--
-SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-
-SPDX-License-Identifier: AGPL-3.0-or-later
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
 # Documentation Style Guide
@@ -33,13 +32,24 @@ Every public class must begin with a **Context-Problem-Solution** narrative.
 ### Example
 
 **Bad (Generic/Descriptive):**
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 # A widget for displaying list items.
 # It allows the user to select an item from an array of strings.
 # Supports scrolling and custom styling.
 ```
+<!-- SPDX-SnippetEnd -->
 
 **Good (Alexandrian/Zinsser/Plain Language):**
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 # Displays a selectable list of items.
 #
@@ -50,6 +60,7 @@ Every public class must begin with a **Context-Problem-Solution** narrative.
 #
 # Use it to build main menus, navigation sidebars, or logs.
 ```
+<!-- SPDX-SnippetEnd -->
 
 ## 3. Method and Attribute Documentation
 
@@ -74,6 +85,11 @@ Every public class must begin with a **Context-Problem-Solution** narrative.
 
 ### Example
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
   # The styling to apply to the content.
   attr_reader :style
@@ -86,6 +102,7 @@ Every public class must begin with a **Context-Problem-Solution** narrative.
     super
   end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ## 4. RDoc Specifics
 

data/doc/contributors/future_work.md

@@ -0,0 +1,169 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Future Work
+
+Ideas for post-v1.0.0 development. These do not block the initial release.
+
+---
+
+## Port Upstream Ratatui Examples
+
+Ratatui ships [example applications](https://github.com/ratatui/ratatui/tree/main/examples) demonstrating real-world patterns. Porting these to RatatuiRuby would:
+
+1. Validate API parity in realistic usage
+2. Provide learning resources for Ruby developers
+3. Surface gaps in the alignment audit
+
+**Candidates for porting:**
+
+- `demo2` — Kitchen sink showcasing all widgets
+- `async` — Background task handling
+- `user_input` — Text input patterns
+- `popup` — Modal dialogs
+
+---
+
+## Cross-Platform Distribution
+
+[CosmoRuby](https://github.com/igravious/cosmoruby) aims to build Ruby with [Cosmopolitan Libc](https://justine.lol/cosmopolitan/), producing single binaries that run on Linux, macOS, Windows, and BSD without recompilation.
+
+**Gap:** RatatuiRuby is a native extension. CosmoRuby does not yet support native extensions.
+
+**When this becomes viable:**
+
+- CosmoRuby adds native extension support
+- Demand emerges for single-binary TUI app distribution
+
+---
+
+## Terminal Graphics Protocols
+
+Terminal graphics protocols (Sixel, Kitty graphics, iTerm2 inline images) bypass the character cell model. Supporting them requires extension points that do not exist today.
+
+### What Third Parties Need
+
+| Extension Point | Purpose | Status |
+|-----------------|---------|--------|
+| `Draw::RawCmd` | Write raw escape sequences, bypassing the cell buffer | Not available |
+| Terminal capability queries | Detect if terminal supports Sixel, Kitty, etc. | Not available |
+| Frame hooks | Run code before/after buffer flush | Not available |
+
+### Why These Matter
+
+The `ratatui-image` crate provides graphics support for Rust Ratatui apps. A `ratatui_ruby-sixels` gem could wrap it, but only if RatatuiRuby exposes:
+
+1. **Raw output access** — Sixel data writes directly to stdout as escape sequences
+2. **Capability detection** — Apps need to query terminal support before sending graphics
+3. **Render coordination** — Graphics must be positioned after the cell buffer renders
+
+### Implementation Sketch
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+# Proposed API (not implemented)
+
+# 1. Raw draw command
+class Draw
+  RawCmd = Data.define(:bytes)
+  def self.raw(bytes) = RawCmd.new(bytes:)
+end
+
+# 2. Terminal queries
+RatatuiRuby.terminal_supports?(:sixel)      # => true/false
+RatatuiRuby.terminal_supports?(:kitty)      # => true/false
+RatatuiRuby.terminal_size_pixels             # => { width: 1920, height: 1080 }
+
+# 3. Custom widget using raw output
+class SixelImage
+  def render(area)
+    sixel_data = encode_image_as_sixel(@image, area)
+    [RatatuiRuby::Draw.raw(sixel_data)]
+  end
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+---
+
+## Custom Backends
+
+Currently hardcoded to Crossterm. A third party might want:
+
+- SSH backend (render to a remote terminal)
+- Web backend (render to browser canvas)
+- Recording backend (capture frames for replay)
+
+**Gap:** No backend plugin architecture.
+
+---
+
+## Custom Event Sources
+
+Currently hardcoded to Crossterm events. A third party might want:
+
+- Network events (WebSocket messages as TUI events)
+- File watcher events
+- IPC events
+
+**Gap:** No event source plugin architecture.
+
+---
+
+## Event Test Doubles
+
+The TestHelper module provides `MockFrame` and `StubRect` for testing render logic in isolation. However, testing `handle_event` currently requires `init_test_terminal` and `inject_test_event`.
+
+For pure unit tests of Kit components, stub event objects would be useful:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+# Proposed API (not implemented)
+StubKeyEvent = Data.define(:code, :modifiers) do
+  def initialize(code:, modifiers: [])
+    super
+  end
+
+  def key? = true
+  def mouse? = false
+end
+
+StubMouseEvent = Data.define(:kind, :button, :x, :y, :modifiers) do
+  def initialize(kind:, button: "left", x:, y:, modifiers: [])
+    super
+  end
+
+  def key? = false
+  def mouse? = true
+  def down? = kind == "down"
+  def up? = kind == "up"
+end
+
+# Usage
+event = StubKeyEvent.new(code: "a", modifiers: ["ctrl"])
+result = component.handle_event(event)
+assert_equal :consumed, result
+```
+<!-- SPDX-SnippetEnd -->
+
+This would let developers test component event handling without terminal dependencies.
+
+## Prioritization
+
+When prioritizing post-1.0 work, consider:
+
+1. **Port upstream examples** — Validates parity, provides learning resources
+2. **`Draw::RawCmd`** — Lowest effort, highest impact for graphics support
+3. **Terminal capability queries** — Required for any graphics work
+4. **Backend plugins** — Large undertaking, defer until clear demand
+5. **CosmoRuby** — Blocked on upstream; monitor progress

data/doc/contributors/index.md

@@ -1,5 +1,5 @@
 <!--
-  SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
   SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 # **ratatui_ruby** Contributors’ Documentation

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

@@ -4,11 +4,16 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
 # alignment_audit
+## Legacy Migrations
+
+### Outstanding
+
+- Migrate away from `schema/` folder structure as mentioned in ruby_frontend.md
+
 ## alignment_audit
 - Symbol Sets
   - line::Set, block::Set, scrollbar::Set
 - Layout
-  - Rect methods (~13)
   - Constraint batch constructors (6)
   - Layout margin, spacing (2)
 - Style
@@ -17,49 +22,17 @@ SPDX-License-Identifier: CC-BY-SA-4.0
   - Span methods (4)
   - Line methods (6)
 
-######  MISALIGNED (non-additive, breaking)
-
-
----
-
-
-
-
-
-
 ### 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.
-
 ---
 
 
 ######  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
 
@@ -144,15 +117,10 @@ These are public `&self` methods on upstream widgets that compute/query values w
 
 ######  State Navigation Methods — Missing
 
-ListState and TableState have navigation helpers that are not exposed.
+TableState has navigation helpers that are not exposed.
 
 | State Class | Missing Method | Ratatui API | Notes |
 |-------------|----------------|-------------|-------|
-| `ListState` | `select_next` | `state.select_next()` | Move selection to next item |
-| `ListState` | `select_previous` | `state.select_previous()` | Move selection to previous item |
-| `ListState` | `select_first` | `state.select_first()` | Jump to first item |
-| `ListState` | `select_last` | `state.select_last()` | Jump to last item |
-
 | `TableState` | `selected_cell` | `state.selected_cell()` | Get (row, col) tuple |
 | `TableState` | `with_selected_cell` | `state.with_selected_cell((r,c))` | Builder pattern |
 | `TableState` | `select_next_column` | `state.select_next_column()` | Navigate columns |
@@ -168,6 +136,11 @@ ListState and TableState have navigation helpers that are not exposed.
 |--------|---------|-------------|-------|
 | `Rect` | `as_position` | `rect.as_position()` → `Position` | Convert to Position |
 | `Rect` | `as_size` | `rect.as_size()` → `Size` | Convert to Size |
+| `Rect` | `outer` | `rect.outer(margin)` → `Rect` | Expand by margin (inverse of `inner`) |
+| `Rect` | `resize` | `rect.resize(size)` → `Rect` | Change dimensions, preserve position |
+| `Rect` | `centered_horizontally` | `rect.centered_horizontally(constraint)` → `Rect` | Center horizontally via Layout |
+| `Rect` | `centered_vertically` | `rect.centered_vertically(constraint)` → `Rect` | Center vertically via Layout |
+| `Rect` | `centered` | `rect.centered(h, v)` → `Rect` | Center both axes |
 | `Constraint` | `apply` | `constraint.apply(length)` → `u16` | Compute constrained size |
 | `Layout` | `split_with_spacers` | `layout.split_with_spacers(area)` | Returns segments AND spacers |
 
@@ -229,8 +202,6 @@ These are gaps that can be filled in future minor releases without breaking exis
 
 | 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 |
@@ -529,10 +500,8 @@ All current parameter names are well-chosen. No changes recommended.
 
 ######  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`
+1. **Add `item` alias** for `list_item`
+2. **Add terse shape aliases**: `circle`, `point`, `rectangle`, `map`, `label`
 
 ######  Medium Priority (Pattern Completion)
 
@@ -549,10 +518,8 @@ All current parameter names are well-chosen. No changes recommended.
 
 ######  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`)
@@ -569,10 +536,8 @@ If all recommendations in this audit are adopted, **none constitute breaking cha
 
 | 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 |
@@ -656,62 +621,6 @@ 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:
@@ -746,41 +655,6 @@ end
 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:
@@ -817,18 +691,6 @@ gauge = Gauge.new(percent: 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
@@ -1011,26 +873,4 @@ end
 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
-
-The `widget_tabs` 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:** Show a multi-step modal flow (e.g., Confirm -> Success) rather than just a static overlay.
--   **widget_list:** Show a master-detail view where selecting a list item updates a detail pane.
--   **widget_input:** (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?"
+```