| 📦 Turbo JS 91999d1 k33g 10h ago | 1 | # Reference: terminal windows |
| 2 | |
| 3 | > Neutral description of the terminal windows Turbo JS opens, the keys they answer to, and the escape sequences the emulator implements. |
| 4 | |
| 5 | ## Opening |
| 6 | |
| 7 | | Route | Condition | |
| 8 | | --- | --- | |
| 9 | | `F8` | Always | |
| 10 | | **Window ▸ New terminal** | Always | |
| 11 | |
| 12 | Neither requires a file to be open. A tool in `.turbo-js/tools.toml` whose `output` is `terminal` also opens one, running that command instead of a shell; see [JavaScript tools](javascript-tools.md). |
| 13 | |
| 14 | ## The shell |
| 15 | |
| 16 | | Property | Value | |
| 17 | | --- | --- | |
| 18 | | Program | `$SHELL`, or `/bin/sh` when it is unset or empty; on Windows `%COMSPEC%`, or `cmd.exe` | |
| 19 | | Working directory | The directory of the file in the front window; the editor's working directory when no file is open | |
| 20 | | `TERM` | `xterm-256color`, always — replacing any inherited value | |
| 21 | | Environment | The editor's own, with `TERM` replaced | |
| 22 | | Controlling terminal | Yes: on Linux and macOS the shell runs in its own session with the pseudo-terminal as its controlling terminal; on Windows it is attached to a pseudo-console. Either way job control and `Ctrl-C` work | |
| 23 | | Initial size | The window's, updated whenever the window is resized | |
| 24 | |
| 25 | ## Platform support |
| 26 | |
| 27 | | Platform | Behaviour | |
| 28 | | --- | --- | |
| 29 | | Linux | Supported (`/dev/ptmx`) | |
| 30 | | macOS | Supported (`/dev/ptmx`) | |
| 31 | | Windows | Supported (pseudo-console, ConPTY): Windows 10 version 1809 or later. Built and vetted; **not yet run by the authors** on a Windows machine | |
| 32 | | Others | `F8` opens a message saying terminal windows are not supported yet; nothing else changes | |
| 33 | |
| 34 | ## Keys |
| 35 | |
| 36 | ### After the program has gone |
| 37 | |
| 38 | A window whose command has finished keeps its output, but stops behaving like a terminal: only `Shift-PgUp` and `Shift-PgDn` are still taken, and every other key reaches the editor — which is what lets `Ctrl-W` close it. |
| 39 | |
| 40 | ### Sent to the shell |
| 41 | |
| 42 | Every key not listed under "kept by the editor" below, encoded as a terminal expects it. |
| 43 | |
| 44 | | Key | Bytes sent | |
| 45 | | --- | --- | |
| 46 | | printable character | its UTF-8 encoding | |
| 47 | | `Alt-<key>` | `ESC` followed by that key's own bytes | |
| 48 | | `Ctrl-A` … `Ctrl-Z` | `0x01` … `0x1a` | |
| 49 | | `Enter` | `\r` | |
| 50 | | `Tab` | `\t` | |
| 51 | | `Shift-Tab` | `ESC [ Z` | |
| 52 | | `Backspace` | `0x7f` | |
| 53 | | `Escape` | `0x1b` | |
| 54 | | `↑` `↓` `→` `←` | `ESC [ A B C D`, or `ESC O A B C D` in application cursor mode | |
| 55 | | `Home` `End` | `ESC [ H`, `ESC [ F`, or the `ESC O` forms in application cursor mode | |
| 56 | | `Insert` `Delete` | `ESC [ 2~`, `ESC [ 3~` | |
| 57 | | `PgUp` `PgDn` | `ESC [ 5~`, `ESC [ 6~` | |
| 58 | | `F1` … `F4` | `ESC O P Q R S` | |
| 59 | | `F5` … `F12` | `ESC [ 15~ 17~ 18~ 19~ 20~ 21~ 23~ 24~` | |
| 60 | |
| 61 | A key with no terminal meaning sends nothing. |
| 62 | |
| 63 | ### Kept by the editor |
| 64 | |
| 65 | | Key | Action | |
| 66 | | --- | --- | |
| 67 | | `F1` … `F12` | Their usual editor action | |
| 68 | | `Alt-X` | Exit | |
| 69 | | `Alt-0` … `Alt-9` | List windows / bring window 1…9 forward | |
| 70 | |
| 71 | Function keys therefore never reach a program inside a terminal window. |
| 72 | |
| 73 | ### Handled by the terminal window itself |
| 74 | |
| 75 | | Key | Action | |
| 76 | | --- | --- | |
| 77 | | `Shift-PgUp` | Back one screenful through the history | |
| 78 | | `Shift-PgDn` | Forward one screenful | |
| 79 | |
| 80 | Any key sent to the shell also returns the view to the live screen. |
| 81 | |
| 82 | ## Mouse |
| 83 | |
| 84 | | Action | Effect | |
| 85 | | --- | --- | |
| 86 | | Wheel up / down | Scroll three lines through the history | |
| 87 | | Click | Brings the window forward; not forwarded to the program | |
| 88 | |
| 89 | Mouse reporting is not implemented, so a program is never told about clicks. |
| 90 | |
| 91 | ## History |
| 92 | |
| 93 | | Property | Value | |
| 94 | | --- | --- | |
| 95 | | Lines kept | 2000 | |
| 96 | | What is kept | Lines scrolled off the top of the primary screen only | |
| 97 | | Alternate screen | Not kept — a full-screen program leaves no history behind | |
| 98 | |
| 99 | ## Emulation |
| 100 | |
| 101 | `TERM` is `xterm-256color`. What is implemented of it: |
| 102 | |
| 103 | ### Control characters |
| 104 | |
| 105 | | Byte | Effect | |
| 106 | | --- | --- | |
| 107 | | `0x07` BEL | Noted; the editor does not sound it | |
| 108 | | `0x08` BS | Cursor left one column | |
| 109 | | `0x09` HT | To the next tab stop, every 8 columns | |
| 110 | | `0x0a` `0x0b` `0x0c` | Line feed | |
| 111 | | `0x0d` CR | To column 1 | |
| 112 | |
| 113 | ### Escape sequences |
| 114 | |
| 115 | | Sequence | Name | Effect | |
| 116 | | --- | --- | --- | |
| 117 | | `ESC D` | IND | Line feed | |
| 118 | | `ESC E` | NEL | Carriage return and line feed | |
| 119 | | `ESC M` | RI | Reverse line feed, keeping the column | |
| 120 | | `ESC 7` | DECSC | Save cursor and style | |
| 121 | | `ESC 8` | DECRC | Restore cursor and style | |
| 122 | | `ESC c` | RIS | Full reset | |
| 123 | |
| 124 | ### CSI sequences |
| 125 | |
| 126 | | Sequence | Name | Effect | |
| 127 | | --- | --- | --- | |
| 128 | | `CSI n A B C D` | CUU CUD CUF CUB | Move n cells up, down, right, left | |
| 129 | | `CSI n E F` | CNL CPL | n lines down / up, to column 1 | |
| 130 | | `CSI n G` | CHA | To column n | |
| 131 | | `CSI r ; c H`, `CSI r ; c f` | CUP HVP | To row r, column c | |
| 132 | | `CSI n d` | VPA | To row n | |
| 133 | | `CSI n J` | ED | Erase display: 0 to end, 1 to start, 2 or 3 all | |
| 134 | | `CSI n K` | EL | Erase line: 0 to end, 1 to start, 2 all | |
| 135 | | `CSI n L` | IL | Insert n blank lines at the cursor | |
| 136 | | `CSI n M` | DL | Delete n lines at the cursor | |
| 137 | | `CSI n @` | ICH | Insert n blank cells | |
| 138 | | `CSI n P` | DCH | Delete n cells | |
| 139 | | `CSI n X` | ECH | Erase n cells in place | |
| 140 | | `CSI n S` | SU | Scroll the region up n lines | |
| 141 | | `CSI n T` | SD | Scroll the region down n lines | |
| 142 | | `CSI t ; b r` | DECSTBM | Set the scroll region to rows t…b | |
| 143 | | `CSI s`, `CSI u` | SCP RCP | Save / restore the cursor | |
| 144 | | `CSI … m` | SGR | Colours and attributes, below | |
| 145 | |
| 146 | `IL` and `DL` do nothing when the cursor is outside the scroll region. |
| 147 | |
| 148 | ### Private modes |
| 149 | |
| 150 | Set with `CSI ? n h`, cleared with `CSI ? n l`. |
| 151 | |
| 152 | | n | Name | Effect | |
| 153 | | --- | --- | --- | |
| 154 | | 1 | DECCKM | Application cursor keys: arrows send `ESC O x` | |
| 155 | | 7 | DECAWM | Auto-wrap at the right margin | |
| 156 | | 25 | DECTCEM | Show the cursor | |
| 157 | | 47, 1047 | | Alternate screen | |
| 158 | | 1048 | | Save / restore the cursor | |
| 159 | | 1049 | | Save the cursor, then the alternate screen | |
| 160 | |
| 161 | Any other mode is parsed and ignored. |
| 162 | |
| 163 | ### SGR |
| 164 | |
| 165 | | Code | Effect | |
| 166 | | --- | --- | |
| 167 | | 0 | Reset | |
| 168 | | 1, 22 | Bold on / off | |
| 169 | | 2, 22 | Dim on / off | |
| 170 | | 3, 23 | Italic on / off | |
| 171 | | 4, 24 | Underline on / off | |
| 172 | | 5, 6, 25 | Blink on / off | |
| 173 | | 7, 27 | Reverse on / off | |
| 174 | | 9, 29 | Strike-through on / off | |
| 175 | | 30–37, 40–47 | The eight normal colours, foreground / background | |
| 176 | | 90–97, 100–107 | The eight bright colours, foreground / background | |
| 177 | | 38;5;n, 48;5;n | Palette colour n of 256 | |
| 178 | | 38;2;r;g;b, 48;2;r;g;b | 24-bit colour | |
| 179 | | 39, 49 | Back to the theme's colour | |
| 180 | |
| 181 | The sixteen named colours are tcell's, which means the palette the user's own terminal is configured with, not fixed hex values. An extended colour that runs out of parameters partway leaves the style unchanged. Any other code is ignored. |
| 182 | |
| 183 | ### OSC |
| 184 | |
| 185 | | Sequence | Effect | |
| 186 | | --- | --- | |
| 187 | | `OSC 0 ; text BEL`, `OSC 2 ; text BEL` | Set the window title | |
| 188 | | `OSC … ST` | The `ESC \` terminator is accepted in place of BEL | |
| 189 | |
| 190 | The title is capped at 4096 bytes. Other OSC commands are parsed and ignored. |
| 191 | |
| 192 | ### Consumed and ignored |
| 193 | |
| 194 | Parsed correctly, so they never appear as stray characters, but with no effect: |
| 195 | |
| 196 | | Sequence | Name | |
| 197 | | --- | --- | |
| 198 | | `ESC P …`, `ESC X …`, `ESC ^ …`, `ESC _ …` | DCS, SOS, PM, APC — read to their string terminator | |
| 199 | | `ESC (`, `ESC )`, `ESC *`, `ESC +`, `ESC %`, `ESC #`, `ESC <space>` | Character-set and line-size selectors — the emulator works in UTF-8 regardless | |
| 200 | | `CSI ? n h`, `CSI ? n l` for any other n | Private modes not listed above | |
| 201 | | Any other CSI final byte, SGR code, or OSC command | | |
| 202 | |
| 203 | ### Not implemented |
| 204 | |
| 205 | Mouse reporting, bracketed paste, shift-in / shift-out, double-width lines, sixel and other graphics protocols, and the DEC status and device-attribute reports. A program that asks for one of these gets no reply, so a program that waits for one waits forever. |
| 206 | |
| 207 | ## Colours |
| 208 | |
| 209 | | Theme key | What it colours | |
| 210 | | --- | --- | |
| 211 | | `terminal.text` | Every cell whose colour the program did not choose | |
| 212 | | `terminal.cursor` | The cell under the cursor, when the window has the focus | |
| 213 | |
| 214 | See [Theme file format](themes.md). |
| 215 | |
| 216 | ## Errors |
| 217 | |
| 218 | | Message | Cause | |
| 219 | | --- | --- | |
| 220 | | Terminal windows are not supported on this platform yet | The build has no pseudo-terminal support: any platform other than Linux, macOS and Windows | |
| 221 | | `openpt: …`, `grantpt: …`, `ptsname: …` | The operating system refused to open a pseudo-terminal | |
| 222 | | `fork/exec …: no such file or directory` | `$SHELL` names a program that does not exist | |
| 223 | |
| 224 | ## See also |
| 225 | |
| 226 | - [How to run shell commands without leaving the editor](../how-to/use-a-terminal.md) |
| 227 | - [Terminal windows](../explanation/terminal-windows.md) |
| 228 | - [Keyboard](keyboard.md) |