libghostty: expose paste encode to C API

Add ghostty_paste_encode() which encodes paste data for writing to
the terminal pty. It strips unsafe control bytes, wraps in bracketed
paste sequences when requested, and replaces newlines with carriage
returns for unbracketed mode. The input buffer is modified in place
and the encoded result is written to a caller-provided output buffer,
following the same buffer/out_written pattern as the other encode
functions like ghostty_size_report_encode.

Update the c-vt-paste example with an encode_example() demonstrating
the new function and add corresponding @snippet references in the
header documentation.

include/ghostty/vt/paste.h

@@ -9,22 +9,32 @@
 
 /** @defgroup paste Paste Utilities
  *
- * Utilities for validating paste data safety.
+ * Utilities for validating and encoding paste data for terminal input.
  *
  * ## Basic Usage
  *
  * Use ghostty_paste_is_safe() to check if paste data contains potentially
  * dangerous sequences before sending it to the terminal.
  *
- * ## Example
+ * Use ghostty_paste_encode() to encode paste data for writing to the pty,
+ * including bracketed paste wrapping and unsafe byte stripping.
+ *
+ * ## Examples
+ *
+ * ### Safety Check
  *
  * @snippet c-vt-paste/src/main.c paste-safety
  *
+ * ### Encoding
+ *
+ * @snippet c-vt-paste/src/main.c paste-encode
+ *
  * @{
  */
 
 #include <stdbool.h>
 #include <stddef.h>
+#include <ghostty/vt/types.h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -47,6 +57,41 @@ extern "C" {
  */
 bool ghostty_paste_is_safe(const char* data, size_t len);
 
+/**
+ * Encode paste data for writing to the terminal pty.
+ *
+ * This function prepares paste data for terminal input by:
+ * - Stripping unsafe control bytes (NUL, ESC, DEL, etc.) by replacing
+ *   them with spaces
+ * - Wrapping the data in bracketed paste sequences if @p bracketed is true
+ * - Replacing newlines with carriage returns if @p bracketed is false
+ *
+ * The input @p data buffer is modified in place during encoding. The
+ * encoded result (potentially with bracketed paste prefix/suffix) is
+ * written to the output buffer.
+ *
+ * If the output buffer is too small, the function returns
+ * GHOSTTY_OUT_OF_SPACE and sets the required size in @p out_written.
+ * The caller can then retry with a sufficiently sized buffer.
+ *
+ * @param data The paste data to encode (modified in place, may be NULL)
+ * @param data_len The length of the input data in bytes
+ * @param bracketed Whether bracketed paste mode is active
+ * @param buf Output buffer to write the encoded result into (may be NULL)
+ * @param buf_len Size of the output buffer in bytes
+ * @param[out] out_written On success, the number of bytes written. On
+ *             GHOSTTY_OUT_OF_SPACE, the required buffer size.
+ * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_SPACE if the buffer
+ *         is too small
+ */
+GhosttyResult ghostty_paste_encode(
+    char* data,
+    size_t data_len,
+    bool bracketed,
+    char* buf,
+    size_t buf_len,
+    size_t* out_written);
+
 #ifdef __cplusplus
 }
 #endif