feat: Desktop notifications (fixes #499)

This only adds support for OSC 777 terminals, but that seems to
include ghostty, wezterm, and probably a number of others.
A demo is included.

Author: gdamore

_demos/notify.go

@@ -0,0 +1,97 @@
+//go:build ignore
+// +build ignore
+
+// Copyright 2025 The TCell Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use file except in compliance with the License.
+// You may obtain a copy of the license at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"fmt"
+	"os"
+	"time"
+
+	"github.com/gdamore/tcell/v3"
+)
+
+func displayHelloWorld(s tcell.Screen, secs int) {
+	w, h := s.Size()
+	s.Clear()
+	style := tcell.StyleDefault.Foreground(tcell.ColorCadetBlue.TrueColor()).Background(tcell.ColorWhite)
+	msg := "Notification Demo"
+	s.PutStrStyled((w-len(msg))/2, h/2-1, msg, style)
+	msg = "(Minimize This Window)"
+	s.PutStrStyled((w-len(msg))/2, h/2+1, msg, style)
+	if secs > 0 {
+		msg = fmt.Sprintf("Incoming in %d Seconds", secs)
+	} else {
+		msg = "Notification Sent!"
+	}
+	s.PutStr((w-len(msg))/2, h/2+3, msg)
+	msg = "Press ESC to exit, ENTER to restart."
+	s.PutStr((w-len(msg))/2, h/2+5, msg)
+	s.Show()
+}
+
+// This program just prints "Hello, World!".  Press ESC to exit.
+func main() {
+
+	s, e := tcell.NewScreen()
+	if e != nil {
+		fmt.Fprintf(os.Stderr, "%v\n", e)
+		os.Exit(1)
+	}
+	if e := s.Init(); e != nil {
+		fmt.Fprintf(os.Stderr, "%v\n", e)
+		os.Exit(1)
+	}
+
+	defStyle := tcell.StyleDefault.
+		Background(tcell.ColorBlack).
+		Foreground(tcell.ColorWhite)
+	s.SetStyle(defStyle)
+
+	when := 10
+	displayHelloWorld(s, when)
+
+	ticker := time.NewTicker(time.Second)
+	var ev tcell.Event
+	for {
+		select {
+		case ev = <-s.EventQ():
+		case <-ticker.C:
+			if when > 0 {
+				when--
+				if when == 0 {
+					s.ShowNotification("Ding Dong!", "The wicked witch is dead.")
+				}
+			}
+			displayHelloWorld(s, when)
+			continue
+		}
+		switch ev := ev.(type) {
+		case *tcell.EventResize:
+			s.Sync()
+		case *tcell.EventKey:
+			switch ev.Key() {
+			case tcell.KeyEnter:
+				when = 10
+			case tcell.KeyEscape:
+				s.Fini()
+				os.Exit(0)
+			}
+		}
+		displayHelloWorld(s, when)
+	}
+}

screen.go

@@ -233,6 +233,10 @@ type Screen interface {
 	// EventPaste with the clipboard content as the Data() field.  Terminals may
 	// prevent this for security reasons.
 	GetClipboard()
+
+	// ShowNotification is used to show a desktop notification, when the terminal
+	// supports it.  Right now only terminals supporting OSC 777 support this.
+	ShowNotification(title string, body string)
 }
 
 // NewScreen returns a default Screen suitable for the user's terminal
@@ -300,6 +304,7 @@ type screenImpl interface {
 	Tty() (Tty, bool)
 	SetClipboard([]byte)
 	GetClipboard()
+	ShowNotification(string, string)
 
 	// Following methods are not part of the Screen api, but are used for interaction with
 	// the common layer code.

simulation.go

@@ -502,3 +502,5 @@ func (s *simscreen) GetClipboard() {
 func (s *simscreen) GetClipboardData() []byte {
 	return s.clipboard
 }
+
+func (s *simscreen) ShowNotification(_ string, _ string) {}

tscreen.go

@@ -120,57 +120,58 @@ func NewTerminfoScreenFromTty(tty Tty) (Screen, error) {
 
 // tScreen represents a screen backed by a terminfo implementation.
 type tScreen struct {
-	tty          Tty
-	h            int
-	w            int
-	fini         bool
-	cells        CellBuffer
-	buffering    bool // true if we are collecting writes to buf instead of sending directly to out
-	buf          bytes.Buffer
-	curstyle     Style
-	style        Style
-	resizeQ      chan bool
-	quit         chan struct{}
-	keychan      chan []byte
-	cx           int
-	cy           int
-	clear        bool
-	cursorx      int
-	cursory      int
-	acs          map[rune]string
-	charset      string
-	encoder      transform.Transformer
-	decoder      transform.Transformer
-	fallback     map[rune]string
-	ncolor       int
-	colors       map[Color]Color
-	palette      []Color
-	truecolor    bool
-	legacy       bool
-	finiOnce     sync.Once
-	enterUrl     string
-	exitUrl      string
-	setWinSize   string
-	cursorStyles map[CursorStyle]string
-	cursorStyle  CursorStyle
-	cursorColor  Color
-	cursorRGB    string
-	cursorFg     string
-	stopQ        chan struct{}
-	eventQ       chan Event
-	running      bool
-	wg           sync.WaitGroup
-	mouseFlags   MouseFlags
-	pasteEnabled bool
-	focusEnabled bool
-	setTitle     string
-	saveTitle    string
-	restoreTitle string
-	title        string
-	setClipboard string
-	enableCsiU   string
-	disableCsiU  string
-	input        *inputProcessor
+	tty           Tty
+	h             int
+	w             int
+	fini          bool
+	cells         CellBuffer
+	buffering     bool // true if we are collecting writes to buf instead of sending directly to out
+	buf           bytes.Buffer
+	curstyle      Style
+	style         Style
+	resizeQ       chan bool
+	quit          chan struct{}
+	keychan       chan []byte
+	cx            int
+	cy            int
+	clear         bool
+	cursorx       int
+	cursory       int
+	acs           map[rune]string
+	charset       string
+	encoder       transform.Transformer
+	decoder       transform.Transformer
+	fallback      map[rune]string
+	ncolor        int
+	colors        map[Color]Color
+	palette       []Color
+	truecolor     bool
+	legacy        bool
+	finiOnce      sync.Once
+	enterUrl      string
+	exitUrl       string
+	setWinSize    string
+	cursorStyles  map[CursorStyle]string
+	cursorStyle   CursorStyle
+	cursorColor   Color
+	cursorRGB     string
+	cursorFg      string
+	stopQ         chan struct{}
+	eventQ        chan Event
+	running       bool
+	wg            sync.WaitGroup
+	mouseFlags    MouseFlags
+	pasteEnabled  bool
+	focusEnabled  bool
+	setTitle      string
+	saveTitle     string
+	restoreTitle  string
+	title         string
+	setClipboard  string
+	notifyDesktop string
+	enableCsiU    string
+	disableCsiU   string
+	input         *inputProcessor
 
 	sync.Mutex
 }
@@ -293,6 +294,11 @@ func (t *tScreen) prepareExtendedOSC() {
 	// sent string, when we support that.
 	t.setClipboard = "\x1b]52;c;%s\x1b\\"
 
+	// OSC 777 is the desktop notification supported by a variety of
+	// newer terminals.  (There was also OSC 9 and OSC 99, but they
+	// are not as widely deployed, and OSC 9 is not unique.)
+	t.notifyDesktop = "\x1b]777;notify;%s;%s\x1b\\"
+
 	if t.enableCsiU == "" {
 		if runtime.GOOS == "windows" && (os.Getenv("TERM") == "" || os.Getenv("TERM_PROGRAM") == "WezTerm") {
 			// on Windows, if we don't have a TERM, use only win32-input-mode
@@ -1179,3 +1185,9 @@ func (t *tScreen) GetClipboard() {
 	}
 	t.Unlock()
 }
+
+func (t *tScreen) ShowNotification(title string, body string) {
+	t.Lock()
+	t.Printf(t.notifyDesktop, title, body)
+	t.Unlock()
+}

wscreen.go

@@ -309,7 +309,7 @@ func (t *wScreen) postEvent(ev Event) {
 	}
 }
 
-func (t *wScreen) onMouseEvent(this js.Value, args []js.Value) interface{} {
+func (t *wScreen) onMouseEvent(this js.Value, args []js.Value) any {
 	mod := ModNone
 	button := ButtonNone
 
@@ -395,7 +395,7 @@ func (t *wScreen) onFocus(this js.Value, args []js.Value) any {
 // happen when javascript calls a function (for example, when
 // mouse input is disabled, when onMouseEvent() is called from
 // js, it redirects here and does nothing).
-func (t *wScreen) unset(this js.Value, args []js.Value) interface{} {
+func (t *wScreen) unset(this js.Value, args []js.Value) any {
 	return nil
 }
 
@@ -496,6 +496,8 @@ func (t *wScreen) SetTitle(title string) {
 	js.Global().Call("setTitle", title)
 }
 
+func (*wScreen) ShowNotification(title string, body string) {}
+
 // WebKeyNames maps string names reported from HTML
 // (KeyboardEvent.key) to tcell accepted keys.
 var WebKeyNames = map[string]Key{