vtx.foundation draft d03

VTX 1 · core · beta draft d03

VTX 1 Wire Specification: core

Oct 11, 2026, revised Nov 16, 202639 pagesALPN vtx1-d03MIT licence

§8Layer 1: grids, cells and glyphs

A grid node is a character-cell surface. It is what the VT engine renders legacy programs into and what the smallest clients implement. Every cell keeps its semantic text, even when it shows a custom glyph.

Grid props

Prop Type Meaning
cols, rows uint Size in cells; change with patch
scrollback uint Lines the client retains above row 0 (default 0)
styles map of style ID → style Named styles that runs refer to; style 0 is the grid default
font text A family name or a sha256: font resource (Section 10)
keys raw or none raw sends all keys to the server while the grid has focus (default raw)
echo none or predict Local prediction of typed characters (Section 6)
mouse none, click, drag or move Which pointer events the grid reports, as in xterm's mouse modes
pointer normal or lock lock captures the pointer for relative motion while the grid has focus, with the pointer.lock permission (Section 12)
size fixed or fill With fill, the client sizes the grid to the space it is given and reports the size in cells with RESIZE (Section 11); the server answers with a patch of cols and rows, and until then the client clips or pads. Default fixed

Style object. fg, bg and ul_color are colours; ul is none, single, double, curly, dotted or dashed; bold, dim, italic, strike, blink and reverse are booleans; link is an https, http or mailto URI that the user opens through the trusted zone (Section 12). Links with other schemes are ignored.

Colours are #rrggbb, a palette entry p0–p255 (the xterm 256-colour palette), or a semantic role: fg, bg, muted, accent, info, success, warning, critical. A client with fewer colours maps them down; roles let it pick the closest meaning rather than the closest RGB.

Palette. Entries p0–p15 and the roles fg and bg follow the client's theme, and the client reports their values in DISPLAY's palette, fg and bg (Section 5), so the VT engine can answer colour queries. Entries p16–p255 are fixed, as in xterm.

Grid ops

Op Fields Effect
cells id, row, col, runs, erase, wrap Writes runs of text from (row, col) to the right; erase: "eol" clears the rest of the row to style 0
fill id, rect [row, col, rows, cols], t, s Fills a rectangle with one grapheme (default a space) in one style
scroll id, n, top, bottom Scrolls rows top–bottom by n; positive moves content up. When top is 0, lines leaving the top enter scrollback
cursor id, row, col, shape, visible, blink Places the cursor; shape is block, bar or underline
style id, sid, style Adds or replaces a named style, and cells that use it change with it; without style, deletes it, and its cells fall back to style 0
clear id, scrollback Clears every cell to a space in style 0; with scrollback: true, drops the scrollback too

Runs. A run is { t, s, g }:

  • t is the text. Graphemes are extended grapheme clusters (UAX #29). East Asian Wide and Fullwidth characters (UAX #11) and emoji presentation sequences take two cells; all others take one. Both sides apply the negotiated Unicode version, so client and server always agree on placement.
  • s is a style ID (default 0) or an inline style object, for a one-off style that needs no entry in styles.
  • g, optional, lists one glyph slot per grapheme of t. The client draws each slot's glyph and keeps t as the cell's text for copy, search, screen readers and fallback.
  • Text past the last column is clipped. Grids never wrap by themselves; the VT engine wraps before it sends. A cells op with wrap: true marks its row as continuing on the next, so copy and search join the two rows and a client that reflows can rejoin them.
{"op":"cells","id":"term","row":2,"col":0,"runs":[{"t":"build-07 ","s":"1"},{"t":"waiting","s":"warn"}],"erase":"eol"}

Glyph slots. Ordinary characters need no slot: the client draws them from t with its font. Custom slots start at 0x110000 (1,114,112), above every Unicode code point, and only custom slots appear in g. The glyph op binds a slot to a glyph resource, {"op":"glyph","slot":1114112,"res":"sha256:…","cells":1}, and without res unbinds it. A glyph with cells: 2 is drawn only for a grapheme that takes two cells; otherwise the client draws t. Until the resource has arrived, or if the client lacks the glyph capability, the client also draws t. The client's glyph_slots limit caps how many slots may be bound at once.

The VT engine. A server-side VT engine runs a legacy program on a pseudo-terminal and turns its output into grid ops. It MUST:

  • set TERM=xterm-256color and COLORTERM=truecolor for the program, and LANG from the session locale with UTF-8;
  • interpret xterm-compatible output, including the alternate screen (as a second grid, toggled with hidden), scroll regions and OSC 8 hyperlinks;
  • map the mouse modes 1000, 1002 and 1003 to the grid's mouse prop (click, drag, move), and encode reports as SGR (mode 1006) when the program asks for it;
  • report focus changes from FOCUS events when the program enabled mode 1004;
  • send everything between the start and end of synchronized output (mode 2026) as one UPDATE;
  • map DECSCUSR to the cursor op's shape and blink;
  • answer DA1, DA2 and XTVERSION itself, and the OSC 4, 10 and 11 colour queries from DISPLAY's palette, fg and bg;
  • set the root title from OSC 0 and 2, send attention with bell for BEL, and set the grid's pointer_shape from OSC 22;
  • turn OSC 52 writes into clipboard writes (Section 13), and answer OSC 52 reads only with the clipboard.read permission, with an empty answer otherwise;
  • turn KEY events into the encoding the program asked for: legacy escape sequences, xterm modifyOtherKeys or the Kitty keyboard protocol;
  • strip ESC, all other C0 controls except tab, carriage return and line feed, and all C1 controls from PASTE text, so a paste cannot end bracketed paste early or inject commands;
  • deliver the cleaned text as bracketed paste when the program enabled it; if it did not and the text holds a line break, first ask the user to confirm through an APPROVAL;
  • send RESIZE and DISPLAY size changes to the program as a window size change (SIGWINCH);
  • drop Kitty graphics and sixel output, which Surfaces 1 maps to image surfaces.