mirrors/ghostty
1
0
Fork 0
mirror of https://github.com/ghostty-org/ghostty.git synced 2026-09-03 12:50:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

libghostty: functions to detect and write until stream ground state

Browse Source 
This adds new functions to both C and Zig to write VT data until the
VT parser reaches a "ground" state. The ground state is when the
parser/stream is stateless: between all partial UTF-8, OSC, CSI, etc.

This lets embedders safely interleave custom VT sequences from multiple
sources. A practical example is a standard terminal reading from a pty
that is then doing custom APC or something mid-stream for their emulator
client.
This commit is contained in:
Mitchell Hashimoto
2026-08-12 06:24:34 -07:00
parent 396166ecbe
commit a69a591af1
5 changed files with 480 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

91
include/ghostty/vt/terminal.h
View File

@@ -54,17 +54,17 @@ extern "C" {
*
* ## Effects
*
* By default, the terminal sequence processing with ghostty_terminal_vt_write()
* only process sequences that directly affect terminal state and
* By default, terminal sequence processing with the VT write functions only
* processes sequences that directly affect terminal state and
* ignores sequences that have side effect behavior or require responses.
* These sequences include things like bell characters, title changes, device
* attributes queries, and more. To handle these sequences, the embedder
* must configure "effects."
*
* Effects are callbacks that the terminal invokes in response to VT
* sequences processed during ghostty_terminal_vt_write(). They let the
* embedding application react to terminal-initiated events such as bell
* characters, title changes, device status report responses, and more.
* sequences processed during VT writes. They let the embedding application
* react to terminal-initiated events such as bell characters, title changes,
* device status report responses, and more.
*
* Each effect is registered with ghostty_terminal_set() using the
* corresponding `GhosttyTerminalOption` identifier. A `NULL` value
@@ -75,9 +75,10 @@ extern "C" {
* back to their own application state without global variables.
* You cannot specify different userdata for different callbacks.
*
* All callbacks are invoked synchronously during
* ghostty_terminal_vt_write(). Callbacks **must not** call
* ghostty_terminal_vt_write() on the same terminal (no reentrancy).
* All callbacks are invoked synchronously during VT writes. Callbacks
* **must not** call ghostty_terminal_vt_write() or
* ghostty_terminal_vt_write_until_ground() on the same terminal
* (no reentrancy).
* And callbacks must be very careful to not block for too long or perform
* expensive operations, since they are blocking further IO processing.
*
@@ -1138,8 +1139,8 @@ typedef enum GHOSTTY_ENUM_TYPED {
*
* Continuation bytes reconstruct an escape sequence or UTF-8 codepoint
* which was unfinished at the end of the most recent
* ghostty_terminal_vt_write() call. They are used automatically by terminal
* snapshots and may also be exported directly with the continuation APIs.
* VT write call. They are used automatically by terminal snapshots and may
* also be exported directly with the continuation APIs.
*
* Tracking is disabled by default. A nonzero value enables tracking and
* sets its byte limit. Passing NULL or a pointer to zero disables tracking.
@@ -1337,9 +1338,9 @@ typedef enum GHOSTTY_ENUM_TYPED {
/**
* The terminal title as set by escape sequences (e.g. OSC 0/2).
*
* Returns a borrowed string. The pointer is valid until the next call
* to ghostty_terminal_vt_write() or ghostty_terminal_reset(). An empty
* string (len=0) is returned when no title has been set.
* Returns a borrowed string. The pointer is valid until the next mutating
* terminal call. An empty string (len=0) is returned when no title has been
* set.
*
* Output type: GhosttyString *
*/
@@ -1349,9 +1350,9 @@ typedef enum GHOSTTY_ENUM_TYPED {
* The terminal's current working directory as set by escape sequences
* (e.g. OSC 7).
*
* Returns a borrowed string. The pointer is valid until the next call
* to ghostty_terminal_vt_write() or ghostty_terminal_reset(). An empty
* string (len=0) is returned when no pwd has been set.
* Returns a borrowed string. The pointer is valid until the next mutating
* terminal call. An empty string (len=0) is returned when no pwd has been
* set.
*
* Output type: GhosttyString *
*/
@@ -1597,6 +1598,21 @@ typedef enum GHOSTTY_ENUM_TYPED {
* Input/output type: GhosttyTerminalModeConfig *
*/
GHOSTTY_TERMINAL_DATA_MODE = 37,
/**
* Whether VT processing is at ground.
*
* Ground is when the stream isn't in the middle of any type of sequence:
* UTF-8, ESC, CSI, OSC, etc. It is the stateless point of the stream.
*
* This is useful to know because it is a point at which you can
* safely insert out-of-band VT sequences. For example, while reading
* from a pty if you want to make your own changes, you can wait until
* the pty input reaches ground, then write yours.
*
* Output type: bool *
*/
GHOSTTY_TERMINAL_DATA_VT_GROUND = 38,
GHOSTTY_TERMINAL_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
} GhosttyTerminalData;
@@ -1682,9 +1698,10 @@ GHOSTTY_API GhosttyResult ghostty_terminal_resize(GhosttyTerminal terminal,
* The behavior of a NULL value is specific to each option and is
* documented by the corresponding GhosttyTerminalOption value.
*
* Callbacks are invoked synchronously during ghostty_terminal_vt_write().
* Callbacks must not call ghostty_terminal_vt_write() on the same
* terminal (no reentrancy).
* Callbacks are invoked synchronously during VT writes. Callbacks must not
* call ghostty_terminal_vt_write() or
* ghostty_terminal_vt_write_until_ground() on the same terminal
* (no reentrancy).
*
* @param terminal The terminal handle (may be NULL, in which case this is a no-op)
* @param option The option to set
@@ -1722,6 +1739,38 @@ GHOSTTY_API void ghostty_terminal_vt_write(GhosttyTerminal terminal,
const uint8_t* data,
size_t len);
/**
* Write VT-encoded data, but only the shortest prefix needed to reach ground.
*
* Ground is when the stream isn't in the middle of any type of sequence:
* UTF-8, ESC, CSI, OSC, etc. It is the stateless point of the stream.
*
* This is useful to know because it is a point at which you can
* safely insert out-of-band VT sequences. For example, while reading
* from a pty if you want to make your own changes, you can wait until
* the pty input reaches ground, then write yours.
*
* If the stream is already at ground then this consumes nothing and returns
* GHOSTTY_SUCCESS. On success, out_consumed is the number of bytes consumed
* before reaching ground, including the byte that reaches it.
* GHOSTTY_NO_VALUE means the full slice was consumed without reaching ground.
*
* @param terminal The terminal handle (must not be NULL)
* @param data Pointer to the data to write, or NULL when len is zero
* @param len Length of the data in bytes
* @param[out] out_consumed Number of bytes consumed (must not be NULL)
* @return GHOSTTY_SUCCESS if ground was reached, GHOSTTY_NO_VALUE if all input
* was consumed without reaching ground, or GHOSTTY_INVALID_VALUE if
* an argument is invalid
*
* @ingroup terminal
*/
GHOSTTY_API GhosttyResult ghostty_terminal_vt_write_until_ground(
GhosttyTerminal terminal,
const uint8_t* data,
size_t len,
size_t* out_consumed);
/**
* Write the terminal's replay-safe VT continuation to a callback writer.
*
@@ -1735,8 +1784,8 @@ GHOSTTY_API void ghostty_terminal_vt_write(GhosttyTerminal terminal,
* GHOSTTY_TERMINAL_OPT_CONTINUATION_MAX_BYTES to a nonzero value before the
* input that produced the continuation was written.
*
* The caller must serialize this operation with ghostty_terminal_vt_write()
* and all other access to the same terminal.
* The caller must serialize this operation with both VT write functions and
* all other access to the same terminal.
*
* @param terminal Terminal to read from (must not be NULL)
* @param writer Destination writer whose write callback must not be NULL