libghostty: add MAX_VALUE sentinels to all C enums for 32-bit sizing (#12189)

Pre-C23, the C standard allows compilers to choose any integer type
that can represent all enum values, so small enums could be backed
by char or short. This breaks ABI compatibility with the Zig side,
which backs these enums with c_int.

Define GHOSTTY_ENUM_MAX_VALUE as INT_MAX in types.h and add it as
the last entry in every enum in include/ghostty/vt/. This forces
the compiler to use int as the backing type, matching c_int on all
targets. INT_MAX is used rather than a fixed constant because enum
constants must be representable as int; values above INT_MAX are a
constraint violation in standard C.

Document this convention in AGENTS.md.

AGENTS.md

@@ -22,6 +22,8 @@ A file for [guiding coding agents](https://agents.md/).
 - Build WASM: `zig build -Demit-lib-vt -Dtarget=wasm32-freestanding -Doptimize=ReleaseSmall`
 - Test: `zig build test-lib-vt -Dtest-filter=<filter>`
   - Prefer this when the change is in a libghostty-vt file
+- All C enums in `include/ghostty/vt/` must have a `_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE`
+  sentinel as the last entry to force int enum sizing (pre-C23 portability).
 
 ## Directory Structure
 

include/ghostty/vt/build_info.h

@@ -35,11 +35,12 @@ extern "C" {
 /**
  * Build optimization mode.
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   GHOSTTY_OPTIMIZE_DEBUG = 0,
   GHOSTTY_OPTIMIZE_RELEASE_SAFE = 1,
   GHOSTTY_OPTIMIZE_RELEASE_SMALL = 2,
   GHOSTTY_OPTIMIZE_RELEASE_FAST = 3,
+  GHOSTTY_OPTIMIZE_MODE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyOptimizeMode;
 
 /**
@@ -47,7 +48,7 @@ typedef enum {
  *
  * Each variant documents the expected output pointer type.
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** Invalid data type. Never results in any data extraction. */
   GHOSTTY_BUILD_INFO_INVALID = 0,
 
@@ -122,6 +123,7 @@ typedef enum {
    * Output type: GhosttyString *
    */
   GHOSTTY_BUILD_INFO_VERSION_BUILD = 10,
+  GHOSTTY_BUILD_INFO_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyBuildInfo;
 
 /**

include/ghostty/vt/device.h

@@ -71,9 +71,10 @@ extern "C" {
  *
  * @ingroup terminal
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
     GHOSTTY_COLOR_SCHEME_LIGHT = 0,
     GHOSTTY_COLOR_SCHEME_DARK = 1,
+    GHOSTTY_COLOR_SCHEME_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyColorScheme;
 
 /**

include/ghostty/vt/focus.h

@@ -35,11 +35,12 @@ extern "C" {
 /**
  * Focus event types for focus reporting mode (mode 1004).
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
     /** Terminal window gained focus */
     GHOSTTY_FOCUS_GAINED = 0,
     /** Terminal window lost focus */
     GHOSTTY_FOCUS_LOST = 1,
+    GHOSTTY_FOCUS_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyFocusEvent;
 
 /**

include/ghostty/vt/formatter.h

@@ -37,7 +37,7 @@ extern "C" {
  *
  * @ingroup formatter
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** Plain text (no escape sequences). */
   GHOSTTY_FORMATTER_FORMAT_PLAIN,
 
@@ -46,6 +46,7 @@ typedef enum {
 
   /** HTML with inline styles. */
   GHOSTTY_FORMATTER_FORMAT_HTML,
+  GHOSTTY_FORMATTER_FORMAT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyFormatterFormat;
 
 /**

include/ghostty/vt/key/encoder.h

@@ -64,7 +64,7 @@ typedef uint8_t GhosttyKittyKeyFlags;
  *
  * @ingroup key
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
     /** Option key is not treated as alt */
     GHOSTTY_OPTION_AS_ALT_FALSE = 0,
     /** Option key is treated as alt */
@@ -73,6 +73,7 @@ typedef enum {
     GHOSTTY_OPTION_AS_ALT_LEFT = 2,
     /** Only right option key is treated as alt */
     GHOSTTY_OPTION_AS_ALT_RIGHT = 3,
+    GHOSTTY_OPTION_AS_ALT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyOptionAsAlt;
 
 /**
@@ -83,7 +84,7 @@ typedef enum {
  *
  * @ingroup key
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
     /** Terminal DEC mode 1: cursor key application mode (value: bool) */
     GHOSTTY_KEY_ENCODER_OPT_CURSOR_KEY_APPLICATION = 0,
     
@@ -104,6 +105,7 @@ typedef enum {
     
     /** macOS option-as-alt setting (value: GhosttyOptionAsAlt) */
     GHOSTTY_KEY_ENCODER_OPT_MACOS_OPTION_AS_ALT = 6,
+    GHOSTTY_KEY_ENCODER_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyKeyEncoderOption;
 
 /**

include/ghostty/vt/key/event.h

@@ -28,13 +28,14 @@ typedef struct GhosttyKeyEventImpl *GhosttyKeyEvent;
  *
  * @ingroup key
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
     /** Key was released */
     GHOSTTY_KEY_ACTION_RELEASE = 0,
     /** Key was pressed */
     GHOSTTY_KEY_ACTION_PRESS = 1,
     /** Key is being repeated (held down) */
     GHOSTTY_KEY_ACTION_REPEAT = 2,
+    GHOSTTY_KEY_ACTION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyKeyAction;
 
 /**
@@ -103,7 +104,7 @@ typedef uint16_t GhosttyMods;
  *
  * @ingroup key
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
     GHOSTTY_KEY_UNIDENTIFIED = 0,
 
     // Writing System Keys (W3C § 3.1.1)
@@ -296,6 +297,7 @@ typedef enum {
     GHOSTTY_KEY_COPY,
     GHOSTTY_KEY_CUT,
     GHOSTTY_KEY_PASTE,
+    GHOSTTY_KEY_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyKey;
 
 /**

include/ghostty/vt/kitty_graphics.h

@@ -107,7 +107,7 @@ extern "C" {
  *
  * @ingroup kitty_graphics
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** Invalid / sentinel value. */
   GHOSTTY_KITTY_GRAPHICS_DATA_INVALID = 0,
 
@@ -119,6 +119,7 @@ typedef enum {
    * Output type: GhosttyKittyGraphicsPlacementIterator *
    */
   GHOSTTY_KITTY_GRAPHICS_DATA_PLACEMENT_ITERATOR = 1,
+  GHOSTTY_KITTY_GRAPHICS_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyKittyGraphicsData;
 
 /**
@@ -126,7 +127,7 @@ typedef enum {
  *
  * @ingroup kitty_graphics
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** Invalid / sentinel value. */
   GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_INVALID = 0,
 
@@ -213,6 +214,7 @@ typedef enum {
    * Output type: int32_t *
    */
   GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_Z = 12,
+  GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyKittyGraphicsPlacementData;
 
 /**
@@ -226,11 +228,12 @@ typedef enum {
  *
  * @ingroup kitty_graphics
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   GHOSTTY_KITTY_PLACEMENT_LAYER_ALL = 0,
   GHOSTTY_KITTY_PLACEMENT_LAYER_BELOW_BG = 1,
   GHOSTTY_KITTY_PLACEMENT_LAYER_BELOW_TEXT = 2,
   GHOSTTY_KITTY_PLACEMENT_LAYER_ABOVE_TEXT = 3,
+  GHOSTTY_KITTY_PLACEMENT_LAYER_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyKittyPlacementLayer;
 
 /**
@@ -238,13 +241,14 @@ typedef enum {
  *
  * @ingroup kitty_graphics
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /**
    * Set the z-layer filter for the iterator.
    *
    * Input type: GhosttyKittyPlacementLayer *
    */
   GHOSTTY_KITTY_GRAPHICS_PLACEMENT_ITERATOR_OPTION_LAYER = 0,
+  GHOSTTY_KITTY_GRAPHICS_PLACEMENT_ITERATOR_OPTION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyKittyGraphicsPlacementIteratorOption;
 
 /**
@@ -252,12 +256,13 @@ typedef enum {
  *
  * @ingroup kitty_graphics
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   GHOSTTY_KITTY_IMAGE_FORMAT_RGB = 0,
   GHOSTTY_KITTY_IMAGE_FORMAT_RGBA = 1,
   GHOSTTY_KITTY_IMAGE_FORMAT_PNG = 2,
   GHOSTTY_KITTY_IMAGE_FORMAT_GRAY_ALPHA = 3,
   GHOSTTY_KITTY_IMAGE_FORMAT_GRAY = 4,
+  GHOSTTY_KITTY_IMAGE_FORMAT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyKittyImageFormat;
 
 /**
@@ -265,9 +270,10 @@ typedef enum {
  *
  * @ingroup kitty_graphics
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   GHOSTTY_KITTY_IMAGE_COMPRESSION_NONE = 0,
   GHOSTTY_KITTY_IMAGE_COMPRESSION_ZLIB_DEFLATE = 1,
+  GHOSTTY_KITTY_IMAGE_COMPRESSION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyKittyImageCompression;
 
 /**
@@ -275,7 +281,7 @@ typedef enum {
  *
  * @ingroup kitty_graphics
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** Invalid / sentinel value. */
   GHOSTTY_KITTY_IMAGE_DATA_INVALID = 0,
 
@@ -335,6 +341,7 @@ typedef enum {
    * Output type: size_t *
    */
   GHOSTTY_KITTY_IMAGE_DATA_DATA_LEN = 8,
+  GHOSTTY_KITTY_IMAGE_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyKittyGraphicsImageData;
 
 /**

include/ghostty/vt/modes.h

@@ -146,7 +146,7 @@ static inline bool ghostty_mode_ansi(GhosttyMode mode) {
  * These correspond to the Ps2 parameter in a DECRPM response
  * sequence (CSI ? Ps1 ; Ps2 $ y).
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
     /** Mode is not recognized */
     GHOSTTY_MODE_REPORT_NOT_RECOGNIZED = 0,
     /** Mode is set (enabled) */
@@ -157,6 +157,7 @@ typedef enum {
     GHOSTTY_MODE_REPORT_PERMANENTLY_SET = 3,
     /** Mode is permanently reset */
     GHOSTTY_MODE_REPORT_PERMANENTLY_RESET = 4,
+    GHOSTTY_MODE_REPORT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyModeReportState;
 
 /**

include/ghostty/vt/mouse/encoder.h

@@ -30,7 +30,7 @@ typedef struct GhosttyMouseEncoderImpl *GhosttyMouseEncoder;
  *
  * @ingroup mouse
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** Mouse reporting disabled. */
   GHOSTTY_MOUSE_TRACKING_NONE = 0,
 
@@ -45,6 +45,7 @@ typedef enum {
 
   /** Any-event tracking mode. */
   GHOSTTY_MOUSE_TRACKING_ANY = 4,
+  GHOSTTY_MOUSE_TRACKING_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyMouseTrackingMode;
 
 /**
@@ -52,12 +53,13 @@ typedef enum {
  *
  * @ingroup mouse
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   GHOSTTY_MOUSE_FORMAT_X10 = 0,
   GHOSTTY_MOUSE_FORMAT_UTF8 = 1,
   GHOSTTY_MOUSE_FORMAT_SGR = 2,
   GHOSTTY_MOUSE_FORMAT_URXVT = 3,
   GHOSTTY_MOUSE_FORMAT_SGR_PIXELS = 4,
+  GHOSTTY_MOUSE_FORMAT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyMouseFormat;
 
 /**
@@ -105,7 +107,7 @@ typedef struct {
  *
  * @ingroup mouse
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** Mouse tracking mode (value: GhosttyMouseTrackingMode). */
   GHOSTTY_MOUSE_ENCODER_OPT_EVENT = 0,
 
@@ -120,6 +122,7 @@ typedef enum {
 
   /** Whether to enable motion deduplication by last cell (value: bool). */
   GHOSTTY_MOUSE_ENCODER_OPT_TRACK_LAST_CELL = 4,
+  GHOSTTY_MOUSE_ENCODER_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyMouseEncoderOption;
 
 /**

include/ghostty/vt/mouse/event.h

@@ -27,7 +27,7 @@ typedef struct GhosttyMouseEventImpl *GhosttyMouseEvent;
  *
  * @ingroup mouse
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** Mouse button was pressed. */
   GHOSTTY_MOUSE_ACTION_PRESS = 0,
 
@@ -36,6 +36,7 @@ typedef enum {
 
   /** Mouse moved. */
   GHOSTTY_MOUSE_ACTION_MOTION = 2,
+  GHOSTTY_MOUSE_ACTION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyMouseAction;
 
 /**
@@ -43,7 +44,7 @@ typedef enum {
  *
  * @ingroup mouse
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   GHOSTTY_MOUSE_BUTTON_UNKNOWN = 0,
   GHOSTTY_MOUSE_BUTTON_LEFT = 1,
   GHOSTTY_MOUSE_BUTTON_RIGHT = 2,
@@ -56,6 +57,7 @@ typedef enum {
   GHOSTTY_MOUSE_BUTTON_NINE = 9,
   GHOSTTY_MOUSE_BUTTON_TEN = 10,
   GHOSTTY_MOUSE_BUTTON_ELEVEN = 11,
+  GHOSTTY_MOUSE_BUTTON_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyMouseButton;
 
 /**

include/ghostty/vt/osc.h

@@ -39,7 +39,7 @@
  *
  * @ingroup osc
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   GHOSTTY_OSC_COMMAND_INVALID = 0,
   GHOSTTY_OSC_COMMAND_CHANGE_WINDOW_TITLE = 1,
   GHOSTTY_OSC_COMMAND_CHANGE_WINDOW_ICON = 2,
@@ -63,6 +63,7 @@ typedef enum {
   GHOSTTY_OSC_COMMAND_CONEMU_XTERM_EMULATION = 20,
   GHOSTTY_OSC_COMMAND_CONEMU_COMMENT = 21,
   GHOSTTY_OSC_COMMAND_KITTY_TEXT_SIZING = 22,
+  GHOSTTY_OSC_COMMAND_TYPE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyOscCommandType;
 
 /**
@@ -73,7 +74,7 @@ typedef enum {
  *
  * @ingroup osc
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** Invalid data type. Never results in any data extraction. */
   GHOSTTY_OSC_DATA_INVALID = 0,
   
@@ -88,6 +89,7 @@ typedef enum {
    * the same parser instance. Memory is owned by the parser.
    */
   GHOSTTY_OSC_DATA_CHANGE_WINDOW_TITLE_STR = 1,
+  GHOSTTY_OSC_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyOscCommandData;
 
 /**

include/ghostty/vt/point.h

@@ -42,7 +42,7 @@ typedef struct {
  *
  * @ingroup point
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** Active area where the cursor can move. */
   GHOSTTY_POINT_TAG_ACTIVE = 0,
 
@@ -54,7 +54,8 @@ typedef enum {
 
   /** Scrollback history only (before active area). */
   GHOSTTY_POINT_TAG_HISTORY = 3,
-} GhosttyPointTag;
+  GHOSTTY_POINT_TAG_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
+  } GhosttyPointTag;
 
 /**
  * Point value union.

include/ghostty/vt/render.h

@@ -86,7 +86,7 @@ extern "C" {
  *
  * @ingroup render
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** Not dirty at all; rendering can be skipped. */
   GHOSTTY_RENDER_STATE_DIRTY_FALSE = 0,
 
@@ -95,6 +95,7 @@ typedef enum {
 
   /** Global state changed; renderer should redraw everything. */
   GHOSTTY_RENDER_STATE_DIRTY_FULL = 2,
+  GHOSTTY_RENDER_STATE_DIRTY_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyRenderStateDirty;
 
 /**
@@ -102,7 +103,7 @@ typedef enum {
  *
  * @ingroup render
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** Bar cursor (DECSCUSR 5, 6). */
   GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BAR = 0,
 
@@ -114,6 +115,7 @@ typedef enum {
 
   /** Hollow block cursor. */
   GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BLOCK_HOLLOW = 3,
+  GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyRenderStateCursorVisualStyle;
 
 /**
@@ -121,7 +123,7 @@ typedef enum {
  *
  * @ingroup render
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** Invalid / sentinel value. */
   GHOSTTY_RENDER_STATE_DATA_INVALID = 0,
 
@@ -185,6 +187,7 @@ typedef enum {
   /** Whether the cursor is on the tail of a wide character (bool).
    *  Only valid when CURSOR_VIEWPORT_HAS_VALUE is true. */
   GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_WIDE_TAIL = 17,
+  GHOSTTY_RENDER_STATE_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyRenderStateData;
 
 /**
@@ -192,9 +195,10 @@ typedef enum {
  *
  * @ingroup render
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** Set dirty state (GhosttyRenderStateDirty). */
   GHOSTTY_RENDER_STATE_OPTION_DIRTY = 0,
+  GHOSTTY_RENDER_STATE_OPTION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyRenderStateOption;
 
 /**
@@ -202,7 +206,7 @@ typedef enum {
  *
  * @ingroup render
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** Invalid / sentinel value. */
   GHOSTTY_RENDER_STATE_ROW_DATA_INVALID = 0,
 
@@ -217,6 +221,7 @@ typedef enum {
    *  valid as long as the underlying render state is not updated. 
    *  It is unsafe to use cell data after updating the render state. */
   GHOSTTY_RENDER_STATE_ROW_DATA_CELLS = 3,
+  GHOSTTY_RENDER_STATE_ROW_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyRenderStateRowData;
 
 /**
@@ -224,9 +229,10 @@ typedef enum {
  *
  * @ingroup render
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** Set dirty state for the current row (bool). */
   GHOSTTY_RENDER_STATE_ROW_OPTION_DIRTY = 0,
+  GHOSTTY_RENDER_STATE_ROW_OPTION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyRenderStateRowOption;
 
 /**
@@ -475,7 +481,7 @@ GHOSTTY_API GhosttyResult ghostty_render_state_row_cells_new(
  *
  * @ingroup render
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** Invalid / sentinel value. */
   GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_INVALID = 0,
 
@@ -509,6 +515,7 @@ typedef enum {
    *  color, in which case the caller should use whatever default foreground
    *  color it wants (e.g. the terminal foreground). */
   GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_FG_COLOR = 6,
+  GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyRenderStateRowCellsData;
 
 /**

include/ghostty/vt/screen.h

@@ -57,7 +57,7 @@ typedef uint64_t GhosttyRow;
  *
  * @ingroup screen
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** A single codepoint (may be zero for empty). */
   GHOSTTY_CELL_CONTENT_CODEPOINT = 0,
 
@@ -69,6 +69,7 @@ typedef enum {
 
   /** No text; background color as RGB. */
   GHOSTTY_CELL_CONTENT_BG_COLOR_RGB = 3,
+  GHOSTTY_CELL_CONTENT_TAG_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyCellContentTag;
 
 /**
@@ -78,7 +79,7 @@ typedef enum {
  *
  * @ingroup screen
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** Not a wide character, cell width 1. */
   GHOSTTY_CELL_WIDE_NARROW = 0,
 
@@ -90,6 +91,7 @@ typedef enum {
 
   /** Spacer at end of soft-wrapped line for a wide character. */
   GHOSTTY_CELL_WIDE_SPACER_HEAD = 3,
+  GHOSTTY_CELL_WIDE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyCellWide;
 
 /**
@@ -100,7 +102,7 @@ typedef enum {
  *
  * @ingroup screen
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** Regular output content, such as command output. */
   GHOSTTY_CELL_SEMANTIC_OUTPUT = 0,
 
@@ -109,6 +111,7 @@ typedef enum {
 
   /** Content that is part of a shell prompt. */
   GHOSTTY_CELL_SEMANTIC_PROMPT = 2,
+  GHOSTTY_CELL_SEMANTIC_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyCellSemanticContent;
 
 /**
@@ -119,7 +122,7 @@ typedef enum {
  *
  * @ingroup screen
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** Invalid data type. Never results in any data extraction. */
   GHOSTTY_CELL_DATA_INVALID = 0,
 
@@ -201,6 +204,7 @@ typedef enum {
    * Output type: GhosttyColorRgb *
    */
   GHOSTTY_CELL_DATA_COLOR_RGB = 11,
+  GHOSTTY_CELL_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyCellData;
 
 /**
@@ -211,7 +215,7 @@ typedef enum {
  *
  * @ingroup screen
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** No prompt cells in this row. */
   GHOSTTY_ROW_SEMANTIC_NONE = 0,
 
@@ -220,6 +224,7 @@ typedef enum {
 
   /** Prompt cells exist and this is a continuation line. */
   GHOSTTY_ROW_SEMANTIC_PROMPT_CONTINUATION = 2,
+  GHOSTTY_ROW_SEMANTIC_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyRowSemanticPrompt;
 
 /**
@@ -230,7 +235,7 @@ typedef enum {
  *
  * @ingroup screen
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** Invalid data type. Never results in any data extraction. */
   GHOSTTY_ROW_DATA_INVALID = 0,
 
@@ -289,6 +294,7 @@ typedef enum {
    * Output type: bool *
    */
   GHOSTTY_ROW_DATA_DIRTY = 8,
+  GHOSTTY_ROW_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyRowData;
 
 /**

include/ghostty/vt/sgr.h

@@ -55,7 +55,7 @@ extern "C" {
  *
  * @ingroup sgr
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   GHOSTTY_SGR_ATTR_UNSET = 0,
   GHOSTTY_SGR_ATTR_UNKNOWN = 1,
   GHOSTTY_SGR_ATTR_BOLD = 2,
@@ -87,6 +87,7 @@ typedef enum {
   GHOSTTY_SGR_ATTR_BRIGHT_FG_8 = 28,
   GHOSTTY_SGR_ATTR_BG_256 = 29,
   GHOSTTY_SGR_ATTR_FG_256 = 30,
+  GHOSTTY_SGR_ATTR_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttySgrAttributeTag;
 
 /**
@@ -94,13 +95,14 @@ typedef enum {
  *
  * @ingroup sgr
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   GHOSTTY_SGR_UNDERLINE_NONE = 0,
   GHOSTTY_SGR_UNDERLINE_SINGLE = 1,
   GHOSTTY_SGR_UNDERLINE_DOUBLE = 2,
   GHOSTTY_SGR_UNDERLINE_CURLY = 3,
   GHOSTTY_SGR_UNDERLINE_DOTTED = 4,
   GHOSTTY_SGR_UNDERLINE_DASHED = 5,
+  GHOSTTY_SGR_UNDERLINE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttySgrUnderline;
 
 /**

include/ghostty/vt/size_report.h

@@ -40,7 +40,7 @@ extern "C" {
  *
  * Determines the output format for the terminal size report.
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
     /** In-band size report (mode 2048): ESC [ 48 ; rows ; cols ; height ; width t */
     GHOSTTY_SIZE_REPORT_MODE_2048 = 0,
     /** XTWINOPS text area size in pixels: ESC [ 4 ; height ; width t */
@@ -49,6 +49,7 @@ typedef enum {
     GHOSTTY_SIZE_REPORT_CSI_16_T = 2,
     /** XTWINOPS text area size in characters: ESC [ 8 ; rows ; cols t */
     GHOSTTY_SIZE_REPORT_CSI_18_T = 3,
+    GHOSTTY_SIZE_REPORT_STYLE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttySizeReportStyle;
 
 /**

include/ghostty/vt/style.h

@@ -46,11 +46,12 @@ typedef uint16_t GhosttyStyleId;
  *
  * @ingroup style
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   GHOSTTY_STYLE_COLOR_NONE = 0,
   GHOSTTY_STYLE_COLOR_PALETTE = 1,
   GHOSTTY_STYLE_COLOR_RGB = 2,
-} GhosttyStyleColorTag;
+  GHOSTTY_STYLE_COLOR_TAG_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
+  } GhosttyStyleColorTag;
 
 /**
  * Style color value union.

include/ghostty/vt/sys.h

@@ -88,7 +88,7 @@ typedef bool (*GhosttySysDecodePngFn)(
 /**
  * System option identifiers for ghostty_sys_set().
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
     /**
      * Set the userdata pointer passed to all sys callbacks.
      *
@@ -106,6 +106,7 @@ typedef enum {
      * Input type: GhosttySysDecodePngFn (function pointer, or NULL)
      */
     GHOSTTY_SYS_OPT_DECODE_PNG = 1,
+    GHOSTTY_SYS_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttySysOption;
 
 /**

include/ghostty/vt/terminal.h

@@ -180,7 +180,7 @@ typedef struct {
  *
  * @ingroup terminal
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** Scroll to the top of the scrollback. */
   GHOSTTY_SCROLL_VIEWPORT_TOP,
 
@@ -189,6 +189,7 @@ typedef enum {
 
   /** Scroll by a delta amount (up is negative). */
   GHOSTTY_SCROLL_VIEWPORT_DELTA,
+  GHOSTTY_SCROLL_VIEWPORT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyTerminalScrollViewportTag;
 
 /**
@@ -221,12 +222,13 @@ typedef struct {
  *
  * @ingroup terminal
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** The primary (normal) screen. */
   GHOSTTY_TERMINAL_SCREEN_PRIMARY = 0,
 
   /** The alternate screen. */
   GHOSTTY_TERMINAL_SCREEN_ALTERNATE = 1,
+  GHOSTTY_TERMINAL_SCREEN_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyTerminalScreen;
 
 /**
@@ -394,7 +396,7 @@ typedef GhosttyString (*GhosttyTerminalXtversionFn)(GhosttyTerminal terminal,
  *
  * @ingroup terminal
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /**
    * Opaque userdata pointer passed to all callbacks.
    *
@@ -571,6 +573,7 @@ typedef enum {
    * Input type: bool*
    */
   GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_SHARED_MEM = 18,
+  GHOSTTY_TERMINAL_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyTerminalOption;
 
 /**
@@ -581,7 +584,7 @@ typedef enum {
  *
  * @ingroup terminal
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
   /** Invalid data type. Never results in any data extraction. */
   GHOSTTY_TERMINAL_DATA_INVALID = 0,
 
@@ -846,6 +849,7 @@ typedef enum {
    * Output type: GhosttyKittyGraphics *
    */
   GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS = 30,
+  GHOSTTY_TERMINAL_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyTerminalData;
 
 /**

include/ghostty/vt/types.h

@@ -7,6 +7,7 @@
 #ifndef GHOSTTY_VT_TYPES_H
 #define GHOSTTY_VT_TYPES_H
 
+#include <limits.h>
 #include <stddef.h>
 #include <stdint.h>
 
@@ -32,10 +33,45 @@
 #endif
 #endif
 
+/**
+ * Enum int-sizing helpers.
+ *
+ * The Zig side backs all C enums with c_int, so the C declarations
+ * must use int as their underlying type to maintain ABI compatibility.
+ *
+ * C23 (detected via __STDC_VERSION__ >= 202311L) supports explicit
+ * enum underlying types with `enum : int { ... }`. For pre-C23
+ * compilers, which are free to choose any type that can represent
+ * all values (C11 §6.7.2.2), we add an INT_MAX sentinel as the last
+ * entry to force the compiler to use int.
+ *
+ * INT_MAX is used rather than a fixed constant like 0xFFFFFFFF
+ * because enum constants must have type int (which is signed).
+ * Values above INT_MAX overflow signed int and are a constraint
+ * violation in standard C; compilers that accept them interpret them
+ * as negative values via two's complement, which can collide with
+ * legitimate negative enum values.
+ *
+ * Usage:
+ * @code
+ * typedef enum GHOSTTY_ENUM_TYPED {
+ *     FOO_A = 0,
+ *     FOO_B = 1,
+ *     FOO_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
+ * } Foo;
+ * @endcode
+ */
+#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 202311L
+#define GHOSTTY_ENUM_TYPED : int
+#else
+#define GHOSTTY_ENUM_TYPED
+#endif
+#define GHOSTTY_ENUM_MAX_VALUE INT_MAX
+
 /**
  * Result codes for libghostty-vt operations.
  */
-typedef enum {
+typedef enum GHOSTTY_ENUM_TYPED {
     /** Operation completed successfully */
     GHOSTTY_SUCCESS = 0,
     /** Operation failed due to failed allocation */
@@ -46,6 +82,7 @@ typedef enum {
     GHOSTTY_OUT_OF_SPACE = -3,
     /** The requested value has no value */
     GHOSTTY_NO_VALUE = -4,
+    GHOSTTY_RESULT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyResult;
 
 /* ---- Opaque handles ---- */