par-term-emu-tui-rust 0.4.0

Textual-based TUI demonstration of par-term-emu-tui-rust terminal emulator

Par Term Emu TUI Rust

A modern terminal emulator TUI built with Textual and par-term-emu-core-rust, featuring efficient rendering, comprehensive ANSI support, and advanced terminal features.

What's New in v0.4.0

Enhanced Configuration Management

• Automatic Config Backup: Every config save creates timestamped backup (config.yaml.backup.YYYYMMDD_HHMMSS)
• Interactive Recovery: When config parsing fails, prompts for recovery options:
  • Reset to defaults
  • Restore from backup
  • View all available backups
  • Exit gracefully
• Comprehensive Validation: All config values validated for proper types, ranges, and formats
  • Numeric values (int/float) properly converted from YAML strings
  • Range clamping for float values (0.0-1.0) like minimum_contrast
  • Positive/non-negative validation for numeric settings
  • RGB tuple validation for color values
  • Enum validation for theme and screenshot format settings
• Config UI Improvements: Optimized widget widths for better layout
• Restart Notification: Toast message after saving config reminds user to restart TUI
• Bold Brightening Default: Changed bold_brightening default from true to false for better color accuracy

Configuration Safety

# Before save: automatic backup created
# ~/.config/par-term-emu-tui-rust/config.yaml.backup.20250118_143022

# Invalid values automatically clamped/corrected
minimum_contrast: 1.5  # Automatically clamped to 1.0
scrollback_lines: -100  # Automatically corrected to 0

# Parse failures trigger interactive recovery:
# 1. Reset to defaults
# 2. Restore from backup
# 3. View all backups
# 4. Exit

Previous Release (v0.3.1)

New Color System Features

• Automatic Contrast Adjustment: iTerm2-compatible minimum contrast system

  • minimum_contrast (0.0-1.0) - Automatic contrast adjustment for live terminal display
  • screenshot_minimum_contrast (0.0-1.0) - Independent contrast setting for screenshots
  • Uses NTSC perceived brightness formula for accurate readability
  • Range: 0.0 (disabled, default) to 1.0 (maximum contrast)
  • Recommended: 0.5 for moderate readability improvements
  • Ensures text remains readable on any background color

• Bold Text Brightening: Enhanced bold text rendering

  • bold_brightening (default: false) - Use bright ANSI colors (8-15) for bold text with normal colors (0-7)
  • Matches iTerm2's "Use Bright Bold" setting
  • When enabled: Bold red (1) automatically renders as bright red (9)
  • When disabled: Bold text uses original color without brightening

Configuration Example

# Live terminal contrast adjustment
minimum_contrast: 0.5  # Moderate contrast for display

# Screenshot-specific contrast (overrides minimum_contrast for screenshots)
screenshot_minimum_contrast: 0.7  # Higher contrast for screenshots

# Bold text appearance
bold_brightening: false  # Use original colors for bold text

Previous Release (v0.3.0)

• Visual Bell Flash: Animated bell icon overlay when terminal receives BEL character (🔔)
• Install Command Discoverability: install subcommand now visible in --help output
• KITTY Keyboard Protocol Documentation: Comprehensive guide for enhanced keyboard handling
• Configuration Expansion: 39 configuration options (up from 30) including new color system features

Improvements

• Better CLI Help: Install subcommand now visible in main help output
• Enhanced Documentation: All docs updated to reference install command and new features
• Code Organization: Added BellFlash widget for visual bell feedback

Documentation

• New KEYBOARD_PROTOCOL.md - Complete KITTY protocol guide
• Enhanced USAGE.md - Install command now documented
• Updated CLAUDE.md - Installation commands reference added
• Updated all documentation to reflect new scrolling default

Previous Release (v0.2.0)

• Fixed all lint errors (22 → 0) and achieved 100% type checking compliance
• Enhanced test suite reliability with all 20 tests passing
• Added KITTY keyboard protocol support with auto-detection
• Improved code consistency and type safety across codebase

Quick Start

# Clone and install
git clone https://github.com/paulrobello/par-term-emu-tui-rust.git
cd par-term-emu-tui-rust
uv sync

# Install components (recommended)
par-term-emu-tui-rust install all

# Run the TUI
make run

See the Quick Start Guide for detailed instructions.

Features

• Efficient Rendering - Textual Line API for optimal performance
• Full ANSI Support - 16/256/true color, bold, italic, underline, and more
• Advanced Color System - Bold brightening and automatic contrast adjustment (iTerm2-compatible)
• Scrollback Buffer - Navigate history with keyboard and mouse
• Mouse Support - Text selection, clickable URLs, and mouse tracking
• Hyperlinks - OSC 8 hyperlinks and auto-detected plain text URLs
• Notifications - OSC 9/777 notification support with toast messages
• Shell Integration - Working directory tracking, prompt navigation
• Screenshots - Multiple formats (PNG, SVG, HTML) with auto-capture and contrast control
• Themes - 12 built-in themes with custom theme support
• Clipboard - Cross-platform copy/paste with OSC 52 support
• KITTY Protocol - Enhanced keyboard protocol with auto-detection

See Features for complete feature documentation.

Documentation

Getting Started

• Quick Start Guide - Get up and running in 5 minutes
• Installation Guide - Detailed installation instructions
• Usage Guide - Command-line options and workflows

Reference

• Features - Complete feature descriptions
• Key Bindings - Keyboard shortcuts and mouse actions
• Configuration Reference - All 39 configuration options
• Themes Guide - Theme system and 12 built-in themes
• Screenshots Guide - Screenshot functionality

Advanced

• Architecture - System design and implementation
• Debug Guide - Debugging and development
• Troubleshooting - Common issues and solutions
• Contributing - Development setup and guidelines

Installation

Prerequisites

• Python 3.12 or higher
• uv package manager
• Terminal with true color support

Install from Source

# Clone repository
git clone https://github.com/paulrobello/par-term-emu-tui-rust.git
cd par-term-emu-tui-rust

# Install dependencies
uv sync

# Install all components
par-term-emu-tui-rust install all

See Installation Guide for detailed instructions.

Basic Usage

# Run with default shell
par-term-emu-tui-rust

# Use custom shell
par-term-emu-tui-rust --shell /bin/zsh

# Apply theme
par-term-emu-tui-rust --theme solarized-dark

# Take screenshot
par-term-emu-tui-rust --screenshot 3 --auto-quit 5

Key Bindings

Shortcut	Action
Ctrl+Shift+Q	Quit application
Ctrl+Shift+S	Take screenshot
Ctrl+Shift+C	Copy selection
Shift+PageUp/Down	Scroll history
Shift+Home/End	Jump to top/bottom

See Key Bindings for complete reference.

Configuration

Configuration file location: ~/.config/par-term-emu-tui-rust/config.yaml

Create default configuration:

par-term-emu-tui-rust --init-config

Essential settings:

# Theme & Colors
theme: "dark-background"
bold_brightening: false          # Use bright colors for bold text
minimum_contrast: 0.0            # Display contrast (0.0=off, 0.5=moderate, 1.0=max)

# Scrollback
scrollback_lines: 10000

# Clipboard
auto_copy_selection: true
middle_click_paste: true

# Screenshots
screenshot_format: "png"
screenshot_minimum_contrast: 0.0  # Screenshot contrast (overrides minimum_contrast)

# Keyboard Protocol
keyboard_protocol_enabled: false
keyboard_protocol_auto_detect: false

See Configuration Reference for all options.

Technology

• Python 3.12+ - Application logic
• Textual - TUI framework
• par-term-emu-core-rust - Terminal emulation (Rust)
• PyYAML - Configuration
• pyperclip - Clipboard support
• xdg-base-dirs - XDG compliance

Security & Safety Notes

Par Term Emu TUI Rust aims to provide sensible, configurable defaults for potentially sensitive features:

• Clipboard access (OSC 52) Controlled by expose_system_clipboard:

  • When true (default), terminal applications can read/write the system clipboard via OSC 52 escape sequences.
  • When false, clipboard reads from applications are blocked.

• Clickable URLs Clickable links (OSC 8 and auto-detected plain URLs) are allowed only for configured schemes:

  • allowed_url_schemes defaults to: http, https, ftp, ftps, file, mailto.
  • Unknown/unsupported schemes are blocked; when warn_on_unknown_url_scheme is true, a non-fatal warning is shown in the TUI instead of opening the link.

• Escape sequence safety Some sequences can be powerful (and potentially dangerous). You can harden behavior with:

  • disable_insecure_sequences: when true, the Rust core filters out escape sequences considered risky.

See the Configuration Reference for details and recommended values for locked-down environments.

Architecture

graph TD
    App[TerminalApp]
    Widget[TerminalWidget]
    Core[Terminal Core Rust]
    Render[Rendering Engine]
    Display[Display]

    App --> Widget
    Widget --> Core
    Core --> Render
    Render --> Display

    style App fill:#e65100,stroke:#ff9800,stroke-width:3px,color:#ffffff
    style Widget fill:#1b5e20,stroke:#4caf50,stroke-width:2px,color:#ffffff
    style Core fill:#0d47a1,stroke:#2196f3,stroke-width:2px,color:#ffffff
    style Render fill:#4a148c,stroke:#9c27b0,stroke-width:2px,color:#ffffff
    style Display fill:#880e4f,stroke:#c2185b,stroke-width:2px,color:#ffffff

See Architecture for detailed system design.

Contributing

Contributions are welcome! Please read the Contributing Guide for:

• Development setup
• Code quality standards
• Testing requirements
• Pull request process

Development Setup

# Clone repository
git clone https://github.com/paulrobello/par-term-emu-tui-rust.git
cd par-term-emu-tui-rust

# Install dependencies
uv sync

# Install pre-commit hooks
uv run pre-commit install

# Run quality checks
make checkall

Resources

• GitHub Repository
• Issue Tracker
• Discussions
• Textual Documentation
• par-term-emu-core-rust

Troubleshooting

For common issues and solutions, see the Troubleshooting Guide.

Quick diagnostics:

# Enable debug logging
par-term-emu-tui-rust --debug

# Test with minimal config
par-term-emu-tui-rust --auto-quit 2

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Paul Robello - [e-mail]

Acknowledgments

• Built with Textual
• Terminal emulation by par-term-emu-core-rust
• Inspired by modern terminal emulators (iTerm2, Alacritty, Wezterm)