Module terminal_capabilities

Expand description

Terminal capability detection model with tear-free output strategies.

This module provides detection of terminal capabilities to inform how ftui behaves on different terminals. Detection is based on environment variables and known terminal program identification.

§Capability Profiles (bd-k4lj.2)

In addition to runtime detection, this module provides predefined terminal profiles for testing and simulation. Each profile represents a known terminal configuration with its expected capabilities.

§Predefined Profiles

Profile	Description
`xterm_256color()`	Standard xterm with 256-color support
`xterm()`	Basic xterm with 16 colors
`vt100()`	VT100 terminal (minimal features)
`dumb()`	Dumb terminal (no capabilities)
`screen()`	GNU Screen multiplexer
`tmux()`	tmux multiplexer
`windows_console()`	Windows Console Host
`modern()`	Modern terminal with all features

§Profile Builder

For custom configurations, use CapabilityProfileBuilder:

use ftui_core::terminal_capabilities::CapabilityProfileBuilder;

let custom = CapabilityProfileBuilder::new()
    .colors_256(true)
    .true_color(true)
    .mouse_sgr(true)
    .build();

§Profile Switching

Profiles can be identified by name for dynamic switching in tests:

use ftui_core::terminal_capabilities::TerminalCapabilities;

let profile = TerminalCapabilities::xterm_256color();
assert_eq!(profile.profile_name(), Some("xterm-256color"));

Override detection in tests by setting FTUI_TEST_PROFILE to a known profile name (for example: dumb, screen, tmux, windows-console).

§Detection Strategy

We detect capabilities using:

COLORTERM: truecolor/24bit support
TERM: terminal type (kitty, xterm-256color, etc.)
TERM_PROGRAM: specific terminal (iTerm.app, WezTerm, Alacritty, Ghostty)
NO_COLOR: de-facto standard for disabling color
TMUX, STY, ZELLIJ, WEZTERM_UNIX_SOCKET, WEZTERM_PANE: multiplexer detection
KITTY_WINDOW_ID: Kitty terminal detection

§Invariants (bd-1rz0.6)

Sync-output safety: use_sync_output() returns false for any multiplexer environment (tmux, screen, zellij, wezterm mux) because CSI ?2026 h/l sequences are unreliable through passthrough. Detection also hard-disables synchronized output in WezTerm sessions as a safety fallback.
Scroll region safety: use_scroll_region() returns false in multiplexers because DECSTBM behavior varies across versions.
Capability monotonicity: Once a capability is detected as absent, it remains absent for the session. We never upgrade capabilities.
Fallback ordering: Capabilities degrade in this order: sync_output → scroll_region → overlay_redraw
Detection determinism: Given the same environment variables, TerminalCapabilities::detect() always produces the same result.

§Failure Modes

Mode	Condition	Fallback Behavior
Dumb terminal	`TERM=dumb` or empty	All advanced features disabled
Unknown mux	Nested or chained mux	Conservative: disable sync/scroll
False positive mux	Non-mux with `TMUX` env	Unnecessary fallback (safe)
Missing env vars	Env cleared by parent	Conservative defaults
Conflicting signals	e.g., modern term inside screen	Mux detection wins

§Decision Rules

The policy methods (use_sync_output(), use_scroll_region(), etc.) implement an evidence-based decision rule:

IF in_any_mux() THEN disable_advanced_features
ELSE IF capability_detected THEN enable_feature
ELSE use_conservative_default

This fail-safe approach means false negatives (disabling a feature that would work) are preferred over false positives (enabling a feature that corrupts output).

§Future: Runtime Probing

Optional feature-gated probing may be added for:

Device attribute queries (DA)
OSC queries for capabilities
Must be bounded with timeouts

Structs§

CapabilityProfileBuilder: Builder for custom terminal capability profiles.
SharedCapabilities: Wait-free shared terminal capabilities for concurrent read/write.
TerminalCapabilities: Terminal capability model.

Enums§

TerminalProfile: Known terminal profile identifiers.