[v2] Hard-tab cursor optimization silently breaks column alignment in `View()` output

[zx8]

Note

Human speaking here! Apologies for the full-blown AI-generated bug report, but this was sufficiently complex for me to track down and debug what was going on that I needed to get an LLM involved and help me write up the issue.

Describe the bug

bubbletea v2's cursedRenderer auto-detects the terminal's TAB0 flag via termios and replaces runs of plain space cells with \t characters as a cursor-movement optimization. This silently corrupts any application output that relies on precise space-based column alignment. The application's View() returns properly padded strings with spaces, but the renderer replaces those spaces with tab characters before writing to the terminal. There is no opt-out mechanism.

Setup

• OS: macOS v25.3.0 - TAB0 is the default termios output flag
• Shell: fish
• Terminal Emulator: iTerm2 (but should reproduce in other terms too)
• Terminal Multiplexer: N/A
• bubbletea: v2.0.1

To Reproduce

1. Create a bubbletea v2 app that renders space-padded columns in View() (e.g. a table with strings.Repeat(" ", n) for alignment)
2. Run it on macOS (or any terminal where termios has TAB0 set - the macOS default)
3. Observe that columns are misaligned - spaces have been replaced with tab characters

Source Code

Minimal reproduction - a two-column aligned table:

package main

import (
  "fmt"
  "strings"

  tea "charm.land/bubbletea/v2"
)

type model struct{}

func (m model) Init() tea.Cmd { return nil }

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
  if msg, ok := msg.(tea.KeyMsg); ok && msg.String() == "q" {
    return m, tea.Quit
  }
  return m, nil
}

func (m model) View() tea.View {
  // Two columns, padded with spaces to align.
  rows := []struct{ left, right string }{
    {"short", "value1"},
    {"much longer name", "value2"},
    {"mid", "value3"},
  }
  maxLeft := 0
  for _, r := range rows {
    if len(r.left) > maxLeft {
      maxLeft = len(r.left)
    }
  }
  var b strings.Builder
  for _, r := range rows {
    pad := strings.Repeat(" ", maxLeft-len(r.left)+2)
    b.WriteString(r.left + pad + r.right + "\n")
  }
  b.WriteString("\npress q to quit\n")
  return tea.NewView(b.String())
}

func main() {
  if _, err := tea.NewProgram(model{}).Run(); err != nil {
    fmt.Println("Error:", err)
  }
}

Expected behavior

Columns should be aligned exactly as the View() output specifies - spaces should remain as spaces.

short             value1
much longer name  value2
mid               value3

Actual behavior

Spaces are replaced with tab characters, breaking column alignment:

short     value1
much longer name  value2
mid     value3

Additional context

The root cause is in cursed_renderer.go where hardTabs is set from termios:

// termios_bsd.go
p.useHardTabs = s.Oflag&unix.TABDLY == unix.TAB0

The cellbuf relativeCursorMove() in screen.go then replaces runs of "clear" cells with \t. A cell is "clear" when Cell.Clear() returns true - any space with no foreground/background/underline and only Bold/Faint/Italic/Blink attributes.

This affects any bubbletea v2 application doing column-aligned output on terminals with TAB0 set (the macOS default), including huh multi-select fields.

Workaround: Wrap padding spaces in SGR 8 (conceal): \x1b[8m + spaces + \x1b[28m. The conceal attribute makes Style.Clear() return false, preventing tab compression, while being visually invisible on space characters.

Suggested fix: One or more of:

1. Add tea.WithHardTabs(false) option to let applications disable the optimization
2. Only apply tab compression to renderer-produced cells, not cells from application View() output
3. Disable by default - the optimization saves minimal bandwidth but breaks a very common pattern

[aymanbagabas]

Hi @zx8, thank you for opening this bug. I'm not able to reproduce this with my set up running v2.0.1 and the example you posted. I'm using Iterm2 here. I also tried Terminal.app and Ghostty all having the same consistent results. Could you post the output of stty -a and a screenshot?

[zx8]

$ stty -a
speed 38400 baud; rows 52; columns 178;
intr = ^C; quit = ^\; erase = ^?; kill = ^U; eof = ^D; eol = <undef>; eol2 = <undef>; start = ^Q; stop = ^S; susp = ^Z; dsusp = ^Y; rprnt = ^R; werase = ^W; lnext = ^V;
discard = ^O; status = ^T; min = 1; time = 0;
-parenb -parodd cs8 hupcl -cstopb cread -clocal -crtscts
-ignbrk brkint -ignpar -parmrk -inpck -istrip -inlcr -igncr icrnl -ixon -ixoff ixany imaxbel iutf8
opost -ocrnl onlcr -onocr -onlret -ofill -ofdel nl0 cr0 tab0 bs0 vt0 ff0
isig icanon iexten echo echoe echok -echonl -noflsh -tostop -echoprt echoctl echoke -flusho -extproc

FWIW I also have this in my shell startup script:

tabs -4

[jmwielandt]

@zx8 what happens if you set tabs to 8 characters?

[zx8]

@jmwielandt With tabs -8 everything is aligned. But it would be nice if I could opt-out of this optimization because tabs spanning 8 spaces isn't nice when I cat files (for programming languages that use tabs) in my terminal.

[aymanbagabas]

Thank you, @zx8, for reporting this one. That is true, the Bubble Tea Cursed Renderer assumes default 8 character tabs for tab cursor movement optimizations. Instead, when tab optimizations are enabled, we should reset column tabs using DECST8C when the renderer starts. This ensures that the terminal resets tabs at every 8th column.

However, the only downside is that not all terminals support this escape sequence and using tabs -4 and other mechanisms would still fall into this issue. Perhaps in that case, we could use HTS, same method that tabs uses, instead of DECST8C to set tabs for every 8th column. Or we could make tab and other renderer optimizations opt-in 🤔

[majiayu000]

Hi, I've been looking into this and traced the root cause.

Proposed approach: Add a tea.WithHardTabs(false) program option (in options.go) that flows through to cursed_renderer.go to skip the useHardTabs optimization. This is the simplest fix (option 3 from maintainer discussion). Modify: options.go (new option), tea.go (new field on Program), cursed_renderer.go (respect the flag). Add tests in options_test.go. Comment on the issue first to align with maintainer on approach before coding.

I'll open a draft PR shortly. Happy to adjust based on your preference.

[aymanbagabas]

Hi @zx8 and @majiayu000, I've opened #1677 to fix this issue. I would appreciate it if you can verify the changes in the PR fix the issue for you 🙂