feat(tui): implement ANSI/VT processing for Windows and enhance color profile handling

Author: alvarorichard

cmd/goanime/main.go

@@ -16,6 +16,12 @@ import (
 )
 
 func main() {
+	// Enable ANSI/VT processing on Windows consoles (classic cmd.exe leaves it
+	// off). Must run before any colored log/TUI output or users see raw escape
+	// codes like ←[38;2;...m instead of colors. If enable fails, color paths
+	// fall back to ASCII via tui.ConsoleColorProfile / SupportsANSI.
+	_ = tui.EnableVirtualTerminal()
+
 	// Save terminal state so we can restore it on exit.
 	// Libraries like promptui (readline) and go-fuzzyfinder (tcell) put the
 	// terminal into raw mode; if the process is interrupted or exits abnormally

internal/tui/color_profile.go

@@ -0,0 +1,54 @@
+package tui
+
+import (
+	"io"
+	"os"
+	"runtime"
+
+	"github.com/charmbracelet/colorprofile"
+)
+
+// ResolveColorProfile picks a safe color profile for writer w.
+//
+// On Windows, colorprofile.Detect returns TrueColor based on the OS build
+// alone — even when classic cmd.exe still has VT processing disabled.
+// Emitting ANSI then prints raw escape garbage. We only allow color above
+// ASCII when VT processing is actually enabled on the target console.
+//
+// Pure function: pass vtEnabled explicitly so unit tests cover every branch
+// without needing a real console.
+func ResolveColorProfile(w io.Writer, env []string, vtEnabled bool) colorprofile.Profile {
+	p := colorprofile.Detect(w, env)
+	if runtime.GOOS != "windows" {
+		return p
+	}
+	// Detect already chose plain text (pipe, NO_COLOR, dumb TERM).
+	if p <= colorprofile.ASCII {
+		return p
+	}
+	// Colored Windows console output requires live VT processing.
+	if !vtEnabled {
+		return colorprofile.ASCII
+	}
+	return p
+}
+
+// ConsoleColorProfile enables VT when possible and returns a safe profile for f.
+// Call once at startup (or from InitLogger) before any colored write.
+func ConsoleColorProfile(f *os.File) colorprofile.Profile {
+	_ = EnableVirtualTerminal()
+	return ResolveColorProfile(f, os.Environ(), HasVirtualTerminal(f))
+}
+
+// SupportsANSI reports whether it is safe to emit ANSI sequences to f.
+// On Windows this means VT processing is active; elsewhere any non-nil file.
+func SupportsANSI(f *os.File) bool {
+	if f == nil {
+		return false
+	}
+	if runtime.GOOS != "windows" {
+		return true
+	}
+	_ = EnableVirtualTerminal()
+	return HasVirtualTerminal(f)
+}

internal/tui/color_profile_test.go

@@ -0,0 +1,166 @@
+package tui
+
+import (
+	"bytes"
+	"os"
+	"runtime"
+	"strings"
+	"testing"
+
+	"github.com/charmbracelet/colorprofile"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestResolveColorProfile_WindowsWithoutVT_ForcesASCII is the regression guard
+// for classic cmd.exe garbage (←[38;2;...m). Detect alone returns TrueColor on
+// Win10+ by OS build; without VT we MUST force ASCII so nothing emits ANSI.
+func TestResolveColorProfile_WindowsWithoutVT_ForcesASCII(t *testing.T) {
+	t.Parallel()
+	if runtime.GOOS != "windows" {
+		t.Skip("Windows-only regression: VT-disabled console")
+	}
+
+	// Simulate a TTY-ish env that Detect upgrades to TrueColor on Win10+.
+	env := []string{
+		"TERM=",
+		"COLORTERM=truecolor",
+	}
+	// Use os.Stderr so Detect sees a real file handle; VT flag forced false.
+	got := ResolveColorProfile(os.Stderr, env, false)
+	assert.LessOrEqual(t, got, colorprofile.ASCII,
+		"Windows console without VT must not emit color ANSI (got %v)", got)
+}
+
+// TestResolveColorProfile_WindowsWithVT_AllowsColor ensures we do not
+// over-downgrade modern hosts (Windows Terminal, cmd with VT on).
+// TTY_FORCE makes Detect treat the writer as a TTY even under go test pipes.
+func TestResolveColorProfile_WindowsWithVT_AllowsColor(t *testing.T) {
+	t.Parallel()
+	if runtime.GOOS != "windows" {
+		t.Skip("Windows-only")
+	}
+
+	env := []string{
+		"TTY_FORCE=1",
+		"WT_SESSION=test-session",
+		"COLORTERM=truecolor",
+	}
+	got := ResolveColorProfile(os.Stderr, env, true)
+	assert.Greater(t, got, colorprofile.ASCII,
+		"VT-enabled Windows console should keep color (got %v)", got)
+
+	// Same env without VT must still force ASCII (the cmd.exe regression).
+	downgraded := ResolveColorProfile(os.Stderr, env, false)
+	assert.LessOrEqual(t, downgraded, colorprofile.ASCII)
+}
+
+// TestResolveColorProfile_NoColorEnv_StaysPlain covers NO_COLOR on any OS.
+func TestResolveColorProfile_NoColorEnv_StaysPlain(t *testing.T) {
+	t.Parallel()
+	env := []string{"NO_COLOR=1", "TERM=xterm-256color", "COLORTERM=truecolor"}
+	got := ResolveColorProfile(os.Stderr, env, true)
+	assert.LessOrEqual(t, got, colorprofile.ASCII)
+}
+
+// TestResolveColorProfile_NonWindows_IgnoresVTFlag documents that Unix
+// hosts always trust Detect (vtEnabled is irrelevant).
+func TestResolveColorProfile_NonWindows_IgnoresVTFlag(t *testing.T) {
+	t.Parallel()
+	if runtime.GOOS == "windows" {
+		t.Skip("Unix-only branch")
+	}
+	env := []string{"TERM=xterm-256color", "COLORTERM=truecolor"}
+	// Even with vtEnabled=false, non-Windows must not force ASCII solely for that.
+	with := ResolveColorProfile(os.Stderr, env, true)
+	without := ResolveColorProfile(os.Stderr, env, false)
+	assert.Equal(t, with, without)
+}
+
+// TestResolveColorProfile_PipeWriter_NoTTY ensures redirected writers stay plain.
+func TestResolveColorProfile_PipeWriter_NoTTY(t *testing.T) {
+	t.Parallel()
+	var buf bytes.Buffer
+	got := ResolveColorProfile(&buf, []string{"TERM=xterm-256color"}, false)
+	assert.LessOrEqual(t, got, colorprofile.ASCII,
+		"non-TTY writer must not use color profiles (got %v)", got)
+}
+
+func TestEnableVirtualTerminal_DoesNotPanic(t *testing.T) {
+	t.Parallel()
+	_ = EnableVirtualTerminal()
+	_ = EnableVirtualTerminal()
+}
+
+func TestHasVirtualTerminal_NilFile(t *testing.T) {
+	t.Parallel()
+	assert.False(t, HasVirtualTerminal(nil))
+}
+
+func TestSupportsANSI_NilFile(t *testing.T) {
+	t.Parallel()
+	assert.False(t, SupportsANSI(nil))
+}
+
+// TestEnableVirtualTerminal_EnablesFlagWhenConsole is the live console check.
+// Skips when stdout is not a console (CI pipes, go test capture).
+func TestEnableVirtualTerminal_EnablesFlagWhenConsole(t *testing.T) {
+	if runtime.GOOS != "windows" {
+		t.Skip("Windows console mode flag only")
+	}
+	ok := EnableVirtualTerminal()
+	if !HasVirtualTerminal(os.Stdout) && !HasVirtualTerminal(os.Stderr) {
+		t.Skip("no console attached (piped CI) — cannot assert VT flag")
+	}
+	require.True(t, ok, "EnableVirtualTerminal should succeed on a real console")
+	assert.True(t, HasVirtualTerminal(os.Stdout) || HasVirtualTerminal(os.Stderr))
+}
+
+// TestConsoleColorProfile_NeverTrueColorWithoutVT hard-guards the user-facing
+// bug: profile used by logger/TUI must never be TrueColor/ANSI256 when VT is off.
+func TestConsoleColorProfile_NeverTrueColorWithoutVT(t *testing.T) {
+	t.Parallel()
+	if runtime.GOOS != "windows" {
+		t.Skip("Windows-only contract")
+	}
+	// Force the pure path with vtEnabled=false regardless of host state.
+	p := ResolveColorProfile(os.Stderr, os.Environ(), false)
+	assert.LessOrEqual(t, p, colorprofile.ASCII)
+}
+
+// TestRestoreTerminalState_NoANSIWhenUnsupported ensures exit cleanup does not
+// dump TerminalResetSequence into classic cmd.exe.
+func TestRestoreTerminalState_NoANSIWhenUnsupported(t *testing.T) {
+	t.Parallel()
+	// bytes.Buffer is not *os.File → SupportsANSI path not taken; sequence writes.
+	// Test the *os.File branch with a temp file (not a console → no VT).
+	f, err := os.CreateTemp(t.TempDir(), "restore-*.txt")
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = f.Close() })
+
+	if runtime.GOOS == "windows" {
+		// Temp file is not a console → SupportsANSI false → no write.
+		RestoreTerminalState(f)
+		_, _ = f.Seek(0, 0)
+		data, err := os.ReadFile(f.Name())
+		require.NoError(t, err)
+		assert.Empty(t, data, "must not write ANSI reset to non-console Windows handle")
+		assert.NotContains(t, string(data), "\x1b")
+		return
+	}
+	// Non-Windows: sequence is written (SupportsANSI true for any non-nil file).
+	RestoreTerminalState(f)
+	_, _ = f.Seek(0, 0)
+	data, err := os.ReadFile(f.Name())
+	require.NoError(t, err)
+	assert.Contains(t, string(data), "\x1b[?25h")
+}
+
+// TestTerminalResetSequence_ContainsNoRIS documents we never hard-reset the
+// screen (would wipe scrollback) — keeps restore safe.
+func TestTerminalResetSequence_ContainsNoRIS(t *testing.T) {
+	t.Parallel()
+	assert.NotContains(t, TerminalResetSequence, "\x1bc")
+	assert.NotContains(t, TerminalResetSequence, "\x1b[2J")
+	assert.True(t, strings.Contains(TerminalResetSequence, "\x1b[?25h"))
+}

internal/tui/find.go

@@ -24,6 +24,9 @@ import (
 
 // ResetTerminal sends ANSI sequences to reset terminal state after tcell
 // and drains any stale bytes from stdin that tcell may have left behind.
+//
+// On Windows consoles without VT processing, ANSI is skipped (only a bare
+// carriage return) so classic cmd.exe never shows raw codes like ←[?25h.
 func ResetTerminal() {
 	// Reset DECCKM (normal cursor keys) + reset keypad numeric mode + show cursor
 	// These match the exact sequences tcell's ExitKeypad should send but
@@ -38,7 +41,11 @@ func ResetTerminal() {
 	// column-0 line instead of glued to leftovers. Deliberately NOT "\r\n":
 	// ResetTerminal runs after every finder/spinner, and an unconditional
 	// newline stacks a blank line per call, riddling the session with gaps.
-	fmt.Fprint(os.Stdout, "\r\033[2K\033[?1l\033>\033[?25h")
+	if SupportsANSI(os.Stdout) {
+		fmt.Fprint(os.Stdout, "\r\033[2K\033[?1l\033>\033[?25h")
+	} else {
+		fmt.Fprint(os.Stdout, "\r")
+	}
 
 	// Drain any stale bytes from stdin (platform-specific implementation). A
 	// short raw/no-echo window also catches late terminal capability responses

internal/tui/restore.go

@@ -48,7 +48,13 @@ const TerminalResetSequence = "" +
 // RestoreTerminalState writes TerminalResetSequence to w, returning sane
 // interactive terminal state on program exit. It is safe to call multiple times
 // and on any exit path.
+//
+// On Windows without VT, the sequence is skipped — emitting it to classic
+// cmd.exe prints raw escape garbage instead of restoring the console.
 func RestoreTerminalState(w io.Writer) {
+	if f, ok := w.(*os.File); ok && !SupportsANSI(f) {
+		return
+	}
 	_, _ = io.WriteString(w, TerminalResetSequence)
 }
 

internal/tui/terminal.go

@@ -5,15 +5,16 @@ import (
 	"strings"
 
 	tea "charm.land/bubbletea/v2"
-	"github.com/charmbracelet/colorprofile"
 )
 
 // BubbleTeaProgramOptions returns default Bubble Tea options that avoid
 // terminal capability probes known to leak raw responses in some terminals.
+// Color profile follows ConsoleColorProfile so classic Windows cmd.exe without
+// VT never receives TrueColor sequences it would print as raw garbage.
 func BubbleTeaProgramOptions(extra ...tea.ProgramOption) []tea.ProgramOption {
 	opts := []tea.ProgramOption{
 		tea.WithEnvironment(safeBubbleTeaEnvironment()),
-		tea.WithColorProfile(colorprofile.TrueColor),
+		tea.WithColorProfile(ConsoleColorProfile(os.Stdout)),
 	}
 	return append(opts, extra...)
 }

internal/tui/terminal_test.go

@@ -19,6 +19,18 @@ func TestSafeBubbleTeaEnvironmentSuppressesCapabilityQueries(t *testing.T) {
 	assertEnvMissing(t, env, "WT_SESSION")
 }
 
+// TestBubbleTeaProgramOptions_UsesResolvedProfile ensures we never hardcode
+// TrueColor (the previous source of cmd.exe garbage when VT is off).
+func TestBubbleTeaProgramOptions_UsesResolvedProfile(t *testing.T) {
+	t.Parallel()
+	opts := BubbleTeaProgramOptions()
+	if len(opts) < 2 {
+		t.Fatalf("expected env + color profile options, got %d", len(opts))
+	}
+	// Construction must not panic; profile comes from ConsoleColorProfile.
+	_ = opts
+}
+
 func TestRunCleanRestoresEnvironmentAndPropagatesError(t *testing.T) {
 	t.Setenv("TERM", "xterm-ghostty")
 	t.Setenv("TERM_PROGRAM", "Ghostty")

internal/tui/vt_other.go

@@ -0,0 +1,14 @@
+//go:build !windows
+
+package tui
+
+import "os"
+
+// EnableVirtualTerminal is a no-op outside Windows. Unix terminals interpret
+// ANSI escape sequences by default. Always returns true.
+func EnableVirtualTerminal() bool { return true }
+
+// HasVirtualTerminal is always true outside Windows: hosts render ANSI natively.
+func HasVirtualTerminal(f *os.File) bool {
+	return f != nil
+}

internal/tui/vt_windows.go

@@ -0,0 +1,55 @@
+//go:build windows
+
+package tui
+
+import (
+	"os"
+
+	"golang.org/x/sys/windows"
+)
+
+// EnableVirtualTerminal turns on ANSI/VT processing for stdout and stderr.
+//
+// Classic cmd.exe on Windows 10 leaves ENABLE_VIRTUAL_TERMINAL_PROCESSING off.
+// Without it, TrueColor/ANSI sequences from lipgloss/log/tcell print as raw
+// garbage (e.g. ←[38;2;255;255;255m). Returns true when at least one of
+// stdout/stderr has VT processing active after the call.
+func EnableVirtualTerminal() bool {
+	outOK := enableVT(os.Stdout)
+	errOK := enableVT(os.Stderr)
+	return outOK || errOK
+}
+
+// HasVirtualTerminal reports whether f is a console with VT processing on.
+func HasVirtualTerminal(f *os.File) bool {
+	if f == nil {
+		return false
+	}
+	return consoleHasVT(windows.Handle(f.Fd()))
+}
+
+func enableVT(f *os.File) bool {
+	if f == nil {
+		return false
+	}
+	handle := windows.Handle(f.Fd())
+	var mode uint32
+	if err := windows.GetConsoleMode(handle, &mode); err != nil {
+		return false
+	}
+	if mode&windows.ENABLE_VIRTUAL_TERMINAL_PROCESSING != 0 {
+		return true
+	}
+	if err := windows.SetConsoleMode(handle, mode|windows.ENABLE_VIRTUAL_TERMINAL_PROCESSING); err != nil {
+		return false
+	}
+	return consoleHasVT(handle)
+}
+
+func consoleHasVT(handle windows.Handle) bool {
+	var mode uint32
+	if err := windows.GetConsoleMode(handle, &mode); err != nil {
+		return false
+	}
+	return mode&windows.ENABLE_VIRTUAL_TERMINAL_PROCESSING != 0
+}