Add browser discovery APIs

Author: jinzhongjia

README.md

@@ -48,6 +48,7 @@ The current phase provides:
   `App.Options.use_cookies`;
 - loopback-only listening by default and caller-provided TLS for explicit
   public listening;
+- general OS URL opening and installed-browser discovery;
 - default-browser launching and deterministic shutdown.
 
 ```zig
@@ -111,6 +112,13 @@ outcome.
 it returns the first connected `Client`. `Window.eval()` uses the same total
 timeout for connection waiting and JavaScript execution.
 
+Call `openUrl(gpa, io, url)` to open any non-empty URL with the OS default
+handler. `browserExists(gpa, io, browser)` checks an explicit `Browser`, while
+`bestBrowser(gpa, io)` returns the first installed browser in the preferred
+platform order or `null`. Discovery probes registered applications on
+Windows and macOS and executable candidates on other platforms without
+opening the selected browser.
+
 Serve a directory by setting
 `.content = .{ .directory = "path/to/public" }`. The path is opened when the
 app starts and closed when it stops. Custom resources receive `webui.Request`

docs/PURE_ZIG_REFACTOR.md

@@ -297,8 +297,7 @@ implementations.
 
 | Upstream API | Current gap |
 |---|---|
-| `webui_open_url()` | The internal OS URL opener is not exposed as a general public API. |
-| `webui_get_best_browser()`, `webui_browser_exist()`, `webui_show_browser()`, `webui_set_browser_folder()` | Browser discovery, selection, and custom executable locations are not implemented. |
+| `webui_show_browser()`, `webui_set_browser_folder()` | Explicit browser selection and custom executable locations are not implemented. |
 | `webui_set_custom_parameters()` | Custom browser command-line arguments are not implemented. |
 | `webui_set_kiosk()`, `webui_focus()`, `webui_minimize()`, `webui_maximize()`, `webui_set_hide()` | Browser window mode and lifecycle controls are not implemented. |
 | `webui_set_resizable()`, `webui_set_size()`, `webui_set_minimum_size()`, `webui_set_position()`, `webui_set_center()` | Browser window geometry controls are not implemented. |
@@ -330,6 +329,8 @@ not implementation gaps:
 | `webui_show()`, `webui_start_server()`, `webui_get_url()` | Initial `Content`, runtime `Window.setContent()`, `App.start()`, `Window.open()`, and `Window.url()`. |
 | `webui_show_client()` | `Client.show()` replaces the window content and navigates only the selected client. |
 | `webui_is_shown()` | `Window.isShown()` reports whether the window has at least one connected browser client. |
+| `webui_open_url()` | `openUrl()` safely passes a non-empty URL as one argument to the platform default opener. |
+| `webui_get_best_browser()`, `webui_browser_exist()` | `bestBrowser()` and `browserExists()` discover registered or executable browser candidates through the public `Browser` enum. |
 | `webui_set_default_root_folder()` | `App.Options.default_directory` supplies directory content to windows created without explicit content. |
 | `webui_set_config(folder_monitor)` | `App.Options.folder_monitor_interval` enables portable recursive directory polling and reloads the affected window's connected clients. |
 | `webui_set_icon()`, `webui_set_icon_file()` | `Window.setIcon()` copies inline data and MIME type; `Window.setIconFile()` loads a supported image file as the window favicon. |
@@ -487,6 +488,6 @@ zig build -Dtarget=aarch64-macos
 
 Continue capability parity:
 
-1. Expose a general OS URL opener and browser discovery queries.
-2. Add explicit browser selection, custom executable locations, and custom
+1. Add explicit browser selection, custom executable locations, and custom
    browser arguments.
+2. Launch and retain selected browser processes and expose their process IDs.

src/app.zig

@@ -1543,7 +1543,7 @@ pub const Window = struct {
     pub fn open(self: Window, io: std.Io, running: *const Running) !void {
         const page_url = try self.url(running, self.state.gpa);
         defer self.state.gpa.free(page_url);
-        try browser.open(self.state.gpa, io, page_url);
+        try browser.openUrl(self.state.gpa, io, page_url);
     }
 
     /// Return whether at least one browser client is connected.

src/browser.zig

@@ -1,22 +1,250 @@
 const std = @import("std");
 const builtin = @import("builtin");
 
-pub fn open(gpa: std.mem.Allocator, io: std.Io, url: []const u8) !void {
-    const result = switch (builtin.os.tag) {
-        .windows => try std.process.run(gpa, io, .{
-            .argv = &.{ "explorer.exe", url },
-        }),
-        .macos => try std.process.run(gpa, io, .{
-            .argv = &.{ "open", url },
-        }),
-        else => try std.process.run(gpa, io, .{
-            .argv = &.{ "xdg-open", url },
+/// Browser families supported by discovery and explicit selection.
+pub const Browser = enum {
+    chrome,
+    firefox,
+    edge,
+    safari,
+    chromium,
+    opera,
+    brave,
+    vivaldi,
+    epic,
+    yandex,
+};
+
+/// Open a non-empty URL with the operating system's default handler.
+pub fn openUrl(
+    gpa: std.mem.Allocator,
+    io: std.Io,
+    url: []const u8,
+) !void {
+    if (url.len == 0) return error.InvalidUrl;
+    const argv: []const []const u8 = switch (builtin.os.tag) {
+        .windows => &.{ "explorer.exe", url },
+        .macos => &.{ "open", url },
+        else => &.{ "xdg-open", url },
+    };
+    if (!try commandSucceeds(gpa, io, argv))
+        return error.BrowserOpenFailed;
+}
+
+/// Return whether a browser is registered or available as an executable.
+pub fn browserExists(
+    gpa: std.mem.Allocator,
+    io: std.Io,
+    selected: Browser,
+) !bool {
+    return switch (builtin.os.tag) {
+        .windows => windowsBrowserExists(gpa, io, selected),
+        .macos => commandSucceeds(gpa, io, &.{
+            "open",
+            "-R",
+            "-a",
+            macosApplication(selected),
         }),
+        else => for (linuxExecutables(selected)) |executable| {
+            if (try commandSucceeds(gpa, io, &.{ executable, "--version" }))
+                break true;
+        } else false,
+    };
+}
+
+/// Return the first available browser in the platform preference order.
+pub fn bestBrowser(
+    gpa: std.mem.Allocator,
+    io: std.Io,
+) !?Browser {
+    for (preferredBrowsers()) |selected|
+        if (try browserExists(gpa, io, selected)) return selected;
+    return null;
+}
+
+fn commandSucceeds(
+    gpa: std.mem.Allocator,
+    io: std.Io,
+    argv: []const []const u8,
+) !bool {
+    const result = std.process.run(gpa, io, .{
+        .argv = argv,
+    }) catch |err| switch (err) {
+        error.FileNotFound, error.AccessDenied, error.InvalidExe => return false,
+        else => return err,
     };
     defer gpa.free(result.stdout);
     defer gpa.free(result.stderr);
-    switch (result.term) {
-        .exited => |code| if (code != 0) return error.BrowserOpenFailed,
-        else => return error.BrowserOpenFailed,
+    return switch (result.term) {
+        .exited => |code| code == 0,
+        else => false,
+    };
+}
+
+fn windowsBrowserExists(
+    gpa: std.mem.Allocator,
+    io: std.Io,
+    selected: Browser,
+) !bool {
+    const executable = windowsExecutable(selected);
+    if (try commandSucceeds(gpa, io, &.{ "where.exe", executable }))
+        return true;
+    // ponytail: Chrome and Chromium share chrome.exe on Windows; inspect
+    // installation metadata if standalone Chromium detection becomes needed.
+    if (selected == .chromium) return false;
+
+    var key_buffer: [160]u8 = undefined;
+    for ([_][]const u8{ "HKCU", "HKLM" }) |root| {
+        const key = try std.fmt.bufPrint(
+            &key_buffer,
+            "{s}\\Software\\Microsoft\\Windows\\CurrentVersion\\" ++
+                "App Paths\\{s}",
+            .{ root, executable },
+        );
+        if (try commandSucceeds(gpa, io, &.{
+            "reg.exe",
+            "query",
+            key,
+            "/ve",
+        })) return true;
+    }
+    return false;
+}
+
+fn windowsExecutable(selected: Browser) []const u8 {
+    return switch (selected) {
+        .chrome => "chrome.exe",
+        .firefox => "firefox.exe",
+        .edge => "msedge.exe",
+        .safari => "Safari.exe",
+        .chromium => "chromium.exe",
+        .opera => "opera.exe",
+        .brave => "brave.exe",
+        .vivaldi => "vivaldi.exe",
+        .epic => "epic.exe",
+        .yandex => "browser.exe",
+    };
+}
+
+fn macosApplication(selected: Browser) []const u8 {
+    return switch (selected) {
+        .chrome => "Google Chrome",
+        .firefox => "Firefox",
+        .edge => "Microsoft Edge",
+        .safari => "Safari",
+        .chromium => "Chromium",
+        .opera => "Opera",
+        .brave => "Brave Browser",
+        .vivaldi => "Vivaldi",
+        .epic => "Epic",
+        .yandex => "Yandex",
+    };
+}
+
+fn linuxExecutables(selected: Browser) []const []const u8 {
+    return switch (selected) {
+        .chrome => &.{ "google-chrome", "google-chrome-stable" },
+        .firefox => &.{"firefox"},
+        .edge => &.{
+            "microsoft-edge-stable",
+            "microsoft-edge-beta",
+            "microsoft-edge-dev",
+        },
+        .safari => &.{},
+        .chromium => &.{ "chromium-browser", "chromium" },
+        .opera => &.{"opera"},
+        .brave => &.{
+            "brave",
+            "brave-browser",
+            "brave-browser-stable",
+            "brave-browser-nightly",
+            "brave-browser-beta",
+        },
+        .vivaldi => &.{ "vivaldi", "vivaldi-stable", "vivaldi-snapshot" },
+        .epic => &.{"epic"},
+        .yandex => &.{"yandex-browser"},
+    };
+}
+
+fn preferredBrowsers() []const Browser {
+    return switch (builtin.os.tag) {
+        .windows => &.{
+            .chrome,
+            .edge,
+            .epic,
+            .vivaldi,
+            .brave,
+            .firefox,
+            .yandex,
+            .chromium,
+            .opera,
+            .safari,
+        },
+        else => &.{
+            .chrome,
+            .edge,
+            .chromium,
+            .epic,
+            .vivaldi,
+            .brave,
+            .firefox,
+            .yandex,
+            .opera,
+            .safari,
+        },
+    };
+}
+
+test "browser candidates and preference order cover every browser" {
+    try std.testing.expectError(
+        error.InvalidUrl,
+        openUrl(std.testing.allocator, std.testing.io, ""),
+    );
+    try std.testing.expectEqualStrings(
+        "chrome.exe",
+        windowsExecutable(.chrome),
+    );
+    try std.testing.expectEqualStrings(
+        "Google Chrome",
+        macosApplication(.chrome),
+    );
+    try std.testing.expectEqualStrings(
+        "google-chrome",
+        linuxExecutables(.chrome)[0],
+    );
+
+    var seen: std.EnumSet(Browser) = .initEmpty();
+    for (preferredBrowsers()) |selected| {
+        try std.testing.expect(!seen.contains(selected));
+        seen.insert(selected);
+    }
+    try std.testing.expectEqual(
+        std.meta.fields(Browser).len,
+        seen.count(),
+    );
+    try std.testing.expectEqual(Browser.chrome, preferredBrowsers()[0]);
+
+    if (builtin.os.tag == .linux) {
+        try std.testing.expect(try commandSucceeds(
+            std.testing.allocator,
+            std.testing.io,
+            &.{"/bin/true"},
+        ));
+        try std.testing.expect(!try commandSucceeds(
+            std.testing.allocator,
+            std.testing.io,
+            &.{"/bin/false"},
+        ));
+        try std.testing.expect(!try commandSucceeds(
+            std.testing.allocator,
+            std.testing.io,
+            &.{"/definitely/missing/browser"},
+        ));
+        if (try bestBrowser(std.testing.allocator, std.testing.io)) |selected|
+            try std.testing.expect(try browserExists(
+                std.testing.allocator,
+                std.testing.io,
+                selected,
+            ));
     }
 }

src/root.zig

@@ -23,9 +23,14 @@ pub const Response = @import("app.zig").Response;
 pub const BroadcastEvalOutcome = @import("app.zig").BroadcastEvalOutcome;
 pub const BroadcastEval = @import("app.zig").BroadcastEval;
 pub const BroadcastEvalResults = @import("app.zig").BroadcastEvalResults;
+pub const Browser = @import("browser.zig").Browser;
+pub const openUrl = @import("browser.zig").openUrl;
+pub const browserExists = @import("browser.zig").browserExists;
+pub const bestBrowser = @import("browser.zig").bestBrowser;
 pub const protocol = @import("protocol.zig");
 
 test {
     _ = @import("app.zig");
+    _ = @import("browser.zig");
     _ = protocol;
 }