craft-native 0.0.77 → 0.0.78

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.78";
 
 // 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

@@ -2222,41 +2222,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

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.78",
   "type": "module",
   "description": "Build desktop apps with web languages - TypeScript SDK for Craft",
   "author": "Chris Breuer <chris@stacksjs.org>",