ratatui_ruby 1.0.0 → 1.0.1

data/doc/getting_started/quickstart.md

@@ -1,291 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-# Quickstart
-
-Welcome to **ratatui_ruby**! This guide will help you get up and running with your first Terminal User Interface in Ruby.
-
-## Installation
-
-See [Installation in the README](../README.md#installation) for setup instructions.
-
-
-## Tutorials
-
-### Basic Application
-
-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
-RatatuiRuby.init_terminal
-
-begin
-  # The Main Loop
-  loop do
-    # 2. Create your UI (Immediate Mode)
-    # We define a Paragraph widget inside a Block with a title and borders.
-    view = RatatuiRuby::Widgets::Paragraph.new(
-      text: "Hello, Ratatui! Press 'q' to quit.",
-      alignment: :center,
-      block: RatatuiRuby::Widgets::Block.new(
-        title: "My Ruby TUI App",
-        title_alignment: :center,
-        borders: [:all],
-        border_style: { fg: "cyan" },
-        style: { fg: "white" }
-      )
-    )
-
-    # 3. Draw the UI
-    RatatuiRuby.draw do |frame|
-      frame.render_widget(view, frame.area)
-    end
-
-    # 4. Poll for events
-    case RatatuiRuby.poll_event
-    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
-      break
-    else
-      nil
-    end
-
-    # 5. Guard against accidental output (optional but recommended)
-    # Wrap any code that might puts/warn to prevent screen corruption.
-    RatatuiRuby.guard_io do
-      # SomeChattyGem.do_something
-    end
-  end
-ensure
-  # 6. Restore the terminal to its original state
-  RatatuiRuby.restore_terminal
-end
-```
-<!-- SYNC:END -->
-<!-- SPDX-SnippetEnd -->
-
-[![quickstart_lifecycle](../images/verify_quickstart_lifecycle.png)](../../examples/verify_quickstart_lifecycle/README.md)
-
-#### How it works
-
-1.  **`RatatuiRuby.init_terminal`**: Enters raw mode and switches to the alternate screen.
-2.  **Immediate Mode UI**: On every iteration, describe your UI by creating `Data` objects (e.g., `Paragraph`, `Block`).
-3.  **`RatatuiRuby.draw { |frame| ... }`**: The block receives a `Frame` object as a canvas. Render widgets onto specific areas. Nothing is drawn until the block finishes, ensuring flicker-free updates.
-4.  **`RatatuiRuby.poll_event`**: Returns a typed `Event` object with predicates like `key?`, `mouse?`, `resize?`, etc. Returns `RatatuiRuby::Event::None` if no events are pending. Use predicates to check event type without pattern matching.
-5.  **`RatatuiRuby.guard_io { }`**: Wraps code that might write to stdout/stderr (e.g., chatty gems). Output is swallowed to prevent screen corruption. Optional but recommended for production apps.
-6.  **`RatatuiRuby.restore_terminal`**: Essential for leaving raw mode and returning to the shell. Always wrap your loop in `begin...ensure` to guarantee this runs.
-
-### Simplified API
-
-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.
-RatatuiRuby.run do |tui|
-  loop do
-    # 2. Create your UI with methods instead of classes.
-    view = tui.paragraph(
-      text: "Hello, Ratatui! Press 'q' to quit.",
-      alignment: :center,
-      block: tui.block(
-        title: "My Ruby TUI App",
-        title_alignment: :center,
-        borders: [:all],
-        border_style: { fg: "cyan" },
-        style: { fg: "white" }
-      )
-    )
-
-    # 3. Use RatatuiRuby methods, too.
-    tui.draw do |frame|
-      frame.render_widget(view, frame.area)
-    end
-
-    # 4. Poll for events with pattern matching
-    case tui.poll_event
-    in { type: :key, code: "q" }
-      break
-    else
-      # Ignore other events
-    end
-  end
-end
-```
-<!-- SYNC:END -->
-<!-- SPDX-SnippetEnd -->
-
-#### How it works
-
-1.  **`RatatuiRuby.run`**: This context manager initializes the terminal before the block starts and ensures `restore_terminal` is called when the block exits (even if an error occurs).
-2.  **Widget Shorthand**: The block yields a `TUI` object (here named `tui`). This object provides factory methods for every widget, allowing you to write `tui.paragraph(...)` instead of the more verbose `RatatuiRuby::Widgets::Paragraph.new(...)`.
-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](../concepts/application_architecture.md).
-
-### Adding Layouts
-
-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
-  tui.draw do |frame|
-    # 1. Split the screen
-    top, bottom = tui.layout_split(
-      frame.area,
-      direction: :vertical,
-      constraints: [
-        tui.constraint_percentage(75),
-        tui.constraint_percentage(25),
-      ]
-    )
-
-    # 2. Render Top Widget
-    frame.render_widget(
-      tui.paragraph(
-        text: "Hello, Ratatui!",
-        alignment: :center,
-        block: tui.block(title: "Content", borders: [:all], border_style: { fg: "cyan" })
-      ),
-      top
-    )
-
-    # 3. Render Bottom Widget with Styled Text
-    # We use a Line of Spans to style specific characters
-    text_line = tui.text_line(
-      spans: [
-        tui.text_span(content: "Press '"),
-        tui.text_span(
-          content: "q",
-          style: tui.style(modifiers: [:bold, :underlined])
-        ),
-        tui.text_span(content: "' to quit."),
-      ],
-      alignment: :center
-    )
-
-    frame.render_widget(
-      tui.paragraph(
-        text: text_line,
-        block: tui.block(title: "Controls", borders: [:all])
-      ),
-      bottom
-    )
-  end
-
-  case tui.poll_event
-  in { type: :key, code: "q" }
-    break
-  else
-    # Ignore other events
-  end
-end
-```
-<!-- SYNC:END -->
-<!-- SPDX-SnippetEnd -->
-
-#### How it works
-
-1.  **`tui.layout_split` (`RatatuiRuby::Layout::Layout.split`)**: Takes an area (like `frame.area`) and splits it into multiple sub-areas based on constraints.
-2.  **`tui.constraint_*` (`RatatuiRuby::Layout::Constraint`)**: Defines how space is distributed (e.g., `percentage`, `length`, `min`, `max`).
-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)
-
-## Examples
-
-These examples showcase the full power of **ratatui_ruby**. You can find their source code in the [examples directory](../../examples).
-
-### Widget Demos
-
-Focused examples for individual widgets. Each demonstrates a single widget and its configuration options.
-
-| Widget                                                        | What it demonstrates                                       |
-| ------------------------------------------------------------- | ---------------------------------------------------------- |
-| [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/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/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/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/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/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
-
-These larger examples combine widgets into complete applications, demonstrating real-world TUI patterns and architectures.
-
-| Application                                                            | Architecture      | What you'll learn                                            |
-| ---------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------ |
-| [All Events](../../examples/app_all_events/app.rb)                     | Model-View-Update | Event handling, unidirectional data flow, scalable structure |
-| [Color Picker](../../examples/app_color_picker/app.rb)                 | Component-Based   | Hit testing, modal dialogs, encapsulated state               |
-| [Debugging Showcase](../../examples/app_debugging_showcase/app.rb)     | Simple Loop       | Remote debugging, Rust backtraces, improved error messages   |
-| [Login Form](../../examples/app_login_form/app.rb)                     | Overlay + Center  | Modal forms, cursor positioning, text input                  |
-| [Stateful Interaction](../../examples/app_stateful_interaction/app.rb) | State Objects     | ListState/TableState, offset read-back, mouse click-to-row   |
-
-#### All Events
-
-[![all_events](../images/app_all_events.png)](../../examples/app_all_events/README.md)
-
-#### Color Picker
-
-[![color_picker](../images/app_color_picker.png)](../../examples/app_color_picker/README.md)
-
-#### Debugging Showcase
-
-[![debugging_showcase](../images/app_debugging_showcase.gif)](../../examples/app_debugging_showcase/README.md)
-
-#### Login Form
-
-[![login_form](../images/app_login_form.png)](../../examples/app_login_form/README.md)
-
-
-## Next Steps
-
-Now that you've seen what **ratatui_ruby** can do:
-
-- **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
-- **Avoid common mistakes**: See [Terminal Output During TUI Sessions](../troubleshooting/tui_output.md) to prevent screen corruption
-- **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/getting_started/why.md

@@ -1,93 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-# Why RatatuiRuby?
-
-The terminal is having a renaissance. Ruby deserves to be at the forefront.
-
-**RatatuiRuby** is a high-performance, immediate-mode TUI engine that brings the power of Rust's [Ratatui](https://ratatui.rs) library directly into Ruby. No ports. No emulations. A native bridge to the industry-standard Rust crate.
-
-
-## The Pitch
-
-You want to build a terminal UI. You love Ruby. Your options were:
-
-1. **Learn Go** for Bubble Tea
-2. **Learn Rust** for Ratatui
-3. **Use a pure-Ruby library** with limited performance
-
-We built a fourth option: **Write Ruby. Run Rust.**
-
-RatatuiRuby gives you Rust's layout engine, rendering speed, and battle-tested widgets — with Ruby's expressiveness, ecosystem, and joy.
-
-
-## RatatuiRuby vs. CharmRuby
-
-[CharmRuby](https://github.com/marcoroth/charm_ruby) is an excellent project by Marco Roth. It provides Ruby bindings to Charm's Go libraries (Bubble Tea, Lipgloss). The Ruby ecosystem is better because both projects exist.
-
-So which one should you choose?
-
-| | CharmRuby | RatatuiRuby |
-|---|-----------|-------------|
-| **Backend** | Go runtime | Rust (no runtime) |
-| **Architecture** | Elm Architecture (MVU) | Immediate-mode + your choice |
-| **GC Behavior** | Two GCs (Ruby + Go) | One GC (Ruby only) |
-| **Rendering** | String manipulation | Constraint-based layout tree |
-| **Best for** | Fans of Bubble Tea, MVU | Native performance, heavy-duty apps |
-
-**What's a runtime?** A runtime is background machinery that a language needs to run. Go has one (for goroutines and garbage collection). Rust doesn't — it compiles to plain machine code. When you use Go bindings, you're running *two* runtimes in the same process (Ruby's and Go's), which adds complexity and memory overhead. With Rust bindings, there's only Ruby.
-
-**Choose CharmRuby** if you prefer Charm's aesthetics or are migrating existing Bubble Tea code.
-
-**Choose RatatuiRuby** if you want zero-overhead native performance and architectural freedom. RatatuiRuby doesn't force a framework — you can build MVU, component-based, or any pattern you prefer.
-
-
-## Why Not Just Write Rust?
-
-Rust is amazing. It's also strict.
-
-The borrow checker enforces memory safety. That's great for systems programming. It's painful for UI iteration. Moving a sidebar, changing a color, or swapping a widget often requires refactoring ownership chains.
-
-With RatatuiRuby, you just change the object. You get Rust's performance where it matters — rendering — and Ruby's flexibility where it counts — designing.
-
-
-## Why Not Just Write Go?
-
-Go is pragmatic. But using Go bindings means running *two* runtimes in the same process: Ruby's and Go's. That adds complexity and memory overhead.
-
-With RatatuiRuby, there's only Ruby. Rust compiles to plain machine code with no runtime — it integrates seamlessly.
-
-
-## Why Ruby?
-
-[Ruby isn't just another language](https://www.ruby-lang.org/en/). It's an ecosystem:
-
-- **[ActiveRecord](https://guides.rubyonrails.org/active_record_basics.html)** — Query your database with elegant, chainable methods
-- **[RSpec](https://rspec.info/)** — Write expressive, readable tests with `describe`, `it`, and `expect`
-- **[Blocks](https://ruby-doc.org/docs/ruby-doc-bundle/UsersGuide/rg/blocks.html)** — Pass behavior to methods with `do...end`, the heart of Ruby's expressiveness
-- **[Metaprogramming](https://ruby-doc.org/docs/ruby-doc-bundle/UsersGuide/rg/objinitialization.html)** — Define methods dynamically, build DSLs, and write code that writes code
-- **[Bundler](https://bundler.io/)** — Access 180,000+ gems with a single `bundle add`
-
-Build a dashboard for your Rails app. Monitor your Sidekiq jobs. Create developer tools in the same language as the code they inspect.
-
-
-## The Philosophy: A Solid Foundation
-
-RatatuiRuby is a **low-level engine**. It provides raw primitives — Layouts, Blocks, Text, Tables, Charts — to build anything.
-
-It doesn't force a framework on you. You can use:
-- **Model-View-Update** for dashboards and data displays
-- **Component-based** patterns for interactive tools
-- **Your own architecture** for everything else
-
-This is the foundation for Ruby's next generation of TUI tools, dashboards, and interactive scripts.
-
-
-## Get Started
-
-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](../concepts/application_architecture.md) — Patterns for scaling

data/doc/index.md

@@ -1,39 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-# Start Here
-
-
-## Documentation for Users
-
-- [README](../README.md): Project overview and installation
-
-### 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
-- [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
-
-- [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
-
-- [Contributing Guidelines](https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md): How to contribute patches and features
-- [More Documentation for Contributors](./contributors/index.md): Internal design docs and style guides

data/doc/troubleshooting/async.md

@@ -1,4 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->

data/doc/troubleshooting/terminal_limitations.md

@@ -1,131 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Terminal Limitations
-
-Some behaviors are outside the control of `ratatui_ruby`. This document explains common pitfalls that affect your application or your users, but cannot be fixed in the library.
-
-## Keyboard Event Interception
-
-### The Problem
-
-Your application receives a key event, but the modifier flags are missing. You pressed Ctrl+PageUp, but the event shows `code="page_up"` with `modifiers=[]`.
-
-### The Cause
-
-Terminal emulators intercept certain key combinations for their own features. The key press never reaches your application—the terminal consumes it first.
-
-Common culprits on macOS:
-
-| Key Combination      | Terminal Behavior                    |
-|---------------------|--------------------------------------|
-| Ctrl+PageUp/Down    | Switch tabs (Terminal.app, iTerm2)   |
-| Ctrl+Tab            | Switch tabs                          |
-| Cmd+T / Cmd+N       | New tab / New window                 |
-| Cmd+C / Cmd+V       | Copy / Paste (not Ctrl)              |
-
-Linux terminals vary widely. Windows Terminal and ConEmu have their own defaults.
-
-### The Solution
-
-1. **Test with different terminals.** Kitty, WezTerm, and Alacritty pass more key combinations through to applications by default. If a key works in Kitty but not Terminal.app, the terminal is the issue.
-
-2. **Reconfigure your terminal.** Most terminal emulators let you unbind or remap default shortcuts in their settings.
-
-3. **Use alternative key bindings.** If your users will run your application in various terminals, design your keybindings to avoid commonly intercepted combinations:
-   - Use Alt+PageUp instead of Ctrl+PageUp
-   - Use Ctrl+J/K instead of Ctrl+Up/Down
-   - Avoid Ctrl+Tab entirely
-
-4. **Document requirements.** If your application depends on specific key combinations, document the terminal requirements for your users.
-
-### Enhanced Keyboard Protocol
-
-Some terminals support the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/), which provides unambiguous key event reporting including:
-
-- Individual modifier key events (LeftShift vs RightShift)
-- Media keys (Play, Pause, Volume controls)
-- Repeat and release events
-
-Terminals with full protocol support:
-- Kitty
-- WezTerm
-- Foot
-- Alacritty (partial)
-
-Standard terminals (Terminal.app, iTerm2, GNOME Terminal) do not support the enhanced protocol.
-
-**RatatuiRuby Status:** The underlying library (crossterm) supports this protocol, but RatatuiRuby does not yet expose a way to enable it. The key code mappings for media keys and individual modifier keys exist, but they will only be received from terminals that enable the protocol by default. This is planned for a future release.
-
-## Mouse Event Limitations
-
-### The Problem
-
-Mouse events work in some terminals but not others. Or they work, but only up to certain coordinates.
-
-### The Cause
-
-Mouse reporting requires terminal escape sequence support. Older terminals may not support:
-
-- SGR mouse mode (coordinates > 223)
-- Mouse motion tracking
-- Button-event tracking
-
-### The Solution
-
-Ensure your terminal supports modern mouse modes. Most actively maintained terminals do. If running in a legacy environment, test mouse functionality and provide keyboard alternatives.
-
-## Focus Events
-
-### The Problem
-
-`Event::FocusGained` and `Event::FocusLost` are never received.
-
-### The Cause
-
-Focus event reporting requires explicit terminal support and configuration. Some terminals don't support it at all.
-
-### 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:
-
-<!-- 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.
-