Terminal programs
A full-screen terminal program — a game, an editor, a dashboard — reads keys the moment they are pressed and redraws many times a second. Nish gives it two layers:
-
nish/term-io, in the standard library, is the whole loop. It opens the terminal, finds out what it can draw, runs your program at a fixed step, sends as many frames as the terminal and the link to it can take, and leaves the terminal as it found it however the program ends. -
nish:termis what it is built on: six functions that read stdin without waiting, set raw mode and say how big the terminal is.
Start with the first. Reach for the second when you want a loop of your own.
A frame loop
runTerminal(options, state, update, render) runs a program. update is
called a fixed number of times a second (options.stepsPerSecond, 60) with
the events since the last step, and answers false to stop. render is
called whenever a frame may go out, and draws into the frame's screen (text
cells) and framebuffer (pixels, when the options ask for one). This program
bounces a square across the screen until you press q:
import { ACTION_PRESS, ATTR_NONE, COLOR_DEFAULT, EVENT_KEY, KEY_CHAR } from "nish/term";
import { Frame, TermInput, defaultTerminalOptions, runTerminal } from "nish/term-io";
class Ball {
x: i32 = 0;
dx: i32 = 1;
}
const update = (b: Ball, input: TermInput): boolean => {
for (const e of input.events) {
if (e.type === EVENT_KEY && e.action === ACTION_PRESS && e.key === KEY_CHAR && e.code === 113) {
return false; // q
}
}
if (b.x + b.dx < 0 || b.x + b.dx > 80) {
b.dx = -b.dx;
}
b.x = b.x + b.dx;
return true;
};
const render = (b: Ball, frame: Frame): void => {
frame.framebuffer.fill(0x102040);
for (let y = 40; y < 50; y++) {
for (let x = b.x; x < b.x + 10; x++) {
frame.framebuffer.set(x, y, 0xffcc00);
}
}
frame.screen.clear(COLOR_DEFAULT);
frame.screen.text(0, 0, `${frame.stats.tier} fps`, COLOR_DEFAULT, COLOR_DEFAULT, ATTR_NONE);
};
export const main = (): i32 => {
const options = defaultTerminalOptions();
options.framebufferWidth = 90;
options.framebufferHeight = 90;
const ran = runTerminal(options, new Ball(), update, render);
if (ran.isErr()) {
writeError(`${ran.error}\n`);
return 1;
}
return 0;
};
The state is yours: any class, passed to both functions. Because update
runs at a fixed step and render only when a frame can go out, the square
moves at the same speed on a fast terminal and on a slow one; the slow one
just shows fewer of its positions. frame.alpha says how far the clock is
past the last step, to draw between two positions.
The framebuffer is drawn as large as the screen allows with its shape kept, centred, and over the text cells it covers: text under the image is hidden. So the example's framebuffer is square, and its label goes at the left edge, in the columns the image leaves free. A cell is about twice as tall as it is wide, so those columns exist only when the screen has more than twice as many columns as rows: a 100×60 terminal has none, and the label is under the image.
input.events holds nish/term's TermEvents: keys (with releases, on a
terminal that has the kitty keyboard protocol), mouse reports when
options.mouse asks for them, pastes, focus changes, and EVENT_RESIZE when
the window changes size, with the screen already resized. input.isDown(key, code) asks whether a key is held, for movement that lasts as long as the
key.
The program also stops on Ctrl-C, and the terminal is put back. Without the
kitty keyboard protocol Ctrl-C is a signal, as it is in raw
mode. With it, Ctrl-C arrives as a key, KEY_CHAR with code 99
and MOD_CTRL, and options.quitOnCtrlC (true) makes it stop the loop; set
it to false and that key reaches update instead. KEY_CTRL_C, the byte
3, never arrives under runTerminal.
runTerminal answers Err with one sentence when it cannot start, and the
program above prints it, or Err("stdin ended") when stdin closes while the
program runs, after putting the terminal back. A pipe on either side is the
usual reason it cannot start:
$ ./ball < /dev/null
stdin is not a terminal (a pipe or CI?)
For a loop of your own, openTerminal(options) answers the Terminal that
runTerminal drives: readEvents(waitMs, events) waits for input and
decodes it, present() sends the screen and framebuffer, stats() says how
the link is doing, and close() puts the terminal back (a second close does
nothing).
Under runTerminal every reply the terminal sends is taken before update
sees the input, including the answers to a query your program writes itself,
such as a cursor position report (CSI 6 n) or the background colour (OSC
11): update never receives an EVENT_REPLY. readEvents takes them the
same way, so under openTerminal too the answer is not yours to read. A
program that needs one asks before it opens the terminal or after it closes
it, in raw mode, and decodes the answer with nish/term's
KeyDecoder.
Opening and closing
Opening the terminal turns raw mode on, switches to the alternate screen,
hides the cursor and asks the terminal what it can do (below). Then it turns
on what the options ask for and the terminal has: the kitty keyboard protocol,
mouse reports, bracketed paste and focus reports. Before each of those reaches
the terminal, the bytes that undo everything so far are handed to the runtime
(setTerminalRestore). So a panic in render, a Ctrl-C, or a kill leaves the terminal as it
was, with the cursor back and the screen you started from.
What it detects, and what it falls back to
The questions go out in one write and the answers come back in a few milliseconds; a terminal that answers nothing is given up on after a quarter of a second. A key you press while it asks is kept and given to the program first. What it finds:
| What | Where it comes from | Without it |
|---|---|---|
| Pixels: kitty graphics | the terminal answers a kitty graphics query | sixel |
| Pixels: sixel | the terminal lists sixel (4) in its DA1 answer and reports 256 or more sixel colour registers |
half blocks, two pixels to a cell (▀) |
| Pixels: half blocks | any terminal but TERM=dumb and the Linux console |
ASCII shading |
| True colour | COLORTERM=truecolor or 24bit, or the terminal reads a 24-bit colour back |
text cells in the 256-colour palette; ASCII image shading in 256 colours with 256color in TERM, else 16 |
| Key releases, Ctrl-C as a key | the kitty keyboard protocol | a key counts as released options.releaseGapMs after its last repeat |
| Tear-free frames | synchronized output (mode 2026) | frames are drawn as they arrive |
| Mouse in pixels | mode 1016, and the terminal reports its cell size | mouse in cells |
frame.caps holds what was found, and frame.stats.backend the pixel
backend in force: GRAPHICS_ASCII (0), GRAPHICS_HALFBLOCK (1),
GRAPHICS_SIXEL (2) or GRAPHICS_KITTY (3), imported from
nish/term-pixels, the same numbers as
nish/term-rate's BACKEND_CAP_*. The Linux console (TERM=linux) gets no
true colour and ASCII, whatever it answers.
Without true colour, text cells are drawn in the 256-colour palette — on the
Linux console and under NO_COLOR too. Only the ASCII backend's shading of
the image drops to 16 colours there, or wherever TERM lacks 256color.
How the frame rate adapts
Each frame is followed by a status query, and the terminal's answer says the
frame has been read. From those answers nish/term-rate measures the round
trip, the bytes a second the link carries and what a frame costs to build, and
picks a frame rate from 60, 30, 20, 15, 10 and 5 that fits all three with
room to spare.
At most one frame is unanswered at a time, so a slow link
shows fewer frames instead of a growing backlog, and a key you press is never
queued behind seconds of drawing. Below options.minFps (10), it draws with
less detail instead: a cheaper pixel backend, a coarser framebuffer, 256
colours. options.prefer = DETAIL_FIRST cuts the rate first; RATE_FIRST
and DETAIL_FIRST come from nish/term-rate.
On a local terminal it starts at the best rate it may use (options.maxFps,
60 by default; 120 needs options.allow120 too) and falls within half a
second if it cannot keep it. It
starts at 30 when the probe's first answer took 5 ms or more, and at 15 when
an SSH_* variable says the session is remote and the probe's answer took
5 ms or more, or never came; it settles within a few seconds. frame.stats shows the numbers;
options.overlay draws them in a corner, one of nish/term-rate's
CORNER_TOP_LEFT, CORNER_TOP_RIGHT, CORNER_BOTTOM_LEFT and
CORNER_BOTTOM_RIGHT, or -1, the default, for none.
Under SSH and multiplexers the measure is only as good as the answer. tmux and GNU screen answer the status query themselves, so inside them the round trip is the multiplexer's, not the terminal's at the end of the link, and the rate can come out higher than the outer terminal keeps up with. mosh answers on the remote host, so it reads as a fast local link and its own limit (about 50 frames a second) does the pacing. Under tmux, kitty graphics and sixel work only where tmux passes them through. If a program looks wrong there, fix the rate or the backend with the overrides below.
Overriding it
| Setting | Effect |
|---|---|
options.fixedFps |
a fixed frame rate; the measuring stops choosing |
options.minFps, options.maxFps, options.allow120 |
the range the rate is chosen in (10 to 60; 120 only when allowed) |
options.prefer |
RATE_FIRST (cut detail below minFps) or DETAIL_FIRST (cut the rate first), from nish/term-rate |
options.graphics |
"kitty", "sixel", "halfblock" or "ascii", as NISH_TERM_GRAPHICS names them, for a program that lets its user pick; "" (the default) detects, and the variable, when set, wins |
options.mouse, paste, focus, kittyKeyboard, quitOnCtrlC |
what is turned on: mouse 1000 clicks, 1002 drags, 1003 all motion, 0 none |
NO_COLOR set to anything |
no true colour: text in the 256-colour palette, ASCII shading in 16 colours; nothing else changed |
NISH_TERM_GRAPHICS |
kitty, sixel, halfblock or ascii instead of what was detected; a pixel backend the terminal did not answer for is refused under a multiplexer, on the Linux console, or when nothing answered |
NISH_TERM_FPS |
a fixed frame rate, over everything else |
The variables are the user's: they let someone running your program fix it
for their terminal without a rebuild. What each one changed is listed in
frame.caps.overrides, joined by ; , so a bug report shows it, for example
NO_COLOR: 16 colours; NISH_TERM_FPS=20: 20 frames a second.
Reporting a terminal that draws wrong
examples/term-probe.ts
prints everything the probe found, one field a line, and then a line of
frame-rate measurements every second for five seconds. Run it in the terminal
that draws wrong and put its output in the bug report:
nish run examples/term-probe.ts
nish:term, underneath
nish:term lets a program read keys the moment they are pressed. It has six
functions:
readStdinreads the bytes that are waiting on stdin;waitStdinwaits for some to arrive, or for a timeout to pass;isTerminalasks whether a descriptor is a terminal;terminalSizeasks how big the terminal is;setRawModeturns off echo and line editing, and turns them back on;setTerminalRestoresets the bytes the program leaves the terminal with.
The rules are in the reference, under
nish:term. It reads the
terminal; drawing on it is the standard library's
nish/term, whose KeyDecoder turns the
bytes readStdin returns into key events.
Every function is also a global, as every nish: export is, but importing
them says where they come from. A program that calls any of them carries the
tty capability, not net; nish run --capabilities shows it.
Errors are numbers
The functions that can fail answer a number, in the same shape as
nish:net: zero or more is success, and
a negative number is a failure. Three of the failures are the same number on
every platform, so a program can branch on them:
| Answer | Meaning |
|---|---|
-7 |
setTerminalRestore: more than 4,096 bytes, checked before the terminal is |
-11 |
readStdin: nothing is waiting yet |
-25 |
not a terminal: a pipe or a file — stdin for setRawMode, stdout for setTerminalRestore, stdout and stderr both for terminalSize |
terminalSize() answers a pair, [columns, rows]. When there is no terminal
the first number is the error and the second is 0, so [-25, 0] means "not
a terminal". A terminal that no one gave a size, such as one a test harness
opens, answers [0, 0].
Reading keys
readStdin(buf, off, len) copies at most len bytes into buf, starting at
off. It never waits. It answers how many bytes it read, 0 when stdin has
ended, or -11 when nothing has arrived yet. Any other negative number means
reading stdin failed, and the loop should stop as it does at the end. Ask for
at least one byte: a len of 0 reads nothing and answers 0, which looks
like the end.
waitStdin(timeoutMs) waits until there is something to read, or until
timeoutMs milliseconds have passed. It answers true when stdin is ready
(its end and an error count, so the read after it answers at once) and false
when the time ran out or a signal ended the wait first. A Ctrl-Z and fg
after setRawMode(true) do not end it: the wait goes on until its timeout.
Before raw mode, whether a stop ends the wait depends on the system, so treat
false as "nothing to read yet" rather than as the time having run out. A
negative timeout waits for ever.
Together they make the loop of an interactive program. Each pass waits up to one frame for a key, handles what came, and draws. A key that arrives early ends the wait at once, and a frame with no key still ends on time.
Raw mode
A terminal normally keeps what you type until you press Enter, and echoes it
as you go. setRawMode(true) turns that off: each key arrives as soon as it is
pressed, and nothing is echoed. A key arrives as its bytes. A letter is one
byte, and an arrow key is three: 27, 91 and then 65 to 68 for up, down,
right and left.
Three things do not change:
-
Ctrl-C still ends the program. It is still a signal, not a byte, and
so are Ctrl-\ and Ctrl-Z. A program stuck in a loop can always be stopped
from the keyboard. So
nish/term'sKEY_CTRL_Cnever comes from a terminalsetRawModeset up. "\n"still starts a new line, soconsole.logworks as it always does.-
The terminal is always put back.
setRawMode(false)restores it, and so does returning frommain,process.exit, a panic or a crash, a Ctrl-C orkill, and a closed pipe on the other end of stdout. Ctrl-Z puts it back while the program is stopped, andfgputs raw mode back on. Onlykill -9,kill -STOP, and a stack overflow on a thread other than the one that calledsetRawMode(true), leave the terminal in raw mode; typestty saneto fix it.
Ctrl-D is a byte in raw mode, 4, not the end of stdin. Treat it as a key if
you want it to quit.
setRawMode answers 0, or -25 when stdin is not a terminal. Calling it
for the mode the terminal is already in does nothing, so setRawMode(false)
is always safe.
A program you start in the background, with app &, is stopped by the shell
when it calls setRawMode(true), the way any program that changes the
terminal is. Type fg and it goes on, in raw mode.
A key-echo loop
This program prints the number of each key you press. It stops on q, on
Ctrl-D, or when stdin ends or fails. Run it in a terminal and press an arrow key to see
its three bytes.
import { isTerminal, readStdin, setRawMode, waitStdin } from "nish:term";
export const main = (): i32 => {
if (!isTerminal(0)) {
console.log("stdin is not a terminal; the keys arrive as they were piped");
}
setRawMode(true);
const keys = new Array<u8>(16);
let running = true;
while (running) {
if (waitStdin(100)) {
const n = readStdin(keys, 0, keys.length);
if (n === 0 || (n < 0 && n !== -11)) {
running = false;
}
for (let i = 0; i < n && i < keys.length; i++) {
const key = keys[i];
console.log(`key ${key}`);
if (key === 113 || key === 4) {
running = false;
}
}
}
}
setRawMode(false);
return 0;
};
It also works with a pipe, printf 'hiq' | ./echo. setRawMode(true) answers
-25 there and changes nothing, and the loop reads the piped bytes as keys.
Leaving the screen as you found it
A full-screen program changes more than the mode: it switches to the
alternate screen, hides the cursor, maybe turns on mouse reporting. Those are
escapes it writes itself, and the escapes that undo them have to go out
however the program ends. setTerminalRestore(bytes) hands them to the
runtime, which writes them once, on the same paths that put raw mode back:
returning from main, process.exit, a panic or a crash, Ctrl-C or kill.
It writes them first, then restores the terminal settings.
import { write } from "nish:io";
import { setRawMode, setTerminalRestore } from "nish:term";
export const main = (): i32 => {
setRawMode(true);
// The alternate screen, with the cursor hidden; then the bytes that undo both.
write("\u001b[?1049h\u001b[?25l");
setTerminalRestore("\u001b[?25h\u001b[?1049l");
console.log("drawn on the alternate screen");
return 0;
};
Each call replaces the bytes from the last one, so set them again whenever
the program turns another mode on, and setTerminalRestore("") once it has
undone them all itself. It answers 0, -25 when stdout is not a terminal
(nothing is kept then), and -7 for more than 4096 bytes. Ctrl-Z and
setRawMode(false) do not end the program, so they leave the bytes unwritten.
The size of the terminal
terminalSize() answers a new pair each time you call it. Call it again on
each frame to notice when the window is resized.
import { isTerminal, terminalSize } from "nish:term";
export const main = (): i32 => {
const size = terminalSize();
if (size[0] < 0) {
console.log(`not a terminal (${size[0]})`);
return 0;
}
console.log(`${size[0]} columns, ${size[1]} rows; stdout is a terminal: ${isTerminal(1)}`);
return 0;
};
Where it runs
nish:term works on Linux and macOS. Under WebAssembly (--profile wasi)
there is no terminal: readStdin waits for its bytes instead of answering
-11, so call waitStdin first, as the loop above does; there it waits at
least 10 ms, even for waitStdin(0). The other four answer "not a terminal". A freestanding --target wasm32 build has no stdin
at all, so the compiler refuses all six there. When a program is run under
Node, isTerminal and terminalSize work, and the other four throw; in a
browser the two answer "not a terminal".

