feat(terminal): bounded key polling and diagnostic styling for FastLED migration

[zackees]

Context

Coordinated with FastLED/cli#229 and draft FastLED/cli#242. Two source investigations confirmed the production consumer is commands.rs manual rebuild polling through keyboard::check_for_space, plus four yellow diagnostic formatting sites in source.rs, wasm_build.rs and compile_stream.rs. The unused public start_listener exposes Crossterm KeyEvent and an unbounded std channel; receiver drop is noticed only after another key arrives.

Existing kernel prior art matters: platform::terminal::input selects the Windows capture core, with an unsupported neutral Unix implementation. Separately, pty-gated TerminalInputSession has real Linux/macOS termios/poll/read implementations and Windows capture, with mode restoration on Drop. Unix reads at most 65536 bytes per chunk; Windows uses a background VecDeque. These are raw terminal chunks, not equivalent to one decoded Crossterm event. Scanning chunks for spaces would mistake some terminal escape sequences or pasted input for rebuild keys.

Proposal

Provide a facade-owned bounded terminal key-polling contract and diagnostic styling sufficient to remove direct Crossterm from FastLED. Reuse and harden existing host input ownership where practical; do not introduce a second runtime or unbounded pump. Keep rebuild-key selection, noninteractive fallback, warning text and color policy in the app. Resolve ownership of the unused listener explicitly rather than migrate its leaking public backend type mechanically.

Acceptance criteria

• Focused RED test/repro before implementation, then GREEN and broad checks in each changed repository.
• Public key/event and style interfaces expose no Crossterm or native host types.
• Polling has bounded waits and storage, exclusive input ownership, noninteractive behavior, cancellation/Drop restoration and observable errors; repeated/released keys, modifiers, escape sequences and queued input have documented behavior.
• Generic parsing, input ownership and restoration tests live upstream, with real Unix PTY and Windows console evidence. Keep app tests for Space/Enter rebuild policy and existing warning formatting.
• Remove direct Crossterm manifest/import references after adoption; no whole-chunk substring shortcut for key matching.
• Feature isolation, native CI, review, release and exact published adoption before closing this migration.

Decisions

• Extend the current terminal capability where possible: existing host implementations mean a new private backend is not justified by the initial unsupported-input observation alone.
• Start from the actual synchronous one-shot poll consumer; do not create a listener or general terminal emulator solely for an unused helper.
• Retain FastLED product decisions locally and move generic terminal mechanisms/tests upstream.
• No build-speed claim without comparable measurements.

Related issues

#155 tracks the complete FastLED migration. The browser xterm.js work in FastLED is separate from this native keyboard input boundary.

[zackees]

Follow-up source audit before implementation: Linux/macOS TerminalInputSession::new saves/restores stdin termios but has no process-wide ownership admission. Windows TerminalInputCore::start_impl guards only its own worker, so separately constructed cores can capture/restore the same console independently. Its worker reads up to512 INPUT_RECORDs per batch, expands native repeat counts into byte vectors, then unconditionally extends a shared VecDeque; public wait returns only Event/Closed/Timeout and cannot report overflow. These are concrete prerequisites for safe reuse: unify input ownership across existing session/core paths, cap queue bytes/events and repeat expansion before allocation, and expose overflow/native failures explicitly. Native key decoding must keep complete VT sequences and bracketed paste distinct from literal Space/Enter; raw substring scanning is not acceptable. No terminal implementation change is claimed yet.

[zackees]

Local first step in sibling feat/terminal-input: one private atomic InputLease now gates Unix stdin raw sessions, Unix tty graphics probes, and Windows capture. The guard is acquired before mode snapshots and held until after restoration. Windows stop/start now retain worker-lock serialization through join/restoration, setting stop only after acquiring that lock so a concurrent start cannot erase the stop request. Focused ownership test observed RED missing lease then GREEN; Linux pty-feature strict all-target Clippy passes. This is uncommitted work in progress: real PTY restoration/concurrency tests, Windows evidence, bounded queue/decode/error contracts and FastLED adoption are still required.

[zackees]

Real Linux PTY integration now passes: a subprocess receives an actual openpty slave as stdin, observes canonical-to-raw transition, verifies a second session is rejected with WouldBlock, drops the owner, compares termios flags and control characters to the original state, then reacquires successfully. Child execution is bounded by a20-second deadline with explicit child cleanup. The graphics probe is also exercised while input is owned. Focused test and strict pty all-target Clippy pass. Full pty suite/default-feature check are running; Windows native evidence, bounded queues/key decoding and FastLED adoption remain unfinished.

[zackees]

Draft PR #186 now holds native input groundwork: shared capture/probe admission, bounded Windows capture/repeat expansion and explicit failure reporting, native Unix PTY and Windows child-console restoration tests. Linux full pty tests and strict Linux/Windows-target Clippy pass; Windows native execution is pending CI. Review caught and fixed trace I/O under the queue lock. The decoded-key/style facade, FastLED adoption and published release consumption remain required; this does not close the issue.

[zackees]

Complete and adopted on both sides; closing with the evidence rather than leaving it open.

kernal-api — gated behind terminal-input / terminal-style, implemented in src/keys.rs, src/terminal_style.rs. with tests/terminal_keys.rs, tests/terminal_input_ownership.rs as its contract tests, and documented in docs/terminal-input.md. It landed with #220's application-foundations rebase.

FastLED — adopted through the pinned release tag: crates/fastled-cli/src/keyboard.rs: use kernal_api::keys::{Key, KeyEvent, TerminalKeys};

🤖 Generated with Claude Code