1/**
2 * @file terminal.h
3 *
4 * Complete terminal emulator state and rendering.
5 */
6
7#ifndef GHOSTTY_VT_TERMINAL_H
8#define GHOSTTY_VT_TERMINAL_H
9
10#include <stdbool.h>
11#include <stddef.h>
12#include <stdint.h>
13#include <ghostty/vt/types.h>
14#include <ghostty/vt/allocator.h>
15#include <ghostty/vt/device.h>
16#include <ghostty/vt/modes.h>
17#include <ghostty/vt/size_report.h>
18#include <ghostty/vt/grid_ref.h>
19#include <ghostty/vt/kitty_graphics.h>
20#include <ghostty/vt/screen.h>
21#include <ghostty/vt/point.h>
22#include <ghostty/vt/selection.h>
23#include <ghostty/vt/style.h>
24
25#ifdef __cplusplus
26extern "C" {
27#endif
28
29/** @defgroup terminal Terminal
30 *
31 * Complete terminal emulator state and rendering.
32 *
33 * A terminal instance manages the full emulator state including the screen,
34 * scrollback, cursor, styles, modes, and VT stream processing.
35 *
36 * Once a terminal session is up and running, you can configure a key encoder
37 * to write keyboard input via ghostty_key_encoder_setopt_from_terminal().
38 *
39 * ### Example: VT stream processing
40 * @snippet c-vt-stream/src/main.c vt-stream-init
41 * @snippet c-vt-stream/src/main.c vt-stream-write
42 *
43 * ## Scrollback Compression
44 *
45 * Scrollback compression is caller-driven. The terminal exposes an opaque
46 * activity token so an embedding application can restart an idle timer only
47 * when compression-relevant state changes. Once idle, call incremental
48 * compression until it no longer reports pending work. libghostty-vt does not
49 * create a timer or background thread.
50 *
51 * @snippet c-vt-compression/src/main.c compression-activity
52 * @snippet c-vt-compression/src/main.c compression-idle-step
53 *
54 * ## Effects
55 *
56 * By default, the terminal sequence processing with ghostty_terminal_vt_write()
57 * only process sequences that directly affect terminal state and
58 * ignores sequences that have side effect behavior or require responses.
59 * These sequences include things like bell characters, title changes, device
60 * attributes queries, and more. To handle these sequences, the embedder
61 * must configure "effects."
62 *
63 * Effects are callbacks that the terminal invokes in response to VT
64 * sequences processed during ghostty_terminal_vt_write(). They let the
65 * embedding application react to terminal-initiated events such as bell
66 * characters, title changes, device status report responses, and more.
67 *
68 * Each effect is registered with ghostty_terminal_set() using the
69 * corresponding `GhosttyTerminalOption` identifier. A `NULL` value
70 * pointer clears the callback and disables the effect.
71 *
72 * A userdata pointer can be attached via `GHOSTTY_TERMINAL_OPT_USERDATA`
73 * and is passed to every callback, allowing callers to route events
74 * back to their own application state without global variables.
75 * You cannot specify different userdata for different callbacks.
76 *
77 * All callbacks are invoked synchronously during
78 * ghostty_terminal_vt_write(). Callbacks **must not** call
79 * ghostty_terminal_vt_write() on the same terminal (no reentrancy).
80 * And callbacks must be very careful to not block for too long or perform
81 * expensive operations, since they are blocking further IO processing.
82 *
83 * The available effects are:
84 *
85 * | Option | Callback Type | Trigger |
86 * |-----------------------------------------|-----------------------------------|-------------------------------------------|
87 * | `GHOSTTY_TERMINAL_OPT_WRITE_PTY` | `GhosttyTerminalWritePtyFn` | Query responses written back to the pty |
88 * | `GHOSTTY_TERMINAL_OPT_BELL` | `GhosttyTerminalBellFn` | BEL character (0x07) |
89 * | `GHOSTTY_TERMINAL_OPT_TITLE_CHANGED` | `GhosttyTerminalTitleChangedFn` | Title change via OSC 0 / OSC 2 |
90 * | `GHOSTTY_TERMINAL_OPT_PWD_CHANGED` | `GhosttyTerminalPwdChangedFn` | Pwd change via OSC 7 / OSC 9 / OSC 1337 |
91 * | `GHOSTTY_TERMINAL_OPT_ENQUIRY` | `GhosttyTerminalEnquiryFn` | ENQ character (0x05) |
92 * | `GHOSTTY_TERMINAL_OPT_XTVERSION` | `GhosttyTerminalXtversionFn` | XTVERSION query (CSI > q) |
93 * | `GHOSTTY_TERMINAL_OPT_SIZE` | `GhosttyTerminalSizeFn` | XTWINOPS size query (CSI 14/16/18 t) |
94 * | `GHOSTTY_TERMINAL_OPT_COLOR_SCHEME` | `GhosttyTerminalColorSchemeFn` | Color scheme query (CSI ? 996 n) |
95 * | `GHOSTTY_TERMINAL_OPT_DEVICE_ATTRIBUTES`| `GhosttyTerminalDeviceAttributesFn`| Device attributes query (CSI c / > c / = c)|
96 * | `GHOSTTY_TERMINAL_OPT_CLIPBOARD_WRITE` | `GhosttyTerminalClipboardWriteFn` | Clipboard write via OSC 52 / OSC 1337 |
97 *
98 * ### Defining a write_pty callback
99 * @snippet c-vt-effects/src/main.c effects-write-pty
100 *
101 * ### Defining a bell callback
102 * @snippet c-vt-effects/src/main.c effects-bell
103 *
104 * ### Defining a title_changed callback
105 * @snippet c-vt-effects/src/main.c effects-title-changed
106 *
107 * ### Defining a clipboard_write callback
108 * @snippet c-vt-effects/src/main.c effects-clipboard-write
109 *
110 * ### Registering effects and processing VT data
111 * @snippet c-vt-effects/src/main.c effects-register
112 *
113 * ## Color Theme
114 *
115 * The terminal maintains a set of colors used for rendering: a foreground
116 * color, a background color, a cursor color, and a 256-color palette. Each
117 * of these has two layers: a **default** value set by the embedder, and an
118 * **override** value that programs running in the terminal can set via OSC
119 * escape sequences (e.g. OSC 10/11/12 for foreground/background/cursor,
120 * OSC 4 for individual palette entries).
121 *
122 * ### Default Colors
123 *
124 * Use ghostty_terminal_set() with the color options to configure the
125 * default colors. These represent the theme or configuration chosen by
126 * the embedder. Passing `NULL` clears the default, leaving the color
127 * unset.
128 *
129 * | Option | Input Type | Description |
130 * |-----------------------------------------|-------------------------|--------------------------------------|
131 * | `GHOSTTY_TERMINAL_OPT_COLOR_FOREGROUND` | `GhosttyColorRgb*` | Default foreground color |
132 * | `GHOSTTY_TERMINAL_OPT_COLOR_BACKGROUND` | `GhosttyColorRgb*` | Default background color |
133 * | `GHOSTTY_TERMINAL_OPT_COLOR_CURSOR` | `GhosttyColorRgb*` | Default cursor color |
134 * | `GHOSTTY_TERMINAL_OPT_COLOR_PALETTE` | `GhosttyColorRgb[256]*` | Default 256-color palette |
135 *
136 * For the palette, passing `NULL` resets to the built-in default palette.
137 * The palette set operation preserves any per-index OSC overrides that
138 * programs have applied; only unmodified indices are updated.
139 *
140 * ### Reading colors
141 *
142 * Use ghostty_terminal_get() to read colors. There are two variants for
143 * each color: the **effective** value (which returns the OSC override if
144 * one is active, otherwise the default) and the **default** value (which
145 * ignores any OSC overrides).
146 *
147 * | Data | Output Type | Description |
148 * |---------------------------------------------------|-------------------------|------------------------------------------------|
149 * | `GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND` | `GhosttyColorRgb*` | Effective foreground (override or default) |
150 * | `GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND` | `GhosttyColorRgb*` | Effective background (override or default) |
151 * | `GHOSTTY_TERMINAL_DATA_COLOR_CURSOR` | `GhosttyColorRgb*` | Effective cursor (override or default) |
152 * | `GHOSTTY_TERMINAL_DATA_COLOR_PALETTE` | `GhosttyColorRgb[256]*` | Current palette (with any OSC overrides) |
153 * | `GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND_DEFAULT` | `GhosttyColorRgb*` | Default foreground only (ignores OSC override) |
154 * | `GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND_DEFAULT` | `GhosttyColorRgb*` | Default background only (ignores OSC override) |
155 * | `GHOSTTY_TERMINAL_DATA_COLOR_CURSOR_DEFAULT` | `GhosttyColorRgb*` | Default cursor only (ignores OSC override) |
156 * | `GHOSTTY_TERMINAL_DATA_COLOR_PALETTE_DEFAULT` | `GhosttyColorRgb[256]*` | Default palette only (ignores OSC overrides) |
157 *
158 * For foreground, background, and cursor colors, the getters return
159 * `GHOSTTY_NO_VALUE` if no color is configured (neither a default nor an
160 * OSC override). The palette getters always succeed since the palette
161 * always has a value (the built-in default if nothing else is set).
162 *
163 * ### Setting a color theme
164 * @snippet c-vt-colors/src/main.c colors-set-defaults
165 *
166 * ### Reading effective and default colors
167 * @snippet c-vt-colors/src/main.c colors-read
168 *
169 * ### Full example with OSC overrides
170 * @snippet c-vt-colors/src/main.c colors-main
171 *
172 * @{
173 */
174
175/**
176 * Terminal initialization options.
177 *
178 * @ingroup terminal
179 */
180typedef struct {
181 /** Terminal width in cells. Must be greater than zero. */
182 uint16_t cols;
183
184 /** Terminal height in cells. Must be greater than zero. */
185 uint16_t rows;
186
187 /** Maximum number of lines to keep in scrollback history. */
188 size_t max_scrollback;
189
190 // TODO: Consider ABI compatibility implications of this struct.
191 // We may want to artificially pad it significantly to support
192 // future options.
193} GhosttyTerminalOptions;
194
195/**
196 * Amount of compression work to perform before returning.
197 *
198 * @ingroup terminal
199 */
200typedef enum GHOSTTY_ENUM_TYPED {
201 /** Perform one bounded compression step suitable for idle scheduling. */
202 GHOSTTY_TERMINAL_COMPRESSION_MODE_INCREMENTAL = 0,
203
204 /** Synchronously inspect every currently eligible page. */
205 GHOSTTY_TERMINAL_COMPRESSION_MODE_FULL = 1,
206 GHOSTTY_TERMINAL_COMPRESSION_MODE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
207} GhosttyTerminalCompressionMode;
208
209/**
210 * Scheduling result from terminal compression.
211 *
212 * @ingroup terminal
213 */
214typedef enum GHOSTTY_ENUM_TYPED {
215 /** Retained-mapping reclamation is unavailable on this target. */
216 GHOSTTY_TERMINAL_COMPRESSION_RESULT_UNSUPPORTED = 0,
217
218 /** More incremental compression work remains. */
219 GHOSTTY_TERMINAL_COMPRESSION_RESULT_PENDING = 1,
220
221 /** The pass has no continuation to schedule. */
222 GHOSTTY_TERMINAL_COMPRESSION_RESULT_COMPLETE = 2,
223 GHOSTTY_TERMINAL_COMPRESSION_RESULT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
224} GhosttyTerminalCompressionResult;
225
226/**
227 * Scroll viewport behavior tag.
228 *
229 * @ingroup terminal
230 */
231typedef enum GHOSTTY_ENUM_TYPED {
232 /** Scroll to the top of the scrollback. */
233 GHOSTTY_SCROLL_VIEWPORT_TOP,
234
235 /** Scroll to the bottom (active area). */
236 GHOSTTY_SCROLL_VIEWPORT_BOTTOM,
237
238 /** Scroll by a delta amount (up is negative). */
239 GHOSTTY_SCROLL_VIEWPORT_DELTA,
240
241 /**
242 * Scroll to an absolute row offset from the top of the scrollable
243 * area. Row 0 is the top of the scrollback and the requested row
244 * becomes the first visible row of the viewport. The value is
245 * clamped so the viewport never scrolls beyond the top of the
246 * active area. If the terminal has no scrollback (e.g. the
247 * alternate screen is active), the viewport always remains on the
248 * active area.
249 *
250 * This is the same row space as the offset field of
251 * GhosttyTerminalScrollbar, so a scrollbar position obtained from
252 * GHOSTTY_TERMINAL_DATA_SCROLLBAR round-trips cleanly.
253 */
254 GHOSTTY_SCROLL_VIEWPORT_ROW,
255 GHOSTTY_SCROLL_VIEWPORT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
256} GhosttyTerminalScrollViewportTag;
257
258/**
259 * Scroll viewport value.
260 *
261 * @ingroup terminal
262 */
263typedef union {
264 /** Scroll delta (only used with GHOSTTY_SCROLL_VIEWPORT_DELTA). Up is negative. */
265 intptr_t delta;
266
267 /** Absolute row offset (only used with GHOSTTY_SCROLL_VIEWPORT_ROW). */
268 size_t row;
269
270 /** Padding for ABI compatibility. Do not use. */
271 uint64_t _padding[2];
272} GhosttyTerminalScrollViewportValue;
273
274/**
275 * Tagged union for scroll viewport behavior.
276 *
277 * @ingroup terminal
278 */
279typedef struct {
280 GhosttyTerminalScrollViewportTag tag;
281 GhosttyTerminalScrollViewportValue value;
282} GhosttyTerminalScrollViewport;
283
284/**
285 * Terminal screen identifier.
286 *
287 * Identifies which screen buffer is active in the terminal.
288 *
289 * @ingroup terminal
290 */
291typedef enum GHOSTTY_ENUM_TYPED {
292 /** The primary (normal) screen. */
293 GHOSTTY_TERMINAL_SCREEN_PRIMARY = 0,
294
295 /** The alternate screen. */
296 GHOSTTY_TERMINAL_SCREEN_ALTERNATE = 1,
297 GHOSTTY_TERMINAL_SCREEN_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
298} GhosttyTerminalScreen;
299
300/**
301 * Visual style of the terminal cursor.
302 *
303 * @ingroup terminal
304 */
305typedef enum GHOSTTY_ENUM_TYPED {
306 /** Bar cursor (DECSCUSR 5, 6). */
307 GHOSTTY_TERMINAL_CURSOR_STYLE_BAR = 0,
308
309 /** Block cursor (DECSCUSR 1, 2). */
310 GHOSTTY_TERMINAL_CURSOR_STYLE_BLOCK = 1,
311
312 /** Underline cursor (DECSCUSR 3, 4). */
313 GHOSTTY_TERMINAL_CURSOR_STYLE_UNDERLINE = 2,
314
315 /** Hollow block cursor. */
316 GHOSTTY_TERMINAL_CURSOR_STYLE_BLOCK_HOLLOW = 3,
317 GHOSTTY_TERMINAL_CURSOR_STYLE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
318} GhosttyTerminalCursorStyle;
319
320/**
321 * Scrollbar state for the terminal viewport.
322 *
323 * Represents the scrollable area dimensions needed to render a scrollbar.
324 *
325 * @ingroup terminal
326 */
327typedef struct {
328 /** Total size of the scrollable area in rows. */
329 uint64_t total;
330
331 /** Offset into the total area that the viewport is at. */
332 uint64_t offset;
333
334 /** Length of the visible area in rows. */
335 uint64_t len;
336} GhosttyTerminalScrollbar;
337
338/**
339 * Callback function type for bell.
340 *
341 * Called when the terminal receives a BEL character (0x07).
342 *
343 * @param terminal The terminal handle
344 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
345 *
346 * @ingroup terminal
347 */
348typedef void (*GhosttyTerminalBellFn)(GhosttyTerminal terminal,
349 void* userdata);
350
351/**
352 * Clipboard destination for a clipboard write.
353 *
354 * Protocol-specific destination identifiers are normalized to these values
355 * before the clipboard write callback is invoked.
356 *
357 * @ingroup terminal
358 */
359typedef enum GHOSTTY_ENUM_TYPED {
360 /** The standard system clipboard. */
361 GHOSTTY_CLIPBOARD_LOCATION_STANDARD = 0,
362
363 /** The selection clipboard. */
364 GHOSTTY_CLIPBOARD_LOCATION_SELECTION = 1,
365
366 /** The primary selection clipboard. */
367 GHOSTTY_CLIPBOARD_LOCATION_PRIMARY = 2,
368 GHOSTTY_CLIPBOARD_LOCATION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
369} GhosttyClipboardLocation;
370
371/**
372 * One MIME representation in a clipboard write.
373 *
374 * Both strings are borrowed and valid only for the duration of the callback.
375 * The data is binary-safe and has already been decoded from any protocol-level
376 * encoding. A zero-length data string is an explicit empty representation; it
377 * does not clear the clipboard.
378 *
379 * This struct has a frozen layout and will not gain fields in future versions.
380 *
381 * @ingroup terminal
382 */
383typedef struct {
384 /** MIME type of the representation. */
385 GhosttyString mime;
386
387 /** Decoded, binary-safe representation data. */
388 GhosttyString data;
389} GhosttyClipboardContent;
390
391/**
392 * A semantic, atomic clipboard write.
393 *
394 * This is a sized struct. The callback must only access fields present in the
395 * size reported by `size`. The request, contents array, MIME strings, and
396 * data strings are all borrowed and valid only for the callback duration.
397 *
398 * All entries in `contents` are representations of the same logical value
399 * and must be committed atomically. A `contents_len` of zero requests that
400 * the destination be cleared. This is distinct from a content entry whose data
401 * has zero length.
402 *
403 * @ingroup terminal
404 */
405typedef struct {
406 /** Size of this struct in bytes. */
407 size_t size;
408
409 /** Clipboard destination. */
410 GhosttyClipboardLocation location;
411
412 /** Borrowed array of MIME representations. */
413 const GhosttyClipboardContent* contents;
414
415 /** Number of entries in contents; zero means clear the destination. */
416 size_t contents_len;
417} GhosttyClipboardWrite;
418
419/**
420 * Result of a clipboard write callback.
421 *
422 * Protocols without write acknowledgements, including OSC 52 and iTerm2
423 * OSC 1337 Copy, ignore this result.
424 *
425 * @ingroup terminal
426 */
427typedef enum GHOSTTY_ENUM_TYPED {
428 /** The clipboard write completed successfully. */
429 GHOSTTY_CLIPBOARD_WRITE_RESULT_SUCCESS = 0,
430
431 /** The clipboard write was denied by policy or the user. */
432 GHOSTTY_CLIPBOARD_WRITE_RESULT_DENIED = 1,
433
434 /** The destination or one or more representations are unsupported. */
435 GHOSTTY_CLIPBOARD_WRITE_RESULT_UNSUPPORTED = 2,
436
437 /** The clipboard is temporarily unavailable. */
438 GHOSTTY_CLIPBOARD_WRITE_RESULT_BUSY = 3,
439
440 /** One or more representations contain invalid data. */
441 GHOSTTY_CLIPBOARD_WRITE_RESULT_INVALID_DATA = 4,
442
443 /** The clipboard write failed due to an I/O error. */
444 GHOSTTY_CLIPBOARD_WRITE_RESULT_IO_ERROR = 5,
445 GHOSTTY_CLIPBOARD_WRITE_RESULT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
446} GhosttyClipboardWriteResult;
447
448/**
449 * Callback function type for clipboard_write.
450 *
451 * Called synchronously for a complete logical clipboard write. Protocol
452 * details such as OSC 52 selectors, base64 encoding, multipart chunks,
453 * aliases, and terminators are normalized before this callback is invoked.
454 * OSC 52 and iTerm2 OSC 1337 Copy writes therefore use the same callback
455 * shape. OSC 52 clipboard read requests ("?") are always ignored and never
456 * forwarded to this callback.
457 *
458 * @param terminal The terminal handle
459 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
460 * @param write Borrowed atomic clipboard write request
461 * @return The result of attempting the clipboard write
462 *
463 * @ingroup terminal
464 */
465typedef GhosttyClipboardWriteResult (*GhosttyTerminalClipboardWriteFn)(
466 GhosttyTerminal terminal,
467 void* userdata,
468 const GhosttyClipboardWrite* write);
469
470/**
471 * Callback function type for color scheme queries (CSI ? 996 n).
472 *
473 * Called when the terminal receives a color scheme device status report
474 * query. Return true and fill *out_scheme with the current color scheme,
475 * or return false to silently ignore the query.
476 *
477 * @param terminal The terminal handle
478 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
479 * @param[out] out_scheme Pointer to store the current color scheme
480 * @return true if the color scheme was filled, false to ignore the query
481 *
482 * @ingroup terminal
483 */
484typedef bool (*GhosttyTerminalColorSchemeFn)(GhosttyTerminal terminal,
485 void* userdata,
486 GhosttyColorScheme* out_scheme);
487
488/**
489 * Callback function type for device attributes queries (DA1/DA2/DA3).
490 *
491 * Called when the terminal receives a device attributes query (CSI c,
492 * CSI > c, or CSI = c). Return true and fill *out_attrs with the
493 * response data, or return false to silently ignore the query.
494 *
495 * The terminal uses whichever sub-struct (primary, secondary, tertiary)
496 * matches the request type, but all three should be filled for simplicity.
497 *
498 * @param terminal The terminal handle
499 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
500 * @param[out] out_attrs Pointer to store the device attributes response
501 * @return true if attributes were filled, false to ignore the query
502 *
503 * @ingroup terminal
504 */
505typedef bool (*GhosttyTerminalDeviceAttributesFn)(GhosttyTerminal terminal,
506 void* userdata,
507 GhosttyDeviceAttributes* out_attrs);
508
509/**
510 * Callback function type for enquiry (ENQ, 0x05).
511 *
512 * Called when the terminal receives an ENQ character. Return the
513 * response bytes as a GhosttyString. The memory must remain valid
514 * until the callback returns. Return a zero-length string to send
515 * no response.
516 *
517 * @param terminal The terminal handle
518 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
519 * @return The response bytes to write back to the pty
520 *
521 * @ingroup terminal
522 */
523typedef GhosttyString (*GhosttyTerminalEnquiryFn)(GhosttyTerminal terminal,
524 void* userdata);
525
526/**
527 * Callback function type for size queries (XTWINOPS).
528 *
529 * Called in response to XTWINOPS size queries (CSI 14/16/18 t).
530 * Return true and fill *out_size with the current terminal geometry,
531 * or return false to silently ignore the query.
532 *
533 * @param terminal The terminal handle
534 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
535 * @param[out] out_size Pointer to store the terminal size information
536 * @return true if size was filled, false to ignore the query
537 *
538 * @ingroup terminal
539 */
540typedef bool (*GhosttyTerminalSizeFn)(GhosttyTerminal terminal,
541 void* userdata,
542 GhosttySizeReportSize* out_size);
543
544/**
545 * Callback function type for title_changed.
546 *
547 * Called when the terminal title changes via escape sequences
548 * (e.g. OSC 0 or OSC 2). The new title can be queried from the
549 * terminal after the callback returns.
550 *
551 * @param terminal The terminal handle
552 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
553 *
554 * @ingroup terminal
555 */
556typedef void (*GhosttyTerminalTitleChangedFn)(GhosttyTerminal terminal,
557 void* userdata);
558
559/**
560 * Callback function type for pwd_changed.
561 *
562 * Called when the terminal pwd (current working directory) changes via
563 * escape sequences: OSC 7 (file:// URI), OSC 9 (ConEmu CurrentDir), or
564 * OSC 1337 CurrentDir (iTerm2). Use ghostty_terminal_get() with
565 * GHOSTTY_TERMINAL_DATA_PWD inside the callback to read the new value.
566 *
567 * The terminal stores whatever bytes the shell emitted, without parsing.
568 * That means for OSC 7 the value is the raw URI (typically file://...);
569 * for OSC 9/OSC 1337 it is typically a bare path. The embedder is
570 * responsible for decoding any URI scheme or host if it cares about them.
571 *
572 * The callback also fires when the shell clears the pwd (e.g. an empty
573 * OSC 7). In that case GHOSTTY_TERMINAL_DATA_PWD returns a zero-length
574 * string.
575 *
576 * @param terminal The terminal handle
577 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
578 *
579 * @ingroup terminal
580 */
581typedef void (*GhosttyTerminalPwdChangedFn)(GhosttyTerminal terminal,
582 void* userdata);
583
584/**
585 * Callback function type for write_pty.
586 *
587 * Called when the terminal needs to write data back to the pty, for
588 * example in response to a device status report or mode query. The
589 * data is only valid for the duration of the call; callers must copy
590 * it if it needs to persist.
591 *
592 * @param terminal The terminal handle
593 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
594 * @param data Pointer to the response bytes
595 * @param len Length of the response in bytes
596 *
597 * @ingroup terminal
598 */
599typedef void (*GhosttyTerminalWritePtyFn)(GhosttyTerminal terminal,
600 void* userdata,
601 const uint8_t* data,
602 size_t len);
603
604/**
605 * Callback function type for XTVERSION.
606 *
607 * Called when the terminal receives an XTVERSION query (CSI > q).
608 * Return the version string (e.g. "myterm 1.0") as a GhosttyString.
609 * The memory must remain valid until the callback returns. Return a
610 * zero-length string to report the default "libghostty" version.
611 *
612 * @param terminal The terminal handle
613 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
614 * @return The version string to report
615 *
616 * @ingroup terminal
617 */
618typedef GhosttyString (*GhosttyTerminalXtversionFn)(GhosttyTerminal terminal,
619 void* userdata);
620
621/**
622 * Terminal option identifiers.
623 *
624 * These values are used with ghostty_terminal_set() to configure
625 * terminal callbacks and associated state.
626 *
627 * @ingroup terminal
628 */
629typedef enum GHOSTTY_ENUM_TYPED {
630 /**
631 * Opaque userdata pointer passed to all callbacks.
632 *
633 * Input type: void*
634 */
635 GHOSTTY_TERMINAL_OPT_USERDATA = 0,
636
637 /**
638 * Callback invoked when the terminal needs to write data back
639 * to the pty (e.g. in response to a DECRQM query or device
640 * status report). Set to NULL to ignore such sequences.
641 *
642 * Input type: GhosttyTerminalWritePtyFn
643 */
644 GHOSTTY_TERMINAL_OPT_WRITE_PTY = 1,
645
646 /**
647 * Callback invoked when the terminal receives a BEL character
648 * (0x07). Set to NULL to ignore bell events.
649 *
650 * Input type: GhosttyTerminalBellFn
651 */
652 GHOSTTY_TERMINAL_OPT_BELL = 2,
653
654 /**
655 * Callback invoked when the terminal receives an ENQ character
656 * (0x05). Set to NULL to send no response.
657 *
658 * Input type: GhosttyTerminalEnquiryFn
659 */
660 GHOSTTY_TERMINAL_OPT_ENQUIRY = 3,
661
662 /**
663 * Callback invoked when the terminal receives an XTVERSION query
664 * (CSI > q). Set to NULL to report the default "libghostty" string.
665 *
666 * Input type: GhosttyTerminalXtversionFn
667 */
668 GHOSTTY_TERMINAL_OPT_XTVERSION = 4,
669
670 /**
671 * Callback invoked when the terminal title changes via escape
672 * sequences (e.g. OSC 0 or OSC 2). Set to NULL to ignore title
673 * change events.
674 *
675 * Input type: GhosttyTerminalTitleChangedFn
676 */
677 GHOSTTY_TERMINAL_OPT_TITLE_CHANGED = 5,
678
679 /**
680 * Callback invoked in response to XTWINOPS size queries
681 * (CSI 14/16/18 t). Set to NULL to silently ignore size queries.
682 *
683 * Input type: GhosttyTerminalSizeFn
684 */
685 GHOSTTY_TERMINAL_OPT_SIZE = 6,
686
687 /**
688 * Callback invoked in response to a color scheme device status
689 * report query (CSI ? 996 n). Return true and fill the out pointer
690 * to report the current scheme, or return false to silently ignore.
691 * Set to NULL to ignore color scheme queries.
692 *
693 * Input type: GhosttyTerminalColorSchemeFn
694 */
695 GHOSTTY_TERMINAL_OPT_COLOR_SCHEME = 7,
696
697 /**
698 * Callback invoked in response to a device attributes query
699 * (CSI c, CSI > c, or CSI = c). Return true and fill the out
700 * pointer with response data, or return false to silently ignore.
701 * Set to NULL to ignore device attributes queries.
702 *
703 * Input type: GhosttyTerminalDeviceAttributesFn
704 */
705 GHOSTTY_TERMINAL_OPT_DEVICE_ATTRIBUTES = 8,
706
707 /**
708 * Set the terminal title manually.
709 *
710 * The string data is copied into the terminal. A NULL value pointer
711 * clears the title (equivalent to setting an empty string).
712 *
713 * Input type: GhosttyString*
714 */
715 GHOSTTY_TERMINAL_OPT_TITLE = 9,
716
717 /**
718 * Set the terminal working directory manually.
719 *
720 * The string data is copied into the terminal. A NULL value pointer
721 * clears the pwd (equivalent to setting an empty string).
722 *
723 * Input type: GhosttyString*
724 */
725 GHOSTTY_TERMINAL_OPT_PWD = 10,
726
727 /**
728 * Set the default foreground color.
729 *
730 * A NULL value pointer clears the default (unset).
731 *
732 * Input type: GhosttyColorRgb*
733 */
734 GHOSTTY_TERMINAL_OPT_COLOR_FOREGROUND = 11,
735
736 /**
737 * Set the default background color.
738 *
739 * A NULL value pointer clears the default (unset).
740 *
741 * Input type: GhosttyColorRgb*
742 */
743 GHOSTTY_TERMINAL_OPT_COLOR_BACKGROUND = 12,
744
745 /**
746 * Set the default cursor color.
747 *
748 * A NULL value pointer clears the default (unset).
749 *
750 * Input type: GhosttyColorRgb*
751 */
752 GHOSTTY_TERMINAL_OPT_COLOR_CURSOR = 13,
753
754 /**
755 * Set the default 256-color palette.
756 *
757 * The value must point to an array of exactly 256 GhosttyColorRgb values.
758 * A NULL value pointer resets to the built-in default palette.
759 *
760 * Input type: GhosttyColorRgb[256]*
761 */
762 GHOSTTY_TERMINAL_OPT_COLOR_PALETTE = 14,
763
764 /**
765 * Set the Kitty image storage limit in bytes.
766 *
767 * Applied to all initialized screens (primary and alternate).
768 * A value of zero disables the Kitty graphics protocol entirely,
769 * deleting all stored images and placements. A NULL value pointer
770 * is equivalent to zero (disables). Has no effect when Kitty graphics
771 * are disabled at build time.
772 *
773 * Input type: uint64_t*
774 */
775 GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_STORAGE_LIMIT = 15,
776
777 /**
778 * Enable or disable Kitty image loading via the file medium.
779 *
780 * A NULL value pointer is a no-op. Has no effect when Kitty graphics
781 * are disabled at build time.
782 *
783 * Input type: bool*
784 */
785 GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_FILE = 16,
786
787 /**
788 * Enable Kitty image loading via the temporary file medium, restricted to
789 * the provided directory. The string data is copied into the terminal.
790 *
791 * A NULL value pointer disables the temporary file medium. Has no effect
792 * when Kitty graphics are disabled at build time.
793 *
794 * Input type: GhosttyString*
795 */
796 GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_TEMP_FILE = 17,
797
798 /**
799 * Enable or disable Kitty image loading via the shared memory medium.
800 *
801 * A NULL value pointer is a no-op. Has no effect when Kitty graphics
802 * are disabled at build time.
803 *
804 * Input type: bool*
805 */
806 GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_SHARED_MEM = 18,
807
808 /**
809 * Set the maximum bytes the APC handler will buffer for all protocols.
810 * This prevents malicious input from causing unbounded memory allocation.
811 * A NULL value pointer removes all overrides, reverting to the built-in
812 * defaults.
813 *
814 * Input type: size_t*
815 */
816 GHOSTTY_TERMINAL_OPT_APC_MAX_BYTES = 19,
817
818 /**
819 * Set the maximum bytes the APC handler will buffer for Kitty graphics
820 * protocol data. A NULL value pointer removes the override, reverting
821 * to the built-in default.
822 *
823 * Input type: size_t*
824 */
825 GHOSTTY_TERMINAL_OPT_APC_MAX_BYTES_KITTY = 20,
826
827 /**
828 * Set the active screen selection.
829 *
830 * The value must point to a GhosttySelection whose grid references are
831 * valid for this terminal's active screen at the time of the call. The
832 * terminal copies the selection immediately and converts it to
833 * terminal-owned tracked state, so the GhosttySelection struct and its
834 * untracked grid references do not need to outlive this call.
835 *
836 * Passing NULL clears the active screen selection.
837 *
838 * Input type: GhosttySelection*
839 */
840 GHOSTTY_TERMINAL_OPT_SELECTION = 21,
841
842 /**
843 * Set the default cursor style used by DECSCUSR reset (CSI 0 q).
844 *
845 * A NULL value pointer resets to the built-in default block cursor.
846 *
847 * Input type: GhosttyTerminalCursorStyle*
848 */
849 GHOSTTY_TERMINAL_OPT_DEFAULT_CURSOR_STYLE = 22,
850
851 /**
852 * Set whether the default cursor should blink when reset by DECSCUSR
853 * (CSI 0 q).
854 *
855 * A NULL value pointer resets to the built-in default of not blinking.
856 *
857 * Input type: bool*
858 */
859 GHOSTTY_TERMINAL_OPT_DEFAULT_CURSOR_BLINK = 23,
860
861 /**
862 * Enable or disable Glyph Protocol APC handling.
863 *
864 * When disabled, Glyph Protocol APC sequences are ignored and no
865 * support/query/register/clear responses are emitted. Disabling also clears
866 * the terminal session's glyph glossary. A NULL value pointer is a no-op.
867 *
868 * Input type: bool*
869 */
870 GHOSTTY_TERMINAL_OPT_GLYPH_PROTOCOL = 24,
871
872 /**
873 * Callback invoked when the terminal pwd changes via escape
874 * sequences (OSC 7, OSC 9, or OSC 1337 CurrentDir). Set to NULL
875 * to ignore pwd change events.
876 *
877 * Input type: GhosttyTerminalPwdChangedFn
878 */
879 GHOSTTY_TERMINAL_OPT_PWD_CHANGED = 25,
880
881 /**
882 * Callback invoked when the running program performs a clipboard write.
883 * OSC 52 and iTerm2 OSC 1337 Copy writes are normalized to an atomic set
884 * of decoded MIME representations. Set to NULL to ignore clipboard writes.
885 * Clipboard read requests are always ignored; see
886 * GhosttyTerminalClipboardWriteFn.
887 *
888 * Input type: GhosttyTerminalClipboardWriteFn
889 */
890 GHOSTTY_TERMINAL_OPT_CLIPBOARD_WRITE = 26,
891 GHOSTTY_TERMINAL_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
892} GhosttyTerminalOption;
893
894/**
895 * Terminal data types.
896 *
897 * These values specify what type of data to extract from a terminal
898 * using `ghostty_terminal_get`.
899 *
900 * @ingroup terminal
901 */
902typedef enum GHOSTTY_ENUM_TYPED {
903 /** Invalid data type. Never results in any data extraction. */
904 GHOSTTY_TERMINAL_DATA_INVALID = 0,
905
906 /**
907 * Terminal width in cells.
908 *
909 * Output type: uint16_t *
910 */
911 GHOSTTY_TERMINAL_DATA_COLS = 1,
912
913 /**
914 * Terminal height in cells.
915 *
916 * Output type: uint16_t *
917 */
918 GHOSTTY_TERMINAL_DATA_ROWS = 2,
919
920 /**
921 * Cursor column position (0-indexed).
922 *
923 * Output type: uint16_t *
924 */
925 GHOSTTY_TERMINAL_DATA_CURSOR_X = 3,
926
927 /**
928 * Cursor row position within the active area (0-indexed).
929 *
930 * Output type: uint16_t *
931 */
932 GHOSTTY_TERMINAL_DATA_CURSOR_Y = 4,
933
934 /**
935 * Whether the cursor has a pending wrap (next print will soft-wrap).
936 *
937 * Output type: bool *
938 */
939 GHOSTTY_TERMINAL_DATA_CURSOR_PENDING_WRAP = 5,
940
941 /**
942 * The currently active screen.
943 *
944 * Output type: GhosttyTerminalScreen *
945 */
946 GHOSTTY_TERMINAL_DATA_ACTIVE_SCREEN = 6,
947
948 /**
949 * Whether the cursor is visible (DEC mode 25).
950 *
951 * Output type: bool *
952 */
953 GHOSTTY_TERMINAL_DATA_CURSOR_VISIBLE = 7,
954
955 /**
956 * Current Kitty keyboard protocol flags.
957 *
958 * Output type: GhosttyKittyKeyFlags * (uint8_t *)
959 */
960 GHOSTTY_TERMINAL_DATA_KITTY_KEYBOARD_FLAGS = 8,
961
962 /**
963 * Scrollbar state for the terminal viewport.
964 *
965 * This is amortized O(1): the total is maintained incrementally as
966 * the terminal is modified and the viewport offset is cached. The
967 * first read after the viewport moves to an arbitrary position that
968 * isn't an absolute row (e.g. scrolling to a selection) may cost
969 * O(pages) to compute the offset, after which it is cached again.
970 *
971 * There is intentionally no change notification for scroll state.
972 * Callers building scrollbars should poll this once per frame or
973 * per write batch and diff the result to detect changes; this is
974 * what Ghostty's own renderer does.
975 *
976 * Output type: GhosttyTerminalScrollbar *
977 */
978 GHOSTTY_TERMINAL_DATA_SCROLLBAR = 9,
979
980 /**
981 * The current SGR style of the cursor.
982 *
983 * This is the style that will be applied to newly printed characters.
984 *
985 * Output type: GhosttyStyle *
986 */
987 GHOSTTY_TERMINAL_DATA_CURSOR_STYLE = 10,
988
989 /**
990 * Whether any mouse tracking mode is active.
991 *
992 * Returns true if any of the mouse tracking modes (X10, normal, button,
993 * or any-event) are enabled.
994 *
995 * Output type: bool *
996 */
997 GHOSTTY_TERMINAL_DATA_MOUSE_TRACKING = 11,
998
999 /**
1000 * The terminal title as set by escape sequences (e.g. OSC 0/2).
1001 *
1002 * Returns a borrowed string. The pointer is valid until the next call
1003 * to ghostty_terminal_vt_write() or ghostty_terminal_reset(). An empty
1004 * string (len=0) is returned when no title has been set.
1005 *
1006 * Output type: GhosttyString *
1007 */
1008 GHOSTTY_TERMINAL_DATA_TITLE = 12,
1009
1010 /**
1011 * The terminal's current working directory as set by escape sequences
1012 * (e.g. OSC 7).
1013 *
1014 * Returns a borrowed string. The pointer is valid until the next call
1015 * to ghostty_terminal_vt_write() or ghostty_terminal_reset(). An empty
1016 * string (len=0) is returned when no pwd has been set.
1017 *
1018 * Output type: GhosttyString *
1019 */
1020 GHOSTTY_TERMINAL_DATA_PWD = 13,
1021
1022 /**
1023 * The total number of rows in the active screen including scrollback.
1024 *
1025 * Output type: size_t *
1026 */
1027 GHOSTTY_TERMINAL_DATA_TOTAL_ROWS = 14,
1028
1029 /**
1030 * The number of scrollback rows (total rows minus viewport rows).
1031 *
1032 * Output type: size_t *
1033 */
1034 GHOSTTY_TERMINAL_DATA_SCROLLBACK_ROWS = 15,
1035
1036 /**
1037 * The total width of the terminal in pixels.
1038 *
1039 * This is cols * cell_width_px as set by ghostty_terminal_resize().
1040 *
1041 * Output type: uint32_t *
1042 */
1043 GHOSTTY_TERMINAL_DATA_WIDTH_PX = 16,
1044
1045 /**
1046 * The total height of the terminal in pixels.
1047 *
1048 * This is rows * cell_height_px as set by ghostty_terminal_resize().
1049 *
1050 * Output type: uint32_t *
1051 */
1052 GHOSTTY_TERMINAL_DATA_HEIGHT_PX = 17,
1053
1054 /**
1055 * The effective foreground color (override or default).
1056 *
1057 * Returns GHOSTTY_NO_VALUE if no foreground color is set.
1058 *
1059 * Output type: GhosttyColorRgb *
1060 */
1061 GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND = 18,
1062
1063 /**
1064 * The effective background color (override or default).
1065 *
1066 * Returns GHOSTTY_NO_VALUE if no background color is set.
1067 *
1068 * Output type: GhosttyColorRgb *
1069 */
1070 GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND = 19,
1071
1072 /**
1073 * The effective cursor color (override or default).
1074 *
1075 * Returns GHOSTTY_NO_VALUE if no cursor color is set.
1076 *
1077 * Output type: GhosttyColorRgb *
1078 */
1079 GHOSTTY_TERMINAL_DATA_COLOR_CURSOR = 20,
1080
1081 /**
1082 * The current 256-color palette.
1083 *
1084 * Output type: GhosttyColorRgb[256] *
1085 */
1086 GHOSTTY_TERMINAL_DATA_COLOR_PALETTE = 21,
1087
1088 /**
1089 * The default foreground color (ignoring any OSC override).
1090 *
1091 * Returns GHOSTTY_NO_VALUE if no default foreground color is set.
1092 *
1093 * Output type: GhosttyColorRgb *
1094 */
1095 GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND_DEFAULT = 22,
1096
1097 /**
1098 * The default background color (ignoring any OSC override).
1099 *
1100 * Returns GHOSTTY_NO_VALUE if no default background color is set.
1101 *
1102 * Output type: GhosttyColorRgb *
1103 */
1104 GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND_DEFAULT = 23,
1105
1106 /**
1107 * The default cursor color (ignoring any OSC override).
1108 *
1109 * Returns GHOSTTY_NO_VALUE if no default cursor color is set.
1110 *
1111 * Output type: GhosttyColorRgb *
1112 */
1113 GHOSTTY_TERMINAL_DATA_COLOR_CURSOR_DEFAULT = 24,
1114
1115 /**
1116 * The default 256-color palette (ignoring any OSC overrides).
1117 *
1118 * Output type: GhosttyColorRgb[256] *
1119 */
1120 GHOSTTY_TERMINAL_DATA_COLOR_PALETTE_DEFAULT = 25,
1121
1122 /**
1123 * The Kitty image storage limit in bytes for the active screen.
1124 *
1125 * A value of zero means the Kitty graphics protocol is disabled.
1126 * Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.
1127 *
1128 * Output type: uint64_t *
1129 */
1130 GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_STORAGE_LIMIT = 26,
1131
1132 /**
1133 * Whether the file medium is enabled for Kitty image loading on the
1134 * active screen.
1135 *
1136 * Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.
1137 *
1138 * Output type: bool *
1139 */
1140 GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_FILE = 27,
1141
1142 /**
1143 * The directory allowed for Kitty image loading via the temporary file
1144 * medium on the active screen. The string is empty when the medium is
1145 * disabled.
1146 *
1147 * Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.
1148 *
1149 * Output type: GhosttyString *
1150 */
1151 GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_TEMP_FILE = 28,
1152
1153 /**
1154 * Whether the shared memory medium is enabled for Kitty image loading
1155 * on the active screen.
1156 *
1157 * Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.
1158 *
1159 * Output type: bool *
1160 */
1161 GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_SHARED_MEM = 29,
1162
1163 /**
1164 * The Kitty graphics image storage for the active screen.
1165 *
1166 * Returns a borrowed pointer to the image storage. The pointer is valid
1167 * until the next mutating terminal call (e.g. ghostty_terminal_vt_write()
1168 * or ghostty_terminal_reset()).
1169 *
1170 * Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.
1171 *
1172 * Output type: GhosttyKittyGraphics *
1173 */
1174 GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS = 30,
1175
1176 /**
1177 * The active screen's current selection.
1178 *
1179 * On success, writes an untracked snapshot of the terminal-owned selection
1180 * to the caller-provided GhosttySelection. The GhosttySelection struct is
1181 * caller-owned and may be kept, but the grid references inside it are
1182 * untracked borrowed references into the active screen. They are only valid
1183 * until the next mutating terminal call, such as ghostty_terminal_set(),
1184 * ghostty_terminal_vt_write(), ghostty_terminal_resize(), or
1185 * ghostty_terminal_reset().
1186 *
1187 * Returns GHOSTTY_NO_VALUE when there is no active selection.
1188 *
1189 * Output type: GhosttySelection *
1190 */
1191 GHOSTTY_TERMINAL_DATA_SELECTION = 31,
1192
1193 /**
1194 * Whether the viewport is currently pinned to the active area.
1195 *
1196 * This is true when the viewport is following the active terminal area,
1197 * and false when the user has scrolled into history.
1198 *
1199 * Output type: bool *
1200 */
1201 GHOSTTY_TERMINAL_DATA_VIEWPORT_ACTIVE = 32,
1202
1203 /**
1204 * Whether VT processing encountered a non-gracefully handled error that may
1205 * have prevented a terminal-owned semantic update.
1206 *
1207 * Processing remains best-effort, and ghostty_terminal_reset() does not
1208 * clear it. Gracefully handled protocol failures, configured limits,
1209 * malformed or unsupported input, and failures limited to external effects
1210 * or query responses do not set it.
1211 *
1212 * This can't currently be unset. This is purely informational to consumers
1213 * if there was some error that happened at some point during VT processing.
1214 *
1215 * Output type: bool *
1216 */
1217 GHOSTTY_TERMINAL_DATA_VT_PROCESSING_ERROR = 33,
1218 GHOSTTY_TERMINAL_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
1219} GhosttyTerminalData;
1220
1221/**
1222 * Create a new terminal instance.
1223 *
1224 * @param allocator Pointer to allocator, or NULL to use the default allocator
1225 * @param terminal Pointer to store the created terminal handle
1226 * @param options Terminal initialization options
1227 * @return GHOSTTY_SUCCESS on success, or an error code on failure
1228 *
1229 * @ingroup terminal
1230 */
1231GHOSTTY_API GhosttyResult ghostty_terminal_new(const GhosttyAllocator* allocator,
1232 GhosttyTerminal* terminal,
1233 GhosttyTerminalOptions options);
1234
1235/**
1236 * Free a terminal instance.
1237 *
1238 * Releases all resources associated with the terminal. After this call,
1239 * the terminal handle becomes invalid and must not be used.
1240 *
1241 * @param terminal The terminal handle to free (may be NULL)
1242 *
1243 * @ingroup terminal
1244 */
1245GHOSTTY_API void ghostty_terminal_free(GhosttyTerminal terminal);
1246
1247/**
1248 * Perform a full reset of the terminal (RIS).
1249 *
1250 * Resets all terminal state back to its initial configuration, including
1251 * modes, scrollback, scrolling region, and screen contents. The terminal
1252 * dimensions are preserved.
1253 *
1254 * @param terminal The terminal handle (may be NULL, in which case this is a no-op)
1255 *
1256 * @ingroup terminal
1257 */
1258GHOSTTY_API void ghostty_terminal_reset(GhosttyTerminal terminal);
1259
1260/**
1261 * Resize the terminal to the given dimensions.
1262 *
1263 * Changes the number of columns and rows in the terminal. The primary
1264 * screen will reflow content if wraparound mode is enabled; the alternate
1265 * screen does not reflow. If the dimensions are unchanged, this is a no-op.
1266 *
1267 * This also updates the terminal's pixel dimensions (used for image
1268 * protocols and size reports), disables synchronized output mode (allowed
1269 * by the spec so that resize results are shown immediately), and sends an
1270 * in-band size report if mode 2048 is enabled.
1271 *
1272 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1273 * @param cols New width in cells (must be greater than zero)
1274 * @param rows New height in cells (must be greater than zero)
1275 * @param cell_width_px Width of a single cell in pixels
1276 * @param cell_height_px Height of a single cell in pixels
1277 * @return GHOSTTY_SUCCESS on success, or an error code on failure
1278 *
1279 * @ingroup terminal
1280 */
1281GHOSTTY_API GhosttyResult ghostty_terminal_resize(GhosttyTerminal terminal,
1282 uint16_t cols,
1283 uint16_t rows,
1284 uint32_t cell_width_px,
1285 uint32_t cell_height_px);
1286
1287/**
1288 * Set an option on the terminal.
1289 *
1290 * Configures terminal callbacks and associated state such as the
1291 * write_pty callback and userdata pointer. The value is passed
1292 * directly for pointer types (callbacks, userdata) or as a pointer
1293 * to the value for non-pointer types (e.g. GhosttyString*).
1294 * NULL clears the option to its default.
1295 *
1296 * Callbacks are invoked synchronously during ghostty_terminal_vt_write().
1297 * Callbacks must not call ghostty_terminal_vt_write() on the same
1298 * terminal (no reentrancy).
1299 *
1300 * @param terminal The terminal handle (may be NULL, in which case this is a no-op)
1301 * @param option The option to set
1302 * @param value Pointer to the value to set (type depends on the option),
1303 * or NULL to clear the option
1304 *
1305 * @ingroup terminal
1306 */
1307GHOSTTY_API GhosttyResult ghostty_terminal_set(GhosttyTerminal terminal,
1308 GhosttyTerminalOption option,
1309 const void* value);
1310
1311/**
1312 * Write VT-encoded data to the terminal for processing.
1313 *
1314 * Feeds raw bytes through the terminal's VT stream parser, updating
1315 * terminal state accordingly. By default, sequences that require output
1316 * (queries, device status reports) are silently ignored. Use
1317 * ghostty_terminal_set() with GHOSTTY_TERMINAL_OPT_WRITE_PTY to install
1318 * a callback that receives response data.
1319 *
1320 * This never fails. Any erroneous input or errors in processing the
1321 * input are logged internally but do not cause this function to fail
1322 * because this input is assumed to be untrusted and from an external
1323 * source; so the primary goal is to keep the terminal state consistent and
1324 * not allow malformed input to corrupt or crash.
1325 *
1326 * @param terminal The terminal handle
1327 * @param data Pointer to the data to write
1328 * @param len Length of the data in bytes
1329 *
1330 * @ingroup terminal
1331 */
1332GHOSTTY_API void ghostty_terminal_vt_write(GhosttyTerminal terminal,
1333 const uint8_t* data,
1334 size_t len);
1335
1336/**
1337 * Scroll the terminal viewport.
1338 *
1339 * Scrolls the terminal's viewport according to the given behavior.
1340 * When using GHOSTTY_SCROLL_VIEWPORT_DELTA, set the delta field in
1341 * the value union to specify the number of rows to scroll (negative
1342 * for up, positive for down). When using GHOSTTY_SCROLL_VIEWPORT_ROW,
1343 * set the row field to the absolute row offset from the top of the
1344 * scrollable area (the same row space as the offset field of
1345 * GhosttyTerminalScrollbar). For other behaviors, the value is ignored.
1346 *
1347 * @param terminal The terminal handle (may be NULL, in which case this is a no-op)
1348 * @param behavior The scroll behavior as a tagged union
1349 *
1350 * @ingroup terminal
1351 */
1352GHOSTTY_API void ghostty_terminal_scroll_viewport(GhosttyTerminal terminal,
1353 GhosttyTerminalScrollViewport behavior);
1354
1355/**
1356 * Return the current compression activity token.
1357 *
1358 * The token is opaque and only equality comparisons are meaningful. An
1359 * embedding application should cache it and restart its compression idle
1360 * delay whenever the value changes. The value may wrap and changes in either
1361 * direction have the same meaning.
1362 *
1363 * This function only observes terminal state. It does not perform or schedule
1364 * compression.
1365 *
1366 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1367 * @param[out] out_activity Receives the current activity token
1368 * @return GHOSTTY_SUCCESS on success, or GHOSTTY_INVALID_VALUE if an argument
1369 * is NULL
1370 *
1371 * @ingroup terminal
1372 */
1373GHOSTTY_API GhosttyResult ghostty_terminal_compression_activity(
1374 GhosttyTerminal terminal,
1375 uint64_t* out_activity);
1376
1377/**
1378 * Compress eligible terminal scrollback.
1379 *
1380 * Incremental mode performs bounded work suitable for an idle callback. A
1381 * pending result means the application should invoke another step while the
1382 * terminal remains idle. A complete result means no continuation is needed
1383 * until ghostty_terminal_compression_activity() changes. Full mode performs
1384 * one synchronous scan and can stall on large scrollback buffers.
1385 *
1386 * Compression is opportunistic. Complete means the pass has finished, not
1387 * that every page was compressed: pages may be unprofitable or encounter an
1388 * allocation or reclamation failure. Compression changes only the terminal's
1389 * storage representation and never its logical contents or scrollback limit.
1390 * Accessing compressed history restores it transparently.
1391 *
1392 * This function is not thread-safe with other operations on the same
1393 * terminal. The caller must serialize it with writes, rendering, searches,
1394 * and other terminal access.
1395 *
1396 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1397 * @param mode The amount of compression work to perform
1398 * @param[out] out_result Receives the compression scheduling result
1399 * @return GHOSTTY_SUCCESS on success, or GHOSTTY_INVALID_VALUE if an argument
1400 * or mode is invalid
1401 *
1402 * @ingroup terminal
1403 */
1404GHOSTTY_API GhosttyResult ghostty_terminal_compress(
1405 GhosttyTerminal terminal,
1406 GhosttyTerminalCompressionMode mode,
1407 GhosttyTerminalCompressionResult* out_result);
1408
1409/**
1410 * Get the current value of a terminal mode.
1411 *
1412 * Returns the value of the mode identified by the given mode.
1413 *
1414 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1415 * @param mode The mode identifying the mode to query
1416 * @param[out] out_value On success, set to true if the mode is set, false
1417 * if it is reset
1418 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal
1419 * is NULL or the mode does not correspond to a known mode
1420 *
1421 * @ingroup terminal
1422 */
1423GHOSTTY_API GhosttyResult ghostty_terminal_mode_get(GhosttyTerminal terminal,
1424 GhosttyMode mode,
1425 bool* out_value);
1426
1427/**
1428 * Set the value of a terminal mode.
1429 *
1430 * Sets the mode identified by the given mode to the specified value.
1431 *
1432 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1433 * @param mode The mode identifying the mode to set
1434 * @param value true to set the mode, false to reset it
1435 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal
1436 * is NULL or the mode does not correspond to a known mode
1437 *
1438 * @ingroup terminal
1439 */
1440GHOSTTY_API GhosttyResult ghostty_terminal_mode_set(GhosttyTerminal terminal,
1441 GhosttyMode mode,
1442 bool value);
1443
1444/**
1445 * Get data from a terminal instance.
1446 *
1447 * Extracts typed data from the given terminal based on the specified
1448 * data type. The output pointer must be of the appropriate type for the
1449 * requested data kind. Valid data types and output types are documented
1450 * in the `GhosttyTerminalData` enum.
1451 *
1452 * @param terminal The terminal handle (may be NULL)
1453 * @param data The type of data to extract
1454 * @param out Pointer to store the extracted data (type depends on data parameter)
1455 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal
1456 * is NULL or the data type is invalid
1457 *
1458 * @ingroup terminal
1459 */
1460GHOSTTY_API GhosttyResult ghostty_terminal_get(GhosttyTerminal terminal,
1461 GhosttyTerminalData data,
1462 void *out);
1463
1464/**
1465 * Get multiple data fields from a terminal in a single call.
1466 *
1467 * This is an optimization over calling ghostty_terminal_get()
1468 * repeatedly, particularly useful in environments with high per-call
1469 * overhead such as FFI or Cgo.
1470 *
1471 * Each element in the keys array specifies a data kind, and the
1472 * corresponding element in the values array receives the result.
1473 * The type of each values[i] pointer must match the output type
1474 * documented for keys[i].
1475 *
1476 * Processing stops at the first error; on success out_written
1477 * is set to count, on error it is set to the index of the
1478 * failing key (i.e. the number of values successfully written).
1479 *
1480 * @param terminal The terminal handle (may be NULL)
1481 * @param count Number of key/value pairs
1482 * @param keys Array of data kinds to query
1483 * @param values Array of output pointers (types must match each key's
1484 * documented output type)
1485 * @param[out] out_written On return, receives the number of values
1486 * successfully written (may be NULL)
1487 * @return GHOSTTY_SUCCESS if all queries succeed
1488 *
1489 * @ingroup terminal
1490 */
1491GHOSTTY_API GhosttyResult ghostty_terminal_get_multi(GhosttyTerminal terminal,
1492 size_t count,
1493 const GhosttyTerminalData* keys,
1494 void** values,
1495 size_t* out_written);
1496
1497/**
1498 * Resolve a point in the terminal grid to a grid reference.
1499 *
1500 * Resolves the given point (which can be in active, viewport, screen,
1501 * or history coordinates) to a grid reference for that location. Use
1502 * ghostty_grid_ref_cell() and ghostty_grid_ref_row() to extract the cell
1503 * and row.
1504 *
1505 * Lookups using the `active` and `viewport` tags are fast. The `screen`
1506 * and `history` tags may require traversing the full scrollback page list
1507 * to resolve the y coordinate, so they can be expensive for large
1508 * scrollback buffers.
1509 *
1510 * This function isn't meant to be used as the core of render loop. It
1511 * isn't built to sustain the framerates needed for rendering large screens.
1512 * Use the render state API for that. This API is instead meant for less
1513 * strictly performance-sensitive use cases.
1514 *
1515 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1516 * @param point The point specifying which cell to look up
1517 * @param[out] out_ref On success, set to the grid reference at the given point (may be NULL)
1518 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal
1519 * is NULL or the point is out of bounds
1520 *
1521 * @ingroup terminal
1522 */
1523GHOSTTY_API GhosttyResult ghostty_terminal_grid_ref(GhosttyTerminal terminal,
1524 GhosttyPoint point,
1525 GhosttyGridRef *out_ref);
1526
1527/**
1528 * Create an owned tracked grid reference for a terminal point.
1529 *
1530 * This is the tracked variant of ghostty_terminal_grid_ref(). The returned
1531 * handle follows the referenced cell as the terminal's page list is modified:
1532 * scrolling, pruning, resize/reflow, and other page-list operations update the
1533 * tracked reference automatically.
1534 *
1535 * The reference is attached to the terminal screen/page-list that is active at
1536 * creation time.
1537 *
1538 * If the point is outside the requested coordinate space, this returns
1539 * GHOSTTY_INVALID_VALUE and writes NULL to out_ref.
1540 *
1541 * The returned handle must be freed with ghostty_tracked_grid_ref_free(). If
1542 * the terminal is freed first, the handle remains valid only for
1543 * tracked-grid-ref APIs: it reports no value and can still be freed.
1544 *
1545 * @param terminal Terminal instance.
1546 * @param point Point to track.
1547 * @param[out] out_ref On success, receives the tracked reference handle.
1548 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if terminal,
1549 * point, or out_ref is invalid, or GHOSTTY_OUT_OF_MEMORY if allocation
1550 * fails.
1551 *
1552 * @ingroup terminal
1553 */
1554GHOSTTY_API GhosttyResult ghostty_terminal_grid_ref_track(
1555 GhosttyTerminal terminal,
1556 GhosttyPoint point,
1557 GhosttyTrackedGridRef *out_ref);
1558
1559/**
1560 * Convert a grid reference back to a point in the given coordinate system.
1561 *
1562 * This is the inverse of ghostty_terminal_grid_ref(): given a grid reference,
1563 * it returns the x/y coordinates in the requested coordinate system (active,
1564 * viewport, screen, or history).
1565 *
1566 * The grid reference must have been obtained from the same terminal instance.
1567 * Like all grid references, it is only valid until the next mutating terminal
1568 * call.
1569 *
1570 * Not every grid reference is representable in every coordinate system. For
1571 * example, a cell in scrollback history cannot be expressed in active
1572 * coordinates, and a cell that has scrolled off the visible area cannot be
1573 * expressed in viewport coordinates. In these cases, the function returns
1574 * GHOSTTY_NO_VALUE.
1575 *
1576 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1577 * @param ref Pointer to the grid reference to convert
1578 * @param tag The target coordinate system
1579 * @param[out] out On success, set to the coordinate in the requested system (may be NULL)
1580 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal
1581 * or ref is NULL/invalid, GHOSTTY_NO_VALUE if the ref falls outside
1582 * the requested coordinate system
1583 *
1584 * @ingroup terminal
1585 */
1586GHOSTTY_API GhosttyResult ghostty_terminal_point_from_grid_ref(
1587 GhosttyTerminal terminal,
1588 const GhosttyGridRef *ref,
1589 GhosttyPointTag tag,
1590 GhosttyPointCoordinate *out);
1591
1592/** @} */
1593
1594#ifdef __cplusplus
1595}
1596#endif
1597
1598#endif /* GHOSTTY_VT_TERMINAL_H */