term
Native raw-mode terminal input for interactive TUIs (EXPERIMENTAL x/
tier, #30). raw-mode/cooked-mode save+restore the tty's termios on fd 0;
read-event returns the next decoded VT/ANSI key ([key name=… mods=(…)]),
resize, or [timeout]; size reports the window dimensions. The substrate for
a lazygit-class XAP terminal surface — a peer renderer to web/agent, not a
wrapped TUI framework. POSIX; gated on the read capability; a non-tty raises
cx-err:CXER3450.
Experimental x/ tier — imported as cx-x/term. Bundled and gated in-tree like any other module, but EXEMPT from the frozen-surface stability promise (std-lib README, decision D3): a semver-breaking change is allowed here while the surface settles, and the frozen-surface canary never counts it. Pin behaviour you depend on with your own fixtures.
term:is-tty
[$term:is-tty] -> bool — Report whether stdin (fd 0) is a terminal. False under a pipe / headless run — guard interactive paths with it. Requires no capability.
term:raw-mode
[$term:raw-mode] -> null — Switch the tty (fd 0) to raw mode (cfmakeraw: no line buffering, no echo, byte-at-a-time) and save the prior termios so cooked-mode restores it. Raises cx-err:CXER3450 on a non-tty. Needs the read capability.
term:cooked-mode
[$term:cooked-mode] -> null — Restore the tty's saved (pre-raw) termios. A no-op if raw-mode was never entered. Pair with raw-mode (ideally via a scope guard) so the terminal is always restored. Needs the read capability.
term:size
[$term:size] -> element — Report the terminal window size as [size rows=R cols=C] (TIOCGWINSZ). Raises cx-err:CXER3450 on a non-tty. Needs the read capability.
term:read-event
[$term:read-event] timeout=INT-MS -> element — Read and decode the next terminal event from raw stdin: [key name=NAME mods=(:ctrl :alt :shift)] for a keystroke (arrows, fn-keys, ctrl/alt-chords, printable), or [timeout] when a timeout=MS bound expires first (#861, R7.1 — the wrapper forwards the primitive's optional duration; the default -1 blocks). For waiting on keystrokes AND live sources together, [$term:select {keys: true timeout: MS}] remains the primitive. Requires raw-mode. Needs the read capability.
term:select
[$term:select] {keys: bool sources: (handle …) timeout: int-ms} -> element — Wait for the FIRST ready of keystrokes (keys: true → raw stdin), any source handle's fd becoming readable (sources: a sequence of [socket]/[exchange]/SSE-stream handles), or the timer (timeout: milliseconds; omit/-1 to block). Returns the decoded [key …] for a keystroke, [ready index=N when source N is readable (read it via its own module, e.g. http:sse-events — term stays decoupled from each source's framing), or [timeout]. The one primitive that unifies live-stream and interactive input in a single loop. Requires raw-mode for keystrokes. Needs the read capability.