par-term-emu-tui-rust 0.2.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.2.0

Code Quality & Testing

• Fixed all lint errors (22 → 0) and achieved 100% type checking compliance
• Enhanced test suite reliability with all 20 tests passing
• Added pytest-asyncio support for async clipboard tests
• 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
• 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
• Themes - 12 built-in themes with custom theme support
• Clipboard - Cross-platform copy/paste with OSC 52 support

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 configuration options
• 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
theme: "dark-background"

# Scrollback
scrollback_lines: 10000

# Clipboard
auto_copy_selection: true
middle_click_paste: true

# Screenshots
screenshot_format: "png"

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)