Skip to main content

Module keymap_terminal

lattice_host

Module keymap_terminal 

Source
Expand description

Keystroke → ANSI byte encoder for Terminal-Insert mode.

Terminal-mode T2.a (2026-05-25): the minimum table that lets a user type at a shell prompt and run commands:

  • printable chars (ASCII + UTF-8) → their bytes.
  • Enter → \r.
  • Tab → \t; Shift-Tab → \x1b[Z (backtab CSI Z).
  • Backspace → \x7f (DEL — what xterm sends by default).
  • Esc → \x1b.
  • Ctrl-a..Ctrl-z → \x01..\x1a.
  • Ctrl-[ / Ctrl-\ / Ctrl-] / Ctrl-^ / Ctrl-_ / Ctrl-Space / Ctrl-@ → their canonical bytes per the VT/xterm table.

Terminal-mode T2.b (2026-05-25): full encoder.

  • Arrows / Home / End / PgUp / PgDn / Insert / Delete → CSI sequences (DECCKM-OFF; the application-cursor-keys variant lands when the alacritty_terminal swap tracks the mode bit).
  • F1–F4 → SS3 ESC O P/Q/R/S.
  • F5–F12 → CSI ESC [ <n> ~.
  • Alt + key → ESC-prefix encoding (\x1b then the key’s own bytes).
  • Shift / Ctrl on arrows / F-keys use the xterm modifyOtherKeys-style ;<n> parameter.

DECCKM (application-cursor-keys) tracking is deferred to T2.c once lattice-terminal::reader swaps to alacritty_terminal, which surfaces the mode bit per terminal. The encoder takes cursor_keys_application_mode: bool so the wiring is one-call-site when the substrate lands; today the only caller passes false (xterm-default cursor keys).

Lives here in lattice-host because crate::chord::KeyChord is host-owned and the substrate crate (lattice-terminal) can’t depend on the host without a cycle. If KeyChord ever moves down to lattice-core this module can relocate to lattice-terminal::encode without changing the surface.

Functions§

key_to_ansi
Encode a single key chord into PTY-stdin bytes. Returns None for chords with no Terminal-Insert meaning yet (modifier-only releases, unmapped F-keys beyond F12). Callers treat None as a no-op rather than a translation error.
key_to_ansi_with_mode
Lower-level encoder with explicit cursor-key mode. When cursor_keys_application_mode is true, bare arrow keys encode as ESC O <letter> (SS3) instead of ESC [ <letter> (CSI). The rest of the table is independent of the mode bit.