ratatui_ruby 0.5.0 → 0.7.0

data/doc/event_handling.md

@@ -10,7 +10,15 @@ SPDX-License-Identifier: AGPL-3.0-or-later
 
 Events are retrieved using `RatatuiRuby.poll_event`. This method returns an instance of a subclass of `RatatuiRuby::Event` (e.g., `RatatuiRuby::Event::Key`, `RatatuiRuby::Event::Mouse`). When no event is available, it returns `RatatuiRuby::Event::None`—a [null object](https://martinfowler.com/eaaCatalog/specialCase.html) that safely responds to all event predicates with `false`.
 
-## 1. Symbol and String Comparison (Simplest)
+## 1. Blocking vs. Polling
+
+Most applications run in a loop (e.g., a game loop or UI loop). To prevent high CPU usage, the loop should wait briefly for input.
+
+*   **Default (Polling):** `RatatuiRuby.poll_event` (no args) waits for **0.016s** (approx 60 FPS). If no event occurs, it returns `RatatuiRuby::Event::None`. This keeps the application responsive.
+*   **Blocking:** `RatatuiRuby.poll_event(timeout: nil)` waits **forever** until an event occurs. Use this for scripts that only react to input and do not need to update the UI on a timer.
+*   **Non-Blocking:** `RatatuiRuby.poll_event(timeout: 0.0)` returns immediately.
+
+## 2. Symbol and String Comparison (Simplest)
 
 For simple key events, `RatatuiRuby::Event::Key` objects can be compared directly to Symbols or Strings. This is often the quickest way to get started.
 
@@ -36,7 +44,7 @@ if event == :enter
 end
 ```
 
-## 2. Predicate Methods (Intermediate)
+## 3. Predicate Methods (Intermediate)
 
 If you need more control or logic (e.g. `if/elsif`), or need to handle non-key events like Resize or Mouse, use the predicate methods.
 
@@ -82,7 +90,7 @@ if event.mouse? && event.scroll_up?
 end
 ```
 
-## 3. Pattern Matching (Powerful)
+## 4. Pattern Matching (Powerful)
 
 For complex applications, Ruby 3.0+ Pattern Matching with the `type:` discriminator is the most idiomatic and concise approach.
 

data/doc/index.md

@@ -7,13 +7,18 @@
 
 ## Documentation for Users
 
-- [README](../README.md)
-- [Quickstart](./quickstart.md)
-- [Application Architecture](./application_architecture.md)
-- [Testing Your Application](./application_testing.md)
+- [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
 
 
 ## Documentation for Contributors
 
-- [Contributing Guidelines](https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md)
-- [More Documentation for Contributors](./contributors/index.md)
+- [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/interactive_design.md

@@ -103,10 +103,10 @@ end
 
 ## Layout.split
 
-`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 `Session` helper (`tui.layout_split`) for cleaner application code.
+`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.
 
 ```ruby
-# Preferred (Session API)
+# Preferred (TUI API)
 left, right = tui.layout_split(area, constraints: [...])
 
 # Manual (Core API)

data/doc/quickstart.md

@@ -8,25 +8,7 @@ Welcome to **ratatui_ruby**! This guide will help you get up and running with yo
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
-```ruby
-gem "ratatui_ruby"
-```
-
-
-And then execute:
-
-```bash
-bundle install
-```
-
-
-Or install it yourself as:
-
-```bash
-gem install ratatui_ruby
-```
+See [Installation in the README](../README.md#installation) for setup instructions.
 
 
 ## Tutorials
@@ -35,21 +17,20 @@ gem install ratatui_ruby
 
 Here is a "Hello World" application that demonstrates the core lifecycle of a **ratatui_ruby** app.
 
+<!-- SYNC:START:../examples/verify_quickstart_lifecycle/app.rb:main -->
 ```ruby
-require "ratatui_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::Paragraph.new(
+    view = RatatuiRuby::Widgets::Paragraph.new(
       text: "Hello, Ratatui! Press 'q' to quit.",
       alignment: :center,
-      block: RatatuiRuby::Block.new(
+      block: RatatuiRuby::Widgets::Block.new(
         title: "My Ruby TUI App",
         title_alignment: :center,
         borders: [:all],
@@ -57,23 +38,28 @@ begin
         style: { fg: "white" }
       )
     )
- 
+
     # 3. Draw the UI
     RatatuiRuby.draw do |frame|
       frame.render_widget(view, frame.area)
     end
- 
+
     # 4. Poll for events
-    event = RatatuiRuby.poll_event
-    break if event.key? && event.code == "q"
+    case RatatuiRuby.poll_event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      break
+    else
+      nil
+    end
   end
 ensure
   # 5. Restore the terminal to its original state
   RatatuiRuby.restore_terminal
 end
 ```
+<!-- SYNC:END -->
 
-![quickstart_lifecycle](./images/verify_quickstart_lifecycle.png)
+[![quickstart_lifecycle](./images/verify_quickstart_lifecycle.png)](../examples/verify_quickstart_lifecycle/README.md)
 
 #### How it works
 
@@ -83,14 +69,13 @@ end
 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.restore_terminal`**: Essential for leaving raw mode and returning to the shell. Always wrap your loop in `begin...ensure` to guarantee this runs.
 
-### Idiomatic Session
+### Simplified API
 
-You can simplify your code by using `RatatuiRuby.run`. This method handles the terminal lifecycle for you, yielding a `Session` object with factory methods for widgets.
+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.
 
-```rb
-require "ratatui_ruby"
-
-# 1. Initialize the terminal and ensure it is restored.
+<!-- 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.
@@ -121,12 +106,13 @@ RatatuiRuby.run do |tui|
   end
 end
 ```
+<!-- SYNC:END -->
 
 #### 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 `Session` object (here named `tui`). This object provides factory methods for every widget, allowing you to write `tui.paragraph(...)` instead of the more verbose `RatatuiRuby::Paragraph.new(...)`.
-3.  **Method Shorthand**: The session object also provides aliases for module functions of `RatatuiRuby`, allowing you to write `tui.draw(...)` instead of the more verbose `RatatuiRuby.draw(...)`.
+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](./application_architecture.md).
@@ -135,164 +121,140 @@ 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.
 
+<!-- SYNC:START:../examples/verify_quickstart_layout/app.rb:main -->
 ```ruby
-require "ratatui_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),
+      ]
+    )
 
-RatatuiRuby.run do |tui|
-  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_color: "cyan")
+      ),
+      top
+    )
 
-      # 2. Render Top Widget
-      frame.render_widget(
-        tui.paragraph(
-          text: "Hello, Ratatui!",
-          alignment: :center,
-          block: tui.block(title: "Content", borders: [:all], border_color: "cyan")
+    # 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])
         ),
-        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
-      )
+        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
+    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
+  case tui.poll_event
+  in { type: :key, code: "q" }
+    break
+  else
+    # Ignore other events
   end
 end
 ```
+<!-- SYNC:END -->
 
 #### How it works
 
-1.  **`tui.layout_split` (`RatatuiRuby::Layout.split`)**: Takes an area (like `frame.area`) and splits it into multiple sub-areas based on constraints.
-2.  **`tui.constraint_*` (`RatatuiRuby::Constraint`)**: Defines how space is distributed (e.g., `percentage`, `length`, `min`, `max`).
+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).
 
-### Sample Applications
-
-Full-featured examples demonstrating complex layouts and real-world TUI patterns.
-
-
-
-#### [All Events](../examples/app_all_events/app.rb)
-
-Handling terminal events is unpredictable. Developers need to know exactly what the terminal sends for `Ctrl+C` or a mouse drag.
-
-This app captures and visualizes every event—keys, mouse, resize, paste, and focus.
-
-Use it to debug your input handling or verify terminal behavior.
-
-**What you'll learn:**
-
-*   **MVVM Architecture**: Separates logic (Model), state (ViewModel), and rendering (View) for clean, testable code.
-*   **Event Handling**: Captures and distinguishes all input types, including modifiers (`Ctrl+C`) and focus changes.
-*   **Scalable Structure**: Organizes a non-trivial application into small, focused classes instead of a monolithic script.
-
-![all_events](./images/app_all_events.png)
-
-#### [Color Picker](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/app_color_picker/app.rb)
-
-Interactive tools require complex state. Mapping mouse clicks to widgets and handling modal dialogs creates messy code if handled in the main loop.
-
-This app implements a full Color Picker using a "Scene-Orchestrated" pattern. The Scene calculates layout and exposes cached rectangles for hit testing.
-
-Use it to build forms, editors, and mouse-driven tools.
-
-**What you'll learn:**
-
-*   **Scene-Orchestrated MVC**: Separates the View (layout/rendering) from the Controller (event loop) and Model (business logic).
-*   **Hit Testing**: Caches layout rectangles during the render pass to handle mouse clicks on specific elements.
-*   **Modal Dialogs**: Implements overlay patterns that intercept input.
-
-#### [Custom Widget (Escape Hatch)](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/app_custom_widget/app.rb)
-
-Demonstrates how to define a custom widget in pure Ruby using the `render(area, buffer)` escape hatch for low-level drawing.
-
-![custom_widget](./images/app_custom_widget.png)
-
-#### [Layout Split Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/widget_layout_split/app.rb)
+### Widget Demos
 
-Demonstrates `Layout.split` with interactive attribute cycling. Features hotkey controls For direction (vertical/horizontal), all 7 flex modes (legacy, start, center, end, space_between, space_around, space_evenly), and constraint types (fill, length, percentage, min, ratio).
+Focused examples for individual widgets. Each demonstrates a single widget and its configuration options.
+
+| 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 |
+| [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 |
+| [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 |
+| [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 |
+| [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 |
+| [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 |
+| [Custom Render](../examples/widget_render/app.rb) | Low-level Draw API, escape hatch for custom widgets |
 
-![widget_layout_split](./images/widget_layout_split.png)
+### Sample Applications
 
-#### [Login Form](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/app_login_form/app.rb)
+These larger examples combine widgets into complete applications, demonstrating real-world TUI patterns and architectures.
 
-Shows how to use `Overlay`, `Center`, and `Cursor` to build a modal login form with text input.
+| 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 |
+| [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 |
 
-![login_form](./images/app_login_form.png)
+#### All Events
 
-#### [Map Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/app_map_demo/app.rb)
+[![all_events](./images/app_all_events.png)](../examples/app_all_events/README.md)
 
-Exhibits the `Canvas` widget's power, rendering a world map with city labels, animated circles, and lines.
+#### Color Picker
 
-![map_demo](./images/app_map_demo.png)
+[![color_picker](./images/app_color_picker.png)](../examples/app_color_picker/README.md)
 
-#### [Table Select](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/app_table_select/app.rb)
+#### Login Form
 
-Demonstrates interactive row selection in the `Table` widget with keyboard navigation, highlighting selected rows with custom styles and symbols, applying a base style, and dynamically adjusting `column_spacing`. Also demonstrates `column_highlight_style` and the new `cell_highlight_style` for precise selection visualization.
+[![login_form](./images/app_login_form.png)](../examples/app_login_form/README.md)
 
-![table_select](./images/app_table_select.png)
 
+## Next Steps
 
-### Widget Demos
+Now that you've seen what **ratatui_ruby** can do:
 
-These smaller, focused examples demonstrate specific widgets and their configuration options.
-
-*   [Bar Chart](../examples/widget_barchart_demo/app.rb)
-*   [Block Padding](../examples/widget_block_padding/app.rb)
-*   [Block Titles](../examples/widget_block_titles/app.rb)
-*   [Box (Block/Paragraph)](../examples/widget_box_demo/app.rb)
-*   [Calendar](../examples/widget_calendar_demo/app.rb)
-*   [Chart](../examples/widget_chart_demo/app.rb)
-*   [Gauge](../examples/widget_gauge_demo/app.rb)
-*   [Line Gauge](../examples/widget_line_gauge_demo/app.rb)
-*   [List](../examples/widget_list_demo/app.rb)
-*   [Popup (Clear)](../examples/widget_popup_demo/app.rb)
-*   [Rect](../examples/widget_rect/app.rb)
-*   [Ratatui Logo](../examples/widget_ratatui_logo_demo/app.rb)
-*   [Ratatui Mascot](../examples/widget_ratatui_mascot_demo/app.rb)
-*   [Rich Text](../examples/widget_rich_text/app.rb)
-*   [Scrollbar](../examples/widget_scrollbar_demo/app.rb)
-*   [Scroll Text](../examples/widget_scroll_text/app.rb)
-*   [Sparkline](../examples/widget_sparkline_demo/app.rb)
-*   [Table Flex](../examples/widget_table_flex/app.rb)
-*   [Tabs](../examples/widget_tabs_demo/app.rb)
-*   [Widget Style Colors](../examples/widget_style_colors/app.rb)
+- **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)
+- **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/terminal_limitations.md

@@ -0,0 +1,92 @@
+<!--
+SPDX-FileCopyrightText: 2025 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.