libghostty: add utf-8 grapheme cell getter to C API

Add a render-state row-cells getter that encodes the current cell's
full grapheme cluster directly as UTF-8 into a caller-provided
GhosttyBuffer. The getter writes the base codepoint first, followed by
any extra grapheme codepoints, and follows the existing buffer-writer
convention where len is bytes written on success or required capacity
on GHOSTTY_OUT_OF_SPACE.

Previously C consumers could query grapheme codepoints, but bindings
that needed UTF-8 text had to reconstruct and encode the cluster
themselves. That duplicated terminal internals in downstream bindings
and made users pay for awkward cross-language struct handling. By
owning the UTF-8/grapheme behavior in libghostty, bindings can use one
stable C API and optionally wrap it with small binding-local helpers.

include/ghostty/vt/render.h

@@ -614,6 +614,19 @@ typedef enum GHOSTTY_ENUM_TYPED {
    *  GhosttyCell for renderers that only need to know whether fetching the
    *  full style is necessary. */
   GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_HAS_STYLING = 8,
+
+  /**
+   * Encode the current cell's full grapheme cluster as UTF-8 into a
+   * caller-provided buffer (GhosttyBuffer).
+   *
+   * The base codepoint is encoded first, followed by any extra grapheme
+   * codepoints. Returns GHOSTTY_SUCCESS with len=0 when the cell has no text.
+   *
+   * If ptr is NULL or cap is too small for a non-empty cell, returns
+   * GHOSTTY_OUT_OF_SPACE without writing any bytes and sets len to the required
+   * buffer size in bytes.
+   */
+  GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_GRAPHEMES_UTF8 = 9,
   GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
 } GhosttyRenderStateRowCellsData;
 

include/ghostty/vt/types.h

@@ -227,6 +227,23 @@ typedef struct {
   size_t len;
 } GhosttyString;
 
+/**
+ * A caller-provided byte buffer.
+ *
+ * APIs that write to this type use `len` for the number of bytes written on
+ * GHOSTTY_SUCCESS and the required byte capacity on GHOSTTY_OUT_OF_SPACE.
+ */
+typedef struct {
+  /** Destination buffer for bytes. May be NULL when cap is 0 to query required size. */
+  uint8_t* ptr;
+
+  /** Capacity of ptr in bytes. */
+  size_t cap;
+
+  /** Bytes written on success, or required byte capacity on GHOSTTY_OUT_OF_SPACE. */
+  size_t len;
+} GhosttyBuffer;
+
 /**
  * A surface-space position in pixels.
  *