@spec activate(t(), MingaEditor.State.Windows.t(), MingaEditor.State.FileTree.t()) ::
  t()

Activates the view, saving the current window layout.

@spec cancel_search(t()) :: t()

Cancels search.

@spec clear_baselines(t()) :: t()

Clears all diff baselines.

@spec clear_display(t(), non_neg_integer()) :: t()

Clears the chat display without affecting conversation history.

Sets display_start_index to the given message count so the renderer skips all messages before this point. Scrolls to bottom.

@spec clear_input(t()) :: t()

Clears the input (after submission). Saves current text to history first.

@spec clear_input_and_scroll(t()) :: t()

Clears the input and scrolls to the bottom.

@spec clear_prefix(t()) :: t()

Clears any pending prefix.

@spec clear_toasts(t()) :: t()

Clears all toasts.

@spec confirm_search(t()) :: t()

Confirms search (keeps matches for n/N navigation, disables input).

@spec deactivate(t()) ::
  {t(), MingaEditor.State.Windows.t() | nil,
   MingaEditor.State.FileTree.t() | nil}

Deactivates the view and returns the restored window layout.

@spec delete_char(t()) :: t()

Deletes the character before the cursor.

At the start of a line (col 0), joins with the previous line. At the start of the first line, no-op.

@spec dismiss_help(t()) :: t()

Dismisses the help overlay.

@spec dismiss_toast(t()) :: t()

Dismisses the current toast.

@spec engage_auto_scroll(t()) :: t()

Re-engages auto-scroll. Delegates to Minga.Editing.Minga.Editing.pin_to_bottom/1.

@spec ensure_prompt_buffer(t()) :: t()

Ensures a prompt Buffer.Server is running. Starts one if prompt_buffer is nil or the process is dead.

@spec get_baseline(t() | MingaEditor.Agent.UIState.View.t(), String.t()) ::
  String.t() | nil

Returns the baseline content for a path, or nil if none recorded.

@spec grow_chat(t()) :: t()

Grows the chat panel width by one step (clamped at max).

@spec history_next(t()) :: t()

Recalls the next (more recent) prompt from history.

@spec history_prev(t()) :: t()

Recalls the previous prompt from history.

@spec input_cursor(t() | MingaEditor.Agent.UIState.Panel.t()) ::
  {non_neg_integer(), non_neg_integer()}

Returns the input cursor position as {line, col}.

@spec input_empty?(t() | MingaEditor.Agent.UIState.Panel.t()) :: boolean()

Returns true if the input is empty (single empty line).

@spec input_line_count(t() | MingaEditor.Agent.UIState.Panel.t()) :: pos_integer()

Returns the number of input lines.

@spec input_lines(t() | MingaEditor.Agent.UIState.Panel.t()) :: [String.t()]

Returns the input lines as a list of strings.

@spec input_text(t() | MingaEditor.Agent.UIState.Panel.t()) :: String.t()

Returns the raw input text (with placeholders, not substituted).

@spec insert_char(t(), String.t()) :: t()

Inserts a character at the cursor position.

@spec insert_newline(t()) :: t()

Inserts a newline at the cursor, splitting the current line.

@spec insert_paste(t(), String.t()) :: t()

Inserts pasted text into the input.

For short pastes (fewer than 3 lines), the text is inserted directly into the buffer. For longer pastes, the text is stored in pasted_blocks and a placeholder token is inserted at the cursor position. The placeholder renders as a compact indicator (e.g. "󰆏 [pasted 23 lines]") but prompt_text/1 substitutes the full content when the prompt is submitted.

@spec maybe_auto_scroll(t()) :: t()

No-op. Streaming events call this; renderer handles pinning.

@spec move_cursor_down(t()) :: t() | :at_bottom

Moves cursor down within the input. Returns :at_bottom if already on the last line.

@spec move_cursor_up(t()) :: t() | :at_top

Moves cursor up within the input. Returns :at_top if already on the first line.

@spec new() :: t()

Creates a new UIState with default sub-structs.

@spec next_search_match(t()) :: t()

Moves to the next search match.

@spec paste_block_index(String.t()) :: non_neg_integer() | nil

Returns the paste block index for a placeholder line, or nil if not a placeholder.

@spec paste_block_line_count(t() | [paste_block()], non_neg_integer()) ::
  non_neg_integer()

Returns the line count for a paste block at the given index.

@spec paste_placeholder?(String.t()) :: boolean()

Returns true if the given line is a paste placeholder token.

@spec prev_search_match(t()) :: t()

Moves to the previous search match.

@spec prompt_text(t() | MingaEditor.Agent.UIState.Panel.t()) :: String.t()

Returns the prompt text with paste placeholders substituted.

This is the text submitted to the LLM. Placeholder tokens are replaced with the full paste content from pasted_blocks.

@spec push_toast(t(), String.t(), :info | :warning | :error) :: t()

Pushes a toast.

@spec record_baseline(t(), String.t(), String.t()) :: t()

Records the baseline content for a file path (first edit only).

@spec reset_split(t()) :: t()

Resets the chat panel width to the configured default.

@spec save_to_history(t()) :: t()

Saves the current input to prompt history (if non-empty).

@spec scroll_down(t(), non_neg_integer()) :: t()

Scrolls the content down. Delegates to Minga.Editing.Minga.Editing.scroll_down/2.

@spec scroll_to_bottom(t()) :: t()

Pins chat to bottom. Delegates to Minga.Editing.Minga.Editing.pin_to_bottom/1.

@spec scroll_to_top(t()) :: t()

Scrolls to top. Delegates to Minga.Editing.Minga.Editing.scroll_to_top/1.

@spec scroll_up(t(), non_neg_integer()) :: t()

Scrolls the content up. Delegates to Minga.Editing.Minga.Editing.scroll_up/2.

@spec scroll_viewer_down(t(), pos_integer()) :: t()

Scrolls the preview pane down by the given number of lines.

@spec scroll_viewer_to_bottom(t()) :: t()

Scrolls the preview pane to a large offset (renderer clamps to actual content).

@spec scroll_viewer_to_top(t()) :: t()

Scrolls the preview pane to the top (offset 0).

@spec scroll_viewer_up(t(), pos_integer()) :: t()

Scrolls the preview pane up by the given number of lines, clamped at 0.

@spec search_input_active?(t() | MingaEditor.Agent.UIState.View.t()) :: boolean()

Returns true if search input is being typed.

@spec search_query(t() | MingaEditor.Agent.UIState.View.t()) :: String.t() | nil

Returns the search query, or nil if not searching.

@spec search_saved_scroll(t() | MingaEditor.Agent.UIState.View.t()) ::
  non_neg_integer() | nil

Returns the saved scroll position from before search started.

@spec searching?(t() | MingaEditor.Agent.UIState.View.t()) :: boolean()

Returns true if search is active.

@spec set_focus(t(), MingaEditor.Agent.UIState.View.focus()) :: t()

Switches focus to the given panel.

@spec set_input_focused(t(), boolean()) :: t()

Sets the input focus state. Entering focus ensures the prompt buffer exists.

@spec set_model_name(t(), String.t()) :: t()

Sets the model name.

@spec set_prefix(t(), MingaEditor.Agent.UIState.View.prefix()) :: t()

Sets the pending prefix for multi-key sequences.

@spec set_prompt_text(t(), String.t()) :: t()

Replaces the input content with the given text. Does not save to history.

@spec set_provider_name(t(), String.t()) :: t()

Sets the provider name.

@spec set_scroll(t(), non_neg_integer()) :: t()

Sets the scroll offset to an absolute value. Unpins from bottom.

@spec set_search_matches(t(), [MingaEditor.Agent.UIState.View.search_match()]) :: t()

Sets search matches and resets current to 0.

@spec set_thinking_level(t(), String.t()) :: t()

Sets the thinking level.

@spec shrink_chat(t()) :: t()

Shrinks the chat panel width by one step (clamped at min).

@spec start_search(t(), non_neg_integer()) :: t()

Starts a search, saving the current scroll position.

@spec tick_spinner(t()) :: t()

Advances the spinner animation frame.

@spec toast_visible?(t() | MingaEditor.Agent.UIState.View.t()) :: boolean()

Returns true if a toast is currently visible.

@spec toggle(t()) :: t()

Toggles panel visibility.

@spec toggle_help(t()) :: t()

Toggles the help overlay visibility.

@spec toggle_paste_expand(t()) :: t()

Toggles expand/collapse on the paste block at the current cursor line.

@spec update_preview(t(), (MingaEditor.Agent.View.Preview.t() ->
                       MingaEditor.Agent.View.Preview.t())) ::
  t()

Updates the preview state with the given function.

@spec update_search_query(t(), String.t()) :: t()

Updates the search query string.