Module key_trace 

Env-gated key-event tracing for diagnosing terminal input problems (remote/mobile clients, “Enter inserted a newline”, paste-vs-typed Enter…).

Enable with RPI_DEBUG_KEYS=1 (appends to <temp>/rpi-keys.log) or RPI_DEBUG_KEYS=<path> to pick the file. Every key the TUI dispatches is appended as one line — wall clock, key code, modifiers, event kind, plus a caller-supplied note (the paste-burst decision, for example):

2026-09-24T12:00:01.234Z code=Char('h') mods=NONE kind=Press
2026-09-24T12:00:01.235Z code=Enter mods=NONE kind=Press gap_ms=1 more_queued=false -> newline (paste burst, Windows only)

What a remote client sends for Enter varies. A phone/RDP client that injects a real key event shows up as code=Enter mods=NONE (and mods=SHIFT when Shift is held), while one that encodes Enter as a bare LF shows up as code=Char('j') mods=CONTROL — in raw mode crossterm decodes the byte 0x0A through its control-code table (0x0A is both LF and Ctrl+J). On Windows the paste-burst decision also prints more_queued=, which is why the probe ignores a key’s own Release event.

Tracing is off unless the env var is set: when disabled the cost is a single OnceLock lookup per key.

Functions

enabled

Whether key tracing is enabled.

key

Append one key event, with an optional note describing what the TUI decided.

note

Append a free-form note (startup banner, terminal info, …).

path

Path the trace is written to (for the startup banner / user hints).