nish/term-probe
What the terminal a program runs in can do (its colours, keyboard protocol, graphics and size), asked of it once at start and read from its answer.
import {
TERM_PROBE_TIMEOUT_MS,
TermCaps,
TermEnv,
TermProbe,
probeQueries,
} from "nish/term-probe";
import { TermEnv, TermProbe, probeQueries } from "nish/term-probe"
const env: TermEnv = new TermEnv()
env.term = "xterm-256color"
const probe: TermProbe = new TermProbe(env, 80, 24, 0.0)
const queries: string = probeQueries(env) // write these to the terminal
// …feed each read: probe.feed(bytes, count, nowMs), until probe.done() or probe.timedOut(nowMs)
console.log(`${probe.result().colors}`)
probeQueries
Every query the probe asks, as one write; TermProbe reads the answers.
TermCaps
What a terminal can do, from its answers to probeQueries and the environment.
TermEnv
The environment the probe reads, each variable "" when unset.
TermProbe
A probe in progress: made when probeQueries is written, at sentAtMs, for a window of cols by rows cells, fed what the terminal sends.
A program writes probeQueries(env) in one write, then feeds what the
terminal sends back to a TermProbe until done() (the terminal answered
the last query) or timedOut(now), and reads the TermCaps from result().
The module is pure: the environment comes in as a TermEnv, times are the
caller's milliseconds as f64 from any origin, and nothing here reads,
writes or waits.
-
TermEnv— the environment variables the probe reads, each "" when unset, one field each in camelCase:term(TERM),colorterm(COLORTERM),termProgram(TERM_PROGRAM),tmux(TMUX),sty(STY),sshConnection,sshClientandsshTty(SSH_CONNECTION,SSH_CLIENT,SSH_TTY),noColor(NO_COLOR),nishTermGraphics(NISH_TERM_GRAPHICS) andnishTermFps(NISH_TERM_FPS, which the probe carries for the renderer and does not read). -
probeQueries(env)— every query, in this order, as one string: XTVERSIONCSI > q, DECRQM for synchronized outputCSI ? 2026 $ pand pixel mouseCSI ? 1016 $ p, kitty's keyboard flagsCSI ? u, a kitty graphics queryAPC G i=31,s=1,v=1,a=q,t=d,f=24;AAAA ST, XTSMGRAPHICS for the sixel colour registersCSI ? 1 ; 1 ; 0 S, the cell sizeCSI 16 t, the text area sizeCSI 14 t, a true-colour background set and read back with DECRQSS (CSI 48 ; 2 ; 1 ; 2 ; 3 m,DCS $ q m ST,CSI m), and DA1CSI clast. Terminals answer in order, so the answer to DA1, which every terminal gives, means the rest are in. Under tmux (TMUXset) the queries only the outer terminal can answer — kitty graphics and the two sizes — go inside tmux's passthrough,DCS tmux; … STwith each ESC doubled; under GNU screen (STYset) the sizes go inside screen'sDCS … ST, and the kitty graphics query and DECRQSS, which hold an ST of their own and which screen would forward rather than answer, are left out. On the Linux console (TERM=linux) both are left out too: it has no string states and would print them. DA1 is never wrapped: the multiplexer answers it, so a multiplexer that forwards no reply still ends the probe. -
TermProbe— the probe in progress, made when the queries are sent.feed(bytes, count, nowMs)decodes a read through its ownKeyDecoder(nish/term), keeping the replies and holding back every other event (a key typed while the probe ran) forheldEvents(), in order.done()is true once DA1 is answered;timedOut(nowMs)oncetimeoutMs(250 by default) has passed since the send with no answer to DA1.timedOutcallsfinish(nowMs)itself; afterdone()the program calls it once: it gives up whatever the decoder still holds (a key cut off at the end of the read with DA1, say) and returnsheldEvents()complete, and later reads go to the program's own decoder.rttMs()is the time from the send to the answer to DA1, -1 before it.result()reads the replies and the environment into aTermCaps, and can be called at any point. -
TermCaps— what the terminal can do:colors(16, 256 or 16777216),trueColor,sync,kittyKeyboard,kittyGraphics,sixel,sixelRegisters,cellWidthPxandcellHeightPx,pixelMouse,multiplexer("none", "tmux" or "screen"),linuxConsole,remoteHint,answered,probeRttMs,graphics("kitty", "sixel", "halfblock" or "ascii"),nameandoverrides; each field's comment says where it comes from.
The environment decides where the terminal cannot answer, and where the user
says so: COLORTERM=truecolor or 24bit means true colour, as does a
DECRQSS that reads the 24-bit background back; otherwise a TERM with
256color in it means 256 colours, and anything else 16. TERM=linux is the
Linux console: 16 colours, ASCII graphics, no kitty keyboard and no
synchronized output, whatever it answered. NO_COLOR set to anything
(no-color.org) means 16 colours and touches nothing but colour.
NISH_TERM_GRAPHICS names a graphics backend to use instead of the one the
answers pick; a pixel backend the terminal did not answer for is refused when
it would come out as garbage or nothing — on the Linux console, under a
multiplexer, or when the terminal answered nothing at all. overrides says
what each variable did, refusals included. The match is exact: kitty,
sixel, halfblock or ascii, lower case, nothing around it.
Under a multiplexer the probe sees the multiplexer first. tmux and screen
answer DA1 themselves, so done() comes on their answer, before any reply
forwarded through the passthrough; probeRttMs is the round trip to the
multiplexer, and graphics come from what the multiplexer itself answers
(tmux's own sixel, say). The environment is taken at face value: an
SSH_* variable or COLORTERM left in a tmux session by the client that
started it still counts, though the client attached now may differ.
Functions
probeQueries
Every query the probe asks, as one write; TermProbe reads the answers.
const probeQueries: (env: TermEnv) => string
envTermEnvrequired
The environment, which picks the queries: under a multiplexer some are wrapped to
reach the terminal outside it, and under screen or the Linux console the kitty graphics and
DECRQSS queries, which answer in strings, are left out.
returnsstringThe queries, ending in DA1, to write at once.
Classes
TermCaps
What a terminal can do, from its answers to probeQueries and the environment.
class TermCaps
| Member | |
|---|---|
new TermCaps() |
Caps of a terminal that answered nothing: 16 colours, ASCII. |
answered: boolean |
Whether the terminal answered DA1; false when the probe timed out. |
cellHeightPx: i32 |
A cell's height in pixels: CSI 16 t, else the text area's from CSI 14 t over the rows; 0 unknown. |
cellWidthPx: i32 |
A cell's width in pixels: CSI 16 t, else the text area's from CSI 14 t over the columns; 0 unknown. |
colors: i32 |
How many colours to draw with: 16, 256 or 16777216. |
graphics: string |
The graphics backend to draw with, best first — "kitty", "sixel" (256 registers or more), "halfblock", "ascii" — after NISH_TERM_GRAPHICS. |
kittyGraphics: boolean |
Whether kitty graphics are there: the query answered OK. |
kittyKeyboard: boolean |
Whether the kitty keyboard protocol is there: CSI ? flags u answered. |
linuxConsole: boolean |
Whether this is the Linux console (TERM=linux). |
multiplexer: string |
The multiplexer in between: "none", "tmux" (TMUX set) or "screen" (STY set). |
name: string |
The terminal's name and version from XTVERSION, else TERM_PROGRAM, else "". |
overrides: string |
What the environment forced, one VARIABLE: effect per entry joined by ; ; "" when nothing. nish/term-io adds NISH_TERM_FPS's, which the controller applies. |
pixelMouse: boolean |
Whether SGR mouse reports in pixels (mode 1016) are known: DECRPM answered set or reset. |
probeRttMs: f64 |
The time from the send to the answer to DA1, in milliseconds; -1 unanswered. |
remoteHint: boolean |
Whether the session looks remote (SSH_CONNECTION, SSH_CLIENT or SSH_TTY set), so slow. |
sixel: boolean |
Whether sixel is there: DA1 lists 4. |
sixelRegisters: i32 |
How many sixel colour registers there are, from XTSMGRAPHICS; 0 unanswered. |
sync: boolean |
Whether synchronized output (mode 2026) is known: DECRPM answered set or reset. |
trueColor: boolean |
Whether 24-bit colour works: COLORTERM, or the background DECRQSS read back. |
TermEnv
The environment the probe reads, each variable "" when unset.
class TermEnv
| Member | |
|---|---|
new TermEnv() |
An environment with every variable unset. |
colorterm: string |
COLORTERM: truecolor or 24bit where the terminal has 24-bit colour. |
nishTermFps: string |
NISH_TERM_FPS: a frame rate for the renderer; carried, not read, by the probe. |
nishTermGraphics: string |
NISH_TERM_GRAPHICS: a graphics backend to use instead of the probed one, kitty, sixel, halfblock or ascii. |
noColor: string |
NO_COLOR: set to anything to ask for no colour (no-color.org). |
sshClient: string |
SSH_CLIENT: set by sshd for a remote session. |
sshConnection: string |
SSH_CONNECTION: set by sshd for a remote session. |
sshTty: string |
SSH_TTY: set by sshd for a remote session with a terminal. |
sty: string |
STY: set inside GNU screen. |
term: string |
TERM: the terminal type, such as xterm-256color or linux. |
termProgram: string |
TERM_PROGRAM: the terminal's name where it sets one, such as iTerm.app or Apple_Terminal. |
tmux: string |
TMUX: set inside tmux. |
TermProbe
A probe in progress: made when probeQueries is written, at sentAtMs,
for a window of cols by rows cells, fed what the terminal sends.
class TermProbe
| Member | |
|---|---|
new TermProbe(env: TermEnv, cols: i32, rows: i32, sentAtMs: f64) |
A probe whose queries were written at sentAtMs to a window of cols by rows cells. |
cols: i32 |
The window's width in cells, to turn CSI 14 t into a cell width. |
env: TermEnv |
The environment the queries were made for. |
replies: TermEvent[] |
The replies so far, in order. |
rows: i32 |
The window's height in cells, to turn CSI 14 t into a cell height. |
sentAtMs: f64 |
When the queries were written. |
timeoutMs: f64 |
How long to wait for the answer to DA1 (TERM_PROBE_TIMEOUT_MS by default). |
done(): boolean |
Whether DA1 has been answered, so every reply is in. |
feed(bytes: u8[], count: i32, nowMs: f64): void |
Decode bytes[0, count), read at nowMs. |
finish(nowMs: f64): TermEvent[] |
End the probe at nowMs: what the decoder still holds — an ESC or the start of a key that came in the read with DA1, or an unfinished reply on a timeout — is given up (the ESC as a key, the reply as nothing) and heldEvents returned complete. Call it once when done() ends the probe (timedOut calls it itself), and hand every later read to the program's own decoder. |
heldEvents(): TermEvent[] |
The events that were not replies — keys typed, a paste — in the order they came, for the program to handle. |
result(): TermCaps |
What the terminal can do, from the replies so far and the environment. |
rttMs(): f64 |
The time from the send to the answer to DA1, in milliseconds; -1 before it. |
timedOut(nowMs: f64): boolean |
Whether timeoutMs has passed since the send with DA1 unanswered. Once it has, it calls finish(nowMs), so heldEvents is complete. |
Constants
250.0
TERM_PROBE_TIMEOUT_MS: f64
How long a probe waits for the answer to DA1 by default, in milliseconds.

