@spec clear(t()) :: {:ok, t()}

Clears the entire screen and moves cursor to home position.

Outputs the following escape sequences:

1. \e[2J - Clear entire screen
2. \e[H - Move cursor to home position (1,1)

Also clears last_frame in state, which forces a full redraw on the next draw_cells/2 call when in incremental mode.

Returns

{:ok, updated_state} with cursor_position set to {1, 1} and last_frame cleared.

@spec compare_frames(
  map(),
  [{TermUI.Backend.position(), TermUI.Backend.cell()}]
) ::
  {[{TermUI.Backend.position(), TermUI.Backend.cell()}],
   [TermUI.Backend.position()]}

Compares two frames to find changed and removed cells.

This is a testing helper function exposed for unit testing the incremental rendering logic. It is not part of the Backend behaviour API.

Uses MapSet for efficient position lookup when finding removed cells, avoiding the need to build a full frame map just for membership testing.

Parameters

• last_frame - Map of {row, col} => {char, fg, bg, attrs} from previous frame
• current_cells - List of {{row, col}, {char, fg, bg, attrs}} tuples for current frame

Returns

Tuple of {changed_cells, removed_positions}:

• changed_cells - Cells that are new or different from last frame
• removed_positions - Positions that were in last frame but not in current

@spec draw_cells(t(), [{TermUI.Backend.position(), TermUI.Backend.cell()}]) ::
  {:ok, t()}

Draws cells to the terminal at specified positions.

In :full_redraw mode (default), clears the screen first then renders all cells. In :incremental mode, only renders the provided cells without clearing.

Cell Format

Each cell is a tuple of {position, cell_data} where:

• position is {row, col} (1-indexed)
• cell_data is {char, fg_color, bg_color, attrs}

Rendering Process

1. In full_redraw mode, clear screen and home cursor
2. Group cells by row for efficient rendering
3. For each row, position cursor and output styled characters
4. Apply color degradation based on color_mode

Returns

{:ok, updated_state} with last_frame updated for incremental mode.

@spec flush(t()) :: {:ok, t()}

Flushes pending output to the terminal.

For TTY mode, output is synchronous so this is largely a no-op.

@spec hide_cursor(t()) :: {:ok, t()}

Hides the terminal cursor.

Outputs \e[?25l escape sequence.

This operation is idempotent - if the cursor is already hidden, no escape sequence is written.

@spec init(keyword()) :: {:ok, t()}

Initializes the TTY backend with detected capabilities.

Accepts options from the Selector including terminal capabilities.

Options

• :capabilities - Map of detected terminal capabilities
• :line_mode - Rendering strategy (default: :full_redraw)
• :alternate_screen - Use alternate screen buffer (default: false)
• :size - Explicit terminal dimensions (default: from capabilities or {24, 80})

Returns

• {:ok, state} - Successfully initialized
• {:error, reason} - Initialization failed

@spec move_cursor(
  t(),
  {pos_integer(), pos_integer()}
) :: {:ok, t()}

Moves the cursor to the specified position.

Position is 1-indexed: {1, 1} is the top-left corner. Outputs \e[row;colH escape sequence. Position is clamped to terminal bounds.

@spec poll_event(t(), non_neg_integer()) ::
  {:ok, TermUI.Backend.event(), t()} | {:timeout, t()} | {:error, term(), t()}

Polls for input events with the specified timeout.

Requests one character at a time with IO.getn/2. Because the terminal stays in cooked mode, the shell or terminal driver may buffer input until Enter. The timeout parameter may not be honored since IO.getn/2 is blocking.

Input is parsed using TermUI.Terminal.EscapeParser to handle escape sequences like arrow keys, function keys, and mouse events.

Partial escape sequences are buffered in the state's input_buffer field and will be completed on subsequent calls.

Returns

• {:ok, event, state} - An input event was received
• {:timeout, state} - No input available (rare with blocking IO)
• {:error, reason, state} - An error occurred

Note

The timeout parameter is not honored due to the blocking nature of IO.getn/2. For non-blocking input, consider using the Raw backend when available.

@spec refresh_size(t()) :: {:ok, TermUI.Backend.size(), t()}

Queries the terminal for its current size and updates state.

Uses :io.rows/0 and :io.columns/0 to get the current terminal dimensions. If the query fails (e.g., not connected to a terminal), the current size is preserved.

This function also clears last_frame to force a full redraw, since the terminal dimensions may have changed.

Note: This is a TTY-specific extension function, not part of the Backend behaviour. The return signature matches TermUI.Backend.Raw.refresh_size/1 for consistency.

Returns

{:ok, {rows, cols}, updated_state} with refreshed size and cleared last_frame.

Example

{:ok, {rows, cols}, state} = TTY.refresh_size(state)

@spec set_size(
  t(),
  {pos_integer(), pos_integer()}
) :: {:ok, t()}

Updates the terminal size and clears the frame buffer.

When the terminal is resized, the previous frame is no longer valid since positions may now be out of bounds or content may need to be reflowed. This function updates the size and clears last_frame to force a full redraw on the next draw_cells/2 call.

Parameters

• state - Current backend state
• new_size - New terminal dimensions as {rows, cols}

Returns

{:ok, updated_state} with new size and cleared last_frame.

@spec show_cursor(t()) :: {:ok, t()}

Shows the terminal cursor.

Outputs \e[?25h escape sequence.

This operation is idempotent - if the cursor is already visible, no escape sequence is written.

@spec shutdown(t()) :: :ok

Shuts down the TTY backend and restores terminal state.

Performs the following cleanup sequence:

1. Reset all text attributes (colors, bold, underline, etc.)
2. Show the cursor (in case it was hidden)
3. Leave alternate screen buffer (if it was entered)

Idempotent Behavior

This function is safe to call multiple times. Each call will emit the same cleanup sequences, which is harmless since terminal state converges to the same result regardless of prior state.

Error Handling

All terminal writes use safe_write/1 which catches and ignores errors. This ensures cleanup completes even if the terminal is in an error state or has been disconnected. We prioritize best-effort cleanup over failing on individual write errors.

No Cooked Mode Restoration

Unlike the Raw backend, the TTY backend never takes the terminal out of cooked mode (the shell is already running). Therefore, no mode restoration is needed during shutdown.

Returns

Always returns :ok.

@spec size(t()) :: {:ok, {pos_integer(), pos_integer()}}

Returns the current terminal dimensions.

Returns

• {:ok, {rows, cols}} - Terminal size