feat: support a Clear command

nil_renderer.go

@@ -7,6 +7,7 @@ func (n nilRenderer) stop()                   {}
 func (n nilRenderer) kill()                   {}
 func (n nilRenderer) write(v string)          {}
 func (n nilRenderer) repaint()                {}
+func (n nilRenderer) clearScreen()            {}
 func (n nilRenderer) altScreen() bool         { return false }
 func (n nilRenderer) enterAltScreen()         {}
 func (n nilRenderer) exitAltScreen()          {}

renderer.go

@@ -21,6 +21,9 @@ type renderer interface {
 	// in succession.
 	repaint()
 
+	// Clears the terminal.
+	clearScreen()
+
 	// Whether or not the alternate screen buffer is enabled.
 	altScreen() bool
 	// Enable the alternate screen buffer.

screen.go

@@ -9,6 +9,20 @@ type WindowSizeMsg struct {
 	Height int
 }
 
+// ClearScreen is a special command that tells the program to clear the screen
+// before the next update. This can be used to move the cursor to the top left
+// of the screen and clear visual clutter when the alt screen is not in use.
+//
+// Note that it should never be necessary to call ClearScreen() for regular
+// redraws.
+func ClearScreen() Msg {
+	return clearScreenMsg{}
+}
+
+// clearScreenMsg is an internal message that signals to clear the screen.
+// You can send a clearScreenMsg with ClearScreen.
+type clearScreenMsg struct{}
+
 // EnterAltScreen is a special command that tells the Bubble Tea program to
 // enter the alternate screen buffer.
 //

standard_renderer.go

@@ -245,6 +245,14 @@ func (r *standardRenderer) repaint() {
 	r.lastRender = ""
 }
 
+func (r *standardRenderer) clearScreen() {
+	r.mtx.Lock()
+	defer r.mtx.Unlock()
+
+	r.out.ClearScreen()
+	r.out.MoveCursor(1, 1)
+}
+
 func (r *standardRenderer) altScreen() bool {
 	return r.altScreenActive
 }
@@ -254,9 +262,17 @@ func (r *standardRenderer) enterAltScreen() {
 	defer r.mtx.Unlock()
 
 	r.altScreenActive = true
-
 	r.out.AltScreen()
+
+	// Ensure that the terminal is cleared, even when it doesn't support
+	// alt screen (or alt screen support is disabled, like GNU screen by
+	// default).
+	//
+	// Note: we can't use r.clearScreen() here because the mutex is already
+	// locked.
+	r.out.ClearScreen()
 	r.out.MoveCursor(1, 1)
+
 	r.repaint()
 }
 
@@ -265,8 +281,8 @@ func (r *standardRenderer) exitAltScreen() {
 	defer r.mtx.Unlock()
 
 	r.altScreenActive = false
-
 	r.out.ExitAltScreen()
+
 	r.repaint()
 }
 

tea.go

@@ -378,6 +378,9 @@ func (p *Program) StartReturningModel() (Model, error) {
 				p.shutdown(false)
 				return model, nil
 
+			case clearScreenMsg:
+				p.renderer.clearScreen()
+
 			case enterAltScreenMsg:
 				p.renderer.enterAltScreen()