@callback clear(state()) :: {:ok, state()}

Clears the entire screen.

Returns {:ok, updated_state} after clearing.

Typically resets cursor to home position as well. Maps to ANSI CSI sequence ESC[2J followed by ESC[H.

@callback draw_cells(state(), [{position(), cell()}]) :: {:ok, state()}

Draws cells to the terminal at specified positions.

Receives a list of {position, cell} tuples. Cells are sorted by position (row-major order) for efficient sequential output.

Returns {:ok, updated_state} after drawing.

Implementation Notes

• Raw backend uses differential rendering (only changed cells)
• TTY backend may use full redraw depending on configuration
• Should optimize cursor movement between cells

@callback flush(state()) :: {:ok, state()}

Flushes pending output to the terminal.

Ensures all buffered output is sent to the terminal device. Returns {:ok, updated_state} after flushing.

Implementation Notes

• May be a no-op if output is unbuffered
• Should be called after draw_cells/2 to ensure visibility

@callback hide_cursor(state()) :: {:ok, state()}

Hides the terminal cursor.

Returns {:ok, updated_state} after hiding cursor.

Typically called before rendering to prevent cursor flicker. Maps to ANSI CSI sequence ESC[?25l.

@callback init(opts :: keyword()) :: {:ok, state()} | {:error, reason :: term()}

Initializes the backend with the given options.

Called once during runtime startup. The options may include:

• :capabilities - Map of detected terminal capabilities (TTY mode)
• Backend-specific options

Returns {:ok, state} on success or {:error, reason} on failure.

Implementation Notes

• Raw backend receives options from successful :shell.start_interactive/1
• TTY backend receives capabilities map from Backend.Selector
• Should set up terminal state (alternate screen, cursor hiding, etc.)

@callback move_cursor(state(), position()) :: {:ok, state()}

Moves the cursor to the specified position.

Position is 1-indexed: {1, 1} is the top-left corner.

Returns {:ok, updated_state} after positioning.

Implementation Notes

• Maps to ANSI CSI sequence ESC[row;colH
• Position should be clamped to terminal bounds

@callback poll_event(state(), timeout :: non_neg_integer()) ::
  {:ok, event(), state()}
  | {:timeout, state()}
  | {:error, reason :: term(), state()}

Polls for input events with the specified timeout.

• timeout - Milliseconds to wait for input (0 for non-blocking)

Returns:

• {:ok, event, updated_state} - Event received
• {:timeout, updated_state} - No input within timeout
• {:error, reason, state} - Error occurred

Implementation Notes

• Raw backend provides immediate keystroke detection
• TTY backend uses blocking IO.getn/2; cooked-mode delivery may wait for Enter
• Timeout may not be honored precisely in TTY mode (blocking IO)
• Events should be parsed into TermUI.Event structs

@callback show_cursor(state()) :: {:ok, state()}

Shows the terminal cursor.

Returns {:ok, updated_state} after showing cursor.

Called after rendering or when cursor visibility is needed. Maps to ANSI CSI sequence ESC[?25h.

@callback shutdown(state()) :: :ok

Shuts down the backend and restores terminal state.

Called during runtime shutdown. Must:

• Restore terminal to its original state
• Release any held resources
• Be idempotent (safe to call multiple times)
• Handle errors gracefully (always return :ok)

Implementation Notes

• Should restore cursor visibility
• Should exit alternate screen if entered
• Should reset all attributes

@callback size(state()) :: {:ok, size()} | {:error, :enotsup}

Returns the current terminal dimensions.

Returns {:ok, {rows, cols}} with the terminal size. Returns {:error, :enotsup} if size cannot be determined.

Implementation Notes

• Size may be cached and require explicit refresh after resize events
• TTY backend may use :io.columns/0 and :io.rows/0
• Raw backend may query terminal directly