vt: replace ghostty_terminal_cell with GhosttyGridRef API

include/ghostty/vt.h

@@ -96,6 +96,7 @@ extern "C" {
 #include <ghostty/vt/focus.h>
 #include <ghostty/vt/formatter.h>
 #include <ghostty/vt/terminal.h>
+#include <ghostty/vt/grid_ref.h>
 #include <ghostty/vt/osc.h>
 #include <ghostty/vt/sgr.h>
 #include <ghostty/vt/style.h>

include/ghostty/vt/grid_ref.h

@@ -0,0 +1,86 @@
+/**
+ * @file grid_ref.h
+ *
+ * Terminal grid reference type for referencing a resolved position in the
+ * terminal grid.
+ */
+
+#ifndef GHOSTTY_VT_GRID_REF_H
+#define GHOSTTY_VT_GRID_REF_H
+
+#include <stddef.h>
+#include <stdint.h>
+#include <ghostty/vt/types.h>
+#include <ghostty/vt/screen.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** @defgroup grid_ref Grid Reference
+ *
+ * A grid reference is a resolved reference to a specific cell position in the
+ * terminal's internal page structure. Obtain a grid reference from
+ * ghostty_terminal_grid_ref(), then extract the cell or row via
+ * ghostty_grid_ref_cell() and ghostty_grid_ref_row().
+ *
+ * A grid reference is only valid until the next update to the terminal
+ * instance. There is no guarantee that a grid reference will remain
+ * valid after ANY operation, even if a seemingly unrelated part of
+ * the grid is changed, so any information related to the grid reference
+ * should be read and cached immediately after obtaining the grid reference.
+ *
+ * This API is not meant to be used as the core of render loop. It isn't 
+ * built to sustain the framerates needed for rendering large screens. 
+ * Use the render state API for that. 
+ *
+ * @{
+ */
+
+/**
+ * A resolved reference to a terminal cell position.
+ *
+ * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it.
+ *
+ * @ingroup grid_ref
+ */
+typedef struct {
+  size_t size;
+  void *node;
+  uint16_t x;
+  uint16_t y;
+} GhosttyGridRef;
+
+/**
+ * Get the cell from a grid reference.
+ *
+ * @param ref Pointer to the grid reference
+ * @param[out] out_cell On success, set to the cell at the ref's position (may be NULL)
+ * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the ref's
+ *         node is NULL
+ *
+ * @ingroup grid_ref
+ */
+GhosttyResult ghostty_grid_ref_cell(const GhosttyGridRef *ref,
+                                    GhosttyCell *out_cell);
+
+/**
+ * Get the row from a grid reference.
+ *
+ * @param ref Pointer to the grid reference
+ * @param[out] out_row On success, set to the row at the ref's position (may be NULL)
+ * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the ref's
+ *         node is NULL
+ *
+ * @ingroup grid_ref
+ */
+GhosttyResult ghostty_grid_ref_row(const GhosttyGridRef *ref,
+                                   GhosttyRow *out_row);
+
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* GHOSTTY_VT_GRID_REF_H */

include/ghostty/vt/terminal.h

@@ -13,6 +13,7 @@
 #include <ghostty/vt/types.h>
 #include <ghostty/vt/allocator.h>
 #include <ghostty/vt/modes.h>
+#include <ghostty/vt/grid_ref.h>
 #include <ghostty/vt/screen.h>
 #include <ghostty/vt/point.h>
 #include <ghostty/vt/style.h>
@@ -377,11 +378,12 @@ GhosttyResult ghostty_terminal_get(GhosttyTerminal terminal,
                                     void *out);
 
 /**
- * Get the cell and row at a given point in the terminal.
+ * Resolve a point in the terminal grid to a grid reference.
  *
- * Looks up the cell at the specified point in the terminal grid. On success,
- * the output parameters are set to the opaque cell and row values, which can
- * be queried further with ghostty_cell_get() and ghostty_row_get().
+ * Resolves the given point (which can be in active, viewport, screen,
+ * or history coordinates) to a grid reference for that location. Use
+ * ghostty_grid_ref_cell() and ghostty_grid_ref_row() to extract the cell
+ * and row.
  *
  * Lookups using the `active` and `viewport` tags are fast. The `screen`
  * and `history` tags may require traversing the full scrollback page list
@@ -395,17 +397,15 @@ GhosttyResult ghostty_terminal_get(GhosttyTerminal terminal,
  *
  * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
  * @param point The point specifying which cell to look up
- * @param[out] out_cell On success, set to the cell at the given point (may be NULL)
- * @param[out] out_row On success, set to the row containing the cell (may be NULL)
+ * @param[out] out_ref On success, set to the grid reference at the given point (may be NULL)
  * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal
  *         is NULL or the point is out of bounds
  *
  * @ingroup terminal
  */
-GhosttyResult ghostty_terminal_cell(GhosttyTerminal terminal,
-                                     GhosttyPoint point,
-                                     GhosttyCell *out_cell,
-                                     GhosttyRow *out_row);
+GhosttyResult ghostty_terminal_grid_ref(GhosttyTerminal terminal,
+                                        GhosttyPoint point,
+                                        GhosttyGridRef *out_ref);
 
 /** @} */