Struct IterationBuffer 

pub struct IterationBuffer {
    pub number: u32,
    pub lines: Arc<Mutex<Vec<Line<'static>>>>,
    pub scroll_offset: usize,
    pub following_bottom: bool,
    pub hat_display: Option<String>,
    pub backend: Option<String>,
    pub started_at: Option<Instant>,
    pub elapsed: Option<Duration>,
    pub wave_info: Option<WaveInfo>,
}

Stores formatted output content for a single Ralph iteration. Each iteration has its own buffer with independent scroll state.

The lines field is wrapped in Arc<Mutex<>> to allow sharing with stream handlers during execution, enabling real-time streaming to the TUI instead of batch transfer after execution completes.

Fields

number: u32

Iteration number (1-indexed for display)

lines: Arc<Mutex<Vec<Line<'static>>>>

Formatted lines of output (shared for streaming)

scroll_offset: usize

Scroll position within this buffer

following_bottom: bool

Whether to auto-scroll to bottom as new content arrives. Starts true, becomes false when user scrolls up, restored when user scrolls to bottom (G key) or manually scrolls down to reach bottom.

hat_display: Option<String>

Hat display name (emoji + name) for this iteration.

backend: Option<String>

Backend used for this iteration (e.g., “claude”, “kiro”).

started_at: Option<Instant>

When this iteration started (for elapsed time calculation).

elapsed: Option<Duration>

Frozen elapsed duration for this iteration (set when completed).

wave_info: Option<WaveInfo>

Wave data associated with this iteration (stored on wave completion).

Implementations

impl IterationBuffer

pub fn new(number: u32) -> Self

Creates a new buffer for the given iteration number.

pub fn lines_handle(&self) -> Arc<Mutex<Vec<Line<'static>>>>

Returns a shared handle to the lines buffer for streaming.

This allows stream handlers to write directly to the buffer, enabling real-time streaming to the TUI.

pub fn append_line(&mut self, line: Line<'static>)

Appends a line to the buffer.

pub fn line_count(&self) -> usize

Returns the total number of lines in the buffer.

pub fn visible_lines(&self, viewport_height: usize) -> Vec<Line<'static>>

Returns a clone of the visible lines based on scroll offset and viewport height.

Note: Returns owned Vec instead of slice due to interior mutability.

pub fn scroll_up(&mut self)

Scrolls up by one line. Disables auto-scroll since user is moving away from bottom.

pub fn scroll_down(&mut self, viewport_height: usize)

Scrolls down by one line, respecting the viewport bounds. Re-enables auto-scroll if user reaches the bottom.

pub fn scroll_top(&mut self)

Scrolls to the top of the buffer. Disables auto-scroll since user is moving away from bottom.

pub fn scroll_bottom(&mut self, viewport_height: usize)

Scrolls to the bottom of the buffer. Re-enables auto-scroll since user explicitly went to bottom.