Skip to content

Comments

fix(tui): use alternate screen buffer for login screen#492

Merged
echobt merged 1 commit intomasterfrom
fix/login-screen-tui-rendering
Jan 29, 2026
Merged

fix(tui): use alternate screen buffer for login screen#492
echobt merged 1 commit intomasterfrom
fix/login-screen-tui-rendering

Conversation

@echobt
Copy link
Contributor

@echobt echobt commented Jan 29, 2026

Problem

Customers reported that on Ubuntu terminals, the TUI login screen was not rendering properly - instead of showing the interactive TUI, it would spam 'Welcome to Cortex CLI v0.0.6' messages repeatedly.

Root Cause

The login screen was using an 'inline' rendering approach that relied on cursor escape sequences (MoveUp/MoveDown) to redraw the content in place. This approach is not reliable across all terminal emulators:

  • Some terminals don't properly support CSI cursor control sequences
  • SSH sessions may filter or not properly handle these escape sequences
  • Certain terminal multiplexer configurations (tmux, screen) can interfere
  • Ubuntu's default GNOME Terminal has specific quirks with inline cursor control

Each render frame would print 12 lines of content and then attempt to move the cursor back up. When the cursor move failed, each frame added more lines instead of overwriting, causing the 'spam' behavior.

Solution

Refactored the login screen to use ratatui with the alternate screen buffer, matching the approach already used by the trust screen:

  1. Uses EnterAlternateScreen for reliable full-screen rendering
  2. Leverages ratatui's proper terminal abstraction and layout system
  3. Uses Terminal::draw() for atomic frame rendering
  4. Works consistently across all terminal emulators

Changes

  • Converted from raw crossterm cursor manipulation to ratatui's Terminal abstraction
  • Used proper Layout and Constraint system for positioning
  • Maintained the same visual design (colors, text, options)
  • Properly handles alternate screen entry/exit for clean terminal restoration

Testing

  • Verified cargo check passes for cortex-cli and cortex-tui
  • Verified cargo fmt passes
  • The fix follows the same pattern as trust_screen.rs which is known to work correctly

This fixes the issue where the login screen would spam 'Welcome to Cortex
CLI' messages on some Ubuntu terminals instead of properly rendering the
interactive TUI.

The root cause was that the inline rendering approach using cursor escape
sequences (MoveUp/MoveDown) was not reliable across all terminal emulators.
Some terminals don't properly support these cursor control sequences,
especially in SSH sessions or with certain terminal multiplexer
configurations.

Solution: Refactored the login screen to use ratatui with the alternate
screen buffer, similar to how the trust screen already works. This approach:
- Uses EnterAlternateScreen for reliable full-screen rendering
- Leverages ratatui's proper terminal abstraction
- Works consistently across all terminal emulators
- Prevents content from leaking to the scrollback buffer

Fixes rendering issues on Ubuntu terminals where cursor escape sequences
were not properly interpreted.
@echobt echobt merged commit b1b54bf into master Jan 29, 2026
4 checks passed
@echobt echobt deleted the fix/login-screen-tui-rendering branch January 29, 2026 09:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants