ratatui_ruby 0.8.0 → 0.9.0

data/doc/concepts/event_handling.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
 -->
 
 # Event Handling
@@ -30,6 +29,11 @@ For simple key events, `RatatuiRuby::Event::Key` objects can be compared directl
 
 For a complete list of supported keys, modifiers, and event types, please refer to the [API Documentation for RatatuiRuby::Event](file:///Users/kerrick/Developer/ratatui_ruby/lib/ratatui_ruby/event.rb).
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 event = RatatuiRuby.poll_event
 
@@ -43,6 +47,7 @@ if event == :enter
   submit_form
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ## 3. Predicate Methods (Intermediate)
 
@@ -54,6 +59,11 @@ Safe to call on *any* event object. They return `true` only for the matching eve
 
 Available: `key?`, `mouse?`, `resize?`, `paste?`, `focus_gained?`, `focus_lost?`.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 event = RatatuiRuby.poll_event
 
@@ -65,6 +75,7 @@ elsif event.resize?
   resize_layout(event.width, event.height)
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ### Helper Predicates
 
@@ -74,26 +85,43 @@ Specific to certain event classes to simplify checks.
 *   `ctrl?`, `alt?`, `shift?`: Check if modifier is held.
 *   `text?`: Returns `true` if the event is a printable character (length == 1).
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 if event.key? && event.ctrl? && event.code == "s"
   save_file
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 #### `RatatuiRuby::Event::Mouse`
 *   `down?`, `up?`, `drag?`: Check mouse action.
 *   `scroll_up?`, `scroll_down?`: Check scroll direction.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 if event.mouse? && event.scroll_up?
   scroll_view(-1)
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ## 4. Pattern Matching (Powerful)
 
 For complex applications, Ruby 3.0+ Pattern Matching with the `type:` discriminator is the most idiomatic and concise approach.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 loop do
   case RatatuiRuby.poll_event
@@ -119,6 +147,7 @@ loop do
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ## Summary of Event Classes
 

data/doc/concepts/interactive_design.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
 -->
 
 # Interactive TUI Design Patterns
@@ -19,6 +19,11 @@ Canonical patterns for building responsive, interactive terminal user interfaces
 
 Structure your event loop into three clear phases:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 def run
   RatatuiRuby.run do |tui|
@@ -33,11 +38,17 @@ def run
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 **Phase 1: Layout Calculation**
 
 Call this inside your `draw` block. It uses the current terminal area provided by the frame:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 def calculate_layout(area)
   # Main area vs sidebar (70% / 30%)
@@ -61,22 +72,34 @@ def calculate_layout(area)
   )
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 **Phase 2: Rendering**
 
 Reuse the cached rects. Build and draw:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 def render(frame)
   frame.render_widget(build_widget(@left_rect), @left_rect)
   frame.render_widget(build_widget(@right_rect), @right_rect)
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 **Phase 3: Event Handling**
 
 Reuse the cached rects. Test clicks:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 def handle_input
   event = RatatuiRuby.poll_event
@@ -93,6 +116,7 @@ def handle_input
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ### Why This Matters
 
@@ -105,6 +129,11 @@ end
 
 `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.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 # Preferred (TUI API)
 left, right = tui.layout_split(area, constraints: [...])
@@ -112,5 +141,6 @@ left, right = tui.layout_split(area, constraints: [...])
 # Manual (Core API)
 left, right = RatatuiRuby::Layout.split(area, constraints: [...])
 ```
+<!-- SPDX-SnippetEnd -->
 
 Use it to establish the single source of truth inside your `draw` block. Store the results in instance variables and reuse them in both `render` and `handle_input`.

data/doc/contributors/auditing/parity.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
 -->
 
@@ -32,6 +32,11 @@ Every audit begins with a question:
 
 Every RatatuiRuby feature has three layers. Gaps can occur at any layer:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```
 ┌─────────────────────────────┐
 │  Ruby API (lib/**/*.rb)    │  ← What users see
@@ -41,6 +46,7 @@ Every RatatuiRuby feature has three layers. Gaps can occur at any layer:
 │  Upstream Ratatui          │  ← Source of truth
 └─────────────────────────────┘
 ```
+<!-- SPDX-SnippetEnd -->
 
 ### Layer 1: Ruby API Gaps
 Ruby doesn't expose a parameter that upstream supports.

data/doc/contributors/design/ruby_frontend.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
 -->
 
@@ -39,11 +39,17 @@ Located in `lib/ratatui_ruby/widgets/`, `lib/ratatui_ruby/layout/`, etc.
 
 These are the actual `Data.define` classes that the Rust backend expects. They have deep, explicit namespaces that match Ratatui:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 RatatuiRuby::Widgets::Paragraph.new(text: "Hello")
 RatatuiRuby::Layout::Constraint.length(20)
 RatatuiRuby::Style::Style.new(fg: :red)
 ```
+<!-- SPDX-SnippetEnd -->
 
 **Layer 2: TUI Facade (The DSL)**
 
@@ -51,6 +57,11 @@ Located in `lib/ratatui_ruby/tui.rb` and `lib/ratatui_ruby/tui/*.rb` mixins.
 
 The `TUI` class provides shorthand factory methods that hide namespace verbosity:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 RatatuiRuby.run do |tui|
   tui.paragraph(text: "Hello")
@@ -58,6 +69,7 @@ RatatuiRuby.run do |tui|
   tui.style(fg: :red)
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 **Why This Matters:**
 
@@ -69,6 +81,11 @@ The TUI facade uses explicit factory method definitions, not runtime metaprogram
 
 **What We Do:**
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 # lib/ratatui_ruby/tui/widget_factories.rb
 module RatatuiRuby
@@ -85,15 +102,22 @@ module RatatuiRuby
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 **What We Don't Do:**
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 # NO: Dynamic method generation
 RatatuiRuby.constants.each do |const|
   define_method(const.underscore) { |**kw| RatatuiRuby.const_get(const).new(**kw) }
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 **Benefits of Explicit Definitions:**
 
@@ -109,6 +133,11 @@ All UI components are pure, immutable `Data.define` value objects. They describe
 
 **Widgets Are Inputs:**
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 # This is just data. It has no behavior, no side effects.
 paragraph = RatatuiRuby::Widgets::Paragraph.new(
@@ -119,11 +148,17 @@ paragraph = RatatuiRuby::Widgets::Paragraph.new(
 # Pass to renderer as input
 frame.render_widget(paragraph, area)
 ```
+<!-- SPDX-SnippetEnd -->
 
 **Immediate Mode Loop:**
 
 Every frame, the application constructs a fresh view tree and passes it to `draw`. No widget state persists between frames. This is Ratatui's core paradigm.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 loop do
   tui.draw do |frame|
@@ -133,6 +168,7 @@ loop do
   break if tui.poll_event.key? && tui.poll_event.code == "q"
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ### 5. Separation of Configuration and Status
 
@@ -142,14 +178,25 @@ Widgets (Configuration) and State (Status) are strictly separated.
 
 Widgets define *what* to render. They are created, rendered, and discarded.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 list = tui.list(items: ["A", "B", "C", "D", "E"])
 ```
+<!-- SPDX-SnippetEnd -->
 
 **Status (Output):**
 
 State objects track *runtime metrics* computed by the Rust backend: scroll offsets, selection positions, etc. They persist across frames.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 # Created once
 @list_state = RatatuiRuby::ListState.new
@@ -160,6 +207,7 @@ frame.render_stateful_widget(list, area, @list_state)
 # Read back computed values
 puts "Scroll offset: #{@list_state.offset}"
 ```
+<!-- SPDX-SnippetEnd -->
 
 **Precedence Rule:**
 
@@ -188,6 +236,11 @@ This separation ensures rendering performance remains in Rust while Ruby handles
 
 ## Directory Structure
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```
 lib/ratatui_ruby/
 ├── tui.rb                    # TUI class, includes all mixins
@@ -221,6 +274,7 @@ lib/ratatui_ruby/
 │   └── cell.rb              # For get_cell_at inspection
 └── schema/                   # Legacy location (being migrated)
 ```
+<!-- SPDX-SnippetEnd -->
 
 ---
 
@@ -230,6 +284,11 @@ lib/ratatui_ruby/
 
 Define the Data class in the appropriate namespace directory:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 # lib/ratatui_ruby/widgets/my_widget.rb
 module RatatuiRuby
@@ -247,9 +306,15 @@ module RatatuiRuby
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ### Step 2: Add the RBS Type
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```rbs
 # sig/ratatui_ruby/widgets/my_widget.rbs
 module RatatuiRuby
@@ -264,15 +329,22 @@ module RatatuiRuby
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ### Step 3: Add the TUI Factory Method
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 # lib/ratatui_ruby/tui/widget_factories.rb
 def my_widget(**kwargs)
   Widgets::MyWidget.new(**kwargs)
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ### Step 4: Implement Rust Rendering
 
@@ -282,9 +354,15 @@ See `rust_backend.md` for the Rust implementation steps.
 
 Add to `lib/ratatui_ruby.rb`:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 require_relative "ratatui_ruby/widgets/my_widget"
 ```
+<!-- SPDX-SnippetEnd -->
 
 ---
 
@@ -324,6 +402,11 @@ These have side effects and are intentionally not Ractor-safe:
 - `TUI` — Has terminal I/O methods
 - `Frame` — Valid only during the `draw` block; invalid after
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 # OK: Cache TUI during run loop
 RatatuiRuby.run do |tui|
@@ -334,3 +417,4 @@ end
 # NOT OK: Include in immutable Model
 Model = Data.define(:tui, :count)  # Don't do this
 ```
+<!-- SPDX-SnippetEnd -->

data/doc/contributors/design/rust_backend.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
 -->
 
@@ -41,6 +41,11 @@ The Rust backend is a pure rendering engine. It receives Ruby objects representi
 
 The backend implements one generic rendering function that accepts any Ruby `Value` and dispatches based on class name. There is no compile-time knowledge of Ruby types—everything is runtime reflection.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```rust
 // rendering.rs
 pub fn render_widget(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
@@ -58,20 +63,32 @@ pub fn render_widget(frame: &mut Frame, area: Rect, node: Value) -> Result<(), E
     }
 }
 ```
+<!-- SPDX-SnippetEnd -->
 
 ### 3. No Custom Rust Structs for UI
 
 Do not define Rust structs that mirror Ruby UI components. This would create synchronization problems when Ruby classes change.
 
 **What We Do:**
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```rust
 // Extract directly from Ruby object
 let text: String = node.funcall("text", ())?;
 let style_val: Value = node.funcall("style", ())?;
 let style = parse_style(style_val)?;
 ```
+<!-- SPDX-SnippetEnd -->
 
 **What We Don't Do:**
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```rust
 // NO: Rust struct mirroring Ruby
 struct Paragraph {
@@ -80,6 +97,7 @@ struct Paragraph {
     block: Option<Block>,
 }
 ```
+<!-- SPDX-SnippetEnd -->
 
 ### 4. Immediate Mode Rendering
 
@@ -91,6 +109,11 @@ This mirrors Ratatui's own immediate mode paradigm. The Rust backend is stateles
 
 Ruby's GC can move or collect objects at any time. All data extracted from Ruby must be owned (copied) before use, never borrowed.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```rust
 // SAFE: Convert to owned String immediately
 let text: String = node.funcall::<_, String>("text", ())?.into_owned();
@@ -100,11 +123,17 @@ let text_ref: &str = node.funcall("text", ())?;  // DON'T
 do_something_that_might_gc();
 use(text_ref);  // CRASH: text_ref may be invalid
 ```
+<!-- SPDX-SnippetEnd -->
 
 ---
 
 ## Directory Structure
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```
 ext/ratatui_ruby/src/
 ├── lib.rs              # Entry point, Ruby module registration
@@ -123,6 +152,7 @@ ext/ratatui_ruby/src/
     ├── canvas.rs
     └── ...
 ```
+<!-- SPDX-SnippetEnd -->
 
 ---
 
@@ -159,6 +189,11 @@ Pure functions for extracting style information from Ruby values. Handles `parse
 
 The routing layer that maps Ruby class names to widget renderers:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```rust
 pub fn render_widget(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
     let class_name: String = node.class().name()?.into_owned();
@@ -191,6 +226,7 @@ pub fn render_widget(frame: &mut Frame, area: Rect, node: Value) -> Result<(), E
     }
 }
 ```
+<!-- SPDX-SnippetEnd -->
 
 **Namespace Pattern:** All built-in widgets use the `RatatuiRuby::Widgets::*` namespace. The dispatcher matches on full class names, not prefixes.
 
@@ -198,6 +234,11 @@ pub fn render_widget(frame: &mut Frame, area: Rect, node: Value) -> Result<(), E
 
 Each widget has its own module with a standard interface:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```rust
 // widgets/paragraph.rs
 pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
@@ -222,6 +263,7 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
     Ok(())
 }
 ```
+<!-- SPDX-SnippetEnd -->
 
 ---
 
@@ -229,6 +271,11 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
 
 ### Step 1: Create the Widget Module
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```rust
 // src/widgets/my_widget.rs
 
@@ -249,18 +296,31 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
     Ok(())
 }
 ```
+<!-- SPDX-SnippetEnd -->
 
 ### Step 2: Register in `widgets/mod.rs`
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```rust
 pub mod my_widget;
 ```
+<!-- SPDX-SnippetEnd -->
 
 ### Step 3: Add Dispatch Arm in `rendering.rs`
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```rust
 "RatatuiRuby::Widgets::MyWidget" => widgets::my_widget::render(frame, area, node),
 ```
+<!-- SPDX-SnippetEnd -->
 
 ### Step 4: Test
 
@@ -274,6 +334,11 @@ Some widgets (List, Table, Scrollbar) support stateful rendering where a mutable
 
 ### The Pattern
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```rust
 pub fn render_stateful_widget(
     frame: &mut Frame,
@@ -299,6 +364,7 @@ pub fn render_stateful_widget(
     Ok(())
 }
 ```
+<!-- SPDX-SnippetEnd -->
 
 **State Precedence:** When using stateful rendering, the State object's values take precedence over Widget properties. This is documented in Ruby.