KetraTermKeyboard & Mouse Input Serialized Encodings
This reference shows representative bytes generated by ketraterm-input.
ESC is 0x1B, CSI is ESC [, and SS3 is ESC O. Spaces in wire notation
separate fields and are not emitted. See the input contract
for validation, policy, protocol precedence, and coordinate limits.
Keyboard cursor and application modes
These examples assume unmodified presses, legacy keyboard mode, and LNM off.
| Event | Normal mode | Application mode |
|---|---|---|
UP |
CSI A |
SS3 A |
DOWN |
CSI B |
SS3 B |
RIGHT |
CSI C |
SS3 C |
LEFT |
CSI D |
SS3 D |
HOME |
CSI H |
SS3 H |
END |
CSI F |
SS3 F |
NUMPAD_1 |
ASCII 1 |
SS3 q |
NUMPAD_ENTER |
CR | SS3 M |
Application cursor mode (DECCKM) selects the cursor-key column. Application
keypad mode, set by DECKPAM and cleared by DECKPNM, selects the keypad-key column.
HOME and END are cursor keys; they are not keypad aliases. PF1-PF4 are separate
key identities from physical F1-F4.
Modified keys
For the default cursor resource level 2, Ctrl+Up emits CSI 1 ; 5 A.
The modifier parameter is one-based: Shift adds 1, Alt adds 2, Ctrl adds 4, and
merged Super/Hyper/Meta adds 8. Lock bits do not alter xterm parameters.
Ordinary-key extended reports have two layouts:
| Resource format | Ctrl+A example |
|---|---|
0, original xterm |
CSI 27 ; 5 ; 97 ~ |
1, CSI-u |
CSI 97 ; 5 u |
These layouts require the relevant modifier resource to select extended
reporting. Setting a format alone does not enable it. modifyOtherKeys level 1
extends combinations that legacy encoding cannot distinguish or represent, level 2 extends
modified ordinary keys, and level 3 also reports unmodified ordinary keys.
A nonzero Kitty mode takes precedence; its modifier mapping and functional-key
identities differ from xterm's. See the
xterm resource contract and
keyboard contract.
Mouse tracking and encoding protocols
Tracking determines which events reach the wire; encoding determines their byte layout. Selecting SGR encoding does not enable tracking. The default coordinate encoding is legacy, not SGR.
For a left-button press at zero-based cell (0, 0) with no modifiers:
| Encoding | Wire report |
|---|---|
| Default legacy | ESC [ M followed by bytes 0x20 0x21 0x21. |
UTF-8 extended (?1005) |
ESC [ M followed by UTF-8 scalars for 32 + Cb, 32 + x, 32 + y; this example has the same bytes as legacy. |
SGR (?1006) |
CSI < 0 ; 1 ; 1 M |
URXVT (?1015) |
CSI 32 ; 1 ; 1 M |
Here x and y are one-based coordinates and Cb is the unshifted button code.
SGR-Pixels (?1016) uses the SGR layout with one-based pixels. A missing pixel
value (-1) falls back independently to the corresponding cell coordinate.
Left, middle, and right use codes 0, 1, and 2. Motion adds 32; no-button motion
uses base code 3. Wheel up/down/left/right use 64/65/66/67. Shift, Alt, and Ctrl
add 4, 8, and 16. SGR releases keep the button identity and end in lowercase m;
legacy-family releases use base code 3 and the encoding's normal final byte.
Legacy coordinates have a one-based limit of 223; UTF-8 extended coordinates
have a limit of 2015. Decimal encodings safely accept the full non-negative
Int range. See the mouse contract
for suppression, clamping, tracking modes, and release identity rules.