phoenix-tui/phoenix
71.4
Strong · 8 November 2026
37.7k
lines of production code
Go
primary language
5
measurements over time
What this system is
Phoenix TUI is a Go framework for building terminal user interfaces that supports cross-platform input handling, including mouse interactions and clipboard access. It provides a rendering engine with differential updates and a theming system, alongside reusable UI components like forms and dialogs. The system also includes utilities for hybrid CLI/TUI applications and automated performance benchmarking.
Features
ExecProcess now safely manages terminal state and supports foreground TTY control
The \ExecProcess\ method now ensures the terminal exits raw mode and alt screen before running an external command and restores them afterward, preventing the TUI from being left in a broken state if the command fails. Additionally, a new \ExecProcessWithTTY\ API (with platform-specific implementations for Linux, macOS, and Windows) allows transferring foreground process group control to the child process, enabling proper job control (e.g., Ctrl+Z) for nested shells or interactive commands.
tea · high confidence
Initial mouse input support with click, drag, and hover detection
The Phoenix TUI framework now includes a dedicated mouse subsystem that parses raw terminal mouse sequences (SGR, X10, and URxvt protocols) and enriches them with high-level semantics. Users can now detect single, double, and triple clicks, track drag operations with configurable thresholds, and receive hover events (enter, leave, move) for specific UI components. The system also handles scroll wheel input and automatically positions context menus to ensure they remain visible within the terminal bounds.
mouse · high confidence
Initial release of the Phoenix TUI rendering engine
The \render\ package introduces the core terminal rendering engine for Phoenix TUI. It provides a \Renderer\ that performs differential rendering to minimize terminal output by comparing buffers and emitting only changed cells. The system includes a \Buffer\ model for managing 2D cell grids with correct Unicode grapheme cluster handling (using \uniseg\), a \Cell\ type for character and style data, and an \OptimizeService\ to reduce redundant ANSI sequences. It also defines value types for \Color\ (RGB to ANSI 256 conversion) and \Style\ (foreground/background, bold, italic, etc.), along with comprehensive tests for all components.
render · high confidence
Initial release of the Phoenix Terminal framework with cross-platform support
The terminal package is introduced as a new component, providing a unified API for terminal manipulation that automatically selects the appropriate backend based on the operating system. On Unix-like systems (Linux, macOS, WSL), it uses ANSI escape codes via the \unix\ package, while on Windows, it leverages the native Windows Console API via the \windows\ package for higher performance and features like cursor readback. The implementation includes comprehensive test coverage for cursor positioning, raw mode lifecycle, alternate screen buffer management, and thread safety, along with benchmarks comparing ANSI and Windows API performance.
terminal · high confidence
Introduce cross-platform clipboard support with history and rich text capabilities
The Phoenix TUI framework now includes a new \clipboard\ package that provides unified clipboard access across Windows, macOS, and Linux, with automatic fallback to OSC 52 escape sequences for SSH and remote sessions. Users can read and write plain text, HTML, and RTF content, and optionally enable a configurable clipboard history manager to track, view, and restore previous clipboard entries. The package includes a builder API for custom configuration and supports image format detection and conversion, though full image copy/paste operations are currently limited to native providers.
clipboard · high confidence
New Confirm and Form components added to the UI library
The components package now includes two new interactive UI widgets: a Confirm dialog and a Form container. The Confirm component provides a Yes/No/Cancel dialog with configurable button labels, keyboard navigation (arrows, Tab, Enter, Escape), and safe defaults (No focused by default for dangerous actions). The Form component allows grouping multiple fields with Tab/Shift+Tab navigation, real-time validation, and submission handling via a SubmitMsg. Both components follow the Elm Architecture pattern (tea.Model) and include comprehensive test coverage.
components · high confidence
New Phoenix TUI example applications for hybrid CLI, mouse interaction, and drag scrolling
Added several new example applications in the \examples/\ directory to demonstrate Phoenix TUI capabilities. The \cobra-cli\ example shows a hybrid CLI/TUI pattern using the Cobra library, allowing tools to switch between scriptable flag-based modes and interactive TUI modes. The \context-menu\ example demonstrates smart edge-detection positioning for popup menus using the \phoenix/mouse\ module. The \drag-scroll\ example illustrates click-and-drag scrolling within the Viewport component. The \hover-highlight\ example provides a comprehensive demo of mouse hover detection, bounding box definitions, and visual feedback for interactive buttons, including associated unit tests. Finally, the \umbrella\ example showcases the convenience API provided by the Phoenix umbrella module.
examples · high confidence
New Theme System with Presets and Runtime Switching
The style module now includes a comprehensive theme system that allows users to define and switch visual identities at runtime. This change introduces four built-in presets—Default, Dark, Light, and HighContrast—along with the ability to create custom themes by specifying color palettes, border styles, spacing scales, and typography settings. A thread-safe ThemeManager enables switching between these themes dynamically, supporting both full replacements and partial overrides (inheritance) to customize specific aspects like primary colors without replacing the entire theme. The system also provides utilities for looking up themes by name and listing all available presets.
style · high confidence
New automated performance benchmarking system with regression tracking
The benchmarks directory now includes a complete performance tracking system for Phoenix TUI, featuring automation scripts to run, compare, and baseline render and Unicode benchmarks. Users and contributors can execute \run\_benchmarks.sh\ to capture current performance metrics and use \compare.sh\ with \benchstat\ to detect regressions against a stable baseline. The system enforces strict performance standards (e.g., 60 FPS target, zero allocations) and includes historical result storage for release milestones. Additionally, comparison tests against libraries like Lipgloss and go-runewidth have been moved into this dedicated benchmarking structure.
benchmarks · high confidence
New release automation and validation scripts
Added a suite of shell scripts to streamline the release process and maintain code quality: bump-versions.sh updates cross-module Go dependencies to a target version; create-release-tags.sh generates the 11 required Git tags (one per module plus the root); lint\_all.sh runs golangci-lint across all 10 modules; fix\_godot.sh corrects comment formatting to satisfy linters; and pre-release-check.sh performs comprehensive validation including Go version checks, formatting, vetting, cross-compilation checks, builds, and tests (with optional WSL2 race detection).
scripts · high confidence
Phoenix TUI Framework v0.2.4: InlineRenderer and Windows stability fixes
This release introduces the InlineRenderer for the tea (Elm Architecture) module, enabling non-alt-screen rendering with per-line diffing, ANSI-preserving width truncation, and height clipping. The Program now integrates this renderer with lazy initialization and automatic window size forwarding. Additionally, six flaky inputReader tests on Windows have been fixed by replacing race-prone checks with a generation counter, and all documentation has been updated to be version-agnostic.
(repo-wide) · high confidence
Behavioural changes
Core package restructure and Unicode width accuracy improvements
The core package has been reorganized to follow a Domain-Driven Design architecture, moving internal domain models and services under an \internal\ directory and exposing clean wrapper types via the new \core.go\ public API. This refactor includes the addition of a high-performance \StringWidth\ function in \unicode.go\ that correctly calculates visual character widths for emojis, CJK characters, and combining marks, addressing common layout bugs found in other libraries. Additionally, comprehensive documentation has been added to clarify the zero-value behavior for public types like \Terminal\, \Size\, and \Position\, ensuring users understand when explicit constructors are required to avoid panics.
core · high confidence
Examples reorganized and migrated to public core API
The example programs have been moved from the repository root into the core/examples directory and updated to import the public core package directly, replacing previous internal service imports. This change also refines the console output formatting by standardizing newline placement and updates the Unicode demo to highlight the fix for the Lipgloss \#562 width calculation bug.
core/examples · high confidence
Internal domain restructuring and Unicode service simplification
The core domain models, values, and services have been moved from \core/domain\ to \core/internal/domain\, making these types internal implementation details that are no longer part of the public API surface. Additionally, the Unicode service has been simplified to rely exclusively on the \uniwidth\ library for string width calculations, removing the previous dependency on \uniseg\ and the complex grapheme clustering logic, which streamlines text rendering performance.
core/internal · high confidence
Layout package internal structure reorganization and example documentation
The layout package has been restructured to move domain models, services, and value types into an internal directory (e.g., \layout/internal/domain\), making them private to the package while preserving the public API surface. This refactoring includes migrating wrapper types and updating import paths across the codebase. Additionally, example tests have been added to demonstrate common usage patterns, such as creating boxes with padding and arranging items in rows and columns using the flexbox layout system.
layout · high confidence
Test coverage
Expanded testing helpers with alternate screen, raw mode, and interface migration
The testing package has been updated to support more comprehensive terminal testing scenarios. NullTerminal and MockTerminal now implement the full terminal interface, including new methods for alternate screen buffer management (EnterAltScreen, ExitAltScreen, IsInAltScreen) and raw mode control (EnterRawMode, ExitRawMode, IsInRawMode). The package has migrated from the internal api package to the main terminal package, updating all type references (e.g., terminal.Terminal, terminal.CursorStyle, terminal.Platform) and adding state tracking for alternate screen and raw mode in MockTerminal. Example tests and documentation have been expanded to demonstrate these new capabilities, including concurrent testing support and error injection scenarios.
testing · high confidence
Dependencies
Phoenix TUI Framework v0.2.4 dependency and module updates
This release updates the Phoenix TUI Framework and its sub-modules to version 0.2.4, aligning internal dependencies such as \github.com/phoenix-tui/phoenix/tea\ and \github.com/phoenix-tui/phoenix/core\. It upgrades \golang.org/x/sys\ to v0.40.0 and \golang.org/x/term\ to v0.39.0, and migrates the width-calculation library from \github.com/rivo/uniseg\ to \github.com/unilibs/uniwidth\ v0.2.0. The root \go.mod\ now explicitly requires all Phoenix sub-modules (clipboard, core, style, tea, terminal) for easier consumption, and several example modules (cobra-cli, context-menu, drag-scroll, hover-highlight, wheel-scroll) have been added or restructured with updated dependency manifests.
(dependencies) · high confidence
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 69 → 71 (+2.1)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.
Lenses
- Code Health 82 → 82 (+0.0)
- Architecture 92 → 92 (-0.4)
- Maturity 53 → 54 (+1.5)
- Readiness 84 → 84 (+0.0)
- Security 93 → 91 (-2.2)
- Event-Driven 100 → 100 (+0.0)
- Performance 80 → 100 (+20.0)
Resolved (1)
- Split components
New (1)
- Projects may be oversized for their cohesion
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
phoenix-tui/phoenix was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 8 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit 5f76dffea0512fe50d2e0c795ff3b2cb8711f866 — the exact code this score is about.
- Scored under rubric-2026.11.2 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.3+preprod-45ab2cab63de.