craft-native 0.0.77 → 0.0.79

package/dist/api/process.d.ts

@@ -62,9 +62,15 @@ export interface SpawnOptions {
     cwd?: string;
     env?: Record<string, string>;
     /**
-     * Run the command through a shell. The Craft bridge translates this
-     * automatically (cmd.exe on Windows, /bin/sh elsewhere). On the Node
-     * fallback the command is rewritten to `cmd.exe /c <cmd>` on win32.
+     * Run `command` as a command line through a shell (cmd.exe on Windows,
+     * /bin/sh elsewhere) instead of executing it directly.
+     *
+     * Off by default, as in Node. Without it `command` is a program and `args`
+     * are its arguments, so a `;` or `|` inside an argument reaches the program
+     * as a plain character rather than as shell syntax.
+     *
+     * A shell takes one string, so `args` cannot be passed with it — supplying
+     * both is refused rather than silently honouring one of them.
      */
     shell?: boolean;
 }

package/dist/api/window.d.ts

@@ -101,11 +101,6 @@ export interface WindowCreateOptions {
     webSidebarMaterialOpacity?: number;
     /** Titlebar style (macOS) */
     titlebarStyle?: 'default' | 'hidden' | 'hiddenInset' | 'customButtonsOnHover';
-    /** Traffic light position (macOS) */
-    trafficLightPosition?: {
-        x: number;
-        y: number;
-    };
     /** Vibrancy effect (macOS) */
     vibrancy?: 'appearance-based' | 'light' | 'dark' | 'titlebar' | 'selection' | 'menu' | 'popover' | 'sidebar' | 'header' | 'sheet' | 'window' | 'hud' | 'fullscreen-ui' | 'tooltip' | 'content' | 'under-window' | 'under-page';
     /** Background material (Windows 11) */
@@ -338,12 +333,23 @@ export declare class Window {
      */
     setVibrancy(vibrancy: WindowCreateOptions['vibrancy'] | null): Promise<void>;
     /**
-     * Set traffic light position (macOS)
-     */
-    setTrafficLightPosition(position: {
-        x: number;
-        y: number;
-    }): Promise<void>;
+     * Where the platform's window buttons are — read, not written.
+     *
+     * There was a `setTrafficLightPosition` here, and a `trafficLightPosition`
+     * window option beside it. Neither ever moved anything: the host has no
+     * handler for the call, and AppKit re-lays out the standard window buttons
+     * after any one-shot `setFrameOrigin:`, which is why `macos.zig` leaves them
+     * where the window server puts them and says so at length.
+     *
+     * What a layout actually needs is the opposite direction — where they *are*,
+     * which the host measures and publishes on every window:
+     *
+     *   window.craft.windowControls        { style, x, y, width, height, ... }
+     *   --craft-window-controls-width      the room to leave, in CSS
+     *
+     * See `CraftWindowControls`, and `docs/features/window-management.md`.
+     */
+    get windowControls(): import('../types.js').CraftWindowControls | undefined;
     /**
      * Set window level (macOS)
      */

package/dist/cli.js

@@ -4191,7 +4191,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.77";
+var version = "0.0.79";
 
 // bin/cli.ts
 var spawnedFrom = process6.env[CRAFT_CLI_SPAWN_MARKER];

package/dist/index.cjs

@@ -2532,8 +2532,8 @@ class Window {
   async setVibrancy(vibrancy) {
     await this._call("setVibrancy", { vibrancy });
   }
-  async setTrafficLightPosition(position) {
-    await this._call("setTrafficLightPosition", position);
+  get windowControls() {
+    return globalThis.craft?.windowControls;
   }
   async setWindowLevel(level) {
     await this._call("setWindowLevel", { level });
@@ -10745,6 +10745,10 @@ class CraftApp {
       args.push("--titlebar-hidden");
     if (window3?.headless)
       args.push("--headless");
+    if (window3?.keepRunning === true)
+      args.push("--keep-running");
+    else if (window3?.keepRunning === false)
+      args.push("--quit-on-close");
     if (window3?.webSidebarMaterial) {
       args.push("--web-sidebar-material");
       if (window3?.webSidebarWidth)

package/dist/index.js

@@ -2302,8 +2302,8 @@ class Window {
   async setVibrancy(vibrancy) {
     await this._call("setVibrancy", { vibrancy });
   }
-  async setTrafficLightPosition(position) {
-    await this._call("setTrafficLightPosition", position);
+  get windowControls() {
+    return globalThis.craft?.windowControls;
   }
   async setWindowLevel(level) {
     await this._call("setWindowLevel", { level });
@@ -10515,6 +10515,10 @@ class CraftApp {
       args.push("--titlebar-hidden");
     if (window3?.headless)
       args.push("--headless");
+    if (window3?.keepRunning === true)
+      args.push("--keep-running");
+    else if (window3?.keepRunning === false)
+      args.push("--quit-on-close");
     if (window3?.webSidebarMaterial) {
       args.push("--web-sidebar-material");
       if (window3?.webSidebarWidth)

package/dist/ios/templates/CraftApp.swift

@@ -364,7 +364,12 @@ struct CraftWebView: UIViewRepresentable {
     func updateUIView(_ webView: WKWebView, context: Context) {}
 
     func makeCoordinator() -> Coordinator {
-        Coordinator(config: config)
+        let coordinator = Coordinator(config: config)
+        // The Zig dispatcher finds CraftSwiftShim by class name; the shim finds
+        // its way back to the live coordinator through this. Weak, because
+        // SwiftUI owns the coordinator's lifetime.
+        CraftSwiftShim.coordinator = coordinator
+        return coordinator
     }
 
     // MARK: - Coordinator (Native Bridge)
@@ -511,8 +516,19 @@ struct CraftWebView: UIViewRepresentable {
             guard let body = message.body as? [String: Any],
                   let action = body["action"] as? String else { return }
 
-            let callbackId = body["callbackId"] as? String
+            dispatch(action: action, body: body, callbackId: body["callbackId"] as? String)
+        }
 
+        /// The action switch, reachable from two directions: the
+        /// WKScriptMessageHandler above, and `CraftSwiftShim.handleAction` when
+        /// the Zig dispatcher hands over an action it has not migrated yet.
+        ///
+        /// A hand-off call arrives with a synthetic callbackId of the form
+        /// "zig:<requestId>". The reply helpers recognise that prefix and route
+        /// the answer back through the Zig runtime's exported
+        /// `craft_ios_deliver_result` instead of evaluating JavaScript here —
+        /// one reply path, owned by whichever side received the page's message.
+        func dispatch(action: String, body: [String: Any], callbackId: String?) {
             switch action {
             case "startListening":
                 if config.enableSpeechRecognition { startSpeechRecognition() }
@@ -2222,41 +2238,33 @@ struct CraftWebView: UIViewRepresentable {
                     _progressCallbacks: [],
                     _statusCallbacks: [],
 
+                    // OTA is not implemented natively. These five used to post
+                    // to actions the switch below does not handle, and register
+                    // a resolve/reject pair that nothing would ever call — they
+                    // also bypassed _createCallback, which is what owns the 30s
+                    // timeout, so the promises hung forever rather than
+                    // rejecting. An immediate rejection is the honest answer:
+                    // an app can catch it, where it could never catch a hang.
+                    _unavailable: function(name) {
+                        return Promise.reject(new Error(
+                            'craft.ota.' + name + ' is not implemented on this platform'
+                        ));
+                    },
                     configure: function(options) {
                         this._config = options;
-                        window.webkit.messageHandlers.craft.postMessage({action: 'otaConfigure', config: options});
+                        console.warn('[craft] ota.configure stored locally; OTA is not implemented natively');
                     },
                     checkForUpdate: function() {
-                        var self = window.craft;
-                        var id = 'cb_' + (++self._callbackId);
-                        window.webkit.messageHandlers.craft.postMessage({action: 'otaCheckForUpdate', callbackId: id});
-                        return new Promise(function(resolve, reject) {
-                            self._callbacks[id] = {resolve: resolve, reject: reject};
-                        });
+                        return window.craft.ota._unavailable('checkForUpdate');
                     },
                     downloadUpdate: function(options) {
-                        var self = window.craft;
-                        var id = 'cb_' + (++self._callbackId);
-                        window.webkit.messageHandlers.craft.postMessage({action: 'otaDownloadUpdate', options: options || {}, callbackId: id});
-                        return new Promise(function(resolve, reject) {
-                            self._callbacks[id] = {resolve: resolve, reject: reject};
-                        });
+                        return window.craft.ota._unavailable('downloadUpdate');
                     },
                     applyUpdate: function() {
-                        var self = window.craft;
-                        var id = 'cb_' + (++self._callbackId);
-                        window.webkit.messageHandlers.craft.postMessage({action: 'otaApplyUpdate', callbackId: id});
-                        return new Promise(function(resolve, reject) {
-                            self._callbacks[id] = {resolve: resolve, reject: reject};
-                        });
+                        return window.craft.ota._unavailable('applyUpdate');
                     },
                     rollback: function() {
-                        var self = window.craft;
-                        var id = 'cb_' + (++self._callbackId);
-                        window.webkit.messageHandlers.craft.postMessage({action: 'otaRollback', callbackId: id});
-                        return new Promise(function(resolve, reject) {
-                            self._callbacks[id] = {resolve: resolve, reject: reject};
-                        });
+                        return window.craft.ota._unavailable('rollback');
                     },
                     getCurrentBundle: function() {
                         // This returns synchronously from stored data
@@ -2434,6 +2442,10 @@ struct CraftWebView: UIViewRepresentable {
                 rejectCallback(callbackId, error: "Native result could not be serialized", code: "SERIALIZATION_ERROR")
                 return
             }
+            // A hand-off from the Zig dispatcher replies through Zig, which
+            // owns the wire format, the request id, and the escaping. Replying
+            // by JavaScript here as well would give the page two answers.
+            if CraftSwiftShim.deliverResultIfHandOff(id, json: resultStr) { return }
             let script = "window.craft._resolveCallback('\(id)', \(resultStr));"
             DispatchQueue.main.async { self.webView?.evaluateJavaScript(script, completionHandler: nil) }
         }
@@ -2444,7 +2456,17 @@ struct CraftWebView: UIViewRepresentable {
 
         private func rejectCallback(_ callbackId: String?, error: String, code: String = "CRAFT_ERROR") {
             guard let id = callbackId else { return }
-            let escapedError = error.replacingOccurrences(of: "'", with: "\\'").replacingOccurrences(of: "\n", with: "\\n")
+            // A hand-off rejection goes back through Zig's error route, so the
+            // page's promise *rejects*. Delivering it as a result would run the
+            // app's then-branch with an error-shaped object — fabricated
+            // success wearing a different hat.
+            if CraftSwiftShim.deliverErrorIfHandOff(id, message: error, code: code) { return }
+            // Backslashes first: escaping ' and \n but not \ let an error
+            // message containing a backslash break out of the string literal.
+            let escapedError = error
+                .replacingOccurrences(of: "\\", with: "\\\\")
+                .replacingOccurrences(of: "'", with: "\\'")
+                .replacingOccurrences(of: "\n", with: "\\n")
             let script = "window.craft._rejectCallback('\(id)', '\(escapedError)', '\(code)');"
             DispatchQueue.main.async { self.webView?.evaluateJavaScript(script, completionHandler: nil) }
         }
@@ -5167,3 +5189,98 @@ extension CraftWebView.Coordinator: WCSessionDelegate {
         }
     }
 }
+
+
+// MARK: - Zig hand-off shim
+
+/// The seam the Zig dispatcher hands unmigrated actions through.
+///
+/// Discovery is symmetric and both directions are runtime-only. Zig finds this
+/// class with `objc_getClass("CraftSwiftShim")`; this class finds Zig's
+/// delivery exports with `dlsym`. Neither side links the other, so a
+/// pure-Swift app (no Zig runtime) and a fully-migrated Zig app (no shim work
+/// left) both build and run without dead dependencies.
+///
+/// The shim decides *what* the answer is, never *how* it reaches the page.
+/// Replies go back through Zig's `craft_ios_deliver_result` /
+/// `craft_ios_deliver_error`, which own the wire format, the request id, and
+/// the escaping. Two components replying to one page by different routes is
+/// how this codebase accumulated five envelopes.
+@objc(CraftSwiftShim)
+final class CraftSwiftShim: NSObject {
+    /// The coordinator serving hand-offs. Set by `makeCoordinator`.
+    static weak var coordinator: CraftWebView.Coordinator?
+
+    private typealias DeliverResultFn = @convention(c) (
+        UnsafePointer<CChar>, UInt, UnsafePointer<CChar>, UInt, Int64
+    ) -> Void
+    private typealias DeliverErrorFn = @convention(c) (
+        UnsafePointer<CChar>, UInt, UnsafePointer<CChar>, UInt,
+        UnsafePointer<CChar>, UInt, Int64
+    ) -> Void
+
+    private static let deliverResult: DeliverResultFn? = {
+        guard let sym = dlsym(dlopen(nil, RTLD_NOW), "craft_ios_deliver_result") else { return nil }
+        return unsafeBitCast(sym, to: DeliverResultFn.self)
+    }()
+
+    private static let deliverError: DeliverErrorFn? = {
+        guard let sym = dlsym(dlopen(nil, RTLD_NOW), "craft_ios_deliver_error") else { return nil }
+        return unsafeBitCast(sym, to: DeliverErrorFn.self)
+    }()
+
+    /// Entry point for the Zig dispatcher. Selector: handleAction:payload:requestId:
+    ///
+    /// Returns false when this shim cannot serve the call — no live
+    /// coordinator, or no Zig runtime to reply through — so Zig answers the
+    /// page with UnknownAction instead of the call vanishing.
+    @objc static func handleAction(_ action: String, payload: String, requestId: Int64) -> Bool {
+        guard let coordinator, deliverResult != nil else { return false }
+
+        let body = ((try? JSONSerialization.jsonObject(with: Data(payload.utf8))) as? [String: Any]) ?? [:]
+
+        // The synthetic callbackId routes this call's reply back through Zig.
+        // It carries the action too, because the reply helpers do not otherwise
+        // know it, and Zig's reply names the action for the page's
+        // action-matching fallback.
+        coordinator.dispatch(action: action, body: body, callbackId: "zig:\(requestId):\(action)")
+        return true
+    }
+
+    /// Route a resolve through Zig when the callbackId marks a hand-off.
+    /// Returns true when the reply has been (or could only be) handled here.
+    static func deliverResultIfHandOff(_ callbackId: String, json: String) -> Bool {
+        guard let (requestId, action) = parseHandOffId(callbackId) else { return false }
+        guard let deliverResult else { return true } // hand-off id but no runtime: drop, never eval JS
+        action.withCString { a in
+            json.withCString { j in
+                deliverResult(a, UInt(strlen(a)), j, UInt(strlen(j)), requestId)
+            }
+        }
+        return true
+    }
+
+    /// Route a rejection through Zig's error path, so the page's promise
+    /// rejects rather than resolving with an error-shaped object.
+    static func deliverErrorIfHandOff(_ callbackId: String, message: String, code: String) -> Bool {
+        guard let (requestId, action) = parseHandOffId(callbackId) else { return false }
+        guard let deliverError else { return true }
+        action.withCString { a in
+            message.withCString { m in
+                code.withCString { c in
+                    deliverError(a, UInt(strlen(a)), m, UInt(strlen(m)), c, UInt(strlen(c)), requestId)
+                }
+            }
+        }
+        return true
+    }
+
+    /// "zig:<requestId>:<action>" -> (requestId, action). Nil for ordinary
+    /// page-issued callback ids, which keep their JavaScript reply path.
+    private static func parseHandOffId(_ callbackId: String) -> (Int64, String)? {
+        guard callbackId.hasPrefix("zig:") else { return nil }
+        let rest = callbackId.dropFirst(4)
+        guard let sep = rest.firstIndex(of: ":"), let id = Int64(rest[..<sep]) else { return nil }
+        return (id, String(rest[rest.index(after: sep)...]))
+    }
+}

package/dist/types.d.ts

@@ -73,6 +73,22 @@ export interface WindowOptions {
      * error rather than a silent no-op.
      */
     headless?: boolean;
+    /**
+     * Keep the process running after the last window closes (macOS).
+     *
+     * Craft decides this from the shape of the app when it is not set: an app
+     * with a tray icon or in menubar-only mode stays running, because outliving
+     * its window is what those are for; an ordinary windowed app quits.
+     *
+     * Set it to `true` for a windowed app that should stay resident and be
+     * brought back by clicking the Dock icon, or `false` for a tray app that
+     * should genuinely go away when its window closes.
+     *
+     * Before this existed the answer was AppKit's default, `false`, for every
+     * app: closing the last window left a process with no window and no way to
+     * get one back.
+     */
+    keepRunning?: boolean;
     /**
      * Remember this window's size and position across launches, under this name
      * (macOS).
@@ -673,11 +689,46 @@ export interface AppInfo {
 /**
  * Notification options
  */
+/**
+ * A button on a notification banner.
+ *
+ * macOS shows two directly on a banner and puts any others behind an
+ * "Options" disclosure, so craft accepts at most four — past that they are
+ * a menu the user has to go looking for rather than a choice they can see.
+ *
+ * Two spellings are accepted. `{ id, label }` is the one to use. `{ action,
+ * title }` is what this type has said since before anything implemented it,
+ * and it keeps working rather than being deleted out from under whoever wrote
+ * against it — the field was published, it just never did anything.
+ */
+export type NotificationAction = {
+    /** Comes back as `actionId` in `craft.notifications.onAction`. */
+    id: string;
+    /** The text on the button. */
+    label: string;
+} | {
+    /** @deprecated Use `id`. */
+    action: string;
+    /** @deprecated Use `label`. */
+    title: string;
+};
 export interface NotificationOptions {
     /**
      * Notification title (required)
      */
     title: string;
+    /**
+     * Buttons on the banner.
+     *
+     * Pressing one brings the app forward and fires
+     * `craft.notifications.onAction` with `{ notificationId, actionId }` —
+     * which is what lets a prompt be answered without switching to the app
+     * first.
+     *
+     * Two buttons cannot share an `id`: the response names the button by id,
+     * and for an Approve/Deny prompt that name is the entire answer.
+     */
+    actions?: NotificationAction[];
     /**
      * Notification body text
      */
@@ -694,13 +745,6 @@ export interface NotificationOptions {
      * - Or any system sound name
      */
     sound?: string;
-    /**
-     * Action buttons (platform dependent)
-     */
-    actions?: Array<{
-        action: string;
-        title: string;
-    }>;
     /**
      * Notification tag (for grouping/replacing)
      */
@@ -916,7 +960,83 @@ export interface CraftMobileAPI {
  * defines the CraftBridge interface with additional mobile-only features
  * such as AR, ML, deep links, OTA updates, widgets, and auth persistence.
  */
+/**
+ * Where the platform drew this window's window buttons — the macOS traffic
+ * lights, and their equivalents elsewhere.
+ *
+ * The buttons are the window server's on every desktop window Craft opens that
+ * is not frameless: real, correctly styled, wired to the keyboard and to
+ * accessibility. A page must never draw replicas beside them, and this is what
+ * makes that unnecessary — it says where they are, so a layout can leave room
+ * instead of inventing its own.
+ *
+ * Every number is measured from the live window and re-sent when it changes: a
+ * resize, a fullscreen transition, a new document. Listen for the
+ * `craft:windowcontrols` event on `window` for layout that CSS cannot express;
+ * everything else is better served by the four CSS variables, which the host
+ * sets before the document is parsed.
+ *
+ * The same facts reach CSS as `--craft-window-controls-width` / `-height` /
+ * `-inset-x` / `-inset-y` / `-replicas`, and the document as
+ * `<html data-craft-window-controls="...">`.
+ */
+export interface CraftWindowControls {
+    /**
+     * `titlebar` — real buttons, in a titlebar above the page. Nothing to do.
+     * `overlay` — real buttons, over the page's own top-left corner. Leave room.
+     * `custom` — a frameless window: no buttons, and the page's own are the only
+     *   ones there can be.
+     * `none` — no window chrome in this environment at all (iOS, Android).
+     */
+    style: 'titlebar' | 'overlay' | 'custom' | 'none';
+    /** The platform drew real buttons for this window. */
+    native: boolean;
+    /**
+     * ...and they are on screen right now. False in fullscreen, where macOS
+     * takes them into an auto-hiding titlebar — which is why a layout should
+     * reserve `reserveWidth` rather than a remembered constant.
+     */
+    visible: boolean;
+    /**
+     * The block's true position, in CSS px from the top-left of the web
+     * viewport. Negative where the buttons are not over the page at all: above
+     * it in a plain titlebar window, to its left in a window whose web content
+     * starts after a native sidebar.
+     */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /**
+     * The room to leave inside the page — the block's far edge, or zero when it
+     * does not reach into the page. `--craft-window-controls-width` / `-height`.
+     */
+    reserveWidth: number;
+    reserveHeight: number;
+    /**
+     * Where the block starts inside the page, zero unless it overlaps.
+     * `--craft-window-controls-inset-x` / `-inset-y`.
+     */
+    insetX: number;
+    insetY: number;
+    /**
+     * The `display` a replica should take: `'none'` wherever real buttons exist
+     * and wherever there is no window to control, and `null` in a frameless
+     * window, where the page's own controls are the real ones. Published as
+     * `--craft-window-controls-replicas`, which is *removed* rather than set when
+     * this is null, so the page's own fallback applies.
+     */
+    replicas: 'none' | null;
+}
 export interface CraftBridgeAPI {
+    /**
+     * Where the platform drew this window's close/minimise/zoom buttons.
+     *
+     * Present in every Craft window, so a UI that has to lay out around them can
+     * ask instead of guessing — and so a UI shared with the browser can tell the
+     * two apart. See `CraftWindowControls`.
+     */
+    windowControls?: CraftWindowControls;
     /**
      * Trackpad gesture phases (desktop only).
      *
@@ -1038,13 +1158,18 @@ export interface CapabilityNamespace {
 export interface CraftCapabilities {
     namespaces: Record<string, CapabilityNamespace>;
     /**
-     * Every `craft:*` event channel, and whether anything native emits on it.
+     * Every `craft:*` event channel, and what craft can say about it.
+     *
+     * `'live'` means something in this build took out a permit to emit on it.
+     * `'unknown'` means craft cannot prove it either way — subscribe and see, and
+     * do **not** disable a feature over it.
      *
-     * A `false` here means subscribing would work and never fire — which cannot
-     * be derived from the action tables, so it is tracked separately by the
-     * emitters themselves.
+     * There is deliberately no `'dead'`. Craft cannot establish absence: the
+     * `craft:window:*` names are composed in JavaScript from
+     * `__craftDeliverWindowEvent('focus')`, so no source scan finds the literal
+     * even though the emitter is right there.
      */
-    channels: Record<string, boolean>;
+    channels: Record<string, 'live' | 'unknown'>;
 }
 /**
  * The only value types `craft.prefs` stores.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "craft-native",
-  "version": "0.0.77",
+  "version": "0.0.79",
   "type": "module",
   "description": "Build desktop apps with web languages - TypeScript SDK for Craft",
   "author": "Chris Breuer <chris@stacksjs.org>",