delta

This README is the one indexed from the repository at its latest ref, not from the tag for this version.

---

Real-Time GTK4/Libadwaita Text Streaming Viewer for GNOME

Delta (Δ) is a high-performance, native GNOME text streaming viewer built in Crystal. Designed strictly around GNOME Human Interface Guidelines (HIG) and Libadwaita, Delta enables developers and sysadmins to inspect live log streams, piped CLI compiler outputs, and watched disk files with Myers diff calculations, 10-step temporal decay visual fading, live regex filtering, ANSI truecolor parsing, and non-blocking asynchronous event-driven I/O.

---

✨ Features

• Universal Stream Ingestion (STDIN / FIFOs / Files): Direct asynchronous ingestion from standard input (-), named pipes, and external log files ([FUNC-006], [TECH-006]).
• Temporal Decay Diff Highlighting: File updates are processed through a line-level Myers diff engine; new and edited lines flash with vibrant accents and smoothly fade to base text over 3 seconds ([FUNC-002], [TECH-003]).
• Smart Follow Mode with Scroll Detachment: Auto-scrolls to the bottom on append, automatically pausing when you scroll up or select text, with a floating action pill to resume follow mode ([FUNC-004], [TECH-005]).
• Live Search, Match Navigation & Line Filtering (Ctrl+F, Alt+L): Floating search overlay with instant PCRE2 regex evaluation, case-sensitivity, sequential match cycling (Enter / Shift+Enter) with "X of Y" match indexing, and a live Line Filter mode (Alt+L) to hide non-matching lines dynamically in real-time streams ([FUNC-005], [TECH-005]).
• Soft Text Wrapping Toggle (Alt+Z, --wrap/--no-wrap): Toggle soft line wrapping on the fly via the HeaderBar or keyboard shortcut without line truncation ([FUNC-004], [TECH-005]).
• ANSI Terminal 24-bit Truecolor & Style Parser: Decodes ECMA-48 SGR terminal escape sequences (16 colors, 256 colors, RGB truecolor, bold, italic, underline) into GtkTextTag ranges while stripping escape codes from raw text storage for clean clipboard copying ([FUNC-005], [TECH-006]).
• 270+ Language Syntax Highlighting: Native lexing powered by Tartrazine with Catppuccin theming and automatic file extension detection ([ADR-003]).
• Circular Ring-Buffer Memory Guard (--max-lines): Configurable buffer line cap (default: 50,000 lines) that automatically trims excess lines from the top to ensure bounded memory usage during infinite stream runs ([TECH-006]).
• Bulletproof UTF-8 Sanitizer: Sanitizes raw binary chunks using GLib g_utf8_make_valid to eliminate crashes on corrupted system logs ([TECH-004]).
• Dedicated Pure Viewer Architecture: Buffer locked against keyboard typing (editable = false) while retaining full keyboard cursor navigation, text selection, and copy ergonomics ([ADR-004]).

---

💻 Quick Usage Examples

# Stream live system journal with initial regex filter
journalctl -f | delta --filter="kernel|systemd" -

# Stream kernel/syslog messages
sudo tail -f /var/log/messages | delta -

# Stream colorful test runner output with text wrapping enabled
crystal spec --verbose | delta --wrap -

# Watch a file on disk with follow mode and 10,000 line ring-buffer
delta --follow --max-lines=10000 /var/log/nginx/access.log

---

🏗️ Architecture & Technology Stack

• Language: Crystal (v1.21.0+)
• GUI Toolkit: GTK4 & Libadwaita via gi-crystal
• Syntax Highlighting: Tartrazine (Pure Crystal Pygments/Chroma lexer)
• Concurrency: GLib-native event loop scheduling (GLib.timeout & GLib.idle_add)
• Diff Algorithm: Non-blocking line-level Myers diff engine (Delta::DiffEngine)

---

🚀 Getting Started

Prerequisites (Fedora Linux)

sudo dnf install crystal shards gtk4-devel libadwaita-devel gtksourceview5-devel gobject-introspection-devel

Building from Source

# Clone the repository
git clone https://gitlab.com/renich/delta.git
cd delta

# Build development binary (bin/delta)
make build

# Build optimized release binary (bin/delta)
make release

# Build static binary via container (bin/delta)
make static

# Run Delta
./bin/delta [file_path]

Quality Assurance & Linting

# Run spec suite
make spec

# Run Ameba static analysis
make lint

# Auto-format codebase
make format

---

📚 Documentation

Detailed modular specifications, architectural blueprints, and roadmaps are maintained in docs/:

• Master Documentation Index
• Functional Specifications
• Technical Specifications
• Project Roadmap
• Architecture Decision Records (ADRs)

---

🤝 Ethical Commitment

Delta strictly adheres to the Universal Code of Honor, prioritizing human welfare, transparency, user data sovereignty, and engineering excellence.

---

💖 Supporting the Project

If you find Delta valuable for your daily development, log inspection, or text streaming workflows, consider sponsoring the author:

You can also sponsor Rénich Bon Ćirić directly on Liberapay (renich).

---

📜 License & Authors

• Code License: GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later)
• Documentation License: GNU Free Documentation License v1.3 or later (GFDL-1.3-or-later)
• Author: Rénich Bon Ćirić <renich@woralelandia.com> | woralelandia.com