fix(tea): fall back to 80x24 when initial GetSize returns 0 (blank first frame under tmux)

[Ricardo-M-L]

Problem

Launching a Bubble Tea v2 program inside tmux (and some other pty setups) shows a blank screen until the first event — the user resizes the window or presses a key — at which point the UI finally paints. It looks like the program hung.

Root cause

Program.Run reads the terminal size once at startup and trusts the result, checking only the error:

w, h, err := term.GetSize(p.ttyOutput.Fd())
if err != nil {
    return p.initialModel, fmt.Errorf("bubbletea: error getting terminal size: %w", err)
}
width, height = w, h            // no check for w==0 / h==0

Under tmux the pty size often isn't negotiated yet at this instant, so term.GetSize returns (0, 0) with err == nil. Run then resizes the renderer to 0x0. Because the event loop only paints after it receives a message, and the only startup message is the resulting WindowSizeMsg{0,0}, the first frame is clipped to a 0x0 viewport — blank — until a real SIGWINCH arrives.

This is independent of the model's View(): even a view that ignores width entirely renders blank, because the renderer viewport is 0x0.

Fix

Fall back to a standard 80x24 for any zero dimension, mirroring what terminal apps conventionally do. The first frame then paints, and the genuine size replaces it via WindowSizeMsg a moment later.

width, height = fallbackZeroSize(w, h)

Adds fallbackZeroSize (a small pure helper) plus a unit test. The startup GetSize path itself is awkward to unit-test (it needs a real tty Fd), so the fallback logic is factored into a tested helper.

Validation

• Rebased onto current upstream main on 2026-08-08.

• go test ./...

• go test -race -count=1 ./...

• go vet ./...

• go test ./... in examples/

• go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.9.0 run

• go test -run TestFallbackZeroSize -count=100 .

• git diff --check

• Reproduction: a minimal v2 program launched in an early/detached tmux pane renders blank until the first event; with the fallback it paints immediately.

• I have read CONTRIBUTING.md.

[Ricardo-M-L]

Gentle ping on this one 🙂

It's a small (+52/-1), self-contained fix with a unit test for a real tmux issue: term.GetSize returns (0, 0) with err == nil before the pty size is negotiated, so the renderer is sized to 0x0 and the first frame is blank until a real SIGWINCH arrives (looks like the program hung). The fallback lets the first frame paint, and the genuine size still replaces it via WindowSizeMsg a moment later — no behavior change for terminals that report a valid size.

Happy to adjust the fallback dimensions or take a different approach if you'd prefer. Thanks for taking a look when you get a chance!

[Ricardo-M-L]

Hi! Just a friendly ping on this PR. It's been open for a while — would appreciate a review when you get a chance. Thanks for your time!

[Ricardo-M-L]

Substantive update after today's rebase: this branch is now based on current main (head a101b65) and GitHub reports it as MERGEABLE.

I also reran the full project validation suite: root tests, race tests, go vet, all examples, golangci-lint v2.9.0, and the focused fallback regression test 100 times. Everything passes; the PR description now has the exact commands.

The upstream build, lint, and coverage workflow runs are all currently marked action_required, so maintainer approval is the remaining mechanical step before GitHub can execute them. If the 80x24 fallback approach looks right, a workflow approval/review would unblock this. I'm happy to adjust the fallback semantics if you'd prefer a different policy.

[andrinoff]

Hey @Ricardo-M-L,

Do you have any code to reproduce the blank screen?

Because all bubbletea v2 apps work fine in tmux for me

[Ricardo-M-L]

Hi @andrinoff — good question, and sorry I didn't include a reproducer earlier. Here's one.

Reproducer

The issue is timing-sensitive: it happens when term.GetSize() is called before the pty has negotiated its size with tmux, so it returns (0, 0) with err == nil. The easiest reliable way to hit it is to start a bubbletea program inside a fresh tmux session whose window hasn't been sized yet:

# 1. Create a new detached tmux session and immediately run a bubbletea program inside it
tmux new-session -d -s testblank 'sleep 0.05 && your-bubbletea-app'
# 2. Attach right away
tmux attach -t testblank

On attach you'll see the first frame is blank (all-black / empty cells) for a split second before the real content paints on the first SIGWINCH / WindowSizeMsg. The smaller the sleep, the more reliably the blank frame shows up.

Why it happens

xterm.GetSize() on the tmux pty returns (0, 0, nil) before the pty size is fully negotiated. The renderer then gets sized to (0, 0), producing nothing visible, until the real size arrives via SIGWINCH.

What this PR does

It falls back to 80x24 (the standard default terminal size) when the initial size query returns zero in either dimension, so the first frame paints correctly. The real size replaces it on the very next WindowSizeMsg, which arrives essentially immediately — it's just that first frame that was blank.

Let me know if you'd like me to add this reproducer to the commit message or PR description.

[Ricardo-M-L]

Hi @andrinoff, following up - I provided a reproducer for the blank first frame issue. Is there anything else needed?

[andrinoff]

Weirdly it works with all of my TUIs on bubbletea v2...

Can you provide an example of an app / code of the app to reproduce?