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

package/README.md

@@ -11,7 +11,7 @@ The default app core uses a checked TypeScript subset and compiles to native cod
 Requires Node.js 24 or later. The CLI command remains `native`.
 
 ```bash
-npm install -g @zogien/native-sdk@fork
+npm install -g @zogien/native-sdk
 ```
 
 The `native` binary arrives as a per-platform optional dependency (`@zogien/native-sdk-<platform>`). Installation also downloads the exact scriptc release, verifies its checksum, and installs the matching compiler API and runtime packs into `~/.native/toolchains/scriptc/`. This package carries the SDK source your apps build against, so `native init` and `native dev` work offline after installation. If npm install scripts are disabled, run `node packages/core/scripts/install_scriptc.mjs` from the installed CLI package before building. `NATIVE_SDK_SCRIPTC_CACHE` selects another toolchain cache directory. The pinned Zig toolchain is fetched into `~/.native/toolchains/` on first build unless a compatible `zig` is already on your PATH.

package/build/app.zig

@@ -2017,8 +2017,14 @@ pub fn addAppArtifacts(b: *std.Build, dep: *std.Build.Dependency, app_options: A
     // on GUI exes (handles inherit; only console AUTO-allocation is
     // gated by the subsystem), so automation harnesses that pipe
     // `app.exe > log 2>&1` keep their logs either way.
+    //
+    // MSVC's CRT enters a GUI-subsystem image through WinMainCRTStartup,
+    // which calls WinMain, but Zig apps export only `main`; MinGW's startup
+    // calls `main` under either subsystem. MSVC targets therefore keep the
+    // GUI subsystem and enter through the console CRT entry instead.
     if (target.result.os.tag == .windows and app_optimize != .Debug) {
         exe.subsystem = .windows;
+        if (target.result.abi == .msvc) exe.entry = .{ .symbol_name = "mainCRTStartup" };
     }
     linkPlatform(b, dep, target, app_mod, exe, selected_platform, web_engine, web_layer, cef_dir, cef_auto_install);
     const install = b.addInstallArtifact(exe, .{});
@@ -2096,32 +2102,25 @@ pub fn addAppArtifacts(b: *std.Build, dep: *std.Build.Dependency, app_options: A
     // not just its test failures. Test builds never analyze `main` (the
     // test runner replaces the entry point), so rules that fire inside it
     // — UiApp.create's Model-defaults rule above all — used to ambush at
-    // `native build`, the LAST step in the loop. Compiling this object
-    // forces full semantic analysis of the app module, entry point
-    // included; nothing links or runs.
-    const analysis_root = b.addWriteFiles().add("app_analysis.zig",
-        \\//! Generated by the app build: force semantic analysis of the
-        \\//! app's entry point at test time. Exactly `main`, transitively —
-        \\//! the same surface `native build` analyzes — so test-time can
-        \\//! never be stricter than the build it fronts.
-        \\comptime {
-        \\    const app = @import("app");
-        \\    if (@hasDecl(app, "main")) _ = &app.main;
-        \\}
-        \\
-    );
-    const analysis_mod = b.createModule(.{
-        .root_source_file = analysis_root,
-        .target = target,
-        .optimize = optimize,
-    });
-    analysis_mod.addImport("app", test_app_mod);
-    const analysis_obj = b.addObject(.{
+    // `native build`, the LAST step in the loop. This executable roots at
+    // the test app module itself, so std.start analyzes `main` exactly as
+    // the app's own entry build does: root-level decls, the body, and the
+    // entry signature. Test time is therefore never stricter, nor laxer,
+    // than the build it fronts. Nothing requests its binary, so Zig
+    // compiles it with -fno-emit-bin: nothing links or runs, and nothing
+    // may ever install it or ask for its emitted bin.
+    //
+    // It must stay an executable. Zig refuses any COFF object compile with
+    // more than one object, archive, or C input, -fno-emit-bin included,
+    // and Windows app modules routinely carry several: the compiled core
+    // archive beside the Debug markup data object, the platform hosts'
+    // C++ sources, and MSVC system import libraries.
+    const entry_analysis = b.addExecutable(.{
         .name = b.fmt("{s}-analysis", .{app_options.name}),
-        .root_module = analysis_mod,
+        .root_module = test_app_mod,
         .use_llvm = useLlvmWorkaround(target),
     });
-    test_step.dependOn(&analysis_obj.step);
+    test_step.dependOn(&entry_analysis.step);
 
     // `zig build model-contract`: reflect the app's Model/Msg into
     // zig-out/model-contract.zon so `native check` can verify markup
@@ -2212,6 +2211,9 @@ pub fn addAppArtifacts(b: *std.Build, dep: *std.Build.Dependency, app_options: A
         package_run.addArgs(&.{ "--web-engine", @tagName(web_engine), "--cef-dir", cef_dir });
         if (cef_auto_install) package_run.addArg("--cef-auto-install");
         if (app_config.updates_enabled and host_os == .macos) package_run.addArg("--update-archive");
+        // Windows updates reach only installed apps, so an app with updates
+        // ships the per-user setup program beside the archive its feed names.
+        if (app_config.updates_enabled and host_os == .windows) package_run.addArgs(&.{ "--installer", "--update-archive" });
         package_run.has_side_effects = true;
         const package_step = b.step("package", "Create a distributable package via the native CLI");
         package_step.dependOn(&package_run.step);
@@ -2314,6 +2316,9 @@ fn appModule(b: *std.Build, dep: *std.Build.Dependency, target: std.Build.Resolv
         if (link_ts_archives) {
             if (stage.service_archive) |service_archive| app_mod.addObjectFile(service_archive);
         }
+        if (link_ts_archives and target.result.os.tag == .windows and target.result.abi == .msvc) {
+            linkScriptcMsvcRuntime(dep, app_mod);
+        }
     }
     if (app_config.sqlite_capability) {
         // `store` and the relational `sqlite` tier share this exact object.
@@ -2331,6 +2336,25 @@ fn appModule(b: *std.Build, dep: *std.Build.Dependency, target: std.Build.Resolv
     return app_mod;
 }
 
+/// The Windows libraries scriptc's runtime pack declares (runtime-pack.json
+/// system_libraries; bcrypt and crypt32 back its TLS). An unused import
+/// library adds no DLL dependency, so they are linked unconditionally.
+const scriptc_windows_system_libraries = [_][]const u8{ "advapi32", "iphlpapi", "ws2_32", "bcrypt", "crypt32" };
+
+/// The pinned scriptc builds its Windows runtime against Zig's MinGW sysroot,
+/// and an MSVC image links the static UCRT without MinGW's default libraries.
+/// Restate what MinGW would have supplied on the module that carries the core
+/// and service archives, so the app exe and every test-side artifact that
+/// imports it (unit tests, model contract, test host) link alike: the pack's
+/// system libraries, MSVC's oldnames.lib for the POSIX names (open, read,
+/// close, ...), and scriptc_mingw_compat.c for the rest of MinGW's startup
+/// and CRT layer (running the runtime's .ctors constructors above all).
+fn linkScriptcMsvcRuntime(dep: *std.Build.Dependency, mod: *std.Build.Module) void {
+    for (scriptc_windows_system_libraries) |name| mod.linkSystemLibrary(name, .{});
+    mod.linkSystemLibrary("oldnames", .{});
+    mod.addCSourceFile(.{ .file = dep.path("src/platform/windows/scriptc_mingw_compat.c"), .flags = &.{} });
+}
+
 /// Compile primary markup bytes independently from the Zig app graph. The
 /// final artifact sees this as an object-file input, so a markup edit dirties
 /// only this tiny C compile and the final link.

package/build/cli.zig

@@ -43,6 +43,12 @@ pub fn createModules(b: *std.Build, target: std.Build.ResolvedTarget, optimize:
     tooling.addImport("android_host", module(b, target, optimize, "src/platform/android/files.zig"));
     tooling.addImport("sqlite_engine", module(b, target, optimize, "src/runtime/sqlite_engine.zig"));
     tooling.addImport("update_feed", module(b, target, optimize, "src/updater/feed.zig"));
+    tooling.addImport("windows_install_config", module(b, target, optimize, "src/windows_install/config.zig"));
+    tooling.addImport("windows_install_payload", module(b, target, optimize, "src/windows_install/payload.zig"));
+    // `native package --installer` writes the Windows setup program and
+    // launcher from these prebuilt copies, so packaging needs no compiler.
+    tooling.addAnonymousImport("windows_launcher_x86_64", .{ .root_source_file = windowsLauncher(b, .x86_64).getEmittedBin() });
+    tooling.addAnonymousImport("windows_launcher_aarch64", .{ .root_source_file = windowsLauncher(b, .aarch64).getEmittedBin() });
     tooling.addIncludePath(b.path("third_party/sqlite"));
     tooling.addCSourceFile(.{
         .file = b.path("third_party/sqlite/sqlite3.c"),
@@ -101,6 +107,22 @@ pub fn buildCommit(b: *std.Build) []const u8 {
     return trimmed;
 }
 
+/// The Windows setup program, launcher and uninstaller of installed apps
+/// (src/windows_install), built for one Windows architecture.
+fn windowsLauncher(b: *std.Build, arch: std.Target.Cpu.Arch) *std.Build.Step.Compile {
+    const launcher = b.addExecutable(.{
+        .name = "native-launcher",
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/windows_install/main.zig"),
+            .target = b.resolveTargetQuery(.{ .cpu_arch = arch, .os_tag = .windows }),
+            .optimize = .ReleaseSmall,
+            .strip = true,
+        }),
+    });
+    launcher.subsystem = .windows;
+    return launcher;
+}
+
 fn module(b: *std.Build, target: std.Build.ResolvedTarget, optimize: std.builtin.OptimizeMode, path: []const u8) *std.Build.Module {
     return b.createModule(.{
         .root_source_file = b.path(path),

package/native-sdk.d.ts

@@ -32,6 +32,8 @@ export interface NativeSdkWindowInfo {
   width: number;
   height: number;
   scale: number;
+  /** Maximized, whoever changed it; `window.zero.on("window:state", ...)` reports each change. */
+  maximized: boolean;
 }
 
 export type NativeSdkWindowTitlebarStyle =

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zogien/native-sdk",
-  "version": "0.11.0-fork.2",
+  "version": "0.11.0-fork.4",
   "description": "Community-maintained fork of Native SDK: TypeScript, Native markup, and native desktop tooling",
   "type": "module",
   "engines": {
@@ -41,14 +41,14 @@
     "tar": "7.5.22"
   },
   "optionalDependencies": {
-    "@zogien/native-sdk-darwin-arm64": "0.11.0-fork.2",
-    "@zogien/native-sdk-darwin-x64": "0.11.0-fork.2",
-    "@zogien/native-sdk-linux-arm64-gnu": "0.11.0-fork.2",
-    "@zogien/native-sdk-linux-arm64-musl": "0.11.0-fork.2",
-    "@zogien/native-sdk-linux-x64-gnu": "0.11.0-fork.2",
-    "@zogien/native-sdk-linux-x64-musl": "0.11.0-fork.2",
-    "@zogien/native-sdk-win32-arm64": "0.11.0-fork.2",
-    "@zogien/native-sdk-win32-x64": "0.11.0-fork.2"
+    "@zogien/native-sdk-darwin-arm64": "0.11.0-fork.4",
+    "@zogien/native-sdk-darwin-x64": "0.11.0-fork.4",
+    "@zogien/native-sdk-linux-arm64-gnu": "0.11.0-fork.4",
+    "@zogien/native-sdk-linux-arm64-musl": "0.11.0-fork.4",
+    "@zogien/native-sdk-linux-x64-gnu": "0.11.0-fork.4",
+    "@zogien/native-sdk-linux-x64-musl": "0.11.0-fork.4",
+    "@zogien/native-sdk-win32-arm64": "0.11.0-fork.4",
+    "@zogien/native-sdk-win32-x64": "0.11.0-fork.4"
   },
   "repository": {
     "type": "git",
@@ -72,7 +72,7 @@
   },
   "publishConfig": {
     "access": "public",
-    "tag": "fork",
+    "tag": "latest",
     "registry": "https://registry.npmjs.org/"
   }
 }

package/packages/core/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@native-sdk/core",
-  "version": "0.11.0-fork.2",
+  "version": "0.11.0-fork.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@native-sdk/core",
-      "version": "0.11.0-fork.2",
+      "version": "0.11.0-fork.4",
       "hasInstallScript": true,
       "dependencies": {
         "@scriptc/types": "0.3.0",

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@native-sdk/core",
-  "version": "0.11.0-fork.2",
+  "version": "0.11.0-fork.4",
   "description": "The TypeScript authoring tier: the app-core subset, its checker and contract frontend, the exact-pinned core compiler dependency, and the SDK module cores import",
   "repository": {
     "type": "git",

package/schemas/app.schema.json

@@ -34,6 +34,7 @@
       }
     },
     "dock_visible": { "type": "boolean", "default": true },
+    "single_instance": { "type": "boolean", "default": false },
     "persist": { "$ref": "#/$defs/persist" },
     "images": { "$ref": "#/$defs/images" },
     "service_packages": {
@@ -138,7 +139,14 @@
       "properties": {
         "feed_url": { "type": "string", "pattern": "^https://", "maxLength": 4096 },
         "public_key": { "type": "string", "pattern": "^[A-Za-z0-9+/]{43}=$" },
-        "check_on_start": { "type": "boolean", "default": false }
+        "public_keys": {
+          "type": "array",
+          "maxItems": 3,
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^[A-Za-z0-9+/]{43}=$" }
+        },
+        "check_on_start": { "type": "boolean", "default": false },
+        "mode": { "type": "string", "enum": ["host", "app"], "default": "host" }
       }
     },
     "bridge": {

package/skill-data/ts-core/SKILL.md

@@ -172,6 +172,8 @@ Four effect families deliver MANY results from one command — a keyed stream th
 - `Cmd.channelOpen(key, { event })` — open an EXTERNAL-SOURCE channel under the app's numeric key: the host stages a long-lived, thread-safe posting seam its NATIVE side feeds — embedders and platform-services extensions post bytes from their own threads (sockets, watchers, workers), and each accepted post dispatches the `event` arm as one `"data"` event. Posting is deliberately not a TS verb — compiled cores are single-threaded, so the core opens, closes, and receives while the posting handle lives on the native side (`Effects.channelHandle(key)`). `key` may be any number expression, a positive integer below 2^53 (a certain-to-be-refused literal stops the build, NS1030). The `event` arm is a five-field record matched by NAME: `key` (the channel key echoed verbatim, so concurrent channels sharing one arm stay distinguishable; a key the wire cannot carry exactly echoes 0), `state` (the `ChannelState` union — import it from `@native-sdk/core` or declare an alias with exactly the three members `"data" | "closed" | "rejected"` in any order; checked BOTH directions, since a narrower union would silently drop states the host emits), `bytes` (`Uint8Array` — the post's payload on `"data"` events, empty otherwise), and `droppedPending`/`droppedTotal` (numbers — the honest back-pressure counters: posts the native handle refused since the previous delivered event, and over the channel's whole life; refused posts count, never silence). One channel per key at a time — a duplicate live key dispatches `"rejected"` — and the key shares the engine's effect-key space (a same-key fetch is blocked while the channel lives). No timer polling anywhere: the source wakes the loop itself. Channel events journal at the effect boundary, so recorded sessions replay the whole stream from the journal — the native posting side is never needed at replay (a native producer that consults `ChannelHandle.live()` before launching keeps replay fully offline; one that launches unconditionally is stopped at its first post, which answers `.closed`).
 - `Cmd.channelClose(key)` — close the open channel under the key, if any: staged posts flush, exactly one `"closed"` event (final drop totals aboard) dispatches the event arm, and the key frees. A key with no open channel no-ops.
 - `Cmd.channelOpenSource(key, source, payload, { event, started })` opens a channel and starts an explicit native producer only for that newly accepted occupancy. The `started` arm has exactly `key: number`, `state: "started" | "skipped" | "failed"`, and `bytes: Uint8Array`; it runs in command order before the settled view. A refused open skips startup and still delivers the ordinary channel rejection. Startup failure carries the native error name; close that channel with `Cmd.channelClose`. Source names are 1–255 UTF-8 bytes and arguments at most 4096 bytes. The built-in `"native-sdk.process.samples"` source takes empty arguments and posts process readings every 500 ms. Native embedders can inject `Effects.channel_sources`; starters copy borrowed arguments before returning and must be quick and nonreentrant. Native recording journals startup results and replay never invokes the producer. The fake and virtual hosts report `UnsupportedChannelSource` unless a native test injects a starter; virtual-host recording of external producers requires the native runtime. See `examples/channel-monitor`.
+- The built-in `"native-sdk.app.launches"` source delivers later launches of a `"single_instance": true` app (manifest; Windows today). The owning process's core opens it with empty arguments, usually from `initialModel`; each later launch arrives as one `"data"` event whose `bytes` are the launch's working directory, then each argument (argv[0] excluded), NUL-separated. Split with `.indexOf(0)`/`.slice`, then decide what to do, typically `Cmd.showWindow(label)` (the later process has already granted the owner foreground permission). Launches that arrive before the open are held for up to 5 seconds. A process that does not own the app gets `started` `"failed"` with `SingleInstanceNotOwned` (`UnsupportedChannelSource` on hosts without single-instance support). The later process never runs core code: it exits with code 0 once the owner accepts the launch, or a distinct non-zero code (see the manifest docs' Single instance section).
+- The built-in `"native-sdk.updates"` source follows the app-driven updater (an `updates` manifest block; Windows installs from the SDK setup program, and macOS apps whose manifest sets `"mode": "app"`). Open it with empty arguments from `initialModel`; it posts the current status at open, then at every change and about every percent of a download. A status is `name value` lines — `state` (`unsupported`/`idle`/`checking`/`up_to_date`/`available`/`downloading`/`ready`/`error`), `installed`, then `version`, `size`, `received`, `percent`, `reason`, `error`, `last updated` when they apply; read lines by name with a byte loop (`status[i] === 10` ends a line, `subarray` slices the value). Drive it with `Cmd.request("native-sdk.updates.<verb>", new Uint8Array(0), { ok, err })` — `status`, `check`, `download`, `cancel`, `discard`, `restart` (quits the app; the staged release starts in its place), `notes` (plain-text release notes): each answers at once — `status` with the status, `notes` with the notes, the rest with an empty ok once accepted — or with an err reason (`unsupported`, `busy`, `not_available`, `not_ready`, `not_downloading`, `invalid_request`, `restart_failed`). Keep the model's status from the channel only: it delivers every change in order, while a request's answer may arrive after a newer post. The updater never shows UI or restarts on its own; the core decides. Elsewhere (macOS with the default host-owned flow, Linux) `state` is `unsupported` with `reason platform`. See the Updates docs.
 - `Cmd.audioCaptureStart(key, { source, sampleRate?, channels? }, { event })` — start a native `"microphone"` or `"system"` audio stream. The host converts into interleaved signed-16 little-endian PCM at 16/24/48 kHz and mono/stereo (default 48 kHz mono), in chunks no larger than 20 ms. The ten-field event arm is matched by NAME: `key`, `state` (exactly `"started" | "data" | "failed" | "stopped" | "rejected"`), `source` (exactly `"microphone" | "system"`), `sampleRate`, `channels`, `timestampMs`, `frames`, `pcm`, `droppedPending`, and `droppedTotal`. PCM is dispatch-lifetime bytes; the commit walker copies it when stored in the model. The bounded queue, wake behavior, drop accounting, journaling, and offline replay are the channel transport's. Microphone and system may run concurrently; a second start for one source replaces that source's prior key.
 - `Cmd.audioCaptureStop(key)` — synchronously quiesce native callbacks, flush already accepted chunks, deliver exactly one `"stopped"` terminal, and free the key. The key remains occupied until that terminal is delivered, so wait for `"stopped"` before reusing it; an earlier restart is rejected. A missing key no-ops. Declare `"microphone"` and/or `"system_audio"` in `app.zon` permissions so macOS dev executables and packaged apps carry the required usage descriptions.
 - `Cmd.imageLoad(id, { path?, url?, cachePath?, expectedBytes? }, { event })` — load an image at runtime under the model-owned NUMERIC ImageId your markup binds (`<image image="{cover}"/>`, `<avatar image="{avatar}"/>`); `id` may be any number expression (ids are model data), a positive integer below 2^53 (a certain-to-be-refused literal like 0 stops the build, NS1030). The source cascade is `audioPlay`'s exactly: local `path` first, a missing file falls through to `url` (fetched whole, installed at the cache path and integrity-gated by `expectedBytes`); at least one of `path`/`url` (NS1029), and prefer OMITTING `cachePath` — the wiring's caches directory (`TsUiApp`'s `image_cache_dir`) derives the content-addressed path from the URL. Exactly ONE `event` arm dispatches per load — a five-field record matched by NAME: `id` (the requested ImageId echoed verbatim, so concurrent loads sharing one arm stay distinguishable; an id the wire cannot carry exactly echoes 0), `state` (the `ImageState` union — exactly the fifteen members `"loaded" | "rejected" | "not_found" | "io_failed" | "connect_failed" | "tls_failed" | "protocol_failed" | "timed_out" | "http_status" | "cancelled" | "too_large" | "unsupported" | "decode_failed" | "registry_full" | "alloc_failed"`, any order; `"alloc_failed"` is resource exhaustion at registration — the host refused the memory, the bytes may be fine, retry when memory frees), `width`/`height` (the actual registered dimensions on `"loaded"`, 0 otherwise), and `status` (the HTTP status for url loads that performed an exchange; 0 when none occurred — local paths, cache hits — so a cached `"loaded"` is distinguishable from a network one). On `"loaded"` the pixels are already registered under the id — store the id in the model then (the store-on-success discipline keeps a fallback rendering until the load lands). One load per id at a time: a duplicate live id dispatches `"rejected"` (the spawn discipline — a load in flight is never replaced implicitly), and image loads are not the string-keyed `Cmd.cancel`'s to end — `Cmd.imageCancel(id)` is their cancel, LOUD like spawn's: the one terminal still arrives as the event arm's `"cancelled"`, and the id frees for a fresh load once it lands (an id with no live load no-ops; the same NS1030 literal gate as `imageLoad`). The default registry has 16 slots and a 1 MiB decoded-pixel target per slot: platform codecs downscale photo-size sources at decode time, preserving aspect, instead of rejecting them. Image-centric apps may declare `.images = .{ .max_image_pixel_bytes = 8388608 }` in app.zon (1–8 MiB accepted); allocation stays lazy per used slot, but filling 16 ceiling-sized slots is a declared 128 MiB high-water. Encoded sources have their own flat 8 MiB bound; only over-bound source bytes report `"too_large"` in normal operation, never a cut decode. `Cmd.imageUnregister(id)` releases a loaded image's registry slot — the gallery eviction move when the 17th distinct image would answer `"registry_full"`: views bound to the id fall back, and the slot accepts the next load. Unregister is synchronous registry surgery, NOT an effect — no result Msg, an unregistered id no-ops (the same NS1030 literal gate) — and it frees only the CURRENT registration: a load in flight under the id still registers at its terminal, so cancel the load first (`Cmd.imageCancel`) to keep the slot free.

package/src/app_runner/app_assets.zig

@@ -3,7 +3,10 @@
 //! Relative paths keep their app-directory meaning during development. In a
 //! packaged macOS app, the same tree lives below `Contents/Resources`; Finder
 //! and `open` do not preserve a useful working directory, so resolve that tree
-//! from the executable's bundle layout before reading it.
+//! from the executable's bundle layout before reading it. A packaged Windows
+//! or Linux artifact keeps the tree in `resources/` beside the executable's
+//! `bin/`, and a shortcut or file manager launch starts in some other
+//! directory, so resolve that tree the same way.
 
 const std = @import("std");
 const builtin = @import("builtin");
@@ -26,10 +29,56 @@ pub fn readFileAlloc(
             limit,
         );
     }
+    if (comptime builtin.os.tag == .windows or builtin.os.tag == .linux) {
+        var executable_buffer: [std.Io.Dir.max_path_bytes]u8 = undefined;
+        const executable_len = std.process.executablePath(io, &executable_buffer) catch
+            return std.Io.Dir.cwd().readFileAlloc(io, path, allocator, limit);
+        return readFileAllocFromDesktopExecutable(
+            io,
+            executable_buffer[0..executable_len],
+            path,
+            allocator,
+            limit,
+        );
+    }
 
     return std.Io.Dir.cwd().readFileAlloc(io, path, allocator, limit);
 }
 
+pub fn readFileAllocFromDesktopExecutable(
+    io: std.Io,
+    executable_path: []const u8,
+    path: []const u8,
+    allocator: std.mem.Allocator,
+    limit: std.Io.Limit,
+) std.Io.Dir.ReadFileAllocError![]u8 {
+    var packaged_path_buffer: [std.Io.Dir.max_path_bytes]u8 = undefined;
+    if (desktopPackagedResourcePath(executable_path, path, &packaged_path_buffer) catch null) |packaged_path| {
+        return std.Io.Dir.cwd().readFileAlloc(io, packaged_path, allocator, limit) catch |err| switch (err) {
+            // As on macOS: a package miss keeps the cwd-relative development
+            // behavior, while a real read failure is not hidden.
+            error.FileNotFound => std.Io.Dir.cwd().readFileAlloc(io, path, allocator, limit),
+            else => |read_err| read_err,
+        };
+    }
+    return std.Io.Dir.cwd().readFileAlloc(io, path, allocator, limit);
+}
+
+/// The packaged copy of a relative asset path when the executable runs
+/// from a Windows or Linux artifact's `bin/`: `<artifact>/resources/<path>`.
+pub fn desktopPackagedResourcePath(
+    executable_path: []const u8,
+    asset_path: []const u8,
+    output: []u8,
+) error{NoSpaceLeft}!?[]const u8 {
+    if (asset_path.len == 0 or std.fs.path.isAbsolute(asset_path)) return null;
+    const executable_dir = std.fs.path.dirname(executable_path) orelse return null;
+    if (!std.ascii.eqlIgnoreCase(std.fs.path.basename(executable_dir), "bin")) return null;
+    const artifact_dir = std.fs.path.dirname(executable_dir) orelse return null;
+    return std.fmt.bufPrint(output, "{s}{c}resources{c}{s}", .{ artifact_dir, std.fs.path.sep, std.fs.path.sep, asset_path }) catch
+        error.NoSpaceLeft;
+}
+
 pub fn readFileAllocFromMacosExecutable(
     io: std.Io,
     executable_path: []const u8,
@@ -136,3 +185,38 @@ test "packaged macOS startup assets read from Contents Resources" {
     defer std.testing.allocator.free(bytes);
     try std.testing.expectEqualStrings("packaged-avatar", bytes);
 }
+
+test "desktop packaged resource path mirrors the app-relative asset tree beside bin" {
+    var buffer: [256]u8 = undefined;
+    const sep = std.fs.path.sep_str;
+    const executable = "pkg" ++ sep ++ "demo" ++ sep ++ "bin" ++ sep ++ "demo.exe";
+    try std.testing.expectEqualStrings(
+        "pkg" ++ sep ++ "demo" ++ sep ++ "resources" ++ sep ++ "assets/fonts/mono.ttf",
+        (try desktopPackagedResourcePath(executable, "assets/fonts/mono.ttf", &buffer)).?,
+    );
+    const uppercase = "pkg" ++ sep ++ "demo" ++ sep ++ "BIN" ++ sep ++ "demo.exe";
+    try std.testing.expect((try desktopPackagedResourcePath(uppercase, "assets/logo.png", &buffer)) != null);
+    // A development binary outside bin/ keeps reading relative to the
+    // working directory, and absolute paths are never redirected.
+    try std.testing.expectEqual(null, try desktopPackagedResourcePath("zig-cache" ++ sep ++ "o" ++ sep ++ "demo.exe", "assets/logo.png", &buffer));
+    try std.testing.expectEqual(null, try desktopPackagedResourcePath(executable, "", &buffer));
+    const absolute = if (builtin.os.tag == .windows) "C:\\logo.png" else "/tmp/logo.png";
+    try std.testing.expectEqual(null, try desktopPackagedResourcePath(executable, absolute, &buffer));
+}
+
+test "packaged desktop startup assets read from resources beside bin" {
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    try tmp.dir.createDirPath(std.testing.io, "demo/bin");
+    try tmp.dir.createDirPath(std.testing.io, "demo/resources/assets/fonts");
+    try tmp.dir.writeFile(std.testing.io, .{ .sub_path = "demo/resources/assets/fonts/mono.ttf", .data = "packaged-font" });
+
+    var executable_buffer: [std.Io.Dir.max_path_bytes]u8 = undefined;
+    const executable_path = try std.fmt.bufPrint(&executable_buffer, ".zig-cache/tmp/{s}/demo/bin/demo.exe", .{tmp.sub_path[0..]});
+    const bytes = try readFileAllocFromDesktopExecutable(std.testing.io, executable_path, "assets/fonts/mono.ttf", std.testing.allocator, .limited(1024));
+    defer std.testing.allocator.free(bytes);
+    try std.testing.expectEqualStrings("packaged-font", bytes);
+
+    // A package miss falls back to the working directory.
+    try std.testing.expectError(error.FileNotFound, readFileAllocFromDesktopExecutable(std.testing.io, executable_path, "assets/fonts/missing.ttf", std.testing.allocator, .limited(1024)));
+}

package/src/app_runner/root.zig

@@ -98,8 +98,9 @@ pub const RunOptions = struct {
             .bundle_id = self.bundle_id,
             .icon_path = self.icon_path,
             .update_feed_url = manifestUpdateString("feed_url"),
-            .update_public_key = manifestUpdateString("public_key"),
+            .update_public_key = manifestUpdatePublicKeys(),
             .update_check_on_start = manifestUpdateCheckOnStart(),
+            .update_mode = manifestUpdateMode(),
             .main_window = .{
                 .id = 1,
                 .label = "main",
@@ -172,12 +173,30 @@ fn manifestUpdateString(comptime field: []const u8) []const u8 {
     };
 }
 
+/// The trusted update keys the updater verifies feeds against:
+/// `public_key` followed by any `public_keys`, comma-joined.
+fn manifestUpdatePublicKeys() []const u8 {
+    const primary = comptime manifestUpdateString("public_key");
+    if (comptime primary.len == 0) return "";
+    if (comptime !@hasField(@TypeOf(app_manifest.updates), "public_keys")) return primary;
+    comptime var keys: []const u8 = primary;
+    inline for (app_manifest.updates.public_keys) |key| keys = keys ++ "," ++ key;
+    return keys;
+}
+
 fn manifestUpdateCheckOnStart() bool {
     if (comptime !@hasField(@TypeOf(app_manifest), "updates")) return false;
     if (comptime !@hasField(@TypeOf(app_manifest.updates), "check_on_start")) return false;
     return app_manifest.updates.check_on_start;
 }
 
+fn manifestUpdateMode() native_sdk.platform.UpdateMode {
+    if (comptime !@hasField(@TypeOf(app_manifest), "updates")) return .host;
+    if (comptime !@hasField(@TypeOf(app_manifest.updates), "mode")) return .host;
+    return comptime std.meta.stringToEnum(native_sdk.platform.UpdateMode, app_manifest.updates.mode) orelse
+        @compileError("app manifest updates.mode must be \"host\" or \"app\"");
+}
+
 const CommandStorage = struct {
     commands: [native_sdk.app_manifest.max_commands]native_sdk.Command = undefined,
 
@@ -651,6 +670,30 @@ fn manifestDeclaresCredentials() bool {
     return false;
 }
 
+fn manifestSingleInstance() bool {
+    return if (comptime @hasField(@TypeOf(app_manifest), "single_instance")) app_manifest.single_instance else false;
+}
+
+/// Manifest `single_instance`: claims ownership before anything else
+/// starts. A later launch hands its working directory and arguments to
+/// the owner and exits here, its exit code naming the delivery result.
+/// Replay never claims. Only the first call claims, so an entry point may
+/// call it before its own startup work and the call in `runWithOptions`
+/// is then a no-op.
+pub fn enforceSingleInstance(init: std.process.Init) void {
+    if (comptime !manifestSingleInstance()) return;
+    if (init.environ_map.get("NATIVE_SDK_SESSION_REPLAY") != null) return;
+    const outcome = native_sdk.single_instance.claim(init.io, init.gpa, init.minimal.args, app_manifest.id) orelse return;
+    switch (outcome) {
+        .primary => {},
+        .standalone => |reason| std.log.warn("single_instance: {s}; running without instance ownership", .{reason}),
+        .secondary => |result| {
+            if (result != .delivered) std.debug.print("{s}: {s}\n", .{ app_manifest.name, result.describe() });
+            std.process.exit(result.exitCode());
+        },
+    }
+}
+
 fn menuItem(comptime item: anytype) native_sdk.MenuItem {
     return .{
         .label = if (@hasField(@TypeOf(item), "label")) item.label else "",
@@ -694,6 +737,7 @@ pub fn runWithOptions(app: native_sdk.App, options: RunOptions, init: std.proces
     if (init.environ_map.get("NATIVE_SDK_SESSION_REPLAY")) |journal_path| {
         return runSessionReplay(app, options, init, journal_path);
     }
+    enforceSingleInstance(init);
     const RecordStoreType = if (comptime manifestDeclaresStore()) native_sdk.RecordStore else void;
     var record_store_value: RecordStoreType = undefined;
     var record_store_open = false;
@@ -859,6 +903,7 @@ fn runMacos(app: native_sdk.App, options: RunOptions, init: std.process.Init) !v
     native_sdk.runtime.launch_timing.lap("runner_main");
     var buffers: StateBuffers = undefined;
     var app_info = options.appInfo(&buffers);
+    configureUpdates(&app_info, init.environ_map);
     const store = prepareStateStore(init.io, init.environ_map, &app_info, &buffers);
     const session_recorder = setupSessionRecorder(init, app_info, app.recording_policy, app.blob_policy);
     // Heap wrapper, latch-gated free: worker threads hold this address
@@ -931,6 +976,7 @@ fn runMacos(app: native_sdk.App, options: RunOptions, init: std.process.Init) !v
 fn runLinux(app: native_sdk.App, options: RunOptions, init: std.process.Init) !void {
     var buffers: StateBuffers = undefined;
     var app_info = options.appInfo(&buffers);
+    configureUpdates(&app_info, init.environ_map);
     const store = prepareStateStore(init.io, init.environ_map, &app_info, &buffers);
     const session_recorder = setupSessionRecorder(init, app_info, app.recording_policy, app.blob_policy);
     // Heap wrapper, latch-gated free: worker threads hold this address
@@ -998,9 +1044,22 @@ fn runLinux(app: native_sdk.App, options: RunOptions, init: std.process.Init) !v
     finishSessionRecorder(session_recorder);
 }
 
+/// Points the app-driven updater at this installation (see
+/// `updater.configureApp`).
+fn configureUpdates(app_info: *native_sdk.platform.AppInfo, environ_map: *std.process.Environ.Map) void {
+    const host: native_sdk.updater.Host = comptime if (std.mem.eql(u8, build_options.platform, "windows"))
+        .windows
+    else if (std.mem.eql(u8, build_options.platform, "macos") and std.mem.eql(u8, build_options.web_engine, "system"))
+        .macos_appkit
+    else
+        .other;
+    native_sdk.updater.configureApp(host, app_info, environ_map);
+}
+
 fn runWindows(app: native_sdk.App, options: RunOptions, init: std.process.Init) !void {
     var buffers: StateBuffers = undefined;
     var app_info = options.appInfo(&buffers);
+    configureUpdates(&app_info, init.environ_map);
     const store = prepareStateStore(init.io, init.environ_map, &app_info, &buffers);
     const session_recorder = setupSessionRecorder(init, app_info, app.recording_policy, app.blob_policy);
     // Heap wrapper, latch-gated free: worker threads hold this address
@@ -1293,9 +1352,10 @@ test "RunOptions resolves manifest commands menus and shortcuts" {
     };
     var info_buffers: StateBuffers = .{};
     const app_info = options.appInfo(&info_buffers);
-    try std.testing.expectEqualStrings("https://example.com/native-update.json", app_info.update_feed_url);
-    try std.testing.expectEqualStrings("11qYAYKxCrfVS/7TyWQHOg7hcvPapiMlrwIaaPcHURo=", app_info.update_public_key);
+    try std.testing.expectEqualStrings("https://example.com/releases/{target}/native-update.json", app_info.update_feed_url);
+    try std.testing.expectEqualStrings("11qYAYKxCrfVS/7TyWQHOg7hcvPapiMlrwIaaPcHURo=,wFDFY3pE+oYp//PMzOIwDLNipj2Z2V/FQUUmb0MyRFo=", app_info.update_public_key);
     try std.testing.expect(app_info.update_check_on_start);
+    try std.testing.expectEqual(native_sdk.platform.UpdateMode.app, app_info.update_mode);
 
     var command_storage: CommandStorage = .{};
     const commands = options.resolvedCommands(&command_storage);

package/src/app_runner/ts_core_main.zig

@@ -54,6 +54,11 @@
 //!                    when a core requests it, so packaged apps never
 //!                    depend on their process working directory for
 //!                    durable files.
+//!   single instance  app.zon's `.single_instance` claims ownership first
+//!                    thing in `main`; a later launch exits after handing
+//!                    its cwd and arguments to the owner, whose core
+//!                    receives them on the `native-sdk.app.launches`
+//!                    channel source.
 //!
 //! Editing this file is never core-level work: it carries no app logic and
 //! regenerates from the SDK on every build.
@@ -169,6 +174,9 @@ pub fn testMain(init: std.process.Init) !void {
 }
 
 pub fn main(init: std.process.Init) !void {
+    // Before persistence, services, or any window: a later launch of a
+    // `single_instance` app exits here once the owner has its arguments.
+    runner.enforceSingleInstance(init);
     var options = appOptions(init.io);
     // The platform caches directory for this app: when the core's
     // `Cmd.audioPlay` names a URL with no cachePath, the bridge derives

package/src/platform/macos/appkit_host.h

@@ -419,6 +419,15 @@ void native_sdk_appkit_set_dock_icon_rgba(native_sdk_appkit_host_t *host, const
 void native_sdk_appkit_set_dock_icon_file(native_sdk_appkit_host_t *host, const char *path, size_t path_len);
 void native_sdk_appkit_configure_updates(native_sdk_appkit_host_t *host, const char *feed_url, size_t feed_url_len, const char *public_key, size_t public_key_len, int check_on_start, const char *target, size_t target_len);
 int native_sdk_appkit_check_for_updates(native_sdk_appkit_host_t *host, int user_initiated);
+// App-driven updates (src/updater/macos.zig); none of these shows UI.
+int native_sdk_macos_updates_eligibility(void);
+size_t native_sdk_macos_updates_staged_version(const char *bundle_id, size_t bundle_id_len, char *output, size_t capacity);
+size_t native_sdk_macos_updates_take_last(const char *bundle_id, size_t bundle_id_len, char *output, size_t capacity);
+int native_sdk_macos_updates_fetch(const char *url, size_t url_len, int allow_loopback_http, uint8_t *output, size_t capacity, size_t *output_len);
+int native_sdk_macos_updates_download(const char *url, size_t url_len, int allow_loopback_http, uint64_t limit, char *path_output, size_t path_capacity, size_t *path_len, void *context, void (*progress)(void *context, uint64_t received), int (*cancelled)(void *context));
+int native_sdk_macos_updates_stage(const char *archive_path, size_t archive_path_len, const char *bundle_id, size_t bundle_id_len, const char *version, size_t version_len);
+void native_sdk_macos_updates_discard(void);
+int native_sdk_macos_updates_install(const char *bundle_id, size_t bundle_id_len, const char *from_version, size_t from_version_len, int relaunch);
 void native_sdk_appkit_run(native_sdk_appkit_host_t *host, native_sdk_appkit_event_callback_t callback, void *context);
 // The host-side shutdown request: a failed event emit asks the host to
 // deliver SHUTDOWN and stop. While the run loop is live the delivery is