Input Handling

TUI Input Handling, Raw Mode, Keyboard, Mouse, Paste, and Focus

Use this skill when a TUI reads keys, handles shortcuts, supports mouse, edits text, manages focus, or needs safe paste behavior.

Input contract

• Only enter raw or cbreak mode for interactive TTY sessions.
• Provide non-interactive alternatives for scripts, pipes, and CI.
• Keep input decoding separate from application actions.
• Make every action reachable by keyboard.
• Treat mouse support as optional progressive enhancement.
• Preserve expected terminal shortcuts unless the user can rebind them.

Raw mode rules

Raw mode disables line discipline and changes signal behavior. Centralize it and restore it reliably. Verify behavior for Ctrl-C, Ctrl-Z/suspend where supported, EOF, resize, terminal close, and fatal exceptions. Passwords and tokens must not echo.

Keybinding design

Good keybindings are discoverable, consistent, and conflict-aware.

• Always provide visible help for common actions.
• Use q, Esc, or Ctrl-C for quit/cancel only when consistent with workflow risk.
• Confirm destructive actions; require stronger confirmation for irreversible work.
• Avoid stealing common terminal, shell, editor, and multiplexer shortcuts unless configurable.
• Support both mnemonic shortcuts and navigational keys where possible.
• Distinguish global shortcuts from focused-widget shortcuts.

Focus model

Every interactive element needs:

• A stable identity.
• Focus eligibility rules.
• A visible focus indicator that does not rely on color alone.
• Tab/Shift-Tab or arrow navigation when appropriate.
• Clear behavior for disabled, hidden, modal, and nested controls.
• Mouse click behavior that updates focus before activating actions.

Paste and mouse safety

Enable bracketed paste for shells, editors, command palettes, and multiline inputs. Parse paste start/end markers and treat pasted text as data, not a sequence of commands. For mouse input, validate coordinates against the current layout and ignore stale events after resize.

Failure modes

Reference files

• references/input-protocols.md - Keyboard, mouse, paste, focus, and resize event details.
• references/keybinding-design.md - Shortcut design, conflict avoidance, and forms/editors.

Input Protocols Reference

Keyboard ambiguity

Traditional terminal input was not designed for modern shortcut-rich applications. Esc may be a key, an Alt prefix, or the start of a control sequence. Ctrl combinations collapse onto control bytes. Function keys vary. Prefer framework parsers and only adopt extended keyboard protocols when you can push/pop modes safely and provide fallbacks.

Bracketed paste

Bracketed paste wraps pasted text with start and end markers so the application can insert text literally. Use it for shells, editors, search boxes, command palettes, and multiline forms. Do not execute pasted content automatically. Apply length limits and validation after paste completes.

Keyboard modes

Legacy protocols encode many keys as ambiguous byte sequences. xterm modifyOtherKeys and the Kitty keyboard protocol can distinguish modifiers, key releases, text vs physical keys, and Esc/Alt ambiguity more reliably. Enable them only when the framework supports safe negotiation, preserve legacy fallbacks, and pop modes during cleanup.

Mouse modes

Mouse protocols include X10, normal tracking, button-event tracking, any-event tracking, SGR coordinates, and URXVT-style encodings. SGR mouse mode is easier to parse than older coordinate encodings and avoids small coordinate limits. Mouse events should include button, release, drag, wheel, modifiers, and coordinates. Validate against current layout. Treat wheel, motion, drag, and hover as high-frequency input and throttle expensive side effects.

Drag, drop, touch, and gestures

Terminal drag usually arrives as mouse motion with a button held, not a high-level drag object. Some emulators support file drop as pasted paths or proprietary escape sequences, and touchpads may map gestures to wheel or mouse events. Treat drag/drop/touch as optional enhancements, validate paths as untrusted input, and provide keyboard alternatives.

Resize events

Resize is an input event. It invalidates layout, viewport measurements, mouse hit boxes, wrapped text, table widths, and snapshot expectations. Coalesce resize storms and render a minimum-size fallback when needed.

Focus events

Focus in/out can pause spinners, suppress notifications, or mark stale views, but should never be required for correctness. Terminals and multiplexers may omit or filter focus events.

Keybinding Design Reference

Shortcut hierarchy

1. Global lifecycle keys: help, quit, cancel, command palette. 2. Navigation keys: arrows, Tab, Shift-Tab, PageUp/PageDown, Home/End. 3. Focused widget keys: editor movement, list selection, table sorting. 4. Mode-specific keys: vim-style normal/insert, search, multi-select. 5. Destructive actions: require confirmation and visible labels.

Conflict avoidance

Be careful with shortcuts commonly used by shells, terminals, editors, OSes, and multiplexers: Ctrl-C, Ctrl-D, Ctrl-Z, Ctrl-S, Ctrl-Q, Ctrl-L, Ctrl-R, Ctrl-A/E, Ctrl-U/K/W, Ctrl-Left/Right, Cmd/Ctrl-C/V for copy/paste, tmux prefix combinations, and terminal search shortcuts. Make advanced bindings configurable.

Text input behavior

Users expect familiar editing behavior: left/right by grapheme, word movement, deletion, selection where supported, paste as literal text, history navigation in command prompts, masked secrets, and validation errors near the field. Do not measure cursor position by bytes.

Discoverability

Show a footer for primary actions, context-specific help for focused widgets, and a complete help overlay or command palette. Help text should mention how to exit, how to recover from display corruption, and how to run non-interactively.