par-term-emu-tui-rust 0.5.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.5.0

Interactive Configuration Editor

• Tabbed Configuration Screen: Press Alt+Ctrl+Shift+C to access comprehensive configuration UI
  • Settings Tab: Widget-based form editor with organized sections
    • 15 configuration categories with proper input widgets (checkboxes, selects, number inputs)
    • Immediate validation and type checking
    • Descriptive labels and help text for all options
  • Raw YAML Tab: Direct YAML editing with syntax highlighting
    • Full access to all configuration options
    • Real-time syntax validation
  • Automatic Backup: Creates timestamped backup before saving changes
  • Restart Reminder: Toast notification reminds user to restart after changes

Terminal Session Recording

• Record Terminal Sessions: Capture all terminal activity with Ctrl+Shift+R
  • Recording indicator (⏺️) in header shows active status
  • Start/stop recording with single keypress
• Multiple Export Formats:
  • Asciicast (.cast) - Compatible with asciinema players
  • JSON (.json) - Raw event data for custom processing
• Smart Directory Selection:
  1. Configured recording_directory (if set)
  2. Shell's current working directory (from OSC 7)
  3. XDG_VIDEOS_DIR/Recordings or ~/Videos/Recordings
  4. Home directory fallback
• Auto-Export: Optionally export recording immediately when stopped
• Customizable Titles: Template-based titles with {timestamp} placeholder
• Optional Auto-Open: Launch recording in default application after export

Backend Integration Enhancements

• Native Notification Control: TUI configuration now surfaces Rust backend notification settings
  • Bell sound volume (0-100)
  • Desktop notifications
  • Visual bell overlay
  • Activity/silence detection thresholds
  • Max notification buffer size
• Clipboard Limits: Configure backend clipboard sync event limits
  • Max sync events retained
  • Max bytes per event
• Shell Integration Stats: Status bar displays shell command statistics
  • Total commands executed
  • Failed command count
  • Average command duration

See CHANGELOG.md for previous releases.

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)
• Interactive Configuration - Tabbed UI with widget-based and raw YAML editing modes
• Session Recording - Record terminal sessions to asciicast or JSON with auto-export
• 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 and backend integration
• Shell Integration - Working directory tracking, prompt navigation, command statistics
• 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 and configurable limits
• 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

• Changelog - Version history and release notes
• Features - Complete feature descriptions
• Key Bindings - Keyboard shortcuts and mouse actions
• Configuration Reference - All 57 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+R	Toggle recording
Ctrl+Shift+C	Copy selection
Alt+Ctrl+Shift+C	Open configuration editor
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)
faint_text_alpha: 0.5            # Faint text alpha (0.0=hidden, 1.0=normal)

# Scrollback
scrollback_lines: 10000

# Clipboard
auto_copy_selection: true
middle_click_paste: true

# Screenshots
screenshot_format: "png"
screenshot_minimum_contrast: null # Screenshot contrast (null=inherits 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)