chore: deprecate some StartupOptions in favor of Cmds (#1307)

options.go

@@ -106,13 +106,18 @@ func WithoutSignals() ProgramOption {
 //
 // To enter the altscreen once the program has already started running use the
 // EnterAltScreen command.
+//
+// Deprecated: use the [EnterAltScreen] [Cmd] in your [Model.Init] instead.
 func WithAltScreen() ProgramOption {
 	return func(p *Program) {
 		p.startupOptions |= withAltScreen
 	}
 }
 
 // WithoutBracketedPaste starts the program with bracketed paste disabled.
+//
+// Deprecated: use the [EnableBracketedPaste] [Cmd] in your [Model.Init]
+// instead.
 func WithoutBracketedPaste() ProgramOption {
 	return func(p *Program) {
 		p.startupOptions |= withoutBracketedPaste
@@ -134,6 +139,9 @@ func WithoutBracketedPaste() ProgramOption {
 // running use the DisableMouse command.
 //
 // The mouse will be automatically disabled when the program exits.
+//
+// Deprecated: use the [EnableMouseCellMotion] [Cmd] in your [Model.Init]
+// instead.
 func WithMouseCellMotion() ProgramOption {
 	return func(p *Program) {
 		p.startupOptions |= withMouseCellMotion // set
@@ -159,6 +167,9 @@ func WithMouseCellMotion() ProgramOption {
 // running use the DisableMouse command.
 //
 // The mouse will be automatically disabled when the program exits.
+//
+// Deprecated: use the [EnableMouseAllMotion] [Cmd] in your [Model.Init]
+// instead.
 func WithMouseAllMotion() ProgramOption {
 	return func(p *Program) {
 		p.startupOptions |= withMouseAllMotion   // set
@@ -188,6 +199,10 @@ func WithoutRenderer() ProgramOption {
 //
 // Deprecated: this incurs a noticeable performance hit. A future release will
 // optimize ANSI automatically without the performance penalty.
+//
+// Deprecated: this will be removed in a future release. This ANSI compressor
+// has major performance implications and we don't recommend using it. In v2,
+// rendering bandwidth will be decreased significantly.
 func WithANSICompressor() ProgramOption {
 	return func(p *Program) {
 		p.startupOptions |= withANSICompressor
@@ -245,6 +260,8 @@ func WithFPS(fps int) ProgramOption {
 // Note that while most terminals and multiplexers support focus reporting,
 // some do not. Also note that tmux needs to be configured to report focus
 // events.
+//
+// Deprecated: use the [EnableReportFocus] [Cmd] in your [Model.Init] instead.
 func WithReportFocus() ProgramOption {
 	return func(p *Program) {
 		p.startupOptions |= withReportFocus

screen.go

@@ -24,7 +24,9 @@ func ClearScreen() Msg {
 type clearScreenMsg struct{}
 
 // EnterAltScreen is a special command that tells the Bubble Tea program to
-// enter the alternate screen buffer.
+// enter the alternate screen buffer (i.e. the full terminal window). The
+// altscreen will be automatically exited when the program quits. To manually
+// exit the altscreen while the program is running, use [ExitAltScreen].
 //
 // Because commands run asynchronously, this command should not be used in your
 // model's Init function. To initialize your program with the altscreen enabled
@@ -49,15 +51,17 @@ func ExitAltScreen() Msg {
 }
 
 // exitAltScreenMsg in an internal message signals that the program should exit
-// alternate screen buffer. You can send a exitAltScreenMsg with ExitAltScreen.
+// alternate screen buffer. You can send a exitAltScreenMsg with
+// [ExitAltScreen].
 type exitAltScreenMsg struct{}
 
 // EnableMouseCellMotion is a special command that enables mouse click,
 // release, and wheel events. Mouse movement events are also captured if
 // a mouse button is pressed (i.e., drag events).
 //
 // Because commands run asynchronously, this command should not be used in your
-// model's Init function. Use the WithMouseCellMotion ProgramOption instead.
+// model's Init function. Use the [WithMouseCellMotion] [ProgramOption]
+// instead.
 func EnableMouseCellMotion() Msg {
 	return enableMouseCellMotionMsg{}
 }
@@ -72,7 +76,7 @@ type enableMouseCellMotionMsg struct{}
 // button is pressed, effectively enabling support for hover interactions.
 //
 // Many modern terminals support this, but not all. If in doubt, use
-// EnableMouseCellMotion instead.
+// [EnableMouseCellMotion] instead.
 //
 // Because commands run asynchronously, this command should not be used in your
 // model's Init function. Use the WithMouseAllMotion ProgramOption instead.
@@ -108,6 +112,9 @@ type hideCursorMsg struct{}
 
 // ShowCursor is a special command for manually instructing Bubble Tea to show
 // the cursor.
+//
+// Deprecated: this will be removed in a future release. In v2, the cursor will
+// can be manged via a dedicated API.
 func ShowCursor() Msg {
 	return showCursorMsg{}
 }
@@ -117,9 +124,10 @@ func ShowCursor() Msg {
 type showCursorMsg struct{}
 
 // EnableBracketedPaste is a special command that tells the Bubble Tea program
-// to accept bracketed paste input.
+// to accept bracketed paste input. To disable bracketed paste, use
+// [DisableBracketedPaste].
 //
-// Note that bracketed paste will be automatically disabled when the
+// Also note that bracketed paste will be automatically disabled when the
 // program quits.
 func EnableBracketedPaste() Msg {
 	return enableBracketedPasteMsg{}
@@ -131,17 +139,18 @@ func EnableBracketedPaste() Msg {
 type enableBracketedPasteMsg struct{}
 
 // DisableBracketedPaste is a special command that tells the Bubble Tea program
-// to accept bracketed paste input.
+// to accept bracketed paste input. To enable bracketed paste, use
+// [EnableBracketedPaste].
 //
-// Note that bracketed paste will be automatically disabled when the
+// Also note that bracketed paste will be automatically disabled when the
 // program quits.
 func DisableBracketedPaste() Msg {
 	return disableBracketedPasteMsg{}
 }
 
-// disableBracketedPasteMsg in an internal message signals that
-// bracketed paste should be disabled. You can send an
-// disableBracketedPasteMsg with DisableBracketedPaste.
+// disableBracketedPasteMsg in an internal message signals that bracketed paste
+// should be disabled. You can send an disableBracketedPasteMsg with
+// DisableBracketedPaste.
 type disableBracketedPasteMsg struct{}
 
 // enableReportFocusMsg is an internal message that signals to enable focus
@@ -167,7 +176,7 @@ func DisableReportFocus() Msg {
 // EnterAltScreen enters the alternate screen buffer, which consumes the entire
 // terminal window. ExitAltScreen will return the terminal to its former state.
 //
-// Deprecated: Use the WithAltScreen ProgramOption instead.
+// Deprecated: Use the [EnterAltScreen] [Cmd] instead.
 func (p *Program) EnterAltScreen() {
 	if p.renderer != nil {
 		p.renderer.enterAltScreen()
@@ -190,7 +199,7 @@ func (p *Program) ExitAltScreen() {
 // EnableMouseCellMotion enables mouse click, release, wheel and motion events
 // if a mouse button is pressed (i.e., drag events).
 //
-// Deprecated: Use the WithMouseCellMotion ProgramOption instead.
+// Deprecated: Use the [EnableMouseCellMotion] [Cmd] instead.
 func (p *Program) EnableMouseCellMotion() {
 	if p.renderer != nil {
 		p.renderer.enableMouseCellMotion()
@@ -215,7 +224,7 @@ func (p *Program) DisableMouseCellMotion() {
 // regardless of whether a mouse button is pressed. Many modern terminals
 // support this, but not all.
 //
-// Deprecated: Use the WithMouseAllMotion ProgramOption instead.
+// Deprecated: Use the [EnableMouseAllMotion] [Cmd] instead.
 func (p *Program) EnableMouseAllMotion() {
 	if p.renderer != nil {
 		p.renderer.enableMouseAllMotion()