ratatui_ruby 0.4.0 → 0.6.0

data/doc/interactive_design.md

@@ -21,10 +21,13 @@ Structure your event loop into three clear phases:
 
 ```ruby
 def run
-  RatatuiRuby.run do
+  RatatuiRuby.run do |tui|
+    @tui = tui
     loop do
-      calculate_layout   # Phase 1: Geometry (once per frame)
-      render             # Phase 2: Draw
+      @tui.draw do |frame|
+        calculate_layout(frame.area) # Phase 1: Geometry (once per frame)
+        render(frame)                # Phase 2: Draw
+      end
       break if handle_input == :quit  # Phase 3: Input
     end
   end
@@ -33,29 +36,27 @@ end
 
 **Phase 1: Layout Calculation**
 
-Call this before rendering and event handling. It's the single source of truth for geometry:
+Call this inside your `draw` block. It uses the current terminal area provided by the frame:
 
 ```ruby
-def calculate_layout
-  full_area = RatatuiRuby::Rect.new(x: 0, y: 0, width: 80, height: 24)
-
+def calculate_layout(area)
   # Main area vs sidebar (70% / 30%)
-  main_area, @sidebar_area = RatatuiRuby::Layout.split(
-    full_area,
+  main_area, @sidebar_area = @tui.layout_split(
+    area,
     direction: :horizontal,
     constraints: [
-      RatatuiRuby::Constraint.percentage(70),
-      RatatuiRuby::Constraint.percentage(30),
+      @tui.constraint_percentage(70),
+      @tui.constraint_percentage(30),
     ]
   )
 
   # Within main area, left vs right panels
-  @left_rect, @right_rect = RatatuiRuby::Layout.split(
+  @left_rect, @right_rect = @tui.layout_split(
     main_area,
     direction: :horizontal,
     constraints: [
-      RatatuiRuby::Constraint.percentage(@left_ratio),
-      RatatuiRuby::Constraint.percentage(100 - @left_ratio)
+      @tui.constraint_percentage(@left_ratio),
+      @tui.constraint_percentage(100 - @left_ratio)
     ]
   )
 end
@@ -66,10 +67,9 @@ end
 Reuse the cached rects. Build and draw:
 
 ```ruby
-def render
-  left_panel = build_widget(@left_rect)
-  right_panel = build_widget(@right_rect)
-  # ... draw ...
+def render(frame)
+  frame.render_widget(build_widget(@left_rect), @left_rect)
+  frame.render_widget(build_widget(@right_rect), @right_rect)
 end
 ```
 
@@ -80,7 +80,6 @@ Reuse the cached rects. Test clicks:
 ```ruby
 def handle_input
   event = RatatuiRuby.poll_event
-  return unless event
 
   case event
   in type: :mouse, kind: "down", x:, y:
@@ -104,18 +103,14 @@ end
 
 ## Layout.split
 
-`Layout.split` computes layout geometry without rendering. It returns an array of `Rect` objects.
+`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.
 
 ```ruby
-rects = Layout.split(
-  area,
-  direction: :horizontal,
-  constraints: [Constraint.percentage(70), Constraint.percentage(30)]
-)
-
-left, right = rects
-# left is a Rect describing the left 70% of the area
-# right is a Rect describing the right 30% of the area
+# Preferred (Session API)
+left, right = tui.layout_split(area, constraints: [...])
+
+# Manual (Core API)
+left, right = RatatuiRuby::Layout.split(area, constraints: [...])
 ```
 
-Use it to establish the single source of truth in `calculate_layout`. Reuse the results in both render and event handling.
+Use it to establish the single source of truth inside your `draw` block. Store the results in instance variables and reuse them in both `render` and `handle_input`.

data/doc/quickstart.md

@@ -29,22 +29,22 @@ gem install ratatui_ruby
 ```
 
 
-## Basic Application
+## Tutorials
+
+### Basic Application
 
 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.
-    # Other widgets include RatatuiRuby::RatatuiMascot, RatatuiRuby::RatatuiLogo, etc.
     view = RatatuiRuby::Paragraph.new(
       text: "Hello, Ratatui! Press 'q' to quit.",
       alignment: :center,
@@ -56,38 +56,43 @@ begin
         style: { fg: "white" }
       )
     )
- 
+
     # 3. Draw the UI
-    RatatuiRuby.draw(view)
- 
+    RatatuiRuby.draw do |frame|
+      frame.render_widget(view, frame.area)
+    end
+
     # 4. Poll for events
-    event = RatatuiRuby.poll_event
-    break if event == "q" || event == :ctrl_c
+    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/quickstart_lifecycle.png)
+![quickstart_lifecycle](./images/verify_quickstart_lifecycle.png)
 
-### How it works
+#### How it works
 
 1.  **`RatatuiRuby.init_terminal`**: Enters raw mode and switches to the alternate screen.
-2.  **Immediate Mode UI**: On every iteration of the loop, you describe what the UI should look like by creating `Data` objects (like `Paragraph` and `Block`).
-3.  **`RatatuiRuby.draw(view)`**: The Ruby UI tree is passed to the Rust backend, which renders it to the terminal.
-4.  **`RatatuiRuby.poll_event`**: Checks for keyboard, mouse, or resize events.
-5.  **`RatatuiRuby.restore_terminal`**: Crucial for leaving raw mode and returning the user to their shell properly. Always wrap your loop in a `begin...ensure` block to guarantee this runs.
+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.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
 
 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.
 
-```rb
-require "ratatui_ruby"
-
-# 1. Initialize the terminal and ensure it is restored.
+<!-- SYNC:START:../examples/verify_quickstart_dsl/app.rb:main -->
+```ruby
 RatatuiRuby.run do |tui|
   loop do
     # 2. Create your UI with methods instead of classes.
@@ -104,168 +109,183 @@ RatatuiRuby.run do |tui|
     )
 
     # 3. Use RatatuiRuby methods, too.
-    tui.draw(view)
-    event = tui.poll_event
-    
-    break if event == "q" || event == :ctrl_c
+    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 -->
 
 #### 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(...)`.
+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(...)`.
+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).
 
-## Examples
-
-To see more complex layouts and widget usage, check out the `examples/` directory in the repository.
+### Adding Layouts
 
-### [Analytics](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/analytics/app.rb)
+Real-world applications often need to split the screen into multiple areas. `RatatuiRuby::Layout` lets you do this easily.
 
-Demonstrates the use of `Tabs` and `BarChart` widgets. Features custom highlight styles, base styles, dividers for the tabs, and dynamic width calculation. The `BarChart` showcases both standard and grouped bars (Quarterly view), highlighting features like `group_gap` spacing, toggling `BarChart::direction`, customizing label/value styles, cycling custom `BarChart::bar_set` characters, and switching between Full and Mini height modes.
+<!-- 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),
+      ]
+    )
 
-![analytics](./images/analytics.png)
+    # 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
+    )
 
-### [All Events](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/all_events/app.rb)
+    # 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
+    )
 
-A comprehensive demonstration of every event type supported by **ratatui_ruby**: Key, Mouse, Resize, Paste, and Focus events.
+    frame.render_widget(
+      tui.paragraph(
+        text: text_line,
+        block: tui.block(title: "Controls", borders: [:all])
+      ),
+      bottom
+    )
+  end
 
-![all_events](./images/all_events.png)
+  case tui.poll_event
+  in { type: :key, code: "q" }
+    break
+  else
+    # Ignore other events
+  end
+end
+```
+<!-- SYNC:END -->
 
-### [Block Padding](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/block_padding/app.rb)
+#### How it works
 
-Demonstrates the `padding` property of the `Block` widget, supporting both uniform and directional padding.
+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`).
+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.
 
-![block_padding](./images/block_padding.png)
+## Examples
 
-### [Block Titles](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/block_titles/app.rb)
+These examples showcase the full power of **ratatui_ruby**. You can find their source code in the [examples directory](../examples).
 
-Demonstrates the `Block` widget's ability to render multiple titles with individual alignment and positioning (top/bottom).
+### Sample Applications
 
-![block_titles](./images/block_titles.png)
+Full-featured examples demonstrating complex layouts and real-world TUI patterns.
 
-### [Box Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/box_demo/app.rb)
 
-A simple demonstration of `Block` and `Paragraph` widgets, reacting to key presses to change colors, border types, border styles, and title styling. Features the new `border_style` parameter for applying colors and modifiers (bold, italic) to borders independently of the content background.
 
-![box_demo](./images/box_demo.png)
+#### [All Events](../examples/app_all_events/app.rb)
 
-### [Calendar Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/calendar_demo/app.rb)
+Handling terminal events is unpredictable. Developers need to know exactly what the terminal sends for `Ctrl+C` or a mouse drag.
 
-Demonstrates the `Calendar` widget with interactive attribute cycling. Features event highlighting (dates with specific styles), toggleable month/weekday headers, and surrounding month visibility (with custom styling) via keyboard shortcuts. Press `h` to toggle month header, `w` to toggle weekday header, `s` to toggle surrounding month dates, and `e` to toggle events.
+This app captures and visualizes every event—keys, mouse, resize, paste, and focus.
 
-![calendar_demo](./images/calendar_demo.png)
+Use it to debug your input handling or verify terminal behavior.
 
-### [Chart Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/chart_demo/app.rb)
+**What you'll learn:**
 
-Demonstrates the `Chart` widget with both scatter and line datasets, including custom axes. Features customizable axis label alignment and legend positioning.
+*   **Proto-TEA Architecture**: Implements unidirectional data flow (Model-View-Update) with immutable state and pure functions.
+*   **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.
 
-![chart_demo](./images/chart_demo.png)
+![all_events](./images/app_all_events.png)
 
-### [Custom Widget (Escape Hatch)](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/custom_widget/app.rb)
+#### [Color Picker](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/app_color_picker/app.rb)
 
-Demonstrates how to define a custom widget in pure Ruby using the `render(area, buffer)` escape hatch for low-level drawing.
+Interactive tools require complex state. Mapping mouse clicks to widgets and handling modal dialogs creates messy code if handled in the main loop.
 
-![custom_widget](./images/custom_widget.png)
+This app implements a full Color Picker using a "Proto-Kit (Component-Based)" pattern. Each component encapsulates its own rendering, state, and event handling.
 
-### [Flex Layout](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/flex_layout/app.rb)
+Use it to build forms, editors, and mouse-driven tools.
 
-Demonstrates modern layout features including `Constraint.fill` and `Constraint.ratio` for proportional space distribution and `flex: :space_between` for evenly distributing fixed-size elements.
+**What you'll learn:**
 
-![flex_layout](./images/flex_layout.png)
+*   **Proto-Kit Architecture**: Self-contained components with `render(tui, frame, area)` and `handle_event(event)`.
+*   **Encapsulated Hit Testing**: Components cache their render area and check `contains?` internally.
+*   **Modal Dialogs**: Implements overlay patterns that intercept input via Chain of Responsibility.
 
-### [LineGauge Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/line_gauge_demo/app.rb)
+#### [Custom Widget (Escape Hatch)](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/app_custom_widget/app.rb)
 
-Demonstrates the `LineGauge` widget with customizable filled and unfilled symbols, base style support via the `style` parameter, independent styling for filled/unfilled portions, and interactive ratio cycling with arrow keys.
+Demonstrates how to define a custom widget in pure Ruby using the `render(area, buffer)` escape hatch for low-level drawing.
 
-![line_gauge_demo](./images/line_gauge_demo.png)
+![custom_widget](./images/app_custom_widget.png)
 
-### [List Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/list_demo/app.rb)
+#### [Layout Split Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/widget_layout_split/app.rb)
 
-Demonstrates the `List` widget with interactive attribute cycling. Features multiple item sets to browse, customizable highlight styles and symbols, and exploration of all List options including direction, highlight spacing, repeat symbol mode, scroll padding, and base styling. The sidebar provides hotkey documentation for discovering all List features, including the new `p` key to adjust scroll padding.
+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).
 
-![list_demo](./images/list_demo.png)
+![widget_layout_split](./images/widget_layout_split.png)
 
-### [Login Form](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/login_form/app.rb)
+#### [Login Form](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/app_login_form/app.rb)
 
 Shows how to use `Overlay`, `Center`, and `Cursor` to build a modal login form with text input.
 
-![login_form](./images/login_form.png)
-
-### [Map Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/map_demo/app.rb)
-
-Exhibits the `Canvas` widget's power, rendering a world map with city labels, animated circles, and lines.
-
-![map_demo](./images/map_demo.png)
-
-### [Mouse Events](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/mouse_events/app.rb)
-
-Detailed plumbing of mouse events, including clicks, drags, and movement tracking.
-
-![mouse_events](./images/mouse_events.png)
-
-### [Popup Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/popup_demo/app.rb)
-
-Demonstrates the `Clear` widget and how to prevent "style bleed" when rendering opaque popups over colored backgrounds.
-
-![popup_demo](./images/popup_demo.png)
-
-### [Ratatui Logo Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/ratatui_logo_demo/app.rb)
-
-Demonstrates the `RatatuiLogo` widget.
-
-
-![ratatui_logo_demo](./images/ratatui_logo_demo.png)
-
-### [Rich Text](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/rich_text/app.rb)
-
-Demonstrates `Text::Span` and `Text::Line` for creating styled text with inline formatting, enabling word-level control over colors and text modifiers.
-
-![rich_text](./images/rich_text.png)
-
-### [Scrollbar Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/scrollbar_demo/app.rb)
-
-A demonstration of the `Scrollbar` widget, featuring mouse wheel scrolling and extensive customization of symbols and styles.
-
-![scrollbar_demo](./images/scrollbar_demo.png)
-
-### [Scroll Text](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/scroll_text/app.rb)
-
-Demonstrates the `Paragraph` widget's scroll functionality, allowing navigation through long text content using arrow keys for both horizontal and vertical scrolling.
-
-![scroll_text](./images/scroll_text.png)
-
-### [Sparkline Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/sparkline_demo/app.rb)
-
-Demonstrates the `Sparkline` widget with interactive attribute cycling. Features multiple data sets with different patterns (steady growth, gaps, random, sawtooth, peaks), and explores all `Sparkline` options including direction, color, the new `absent_value_symbol` and `absent_value_style` parameters for distinguishing zero/absent values from low data, and the new `bar_set` parameter for custom bar characters.
-
-![sparkline_demo](./images/sparkline_demo.png)
-
-### [Gauge Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/gauge_demo/app.rb)
-
-Demonstrates the `Gauge` widget with interactive attribute cycling. Features multiple gauge instances with customizable ratio, gauge color, background style, Unicode toggle, and label modes. The sidebar provides hotkey documentation for exploring all Gauge options, including the distinction between `style` (background) and `gauge_style` (filled bar).
-
-![gauge_demo](./images/gauge_demo.png)
-
-### [Table Select](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/table_select/app.rb)
-
-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)
 
-![table_select](./images/table_select.png)
 
-### [Table Flex](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/table_flex/app.rb)
 
-Demonstrates different flex modes in the `Table` widget, such as `:space_between` and `:space_around`, allowing for modern, responsive table layouts.
 
-![table_flex](./images/table_flex.png)
 
-### [Widget Style Colors](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/widget_style_colors/app.rb)
 
-Demonstrates hexadecimal color code support in Style parameters. Renders an 80x24 color gradient using HSL-to-RGB conversion and #RRGGBB hex codes, showcasing 24-bit true color rendering on capable terminals.
+### Widget Demos
 
-![widget_style_colors](./images/widget_style_colors.png)
+These smaller, focused examples demonstrate specific widgets and their configuration options.
 
+*   [Bar Chart](../examples/widget_barchart_demo/app.rb)
+*   [Block (Interactive Demo)](../examples/widget_block_demo/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)
+*   [Map (Canvas)](../examples/widget_map_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 (Selection)](../examples/widget_table_demo/app.rb)
+*   [Tabs](../examples/widget_tabs_demo/app.rb)
+*   [Widget Style Colors](../examples/widget_style_colors/app.rb)

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.