This is mostly brainstorming and a place to collect requests and descriptions.
I strongly believe we should set a baseline that every terminal implementing the capability report feature should fullfil. This is in a way a implicit capability that is assumed to be always available.
The set of capabilities proposed inherently assumes a terminal that has a lot of common features and a base capability set. Parts of this base capability set are loosely defined by the selection of the TERM variable setup by the terminal.
Additionally we should require some or all of these:
- unknown sequences are ignored without any side effects (no 'bell', no visual glitche, logging in debugging modes is ok)
-
- CSI sequences including private sequences with "?", ">", "=", or "<" and sequences with intermediate characters between the parameters and the final character. TODO define this more formally. Implementations may impose a reasonable limit on the total length of the sequence. TODO define a lower bound for accepted sequence length in some way.
-
- OSC sequences. Including support for termination with ESC \
-
- APC sequences. Including support for termination with ESC \
-
- PM sequences. Including support for termination with ESC \
Many terminals support 24-bit and 256 color selection. Supported control sequence formats differ.
Format survey: https://gist.github.com/textshell/93ae4cbf4d8f93e26bdd1affda90318f
Many terminal application and implementation authors feel that the version based on ";" is breaking basic expectations of SGR sequence usage and should no longer be recommended, but it's still the single most widely supported sequence.
Possible capability descriptions include:
ESC[...;48:2:〈red〉:〈green〉:〈blue〉;...m -> changes background color to the specified color (range 0..255)
ESC[...;38:2:〈red〉:〈green〉:〈blue〉;...m -> changes foreground color to the specified color (range 0..255)
Conditional on capability deco-color:
- ESC[...;58:2:〈red〉:〈green〉:〈blue〉;...m -> changes decoration color to the specified color (range 0..255)
Terminals MAY support another number of subparameters. The interpretation of such sequences is not specified. Applications should not send additional subparameters, unless guided by another specification.
ESC[...;48:2::〈red〉:〈green〉:〈blue〉;...m -> changes background color to the specified color (range 0..255)
ESC[...;38:2::〈red〉:〈green〉:〈blue〉;...m -> changes foreground color to the specified color (range 0..255)
Conditional on capability deco-color:
- ESC[...;58:2::〈red〉:〈green〉:〈blue〉;...m -> changes decoration color to the specified color (range 0..255)
Terminals MAY support another number of subparameters. The interpretation of such sequences is not specified. Applications should not send additional subparameters, unless guided by another specification.
ESC[...;48:2:0:〈red〉:〈green〉:〈blue〉;...m -> changes background color to the specified color (range 0..255)
ESC[...;38:2:0:〈red〉:〈green〉:〈blue〉;...m -> changes foreground color to the specified color (range 0..255)
Conditional on capability deco-color:
- ESC[...;58:2:0:〈red〉:〈green〉:〈blue〉;...m -> changes decoration color to the specified color (range 0..255)
Terminals MAY support another number of subparameters. The interpretation of such sequences is not specified. Applications should not send additional subparameters, unless guided by another specification.
ESC[...;48;2;〈red〉;〈green〉;〈blue〉;...m -> changes background color to the specified color (range 0..255) ESC[...;38;2;〈red〉;〈green〉;〈blue〉;...m -> changes foreground color to the specified color (range 0..255)
Conditional on capability deco-color:
- ESC[...;58;2;〈red〉;〈green〉;〈blue〉;...m -> changes decoration color to the specified color (range 0..255)
ESC[...;48:5:〈index〉;...m -> changes background color to the specified color (range 0..255) ESC[...;38:5:〈index〉;...m -> changes foreground color to the specified color (range 0..255)
Conditional on capability deco-color:
- ESC[...;58:5:〈index〉;...m -> changes decoration color to the specified color (range 0..255)
Note: This is not the most widely supported sequence. But this seems to be the sequence to use going forward. So it should have a capability. Applications needs a concrete sequence they can use. If the other sequence is deemed important enough it needs an distinct capability.
ESC[...;48;5;〈index〉;...m -> changes background color to the specified color (range 0..255) ESC[...;38;5;〈index〉;...m -> changes foreground color to the specified color (range 0..255)
Conditional on capability deco-color:
- ESC[...;58;5;〈index〉;...m -> changes decoration color to the specified color (range 0..255)
Colors set via sequences in any of the 256-color* and RGB* conditional on deco-color set underline colors (for all types of underlines)
Example:
$ printf '\033[4;58:2:255:0:0mtest\033[0m\n'
The Terminal responds to ESC[?6n with ESC[?〈row〉;〈column〉R where row and column are 1 based and report the current cursor position.
The specific syntax difference to a more widely supported sequence is the reply that includes a '?' which allows distinguishing the report from a common report encoding ofthe F1 key.
Example:
$ printf '\033[?6n'; read -r a
^[[?12;1R
See: http://terminalguide.namepad.de/seq/csi_sn__p-6/
This control allows confining the scroll region and line wrapping into a subrange of the horizontal terminal space. In conjunction with the Cursor Origin Mode it can also confine the cursor movement.
The setup control sequence is only active while mode "?69" is enabled. If this mode is disabled the terminal MUST restore the scroll region to the full width of the terminal. The cursor position MUST not be changed when the mode is disabled. If printing the next character before disabling the mode would have produced a line wrap, this state is preserved after the mode is disabled (i.e. even if the margin is now not on the cursor, printing a character still wraps before the character is printed)
The horizontal scroll region (i.e. margins) are setup using the sequence:
ESC[〈left〉;〈right〉s
If 〈left〉 is empty the terminal MUST default it to the value 1 (the left most column). If 〈right〉 is empty, zero or bigger than the right-most column the terminal MUST execute the sequence as if it had used the right most column for 〈right〉.
If 〈left〉 is bigger or equal to 〈right〉 then the terminal MUST ignore the sequence.
The scroll region of the terminal is restricted to the columns starting at and including 〈left〉 to the column 〈right〉 (included).
As a side effect of execution of this sequence the cursor is moved to the top-left cell of the terminal if mode "?6" is not active. If mode "?6" is active the cursor is moved to the top left cell of the scroll region.
The Cursor Origin Mode("?6") is used to adjust the effect of the configured scroll region. If it's active, the cursor movement is constrained to the scrolling region. When the mode is enabled the cursor is moved to the top-left cell of the scrolling region. This movement happens on each ESC[?6h even if the mode was already active. ESC[?6l moves the cursor to the top-left cell of the terminal. See below for additional details.
If the cursor position after the following sequences would be right of the right most column of the scrolling region the cursor will be placed on the right most column of the scrolling region: TAB or ESC[〈amount〉I or ESC[〈amount〉a
If Cursor Origin Mode is active and the cursor position after the following sequences would be left of the left most column of the scrolling region the cursor will be placed on the left most column of the scrolling region: ESC[〈amount〉Z
Movement of the following sequences will stop at left-most column of the scrolling-region (but are not restricted if the cursor is already outside of the scrolling region): ESC[〈〉D¹² BACKSPACE¹²
Movement of the following sequence will stop at right-most column of the scrolling-region (but are not restricted if the cursor is already outside of the scrolling region): ESC[〈〉C¹
¹ also resets pending wrap state ² more complex handling applies if both modes ?45 and ?7 are enabled
The following sequences are restricted to act inside the scrolling region and do nothing when the cursor is outside of the scrolling region: ESC[〈amount〉␣A or ESC[〈amount〉␣@ or ESC[〈amount〉L or ESC[〈amount〉M or ESC[〈amount〉P or ESC[〈amount〉@ or ESC[〈amount〉'} or ESC[〈amount〉'~
The following sequences do not scroll if the cursor is outside of the scrolling region and if the cursor is moved to the left it is moved to the left most column of the terminal if the cursor is left of the scrolling region and to the left most column of the scrolling region otherwise: LF, VT, FF, ESC E, CR, ESC D, ESC[〈amount〉E, ESC[〈amount〉F, ESC M
The following sequences only have their scrolling behaviour if the cursor is on the left most resp. right most column of the scrolling region: ESC 6 or ESC 9
The following sequences are restricted to act inside the scrolling region and use scrolling region relative positions only when Cursor Origin Mode("?6") is active: ESC[〈〉;〈〉;〈〉;〈〉${ or ESC[〈〉;〈〉;〈〉;〈〉$z or ESC[〈〉;〈〉;〈〉;〈〉;〈〉;〈〉;〈〉;〈〉;$v or ESC[〈〉;〈〉;〈〉;〈〉;〈〉;$x or ESC[〈〉;〈〉;〈〉;〈〉;〈〉$t or ESC[〈〉;〈〉;〈〉;〈〉;〈〉$r
The controls to move the cursor to an absolute column (ESC[〈row〉;〈col〉H or ESC[〈row〉;〈col〉f or ESC[〈col〉` or ESC[〈col〉G ) are not affected by the scroll region, unless Cursor Origin Mode is active. In that case the position is relative to the left-most column of the scroll region and the movement is constraint to be within the scroll region.
ESC[6n and ESC[?6n report cursor position relative to the scrolling region only if Cursor Origin Mode is active, otherwise they report relative to the top-left cell of the terminal.
The save/restore cursor sequences use position relative to the origin defined via Cursor Origin Mode, changes to the scrolling region between save and restore will result in a cursor movement as a consequence: ESC 7 or ESC 8 or ESC[s or ESC[u
The following sequences are restricted to the scrolling region and are active for all cursor positions: ESC[〈amount〉S or ESC[〈amount〉T
The following sequences are never restricted to the scrolling region: ESC[〈cmd〉K or ESC[?〈cmd〉K or ESC[〈cmd〉J or ESC[?〈cmd〉J or ESC[〈amount〉X
If scrolling in the scroll region intersects with a multi-cell character that also in part is outside of the scroll region, the terminal MUST first (before scrolling) replace each such character with spaces preserving this character's background color (not using the active background color from SGR).
Repeat previously printed character 〈amount〉 times.
Repeats the last previously printed character if it is a printable charcter. Only characters with codepoint < 256 are supported.
If 〈amount〉 = 0 the terminal MUST excute this sequence as if it had 〈amount〉 set to 1.
The behavior of this sequence is implementation defined if 〈amount〉 is larger than the number of repetitions of the character than fits into the space right of the cursor in the current line.
This has the same effect as printing the character multiple times.
Sequence:
ESC[〈amount〉b
ESC[?...;1000;...m or ESC[?...;1002;...m or ESC[?...;1003;...m AND ESC[?...;1006;...m
Will enable mouse click / move / drag reports.
Alternatives:
- split into more fine grained capabilites for 1002 and 1003.
Rejected alternatives:
- add capabilities for 1001: Barely used, only one known implementation(xterm)
- 1005 and 1015: strictly worse than 1006
XXX: We should be open to reserve an additional capability for a mode that translates scroll action to a distinct report.
When the alternate screen is active and the mouse wheel is used send arrow up and down.
This is activated as mode "?1007". Default setting of this mode is implementation defined.
The number of arrow up or arrow down sequences that are transmitted is implementation defined.
All mouse reporting modes suppress this and report only in their specific format instead.
Bracket clipboard paste contents in delimiter sequences.
This is activated as mode "?2004".
When pasting from the (e.g. system) clipboard add ESC[200~ before the clipboard contents and ESC[201~ after the clipboard contents.
This allows applications to distinguish clipboard contents from manually typed text.
The terminal MUST ensure that clipboard contents can't cause a ESC[201~ to be transmitted before it's end.
The terminal supports fonts that are considerably bigger than what is needed for the users primary human language. Applications do not need to be conservative about usage of fancy characters. This does not imply any particular set of supported codepoints, but rather conveys that no terminal limitation restricts the user from selecting a fully featured font.
This capability means that the terminal is configured to to read input in utf8 encoding. This also means that the terminal interprets implementation defined ranges of code-points are double wide, which advance the cursor position by two cell when printed.
In some terminals this property is configurable in a running terminal session. The capability state retrieved by the query control sequence reflects the configuration at the time of processing the query. The environment variable cached version of this capability reflects the state of configuration at some point in the past in the same terminal session and thus might be outdated.
Characters with the unicode property TODO are interpreted as 2 cell wide.
TODO: Add a few examples.
TODO: Should this explicitly allow line-drawing characters to still use 1 cell width? Full width line-drawing does not seem to make much sense.
In some terminals this property is configurable in a running terminal session. The capability state retrieved by the query control sequence reflects the configuration at the time of processing the query. The environment variable cached version of this capability reflects the state of configuration at some point in the past in the same terminal session and thus might be outdated.
ESC] 0 ; 〈str〉 ESC \ -> sets the terminal or tab title ESC[22t -> the current title to a internal stack ESC[23t -> restore the last title saved to the stack to current title. This removes the last added title from the stack. Applications MUST call this exactly as often as ESC[22t.
If a terminal supports OSC 1 or OSC 2 the save/restore feature has to cover these too.
Note: Supported Stack size is unspecified. Terminals should implement a stack of at least depth 4. Good terminals support larger stack sizes.
Note: Is there a practical use of specifying OSC 1 and OSC 2? If so how?
Background: http://terminalguide.namepad.de/seq/csi_st-22/ , http://terminalguide.namepad.de/seq/csi_st-23/
printf 'abc\033[42m\033[0K\033[44m\033[4C\033[0K\033[0m\n' should show some green and some blue
If a terminal implements end of line heuristics for clipboard or text extraction usages the erased cells MUST be considered after the end of the line and MUST not produce space characters on text extraction.
ESC[...;53;...m -> text is displayed with overline ESC[...;55;...m -> unset overline
ESC[...;9;...m -> text is displayed with strikethrough ESC[...;29;...m -> unset strikethrough
ESC[...;21;...m -> text is displayed with double underline ESC[...;24;...m -> unset double underline
This is mutually exclusive with other underline styles. The last specified wins.
ESC[...;4:3;...m -> text is displayed with curly underline ESC[...;24;...m -> unset curly underline
This is mutually exclusive with other underline styles. The last specified wins.
ESC[...;3;...m -> text is displayed with italic font variant ESC[...;23;...m -> unset italic
TODO: https://gitlab.freedesktop.org/terminal-wg/specifications/-/merge_requests/2
TODO: mintty
TODO: OSC 7
TODO: https://iterm2.com/documentation-escape-codes.html
TODO
ESC[1␣q and ESC[2␣q -> display a block shaped cursor ESC[0␣q -> reset cursor shape to default
ESC[3␣q and ESC[4␣q -> display a underline shaped cursor ESC[0␣q -> reset cursor shape to default
ESC[5␣q and ESC[6␣q -> display a bar shaped cursor (between cells) ESC[0␣q -> reset cursor shape to default
See: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda
XXX: Supporting this sequence has security implications, we should be open to additional capabilities in this space that come with a well defined security model.
TODO
- sgr: underline(4)
- OSC 52 clipboard (read, write)
- bidi specification from Egmont (https://terminal-wg.pages.freedesktop.org/bidi/future-improvement-ideas/feature-reporting.html)
- UTF-8: Can this be removed, by just saying that any modern system should be doing utf-8 anyway? Is this utf8 is active? Or that it could be enabled? Does the termios flag suffice to detect utf8?
- Unicode version: How fine grained? Which versions had interesting enough changes? Unicode releases fairly often, if everything is covered this needs a lot of caps.
- focus reporting: What decisions will this enable?
- DECFRA
- Add a capability for alt-screen support? Is it sufficient to only require mode "?1049" ?