Add typed browser launch controls

Author: jinzhongjia

README.md

@@ -122,9 +122,12 @@ 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
+with an optional full executable path, additional argv, and typed kiosk,
+window size, window position, and high-contrast controls. Chromium-family
+browsers support all four controls; Firefox supports kiosk mode. Unsupported
+browser and control combinations return `error.UnsupportedBrowserControl`.
+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.

docs/PURE_ZIG_REFACTOR.md

@@ -30,7 +30,7 @@ deleted.
 | Server and security | HTTP, WebSocket, TLS, loopback/public policy, capabilities, Origin checks, cookies, and protocol limits are implemented. |
 | Browser bridge | Bindings, typed arguments and replies, events, deferred replies, JavaScript evaluation, raw data, navigation, and multiple clients are implemented. |
 | Content and lifecycle | HTML, directories, custom handlers, external URLs, runtime content replacement, default directories, favicons, directory monitoring, logging, and deterministic shutdown are implemented. |
-| Browser integration | Default URL opening, browser discovery, explicit browser selection, custom executables and argv, direct child tracking, replacement, and shutdown cleanup are implemented. |
+| Browser integration | Default URL opening, browser discovery, explicit browser selection, typed launch controls, custom executables and argv, direct child tracking, replacement, and shutdown cleanup are implemented. |
 | Current validation | `zig build test`, native builds, Windows x86_64 builds, macOS aarch64 builds, and Windows/macOS test-module cross-compilation pass. |
 
 Remaining work is limited to browser window controls and geometry, managed
@@ -321,10 +321,10 @@ implementations.
 
 | Upstream API | Current gap |
 |---|---|
-| `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_focus()`, `webui_minimize()`, `webui_maximize()`, `webui_set_hide()` | Runtime browser window lifecycle controls are not implemented. |
+| `webui_set_resizable()`, `webui_set_minimum_size()`, `webui_set_center()` | The remaining 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_is_high_contrast()` | Portable host high-contrast detection is 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()` | A portable parent-process numeric ID accessor is not implemented. |
@@ -354,6 +354,7 @@ not implementation gaps:
 | `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_set_kiosk()`, `webui_set_size()`, `webui_set_position()`, `webui_set_high_contrast()` | Typed `BrowserLaunchOptions` generate supported Chromium-family launch controls; Firefox also supports kiosk mode. Unsupported combinations return an error. |
 | `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. |
@@ -429,11 +430,13 @@ and shutdown cleanup are implemented.
 This completes the browser discovery, selection, custom-parameter, and direct
 child tracking methods in the ledger.
 
-### Browser window controls
+### Browser window controls (partial)
 
-- Implement kiosk, focus, minimize, maximize, hidden, resizable, geometry,
-  frameless, transparent, and high-contrast controls where the selected
-  browser and platform support them.
+- Typed kiosk, size, position, and high-contrast launch controls are
+  implemented where the selected browser supports them.
+- Implement focus, minimize, maximize, hidden, resizable, minimum-size,
+  centering, frameless, and transparent controls where the selected browser
+  and platform support them.
 - Implement managed profiles and proxy configuration.
 
 This completes the window control, profile, and proxy methods in the ledger.
@@ -516,6 +519,6 @@ zig build -Dtarget=aarch64-macos
 
 Continue capability parity:
 
-1. Add typed browser launch controls for kiosk, hidden, high-contrast,
-   resizable, size, and position behavior.
-2. Add managed browser profiles and proxy configuration.
+1. Add managed browser profiles and proxy configuration.
+2. Implement or explicitly reject the remaining platform-specific runtime
+   window controls.

src/browser.zig

@@ -16,11 +16,29 @@ pub const Browser = enum {
 };
 
 pub const LaunchOptions = struct {
+    pub const Size = struct {
+        width: u32,
+        height: u32,
+    };
+
+    pub const Position = struct {
+        x: i32,
+        y: i32,
+    };
+
     browser: Browser,
     /// Full path or PATH-resolvable executable name. Null uses discovery.
     executable: ?[]const u8 = null,
     /// Additional arguments inserted before the browser URL argument.
     arguments: []const []const u8 = &.{},
+    /// Start in kiosk mode. Supported by Chromium-family browsers and Firefox.
+    kiosk: bool = false,
+    /// Initial outer window size. Supported by Chromium-family browsers.
+    size: ?Size = null,
+    /// Initial window position. Supported by Chromium-family browsers.
+    position: ?Position = null,
+    /// Force native high-contrast UI. Supported by Chromium-family browsers.
+    high_contrast: bool = false,
 };
 
 /// PID on POSIX and a process handle on Windows.
@@ -73,6 +91,7 @@ pub fn launch(
     if (url.len == 0) return error.InvalidUrl;
     if (options.executable) |executable|
         if (executable.len == 0) return error.InvalidBrowserExecutable;
+    try validateLaunchOptions(options);
 
     const discovered = if (options.executable == null)
         try resolveExecutable(gpa, io, options.browser) orelse
@@ -82,32 +101,82 @@ pub fn launch(
     defer if (discovered) |executable| gpa.free(executable);
     const executable = options.executable orelse discovered.?;
 
-    var argv: std.ArrayList([]const u8) = .empty;
-    defer argv.deinit(gpa);
-    try argv.append(gpa, executable);
-    try argv.appendSlice(gpa, options.arguments);
-    const app_url = switch (options.browser) {
-        .firefox, .safari => null,
-        else => try std.fmt.allocPrint(gpa, "--app={s}", .{url}),
-    };
-    defer if (app_url) |argument| gpa.free(argument);
-    switch (options.browser) {
-        .firefox => {
-            try argv.append(gpa, "-new-window");
-            try argv.append(gpa, url);
-        },
-        .safari => try argv.append(gpa, url),
-        else => try argv.append(gpa, app_url.?),
-    }
+    var arena = std.heap.ArenaAllocator.init(gpa);
+    defer arena.deinit();
+    const argv = try buildLaunchArgv(
+        arena.allocator(),
+        executable,
+        url,
+        options,
+    );
 
     return std.process.spawn(io, .{
-        .argv = argv.items,
+        .argv = argv,
         .stdin = .ignore,
         .stdout = .ignore,
         .stderr = .ignore,
     });
 }
 
+fn buildLaunchArgv(
+    allocator: std.mem.Allocator,
+    executable: []const u8,
+    url: []const u8,
+    options: LaunchOptions,
+) ![]const []const u8 {
+    try validateLaunchOptions(options);
+
+    var argv: std.ArrayList([]const u8) = .empty;
+    try argv.append(allocator, executable);
+    try argv.appendSlice(allocator, options.arguments);
+    if (options.kiosk) try argv.append(allocator, "--kiosk");
+    if (options.size) |size| try argv.append(
+        allocator,
+        try std.fmt.allocPrint(
+            allocator,
+            "--window-size={d},{d}",
+            .{ size.width, size.height },
+        ),
+    );
+    if (options.position) |position| try argv.append(
+        allocator,
+        try std.fmt.allocPrint(
+            allocator,
+            "--window-position={d},{d}",
+            .{ position.x, position.y },
+        ),
+    );
+    if (options.high_contrast)
+        try argv.append(allocator, "--force-high-contrast");
+    switch (options.browser) {
+        .firefox => {
+            try argv.append(allocator, "-new-window");
+            try argv.append(allocator, url);
+        },
+        .safari => try argv.append(allocator, url),
+        else => try argv.append(
+            allocator,
+            try std.fmt.allocPrint(allocator, "--app={s}", .{url}),
+        ),
+    }
+    return argv.toOwnedSlice(allocator);
+}
+
+fn validateLaunchOptions(options: LaunchOptions) !void {
+    if (options.size) |size|
+        if (size.width == 0 or size.height == 0)
+            return error.InvalidWindowSize;
+    switch (options.browser) {
+        .firefox => if (options.size != null or
+            options.position != null or options.high_contrast)
+            return error.UnsupportedBrowserControl,
+        .safari => if (options.kiosk or options.size != null or
+            options.position != null or options.high_contrast)
+            return error.UnsupportedBrowserControl,
+        else => {},
+    }
+}
+
 fn commandSucceeds(
     gpa: std.mem.Allocator,
     io: std.Io,
@@ -334,6 +403,83 @@ fn preferredBrowsers() []const Browser {
     };
 }
 
+test "typed browser controls build supported argv" {
+    var arena = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena.deinit();
+
+    const chromium = try buildLaunchArgv(
+        arena.allocator(),
+        "/browser",
+        "https://127.0.0.1/",
+        .{
+            .browser = .chromium,
+            .arguments = &.{"--guest"},
+            .kiosk = true,
+            .size = .{ .width = 1280, .height = 720 },
+            .position = .{ .x = -20, .y = 30 },
+            .high_contrast = true,
+        },
+    );
+    const expected_chromium: []const []const u8 = &.{
+        "/browser",
+        "--guest",
+        "--kiosk",
+        "--window-size=1280,720",
+        "--window-position=-20,30",
+        "--force-high-contrast",
+        "--app=https://127.0.0.1/",
+    };
+    try std.testing.expectEqualDeep(expected_chromium, chromium);
+
+    const firefox = try buildLaunchArgv(
+        arena.allocator(),
+        "/firefox",
+        "https://127.0.0.1/",
+        .{ .browser = .firefox, .kiosk = true },
+    );
+    const expected_firefox: []const []const u8 = &.{
+        "/firefox",
+        "--kiosk",
+        "-new-window",
+        "https://127.0.0.1/",
+    };
+    try std.testing.expectEqualDeep(expected_firefox, firefox);
+
+    try std.testing.expectError(
+        error.InvalidWindowSize,
+        buildLaunchArgv(
+            arena.allocator(),
+            "/browser",
+            "https://127.0.0.1/",
+            .{
+                .browser = .chromium,
+                .size = .{ .width = 0, .height = 720 },
+            },
+        ),
+    );
+    try std.testing.expectError(
+        error.UnsupportedBrowserControl,
+        buildLaunchArgv(
+            arena.allocator(),
+            "/firefox",
+            "https://127.0.0.1/",
+            .{
+                .browser = .firefox,
+                .position = .{ .x = 0, .y = 0 },
+            },
+        ),
+    );
+    try std.testing.expectError(
+        error.UnsupportedBrowserControl,
+        buildLaunchArgv(
+            arena.allocator(),
+            "/safari",
+            "https://127.0.0.1/",
+            .{ .browser = .safari, .kiosk = true },
+        ),
+    );
+}
+
 test "browser candidates and preference order cover every browser" {
     try std.testing.expectError(
         error.InvalidUrl,