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

package/src/primitives/app_manifest/root.zig

@@ -83,6 +83,7 @@ pub const FileAssociation = types.FileAssociation;
 pub const UrlScheme = types.UrlScheme;
 pub const PackageMetadata = types.PackageMetadata;
 pub const UpdateConfig = types.UpdateConfig;
+pub const UpdateMode = types.UpdateMode;
 pub const Manifest = types.Manifest;
 pub const ImagesConfig = types.ImagesConfig;
 pub const validateManifest = validation.validateManifest;

package/src/primitives/app_manifest/tests.zig

@@ -125,6 +125,41 @@ test "updates require paired HTTPS feed and Ed25519 public key" {
     }));
 }
 
+test "app-driven updates need a feed to drive" {
+    try validateUpdates(.{
+        .feed_url = "https://example.com/native-update.json",
+        .public_key = "11qYAYKxCrfVS/7TyWQHOg7hcvPapiMlrwIaaPcHURo=",
+        .mode = .app,
+    });
+    try std.testing.expectError(error.MissingRequiredField, validateUpdates(.{ .mode = .app }));
+}
+
+test "update feed URLs may name the target and installed version" {
+    const key = "11qYAYKxCrfVS/7TyWQHOg7hcvPapiMlrwIaaPcHURo=";
+    try validateUpdates(.{ .feed_url = "https://example.com/releases/{target}/native-update.json", .public_key = key });
+    try validateUpdates(.{ .feed_url = "https://example.com/feed?target={target}&from={current_version}", .public_key = key });
+    try std.testing.expectError(error.InvalidUrl, validateUpdates(.{ .feed_url = "https://example.com/{arch}/native-update.json", .public_key = key }));
+    try std.testing.expectError(error.InvalidUrl, validateUpdates(.{ .feed_url = "https://example.com/{target/native-update.json", .public_key = key }));
+    try std.testing.expectError(error.InvalidUrl, validateUpdates(.{ .feed_url = "https://example.com/target}/native-update.json", .public_key = key }));
+    try std.testing.expectError(error.InvalidUrl, validateUpdates(.{ .feed_url = "https://{target}.example.com/native-update.json", .public_key = key }));
+}
+
+test "update public_keys add distinct trusted keys beside public_key" {
+    const key = "11qYAYKxCrfVS/7TyWQHOg7hcvPapiMlrwIaaPcHURo=";
+    const other = "wFDFY3pE+oYp//PMzOIwDLNipj2Z2V/FQUUmb0MyRFo=";
+    const rotated = [_][]const u8{other};
+    try validateUpdates(.{ .feed_url = "https://example.com/native-update.json", .public_key = key, .public_keys = &rotated });
+    try std.testing.expectError(error.MissingRequiredField, validateUpdates(.{ .public_keys = &rotated }));
+    const repeated = [_][]const u8{key};
+    try std.testing.expectError(error.MissingRequiredField, validateUpdates(.{ .feed_url = "https://example.com/native-update.json", .public_key = key, .public_keys = &repeated }));
+    const duplicated = [_][]const u8{ other, other };
+    try std.testing.expectError(error.MissingRequiredField, validateUpdates(.{ .feed_url = "https://example.com/native-update.json", .public_key = key, .public_keys = &duplicated }));
+    const malformed = [_][]const u8{"not-a-public-key"};
+    try std.testing.expectError(error.MissingRequiredField, validateUpdates(.{ .feed_url = "https://example.com/native-update.json", .public_key = key, .public_keys = &malformed }));
+    const too_many = [_][]const u8{ other, "IBLLkMpg6OXY2vZuInLSIz4EhtVX6MZhQe2JIBd9frc=", "+AzM3OSuHAeuIIoq35mjEK5CB+Awb6AjYRCwaCe7uNA=", "n0lDnp2wlbxBEe0l01eV2DG8VaBH9LHX9q7jd3u0EiA=" };
+    try std.testing.expectError(error.MissingRequiredField, validateUpdates(.{ .feed_url = "https://example.com/native-update.json", .public_key = key, .public_keys = &too_many }));
+}
+
 test "accessory startup requires the tray capability" {
     const tray_capabilities = [_]Capability{.tray};
     try validateManifest(.{

package/src/primitives/app_manifest/types.zig

@@ -647,9 +647,21 @@ pub const PackageMetadata = struct {
 pub const UpdateConfig = struct {
     feed_url: ?[]const u8 = null,
     public_key: ?[]const u8 = null,
+    /// Further trusted keys beside `public_key`, so a release signed with
+    /// a key being rotated out still verifies on installs that know it.
+    public_keys: []const []const u8 = &.{},
     check_on_start: bool = false,
+    /// Who drives updates on macOS: the host's own prompts, or the app
+    /// through the `native-sdk.updates` requests and channel. Windows apps
+    /// always drive updates themselves.
+    mode: UpdateMode = .host,
 };
 
+pub const UpdateMode = enum { host, app };
+
+/// `public_key` plus at most this many `public_keys`.
+pub const max_update_public_keys: usize = 3;
+
 pub const PersistRestore = struct {
     ok: []const u8,
     none: []const u8,

package/src/primitives/app_manifest/validation.zig

@@ -657,17 +657,55 @@ pub fn validateSecurity(security: SecurityConfig) ValidationError!void {
 pub fn validateUpdates(updates: UpdateConfig) ValidationError!void {
     if ((updates.feed_url == null) != (updates.public_key == null)) return error.MissingRequiredField;
     if (updates.check_on_start and updates.feed_url == null) return error.MissingRequiredField;
+    if (updates.mode == .app and updates.feed_url == null) return error.MissingRequiredField;
+    if (updates.public_keys.len > 0 and updates.public_key == null) return error.MissingRequiredField;
+    if (updates.public_keys.len > types.max_update_public_keys) return error.MissingRequiredField;
     if (updates.feed_url) |url| {
         if (url.len > 4096) return error.InvalidUrl;
         if (!std.mem.startsWith(u8, url, "https://")) return error.InvalidUrl;
         try validateUrl(url);
+        try validateFeedUrlPlaceholders(url);
+    }
+    if (updates.public_key) |key| try validateUpdatePublicKey(key);
+    for (updates.public_keys, 0..) |key, index| {
+        try validateUpdatePublicKey(key);
+        if (std.mem.eql(u8, key, updates.public_key.?)) return error.MissingRequiredField;
+        for (updates.public_keys[0..index]) |previous| {
+            if (std.mem.eql(u8, key, previous)) return error.MissingRequiredField;
+        }
     }
-    if (updates.public_key) |key| {
-        var decoded: [std.crypto.sign.Ed25519.PublicKey.encoded_length]u8 = undefined;
-        const decoded_len = std.base64.standard.Decoder.calcSizeForSlice(key) catch return error.MissingRequiredField;
-        if (decoded_len != decoded.len) return error.MissingRequiredField;
-        std.base64.standard.Decoder.decode(&decoded, key) catch return error.MissingRequiredField;
-        _ = std.crypto.sign.Ed25519.PublicKey.fromBytes(decoded) catch return error.MissingRequiredField;
+}
+
+fn validateUpdatePublicKey(key: []const u8) ValidationError!void {
+    var decoded: [std.crypto.sign.Ed25519.PublicKey.encoded_length]u8 = undefined;
+    const decoded_len = std.base64.standard.Decoder.calcSizeForSlice(key) catch return error.MissingRequiredField;
+    if (decoded_len != decoded.len) return error.MissingRequiredField;
+    std.base64.standard.Decoder.decode(&decoded, key) catch return error.MissingRequiredField;
+    _ = std.crypto.sign.Ed25519.PublicKey.fromBytes(decoded) catch return error.MissingRequiredField;
+}
+
+/// A feed_url may name `{target}` and `{current_version}`, which each
+/// installed app expands for itself, in its path or query only.
+fn validateFeedUrlPlaceholders(url: []const u8) ValidationError!void {
+    const authority_start = "https://".len;
+    const authority_end = std.mem.findAnyPos(u8, url, authority_start, "/?#") orelse url.len;
+    if (std.mem.findAny(u8, url[0..authority_end], "{}") != null) return error.InvalidUrl;
+    var index = authority_end;
+    while (index < url.len) : (index += 1) {
+        switch (url[index]) {
+            '{' => {
+                const rest = url[index..];
+                const placeholder = if (std.mem.startsWith(u8, rest, "{target}"))
+                    "{target}"
+                else if (std.mem.startsWith(u8, rest, "{current_version}"))
+                    "{current_version}"
+                else
+                    return error.InvalidUrl;
+                index += placeholder.len - 1;
+            },
+            '}' => return error.InvalidUrl,
+            else => {},
+        }
     }
 }
 

package/src/root.zig

@@ -157,6 +157,7 @@ pub const EffectChannelSourceState = runtime.EffectChannelSourceState;
 pub const EffectChannelSourceResult = runtime.EffectChannelSourceResult;
 pub const max_channel_source_payload = runtime.max_channel_source_payload;
 pub const ChannelHandle = runtime.ChannelHandle;
+pub const single_instance = runtime.single_instance;
 pub const max_effect_channels = runtime.max_effect_channels;
 pub const max_effect_channel_bytes = runtime.max_effect_channel_bytes;
 pub const max_effect_channel_pending = runtime.max_effect_channel_pending;
@@ -269,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/channel_sources.zig

@@ -1,19 +1,67 @@
 //! Explicit native external-producer capabilities. Portable app state and
-//! channel lifecycle stay in the app; this source owns a detached OS sampler.
+//! channel lifecycle stay in the app; `native-sdk.process.samples` owns a
+//! detached OS sampler, `native-sdk.app.launches` hands the channel to
+//! the single-instance listener (single_instance.zig), and
+//! `native-sdk.updates` receives the updater's status records
+//! (updater/engine.zig).
 const std = @import("std");
 const builtin = @import("builtin");
 const effects = @import("effects.zig");
 const clock = @import("clock.zig");
+const single_instance = @import("single_instance.zig");
+const update_engine = @import("../updater/engine.zig");
 const sample_interval_ms = 500;
 const max_line_bytes = 96;
 
 pub fn start(name: []const u8, payload: []const u8, handle: effects.ChannelHandle) !void {
+    if (std.mem.eql(u8, name, single_instance.source_name)) return single_instance.attach(payload, handle);
+    if (std.mem.eql(u8, name, update_engine.channel_source)) return attachUpdates(payload, handle);
     if (!std.mem.eql(u8, name, "native-sdk.process.samples")) return error.UnknownChannelSource;
     if (payload.len != 0) return error.InvalidChannelSourceArguments;
     if (comptime builtin.single_threaded) return error.UnsupportedChannelSource;
     try startSamplerThread(handle);
 }
 
+/// The open `native-sdk.updates` channels, each the engine's sink. A slot
+/// frees itself when its channel answers `.closed`.
+const UpdateChannel = struct {
+    handle: effects.ChannelHandle = undefined,
+    used: std.atomic.Value(bool) = .init(false),
+
+    fn post(context: *anyopaque, bytes: []const u8) update_engine.Posted {
+        const self: *UpdateChannel = @ptrCast(@alignCast(context));
+        return switch (self.handle.post(bytes)) {
+            .accepted => .delivered,
+            .dropped_full, .dropped_oversized => .dropped,
+            .closed => {
+                self.used.store(false, .release);
+                return .closed;
+            },
+        };
+    }
+};
+var update_channels: [4]UpdateChannel = .{UpdateChannel{}} ** 4;
+
+comptime {
+    // Every status record fits one post; notes travel by request.
+    std.debug.assert(update_engine.max_status_bytes <= effects.max_effect_channel_bytes);
+}
+
+fn attachUpdates(payload: []const u8, handle: effects.ChannelHandle) !void {
+    if (payload.len != 0) return error.InvalidChannelSourceArguments;
+    for (&update_channels) |*channel| {
+        if (channel.used.cmpxchgStrong(false, true, .acq_rel, .acquire) == null) {
+            channel.handle = handle;
+            update_engine.attach(.{ .context = channel, .post = UpdateChannel.post }) catch {
+                channel.used.store(false, .release);
+                return error.UnsupportedChannelSource;
+            };
+            return;
+        }
+    }
+    return error.UnsupportedChannelSource;
+}
+
 fn startSamplerThread(handle: effects.ChannelHandle) std.Thread.SpawnError!void {
     const thread = try std.Thread.spawn(.{}, samplerMain, .{handle});
     thread.detach();

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