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 code sequences may change based on experience and feedback.

Notation: Literal characters are written as quoted string literals with escape sequences as understood 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]7;file://" hostname "/"directory "\a"

Specifies the current directory of the process. (This is generated by some shells by default. On Fedora this is done by the script /etc/profile.d/vte.sh.)

"\e]8;" options ";" url "\a" text "\e]8;;\a"

Create a link with the given url and display text (which can contain other escape sequences for styling). The options are ignored. The link has class="plain". See this link.

"\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 (a fragment). The html-text can be a complete html file, but elements such as <html>, <body> or <style> are ignored.

The HTML is sanity-checked for safety.

A <base href="base-url"/> element in the html-text is skipped, except that the base-url is used for subsequent relative URLs (for src attributes for <img> elements, and for href attributes for <a> elements) in the same html-text.

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;" keyName "\a"
"\e]74;" keyName "\a"
"\e]73;" keyName "\t" kstr "\a"
"\e]74;" keyName "\t" kstr "\a"

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

"\e]104;" op , url "a\n"

Create a new sub-window (pane), based on the op. This displays the url webpage in an <iframe>.

"\e]105;" op , saved-url "a\n"

Create a new sub-window (pane), based on the op. This is displays the saved-url, a previously saved terminal session.

"\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"
"\e[15;" edit-mode "u"

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

The edit-mode specifies what kind of input-line-editing is in effect, which affects how mouse clicks are handled. If edit-mode is 0, it means there is no input-line-editing, and no arrow key support by the client; the value 1 (the default) means single-line editing (like GNU readline); the value 2 means the first line of a multi-line editing group (as JLine3).

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

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

"\e]119;" context-id "\a"
"\e[19u" (deprecated)

Start a command group. This command implicitly does a "fresh line" and ends any existing command group with the same context-id. (The "\e[19u" variant is equivalent to an empty context-id - i.e. "\e]119;\a".) Creates a nested command-group if there is no existing command group with the same context-id.

You can write this string before writing an input prompt string. The content-id is commonly the process-id of the REPL.

"\e]120;" group-id "\a"

(Experimental) Enter a new command-group without closing any current group.

"\e]121;" group-id "\a"

(Experimental) Exit the command-group with the given group-id.

"\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[81u\n"

Requent to send the state of the window as a WINDOW-CONTENTS response.

"\e[90;" op "u\n"

Create a new sub-window (pane), based on the op.

"\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.

"\e]103;" state "\a"

Send saved state to new window.

Urgent messages

"\x13" "\x15" sequence "\x14"

This is an “urgent” command sequence, which is the same as sequence, but at higher priority. If the terminal is in the middle of some other escape sequence (or a multi-byte UTF-8 sequence), save the state, evaluate sequence, and restore the state.

"\x13" sequence "\x14"
"\x13" "\x16" sequence "\x14"

These variants are reserved for the domterm backend (server). These are similar to the previous variant, but the sequence is not counted in the running count (used for flow control), nor is it included if an output log is saved (in case it is needed detach+attach). For the second form only: When DomTerm receives a sequence of bytes that contains an urgent sequence, it will execute that before handling preceding bytes.

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 the list-stylesheets command.

\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 " keyname "\t" kchars "\n"

Used by auto-line mode to report a key event to back-end. The keyName is an encoding of the key event in the style of browserkeymap; kchars is a string literal (JSON-formatted) of the characters that are normally transmitted to the back-end. In auto-line mode, if the pty is in canonical mode, then keyName is returned to DomTerm (using "\e]74;" keyName "\a"); otherwise kchars are sent to the pty.

"\x92" "LINK " ref-info "\n"

Sent by the DomTerm browser when the user clicks on an <a> link. The ref-info is a JSON-encoded object with information about the link. The object must have at least an href property. Typically, backend should open href in the default browser of the user’s desktop, though this is contomizable.

"\x92" "RECEIVED " count "\n"

This is used for flow-control. The count is the number of bytes received and processed by the front-end.

"\x92" "SESSION-NAME " session-name "\n"

Set session-name (a JSON-quoted string) as the name for this session.

"\x92" "DETACH\n"

Don’t destroy the session when the last window is closed; instead detach it. (Don’t necessary detach now, if there are other windows on the session.)

"\x92" "FOCUSED\n"

The current (sub-)window has focus.

"\x92" "WINDOW-CONTENTS " rcount "," state "\n"

Report enough of the browser part of the session state so that it can be reproduced when a window is sttached to the session. The state is a JSON-encoded structure. The rcount is similar to the value reported RECEIVED, but as of the start of the most recent urgent message.

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

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