ratatui_ruby 0.7.0 → 0.7.2

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

@@ -1668,7 +1668,7 @@ These are v1.0.0 quality improvements that refine the example suite after P0 is
 **Status:** Important for API discoverability — Documentation should link library and examples
 
 RDoc should cross-link between:
-- **Library classes/methods** ↔ **Examples that use them** (See also: examples/widget_foo_demo)
+- **Library classes/methods** ↔ **Examples that use them** (See also: examples/widget_foo)
 - **Primary methods** ↔ **DWIM/TIMTOWTDI aliases** (See also: tui.foo_bar as alias for tui.foo(:bar))
 
 ######  Current Practice
@@ -1685,7 +1685,7 @@ Done for:
 
 ######  Action
 
-1. Add `# See also: examples/widget_foo_demo/app.rb` to class/method RDoc
+1. Add `# See also: examples/widget_foo/app.rb` to class/method RDoc
 2. Link DWIM methods to TIMTOWTDI variants: `# Also available as: tui.constraint_length (DWIM) vs tui.constraint(:length) (TIMTOWTDI)`
 3. Create consistent pattern across all public APIs in `lib/ratatui_ruby/`
 
@@ -1694,7 +1694,7 @@ Done for:
 ```ruby
 #### Renders text with styling.
 #
-#### See also: examples/widget_paragraph_demo/app.rb (basic paragraph rendering)
+#### See also: examples/widget_paragraph/app.rb (basic paragraph rendering)
 class Paragraph < Data.define(...)
   # ...
 end
@@ -1714,16 +1714,16 @@ end
 
 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_demo
+######  The Standard: widget_tabs
 
-The `widget_tabs_demo` 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).
+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_demo:** Show a multi-step modal flow (e.g., Confirm -> Success) rather than just a static overlay.
--   **widget_list_demo:** Show a master-detail view where selecting a list item updates a detail pane.
--   **widget_input_demo:** (If created) Show specific validation logic (email vs number).
+-   **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/{quickstart.md → getting_started/quickstart.md}

@@ -59,7 +59,7 @@ end
 ```
 <!-- SYNC:END -->
 
-[![quickstart_lifecycle](./images/verify_quickstart_lifecycle.png)](../examples/verify_quickstart_lifecycle/README.md)
+[![quickstart_lifecycle](../images/verify_quickstart_lifecycle.png)](../../examples/verify_quickstart_lifecycle/README.md)
 
 #### How it works
 
@@ -115,7 +115,7 @@ end
 3.  **Method Shorthand**: The `TUI` object also provides aliases for module functions of `RatatuiRuby`, allowing you to write `tui.draw(...)` instead of the more verbose `RatatuiRuby.draw(...)`.
 4.  **Pattern Matching for Events**: Use `case...in` with pattern matching for elegant event dispatch. Always include an `else` clause at the end to catch unmatched event types (mouse, resize, paste, focus, etc.), otherwise Ruby raises `NoMatchingPatternError`.
 
-For a deeper dive into the available application architectures (Manual vs Managed), see [Application Architecture](./application_architecture.md).
+For a deeper dive into the available application architectures (Manual vs Managed), see [Application Architecture](../concepts/application_architecture.md).
 
 ### Adding Layouts
 
@@ -185,7 +185,7 @@ end
 3.  **`Frame#render_widget(widget, rect)`**: You pass the specific area (like `top` or `bottom`) to render the widget into that exact region.
 4.  **`tui.text_span` (`RatatuiRuby::Text::Span`)**: Allows for rich styling within a single line of text.
 
-[![quickstart_layout](./images/verify_quickstart_layout.png)](../examples/verify_quickstart_layout/README.md)
+[![quickstart_layout](../images/verify_quickstart_layout.png)](../../examples/verify_quickstart_layout/README.md)
 
 ## Examples
 
@@ -197,32 +197,32 @@ Focused examples for individual widgets. Each demonstrates a single widget and i
 
 | Widget | What it demonstrates |
 |--------|---------------------|
-| [Bar Chart](../examples/widget_barchart_demo/app.rb) | Grouped bars, data visualization, custom bar styling |
-| [Block](../examples/widget_block_demo/app.rb) | Borders, titles, padding, nested widgets |
-| [Box](../examples/widget_box_demo/app.rb) | Block + Paragraph composition, text wrapping |
-| [Calendar](../examples/widget_calendar_demo/app.rb) | Date highlighting, month display, event markers |
-| [Chart](../examples/widget_chart_demo/app.rb) | Line/scatter plots, axes, legends, datasets |
-| [Gauge](../examples/widget_gauge_demo/app.rb) | Progress bars, percentage display, unicode blocks |
+| [Bar Chart](../examples/widget_barchart/app.rb) | Grouped bars, data visualization, custom bar styling |
+| [Block](../examples/widget_block/app.rb) | Borders, titles, padding, nested widgets |
+| [Box](../examples/widget_box/app.rb) | Block + Paragraph composition, text wrapping |
+| [Calendar](../examples/widget_calendar/app.rb) | Date highlighting, month display, event markers |
+| [Chart](../examples/widget_chart/app.rb) | Line/scatter plots, axes, legends, datasets |
+| [Gauge](../examples/widget_gauge/app.rb) | Progress bars, percentage display, unicode blocks |
 | [Layout Split](../examples/widget_layout_split/app.rb) | Constraint types, flex modes, responsive layouts |
-| [Line Gauge](../examples/widget_line_gauge_demo/app.rb) | Horizontal progress, labels, thin-style gauges |
-| [List](../examples/widget_list_demo/app.rb) | Selection, scrolling, highlight styles, rich text items |
-| [Map](../examples/widget_map_demo/app.rb) | Canvas widget, world map rendering, coordinates |
-| [Popup](../examples/widget_popup_demo/app.rb) | Clear widget, modal dialogs, overlay composition |
-| [Ratatui Logo](../examples/widget_ratatui_logo_demo/app.rb) | Decorative branding widget |
-| [Ratatui Mascot](../examples/widget_ratatui_mascot_demo/app.rb) | ASCII art Ferris mascot |
+| [Line Gauge](../examples/widget_line_gauge/app.rb) | Horizontal progress, labels, thin-style gauges |
+| [List](../examples/widget_list/app.rb) | Selection, scrolling, highlight styles, rich text items |
+| [Map](../examples/widget_map/app.rb) | Canvas widget, world map rendering, coordinates |
+| [Popup](../examples/widget_popup/app.rb) | Clear widget, modal dialogs, overlay composition |
+| [Ratatui Logo](../examples/widget_ratatui_logo/app.rb) | Decorative branding widget |
+| [Ratatui Mascot](../examples/widget_ratatui_mascot/app.rb) | ASCII art Ferris mascot |
 | [Rect](../examples/widget_rect/app.rb) | Geometry helpers, area calculations, contains/intersection |
 | [Rich Text](../examples/widget_rich_text/app.rb) | Spans, lines, inline styling, mixed colors |
-| [Scrollbar](../examples/widget_scrollbar_demo/app.rb) | Orientations, thumb/track styling, scroll state |
+| [Scrollbar](../examples/widget_scrollbar/app.rb) | Orientations, thumb/track styling, scroll state |
 | [Scroll Text](../examples/widget_scroll_text/app.rb) | Paragraph scrolling, viewport control, long content |
-| [Sparkline](../examples/widget_sparkline_demo/app.rb) | Mini charts, time series, bar sets |
+| [Sparkline](../examples/widget_sparkline/app.rb) | Mini charts, time series, bar sets |
 | [Style Colors](../examples/widget_style_colors/app.rb) | Named colors, RGB, indexed 256-color palette |
-| [Table](../examples/widget_table_demo/app.rb) | Row selection, column widths, per-cell styling |
-| [Tabs](../examples/widget_tabs_demo/app.rb) | Tab navigation, highlighting, dividers |
+| [Table](../examples/widget_table/app.rb) | Row selection, column widths, per-cell styling |
+| [Tabs](../examples/widget_tabs/app.rb) | Tab navigation, highlighting, dividers |
 | [Text Width](../examples/widget_text_width/app.rb) | Unicode-aware width measurement, CJK support |
-| [Canvas](../examples/widget_canvas_demo/app.rb) | Drawing shapes, markers, custom graphics |
-| [Cell](../examples/widget_cell_demo/app.rb) | Buffer cell inspection, styling attributes |
-| [Center](../examples/widget_center_demo/app.rb) | Centering content, horizontal/vertical alignment |
-| [Overlay](../examples/widget_overlay_demo/app.rb) | Layering widgets, modal backgrounds |
+| [Canvas](../examples/widget_canvas/app.rb) | Drawing shapes, markers, custom graphics |
+| [Cell](../examples/widget_cell/app.rb) | Buffer cell inspection, styling attributes |
+| [Center](../examples/widget_center/app.rb) | Centering content, horizontal/vertical alignment |
+| [Overlay](../examples/widget_overlay/app.rb) | Layering widgets, modal backgrounds |
 | [Custom Render](../examples/widget_render/app.rb) | Low-level Draw API, escape hatch for custom widgets |
 
 ### Sample Applications
@@ -253,8 +253,8 @@ These larger examples combine widgets into complete applications, demonstrating
 
 Now that you've seen what **ratatui_ruby** can do:
 
-- **Deep dive**: Read the [Application Architecture](./application_architecture.md) guide for scaling patterns
-- **Test your TUI**: See the [Testing Guide](./application_testing.md) for snapshot and style assertions
-- **Explore the API**: Browse the [full RDoc documentation](./index.md)
+- **Deep dive**: Read the [Application Architecture](../concepts/application_architecture.md) guide for scaling patterns
+- **Test your TUI**: See the [Testing Guide](../concepts/application_testing.md) for snapshot and style assertions
+- **Explore the API**: Browse the [full RDoc documentation](../index.md)
 - **Learn the philosophy**: Read [Why RatatuiRuby?](./why.md) for comparisons and design decisions
 - **Get help**: Join the [discussion mailing list](https://lists.sr.ht/~kerrick/ratatui_ruby-discuss)

data/doc/{why.md → getting_started/why.md}

@@ -90,4 +90,4 @@ Ready to build?
 
 - [Quickstart Guide](./quickstart.md) — Your first app in 5 minutes
 - [Widget Gallery](./quickstart.md#widget-demos) — See what's possible
-- [Application Architecture](./application_architecture.md) — Patterns for scaling
+- [Application Architecture](../concepts/application_architecture.md) — Patterns for scaling

data/doc/index.md

@@ -2,20 +2,34 @@
   SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
   SPDX-License-Identifier: CC-BY-SA-4.0
 -->
-# **ratatui_ruby** Documentation
+# Start Here
 
 
 ## Documentation for Users
 
 - [README](../README.md): Project overview and installation
-- [Why RatatuiRuby?](./why.md): Philosophy, comparisons, and what makes us different
-- [Quickstart](./quickstart.md): Build your first TUI app
-- [Application Architecture](./application_architecture.md): Lifecycle patterns and API choices
-- [Event Handling](./event_handling.md): Keyboard, mouse, and terminal events
-- [Interactive Design](./interactive_design.md): Cached layout pattern for hit testing
-- [Terminal Limitations](./terminal_limitations.md): Platform quirks and workarounds
-- [Testing Your Application](./application_testing.md): Snapshot testing and style assertions
-- [Migrating to v0.7.0](./v0.7.0_migration.md): Namespace changes and upgrade guide
+
+### Getting Started
+
+- [Why RatatuiRuby?](./getting_started/why.md): Philosophy, comparisons, and what makes us different
+- [Quickstart](./getting_started/quickstart.md): Build your first TUI app
+
+### Concepts
+
+- [Application Architecture](./concepts/application_architecture.md): Lifecycle patterns and API choices
+- [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
+- [Async Operations](./concepts/async.md): Background tasks and non-blocking I/O
+
+### Troubleshooting
+
+- [Debugging](./troubleshooting/debugging.md): Debugging techniques and tools
+- [Terminal Limitations](./troubleshooting/terminal_limitations.md): Platform quirks and workarounds
+
+### Migration
+
+- [Migrating to v0.7.0](./migration/v0_7_0.md): Namespace changes and upgrade guide
 
 
 ## Documentation for Contributors

data/doc/troubleshooting/debugging.md

@@ -0,0 +1,71 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Debugging TUI Applications
+
+TUI applications run in raw terminal mode. stderr and stdout carry terminal escape sequences. Using `puts` or `warn` inside the render loop corrupts the display.
+
+This creates a problem: how do you inspect variables and trace execution?
+
+Write debug output to files. Tail them in a separate terminal.
+
+## File-Based Logging
+
+Create timestamped log files to avoid overwrites:
+
+```ruby
+FileUtils.mkdir_p(File.join(Dir.tmpdir, "my_debug"))
+timestamp = Time.now.strftime('%Y%m%d_%H%M%S_%N')
+File.write(
+  File.join(Dir.tmpdir, "my_debug", "#{timestamp}.log"),
+  "variable=#{value.inspect}\n"
+)
+```
+
+Or append to a single file:
+
+```ruby
+File.write("/tmp/debug.log", "#{Time.now}: #{message}\n", mode: "a")
+```
+
+Tail the logs in a separate terminal:
+
+```bash
+# Single file
+tail -f /tmp/debug.log
+
+# Directory of timestamped files
+watch -n 0.5 'ls -la /tmp/my_debug/ && cat /tmp/my_debug/*.log'
+```
+
+## REPL Debugging with `__FILE__` Guards
+
+Unit tests verify correctness. But during exploratory debugging, you want to poke at objects interactively. Loading the full TUI just to inspect one object is slow.
+
+Wrap your main execution in a guard:
+
+```ruby
+if __FILE__ == $PROGRAM_NAME
+  MyApp.new.run
+end
+```
+
+Now load the file and interact with classes directly:
+
+```bash
+ruby -e 'load "./bin/my_tui"; obj = MyClass.new; sleep 1; puts obj.result'
+```
+
+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.
+
+## Isolating Terminal Issues
+
+Something works in a `ruby -e` script but fails in the TUI. Common causes:
+
+1. **Thread context.** Ruby threads share the process's terminal state.
+2. **Raw mode.** External commands fail when stdin/stdout are reconfigured.
+3. **SSH/Git auth.** Commands that prompt for credentials hang or return empty.
+
+See [Async Operations](async.md) for solutions.

data/doc/{terminal_limitations.md → troubleshooting/terminal_limitations.md}

@@ -90,3 +90,36 @@ Focus event reporting requires explicit terminal support and configuration. Some
 ### The Solution
 
 Don't rely on focus events for critical functionality. Treat them as nice-to-have enhancements. If your application shows stale data when the user returns, periodically refresh instead of waiting for focus events.
+
+## Process Termination
+
+### The Problem
+
+Your TUI app is terminated by `kill -9` or the [OOM killer](https://en.wikipedia.org/wiki/Out_of_memory#Out_of_memory_management). The terminal stays in raw mode. The user's cursor vanishes. Input echoes weirdly. Their shell is unusable.
+
+### The Cause
+
+SIGKILL (`kill -9`) terminates processes immediately. No cleanup code runs. The terminal never receives the escape sequences to restore normal mode.
+
+This also happens when:
+- The system OOM killer terminates your process
+- A parent process force-kills your app
+- A debugger disconnects ungracefully
+
+### The Solution
+
+There's no way to catch SIGKILL. You can only mitigate the impact.
+
+**Tell your users how to recover.** In your README or troubleshooting docs, explain: if the terminal breaks, type `reset` and press Enter. The characters won't echo, but the command runs.
+
+**Script graceful shutdowns.** If you write deployment or process management scripts, prefer graceful signals with a timeout before SIGKILL:
+
+```bash
+# Graceful first, force if needed
+kill -15 $PID
+sleep 2
+kill -0 $PID 2>/dev/null && kill -9 $PID
+```
+
+See [Application Architecture: Signal Handling](../concepts/application_architecture.md#signal-handling) for programmatic cleanup strategies.
+

data/examples/app_all_events/README.md

@@ -99,3 +99,4 @@ The Color Picker uses a Component-Based pattern. Each component encapsulates its
 
 Use this pattern for forms, editors, and mouse-driven tools.
 
+[Read the source code →](app.rb)

data/examples/app_all_events/app.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 $LOAD_PATH.unshift File.expand_path(__dir__)

data/examples/app_all_events/model/app_model.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 require_relative "timestamp"
 require_relative "event_entry"

data/examples/app_all_events/model/event_color_cycle.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 # Cycles through a set of colors for event logging.
 #

data/examples/app_all_events/model/event_entry.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 require_relative "timestamp"
 require "ratatui_ruby"

data/examples/app_all_events/model/msg.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 # Semantic message types for the Model-View-Update architecture.
 #

data/examples/app_all_events/model/timestamp.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 # Represents a high-resolution point in time.
 #

data/examples/app_all_events/update.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 require_relative "model/app_model"
 require_relative "model/msg"

data/examples/app_all_events/view/app_view.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 require_relative "../view"
 require_relative "counts_view"

data/examples/app_all_events/view/controls_view.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 require_relative "../view"
 

data/examples/app_all_events/view/counts_view.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 require_relative "../view"
 

data/examples/app_all_events/view/live_view.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 require_relative "../view"
 

data/examples/app_all_events/view/log_view.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 require_relative "../view"
 

data/examples/app_all_events/view.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 module View
 end

data/examples/app_color_picker/README.md

@@ -134,3 +134,5 @@ Use this pattern for forms, editors, and mouse-driven tools.
 Dashboards display data. They rarely require complex mouse interaction. Model-View-Update works best there. State is immutable. Logic is pure. Updates are predictable. This simplifies testing.
 
 Use that pattern for logs, monitors, and data viewers.
+
+[Read the source code →](app.rb)

data/examples/app_color_picker/app.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 $LOAD_PATH.unshift File.expand_path(__dir__)

data/examples/app_color_picker/clipboard.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 # Manages system clipboard interaction with transient feedback.
 #

data/examples/app_color_picker/color.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 require "chroma"
 require "wcag_color_contrast"

data/examples/app_color_picker/controls.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 # A display-only component showing keyboard shortcuts and clipboard feedback.
 #

data/examples/app_color_picker/copy_dialog.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 require_relative "clipboard"
 

data/examples/app_color_picker/export_pane.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 # A self-contained component displaying export formats for a color.
 #

data/examples/app_color_picker/harmony.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 # A single color variant with label and styling information.
 #

data/examples/app_color_picker/input.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 require_relative "color"
 

data/examples/app_color_picker/main_container.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 require_relative "input"
 require_relative "palette"

data/examples/app_color_picker/palette.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 require_relative "color"
 

data/examples/app_login_form/README.md

@@ -43,7 +43,10 @@ ruby examples/app_login_form/app.rb
 ## Learning Outcomes
 
 Use this example if you need to...
+
 - Create a modal dialog or popup.
 - Center a widget on the screen (vertically and horizontally).
 - Implement a simple text input field with cursor management.
 - layer widgets using the `Overlay` widget.
+
+[Read the source code →](app.rb)

data/examples/app_login_form/app.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 require "ratatui_ruby"

data/examples/app_stateful_interaction/README.md

@@ -31,3 +31,5 @@ In `ratatui_ruby`'s Stateful Rendering:
 | `Tab` / `←` / `→` | Switch active pane (List vs Table) |
 | `Mouse Click` | Select the clicked row (Works with scrolling!) |
 | `q` | Quit |
+
+[Read the source code →](app.rb)

data/examples/app_stateful_interaction/app.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 require "ratatui_ruby"

data/examples/timeout_demo.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+#--
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
+#++
 
 # Timeout Demo: Non-Blocking Event Polling
 #

data/examples/verify_quickstart_dsl/README.md

@@ -5,7 +5,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 
 # Quickstart DSL Verification
 
-Verifies the "Simplified API" tutorial in the [Quickstart](../../doc/quickstart.md#simplified-api).
+Verifies the "Simplified API" tutorial in the [Quickstart](../../doc/getting_started/quickstart.md#simplified-api).
 
 This example exists as a documentation regression test. It ensures the recommended TUI facade and managed lifecycle workflow remains functional.
 
@@ -46,4 +46,4 @@ end
 ```
 <!-- SYNC:END -->
 
-[![verify_quickstart_dsl](../../doc/images/verify_quickstart_dsl.png)](../../doc/quickstart.md#simplified-api)
+[![verify_quickstart_dsl](../../doc/images/verify_quickstart_dsl.png)](../../doc/getting_started/quickstart.md#simplified-api)