🚀 Phoenix TUI v0.1.0-beta.3 Released - ExecProcess + Performance Tracking

[kolkov]

We're excited to announce Phoenix TUI Framework v0.1.0-beta.3! This release brings powerful new capabilities for running interactive commands, a convenient umbrella module, and comprehensive performance tracking.

---

🎯 Highlights

1. ExecProcess API - Run Interactive Commands ⭐

The biggest feature in this release! Execute external interactive programs (vim, ssh, tmux, claude, etc.) directly from your TUI application with proper terminal mode management.

Example - Running vim:

package main

import (
    "os/exec"
    tea "github.com/phoenix-tui/phoenix/tea/api"
)

func (m model) Update(msg tea.Msg) (model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.KeyMsg:
        if msg.String() == "e" {
            // Open vim editor
            cmd := exec.Command("vim", "myfile.txt")
            return m, tea.ExecProcess(cmd)
        }
    }
    return m, nil
}

What it handles for you:

• ✅ Terminal raw mode management (exit → restore automatically)
• ✅ Alt screen coordination (seamless transitions)
• ✅ Input reader lifecycle (no goroutine leaks)
• ✅ Error recovery (terminal state always restored)
• ✅ Cross-platform support (Unix + Windows)

Use cases:

• Text editors: vim, nano, emacs
• Shell commands: bash, zsh, ssh sessions
• Interactive tools: claude, tmux, htop
• Any command that needs full terminal control

2. Umbrella Module - Simplified Imports 🎁

New convenience package that re-exports all Phoenix libraries:

Before:

  import (
      "github.com/phoenix-tui/phoenix/core/api"
      "github.com/phoenix-tui/phoenix/style/api"
      "github.com/phoenix-tui/phoenix/tea/api"
      // ... 8 more imports
  )

After:

import "github.com/phoenix-tui/phoenix"

  // All 21 functions available:
  term := phoenix.AutoDetectTerminal()
  style := phoenix.NewStyle().Bold().Foreground("#00FF00")
  program := phoenix.NewProgram(model)

Benefits:

• ✅ Simpler imports for new users
• ✅ 100% optional (can still import individual modules)
• ✅ 100% test coverage

3. Performance Tracking System 📊

Comprehensive benchmarking infrastructure with automated tracking:

Performance metrics (v0.1.0-beta.3):

• 🚀 Render: 37,818 FPS (630x faster than 60 FPS target) - +30% improvement!
• ⚡ Unicode ASCII: 64 ns/op (-29% faster than beta.2)
• ⚡ Unicode Emoji: 110 ns/op (-34% faster than beta.2)
• 💾 Memory: 4 B/op, 0 allocations

Automated workflow:

Run benchmarks

bash benchmarks/scripts/run_benchmarks.sh

Compare with baseline (detect regressions)

bash benchmarks/scripts/compare.sh

Set new baseline after release

bash benchmarks/scripts/set_baseline.sh

Results saved in benchmarks/results/ with version history for tracking performance over time.

---

🐛 Critical Fixes

Race Condition Fix - InputReader Lifecycle 🔥

Problem: ExecProcess could deadlock due to goroutine lifecycle race condition.

Solution: Generation counter pattern to prevent old goroutines from interfering:

type Program[T any] struct {
inputReaderGeneration uint64 // Generation counter
// ... other fields
}

func (p *Program[T]) stopInputReader() {
p.mu.Lock()
p.inputReaderGeneration++ // Invalidate old goroutine
p.mu.Unlock()
}

Impact:

• ✅ Zero performance overhead
• ✅ No additional memory allocations
• ✅ All 29 ExecProcess tests passing
• ✅ GoSh shell confirmed working

Thanks to: GoSh team for discovering and validating the fix in production! 🙏

Terminal Mode Management 🔧

Fixed stdin not working in external commands:

• ExecProcess now properly manages raw mode transitions
• External commands (vim, ssh) receive proper cooked mode
• Added 10 comprehensive raw mode tests (Unix + Windows)

TextArea Keybindings ⌨️

• Fixed Ctrl+W (kill word backward)
• Fixed Alt+Backspace (kill word backward)
• Both now work correctly in Emacs mode
• 35+ keybindings tests all passing

---

📊 Statistics

Code changes:

• 7,738 lines added
• 49 files changed
• 250+ new tests added (≈2,450 lines)
• 6 new example programs

Test coverage:

• clipboard: 90%+ ✅
• components: 94.5%+ ✅
• core: 95%+ ✅
• layout: 97.9%+ ✅
• tea: 95.7%+ ✅
• render: 87.1%+ ✅

Performance improvements vs beta.2:

• +30% render speed
• +29% Unicode ASCII processing
• +34% Unicode Emoji processing
• +28% scrolling terminal
• +24% code editor rendering

---

📦 Installation

Umbrella module (recommended):
go get github.com/phoenix-tui/phoenix@v0.1.0-beta.3

Individual modules:
go get github.com/phoenix-tui/phoenix/tea@v0.1.0-beta.3
go get github.com/phoenix-tui/phoenix/style@v0.1.0-beta.3
go get github.com/phoenix-tui/phoenix/components@v0.1.0-beta.3

... other modules

---

🔗 Links

• GitHub Release: https://github.com/phoenix-tui/phoenix/releases/tag/v0.1.0-beta.3
• CHANGELOG: https://github.com/phoenix-tui/phoenix/blob/main/CHANGELOG.md#010-beta3---2025-10-23-execprocess--performance-tracking
• Examples: https://github.com/phoenix-tui/phoenix/tree/main/examples
• Benchmarks: https://github.com/phoenix-tui/phoenix/tree/main/benchmarks

---

🎯 What's Next?

Upcoming in future releases:

• Advanced mouse support (drag & drop, hover events)
• Enhanced clipboard operations (images, formats)
• More components (tree view, tabs, menus)
• Theme system
• Migration guide from Bubbletea

---

🙏 Acknowledgments

Special thanks to:

• GoSh team for testing ExecProcess in production and validating the race condition fix
• Beta testers who provided valuable feedback
• Contributors who reported issues and suggested improvements

---

🐛 Found a Bug?

Please report issues at: https://github.com/phoenix-tui/phoenix/issues

---

💬 Questions or Feedback?

Join the discussion! We'd love to hear:

• What you're building with Phoenix
• Feature requests
• API feedback
• Performance reports

Happy coding! 🔥

---

Phoenix TUI Framework - Next-generation Terminal UI framework for GoPerformance: 37,818 FPS | Coverage: 90%+ | Architecture: DDD + Clean Architecture