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

package/src/platform/macos/cef_host.mm

@@ -3712,6 +3712,27 @@ int native_sdk_appkit_show_message_dialog(native_sdk_appkit_host_t *host, const
     }
 }
 
+/* Asynchronous dialogs are not offered here: root.zig leaves them unbound
+ * for the Chromium engine, so the runtime shows the blocking ones above. */
+int native_sdk_appkit_request_dialog(native_sdk_appkit_host_t *host, const native_sdk_appkit_dialog_request_t *request) {
+    (void)host;
+    (void)request;
+    return 0;
+}
+
+void native_sdk_appkit_cancel_dialog(native_sdk_appkit_host_t *host, uint64_t id) {
+    (void)host;
+    (void)id;
+}
+
+int native_sdk_appkit_poll_dialog_result(native_sdk_appkit_host_t *host, char *buffer, size_t buffer_len, native_sdk_appkit_dialog_result_t *result) {
+    (void)host;
+    (void)buffer;
+    (void)buffer_len;
+    (void)result;
+    return 0;
+}
+
 static NSImage *NativeSdkCefTrayImageWithOpacity(NSImage *source, double opacity) {
     if (!source) return nil;
     const CGFloat fraction = MAX(0.0, MIN(1.0, opacity));

package/src/platform/macos/root.zig

@@ -9,6 +9,7 @@ const canvas = @import("canvas");
 // macOS mask/inset render so the Dock tile matches `native package`.
 const app_icon = canvas.app_icon;
 const updater_c_api = @import("../../updater/c_api.zig");
+const update_feed = @import("../../updater/feed.zig");
 
 comptime {
     _ = updater_c_api.native_sdk_update_verify_feed;
@@ -355,6 +356,23 @@ const AppKitMessageDialogOpts = extern struct {
     tertiary_button_len: usize,
 };
 
+const AppKitDialogRequest = extern struct {
+    id: u64,
+    parent_window_id: u64,
+    kind: c_int,
+    open_opts: ?*const AppKitOpenDialogOpts,
+    save_opts: ?*const AppKitSaveDialogOpts,
+    message_opts: ?*const AppKitMessageDialogOpts,
+};
+
+const AppKitDialogResult = extern struct {
+    id: u64,
+    outcome: c_int,
+    button: c_int,
+    count: usize,
+    bytes_written: usize,
+};
+
 const AppKitWidgetAccessibilityNode = extern struct {
     id: u64,
     parent_id: u64,
@@ -461,6 +479,9 @@ const AppKitTrayChartRow = extern struct {
 extern fn native_sdk_appkit_show_open_dialog(host: *AppKitHost, opts: *const AppKitOpenDialogOpts, buffer: [*]u8, buffer_len: usize) AppKitOpenDialogResult;
 extern fn native_sdk_appkit_show_save_dialog(host: *AppKitHost, opts: *const AppKitSaveDialogOpts, buffer: [*]u8, buffer_len: usize) usize;
 extern fn native_sdk_appkit_show_message_dialog(host: *AppKitHost, opts: *const AppKitMessageDialogOpts) c_int;
+extern fn native_sdk_appkit_request_dialog(host: *AppKitHost, request: *const AppKitDialogRequest) c_int;
+extern fn native_sdk_appkit_cancel_dialog(host: *AppKitHost, id: u64) void;
+extern fn native_sdk_appkit_poll_dialog_result(host: *AppKitHost, buffer: [*]u8, buffer_len: usize, result: *AppKitDialogResult) c_int;
 extern fn native_sdk_appkit_create_tray(host: *AppKitHost, status_item_id: u32, icon_path: [*]const u8, icon_path_len: usize, title: [*]const u8, title_len: usize, tooltip: [*]const u8, tooltip_len: usize, visible: c_int, width: f64, tone: c_int, icon_opacity: f64, monospaced: c_int, font_size: f64, font_weight: c_int, activation_command: [*]const u8, activation_command_len: usize, alternate_activation_command: [*]const u8, alternate_activation_command_len: usize, open_command: [*]const u8, open_command_len: usize) void;
 extern fn native_sdk_appkit_update_tray_shell(host: *AppKitHost, status_item_id: u32, icon_path: [*]const u8, icon_path_len: usize, tooltip: [*]const u8, tooltip_len: usize, visible: c_int, activation_command: [*]const u8, activation_command_len: usize, alternate_activation_command: [*]const u8, alternate_activation_command_len: usize, open_command: [*]const u8, open_command_len: usize) void;
 extern fn native_sdk_appkit_update_tray_menu(host: *AppKitHost, status_item_id: u32, item_ids: [*]const u32, labels: [*]const [*]const u8, label_lens: [*]const usize, separators: [*]const c_int, enabled_flags: [*]const c_int, details: [*]const [*]const u8, detail_lens: [*]const usize, roles: [*]const c_int, keys: [*]const [*]const u8, key_lens: [*]const usize, modifiers: [*]const u32, count: usize) void;
@@ -685,12 +706,10 @@ pub const MacPlatform = struct {
         const dock_icon = planDockIcon(app_info.icon_path);
         const icon_path = if (dock_icon == .host_file) app_info.icon_path else "";
         const host = native_sdk_appkit_create(app_info.app_name.ptr, app_info.app_name.len, display_name.ptr, display_name.len, app_info.version.ptr, app_info.version.len, app_info.description.ptr, app_info.description.len, if (app_info.has_web_content) 1 else 0, if (app_info.dock_visible) 1 else 0, window_title.ptr, window_title.len, app_info.bundle_id.ptr, app_info.bundle_id.len, icon_path.ptr, icon_path.len, window_options.label.ptr, window_options.label.len, frame.x, frame.y, frame.width, frame.height, if (window_options.restore_state) 1 else 0, initialPlacementInt(window_options.initial_placement), restorePolicyInt(window_options.restore_policy), if (window_options.resizable) 1 else 0, titlebarStyleInt(window_options.titlebar), showModeInt(window_options.show), windowFlags(window_options)) orelse return error.CreateFailed;
-        const update_target = comptime switch (builtin.cpu.arch) {
-            .aarch64 => "macos-aarch64",
-            .x86_64 => "macos-x86_64",
-            else => "macos-unsupported",
-        };
-        native_sdk_appkit_configure_updates(host, app_info.update_feed_url.ptr, app_info.update_feed_url.len, app_info.update_public_key.ptr, app_info.update_public_key.len, if (app_info.update_check_on_start) 1 else 0, update_target.ptr, update_target.len);
+        const update_target = comptime update_feed.currentTarget() orelse "macos-unsupported";
+        var update_feed_url_buffer: [update_feed.max_feed_url_bytes]u8 = undefined;
+        const update_feed_url = expandedUpdateFeedUrl(&update_feed_url_buffer, app_info.update_feed_url, update_target, app_info.version);
+        native_sdk_appkit_configure_updates(host, update_feed_url.ptr, update_feed_url.len, app_info.update_public_key.ptr, app_info.update_public_key.len, if (app_info.update_check_on_start) 1 else 0, update_target.ptr, update_target.len);
         switch (dock_icon) {
             .host_file => {},
             .masked_render => spawnDevDockIconRender(host, app_info.icon_path),
@@ -805,6 +824,9 @@ pub const MacPlatform = struct {
                 .show_open_dialog_fn = showOpenDialog,
                 .show_save_dialog_fn = showSaveDialog,
                 .show_message_dialog_fn = showMessageDialog,
+                .request_dialog_fn = if (self.web_engine == .system) requestDialog else null,
+                .cancel_dialog_fn = if (self.web_engine == .system) cancelDialog else null,
+                .poll_dialog_result_fn = if (self.web_engine == .system) pollDialogResult else null,
                 .show_notification_fn = showNotification,
                 .set_credential_fn = setCredential,
                 .get_credential_fn = getCredential,
@@ -2390,6 +2412,18 @@ fn checkForUpdates(context: ?*anyopaque, user_initiated: bool) anyerror!void {
     if (native_sdk_appkit_check_for_updates(self.host, if (user_initiated) 1 else 0) == 0) return error.UnsupportedService;
 }
 
+/// The feed URL the host fetches: the manifest's, with `{target}` and
+/// `{current_version}` expanded for this install. A URL this build cannot
+/// expand leaves updates unconfigured rather than fetching some other
+/// target's feed.
+fn expandedUpdateFeedUrl(buffer: []u8, template: []const u8, target: []const u8, version: []const u8) []const u8 {
+    if (template.len == 0) return "";
+    return update_feed.expandFeedUrl(buffer, template, target, version) catch |err| {
+        std.log.warn("updates disabled: feed_url cannot be expanded for {s} {s} ({s})", .{ target, version, @errorName(err) });
+        return "";
+    };
+}
+
 fn configureSecurityPolicy(context: ?*anyopaque, policy: security.Policy) anyerror!void {
     const self: *MacPlatform = @ptrCast(@alignCast(context.?));
     var origins_buffer: [4096]u8 = undefined;
@@ -2683,11 +2717,9 @@ fn viewKindInt(kind: platform_mod.ViewKind) c_int {
     };
 }
 
-fn showOpenDialog(context: ?*anyopaque, options: platform_mod.OpenDialogOptions, buffer: []u8) anyerror!platform_mod.OpenDialogResult {
-    const self: *MacPlatform = @ptrCast(@alignCast(context.?));
-    var ext_buf: [1024]u8 = undefined;
-    const ext_str = flattenFilters(options.filters, &ext_buf);
-    const opts = AppKitOpenDialogOpts{
+fn appKitOpenDialogOpts(options: platform_mod.OpenDialogOptions, ext_buf: []u8) AppKitOpenDialogOpts {
+    const ext_str = flattenFilters(options.filters, ext_buf);
+    return .{
         .title = options.title.ptr,
         .title_len = options.title.len,
         .default_path = options.default_path.ptr,
@@ -2697,19 +2729,11 @@ fn showOpenDialog(context: ?*anyopaque, options: platform_mod.OpenDialogOptions,
         .allow_directories = if (options.allow_directories) 1 else 0,
         .allow_multiple = if (options.allow_multiple) 1 else 0,
     };
-    const result = native_sdk_appkit_show_open_dialog(self.host, &opts, buffer.ptr, buffer.len);
-    if (result.bytes_written > buffer.len) return error.NoSpaceLeft;
-    return .{
-        .count = result.count,
-        .paths = buffer[0..result.bytes_written],
-    };
 }
 
-fn showSaveDialog(context: ?*anyopaque, options: platform_mod.SaveDialogOptions, buffer: []u8) anyerror!?[]const u8 {
-    const self: *MacPlatform = @ptrCast(@alignCast(context.?));
-    var ext_buf: [1024]u8 = undefined;
-    const ext_str = flattenFilters(options.filters, &ext_buf);
-    const opts = AppKitSaveDialogOpts{
+fn appKitSaveDialogOpts(options: platform_mod.SaveDialogOptions, ext_buf: []u8) AppKitSaveDialogOpts {
+    const ext_str = flattenFilters(options.filters, ext_buf);
+    return .{
         .title = options.title.ptr,
         .title_len = options.title.len,
         .default_path = options.default_path.ptr,
@@ -2719,15 +2743,10 @@ fn showSaveDialog(context: ?*anyopaque, options: platform_mod.SaveDialogOptions,
         .extensions = ext_str.ptr,
         .extensions_len = ext_str.len,
     };
-    const written = native_sdk_appkit_show_save_dialog(self.host, &opts, buffer.ptr, buffer.len);
-    if (written > buffer.len) return error.NoSpaceLeft;
-    if (written == 0) return null;
-    return buffer[0..written];
 }
 
-fn showMessageDialog(context: ?*anyopaque, options: platform_mod.MessageDialogOptions) anyerror!platform_mod.MessageDialogResult {
-    const self: *MacPlatform = @ptrCast(@alignCast(context.?));
-    const opts = AppKitMessageDialogOpts{
+fn appKitMessageDialogOpts(options: platform_mod.MessageDialogOptions) AppKitMessageDialogOpts {
+    return .{
         .style = @intFromEnum(options.style),
         .title = options.title.ptr,
         .title_len = options.title.len,
@@ -2742,10 +2761,96 @@ fn showMessageDialog(context: ?*anyopaque, options: platform_mod.MessageDialogOp
         .tertiary_button = options.tertiary_button.ptr,
         .tertiary_button_len = options.tertiary_button.len,
     };
+}
+
+fn showOpenDialog(context: ?*anyopaque, options: platform_mod.OpenDialogOptions, buffer: []u8) anyerror!platform_mod.OpenDialogResult {
+    const self: *MacPlatform = @ptrCast(@alignCast(context.?));
+    var ext_buf: [1024]u8 = undefined;
+    const opts = appKitOpenDialogOpts(options, &ext_buf);
+    const result = native_sdk_appkit_show_open_dialog(self.host, &opts, buffer.ptr, buffer.len);
+    if (result.bytes_written > buffer.len) return error.NoSpaceLeft;
+    return .{
+        .count = result.count,
+        .paths = buffer[0..result.bytes_written],
+    };
+}
+
+fn showSaveDialog(context: ?*anyopaque, options: platform_mod.SaveDialogOptions, buffer: []u8) anyerror!?[]const u8 {
+    const self: *MacPlatform = @ptrCast(@alignCast(context.?));
+    var ext_buf: [1024]u8 = undefined;
+    const opts = appKitSaveDialogOpts(options, &ext_buf);
+    const written = native_sdk_appkit_show_save_dialog(self.host, &opts, buffer.ptr, buffer.len);
+    if (written > buffer.len) return error.NoSpaceLeft;
+    if (written == 0) return null;
+    return buffer[0..written];
+}
+
+fn showMessageDialog(context: ?*anyopaque, options: platform_mod.MessageDialogOptions) anyerror!platform_mod.MessageDialogResult {
+    const self: *MacPlatform = @ptrCast(@alignCast(context.?));
+    const opts = appKitMessageDialogOpts(options);
     const result = native_sdk_appkit_show_message_dialog(self.host, &opts);
     return @enumFromInt(result);
 }
 
+// The host copies every option before returning, so they may live on this
+// stack; the result comes back through pollDialogResult on a later wake.
+fn requestDialog(context: ?*anyopaque, request: platform_mod.DialogRequest) anyerror!void {
+    const self: *MacPlatform = @ptrCast(@alignCast(context.?));
+    var ext_buf: [1024]u8 = undefined;
+    var open_opts: AppKitOpenDialogOpts = undefined;
+    var save_opts: AppKitSaveDialogOpts = undefined;
+    var message_opts: AppKitMessageDialogOpts = undefined;
+    var native_request = AppKitDialogRequest{
+        .id = request.id,
+        .parent_window_id = request.parent_window_id orelse 0,
+        .kind = @intFromEnum(std.meta.activeTag(request.options)),
+        .open_opts = null,
+        .save_opts = null,
+        .message_opts = null,
+    };
+    switch (request.options) {
+        .open => |options| {
+            open_opts = appKitOpenDialogOpts(options, &ext_buf);
+            native_request.open_opts = &open_opts;
+        },
+        .save => |options| {
+            save_opts = appKitSaveDialogOpts(options, &ext_buf);
+            native_request.save_opts = &save_opts;
+        },
+        .message => |options| {
+            message_opts = appKitMessageDialogOpts(options);
+            native_request.message_opts = &message_opts;
+        },
+    }
+    if (native_sdk_appkit_request_dialog(self.host, &native_request) == 0) return error.DialogUnavailable;
+}
+
+fn cancelDialog(context: ?*anyopaque, id: platform_mod.DialogRequestId) void {
+    const self: *MacPlatform = @ptrCast(@alignCast(context.?));
+    native_sdk_appkit_cancel_dialog(self.host, id);
+}
+
+fn pollDialogResult(context: ?*anyopaque, buffer: []u8) ?platform_mod.DialogResult {
+    const self: *MacPlatform = @ptrCast(@alignCast(context.?));
+    var result: AppKitDialogResult = undefined;
+    if (native_sdk_appkit_poll_dialog_result(self.host, buffer.ptr, buffer.len, &result) == 0) return null;
+    return .{
+        .id = result.id,
+        .outcome = switch (result.outcome) {
+            0 => .selected,
+            1 => .cancelled,
+            else => .failed,
+        },
+        .paths = buffer[0..@min(result.bytes_written, buffer.len)],
+        .count = result.count,
+        .button = switch (result.button) {
+            1 => .secondary,
+            2 => .tertiary,
+            else => .primary,
+        },
+    };
+}
+
 const max_tray_items: usize = 32;
 
 fn createTray(context: ?*anyopaque, status_item_id: platform_mod.StatusItemId, options: platform_mod.TrayOptions) anyerror!void {
@@ -3103,6 +3208,18 @@ test "mac updater hashes archives off the main thread and treats user cancellati
     try std.testing.expect(std.mem.indexOf(u8, download_body, "strongSelf.updateCheckRunning = NO;") != null);
 }
 
+test "mac updater fetches the feed URL expanded for this install" {
+    var buffer: [update_feed.max_feed_url_bytes]u8 = undefined;
+    try std.testing.expectEqualStrings(
+        "https://example.com/releases/macos-aarch64/native-update.json?from=1.2.3",
+        expandedUpdateFeedUrl(&buffer, "https://example.com/releases/{target}/native-update.json?from={current_version}", "macos-aarch64", "1.2.3"),
+    );
+    try std.testing.expectEqualStrings("", expandedUpdateFeedUrl(&buffer, "", "macos-aarch64", "1.2.3"));
+    // A build with no release format fetches nothing rather than another
+    // target's feed.
+    try std.testing.expectEqualStrings("", expandedUpdateFeedUrl(&buffer, "https://example.com/{target}.json", "macos-unsupported", "1.2.3"));
+}
+
 test "mac updater binds packaged releases to the installed bundle identity" {
     const host_source = @embedFile("appkit_host.m");
     try std.testing.expect(std.mem.indexOf(u8, host_source, "static NSString *NativeSdkPackagedBundleIdentifier(void)") != null);

package/src/platform/null_platform.zig

@@ -117,8 +117,36 @@ const SaveDialogOptions = types.SaveDialogOptions;
 const MessageDialogStyle = types.MessageDialogStyle;
 const MessageDialogResult = types.MessageDialogResult;
 const MessageDialogOptions = types.MessageDialogOptions;
+const DialogRequestId = types.DialogRequestId;
+const DialogKind = types.DialogKind;
+const DialogRequest = types.DialogRequest;
+const DialogOutcome = types.DialogOutcome;
+const DialogResult = types.DialogResult;
 const NotificationOptions = types.NotificationOptions;
 const CredentialKey = types.CredentialKey;
+
+const max_null_dialogs = 16;
+
+/// One asynchronous dialog the null platform was asked to present.
+pub const NullDialog = struct {
+    state: enum { free, presented, finished } = .free,
+    id: DialogRequestId = 0,
+    kind: DialogKind = .open,
+    parent_window_id: ?WindowId = null,
+    /// Request order, so `pollDialogResult` reports finishes in order.
+    finished_order: u64 = 0,
+    outcome: DialogOutcome = .cancelled,
+    button: MessageDialogResult = .primary,
+    count: usize = 0,
+    paths: [512]u8 = undefined,
+    paths_len: usize = 0,
+    title: [128]u8 = undefined,
+    title_len: usize = 0,
+
+    pub fn titleText(self: *const NullDialog) []const u8 {
+        return self.title[0..self.title_len];
+    }
+};
 const Credential = types.Credential;
 const LocalTimeStyle = types.LocalTimeStyle;
 const StatusItemId = types.StatusItemId;
@@ -527,6 +555,17 @@ pub const NullPlatform = struct {
     save_dialog_count: usize = 0,
     message_dialog_count: usize = 0,
     message_dialog_result: MessageDialogResult = .primary,
+    /// Asynchronous dialogs, once a test opts in (`useAsyncDialogs`):
+    /// requests the runtime made, in order, and the results tests finished
+    /// them with. Nothing finishes on its own; a test calls `finishDialog`
+    /// (or the runtime cancels), which posts a wake like a real host.
+    dialogs: [max_null_dialogs]NullDialog = [_]NullDialog{.{}} ** max_null_dialogs,
+    dialog_request_count: usize = 0,
+    dialog_cancel_count: usize = 0,
+    dialog_finish_sequence: u64 = 0,
+    /// The next `requestDialog` fails, modelling a host that cannot
+    /// present.
+    fail_next_dialog_request: bool = false,
     notification_title: [max_notification_title_bytes]u8 = undefined,
     notification_title_len: usize = 0,
     notification_subtitle: [max_notification_subtitle_bytes]u8 = undefined,
@@ -1650,6 +1689,103 @@ pub const NullPlatform = struct {
         return self.message_dialog_result;
     }
 
+    /// Route `services` (this platform's, as the runtime holds them) through
+    /// the asynchronous dialog services. Opt-in: by default the null
+    /// platform answers the blocking dialog calls at once, which app tests
+    /// rely on, and its asynchronous dialogs never finish on their own.
+    pub fn useAsyncDialogs(self: *NullPlatform, services: *PlatformServices) void {
+        std.debug.assert(services.context == @as(?*anyopaque, @ptrCast(self)));
+        services.request_dialog_fn = requestDialog;
+        services.cancel_dialog_fn = cancelDialog;
+        services.poll_dialog_result_fn = pollDialogResult;
+    }
+
+    fn requestDialog(context: ?*anyopaque, request: DialogRequest) anyerror!void {
+        const self: *NullPlatform = @ptrCast(@alignCast(context.?));
+        if (self.fail_next_dialog_request) {
+            self.fail_next_dialog_request = false;
+            return error.DialogUnavailable;
+        }
+        const slot = for (&self.dialogs) |*dialog| {
+            if (dialog.state == .free) break dialog;
+        } else return error.DialogUnavailable;
+        const title = switch (request.options) {
+            .open => |open| open.title,
+            .save => |save| save.title,
+            .message => |message| if (message.title.len > 0) message.title else message.message,
+        };
+        slot.* = .{ .state = .presented, .id = request.id, .kind = request.options, .parent_window_id = request.parent_window_id };
+        slot.title_len = @min(title.len, slot.title.len);
+        @memcpy(slot.title[0..slot.title_len], title[0..slot.title_len]);
+        self.dialog_request_count += 1;
+    }
+
+    fn cancelDialog(context: ?*anyopaque, id: DialogRequestId) void {
+        const self: *NullPlatform = @ptrCast(@alignCast(context.?));
+        const dialog = self.presentedDialog(id) orelse return;
+        self.dialog_cancel_count += 1;
+        self.markDialogFinished(dialog, .cancelled);
+    }
+
+    fn pollDialogResult(context: ?*anyopaque, buffer: []u8) ?DialogResult {
+        const self: *NullPlatform = @ptrCast(@alignCast(context.?));
+        var next: ?*NullDialog = null;
+        for (&self.dialogs) |*dialog| {
+            if (dialog.state != .finished) continue;
+            if (next == null or dialog.finished_order < next.?.finished_order) next = dialog;
+        }
+        const dialog = next orelse return null;
+        const len = @min(dialog.paths_len, buffer.len);
+        @memcpy(buffer[0..len], dialog.paths[0..len]);
+        const result: DialogResult = .{ .id = dialog.id, .outcome = dialog.outcome, .paths = buffer[0..len], .count = dialog.count, .button = dialog.button };
+        dialog.* = .{};
+        return result;
+    }
+
+    fn presentedDialog(self: *NullPlatform, id: DialogRequestId) ?*NullDialog {
+        for (&self.dialogs) |*dialog| {
+            if (dialog.state == .presented and dialog.id == id) return dialog;
+        }
+        return null;
+    }
+
+    fn markDialogFinished(self: *NullPlatform, dialog: *NullDialog, outcome: DialogOutcome) void {
+        dialog.state = .finished;
+        dialog.outcome = outcome;
+        dialog.finished_order = self.dialog_finish_sequence;
+        self.dialog_finish_sequence += 1;
+        _ = self.wake_count.fetchAdd(1, .release);
+    }
+
+    /// Test helper: how many dialogs are showing right now.
+    pub fn presentedDialogCount(self: *const NullPlatform) usize {
+        var count: usize = 0;
+        for (self.dialogs) |dialog| {
+            if (dialog.state == .presented) count += 1;
+        }
+        return count;
+    }
+
+    /// Test helper: the presented dialog with `id`, for inspecting its
+    /// kind, parent and title.
+    pub fn findPresentedDialog(self: *NullPlatform, id: DialogRequestId) ?*const NullDialog {
+        return self.presentedDialog(id);
+    }
+
+    /// Test helper: the user picked `paths` (newline-separated) in an
+    /// open or save dialog, or pressed `button` in a message dialog. Posts
+    /// the wake a real host would; `error.DialogNotPresented` names a
+    /// dialog that is not showing.
+    pub fn finishDialog(self: *NullPlatform, id: DialogRequestId, outcome: DialogOutcome, paths: []const u8, button: MessageDialogResult) error{ DialogNotPresented, NoSpaceLeft }!void {
+        const dialog = self.presentedDialog(id) orelse return error.DialogNotPresented;
+        if (paths.len > dialog.paths.len) return error.NoSpaceLeft;
+        @memcpy(dialog.paths[0..paths.len], paths);
+        dialog.paths_len = paths.len;
+        dialog.count = if (paths.len == 0) 0 else std.mem.count(u8, paths, "\n") + 1;
+        dialog.button = button;
+        self.markDialogFinished(dialog, outcome);
+    }
+
     fn showNotification(context: ?*anyopaque, options: NotificationOptions) anyerror!void {
         const self: *NullPlatform = @ptrCast(@alignCast(context.?));
         self.notification_title = undefined;

package/src/platform/root.zig

@@ -119,6 +119,7 @@ pub const ViewPatch = types.ViewPatch;
 pub const Cursor = types.Cursor;
 pub const ViewInfo = types.ViewInfo;
 pub const AppInfo = types.AppInfo;
+pub const UpdateMode = types.UpdateMode;
 pub const Surface = types.Surface;
 pub const BridgeMessage = types.BridgeMessage;
 pub const ViewFocusEvent = types.ViewFocusEvent;
@@ -136,6 +137,12 @@ pub const SaveDialogOptions = types.SaveDialogOptions;
 pub const MessageDialogStyle = types.MessageDialogStyle;
 pub const MessageDialogResult = types.MessageDialogResult;
 pub const MessageDialogOptions = types.MessageDialogOptions;
+pub const DialogRequestId = types.DialogRequestId;
+pub const DialogKind = types.DialogKind;
+pub const DialogOptions = types.DialogOptions;
+pub const DialogRequest = types.DialogRequest;
+pub const DialogOutcome = types.DialogOutcome;
+pub const DialogResult = types.DialogResult;
 pub const NotificationOptions = types.NotificationOptions;
 pub const NotificationCommandEvent = types.NotificationCommandEvent;
 pub const CredentialKey = types.CredentialKey;

package/src/platform/types.zig

@@ -1289,6 +1289,9 @@ pub const ViewInfo = struct {
     }
 };
 
+/// Who drives updates on macOS (the manifest's `updates.mode`).
+pub const UpdateMode = enum { host, app };
+
 pub const AppInfo = struct {
     app_name: []const u8 = "native-sdk",
     /// The human-facing application name (app.zon `display_name`) the
@@ -1323,9 +1326,15 @@ pub const AppInfo = struct {
     window_title: []const u8 = "",
     bundle_id: []const u8 = "dev.native_sdk.app",
     icon_path: []const u8 = "",
+    /// The manifest's feed URL, before the host expands `{target}` and
+    /// `{current_version}` for this install.
     update_feed_url: []const u8 = "",
+    /// The trusted update keys: base64 Ed25519 public keys, comma-joined.
     update_public_key: []const u8 = "",
     update_check_on_start: bool = false,
+    /// `.app`: the app drives updates through `native-sdk.updates` and the
+    /// macOS host shows no update UI of its own.
+    update_mode: UpdateMode = .host,
     main_window: WindowOptions = .{},
     windows: []const WindowOptions = &.{},
 
@@ -1445,6 +1454,56 @@ pub const MessageDialogOptions = struct {
     tertiary_button: []const u8 = "",
 };
 
+/// Identifies one asynchronous dialog (`PlatformServices.requestDialog`).
+/// The runtime allocates ids; zero is never used.
+pub const DialogRequestId = u64;
+
+pub const DialogKind = enum(u8) {
+    open,
+    save,
+    message,
+};
+
+pub const DialogOptions = union(DialogKind) {
+    open: OpenDialogOptions,
+    save: SaveDialogOptions,
+    message: MessageDialogOptions,
+};
+
+/// One dialog the runtime asks the platform to present without blocking.
+/// Strings borrow runtime storage only for the duration of the call; a
+/// platform that presents later copies what it keeps.
+pub const DialogRequest = struct {
+    id: DialogRequestId,
+    /// The window the dialog belongs to (a macOS sheet, a Windows owner, a
+    /// GTK transient parent). Null presents it without a parent.
+    parent_window_id: ?WindowId = null,
+    options: DialogOptions,
+};
+
+pub const DialogOutcome = enum(u8) {
+    /// Open and save: the user chose `paths`. Message: the user pressed
+    /// `button`.
+    selected,
+    /// Closed without a choice: the user cancelled or dismissed it, or it
+    /// was closed for them (its window closed, the request was cancelled,
+    /// the session is ending).
+    cancelled,
+    /// The platform could not present the dialog.
+    failed,
+};
+
+pub const DialogResult = struct {
+    id: DialogRequestId,
+    outcome: DialogOutcome,
+    /// Open: `count` newline-separated paths. Save: one path. Empty
+    /// otherwise.
+    paths: []const u8 = "",
+    count: usize = 0,
+    /// Message dialogs reporting `.selected`.
+    button: MessageDialogResult = .primary,
+};
+
 pub const NotificationOptions = struct {
     /// Stable host identity. Reissuing a non-empty id replaces the
     /// notification with that id and its action binding.
@@ -2811,6 +2870,18 @@ pub const PlatformServices = struct {
     show_open_dialog_fn: ?*const fn (context: ?*anyopaque, options: OpenDialogOptions, buffer: []u8) anyerror!OpenDialogResult = null,
     show_save_dialog_fn: ?*const fn (context: ?*anyopaque, options: SaveDialogOptions, buffer: []u8) anyerror!?[]const u8 = null,
     show_message_dialog_fn: ?*const fn (context: ?*anyopaque, options: MessageDialogOptions) anyerror!MessageDialogResult = null,
+    /// Asynchronous dialogs. `request_dialog_fn` returns promptly and
+    /// never runs a nested event loop on the caller's stack: the platform
+    /// presents the dialog on its own schedule, and when it finishes it
+    /// keeps the result and posts a wake (`wake_fn`). The runtime drains
+    /// finished dialogs with `poll_dialog_result_fn`, whose result paths
+    /// borrow `buffer`. `cancel_dialog_fn` closes a presented dialog,
+    /// which then finishes as `.cancelled`; unknown ids are a no-op.
+    /// Platforms without these keep the synchronous `show_*_dialog_fn`
+    /// family, which the runtime falls back to.
+    request_dialog_fn: ?*const fn (context: ?*anyopaque, request: DialogRequest) anyerror!void = null,
+    cancel_dialog_fn: ?*const fn (context: ?*anyopaque, id: DialogRequestId) void = null,
+    poll_dialog_result_fn: ?*const fn (context: ?*anyopaque, buffer: []u8) ?DialogResult = null,
     show_notification_fn: ?*const fn (context: ?*anyopaque, options: NotificationOptions) anyerror!void = null,
     set_credential_fn: ?*const fn (context: ?*anyopaque, credential: Credential) anyerror!void = null,
     get_credential_fn: ?*const fn (context: ?*anyopaque, key: CredentialKey, buffer: []u8) anyerror![]const u8 = null,
@@ -3368,6 +3439,25 @@ pub const PlatformServices = struct {
         return msg_fn(self.context, options);
     }
 
+    pub fn supportsAsyncDialogs(self: PlatformServices) bool {
+        return self.request_dialog_fn != null and self.poll_dialog_result_fn != null;
+    }
+
+    pub fn requestDialog(self: PlatformServices, request: DialogRequest) anyerror!void {
+        const request_fn = self.request_dialog_fn orelse return error.UnsupportedService;
+        return request_fn(self.context, request);
+    }
+
+    pub fn cancelDialog(self: PlatformServices, id: DialogRequestId) void {
+        const cancel_fn = self.cancel_dialog_fn orelse return;
+        cancel_fn(self.context, id);
+    }
+
+    pub fn pollDialogResult(self: PlatformServices, buffer: []u8) ?DialogResult {
+        const poll_fn = self.poll_dialog_result_fn orelse return null;
+        return poll_fn(self.context, buffer);
+    }
+
     pub fn showNotification(self: PlatformServices, options: NotificationOptions) anyerror!void {
         const notify_fn = self.show_notification_fn orelse return error.UnsupportedService;
         return notify_fn(self.context, options);