vt: add mouse encoding C API

Expose the internal mouse encoding functionality through the C API,
following the same pattern as the existing key encoding API. This
allows external consumers of libvt to encode mouse events into
terminal escape sequences (X10, UTF-8, SGR, URxvt, SGR-Pixels).

The API is split into two opaque handle types: GhosttyMouseEvent
for building normalized mouse events (action, button, modifiers,
position) and GhosttyMouseEncoder for converting those events into
escape sequences. The encoder is configured via a setopt interface
supporting tracking mode, output format, renderer geometry, button
state, and optional motion deduplication by last cell.

Encoder state can also be bulk-configured from a terminal handle
via ghostty_mouse_encoder_setopt_from_terminal. Failed encodes due
to insufficient buffer space report the required size without
mutating deduplication state.

include/ghostty/vt.h

@@ -31,6 +31,7 @@
  * - @ref terminal "Terminal" - Complete terminal emulator state and rendering
  * - @ref formatter "Formatter" - Format terminal content as plain text, VT sequences, or HTML
  * - @ref key "Key Encoding" - Encode key events into terminal sequences
+ * - @ref mouse "Mouse Encoding" - Encode mouse events into terminal sequences
  * - @ref osc "OSC Parser" - Parse OSC (Operating System Command) sequences
  * - @ref sgr "SGR Parser" - Parse SGR (Select Graphic Rendition) sequences
  * - @ref paste "Paste Utilities" - Validate paste data safety
@@ -88,6 +89,7 @@ extern "C" {
 #include <ghostty/vt/osc.h>
 #include <ghostty/vt/sgr.h>
 #include <ghostty/vt/key.h>
+#include <ghostty/vt/mouse.h>
 #include <ghostty/vt/paste.h>
 #include <ghostty/vt/wasm.h>
 

include/ghostty/vt/mouse.h

@@ -0,0 +1,35 @@
+/**
+ * @file mouse.h
+ *
+ * Mouse encoding module - encode mouse events into terminal escape sequences.
+ */
+
+#ifndef GHOSTTY_VT_MOUSE_H
+#define GHOSTTY_VT_MOUSE_H
+
+/** @defgroup mouse Mouse Encoding
+ *
+ * Utilities for encoding mouse events into terminal escape sequences,
+ * supporting X10, UTF-8, SGR, URxvt, and SGR-Pixels mouse protocols.
+ *
+ * ## Basic Usage
+ *
+ * 1. Create an encoder instance with ghostty_mouse_encoder_new().
+ * 2. Configure encoder options with ghostty_mouse_encoder_setopt() or
+ *    ghostty_mouse_encoder_setopt_from_terminal().
+ * 3. For each mouse event:
+ *    - Create a mouse event with ghostty_mouse_event_new().
+ *    - Set event properties (action, button, modifiers, position).
+ *    - Encode with ghostty_mouse_encoder_encode().
+ *    - Free the event with ghostty_mouse_event_free() or reuse it.
+ * 4. Free the encoder with ghostty_mouse_encoder_free() when done.
+ *
+ * @{
+ */
+
+#include <ghostty/vt/mouse/event.h>
+#include <ghostty/vt/mouse/encoder.h>
+
+/** @} */
+
+#endif /* GHOSTTY_VT_MOUSE_H */

include/ghostty/vt/mouse/encoder.h

@@ -0,0 +1,211 @@
+/**
+ * @file encoder.h
+ *
+ * Mouse event encoding to terminal escape sequences.
+ */
+
+#ifndef GHOSTTY_VT_MOUSE_ENCODER_H
+#define GHOSTTY_VT_MOUSE_ENCODER_H
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <ghostty/vt/allocator.h>
+#include <ghostty/vt/mouse/event.h>
+#include <ghostty/vt/terminal.h>
+#include <ghostty/vt/types.h>
+
+/**
+ * Opaque handle to a mouse encoder instance.
+ *
+ * This handle represents a mouse encoder that converts normalized
+ * mouse events into terminal escape sequences.
+ *
+ * @ingroup mouse
+ */
+typedef struct GhosttyMouseEncoder *GhosttyMouseEncoder;
+
+/**
+ * Mouse tracking mode.
+ *
+ * @ingroup mouse
+ */
+typedef enum {
+  /** Mouse reporting disabled. */
+  GHOSTTY_MOUSE_TRACKING_NONE = 0,
+
+  /** X10 mouse mode. */
+  GHOSTTY_MOUSE_TRACKING_X10 = 1,
+
+  /** Normal mouse mode (button press/release only). */
+  GHOSTTY_MOUSE_TRACKING_NORMAL = 2,
+
+  /** Button-event tracking mode. */
+  GHOSTTY_MOUSE_TRACKING_BUTTON = 3,
+
+  /** Any-event tracking mode. */
+  GHOSTTY_MOUSE_TRACKING_ANY = 4,
+} GhosttyMouseTrackingMode;
+
+/**
+ * Mouse output format.
+ *
+ * @ingroup mouse
+ */
+typedef enum {
+  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,
+} GhosttyMouseFormat;
+
+/**
+ * Mouse encoder size and geometry context.
+ *
+ * This describes the rendered terminal geometry used to convert
+ * surface-space positions into encoded coordinates.
+ *
+ * @ingroup mouse
+ */
+typedef struct {
+  /** Size of this struct in bytes. Must be set to sizeof(GhosttyMouseEncoderSize). */
+  size_t size;
+
+  /** Full screen width in pixels. */
+  uint32_t screen_width;
+
+  /** Full screen height in pixels. */
+  uint32_t screen_height;
+
+  /** Cell width in pixels. Must be non-zero. */
+  uint32_t cell_width;
+
+  /** Cell height in pixels. Must be non-zero. */
+  uint32_t cell_height;
+
+  /** Top padding in pixels. */
+  uint32_t padding_top;
+
+  /** Bottom padding in pixels. */
+  uint32_t padding_bottom;
+
+  /** Right padding in pixels. */
+  uint32_t padding_right;
+
+  /** Left padding in pixels. */
+  uint32_t padding_left;
+} GhosttyMouseEncoderSize;
+
+/**
+ * Mouse encoder option identifiers.
+ *
+ * These values are used with ghostty_mouse_encoder_setopt() to configure
+ * the behavior of the mouse encoder.
+ *
+ * @ingroup mouse
+ */
+typedef enum {
+  /** Mouse tracking mode (value: GhosttyMouseTrackingMode). */
+  GHOSTTY_MOUSE_ENCODER_OPT_EVENT = 0,
+
+  /** Mouse output format (value: GhosttyMouseFormat). */
+  GHOSTTY_MOUSE_ENCODER_OPT_FORMAT = 1,
+
+  /** Renderer size context (value: GhosttyMouseEncoderSize). */
+  GHOSTTY_MOUSE_ENCODER_OPT_SIZE = 2,
+
+  /** Whether any mouse button is currently pressed (value: bool). */
+  GHOSTTY_MOUSE_ENCODER_OPT_ANY_BUTTON_PRESSED = 3,
+
+  /** Whether to enable motion deduplication by last cell (value: bool). */
+  GHOSTTY_MOUSE_ENCODER_OPT_TRACK_LAST_CELL = 4,
+} GhosttyMouseEncoderOption;
+
+/**
+ * Create a new mouse encoder instance.
+ *
+ * @param allocator Pointer to allocator, 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 mouse
+ */
+GhosttyResult ghostty_mouse_encoder_new(const GhosttyAllocator *allocator,
+                                        GhosttyMouseEncoder *encoder);
+
+/**
+ * Free a mouse encoder instance.
+ *
+ * @param encoder The encoder handle to free (may be NULL)
+ *
+ * @ingroup mouse
+ */
+void ghostty_mouse_encoder_free(GhosttyMouseEncoder encoder);
+
+/**
+ * Set an option on the mouse encoder.
+ *
+ * A null pointer value does nothing. It does not reset to defaults.
+ *
+ * @param encoder The encoder handle, must not be NULL
+ * @param option The option to set
+ * @param value Pointer to option value (type depends on option)
+ *
+ * @ingroup mouse
+ */
+void ghostty_mouse_encoder_setopt(GhosttyMouseEncoder encoder,
+                                  GhosttyMouseEncoderOption option,
+                                  const void *value);
+
+/**
+ * Set encoder options from a terminal's current state.
+ *
+ * This sets tracking mode and output format from terminal state.
+ * It does not modify size or any-button state.
+ *
+ * @param encoder The encoder handle, must not be NULL
+ * @param terminal The terminal handle, must not be NULL
+ *
+ * @ingroup mouse
+ */
+void ghostty_mouse_encoder_setopt_from_terminal(GhosttyMouseEncoder encoder,
+                                                GhosttyTerminal terminal);
+
+/**
+ * Reset internal encoder state.
+ *
+ * This clears motion deduplication state (last tracked cell).
+ *
+ * @param encoder The encoder handle (may be NULL)
+ *
+ * @ingroup mouse
+ */
+void ghostty_mouse_encoder_reset(GhosttyMouseEncoder encoder);
+
+/**
+ * Encode a mouse event into a terminal escape sequence.
+ *
+ * Not all mouse events produce output. In such cases this returns
+ * GHOSTTY_SUCCESS with out_len set to 0.
+ *
+ * If the output buffer is too small, this returns GHOSTTY_OUT_OF_MEMORY
+ * and out_len contains the required size.
+ *
+ * @param encoder The encoder handle, must not be NULL
+ * @param event The mouse event to encode, must not be NULL
+ * @param out_buf Buffer to write encoded bytes to, or NULL to query required size
+ * @param out_buf_size Size of out_buf in bytes
+ * @param out_len Pointer to store bytes written (or required bytes on failure)
+ * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY if buffer is too small,
+ *         or another error code
+ *
+ * @ingroup mouse
+ */
+GhosttyResult ghostty_mouse_encoder_encode(GhosttyMouseEncoder encoder,
+                                           GhosttyMouseEvent event,
+                                           char *out_buf,
+                                           size_t out_buf_size,
+                                           size_t *out_len);
+
+#endif /* GHOSTTY_VT_MOUSE_ENCODER_H */

include/ghostty/vt/mouse/event.h

@@ -0,0 +1,193 @@
+/**
+ * @file event.h
+ *
+ * Mouse event representation and manipulation.
+ */
+
+#ifndef GHOSTTY_VT_MOUSE_EVENT_H
+#define GHOSTTY_VT_MOUSE_EVENT_H
+
+#include <stdbool.h>
+#include <ghostty/vt/allocator.h>
+#include <ghostty/vt/key/event.h>
+#include <ghostty/vt/types.h>
+
+/**
+ * Opaque handle to a mouse event.
+ *
+ * This handle represents a normalized mouse input event containing
+ * action, button, modifiers, and surface-space position.
+ *
+ * @ingroup mouse
+ */
+typedef struct GhosttyMouseEvent *GhosttyMouseEvent;
+
+/**
+ * Mouse event action type.
+ *
+ * @ingroup mouse
+ */
+typedef enum {
+  /** Mouse button was pressed. */
+  GHOSTTY_MOUSE_ACTION_PRESS = 0,
+
+  /** Mouse button was released. */
+  GHOSTTY_MOUSE_ACTION_RELEASE = 1,
+
+  /** Mouse moved. */
+  GHOSTTY_MOUSE_ACTION_MOTION = 2,
+} GhosttyMouseAction;
+
+/**
+ * Mouse button identity.
+ *
+ * @ingroup mouse
+ */
+typedef enum {
+  GHOSTTY_MOUSE_BUTTON_UNKNOWN = 0,
+  GHOSTTY_MOUSE_BUTTON_LEFT = 1,
+  GHOSTTY_MOUSE_BUTTON_RIGHT = 2,
+  GHOSTTY_MOUSE_BUTTON_MIDDLE = 3,
+  GHOSTTY_MOUSE_BUTTON_FOUR = 4,
+  GHOSTTY_MOUSE_BUTTON_FIVE = 5,
+  GHOSTTY_MOUSE_BUTTON_SIX = 6,
+  GHOSTTY_MOUSE_BUTTON_SEVEN = 7,
+  GHOSTTY_MOUSE_BUTTON_EIGHT = 8,
+  GHOSTTY_MOUSE_BUTTON_NINE = 9,
+  GHOSTTY_MOUSE_BUTTON_TEN = 10,
+  GHOSTTY_MOUSE_BUTTON_ELEVEN = 11,
+} GhosttyMouseButton;
+
+/**
+ * Mouse position in surface-space pixels.
+ *
+ * @ingroup mouse
+ */
+typedef struct {
+  float x;
+  float y;
+} GhosttyMousePosition;
+
+/**
+ * Create a new mouse event instance.
+ *
+ * @param allocator Pointer to allocator, or NULL to use the default allocator
+ * @param event Pointer to store the created event handle
+ * @return GHOSTTY_SUCCESS on success, or an error code on failure
+ *
+ * @ingroup mouse
+ */
+GhosttyResult ghostty_mouse_event_new(const GhosttyAllocator *allocator,
+                                      GhosttyMouseEvent *event);
+
+/**
+ * Free a mouse event instance.
+ *
+ * @param event The mouse event handle to free (may be NULL)
+ *
+ * @ingroup mouse
+ */
+void ghostty_mouse_event_free(GhosttyMouseEvent event);
+
+/**
+ * Set the event action.
+ *
+ * @param event The event handle, must not be NULL
+ * @param action The action to set
+ *
+ * @ingroup mouse
+ */
+void ghostty_mouse_event_set_action(GhosttyMouseEvent event,
+                                    GhosttyMouseAction action);
+
+/**
+ * Get the event action.
+ *
+ * @param event The event handle, must not be NULL
+ * @return The event action
+ *
+ * @ingroup mouse
+ */
+GhosttyMouseAction ghostty_mouse_event_get_action(GhosttyMouseEvent event);
+
+/**
+ * Set the event button.
+ *
+ * This sets a concrete button identity for the event.
+ * To represent "no button" (for motion events), use
+ * ghostty_mouse_event_clear_button().
+ *
+ * @param event The event handle, must not be NULL
+ * @param button The button to set
+ *
+ * @ingroup mouse
+ */
+void ghostty_mouse_event_set_button(GhosttyMouseEvent event,
+                                    GhosttyMouseButton button);
+
+/**
+ * Clear the event button.
+ *
+ * This sets the event button to "none".
+ *
+ * @param event The event handle, must not be NULL
+ *
+ * @ingroup mouse
+ */
+void ghostty_mouse_event_clear_button(GhosttyMouseEvent event);
+
+/**
+ * Get the event button.
+ *
+ * @param event The event handle, must not be NULL
+ * @param out_button Output pointer for the button value (may be NULL)
+ * @return true if a button is set, false if no button is set
+ *
+ * @ingroup mouse
+ */
+bool ghostty_mouse_event_get_button(GhosttyMouseEvent event,
+                                    GhosttyMouseButton *out_button);
+
+/**
+ * Set keyboard modifiers held during the event.
+ *
+ * @param event The event handle, must not be NULL
+ * @param mods Modifier bitmask
+ *
+ * @ingroup mouse
+ */
+void ghostty_mouse_event_set_mods(GhosttyMouseEvent event,
+                                  GhosttyMods mods);
+
+/**
+ * Get keyboard modifiers held during the event.
+ *
+ * @param event The event handle, must not be NULL
+ * @return Modifier bitmask
+ *
+ * @ingroup mouse
+ */
+GhosttyMods ghostty_mouse_event_get_mods(GhosttyMouseEvent event);
+
+/**
+ * Set the event position in surface-space pixels.
+ *
+ * @param event The event handle, must not be NULL
+ * @param position The position to set
+ *
+ * @ingroup mouse
+ */
+void ghostty_mouse_event_set_position(GhosttyMouseEvent event,
+                                      GhosttyMousePosition position);
+
+/**
+ * Get the event position in surface-space pixels.
+ *
+ * @param event The event handle, must not be NULL
+ * @return The current event position
+ *
+ * @ingroup mouse
+ */
+GhosttyMousePosition ghostty_mouse_event_get_position(GhosttyMouseEvent event);
+
+#endif /* GHOSTTY_VT_MOUSE_EVENT_H */