Terminal renderer

[arcanis]

I was thinking to use xterm.js to power a multiplexer in a terminal UI library, but I'm not entirely sure what's the best way to achieve that (with "best" being "most correct but simple"). In short, I have to implement a renderLine function that, given a line number, returns the ansi sequence to render this line. I did a first attempt by using @xterm/addon-serialize, but it cannot run tools like emacs properly - I suspect the addon is returning terminal sequences that aren't limited to pure rendering.

My second idea was to use a custom renderer (similar to the canvas / webgl ones), but I looked at the code and they both seem very complex. I'd have expected a way to ask for xterm.js the set of characters and style to apply on every cell from a given range, but I didn't find how to do that just yet. Did I miss some internal API?

[jerch]

@arcanis What do you mean with:

I have to implement a renderLine function that, given a line number, returns the ansi sequence to render this line.

Can you explain more in detail, where the data comes from? How is xterm.js involved here?

My guess currently goes into the direction, that you want to use xterm.js for the multiplexed sub terminals. That should be possible with xterm-headless (thus should even work in nodejs).
Idk for sure, if the interface of the serialize addon is fine-grained enough for your output needs, but it is def. the right place to lookup the idea of buffer scraping in xterm.js. This is indeed like an "escape sequence string renderer", still looking up the screen renderers prolly does not help you much here, as those are highly optimized for various aspects hiding the basic scraping logic.

Since you ask for internal APIs - most buffer related things are under src/common/buffer:

• Buffer.ts - buffer class bundling bufferlines vertically, also deals with reflow, scrollback, attributes etc.
• BufferLine.ts - holds a single row of cell data, has primitives to read&write data
• CellData.ts - convenient class for read access of cell data (used by all renderers, much easier to use than the bufferline primitives)

Reading buffer data down to cell level is also exposed on the official public API (preferable, unless you dont mind hard linking against a certain minor version of xterm.js). Cell writing is not exposed, to see how thats done, see

xterm.js/src/common/InputHandler.ts

Lines 507 to 647 in 1da0db4

	public print(data: Uint32Array, start: number, end: number): void {
	let code: number;
	let chWidth: number;
	const charset = this._charsetService.charset;
	const screenReaderMode = this._optionsService.rawOptions.screenReaderMode;
	const cols = this._bufferService.cols;
	const wraparoundMode = this._coreService.decPrivateModes.wraparound;
	const insertMode = this._coreService.modes.insertMode;
	const curAttr = this._curAttrData;
	let bufferRow = this._activeBuffer.lines.get(this._activeBuffer.ybase + this._activeBuffer.y)!;
	this._dirtyRowTracker.markDirty(this._activeBuffer.y);
	// handle wide chars: reset start_cell-1 if we would overwrite the second cell of a wide char
	if (this._activeBuffer.x && end - start > 0 && bufferRow.getWidth(this._activeBuffer.x - 1) === 2) {
	bufferRow.setCellFromCodepoint(this._activeBuffer.x - 1, 0, 1, curAttr);
	}
	let precedingJoinState = this._parser.precedingJoinState;
	for (let pos = start; pos < end; ++pos) {
	code = data[pos];
	// get charset replacement character
	// charset is only defined for ASCII, therefore we only
	// search for an replacement char if code < 127
	if (code < 127 && charset) {
	const ch = charset[String.fromCharCode(code)];
	if (ch) {
	code = ch.charCodeAt(0);
	}
	}
	const currentInfo = this._unicodeService.charProperties(code, precedingJoinState);
	chWidth = UnicodeService.extractWidth(currentInfo);
	const shouldJoin = UnicodeService.extractShouldJoin(currentInfo);
	const oldWidth = shouldJoin ? UnicodeService.extractWidth(precedingJoinState) : 0;
	precedingJoinState = currentInfo;
	if (screenReaderMode) {
	this._onA11yChar.fire(stringFromCodePoint(code));
	}
	if (this._getCurrentLinkId()) {
	this._oscLinkService.addLineToLink(this._getCurrentLinkId(), this._activeBuffer.ybase + this._activeBuffer.y);
	}
	// goto next line if ch would overflow
	// NOTE: To avoid costly width checks here,
	// the terminal does not allow a cols < 2.
	if (this._activeBuffer.x + chWidth - oldWidth > cols) {
	// autowrap - DECAWM
	// automatically wraps to the beginning of the next line
	if (wraparoundMode) {
	const oldRow = bufferRow;
	let oldCol = this._activeBuffer.x - oldWidth;
	this._activeBuffer.x = oldWidth;
	this._activeBuffer.y++;
	if (this._activeBuffer.y === this._activeBuffer.scrollBottom + 1) {
	this._activeBuffer.y--;
	this._bufferService.scroll(this._eraseAttrData(), true);
	} else {
	if (this._activeBuffer.y >= this._bufferService.rows) {
	this._activeBuffer.y = this._bufferService.rows - 1;
	}
	// The line already exists (eg. the initial viewport), mark it as a
	// wrapped line
	this._activeBuffer.lines.get(this._activeBuffer.ybase + this._activeBuffer.y)!.isWrapped = true;
	}
	// row changed, get it again
	bufferRow = this._activeBuffer.lines.get(this._activeBuffer.ybase + this._activeBuffer.y)!;
	if (oldWidth > 0 && bufferRow instanceof BufferLine) {
	// Combining character widens 1 column to 2.
	// Move old character to next line.
	bufferRow.copyCellsFrom(oldRow as BufferLine,
	oldCol, 0, oldWidth, false);
	}
	// clear left over cells to the right
	while (oldCol < cols) {
	oldRow.setCellFromCodepoint(oldCol++, 0, 1, curAttr);
	}
	} else {
	this._activeBuffer.x = cols - 1;
	if (chWidth === 2) {
	// FIXME: check for xterm behavior
	// What to do here? We got a wide char that does not fit into last cell
	continue;
	}
	}
	}
	// insert combining char at last cursor position
	// this._activeBuffer.x should never be 0 for a combining char
	// since they always follow a cell consuming char
	// therefore we can test for this._activeBuffer.x to avoid overflow left
	if (shouldJoin && this._activeBuffer.x) {
	const offset = bufferRow.getWidth(this._activeBuffer.x - 1) ? 1 : 2;
	// if empty cell after fullwidth, need to go 2 cells back
	// it is save to step 2 cells back here
	// since an empty cell is only set by fullwidth chars
	bufferRow.addCodepointToCell(this._activeBuffer.x - offset,
	code, chWidth);
	for (let delta = chWidth - oldWidth; --delta >= 0; ) {
	bufferRow.setCellFromCodepoint(this._activeBuffer.x++, 0, 0, curAttr);
	}
	continue;
	}
	// insert mode: move characters to right
	if (insertMode) {
	// right shift cells according to the width
	bufferRow.insertCells(this._activeBuffer.x, chWidth - oldWidth, this._activeBuffer.getNullCell(curAttr));
	// test last cell - since the last cell has only room for
	// a halfwidth char any fullwidth shifted there is lost
	// and will be set to empty cell
	if (bufferRow.getWidth(cols - 1) === 2) {
	bufferRow.setCellFromCodepoint(cols - 1, NULL_CELL_CODE, NULL_CELL_WIDTH, curAttr);
	}
	}
	// write current char to buffer and advance cursor
	bufferRow.setCellFromCodepoint(this._activeBuffer.x++, code, chWidth, curAttr);
	// fullwidth char - also set next cell to placeholder stub and advance cursor
	// for graphemes bigger than fullwidth we can simply loop to zero
	// we already made sure above, that this._activeBuffer.x + chWidth will not overflow right
	if (chWidth > 0) {
	while (--chWidth) {
	// other than a regular empty cell a cell following a wide char has no width
	bufferRow.setCellFromCodepoint(this._activeBuffer.x++, 0, 0, curAttr);
	}
	}
	}
	this._parser.precedingJoinState = precedingJoinState;
	// handle wide chars: reset cell to the right if it is second cell of a wide char
	if (this._activeBuffer.x < cols && end - start > 0 && bufferRow.getWidth(this._activeBuffer.x) === 0 && !bufferRow.hasContent(this._activeBuffer.x)) {
	bufferRow.setCellFromCodepoint(this._activeBuffer.x, 0, 1, curAttr);
	}
	this._dirtyRowTracker.markDirty(this._activeBuffer.y);
	}

.