Merge pull request #399 from pluiedev/pluie/jj-poqplzsntrln

docs/vt: document a bunch of OSCs

Author: mitchellh

docs/nav.json

@@ -182,6 +182,11 @@
           "path": "/reference",
           "title": "Reference"
         },
+        {
+          "type": "link",
+          "path": "/external",
+          "title": "External Protocols"
+        },
         {
           "type": "folder",
           "path": "/concepts",
@@ -201,6 +206,11 @@
               "type": "link",
               "path": "/screen",
               "title": "Screen"
+            },
+            {
+              "type": "link",
+              "path": "/colors",
+              "title": "Colors"
             }
           ]
         },
@@ -434,6 +444,83 @@
               "title": "Shift-Escape Behavior (XTSHIFTESCAPE)"
             }
           ]
+        },
+        {
+          "type": "folder",
+          "path": "/osc",
+          "title": "OSC",
+          "children": [
+            {
+              "type": "link",
+              "path": "/0",
+              "title": "Change Window Icon and Title (OSC 0)"
+            },
+            {
+              "type": "link",
+              "path": "/1",
+              "title": "Change Window Icon (OSC 1)"
+            },
+            {
+              "type": "link",
+              "path": "/2",
+              "title": "Change Window Title (OSC 2)"
+            },
+            {
+              "type": "link",
+              "path": "/4",
+              "title": "Query or Change Palette Colors (OSC 4)"
+            },
+            {
+              "type": "link",
+              "path": "/5",
+              "title": "Query or Change Special Colors (OSC 5)"
+            },
+            {
+              "type": "link",
+              "path": "/7",
+              "title": "Change Working Directory (OSC 7)"
+            },
+            {
+              "type": "link",
+              "path": "/9",
+              "title": "Show Desktop Notification (OSC 9)"
+            },
+            {
+              "type": "link",
+              "path": "/conemu",
+              "title": "ConEmu Extensions (OSC 9;n)"
+            },
+            {
+              "type": "link",
+              "path": "/1x",
+              "title": "Query or Change Dynamic Colors (OSC 10–19)"
+            },
+            {
+              "type": "link",
+              "path": "/22",
+              "title": "Change Pointer Shape (OSC 22)"
+            },
+            {
+              "type": "link",
+              "path": "/52",
+              "title": "Query or Change Clipboard Data (OSC 52)"
+            },
+            {
+              "type": "link",
+              "path": "/104",
+              "title": "Reset Palette Colors (OSC 104)"
+            },
+            {
+              "type": "link",
+              "path": "/105",
+              "title": "Reset Special Colors (OSC 105)"
+            },
+            {
+              "type": "link",
+              "path": "/11x",
+              "title": "Reset Dynamic Colors (OSC 110–119)"
+            }
+          ]
         }
       ]
     },

docs/vt/concepts/colors.mdx

@@ -0,0 +1,72 @@
+---
+title: Colors
+description: All sorts of information regarding colors in terminal emulation.
+---
+
+Ghostty emulates a full 256-color palette, as well as 5 **special colors**
+and 3 **dynamic colors**.
+
+## Special Colors
+
+The special colors, when specified, are used to color cells with particular
+styles — bold, underline, blink, reversed and italic. They can be queried
+or changed either with [OSC 4] using indices from 256 to 260 inclusive,
+or [OSC 5] with indices from 0 to 4 inclusive respectively. The ordinary
+palette colors are used instead of special colors when not specified.
+
+[OSC 4]: /docs/vt/osc/4-5
+[OSC 5]: /docs/vt/osc/4-5
+
+## Dynamic Colors
+
+The dynamic colors are used by the terminal to color cells independent of
+their own styles, when they are selected, highlighted, etc. They are also
+supposed to be *dynamically updated* by programs after the terminal has been
+initialized, hence their name. Ghostty currently supports three of these
+colors: the foreground color, the background color and the cursor color,
+which are queried or modified with [OSCs 10 to 12] respectively.
+
+[OSCs 10 to 12]: /docs/vt/osc/1x
+
+## Color Specifications
+
+Each color in the terminal is specified with a **color specification**.
+These originated from xterm, which allows any string that can be parsed by
+X11's standard [`XParseColor`] function to serve as a color. However, since
+Ghostty supports platforms other than X11, we have our own color parser that
+is compatible but not guaranteed to be the same as xterm, which is
+documented below.
+
+[`XParseColor`]: https://linux.die.net/man/3/xparsecolor
+
+### Hexadecimal RGB
+
+<VTSequence sequence={["rgb:", "Pr", "/", "Pg", "/", "Pb"]} /><br/>
+<VTSequence sequence={["#", "Pr", "Pg", "Pb"]} />
+
+Where each of `r`, `g` and `b` can be one to four hexadecimal digits,
+corresponding to 4, 8, 12 or 16 bit color channels respectively.
+
+> [!NOTE]
+> When using the `#` syntax, each channel **must have the same number of
+> digits**.
+>
+> Additionally, Ghostty does not yet recognize 16-bit color channels when
+> using the `#` syntax. This is a limitation that may be resolved in the
+> future.
+
+### Intensity RGB
+
+Another format uses the numerical *intensity* of each channel, as follows:
+
+<VTSequence sequence={["rgbi:", "Pr", "/", "Pg", "/", "Pb"]} />
+
+Where each of `r`, `g` and `b` is a decimal number between `0` and `1`.
+
+### Named
+
+Certain colors can also be specified with their names. The exact list of
+accepted color names are implementation-defined, but Ghostty uses the
+[X color name database](https://gitlab.freedesktop.org/xorg/app/rgb) as used
+by X11 itself. The colors are ASCII case-insensitive, meaning `red` and `RED`
+correspond to the same color.

docs/vt/concepts/sequences.mdx

@@ -10,57 +10,89 @@ that programs interact with the terminal.
 
 Programs running within terminals only have a single way to communicate
 with the terminal: writing bytes to the connected file descriptor
-(typically a pty). In order to differentiate between text to be
-displayed and commands to be executed, terminals use special syntax
-known collectively as **control sequences**.
-
-Due to the historical nature of terminals, control sequences come
-in a handful of different formats. Most begin with an escape character
-(`0x1B`), so control sequences are sometimes referred to as
-**escape codes** or **escape sequences**.
-
-There are eight types of control sequences:
-
-- Control Characters
-- Escape Sequences
-- CSI Sequences ("Control Sequence Introducer")
-- OSC Sequences ("Operating System Command")
-- DCS Sequences ("Device Control Sequence")
-- SOS Sequences ("Start Of String")
-- PM Sequences ("Privacy Message")
-- APC Sequences ("Application Program Command")
+(typically a pseudo-terminal, or a "pty" for short). In order to
+differentiate between text to be displayed and commands to be executed,
+terminals use special syntax known collectively as **control sequences**.
 
 Each type of control sequence has a different format and purpose.
 They are described below along with their specific syntax. The
 [reference](/docs/vt/reference) contains a full list of supported
 control sequences grouped by type.
 
-## Control Characters
+## C0 control characters
 
-Control characters are single byte characters that have a special
-meaning. They have no encoding format; you send the bytes as-is.
-For example, [backspace](/docs/vt/control/bs) is `0x08`,
-[linefeed](/docs/vt/control/lf) is `0x0A`, etc.
+Each control sequence starts with a special, unprintable character, known
+as a **control character**. The simplest control characters, known as
+**C0 control characters**, lie between `0x00` and `0x20` in the ASCII
+encoding and take no parameters other than themselves.
 
 There are very few control characters, but they're important
 to be aware of because the single byte value impacts the terminal
 state.
 
-## Escape Sequences
+C0 characters meaningful to terminal emulation include:
 
-Escape sequences are in the format below. An example escape sequence
-is `ESC D`.
+| C0     | Abbr    | Full name       | Function                                    |
+|--------|---------|-----------------|---------------------------------------------|
+| `0x07` | [`BEL`] | Bell            | Raise the attention of the user.            |
+| `0x08` | [`BS`]  | Backspace       | Move the cursor backward one position.      |
+| `0x09` | [`TAB`] | Tab             | Move the cursor right to the next tab stop. |
+| `0x0A` | [`LF`]  | Linefeed        | Move the cursor down one line.              |
+| `0x0D` | [`CR`]  | Carriage Return | Move the cursor to the leftmost column.     |
+
+[`BEL`]: /docs/vt/control/bel
+[`BS`]: /docs/vt/control/bs
+[`TAB`]: /docs/vt/control/tab
+[`LF`]: /docs/vt/control/lf
+[`CR`]: /docs/vt/control/cr
+
+## Escape sequences
+
+One of the C0 characters, Escape (`0x1b`, `ESC`), is special. It can either
+start a few discrete sequences or begin entire families of sequences, which is
+also why control sequences are also *pars pro toto* commonly known as
+**escape sequences**.
+
+Not all sequences that begin with Escape are Escape sequences as defined here
+(they are more likely to be [C1 sequences](#c1-sequences)),
+but a true Escape sequence like `ESC D` are in the format below.
 
 ```
 esc_sequence = "0x1B" intermediates final
 intermediates = [0x20-0x2F]*
 final = [0x30-0x7E]
 ```
 
-## CSI Sequences
+## `Fe` sequences
+
+When Escape is followed by certain printable characters, for various historical
+reasons they are instead interpreted together as **C1 control characters**,
+some of which are responsible for many families of sequences known collectively
+as `Fe` sequences. These characters can also be represented by single 8-bit
+characters, but they remain **predominantly** encoded with Escape characters as
+to avoid conflicting with UTF-8 and other high-byte encodings usually used in
+modern terminals.
+
+| ESC code | C1     | Abbr | Full name                   | Function                                                                                                 |
+|----------|--------|------|-----------------------------|----------------------------------------------------------------------------------------------------------|
+| `ESC [`  | `0x9b` | CSI  | Control Sequence Introducer | By far the most common. Uses integers to control the cursor, the screen, modes, cells, and their styles. |
+| `ESC ]`  | `0x9d` | OSC  | Operating System Command    | Often used in modern terminal extensions to transmit string data.                                        |
+| `ESC P`  | `0x90` | DCS  | Device Control Sequence     | Most often used when querying the terminal's capabilities (XTGETTCAP). Rare otherwise.                   |
+| `ESC _`  | `0x9f` | APC  | Application Program Command | Used in very complex protocols like the Kitty Graphics Protocol that require arbitrary payloads.         |
+| `ESC X`  | `0x98` | SOS  | Start of String             | Obsolete. Ignored by Ghostty.                                                                            |
+| `ESC ^`  | `0x9e` | PM   | Private Message             | Obsolete. Ignored by Ghostty.                                                                            |
+
+### CSI
+
+CSI sequences are *by far* the most common type of C1 sequences.
+They use integer parameters separated either with colons (`:`) or semicolons
+(`;`) to move the cursor, set the terminal's mode, scroll up or down, insert
+and delete cells and lines, change the styles of cells, etc.
 
-CSI sequences are in the format below. An example CSI sequence
-is `ESC [ 1 ; 2 m`. CSI sequences are only capable of encoding integer values.
+Their primary limitation is that they can **only** encode integer values.
+Other sequence types such as OSC or DCS are needed to encode string data.
+
+CSI sequences follow the format below. An example CSI sequence is `ESC [ 1 ; 2 m`.
 
 ```
 csi_sequence = "0x1B" "[" params intermediates final
@@ -71,21 +103,45 @@ intermediates = [0x20-0x2F]*
 final = [0x40-0x7E]
 ```
 
-## OSC Sequences
+### OSC
+
+OSC sequences are typically used to encode strings or other non-integer data to
+transmit between the terminal and an application. They usually alter variables
+regarding the terminal emulator itself, such as its title, palette,
+clipboard, etc., or instruct it on extra features like hyperlinks, progress
+reports, the current working directory, and so on.
+
+As a result of its flexibility, OSC sequences are very often used by modern
+extensions to offer new functionality that older terminals can simply ignore.
+
+An OSC sequence begins with OSC (`ESC ]` or `0x9d`). Then, by convention, an
+integer is added to identify the operation 
 
-OSC Sequences are typically used to encode strings or other non-integer data to
-transmit between the terminal and the application. The format of an OSC sequence
-is below. An example OSC sequence is `OSC 2 ; 👻  Ghostty 👻  ST` (where `ST` is
-the String Terminator). By convention, OSC sequences *usually* have some integer
-identifier to identify the sequence.
+The format of an OSC sequence is below. By convention, OSC sequences are
+identified by an integer identifier followed by a semicolon (`;`), although
+this is never required by the standard. Certain obsolete OSC sequences use
+non-numeric identifiers before the semicolon, but Ghostty does not support
+
+> [!NOTE]
+> Due to yet more convoluted historical reasons, OSC sequences in xterm (and
+> by extension Ghostty) may be terminated with the Bell character (`BEL`,
+> `0x07`) instead of the standard String Terminator (`ST`, `ESC \` or `0x9c`).
+>
+> While they are in most cases interchangeable, Ghostty will try to echo back
+> the terminator used in an OSC sequence when replying, to ensure maximum
+> compatibility with older programs and terminals. New code should always
+> prefer `ST` due to standards compliance.
+
+them. An example OSC sequence is `OSC 2 ; 👻  Ghostty 👻  ST` (where `ST` is
+the String Terminator).
 
 ```
-osc_sequence = "0x1B" "]" data ST
+osc_sequence = "0x1B" "]" data terminator
 data = [0x20-0xFF]
-ST = "0x1B" "0x5C"
+terminator = "0x1B" "0x5C"
 ```
 
-## DCS Sequences
+### DCS
 
 DCS Sequences are like a CSI sequence combined with an OSC sequence: they
 natively support integer parameters as well as string values. An example DSC
@@ -101,7 +157,7 @@ data = [0x20-0xFF]
 ST = "0x1B" "0x5C"
 ```
 
-## APC Sequences
+### APC
 
 Ghostty supports APC sequences. Currently there is only one supported APC
 sequence: the Kitty Graphics Protocol sequence. This is documented [here](https://sw.kovidgoyal.net/kitty/graphics-protocol/).
@@ -112,7 +168,7 @@ data = [0x20-0xFF]
 ST = "0x1B" "0x5C"
 ```
 
-## SOS and PM Sequences
+### SOS and PM
 
 SOS and PM sequences are entirely ignored by Ghostty.
 

docs/vt/external.mdx

@@ -0,0 +1,23 @@
+---
+title: External Protocols
+description: A list of external protocols that Ghostty supports.
+---
+
+Ghostty inherits the rich tradition of innovation from other terminal
+emulators, and many modern, well-written specifications do not need to
+be reinvented here. If Ghostty's behavior deviates from these specifications,
+we treat them as bugs which will be fixed according to spec.
+
+Note that we may still provide specifications here if upstream behavior is
+not well-specified (such is the case for most xterm and [ConEmu] extensions),
+or Ghostty intentionally deviates from it for good reason.
+
+[ConEmu]: /docs/vt/osc/conemu
+
+Below is a list of protocols that Ghostty supports, which originate from other
+terminal emulators:
+
+| Protocol                      | Specification |
+|-------------------------------|--------|
+| OSC 8 (Hyperlinks) | [VTE and iTerm2](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda)|
+| OSC 21 (Kitty Color Protocol) | [Kitty](https://sw.kovidgoyal.net/kitty/color-stack/)|