@zogien/native-sdk 0.11.0-fork.4 → 0.11.0-fork.5

package/src/root.zig

@@ -270,6 +270,13 @@ pub const SaveDialogOptions = platform.SaveDialogOptions;
 pub const MessageDialogStyle = platform.MessageDialogStyle;
 pub const MessageDialogResult = platform.MessageDialogResult;
 pub const MessageDialogOptions = platform.MessageDialogOptions;
+pub const DialogRequestId = platform.DialogRequestId;
+pub const DialogKind = platform.DialogKind;
+pub const DialogOptions = platform.DialogOptions;
+pub const DialogOutcome = platform.DialogOutcome;
+pub const DialogResult = platform.DialogResult;
+pub const DialogCompletion = runtime.DialogCompletion;
+pub const DialogRequestOptions = runtime.DialogRequestOptions;
 pub const NotificationOptions = platform.NotificationOptions;
 pub const StatusItemId = platform.StatusItemId;
 pub const primary_status_item_id = platform.primary_status_item_id;

package/src/runtime/builtin_bridge.zig

@@ -52,6 +52,7 @@ pub fn RuntimeBuiltinBridge(comptime Runtime: type) type {
     const App = runtime_api.App(Runtime);
     const SystemServiceMethods = runtime_system_services.RuntimeSystemServices(Runtime);
     const WindowViewMethods = runtime_window_views.RuntimeWindowViews(Runtime);
+    const AsyncBridgeResponseSlot = @import("async_bridge.zig").AsyncBridgeResponseSlot(Runtime);
 
     return struct {
         const Self = @This();
@@ -125,15 +126,106 @@ pub fn RuntimeBuiltinBridge(comptime Runtime: type) type {
             return bridge.writeSuccessResponse(response_buffer, request.id, result);
         }
 
-        fn dispatchCompiledDialogBridgeCommand(self: *Runtime, request: bridge.Request, result_buffer: []u8, response_buffer: []u8) []const u8 {
+        fn dispatchCompiledDialogBridgeCommand(self: *Runtime, request: bridge.Request, message: platform.BridgeMessage, result_buffer: []u8, response_buffer: []u8) ?[]const u8 {
             const plan = builtin_coordination.route(self.builtin_coordination_policy.?, .dialog, request.command);
-            const result = switch (plan.verb()) {
-                .dialog_openFile => SystemServiceMethods.openFileDialogFromJson(self, request.payload, result_buffer) catch |err| return Self.writeCompiledBuiltinError(self, request.id, err, response_buffer),
-                .dialog_saveFile => SystemServiceMethods.saveFileDialogFromJson(self, request.payload, result_buffer) catch |err| return Self.writeCompiledBuiltinError(self, request.id, err, response_buffer),
-                .dialog_showMessage => SystemServiceMethods.showMessageDialogFromJson(self, request.payload, result_buffer) catch |err| return Self.writeCompiledBuiltinError(self, request.id, err, response_buffer),
+            const kind: platform.DialogKind = switch (plan.verb()) {
+                .dialog_openFile => .open,
+                .dialog_saveFile => .save,
+                .dialog_showMessage => .message,
                 else => return bridge.writeErrorResponse(response_buffer, request.id, .unknown_command, plan.unknownMessage()),
             };
-            return bridge.writeSuccessResponse(response_buffer, request.id, result);
+            return Self.startDialogBridgeCommand(self, kind, request, message, result_buffer, response_buffer);
+        }
+
+        /// Queue the dialog and answer the bridge request when it
+        /// finishes. Null means the response is deferred; a returned
+        /// response is an immediate refusal, or, on a platform without
+        /// asynchronous dialogs, the blocking dialog's answer.
+        fn startDialogBridgeCommand(self: *Runtime, kind: platform.DialogKind, request: bridge.Request, message: platform.BridgeMessage, result_buffer: []u8, response_buffer: []u8) ?[]const u8 {
+            var storage = json.StringStorage.init(result_buffer);
+            const options = SystemServiceMethods.dialogOptionsFromJson(kind, request.payload, &storage) catch |err| return Self.writeDialogBridgeError(self, request.id, err, response_buffer);
+            if (!self.options.platform.services.supportsAsyncDialogs()) return Self.answerDialogBridgeCommand(self, kind, request.id, options, result_buffer, response_buffer);
+            const slot =Self.reserveDialogBridgeResponse(self, message) catch |err| return Self.writeDialogBridgeError(self, request.id, err, response_buffer);
+            var tag: [1 + bridge.max_id_bytes]u8 = undefined;
+            tag[0] = @intFromEnum(kind);
+            @memcpy(tag[1..][0..request.id.len], request.id);
+            _ = self.requestDialog(.{
+                .options = options,
+                .parent_window_id = Self.openWindowId(self, message.window_id),
+            }, .{
+                .context = slot,
+                .tag = tag[0 .. 1 + request.id.len],
+                .on_result = Self.finishDialogBridgeCommand,
+            }) catch |err| {
+                slot.release();
+                return Self.writeDialogBridgeError(self, request.id, err, response_buffer);
+            };
+            return null;
+        }
+
+        fn finishDialogBridgeCommand(context: *anyopaque, runtime: *Runtime, tag: []const u8, result: platform.DialogResult) anyerror!void {
+            _ = runtime;
+            const slot: *AsyncBridgeResponseSlot = @ptrCast(@alignCast(context));
+            const kind: platform.DialogKind = @enumFromInt(tag[0]);
+            const id = tag[1..];
+            var result_buffer: [bridge.max_result_bytes]u8 = undefined;
+            var response_buffer: [bridge.max_response_bytes]u8 = undefined;
+            const response = if (result.outcome == .failed)
+                bridge.writeErrorResponse(&response_buffer, id, .internal_error, "Dialog could not be shown")
+            else if (SystemServiceMethods.writeDialogResultJson(kind, result, &result_buffer)) |value|
+                bridge.writeSuccessResponse(&response_buffer, id, value)
+            else |err|
+                bridge.writeErrorResponse(&response_buffer, id, builtinBridgeErrorCode(err), builtinBridgeErrorMessage(err));
+            try slot.respond(response);
+        }
+
+        /// Platforms without asynchronous dialogs (Chromium builds, the
+        /// null platform) answer from the blocking call, at once, as they
+        /// always have. `options` borrows `result_buffer`, which is free
+        /// again once the dialog has returned.
+        fn answerDialogBridgeCommand(self: *Runtime, kind: platform.DialogKind, id: []const u8, options: platform.DialogOptions, result_buffer: []u8, response_buffer: []u8) []const u8 {
+            var paths: [platform.max_dialog_paths_bytes]u8 = undefined;
+            const result: platform.DialogResult = switch (options) {
+                .open => |open| opened: {
+                    const opened = self.showOpenDialog(open, &paths) catch |err| return Self.writeDialogBridgeError(self, id, err, response_buffer);
+                    break :opened .{ .id = 0, .outcome = if (opened.count == 0) .cancelled else .selected, .paths = opened.paths, .count = opened.count };
+                },
+                .save => |save| saved: {
+                    const saved = self.showSaveDialog(save, paths[0..platform.max_dialog_path_bytes]) catch |err| return Self.writeDialogBridgeError(self, id, err, response_buffer);
+                    const path = saved orelse break :saved .{ .id = 0, .outcome = .cancelled };
+                    break :saved .{ .id = 0, .outcome = .selected, .paths = path, .count = 1 };
+                },
+                .message => |dialog| .{
+                    .id = 0,
+                    .outcome = .selected,
+                    .button = self.showMessageDialog(dialog) catch |err| return Self.writeDialogBridgeError(self, id, err, response_buffer),
+                },
+            };
+            const value = SystemServiceMethods.writeDialogResultJson(kind, result, result_buffer) catch |err| return Self.writeDialogBridgeError(self, id, err, response_buffer);
+            return bridge.writeSuccessResponse(response_buffer, id, value);
+        }
+
+        fn writeDialogBridgeError(self: *Runtime, id: []const u8, err: anyerror, output: []u8) []const u8 {
+            if (self.builtin_coordination_policy != null) return Self.writeCompiledBuiltinError(self, id, err, output);
+            return bridge.writeErrorResponse(output, id, builtinBridgeErrorCode(err), builtinBridgeErrorMessage(err));
+        }
+
+        fn reserveDialogBridgeResponse(self: *Runtime, message: platform.BridgeMessage) !*AsyncBridgeResponseSlot {
+            for (&self.async_bridge_responses) |*slot| {
+                if (slot.in_use) continue;
+                try slot.init(self, .{ .origin = message.origin, .window_id = message.window_id, .webview_label = message.webview_label });
+                return slot;
+            }
+            return error.AsyncBridgeResponseLimitReached;
+        }
+
+        /// The requesting window when the runtime knows it as open;
+        /// otherwise null lets the broker pick a parent.
+        fn openWindowId(self: *Runtime, window_id: platform.WindowId) ?platform.WindowId {
+            for (self.windows[0..self.window_count]) |window| {
+                if (window.info.id == window_id and window.info.open) return window_id;
+            }
+            return null;
         }
 
         fn dispatchCompiledOsBridgeCommand(self: *Runtime, request: bridge.Request, origin: []const u8, result_buffer: []u8, response_buffer: []u8) []const u8 {
@@ -306,17 +398,20 @@ pub fn RuntimeBuiltinBridge(comptime Runtime: type) type {
             return bridge.writeSuccessResponse(response_buffer, request.id, result);
         }
 
-        pub fn dispatchDialogBridgeCommand(self: *Runtime, request: bridge.Request, result_buffer: []u8, response_buffer: []u8) []const u8 {
-            if (self.builtin_coordination_policy != null) return Self.dispatchCompiledDialogBridgeCommand(self, request, result_buffer, response_buffer);
-            const result = if (std.mem.eql(u8, request.command, "native-sdk.dialog.openFile"))
-                SystemServiceMethods.openFileDialogFromJson(self, request.payload, result_buffer) catch |err| return bridge.writeErrorResponse(response_buffer, request.id, builtinBridgeErrorCode(err), builtinBridgeErrorMessage(err))
+        /// Dialog commands answer asynchronously: null means the response
+        /// will follow when the dialog finishes (see
+        /// `startDialogBridgeCommand`).
+        pub fn dispatchDialogBridgeCommand(self: *Runtime, request: bridge.Request, message: platform.BridgeMessage, result_buffer: []u8, response_buffer: []u8) ?[]const u8 {
+            if (self.builtin_coordination_policy != null) return Self.dispatchCompiledDialogBridgeCommand(self, request, message, result_buffer, response_buffer);
+            const kind: platform.DialogKind = if (std.mem.eql(u8, request.command, "native-sdk.dialog.openFile"))
+                .open
             else if (std.mem.eql(u8, request.command, "native-sdk.dialog.saveFile"))
-                SystemServiceMethods.saveFileDialogFromJson(self, request.payload, result_buffer) catch |err| return bridge.writeErrorResponse(response_buffer, request.id, builtinBridgeErrorCode(err), builtinBridgeErrorMessage(err))
+                .save
             else if (std.mem.eql(u8, request.command, "native-sdk.dialog.showMessage"))
-                SystemServiceMethods.showMessageDialogFromJson(self, request.payload, result_buffer) catch |err| return bridge.writeErrorResponse(response_buffer, request.id, builtinBridgeErrorCode(err), builtinBridgeErrorMessage(err))
+                .message
             else
                 return bridge.writeErrorResponse(response_buffer, request.id, .unknown_command, "Unknown dialog command");
-            return bridge.writeSuccessResponse(response_buffer, request.id, result);
+            return Self.startDialogBridgeCommand(self, kind, request, message, result_buffer, response_buffer);
         }
 
         pub fn dispatchOsBridgeCommand(self: *Runtime, request: bridge.Request, origin: []const u8, result_buffer: []u8, response_buffer: []u8) []const u8 {

package/src/runtime/core.zig

@@ -30,6 +30,7 @@ const runtime_session_state = @import("session_state.zig");
 const session_journal = @import("session_journal.zig");
 const runtime_state = @import("state.zig");
 const runtime_system_services = @import("system_services.zig");
+const runtime_dialogs = @import("dialogs.zig");
 const runtime_builtin_bridge = @import("builtin_bridge.zig");
 const runtime_view = @import("view.zig");
 const runtime_window_views = @import("window_views.zig");
@@ -110,6 +111,10 @@ const FocusTraversalDirection = runtime_state.FocusTraversalDirection;
 const copySourceInto = runtime_state.copySourceInto;
 const sourceWebViewUrl = runtime_state.sourceWebViewUrl;
 const AsyncBridgeResponseSlot = runtime_async_bridge.AsyncBridgeResponseSlot(Runtime);
+pub const DialogCompletion = runtime_dialogs.Completion(Runtime);
+pub const DialogRequestOptions = runtime_dialogs.DialogRequestOptions;
+pub const max_dialog_requests = runtime_dialogs.max_dialog_requests;
+pub const max_dialog_tag_bytes = runtime_dialogs.max_dialog_tag_bytes;
 const platformCursorFromCanvas = widget_bridge.platformCursorFromCanvas;
 const widgetRoleName = widget_bridge.widgetRoleName;
 const platformWidgetAccessibilityRole = widget_bridge.platformWidgetAccessibilityRole;
@@ -351,6 +356,8 @@ pub const Runtime = struct {
     /// copy bound, so `initAt` assigns it explicitly.
     frame_profile: runtime_frame_profile.FrameProfile = .{},
     async_bridge_responses: [max_async_bridge_responses]AsyncBridgeResponseSlot = [_]AsyncBridgeResponseSlot{.{}} ** max_async_bridge_responses,
+    /// Asynchronous dialogs in flight (see `dialogs.zig`).
+    dialog_broker: runtime_dialogs.Broker(Runtime) = .{},
     automation_windows: [automation.snapshot.max_windows]automation.snapshot.Window = undefined,
     /// Snapshot-side storage for the frame profile's per-stage stats
     /// (the snapshot Input only references runtime-owned memory).
@@ -562,6 +569,9 @@ pub const Runtime = struct {
             item.title = "";
             item.item_count = 0;
         }
+        // The dialog broker's result buffer exceeds the copy bound too;
+        // reset its bookkeeping and leave the buffer alone.
+        self.dialog_broker.reset();
         self.started_timestamp_ns = timestampToU64(nowNanoseconds());
         self.text_measure_provider = if (options.platform.services.measure_text_fn) |measure_fn|
             .{
@@ -600,6 +610,7 @@ pub const Runtime = struct {
     /// host) call it to return the storage.
     pub fn deinit(self: *Runtime) void {
         self.disarmMediaSurfaceWakes();
+        self.releaseDialogs();
         for (self.views[0..self.view_count]) |*view| {
             if (view.widget_text_bytes_heap_owned) self.owned_allocator.free(view.widget_text_bytes);
             if (view.canvas_widget_text_history_bytes_heap_owned) self.owned_allocator.free(view.canvas_widget_text_history_bytes);
@@ -832,6 +843,19 @@ pub const Runtime = struct {
     pub const showOpenDialog = SystemServiceMethods.showOpenDialog;
     pub const showSaveDialog = SystemServiceMethods.showSaveDialog;
     pub const showMessageDialog = SystemServiceMethods.showMessageDialog;
+
+    const DialogMethods = runtime_dialogs.RuntimeDialogs(Runtime);
+    pub const requestDialog = DialogMethods.requestDialog;
+    pub const requestOpenDialog = DialogMethods.requestOpenDialog;
+    pub const requestSaveDialog = DialogMethods.requestSaveDialog;
+    pub const requestMessageDialog = DialogMethods.requestMessageDialog;
+    pub const cancelDialog = DialogMethods.cancelDialog;
+    pub const adoptDialogResults = DialogMethods.adoptDialogResults;
+    pub const cancelDialogsForWindow = DialogMethods.cancelDialogsForWindow;
+    pub const abandonDialogs = DialogMethods.abandonDialogs;
+    pub const pendingDialogCount = DialogMethods.pendingDialogCount;
+    const releaseDialogs = DialogMethods.releaseDialogs;
+
     pub const showNotification = SystemServiceMethods.showNotification;
     pub const setCredential = SystemServiceMethods.setCredential;
     pub const getCredential = SystemServiceMethods.getCredential;
@@ -863,9 +887,6 @@ pub const Runtime = struct {
     const revealPathFromJson = SystemServiceMethods.revealPathFromJson;
     const addRecentDocumentFromJson = SystemServiceMethods.addRecentDocumentFromJson;
     const clearRecentDocumentsFromJson = SystemServiceMethods.clearRecentDocumentsFromJson;
-    const openFileDialogFromJson = SystemServiceMethods.openFileDialogFromJson;
-    const saveFileDialogFromJson = SystemServiceMethods.saveFileDialogFromJson;
-    const showMessageDialogFromJson = SystemServiceMethods.showMessageDialogFromJson;
 
     /// Start (or replace) a platform timer. The platform delivers `.timer`
     /// events carrying `id` until `cancelTimer` (or after the first fire when

package/src/runtime/dialog_tests.zig

@@ -0,0 +1,367 @@
+const support = @import("test_support.zig");
+const std = support.std;
+const geometry = support.geometry;
+const platform = support.platform;
+const App = support.App;
+const Runtime = support.Runtime;
+const TestHarness = support.TestHarness;
+const DialogCompletion = support.runtime_module.DialogCompletion;
+
+const Probe = struct {
+    calls: usize = 0,
+    ids: [8]platform.DialogRequestId = undefined,
+    outcomes: [8]platform.DialogOutcome = undefined,
+    last_paths: [256]u8 = undefined,
+    last_paths_len: usize = 0,
+    last_count: usize = 0,
+    last_button: platform.MessageDialogResult = .primary,
+    last_tag: [64]u8 = undefined,
+    last_tag_len: usize = 0,
+
+    fn completion(self: *Probe, tag: []const u8) DialogCompletion {
+        return .{ .context = self, .tag = tag, .on_result = onResult };
+    }
+
+    fn onResult(context: *anyopaque, runtime: *Runtime, tag: []const u8, result: platform.DialogResult) anyerror!void {
+        _ = runtime;
+        const self: *Probe = @ptrCast(@alignCast(context));
+        self.ids[self.calls] = result.id;
+        self.outcomes[self.calls] = result.outcome;
+        self.calls += 1;
+        self.last_paths_len = result.paths.len;
+        @memcpy(self.last_paths[0..result.paths.len], result.paths);
+        self.last_count = result.count;
+        self.last_button = result.button;
+        self.last_tag_len = tag.len;
+        @memcpy(self.last_tag[0..tag.len], tag);
+    }
+
+    fn paths(self: *const Probe) []const u8 {
+        return self.last_paths[0..self.last_paths_len];
+    }
+
+    fn tagText(self: *const Probe) []const u8 {
+        return self.last_tag[0..self.last_tag_len];
+    }
+};
+
+fn dialogApp(harness: *TestHarness()) App {
+    return .{ .context = harness, .name = "dialogs", .source = platform.WebViewSource.html("<p>Dialogs</p>") };
+}
+
+/// A started runtime whose null platform presents dialogs asynchronously.
+fn started() !*TestHarness() {
+    const harness = try startedBlocking();
+    harness.null_platform.useAsyncDialogs(&harness.runtime.options.platform.services);
+    return harness;
+}
+
+/// The null platform as app tests get it: blocking dialogs that answer at
+/// once.
+fn startedBlocking() !*TestHarness() {
+    const harness = try TestHarness().create(std.testing.allocator, .{});
+    errdefer harness.destroy(std.testing.allocator);
+    try harness.runtime.dispatchPlatformEvent(dialogApp(harness), .app_start);
+    return harness;
+}
+
+/// Deliver the wakes the platform posted, as a host loop would.
+fn deliverWakes(harness: *TestHarness()) !void {
+    while (harness.null_platform.takeWake()) |event| try harness.runtime.dispatchPlatformEvent(dialogApp(harness), event);
+}
+
+fn closeMainWindow(harness: *TestHarness()) !void {
+    try harness.runtime.dispatchPlatformEvent(dialogApp(harness), .{ .window_frame_changed = .{
+        .id = 1,
+        .label = "main",
+        .title = "",
+        .frame = geometry.RectF.init(0, 0, 720, 480),
+        .scale_factor = 1,
+        .open = false,
+        .focused = false,
+    } });
+}
+
+test "dialog requests return at once and complete on a later wake" {
+    const harness = try started();
+    defer harness.destroy(std.testing.allocator);
+    var probe: Probe = .{};
+
+    const id = try harness.runtime.requestOpenDialog(.{ .title = "Open", .allow_multiple = true }, null, probe.completion("request-1"));
+    try std.testing.expectEqual(@as(usize, 0), probe.calls);
+    const shown = harness.null_platform.findPresentedDialog(id).?;
+    try std.testing.expectEqual(platform.DialogKind.open, shown.kind);
+    try std.testing.expectEqual(@as(?platform.WindowId, 1), shown.parent_window_id);
+    try std.testing.expectEqualStrings("Open", shown.titleText());
+
+    try harness.null_platform.finishDialog(id, .selected, "/a.txt\n/b.txt", .primary);
+    try std.testing.expectEqual(@as(usize, 0), probe.calls);
+    try deliverWakes(harness);
+
+    try std.testing.expectEqual(@as(usize, 1), probe.calls);
+    try std.testing.expectEqual(id, probe.ids[0]);
+    try std.testing.expectEqual(platform.DialogOutcome.selected, probe.outcomes[0]);
+    try std.testing.expectEqualStrings("/a.txt\n/b.txt", probe.paths());
+    try std.testing.expectEqual(@as(usize, 2), probe.last_count);
+    try std.testing.expectEqualStrings("request-1", probe.tagText());
+    try std.testing.expectEqual(@as(usize, 0), harness.runtime.pendingDialogCount());
+}
+
+test "dialogs for one window show one at a time in request order" {
+    const harness = try started();
+    defer harness.destroy(std.testing.allocator);
+    var probe: Probe = .{};
+
+    const first = try harness.runtime.requestOpenDialog(.{}, null, probe.completion(""));
+    const second = try harness.runtime.requestMessageDialog(.{ .message = "Next" }, 1, probe.completion(""));
+    const detached = try harness.runtime.requestDialog(.{ .options = .{ .save = .{ .default_name = "a.txt" } }, .detached = true }, probe.completion(""));
+    try std.testing.expectEqual(@as(usize, 2), harness.null_platform.presentedDialogCount());
+    try std.testing.expect(harness.null_platform.findPresentedDialog(second) == null);
+    try std.testing.expectEqual(@as(?platform.WindowId, null), harness.null_platform.findPresentedDialog(detached).?.parent_window_id);
+
+    try harness.null_platform.finishDialog(first, .cancelled, "", .primary);
+    try deliverWakes(harness);
+    try std.testing.expect(harness.null_platform.findPresentedDialog(second) != null);
+
+    try harness.null_platform.finishDialog(detached, .selected, "/a.txt", .primary);
+    try deliverWakes(harness);
+    try harness.null_platform.finishDialog(second, .selected, "", .secondary);
+    try deliverWakes(harness);
+
+    try std.testing.expectEqual(@as(usize, 3), probe.calls);
+    try std.testing.expectEqualSlices(platform.DialogRequestId, &.{ first, detached, second }, probe.ids[0..3]);
+    try std.testing.expectEqual(platform.MessageDialogResult.secondary, probe.last_button);
+}
+
+test "cancelling a queued dialog never shows it and a presented one closes" {
+    const harness = try started();
+    defer harness.destroy(std.testing.allocator);
+    var probe: Probe = .{};
+
+    const first = try harness.runtime.requestOpenDialog(.{}, null, probe.completion(""));
+    const second = try harness.runtime.requestOpenDialog(.{}, null, probe.completion(""));
+    harness.runtime.cancelDialog(second);
+    try std.testing.expectEqual(@as(usize, 0), probe.calls);
+    try deliverWakes(harness);
+    try std.testing.expectEqual(@as(usize, 1), probe.calls);
+    try std.testing.expectEqual(second, probe.ids[0]);
+    try std.testing.expectEqual(platform.DialogOutcome.cancelled, probe.outcomes[0]);
+    try std.testing.expectEqual(@as(usize, 1), harness.null_platform.dialog_request_count);
+
+    harness.runtime.cancelDialog(first);
+    try std.testing.expectEqual(@as(usize, 1), harness.null_platform.dialog_cancel_count);
+    try deliverWakes(harness);
+    try std.testing.expectEqual(@as(usize, 2), probe.calls);
+    try std.testing.expectEqual(platform.DialogOutcome.cancelled, probe.outcomes[1]);
+    harness.runtime.cancelDialog(first);
+    try std.testing.expectEqual(@as(usize, 1), harness.null_platform.dialog_cancel_count);
+}
+
+test "closing the parent window cancels its dialogs and leaves others" {
+    const harness = try started();
+    defer harness.destroy(std.testing.allocator);
+    var probe: Probe = .{};
+
+    const shown = try harness.runtime.requestOpenDialog(.{}, null, probe.completion(""));
+    const queued = try harness.runtime.requestOpenDialog(.{}, null, probe.completion(""));
+    const detached = try harness.runtime.requestDialog(.{ .options = .{ .open = .{} }, .detached = true }, probe.completion(""));
+    try closeMainWindow(harness);
+    try deliverWakes(harness);
+
+    // Platform-reported results drain before the runtime's own.
+    try std.testing.expectEqual(@as(usize, 2), probe.calls);
+    try std.testing.expectEqualSlices(platform.DialogRequestId, &.{ shown, queued }, probe.ids[0..2]);
+    try std.testing.expectEqualSlices(platform.DialogOutcome, &.{ .cancelled, .cancelled }, probe.outcomes[0..2]);
+    try std.testing.expect(harness.null_platform.findPresentedDialog(detached) != null);
+}
+
+test "an app stop drops pending dialogs without running completions" {
+    const harness = try started();
+    defer harness.destroy(std.testing.allocator);
+    var probe: Probe = .{};
+
+    _ = try harness.runtime.requestOpenDialog(.{}, null, probe.completion(""));
+    _ = try harness.runtime.requestOpenDialog(.{}, null, probe.completion(""));
+    try harness.runtime.dispatchPlatformEvent(dialogApp(harness), .app_shutdown);
+    try std.testing.expectEqual(@as(usize, 0), harness.runtime.pendingDialogCount());
+    try std.testing.expectEqual(@as(usize, 1), harness.null_platform.dialog_cancel_count);
+    try deliverWakes(harness);
+    try std.testing.expectEqual(@as(usize, 0), probe.calls);
+}
+
+test "a dialog the platform cannot present reports failed" {
+    const harness = try started();
+    defer harness.destroy(std.testing.allocator);
+    var probe: Probe = .{};
+
+    harness.null_platform.fail_next_dialog_request = true;
+    const failed = try harness.runtime.requestOpenDialog(.{}, null, probe.completion(""));
+    const next = try harness.runtime.requestOpenDialog(.{}, null, probe.completion(""));
+    try deliverWakes(harness);
+    try std.testing.expectEqual(@as(usize, 1), probe.calls);
+    try std.testing.expectEqual(failed, probe.ids[0]);
+    try std.testing.expectEqual(platform.DialogOutcome.failed, probe.outcomes[0]);
+    try std.testing.expect(harness.null_platform.findPresentedDialog(next) != null);
+}
+
+test "platforms without asynchronous dialogs fall back to the blocking call" {
+    const harness = try startedBlocking();
+    defer harness.destroy(std.testing.allocator);
+    var probe: Probe = .{};
+
+    _ = try harness.runtime.requestOpenDialog(.{}, null, probe.completion(""));
+    try std.testing.expectEqual(@as(usize, 1), harness.null_platform.open_dialog_count);
+    try std.testing.expectEqual(@as(usize, 0), probe.calls);
+    try deliverWakes(harness);
+    try std.testing.expectEqual(@as(usize, 1), probe.calls);
+    try std.testing.expectEqualStrings("/tmp/native-sdk-open.txt", probe.paths());
+
+    harness.null_platform.message_dialog_result = .tertiary;
+    _ = try harness.runtime.requestMessageDialog(.{ .message = "Sure?" }, null, probe.completion(""));
+    try deliverWakes(harness);
+    try std.testing.expectEqual(platform.DialogOutcome.selected, probe.outcomes[1]);
+    try std.testing.expectEqual(platform.MessageDialogResult.tertiary, probe.last_button);
+}
+
+test "a completion may request the next dialog without jumping the queue" {
+    const harness = try started();
+    defer harness.destroy(std.testing.allocator);
+    const Chain = struct {
+        harness: *TestHarness(),
+        probe: Probe = .{},
+        third: platform.DialogRequestId = 0,
+
+        fn onResult(context: *anyopaque, runtime: *Runtime, tag: []const u8, result: platform.DialogResult) anyerror!void {
+            const self: *@This() = @ptrCast(@alignCast(context));
+            try Probe.onResult(&self.probe, runtime, tag, result);
+            if (self.third == 0) self.third = try runtime.requestOpenDialog(.{}, 1, .{ .context = self, .on_result = onResult });
+        }
+    };
+    var chain: Chain = .{ .harness = harness };
+
+    const first = try harness.runtime.requestOpenDialog(.{}, null, .{ .context = &chain, .on_result = Chain.onResult });
+    const second = try harness.runtime.requestOpenDialog(.{}, null, .{ .context = &chain, .on_result = Chain.onResult });
+    try harness.null_platform.finishDialog(first, .cancelled, "", .primary);
+    try deliverWakes(harness);
+    try std.testing.expect(chain.third != 0);
+    try std.testing.expect(harness.null_platform.findPresentedDialog(second) != null);
+    try std.testing.expect(harness.null_platform.findPresentedDialog(chain.third) == null);
+
+    try harness.null_platform.finishDialog(second, .cancelled, "", .primary);
+    try deliverWakes(harness);
+    try std.testing.expect(harness.null_platform.findPresentedDialog(chain.third) != null);
+}
+
+test "dialog requests are validated before they queue" {
+    const harness = try started();
+    defer harness.destroy(std.testing.allocator);
+    var probe: Probe = .{};
+
+    const long_tag = [_]u8{'t'} ** (support.runtime_module.max_dialog_tag_bytes + 1);
+    try std.testing.expectError(error.DialogTagTooLarge, harness.runtime.requestOpenDialog(.{}, null, probe.completion(&long_tag)));
+    try std.testing.expectError(error.InvalidDialogOptions, harness.runtime.requestMessageDialog(.{ .primary_button = "" }, null, probe.completion("")));
+    const long_title = [_]u8{'x'} ** (platform.max_dialog_title_bytes + 1);
+    try std.testing.expectError(error.DialogFieldTooLarge, harness.runtime.requestOpenDialog(.{ .title = &long_title }, null, probe.completion("")));
+    try std.testing.expectError(error.WindowNotFound, harness.runtime.requestOpenDialog(.{}, 99, probe.completion("")));
+    try std.testing.expectEqual(@as(usize, 0), harness.runtime.pendingDialogCount());
+
+    for (0..support.runtime_module.max_dialog_requests) |_| _ = try harness.runtime.requestOpenDialog(.{}, null, probe.completion(""));
+    try std.testing.expectError(error.DialogQueueFull, harness.runtime.requestOpenDialog(.{}, null, probe.completion("")));
+}
+
+test "a failing completion is recorded and the queue moves on" {
+    const harness = try started();
+    defer harness.destroy(std.testing.allocator);
+    const Failing = struct {
+        fn onResult(context: *anyopaque, runtime: *Runtime, tag: []const u8, result: platform.DialogResult) anyerror!void {
+            _ = .{ context, runtime, tag, result };
+            return error.CompletionFailed;
+        }
+    };
+    var probe: Probe = .{};
+    const first = try harness.runtime.requestOpenDialog(.{}, null, .{ .context = &probe, .on_result = Failing.onResult });
+    const second = try harness.runtime.requestOpenDialog(.{}, null, probe.completion(""));
+    const errors_before = harness.runtime.dispatch_error_total;
+    try harness.null_platform.finishDialog(first, .cancelled, "", .primary);
+    try deliverWakes(harness);
+    try std.testing.expectEqual(errors_before + 1, harness.runtime.dispatch_error_total);
+    try std.testing.expect(harness.null_platform.findPresentedDialog(second) != null);
+}
+
+fn allowDialogBridge(harness: *TestHarness()) void {
+    const permissions = struct {
+        const dialog = [_][]const u8{support.security.permission_dialog};
+        const commands = [_]support.bridge.CommandPolicy{
+            .{ .name = "native-sdk.dialog.openFile", .permissions = &dialog, .origins = &.{"zero://inline"} },
+            .{ .name = "native-sdk.dialog.saveFile", .permissions = &dialog, .origins = &.{"zero://inline"} },
+            .{ .name = "native-sdk.dialog.showMessage", .permissions = &dialog, .origins = &.{"zero://inline"} },
+        };
+    };
+    harness.runtime.options.security.permissions = &permissions.dialog;
+    harness.runtime.options.builtin_bridge = .{ .enabled = true, .commands = &permissions.commands };
+}
+
+fn sendBridge(harness: *TestHarness(), bytes: []const u8) !void {
+    try harness.runtime.dispatchPlatformEvent(dialogApp(harness), .{ .bridge_message = .{ .bytes = bytes, .origin = "zero://inline", .window_id = 1 } });
+}
+
+test "built-in bridge dialogs answer when the dialog finishes" {
+    const harness = try started();
+    defer harness.destroy(std.testing.allocator);
+    allowDialogBridge(harness);
+
+    try sendBridge(harness, "{\"id\":\"pick\",\"command\":\"native-sdk.dialog.openFile\",\"payload\":{\"title\":\"Pick\",\"allowMultiple\":true}}");
+    try std.testing.expectEqualStrings("", harness.null_platform.lastBridgeResponse());
+    const shown = harness.null_platform.findPresentedDialog(1).?;
+    try std.testing.expectEqualStrings("Pick", shown.titleText());
+    try std.testing.expectEqual(@as(?platform.WindowId, 1), shown.parent_window_id);
+
+    try harness.null_platform.finishDialog(1, .selected, "/a.txt\n/b.txt", .primary);
+    try deliverWakes(harness);
+    const response = harness.null_platform.lastBridgeResponse();
+    try std.testing.expect(std.mem.indexOf(u8, response, "\"id\":\"pick\"") != null);
+    try std.testing.expect(std.mem.indexOf(u8, response, "[\"/a.txt\",\"/b.txt\"]") != null);
+}
+
+test "built-in bridge dialogs report dismissal, cancellation and failure" {
+    const harness = try started();
+    defer harness.destroy(std.testing.allocator);
+    allowDialogBridge(harness);
+
+    try sendBridge(harness, "{\"id\":\"ask\",\"command\":\"native-sdk.dialog.showMessage\",\"payload\":{\"message\":\"Delete?\",\"primaryButton\":\"Delete\",\"secondaryButton\":\"Keep\"}}");
+    try harness.null_platform.finishDialog(1, .cancelled, "", .primary);
+    try deliverWakes(harness);
+    try std.testing.expect(std.mem.indexOf(u8, harness.null_platform.lastBridgeResponse(), "\"dismissed\"") != null);
+
+    try sendBridge(harness, "{\"id\":\"save\",\"command\":\"native-sdk.dialog.saveFile\",\"payload\":{\"defaultName\":\"a.txt\"}}");
+    try harness.null_platform.finishDialog(2, .cancelled, "", .primary);
+    try deliverWakes(harness);
+    const saved = harness.null_platform.lastBridgeResponse();
+    try std.testing.expect(std.mem.indexOf(u8, saved, "\"id\":\"save\"") != null);
+    try std.testing.expect(std.mem.indexOf(u8, saved, "null") != null);
+
+    harness.null_platform.fail_next_dialog_request = true;
+    try sendBridge(harness, "{\"id\":\"broken\",\"command\":\"native-sdk.dialog.openFile\",\"payload\":{}}");
+    try deliverWakes(harness);
+    const broken = harness.null_platform.lastBridgeResponse();
+    try std.testing.expect(std.mem.indexOf(u8, broken, "\"id\":\"broken\"") != null);
+    try std.testing.expect(std.mem.indexOf(u8, broken, "\"internal_error\"") != null);
+}
+
+test "built-in bridge dialogs on platforms without asynchronous dialogs answer at once" {
+    const harness = try startedBlocking();
+    defer harness.destroy(std.testing.allocator);
+    allowDialogBridge(harness);
+
+    try sendBridge(harness, "{\"id\":\"pick\",\"command\":\"native-sdk.dialog.openFile\",\"payload\":{\"title\":\"Pick\"}}");
+    const picked = harness.null_platform.lastBridgeResponse();
+    try std.testing.expect(std.mem.indexOf(u8, picked, "\"id\":\"pick\"") != null);
+    try std.testing.expect(std.mem.indexOf(u8, picked, "[\"/tmp/native-sdk-open.txt\"]") != null);
+
+    harness.null_platform.message_dialog_result = .secondary;
+    try sendBridge(harness, "{\"id\":\"ask\",\"command\":\"native-sdk.dialog.showMessage\",\"payload\":{\"message\":\"Delete?\",\"secondaryButton\":\"Keep\"}}");
+    try std.testing.expect(std.mem.indexOf(u8, harness.null_platform.lastBridgeResponse(), "\"secondary\"") != null);
+    try std.testing.expectEqual(@as(usize, 1), harness.null_platform.open_dialog_count);
+    try std.testing.expectEqual(@as(usize, 1), harness.null_platform.message_dialog_count);
+    try std.testing.expectEqual(@as(usize, 0), harness.runtime.pendingDialogCount());
+}