@devries-cameron20 / t3code-1 / commits / 3908c4eab3
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

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 */