The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 14:45 UTC
fix(terminal): answer OSC color queries so CLIs pick light colors (#36777)
Julius Marminge committed
Nov 14, 2026 at 06:34 UTC
3908c4eab3ac33eb990e3b961738fbbb3951e0ff
17 files changed
+842
-37
apps/mobile/modules/t3-terminal/THIRD_PARTY_NOTICES.md
+1
-1
@@ -21,7 +21,7 @@ The Android terminal renderer vendors upstream `libghostty-vt` shared libraries
21
The web terminal vendors a WebAssembly build from the same revision and uses the same C ABI.
22
23
- Upstream project: https://github.com/ghostty-org/ghostty
24
-- Vendored revision: `9f62873bf195e4d8a762d768a1405a5f2f7b1697`
24
+- Vendored revision: `3ff6d08fad56f2d6b81420a27bdc56ee707b453e`
25
- License: MIT
26
27
Ghostty's MIT license applies to the vendored Android and web libraries. Keep this notice and both
apps/mobile/modules/t3-terminal/android/src/main/jniLibs/arm64-v8a/libghostty-vt.so
Binary files a/apps/mobile/modules/t3-terminal/android/src/main/jniLibs/arm64-v8a/libghostty-vt.so and b/apps/mobile/modules/t3-terminal/android/src/main/jniLibs/arm64-v8a/libghostty-vt.so differ
apps/mobile/modules/t3-terminal/android/src/main/jniLibs/armeabi-v7a/libghostty-vt.so
Binary files a/apps/mobile/modules/t3-terminal/android/src/main/jniLibs/armeabi-v7a/libghostty-vt.so and b/apps/mobile/modules/t3-terminal/android/src/main/jniLibs/armeabi-v7a/libghostty-vt.so differ
apps/mobile/modules/t3-terminal/android/src/main/jniLibs/x86/libghostty-vt.so
Binary files a/apps/mobile/modules/t3-terminal/android/src/main/jniLibs/x86/libghostty-vt.so and b/apps/mobile/modules/t3-terminal/android/src/main/jniLibs/x86/libghostty-vt.so differ
apps/mobile/modules/t3-terminal/android/src/main/jniLibs/x86_64/libghostty-vt.so
Binary files a/apps/mobile/modules/t3-terminal/android/src/main/jniLibs/x86_64/libghostty-vt.so and b/apps/mobile/modules/t3-terminal/android/src/main/jniLibs/x86_64/libghostty-vt.so differ
apps/mobile/modules/t3-terminal/scripts/build-libghostty-android.sh
+1
-1
@@ -7,7 +7,7 @@ MODULE_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
7
VENDOR_DIR="${MODULE_DIR}/../../../../native/libghostty-vt"
8
PATCH_DIR="${SCRIPT_DIR}/libghostty-android-patches"
9
10
-GHOSTTY_REVISION="${GHOSTTY_REVISION:-9f62873bf195e4d8a762d768a1405a5f2f7b1697}"
10
+GHOSTTY_REVISION="${GHOSTTY_REVISION:-3ff6d08fad56f2d6b81420a27bdc56ee707b453e}"
11
GHOSTTY_SOURCE_DIR="${GHOSTTY_SOURCE_DIR:-${HOME}/.cache/t3code/ghostty-${GHOSTTY_REVISION:0:8}}"
12
GHOSTTY_ZIG_VERSION="${GHOSTTY_ZIG_VERSION:-0.15.2}"
13
GHOSTTY_ZIG="${GHOSTTY_ZIG:-}"
apps/web/src/terminal/ghostty/core.test.ts
+12
@@ -296,6 +296,18 @@ describe("GhosttyTerminalCore snapshots", () => {
296
expect(core.snapshot()).toEqual(reference.snapshot());
297
});
298
299
+ it("answers an OSC 11 background query with the theme background", async () => {
300
+ const replies: string[] = [];
301
+ const core = await createCore((data) => replies.push(data));
302
+ core.setTheme({
303
+ foreground: { r: 0, g: 0, b: 0 },
304
+ background: { r: 255, g: 255, b: 255 },
305
+ cursor: { r: 0, g: 0, b: 0 },
306
+ });
307
+ core.write("\x1b]11;?\x1b\\");
308
+ expect(replies.join("")).toMatch(/^\x1b\]11;rgb:ffff\/ffff\/ffff(\x07|\x1b\\)$/);
309
+ });
310
+
311
it("answers a live VT query when batched reads cross a chunk compaction", async () => {
312
const replies: string[] = [];
313
const core = await createCore((data) => replies.push(data));
apps/web/src/terminal/ghostty/vendor/ghostty-vt.wasm
Binary files a/apps/web/src/terminal/ghostty/vendor/ghostty-vt.wasm and b/apps/web/src/terminal/ghostty/vendor/ghostty-vt.wasm differ
native/libghostty-vt/VERSION
+1
-1
@@ -1 +1 @@
1
-9f62873bf195e4d8a762d768a1405a5f2f7b1697
1
+3ff6d08fad56f2d6b81420a27bdc56ee707b453e
native/libghostty-vt/include/ghostty/vt.h
+3
@@ -34,6 +34,7 @@
34
* - @ref osc "OSC Parser" - Parse OSC (Operating System Command) sequences
35
* - @ref sgr "SGR Parser" - Parse SGR (Select Graphic Rendition) sequences
36
* - @ref paste "Paste Utilities" - Validate paste data safety
37
+ * - @ref unicode "Unicode Utilities" - Codepoint properties for text layout
38
* - @ref build_info "Build Info" - Query compile-time build configuration
39
* - @ref allocator "Memory Management" - Memory management and custom allocators
40
* - @ref wasm "WebAssembly Utilities" - WebAssembly convenience functions
@@ -125,6 +126,7 @@ extern "C" {
126
#include <ghostty/vt/allocator.h>
127
#include <ghostty/vt/build_info.h>
128
#include <ghostty/vt/color.h>
129
+#include <ghostty/vt/color_scheme.h>
130
#include <ghostty/vt/device.h>
131
#include <ghostty/vt/focus.h>
132
#include <ghostty/vt/formatter.h>
@@ -145,6 +147,7 @@ extern "C" {
147
#include <ghostty/vt/screen.h>
148
#include <ghostty/vt/selection.h>
149
#include <ghostty/vt/size_report.h>
150
+#include <ghostty/vt/unicode.h>
151
#include <ghostty/vt/wasm.h>
152
153
#ifdef __cplusplus
native/libghostty-vt/include/ghostty/vt/color.h
+407
-25
@@ -7,6 +7,114 @@
7
#ifndef GHOSTTY_VT_COLOR_H
8
#define GHOSTTY_VT_COLOR_H
9
10
+/** @defgroup color Color Utilities
11
+ *
12
+ * Color parsing, palette generation, color math, and X11 color name
13
+ * utilities shared by libghostty-vt.
14
+ *
15
+ * These APIs expose Ghostty's color semantics directly to embedders. Use
16
+ * them when an application needs to parse the same color strings as Ghostty
17
+ * config and theme files, generate the same 256-color palette used by the
18
+ * terminal, list supported X11 color names, or make UI decisions from
19
+ * luminance and contrast values.
20
+ *
21
+ * ## Parsing Colors
22
+ *
23
+ * ghostty_color_parse() accepts the flexible syntax used by Ghostty for
24
+ * terminal colors:
25
+ *
26
+ * - X11 color names, matched ASCII case-insensitively.
27
+ * - 3- or 6-digit hex colors, with or without a leading `#`.
28
+ * - 9- or 12-digit hex colors, with a leading `#`.
29
+ * - XParseColor-style `rgb:<red>/<green>/<blue>` values.
30
+ * - XParseColor-style `rgbi:<red>/<green>/<blue>` values.
31
+ *
32
+ * Leading and trailing spaces and tabs are ignored. Use
33
+ * ghostty_color_parse_x11() when only X11 names should be accepted.
34
+ *
35
+ * @code{.c}
36
+ * GhosttyColorRgb color;
37
+ *
38
+ * if (ghostty_color_parse(
39
+ * "ForestGreen",
40
+ * sizeof("ForestGreen") - 1,
41
+ * &color) != GHOSTTY_SUCCESS) {
42
+ * // Handle invalid color input.
43
+ * }
44
+ *
45
+ * ghostty_color_parse("#abc", sizeof("#abc") - 1, &color);
46
+ * ghostty_color_parse("rgb:12/34/56", sizeof("rgb:12/34/56") - 1, &color);
47
+ * @endcode
48
+ *
49
+ * ## Palette Entries
50
+ *
51
+ * ghostty_color_parse_palette_entry() parses a single Ghostty palette
52
+ * override in `INDEX=COLOR` form. The index may be decimal or use a `0x`,
53
+ * `0o`, or `0b` prefix. The color side uses ghostty_color_parse().
54
+ *
55
+ * @code{.c}
56
+ * GhosttyColorRgb palette[256];
57
+ * ghostty_color_palette_default(palette);
58
+ *
59
+ * uint8_t index;
60
+ * GhosttyColorRgb rgb;
61
+ *
62
+ * if (ghostty_color_parse_palette_entry(
63
+ * "0x10=#282c34",
64
+ * sizeof("0x10=#282c34") - 1,
65
+ * &index,
66
+ * &rgb) == GHOSTTY_SUCCESS) {
67
+ * palette[index] = rgb;
68
+ * }
69
+ * @endcode
70
+ *
71
+ * ## Palette Generation
72
+ *
73
+ * ghostty_color_palette_generate() derives the 216-color cube and grayscale
74
+ * ramp from a base palette, background, and foreground. Set bits in
75
+ * GhosttyColorPaletteMask preserve specific indices from the base palette.
76
+ * The output may alias the base input.
77
+ *
78
+ * @code{.c}
79
+ * GhosttyColorRgb palette[256];
80
+ * ghostty_color_palette_default(palette);
81
+ *
82
+ * GhosttyColorPaletteMask skip = {0};
83
+ * GHOSTTY_COLOR_PALETTE_MASK_SET(&skip, 16);
84
+ *
85
+ * GhosttyColorRgb background = {40, 44, 52};
86
+ * GhosttyColorRgb foreground = {220, 223, 228};
87
+ *
88
+ * ghostty_color_palette_generate(
89
+ * palette,
90
+ * &skip,
91
+ * &background,
92
+ * &foreground,
93
+ * true,
94
+ * palette);
95
+ * @endcode
96
+ *
97
+ * ## X11 Color Names
98
+ *
99
+ * The X11 name table is static program-lifetime memory. Entries are in
100
+ * rgb.txt order and are terminated by an entry with `name == NULL`.
101
+ * ghostty_color_x11_name_count() returns the number of non-terminator
102
+ * entries.
103
+ *
104
+ * @code{.c}
105
+ * const GhosttyColorX11Entry* names = ghostty_color_x11_names();
106
+ * size_t count = ghostty_color_x11_name_count();
107
+ *
108
+ * for (size_t i = 0; i < count; i++) {
109
+ * // names[i].name and names[i].color are valid here.
110
+ * }
111
+ * @endcode
112
+ *
113
+ * @{
114
+ */
115
+
116
+#include <stdbool.h>
117
+#include <stddef.h>
118
#include <stdint.h>
119
#include <ghostty/vt/types.h>
120
@@ -17,7 +125,7 @@ extern "C" {
125
/**
126
* RGB color value.
127
*
20
- * @ingroup sgr
128
+ * @ingroup color
129
*/
130
typedef struct {
131
uint8_t r; /**< Red component (0-255) */
@@ -28,49 +136,128 @@ typedef struct {
136
/**
137
* Palette color index (0-255).
138
*
31
- * @ingroup sgr
139
+ * @ingroup color
140
*/
141
typedef uint8_t GhosttyColorPaletteIndex;
142
35
-/** @addtogroup sgr
36
- * @{
143
+/**
144
+ * A 256-bit mask of palette indices.
145
+ *
146
+ * Index i is set iff `(bits[i >> 6] >> (i & 63)) & 1` is 1.
147
+ * The mask is typically initialized to zero and then populated with
148
+ * GHOSTTY_COLOR_PALETTE_MASK_SET().
149
+ *
150
+ * @code{.c}
151
+ * GhosttyColorPaletteMask mask = {0};
152
+ * GHOSTTY_COLOR_PALETTE_MASK_SET(&mask, 20);
153
+ * if (GHOSTTY_COLOR_PALETTE_MASK_IS_SET(&mask, 20)) {
154
+ * // Index 20 will be preserved.
155
+ * }
156
+ * @endcode
157
+ *
158
+ * @ingroup color
159
*/
160
+typedef struct {
161
+ uint64_t bits[4];
162
+} GhosttyColorPaletteMask;
163
+
164
+/**
165
+ * An entry in Ghostty's X11 color name table.
166
+ *
167
+ * @ingroup color
168
+ */
169
+typedef struct {
170
+ /** Null-terminated color name. NULL marks the end of the table. */
171
+ const char* name;
172
+ /** The RGB value of the color. */
173
+ GhosttyColorRgb color;
174
+} GhosttyColorX11Entry;
175
+
176
+/**
177
+ * Return the storage word for a palette mask index.
178
+ *
179
+ * @param index The palette index (0-255)
180
+ *
181
+ * @ingroup color
182
+ */
183
+#define GHOSTTY_COLOR_PALETTE_MASK_WORD(index) ((index) >> 6)
184
+
185
+/**
186
+ * Return the storage bit for a palette mask index.
187
+ *
188
+ * @param index The palette index (0-255)
189
+ *
190
+ * @ingroup color
191
+ */
192
+#define GHOSTTY_COLOR_PALETTE_MASK_BIT(index) (UINT64_C(1) << ((index) & 63))
193
39
-/** Black color (0) @ingroup sgr */
194
+/**
195
+ * Set a palette mask index.
196
+ *
197
+ * @param mask Pointer to a GhosttyColorPaletteMask
198
+ * @param index The palette index (0-255)
199
+ *
200
+ * @ingroup color
201
+ */
202
+#define GHOSTTY_COLOR_PALETTE_MASK_SET(mask, index) \
203
+ ((mask)->bits[GHOSTTY_COLOR_PALETTE_MASK_WORD(index)] |= GHOSTTY_COLOR_PALETTE_MASK_BIT(index))
204
+
205
+/**
206
+ * Clear a palette mask index.
207
+ *
208
+ * @param mask Pointer to a GhosttyColorPaletteMask
209
+ * @param index The palette index (0-255)
210
+ *
211
+ * @ingroup color
212
+ */
213
+#define GHOSTTY_COLOR_PALETTE_MASK_UNSET(mask, index) \
214
+ ((mask)->bits[GHOSTTY_COLOR_PALETTE_MASK_WORD(index)] &= ~GHOSTTY_COLOR_PALETTE_MASK_BIT(index))
215
+
216
+/**
217
+ * Test whether a palette mask index is set.
218
+ *
219
+ * @param mask Pointer to a GhosttyColorPaletteMask
220
+ * @param index The palette index (0-255)
221
+ * @return true if the palette index is set, false otherwise
222
+ *
223
+ * @ingroup color
224
+ */
225
+#define GHOSTTY_COLOR_PALETTE_MASK_IS_SET(mask, index) \
226
+ (((mask)->bits[GHOSTTY_COLOR_PALETTE_MASK_WORD(index)] & GHOSTTY_COLOR_PALETTE_MASK_BIT(index)) != 0)
227
+
228
+/** Black color (0) @ingroup color */
229
#define GHOSTTY_COLOR_NAMED_BLACK 0
41
-/** Red color (1) @ingroup sgr */
230
+/** Red color (1) @ingroup color */
231
#define GHOSTTY_COLOR_NAMED_RED 1
43
-/** Green color (2) @ingroup sgr */
232
+/** Green color (2) @ingroup color */
233
#define GHOSTTY_COLOR_NAMED_GREEN 2
45
-/** Yellow color (3) @ingroup sgr */
234
+/** Yellow color (3) @ingroup color */
235
#define GHOSTTY_COLOR_NAMED_YELLOW 3
47
-/** Blue color (4) @ingroup sgr */
236
+/** Blue color (4) @ingroup color */
237
#define GHOSTTY_COLOR_NAMED_BLUE 4
49
-/** Magenta color (5) @ingroup sgr */
238
+/** Magenta color (5) @ingroup color */
239
#define GHOSTTY_COLOR_NAMED_MAGENTA 5
51
-/** Cyan color (6) @ingroup sgr */
240
+/** Cyan color (6) @ingroup color */
241
#define GHOSTTY_COLOR_NAMED_CYAN 6
53
-/** White color (7) @ingroup sgr */
242
+/** White color (7) @ingroup color */
243
#define GHOSTTY_COLOR_NAMED_WHITE 7
55
-/** Bright black color (8) @ingroup sgr */
244
+/** Bright black color (8) @ingroup color */
245
#define GHOSTTY_COLOR_NAMED_BRIGHT_BLACK 8
57
-/** Bright red color (9) @ingroup sgr */
246
+/** Bright red color (9) @ingroup color */
247
#define GHOSTTY_COLOR_NAMED_BRIGHT_RED 9
59
-/** Bright green color (10) @ingroup sgr */
248
+/** Bright green color (10) @ingroup color */
249
#define GHOSTTY_COLOR_NAMED_BRIGHT_GREEN 10
61
-/** Bright yellow color (11) @ingroup sgr */
250
+/** Bright yellow color (11) @ingroup color */
251
#define GHOSTTY_COLOR_NAMED_BRIGHT_YELLOW 11
63
-/** Bright blue color (12) @ingroup sgr */
252
+/** Bright blue color (12) @ingroup color */
253
#define GHOSTTY_COLOR_NAMED_BRIGHT_BLUE 12
65
-/** Bright magenta color (13) @ingroup sgr */
254
+/** Bright magenta color (13) @ingroup color */
255
#define GHOSTTY_COLOR_NAMED_BRIGHT_MAGENTA 13
67
-/** Bright cyan color (14) @ingroup sgr */
256
+/** Bright cyan color (14) @ingroup color */
257
#define GHOSTTY_COLOR_NAMED_BRIGHT_CYAN 14
69
-/** Bright white color (15) @ingroup sgr */
258
+/** Bright white color (15) @ingroup color */
259
#define GHOSTTY_COLOR_NAMED_BRIGHT_WHITE 15
260
72
-/** @} */
73
-
261
/**
262
* Get the RGB color components.
263
*
@@ -78,20 +265,215 @@ typedef uint8_t GhosttyColorPaletteIndex;
265
* from a GhosttyColorRgb value. Primarily useful in WebAssembly environments
266
* where accessing struct fields directly is difficult.
267
*
81
- * @param color The RGB color value
268
+ * @param color Pointer to the RGB color value
269
* @param r Pointer to store the red component (0-255)
270
* @param g Pointer to store the green component (0-255)
271
* @param b Pointer to store the blue component (0-255)
272
*
86
- * @ingroup sgr
273
+ * @ingroup color
274
*/
88
-GHOSTTY_API void ghostty_color_rgb_get(GhosttyColorRgb color,
275
+GHOSTTY_API void ghostty_color_rgb_get(const GhosttyColorRgb* color,
276
uint8_t* r,
277
uint8_t* g,
278
uint8_t* b);
279
280
+/**
281
+ * Parse an X11 color name.
282
+ *
283
+ * The color name is resolved from Ghostty's embedded rgb.txt table.
284
+ * Leading and trailing spaces and tabs are trimmed, and matching is
285
+ * ASCII case-insensitive. Hex values are not accepted by this function.
286
+ *
287
+ * @param name The color name bytes (must not be NULL)
288
+ * @param len The length of @p name in bytes
289
+ * @param[out] out The parsed RGB color
290
+ * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if no color
291
+ * matches or @p name is NULL
292
+ *
293
+ * @ingroup color
294
+ */
295
+GHOSTTY_API GhosttyResult ghostty_color_parse_x11(
296
+ const char* name,
297
+ size_t len,
298
+ GhosttyColorRgb* out);
299
+
300
+/**
301
+ * Parse a flexible Ghostty color value.
302
+ *
303
+ * Accepts Ghostty's terminal color syntax: X11 color names, hex colors
304
+ * in 3-, 6-, 9-, or 12-digit form (the leading # is optional for 3- and
305
+ * 6-digit values), and rgb:<red>/<green>/<blue> or
306
+ * rgbi:<red>/<green>/<blue> specifications. Leading and trailing spaces
307
+ * and tabs are trimmed.
308
+ *
309
+ * @param value The color value bytes (must not be NULL)
310
+ * @param len The length of @p value in bytes
311
+ * @param[out] out The parsed RGB color
312
+ * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if parsing
313
+ * fails or @p value is NULL
314
+ *
315
+ * @ingroup color
316
+ */
317
+GHOSTTY_API GhosttyResult ghostty_color_parse(
318
+ const char* value,
319
+ size_t len,
320
+ GhosttyColorRgb* out);
321
+
322
+/**
323
+ * Parse a Ghostty palette entry.
324
+ *
325
+ * Accepts Ghostty palette config syntax: N=COLOR. N is a palette index
326
+ * from 0 to 255 in decimal or in 0x, 0o, or 0b-prefixed form. Spaces and
327
+ * tabs around N and COLOR are ignored. COLOR accepts the same syntax as
328
+ * ghostty_color_parse().
329
+ *
330
+ * @param value The palette entry bytes (must not be NULL)
331
+ * @param len The length of @p value in bytes
332
+ * @param[out] out_index The parsed palette index
333
+ * @param[out] out_rgb The parsed RGB color
334
+ * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE on any
335
+ * failure, including index overflow
336
+ *
337
+ * @ingroup color
338
+ */
339
+GHOSTTY_API GhosttyResult ghostty_color_parse_palette_entry(
340
+ const char* value,
341
+ size_t len,
342
+ uint8_t* out_index,
343
+ GhosttyColorRgb* out_rgb);
344
+
345
+/**
346
+ * Get Ghostty's built-in default 256-color palette.
347
+ *
348
+ * Writes exactly 256 entries: Ghostty's base16 defaults, the xterm
349
+ * 6x6x6 color cube, and the grayscale ramp.
350
+ *
351
+ * @param[out] out The output palette, an array of exactly 256
352
+ * GhosttyColorRgb values
353
+ *
354
+ * @ingroup color
355
+ */
356
+GHOSTTY_API void ghostty_color_palette_default(GhosttyColorRgb* out);
357
+
358
+/**
359
+ * Generate a 256-color palette from base colors.
360
+ *
361
+ * The base palette supplies indices 0-15, which are always preserved.
362
+ * If @p base is NULL, Ghostty's default palette is used. If @p skip is
363
+ * NULL, no extra indices are skipped. Set bits in @p skip preserve those
364
+ * indices from @p base. The 216-color cube at indices 16-231 is generated
365
+ * with trilinear CIELAB interpolation, and the grayscale ramp at indices
366
+ * 232-255 is interpolated from the background to the foreground.
367
+ *
368
+ * For light themes, @p harmonious controls whether the generated palette
369
+ * keeps the background-to-foreground orientation. When false, Ghostty
370
+ * swaps the light background and dark foreground so the cube and ramp run
371
+ * dark-to-light. The output palette may be the same pointer as @p base.
372
+ *
373
+ * @param base The base palette, an array of exactly 256 GhosttyColorRgb
374
+ * values, or NULL to use Ghostty's default palette
375
+ * @param skip The palette indices to preserve from @p base, or NULL for
376
+ * an empty mask
377
+ * @param bg The terminal background color (must not be NULL)
378
+ * @param fg The terminal foreground color (must not be NULL)
379
+ * @param harmonious Whether light themes keep background-to-foreground
380
+ * orientation
381
+ * @param[out] out The output palette, an array of exactly 256
382
+ * GhosttyColorRgb values
383
+ *
384
+ * @ingroup color
385
+ */
386
+GHOSTTY_API void ghostty_color_palette_generate(
387
+ const GhosttyColorRgb* base,
388
+ const GhosttyColorPaletteMask* skip,
389
+ const GhosttyColorRgb* bg,
390
+ const GhosttyColorRgb* fg,
391
+ bool harmonious,
392
+ GhosttyColorRgb* out);
393
+
394
+/**
395
+ * Calculate W3C relative luminance for an RGB color.
396
+ *
397
+ * Returns a normalized value from 0.0 for black to 1.0 for white.
398
+ * See https://www.w3.org/TR/WCAG20/#relativeluminancedef.
399
+ *
400
+ * @param color The RGB color (must not be NULL)
401
+ * @return Relative luminance in the range 0.0 to 1.0
402
+ *
403
+ * @ingroup color
404
+ */
405
+GHOSTTY_API double ghostty_color_luminance(const GhosttyColorRgb* color);
406
+
407
+/**
408
+ * Calculate perceived luminance for an RGB color.
409
+ *
410
+ * Returns a normalized value from 0.0 for black to 1.0 for white.
411
+ * Ghostty treats a background color as light when this exceeds 0.5.
412
+ * This is not the metric used internally by
413
+ * ghostty_color_palette_generate(), which uses CIELAB lightness.
414
+ *
415
+ * @param color The RGB color (must not be NULL)
416
+ * @return Perceived luminance in the range 0.0 to 1.0
417
+ *
418
+ * @ingroup color
419
+ */
420
+GHOSTTY_API double ghostty_color_perceived_luminance(const GhosttyColorRgb* color);
421
+
422
+/**
423
+ * Calculate the WCAG contrast ratio between two RGB colors.
424
+ *
425
+ * The contrast ratio is symmetric and ranges from 1.0 for identical
426
+ * colors to 21.0 for black and white.
427
+ *
428
+ * @param a The first RGB color (must not be NULL)
429
+ * @param b The second RGB color (must not be NULL)
430
+ * @return WCAG contrast ratio in the range 1.0 to 21.0
431
+ *
432
+ * @ingroup color
433
+ */
434
+GHOSTTY_API double ghostty_color_contrast(const GhosttyColorRgb* a,
435
+ const GhosttyColorRgb* b);
436
+
437
+/**
438
+ * Get Ghostty's X11 color name table.
439
+ *
440
+ * The returned pointer references static memory valid for the program
441
+ * lifetime and is never NULL. Entries are in rgb.txt order and are
442
+ * terminated by an entry with name == NULL. Aliases are separate entries,
443
+ * such as "medium spring green" and "MediumSpringGreen". Names are the
444
+ * exact supported spellings from rgb.txt; ghostty_color_parse_x11() also
445
+ * matches them case-insensitively.
446
+ *
447
+ * @code{.c}
448
+ * for (const GhosttyColorX11Entry* e = ghostty_color_x11_names();
449
+ * e->name != NULL;
450
+ * e++) {
451
+ * // e->name and e->color are valid here.
452
+ * }
453
+ * @endcode
454
+ *
455
+ * @return Pointer to the first X11 color entry
456
+ *
457
+ * @ingroup color
458
+ */
459
+GHOSTTY_API const GhosttyColorX11Entry* ghostty_color_x11_names(void);
460
+
461
+/**
462
+ * Get the number of X11 color name entries.
463
+ *
464
+ * The returned count excludes the NULL terminator and is provided so
465
+ * bindings can preallocate storage before reading ghostty_color_x11_names().
466
+ *
467
+ * @return Number of X11 color name entries
468
+ *
469
+ * @ingroup color
470
+ */
471
+GHOSTTY_API size_t ghostty_color_x11_name_count(void);
472
+
473
#ifdef __cplusplus
474
}
475
#endif
476
477
+/** @} */
478
+
479
#endif /* GHOSTTY_VT_COLOR_H */
native/libghostty-vt/include/ghostty/vt/color_scheme.h
new
+73
@@ -0,0 +1,73 @@
1
+/**
2
+ * @file color_scheme.h
3
+ *
4
+ * Color scheme report encoding - encode terminal color scheme reports into
5
+ * escape sequences.
6
+ */
7
+
8
+#ifndef GHOSTTY_VT_COLOR_SCHEME_H
9
+#define GHOSTTY_VT_COLOR_SCHEME_H
10
+
11
+/** @defgroup color_scheme Color Scheme Report Encoding
12
+ *
13
+ * Utilities for encoding color scheme reports into terminal escape
14
+ * sequences for color scheme reporting mode (mode 2031).
15
+ *
16
+ * ## Basic Usage
17
+ *
18
+ * Use ghostty_color_scheme_report_encode() to encode a color scheme report
19
+ * into a caller-provided buffer. If the buffer is too small, the function
20
+ * returns GHOSTTY_OUT_OF_SPACE and sets the required size in the output
21
+ * parameter.
22
+ *
23
+ * ## Example
24
+ *
25
+ * @snippet c-vt-color-scheme/src/main.c color-scheme-report-encode
26
+ *
27
+ * @{
28
+ */
29
+
30
+#include <stddef.h>
31
+#include <ghostty/vt/types.h>
32
+#include <ghostty/vt/device.h>
33
+
34
+#ifdef __cplusplus
35
+extern "C" {
36
+#endif
37
+
38
+/**
39
+ * Encode a color scheme report into an escape sequence.
40
+ *
41
+ * Encodes a color scheme report into the provided buffer. Dark color schemes
42
+ * emit ESC [ ? 997 ; 1 n, and light color schemes emit ESC [ ? 997 ; 2 n.
43
+ * The encoded bytes are identical to the terminal's internal CSI ? 996 n
44
+ * query response.
45
+ *
46
+ * Hosts should gate unsolicited sends on GHOSTTY_MODE_COLOR_SCHEME_REPORT
47
+ * (mode 2031) being set, which can be checked via the mode getters.
48
+ *
49
+ * If the buffer is too small, the function returns GHOSTTY_OUT_OF_SPACE
50
+ * and writes the required buffer size to @p out_written. The caller can
51
+ * then retry with a sufficiently sized buffer.
52
+ *
53
+ * @param scheme The color scheme to encode
54
+ * @param buf Output buffer to write the encoded sequence into (may be NULL)
55
+ * @param buf_len Size of the output buffer in bytes
56
+ * @param[out] out_written On success, the number of bytes written. On
57
+ * GHOSTTY_OUT_OF_SPACE, the required buffer size.
58
+ * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_SPACE if the buffer
59
+ * is too small
60
+ */
61
+GHOSTTY_API GhosttyResult ghostty_color_scheme_report_encode(
62
+ GhosttyColorScheme scheme,
63
+ char* buf,
64
+ size_t buf_len,
65
+ size_t* out_written);
66
+
67
+#ifdef __cplusplus
68
+}
69
+#endif
70
+
71
+/** @} */
72
+
73
+#endif /* GHOSTTY_VT_COLOR_SCHEME_H */
native/libghostty-vt/include/ghostty/vt/kitty_graphics.h
+87
-3
@@ -84,6 +84,28 @@ extern "C" {
84
* - ghostty_kitty_graphics_placement_rect() — bounding rectangle as a
85
* @ref GhosttySelection.
86
*
87
+ * ## Change Detection
88
+ *
89
+ * Generation stamps allow renderers to cheaply detect whether Kitty
90
+ * graphics state changed between frames:
91
+ *
92
+ * - @ref GHOSTTY_KITTY_GRAPHICS_DATA_GENERATION is a storage-wide stamp
93
+ * updated on any transmit, placement, or delete. If unchanged, the
94
+ * placement set and all image data are identical and both placement
95
+ * snapshots and per-image staleness checks can be skipped. Placement
96
+ * geometry can still change independently (scrolling moves
97
+ * placements), so ghostty_kitty_graphics_placement_render_info()
98
+ * should still be recomputed on dirty frames.
99
+ * - @ref GHOSTTY_KITTY_IMAGE_DATA_GENERATION is a per-image stamp
100
+ * changed on every add/replace of that image ID. Texture caches
101
+ * should treat a cached texture as stale when this differs from the
102
+ * cached value; dimension/length heuristics cannot detect a
103
+ * same-sized retransmission.
104
+ *
105
+ * Stamps are unique and monotonically increasing process-wide, so
106
+ * caches keyed on a generation value never alias across screens
107
+ * (main/alternate), resets, or terminals.
108
+ *
109
* ## Lifetime and Thread Safety
110
*
111
* All handles borrowed from the terminal (GhosttyKittyGraphics,
@@ -119,6 +141,29 @@ typedef enum GHOSTTY_ENUM_TYPED {
141
* Output type: GhosttyKittyGraphicsPlacementIterator *
142
*/
143
GHOSTTY_KITTY_GRAPHICS_DATA_PLACEMENT_ITERATOR = 1,
144
+
145
+ /**
146
+ * Generation stamp of the last content mutation to this storage:
147
+ * any image transmit/replace, placement add, or delete. Zero means
148
+ * the storage has never been mutated (and is therefore empty).
149
+ *
150
+ * If the generation is unchanged since a previous query, the set of
151
+ * placements and all image data are identical, so placement iteration
152
+ * and image staleness checks can be skipped entirely. Note that
153
+ * placement *geometry* may still have changed (scrolling and resizing
154
+ * move placements without changing the storage contents), so rendering
155
+ * geometry such as ghostty_kitty_graphics_placement_render_info()
156
+ * must still be recomputed for frames marked dirty.
157
+ *
158
+ * Stamps are unique and monotonically increasing process-wide: a
159
+ * value observed from any storage never recurs for different content,
160
+ * even across screen switches (main vs. alternate screen have
161
+ * independent storages) or terminal resets. It is therefore safe to
162
+ * key caches on this value alone.
163
+ *
164
+ * Output type: uint64_t *
165
+ */
166
+ GHOSTTY_KITTY_GRAPHICS_DATA_GENERATION = 2,
167
GHOSTTY_KITTY_GRAPHICS_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
168
} GhosttyKittyGraphicsData;
169
@@ -255,6 +300,12 @@ typedef enum GHOSTTY_ENUM_TYPED {
300
/**
301
* Pixel format of a Kitty graphics image.
302
*
303
+ * Note that stored images are always fully decoded:
304
+ * GHOSTTY_KITTY_IMAGE_FORMAT_PNG is never returned by
305
+ * ghostty_kitty_graphics_image_get() because PNG payloads are decoded
306
+ * to GHOSTTY_KITTY_IMAGE_FORMAT_RGBA before storage. The PNG value
307
+ * exists only for protocol-level completeness.
308
+ *
309
* @ingroup kitty_graphics
310
*/
311
typedef enum GHOSTTY_ENUM_TYPED {
@@ -269,6 +320,12 @@ typedef enum GHOSTTY_ENUM_TYPED {
320
/**
321
* Compression of a Kitty graphics image.
322
*
323
+ * Note that stored images are always decompressed:
324
+ * GHOSTTY_KITTY_IMAGE_COMPRESSION_ZLIB_DEFLATE payloads are inflated
325
+ * before storage, so ghostty_kitty_graphics_image_get() always reports
326
+ * GHOSTTY_KITTY_IMAGE_COMPRESSION_NONE. Consumers never need to
327
+ * inflate image data themselves.
328
+ *
329
* @ingroup kitty_graphics
330
*/
331
typedef enum GHOSTTY_ENUM_TYPED {
@@ -315,14 +372,17 @@ typedef enum GHOSTTY_ENUM_TYPED {
372
GHOSTTY_KITTY_IMAGE_DATA_HEIGHT = 4,
373
374
/**
318
- * Pixel format of the image.
375
+ * Pixel format of the image. Never GHOSTTY_KITTY_IMAGE_FORMAT_PNG;
376
+ * PNG payloads are decoded to RGBA before storage.
377
*
378
* Output type: GhosttyKittyImageFormat *
379
*/
380
GHOSTTY_KITTY_IMAGE_DATA_FORMAT = 5,
381
382
/**
325
- * Compression of the image.
383
+ * Compression of the image. Always
384
+ * GHOSTTY_KITTY_IMAGE_COMPRESSION_NONE; compressed payloads are
385
+ * inflated before storage.
386
*
387
* Output type: GhosttyKittyImageCompression *
388
*/
@@ -332,17 +392,41 @@ typedef enum GHOSTTY_ENUM_TYPED {
392
* Borrowed pointer to the raw pixel data. Valid as long as the
393
* underlying terminal is not mutated.
394
*
395
+ * The data is always fully decoded, uncompressed pixels in the
396
+ * format reported by GHOSTTY_KITTY_IMAGE_DATA_FORMAT: zlib payloads
397
+ * are inflated and PNG payloads are decoded to RGBA at transmission
398
+ * time, before the image is stored. Consumers can upload this
399
+ * directly to the GPU without any decode step.
400
+ *
401
* Output type: const uint8_t **
402
*/
403
GHOSTTY_KITTY_IMAGE_DATA_DATA_PTR = 7,
404
405
/**
340
- * Length of the raw pixel data in bytes.
406
+ * Length of the raw pixel data in bytes. Always equal to
407
+ * width * height * bytes-per-pixel for the reported format.
408
*
409
* Output type: size_t *
410
*/
411
GHOSTTY_KITTY_IMAGE_DATA_DATA_LEN = 8,
412
413
+ /**
414
+ * Generation stamp assigned when this image was added to (or
415
+ * replaced in) the storage. A changed generation for a given image
416
+ * ID means the pixel contents may have changed even when the
417
+ * dimensions, format, and data length are identical (e.g. a
418
+ * retransmission of the same image ID), so texture caches must key
419
+ * staleness on this value rather than on size heuristics.
420
+ *
421
+ * Stamps are unique and monotonically increasing process-wide and
422
+ * are drawn from the same sequence as
423
+ * GHOSTTY_KITTY_GRAPHICS_DATA_GENERATION. Never zero for a stored
424
+ * image, so zero can be used as an "empty" sentinel by callers.
425
+ *
426
+ * Output type: uint64_t *
427
+ */
428
+ GHOSTTY_KITTY_IMAGE_DATA_GENERATION = 9,
429
+
430
GHOSTTY_KITTY_IMAGE_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
431
} GhosttyKittyGraphicsImageData;
432
native/libghostty-vt/include/ghostty/vt/render.h
+66
@@ -39,6 +39,18 @@ extern "C" {
39
* 2. Update it from a terminal instance whenever you need.
40
* 3. Read from the render state to get the data needed to draw your frame.
41
*
42
+ * ## Two-Phase Updates
43
+ *
44
+ * For callers that synchronize terminal access (e.g. a renderer thread
45
+ * sharing a lock with an IO thread), the update can be split into two
46
+ * phases to minimize the time the terminal must be held exclusively:
47
+ * ghostty_render_state_begin_update requires terminal access, while
48
+ * ghostty_render_state_end_update completes any deferred work using only
49
+ * memory owned by the render state. A typical renderer would lock, begin
50
+ * the update, unlock, and then end the update while the IO thread is free
51
+ * to continue modifying the terminal. ghostty_render_state_update is a
52
+ * convenience that performs both phases in one call.
53
+ *
54
* ## Dirty Tracking
55
*
56
* Dirty tracking is a key feature of the render state that allows renderers
@@ -331,6 +343,12 @@ GHOSTTY_API void ghostty_render_state_free(GhosttyRenderState state);
343
* This consumes terminal/screen dirty state in the same way as the internal
344
* render state update path.
345
*
346
+ * This is a convenience function that performs a full update in one call,
347
+ * equivalent to ghostty_render_state_begin_update immediately followed by
348
+ * ghostty_render_state_end_update. Callers that hold a lock over the
349
+ * terminal state should prefer calling the two phases directly so that the
350
+ * lock is only held for the begin phase.
351
+ *
352
* @param state The render state handle (NULL returns GHOSTTY_INVALID_VALUE)
353
* @param terminal The terminal handle to read from (NULL returns GHOSTTY_INVALID_VALUE)
354
* @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if `state` or
@@ -342,6 +360,54 @@ GHOSTTY_API void ghostty_render_state_free(GhosttyRenderState state);
360
GHOSTTY_API GhosttyResult ghostty_render_state_update(GhosttyRenderState state,
361
GhosttyTerminal terminal);
362
363
+/**
364
+ * Begin an update of a render state instance from a terminal.
365
+ *
366
+ * Every begin must be completed with a ghostty_render_state_end_update call
367
+ * before the render state is read.
368
+ *
369
+ * This two-phase structure exists for callers that synchronize access to the
370
+ * terminal state (e.g. with a lock shared with an IO thread): only this
371
+ * function requires terminal access, so a caller can hold its lock for this
372
+ * call only and then call ghostty_render_state_end_update after releasing
373
+ * it. The end phase exclusively reads and writes memory owned by the render
374
+ * state, so it is safe to call while the terminal is being modified.
375
+ *
376
+ * Work that doesn't require terminal access may be deferred to the end phase
377
+ * to keep this call (and therefore lock hold time) as short as possible.
378
+ * Callers must treat the render state as incomplete until
379
+ * ghostty_render_state_end_update is called.
380
+ *
381
+ * This consumes terminal/screen dirty state in the same way as the internal
382
+ * render state update path.
383
+ *
384
+ * @param state The render state handle (NULL returns GHOSTTY_INVALID_VALUE)
385
+ * @param terminal The terminal handle to read from (NULL returns GHOSTTY_INVALID_VALUE)
386
+ * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if `state` or
387
+ * `terminal` is NULL, GHOSTTY_OUT_OF_MEMORY if updating the state requires
388
+ * allocation and that allocation fails
389
+ *
390
+ * @ingroup render
391
+ */
392
+GHOSTTY_API GhosttyResult ghostty_render_state_begin_update(GhosttyRenderState state,
393
+ GhosttyTerminal terminal);
394
+
395
+/**
396
+ * Complete a prior ghostty_render_state_begin_update call by performing any
397
+ * deferred work.
398
+ *
399
+ * This only reads and writes memory owned by the render state, so it is safe
400
+ * to call while the terminal is being modified (no terminal synchronization
401
+ * is required). Calling this without a prior begin is a safe no-op.
402
+ *
403
+ * @param state The render state handle (NULL returns GHOSTTY_INVALID_VALUE)
404
+ * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if `state` is
405
+ * NULL
406
+ *
407
+ * @ingroup render
408
+ */
409
+GHOSTTY_API GhosttyResult ghostty_render_state_end_update(GhosttyRenderState state);
410
+
411
/**
412
* Get a value from a render state.
413
*
native/libghostty-vt/include/ghostty/vt/sgr.h
+5
-2
@@ -19,8 +19,11 @@
19
* The parser processes SGR parameters from CSI sequences (e.g., `ESC[1;31m`)
20
* and returns individual text attributes like bold, italic, colors, etc.
21
* It supports both semicolon (`;`) and colon (`:`) separators, possibly mixed,
22
- * and handles various color formats including 8-color, 16-color, 256-color,
23
- * X11 named colors, and RGB in multiple formats.
22
+ * and handles SGR color attributes including 8-color, 16-color, 256-color,
23
+ * direct RGB, underline color, and reset forms. Color values are returned
24
+ * using the shared @ref color types; applications that need to parse Ghostty
25
+ * config/theme color strings, generate palettes, inspect X11 color names, or
26
+ * calculate luminance and contrast should use the @ref color APIs directly.
27
*
28
* ## Basic Usage
29
*
native/libghostty-vt/include/ghostty/vt/terminal.h
+32
-4
@@ -191,6 +191,21 @@ typedef enum GHOSTTY_ENUM_TYPED {
191
192
/** Scroll by a delta amount (up is negative). */
193
GHOSTTY_SCROLL_VIEWPORT_DELTA,
194
+
195
+ /**
196
+ * Scroll to an absolute row offset from the top of the scrollable
197
+ * area. Row 0 is the top of the scrollback and the requested row
198
+ * becomes the first visible row of the viewport. The value is
199
+ * clamped so the viewport never scrolls beyond the top of the
200
+ * active area. If the terminal has no scrollback (e.g. the
201
+ * alternate screen is active), the viewport always remains on the
202
+ * active area.
203
+ *
204
+ * This is the same row space as the offset field of
205
+ * GhosttyTerminalScrollbar, so a scrollbar position obtained from
206
+ * GHOSTTY_TERMINAL_DATA_SCROLLBAR round-trips cleanly.
207
+ */
208
+ GHOSTTY_SCROLL_VIEWPORT_ROW,
209
GHOSTTY_SCROLL_VIEWPORT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
210
} GhosttyTerminalScrollViewportTag;
211
@@ -203,6 +218,9 @@ typedef union {
218
/** Scroll delta (only used with GHOSTTY_SCROLL_VIEWPORT_DELTA). Up is negative. */
219
intptr_t delta;
220
221
+ /** Absolute row offset (only used with GHOSTTY_SCROLL_VIEWPORT_ROW). */
222
+ size_t row;
223
+
224
/** Padding for ABI compatibility. Do not use. */
225
uint64_t _padding[2];
226
} GhosttyTerminalScrollViewportValue;
@@ -767,9 +785,16 @@ typedef enum GHOSTTY_ENUM_TYPED {
785
/**
786
* Scrollbar state for the terminal viewport.
787
*
770
- * This may be expensive to calculate depending on where the viewport
771
- * is (arbitrary pins are expensive). The caller should take care to only
772
- * call this as needed and not too frequently.
788
+ * This is amortized O(1): the total is maintained incrementally as
789
+ * the terminal is modified and the viewport offset is cached. The
790
+ * first read after the viewport moves to an arbitrary position that
791
+ * isn't an absolute row (e.g. scrolling to a selection) may cost
792
+ * O(pages) to compute the offset, after which it is cached again.
793
+ *
794
+ * There is intentionally no change notification for scroll state.
795
+ * Callers building scrollbars should poll this once per frame or
796
+ * per write batch and diff the result to detect changes; this is
797
+ * what Ghostty's own renderer does.
798
*
799
* Output type: GhosttyTerminalScrollbar *
800
*/
@@ -1120,7 +1145,10 @@ GHOSTTY_API void ghostty_terminal_vt_write(GhosttyTerminal terminal,
1145
* Scrolls the terminal's viewport according to the given behavior.
1146
* When using GHOSTTY_SCROLL_VIEWPORT_DELTA, set the delta field in
1147
* the value union to specify the number of rows to scroll (negative
1123
- * for up, positive for down). For other behaviors, the value is ignored.
1148
+ * for up, positive for down). When using GHOSTTY_SCROLL_VIEWPORT_ROW,
1149
+ * set the row field to the absolute row offset from the top of the
1150
+ * scrollable area (the same row space as the offset field of
1151
+ * GhosttyTerminalScrollbar). For other behaviors, the value is ignored.
1152
*
1153
* @param terminal The terminal handle (may be NULL, in which case this is a no-op)
1154
* @param behavior The scroll behavior as a tagged union
native/libghostty-vt/include/ghostty/vt/unicode.h
new
+154
@@ -0,0 +1,154 @@
1
+/**
2
+ * @file unicode.h
3
+ *
4
+ * Unicode utilities - codepoint properties matching the terminal's
5
+ * text layout semantics.
6
+ */
7
+
8
+#ifndef GHOSTTY_VT_UNICODE_H
9
+#define GHOSTTY_VT_UNICODE_H
10
+
11
+/** @defgroup unicode Unicode Utilities
12
+ *
13
+ * Unicode codepoint properties matching the terminal's text layout
14
+ * semantics.
15
+ *
16
+ * ## Basic Usage
17
+ *
18
+ * Use ghostty_unicode_codepoint_width() to determine how many terminal
19
+ * grid cells a codepoint occupies, using the exact same width table the
20
+ * terminal itself uses when laying out printed text. Use
21
+ * ghostty_unicode_grapheme_width() to segment and measure full grapheme
22
+ * clusters with the same rules the terminal uses when mode 2027 is
23
+ * enabled. These functions are useful for predicting column layout of
24
+ * text that has not yet been written to the terminal, such as IME
25
+ * preedit (composition) overlays.
26
+ *
27
+ * @{
28
+ */
29
+
30
+#include <stddef.h>
31
+#include <stdint.h>
32
+#include <ghostty/vt/types.h>
33
+
34
+#ifdef __cplusplus
35
+extern "C" {
36
+#endif
37
+
38
+/**
39
+ * Returns the terminal display width of a Unicode codepoint in
40
+ * terminal grid cells: 0, 1, or 2.
41
+ *
42
+ * This is the same width table the terminal itself uses when laying
43
+ * out printed text, so callers can predict column layout (e.g. IME
44
+ * preedit overlays) that exactly matches what the terminal will do
45
+ * when the text is actually written to it.
46
+ *
47
+ * Semantics:
48
+ * - Returns 0 for zero-width codepoints: C0/C1 control characters,
49
+ * nonspacing and enclosing combining marks, default-ignorable
50
+ * codepoints (ZWJ, ZWNJ, variation selectors, etc.), and
51
+ * surrogate codepoints.
52
+ * - Returns 2 for wide codepoints: East Asian Wide/Fullwidth
53
+ * (including emoji with default emoji presentation) and regional
54
+ * indicators. Width is clamped to 2 (e.g. the three-em dash).
55
+ * - Returns 1 for everything else, including invalid codepoints
56
+ * beyond U+10FFFF (this function is total; it never fails).
57
+ *
58
+ * This operates on a single codepoint only and therefore cannot account
59
+ * for grapheme-cluster-level width rules (VS16 emoji presentation,
60
+ * combining sequences, etc.). For cluster-accurate widths, use
61
+ * ghostty_unicode_grapheme_width(). Summing per-codepoint widths is only
62
+ * correct when mode 2027 (grapheme clustering) is disabled.
63
+ *
64
+ * This function is pure, allocates nothing, and is thread-safe.
65
+ *
66
+ * @param cp The Unicode codepoint to measure
67
+ * @return Display width in cells: 0, 1, or 2
68
+ */
69
+GHOSTTY_API uint8_t ghostty_unicode_codepoint_width(uint32_t cp);
70
+
71
+/**
72
+ * Measures the terminal display width of the first grapheme cluster in a
73
+ * sequence of Unicode codepoints.
74
+ *
75
+ * This uses the exact same grapheme segmentation and cluster width rules
76
+ * the terminal itself uses when printing text with grapheme clustering
77
+ * enabled (mode 2027), so callers can predict column layout (e.g. IME
78
+ * preedit overlays) that exactly matches what the terminal will do when
79
+ * the text is actually written to it. Unlike
80
+ * ghostty_unicode_codepoint_width(), this accounts for cluster-level
81
+ * rules: emoji variation selectors, ZWJ sequences, combining marks, and
82
+ * skin tone modifiers.
83
+ *
84
+ * Reads codepoints from cps until the terminal would consider the
85
+ * grapheme cluster complete, stores the cluster's total width in cells
86
+ * (0, 1, or 2) into width (which may be NULL if only segmentation is
87
+ * desired), and returns the number of codepoints consumed. Returns 0 if
88
+ * and only if len is 0; otherwise consumes at least one codepoint. Measure
89
+ * a whole string by calling in a loop:
90
+ *
91
+ * @code
92
+ * size_t total = 0;
93
+ * for (size_t i = 0; i < len;) {
94
+ * uint8_t width;
95
+ * i += ghostty_unicode_grapheme_width(cps + i, len - i, &width);
96
+ * total += width;
97
+ * }
98
+ * @endcode
99
+ *
100
+ * This is not a streaming API. The provided sequence must contain a
101
+ * complete first grapheme cluster, or the logical end of the string. If
102
+ * input arrives in chunks, keep buffering while this function consumes all
103
+ * available codepoints (return value == len) and the stream may still
104
+ * continue; a later codepoint could still extend the cluster and change
105
+ * its width.
106
+ *
107
+ * Width semantics, matching the terminal with mode 2027 enabled:
108
+ * - The cluster starts at the width of its first codepoint, as returned by
109
+ * ghostty_unicode_codepoint_width().
110
+ * - VS16 (U+FE0F) forces the cluster wide (2) and VS15 (U+FE0E) forces it
111
+ * narrow (1), but only when the immediately preceding codepoint in the
112
+ * cluster is a valid emoji variation sequence base (per Unicode
113
+ * emoji-variation-sequences.txt). Invalid variation selectors are
114
+ * ignored entirely.
115
+ * - Any other continuation codepoint that contributes to grapheme width
116
+ * forces the cluster wide (2). Note this means cluster width is NOT the
117
+ * maximum of per-codepoint widths: some continuation marks have narrow
118
+ * codepoint width yet still widen the cluster.
119
+ *
120
+ * Mode dependence: this models mode 2027 (grapheme clustering) enabled,
121
+ * which is Ghostty's recommended configuration. When mode 2027 is
122
+ * disabled, clusters never combine and variation selectors never change
123
+ * width; predict layout in that case by summing
124
+ * ghostty_unicode_codepoint_width() over each codepoint instead.
125
+ *
126
+ * Edge cases:
127
+ * - Codepoints beyond U+10FFFF consume one codepoint, have width 1, and
128
+ * are always cluster boundaries. This function is total; it never fails.
129
+ * - Control characters (C0/C1, CR, LF) are never printed through the
130
+ * terminal's text path; passing them here returns an unspecified (but
131
+ * stable and bounded) result.
132
+ * - A cluster whose first codepoint is zero-width (e.g. a lone combining
133
+ * mark) is malformed at a cell start; the terminal may attach it to
134
+ * earlier screen content. This function reports the fold result for the
135
+ * sequence in isolation (typically 0).
136
+ *
137
+ * This function is pure, allocates nothing, and is thread-safe.
138
+ *
139
+ * @param cps Pointer to codepoints (may be NULL only when len is 0)
140
+ * @param len Number of codepoints available
141
+ * @param width Out: cluster display width in cells (0-2); may be NULL
142
+ * @return Number of codepoints in the first grapheme cluster
143
+ */
144
+GHOSTTY_API size_t ghostty_unicode_grapheme_width(const uint32_t *cps,
145
+ size_t len,
146
+ uint8_t *width);
147
+
148
+#ifdef __cplusplus
149
+}
150
+#endif
151
+
152
+/** @} */
153
+
154
+#endif /* GHOSTTY_VT_UNICODE_H */