Implement Enable/Disable/Detect Kitty Keyboard Protocol

ansicolors.go

@@ -1,6 +1,6 @@
 package termenv
 
-// ANSI color codes
+// ANSI color codes.
 const (
 	ANSIBlack ANSIColor = iota
 	ANSIRed

color.go

@@ -14,7 +14,7 @@
 	ErrInvalidColor = errors.New("invalid color")
 )
 
-// Foreground and Background sequence codes
+// Foreground and Background sequence codes.
 const (
 	Foreground = "38"
 	Background = "48"
@@ -83,9 +83,9 @@
 	}
 
 	if col < 8 {
 		return fmt.Sprintf("%d", bgMod(col)+30)
 	}
 	return fmt.Sprintf("%d", bgMod(col-8)+90)
 }
 
 // Sequence returns the ANSI Sequence for the color.
@@ -108,7 +108,7 @@
 	if bg {
 		prefix = Background
 	}
 	return fmt.Sprintf("%s;2;%d;%d;%d", prefix, uint8(f.R*255), uint8(f.G*255), uint8(f.B*255))
 }
 
 func xTermColor(s string) (RGBColor, error) {
@@ -166,13 +166,13 @@
 		if v < 115 {
 			return 1
 		}
 		return int((v - 35) / 40)
 	}
 
 	// Calculate the nearest 0-based color index at 16..231
 	r := v2ci(c.R * 255.0) // 0..5 each
 	g := v2ci(c.G * 255.0)
 	b := v2ci(c.B * 255.0)
 	ci := 36*r + 6*g + b /* 0..215 */
 
 	// Calculate the represented colors back from the index
@@ -198,7 +198,7 @@
 	grayDist := c.DistanceHSLuv(g2)
 
 	if colorDist <= grayDist {
 		return ANSI256Color(16 + ci)
 	}
 	return ANSI256Color(232 + grayIdx)
 }

output.go

@@ -35,6 +35,8 @@ type Output struct {
 	fgColor   Color
 	bgSync    *sync.Once
 	bgColor   Color
+	kkpFlags  byte
+	kkpSync   *sync.Once
 }
 
 // Environ is an interface for getting environment variables.
@@ -205,3 +207,33 @@ func (o Output) Write(p []byte) (int, error) {
 func (o Output) WriteString(s string) (int, error) {
 	return o.Write([]byte(s))
 }
+
+// KittyKeyboardProtocolSupport returns which progressive enhancements the
+// terminal supports for the kitty keyboard protocol.
+//
+// https://sw.kovidgoyal.net/kitty/keyboard-protocol/#progressive-enhancement
+//
+// The byte returned represents the bitset of supported flags.
+//
+// 0b1     (01) — Disambiguate escape codes
+// 0b10    (02) — Report event types
+// 0b100   (04) — Report alternate keys
+// 0b1000  (08) — Report all keys as escape codes
+// 0b10000 (16) — Report associated text.
+func (o Output) KittyKeyboardProtocolSupport() byte {
+	f := func() {
+		if !o.isTTY() {
+			return
+		}
+
+		o.kkpFlags = o.kittyKeyboardProtocolSupport()
+	}
+
+	if o.cache {
+		o.kkpSync.Do(f)
+	} else {
+		f()
+	}
+
+	return o.kkpFlags
+}

profile.go

@@ -12,13 +12,13 @@ import (
 type Profile int
 
 const (
-	// TrueColor, 24-bit color profile
+	// TrueColor, 24-bit color profile.
 	TrueColor = Profile(iota)
-	// ANSI256, 8-bit color profile
+	// ANSI256, 8-bit color profile.
 	ANSI256
-	// ANSI, 4-bit color profile
+	// ANSI, 4-bit color profile.
 	ANSI
-	// Ascii, uncolored profile
+	// Ascii, uncolored profile.
 	Ascii //nolint:revive
 )
 

screen.go

@@ -60,6 +60,11 @@
 	StartBracketedPasteSeq   = "200~"
 	EndBracketedPasteSeq     = "201~"
 
+	// Kitty Keyboard Protocol.
+	// https://sw.kovidgoyal.net/kitty/keyboard-protocol
+	EnableKittyKeyboardProtocol  = ">1u"
+	DisableKittyKeyboardProtocol = "<u"
+
 	// Session.
 	SetWindowTitleSeq     = "2;%s" + string(BEL)
 	SetForegroundColorSeq = "10;%s" + string(BEL)
@@ -113,7 +118,7 @@
 
 // ClearScreen clears the visible portion of the terminal.
 func (o Output) ClearScreen() {
 	fmt.Fprintf(o.w, CSI+EraseDisplaySeq, 2)
 	o.MoveCursor(1, 1)
 }
 
@@ -301,6 +306,16 @@
 	fmt.Fprintf(o.w, CSI+DisableBracketedPasteSeq)
 }
 
+// EnableKittyKeyboardProtocol enables the kitty keyboard protocol.
+func (o Output) EnableKittyKeyboardProtocol() {
+	fmt.Fprintf(o.w, CSI+EnableKittyKeyboardProtocol)
+}
+
+// DisableKittyKeyboardProtocol disables the kitty keyboard protocol.
+func (o Output) DisableKittyKeyboardProtocol() {
+	fmt.Fprintf(o.w, CSI+DisableKittyKeyboardProtocol)
+}
+
 // Legacy functions.
 
 // Reset the terminal to its default style, removing any active styles.

termenv.go

@@ -13,15 +13,15 @@ var (
 )
 
 const (
-	// Escape character
+	// Escape character.
 	ESC = '\x1b'
-	// Bell
+	// Bell.
 	BEL = '\a'
-	// Control Sequence Introducer
+	// Control Sequence Introducer.
 	CSI = string(ESC) + "["
-	// Operating System Command
+	// Operating System Command.
 	OSC = string(ESC) + "]"
-	// String Terminator
+	// String Terminator.
 	ST = string(ESC) + `\`
 )
 

termenv_unix.go

@@ -14,7 +14,7 @@
 )
 
 const (
-	// timeout for OSC queries
+	// timeout for OSC queries.
 	OSCTimeout = 5 * time.Second
 )
 
@@ -113,6 +113,79 @@
 	return ANSIColor(0)
 }
 
+func (o Output) kittyKeyboardProtocolSupport() byte {
+	// screen/tmux can't support OSC, because they can be connected to multiple
+	// terminals concurrently.
+	term := o.environ.Getenv("TERM")
+	if strings.HasPrefix(term, "screen") || strings.HasPrefix(term, "tmux") {
+		return 0
+	}
+
+	tty := o.TTY()
+	if tty == nil {
+		return 0
+	}
+
+	if !o.unsafe {
+		fd := int(tty.Fd())
+		// if in background, we can't control the terminal
+		if !isForeground(fd) {
+			return 0
+		}
+
+		t, err := unix.IoctlGetTermios(fd, tcgetattr)
+		if err != nil {
+			return 0
+		}
+		defer unix.IoctlSetTermios(fd, tcsetattr, t) //nolint:errcheck
+
+		noecho := *t
+		noecho.Lflag = noecho.Lflag &^ unix.ECHO
+		noecho.Lflag = noecho.Lflag &^ unix.ICANON
+		if err := unix.IoctlSetTermios(fd, tcsetattr, &noecho); err != nil {
+			return 0
+		}
+	}
+
+	// first, send CSI query to see whether this terminal supports the
+	// kitty keyboard protocol
+	fmt.Fprintf(tty, CSI+"?u")
+
+	// then, query primary device data, should be supported by all terminals
+	// if we receive a response for the primary device data befor the kitty keyboard
+	// protocol response, this terminal does not support kitty keyboard protocol.
+	fmt.Fprintf(tty, CSI+"c")
+
+	response, isAttrs, err := o.readNextResponseKittyKeyboardProtocol()
+
+	// we queried for the kitty keyboard protocol current progressive enhancements
+	// but received the primary device attributes response, therefore this terminal
+	// does not support the kitty keyboard protocol.
+	if err != nil || isAttrs {
+		return 0
+	}
+
+	// read the primary attrs response and ignore it.
+	_, _, err = o.readNextResponseKittyKeyboardProtocol()
+	if err != nil {
+		return 0
+	}
+
+	// we receive a valid response to the kitty keyboard protocol query, this
+	// terminal supports the protocol.
+	//
+	// parse the response and return the flags supported.
+	//
+	//   0    1 2 3 4
+	//   \x1b [ ? 1 u
+	//
+	if len(response) <= 3 {
+		return 0
+	}
+
+	return response[3]
+}
+
 func (o *Output) waitForData(timeout time.Duration) error {
 	fd := o.TTY().Fd()
 	tv := unix.NsecToTimeval(int64(timeout))
@@ -157,6 +230,62 @@
 	return b[0], nil
 }
 
+// readNextResponseKittyKeyboardProtocol reads either a CSI response to the current
+// progressive enhancement status or primary device attributes response.
+//   - CSI response: "\x1b]?31u"
+//   - primary device attributes response: "\x1b]?64;1;2;7;8;9;15;18;21;44;45;46c"
+func (o *Output) readNextResponseKittyKeyboardProtocol() (response string, isAttrs bool, err error) {
+	start, err := o.readNextByte()
+	if err != nil {
+		return "", false, ErrStatusReport
+	}
+
+	// first byte must be ESC
+	for start != ESC {
+		start, err = o.readNextByte()
+		if err != nil {
+			return "", false, ErrStatusReport
+		}
+	}
+
+	response += string(start)
+
+	// next byte is [
+	tpe, err := o.readNextByte()
+	if err != nil {
+		return "", false, ErrStatusReport
+	}
+	response += string(tpe)
+
+	if tpe != '[' {
+		return "", false, ErrStatusReport
+	}
+
+	for {
+		b, err := o.readNextByte()
+		if err != nil {
+			return "", false, ErrStatusReport
+		}
+		response += string(b)
+
+		switch b {
+		case 'u':
+			// kitty keyboard protocol response
+			return response, false, nil
+		case 'c':
+			// primary device attributes response
+			return response, true, nil
+		}
+
+		// both responses have less than 38 bytes, so if we read more, that's an error
+		if len(response) > 38 {
+			break
+		}
+	}
+
+	return response, isAttrs, nil
+}
+
 // readNextResponse reads either an OSC response or a cursor position response:
 //   - OSC response: "\x1b]11;rgb:1111/1111/1111\x1b\\"
 //   - cursor position response: "\x1b[42;1R"

termenv_windows.go

@@ -54,6 +54,11 @@ func (o Output) backgroundColor() Color {
 	return ANSIColor(0)
 }
 
+func (o Output) kittyKeyboardProtocolSupport() byte {
+	// default byte
+	return 0b00000
+}
+
 // EnableWindowsANSIConsole enables virtual terminal processing on Windows
 // platforms. This allows the use of ANSI escape sequences in Windows console
 // applications. Ensure this gets called before anything gets rendered with