io.worxbend.tui.terminal

A terminal a TUI can draw to and read input from.

Implementations own the physical (or simulated) terminal: raw mode, the alternate screen, cursor visibility, and translating Buffer diffs into whatever the device understands. Everything above this trait — runtime, widgets, DSL — is backend-agnostic.

I/O failures are values (Either[BackendError, A]) because callers can meaningfully degrade (log and continue vs. abort); throw is reserved for genuine defects.

draw flushes only the cells that changed since the previous draw call (diff-based updates); the first call after construction, or after the buffer area changes, flushes everything.

How many colors the terminal can actually show; RGB output is downsampled to fit.

NoColor is not a device capability but an explicit opt-out: when it is in effect the backend emits text attributes (bold, underline, …) but no foreground/background color at all. It is what honoring the NO_COLOR convention resolves to.

An in-memory Backend for headless end-to-end testing: renders into a retained snapshot instead of a TTY and reads synthetic events posted by the test driver.

Thread contract: the runner calls readEvent/draw on the render thread while a test thread posts events and inspects lastDrawn — hence the blocking queue and volatile snapshot.

Backend implementation over JLine 3's system terminal.

Owns the JLine Terminal for its whole lifetime: construct via JLine3Backend.create, release with close() (which restores cooked mode, the main screen, and cursor visibility if still active). draw keeps a snapshot of the last flushed frame and writes only the diff.

Signals are owned here rather than left to JLine's defaults. INT/QUIT become Event.Interrupt so the runner unwinds through its normal teardown; TSTP/CONT hand the terminal back to the shell and take it again on resume; WINCH posts a coalesced resize. See JLine3Backend.create for why the defaults are unusable.