ratatui_ruby 0.7.4 → 0.9.0

data/doc/concepts/custom_widgets.md

@@ -0,0 +1,247 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Custom Widgets
+
+Build anything. Escape the widget library.
+
+## What Terminals Offer
+
+Terminals do not have pixels. They have character cells arranged in a grid. Each cell holds one character with foreground color, background color, and text modifiers (bold, italic, underline).
+
+This constraint shapes what you can draw:
+
+- **Characters**: Any Unicode character fits in a cell
+- **Box-drawing**: Lines, corners, and boxes (`│`, `┌`, `─`, `└`)
+- **Block elements**: Partial fills (`▀`, `▄`, `█`, `░`, `▒`, `▓`)
+- **Braille patterns**: 2×4 "pixel" grids per cell for pseudo-graphics
+- **Nerd Fonts**: Icons and glyphs if the user's font supports them
+
+The built-in Canvas widget uses Braille patterns for line graphs and shapes. Custom widgets give you direct control over every cell.
+
+## The Problem
+
+Standard widgets handle common needs. Paragraphs display text. Lists show selections. Tables organize data.
+
+But terminals can do more. You want a game board, a network graph, or a custom visualization. The built-in widgets cannot help you here.
+
+## The Solution
+
+Any Ruby object that implements `render(area)` works as a widget. You are not limited to what the library ships. Define a class. Implement one method. Pass it to `frame.render_widget`.
+
+The Engine calls your `render` method with the area where your widget should draw. You return an array of Draw commands. The Engine executes them.
+
+## The Contract
+
+Your custom widget implements [the `_CustomWidget` interface](../../sig/ratatui_ruby/frame.rbs). The `area` parameter is a `Rect` with `x`, `y`, `width`, and `height`. It tells you where to draw and how much space you have.
+
+## Draw Commands
+
+Two commands describe what to draw:
+
+| Command | Purpose |
+|---------|---------|
+| `Draw.string(x, y, text, style)` | Draw a styled string at absolute coordinates |
+| `Draw.cell(x, y, cell)` | Draw a single cell (character + style) |
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+class HelloWidget
+  def render(area)
+    [
+      RatatuiRuby::Draw.string(
+        area.x,
+        area.y,
+        "Hello, World!",
+        RatatuiRuby::Style::Style.new(fg: :green, modifiers: [:bold])
+      )
+    ]
+  end
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+## Coordinate Offsets
+
+The `area.x` and `area.y` values are not always zero. When your widget renders inside a `Block` with borders, or within a nested layout, the area's origin shifts.
+
+Always add `area.x` and `area.y` to your drawing coordinates. This pattern ensures your widget works regardless of where it appears on screen.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+class DiagonalWidget
+  def render(area)
+    (0...area.height).filter_map do |i|
+      next if i >= area.width  # Stay within bounds
+
+      RatatuiRuby::Draw.string(
+        area.x + i,  # Offset from area origin
+        area.y + i,
+        "\\",
+        RatatuiRuby::Style::Style.new(fg: :red)
+      )
+    end
+  end
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+## Composability
+
+Custom widgets compose with standard widgets. Wrap them in Blocks. Place them in layouts. Mix them with Paragraphs and Lists.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+RatatuiRuby.run do |tui|
+  tui.draw do |frame|
+    areas = tui.layout_split(
+      frame.area,
+      direction: :horizontal,
+      constraints: [tui.constraint_percentage(50), tui.constraint_percentage(50)]
+    )
+
+    # Standard widget on the left
+    frame.render_widget(tui.paragraph(text: "Standard"), areas[0])
+
+    # Custom widget on the right
+    frame.render_widget(DiagonalWidget.new, areas[1])
+  end
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+To render inside a bordered Block, calculate the inner area first:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+tui.draw do |frame|
+  # Render the block frame
+  block = tui.block(title: "Custom", borders: [:all])
+  frame.render_widget(block, frame.area)
+
+  # Calculate inner area (1-cell border on all sides)
+  inner = tui.rect(
+    x: frame.area.x + 1,
+    y: frame.area.y + 1,
+    width: [frame.area.width - 2, 0].max,
+    height: [frame.area.height - 2, 0].max
+  )
+
+  # Render custom widget inside
+  frame.render_widget(MyWidget.new, inner)
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+## Using Custom Widgets in Layouts
+
+Custom widgets work as children in Layout trees. The layout system passes the calculated area to your `render` method.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+layout = RatatuiRuby::Layout::Layout.new(
+  direction: :vertical,
+  constraints: [
+    RatatuiRuby::Layout::Constraint.length(1),
+    RatatuiRuby::Layout::Constraint.fill(1),
+  ],
+  children: [
+    RatatuiRuby::Widgets::Paragraph.new(text: "Header"),
+    MyCustomWidget.new,  # Your widget here
+  ]
+)
+
+RatatuiRuby.draw(layout)
+```
+<!-- SPDX-SnippetEnd -->
+
+## Testing Custom Widgets
+
+Custom widgets return arrays. Test them by calling `render` directly and asserting on the result.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+def test_hello_widget_output
+  area = RatatuiRuby::Rect.new(x: 0, y: 0, width: 20, height: 5)
+  widget = HelloWidget.new
+  commands = widget.render(area)
+
+  assert_equal 1, commands.length
+  assert_equal 0, commands[0].x
+  assert_equal 0, commands[0].y
+  assert_equal "Hello, World!", commands[0].string
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+For visual testing, use the test helper to render to a buffer and assert on content:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+class TestMyWidget < Minitest::Test
+  include RatatuiRuby::TestHelper
+
+  def test_renders_in_terminal
+    with_test_terminal(10, 5) do
+      RatatuiRuby.draw(MyWidget.new)
+      assert_equal "Expected  ", buffer_content[0]
+    end
+  end
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+## Typing Your Widgets (RBS)
+
+Type your custom widgets by implementing the `_CustomWidget` interface:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```rbs
+# my_widget.rbs
+class MyWidget
+  def render: (RatatuiRuby::Rect area) -> Array[RatatuiRuby::Draw::StringCmd | RatatuiRuby::Draw::CellCmd]
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+The interface uses structural typing. Any class with a matching `render` signature satisfies it.
+
+## Related Resources
+
+- [Custom Render Example](../examples/widget_render/README.md) — Full working example
+- [Cell Example](../examples/widget_cell/README.md) — Low-level cell drawing
+- [Application Testing](./application_testing.md) — Test helper reference

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 -->