Add managed browser launching

Author: jinzhongjia

README.md

@@ -49,6 +49,8 @@ The current phase provides:
 - loopback-only listening by default and caller-provided TLS for explicit
   public listening;
 - general OS URL opening and installed-browser discovery;
+- explicit browser launching with custom executable paths and argv;
+- per-window browser child identifiers and deterministic process cleanup;
 - default-browser launching and deterministic shutdown.
 
 ```zig
@@ -115,9 +117,17 @@ 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.
+platform order or `null`. Discovery probes Windows application registration,
+standard macOS application bundles, and executable candidates on other
+platforms without opening the selected browser.
+
+`Window.openWithBrowser(&running, options)` launches a selected `Browser`
+with an optional full executable path and additional argv. Chromium-family
+browsers receive an `--app=` URL argument; Firefox receives `-new-window`.
+The returned `BrowserProcessId`, also available through
+`Window.browserProcessId()`, is a PID on POSIX and a process handle on
+Windows. Each window retains at most one launched child; launching another
+replaces it, and `Running.stop()` kills and reaps every retained child.
 
 Serve a directory by setting
 `.content = .{ .directory = "path/to/public" }`. The path is opened when the

docs/PURE_ZIG_REFACTOR.md

@@ -297,15 +297,13 @@ implementations.
 
 | Upstream API | Current gap |
 |---|---|
-| `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. |
 | `webui_set_frameless()`, `webui_set_transparent()` | Frameless and transparent browser window modes are not implemented. |
 | `webui_set_high_contrast()`, `webui_is_high_contrast()` | High-contrast mode control and detection are not implemented. |
 | `webui_set_profile()`, `webui_delete_profile()`, `webui_delete_all_profiles()` | Managed browser profiles are not implemented. |
 | `webui_set_proxy()` | Browser proxy configuration is not implemented. |
-| `webui_get_parent_process_id()`, `webui_get_child_process_id()` | Browser process tracking is not implemented. |
+| `webui_get_parent_process_id()` | A portable parent-process numeric ID accessor is not implemented. |
 | `webui_set_runtime()` | Deno, Node.js, and Bun execution for served files is not implemented. |
 | `webui_show_wv()`, `webui_set_close_handler_wv()`, `webui_get_hwnd()`, `webui_win32_get_hwnd()` | Native WebView hosting and native window handles are outside the pure Zig browser core. |
 
@@ -331,6 +329,8 @@ not implementation gaps:
 | `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_show_browser()`, `webui_set_browser_folder()`, `webui_set_custom_parameters()` | `Window.openWithBrowser()` accepts a `BrowserLaunchOptions` value with an explicit browser, optional full executable path, and additional argv. |
+| `webui_get_child_process_id()` | `Window.openWithBrowser()` returns the retained direct child's `BrowserProcessId`; `Window.browserProcessId()` retrieves it later. |
 | `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. |
@@ -396,19 +396,23 @@ This completes `webui_show()`, `webui_show_client()`, `webui_is_shown()`,
 the dynamic root and file-handler methods, `webui_set_default_root_folder()`,
 `webui_set_icon()`, and `webui_set_icon_file()`.
 
-### Managed browsers and window controls
+### Managed browser launch (complete)
+
+Browser discovery, default URL opening, explicit browser selection, custom
+executable paths and argv, per-window direct child identifiers, replacement,
+and shutdown cleanup are implemented.
+
+This completes the browser discovery, selection, custom-parameter, and direct
+child tracking methods in the ledger.
+
+### Browser window controls
 
-- Discover supported browsers and select the best or an explicit browser.
-- Support a custom browser executable directory and caller-provided argv.
-- Expose a general URL opener.
-- Launch and retain managed browser processes and expose their process IDs.
 - Implement kiosk, focus, minimize, maximize, hidden, resizable, geometry,
   frameless, transparent, and high-contrast controls where the selected
   browser and platform support them.
 - Implement managed profiles and proxy configuration.
 
-This completes the browser selection, browser process, window control,
-profile, and proxy methods in the ledger.
+This completes the window control, profile, and proxy methods in the ledger.
 
 ### File monitoring (complete)
 
@@ -488,6 +492,6 @@ zig build -Dtarget=aarch64-macos
 
 Continue capability parity:
 
-1. Add explicit browser selection, custom executable locations, and custom
-   browser arguments.
-2. Launch and retain selected browser processes and expose their process IDs.
+1. Add typed browser launch controls for kiosk, hidden, high-contrast,
+   resizable, size, and position behavior.
+2. Add managed browser profiles and proxy configuration.

src/app.zig

@@ -63,6 +63,8 @@ pub const EventHandler = *const fn (
 ) anyerror!void;
 pub const Request = Linsang.Request;
 pub const Response = Linsang.Response;
+pub const BrowserLaunchOptions = browser.LaunchOptions;
+pub const BrowserProcessId = browser.ProcessId;
 
 pub const EventKind = enum {
     connected,
@@ -1546,6 +1548,41 @@ pub const Window = struct {
         try browser.openUrl(self.state.gpa, io, page_url);
     }
 
+    /// Launch and retain one explicitly selected browser process.
+    pub fn openWithBrowser(
+        self: Window,
+        running: *Running,
+        options: BrowserLaunchOptions,
+    ) !BrowserProcessId {
+        if (running.stopped or !running.app.started)
+            return error.NotRunning;
+        if (!running.app.hasWindow(self.state)) return error.UnknownWindow;
+        const page_url = try self.url(running, self.state.gpa);
+        defer self.state.gpa.free(page_url);
+        const child = try browser.launch(
+            self.state.gpa,
+            running.inner.io,
+            page_url,
+            options,
+        );
+        return running.app.manageBrowser(
+            running.inner.io,
+            self.state,
+            child,
+        );
+    }
+
+    /// Return the platform-native identifier of the retained browser child.
+    pub fn browserProcessId(
+        self: Window,
+        running: *const Running,
+    ) !?BrowserProcessId {
+        if (running.stopped or !running.app.started)
+            return error.NotRunning;
+        if (!running.app.hasWindow(self.state)) return error.UnknownWindow;
+        return running.app.browserId(running.inner.io, self.state);
+    }
+
     /// Return whether at least one browser client is connected.
     pub fn isShown(self: Window, io: std.Io) bool {
         return self.state.hasClients(io);
@@ -1712,6 +1749,13 @@ pub const Window = struct {
     }
 };
 
+const ManagedBrowser = struct {
+    // ponytail: exited launchers are reaped on replacement or stop; add wait
+    // tasks only if one bounded child per window becomes insufficient.
+    window: *WindowState,
+    child: std.process.Child,
+};
+
 pub const App = struct {
     gpa: std.mem.Allocator,
     options: Options,
@@ -1720,6 +1764,8 @@ pub const App = struct {
     server_io: ?std.Io = null,
     tls_auth: ?Linsang.tls.CertKeyPair = null,
     monitor_tasks: std.Io.Group = .init,
+    managed_browsers: std.ArrayList(ManagedBrowser) = .empty,
+    browser_mutex: std.Io.Mutex = .init,
     started: bool = false,
     closed: std.atomic.Value(bool) = .init(false),
     unauthenticated_connections: std.atomic.Value(usize) = .init(0),
@@ -1764,6 +1810,8 @@ pub const App = struct {
         std.debug.assert(self.server_io == null);
         std.debug.assert(self.tls_auth == null);
         std.debug.assert(self.monitor_tasks.token.load(.acquire) == null);
+        std.debug.assert(self.managed_browsers.items.len == 0);
+        self.managed_browsers.deinit(self.gpa);
         for (self.windows.items) |window| window.deinit();
         self.windows.deinit(self.gpa);
         self.* = undefined;
@@ -1917,6 +1965,51 @@ pub const App = struct {
         for (self.windows.items) |window| window.content.closeDirectory();
     }
 
+    fn manageBrowser(
+        self: *App,
+        io: std.Io,
+        window: *WindowState,
+        child: std.process.Child,
+    ) !BrowserProcessId {
+        var owned = child;
+        errdefer owned.kill(io);
+        const id = owned.id.?;
+
+        self.browser_mutex.lockUncancelable(io);
+        defer self.browser_mutex.unlock(io);
+        for (self.managed_browsers.items) |*managed| {
+            if (managed.window != window) continue;
+            managed.child.kill(io);
+            managed.child = owned;
+            return id;
+        }
+        try self.managed_browsers.append(self.gpa, .{
+            .window = window,
+            .child = owned,
+        });
+        return id;
+    }
+
+    fn browserId(
+        self: *App,
+        io: std.Io,
+        window: *WindowState,
+    ) ?BrowserProcessId {
+        self.browser_mutex.lockUncancelable(io);
+        defer self.browser_mutex.unlock(io);
+        for (self.managed_browsers.items) |*managed|
+            if (managed.window == window) return managed.child.id;
+        return null;
+    }
+
+    fn stopBrowsers(self: *App, io: std.Io) void {
+        self.browser_mutex.lockUncancelable(io);
+        defer self.browser_mutex.unlock(io);
+        for (self.managed_browsers.items) |*managed|
+            managed.child.kill(io);
+        self.managed_browsers.clearRetainingCapacity();
+    }
+
     fn hasWindow(self: *const App, state: *WindowState) bool {
         // ponytail: window counts are tiny; use a map if hundreds become normal.
         for (self.windows.items) |window|
@@ -1960,6 +2053,7 @@ pub const Running = struct {
         self.app.monitor_tasks.cancel(self.inner.io);
         for (self.app.windows.items) |window|
             window.cancelEvents(self.inner.io);
+        self.app.stopBrowsers(self.inner.io);
         self.app.closeDirectories();
         self.app.deinitTls();
         self.stopped = true;
@@ -3161,6 +3255,141 @@ fn authenticateTestClient(
     return std.mem.eql(u8, response.payload, &.{1});
 }
 
+fn readTestFileEventually(
+    dir: std.Io.Dir,
+    io: std.Io,
+    gpa: std.mem.Allocator,
+    path: []const u8,
+) ![]u8 {
+    for (0..100) |_| {
+        const data = dir.readFileAlloc(
+            io,
+            path,
+            gpa,
+            .limited(4096),
+        ) catch |err| {
+            if (err != error.FileNotFound) return err;
+            try std.Io.sleep(io, .fromMilliseconds(1), .awake);
+            continue;
+        };
+        return data;
+    }
+    return error.Timeout;
+}
+
+test "selected browser launch owns argv process and shutdown" {
+    if (@import("builtin").os.tag != .linux) return error.SkipZigTest;
+    const gpa = std.testing.allocator;
+    var threaded = std.Io.Threaded.init(gpa, .{ .async_limit = .unlimited });
+    defer threaded.deinit();
+    const io = threaded.io();
+
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    try tmp.dir.writeFile(io, .{
+        .sub_path = "fake-browser",
+        .data =
+        \\#!/bin/sh
+        \\output=$1
+        \\shift
+        \\printf '%s\n' "$@" > "$output"
+        \\exec sleep 30
+        ,
+        .flags = .{ .permissions = .executable_file },
+    });
+    const executable = try std.fmt.allocPrint(
+        gpa,
+        ".zig-cache/tmp/{s}/fake-browser",
+        .{tmp.sub_path},
+    );
+    defer gpa.free(executable);
+    const first_capture = try std.fmt.allocPrint(
+        gpa,
+        ".zig-cache/tmp/{s}/first-argv",
+        .{tmp.sub_path},
+    );
+    defer gpa.free(first_capture);
+    const second_capture = try std.fmt.allocPrint(
+        gpa,
+        ".zig-cache/tmp/{s}/second-argv",
+        .{tmp.sub_path},
+    );
+    defer gpa.free(second_capture);
+
+    var app = App.init(gpa, .{});
+    defer app.deinit();
+    const window = try app.createWindow(.{
+        .content = .{ .html = "managed browser" },
+    });
+    var running = try app.start(io);
+    defer running.stop() catch {};
+    try std.testing.expectError(
+        error.InvalidBrowserExecutable,
+        window.openWithBrowser(&running, .{
+            .browser = .firefox,
+            .executable = "",
+        }),
+    );
+    const page_url = try window.url(&running, gpa);
+    defer gpa.free(page_url);
+
+    const first_id = try window.openWithBrowser(&running, .{
+        .browser = .firefox,
+        .executable = executable,
+        .arguments = &.{ first_capture, "--private-window" },
+    });
+    try std.testing.expectEqual(
+        first_id,
+        (try window.browserProcessId(&running)).?,
+    );
+    const first_argv = try readTestFileEventually(
+        tmp.dir,
+        io,
+        gpa,
+        "first-argv",
+    );
+    defer gpa.free(first_argv);
+    const expected_first = try std.fmt.allocPrint(
+        gpa,
+        "--private-window\n-new-window\n{s}\n",
+        .{page_url},
+    );
+    defer gpa.free(expected_first);
+    try std.testing.expectEqualStrings(expected_first, first_argv);
+
+    const second_id = try window.openWithBrowser(&running, .{
+        .browser = .chromium,
+        .executable = executable,
+        .arguments = &.{ second_capture, "--guest" },
+    });
+    try std.testing.expectEqual(
+        second_id,
+        (try window.browserProcessId(&running)).?,
+    );
+    try std.testing.expectEqual(@as(usize, 1), app.managed_browsers.items.len);
+    const second_argv = try readTestFileEventually(
+        tmp.dir,
+        io,
+        gpa,
+        "second-argv",
+    );
+    defer gpa.free(second_argv);
+    const expected_second = try std.fmt.allocPrint(
+        gpa,
+        "--guest\n--app={s}\n",
+        .{page_url},
+    );
+    defer gpa.free(expected_second);
+    try std.testing.expectEqualStrings(expected_second, second_argv);
+
+    try running.stop();
+    try std.testing.expectEqual(@as(usize, 0), app.managed_browsers.items.len);
+    try std.testing.expectError(
+        error.NotRunning,
+        window.browserProcessId(&running),
+    );
+}
+
 test "directory monitor reloads changed window only" {
     if (@import("builtin").os.tag != .linux) return error.SkipZigTest;
     const gpa = std.testing.allocator;