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

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

@@ -2211,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);
@@ -2824,8 +2827,7 @@ fn linkPlatform(b: *std.Build, dep: *std.Build.Dependency, target: std.Build.Res
                 // The vendored WebView2 SDK header (third_party/webview2)
                 // turns on the host's embedded-WebView layer; the host
                 // fails the compile by design if it cannot be found.
-                app_mod.addIncludePath(dep.path("third_party/webview2/include"));
-                if (windowsSdkWinrtIncludeDir(b, target)) |winrt| app_mod.addSystemIncludePath(.{ .cwd_relative = winrt });
+                addWebView2HostIncludes(b, app_mod, dep.path("third_party/webview2/include"), target);
                 app_mod.addCSourceFile(.{ .file = dep.path("src/platform/windows/webview2_host.cpp"), .flags = &.{"-std=c++17"} });
                 app_mod.addCSourceFile(.{ .file = dep.path("src/platform/windows/gpu_surface_renderer.cpp"), .flags = &.{"-std=c++17"} });
                 // WebView2Loader.dll rides next to the installed app
@@ -2868,36 +2870,7 @@ fn linkPlatform(b: *std.Build, dep: *std.Build.Dependency, target: std.Build.Res
                 app_mod.addObjectFile(b.path(b.fmt("{s}/libcef_dll_wrapper/libcef_dll_wrapper.lib", .{cef_dir})));
             },
         }
-        app_mod.linkSystemLibrary("c", .{});
-        // The MSVC target compiles the hosts against the toolchain's own
-        // STL, which pulls in msvcprt/vcruntime through its default-lib
-        // directives; Zig's libc++/libc++abi cannot be built against the
-        // MSVC CRT headers (cxxabi.h collides with vcruntime_typeinfo.h).
-        if (target.result.abi != .msvc) app_mod.linkSystemLibrary("c++", .{});
-        app_mod.linkSystemLibrary("user32", .{});
-        app_mod.linkSystemLibrary("gdi32", .{});
-        // Retained gpu_surface packets are composited into a hardware
-        // Direct2D target; DirectWrite draws the engine-measured text
-        // runs (including registered in-memory fonts) on that target.
-        app_mod.linkSystemLibrary("d2d1", .{});
-        app_mod.linkSystemLibrary("dwrite", .{});
-        app_mod.linkSystemLibrary("imm32", .{});
-        app_mod.linkSystemLibrary("comctl32", .{});
-        app_mod.linkSystemLibrary("ole32", .{});
-        app_mod.linkSystemLibrary("oleacc", .{});
-        app_mod.linkSystemLibrary("shell32", .{});
-        // TypeScript cores link ScriptC's host runtime, whose network-interface
-        // helpers use GetAdaptersAddresses and Winsock address conversion; the
-        // in-process service archive shares the same runtime and additionally
-        // reaches advapi32 (crypto-backed randomness).
-        app_mod.linkSystemLibrary("iphlpapi", .{});
-        app_mod.linkSystemLibrary("ws2_32", .{});
-        app_mod.linkSystemLibrary("advapi32", .{});
-        // The audio backend: Media Foundation (session + source resolver
-        // + streaming audio renderer) and WinHTTP (the cache fill).
-        app_mod.linkSystemLibrary("mf", .{});
-        app_mod.linkSystemLibrary("mfplat", .{});
-        app_mod.linkSystemLibrary("winhttp", .{});
+        linkWindowsHostLibraries(app_mod, target);
         if (web_engine == .chromium) app_mod.linkSystemLibrary("libcef", .{});
     }
 }
@@ -2925,6 +2898,53 @@ fn addPlatformLinkSearchPaths(b: *std.Build, platform: PlatformOption, web_engin
 
 /// The vendored WebView2Loader.dll for the target architecture, relative
 /// to the framework root.
+/// The system libraries the Windows host links, for an app executable
+/// and for the host's own test harness alike.
+pub fn linkWindowsHostLibraries(module: *std.Build.Module, target: std.Build.ResolvedTarget) void {
+    module.linkSystemLibrary("c", .{});
+    // The MSVC target compiles the hosts against the toolchain's own
+    // STL, which pulls in msvcprt/vcruntime through its default-lib
+    // directives; Zig's libc++/libc++abi cannot be built against the
+    // MSVC CRT headers (cxxabi.h collides with vcruntime_typeinfo.h).
+    if (target.result.abi != .msvc) module.linkSystemLibrary("c++", .{});
+    module.linkSystemLibrary("user32", .{});
+    module.linkSystemLibrary("gdi32", .{});
+    // Retained gpu_surface packets are composited into a hardware
+    // Direct2D target; DirectWrite draws the engine-measured text
+    // runs (including registered in-memory fonts) on that target.
+    module.linkSystemLibrary("d2d1", .{});
+    module.linkSystemLibrary("dwrite", .{});
+    module.linkSystemLibrary("imm32", .{});
+    module.linkSystemLibrary("comctl32", .{});
+    module.linkSystemLibrary("ole32", .{});
+    module.linkSystemLibrary("oleacc", .{});
+    module.linkSystemLibrary("shell32", .{});
+    // TypeScript cores link ScriptC's host runtime, whose network-interface
+    // helpers use GetAdaptersAddresses and Winsock address conversion; the
+    // in-process service archive shares the same runtime and additionally
+    // reaches advapi32 (crypto-backed randomness).
+    module.linkSystemLibrary("iphlpapi", .{});
+    module.linkSystemLibrary("ws2_32", .{});
+    module.linkSystemLibrary("advapi32", .{});
+    // The audio backend: Media Foundation (session + source resolver
+    // + streaming audio renderer) and WinHTTP (the cache fill).
+    module.linkSystemLibrary("mf", .{});
+    module.linkSystemLibrary("mfplat", .{});
+    module.linkSystemLibrary("winhttp", .{});
+}
+
+/// The WebView2 host's include paths: the vendored WebView2 SDK header
+/// directory, plus WRL for MSVC targets (`windowsSdkWinrtIncludeDir`).
+pub fn addWebView2HostIncludes(b: *std.Build, module: *std.Build.Module, sdk_include: std.Build.LazyPath, target: std.Build.ResolvedTarget) void {
+    module.addIncludePath(sdk_include);
+    if (windowsSdkWinrtIncludeDir(b, target)) |winrt| module.addSystemIncludePath(.{ .cwd_relative = winrt });
+}
+
+/// The vendored WebView2Loader.dll's directory, relative to the SDK root.
+pub fn webView2LoaderDir(target: std.Build.ResolvedTarget) []const u8 {
+    return std.fs.path.dirname(webView2LoaderSubPath(target)).?;
+}
+
 fn webView2LoaderSubPath(target: std.Build.ResolvedTarget) []const u8 {
     return if (target.result.cpu.arch == .aarch64)
         "third_party/webview2/arm64/WebView2Loader.dll"
@@ -2954,8 +2974,7 @@ fn addWebView2RuntimeRunFiles(dep: *std.Build.Dependency, target: std.Build.Reso
     if (web_engine != .system) return;
     if (!web_layer) return;
     if (target.result.os.tag != .windows) return;
-    const loader_dir = std.fs.path.dirname(webView2LoaderSubPath(target)).?;
-    run.addPathDir(dep.builder.pathFromRoot(loader_dir));
+    run.addPathDir(dep.builder.pathFromRoot(webView2LoaderDir(target)));
 }
 
 fn addCefRuntimeRunFiles(b: *std.Build, target: std.Build.ResolvedTarget, run: *std.Build.Step.Run, exe: *std.Build.Step.Compile, web_engine: WebEngineOption, cef_dir: []const u8) void {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zogien/native-sdk",
-  "version": "0.11.0-fork.3",
+  "version": "0.11.0-fork.5",
   "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.3",
-    "@zogien/native-sdk-darwin-x64": "0.11.0-fork.3",
-    "@zogien/native-sdk-linux-arm64-gnu": "0.11.0-fork.3",
-    "@zogien/native-sdk-linux-arm64-musl": "0.11.0-fork.3",
-    "@zogien/native-sdk-linux-x64-gnu": "0.11.0-fork.3",
-    "@zogien/native-sdk-linux-x64-musl": "0.11.0-fork.3",
-    "@zogien/native-sdk-win32-arm64": "0.11.0-fork.3",
-    "@zogien/native-sdk-win32-x64": "0.11.0-fork.3"
+    "@zogien/native-sdk-darwin-arm64": "0.11.0-fork.5",
+    "@zogien/native-sdk-darwin-x64": "0.11.0-fork.5",
+    "@zogien/native-sdk-linux-arm64-gnu": "0.11.0-fork.5",
+    "@zogien/native-sdk-linux-arm64-musl": "0.11.0-fork.5",
+    "@zogien/native-sdk-linux-x64-gnu": "0.11.0-fork.5",
+    "@zogien/native-sdk-linux-x64-musl": "0.11.0-fork.5",
+    "@zogien/native-sdk-win32-arm64": "0.11.0-fork.5",
+    "@zogien/native-sdk-win32-x64": "0.11.0-fork.5"
   },
   "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.3",
+  "version": "0.11.0-fork.5",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@native-sdk/core",
-      "version": "0.11.0-fork.3",
+      "version": "0.11.0-fork.5",
       "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.3",
+  "version": "0.11.0-fork.5",
   "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/core/references/bridge-security-native-capabilities.md

@@ -206,6 +206,10 @@ const result = await window.zero.invoke("native-sdk.dialog.showMessage", {
 });
 ```
 
+Each promise resolves when its dialog closes; the app keeps running meanwhile. `openFile` gives an array of paths and `saveFile` a path, or `null` when cancelled; `showMessage` gives `"primary"`, `"secondary"`, `"tertiary"`, or `"dismissed"` when closed without a button.
+
+From Zig, use `runtime.requestOpenDialog`, `requestSaveDialog` or `requestMessageDialog` with a `DialogCompletion`: the answer arrives in `on_result` on a later dispatch. The older `runtime.showOpenDialog` family blocks the event dispatch until the dialog closes; do not use it in new code.
+
 Use native dialogs for trusted app UI. Do not expose arbitrary filesystem access to remote or untrusted origins.
 
 ## Error handling

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/linux/cef_host.cpp

@@ -610,4 +610,26 @@ int native_sdk_gtk_show_message_dialog(Host *host, const void *opts) {
     return 0;
 }
 
+/* Asynchronous dialogs are not offered here: root.zig leaves them unbound
+ * for the Chromium engine, so the runtime falls back to the blocking
+ * calls above. */
+int native_sdk_gtk_request_dialog(Host *host, const void *request) {
+    (void)host;
+    (void)request;
+    return 0;
+}
+
+void native_sdk_gtk_cancel_dialog(Host *host, uint64_t id) {
+    (void)host;
+    (void)id;
+}
+
+int native_sdk_gtk_poll_dialog_result(Host *host, char *buffer, size_t buffer_len, void *result) {
+    (void)host;
+    (void)buffer;
+    (void)buffer_len;
+    (void)result;
+    return 0;
+}
+
 }