ratatui_ruby 0.7.4 → 0.9.0

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.
 

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