aboutsummaryrefslogtreecommitdiff
path: root/vendor/libghostty-vt/include/ghostty/vt/wasm.h
diff options
context:
space:
mode:
authorCan Celik <ogulcancelik@gmail.com>2026-09-10 21:51:57 +0300
committerGitHub <noreply@github.com>2026-09-10 21:51:57 +0300
commit425c86179791cd32e2d4ce0ae7f269940b4b0663 (patch)
treee52c4383a6d69216cbe2a32638bf90841d7e2189 /vendor/libghostty-vt/include/ghostty/vt/wasm.h
parent90e947a6e26e02f10ec7f1694c4eb5b78a86406b (diff)
chore: upgrade libghostty and preserve terminal behavior (#3906)
Diffstat (limited to 'vendor/libghostty-vt/include/ghostty/vt/wasm.h')
-rw-r--r--vendor/libghostty-vt/include/ghostty/vt/wasm.h168
1 files changed, 84 insertions, 84 deletions
diff --git a/vendor/libghostty-vt/include/ghostty/vt/wasm.h b/vendor/libghostty-vt/include/ghostty/vt/wasm.h
index e2b63e2c..2f9ff5df 100644
--- a/vendor/libghostty-vt/include/ghostty/vt/wasm.h
+++ b/vendor/libghostty-vt/include/ghostty/vt/wasm.h
@@ -10,12 +10,12 @@
#ifdef __wasm__
#include <stddef.h>
-#include <stdint.h>
#include <ghostty/vt/types.h>
/** @defgroup wasm WebAssembly Utilities
*
- * Convenience functions for allocating various types in WebAssembly builds.
+ * Convenience functions for working with the low-level C ABI in WebAssembly
+ * builds.
* **These are only available the libghostty-vt wasm module.**
*
* Ghostty relies on pointers to various types for ABI compatibility, and
@@ -28,37 +28,64 @@
* your custom allocator. This is a very rare use case in the WebAssembly
* world so these are optimized for simplicity.
*
+ * Use ghostty_wasm_alloc() and ghostty_wasm_free() for host-owned scratch
+ * buffers and ABI values. Dynamic-language hosts can use ghostty_type_json()
+ * to discover pointer and size_t widths, maximum alignment, byte order, and
+ * the size and alignment of public C structs. Do not mix allocation families:
+ * buffers returned by libghostty-vt allocating APIs must still be released
+ * with ghostty_free(), and opaque handles must be released with their
+ * type-specific destructor.
+ *
+ * ## Memory growth
+ *
+ * An exported function may grow Wasm linear memory when it allocates. Numeric
+ * pointers and handles remain valid, but JavaScript ArrayBuffer, DataView, and
+ * typed-array objects created before the growth may no longer cover the live
+ * memory. Reacquire `exports.memory.buffer` immediately before every host-side
+ * memory access. A host that caches views should recreate them whenever either
+ * the buffer identity or its byte length changes.
+ *
* ## Example Usage
*
- * Here's a simple example of using the Wasm utilities with the key encoder:
+ * Here's a simple example that creates a terminal, writes bytes, and safely
+ * handles memory growth:
*
* @code
* const { exports } = wasmInstance;
- * const view = new DataView(wasmMemory.buffer);
- *
- * // Create key encoder
- * const encoderPtr = exports.ghostty_wasm_alloc_opaque();
- * exports.ghostty_key_encoder_new(null, encoderPtr);
- * const encoder = view.getUint32(encoder, true);
- *
- * // Configure encoder with Kitty protocol flags
- * const flagsPtr = exports.ghostty_wasm_alloc_u8();
- * view.setUint8(flagsPtr, 0x1F);
- * exports.ghostty_key_encoder_setopt(encoder, 5, flagsPtr);
- *
- * // Allocate output buffer and size pointer
- * const bufferSize = 32;
- * const bufPtr = exports.ghostty_wasm_alloc_u8_array(bufferSize);
- * const writtenPtr = exports.ghostty_wasm_alloc_usize();
- *
- * // Encode the key event
- * exports.ghostty_key_encoder_encode(
- * encoder, eventPtr, bufPtr, bufferSize, writtenPtr
- * );
- *
- * // Read encoded output
- * const bytesWritten = view.getUint32(writtenPtr, true);
- * const encoded = new Uint8Array(wasmMemory.buffer, bufPtr, bytesWritten);
+ * const memory = exports.memory;
+ * let cachedBuffer = null;
+ * let cachedLength = 0;
+ * let cachedBytes = null;
+ *
+ * function bytes() {
+ * const buffer = memory.buffer;
+ * if (buffer !== cachedBuffer || buffer.byteLength !== cachedLength) {
+ * cachedBuffer = buffer;
+ * cachedLength = buffer.byteLength;
+ * cachedBytes = new Uint8Array(buffer);
+ * }
+ * return cachedBytes;
+ * }
+ *
+ * function check(result) {
+ * if (result !== 0) throw new Error(`libghostty-vt error: ${result}`);
+ * }
+ *
+ * // One slot can be reused for every opaque-handle constructor.
+ * const slot = exports.ghostty_wasm_alloc_opaque();
+ * if (slot === 0) throw new Error("out of memory");
+ * check(exports.ghostty_terminal_new(0, slot, 80, 24));
+ * const terminal = exports.ghostty_wasm_take_opaque(slot);
+ *
+ * const input = new TextEncoder().encode("Hello, world!");
+ * const inputPtr = exports.ghostty_wasm_alloc(input.length);
+ * if (inputPtr === 0) throw new Error("out of memory");
+ * bytes().set(input, inputPtr); // Acquires the current memory after alloc.
+ * exports.ghostty_terminal_vt_write(terminal, inputPtr, input.length);
+ *
+ * exports.ghostty_wasm_free(inputPtr, input.length);
+ * exports.ghostty_terminal_free(terminal);
+ * exports.ghostty_wasm_free_opaque(slot);
* @endcode
*
* @remark The code above is pretty ugly! This is the lowest level interface
@@ -69,89 +96,62 @@
*/
/**
- * Allocate an opaque pointer. This can be used for any opaque pointer
- * types such as GhosttyKeyEncoder, GhosttyKeyEvent, etc.
- *
- * @return Pointer to allocated opaque pointer, or NULL if allocation failed
- * @ingroup wasm
- */
-GHOSTTY_API void** ghostty_wasm_alloc_opaque(void);
-
-/**
- * Free an opaque pointer allocated by ghostty_wasm_alloc_opaque().
- *
- * @param ptr Pointer to free, or NULL (NULL is safely ignored)
- * @ingroup wasm
- */
-GHOSTTY_API void ghostty_wasm_free_opaque(void **ptr);
-
-/**
- * Allocate an array of uint8_t values.
+ * Allocate caller-owned storage for a Wasm ABI value or scratch buffer.
*
- * @param len Number of uint8_t elements to allocate
- * @return Pointer to allocated array, or NULL if allocation failed
- * @ingroup wasm
- */
-GHOSTTY_API uint8_t* ghostty_wasm_alloc_u8_array(size_t len);
-
-/**
- * Free an array allocated by ghostty_wasm_alloc_u8_array().
+ * The returned address is aligned to the target's maximum C ABI alignment,
+ * reported as `abi.max_alignment` by ghostty_type_json(). The memory is
+ * uninitialized. A zero-length request returns NULL.
*
- * @param ptr Pointer to the array to free, or NULL (NULL is safely ignored)
- * @param len Length of the array (must match the length passed to alloc)
- * @ingroup wasm
- */
-GHOSTTY_API void ghostty_wasm_free_u8_array(uint8_t *ptr, size_t len);
-
-/**
- * Allocate an array of uint16_t values.
+ * The returned pointer must be released with ghostty_wasm_free() using the
+ * exact same length.
*
- * @param len Number of uint16_t elements to allocate
- * @return Pointer to allocated array, or NULL if allocation failed
+ * @param len Number of bytes to allocate
+ * @return Pointer to allocated storage, or NULL if len is zero or allocation
+ * failed
* @ingroup wasm
*/
-GHOSTTY_API uint16_t* ghostty_wasm_alloc_u16_array(size_t len);
+GHOSTTY_API void* ghostty_wasm_alloc(size_t len);
/**
- * Free an array allocated by ghostty_wasm_alloc_u16_array().
+ * Free storage allocated by ghostty_wasm_alloc().
*
- * @param ptr Pointer to the array to free, or NULL (NULL is safely ignored)
- * @param len Length of the array (must match the length passed to alloc)
+ * @param ptr Pointer to free, or NULL (NULL is safely ignored)
+ * @param len Original allocation length passed to ghostty_wasm_alloc()
* @ingroup wasm
*/
-GHOSTTY_API void ghostty_wasm_free_u16_array(uint16_t *ptr, size_t len);
+GHOSTTY_API void ghostty_wasm_free(void *ptr, size_t len);
/**
- * Allocate a single uint8_t value.
+ * Allocate an opaque pointer. This can be used for any opaque pointer
+ * types such as GhosttyKeyEncoder, GhosttyKeyEvent, etc. The allocated slot
+ * is initialized to NULL and may be reused across constructors.
*
- * @return Pointer to allocated uint8_t, or NULL if allocation failed
+ * @return Pointer to allocated opaque pointer, or NULL if allocation failed
* @ingroup wasm
*/
-GHOSTTY_API uint8_t* ghostty_wasm_alloc_u8(void);
+GHOSTTY_API void** ghostty_wasm_alloc_opaque(void);
/**
- * Free a uint8_t allocated by ghostty_wasm_alloc_u8().
+ * Free an opaque pointer allocated by ghostty_wasm_alloc_opaque().
*
* @param ptr Pointer to free, or NULL (NULL is safely ignored)
* @ingroup wasm
*/
-GHOSTTY_API void ghostty_wasm_free_u8(uint8_t *ptr);
+GHOSTTY_API void ghostty_wasm_free_opaque(void **ptr);
/**
- * Allocate a single size_t value.
+ * Take an opaque handle from an out-parameter slot.
*
- * @return Pointer to allocated size_t, or NULL if allocation failed
- * @ingroup wasm
- */
-GHOSTTY_API size_t* ghostty_wasm_alloc_usize(void);
-
-/**
- * Free a size_t allocated by ghostty_wasm_alloc_usize().
+ * Returns the handle currently stored in @p slot and resets the slot to NULL.
+ * This function does not allocate, free the returned handle, or free the slot.
+ * Always check the GhosttyResult returned by the function that populated the
+ * slot before calling this function.
*
- * @param ptr Pointer to free, or NULL (NULL is safely ignored)
+ * @param slot Pointer to an opaque out-parameter slot, or NULL
+ * @return Stored opaque handle, or NULL if slot or its value is NULL
* @ingroup wasm
*/
-GHOSTTY_API void ghostty_wasm_free_usize(size_t *ptr);
+GHOSTTY_API void* ghostty_wasm_take_opaque(void **slot);
/** @} */