v0.5.0 key releases: key model, protocol source, console sources (#12)

* key model for releases: KeyAction, SetKeyReport, focus and key report events, hold pairing

A key event now carries its Action: KeyPress, KeyRepeat or KeyRelease. Every
terminal still reports presses only, so Action stays KeyPress and every event
is what v0.4.3 sent, until a game asks with SetKeyReport. The ask names the
sources releases may come from (KeySourceConsole, KeySourceProtocol); an
EventKeyReport answers each ask with the level reached and its source. No
source exists yet, so every ask answers presses and nothing is written.

KeyHolds pairs a release with its press by physical key, so a release carries
what its press carried, and turns a source's lost reports into Lost releases.
It is exported for hosts that read native key events (KeySourceHost).

The reader sends keys through the level in force: at presses a repeat is a
press and a release is dropped; at releases a key with no physical key behind
it is a tap. Focus reports end every hold, Lost, before EventFocus; they are
read only once a source turns them on. Mouse events gain a Touch bit for hosts.

Terminal gains SetKeyReport, so this is v0.5.0.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B3zCVjspRDuEuMrDTumVhp

* protocol source: releases from the terminal's key event protocol, Alacritty's

SetKeyReport with KeySourceProtocol asks the terminal whether it has the key
event protocol (CSI ? u, fenced by a DA1 request), pushes its flags (all five,
CSI > 31 u) and asks what they came to before reporting releases. A terminal
must confirm event types, every key as an escape code and the text keys type;
one that answers DA1 alone, takes the push without them, or answers nothing
within two seconds stays at presses, and is not asked again. Detection goes by
these answers only, never by TERM or the terminal's name.

While the flags are pushed, key reports are decoded into the events a legacy
terminal sends for the same keys, so a game can keep the protocol on for its
whole run: Shift goes into the character, Ctrl with a character into its
control key, Alt stays a modifier; Super, the locks, lone modifiers, media keys
and F13 and up report nothing. Ctrl with a character that has no control key
keeps ModCtrl. Releases pair with their presses through KeyHolds; a key the
terminal names none for (text from an input method) is a tap.

Focus reports come on with the protocol and end every hold, Lost, as focus
leaves. Going back to presses releases what is held, pops the flags and stops
focus reports, decoding until the terminal confirms the pop. Fini pops the
flags before the alternate screen goes, and EmergencyReset when they are
pushed. Fini now stops the input reader without holding the terminal's lock,
since the reader writes its requests through it.

Checked against Alacritty 0.13.2 on Xvfb with xdotool: 58 key combinations
read identically with the protocol on and off (Ctrl+1 keeps ModCtrl), every
press got its release, Shift released first still released 'A', focus loss
and a release swallowed by Alacritty's Vi mode ended holds Lost. Inside tmux
3.4 the ask came to presses.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B3zCVjspRDuEuMrDTumVhp

---------

Co-authored-by: Claude <noreply@anthropic.com>

terminal.go

@@ -1,6 +1,7 @@
 package terminal
 
 import (
+	"fmt"
 	"io"
 	"os"
 	"sync"
@@ -97,6 +98,16 @@ type Terminal interface {
 	// SetPasteMode turns bracketed paste on or off: on, a paste arrives as
 	// one EventPaste rather than as keys, so its newlines don't press Enter
 	SetPasteMode(on bool) error
+
+	// SetKeyReport asks for keys to be reported at level report. Releases come
+	// through the first source in allow the terminal has, the console before
+	// the protocol; KeyReportPresses gives up the source in use. It returns at
+	// once, and an EventKeyReport follows with what the terminal reports now,
+	// so a game learns the outcome of every ask; asks the reader has not yet
+	// acted on are answered together, by the latest. A change of source ends
+	// the holds it leaves with Lost releases. Until an ask for releases, nothing
+	// is sent to the terminal or switched.
+	SetKeyReport(report KeyReport, allow KeySource) error
 }
 
 // ResizeEvent represents a terminal resize
@@ -121,6 +132,7 @@ type termImpl struct {
 	finalized   bool
 	mouseMode   MouseMode
 	paste       bool
+	keyProto    bool // the key protocol's flags are pushed
 
 	// Output reaches the terminal on writeLoop's goroutine, so a terminal that
 	// stops reading holds that goroutine rather than whoever draws. queued is what
@@ -198,6 +210,8 @@ func (t *termImpl) Init() error {
 
 	// Create input reader wrapping backend
 	t.input = newInputReader(t.backend)
+	t.input.sources = backendKeySources(t.backend)
+	t.input.write = t.keyWrite
 
 	// Set resize handler on backend
 	t.backend.SetResizeHandler(func(w, h int) {
@@ -271,10 +285,20 @@ func (t *termImpl) Fini() {
 		w.Write(csiPasteOff)
 	}
 
-	// Stop handlers
+	// Key reports as the terminal had them, before the screen they were pushed on goes
+	if t.keyProto {
+		w.Write(csiKeyPop)
+		w.Write(csiFocusOff)
+		t.keyProto = false
+		keyProtoPushed.Store(false)
+	}
+	t.mu.Unlock()
+
+	// Stop handlers; the reader may be waiting on mu to write, and finds Fini begun
 	if t.input != nil {
 		t.input.stop()
 	}
+	t.mu.Lock()
 
 	// Show cursor
 	w.Write(csiCursorShow)
@@ -576,6 +600,44 @@ func (t *termImpl) SetPasteMode(on bool) error {
 	return nil
 }
 
+// keyProtoPushed is whether a Terminal has the key protocol's flags pushed, for
+// EmergencyReset to pop
+var keyProtoPushed atomic.Bool
+
+// keyWrite queues seq, the input reader's request, for the terminal unless Fini
+// has begun; pushed is whether the protocol's flags are pushed once it is
+// written, which Fini and EmergencyReset undo
+func (t *termImpl) keyWrite(seq []byte, pushed bool) bool {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	if !t.initialized || t.finalized {
+		return false
+	}
+	t.releaseLocked()
+	t.output.buf.Write(seq)
+	t.sendLocked()
+	// A terminal that takes a request for its own (an old st restores the
+	// cursor on CSI ? u) has moved it as far as the next frame knows
+	t.output.invalidateCursor()
+	t.keyProto = pushed
+	keyProtoPushed.Store(pushed)
+	return true
+}
+
+// SetKeyReport hands the ask to the input reader, which answers it
+func (t *termImpl) SetKeyReport(report KeyReport, allow KeySource) error {
+	if report > KeyReportReleases {
+		return fmt.Errorf("terminal: unknown key report %d", report)
+	}
+	t.mu.Lock()
+	ready := t.initialized && !t.finalized
+	t.mu.Unlock()
+	if ready {
+		t.input.askKeys(report, allow)
+	}
+	return nil
+}
+
 // EmergencyReset attempts to restore terminal to sane state
 // Call this from panic recovery if Fini() cannot be called normally. Given a
 // redirected stdout, it writes to the controlling terminal instead.
@@ -593,6 +655,10 @@ func EmergencyReset(w io.Writer) {
 	w.Write(csiMouseClickOff)
 	w.Write(csiMouseSGROff)
 	w.Write(csiPasteOff)
+	if keyProtoPushed.Load() {
+		w.Write(csiKeyPop)
+		w.Write(csiFocusOff)
+	}
 
 	// Write sequences to provided writer
 	w.Write(csiCursorShow)