Last indexed: 7 February 2026 (2e2181)

Terminal Integration

Purpose and Scope

This document describes how the hypervel/prompts library interfaces with the terminal at a low level. It covers raw mode terminal configuration, cursor control, ANSI escape sequences, input reading, and output management through Symfony Console abstractions.

For information about the high-level prompt lifecycle and rendering, see The Prompt Lifecycle. For state management and validation, see State Management and Validation. For specific ANSI color styling details, see ANSI Colors and Styling.

Terminal Abstraction Layer

The library uses a Terminal class as the primary abstraction for all terminal I/O operations. Each Prompt instance maintains a static reference to a shared Terminal instance, ensuring consistent terminal state across all prompts.

Terminal Instance Management

The Prompt class provides a static accessor for the terminal:

src/Prompt.php93-94 src/Prompt.php244-248

The terminal is lazily initialized on first access and shared across all prompt instances within the same process.

Raw Mode Configuration

When a prompt starts execution, it configures the terminal into raw mode to capture individual keystrokes without buffering:

src/Prompt.php121-128

The setTty('-icanon -isig -echo') call configures the terminal with:

-icanon: Disables canonical (line-buffered) input mode
-isig: Disables signal generation for special characters
-echo: Disables echoing of input characters

If TTY configuration fails (e.g., in a non-interactive environment), the prompt automatically falls back to non-interactive mode.

TTY Restoration

The terminal state is restored when a prompt completes or is destroyed:

src/Prompt.php443-448

The destructor ensures the terminal is properly restored even if an exception occurs during prompt execution.

Sources: src/Prompt.php93-94 src/Prompt.php121-128 src/Prompt.php244-248 src/Prompt.php443-448

Terminal State Diagram

Sources: src/Prompt.php104-161

Output Management

The library abstracts terminal output through Symfony Console's OutputInterface, allowing integration with existing console applications while providing specialized output handling for prompts.

OutputInterface Integration

The Prompt class maintains a static output instance:

src/Prompt.php88-89 src/Prompt.php216-228

By default, a ConsoleOutput instance is created, but applications can inject custom output implementations via setOutput().

Direct Writing Mechanism

Prompts bypass normal output buffering using a direct writing mechanism:

src/Prompt.php233-240

This method attempts three approaches in order:

writeDirectly() method on custom output implementations
getOutput()->write() on wrapped output objects
Standard write() as fallback

Direct writing is critical for cursor control sequences and frame updates, as it prevents interference from output buffering.

Output Usage During Rendering

The rendering process writes to the terminal through the output abstraction:

src/Prompt.php280-310

The initial render (state 'initial') writes the frame directly. Subsequent renders calculate the frame difference, move the cursor to the start position, clear downward, and write the updated frame.

Sources: src/Prompt.php88-89 src/Prompt.php216-240 src/Prompt.php280-310

Input Reading Loop

The core input mechanism is a blocking read loop that processes keystrokes one at a time.

The runLoop Implementation

src/Prompt.php163-186

The loop:

Calls terminal()->read() to get the next keystroke
Returns null when no more input is available
Skips empty strings (indicating read failures)
Invokes the provided callable with the key
Continues until a Result is returned
Extracts the value from the Result wrapper

Keystroke Processing

The prompt() method uses runLoop to process each key:

src/Prompt.php133-155

For each key:

handleKeyPress() processes the key and updates state
render() updates the terminal display
Special keys (CTRL_C, CTRL_U) trigger cancellation or reversion
Returning false from handleKeyPress() signals completion

Terminal Dimensions

Before each render, the terminal dimensions are refreshed:

src/Prompt.php283 src/Prompt.php300

This ensures prompts adapt to terminal resize events.

Sources: src/Prompt.php104-155 src/Prompt.php163-186 src/Prompt.php280-310

Input/Output Flow Diagram

Sources: src/Prompt.php104-161 src/Prompt.php163-186 src/Prompt.php233-240 src/Prompt.php280-310

Cursor Control

The Cursor trait provides methods for controlling cursor visibility and position.

Cursor Visibility

src/Prompt.php18 src/Prompt.php130

The cursor is hidden when rendering begins to prevent visual artifacts during frame updates. It's restored during cleanup:

src/Prompt.php445

Cursor Positioning

The rendering system uses cursor positioning to update frames in place:

src/Prompt.php304-306

These methods move the cursor to column 1, then upward by the height of the previous frame, allowing the new frame to overwrite the old one.

The Cursor trait implements these operations using ANSI escape sequences (CSI codes).

Sources: src/Prompt.php18 src/Prompt.php130 src/Prompt.php304-306 src/Prompt.php445

Erase Operations

The Erase trait provides methods for clearing parts of the terminal.

Clearing During Render Updates

src/Prompt.php19 src/Prompt.php306

The eraseDown() method clears from the cursor position to the end of the screen, ensuring old frame content doesn't remain visible when the new frame is shorter.

The Erase trait implements operations for:

Erasing from cursor to end of line
Erasing entire lines
Erasing from cursor to end of screen
Clearing the entire screen

Sources: src/Prompt.php19 src/Prompt.php306

ANSI Escape Sequences and Styling

The library uses ANSI escape sequences for terminal control and styling through several mechanisms.

Colors Trait Integration

src/Prompt.php17

The Colors trait provides methods for text and background colors, which are applied through ANSI SGR (Select Graphic Rendition) codes. See ANSI Colors and Styling for complete details.

Termwind Integration

The rendering system leverages Termwind for advanced styling through HTML-like syntax. Termwind converts high-level styling directives into ANSI escape sequences. See Termwind Integration for details.

Dimension-Aware Rendering

src/Prompt.php300-302

The rendering system queries terminal dimensions and slices the frame to fit within the visible area, preventing issues with frames taller than the terminal.

Sources: src/Prompt.php17 src/Prompt.php300-302

Signal Handling

Some prompts register signal handlers to gracefully handle interruptions.

SIGINT Handling in Progress Bars

src/Progress.php104-111

The Progress class intercepts SIGINT (Ctrl+C) to:

Set state to 'cancel'
Render the final frame showing cancellation
Exit the process

The original pcntl_async_signals setting is captured and restored:

src/Progress.php30 src/Progress.php199-206

This ensures signal handling doesn't interfere with other parts of the application after the progress bar completes.

Sources: src/Progress.php30 src/Progress.php104-111 src/Progress.php199-206