Struct TuiState 

pub struct TuiState {

    pub pending_hat: Option<(HatId, String)>,
    pub pending_backend: Option<String>,
    pub iteration: u32,
    pub prev_iteration: u32,
    pub loop_started: Option<Instant>,
    pub iteration_started: Option<Instant>,
    pub last_event: Option<String>,
    pub last_event_at: Option<Instant>,
    pub show_help: bool,
    pub mouse_capture_enabled: bool,
    pub in_scroll_mode: bool,
    pub search_query: String,
    pub search_forward: bool,
    pub max_iterations: Option<u32>,
    pub idle_timeout_remaining: Option<Duration>,
    pub update_status: UpdateStatus,
    pub iterations: Vec<IterationBuffer>,
    pub current_view: usize,
    pub following_latest: bool,
    pub new_iteration_alert: Option<usize>,
    pub search_state: SearchState,
    pub loop_completed: bool,
    pub final_iteration_elapsed: Option<Duration>,
    pub final_loop_elapsed: Option<Duration>,
    pub task_counts: TaskCounts,
    pub active_task: Option<TaskSummary>,
    pub wave_active: Option<WaveInfo>,
    pub wave_active_iteration_idx: Option<usize>,
    pub wave_view_active: bool,
    pub wave_view_index: usize,
    pub guidance_mode: Option<GuidanceMode>,
    pub guidance_input: String,
    pub guidance_next_queue: Arc<Mutex<Vec<String>>>,
    pub events_path: Option<PathBuf>,
    pub urgent_steer_path: Option<PathBuf>,
    pub guidance_flash: Option<(GuidanceMode, GuidanceResult, Instant)>,
    pub subprocess_error: Option<String>,
    pub rpc_text_buffer: String,
    pub rpc_text_line_count: usize,
    /* private fields */
}

Observable state derived from loop events.

Fields

pending_hat: Option<(HatId, String)>

Which hat will process next event (ID + display name).

pending_backend: Option<String>

Backend expected for the next iteration (used when metadata is missing).

iteration: u32

Current iteration number (0-indexed, display as +1).

prev_iteration: u32

Previous iteration number (for detecting changes).

loop_started: Option<Instant>

When loop began.

iteration_started: Option<Instant>

When current iteration began.

last_event: Option<String>

Most recent event topic.

last_event_at: Option<Instant>

Timestamp of last event.

show_help: bool

Whether to show help overlay.

mouse_capture_enabled: bool

Whether mouse capture is enabled for wheel scrolling. When false, the terminal keeps native drag-to-select behavior.

in_scroll_mode: bool

Whether in scroll mode.

search_query: String

Current search query (if in search input mode).

search_forward: bool

Search direction (true = forward, false = backward).

max_iterations: Option<u32>

Maximum iterations from config.

idle_timeout_remaining: Option<Duration>

Idle timeout countdown.

update_status: UpdateStatus

Status of the asynchronous update check.

iterations: Vec<IterationBuffer>

Content buffers for each iteration.

current_view: usize

Index of the iteration currently being viewed (0-indexed).

following_latest: bool

Whether to automatically follow the latest iteration.

new_iteration_alert: Option<usize>

Alert about a new iteration (shown when viewing history and new iteration arrives). Contains the iteration number to alert about. Cleared when navigating to latest.

search_state: SearchState

Search state for finding and navigating matches in iteration content.

loop_completed: bool

Whether the loop has completed (received loop.terminate event).

final_iteration_elapsed: Option<Duration>

Frozen elapsed time when loop completed (timer stops at this value).

final_loop_elapsed: Option<Duration>

Frozen total elapsed time when loop completed (footer timer stops).

task_counts: TaskCounts

Aggregate task counts for display in TUI widgets.

active_task: Option<TaskSummary>

Currently active task (if any) for display in TUI widgets.

wave_active: Option<WaveInfo>

Active wave info for header display (only set while a wave is running).

wave_active_iteration_idx: Option<usize>

Index into iterations that the active wave belongs to. Used by wave_info_for_view() to only return wave_active when viewing the specific iteration that owns the running wave.

wave_view_active: bool

Whether the wave worker drill-down view is active.

wave_view_index: usize

Index of the worker currently being viewed in wave view (0-indexed).

guidance_mode: Option<GuidanceMode>

Active guidance input mode (None when not entering guidance).

guidance_input: String

Text being typed in guidance input.

guidance_next_queue: Arc<Mutex<Vec<String>>>

Queue of guidance messages for the next iteration (drained by loop_runner).

events_path: Option<PathBuf>

Path to events.jsonl for writing urgent guidance for the next prompt.

urgent_steer_path: Option<PathBuf>

Path to the urgent-steer marker file used to gate ralph emit.

guidance_flash: Option<(GuidanceMode, GuidanceResult, Instant)>

Brief flash message after attempting to send guidance. (mode, result, when)

subprocess_error: Option<String>

Error message set when subprocess exits before sending any RPC events. When set, the TUI displays an error state instead of empty content.

rpc_text_buffer: String

Buffer for accumulating streaming text deltas received via RPC. Text is rendered as a group when frozen (on tool call, error, or iteration end) rather than rendering each small delta independently.

rpc_text_line_count: usize

Number of lines in the current iteration buffer that belong to the current (unfrozen) text. When new text arrives, these lines are replaced with a fresh render of the full accumulated text.

Implementations

impl TuiState

pub fn new() -> Self

Creates empty state. Timer starts immediately at creation.

pub fn with_hat_map(hat_map: HashMap<String, (HatId, String)>) -> Self

Creates state with a custom hat map for dynamic topic-to-hat resolution. Timer starts immediately at creation.

pub fn set_current_branch(&mut self, branch: Option<String>)

Sets the git branch displayed by the TUI.

pub fn current_branch(&self) -> Option<&str>

Returns the git branch displayed by the TUI, if known.

pub fn set_hat_map(&mut self, hat_map: HashMap<String, (HatId, String)>)

Replaces the dynamic topic-to-hat mapping without resetting the rest of the state.

pub fn update(&mut self, event: &Event)

Updates state based on event topic.

pub fn get_pending_hat_display(&self) -> String

Returns formatted hat display (emoji + name).

pub fn get_loop_elapsed(&self) -> Option<Duration>

Time since loop started.

pub fn get_iteration_elapsed(&self) -> Option<Duration>

Time since iteration started, or frozen value if loop completed.

pub fn is_active(&self) -> bool

True if event received in last 2 seconds.

pub fn iteration_changed(&self) -> bool

True if iteration changed since last check.

pub fn get_task_counts(&self) -> &TaskCounts

Returns a reference to the current task counts.

pub fn get_active_task(&self) -> Option<&TaskSummary>

Returns a reference to the active task, if any.

pub fn set_task_counts(&mut self, counts: TaskCounts)

Updates the task counts.

pub fn set_active_task(&mut self, task: Option<TaskSummary>)

Sets the active task.

pub fn has_open_tasks(&self) -> bool

Returns true if there are any open tasks.

pub fn get_task_progress_display(&self) -> String

Returns a formatted string for task progress display (e.g., “3/5 tasks”).

pub fn start_new_iteration(&mut self)

Starts a new iteration, creating a new IterationBuffer. If following_latest is true, current_view is updated to the new iteration. If not following, sets the new_iteration_alert to notify the user.

pub fn start_new_iteration_with_metadata( &mut self, hat_display: Option<String>, backend: Option<String>, )

Starts a new iteration with optional metadata for hat and backend display.

pub fn finish_latest_iteration(&mut self)

Finalizes the latest iteration’s elapsed time if it isn’t already set.

pub fn current_iteration_hat_display(&self) -> Option<&str>

Returns the hat display for the currently viewed iteration, if available.

pub fn current_iteration_backend(&self) -> Option<&str>

Returns the backend display for the currently viewed iteration, if available.

pub fn current_iteration(&self) -> Option<&IterationBuffer>

Returns a reference to the currently viewed iteration buffer.

pub fn current_iteration_mut(&mut self) -> Option<&mut IterationBuffer>

Returns a mutable reference to the currently viewed iteration buffer.

pub fn current_iteration_lines_handle( &self, ) -> Option<Arc<Mutex<Vec<Line<'static>>>>>

Returns a shared handle to the current iteration’s lines buffer.

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

pub fn latest_iteration_lines_handle( &self, ) -> Option<Arc<Mutex<Vec<Line<'static>>>>>

Returns a shared handle to the latest iteration’s lines buffer.

This should be used when writing output from the currently executing iteration, regardless of which iteration the user is viewing. This prevents output from being written to the wrong iteration when the user is reviewing an older iteration.

pub fn navigate_next(&mut self)

Navigates to the next iteration (if not at the last one). If reaching the last iteration, re-enables following_latest and clears alerts.

pub fn navigate_prev(&mut self)

Navigates to the previous iteration (if not at the first one). Disables following_latest when navigating backwards.

pub fn total_iterations(&self) -> usize

Returns the total number of iterations.

pub fn search(&mut self, query: &str)

Searches for the given query in the current iteration’s content. Populates matches with (line_index, char_offset) pairs. Search is case-insensitive.

pub fn next_match(&mut self)

Navigates to the next match, cycling back to the first if at the end.

pub fn prev_match(&mut self)

Navigates to the previous match, cycling to the last if at the beginning.

pub fn clear_search(&mut self)

Clears the search state.

pub fn start_guidance(&mut self, mode: GuidanceMode)

Enters guidance input mode.

pub fn cancel_guidance(&mut self)

Cancels guidance input without sending.

pub fn send_guidance(&mut self) -> bool

Sends the current guidance input.

For GuidanceMode::Next, pushes to the shared queue (drained by loop_runner). For GuidanceMode::Now, writes an urgent-steer marker immediately and records human.guidance for the next prompt boundary.

Returns true if guidance was sent successfully.

pub fn is_guidance_active(&self) -> bool

Returns true if guidance input is currently active.

pub fn clear_expired_guidance_flash(&mut self)

Clears flash message if it has expired.

pub fn active_guidance_flash(&self) -> Option<(GuidanceMode, GuidanceResult)>

Returns active guidance flash (mode + result) if still within display window (2 seconds).

pub fn set_update_status(&mut self, status: UpdateStatus)

Updates the cached result of the asynchronous version check.

pub fn wave_info_for_wave_view(&self) -> Option<&WaveInfo>

Returns the WaveInfo for the current wave view (public, for header rendering).

pub fn enter_wave_view(&mut self)

Enters wave worker drill-down view. No-op if no wave data exists.

pub fn exit_wave_view(&mut self)

Exits wave worker drill-down view.

pub fn wave_view_next(&mut self)

Cycles to the next worker in wave view.

pub fn wave_view_prev(&mut self)

Cycles to the previous worker in wave view.

pub fn current_wave_worker_buffer(&self) -> Option<&IterationBuffer>

Returns the current wave worker buffer (immutable) for rendering.

pub fn current_wave_worker_buffer_mut(&mut self) -> Option<&mut IterationBuffer>

Returns the current wave worker buffer (mutable) for scrolling.

Trait Implementations

impl Default for TuiState

fn default() -> Self

Returns the “default value” for a type.