libtermy

libtermy is the embeddable Termy terminal engine. The first cut is split into:

• termy_core — Rust API for a single headless terminal surface.
• termy_ffi — C ABI wrapper over termy_core.

The core API owns PTY startup, terminal parsing, input writes, resize, event draining, damage snapshots, and renderer-neutral frame snapshots. It does not depend on GPUI and does not expose Termy's app chrome, tabs, panes, or tmux session model as part of the public v1 surface.

termy_core can also load Termy's normal config format through the existing headless termy_config_core parser. Config loading returns the full parsed AppConfig, parse diagnostics, and a TerminalRuntimeConfig ready to pass into terminal creation. Missing default config files fall back to defaults without creating files; explicit missing paths are reported as load errors.

Rust Embedding

Use termy_core::Terminal directly:

let loaded_config = termy_core::load_config_from_default_path()?;
let cell_metrics = termy_core::measure_cell_from_config(&loaded_config.app_config);
let terminal = termy_core::Terminal::new(
    termy_core::TerminalSize {
        cols: 80,
        rows: 24,
        cell_width: cell_metrics.cell_width,
        cell_height: cell_metrics.cell_height,
    },
    None,
    None,
    None,
    Some(&loaded_config.runtime_config),
    None,
)?;
terminal.write(b"echo hello\r");
let frame = terminal.snapshot();

TermyFrame contains a flat row-major Vec<TermyCell>, cursor state, scroll state, and cell colors as simple RGBA bytes.

Use termy_core::measure_cell(font_family, font_size, line_height) or termy_core::measure_cell_from_config(&app_config) to derive the TerminalSize cell width and height from Termy's font metrics instead of guessing a monospace ratio in the host app.

C ABI

Use termy_ffi as an opaque-handle API:

• crates/ffi/include/termy.h
• termy_config_load_default
• termy_config_load_path
• termy_config_from_contents
• termy_config_free
• termy_terminal_new_with_config
• termy_terminal_new
• termy_terminal_free
• termy_terminal_write
• termy_terminal_resize
• termy_terminal_snapshot
• termy_frame_free
• termy_terminal_take_damage
• termy_damage_free
• termy_terminal_drain_events
• termy_event_batch_free
• termy_terminal_search
• termy_search_batch_free

Any returned frame, damage, event batch, search batch, or standalone byte payload must be released by the matching termy_*_free function. Event payloads owned by an event batch are freed by termy_event_batch_free; do not free them separately. Search match line payloads owned by a search batch are freed by termy_search_batch_free.

Embedders should synchronize access to a terminal handle if they call into it from multiple threads.

Config Diagnostics

Config diagnostics are available through termy_config_diagnostics and must be released with termy_config_diagnostics_free.

Render Config

Renderer-facing config values are available through termy_config_render_config and must be released with termy_render_config_free. This returns the parsed font family, font size, line height, padding, background opacity, cursor blink, cursor style, and measured cell width/height so non-Rust embedders can render the terminal with the same user config that was passed into termy_terminal_new_with_config.

Event Kinds

Progress States

Cursor Styles

Search

Search returns visible-frame matches only. Each TermyFfiSearchMatch reports the row, inclusive start and end columns, and the visible line text that matched.

The C ABI header is at crates/ffi/include/termy.h.