Input API

The input module controls the native listener and exposes consuming and non-consuming snapshots. Built-in widgets usually receive input through engine.main_loop(), not through manual feed calls.

Method	How to use it	Why it exists
input.listen() -> None	Start before interactive loops that need keyboard or mouse input.	Starts the native listener that feeds input snapshots to the frame loop.
input.stop() -> None	Stop during cleanup before engine.shutdown().	Stops the listener thread and releases terminal input mode.
input.get_snapshot() -> InputSnapshot	Use only when you intentionally want to consume the next snapshot manually.	Provides low-level explicit input reads for custom control flows.
input.peek_snapshot() -> InputSnapshot	Use for diagnostics or non-consuming inspection of latest input state.	Lets tools inspect input without stealing events from builder routing.

Snapshot Shape

InputSnapshot: term_x, term_y, keyboard, mouse, consumed_keyboard, consumed_mouse.
KeyboardKey: btn, code, scancode, modifiers, pressed, repeat, has_event.
MouseKey: event, btn, buttons_held, col, row, has_event.

Usage Pattern

input.listen()
try:
    while running:
        engine.main_loop()
        latest = input.peek_snapshot()  # optional diagnostics
finally:
    input.stop()