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}`)

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, sshClient and sshTty (SSH_CONNECTION, SSH_CLIENT, SSH_TTY), noColor (NO_COLOR), nishTermGraphics (NISH_TERM_GRAPHICS) and nishTermFps (NISH_TERM_FPS, which the probe carries for the renderer and does not read).
  • probeQueries(env) — every query, in this order, as one string: XTVERSION CSI > q, DECRQM for synchronized output CSI ? 2026 $ p and pixel mouse CSI ? 1016 $ p, kitty's keyboard flags CSI ? u, a kitty graphics query APC G i=31,s=1,v=1,a=q,t=d,f=24;AAAA ST, XTSMGRAPHICS for the sixel colour registers CSI ? 1 ; 1 ; 0 S, the cell size CSI 16 t, the text area size CSI 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 DA1 CSI c last. Terminals answer in order, so the answer to DA1, which every terminal gives, means the rest are in. Under tmux (TMUX set) the queries only the outer terminal can answer — kitty graphics and the two sizes — go inside tmux's passthrough, DCS tmux; … ST with each ESC doubled; under GNU screen (STY set) the sizes go inside screen's DCS … 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 own KeyDecoder (nish/term), keeping the replies and holding back every other event (a key typed while the probe ran) for heldEvents(), in order. done() is true once DA1 is answered; timedOut(nowMs) once timeoutMs (250 by default) has passed since the send with no answer to DA1. timedOut calls finish(nowMs) itself; after done() 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 returns heldEvents() 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 a TermCaps, and can be called at any point.
  • TermCaps — what the terminal can do: colors (16, 256 or 16777216), trueColor, sync, kittyKeyboard, kittyGraphics, sixel, sixelRegisters, cellWidthPx and cellHeightPx, pixelMouse, multiplexer ("none", "tmux" or "screen"), linuxConsole, remoteHint, answered, probeRttMs, graphics ("kitty", "sixel", "halfblock" or "ascii"), name and overrides; 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.

returnsstring

The 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.