ratatui_ruby 0.8.0 → 0.9.1

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

@@ -4,12 +4,17 @@ 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)
+  - ~~Constraint batch constructors (6)~~ ✅ DONE
   - Layout margin, spacing (2)
 - Style
   - sub_modifier, underline_color (2)
@@ -17,60 +22,22 @@ 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
+######  `Layout::Constraint` — Batch Constructors ✅ DONE
 
-| Missing Method | Signature |
-|----------------|-----------|
-| `from_lengths` | `Constraint.from_lengths([10, 20, 30])` → `[Constraint]` |
-| `from_percentages` | `Constraint.from_percentages([25, 50, 25])` → `[Constraint]` |
-| `from_mins` | `Constraint.from_mins([5, 10, 15])` → `[Constraint]` |
-| `from_maxes` | `Constraint.from_maxes([20, 30, 40])` → `[Constraint]` |
-| `from_fills` | `Constraint.from_fills([1, 2, 1])` → `[Constraint]` |
-| `from_ratios` | `Constraint.from_ratios([[1,4], [2,4], [1,4]])` → `[Constraint]` |
+All 6 batch constructors implemented in v0.8.0:
+- `from_lengths`, `from_percentages`, `from_mins`, `from_maxes`, `from_fills`, `from_ratios`
 
 ---
 
@@ -144,15 +111,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 +130,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 +196,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 +494,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 +512,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 +530,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 +615,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 +649,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 +685,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 +867,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?"
+```

data/doc/getting_started/quickstart.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
 -->
 # Quickstart
@@ -17,6 +17,11 @@ See [Installation in the README](../README.md#installation) for setup instructio
 
 Here is a "Hello World" application that demonstrates the core lifecycle of a **ratatui_ruby** app.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 <!-- SYNC:START:examples/verify_quickstart_lifecycle/app.rb:main -->
 ```ruby
 # 1. Initialize the terminal
@@ -34,7 +39,7 @@ begin
         title: "My Ruby TUI App",
         title_alignment: :center,
         borders: [:all],
-        border_color: "cyan",
+        border_style: { fg: "cyan" },
         style: { fg: "white" }
       )
     )
@@ -64,6 +69,7 @@ ensure
 end
 ```
 <!-- SYNC:END -->
+<!-- SPDX-SnippetEnd -->
 
 [![quickstart_lifecycle](../images/verify_quickstart_lifecycle.png)](../../examples/verify_quickstart_lifecycle/README.md)
 
@@ -80,6 +86,11 @@ end
 
 You can simplify your code by using `RatatuiRuby.run`. This method handles the terminal lifecycle for you, yielding a `TUI` object with factory methods for widgets.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 <!-- SYNC:START:examples/verify_quickstart_dsl/app.rb:main -->
 ```ruby
 # 1. Initialize the terminal, start the run loop, and ensure the terminal is restored.
@@ -93,7 +104,7 @@ RatatuiRuby.run do |tui|
         title: "My Ruby TUI App",
         title_alignment: :center,
         borders: [:all],
-        border_color: "cyan",
+        border_style: { fg: "cyan" },
         style: { fg: "white" }
       )
     )
@@ -114,6 +125,7 @@ RatatuiRuby.run do |tui|
 end
 ```
 <!-- SYNC:END -->
+<!-- SPDX-SnippetEnd -->
 
 #### How it works
 
@@ -128,6 +140,11 @@ For a deeper dive into the available application architectures (Manual vs Manage
 
 Real-world applications often need to split the screen into multiple areas. `RatatuiRuby::Layout` lets you do this easily.
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 <!-- SYNC:START:examples/verify_quickstart_layout/app.rb:main -->
 ```ruby
 loop do
@@ -147,7 +164,7 @@ loop do
       tui.paragraph(
         text: "Hello, Ratatui!",
         alignment: :center,
-        block: tui.block(title: "Content", borders: [:all], border_color: "cyan")
+        block: tui.block(title: "Content", borders: [:all], border_style: { fg: "cyan" })
       ),
       top
     )
@@ -184,6 +201,7 @@ loop do
 end
 ```
 <!-- SYNC:END -->
+<!-- SPDX-SnippetEnd -->
 
 #### How it works
 

data/doc/getting_started/why.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
 -->
 # Why RatatuiRuby?

data/doc/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
 -->
 # Start Here
@@ -20,6 +20,7 @@
 - [Event Handling](./concepts/event_handling.md): Keyboard, mouse, and terminal events
 - [Interactive Design](./concepts/interactive_design.md): Cached layout pattern for hit testing
 - [Testing Your Application](./concepts/application_testing.md): Snapshot testing and style assertions
+- [Custom Widgets](./concepts/custom_widgets.md): Build anything with the Draw API
 - [Async Operations](./concepts/async.md): Background tasks and non-blocking I/O
 
 ### Troubleshooting

data/doc/troubleshooting/debugging.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
 -->
 
 # Debugging TUI Applications
@@ -15,6 +15,11 @@ Write debug output to files. Tail them in a separate terminal.
 
 Create timestamped log files to avoid overwrites:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 FileUtils.mkdir_p(File.join(Dir.tmpdir, "my_debug"))
 timestamp = Time.now.strftime('%Y%m%d_%H%M%S_%N')
@@ -23,15 +28,27 @@ File.write(
   "variable=#{value.inspect}\n"
 )
 ```
+<!-- SPDX-SnippetEnd -->
 
 Or append to a single file:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 File.write("/tmp/debug.log", "#{Time.now}: #{message}\n", mode: "a")
 ```
+<!-- SPDX-SnippetEnd -->
 
 Tail the logs in a separate terminal:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```bash
 # Single file
 tail -f /tmp/debug.log
@@ -39,6 +56,7 @@ tail -f /tmp/debug.log
 # Directory of timestamped files
 watch -n 0.5 'ls -la /tmp/my_debug/ && cat /tmp/my_debug/*.log'
 ```
+<!-- SPDX-SnippetEnd -->
 
 ## REPL Debugging with `__FILE__` Guards
 
@@ -46,17 +64,29 @@ Unit tests verify correctness. But during exploratory debugging, you want to pok
 
 Wrap your main execution in a guard:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 if __FILE__ == $PROGRAM_NAME
   MyApp.new.run
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 Now load the file and interact with classes directly:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```bash
 ruby -e 'load "./bin/my_tui"; obj = MyClass.new; sleep 1; puts obj.result'
 ```
+<!-- SPDX-SnippetEnd -->
 
 This exercises domain logic without entering raw terminal mode. Use it for exploratory debugging. Write tests using the [TestHelper](application_testing.md) for regression coverage.
 

data/doc/troubleshooting/terminal_limitations.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
 -->
 
 # Terminal Limitations
@@ -114,12 +114,18 @@ There's no way to catch SIGKILL. You can only mitigate the impact.
 
 **Script graceful shutdowns.** If you write deployment or process management scripts, prefer graceful signals with a timeout before SIGKILL:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```bash
 # Graceful first, force if needed
 kill -15 $PID
 sleep 2
 kill -0 $PID 2>/dev/null && kill -9 $PID
 ```
+<!-- SPDX-SnippetEnd -->
 
 See [Application Architecture: Signal Handling](../concepts/application_architecture.md#signal-handling) for programmatic cleanup strategies.
 

data/doc/troubleshooting/tui_output.md

@@ -28,6 +28,11 @@ In raw mode:
 
 If you're using a gem that might write to stdout/stderr, wrap its calls:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 RatatuiRuby.run do |tui|
   RatatuiRuby.guard_io do
@@ -38,9 +43,15 @@ RatatuiRuby.run do |tui|
   # Object::STDERR.puts "debug: something"  # Escape hatch (corrupts display!)
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ### Defer output until after the TUI exits
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 messages = []
 
@@ -54,11 +65,17 @@ end
 # Now safe to print
 messages.each { |msg| puts msg }
 ```
+<!-- SPDX-SnippetEnd -->
 
 ### Use Logger to write to a file
 
 The `Logger` class from Ruby's standard library is the idiomatic solution:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 require "logger"
 require "tmpdir"
@@ -73,9 +90,15 @@ RatatuiRuby.run do |tui|
   # ... TUI logic ...
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ### Display messages in the TUI itself
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 RatatuiRuby.run do |tui|
   @status_message = "Something happened"
@@ -89,6 +112,7 @@ RatatuiRuby.run do |tui|
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ## Library Behavior
 
@@ -100,6 +124,11 @@ You don't need to do anything special for library warnings—they're handled aut
 
 If you need to write to stdout/stderr even when `guard_io` is active (e.g., for [pipeline integration](#headless-mode-batchpipelinecli) or IPC), use the original IO constants:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 RatatuiRuby.guard_io do
   SomeChattyGem.do_something  # This is swallowed
@@ -108,6 +137,7 @@ RatatuiRuby.guard_io do
   Object::STDOUT.puts "structured output for downstream tools"
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 This works regardless of whether `guard_io` is active. During a TUI session, the display will be corrupted—but the output will reach its destination.
 
@@ -115,6 +145,11 @@ This works regardless of whether `guard_io` is active. During a TUI session, the
 
 If your app supports both TUI and non-TUI modes (e.g., `my_app --no-tui`), call `headless!` at startup to silence `guard_io` warnings:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 if ARGV.include?("--no-tui")
   RatatuiRuby.headless!
@@ -126,6 +161,7 @@ else
   end
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 When headless, `guard_io` becomes a no-op (output flows normally), and calling `run` or `init_terminal` raises an error.
 
@@ -133,6 +169,11 @@ When headless, `guard_io` becomes a no-op (output flows normally), and calling `
 
 Some apps need to temporarily leave TUI mode for user interaction—like lazygit does when opening an external editor for commit messages. Use `restore_terminal` and `init_terminal`:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 RatatuiRuby.run do |tui|
   # ... TUI is active ...
@@ -151,5 +192,6 @@ RatatuiRuby.run do |tui|
   # ... TUI is active again ...
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 This pattern lets you hand control back to the user or spawn external processes that need normal terminal access.