vt: expose ghostty_terminal_new/free

include/ghostty/vt.h

@@ -28,6 +28,7 @@
  * @section groups_sec API Reference
  *
  * The API is organized into the following groups:
+ * - @ref terminal "Terminal Lifecycle" - Create and destroy terminal instances
  * - @ref key "Key Encoding" - Encode key events into terminal sequences
  * - @ref osc "OSC Parser" - Parse OSC (Operating System Command) sequences
  * - @ref sgr "SGR Parser" - Parse SGR (Select Graphic Rendition) sequences
@@ -74,6 +75,7 @@ extern "C" {
 
 #include <ghostty/vt/result.h>
 #include <ghostty/vt/allocator.h>
+#include <ghostty/vt/terminal.h>
 #include <ghostty/vt/osc.h>
 #include <ghostty/vt/sgr.h>
 #include <ghostty/vt/key.h>

include/ghostty/vt/terminal.h

@@ -0,0 +1,88 @@
+/**
+ * @file terminal.h
+ *
+ * Terminal lifecycle management.
+ */
+
+#ifndef GHOSTTY_VT_TERMINAL_H
+#define GHOSTTY_VT_TERMINAL_H
+
+#include <stddef.h>
+#include <stdint.h>
+#include <ghostty/vt/result.h>
+#include <ghostty/vt/allocator.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** @defgroup terminal Terminal Lifecycle
+ *
+ * Minimal API for creating and destroying terminal instances.
+ *
+ * This currently only exposes lifecycle operations. Additional terminal
+ * APIs will be added over time.
+ *
+ * @{
+ */
+
+/**
+ * Opaque handle to a terminal instance.
+ *
+ * @ingroup terminal
+ */
+typedef struct GhosttyTerminal* GhosttyTerminal;
+
+/**
+ * Terminal initialization options.
+ *
+ * @ingroup terminal
+ */
+typedef struct {
+  /** Terminal width in cells. Must be greater than zero. */
+  uint16_t cols;
+
+  /** Terminal height in cells. Must be greater than zero. */
+  uint16_t rows;
+
+  /** Maximum number of lines to keep in scrollback history. */
+  size_t max_scrollback;
+
+  // TODO: Consider ABI compatibility implications of this struct.
+  // We may want to artificially pad it significantly to support
+  // future options.
+} GhosttyTerminalOptions;
+
+/**
+ * Create a new terminal instance.
+ *
+ * @param allocator Pointer to allocator, or NULL to use the default allocator
+ * @param terminal Pointer to store the created terminal handle
+ * @param options Terminal initialization options
+ * @return GHOSTTY_SUCCESS on success, or an error code on failure
+ *
+ * @ingroup terminal
+ */
+GhosttyResult ghostty_terminal_new(const GhosttyAllocator* allocator,
+                                   GhosttyTerminal* terminal,
+                                   GhosttyTerminalOptions options);
+
+/**
+ * Free a terminal instance.
+ *
+ * Releases all resources associated with the terminal. After this call,
+ * the terminal handle becomes invalid and must not be used.
+ *
+ * @param terminal The terminal handle to free (may be NULL)
+ *
+ * @ingroup terminal
+ */
+void ghostty_terminal_free(GhosttyTerminal terminal);
+
+/** @} */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* GHOSTTY_VT_TERMINAL_H */