Spec for extended keyboard protocol

protocol-extensions.asciidoc

@@ -301,3 +301,78 @@ the file repeatedly with no overhead.
 | y  | _y-offset_ -- the row in the pixel data to start from (0-based)
 
 |===
+
+
+== Keyboard handling
+
+There are various problems with the current state of keyboard handling. They
+include:
+
+  * No way to use modifiers other than `Ctrl` and `Alt`
+  * No reliable way to distinguish single `Esc` keypresses from the 
+    start of a escape sequence. Currently, client programs use 
+    fragile timing related hacks for this, leading to bugs, for example:
+    link:https://github.com/neovim/neovim/issues/2035[neovim #2035]
+
+There are already two distinct keyboard handling modes, _normal mode_ and
+_application mode_. These modes generate different escape sequences for the
+various special keys (arrow keys, function keys, home/end etc.) Most terminals
+start out in normal mode, however, most shell programs like `bash` switch them to
+application mode. We propose adding a third mode, named _full mode_ that addresses
+the shortcomings listed above.
+
+Switching to the new _full mode_ is accomplished using the standard private
+mode DECSET escape sequence
+
+```
+<ESC>[?2017h
+```
+
+and to leave _full mode_, use DECRST
+
+```
+<ESC>[?2017l
+```
+
+The number `2017` above is not used for any existing modes, as far as I know.
+Client programs can query if the terminal emulator is in _full mode_ by using 
+the standard link:http://vt100.net/docs/vt510-rm/DECRQM[DECRQM] escape sequence.
+
+The new mode works as follows:
+
+  * All printable key presses without modifier keys are sent just as in the
+    _normal mode_. This means all printable ASCII characters and in addition,
+    `Enter`, `Space` and `Backspace`. Also any unicode characters generated by
+    platform specific extended input modes, such as using the `AltGr` key. This
+    is done so that client programs that are not aware of this mode can still
+    handle basic text entry, so if a _full mode_ using program crashes and does
+    not reset, the user can still issue a `reset` command in the shell to restore
+    normal key handling. Note that this includes pressing the `Shift` modifier
+    and printable keys.
+
+  * For non printable keys and key combinations including one or more modifiers,
+    an escape sequence encoding the key event is sent. For details on the
+    escape sequence, see below.
+
+The escape sequence encodes the following properties:
+
+  * Type of event: `press,repeat,release`
+  * Modifiers pressed at the time of the event
+  * The actual key being pressed 
+
+```
+<ESC>_K<type><modifiers>:<key><ESC>\
+```
+
+Where `<type>` is one of `p` -- press, `r` -- release and `t` -- repeat. 
+Modifiers is zero or more of `c` -- Control, `a` -- Alt, `s` -- Shift and `m` -- Meta.
+`<key>` is a number corresponding to the key pressed. The key name to number mapping
+is defined in link:key_encoding.asciidoc[this table].
+
+For example:
+
+```
+<ESC>_Kpca:88<ESC>\
+```
+
+Is the key press event `<Ctrl>+<Alt>+x`.