anima-core 0.2.1 → 1.0.0

data/skills/ratatui-ruby/references/core-concepts.md

@@ -0,0 +1,340 @@
+# Core Concepts
+
+RatatuiRuby provides immediate-mode terminal rendering with managed lifecycle. This reference covers application initialization, terminal lifecycle, viewport modes, and core objects.
+
+## RatatuiRuby.run
+
+Entry point handling complete terminal lifecycle with exception safety.
+
+```ruby
+RatatuiRuby.run do |tui|
+  loop do
+    tui.draw do |frame|
+      frame.render_widget(tui.paragraph(text: "Hello"), frame.area)
+    end
+
+    case tui.poll_event
+    in {type: :key, code: "q"}
+      break
+    end
+  end
+end
+# Terminal restored automatically
+```
+
+### Options
+
+| Option | Default | Purpose |
+|--------|---------|---------|
+| `focus_events` | `true` | Enable focus change events |
+| `bracketed_paste` | `true` | Enable bracketed paste mode |
+| `viewport` | `nil` | Viewport mode (`nil`/`:fullscreen` or `:inline`) |
+| `height` | `nil` | Lines for inline viewport (required when `viewport: :inline`) |
+
+```ruby
+RatatuiRuby.run(viewport: :inline, height: 8) do |tui|
+  # 8-line inline viewport
+end
+```
+
+### Manual Lifecycle (Advanced)
+
+For fine-grained control, use `init_terminal` and `restore_terminal` with `ensure`:
+
+```ruby
+RatatuiRuby.init_terminal
+begin
+  RatatuiRuby.draw do |frame|
+    frame.render_widget(widget, frame.area)
+  end
+ensure
+  RatatuiRuby.restore_terminal  # Always executes
+end
+```
+
+## Terminal Lifecycle
+
+Three-phase lifecycle prevents terminal corruption.
+
+### Phase 1: Setup (`init_terminal`)
+
+- Enters alternate screen (fullscreen) or creates fixed region (inline)
+- Enables raw mode for direct key capture
+- Configures focus events and bracketed paste
+- Sets `@tui_session_active = true`
+
+### Phase 2: Loop
+
+Application code executes with access to TUI instance:
+- `draw` renders UI
+- `poll_event` captures input
+- Application logic manages state
+
+### Phase 3: Teardown (`restore_terminal`)
+
+Guaranteed cleanup via `ensure` block:
+- Leaves alternate screen
+- Disables raw mode
+- Flushes warnings
+- Sets `@tui_session_active = false`
+
+### Signal Handling
+
+- Most signals (SIGTERM, SIGINT) trigger stack unwinding, allowing `ensure` execution
+- **SIGKILL cannot be caught** - may leave terminal in raw mode
+- **Ctrl+C in raw mode** captured as key event, not SIGINT - handle explicitly:
+
+```ruby
+case tui.poll_event
+in {type: :key, code: "c", modifiers: ["ctrl"]}
+  break
+end
+```
+
+## Viewport Modes
+
+### Fullscreen (Default)
+
+Takes over entire terminal, clears on exit.
+
+```ruby
+RatatuiRuby.run do |tui|
+  # Fullscreen is default
+end
+
+# Or explicitly:
+RatatuiRuby.run(viewport: :fullscreen) do |tui|
+  # ...
+end
+```
+
+**Characteristics:**
+- Alternate screen buffer for isolated rendering
+- All content cleared on exit
+- No scrollback preservation
+- Full terminal dimensions via `frame.area`
+- Best for complete TUI applications
+
+### Inline Mode
+
+Fixed-height region preserving scrollback after exit.
+
+```ruby
+RatatuiRuby.run(viewport: :inline, height: 8) do |tui|
+  # 8-line region
+end
+```
+
+**Characteristics:**
+- Fixed height (required parameter)
+- Content persists in scrollback
+- Supports `insert_before` for logging above viewport
+- Best for status displays, progress indicators, inline widgets
+
+**Logging during inline mode:**
+
+```ruby
+# Option 1: Pass widget directly
+RatatuiRuby.insert_before(height, widget)
+
+# Option 2: Use block to generate widget (block returns widget, doesn't receive frame)
+RatatuiRuby.insert_before(height) do
+  tui.paragraph(text: "Log message")  # Block returns a widget
+end
+```
+
+## Frame Object
+
+Controlled access to terminal buffer during rendering. Valid only within `draw` block.
+
+### Methods
+
+#### `area()`
+
+Returns `Rect` of entire drawable region:
+
+```ruby
+tui.draw do |frame|
+  puts "Size: #{frame.area.width}x#{frame.area.height}"
+end
+```
+
+#### `render_widget(widget, area)`
+
+Renders stateless widget at specified area:
+
+```ruby
+tui.draw do |frame|
+  para = tui.paragraph(text: "Content")
+  frame.render_widget(para, frame.area)
+end
+```
+
+#### `render_stateful_widget(widget, area, state)`
+
+Renders widget with persistent state (scroll position, selection):
+
+```ruby
+@list_state = tui.list_state
+
+tui.draw do |frame|
+  list = tui.list(items: ["A", "B", "C"])
+  frame.render_stateful_widget(list, frame.area, @list_state)
+end
+
+# State reflects current selection/offset
+puts "Selected: #{@list_state.selected}"
+```
+
+State object is single source of truth, overriding widget configuration.
+
+#### `set_cursor_position(x, y)`
+
+Positions cursor at zero-indexed coordinates:
+
+```ruby
+tui.draw do |frame|
+  frame.render_widget(tui.paragraph(text: "Name: [alice]"), frame.area)
+  frame.set_cursor_position(7, 0)  # After "Name: ["
+end
+```
+
+### Thread Safety
+
+Frame is not Ractor-shareable. Valid only during draw block execution.
+
+### Layout Reuse Pattern
+
+Store layout results for hit testing:
+
+```ruby
+tui.draw do |frame|
+  sidebar, main = tui.layout_split(frame.area, ...)
+  frame.render_widget(sidebar_widget, sidebar)
+  frame.render_widget(main_widget, main)
+  @regions = {sidebar:, main:}  # Reuse for click detection
+end
+```
+
+## TUI Factory Object
+
+Manages lifecycle and provides concise factory methods.
+
+### Access
+
+```ruby
+RatatuiRuby.run do |tui|
+  # tui is RatatuiRuby::TUI instance
+end
+```
+
+### Factory Comparison
+
+```ruby
+# Without factories (verbose):
+para = RatatuiRuby::Widgets::Paragraph.new(
+  text: "Hello",
+  block: RatatuiRuby::Widgets::Block.new(borders: [:all])
+)
+
+# With factories (concise):
+para = tui.paragraph(text: "Hello", block: tui.block(borders: [:all]))
+```
+
+### Factory Modules
+
+| Module | Methods | Purpose |
+|--------|---------|---------|
+| **WidgetFactories** | `paragraph`, `block`, `list`, `table`, `gauge` | UI components |
+| **LayoutFactories** | `rect`, `constraint_*`, `layout`, `layout_split` | Layouts |
+| **StyleFactories** | `style` | Formatting |
+| **TextFactories** | `text_span`, `text_line`, `text_width` | Styled text |
+| **StateFactories** | `list_state`, `table_state`, `scrollbar_state` | Widget state |
+| **CanvasFactories** | `shape_map`, `shape_line`, `shape_point` | Canvas shapes |
+| **BufferFactories** | `cell` | Testing |
+| **Core** | `draw`, `poll_event`, `get_cell_at` | Terminal ops |
+
+### DWIM Coercion
+
+Factories implement "Do What I Mean" argument coercion with automatic type normalization and validation.
+
+## Module Functions
+
+### Drawing
+
+```ruby
+# Declarative (tree-based)
+RatatuiRuby.draw(widget)
+
+# Imperative (block-based)
+RatatuiRuby.draw do |frame|
+  frame.render_widget(widget, frame.area)
+end
+```
+
+### Event Polling
+
+```ruby
+event = RatatuiRuby.poll_event                # ~60 FPS default (16ms)
+event = RatatuiRuby.poll_event(timeout: nil)  # Block until event
+event = RatatuiRuby.poll_event(timeout: 0.0)  # Non-blocking
+```
+
+### Terminal Inspection
+
+| Method | Returns |
+|--------|---------|
+| `get_terminal_size()` | Full terminal dimensions as `Rect` |
+| `get_terminal_area()` | Alias for `get_terminal_size` |
+| `get_viewport_area()` | Current viewport area |
+| `get_viewport_size()` | Alias for `get_viewport_area` |
+| `get_cell_at(x, y)` | `Buffer::Cell` at coordinates (for testing) |
+
+## Complete Example
+
+```ruby
+RatatuiRuby.run do |tui|
+  @list_state = tui.list_state(0)
+  items = ["Dashboard", "Settings", "Help", "Quit"]
+
+  loop do
+    tui.draw do |frame|
+      sidebar, content = tui.layout_split(
+        frame.area,
+        direction: :horizontal,
+        constraints: [tui.constraint_length(20), tui.constraint_min(0)]
+      )
+
+      # Sidebar with stateful list
+      list = tui.list(
+        items:,
+        block: tui.block(title: "Menu", borders: [:all])
+      )
+      frame.render_stateful_widget(list, sidebar, @list_state)
+
+      # Content area
+      selected_item = items[@list_state.selected] || "None"
+      frame.render_widget(
+        tui.paragraph(
+          text: "Selected: #{selected_item}",
+          block: tui.block(title: "Content", borders: [:all])
+        ),
+        content
+      )
+    end
+
+    case tui.poll_event
+    in {type: :key, code: "q"}
+      break
+    in {type: :key, code: "j"} | {type: :key, code: "down"}
+      @list_state.select_next
+    in {type: :key, code: "k"} | {type: :key, code: "up"}
+      @list_state.select_previous
+    in {type: :key, code: "c", modifiers: ["ctrl"]}
+      break
+    else
+      # Continue
+    end
+  end
+end
+```

data/skills/ratatui-ruby/references/events.md

@@ -0,0 +1,387 @@
+# Event Handling
+
+RatatuiRuby provides a robust event system for keyboard, mouse, resize, paste, and focus events. This reference covers polling, event types, and handling patterns.
+
+## poll_event
+
+Primary method for retrieving user input:
+
+```ruby
+event = RatatuiRuby.poll_event(timeout: 0.016)
+```
+
+### Timeout Options
+
+| Value | Behavior |
+|-------|----------|
+| `0.016` (default) | ~60 FPS, smooth rendering loops |
+| `nil` | Block until event arrives |
+| `0.0` | Non-blocking, return immediately |
+| Positive float | Wait specified duration |
+
+### Return Types
+
+- `Event::Key` — Keyboard input
+- `Event::Mouse` — Mouse interactions
+- `Event::Resize` — Terminal dimension changes
+- `Event::Paste` — Clipboard content
+- `Event::FocusGained` — Terminal received focus
+- `Event::FocusLost` — Terminal lost focus
+- `Event::None` — No event (Null Object pattern)
+
+## Event Base Class
+
+Type-checking predicates:
+
+```ruby
+event.key?           # Keyboard event
+event.mouse?         # Mouse activity
+event.resize?        # Terminal resize
+event.paste?         # Clipboard paste
+event.focus_gained?  # Focus acquisition
+event.focus_lost?    # Focus loss
+event.none?          # No event
+```
+
+## Key Events
+
+### Attributes
+
+```ruby
+event.code       # Key identifier: "a", "enter", "up", "f1"
+event.modifiers  # Active modifiers: ["ctrl"], ["alt", "shift"]
+event.kind       # Category: :standard, :function, :media, :modifier, :system
+```
+
+### Comparison Methods
+
+```ruby
+# Symbol comparison
+event == :ctrl_c
+event == :shift_up
+event == :q
+
+# String comparison
+event == "c"
+event == "enter"
+
+# Object comparison
+event == Event::Key.new(code: "c", modifiers: ["ctrl"])
+```
+
+### Helper Predicates
+
+Dynamic methods via `method_missing`:
+
+```ruby
+event.ctrl_c?      # Ctrl+C
+event.enter?       # Enter key
+event.shift_up?    # Shift+Up
+event.q?           # "q" key
+event.esc?         # Escape
+event.space?       # Space bar
+event.tab?         # Tab key
+```
+
+DWIM (Do What I Mean) shortcuts:
+
+```ruby
+event.pause?       # Matches "pause" and "media_pause"
+event.play?        # Matches "media_play"
+```
+
+### Character Detection
+
+```ruby
+event.text?        # True for printable characters
+event.char         # Character or nil for special keys
+event.to_s         # Character or empty string
+```
+
+### Key Categories
+
+**Navigation:**
+- `up`, `down`, `left`, `right`
+- `home`, `end`, `page_up`, `page_down`
+- `insert`, `delete`
+
+**System:**
+- `print_screen`, `pause`, `menu`
+
+**Media:**
+- `play`, `media_pause`, `play_pause`, `stop`
+- `track_next`, `track_previous`
+- `mute_volume`, `lower_volume`, `raise_volume`
+
+**Modifiers:**
+- `left_shift`, `right_shift`
+- `left_control`, `right_control`
+- `left_alt`, `right_alt`
+
+### Pattern Matching
+
+```ruby
+case event
+in type: :key, code: "c", modifiers: ["ctrl"]
+  break
+in type: :key, code: "q"
+  break
+in type: :key, kind: :media
+  handle_media_key
+in type: :key, code: "j"
+  move_down
+in type: :key, code: "k"
+  move_up
+end
+```
+
+## Mouse Events
+
+### Attributes
+
+```ruby
+event.kind       # "down", "up", "drag", "moved", "scroll_up", "scroll_down"
+event.button     # "left", "right", "middle", "none", nil
+event.x          # Column coordinate (zero-indexed)
+event.y          # Row coordinate (zero-indexed)
+event.modifiers  # Active keyboard modifiers
+```
+
+### Event Type Methods
+
+```ruby
+event.down?        # Button pressed
+event.up?          # Button released
+event.drag?        # Dragging
+event.scroll_up?   # Scroll up
+event.scroll_down? # Scroll down
+```
+
+### Usage
+
+```ruby
+if event.mouse? && event.down? && event.button == "left"
+  handle_click(event.x, event.y)
+end
+```
+
+### Pattern Matching
+
+```ruby
+case event
+in type: :mouse, kind: "down", button: "left", x:, y:
+  handle_click(x, y)
+in type: :mouse, kind: "drag", x:, y:
+  handle_drag(x, y)
+in type: :mouse, kind: "scroll_up"
+  scroll_up
+in type: :mouse, kind: "scroll_down"
+  scroll_down
+end
+```
+
+## Resize Events
+
+### Attributes
+
+```ruby
+event.width      # New terminal width in columns
+event.height     # New terminal height in rows
+```
+
+### Usage
+
+```ruby
+if event.resize?
+  recalculate_layout(event.width, event.height)
+end
+```
+
+### Pattern Matching
+
+```ruby
+case event
+in type: :resize, width:, height:
+  update_dimensions(width, height)
+end
+```
+
+## Paste Events
+
+Handles pasted text as atomic action (prevents rapid keystroke flood).
+
+### Attributes
+
+```ruby
+event.content    # Pasted text string
+```
+
+### Usage
+
+```ruby
+if event.paste?
+  insert_text(event.content)
+end
+```
+
+### Pattern Matching
+
+```ruby
+case event
+in type: :paste, content:
+  process_pasted_content(content)
+end
+```
+
+## Focus Events
+
+Track terminal window focus state. **Limited terminal support** (iTerm2, Kitty, newer xterm).
+
+### FocusGained
+
+```ruby
+if event.focus_gained?
+  resume_animations
+  refresh_data
+end
+```
+
+### FocusLost
+
+```ruby
+if event.focus_lost?
+  pause_animations
+  reduce_polling_frequency
+end
+```
+
+### Pattern Matching
+
+```ruby
+case event
+in type: :focus_gained
+  restore_foreground_mode
+in type: :focus_lost
+  enter_background_mode
+end
+```
+
+## None Events (Null Object)
+
+Returns when no input available. Eliminates nil-checks:
+
+```ruby
+if event.none?
+  # Timeout expired, continue rendering
+  update_clock_display
+end
+
+# Safe to call predicates (all return false)
+event.ctrl_c?  # => false
+event.key?     # => false
+```
+
+## Complete Event Loop
+
+```ruby
+RatatuiRuby.run do |tui|
+  loop do
+    tui.draw { |frame| render_view(model, frame) }
+
+    case tui.poll_event
+  # Exit conditions
+  in {type: :key, code: "q"} | {type: :key, code: "c", modifiers: ["ctrl"]}
+    break
+
+  # Navigation
+  in type: :key, code: "up" | "k"
+    model = move_up(model)
+  in type: :key, code: "down" | "j"
+    model = move_down(model)
+  in type: :key, code: "enter"
+    model = activate(model)
+
+  # Mouse
+  in type: :mouse, kind: "down", button: "left", x:, y:
+    model = handle_click(model, x, y)
+  in type: :mouse, kind: "scroll_up"
+    model = scroll_up(model)
+  in type: :mouse, kind: "scroll_down"
+    model = scroll_down(model)
+
+  # Terminal
+  in type: :resize, width:, height:
+    model = update_layout(model, width, height)
+  in type: :paste, content:
+    model = insert_text(model, content)
+
+  # Focus
+  in type: :focus_lost
+    model = enter_background(model)
+  in type: :focus_gained
+    model = resume_foreground(model)
+
+  else
+    # Catch unmatched events (required to prevent NoMatchingPatternError)
+    nil
+  end
+  end
+end
+```
+
+## Event Handling Patterns
+
+### Helper Method Approach
+
+```ruby
+event = tui.poll_event
+break if event.ctrl_c?
+@list_state.select_next if event.down? || event.j?
+@list_state.select_previous if event.up? || event.k?
+```
+
+### Predicate Chain
+
+```ruby
+event = tui.poll_event
+case
+when event.ctrl_c? then break
+when event.enter? then activate_selection
+when event.up?, event.k? then move_up
+when event.down?, event.j? then move_down
+end
+```
+
+### Mixed Pattern Matching
+
+```ruby
+case tui.poll_event
+in Event::Key if _1.ctrl_c?
+  break
+in Event::Key => e if e.text?
+  insert_character(e.char)
+in Event::Mouse => e if e.down?
+  handle_click(e.x, e.y)
+end
+```
+
+## Terminal Compatibility Notes
+
+Some key combinations intercepted by terminal emulators:
+- Ctrl+PageUp/PageDown (tab switching)
+- Ctrl+Tab
+- Cmd+key (macOS)
+
+For broader key support, use Kitty, WezTerm, or Alacritty with enhanced key protocols.
+
+## Quick Reference
+
+| Event Type | Key Attributes | Common Predicates |
+|------------|----------------|-------------------|
+| Key | `code`, `modifiers`, `kind` | `ctrl_c?`, `enter?`, `up?`, `down?`, `text?` |
+| Mouse | `kind`, `button`, `x`, `y`, `modifiers` | `down?`, `up?`, `drag?`, `scroll_up?` |
+| Resize | `width`, `height` | `resize?` |
+| Paste | `content` | `paste?` |
+| FocusGained | — | `focus_gained?` |
+| FocusLost | — | `focus_lost?` |
+| None | — | `none?` |