feat(lib): port libghostty, Ghostty's embedded C API

Ports apprt/embedded.zig, main_c.zig and config/CApi.zig + c_get.zig as
crates/ghostty-lib (cdylib/staticlib/rlib `libghostty`), exporting every
function of the unchanged include/ghostty.h - the ABI Ghostty's Swift
macOS/iOS app links against. The embedded runtime implements the
runtime traits over the host's C callbacks, so the real core drives it.

- ghostty-core selects the renderer per target: Metal on Apple (surface
  NSView/UIView via RtSurface::platform_view), OpenGL elsewhere.
- ghostty_config_get follows Zig's c_get rules via a CValue type (143
  supported keys, checked against the Zig field types).
- The inspector C API is complete; its Metal backend replaces ImGui's
  Metal renderer and has not run.

Verification: generated C ABI probe (sizeof/alignof/offsetof of every
struct/union, 755 enum values, every function linked, nm exports, headers
byte-identical to upstream); a C host on Linux covering init, CLI
actions, config, app, keys, focus and color scheme; an opt-in
test-platform feature creating real surfaces on Linux with headless EGL
and a pty (13 tests). Apple targets are clippy-clean but not run; the
Swift app has not been built against it.

Test Plan:
- cargo test -p ghostty-lib (and --features test-platform)
- cargo clippy --target aarch64-apple-darwin -p ghostty-lib (cross env
  in docs/rewrite/notes/macos-M1.md)

crates/ghostty-core/Cargo.toml

@@ -30,3 +30,4 @@ workspace = true
 
 [target.'cfg(target_vendor = "apple")'.dependencies]
 oslog = { version = "0.2.0", default-features = false }
+objc2-core-foundation = "0.3.2"

crates/ghostty-core/src/app.rs

@@ -488,6 +488,27 @@ impl App {
         }
     }
 
+    /// Create a surface and add it to the app (`CoreApp::new_surface` with
+    /// the concrete surface type, for runtimes that need more than the
+    /// [`CoreSurface`] trait, e.g. the embedded C API).
+    pub fn create_surface(
+        &self,
+        id: SurfaceId,
+        config: Config,
+        rt_app: Rc<dyn RtApp>,
+        rt_surface: Rc<dyn RtSurface>,
+    ) -> Result<Rc<Surface>, CoreError> {
+        let surface = Surface::new(
+            id,
+            Rc::clone(&self.state),
+            Arc::new(config),
+            Rc::clone(&rt_app),
+            rt_surface,
+        )?;
+        self.add_surface(id, &surface, &rt_app);
+        Ok(surface)
+    }
+
     /// Add an initialized surface. Since we have non-zero surfaces, the quit
     /// timer is cancelled.
     pub(crate) fn add_surface(&self, id: SurfaceId, surface: &Rc<Surface>, rt: &Rc<dyn RtApp>) {
@@ -589,15 +610,7 @@ impl CoreApp for App {
         rt_app: Rc<dyn RtApp>,
         rt_surface: Rc<dyn RtSurface>,
     ) -> Result<Rc<dyn CoreSurface>, CoreError> {
-        let surface = Surface::new(
-            id,
-            Rc::clone(&self.state),
-            Arc::new(config),
-            Rc::clone(&rt_app),
-            rt_surface,
-        )?;
-        self.add_surface(id, &surface, &rt_app);
-        Ok(surface)
+        Ok(self.create_surface(id, config, rt_app, rt_surface)?)
     }
 
     fn delete_surface(&self, id: SurfaceId) {

crates/ghostty-core/src/global.rs

@@ -38,6 +38,13 @@ impl Logging {
     /// invalid value (including an empty part) yields the default.
     #[must_use]
     pub fn parse(v: &str) -> Logging {
+        Logging::parse_with(v, Logging::default())
+    }
+
+    /// [`Logging::parse`] with an explicit default (lib mode defaults to no
+    /// stderr logging).
+    #[must_use]
+    pub fn parse_with(v: &str, default: Logging) -> Logging {
         match v {
             "1" | "t" | "T" | "true" => {
                 return Logging {
@@ -53,7 +60,7 @@ impl Logging {
             }
             _ => {}
         }
-        let mut out = Logging::default();
+        let mut out = default;
         for part in v.split(',') {
             let part = part.trim_matches([' ', '\t']);
             let (name, value) = match part.strip_prefix("no-") {
@@ -63,7 +70,7 @@ impl Logging {
             match name {
                 "stderr" => out.stderr = value,
                 "macos" => out.macos = value,
-                _ => return Logging::default(),
+                _ => return default,
             }
         }
         out
@@ -134,8 +141,25 @@ pub fn state() -> &'static GlobalState {
 /// Initialize the global state: logging, rlimits, resources dir and i18n.
 /// Call once, early (Zig: `GlobalState.init`).
 pub fn init(opts: InitOptions) -> &'static GlobalState {
+    init_with(opts, Logging::default())
+}
+
+/// [`init`] for the embedded library (`ghostty_init`): Zig's
+/// `GlobalState.Logging.stderr` defaults to `build_config.app_runtime !=
+/// .none`, i.e. off for the lib artifact.
+pub fn init_lib(opts: InitOptions) -> &'static GlobalState {
+    init_with(
+        opts,
+        Logging {
+            stderr: false,
+            ..Logging::default()
+        },
+    )
+}
+
+fn init_with(opts: InitOptions, default_logging: Logging) -> &'static GlobalState {
     STATE.get_or_init(|| {
-        let mut logging = Logging::default();
+        let mut logging = default_logging;
 
         // If we have an action executing, we disable logging by default
         // since we write to stderr we don't want logs messing up our
@@ -146,7 +170,7 @@ pub fn init(opts: InitOptions) -> &'static GlobalState {
 
         // Env vars are useful for logging too because they are easy to set.
         if let Ok(v) = std::env::var("GHOSTTY_LOG") {
-            logging = Logging::parse(&v);
+            logging = Logging::parse_with(&v, default_logging);
         }
 
         init_logger(logging);

crates/ghostty-core/src/surface/mod.rs

@@ -89,14 +89,13 @@ use ghostty_font::{
 };
 use ghostty_input::{Mods, MouseButton, MouseButtonState, ScrollMods};
 use ghostty_renderer::{
+    Api as GraphicsApi,
     Health,
-    // The generic renderer over the OpenGL API (the GTK runtime's graphics
-    // API). `ghostty_renderer::Renderer` is the platform default, which is
-    // Metal on Apple targets; the embedded (macOS) runtime provides its own
-    // Metal-based surface setup (TODO(integration): L1).
-    generic::{Host as RendererHost, Renderer},
+    // The renderer over the graphics API selected for the target (Zig:
+    // `renderer.zig`): Metal on Apple targets, OpenGL elsewhere.
+    Renderer,
+    generic::Host as RendererHost,
     message::{FontGridChange, Message as RendererMessage},
-    opengl::OpenGL,
     options::Options as RendererOptions,
     size::{CellSize, Coordinate, Padding, ScreenSize, Size},
     state::{Preedit, PreeditCodepoint, State as RenderStateData},
@@ -197,6 +196,31 @@ impl RendererHost for HostImpl {
     }
 }
 
+/// Create the graphics API for a new surface (Zig: `Renderer.surfaceInit`).
+#[cfg(not(target_vendor = "apple"))]
+fn init_graphics_api(
+    config: &Config,
+    rt_surface: &dyn RtSurface,
+) -> Result<GraphicsApi, CoreError> {
+    let mut api = GraphicsApi::init(config.alpha_blending);
+    api.prepare_context(|name| rt_surface.gl_proc_address(name))
+        .map_err(|e| format!("failed to prepare the OpenGL context: {e}"))?;
+    Ok(api)
+}
+
+/// Create the graphics API for a new surface (Zig: `Renderer.surfaceInit`):
+/// the Metal layer is attached to the NSView/UIView the host provided.
+#[cfg(target_vendor = "apple")]
+fn init_graphics_api(
+    config: &Config,
+    rt_surface: &dyn RtSurface,
+) -> Result<GraphicsApi, CoreError> {
+    let view = rt_surface.platform_view();
+    let scale = f64::from(rt_surface.get_content_scale().x);
+    GraphicsApi::init_with_view(config.alpha_blending, view, scale)
+        .map_err(|e| format!("failed to initialize the Metal renderer: {e}").into())
+}
+
 /// Font state of the surface.
 pub struct FontState {
     /// The key of the font grid we hold a reference on.
@@ -333,13 +357,8 @@ impl Surface {
 
         // Initialize our renderer with our initialized surface (Zig:
         // `Renderer.surfaceInit`): load the GL functions for the current
-        // context.
-        let mut api = OpenGL::init(config.alpha_blending);
-        {
-            let rt = Rc::clone(&rt_surface);
-            api.prepare_context(|name| rt.gl_proc_address(name))
-                .map_err(|e| format!("failed to prepare the OpenGL context: {e}"))?;
-        }
+        // context (OpenGL) or attach the Metal layer to the host's view.
+        let api = init_graphics_api(&config, rt_surface.as_ref())?;
 
         // Determine our DPI configurations so we can properly configure
         // font points to pixels and handle other high-DPI scaling factors.
@@ -708,6 +727,34 @@ impl Surface {
         self.renderer_handle.send(msg);
     }
 
+    /// Tell the renderer which display the surface is on (the embedded
+    /// `ghostty_surface_set_display_id`).
+    #[cfg(target_vendor = "apple")]
+    pub fn set_macos_display_id(&self, id: u32) {
+        self.send_renderer(RendererMessage::MacosDisplayId(id));
+    }
+
+    /// A retained `CTFontRef` for the primary font, for macOS quicklook
+    /// (the embedded `ghostty_surface_quicklook_font`). `scale` is the
+    /// content scale. The caller owns the reference.
+    #[cfg(target_vendor = "apple")]
+    #[must_use]
+    pub fn quicklook_font(&self, scale: f32) -> Option<*mut std::ffi::c_void> {
+        let grid = self.renderer.font_grid();
+        let mut state = grid.write();
+        let face = state
+            .resolver
+            .collection
+            .get_face(ghostty_font::collection::Index::default())
+            .ok()?;
+        let font = face.quicklook_font(f64::from(scale));
+        Some(
+            objc2_core_foundation::CFRetained::into_raw(font)
+                .as_ptr()
+                .cast(),
+        )
+    }
+
     /// Current sizes.
     #[must_use]
     pub fn size(&self) -> Size {
@@ -1810,6 +1857,14 @@ impl Surface {
 
     /// Write the last presented frame as a PNG. Requires the GL context to be
     /// current.
+    #[cfg(target_vendor = "apple")]
+    pub fn write_screenshot_png(&self, _path: &std::path::Path) -> Result<(), CoreError> {
+        Err("screenshots are not supported by the Metal renderer".into())
+    }
+
+    /// Write the last presented frame as a PNG. Requires the GL context to be
+    /// current.
+    #[cfg(not(target_vendor = "apple"))]
     pub fn write_screenshot_png(&self, path: &std::path::Path) -> Result<(), CoreError> {
         let Some((w, h, px)) = self.renderer.last_frame_pixels() else {
             return Err("no frame has been presented yet".into());
@@ -1832,11 +1887,13 @@ impl Surface {
     /// The pixels of the last presented frame (`width`, `height`, RGBA8,
     /// bottom-up). Test/debug hook for headless integration tests; requires
     /// the GL context to be current on the calling thread.
+    #[cfg(not(target_vendor = "apple"))]
     pub fn frame_pixels(&self) -> Option<(usize, usize, Vec<u8>)> {
         self.renderer.last_frame_pixels()
     }
 
     /// The GLArea was (re)realized; the GL context is current.
+    #[cfg(not(target_vendor = "apple"))]
     pub fn renderer_realized(&self) -> Result<(), CoreError> {
         let rt = Rc::clone(&self.rt_surface);
         self.renderer
@@ -1844,6 +1901,13 @@ impl Surface {
         Ok(())
     }
 
+    /// The display was (re)realized (Metal has nothing to reload).
+    #[cfg(target_vendor = "apple")]
+    pub fn renderer_realized(&self) -> Result<(), CoreError> {
+        self.renderer.display_realized_with(|_| {})?;
+        Ok(())
+    }
+
     /// The GLArea is being unrealized; the GL context is current.
     pub fn renderer_unrealized(&self) {
         self.renderer.display_unrealized();

crates/ghostty-core/tests/e2e_bindings.rs

@@ -1,5 +1,8 @@
 //! Keybinding actions end to end (default and configured bindings).
 
+// These drive the real surface over a headless OpenGL context; the Apple targets render
+// with Metal.
+#![cfg(not(target_vendor = "apple"))]
 #![allow(clippy::unwrap_used, clippy::expect_used)]
 
 use std::fmt::Write as _;

crates/ghostty-core/tests/e2e_ime.rs

@@ -1,5 +1,8 @@
 //! IME: preedit state and rendering, commit, composing key events.
 
+// These drive the real surface over a headless OpenGL context; the Apple targets render
+// with Metal.
+#![cfg(not(target_vendor = "apple"))]
 #![allow(clippy::unwrap_used, clippy::expect_used)]
 
 mod common;

crates/ghostty-core/tests/e2e_inspector.rs

@@ -2,6 +2,9 @@
 //! recording (with the pty encoding and triggered bindings) and VT event
 //! recording while data is read from the pty.
 
+// These drive the real surface over a headless OpenGL context; the Apple targets render
+// with Metal.
+#![cfg(not(target_vendor = "apple"))]
 #![allow(clippy::unwrap_used, clippy::expect_used, clippy::assert_is_empty)]
 
 mod common;

crates/ghostty-core/tests/e2e_keys.rs

@@ -1,6 +1,9 @@
 //! Keyboard input end to end: key events -> core Surface -> encoder -> pty ->
 //! a real `cat` child that records the exact bytes it received.
 
+// These drive the real surface over a headless OpenGL context; the Apple targets render
+// with Metal.
+#![cfg(not(target_vendor = "apple"))]
 #![allow(clippy::unwrap_used, clippy::expect_used)]
 
 mod common;

crates/ghostty-core/tests/e2e_mouse.rs

@@ -1,6 +1,9 @@
 //! Mouse end to end: selection, copy-on-select, multi-click, mouse reporting
 //! formats, alternate scroll, shift bypass and links.
 
+// These drive the real surface over a headless OpenGL context; the Apple targets render
+// with Metal.
+#![cfg(not(target_vendor = "apple"))]
 #![allow(clippy::unwrap_used, clippy::expect_used)]
 
 mod common;

crates/ghostty-core/tests/e2e_term.rs

@@ -1,6 +1,9 @@
 //! Terminal <-> runtime events: resize, focus, title, pwd, bell, OSC 52,
 //! notifications, progress, child exit.
 
+// These drive the real surface over a headless OpenGL context; the Apple targets render
+// with Metal.
+#![cfg(not(target_vendor = "apple"))]
 #![allow(clippy::unwrap_used, clippy::expect_used)]
 
 mod common;