Wire byte protocol

DomTerm mostly handles standard ansi/xterm escape sequences. This section documents DomTerm-specific extensions. (Future: We should also document what xterm features aren’t implemented.)

The following are preliminary code sequences, which may change based on experience and feedback.

Notation: Literal characters are written as quoted string literals with escape sequences as understoof by bash’s echo -e. Specifically "\e" is an escape; "\a" is alert (bell); "\xHH" is the 8-bit characters whose value is HH (hexadecimal).

Special sequences sent by back-end and handled by DomTerm

"\e[3J"

Erase the scrollback buffer (i.e. any lines above the home line). (This is an xterm feature.)

"\e[>0c"

Request Secondary Device Attributes. (This is a standard request for xt100style terminals, including xterm.) DomTerm responds "\e]990;XXYYYZZ;0c", where the number XXYYYZZ is derived from the DomTerm version number "XXX.YYY.ZZ".

"\e]30;" name "\a"

Sets the “session name” to name, which is shown in the window title. Specifically sets the name attribute of the top-level domterm <div> node to name. This can be used to enable stylesheet rules to only apply to specfic DomTerm windows. If an active CSS stylesheet contains:

div.domterm[name="name"] { rules }

then the rules are only active for a DomTerm element whose session name is name.

"\e]72;" html-text "\a"

Insert HTML text.

The HTML is sanity-checked for safety. It needs to be well-formed XML; thus to write a horizontal line you must write <hr/> (with the extra “/”).

The actual policy for allowed elements and attributes can be changed by overwriting the elementInfo and allowAttribute functions in terminal.js. The default policy is a work-in-progress.

"\e]73;" key "\a"
"\e]74;" key "\a"

Simulate pressing key. Used by auto-line mode. The 73 variant supresses echo.

"\e[12u"

Start of error output. DomTerm places the following text inside a <span> element whose std attribute has the value "error". The default style is to display the text in red.

"\e[11u"

End of error output.

"\e[14u"

Start of prompt. DomTerm places the following text inside a <span> element whose std attribute has the value "prompt". The default style is to display the text in green.

"\e[13u"

End of prompt. The prompt is included in selections that surround it.

"\e[18u"

End of non-selectable prompt. The prompt is not part of the text content of the document, and is not included in selections. The prompt string must be plain text with no styling. You can use this for all prompts, but it is especially recommended for continuation lines, such as the shell’s PS2 prompt.

"\e[15u"

Start of an input line. This also implicitly ends a (selectable) prompt. The input line is implicitly terminated by a '\n' (carriage return).

"\e[16u"
"\e[17u"

Delimit a hide/show "button", with "\e[16u" before and "\e[17u" after.

"\e[19u"

Start a command group. This command implicitly does a "fresh line" and ends any existing command group, You can write this string before writing an input prompt string.

"\e[20u"

Starts a "fresh line": If at the beginning of line, does nothing. Otherwise moves to the start of a new line.

"\e[80;97u"
"\e[80;99u"
"\e[80;108u"
"\e[80;112u"

Set input editing mode. The value 99 ('c') sets character mode; the value 108 ('l') sets line-editing mode. The value 97 ('a') set automatic mode, which switches between character mode and line-editing mode based on the mode of the inferior process (when using a PTY). The value 112 ('p' for "pipe") is like line-editing mode, but the inferiors doesn’t echo the input, so we have to do it. This mode is useful when the input is a pipe or some other non-tty stream.

"\e[99;99u"

End-of-file on the output stream. Calls the eofSeen method of DomTerm, which may close the current window or other appropriate action.

Stylesheet manipulation

"\e]90;\a"

A request to return a list of the stylesheets in the document.

Result to client: "\x9D" stylesheets "\n"

Each stylesheet is a JSON-formatted string, separated by "\t", suitable for printing by dt-util list-stylesheets.

\e]91;" index "\a"

Disable the stylesheet that has index index in the list of stylesheets in the document.

Result to client: "\x9D" message "\n" where message is empty if there was no problem, and is otherwise an error message.

\e]92;" index "\a"

As above, but enable the specified stylesheet.

\e]93;" index "\a"

Return the contents of the specified stylesheet.

On success the result is "\x9D" rule* "\x9D" where each is a JSON-quoted string. On failure, the result is a (non-quoted) error message.

\e]94;" rule "\a"

If necessary, create a new temporary stylesheet, and add the specified JSON-quoted rule to the end of it.

\e]95;" name "," styles "\a"
\e]96;" name "," styles "\a"

Create or replace a stylesheet with the given name. If there is a <style> with a name attribute equal to name, it is replaced; otherwise a new one is created, with its name set to name. The styles is the literal contents of the new stylesheet; it becomes the child of the <style> element (as a single text node). Both name and styles are strings in quoted (JSON) format.

If the code is 96, no response is sent. If the code is 95, the result to the client is "\x9D" index "\n" where index is the index of the replaced or created stylesheet.

Pretty-printing

"Pretty-printing" refers to breaking a text info multiple lines in a way to minimize the number of lines needed while preserving logical structure and adding helpful indentation. DomTerm implements the features and concepts of the Common Lisp pretty-printing feature. The following uses the latter’s terminology. Doing line-breaking in DomTerm means it can dynamically adjust for varying line width.

"\e]110\a"
"\e]110;" per-line-prefix "\a"

Start a logical block, followed by sections of the output that logically belong together, and that DomTerm will try to group on the same line. If the group needs to be broken into multiple lines, continuation lines will be indented to the current horizontal position.

If there is a “prefix” before the group, send it to DomTerm before this command. On the other hand, if there is a per-line-prefix (a JSON-quoted string) it will written both at the current position, and at the same position in any continuation lines.

"\e]111\a"

End a logical block. If there is a "suffix", send it to DomTerm after this command.

"\e]112;" amount "\a"

Adjust identation of future lines (in the current block). The amount is measured in characters, and is relative to the current position. A negative amount is allowed, as long as you don’t end up to the left of any per-line prefixes.

"\e]113;" amount "\a"

Similar to the 112 command, but amount is relative to the start of the current block (after any per-line prefix).

"\e]114;" prefix "\a"

Adds an extra per-line prefix for future lines, specified by prefix, a JSON-quoted string.

"\e]115\a"

Add a “fill”-type conditional newline.

"\e]116\a"

Add a “linear”-type conditional newline.

"\e]117\a"

Add a “miser”-type conditional newline (which is currently treated the same as a “fill” newline).

"\e]118\a"

A required newline. This should be used (rather than a plain newline) when inside a logical-block.

"\e]115;"prebreak","postbreak","nonbreak "\a"
"\e]116;"prebreak","postbreak","nonbreak "\a"
"\e]117;"prebreak","postbreak","nonbreak "\a"
"\e]118;"prebreak","postbreak","nonbreak "\a"

Line-breaks of the types given above, but with specific strings to be used. Each string is JSON-quoted. The nonbreak string is used if the line is not broken here. If there is a break, the prebreak string is used before the break, and the postbreak string is used after the break (following any indentatioon and per-line prefixes).

For example to insert a hyphenation point, you might write:

\e]115;"-","",""\a

German used to have a rule where “ck” would be hyphenated as “k-k”, as in Zucker (suger):

Zu\e]115;"-k","k","ck"\aer

Special sequences sent by DomTerm to back-end

"\x92" name " " data "\n"

General format for reporting events, where name is the name of the event (an identifier). The data can be any text not including a "\n" (or other control character); JSON format is used in some cases.

"\x92" "WS " rows " " cols " " height " " width "\n"

Report window size from DomTerm to the back-end.

"\x92" "KEY " kcode " " kchars "\n"

Used by auto-line mode to report a key event to back-end. The kcode is a numeric key code, while kchars is as string literal (JSON-formatted) of the characters that are normally transmitted to the back-end. (If the events was a key-press event, the kcode is negated first.) In auto-line mode, if the pty is in canonical mode, then key is returned to DomTerm (using "\e]74;" key "\a"); otherwise kchars are sent to the pty.

"\x92" "ALINK " href "\n"

Sent by the DomTerm browser when the user clicks on an <a> link. The backend should open href (which is JSON-encoded) in the default browser of the user’s desktop. (In the future to better support remote desktops, the backend should support a proxy server: The href should be resolved based on the backend’s environment.)

"\x92" "VERSION " version-info "\n"

Sends version-info to the back-end. Used during initialization.