Split RPC files and add docs

Author: ItsMeSamey

build.zig

@@ -145,7 +145,9 @@ pub fn build(b: *Build) void {
     const minify_embedded_js = b.option(bool, "minify-embedded-js", "Minify embedded JS helpers with pure Zig asset processing (default: true)") orelse true;
     const minify_written_js = b.option(bool, "minify-written-js", "Minify written JS helper assets with pure Zig asset processing (default: false)") orelse false;
     const selected_example = b.option(ExampleChoice, "example", "Example to run with `zig build run` (default: all)") orelse .all;
-    const run_mode = b.option([]const u8, "run-mode", "Runtime launch order for examples. Presets: `webview`, `browser` (app-window), `web-tab`, `web-url`. Or ordered tokens (`webview,browser,web-url`, `browser,webview`, etc). Default: webview,browser,web-url") orelse "webview,browser,web-url";
+    const run_mode_option = b.option([]const u8, "run-mode", "Runtime launch order for examples. Presets: `webview`, `browser` (app-window), `web-tab`, `web-url`. Or ordered tokens (`webview,browser,web-url`, `browser,webview`, etc). Default: webview,browser,web-url");
+    const run_mode = run_mode_option orelse "webview,browser,web-url";
+    const run_mode_explicit = run_mode_option != null;
     const linux_webview_target = b.option([]const u8, "linux-webview-target", "Linux native webview runtime target for examples: `webview` (WebKit2GTK 4.1/4.0, default) or `webkitgtk-6`") orelse "webview";
     if (!isValidRunMode(run_mode)) {
         @panic("invalid -Drun-mode value: use `webview`, `browser`, `web-tab`, `web-url`, or an ordered comma-separated combination");
@@ -161,6 +163,7 @@ pub fn build(b: *Build) void {
     build_opts.addOption(bool, "enable_tls", enable_tls);
     build_opts.addOption(bool, "enable_webui_log", enable_webui_log);
     build_opts.addOption([]const u8, "run_mode", run_mode);
+    build_opts.addOption(bool, "run_mode_explicit", run_mode_explicit);
     build_opts.addOption([]const u8, "linux_webview_target", linux_webview_target);
     build_opts.addOption([]const u8, "runtime_helpers_embed_path", runtime_helpers_assets.embed_path);
     build_opts.addOption([]const u8, "runtime_helpers_written_path", runtime_helpers_assets.written_path);

examples/shared/demo_runner.zig

@@ -165,6 +165,13 @@ fn parseRunModeSpec(mode: []const u8) RunModeSpec {
     };
 }
 
+fn effectiveRunModeSpec(run_mode: []const u8, run_mode_explicit: bool, darling_runtime: bool) RunModeSpec {
+    if (darling_runtime and !run_mode_explicit) {
+        return parseRunModeSpec("web-tab");
+    }
+    return parseRunModeSpec(run_mode);
+}
+
 fn surfaceName(surface: webui.LaunchSurface) []const u8 {
     return switch (surface) {
         .native_webview => "native webview",
@@ -179,7 +186,11 @@ pub fn runExample(comptime kind: ExampleKind, comptime RpcMethods: type) !void {
 
     const allocator = gpa.allocator();
     const app_options = appOptionsFor(kind);
-    const run_mode_spec = parseRunModeSpec(webui.BuildFlags.run_mode);
+    const run_mode_spec = effectiveRunModeSpec(
+        webui.BuildFlags.run_mode,
+        webui.BuildFlags.run_mode_explicit,
+        webui.isDarlingRuntime(),
+    );
 
     var service = try webui.Service.init(allocator, RpcMethods, .{
         .app = app_options,
@@ -352,8 +363,11 @@ fn tagFor(comptime kind: ExampleKind) []const u8 {
 }
 
 fn appOptionsFor(comptime kind: ExampleKind) webui.AppOptions {
-    const run_mode = webui.BuildFlags.run_mode;
-    const run_mode_spec = parseRunModeSpec(run_mode);
+    const run_mode_spec = effectiveRunModeSpec(
+        webui.BuildFlags.run_mode,
+        webui.BuildFlags.run_mode_explicit,
+        webui.isDarlingRuntime(),
+    );
     const launch_policy = run_mode_spec.launch_policy;
     const launch_pref = run_mode_spec.browser_launch_preference;
     const native_first = launch_policy.first == .native_webview;
@@ -404,6 +418,18 @@ test "run-mode browser launch preference parser supports web-tab" {
     try std.testing.expectEqual(BrowserLaunchPreference.auto, parseRunModeSpec("web-url").browser_launch_preference);
 }
 
+test "darling default example mode switches to web-tab when run-mode was not explicit" {
+    const spec = effectiveRunModeSpec("webview,browser,web-url", false, true);
+    try std.testing.expectEqual(BrowserLaunchPreference.web_tab, spec.browser_launch_preference);
+    try std.testing.expectEqual(@as(webui.LaunchSurface, .web_url), spec.launch_policy.first);
+}
+
+test "explicit run-mode wins over darling default override" {
+    const spec = effectiveRunModeSpec("webview", true, true);
+    try std.testing.expectEqual(BrowserLaunchPreference.auto, spec.browser_launch_preference);
+    try std.testing.expectEqual(@as(webui.LaunchSurface, .native_webview), spec.launch_policy.first);
+}
+
 test "web-tab auto-open intent survives mixed fallback run-modes" {
     try std.testing.expect(shouldAutoOpenTab(parseRunModeSpec("web-tab")));
     try std.testing.expect(shouldAutoOpenTab(parseRunModeSpec("webview,web-tab,web-url")));

src/root.zig

@@ -2,6 +2,7 @@ const std = @import("std");
 
 const bridge_runtime_helpers = @import("bridge/runtime_helpers.zig");
 const core_runtime = @import("ported/webui.zig");
+const runtime_env = @import("ported/runtime_env.zig");
 const civetweb = @import("network/civetweb.zig");
 const tls_runtime = @import("network/tls_runtime.zig");
 const api_types = @import("root/api_types.zig");
@@ -52,6 +53,11 @@ pub fn defaultWebviewProfilePath(allocator: std.mem.Allocator) ![]u8 {
     return core_runtime.defaultWebviewProfilePath(allocator);
 }
 
+/// Returns whether a macOS-targeted binary is currently running under Darling.
+pub fn isDarlingRuntime() bool {
+    return runtime_env.isDarlingRuntime();
+}
+
 pub const Size = window_style_types.Size;
 pub const Point = window_style_types.Point;
 pub const WindowIcon = window_style_types.WindowIcon;

src/root/api_types.zig

@@ -12,6 +12,7 @@ pub const BuildFlags = struct {
     pub const enable_tls = build_options.enable_tls;
     pub const enable_webui_log = build_options.enable_webui_log;
     pub const run_mode = build_options.run_mode;
+    pub const run_mode_explicit = build_options.run_mode_explicit;
     pub const linux_webview_target = build_options.linux_webview_target;
 };