### Install Dependencies

Source: https://github.com/marcoroth/bubbletea-ruby/blob/main/README.md

Installs the necessary Ruby dependencies for the project using Bundler.

```bash
bundle install
```

--------------------------------

### Install Bubbletea Gem

Source: https://github.com/marcoroth/bubbletea-ruby/blob/main/README.md

Install the Bubbletea gem directly using the gem command.

```bash
gem install bubbletea
```

--------------------------------

### Basic Counter Example

Source: https://github.com/marcoroth/bubbletea-ruby/blob/main/README.md

A fundamental Bubbletea application demonstrating the Elm Architecture with a simple counter. Requires the Bubbletea gem and implements init, update, and view methods.

```ruby
require "bubbletea"

class Counter
  include Bubbletea::Model

  def initialize
    @count = 0
  end

  def init
    [self, nil]
  end

  def update(message)
    case message
    when Bubbletea::KeyMessage
      case message.to_s
      when "q", "ctrl+c"
        [self, Bubbletea.quit]
      when "up", "k"
        @count += 1
        [self, nil]
      when "down", "j"
        @count -= 1
        [self, nil]
      else
        [self, nil]
      end
    else
      [self, nil]
    end
  end

  def view
    "Count: #{@count}\n\nPress up/down to change, q to quit"
  end
end

Bubbletea.run(Counter.new)
```

--------------------------------

### Bubbletea Counter Example

Source: https://context7.com/marcoroth/bubbletea-ruby/llms.txt

Implements the Bubbletea::Model interface to create a simple counter application. Handles key presses for incrementing, decrementing, resetting, and quitting. Requires 'bubbletea' gem.

```ruby
require "bubbletea"

class Counter
  include Bubbletea::Model

  attr_reader :count

  def initialize
    @count = 0
  end

  # init returns [model, command] - initial state and optional startup command
  def init
    [self, nil]
  end

  # update receives messages and returns [model, command]
  def update(message)
    case message
    when Bubbletea::KeyMessage
      case message.to_s
      when "q", "ctrl+c"
        [self, Bubbletea.quit]
      when "up", "k"
        @count += 1
        [self, nil]
      when "down", "j"
        @count -= 1
        [self, nil]
      when "r"
        @count = 0
        [self, nil]
      else
        [self, nil]
      end
    else
      [self, nil]
    end
  end

  # view returns a string to render
  def view
    lines = []
    lines << ""
    lines << "  Bubbletea Counter Example"
    lines << "  ========================="
    lines << ""
    lines << "  Count: #{@count}"
    lines << ""
    lines << "  Controls:"
    lines << "    up/k   Increment"
    lines << "    down/j Decrement"
    lines << "    r      Reset"
    lines << "    q      Quit"
    lines << ""
    lines.join("\n")
  end
end

Bubbletea.run(Counter.new)
```

--------------------------------

### Bubbletea Application Entry Point with Options

Source: https://context7.com/marcoroth/bubbletea-ruby/llms.txt

Demonstrates running a Bubbletea application with various configuration options for terminal features. Includes window size tracking and quitting on 'q'. Requires 'bubbletea' gem.

```ruby
require "bubbletea"

class MyApp
  include Bubbletea::Model

  def initialize
    @width = 0
    @height = 0
  end

  def init
    [self, nil]
  end

  def update(message)
    case message
    when Bubbletea::WindowSizeMessage
      @width = message.width
      @height = message.height
      [self, nil]
    when Bubbletea::KeyMessage
      return [self, Bubbletea.quit] if message.to_s == "q"
      [self, nil]
    else
      [self, nil]
    end
  end

  def view
    "Terminal: #{@width}x#{@height}\nPress q to quit"
  end
end

# Run with options
Bubbletea.run(MyApp.new,
  alt_screen: true,          # Use alternate screen buffer (fullscreen mode)
  mouse_all_motion: true,    # Track all mouse movements
  mouse_cell_motion: false,  # Track mouse clicks only
  bracketed_paste: true,     # Enable bracketed paste mode
  report_focus: true,        # Report terminal focus/blur events
  fps: 60                    # Target frames per second
)
```

--------------------------------

### Run Bubbletea with Options

Source: https://github.com/marcoroth/bubbletea-ruby/blob/main/README.md

Shows how to launch a Bubbletea application with various configuration options, such as enabling the alternate screen, mouse tracking, and focus reporting.

```ruby
Bubbletea.run(MyModel.new,
  alt_screen: true,
  mouse_all_motion: true,
  report_focus: true
)
```

--------------------------------

### Build Go Library and Compile Extension

Source: https://github.com/marcoroth/bubbletea-ruby/blob/main/README.md

Compiles the Go library and the Ruby extension for the Bubbletea gem.

```bash
bundle exec rake compile
```

--------------------------------

### Run Demos

Source: https://github.com/marcoroth/bubbletea-ruby/blob/main/README.md

Executes various demo applications included with the Bubbletea gem.

```bash
demo/counter
```

```bash
demo/spinner
```

```bash
demo/test_runner
```

--------------------------------

### Styling with Lipgloss in Bubbletea

Source: https://github.com/marcoroth/bubbletea-ruby/blob/main/README.md

Demonstrates how to use Lipgloss for styling text elements within a Bubbletea application. Requires both bubbletea and lipgloss gems.

```ruby
require "bubbletea"
require "lipgloss"

class StyledApp
  include Bubbletea::Model

  def initialize
    @title_style = Lipgloss::Style.new
      .bold(true)
      .foreground("212")

    @help_style = Lipgloss::Style.new
      .foreground("241")
  end

  def view
    lines = []
    lines << @title_style.render("My App")
    lines << ""
    lines << @help_style.render("Press q to quit")
    lines.join("\n")
  end
end
```

--------------------------------

### Compose Commands with Bubbletea.batch and Bubbletea.sequence

Source: https://context7.com/marcoroth/bubbletea-ruby/llms.txt

Illustrates `Bubbletea.batch` for concurrent command execution and `Bubbletea.sequence` for ordered execution. Useful for combining operations like screen mode changes with message scheduling.

```ruby
require "bubbletea"

class StartupMessage < Bubbletea::Message
end

class TickMessage < Bubbletea::Message
end

class BatchDemo
  include Bubbletea::Model

  def initialize
    @started = false
    @ticks = 0
  end

  def init
    # Use batch to run multiple commands concurrently
    [self, Bubbletea.batch(
      Bubbletea.send_message(StartupMessage.new),
      schedule_tick
    )]
  end

  def update(message)
    case message
    when StartupMessage
      @started = true
      [self, nil]

    when TickMessage
      @ticks += 1
      [self, schedule_tick]

    when Bubbletea::KeyMessage
      case message.to_s
      when "q"
        [self, Bubbletea.quit]
      when "a"
        # Use sequence to run commands in order
        [self, Bubbletea.sequence(
          Bubbletea.enter_alt_screen,
          Bubbletea.set_window_title("Alt Screen Mode")
        )]
      when "n"
        [self, Bubbletea.sequence(
          Bubbletea.exit_alt_screen,
          Bubbletea.set_window_title("Normal Mode")
        )]
      else
        [self, nil]
      end

    else
      [self, nil]
    end
  end

  def view
    "Started: #{@started}\nTicks: #{@ticks}\n\n a: alt screen  n: normal  q: quit"
  end

  private

  def schedule_tick
    Bubbletea.tick(1.0) { TickMessage.new }
  end
end

Bubbletea.run(BatchDemo.new)
```

--------------------------------

### Run Tests

Source: https://github.com/marcoroth/bubbletea-ruby/blob/main/README.md

Executes the test suite for the Bubbletea Ruby gem.

```bash
bundle exec rake test
```

--------------------------------

### Handle Key Messages in Update

Source: https://github.com/marcoroth/bubbletea-ruby/blob/main/README.md

Illustrates how to handle various key press messages within the update method of a Bubbletea model. Supports quitting, navigation, and other common key actions.

```ruby
def update(message)
  case message
  when Bubbletea::KeyMessage
    case message.to_s
    when "q", "ctrl+c", "esc"
      [self, Bubbletea.quit]
    when "up", "k"
      # handle up
    when "down", "j"
      # handle down
    when "enter"
      # handle enter
    end
  end
end
```

--------------------------------

### Interactive List Selection with Bubbletea

Source: https://context7.com/marcoroth/bubbletea-ruby/llms.txt

Demonstrates cursor movement, multi-select, and displaying results in a terminal list selection menu. Requires the Bubbletea gem.

```ruby
require "bubbletea"

class ListModel
  include Bubbletea::Model

  CHOICES = [
    "Buy carrots",
    "Buy celery",
    "Buy kohlrabi",
    "Buy artichokes",
    "Buy spinach",
  ].freeze

  def initialize
    @cursor = 0
    @selected = {}
    @quitting = false
  end

  def init
    [self, nil]
  end

  def update(message)
    case message
    when Bubbletea::KeyMessage
      case message.to_s
      when "q", "ctrl+c"
        @quitting = true
        [self, Bubbletea.quit]
      when "up", "k"
        @cursor = (@cursor - 1) % CHOICES.length
        [self, nil]
      when "down", "j"
        @cursor = (@cursor + 1) % CHOICES.length
        [self, nil]
      when " ", "space", "enter"
        # Toggle selection
        if @selected[@cursor]
          @selected.delete(@cursor)
        else
          @selected[@cursor] = true
        end
        [self, nil]
      else
        [self, nil]
      end
    else
      [self, nil]
    end
  end

  def view
    return final_view if @quitting

    lines = []
    lines << ""
    lines << "  What should we buy at the market?"
    lines << ""

    CHOICES.each_with_index do |choice, i|
      cursor = i == @cursor ? ">" : " "
      checked = @selected[i] ? "[x]" : "[ ]"
      lines << "  #{cursor} #{checked} #{choice}"
    end

    lines << ""
    lines << "  Press space to select, q to quit."
    lines << ""
    lines.join("\n")
  end

  private

  def final_view
    selected_items = @selected.keys.map { |i| CHOICES[i] }

    lines = []
    lines << ""
    if selected_items.empty?
      lines << "  You didn't select anything!"
    else
      lines << "  Shopping list:"
      selected_items.each { |item| lines << "    - #{item}" }
    end
    lines << ""
    lines.join("\n")
  end
end

Bubbletea.run(ListModel.new)
```

--------------------------------

### Handle Terminal Resize Events with Bubbletea::WindowSizeMessage

Source: https://context7.com/marcoroth/bubbletea-ruby/llms.txt

Respond to terminal window resize events using `WindowSizeMessage`, which provides the new `width` and `height` of the terminal. This message is also sent on application startup to provide initial dimensions. Press 'q' to quit.

```ruby
require "bubbletea"

class ResizeDemo
  include Bubbletea::Model

  def initialize
    @width = 0
    @height = 0
    @resize_count = 0
  end

  def init
    [self, nil]
  end

  def update(message)
    case message
    when Bubbletea::WindowSizeMessage
      @width = message.width
      @height = message.height
      @resize_count += 1
      [self, nil]

    when Bubbletea::KeyMessage
      return [self, Bubbletea.quit] if message.to_s == "q"
      [self, nil]

    else
      [self, nil]
    end
  end

  def view
    lines = []
    lines << ""
    lines << "  Window Resize Demo"
    lines << "  =================="
    lines << ""
    lines << "  Terminal size: #{@width} x #{@height}"
    lines << "  Resize events: #{@resize_count}"
    lines << ""
    lines << "  Try resizing your terminal window!"
    lines << ""
    lines << "  Press 'q' to quit"
    lines << ""
    lines.join("\n")
  end
end

Bubbletea.run(ResizeDemo.new)
```

--------------------------------

### Handle Keyboard Input with Bubbletea::KeyMessage

Source: https://context7.com/marcoroth/bubbletea-ruby/llms.txt

Use `KeyMessage` to detect key presses, including special keys and character input. Predicate methods like `enter?` and `ctrl?` simplify checks. Pattern matching on `to_s` can be used for specific key combinations like 'q' or 'ctrl+c' to quit or suspend the application.

```ruby
require "bubbletea"

class KeyHandler
  include Bubbletea::Model

  def initialize
    @last_key = "none"
    @key_info = ""
  end

  def init
    [self, nil]
  end

  def update(message)
    case message
    when Bubbletea::KeyMessage
      @last_key = message.to_s

      # Use predicate methods for common keys
      @key_info = case
      when message.enter?
        "Enter key pressed"
      when message.backspace?
        "Backspace pressed"
      when message.tab?
        "Tab pressed"
      when message.esc?
        "Escape pressed"
      when message.space?
        "Space pressed"
      when message.up?
        "Up arrow"
      when message.down?
        "Down arrow"
      when message.left?
        "Left arrow"
      when message.right?
        "Right arrow"
      when message.ctrl?
        "Control key combination"
      else
        "Character: #{message.char || message.to_s}"
      end

      # Pattern match on string representation
      case message.to_s
      when "q", "ctrl+c"
        return [self, Bubbletea.quit]
      when "ctrl+z"
        return [self, Bubbletea.suspend]
      end

      [self, nil]
    else
      [self, nil]
    end
  end

  def view
    "Last key: #{@last_key}\nInfo: #{@key_info}\n\nPress any key (q to quit)"
  end
end

Bubbletea.run(KeyHandler.new)
```

--------------------------------

### Toggle Alternate Screen Buffer with Bubbletea

Source: https://context7.com/marcoroth/bubbletea-ruby/llms.txt

Use `Bubbletea.enter_alt_screen` and `Bubbletea.exit_alt_screen` to switch between the normal terminal buffer and an alternate screen. This is ideal for fullscreen applications.

```ruby
require "bubbletea"

class AltscreenToggle
  include Bubbletea::Model

  def initialize
    @altscreen = false
  end

  def init
    [self, nil]
  end

  def update(message)
    case message
    when Bubbletea::KeyMessage
      case message.to_s
      when "q", "ctrl+c"
        [self, Bubbletea.quit]
      when " ", "space"
        @altscreen = !@altscreen
        # Toggle between alt screen and normal mode
        cmd = @altscreen ? Bubbletea.enter_alt_screen : Bubbletea.exit_alt_screen
        [self, cmd]
      else
        [self, nil]
      end
    else
      [self, nil]
    end
  end

  def view
    mode = @altscreen ? "ALTSCREEN" : "INLINE"
    "\n\n  You're in #{mode} mode\n\n  space: toggle mode  q: quit\n"
  end
end

# Start in normal (inline) mode
Bubbletea.run(AltscreenToggle.new)

# Or start directly in alt screen mode with:
# Bubbletea.run(AltscreenToggle.new, alt_screen: true)
```

--------------------------------

### Handle Mouse Events with Bubbletea::MouseMessage

Source: https://context7.com/marcoroth/bubbletea-ruby/llms.txt

Capture mouse interactions using `MouseMessage`, which provides coordinates, button states, actions (press, release, motion), and modifier keys. Enable mouse tracking via `mouse_cell_motion` or `mouse_all_motion` options in `Bubbletea.run`. Clear events by pressing 'c' and quit by pressing 'q'.

```ruby
require "bubbletea"

class MouseDemo
  include Bubbletea::Model

  def initialize
    @events = []
    @max_events = 10
  end

  def init
    [self, nil]
  end

  def update(message)
    case message
    when Bubbletea::KeyMessage
      return [self, Bubbletea.quit] if message.to_s == "q"
      @events = [] if message.to_s == "c"  # Clear on 'c'
      [self, nil]

    when Bubbletea::MouseMessage
      # Access position
      x, y = message.x, message.y

      # Check action type
      action = case
      when message.press? then "press"
      when message.release? then "release"
      when message.motion? then "motion"
      else "unknown"
      end

      # Check button type
      button = case
      when message.left? then "left"
      when message.right? then "right"
      when message.middle? then "middle"
      when message.wheel? then "wheel"
      else "none"
      end

      # Check modifiers
      modifiers = []
      modifiers << "shift" if message.shift
      modifiers << "alt" if message.alt
      modifiers << "ctrl" if message.ctrl

      event_str = "(#{x}, #{y}) #{action} #{button}"
      event_str += " [#{modifiers.join("+")}]" if modifiers.any?

      @events.unshift(event_str)
      @events = @events.take(@max_events)
      [self, nil]

    else
      [self, nil]
    end
  end

  def view
    lines = ["Mouse Demo - move/click mouse, 'c' to clear, 'q' to quit", ""]
    lines += @events.empty? ? ["(no events yet)"] : @events
    lines.join("\n")
  end
end

# Enable all mouse motion tracking
Bubbletea.run(MouseDemo.new, mouse_all_motion: true)
```

--------------------------------

### Key Message Helper Methods

Source: https://github.com/marcoroth/bubbletea-ruby/blob/main/README.md

Provides a list of convenient boolean helper methods available on Bubbletea::KeyMessage objects for checking specific keys and modifiers.

```ruby
message.enter?
message.backspace?
message.tab?
message.esc?
message.space?
message.ctrl?
message.up?
message.down?
message.left?
message.right?
```

--------------------------------

### Handle Terminal Focus Events in Bubbletea

Source: https://context7.com/marcoroth/bubbletea-ruby/llms.txt

Demonstrates how to use FocusMessage and BlurMessage to react to terminal focus changes. Enable focus reporting with `report_focus: true` in Bubbletea.run.

```ruby
require "bubbletea"

class FocusDemo
  include Bubbletea::Model

  def initialize
    @focused = true
    @focus_count = 0
    @blur_count = 0
  end

  def init
    [self, nil]
  end

  def update(message)
    case message
    when Bubbletea::FocusMessage
      @focused = true
      @focus_count += 1
      [self, nil]

    when Bubbletea::BlurMessage
      @focused = false
      @blur_count += 1
      [self, nil]

    when Bubbletea::KeyMessage
      return [self, Bubbletea.quit] if message.to_s == "q"
      [self, nil]

    else
      [self, nil]
    end
  end

  def view
    status = @focused ? "FOCUSED" : "BLURRED"
    "Terminal is: #{status}\nFocus events: #{@focus_count}\nBlur events: #{@blur_count}\n\nClick outside terminal to blur, q to quit"
  end
end

# Enable focus reporting
Bubbletea.run(FocusDemo.new, report_focus: true)
```

--------------------------------

### Schedule Tick for Animations

Source: https://github.com/marcoroth/bubbletea-ruby/blob/main/README.md

Demonstrates using Bubbletea.tick to schedule recurring messages for creating animations. Requires a custom message class and a scheduling function.

```ruby
class TickMessage < Bubbletea::Message; end

def init
  [self, schedule_tick]
end

def update(message)
  case message
  when TickMessage
    @frame = (@frame + 1) % FRAMES.length
    [self, schedule_tick]
  end
end

def schedule_tick
  Bubbletea.tick(0.1) { TickMessage.new }
end
```

--------------------------------

### Send Delayed and Immediate Messages with Bubbletea

Source: https://context7.com/marcoroth/bubbletea-ruby/llms.txt

Use `Bubbletea.send_message` to dispatch messages immediately or with a specified delay. Useful for triggering updates or scheduling deferred actions within your application.

```ruby
require "bubbletea"

class DataLoadedMessage < Bubbletea::Message
  attr_reader :data

  def initialize(data)
    super()
    @data = data
  end
end

class SendMessageDemo
  include Bubbletea::Model

  def initialize
    @data = nil
    @loading = false
  end

  def init
    [self, nil]
  end

  def update(message)
    case message
    when DataLoadedMessage
      @data = message.data
      @loading = false
      [self, nil]

    when Bubbletea::KeyMessage
      case message.to_s
      when "q"
        [self, Bubbletea.quit]
      when "l"
        # Simulate loading data with a delayed message
        @loading = true
        [self, Bubbletea.send_message(
          DataLoadedMessage.new("Hello from delayed message!"),
          delay: 2  # 2 second delay
        )]
      when "i"
        # Send immediate message (no delay)
        [self, Bubbletea.send_message(
          DataLoadedMessage.new("Instant data!")
        )]
      else
        [self, nil]
      end

    else
      [self, nil]
    end
  end

  def view
    status = @loading ? "Loading..." : (@data || "No data")
    "Data: #{status}\n\nl: load (2s delay)  i: instant  q: quit"
  end
end

Bubbletea.run(SendMessageDemo.new)
```

--------------------------------

### Create Timed Events with Bubbletea.tick

Source: https://context7.com/marcoroth/bubbletea-ruby/llms.txt

Utilizes `Bubbletea.tick` to schedule messages after a specified duration, ideal for animations and periodic updates. The block passed to `tick` must return a message instance.

```ruby
require "bubbletea"

class TickMessage < Bubbletea::Message
end

class Spinner
  include Bubbletea::Model

  FRAMES = ["⣾", "⣽", "⣻", "⢿", "⡿", "⣟", "⣯", "⣷"].freeze
  TICK_DURATION = 0.08  # 80ms per frame

  def initialize
    @frame = 0
    @progress = 0
    @loading = true
  end

  def init
    # Schedule first tick on startup
    [self, schedule_tick]
  end

  def update(message)
    case message
    when TickMessage
      if @loading
        @frame = (@frame + 1) % FRAMES.length
        @progress += 2
        @loading = false if @progress >= 100
      end
      # Continue ticking while loading
      [self, @loading ? schedule_tick : nil]

    when Bubbletea::KeyMessage
      case message.to_s
      when "q", "ctrl+c"
        [self, Bubbletea.quit]
      when "r"
        # Restart animation
        @frame = 0
        @progress = 0
        @loading = true
        [self, schedule_tick]
      else
        [self, nil]
      end

    else
      [self, nil]
    end
  end

  def view
    if @loading
      "#{FRAMES[@frame]} Loading... (#{@progress}%)\n\n r: restart  q: quit"
    else
      "✓ Complete!\n\n r: restart  q: quit"
    end
  end

  private

  def schedule_tick
    # tick(duration) { message } - returns command that sends message after duration
    Bubbletea.tick(TICK_DURATION) { TickMessage.new }
  end
end

Bubbletea.run(Spinner.new)
```

--------------------------------

### Detecting TTY with Bubbletea.tty?

Source: https://context7.com/marcoroth/bubbletea-ruby/llms.txt

Checks if the program is running in an interactive terminal to handle non-interactive environments gracefully. Requires the Bubbletea gem.

```ruby
require "bubbletea"

class MyApp
  include Bubbletea::Model

  def init
    [self, nil]
  end

  def update(message)
    case message
    when Bubbletea::KeyMessage
      return [self, Bubbletea.quit] if message.to_s == "q"
    end
    [self, nil]
  end

  def view
    "Interactive TUI Application\nPress q to quit"
  end
end

# Check for TTY before running
unless Bubbletea.tty?
  puts "Error: This application requires a TTY. Run it directly in a terminal."
  exit 1
end

Bubbletea.run(MyApp.new)
```

--------------------------------

### Add Bubbletea to Gemfile

Source: https://github.com/marcoroth/bubbletea-ruby/blob/main/README.md

Include the Bubbletea gem in your project's Gemfile for dependency management.

```ruby
gem "bubbletea"
```

--------------------------------

### Set Terminal Window Title with Bubbletea

Source: https://context7.com/marcoroth/bubbletea-ruby/llms.txt

The `Bubbletea.set_window_title` command allows you to change the title of the terminal window or tab. This is useful for displaying application status or context.

```ruby
require "bubbletea"

class TitleDemo
  include Bubbletea::Model

  TITLES = [
    "Bubbletea Demo",
    "Processing...",
    "Ready!",
    "Working...",
  ].freeze

  def initialize
    @title_index = 0
  end

  def init
    [self, Bubbletea.set_window_title(TITLES[@title_index])]
  end

  def update(message)
    case message
    when Bubbletea::KeyMessage
      case message.to_s
      when "q"
        [self, Bubbletea.quit]
      when "t"
        # Cycle through titles
        @title_index = (@title_index + 1) % TITLES.length
        [self, Bubbletea.set_window_title(TITLES[@title_index])]
      else
        [self, nil]
      end
    else
      [self, nil]
    end
  end

  def view
    "Current title: #{TITLES[@title_index]}\n\nt: change title  q: quit"
  end
end

Bubbletea.run(TitleDemo.new, alt_screen: true)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.