ghostty-rs/docs/rewrite/notes/libghostty-L1.md

libghostty: the embedded C API (Phase 8, agent L1)

Crate crates/ghostty-lib (crate types cdylib + staticlib + rlib, [lib] name = "ghostty" so Cargo produces libghostty.{so,a,dylib} directly). include/ghostty.h and include/module.modulemap are byte-identical copies of ZIG/include (a test compares them when the Zig checkout is present). unsafe_code = "deny" crate wide; every FFI module has #![allow(unsafe_code)] with // SAFETY: comments.

Mapping

Zig	Rust (crates/ghostty-lib/src)
main_c.zig (ghostty_init, _cli_try_action, _info, _translate, _string_free, String)	main_c.rs
config/CApi.zig, config/c_get.zig, Config.zig cvals	config_capi.rs + ghostty-config/src/c_value.rs (CValue, ConfigField::c_value, Config::c_value)
apprt/action.zig C/cval (target + action unions)	action_c.rs, C layouts in types.rs
apprt/embedded.zig App, Surface, Platform, CAPI	embedded.rs (AppRt: RtApp, SurfaceRt: RtSurface, AppHandle, Surface, all ghostty_app_*/ghostty_surface_*)
apprt/embedded.zig Inspector + ghostty_inspector_*	inspector.rs (+ inspector_metal.rs, Apple only)
benchmark/CApi.zig	benchmark.rs (ghostty_benchmark_cli)
include/ghostty.h structs/unions/enums	types.rs (#[repr(C)], enums are c_int)

ghostty_set_window_background_blur is exported on every platform (no-op off macOS), like Zig. The Darwin-only exports (ghostty_surface_set_display_id, _quicklook_font, _quicklook_word, ghostty_inspector_metal_*) are cfg(target_vendor = "apple"), matching the header's #ifdef __APPLE__.

Runtime design

• The embedded runtime implements ghostty_apprt::runtime_api::{RtApp, RtSurface}; the real ghostty-core drives it. AppRt holds a copy of ghostty_runtime_config_s, the app config (Arc<Config>, updated on the app-targeted config_change action exactly like Zig's performPreAction), the surface registry (for titles) and the Keymap. SurfaceRt holds userdata, the view pointer, content scale / size / cursor position and the title.
• ghostty_app_t = Box<AppHandle>, ghostty_surface_t = Box<Surface>. The address of the Surface is its SurfaceId in core and the ghostty_surface_t in ghostty_target_s, so actions fired during Surface::new (cell size, size limit, title) already name the handle the host will get back.
• core::App::create_surface (new) returns the concrete Rc<core::Surface> so the embedded API can reach everything Zig's core_surface exposes (text_callback, refresh_callback, draw, mouse_captured, dump_text_locked, lock_terminal, ...), not only the CoreSurface trait.
• Everything is main-thread only (core uses Rc/RefCell); the single cross-thread entry is wakeup_cb (WakerImpl, a Waker). No RefCell borrow is held across a call into the host (the host may re-enter).
• Clipboard: read_clipboard_cb gets a Box<ClipboardRequest> pointer that is consumed by ghostty_surface_complete_clipboard_request (kept alive when confirm_read_clipboard_cb is invoked, like Zig).
• ghostty_config_t is a Box<CConfig> (config + the memory ghostty_config_get hands out pointers into: strings, color lists, command lists, diagnostics; kept until ghostty_config_free, identical values return identical pointers). Enum tag names are interned for the process lifetime. The config_change action passes a temporary CConfig handle that is freed after the callback returns.

Config C getters (c_get.zig)

ConfigField::c_value() -> CValue (default Unsupported) is implemented by: bool, u8/u32 (c_uint), i16 (c_short), f32/f64, Option<String> (?[:0]const u8: unset -> true + NULL), every config_enum! (tag name), every config_packed! (bits as c_uint, <= 32 fields), Option<T> (None -> false), Color, ColorList, Palette, RepeatableCommand, QuickTerminalSize, BackgroundBlur (0/20/radius/-1/-2), Duration (usize ms), Path, WindowDecoration, CursorStyle, OptionAsAlt. Everything else (String, u16, u64, usize, unions without cval, repeatable types, ...) is unsupported (get returns false) exactly like Zig. ghostty-config has a test (c_value_supported_keys_match_zig, data in testdata/c_get_supported.txt) that compares the supported key set (143 keys) with the one derived from the Zig field types. RepeatableStringMap::put was added (needed for surface env_vars).

Platform gating (renderer selection)

• ghostty-core no longer hard-codes OpenGL: surface/mod.rs uses ghostty_renderer::{Renderer, Api} (Metal on target_vendor = "apple", OpenGL elsewhere; Zig's renderer.zig). init_graphics_api is OpenGL::init + prepare_context(rt.gl_proc_address) off Apple and Metal::init_with_view(blending, view, scale) on Apple. RtSurface::platform_view() (new, default null) carries the NSView/UIView; Metal::init_with_view (new, in the renderer crate's unsafe-allowed metal module) turns the raw pointer into the ViewInfo. GL-only helpers (frame_pixels, screenshots, display_realized(loader)) are cfg(not(apple)).
• Surfaces: Zig's Platform.init only accepts macos/ios on Darwin targets and fails with UnsupportedPlatform everywhere else, so ghostty_surface_new returns NULL on Linux (tested). No host-supplied OpenGL context exists in Zig, so there is none here either.
• New renderer/font/core helpers for the Darwin exports: Renderer::font_grid(), coretext::Face::quicklook_font, core::Surface::{set_macos_display_id, quicklook_font} (core gained an Apple-only objc2-core-foundation dep).
• Test seam: cargo feature test-platform (off by default, enabled by --all-features) lets ghostty_surface_new accept platform_tag = 1000 and takes the OpenGL loader from a thread-local the test installs (headless EGL). Production behaviour is unchanged.

Deviations from the Zig

• ghostty_init stores the given argv only to detect the CLI action; config CLI parsing and +action execution use the process arguments (ghostty_os::args, NSProcessInfo on macOS), which are the same in a real process. ghostty_init returns 1 for multiple/invalid actions (Zig: error from detectArgs). The +action runs through ghostty_cli::run_from_args (so +version etc. print exactly like the binary).
• Lib-mode logging default: stderr off (GlobalState.Logging.stderr = app_runtime != .none), via the new ghostty_core::global::init_lib. BuildInfo for +version reports .none runtime / CoreText + Metal on Apple.
• Invalid enum values coming from C (mouse state/button, split directions, color scheme, key action, pressure stage) are ignored / return false (Zig: UB / safety panic). Null handles are tolerated.
• ghostty_surface_key_is_binding writes only the low byte (Zig writes the u8 Flags.C through the enum pointer).
• ghostty_surface_inherited_config working-directory strings are kept in the surface (valid until it is freed) instead of leaking an allocation per call.
• initial_input is escaped like std.zig.stringEscape, except non-ASCII code points use \u{..} (the config Raw value is a Rust String, which cannot hold the \xNN bytes of a split UTF-8 sequence).
• ghostty_benchmark_cli splits the args string itself (quotes group, \ escapes inside quotes) and runs ghostty_bench::benches::main_action.
• Header typo kept: chostty_ipc_target_s; ghostty_inspector_metal_shutdown is declared bool in the header but Zig exports it as void (we follow Zig; the Swift app ignores the result).

Inspector

C API complete: ghostty_surface_inspector (one per surface, returns the existing one), ghostty_inspector_free (takes the surface), size / content scale / focus / mouse / scroll / key / text feed a per-inspector Dear ImGui Context (ghostty_inspector::setup, style scaled by the factor change, scroll x0.1 for precision devices, only left/middle/right buttons). Activation calls core::Surface::activate_inspector and RtSurface::redraw_inspector raises the render_inspector action, as in Zig.

inspector_metal.rs (Apple only, compile-checked only) replaces Dear ImGui's imgui_impl_metal.mm: the same MSL shaders compiled with newLibraryWithSource, a pipeline keyed by the host render pass' formats, per-draw-list buffers, dear-imgui-rs managed textures (RGBA32/Alpha8 -> RGBA8), RENDERER_HAS_VTX_OFFSET | RENDERER_HAS_TEXTURES. Two frames are built per render (the first only end_frame), like Zig. Raw draw callbacks are ignored. It has never run on a Mac.

Tests

• Unit: 20 in src (string helpers, ghostty_config_get ports of the Zig tests: bool/enum/optional null/unknown key/optional string null/float/struct cval, the c_get: tests u8/enum/color/optional/background-blur/ split-preserve-zoom, action/target conversions, benchmark arg splitting). ghostty-config: +4 c_value tests and the two RepeatableCommand cval tests (previously skipped).
• tests/abi.rs (generated C probe compiled with cc, linked against libghostty.so): sizeof/alignof/offsetof of every struct and union of the header (field names parsed from the header, so a missing field fails), sizeof + value of every enumerator of every enum (755 values, compared with the Rust definitions: Key::ALL, apprt::action::Key, MouseShape, Mods bits, ...), the address of every declared function (links), nm -D exports == declared functions, header files identical to upstream. The probe asserts every header enum/struct is covered.
• tests/c_host.rs + tests/c/host.c: a C host program on the unchanged header: ghostty_init, +version / +list-keybinds through ghostty_cli_try_action, config new/load_file/finalize/get (bool, enum, string, colors, palette, float, packed, short blur, duration, quick-terminal-size, command list, unsupported/unknown/unset keys), triggers, diagnostics, clone, open_path, app new/tick/key/key_is_binding/focus/color scheme/open_config/ update_config (the config_change action carries a readable config), global keybinds, ghostty_surface_new returning NULL off Darwin, ghostty_benchmark_cli.
• tests/surface.rs (feature test-platform, headless EGL, real shell on a real pty): 13 tests driving the exported C surface API: creation/actions/size/scale/free, text + key input, key_is_binding flags, selection + copy/paste (including the unsafe-paste confirmation round trip), OSC 52 / title / pwd actions, inherited config, env vars / working directory / initial input / font size options, mouse capture and reports, focus/occlusion/preedit/splits/ close callback, child exit, app + surface config updates, inspector API, rejected platforms.
• Cross-compile checks (recipe from macos-M1.md, wrappers around zig cc; the CoreGraphics/Metal/CoreText code is only type-checked): cargo check|clippy --all-targets -p ghostty-lib --target aarch64-apple-darwin and x86_64-apple-darwin pass with -D warnings, as does -p ghostty-core.

Known gaps

• Nothing in the Apple-only paths (Metal surface setup, display link, quicklook, window blur, Metal inspector) has run on a Mac; the Swift app has not been built against the library.
• ghostty_translate returns interned translations; ghostty_init ignores argv beyond action detection (see above).
• Only the debug-profile static library was inspected (~500 MB with debug info); release/production sizes untested.