lib-vt: expose key encoding as a C API

1 files changed, 638 insertions, 1 deletions

diff --git a/include/ghostty/vt.h b/include/ghostty/vt.h
index 4b930a96f..7815ebb81 100644
--- a/include/ghostty/vt.h
+++ b/include/ghostty/vt.h
@@ -27,6 +27,7 @@
  * @section groups_sec API Reference
  *
  * The API is organized into the following groups:
+ * - @ref key "Key Encoding" - Encode key events into terminal sequences
  * - @ref osc "OSC Parser" - Parse OSC (Operating System Command) sequences
  * - @ref allocator "Memory Management" - Memory management and custom allocators
  *
@@ -319,7 +320,643 @@ typedef struct {
 /** @} */ // end of allocator group
 
 //-------------------------------------------------------------------
-// Functions
+// Key Encoding 
+
+/** @defgroup key Key Encoding
+ *
+ * Utilities for encoding key events into terminal escape sequences,
+ * supporting both legacy encoding as well as Kitty Keyboard Protocol.
+ *
+ * @{
+ */
+
+/**
+ * Opaque handle to a key event.
+ * 
+ * This handle represents a keyboard input event containing information about
+ * the physical key pressed, modifiers, and generated text. The event can be
+ * configured using the `ghostty_key_event_set_*` functions.
+ *
+ * @ingroup key
+ */
+typedef struct GhosttyKeyEvent *GhosttyKeyEvent;
+
+/**
+ * Keyboard input event types.
+ *
+ * @ingroup key
+ */
+typedef enum {
+    /** 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,
+} GhosttyKeyAction;
+
+/**
+ * Keyboard modifier keys bitmask.
+ *
+ * A bitmask representing all keyboard modifiers. This tracks which modifier keys 
+ * are pressed and, where supported by the platform, which side (left or right) 
+ * of each modifier is active.
+ *
+ * Use the GHOSTTY_MODS_* constants to test and set individual modifiers.
+ *
+ * Modifier side bits are only meaningful when the corresponding modifier bit is set.
+ * Not all platforms support distinguishing between left and right modifier 
+ * keys and Ghostty is built to expect that some platforms may not provide this
+ * information.
+ *
+ * @ingroup key
+ */
+typedef uint16_t GhosttyMods;
+
+/** Shift key is pressed */
+#define GHOSTTY_MODS_SHIFT (1 << 0)
+/** Control key is pressed */
+#define GHOSTTY_MODS_CTRL (1 << 1)
+/** Alt/Option key is pressed */
+#define GHOSTTY_MODS_ALT (1 << 2)
+/** Super/Command/Windows key is pressed */
+#define GHOSTTY_MODS_SUPER (1 << 3)
+/** Caps Lock is active */
+#define GHOSTTY_MODS_CAPS_LOCK (1 << 4)
+/** Num Lock is active */
+#define GHOSTTY_MODS_NUM_LOCK (1 << 5)
+
+/**
+ * Right shift is pressed (0 = left, 1 = right).
+ * Only meaningful when GHOSTTY_MODS_SHIFT is set.
+ */
+#define GHOSTTY_MODS_SHIFT_SIDE (1 << 6)
+/**
+ * Right ctrl is pressed (0 = left, 1 = right).
+ * Only meaningful when GHOSTTY_MODS_CTRL is set.
+ */
+#define GHOSTTY_MODS_CTRL_SIDE (1 << 7)
+/**
+ * Right alt is pressed (0 = left, 1 = right).
+ * Only meaningful when GHOSTTY_MODS_ALT is set.
+ */
+#define GHOSTTY_MODS_ALT_SIDE (1 << 8)
+/**
+ * Right super is pressed (0 = left, 1 = right).
+ * Only meaningful when GHOSTTY_MODS_SUPER is set.
+ */
+#define GHOSTTY_MODS_SUPER_SIDE (1 << 9)
+
+/**
+ * Physical key codes.
+ *
+ * The set of key codes that Ghostty is aware of. These represent physical keys 
+ * on the keyboard and are layout-independent. For example, the "a" key on a US 
+ * keyboard is the same as the "ф" key on a Russian keyboard, but both will 
+ * report the same key_a value.
+ *
+ * Layout-dependent strings are provided separately as UTF-8 text and are produced 
+ * by the platform. These values are based on the W3C UI Events KeyboardEvent code 
+ * standard. See: https://www.w3.org/TR/uievents-code
+ *
+ * @ingroup key
+ */
+typedef enum {
+    GHOSTTY_KEY_UNIDENTIFIED = 0,
+
+    // Writing System Keys (W3C § 3.1.1)
+    GHOSTTY_KEY_BACKQUOTE,
+    GHOSTTY_KEY_BACKSLASH,
+    GHOSTTY_KEY_BRACKET_LEFT,
+    GHOSTTY_KEY_BRACKET_RIGHT,
+    GHOSTTY_KEY_COMMA,
+    GHOSTTY_KEY_DIGIT_0,
+    GHOSTTY_KEY_DIGIT_1,
+    GHOSTTY_KEY_DIGIT_2,
+    GHOSTTY_KEY_DIGIT_3,
+    GHOSTTY_KEY_DIGIT_4,
+    GHOSTTY_KEY_DIGIT_5,
+    GHOSTTY_KEY_DIGIT_6,
+    GHOSTTY_KEY_DIGIT_7,
+    GHOSTTY_KEY_DIGIT_8,
+    GHOSTTY_KEY_DIGIT_9,
+    GHOSTTY_KEY_EQUAL,
+    GHOSTTY_KEY_INTL_BACKSLASH,
+    GHOSTTY_KEY_INTL_RO,
+    GHOSTTY_KEY_INTL_YEN,
+    GHOSTTY_KEY_A,
+    GHOSTTY_KEY_B,
+    GHOSTTY_KEY_C,
+    GHOSTTY_KEY_D,
+    GHOSTTY_KEY_E,
+    GHOSTTY_KEY_F,
+    GHOSTTY_KEY_G,
+    GHOSTTY_KEY_H,
+    GHOSTTY_KEY_I,
+    GHOSTTY_KEY_J,
+    GHOSTTY_KEY_K,
+    GHOSTTY_KEY_L,
+    GHOSTTY_KEY_M,
+    GHOSTTY_KEY_N,
+    GHOSTTY_KEY_O,
+    GHOSTTY_KEY_P,
+    GHOSTTY_KEY_Q,
+    GHOSTTY_KEY_R,
+    GHOSTTY_KEY_S,
+    GHOSTTY_KEY_T,
+    GHOSTTY_KEY_U,
+    GHOSTTY_KEY_V,
+    GHOSTTY_KEY_W,
+    GHOSTTY_KEY_X,
+    GHOSTTY_KEY_Y,
+    GHOSTTY_KEY_Z,
+    GHOSTTY_KEY_MINUS,
+    GHOSTTY_KEY_PERIOD,
+    GHOSTTY_KEY_QUOTE,
+    GHOSTTY_KEY_SEMICOLON,
+    GHOSTTY_KEY_SLASH,
+
+    // Functional Keys (W3C § 3.1.2)
+    GHOSTTY_KEY_ALT_LEFT,
+    GHOSTTY_KEY_ALT_RIGHT,
+    GHOSTTY_KEY_BACKSPACE,
+    GHOSTTY_KEY_CAPS_LOCK,
+    GHOSTTY_KEY_CONTEXT_MENU,
+    GHOSTTY_KEY_CONTROL_LEFT,
+    GHOSTTY_KEY_CONTROL_RIGHT,
+    GHOSTTY_KEY_ENTER,
+    GHOSTTY_KEY_META_LEFT,
+    GHOSTTY_KEY_META_RIGHT,
+    GHOSTTY_KEY_SHIFT_LEFT,
+    GHOSTTY_KEY_SHIFT_RIGHT,
+    GHOSTTY_KEY_SPACE,
+    GHOSTTY_KEY_TAB,
+    GHOSTTY_KEY_CONVERT,
+    GHOSTTY_KEY_KANA_MODE,
+    GHOSTTY_KEY_NON_CONVERT,
+
+    // Control Pad Section (W3C § 3.2)
+    GHOSTTY_KEY_DELETE,
+    GHOSTTY_KEY_END,
+    GHOSTTY_KEY_HELP,
+    GHOSTTY_KEY_HOME,
+    GHOSTTY_KEY_INSERT,
+    GHOSTTY_KEY_PAGE_DOWN,
+    GHOSTTY_KEY_PAGE_UP,
+
+    // Arrow Pad Section (W3C § 3.3)
+    GHOSTTY_KEY_ARROW_DOWN,
+    GHOSTTY_KEY_ARROW_LEFT,
+    GHOSTTY_KEY_ARROW_RIGHT,
+    GHOSTTY_KEY_ARROW_UP,
+
+    // Numpad Section (W3C § 3.4)
+    GHOSTTY_KEY_NUM_LOCK,
+    GHOSTTY_KEY_NUMPAD_0,
+    GHOSTTY_KEY_NUMPAD_1,
+    GHOSTTY_KEY_NUMPAD_2,
+    GHOSTTY_KEY_NUMPAD_3,
+    GHOSTTY_KEY_NUMPAD_4,
+    GHOSTTY_KEY_NUMPAD_5,
+    GHOSTTY_KEY_NUMPAD_6,
+    GHOSTTY_KEY_NUMPAD_7,
+    GHOSTTY_KEY_NUMPAD_8,
+    GHOSTTY_KEY_NUMPAD_9,
+    GHOSTTY_KEY_NUMPAD_ADD,
+    GHOSTTY_KEY_NUMPAD_BACKSPACE,
+    GHOSTTY_KEY_NUMPAD_CLEAR,
+    GHOSTTY_KEY_NUMPAD_CLEAR_ENTRY,
+    GHOSTTY_KEY_NUMPAD_COMMA,
+    GHOSTTY_KEY_NUMPAD_DECIMAL,
+    GHOSTTY_KEY_NUMPAD_DIVIDE,
+    GHOSTTY_KEY_NUMPAD_ENTER,
+    GHOSTTY_KEY_NUMPAD_EQUAL,
+    GHOSTTY_KEY_NUMPAD_MEMORY_ADD,
+    GHOSTTY_KEY_NUMPAD_MEMORY_CLEAR,
+    GHOSTTY_KEY_NUMPAD_MEMORY_RECALL,
+    GHOSTTY_KEY_NUMPAD_MEMORY_STORE,
+    GHOSTTY_KEY_NUMPAD_MEMORY_SUBTRACT,
+    GHOSTTY_KEY_NUMPAD_MULTIPLY,
+    GHOSTTY_KEY_NUMPAD_PAREN_LEFT,
+    GHOSTTY_KEY_NUMPAD_PAREN_RIGHT,
+    GHOSTTY_KEY_NUMPAD_SUBTRACT,
+    GHOSTTY_KEY_NUMPAD_SEPARATOR,
+    GHOSTTY_KEY_NUMPAD_UP,
+    GHOSTTY_KEY_NUMPAD_DOWN,
+    GHOSTTY_KEY_NUMPAD_RIGHT,
+    GHOSTTY_KEY_NUMPAD_LEFT,
+    GHOSTTY_KEY_NUMPAD_BEGIN,
+    GHOSTTY_KEY_NUMPAD_HOME,
+    GHOSTTY_KEY_NUMPAD_END,
+    GHOSTTY_KEY_NUMPAD_INSERT,
+    GHOSTTY_KEY_NUMPAD_DELETE,
+    GHOSTTY_KEY_NUMPAD_PAGE_UP,
+    GHOSTTY_KEY_NUMPAD_PAGE_DOWN,
+
+    // Function Section (W3C § 3.5)
+    GHOSTTY_KEY_ESCAPE,
+    GHOSTTY_KEY_F1,
+    GHOSTTY_KEY_F2,
+    GHOSTTY_KEY_F3,
+    GHOSTTY_KEY_F4,
+    GHOSTTY_KEY_F5,
+    GHOSTTY_KEY_F6,
+    GHOSTTY_KEY_F7,
+    GHOSTTY_KEY_F8,
+    GHOSTTY_KEY_F9,
+    GHOSTTY_KEY_F10,
+    GHOSTTY_KEY_F11,
+    GHOSTTY_KEY_F12,
+    GHOSTTY_KEY_F13,
+    GHOSTTY_KEY_F14,
+    GHOSTTY_KEY_F15,
+    GHOSTTY_KEY_F16,
+    GHOSTTY_KEY_F17,
+    GHOSTTY_KEY_F18,
+    GHOSTTY_KEY_F19,
+    GHOSTTY_KEY_F20,
+    GHOSTTY_KEY_F21,
+    GHOSTTY_KEY_F22,
+    GHOSTTY_KEY_F23,
+    GHOSTTY_KEY_F24,
+    GHOSTTY_KEY_F25,
+    GHOSTTY_KEY_FN,
+    GHOSTTY_KEY_FN_LOCK,
+    GHOSTTY_KEY_PRINT_SCREEN,
+    GHOSTTY_KEY_SCROLL_LOCK,
+    GHOSTTY_KEY_PAUSE,
+
+    // Media Keys (W3C § 3.6)
+    GHOSTTY_KEY_BROWSER_BACK,
+    GHOSTTY_KEY_BROWSER_FAVORITES,
+    GHOSTTY_KEY_BROWSER_FORWARD,
+    GHOSTTY_KEY_BROWSER_HOME,
+    GHOSTTY_KEY_BROWSER_REFRESH,
+    GHOSTTY_KEY_BROWSER_SEARCH,
+    GHOSTTY_KEY_BROWSER_STOP,
+    GHOSTTY_KEY_EJECT,
+    GHOSTTY_KEY_LAUNCH_APP_1,
+    GHOSTTY_KEY_LAUNCH_APP_2,
+    GHOSTTY_KEY_LAUNCH_MAIL,
+    GHOSTTY_KEY_MEDIA_PLAY_PAUSE,
+    GHOSTTY_KEY_MEDIA_SELECT,
+    GHOSTTY_KEY_MEDIA_STOP,
+    GHOSTTY_KEY_MEDIA_TRACK_NEXT,
+    GHOSTTY_KEY_MEDIA_TRACK_PREVIOUS,
+    GHOSTTY_KEY_POWER,
+    GHOSTTY_KEY_SLEEP,
+    GHOSTTY_KEY_AUDIO_VOLUME_DOWN,
+    GHOSTTY_KEY_AUDIO_VOLUME_MUTE,
+    GHOSTTY_KEY_AUDIO_VOLUME_UP,
+    GHOSTTY_KEY_WAKE_UP,
+
+    // Legacy, Non-standard, and Special Keys (W3C § 3.7)
+    GHOSTTY_KEY_COPY,
+    GHOSTTY_KEY_CUT,
+    GHOSTTY_KEY_PASTE,
+} GhosttyKey;
+
+/**
+ * Kitty keyboard protocol flags.
+ *
+ * Bitflags representing the various modes of the Kitty keyboard protocol.
+ * These can be combined using bitwise OR operations. Valid values all
+ * start with `GHOSTTY_KITTY_KEY_`.
+ *
+ * @ingroup key
+ */
+typedef uint8_t GhosttyKittyKeyFlags;
+
+/** Kitty keyboard protocol disabled (all flags off) */
+#define GHOSTTY_KITTY_KEY_DISABLED 0
+
+/** Disambiguate escape codes */
+#define GHOSTTY_KITTY_KEY_DISAMBIGUATE (1 << 0)
+
+/** Report key press and release events */
+#define GHOSTTY_KITTY_KEY_REPORT_EVENTS (1 << 1)
+
+/** Report alternate key codes */
+#define GHOSTTY_KITTY_KEY_REPORT_ALTERNATES (1 << 2)
+
+/** Report all key events including those normally handled by the terminal */
+#define GHOSTTY_KITTY_KEY_REPORT_ALL (1 << 3)
+
+/** Report associated text with key events */
+#define GHOSTTY_KITTY_KEY_REPORT_ASSOCIATED (1 << 4)
+
+/** All Kitty keyboard protocol flags enabled */
+#define GHOSTTY_KITTY_KEY_ALL (GHOSTTY_KITTY_KEY_DISAMBIGUATE | GHOSTTY_KITTY_KEY_REPORT_EVENTS | GHOSTTY_KITTY_KEY_REPORT_ALTERNATES | GHOSTTY_KITTY_KEY_REPORT_ALL | GHOSTTY_KITTY_KEY_REPORT_ASSOCIATED)
+
+/**
+ * macOS option key behavior.
+ *
+ * Determines whether the "option" key on macOS is treated as "alt" or not.
+ * See the Ghostty `macos-option-as-alt` configuration option for more details.
+ *
+ * @ingroup key
+ */
+typedef enum {
+    /** Option key is not treated as alt */
+    GHOSTTY_OPTION_AS_ALT_FALSE = 0,
+    /** Option key is treated as alt */
+    GHOSTTY_OPTION_AS_ALT_TRUE = 1,
+    /** Only left option key is treated as alt */
+    GHOSTTY_OPTION_AS_ALT_LEFT = 2,
+    /** Only right option key is treated as alt */
+    GHOSTTY_OPTION_AS_ALT_RIGHT = 3,
+} GhosttyOptionAsAlt;
+
+/**
+ * Create a new key event instance.
+ * 
+ * Creates a new key event with default values. The event must be freed using
+ * ghostty_key_event_free() when no longer needed.
+ * 
+ * @param allocator Pointer to the allocator to use for memory management, or NULL to use the default allocator
+ * @param event Pointer to store the created key event handle
+ * @return GHOSTTY_SUCCESS on success, or an error code on failure
+ * 
+ * @ingroup key
+ */
+GhosttyResult ghostty_key_event_new(const GhosttyAllocator *allocator, GhosttyKeyEvent *event);
+
+/**
+ * Free a key event instance.
+ * 
+ * Releases all resources associated with the key event. After this call,
+ * the event handle becomes invalid and must not be used.
+ * 
+ * @param event The key event handle to free (may be NULL)
+ * 
+ * @ingroup key
+ */
+void ghostty_key_event_free(GhosttyKeyEvent event);
+
+/**
+ * Set the key action (press, release, repeat).
+ *
+ * @param event The key event handle, must not be NULL
+ * @param action The action to set
+ *
+ * @ingroup key
+ */
+void ghostty_key_event_set_action(GhosttyKeyEvent event, GhosttyKeyAction action);
+
+/**
+ * Get the key action (press, release, repeat).
+ *
+ * @param event The key event handle, must not be NULL
+ * @return The key action
+ *
+ * @ingroup key
+ */
+GhosttyKeyAction ghostty_key_event_get_action(GhosttyKeyEvent event);
+
+/**
+ * Set the physical key code.
+ *
+ * @param event The key event handle, must not be NULL
+ * @param key The physical key code to set
+ *
+ * @ingroup key
+ */
+void ghostty_key_event_set_key(GhosttyKeyEvent event, GhosttyKey key);
+
+/**
+ * Get the physical key code.
+ *
+ * @param event The key event handle, must not be NULL
+ * @return The physical key code
+ *
+ * @ingroup key
+ */
+GhosttyKey ghostty_key_event_get_key(GhosttyKeyEvent event);
+
+/**
+ * Set the modifier keys bitmask.
+ *
+ * @param event The key event handle, must not be NULL
+ * @param mods The modifier keys bitmask to set
+ *
+ * @ingroup key
+ */
+void ghostty_key_event_set_mods(GhosttyKeyEvent event, GhosttyMods mods);
+
+/**
+ * Get the modifier keys bitmask.
+ *
+ * @param event The key event handle, must not be NULL
+ * @return The modifier keys bitmask
+ *
+ * @ingroup key
+ */
+GhosttyMods ghostty_key_event_get_mods(GhosttyKeyEvent event);
+
+/**
+ * Set the consumed modifiers bitmask.
+ *
+ * @param event The key event handle, must not be NULL
+ * @param consumed_mods The consumed modifiers bitmask to set
+ *
+ * @ingroup key
+ */
+void ghostty_key_event_set_consumed_mods(GhosttyKeyEvent event, GhosttyMods consumed_mods);
+
+/**
+ * Get the consumed modifiers bitmask.
+ *
+ * @param event The key event handle, must not be NULL
+ * @return The consumed modifiers bitmask
+ *
+ * @ingroup key
+ */
+GhosttyMods ghostty_key_event_get_consumed_mods(GhosttyKeyEvent event);
+
+/**
+ * Set whether the key event is part of a composition sequence.
+ *
+ * @param event The key event handle, must not be NULL
+ * @param composing Whether the key event is part of a composition sequence
+ *
+ * @ingroup key
+ */
+void ghostty_key_event_set_composing(GhosttyKeyEvent event, bool composing);
+
+/**
+ * Get whether the key event is part of a composition sequence.
+ *
+ * @param event The key event handle, must not be NULL
+ * @return Whether the key event is part of a composition sequence
+ *
+ * @ingroup key
+ */
+bool ghostty_key_event_get_composing(GhosttyKeyEvent event);
+
+/**
+ * Set the UTF-8 text generated by the key event.
+ *
+ * The key event does NOT take ownership of the text pointer. The caller
+ * must ensure the string remains valid for the lifetime needed by the event.
+ *
+ * @param event The key event handle, must not be NULL
+ * @param utf8 The UTF-8 text to set (or NULL for empty)
+ * @param len Length of the UTF-8 text in bytes
+ *
+ * @ingroup key
+ */
+void ghostty_key_event_set_utf8(GhosttyKeyEvent event, const char *utf8, size_t len);
+
+/**
+ * Get the UTF-8 text generated by the key event.
+ *
+ * The returned pointer is valid until the event is freed or the UTF-8 text is modified.
+ *
+ * @param event The key event handle, must not be NULL
+ * @param len Pointer to store the length of the UTF-8 text in bytes (may be NULL)
+ * @return The UTF-8 text (or NULL for empty)
+ *
+ * @ingroup key
+ */
+const char *ghostty_key_event_get_utf8(GhosttyKeyEvent event, size_t *len);
+
+/**
+ * Set the unshifted Unicode codepoint.
+ *
+ * @param event The key event handle, must not be NULL
+ * @param codepoint The unshifted Unicode codepoint to set
+ *
+ * @ingroup key
+ */
+void ghostty_key_event_set_unshifted_codepoint(GhosttyKeyEvent event, uint32_t codepoint);
+
+/**
+ * Get the unshifted Unicode codepoint.
+ *
+ * @param event The key event handle, must not be NULL
+ * @return The unshifted Unicode codepoint
+ *
+ * @ingroup key
+ */
+uint32_t ghostty_key_event_get_unshifted_codepoint(GhosttyKeyEvent event);
+
+/**
+ * Opaque handle to a key encoder instance.
+ *
+ * This handle represents a key encoder that converts key events into terminal
+ * escape sequences. The encoder supports both legacy encoding and the Kitty
+ * Keyboard Protocol, depending on the options set.
+ *
+ * @ingroup key
+ */
+typedef struct GhosttyKeyEncoder *GhosttyKeyEncoder;
+
+/**
+ * Key encoder option identifiers.
+ *
+ * These values are used with ghostty_key_encoder_setopt() to configure
+ * the behavior of the key encoder.
+ *
+ * @ingroup key
+ */
+typedef enum {
+    /** Terminal DEC mode 1: cursor key application mode (value: bool) */
+    GHOSTTY_KEY_ENCODER_OPT_CURSOR_KEY_APPLICATION = 0,
+    
+    /** Terminal DEC mode 66: keypad key application mode (value: bool) */
+    GHOSTTY_KEY_ENCODER_OPT_KEYPAD_KEY_APPLICATION = 1,
+    
+    /** Terminal DEC mode 1035: ignore keypad with numlock (value: bool) */
+    GHOSTTY_KEY_ENCODER_OPT_IGNORE_KEYPAD_WITH_NUMLOCK = 2,
+    
+    /** Terminal DEC mode 1036: alt sends escape prefix (value: bool) */
+    GHOSTTY_KEY_ENCODER_OPT_ALT_ESC_PREFIX = 3,
+    
+    /** xterm modifyOtherKeys mode 2 (value: bool) */
+    GHOSTTY_KEY_ENCODER_OPT_MODIFY_OTHER_KEYS_STATE_2 = 4,
+    
+    /** Kitty keyboard protocol flags (value: GhosttyKittyKeyFlags bitmask) */
+    GHOSTTY_KEY_ENCODER_OPT_KITTY_FLAGS = 5,
+    
+    /** macOS option-as-alt setting (value: GhosttyOptionAsAlt) */
+    GHOSTTY_KEY_ENCODER_OPT_MACOS_OPTION_AS_ALT = 6,
+} GhosttyKeyEncoderOption;
+
+/**
+ * Create a new key encoder instance.
+ *
+ * Creates a new key encoder with default options. The encoder can be configured
+ * using ghostty_key_encoder_setopt() and must be freed using
+ * ghostty_key_encoder_free() when no longer needed.
+ *
+ * @param allocator Pointer to the allocator to use for memory management, or NULL to use the default allocator
+ * @param encoder Pointer to store the created encoder handle
+ * @return GHOSTTY_SUCCESS on success, or an error code on failure
+ *
+ * @ingroup key
+ */
+GhosttyResult ghostty_key_encoder_new(const GhosttyAllocator *allocator, GhosttyKeyEncoder *encoder);
+
+/**
+ * Free a key encoder instance.
+ *
+ * Releases all resources associated with the key encoder. After this call,
+ * the encoder handle becomes invalid and must not be used.
+ *
+ * @param encoder The encoder handle to free (may be NULL)
+ *
+ * @ingroup key
+ */
+void ghostty_key_encoder_free(GhosttyKeyEncoder encoder);
+
+/**
+ * Set an option on the key encoder.
+ *
+ * Configures the behavior of the key encoder. Options control various aspects
+ * of encoding such as terminal modes (cursor key application mode, keypad mode),
+ * protocol selection (Kitty keyboard protocol flags), and platform-specific
+ * behaviors (macOS option-as-alt).
+ *
+ * A null pointer value does nothing. It does not reset the value to the
+ * default. The setopt call will do nothing.
+ *
+ * @param encoder The encoder handle, must not be NULL
+ * @param option The option to set
+ * @param value Pointer to the value to set (type depends on the option)
+ *
+ * @ingroup key
+ */
+void ghostty_key_encoder_setopt(GhosttyKeyEncoder encoder, GhosttyKeyEncoderOption option, const void *value);
+
+/**
+ * Encode a key event into a terminal escape sequence.
+ *
+ * Converts a key event into the appropriate terminal escape sequence based on
+ * the encoder's current options. The sequence is written to the provided buffer.
+ *
+ * Not all key events produce output. For example, unmodified modifier keys
+ * typically don't generate escape sequences. Check the out_len parameter to
+ * determine if any data was written.
+ *
+ * If the output buffer is too small, this function returns GHOSTTY_OUT_OF_MEMORY
+ * and out_len will contain the required buffer size. The caller can then
+ * allocate a larger buffer and call the function again.
+ *
+ * @param encoder The encoder handle, must not be NULL
+ * @param event The key event to encode, must not be NULL
+ * @param out_buf Buffer to write the encoded sequence to
+ * @param out_buf_size Size of the output buffer in bytes
+ * @param out_len Pointer to store the number of bytes written (may be NULL)
+ * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY if buffer too small, or other error code
+ *
+ * @ingroup key
+ */
+GhosttyResult ghostty_key_encoder_encode(GhosttyKeyEncoder encoder, GhosttyKeyEvent event, char *out_buf, size_t out_buf_size, size_t *out_len);
+
+/** @} */ // end of key group
+
+//-------------------------------------------------------------------
+// OSC Parser
 
 /** @defgroup osc OSC Parser
  *