libghostty

MoonBit bindings for Ghostty VT with a shared API across native, js, wasm, and wasm-gc.

Targets

This package exposes one public MoonBit API from lib.mbt, with different backend implementations selected by target.

target	backend file	runtime
native	backend_native.mbt	libghostty-vt loaded through dlopen
js	backend_js.mbt	inline JS runtime that loads ghostty-vt.wasm
wasm / wasm-gc	backend_wasm.mbt	host import bridge + ghostty-vt.wasm

The public API stays the same:

• load()
• loaded()
• backend()
• last_error()
• build_info()
• Terminal::new(...)
• Terminal::write(...)
• Terminal::write_bytes(...)
• Terminal::reset()
• Terminal::resize(...)
• Terminal::cols()
• Terminal::rows()
• Terminal::title()
• Terminal::pwd()
• Terminal::format(...)
• Terminal::format_plain(...)

Native backend

native uses stub.c as a small dynamic loader in the same style as mizchi/libgit2.

• It resolves libghostty-vt symbols at runtime.
• RuntimeConfig.native_library_path can override the shared library path.
• The included native test uses mock_libghostty_vt.c and vendor/libghostty-vt.dylib so the common API can be exercised without building upstream Ghostty in this repository.

JS backend

js loads ghostty-vt.wasm directly from JavaScript.

Resolution order:

1. RuntimeConfig.wasm_module_path
2. globalThis.__mbt_ghostty_wasm_module_path
3. globalThis.LIBGHOSTTY_WASM_PATH
4. globalThis.LIBGHOSTTY_WASM_URL
5. ./vendor/ghostty-vt.wasm

For this repository, the recommended local path is:

• ./.runtime/ghostty-vt.wasm

You can prepare it with:

bash scripts/fetch_ghostty_vt_wasm.sh

Behavior:

1. If ../restty/reference/ghostty exists and apple/container is available, the script builds upstream ghostty-vt.wasm inside a Linux container with Zig 0.15.2 and writes the result to .runtime/ghostty-vt.wasm.
2. If LIBGHOSTTY_VT_WASM_SRC is set, that path is copied into .runtime/.
3. If a host-built ../restty/reference/ghostty/zig-out/bin/ghostty-vt.wasm exists, it is copied into .runtime/.
4. Otherwise, a mock-compatible fallback wasm is built from tools/mock_ghostty_vt_wasm/ and copied into .runtime/.

The fallback wasm is intentionally aligned with the checked-in native mock library so that native/js parity can still be tested when upstream Ghostty cannot be built locally.

WASM backend

wasm and wasm-gc use the same MoonBit API, but they cannot embed extern "js" directly. Instead, they depend on two host import modules:

• ghostty_bridge
• ghostty_host

ghostty_bridge

This module carries strings and byte arrays between MoonBit and the host. The MoonBit side is implemented in wasm_bridge.mbt.

Required imports:

• begin_create_string
• string_append_char
• finish_create_string
• begin_read_string
• string_read_char
• finish_read_string
• begin_create_byte_array
• byte_array_append_byte
• finish_create_byte_array

ghostty_host

This module is the actual Ghostty VT adapter that the host must provide.

Required imports:

• load
• loaded
• last_error
• terminal_new
• terminal_is_null
• terminal_close
• terminal_write
• terminal_reset
• terminal_resize
• terminal_cols
• terminal_rows
• terminal_title
• terminal_pwd
• terminal_format
• build_info_bool
• build_info_string

The intended structure is:

1. The host loads ghostty-vt.wasm.
2. The host implements ghostty_host.* in terms of that runtime.
3. The MoonBit wasm / wasm-gc artifact calls those imports through backend_wasm.mbt.

This keeps the MoonBit contract stable even though the actual runtime boundary differs between js and wasm.

Validation

Validated in this repository with:

moon test --target native
moon check --target js
moon check --target wasm
moon check --target wasm-gc

To verify native/js parity with the same scenario:

bash scripts/check_native_js_parity.sh

To verify wasm / wasm-gc parity with the same scenario:

bash scripts/check_wasm_parity.sh

This uses a Node-based host adapter in scripts/ghostty_runtime_adapter.mjs to provide the ghostty_bridge and ghostty_host imports expected by the MoonBit wasm targets.