ratatui_ruby 0.8.0 → 0.9.1

data/README.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
@@ -21,7 +21,7 @@ Mailing List: Announcements](https://img.shields.io/badge/mailing_list-announcem
 **ratatui_ruby** is a community wrapper that is not affiliated with [the Ratatui team](https://github.com/orgs/ratatui/people).
 
 > [!WARNING]
-> **ratatui_ruby** is currently in **BETA**. The API may change between minor versions.
+> **ratatui_ruby** is currently in **ALPHA**. The API may change between minor versions.
 
 **[Why RatatuiRuby?](./doc/getting_started/why.md)** — Native Rust performance, zero runtime overhead, and Ruby's expressiveness. [See how we compare](./doc/getting_started/why.md) to CharmRuby, raw Rust, and Go.
 
@@ -44,27 +44,50 @@ including Ruby 4.
 
 Add this line to your application's Gemfile:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 gem "ratatui_ruby"
 ```
+<!-- SPDX-SnippetEnd -->
 
 And then execute:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```bash
 bundle install
 ```
+<!-- SPDX-SnippetEnd -->
 
 Or install it yourself with:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```bash
 gem install ratatui_ruby
 ```
+<!-- SPDX-SnippetEnd -->
 
 
 ## Usage
 
 **ratatui_ruby** uses an immediate-mode API. You describe your UI using Ruby objects and call `draw` in a loop.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 <!-- SYNC:START:examples/verify_readme_usage/app.rb:main -->
 ```ruby
 RatatuiRuby.run do |tui|
@@ -77,7 +100,7 @@ RatatuiRuby.run do |tui|
           block: tui.block(
             title: "My Ruby TUI App",
             borders: [:all],
-            border_color: "cyan"
+            border_style: { fg: "cyan" }
           )
         ),
         frame.area
@@ -93,6 +116,7 @@ RatatuiRuby.run do |tui|
 end
 ```
 <!-- SYNC:END -->
+<!-- SPDX-SnippetEnd -->
 
 ![Hello Ratatui](./doc/images/verify_readme_usage.png)
 
@@ -138,8 +162,12 @@ Want to help develop **ratatui_ruby**? Check out the [contribution guide on the
 
 ## Copyright & License
 
-**ratatui_ruby** is copyright 2025, Kerrick Long. **ratatui_ruby** is licensed under the GNU Affero General Public License v3.0 or later; see [LICENSES/AGPL-3.0-or-later.txt](./LICENSES/AGPL-3.0-or-later) for the full text.
+**ratatui_ruby** is copyright 2025, Kerrick Long.
+
+The library is [LGPL-3.0-or-later](./LICENSES/LGPL-3.0-or-later.txt): you can use it in proprietary applications, but you must share changes you make to **ratatui_ruby** itself. Documentation snippets and widget examples are [MIT-0](./LICENSES/MIT-0.txt): copy and use them without attribution.
+
+Documentation is [CC-BY-SA-4.0](./LICENSES/CC-BY-SA-4.0.txt). Build tooling and full app examples are [AGPL-3.0-or-later](./LICENSES/AGPL-3.0-or-later.txt). See each file's SPDX comment for specifics.
 
-Some parts of this program are copied from other sources under appropriate reuse licenses, and the copyright belongs to their respective owners. See the [REUSE Specification – Version 3.3](https://reuse.software/spec-3.3/) for information about how we comply with attribution and licensing requirements.
+Some parts of this program are copied from other sources under appropriate reuse licenses, and the copyright belongs to their respective owners. See the [REUSE Specification – Version 3.3](https://reuse.software/spec-3.3/) for details.
 
 This program was created with significant assistance from multiple LLMs. The process was human-controlled through creative prompts, with human contributions to each commit. See commit footers for model attribution. [declare-ai.org](https://declare-ai.org/1.0.0/creative.html)

data/Rakefile

@@ -8,4 +8,4 @@ require "bundler/gem_tasks"
 # Import all tasks from the tasks/ directory
 Dir.glob("tasks/*.rake").each { |r| import r }
 
-task default: %w[lint:fix sourcehut test lint]
+task default: %w[lint:fix sourcehut test lint license:new]

data/doc/concepts/application_architecture.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
 -->
 
 # Application Architecture
@@ -24,6 +23,11 @@ Terminals have state. They remember cursor positions, input modes, and screen bu
 
 This method acts as a safety net. It initializes the terminal, yields control to your block, and restores the terminal afterwards—even if your code raises an exception.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 RatatuiRuby.run do |tui|
   loop do
@@ -35,11 +39,17 @@ RatatuiRuby.run do |tui|
 end
 # Terminal is restored here
 ```
+<!-- SPDX-SnippetEnd -->
 
 #### Manual Management
 
 Need granular control? You can initialize and restore the terminal yourself. Use `ensure` blocks to guarantee cleanup.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 RatatuiRuby.init_terminal
 begin
@@ -51,6 +61,7 @@ ensure
   # Terminal is restored here
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 #### Signal Handling
 
@@ -69,6 +80,11 @@ External processes send signals. Your TUI must handle them gracefully.
 > [!IMPORTANT]
 > **Ctrl+C in Raw Mode:** When your app is in raw mode, pressing Ctrl+C does *not* send SIGINT. It's captured as a `:ctrl_c` key event. Handle this in your event loop—don't use `trap("INT")`.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 RatatuiRuby.run do |tui|
   loop do
@@ -78,6 +94,7 @@ RatatuiRuby.run do |tui|
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 **Recovery:** If a TUI app leaves your terminal broken, run `reset` in the shell to restore normal behavior.
 
@@ -97,6 +114,11 @@ Most widgets are stateless configuration. You create them, render them, and they
 
 **Use Case:** When you need to read back the scroll offset (e.g., for mouse hit testing) or persist selection without managing indexes manually.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 # Initialize state once
 @list_state = RatatuiRuby::ListState.new
@@ -116,6 +138,7 @@ RatatuiRuby.run do |tui|
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ### API Convenience
 
@@ -125,6 +148,11 @@ Writing UI trees involves nesting many widgets.
 
 **The Solution:** The TUI API (`tui`) provides shorthand factories for every widget. It yields a TUI object to your block.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 RatatuiRuby.run do |tui|
   loop do
@@ -167,11 +195,17 @@ RatatuiRuby.run do |tui|
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 #### Raw API
 
 Building your own abstractions? You might prefer explicit class instantiation. The raw constants are always available.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 RatatuiRuby.run do
   loop do
@@ -212,6 +246,7 @@ RatatuiRuby.run do
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ## Thread and Ractor Safety
 
@@ -236,6 +271,11 @@ These have side effects and are intentionally not shareable:
 | `TUI` | Cache in `@tui` during run loop. Don't include in Models. |
 | `Frame` | Pass to helpers during draw block. Invalid after block returns. |
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 # Good: Cache session in instance variable
 RatatuiRuby.run do |tui|
@@ -246,6 +286,7 @@ end
 # Bad: Include in immutable Model (won't work with Ractors)
 Model = Data.define(:tui, :count)  # Don't do this
 ```
+<!-- SPDX-SnippetEnd -->
 
 
 ## Reference Architectures

data/doc/concepts/application_testing.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
 -->
 # Application Testing Guide
@@ -18,19 +18,31 @@ Use it to write fast, deterministic tests for your TUI applications.
 
 First, require the test helper in your test file or `test_helper.rb`:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 require "ratatui_ruby/test_helper"
 require "minitest/autorun" # or your preferred test framework
 ```
+<!-- SPDX-SnippetEnd -->
 
 Then, include the module in your test class:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 class MyApplicationTest < Minitest::Test
   include RatatuiRuby::TestHelper
   # ...
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ## Writing a View Test
 
@@ -40,6 +52,11 @@ To test a view or widget, wrap your assertions in `with_test_terminal`. This set
 2.  **Render your code:** Instantiate your widget and draw it to a frame.
 3.  **Assert output:** Check the `buffer_content` against your expectations.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 def test_rendering
   # Uses default 80x24 terminal
@@ -57,6 +74,7 @@ def test_rendering
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 For the full API list, including `buffer_content` and `cursor_position`, see [RatatuiRuby::TestHelper::Terminal](../lib/ratatui_ruby/test_helper/terminal.rb).
 
@@ -66,6 +84,11 @@ You often need to check colors and modifiers (bold, italic) to ensure your highl
 
 Use `assert_fg_color`, `assert_bg_color`, and modifier helpers like `assert_bold`.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 # Assert specific cell style
 assert_fg_color(:red, 0, 0)
@@ -74,6 +97,7 @@ assert_bold(0, 0)
 # Or check a whole area
 assert_area_style({ x: 0, y: 0, w: 10, h: 1 }, bg: :blue)
 ```
+<!-- SPDX-SnippetEnd -->
 
 See [RatatuiRuby::TestHelper::StyleAssertions](../lib/ratatui_ruby/test_helper/style_assertions.rb) for the comprehensive list of style helpers.
 
@@ -86,6 +110,11 @@ Use `inject_event` to push mock events into the queue. This ensures safe, determ
 > [!IMPORTANT]
 > Call `inject_event` inside a `with_test_terminal` block to avoid race conditions.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 with_test_terminal do
   # Simulate 'q' key press
@@ -96,6 +125,7 @@ with_test_terminal do
   assert_equal "q", event.code
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 See [RatatuiRuby::TestHelper::EventInjection](../lib/ratatui_ruby/test_helper/event_injection.rb) for helper methods like `inject_keys` and `inject_click`.
 
@@ -105,12 +135,18 @@ Snapshots let you verify complex layouts without manually asserting every line.
 
 Use `assert_snapshots` to compare the current screen against stored reference files.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 with_test_terminal do
   MyApp.new.run
   assert_snapshots("dashboard_view")
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 This generates both `.txt` (plain text) and `.ansi` (styled) snapshot files. The `.ansi` files contain ANSI escape codes—`cat` them in a terminal to see exactly what the screen looked like. For a visual tour of your test suite, try `cat **/*.ansi` in any shell that supports globbing.
 
@@ -130,6 +166,11 @@ Sometimes you want to test a single view component without spinning up the full
 
 Use `MockFrame` and `StubRect` to test render logic in isolation.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 def test_logs_view
   frame = RatatuiRuby::TestHelper::TestDoubles::MockFrame.new
@@ -143,6 +184,7 @@ def test_logs_view
   assert_equal "Logs", rendered[:widget].block.title
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 See [RatatuiRuby::TestHelper::TestDoubles](../lib/ratatui_ruby/test_helper/test_doubles.rb).
 

data/doc/concepts/async.md

@@ -1,6 +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
 -->
 
 # Async Operations in TUI Applications
@@ -21,12 +21,18 @@ This guide explains async patterns that work with raw terminal mode.
 
 ### What Breaks
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 # These fail inside a Thread during raw mode:
 `git ls-remote --tags origin`           # Returns empty or hangs
 IO.popen(["git", "ls-remote", ...])     # Same
 Open3.capture2("git", "ls-remote", ...) # Same
 ```
+<!-- SPDX-SnippetEnd -->
 
 The commands succeed synchronously. They fail asynchronously. The difference: thread context inherits the parent's raw terminal state.
 
@@ -46,11 +52,17 @@ Ruby's GIL releases during I/O. But:
 
 Run slow operations before entering the TUI:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 def initialize
   @data = fetch_data  # Runs before RatatuiRuby.run
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 **Trade-off**: Delays startup.
 
@@ -58,6 +70,11 @@ end
 
 Spawn a separate process before entering raw mode. Write results to a temp file. Poll for completion:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 class AsyncChecker
   CACHE_FILE = File.join(Dir.tmpdir, "my_check_result.txt")
@@ -81,6 +98,7 @@ class AsyncChecker
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 **Key points**:
 
@@ -93,9 +111,15 @@ end
 
 Ruby threads work for pure computation:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 Thread.new { @result = expensive_calculation }
 ```
+<!-- SPDX-SnippetEnd -->
 
 Avoid threads for shell commands.
 
@@ -122,6 +146,11 @@ For TUI async, `Process.spawn` solves the problem cleanly.
 
 Check if a tag exists on the remote:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 class GitRepo
   CACHE_FILE = File.join(Dir.tmpdir, "git_tag_pushed.txt")
@@ -156,5 +185,6 @@ class GitRepo
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 The TUI starts instantly. The tag check runs in the background. The checklist updates when the result arrives.