Module terminal_capabilities 

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)

1. 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.

2. Scroll region safety: use_scroll_region() returns false in multiplexers because DECSTBM behavior varies across versions.

3. Capability monotonicity: Once a capability is detected as absent, it remains absent for the session. We never upgrade capabilities.

4. Fallback ordering: Capabilities degrade in this order: sync_output → scroll_region → overlay_redraw

5. 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.