Overview

Relevant source files

• README.md
• gleam.toml
• test/event_test.gleam

This document provides a high-level introduction to the Etch library, covering its purpose, architecture, and main components. For detailed documentation on specific modules, see the Core Modules section 3. For platform-specific implementation details, see Platform Support 5.

Purpose and Scope

Etch is a terminal user interface (TUI) backend library for Gleam that provides cross-platform terminal control, event handling, and text styling capabilities. It compiles to both Erlang/BEAM and JavaScript targets, enabling TUI applications to run on multiple runtimes including Erlang, Bun, Deno, and Node.js.

Core Capabilities:

• Terminal state management: terminal.enter_raw(), terminal.exit_raw(), alternate screen control, window size queries via terminal.get_size()
• Command abstraction: All operations represented as Command type variants
• Event handling: Structured Event types for keyboard (KeyEvent), mouse (MouseEvent), focus, and resize
• Text styling: style.Color (RGB, ANSI-256, standard) and style.Attribute (bold, italic, underline)
• Cursor control: cursor.move_to(), cursor.hide(), cursor.show()

The library has zero third-party dependencies beyond gleam_stdlib, gleam_erlang, and gleam_javascript.

Sources: README.md1-9 gleam.toml1-6 gleam.toml21-24

Library Structure

The following table describes the main public modules and their responsibilities:

Module	Purpose	Key Types
etch/command	Unified command interface for all terminal operations	Command
etch/stdout	Command queue management and execution	Queue
etch/event	Event parsing, event server, and event reading	Event, KeyEvent, MouseEvent
etch/terminal	Terminal state control (raw mode, screen, dimensions)	ClearType, WindowSize
etch/cursor	Cursor positioning and visibility control	-
etch/style	Text colors and attributes	Color, Attribute

Internal modules (not part of the public API):

• etch/internal/* - Implementation details
• input/* - Platform-specific input FFI
• terminal/* - Platform-specific terminal FFI

Sources: gleam.toml8-14 README.md11-46

High-Level Architecture

System Component Diagram

Architectural Layers:

1. Application Layer: User code imports public modules (etch/stdout, etch/event, etch/terminal, etc.)
2. Public API: Six modules exposing command construction, execution, event handling, and styling
3. Internal Implementation: etch/internal/consts provides ANSI sequences, input module handles raw input parsing
4. FFI Layer: Platform-specific implementations in terminal_ffi.mjs/terminal_ffi.erl and input_ffi.mjs/event_ffi.erl
5. Runtime: All FFI implementations ultimately interact with terminal I/O (stdin/stdout/TTY device)

Data flows downward for output (commands → ANSI sequences → stdout) and upward for input (stdin → parsed events → application).

Sources: gleam.toml6-17 gleam.toml8-12 README.md7-9 src/etch/command.gleam1-9 src/etch/stdout.gleam1-10

Module Dependency Graph

Dependency Relationships Between Modules

Key Dependencies:

• etch/stdout: Orchestrates all other modules, depends on command, style, cursor, terminal, event
• etch/command: Aggregates types from specialized modules (cursor, style, terminal, event)
• etch/internal/consts: Provides ANSI escape sequence constants to cursor, style, terminal
• input module: Hidden internal module that interfaces with input_ffi.mjs, event_ffi.erl, signal_handler.erl
• FFI layer: Platform-specific implementations in .erl (Erlang) and .mjs (JavaScript) files

The stdout module acts as the primary coordinator, while command serves as the type aggregator. Internal modules are marked non-public via internal_modules in gleam.toml.

Sources: gleam.toml8-14 gleam.toml21-24 src/etch/command.gleam1-9 src/etch/stdout.gleam1-27

Platform Support Matrix

Target	Primary Runtime	Raw Mode	Event Loop	Mouse Support	Build Command
JavaScript	Bun	✓	Promise-based	✓	gleam build
JavaScript	Deno	✓	Promise-based	✓	gleam build
JavaScript	Node.js	✓	Promise-based	✓	gleam build
Erlang	BEAM	✓	Process-based	✓	gleam build --target erlang

Platform-specific code is selected at compile time using @target annotations:

@target(erlang)
pub fn init_event_server() -> Result(Subject(EventMessage), String)

@target(javascript)
pub fn init_event_server() -> Result(Subject(EventMessage), String)

Sources: gleam.toml6-17 README.md98-163 test/etch_test.gleam8-28

Command Execution Model

Command Processing Flow

Execution Strategies:

1. Immediate Execution: stdout.execute(commands: List(Command)) - Directly calls flush_inner() and writes to stdout immediately
2. Batched Execution: Create Queue([]), call queue(q, commands) repeatedly to accumulate, then flush(queue) - More efficient for multiple operations

Implementation Details:

• flush_inner() at src/etch/stdout.gleam53-166 pattern-matches each Command variant
• Each command type delegates to specialized modules (style, cursor, terminal) to generate ANSI escape sequences
• string_builder (via StringTree) accumulates sequences with O(1) append operations
• Final output is a single io.print() call, minimizing I/O and reducing flicker

Sources: README.md50-77 src/etch/stdout.gleam35-51 src/etch/stdout.gleam53-166

Event Processing Architecture

Event Pipeline from Terminal to Application

Event Processing Flow:

1. Initialization: event.init_event_server() at src/etch/event.gleam137-158 spawns background process and returns Subject(EventMessage)
2. Input Loop: input_loop() continuously calls input_ffi.get_chars() to read raw bytes from stdin in raw mode
3. Parsing: parse_events() at src/etch/event.gleam160-296 interprets escape sequences
4. Routing: handle_escape_code() routes to specialized parsers based on sequence format
5. Specialized Parsing:
   • Keyboard: parse_u_encoded_key_code(), parse_special_key_code(), parse_modifier_key_code()
   • Mouse: parse_normal_mouse(), parse_sgr_mouse(), parse_rxvt_mouse() (supports 3 mouse protocols)
   • Focus: Focus gained/lost events
6. Buffering: Parsed events stored in Subject(EventMessage) queue
7. Consumption: Applications call event.poll(timeout) (non-blocking) or event.read() (blocking)

Supported Event Types: KeyEvent, MouseEvent, FocusGained, FocusLost, Resize(width, height), CursorPosition(row, col)

Sources: src/etch/event.gleam137-158 src/etch/event.gleam160-296 test/event_test.gleam19-96 test/event_test.gleam311-331

Key Design Decisions

Command-Based API

All terminal operations are represented as data (Command variants) rather than being executed immediately. This enables:

• Batching multiple operations for performance
• Testing command generation without I/O
• Composing command sequences programmatically

Sources: README.md43-46 src/etch/command.gleam3-11

Cross-Platform Compilation

Etch uses Gleam's multi-target compilation with platform-specific FFI implementations:

• Erlang: Uses shell:start_interactive, ETS tables for state, process-based concurrency
• JavaScript: Uses process.stdin.setRawMode(), Promises for async, Result types for errors

The same high-level API compiles to platform-appropriate implementations.

Sources: gleam.toml6-22 src/terminal/terminal_ffi.erl5-8 src/terminal/terminal_ffi.mjs7-19

Zero External Dependencies

Etch depends only on Gleam's official platform libraries:

• gleam_stdlib (>= 0.44.0) - core types and functions
• gleam_erlang (>= 1.3.0) - Erlang/BEAM platform integration
• gleam_javascript (>= 1.0.0) - JavaScript runtime integration

No third-party terminal libraries are used. All ANSI sequence generation (in etch/internal/consts) and escape code parsing (in event.parse_events()) is implemented directly in Gleam.

Sources: gleam.toml21-24 README.md8

Internal Module Encapsulation

Implementation details are hidden via internal_modules configuration in gleam.toml, preventing users from depending on unstable internals:

These modules (etch/internal/consts, input, terminal) provide ANSI sequence constants and FFI bridge code but are not part of the public API. Only the six documented public modules are stable:

Public Module	Key Functions/Types
etch/stdout	execute(), queue(), flush(), Queue
etch/event	init_event_server(), poll(), read(), Event, KeyEvent, MouseEvent
etch/terminal	enter_raw(), exit_raw(), get_size(), ClearType
etch/command	Command type with all variants
etch/style	Color, Attribute, rgb(), ansi()
etch/cursor	move_to(), hide(), show(), save(), restore()

Sources: gleam.toml8-12 README.md11-46

Example Usage

Basic Terminal Application Structure:

Typical Application Lifecycle:

1. Setup: Enter raw mode, alternate screen, hide cursor
2. Event Loop: Read events, update state, queue rendering commands, flush
3. Cleanup: Restore cursor, leave alternate screen, exit raw mode

See dev/examples/hello_world.gleam and dev/examples/snake.gleam for complete examples.

Sources: README.md50-78 README.md81-93

Next Steps

• For basic usage tutorials, see Getting Started 2
• For detailed module documentation, see Core Modules 3
• For building interactive applications, see Building Interactive Applications 4
• For platform-specific details, see Platform Support 5