Add support for OSC 99 desktop notifications

Author: danielgatis

README.md

@@ -152,6 +152,7 @@ Configure terminal at creation:
 - `WithBell(provider)`: Handler for bell events
 - `WithTitle(provider)`: Handler for title changes
 - `WithClipboard(provider)`: Handler for OSC 52 clipboard
+- `WithNotification(provider)`: Handler for OSC 99 desktop notifications (Kitty protocol)
 - `WithMiddleware(mw)`: Intercept handler calls
 
 ### Providers
@@ -162,6 +163,7 @@ Interfaces for external events (all optional, default to no-ops):
 - `ClipboardProvider`: Called on OSC 52 (clipboard read/write)
 - `ScrollbackProvider`: Stores lines scrolled off top
 - `RecordingProvider`: Captures raw input bytes
+- `NotificationProvider`: Called on OSC 99 (desktop notifications, Kitty protocol)
 
 ### Dirty tracking
 
@@ -172,6 +174,40 @@ Cells track modification state:
 
 Useful for incremental rendering (only redraw changed cells).
 
+### Desktop Notifications (OSC 99)
+
+The terminal supports the Kitty desktop notification protocol (OSC 99). Implement `NotificationProvider` to handle notifications:
+
+```go
+type MyNotificationHandler struct{}
+
+func (h *MyNotificationHandler) Notify(payload *headlessterm.NotificationPayload) string {
+    // Handle the notification
+    fmt.Printf("Notification: %s\n", string(payload.Data))
+
+    // For query requests, return capabilities
+    if payload.PayloadType == "?" {
+        return "\x1b]99;i=test;p=title:body\x1b\\"
+    }
+    return ""
+}
+
+term := headlessterm.New(
+    headlessterm.WithNotification(&MyNotificationHandler{}),
+)
+```
+
+The `NotificationPayload` contains:
+- `ID`: Unique identifier for chunking/tracking
+- `PayloadType`: Type of data ("title", "body", "icon", "?", etc.)
+- `Data`: Payload content (decoded if base64)
+- `Urgency`: 0 (low), 1 (normal), 2 (critical)
+- `Sound`: Notification sound ("system", "silent", etc.)
+- `Actions`: Click behavior ("focus", "report")
+- And more fields for icons, timeouts, app name, etc.
+
+See [Kitty Desktop Notifications](https://sw.kovidgoyal.net/kitty/desktop-notifications/) for protocol details.
+
 ## Buy me a coffee
 
 Liked some of my work? Buy me a coffee (or more likely a beer)

go.mod

@@ -3,7 +3,7 @@ module github.com/danielgatis/go-headless-term
 go 1.25.1
 
 require (
-	github.com/danielgatis/go-ansicode v1.0.12
+	github.com/danielgatis/go-ansicode v1.0.13
 	github.com/unilibs/uniwidth v0.1.0
 )
 

go.sum

@@ -1,5 +1,5 @@
-github.com/danielgatis/go-ansicode v1.0.12 h1:x23jSR5nvnhBLirKJC9qz/INcSKZct77jB0PAMug1G8=
-github.com/danielgatis/go-ansicode v1.0.12/go.mod h1:bQSArJFM0i5KrUsziqk5yrLryYSK30NNOzOTnTm2dGg=
+github.com/danielgatis/go-ansicode v1.0.13 h1:RadT1hkYsO6JphWiC4T1NVRjkVAiRtwI9Q9LM90WwCA=
+github.com/danielgatis/go-ansicode v1.0.13/go.mod h1:bQSArJFM0i5KrUsziqk5yrLryYSK30NNOzOTnTm2dGg=
 github.com/danielgatis/go-iterator v0.0.1 h1:pTptWDVAKzR0EUdtfmFMP3v+hSetqB091V9um1DTO8I=
 github.com/danielgatis/go-iterator v0.0.1/go.mod h1:+gTbPAMdVIKwmqw7kr/mo5IFIzz2MFiRyYylcRvgbHs=
 github.com/danielgatis/go-utf8 v1.0.1 h1:0tXC3eI9I+11X3DwF46Auqjcq1KrsQCQsaI8k/ymGhU=

handler.go

@@ -1595,6 +1595,28 @@ func (t *Terminal) startOfStringReceivedInternal(data []byte) {
 	}
 }
 
+// DesktopNotification handles OSC 99 desktop notification sequences (Kitty protocol).
+// It delegates to the configured NotificationProvider if present.
+// Responses from the provider (e.g., for query requests) are written back to the terminal.
+func (t *Terminal) DesktopNotification(payload *NotificationPayload) {
+	if t.middleware != nil && t.middleware.DesktopNotification != nil {
+		t.middleware.DesktopNotification(payload, t.desktopNotificationInternal)
+		return
+	}
+	t.desktopNotificationInternal(payload)
+}
+
+func (t *Terminal) desktopNotificationInternal(payload *NotificationPayload) {
+	if t.notificationProvider == nil {
+		return
+	}
+
+	response := t.notificationProvider.Notify(payload)
+	if response != "" {
+		t.writeResponseString(response)
+	}
+}
+
 // SetTerminalCharAttribute applies SGR attributes to the cell template (colors, bold, underline, etc.).
 func (t *Terminal) SetTerminalCharAttribute(attr ansicode.TerminalCharAttribute) {
 	if t.middleware != nil && t.middleware.SetTerminalCharAttribute != nil {

middleware.go

@@ -212,6 +212,9 @@ type Middleware struct {
 
 	// SixelReceived wraps the SixelReceived handler
 	SixelReceived func(params [][]uint16, data []byte, next func([][]uint16, []byte))
+
+	// DesktopNotification wraps the DesktopNotification handler (OSC 99)
+	DesktopNotification func(payload *NotificationPayload, next func(*NotificationPayload))
 }
 
 // Merge copies non-nil middleware functions from other into this, overwriting existing values.
@@ -424,4 +427,7 @@ func (m *Middleware) Merge(other *Middleware) {
 	if other.SixelReceived != nil {
 		m.SixelReceived = other.SixelReceived
 	}
+	if other.DesktopNotification != nil {
+		m.DesktopNotification = other.DesktopNotification
+	}
 }