Key Encoding Table

The specification for terminal-input and for Lab 13. Every row should be a unit test.

Bytes are shown in hex and as escapes. CSI = 1b 5b · SS3 = 1b 4f.

Modifier parameter = 1 + shift(1) + alt(2) + ctrl(4) + super(8).

Ordinary Characters

Use the text event for these. Physical keys break on Dvorak and AZERTY; text handles composition and IME correctly.

Named Keys, Unmodified

Arrow Keys (Mode-Dependent)

Modified arrows always use the CSI form, even when DECCKM is set. That asymmetry is xterm's behavior, and programs depend on it:

Home and End take the same form: CSI 1;5 H for Ctrl+Home.

Function Keys

Note the gaps: there is no 16~ and no 22~. They are historical, and getting them wrong shifts every subsequent function key.

Modified: the modifier goes after the number — CSI 15;2~ for Shift+F5, CSI 1;5 P for Ctrl+F1.

Control Combinations

The rule: Ctrl + char = uppercase(char) & 0x1F.

Ctrl+M, Ctrl+I, and Ctrl+[ are not analogous to Enter, Tab, and Escape — they are the same bytes. A program cannot distinguish them, which is why vim cannot bind Ctrl+M separately from Enter.

Ctrl with a digit or punctuation (Ctrl+1, Ctrl+5) has no legacy encoding. Send nothing, or use modifyOtherKeys. Sending a wrong byte is worse than sending none.

Alt / Meta

The rule: ESC prefix, then the key's normal bytes.

Never use 8-bit meta (0x62 | 0x80 = 0xe2) — it is a valid UTF-8 lead byte and collides with text.

macOS: Option is a composing modifier by default (Option+B gives ∫). Provide an "Option as Meta" setting, default it on for the left Option key, and use the logical key rather than the text.

Keypad (DECKPAM / DECKPNM)

Paste

Always:

• Normalize \r\n and \n to \r — the keyboard sends CR, and ICRNL converts. A pasted \n bypasses that path.
• Strip CSI 201~ from the payload. Otherwise a crafted clipboard escapes the envelope and the remainder runs as typed input. This is a real, exploited attack.
• Consider warning on a multi-line paste when the mode is off — it executes immediately.

Mouse

Only sent when a mouse mode (?1000/?1002/?1003) is enabled. Shift always bypasses reporting so the user can select text.

SGR encoding (?1006) — use this

   Press:    CSI < b ; x ; y M       (uppercase M)
   Release:  CSI < b ; x ; y m       (lowercase m)

   b = button + modifiers:
     0 = left   1 = middle   2 = right
     +4 shift   +8 alt       +16 ctrl
     +32 motion
     64 = wheel up   65 = wheel down
   x, y = 1-BASED cell coordinates. Decimal, so no limit.

Legacy X10 (the default without ?1006)

   CSI M Cb Cx Cy      each byte = value + 32

   FATAL LIMIT: one byte per coordinate, so columns/rows above 223 CANNOT be
   encoded. This is why ?1006 exists. Suppress the event rather than emit
   garbage.

Focus (?1004)

Used by vim (reload changed files) and tmux. Two lines to implement.

Beyond the Legacy Protocol

modifyOtherKeys (xterm)

   Enable:  CSI > 4 ; 2 m        Disable: CSI > 4 ; 0 m

   Keys with no legacy encoding become:
     CSI 27 ; <modifier> ; <codepoint> ~

   Ctrl+1        → CSI 27;5;49~
   Ctrl+Shift+A  → CSI 27;6;65~

The kitty keyboard protocol

   CSI > <flags> u    push    CSI < u    pop    CSI ? u    query

   flags: 1 = disambiguate escape codes   (fixes the Escape ambiguity)
          2 = report event types (press/repeat/release)
          4 = report alternate keys
          8 = report all keys as escape codes
         16 = report associated text

   Keys become:  CSI <unicode-key> [; <mods> [: <event>]] u

Recommended scope: the legacy table above, plus modifyOtherKeys, plus kitty flag 1 if you have the appetite. Full kitty support is a stretch goal.

The Escape Ambiguity

   Escape:    1b
   Up arrow:  1b 5b 41
              ^^ identical first byte

A program reading bytes cannot distinguish them without a timeout (25–50 ms is the modern recommendation; tmux's 500 ms default is why "vim feels laggy in tmux").

Your GUI does not have this problem — it receives real key events. A terminal-based mux client does. That is a genuine architectural advantage of a graphical client.

The Test

#![allow(unused)]
fn main() {
#[test]
fn key_encoding_table() {
    let d = TerminalModes::default();
    let mut app = d; app.insert(Mode::APP_CURSOR_KEYS);

    let cases: &[(Key, Modifiers, &TerminalModes, &[u8])] = &[
        (Named(Enter),      NONE,  &d,   b"\r"),
        (Named(Tab),        NONE,  &d,   b"\t"),
        (Named(Tab),        SHIFT, &d,   b"\x1b[Z"),
        (Named(Backspace),  NONE,  &d,   b"\x7f"),
        (Named(Backspace),  CTRL,  &d,   b"\x08"),
        (Named(Escape),     NONE,  &d,   b"\x1b"),
        (Named(ArrowUp),    NONE,  &d,   b"\x1b[A"),
        (Named(ArrowUp),    NONE,  &app, b"\x1bOA"),
        (Named(ArrowUp),    CTRL,  &d,   b"\x1b[1;5A"),
        (Named(ArrowUp),    CTRL,  &app, b"\x1b[1;5A"),   // CSI even under DECCKM
        (Named(Home),       NONE,  &d,   b"\x1b[H"),
        (Named(End),        NONE,  &d,   b"\x1b[F"),
        (Named(Delete),     NONE,  &d,   b"\x1b[3~"),
        (Named(Delete),     CTRL,  &d,   b"\x1b[3;5~"),
        (Named(F1),         NONE,  &d,   b"\x1bOP"),
        (Named(F5),         NONE,  &d,   b"\x1b[15~"),
        (Named(F12),        NONE,  &d,   b"\x1b[24~"),
        (Named(F5),         SHIFT, &d,   b"\x1b[15;2~"),
        (Char('c'),         CTRL,  &d,   b"\x03"),
        (Char('['),         CTRL,  &d,   b"\x1b"),
        (Named(Space),      CTRL,  &d,   b"\x00"),
        (Char('b'),         ALT,   &d,   b"\x1bb"),
        (Char('c'),         CTRL_ALT, &d, b"\x1b\x03"),
    ];
    for (key, mods, modes, want) in cases {
        assert_eq!(encode_key(*key, *mods, modes).as_deref(), Some(*want),
                   "key={key:?} mods={mods:?}");
    }
}
}

Verifying Against a Real Terminal

# Run your Lab 1 inspector in xterm and in your terminal; press the same keys
# in the same order; diff.
cargo run -p raw-inspector | tee /tmp/reference.txt     # in xterm
cargo run -p raw-inspector | tee /tmp/mine.txt          # inside your terminal
diff /tmp/reference.txt /tmp/mine.txt

Every difference is a bug or a deliberate decision. Write the table: key, reference bytes, your bytes, verdict.

See also: Input Encoding · Trace a Keystroke · Escape Sequence Cheat Sheet