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

package/src/runtime/tests.zig

@@ -45,4 +45,5 @@ test {
     _ = @import("persist_store.zig");
     _ = @import("session_record.zig");
     _ = @import("session_tests.zig");
+    _ = @import("window_controls_tests.zig");
 }

package/src/runtime/window_controls.zig

@@ -0,0 +1,73 @@
+//! Window controls for app-drawn title bars, beyond minimize: maximize,
+//! restore from maximized, and the user-close request. Each is the real
+//! OS verb for a tracked, open window. Like `minimizeWindow`, no runtime
+//! bookkeeping moves here: the host's own frame events report what the
+//! OS did, the same way they report the caption buttons, the system menu,
+//! and keyboard shortcuts.
+const lifecycle = @import("window_lifecycle_policy.zig");
+const std = @import("std");
+const runtime_window_views = @import("window_views.zig");
+const platform = @import("../platform/root.zig");
+
+/// The page event a window's WebViews receive when its maximized state
+/// changes, whoever changed it, so a page-drawn maximize/restore button
+/// can follow the caption double-click, the system menu, and keyboard
+/// shortcuts: `window.zero.on("window:state", ({ maximized }) => ...)`.
+pub const window_state_event = "window:state";
+
+/// Called by the runtime's window-state update when `maximized` flips.
+/// Best effort, like the other page notifications: the detail is always
+/// valid JSON, so the only failure is a host without page events
+/// (`error.UnsupportedService`), where no page exists to tell.
+pub fn announceMaximized(runtime: anytype, window_id: platform.WindowId, maximized: bool) void {
+    var detail_buffer: [64]u8 = undefined;
+    const detail = std.fmt.bufPrint(&detail_buffer, "{{\"windowId\":{d},\"maximized\":{s}}}", .{ window_id, if (maximized) "true" else "false" }) catch return;
+    runtime.options.platform.services.emitWindowEvent(window_id, window_state_event, detail) catch {};
+}
+
+pub fn RuntimeWindowControls(comptime Runtime: type) type {
+    const WindowViewMethods = runtime_window_views.RuntimeWindowViews(Runtime);
+
+    return struct {
+        /// Maximize a window. Refused for a non-resizable window
+        /// (`error.WindowNotResizable`) and for one that is not on the
+        /// glass (`error.WindowHidden`). `WindowInfo.maximized` follows
+        /// the host's frame event.
+        pub fn maximizeWindow(self: *Runtime, window_id: platform.WindowId) anyerror!void {
+            try requireOpenWindow(self, window_id);
+            try self.options.platform.services.maximizeWindow(window_id);
+        }
+
+        /// Restore a maximized window to its normal frame. A window that
+        /// is not maximized is left as it is.
+        pub fn unmaximizeWindow(self: *Runtime, window_id: platform.WindowId) anyerror!void {
+            try requireOpenWindow(self, window_id);
+            try self.options.platform.services.unmaximizeWindow(window_id);
+        }
+
+        /// Ask a window to close as if the user pressed its close button,
+        /// so its `close_policy` applies: `.hide` hides it and keeps its
+        /// views, `.quit` closes it and dispatches `window_closed`.
+        /// `closeWindow` remains the app's own unconditional close. The
+        /// request is queued; its outcome arrives as the host's frame
+        /// events, so success here means the request was delivered.
+        pub fn requestCloseWindow(self: *Runtime, window_id: platform.WindowId) anyerror!void {
+            try requireOpenWindow(self, window_id);
+            try self.options.platform.services.requestCloseWindow(window_id);
+        }
+
+        /// The liveness gate every window verb shares: a closed window
+        /// keeps its table slot, so a resolvable id is not enough.
+        fn requireOpenWindow(self: *Runtime, window_id: platform.WindowId) !void {
+            if (self.window_lifecycle_policy) |policy| {
+                // The compiled policy knows close, hide, show, and focus,
+                // which move runtime flags, and minimize, which moves
+                // none. These controls move none either, so they take
+                // minimize's admission: the window exists and is open.
+                return lifecycle.plan(policy, self, .begin, .{ .id = window_id, .variant = @intFromEnum(lifecycle.Verb.minimize) }).admitted();
+            }
+            const index = WindowViewMethods.findWindowIndexById(self, window_id) orelse return error.WindowNotFound;
+            if (!self.windows[index].info.open) return error.WindowNotFound;
+        }
+    };
+}

package/src/runtime/window_controls_tests.zig

@@ -0,0 +1,192 @@
+const support = @import("test_support.zig");
+const std = support.std;
+const platform = support.platform;
+const App = support.App;
+const Runtime = support.Runtime;
+const Event = support.Event;
+const TestHarness = support.TestHarness;
+const window_controls = @import("window_controls.zig");
+const bridge_responses = @import("bridge_responses.zig");
+
+const ControlsApp = struct {
+    window_closed_count: u32 = 0,
+
+    fn app(self: *@This()) App {
+        return .{ .context = self, .name = "window-controls", .source = platform.WebViewSource.html("<p>Controls</p>"), .event_fn = event };
+    }
+
+    fn event(context: *anyopaque, runtime: *Runtime, incoming: Event) !void {
+        _ = runtime;
+        const self: *@This() = @ptrCast(@alignCast(context));
+        if (incoming == .window_closed) self.window_closed_count += 1;
+    }
+};
+
+fn windowInfo(runtime: *const Runtime, window_id: platform.WindowId) ?platform.WindowInfo {
+    for (runtime.windows[0..runtime.window_count]) |window| {
+        if (window.info.id == window_id) return window.info;
+    }
+    return null;
+}
+
+fn expectEveryControlRefused(runtime: *Runtime, window_id: platform.WindowId, expected: anyerror) !void {
+    try std.testing.expectError(expected, runtime.maximizeWindow(window_id));
+    try std.testing.expectError(expected, runtime.unmaximizeWindow(window_id));
+    try std.testing.expectError(expected, runtime.requestCloseWindow(window_id));
+}
+
+test "maximize and unmaximize reach the host and maximized follows its frame events" {
+    const harness = try TestHarness().create(std.testing.allocator, .{});
+    defer harness.destroy(std.testing.allocator);
+    var app_state: ControlsApp = .{};
+    try harness.start(app_state.app());
+
+    const tools = try harness.runtime.createWindow(.{ .label = "tools", .title = "Tools" });
+    try harness.runtime.maximizeWindow(tools.id);
+    // The verb moves no runtime state; the host's frame event reports it.
+    try std.testing.expect(!windowInfo(&harness.runtime, tools.id).?.maximized);
+    try harness.runtime.dispatchPlatformEvent(app_state.app(), harness.null_platform.windowFrameEvent(tools.id).?);
+    try std.testing.expect(windowInfo(&harness.runtime, tools.id).?.maximized);
+    try std.testing.expect(windowInfo(&harness.runtime, tools.id).?.state().maximized);
+    var output: [platform.max_windows]platform.WindowInfo = undefined;
+    for (harness.runtime.listWindows(&output)) |listed| {
+        if (listed.id == tools.id) try std.testing.expect(listed.maximized);
+    }
+
+    try harness.runtime.unmaximizeWindow(tools.id);
+    try harness.runtime.dispatchPlatformEvent(app_state.app(), harness.null_platform.windowFrameEvent(tools.id).?);
+    try std.testing.expect(!windowInfo(&harness.runtime, tools.id).?.maximized);
+    // Restoring a window that is not maximized leaves it as it is.
+    try harness.runtime.unmaximizeWindow(tools.id);
+    try std.testing.expect(!harness.null_platform.windows[1].maximized);
+}
+
+test "a maximized change reaches the window's pages and its window JSON" {
+    const harness = try TestHarness().create(std.testing.allocator, .{});
+    defer harness.destroy(std.testing.allocator);
+    var app_state: ControlsApp = .{};
+    try harness.start(app_state.app());
+
+    const tools = try harness.runtime.createWindow(.{ .label = "tools" });
+    try harness.runtime.maximizeWindow(tools.id);
+    const before = harness.null_platform.windowEventCount();
+    try harness.runtime.dispatchPlatformEvent(app_state.app(), harness.null_platform.windowFrameEvent(tools.id).?);
+    try std.testing.expectEqual(before + 1, harness.null_platform.windowEventCount());
+    try std.testing.expectEqual(tools.id, harness.null_platform.lastWindowEventWindowId());
+    try std.testing.expectEqualStrings(window_controls.window_state_event, harness.null_platform.lastWindowEventName());
+    try std.testing.expectEqualStrings("{\"windowId\":2,\"maximized\":true}", harness.null_platform.lastWindowEventDetail());
+
+    // A page loading now reads the same state from the window list.
+    var json_buffer: [512]u8 = undefined;
+    var writer = std.Io.Writer.fixed(&json_buffer);
+    try bridge_responses.writeWindowJsonToWriter(windowInfo(&harness.runtime, tools.id).?, &writer);
+    try std.testing.expect(std.mem.endsWith(u8, writer.buffered(), ",\"maximized\":true}"));
+
+    // A frame event that leaves the state alone (a move) tells nobody.
+    try harness.runtime.dispatchPlatformEvent(app_state.app(), harness.null_platform.windowFrameEvent(tools.id).?);
+    try std.testing.expectEqual(before + 1, harness.null_platform.windowEventCount());
+
+    try harness.runtime.unmaximizeWindow(tools.id);
+    try harness.runtime.dispatchPlatformEvent(app_state.app(), harness.null_platform.windowFrameEvent(tools.id).?);
+    try std.testing.expectEqual(before + 2, harness.null_platform.windowEventCount());
+    try std.testing.expectEqualStrings("{\"windowId\":2,\"maximized\":false}", harness.null_platform.lastWindowEventDetail());
+}
+
+test "a maximize the app did not request still updates maximized" {
+    const harness = try TestHarness().create(std.testing.allocator, .{});
+    defer harness.destroy(std.testing.allocator);
+    var app_state: ControlsApp = .{};
+    try harness.start(app_state.app());
+
+    // A caption double-click, the system menu, or Win+Up: the host's
+    // frame event is the only signal, and it is enough.
+    var state = windowInfo(&harness.runtime, 1).?.state();
+    state.maximized = true;
+    try harness.runtime.dispatchPlatformEvent(app_state.app(), .{ .window_frame_changed = state });
+    try std.testing.expect(windowInfo(&harness.runtime, 1).?.maximized);
+    state.maximized = false;
+    try harness.runtime.dispatchPlatformEvent(app_state.app(), .{ .window_frame_changed = state });
+    try std.testing.expect(!windowInfo(&harness.runtime, 1).?.maximized);
+}
+
+test "window controls refuse unknown, closed, hidden, and non-resizable windows" {
+    const harness = try TestHarness().create(std.testing.allocator, .{});
+    defer harness.destroy(std.testing.allocator);
+    var app_state: ControlsApp = .{};
+    try harness.start(app_state.app());
+
+    try expectEveryControlRefused(&harness.runtime, 99, error.WindowNotFound);
+
+    const fixed = try harness.runtime.createWindow(.{ .label = "fixed", .resizable = false });
+    try std.testing.expectError(error.WindowNotResizable, harness.runtime.maximizeWindow(fixed.id));
+
+    const tools = try harness.runtime.createWindow(.{ .label = "tools" });
+    try harness.runtime.hideWindow(tools.id);
+    try std.testing.expectError(error.WindowHidden, harness.runtime.maximizeWindow(tools.id));
+
+    // A closed window keeps its runtime slot; resolving its id is not
+    // liveness, and no verb reaches the host for it.
+    try harness.runtime.closeWindow(tools.id);
+    try expectEveryControlRefused(&harness.runtime, tools.id, error.WindowNotFound);
+    try std.testing.expect(harness.null_platform.takeQueuedCloseRequest() == null);
+}
+
+test "requestCloseWindow closes a quit-policy window the way the user's close button does" {
+    const harness = try TestHarness().create(std.testing.allocator, .{});
+    defer harness.destroy(std.testing.allocator);
+    var app_state: ControlsApp = .{};
+    try harness.start(app_state.app());
+
+    const tools = try harness.runtime.createWindow(.{ .label = "tools" });
+    try harness.runtime.requestCloseWindow(tools.id);
+    // Only a request: the window is untouched until the host handles it.
+    try std.testing.expect(windowInfo(&harness.runtime, tools.id).?.open);
+    try std.testing.expectEqual(@as(u32, 0), app_state.window_closed_count);
+
+    try harness.runtime.dispatchPlatformEvent(app_state.app(), harness.null_platform.takeQueuedCloseRequest().?);
+    try std.testing.expect(!windowInfo(&harness.runtime, tools.id).?.open);
+    try std.testing.expectEqual(@as(u32, 1), app_state.window_closed_count);
+    try std.testing.expect(harness.null_platform.takeQueuedCloseRequest() == null);
+
+    // closeWindow keeps its meaning: the app's own close, which never
+    // reports back as a user close.
+    const other = try harness.runtime.createWindow(.{ .label = "other" });
+    try harness.runtime.closeWindow(other.id);
+    try std.testing.expectEqual(@as(u32, 1), app_state.window_closed_count);
+}
+
+test "requestCloseWindow hides a hide-policy window and keeps it alive" {
+    const harness = try TestHarness().create(std.testing.allocator, .{});
+    defer harness.destroy(std.testing.allocator);
+    var app_state: ControlsApp = .{};
+    try harness.start(app_state.app());
+
+    const palette = try harness.runtime.createWindow(.{ .label = "palette", .close_policy = .hide });
+    _ = try harness.runtime.createView(.{ .window_id = palette.id, .label = "action", .kind = .button, .frame = .init(10, 10, 80, 30) });
+    const view_count = harness.runtime.view_count;
+
+    try harness.runtime.requestCloseWindow(palette.id);
+    try harness.runtime.dispatchPlatformEvent(app_state.app(), harness.null_platform.takeQueuedCloseRequest().?);
+    const info = windowInfo(&harness.runtime, palette.id).?;
+    try std.testing.expect(info.open);
+    try std.testing.expect(info.hidden);
+    try std.testing.expectEqual(view_count, harness.runtime.view_count);
+    try std.testing.expectEqual(@as(u32, 0), app_state.window_closed_count);
+
+    // The hidden window comes back with its views, as after a user close.
+    try harness.runtime.showWindow(palette.id);
+    try std.testing.expect(!windowInfo(&harness.runtime, palette.id).?.hidden);
+}
+
+test "a close request for a window the app closed first is dropped" {
+    const harness = try TestHarness().create(std.testing.allocator, .{});
+    defer harness.destroy(std.testing.allocator);
+    var app_state: ControlsApp = .{};
+    try harness.start(app_state.app());
+
+    const tools = try harness.runtime.createWindow(.{ .label = "tools" });
+    try harness.runtime.requestCloseWindow(tools.id);
+    try harness.runtime.closeWindow(tools.id);
+    try std.testing.expect(harness.null_platform.takeQueuedCloseRequest() == null);
+    try std.testing.expectEqual(@as(u32, 0), app_state.window_closed_count);
+}

package/src/runtime/window_storage.zig

@@ -220,6 +220,9 @@ pub fn RuntimeWindowStorage(comptime Runtime: type) type {
             const index = existing_index orelse try Self.reserveWindow(self, state.id, state.label, state.title, null, true, .allow_source_less);
             self.windows[index].info.frame = state.frame;
             self.windows[index].info.scale_factor = state.scale_factor;
+            const was_maximized = self.windows[index].info.maximized;
+            self.windows[index].info.maximized = state.maximized;
+            if (was_maximized != state.maximized) @import("window_controls.zig").announceMaximized(self, state.id, state.maximized);
             if (self.window_lifecycle_policy == null) {
                 self.windows[index].info.open = state.open;
                 self.windows[index].info.hidden = state.hidden;

package/src/tooling/manifest.zig

@@ -212,6 +212,9 @@ pub const Metadata = struct {
         if (self.url_schemes.len > 0) allocator.free(self.url_schemes);
         if (self.updates.feed_url) |value| allocator.free(value);
         if (self.updates.public_key) |value| allocator.free(value);
+        for (self.updates.public_keys) |value| allocator.free(value);
+        if (self.updates.public_keys.len > 0) allocator.free(self.updates.public_keys);
+        if (self.updates.mode) |value| allocator.free(value);
         if (self.dmg.volume_name) |value| allocator.free(value);
         if (self.dmg.background) |value| allocator.free(value);
         for (self.dmg.items) |item| {
@@ -425,11 +428,50 @@ pub const DmgMetadata = struct {
 pub const UpdateMetadata = struct {
     feed_url: ?[]const u8 = null,
     public_key: ?[]const u8 = null,
+    public_keys: []const []const u8 = &.{},
     check_on_start: bool = false,
+    /// `host` or `app`; null leaves the host default.
+    mode: ?[]const u8 = null,
 
     pub fn enabled(self: UpdateMetadata) bool {
         return self.feed_url != null;
     }
+
+    /// Whether `public_key` is set and it and every `public_keys` entry
+    /// decode as base64 Ed25519 public keys.
+    pub fn publicKeysAreValid(self: UpdateMetadata) bool {
+        const primary = self.public_key orelse return false;
+        if (decodeUpdatePublicKey(primary) == null) return false;
+        for (self.public_keys) |key| {
+            if (decodeUpdatePublicKey(key) == null) return false;
+        }
+        return true;
+    }
+
+    /// Whether `public_key` or one of `public_keys` decodes to the same key
+    /// as this base64 public key.
+    pub fn trustsPublicKey(self: UpdateMetadata, public_key: []const u8) bool {
+        const wanted = decodeUpdatePublicKey(public_key) orelse return false;
+        if (self.public_key) |primary| {
+            if (decodeUpdatePublicKey(primary)) |bytes| {
+                if (std.mem.eql(u8, &bytes, &wanted)) return true;
+            }
+        }
+        for (self.public_keys) |key| {
+            if (decodeUpdatePublicKey(key)) |bytes| {
+                if (std.mem.eql(u8, &bytes, &wanted)) return true;
+            }
+        }
+        return false;
+    }
+
+    fn decodeUpdatePublicKey(value: []const u8) ?[32]u8 {
+        var bytes: [32]u8 = undefined;
+        const size = std.base64.standard.Decoder.calcSizeForSlice(value) catch return null;
+        if (size != bytes.len) return null;
+        std.base64.standard.Decoder.decode(&bytes, value) catch return null;
+        return bytes;
+    }
 };
 
 pub const FrontendDevMetadata = struct {
@@ -580,7 +622,9 @@ pub fn validateFile(allocator: std.mem.Allocator, io: std.Io, path: []const u8)
     defer allocator.free(file_associations);
     const url_schemes = parseUrlSchemes(allocator, metadata.url_schemes) catch return .{ .ok = false, .message = "app manifest URL schemes are invalid" };
     defer allocator.free(url_schemes);
-    const updates = convertUpdates(metadata.updates) catch return .{ .ok = false, .message = "app manifest updates are invalid - updates require an HTTPS feed_url and a base64 Ed25519 public_key; check_on_start requires both" };
+    const updates_message = "app manifest updates are invalid - updates require an HTTPS feed_url and a base64 Ed25519 public_key; public_keys adds at most 3 further distinct keys; feed_url may name {target} and {current_version} in its path or query; check_on_start requires both; mode is \"host\" or \"app\"";
+    const updates = convertUpdates(metadata.updates) catch return .{ .ok = false, .message = updates_message };
+    app_manifest.validateUpdates(updates) catch return .{ .ok = false, .message = updates_message };
     // General manifest validation owns only values the app explicitly
     // declared. Archive-time fallbacks (notably display_name as the volume
     // name) are validated when a macOS archive is actually requested, so an
@@ -751,17 +795,20 @@ fn duplicateRawUpdates(allocator: std.mem.Allocator, raw: RawUpdates) !UpdateMet
     return .{
         .feed_url = try duplicateOptionalString(allocator, raw.feed_url),
         .public_key = try duplicateOptionalString(allocator, raw.public_key),
+        .public_keys = try duplicateStringList(allocator, raw.public_keys),
         .check_on_start = raw.check_on_start,
+        .mode = try duplicateOptionalString(allocator, raw.mode),
     };
 }
 
 fn convertUpdates(updates: UpdateMetadata) !app_manifest.UpdateConfig {
-    if (updates.feed_url == null and updates.public_key == null and !updates.check_on_start) return .{};
+    if (updates.feed_url == null and updates.public_key == null and updates.public_keys.len == 0 and !updates.check_on_start and updates.mode == null) return .{};
     const feed_url = updates.feed_url orelse return error.InvalidUpdates;
     const public_key = updates.public_key orelse return error.InvalidUpdates;
     if (!std.mem.startsWith(u8, feed_url, "https://")) return error.InvalidUpdates;
     if (public_key.len == 0) return error.InvalidUpdates;
-    return .{ .feed_url = feed_url, .public_key = public_key, .check_on_start = updates.check_on_start };
+    const mode: app_manifest.UpdateMode = if (updates.mode) |value| std.meta.stringToEnum(app_manifest.UpdateMode, value) orelse return error.InvalidUpdates else .host;
+    return .{ .feed_url = feed_url, .public_key = public_key, .public_keys = updates.public_keys, .check_on_start = updates.check_on_start, .mode = mode };
 }
 
 fn duplicateRawServicePackages(allocator: std.mem.Allocator, packages: []const raw_manifest.RawServicePackage) ![]const ServicePackageMetadata {
@@ -2555,6 +2602,67 @@ test "JSON manifest parser carries native update configuration" {
     try std.testing.expectEqualStrings("https://example.com/native-update.json", metadata.updates.feed_url.?);
 }
 
+test "JSON manifest parser carries per-target feeds and rotated update keys" {
+    const metadata = try parseJsonText(std.testing.allocator,
+        \\{
+        \\  "id": "com.example.updates",
+        \\  "name": "updates",
+        \\  "version": "1.2.3",
+        \\  "updates": {
+        \\    "feed_url": "https://example.com/releases/{target}/native-update.json",
+        \\    "public_key": "wFDFY3pE+oYp//PMzOIwDLNipj2Z2V/FQUUmb0MyRFo=",
+        \\    "public_keys": ["11qYAYKxCrfVS/7TyWQHOg7hcvPapiMlrwIaaPcHURo="],
+        \\    "mode": "app"
+        \\  }
+        \\}
+    );
+    defer metadata.deinit(std.testing.allocator);
+    try std.testing.expectEqualStrings("https://example.com/releases/{target}/native-update.json", metadata.updates.feed_url.?);
+    try std.testing.expectEqualStrings("app", metadata.updates.mode.?);
+    try std.testing.expectEqual(app_manifest.UpdateMode.app, (try convertUpdates(metadata.updates)).mode);
+    try std.testing.expect(metadata.updates.trustsPublicKey("wFDFY3pE+oYp//PMzOIwDLNipj2Z2V/FQUUmb0MyRFo="));
+    try std.testing.expect(metadata.updates.trustsPublicKey("11qYAYKxCrfVS/7TyWQHOg7hcvPapiMlrwIaaPcHURo="));
+    try std.testing.expect(!metadata.updates.trustsPublicKey("IBLLkMpg6OXY2vZuInLSIz4EhtVX6MZhQe2JIBd9frc="));
+}
+
+test "manifest validation names the update rules" {
+    var cwd = std.Io.Dir.cwd();
+    const root = ".zig-cache/test-validate-updates";
+    try cwd.deleteTree(std.testing.io, root);
+    defer cwd.deleteTree(std.testing.io, root) catch {};
+    try cwd.createDirPath(std.testing.io, root);
+    try cwd.writeFile(std.testing.io, .{ .sub_path = root ++ "/app.json", .data =
+        \\{
+        \\  "id": "com.example.updates",
+        \\  "name": "updates",
+        \\  "version": "1.2.3",
+        \\  "updates": {
+        \\    "feed_url": "https://example.com/{arch}/native-update.json",
+        \\    "public_key": "wFDFY3pE+oYp//PMzOIwDLNipj2Z2V/FQUUmb0MyRFo="
+        \\  }
+        \\}
+    });
+    const result = try validateFile(std.testing.allocator, std.testing.io, root ++ "/app.json");
+    try std.testing.expect(!result.ok);
+    try std.testing.expect(std.mem.indexOf(u8, result.message, "{target} and {current_version}") != null);
+
+    try cwd.writeFile(std.testing.io, .{ .sub_path = root ++ "/app.json", .data =
+        \\{
+        \\  "id": "com.example.updates",
+        \\  "name": "updates",
+        \\  "version": "1.2.3",
+        \\  "updates": {
+        \\    "feed_url": "https://example.com/{target}/native-update.json",
+        \\    "public_key": "wFDFY3pE+oYp//PMzOIwDLNipj2Z2V/FQUUmb0MyRFo=",
+        \\    "mode": "automatic"
+        \\  }
+        \\}
+    });
+    const mode_result = try validateFile(std.testing.allocator, std.testing.io, root ++ "/app.json");
+    try std.testing.expect(!mode_result.ok);
+    try std.testing.expect(std.mem.indexOf(u8, mode_result.message, "mode is \"host\" or \"app\"") != null);
+}
+
 test "JSON file validation rejects null with a teaching diagnostic regardless of extension case" {
     var cwd = std.Io.Dir.cwd();
     const root = ".zig-cache/test-validate-json-null";

package/src/tooling/package.zig

@@ -9,6 +9,7 @@ const diagnostics = @import("diagnostics");
 const ios_tool = @import("ios.zig");
 const manifest_tool = @import("manifest.zig");
 const web_engine_tool = @import("web_engine.zig");
+const windows_installer = @import("windows_installer.zig");
 const xcodeproj_tool = @import("xcodeproj.zig");
 
 /// The SDK's default app icon (kept in sync by `zig build generate-icon`):
@@ -86,9 +87,14 @@ pub const PackageOptions = struct {
     /// then staple and validate its ticket. Requires identity signing and a
     /// notarytool Keychain profile in `signing.profile`.
     notarize: bool = false,
-    /// Emit the ZIP consumed by the native updater. macOS only; unlike the
-    /// user-facing DMG, this archive contains exactly the packaged .app.
+    /// Emit the ZIP consumed by the native updater. On macOS it contains
+    /// exactly the packaged .app (unlike the user-facing DMG); on Windows
+    /// it is the install image a setup program carries
+    /// (windows_installer.zig).
     update_archive: bool = false,
+    /// Emit a per-user setup program beside a Windows artifact
+    /// (windows_installer.zig). Windows only.
+    installer: bool = false,
     /// The process environment, when the caller has one (the CLI). The
     /// Android artifact probes it for the SDK/NDK toolchain to assemble
     /// the debug APK; without it the generated project is still complete
@@ -161,6 +167,7 @@ pub const PackageStats = struct {
     web_layer: ?manifest_tool.WebLayer = null,
     archive_path: ?[]const u8 = null,
     update_archive_path: ?[]const u8 = null,
+    installer_path: ?[]const u8 = null,
     /// The Windows subsystem verdict: `console` when the package
     /// wrapped a CONSOLE-subsystem exe (the app will flash a terminal
     /// window behind itself on every launch), `gui` for a GUI-subsystem
@@ -278,13 +285,51 @@ pub fn createPackage(allocator: std.mem.Allocator, io: std.Io, options: PackageO
         stats.notarized = true;
     }
     if (options.update_archive) {
-        if (options.target != .macos) return error.UnsupportedUpdateTarget;
         if (!options.metadata.updates.enabled()) return error.UpdatesNotConfigured;
-        stats.update_archive_path = try createUpdateArchive(allocator, io, options);
+        stats.update_archive_path = switch (options.target) {
+            .macos => try createUpdateArchive(allocator, io, options),
+            .windows => try createWindowsImageFile(allocator, io, options, .update_archive),
+            else => return error.UnsupportedUpdateTarget,
+        };
+    }
+    if (options.installer) {
+        if (options.target != .windows) return error.UnsupportedInstallerTarget;
+        stats.installer_path = try createWindowsImageFile(allocator, io, options, .setup);
     }
     return stats;
 }
 
+/// The per-user setup program or the update archive, beside the artifact
+/// directory, for the architecture of the packaged executable.
+fn createWindowsImageFile(allocator: std.mem.Allocator, io: std.Io, options: PackageOptions, kind: enum { setup, update_archive }) ![]const u8 {
+    const binary_path = options.binary_path orelse {
+        std.debug.print("error: --installer and --update-archive need the app executable; pass --binary\n", .{});
+        return error.MissingBinary;
+    };
+    const arch: windows_installer.Arch = if (try peExecutableIsArm64(io, binary_path)) .aarch64 else .x86_64;
+    const executable = try std.fmt.allocPrint(allocator, "{s}.exe", .{options.metadata.name});
+    defer allocator.free(executable);
+    const file_name = switch (kind) {
+        .setup => try windows_installer.setupFileName(allocator, options.metadata, arch),
+        .update_archive => try windows_installer.updateArchiveFileName(allocator, options.metadata, arch),
+    };
+    defer allocator.free(file_name);
+    const path = try std.fs.path.join(allocator, &.{ std.fs.path.dirname(options.output_path) orelse ".", file_name });
+    errdefer allocator.free(path);
+    const image_options: windows_installer.Options = .{
+        .artifact_dir = options.output_path,
+        .metadata = options.metadata,
+        .executable = executable,
+        .arch = arch,
+        .output_path = path,
+    };
+    switch (kind) {
+        .setup => try windows_installer.createSetup(allocator, io, image_options),
+        .update_archive => try windows_installer.createUpdateArchive(allocator, io, image_options),
+    }
+    return path;
+}
+
 fn metadataHasCapability(metadata: manifest_tool.Metadata, name: []const u8) bool {
     for (metadata.capabilities) |capability| {
         if (std.mem.eql(u8, capability, name)) return true;
@@ -332,6 +377,9 @@ pub fn printDiagnostic(stats: PackageStats) void {
     if (stats.update_archive_path) |archive| {
         std.debug.print("  update archive: {s}\n", .{archive});
     }
+    if (stats.installer_path) |installer| {
+        std.debug.print("  installer: {s}\n", .{installer});
+    }
 }
 
 fn createUpdateArchive(allocator: std.mem.Allocator, io: std.Io, options: PackageOptions) ![]const u8 {
@@ -500,7 +548,7 @@ fn createDesktopArtifact(allocator: std.mem.Allocator, io: std.Io, options: Pack
         try makeExecutable(dir, io, service_subpath);
     }
 
-    const assets_output = try assetOutputPath(allocator, options.output_path, "resources", options);
+    const assets_output = try desktopAssetOutputPath(allocator, options);
     defer allocator.free(assets_output);
     const bundle_stats = try assets_tool.bundle(allocator, io, options.assets_dir, assets_output);
     try writeFile(dir, io, "README.txt", artifactReadme(options.target));
@@ -787,6 +835,20 @@ fn macosAssetOutputPath(allocator: std.mem.Allocator, options: PackageOptions) !
     return std.fs.path.join(allocator, &.{ options.output_path, "Contents/Resources" });
 }
 
+/// Where a Windows or Linux artifact carries the app's assets: the macOS
+/// bundle's layout (macosAssetOutputPath) under resources/. The packaged
+/// runner and Windows host resolve relative asset paths against the
+/// resources/ directory beside the executable's bin/, so a relative path
+/// the app reads ("assets/fonts/mono.ttf") names the same file it names
+/// in a dev run.
+fn desktopAssetOutputPath(allocator: std.mem.Allocator, options: PackageOptions) ![]const u8 {
+    if (options.frontend != null) return assetOutputPath(allocator, options.output_path, "resources", options);
+    if (appRelativeAssetSubpath(options.assets_dir)) |subpath| {
+        return std.fs.path.join(allocator, &.{ options.output_path, "resources", subpath });
+    }
+    return std.fs.path.join(allocator, &.{ options.output_path, "resources" });
+}
+
 /// The asset directory as an app-relative bundle subpath, or null when
 /// it cannot honestly be one (empty, ".", absolute, or escaping the app
 /// root through a ".." segment).
@@ -1465,7 +1527,7 @@ fn elfStringAt(strtab: []const u8, offset: u64) ?[]const u8 {
 /// Whether a PE executable targets arm64, read from the COFF machine
 /// field. Anything unrecognized falls back to x64, the default Windows
 /// build target.
-fn peExecutableIsArm64(io: std.Io, path: []const u8) !bool {
+pub fn peExecutableIsArm64(io: std.Io, path: []const u8) !bool {
     var file = try std.Io.Dir.cwd().openFile(io, path, .{});
     defer file.close(io);
     var read_buffer: [4096]u8 = undefined;
@@ -1798,7 +1860,7 @@ fn appendFmt(allocator: std.mem.Allocator, out: *std.ArrayList(u8), comptime for
     try out.appendSlice(allocator, text);
 }
 
-fn trimExtensionDot(extension: []const u8) []const u8 {
+pub fn trimExtensionDot(extension: []const u8) []const u8 {
     if (extension.len > 0 and extension[0] == '.') return extension[1..];
     return extension;
 }
@@ -2109,7 +2171,7 @@ fn windowsRegistrationScript(allocator: std.mem.Allocator, metadata: manifest_to
     return out.toOwnedSlice(allocator);
 }
 
-fn windowsProgId(allocator: std.mem.Allocator, metadata: manifest_tool.Metadata, association: manifest_tool.FileAssociationMetadata) ![]const u8 {
+pub fn windowsProgId(allocator: std.mem.Allocator, metadata: manifest_tool.Metadata, association: manifest_tool.FileAssociationMetadata) ![]const u8 {
     const app = try windowsIdentifierComponentAlloc(allocator, metadata.id);
     defer allocator.free(app);
     const name = try windowsIdentifierComponentAlloc(allocator, association.name);
@@ -3432,6 +3494,34 @@ test "macOS package mirrors app assets at their app-relative path" {
     try std.testing.expectEqualStrings("mp3-bytes", bundled);
 }
 
+test "windows and linux packages mirror app assets at their app-relative path" {
+    // The packaged runner resolves "assets/music/track.mp3" against the
+    // resources/ directory beside bin/, so the artifact keeps the asset
+    // tree at the relative path a dev run reads.
+    var cwd = std.Io.Dir.cwd();
+    const root = ".zig-cache/test-package-desktop-asset-layout";
+    try cwd.deleteTree(std.testing.io, root);
+    defer cwd.deleteTree(std.testing.io, root) catch {};
+    try cwd.createDirPath(std.testing.io, root ++ "/assets/music");
+    try cwd.writeFile(std.testing.io, .{ .sub_path = root ++ "/assets/music/track.mp3", .data = "mp3-bytes" });
+
+    const metadata: manifest_tool.Metadata = .{ .id = "dev.example.app", .name = "demo", .version = "1.2.3" };
+    inline for (.{ PackageTarget.windows, PackageTarget.linux }) |target| {
+        const output = root ++ "/demo-" ++ @tagName(target);
+        const stats = try createPackage(std.testing.allocator, std.testing.io, .{
+            .metadata = metadata,
+            .target = target,
+            .output_path = output,
+            .assets_dir = root ++ "/assets",
+        });
+        try std.testing.expectEqual(@as(usize, 1), stats.asset_count);
+        const packaged = try readPath(std.testing.allocator, std.testing.io, output ++ "/resources/" ++ root ++ "/assets/music/track.mp3");
+        defer std.testing.allocator.free(packaged);
+        try std.testing.expectEqualStrings("mp3-bytes", packaged);
+        try std.testing.expectError(error.FileNotFound, readPath(std.testing.allocator, std.testing.io, output ++ "/resources/music/track.mp3"));
+    }
+}
+
 test "app-relative asset subpaths accept plain trees and reject escapes" {
     try std.testing.expectEqualStrings("assets", appRelativeAssetSubpath("assets").?);
     try std.testing.expectEqualStrings("data/sounds", appRelativeAssetSubpath("data/sounds").?);

package/src/tooling/raw_manifest.zig

@@ -19,6 +19,11 @@ pub const RawManifest = struct {
     /// startup window is created; the runtime dock-presence command may
     /// still promote or demote the app later.
     dock_visible: bool = true,
+    /// Whether one process per bundle id, user, and login session owns
+    /// the app. A later launch hands its working directory and arguments
+    /// to the owner over the `native-sdk.app.launches` channel source and
+    /// exits before creating windows (Windows today).
+    single_instance: bool = false,
     persist: ?RawPersist = null,
     images: RawImages = .{},
     service_packages: []const RawServicePackage = &.{},
@@ -55,7 +60,9 @@ pub const RawManifest = struct {
 pub const RawUpdates = struct {
     feed_url: ?[]const u8 = null,
     public_key: ?[]const u8 = null,
+    public_keys: []const []const u8 = &.{},
     check_on_start: bool = false,
+    mode: ?[]const u8 = null,
 };
 
 pub const RawImages = struct {