refactor: improve API naming and add macOS cross-compilation CI

- Rename dispatchNoContext/bindNoContext to dispatchSimple/bindSimple
- Rename init to addInitScript to avoid conflict with Zig constructor
convention
- Make Status enum pub so callers can reference the type by name
- Mark mapError as inline
- Add macOS SDK cross-compilation steps to CI with caching

Author: happystraw

.github/workflows/doc.yml

@@ -38,7 +38,7 @@ jobs:
       - name: Setup Pages
         uses: actions/configure-pages@v3
       - uses: mlugg/setup-zig@v2
-      - name: Install development headers
+      - name: Install linux development libraries
         uses: awalsh128/cache-apt-pkgs-action@latest
         with:
           packages: libgtk-3-dev libwebkit2gtk-4.1-dev

.github/workflows/test.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
       - uses: mlugg/setup-zig@v2
-      - name: Install development headers
+      - name: Install linux development libraries
         uses: awalsh128/cache-apt-pkgs-action@latest
         with:
           packages: libgtk-3-dev libwebkit2gtk-4.1-dev
@@ -38,6 +38,22 @@ jobs:
       - name: Build examples (ReleaseSafe)
         run: |
           zig build examples -Doptimize=ReleaseSafe
-      - name: Build examples (Cross-compile for Windows ReleaseFast)
+      - name: Build examples (Cross-compile for Windows x86_64 ReleaseFast)
         run: |
           zig build examples -Dtarget=x86_64-windows -Doptimize=ReleaseFast
+      - name: Cache macOS SDK
+        id: cache-macos-sdk
+        uses: actions/cache@v4
+        with:
+          path: MacOSX15.5.sdk
+          key: macos-sdk-15.5
+      - name: Download macOS SDK
+        if: steps.cache-macos-sdk.outputs.cache-hit != 'true'
+        run: |
+          curl -L https://github.com/joseluisq/macosx-sdks/releases/download/15.5/MacOSX15.5.sdk.tar.xz | tar -xJ
+      - name: Build examples (Cross-compile for macOS aarch64 ReleaseFast)
+        run: |
+          zig build examples -Dtarget=aarch64-macos -Dmacos-sdk=${{ github.workspace }}/MacOSX15.5.sdk -Doptimize=ReleaseFast
+      - name: Build examples (Cross-compile for macOS x86_64 ReleaseFast)
+        run: |
+          zig build examples -Dtarget=x86_64-macos -Dmacos-sdk=${{ github.workspace }}/MacOSX15.5.sdk -Doptimize=ReleaseFast

README.md

@@ -2,7 +2,7 @@
 
 Zig bindings for [webview/webview](https://github.com/webview/webview) — a tiny cross-platform library for building desktop applications with web technologies using a native browser widget.
 
-Zig API with error unions, comptime-powered typed callbacks, and JS ↔ Zig bindings via `bind` / `respond`.
+Idiomatic Zig API featuring error unions and comptime-powered typed callbacks.
 
 ## Requirements
 
@@ -38,7 +38,7 @@ pub fn main() !void {
     defer w.destroy() catch unreachable;
     try w.setTitle("Hello");
     try w.setSize(800, 600, .none);
-    try w.navigate("https://example.com");
+    try w.setHtml("Thanks for using webview!");
     try w.run();
 }
 ```
@@ -67,15 +67,41 @@ Cross-compilation to macOS and Windows is supported.
 Obtain a macOS SDK (e.g. via [macosx-sdks](https://github.com/joseluisq/macosx-sdks)) and pass its path with `-Dmacos-sdk`:
 
 ```sh
-zig build -Dtarget=aarch64-macos -Dmacos-sdk=/path/to/MacOSX.sdk
+zig build examples -Dtarget=aarch64-macos -Dmacos-sdk=/path/to/MacOSX.sdk
 # or for x86_64
-zig build -Dtarget=x86_64-macos -Dmacos-sdk=/path/to/MacOSX.sdk
+zig build examples -Dtarget=x86_64-macos -Dmacos-sdk=/path/to/MacOSX.sdk
 ```
 
 **Targeting Windows**
 
 The required WebView2 headers are already bundled in `deps/WebView2/`, so no extra setup is needed:
 
 ```sh
-zig build -Dtarget=x86_64-windows
+zig build examples -Dtarget=x86_64-windows
 ```
+
+## C API to Zig API Mapping
+
+| C Function | Zig Method |
+|---|---|
+| `webview_create(debug, window)` | `Webview.create(debug, window) !*Webview` |
+| `webview_destroy(w)` | `w.destroy() !void` |
+| `webview_run(w)` | `w.run() !void` |
+| `webview_terminate(w)` | `w.terminate() !void` |
+| `webview_dispatch(w, fn, arg)` | `w.dispatchRaw(callback, arg) !void` |
+| `webview_dispatch(w, fn, arg)` | `w.dispatch(T, callback, arg) !void` |
+| `webview_dispatch(w, fn, null)` | `w.dispatchSimple(callback) !void` |
+| `webview_get_window(w)` | `w.getWindow() ?*anyopaque` |
+| `webview_get_native_handle(w, kind)` | `w.getNativeHandle(kind) ?*anyopaque` |
+| `webview_set_title(w, title)` | `w.setTitle(title) !void` |
+| `webview_set_size(w, width, height, hint)` | `w.setSize(width, height, hint) !void` |
+| `webview_navigate(w, url)` | `w.navigate(url) !void` |
+| `webview_set_html(w, html)` | `w.setHtml(html) !void` |
+| `webview_init(w, js)` | `w.addInitScript(js) !void` |
+| `webview_eval(w, js)` | `w.eval(js) !void` |
+| `webview_bind(w, name, fn, arg)` | `w.bindRaw(name, callback, arg) !void` |
+| `webview_bind(w, name, fn, arg)` | `w.bind(T, name, callback, arg) !void` |
+| `webview_bind(w, name, fn, null)` | `w.bindSimple(name, callback) !void` |
+| `webview_unbind(w, name)` | `w.unbind(name) !void` |
+| `webview_return(w, id, status, result)` | `w.respond(id, status, result) !void` |
+| `webview_version()` | `Webview.version() Version` |

build.zig

@@ -119,9 +119,7 @@ fn addExamplesStep(b: *std.Build, options: BuildOptions, mod: *std.Build.Module)
                 .{ .name = "webview", .module = mod },
             },
         });
-        if (options.target.result.os.tag == .macos) {
-            tryApplyMacOsSdk(b, example_mod, options);
-        }
+        tryApplyMacOsSdk(b, example_mod, options);
         const exe = b.addExecutable(.{
             .name = name,
             .root_module = example_mod,
@@ -157,8 +155,12 @@ fn createCModule(b: *std.Build, options: BuildOptions) *std.Build.Module {
     return c_mod;
 }
 
-fn tryApplyMacOsSdk(b: *std.Build, mod: *std.Build.Module, options: BuildOptions) void {
-    if (builtin.os.tag != .macos and options.macos_sdk != null) {
+/// Applies macOS SDK configuration for cross-compilation.
+///
+/// Automatically configures system include paths, library paths, and framework paths
+/// when cross-compiling for macOS from non-macOS hosts.
+pub fn tryApplyMacOsSdk(b: *std.Build, mod: *std.Build.Module, options: BuildOptions) void {
+    if (options.target.result.os.tag == .macos and builtin.os.tag != .macos and options.macos_sdk != null) {
         const macos_sdk_path: std.Build.LazyPath = .{ .cwd_relative = options.macos_sdk.? };
         mod.addSystemIncludePath(macos_sdk_path.path(b, "usr/include"));
         mod.addLibraryPath(macos_sdk_path.path(b, "usr/lib"));

src/root.zig

@@ -32,7 +32,7 @@ pub const Webview = opaque {
         /// Signifies that something does not exist.
         NotFound,
     };
-    fn mapError(err: c.webview_error_t) Error!void {
+    inline fn mapError(err: c.webview_error_t) Error!void {
         switch (err) {
             c.WEBVIEW_ERROR_OK => {},
             c.WEBVIEW_ERROR_MISSING_DEPENDENCY => return Error.MissingDependency,
@@ -104,7 +104,9 @@ pub const Webview = opaque {
     /// Returns `Error.MissingDependency` if WebView2 is unavailable on Windows.
     pub fn create(debug: bool, window: ?*anyopaque) Error!*Webview {
         const w = c.webview_create(@intFromBool(debug), window);
-        return @ptrCast(w orelse return Error.Unspecified);
+        if (w == null) return Error.Unspecified;
+        if (@intFromPtr(w) < 0) return mapError(@intFromPtr(w));
+        return @ptrCast(w);
     }
 
     /// Destroys a webview instance and closes the native window.
@@ -129,10 +131,10 @@ pub const Webview = opaque {
     /// this function can be used to schedule code to execute on the main/GUI
     /// thread and thereby make that execution safe in multi-threaded applications.
     ///
-    /// See also `dispatch` and `dispatchNoContext`
+    /// See also `dispatch` and `dispatchSimple`
     pub fn dispatchRaw(
         self: *Webview,
-        comptime callback: fn (w: *Webview, arg: ?*anyopaque) void,
+        callback: fn (w: *Webview, arg: ?*anyopaque) void,
         arg: ?*anyopaque,
     ) Error!void {
         const S = struct {
@@ -153,42 +155,36 @@ pub const Webview = opaque {
     /// Schedules a function to be invoked on the thread with the run/event loop,
     /// with a typed argument.
     ///
-    /// Like `dispatchRaw`, but the callback receives a `*T` pointer instead of
-    /// `?*anyopaque`. When `T` is `void`, no argument is passed and `arg` should
-    /// be `{}`.
+    /// Like `dispatchRaw`, but the callback receives a `*T` pointer instead of `?*anyopaque`,
+    /// providing type safety for the user-provided argument.
     ///
-    /// See also `dispatchNoContext`
+    /// See also `dispatchSimple`
     pub fn dispatch(
         self: *Webview,
         comptime T: type,
-        comptime callback: DispatchCallbackType(T),
-        arg: if (T == void) void else *T,
+        callback: DispatchCallbackType(T),
+        arg: *T,
     ) Error!void {
         const S = struct {
             fn cb(w: c.webview_t, a: ?*anyopaque) callconv(.c) void {
-                if (comptime T == void) {
-                    callback(.from(w));
-                } else {
-                    callback(.from(w), @ptrCast(@alignCast(a.?)));
-                }
+                callback(.from(w), @ptrCast(@alignCast(a.?)));
             }
         };
-        return mapError(c.webview_dispatch(
-            self.ptr(),
-            S.cb,
-            if (comptime T == void) null else @ptrCast(arg),
-        ));
+        return mapError(c.webview_dispatch(self.ptr(), S.cb, @ptrCast(arg)));
     }
 
     /// Schedules a function to be invoked on the thread with the run/event loop,
     /// without a user-provided argument.
-    ///
-    /// Shorthand for `dispatch(void, callback, {})`.
-    pub inline fn dispatchNoContext(
+    pub fn dispatchSimple(
         self: *Webview,
-        comptime callback: DispatchCallbackType(void),
+        callback: DispatchCallbackType(void),
     ) Error!void {
-        return self.dispatch(void, callback, {});
+        const S = struct {
+            fn cb(w: c.webview_t, _: ?*anyopaque) callconv(.c) void {
+                callback(.from(w));
+            }
+        };
+        return mapError(c.webview_dispatch(self.ptr(), S.cb, null));
     }
 
     /// Returns the native handle of the window associated with the webview
@@ -242,7 +238,7 @@ pub const Webview = opaque {
 
     /// Injects JavaScript code to be executed immediately upon loading a page.
     /// The code will be executed before `window.onload`.
-    pub fn init(self: *Webview, js: [:0]const u8) Error!void {
+    pub fn addInitScript(self: *Webview, js: [:0]const u8) Error!void {
         return mapError(c.webview_init(self.ptr(), js.ptr));
     }
 
@@ -263,7 +259,7 @@ pub const Webview = opaque {
     /// Returns `Error.Duplicate` if a binding already exists with the
     /// specified name.
     ///
-    /// See also `bind` and `bindNoContext`
+    /// See also `bind` and `bindSimple`
     pub fn bindRaw(
         self: *Webview,
         name: [:0]const u8,
@@ -289,46 +285,41 @@ pub const Webview = opaque {
     ///
     /// Like `bindRaw`, but the callback receives a `*T` pointer instead of `?*anyopaque`,
     /// providing type safety for the user-provided argument.
-    /// When `T` is `void`, no argument is passed and `arg` should be `{}`.
     ///
     /// Returns `Error.Duplicate` if a binding already exists with the specified name.
     ///
-    /// See also `bindNoContext`
+    /// See also `bindSimple`
     pub fn bind(
         self: *Webview,
         comptime T: type,
         name: [:0]const u8,
-        comptime callback: BindCallbackType(T),
-        arg: if (T == void) void else *T,
+        callback: BindCallbackType(T),
+        arg: *T,
     ) Error!void {
         const S = struct {
             fn cb(id: [*c]const u8, req: [*c]const u8, a: ?*anyopaque) callconv(.c) void {
-                if (comptime T == void) {
-                    callback(std.mem.span(id), std.mem.span(req));
-                } else {
-                    callback(std.mem.span(id), std.mem.span(req), @ptrCast(@alignCast(a.?)));
-                }
+                callback(std.mem.span(id), std.mem.span(req), @ptrCast(@alignCast(a.?)));
             }
         };
-        return mapError(c.webview_bind(
-            self.ptr(),
-            name.ptr,
-            S.cb,
-            if (comptime T == void) null else @ptrCast(arg),
-        ));
+        return mapError(c.webview_bind(self.ptr(), name.ptr, S.cb, @ptrCast(arg)));
     }
 
     /// Binds a function to a new global JavaScript function without a user-provided argument.
     ///
     /// Shorthand for `bind(void, name, callback, {})`.
     ///
     /// Returns `Error.Duplicate` if a binding already exists with the specified name.
-    pub inline fn bindNoContext(
+    pub fn bindSimple(
         self: *Webview,
         name: [:0]const u8,
-        comptime callback: BindCallbackType(void),
+        callback: BindCallbackType(void),
     ) Error!void {
-        return self.bind(void, name, callback, {});
+        const S = struct {
+            fn cb(id: [*c]const u8, req: [*c]const u8, _: ?*anyopaque) callconv(.c) void {
+                callback(std.mem.span(id), std.mem.span(req));
+            }
+        };
+        return mapError(c.webview_bind(self.ptr(), name.ptr, S.cb, null));
     }
 
     /// Removes a binding created with `bind`.
@@ -338,7 +329,7 @@ pub const Webview = opaque {
         return mapError(c.webview_unbind(self.ptr(), name.ptr));
     }
 
-    const Status = enum(i32) {
+    pub const Status = enum(i32) {
         ok = 0,
         err = 1,
         _,