vt: add ghostty_terminal_get for reading terminal state

Add a typed data query API to the terminal C interface, following
the same OutType pattern used by the OSC command data API. The new
ghostty_terminal_get function takes a GhosttyTerminalData tag and
an output pointer, returning GhosttyResult.

Currently exposes cols, rows, cursor x/y position, and cursor
pending wrap state. The GhosttyTerminalData enum is placed with the
other types in the header (before functions) per the ordering
convention.

include/ghostty/vt/terminal.h

@@ -97,6 +97,119 @@ typedef struct {
   GhosttyTerminalScrollViewportValue value;
 } GhosttyTerminalScrollViewport;
 
+/**
+ * Terminal screen identifier.
+ *
+ * Identifies which screen buffer is active in the terminal.
+ *
+ * @ingroup terminal
+ */
+typedef enum {
+  /** The primary (normal) screen. */
+  GHOSTTY_TERMINAL_SCREEN_PRIMARY = 0,
+
+  /** The alternate screen. */
+  GHOSTTY_TERMINAL_SCREEN_ALTERNATE = 1,
+} GhosttyTerminalScreen;
+
+/**
+ * Scrollbar state for the terminal viewport.
+ *
+ * Represents the scrollable area dimensions needed to render a scrollbar.
+ *
+ * @ingroup terminal
+ */
+typedef struct {
+  /** Total size of the scrollable area in rows. */
+  uint64_t total;
+
+  /** Offset into the total area that the viewport is at. */
+  uint64_t offset;
+
+  /** Length of the visible area in rows. */
+  uint64_t len;
+} GhosttyTerminalScrollbar;
+
+/**
+ * Terminal data types.
+ *
+ * These values specify what type of data to extract from a terminal
+ * using `ghostty_terminal_get`.
+ *
+ * @ingroup terminal
+ */
+typedef enum {
+  /** Invalid data type. Never results in any data extraction. */
+  GHOSTTY_TERMINAL_DATA_INVALID = 0,
+
+  /**
+   * Terminal width in cells.
+   *
+   * Output type: uint16_t *
+   */
+  GHOSTTY_TERMINAL_DATA_COLS = 1,
+
+  /**
+   * Terminal height in cells.
+   *
+   * Output type: uint16_t *
+   */
+  GHOSTTY_TERMINAL_DATA_ROWS = 2,
+
+  /**
+   * Cursor column position (0-indexed).
+   *
+   * Output type: uint16_t *
+   */
+  GHOSTTY_TERMINAL_DATA_CURSOR_X = 3,
+
+  /**
+   * Cursor row position within the active area (0-indexed).
+   *
+   * Output type: uint16_t *
+   */
+  GHOSTTY_TERMINAL_DATA_CURSOR_Y = 4,
+
+  /**
+   * Whether the cursor has a pending wrap (next print will soft-wrap).
+   *
+   * Output type: bool *
+   */
+  GHOSTTY_TERMINAL_DATA_CURSOR_PENDING_WRAP = 5,
+
+  /**
+   * The currently active screen.
+   *
+   * Output type: GhosttyTerminalScreen *
+   */
+  GHOSTTY_TERMINAL_DATA_ACTIVE_SCREEN = 6,
+
+  /**
+   * Whether the cursor is visible (DEC mode 25).
+   *
+   * Output type: bool *
+   */
+  GHOSTTY_TERMINAL_DATA_CURSOR_VISIBLE = 7,
+
+  /**
+   * Current Kitty keyboard protocol flags.
+   *
+   * Output type: GhosttyKittyKeyFlags * (uint8_t *)
+   */
+  GHOSTTY_TERMINAL_DATA_KITTY_KEYBOARD_FLAGS = 8,
+
+  /**
+   * Scrollbar state for the terminal viewport.
+   *
+   * This may be expensive to calculate depending on where the viewport
+   * is (arbitrary pins are expensive). The caller should take care to only
+   * call this as needed and not too frequently.
+   *
+   * Output type: GhosttyTerminalScrollbar *
+   */
+  GHOSTTY_TERMINAL_DATA_SCROLLBAR = 9,
+} GhosttyTerminalData;
+
 /**
  * Create a new terminal instance.
  *
@@ -228,8 +341,28 @@ GhosttyResult ghostty_terminal_mode_get(GhosttyTerminal terminal,
  * @ingroup terminal
  */
 GhosttyResult ghostty_terminal_mode_set(GhosttyTerminal terminal,
-                                        GhosttyMode mode,
-                                        bool value);
+                                         GhosttyMode mode,
+                                         bool value);
+
+/**
+ * Get data from a terminal instance.
+ *
+ * Extracts typed data from the given terminal based on the specified
+ * data type. The output pointer must be of the appropriate type for the
+ * requested data kind. Valid data types and output types are documented
+ * in the `GhosttyTerminalData` enum.
+ *
+ * @param terminal The terminal handle (may be NULL)
+ * @param data The type of data to extract
+ * @param out Pointer to store the extracted data (type depends on data parameter)
+ * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal
+ *         is NULL or the data type is invalid
+ *
+ * @ingroup terminal
+ */
+GhosttyResult ghostty_terminal_get(GhosttyTerminal terminal,
+                                   GhosttyTerminalData data,
+                                   void *out);
 
 /** @} */