craft-native 0.0.443 → 0.0.449

package/README.md

@@ -339,6 +339,29 @@ if (await updater.checkForUpdates()) {
 }
 ```
 
+### Background update lifecycle
+
+Start and stop background checks through Craft rather than an app-owned timer:
+
+```ts
+updater.startAutoCheck({
+  initialDelay: 60_000,
+  enabled: async () => (await readNativePreferences()).automaticUpdates,
+  autoDownload: true,
+})
+// On native backend shutdown:
+updater.stopAutoCheck()
+```
+
+`checkInterval` on the updater config controls cadence. `enabled` is re-read
+at most a minute later (`policyInterval`), and again before a background download.
+The host owns preference storage; Craft creates no parallel database. Starts are
+idempotent, concurrent manifest checks and downloads share one operation, and a
+verified download stays ready until the user chooses installation. Stopping also
+invalidates policy reads already in flight. Downloads already started may finish.
+`autoInstall` defaults to false; keep it false when installation requires a user
+choice. Timers are unreferenced so they cannot keep a backend process alive.
+
 ### macOS trust
 
 The manifest's SHA-256 proves the download matches what the manifest asked for. It

package/dist/cli.js

@@ -3228,7 +3228,7 @@ function pinCraftNativeDependency(packagePath, craftVersion) {
 `);
 }
 // package.json
-var version = "0.0.443";
+var version = "0.0.449";
 
 // bin/cli.ts
 var spawnedFrom = process6.env[CRAFT_CLI_SPAWN_MARKER];

package/dist/index.cjs

@@ -376,7 +376,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.443";
+var version = "0.0.449";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;
@@ -11156,7 +11156,12 @@ class AutoUpdater extends import_events3.EventEmitter {
   config;
   updateInfo = null;
   downloadPath = null;
+  verifiedDownloadPath = null;
   checkTimer = null;
+  autoCheckGeneration = 0;
+  autoCheckRunning = false;
+  checking = null;
+  downloading = null;
   cachedEtag = null;
   cachedLastModified = null;
   cachedManifest = null;
@@ -11193,21 +11198,63 @@ class AutoUpdater extends import_events3.EventEmitter {
       ...config
     };
   }
-  startAutoCheck() {
-    this.checkForUpdates();
-    if (this.config.checkInterval) {
-      this.checkTimer = setInterval(() => {
-        this.checkForUpdates();
-      }, this.config.checkInterval);
-    }
+  startAutoCheck(options = {}) {
+    if (this.autoCheckRunning)
+      return;
+    const initialDelay = options.initialDelay ?? 0;
+    const policyInterval = options.policyInterval ?? 60000;
+    const interval = this.config.checkInterval ?? 3600000;
+    if (!Number.isFinite(initialDelay) || initialDelay < 0 || !Number.isFinite(policyInterval) || policyInterval <= 0 || !Number.isFinite(interval) || interval < 0)
+      throw new Error("Updater: automatic check intervals must be finite and non-negative, with a positive policyInterval");
+    this.autoCheckRunning = true;
+    const generation = ++this.autoCheckGeneration;
+    const active = () => this.autoCheckRunning && generation === this.autoCheckGeneration;
+    const enabled = async () => active() && (await options.enabled?.() ?? true) && active();
+    let nextCheck = Date.now() + initialDelay;
+    const schedule = (delay) => {
+      if (!active())
+        return;
+      this.checkTimer = setTimeout(() => {
+        tick();
+      }, delay);
+      this.checkTimer.unref?.();
+    };
+    const tick = async () => {
+      try {
+        if (await enabled() && Date.now() >= nextCheck && !(this.verifiedDownloadPath && import_fs4.existsSync(this.verifiedDownloadPath)) && !this.checking && !this.downloading) {
+          nextCheck = interval === 0 ? Infinity : Date.now() + interval;
+          const update = await this.checkForUpdates({ autoDownload: false });
+          if (update && !this.lastError && (options.autoDownload ?? this.config.autoDownload) && await enabled())
+            await this.downloadUpdate();
+        }
+      } catch (error) {
+        if (active())
+          this.emitError(error);
+      } finally {
+        if (active() && (interval !== 0 || nextCheck !== Infinity))
+          schedule(Math.min(policyInterval, nextCheck > Date.now() ? nextCheck - Date.now() : policyInterval));
+      }
+    };
+    schedule(initialDelay);
   }
   stopAutoCheck() {
-    if (this.checkTimer) {
-      clearInterval(this.checkTimer);
-      this.checkTimer = null;
+    this.autoCheckRunning = false;
+    this.autoCheckGeneration++;
+    if (this.checkTimer)
+      clearTimeout(this.checkTimer);
+    this.checkTimer = null;
+  }
+  checkForUpdates(options = {}) {
+    if (!this.checking && this.downloading)
+      return this.downloading.then(() => this.checkForUpdates(options));
+    if (!this.checking) {
+      this.checking = this.performCheck(options.autoDownload ?? this.config.autoDownload ?? true).finally(() => {
+        this.checking = null;
+      });
     }
+    return this.checking;
   }
-  async checkForUpdates() {
+  async performCheck(autoDownload) {
     this.emit("checking-for-update");
     this.lastError = null;
     try {
@@ -11223,7 +11270,7 @@ class AutoUpdater extends import_events3.EventEmitter {
         if (this.isNewerVersion(this.cachedManifest.version, this.config.currentVersion)) {
           this.updateInfo = this.cachedManifest;
           this.emit("update-available", this.cachedManifest);
-          if (this.config.autoDownload) {
+          if (autoDownload) {
             await this.downloadUpdate();
           }
           return this.cachedManifest;
@@ -11243,9 +11290,13 @@ class AutoUpdater extends import_events3.EventEmitter {
         if (updateInfo.minVersion && this.isNewerVersion(updateInfo.minVersion, this.config.currentVersion)) {
           console.log(`Update requires minimum version ${updateInfo.minVersion}`);
         }
+        if (this.updateInfo?.version !== updateInfo.version) {
+          this.downloadPath = null;
+          this.verifiedDownloadPath = null;
+        }
         this.updateInfo = updateInfo;
         this.emit("update-available", updateInfo);
-        if (this.config.autoDownload) {
+        if (autoDownload) {
           await this.downloadUpdate();
         }
         return updateInfo;
@@ -11258,7 +11309,19 @@ class AutoUpdater extends import_events3.EventEmitter {
       return null;
     }
   }
-  async downloadUpdate() {
+  downloadUpdate() {
+    if (this.downloading)
+      return this.downloading;
+    if (this.verifiedDownloadPath && import_fs4.existsSync(this.verifiedDownloadPath))
+      return Promise.resolve(this.verifiedDownloadPath);
+    if (!this.downloading) {
+      this.downloading = this.performDownload().finally(() => {
+        this.downloading = null;
+      });
+    }
+    return this.downloading;
+  }
+  async performDownload() {
     if (!this.updateInfo) {
       throw new Error("No update available");
     }
@@ -11366,6 +11429,7 @@ class AutoUpdater extends import_events3.EventEmitter {
           throw new Error("Download verification failed: invalid signature");
         }
       }
+      this.verifiedDownloadPath = this.downloadPath;
       this.emit("update-downloaded", {
         path: this.downloadPath,
         version: this.updateInfo.version,

package/dist/index.d.cts

@@ -36,7 +36,7 @@ export * from './styles/index.js';
 export * from './optimizations/index.js';
 export * as updater from './updater/index.js';
 export { AutoUpdater, generateUpdateManifest } from './updater/index.js';
-export type { UpdateInfo as UpdateManifest, UpdateProgress, UpdaterConfig, UpdaterEvent, PlatformUpdate, } from './updater/index.js';
+export type { AutoCheckOptions, CheckForUpdatesOptions, UpdateInfo as UpdateManifest, UpdateProgress, UpdaterConfig, UpdaterEvent, PlatformUpdate, } from './updater/index.js';
 export { canReplaceBundle, clearQuarantine, dittoBundle, extractBundle, extractBundleFromDmg, extractBundleFromZip, readBundleIdentity, swapBundle, verifyBundleTrust, } from './updater/index.js';
 export type { BundleIdentity, BundleTrustFailure, BundleTrustPolicy, BundleTrustResult, StagedBundle, SwapResult, } from './updater/index.js';
 export declare class CraftApp {

package/dist/index.d.ts

@@ -36,7 +36,7 @@ export * from './styles/index.js';
 export * from './optimizations/index.js';
 export * as updater from './updater/index.js';
 export { AutoUpdater, generateUpdateManifest } from './updater/index.js';
-export type { UpdateInfo as UpdateManifest, UpdateProgress, UpdaterConfig, UpdaterEvent, PlatformUpdate, } from './updater/index.js';
+export type { AutoCheckOptions, CheckForUpdatesOptions, UpdateInfo as UpdateManifest, UpdateProgress, UpdaterConfig, UpdaterEvent, PlatformUpdate, } from './updater/index.js';
 export { canReplaceBundle, clearQuarantine, dittoBundle, extractBundle, extractBundleFromDmg, extractBundleFromZip, readBundleIdentity, swapBundle, verifyBundleTrust, } from './updater/index.js';
 export type { BundleIdentity, BundleTrustFailure, BundleTrustPolicy, BundleTrustResult, StagedBundle, SwapResult, } from './updater/index.js';
 export declare class CraftApp {

package/dist/index.js

@@ -117,7 +117,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.443";
+var version = "0.0.449";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;
@@ -10912,7 +10912,12 @@ class AutoUpdater extends EventEmitter3 {
   config;
   updateInfo = null;
   downloadPath = null;
+  verifiedDownloadPath = null;
   checkTimer = null;
+  autoCheckGeneration = 0;
+  autoCheckRunning = false;
+  checking = null;
+  downloading = null;
   cachedEtag = null;
   cachedLastModified = null;
   cachedManifest = null;
@@ -10949,21 +10954,63 @@ class AutoUpdater extends EventEmitter3 {
       ...config
     };
   }
-  startAutoCheck() {
-    this.checkForUpdates();
-    if (this.config.checkInterval) {
-      this.checkTimer = setInterval(() => {
-        this.checkForUpdates();
-      }, this.config.checkInterval);
-    }
+  startAutoCheck(options = {}) {
+    if (this.autoCheckRunning)
+      return;
+    const initialDelay = options.initialDelay ?? 0;
+    const policyInterval = options.policyInterval ?? 60000;
+    const interval = this.config.checkInterval ?? 3600000;
+    if (!Number.isFinite(initialDelay) || initialDelay < 0 || !Number.isFinite(policyInterval) || policyInterval <= 0 || !Number.isFinite(interval) || interval < 0)
+      throw new Error("Updater: automatic check intervals must be finite and non-negative, with a positive policyInterval");
+    this.autoCheckRunning = true;
+    const generation = ++this.autoCheckGeneration;
+    const active = () => this.autoCheckRunning && generation === this.autoCheckGeneration;
+    const enabled = async () => active() && (await options.enabled?.() ?? true) && active();
+    let nextCheck = Date.now() + initialDelay;
+    const schedule = (delay) => {
+      if (!active())
+        return;
+      this.checkTimer = setTimeout(() => {
+        tick();
+      }, delay);
+      this.checkTimer.unref?.();
+    };
+    const tick = async () => {
+      try {
+        if (await enabled() && Date.now() >= nextCheck && !(this.verifiedDownloadPath && existsSync5(this.verifiedDownloadPath)) && !this.checking && !this.downloading) {
+          nextCheck = interval === 0 ? Infinity : Date.now() + interval;
+          const update = await this.checkForUpdates({ autoDownload: false });
+          if (update && !this.lastError && (options.autoDownload ?? this.config.autoDownload) && await enabled())
+            await this.downloadUpdate();
+        }
+      } catch (error) {
+        if (active())
+          this.emitError(error);
+      } finally {
+        if (active() && (interval !== 0 || nextCheck !== Infinity))
+          schedule(Math.min(policyInterval, nextCheck > Date.now() ? nextCheck - Date.now() : policyInterval));
+      }
+    };
+    schedule(initialDelay);
   }
   stopAutoCheck() {
-    if (this.checkTimer) {
-      clearInterval(this.checkTimer);
-      this.checkTimer = null;
+    this.autoCheckRunning = false;
+    this.autoCheckGeneration++;
+    if (this.checkTimer)
+      clearTimeout(this.checkTimer);
+    this.checkTimer = null;
+  }
+  checkForUpdates(options = {}) {
+    if (!this.checking && this.downloading)
+      return this.downloading.then(() => this.checkForUpdates(options));
+    if (!this.checking) {
+      this.checking = this.performCheck(options.autoDownload ?? this.config.autoDownload ?? true).finally(() => {
+        this.checking = null;
+      });
     }
+    return this.checking;
   }
-  async checkForUpdates() {
+  async performCheck(autoDownload) {
     this.emit("checking-for-update");
     this.lastError = null;
     try {
@@ -10979,7 +11026,7 @@ class AutoUpdater extends EventEmitter3 {
         if (this.isNewerVersion(this.cachedManifest.version, this.config.currentVersion)) {
           this.updateInfo = this.cachedManifest;
           this.emit("update-available", this.cachedManifest);
-          if (this.config.autoDownload) {
+          if (autoDownload) {
             await this.downloadUpdate();
           }
           return this.cachedManifest;
@@ -10999,9 +11046,13 @@ class AutoUpdater extends EventEmitter3 {
         if (updateInfo.minVersion && this.isNewerVersion(updateInfo.minVersion, this.config.currentVersion)) {
           console.log(`Update requires minimum version ${updateInfo.minVersion}`);
         }
+        if (this.updateInfo?.version !== updateInfo.version) {
+          this.downloadPath = null;
+          this.verifiedDownloadPath = null;
+        }
         this.updateInfo = updateInfo;
         this.emit("update-available", updateInfo);
-        if (this.config.autoDownload) {
+        if (autoDownload) {
           await this.downloadUpdate();
         }
         return updateInfo;
@@ -11014,7 +11065,19 @@ class AutoUpdater extends EventEmitter3 {
       return null;
     }
   }
-  async downloadUpdate() {
+  downloadUpdate() {
+    if (this.downloading)
+      return this.downloading;
+    if (this.verifiedDownloadPath && existsSync5(this.verifiedDownloadPath))
+      return Promise.resolve(this.verifiedDownloadPath);
+    if (!this.downloading) {
+      this.downloading = this.performDownload().finally(() => {
+        this.downloading = null;
+      });
+    }
+    return this.downloading;
+  }
+  async performDownload() {
     if (!this.updateInfo) {
       throw new Error("No update available");
     }
@@ -11122,6 +11185,7 @@ class AutoUpdater extends EventEmitter3 {
           throw new Error("Download verification failed: invalid signature");
         }
       }
+      this.verifiedDownloadPath = this.downloadPath;
       this.emit("update-downloaded", {
         path: this.downloadPath,
         version: this.updateInfo.version,

package/dist/ios/templates/CraftNativeScreen.swift

@@ -5524,6 +5524,22 @@ final class CraftNativeSolidSwitch: UIControl {
     private let naturalSize = UISwitch().intrinsicContentSize
     private var touchOrigin: CGPoint?
     private var dragPosition: CGFloat?
+    /// Where the thumb is *drawn*, which is where it rests except while a
+    /// change travels there. `thumbRect` keeps reporting the resting position,
+    /// so hit-testing, the drag maths and tests all read one instant,
+    /// authoritative value and only the drawing lags behind it.
+    private var drawnPosition: CGFloat = 0
+    private var travel: CADisplayLink?
+    private var travelFrom: CGFloat = 0
+    private var travelStart: CFTimeInterval = 0
+    /// Drawing can settle independently of immediate value changes and taps.
+    private static let travelDuration: CFTimeInterval = 0.38
+    /// Thumb stretch while held, from 0 (released) to 1 (pressed).
+    private var pressAmount: CGFloat = 0
+    private var pressTarget: CGFloat = 0
+    private var pressFrom: CGFloat = 0
+    private var pressStart: CFTimeInterval = 0
+    private static let pressDuration: CFTimeInterval = 0.14
     override var intrinsicContentSize: CGSize { naturalSize }
     override var isEnabled: Bool {
         didSet {
@@ -5533,6 +5549,14 @@ final class CraftNativeSolidSwitch: UIControl {
         }
     }
     override var canBecomeFirstResponder: Bool { isEnabled }
+    override var isHidden: Bool {
+        didSet { if isHidden { settleMotion(cancelTracking: true) } }
+    }
+    override var semanticContentAttribute: UISemanticContentAttribute {
+        didSet {
+            if oldValue != semanticContentAttribute { settleMotion(cancelTracking: true) }
+        }
+    }
 
     override init(frame: CGRect) {
         super.init(frame: frame)
@@ -5544,11 +5568,111 @@ final class CraftNativeSolidSwitch: UIControl {
     required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") }
 
     func setOn(_ value: Bool) {
+        let previous = visualPosition
+        let changed = isOn != value
         isOn = value
         refreshAccessibility()
+        guard changed else { setNeedsDisplay(); return }
+        drawnPosition = previous
+        moveThumb()
+    }
+
+    private var canAnimate: Bool {
+        guard isEnabled, !UIAccessibility.isReduceMotionEnabled, let window,
+              convert(bounds, to: window).intersects(window.bounds) else { return false }
+        var ancestor: UIView? = self
+        while let view = ancestor {
+            if view.isHidden || view.alpha <= 0 { return false }
+            ancestor = view.superview
+        }
+        return true
+    }
+
+    private func settleMotion(cancelTracking: Bool = false) {
+        travel?.invalidate()
+        travel = nil
+        drawnPosition = restingPosition
+        pressAmount = 0
+        pressTarget = 0
+        if cancelTracking {
+            touchOrigin = nil
+            dragPosition = nil
+        }
+        setNeedsDisplay()
+    }
+
+    /// Only drawing travels; value, accessibility and hit geometry change at once.
+    private func moveThumb() {
+        travel?.invalidate()
+        travel = nil
+        let target = restingPosition
+        travelFrom = dragPosition ?? drawnPosition
+        guard canAnimate else { settleMotion(); return }
+        travelStart = CACurrentMediaTime()
+        guard travelFrom != target || pressAmount != pressTarget else {
+            drawnPosition = target
+            setNeedsDisplay()
+            return
+        }
+        startLink()
+    }
+
+    /// Stretch the thumb toward where it is going, or let it relax back.
+    private func press(_ amount: CGFloat) {
+        guard pressTarget != amount else { return }
+        pressFrom = pressAmount
+        pressTarget = amount
+        pressStart = CACurrentMediaTime()
+        guard canAnimate else { settleMotion(); return }
+        if travel == nil {
+            drawnPosition = restingPosition
+            travelFrom = restingPosition
+            travelStart = CACurrentMediaTime()
+        }
+        startLink()
+    }
+
+    private func startLink() {
+        guard travel == nil else { return }
+        let link = CADisplayLink(target: self, selector: #selector(stepThumb))
+        link.add(to: .main, forMode: .common)
+        travel = link
+    }
+
+    @objc private func stepThumb() {
+        guard canAnimate else { settleMotion(); return }
+        let now = CACurrentMediaTime()
+        let target = restingPosition
+        let position = min(1, max(0, (now - travelStart) / Self.travelDuration))
+        drawnPosition = travelFrom + (target - travelFrom) * CGFloat(Self.spring(position))
+        let pressed = min(1, max(0, (now - pressStart) / Self.pressDuration))
+        pressAmount = pressFrom + (pressTarget - pressFrom) * CGFloat(pressed * pressed * (3 - 2 * pressed))
         setNeedsDisplay()
+        guard position >= 1, pressed >= 1 else { return }
+        drawnPosition = target
+        pressAmount = pressTarget
+        travel?.invalidate()
+        travel = nil
     }
 
+    /// A small spring overshoot, applied only to opaque drawing geometry.
+    private static func spring(_ fraction: Double) -> Double {
+        guard fraction < 1 else { return 1 }
+        let damping = 0.68, frequency = 15.0
+        let damped = frequency * (1 - damping * damping).squareRoot()
+        let decay = exp(-damping * frequency * fraction)
+        return 1 - decay * (cos(damped * fraction) + (damping * frequency / damped) * sin(damped * fraction))
+    }
+
+    /// A display link retains this control, so a switch that leaves the screen
+    /// mid-travel would hold itself alive and keep drawing frames nobody sees.
+    override func willMove(toWindow newWindow: UIWindow?) {
+        super.willMove(toWindow: newWindow)
+        guard newWindow == nil else { return }
+        settleMotion(cancelTracking: true)
+    }
+    deinit { travel?.invalidate() }
+
     func refreshAccessibility() {
         accessibilityTraits = .button
         if #available(iOS 17.0, *) { accessibilityTraits.insert(.toggleButton) }
@@ -5561,21 +5685,99 @@ final class CraftNativeSolidSwitch: UIControl {
         let size = CGSize(width: min(bounds.width, naturalSize.width), height: min(bounds.height, naturalSize.height))
         return CGRect(x: bounds.midX - size.width / 2, y: bounds.midY - size.height / 2, width: size.width, height: size.height)
     }
-    var thumbRect: CGRect {
+    private var restingPosition: CGFloat {
+        (isOn == (effectiveUserInterfaceLayoutDirection != .rightToLeft)) ? 1 : 0
+    }
+    private var visualPosition: CGFloat {
+        dragPosition ?? (travel == nil ? restingPosition : drawnPosition)
+    }
+    /// Where the thumb belongs now. A finger on it wins, then the state.
+    var thumbRect: CGRect { thumbRect(at: dragPosition ?? restingPosition) }
+    /// Where this frame draws it: the same, except part-way through a travel,
+    /// and stretched toward its destination while a finger holds it down.
+    private var drawnThumbRect: CGRect {
+        let position = visualPosition
+        let rect = thumbRect(at: position)
+        guard pressAmount > 0 else { return rect }
+        let track = trackRect.insetBy(dx: 2, dy: 2)
+        let stretch = rect.width * 0.18 * pressAmount
+        // It grows toward the end it is heading for, so the edge nearest the
+        // finger stays put and the far edge reaches.
+        let x = position < 0.5 ? rect.minX : rect.minX - stretch
+        return CGRect(x: min(max(x, track.minX), track.maxX - rect.width - stretch),
+                      y: rect.minY, width: rect.width + stretch, height: rect.height)
+    }
+    private func thumbRect(at position: CGFloat) -> CGRect {
         let track = trackRect.insetBy(dx: 2, dy: 2)
-        let onRight = effectiveUserInterfaceLayoutDirection != .rightToLeft
-        let position = dragPosition ?? ((isOn == onRight) ? 1 : 0)
         return CGRect(x: track.minX + (track.width - track.height) * position, y: track.minY, width: track.height, height: track.height)
     }
     override func draw(_ rect: CGRect) {
         let track = trackRect
-        guard track.width > 4, track.height > 4 else { return }
-        (isEnabled ? (isOn ? onColor ?? .systemGreen : offColor ?? .systemGray4) : UIColor.systemGray4).setFill()
-        UIBezierPath(roundedRect: track, cornerRadius: track.height / 2).fill()
+        guard track.width > 4, track.height > 4, let context = UIGraphicsGetCurrentContext() else { return }
+        let position = visualPosition
+        // The track's colour arrives *with* the thumb. Filling it from `isOn`
+        // turns the whole track the instant the value changes, so the colour
+        // overtakes the thumb and the two read as two separate things moving.
+        let dim = isEnabled ? (offColor ?? .systemGray4) : UIColor.systemGray4
+        let lit = isEnabled ? (onColor ?? .systemGreen) : UIColor.systemGray4
+        let onness = effectiveUserInterfaceLayoutDirection != .rightToLeft ? position : 1 - position
+        Self.blend(dim, lit, onness).setFill()
+        let trackPath = UIBezierPath(roundedRect: track, cornerRadius: track.height / 2)
+        trackPath.fill()
+        // The well the thumb sits in: shaded under its own top rim.
+        context.saveGState()
+        trackPath.addClip()
+        if let shade = CGGradient(colorsSpace: CGColorSpaceCreateDeviceRGB(),
+                                  colors: [UIColor.black.withAlphaComponent(0.10).cgColor, UIColor.clear.cgColor] as CFArray,
+                                  locations: [0, 1]) {
+            context.drawLinearGradient(shade, start: CGPoint(x: track.midX, y: track.minY),
+                                       end: CGPoint(x: track.midX, y: track.minY + track.height * 0.55), options: [])
+        }
+        context.restoreGState()
+
+        let thumb = drawnThumbRect
+        let thumbPath = UIBezierPath(roundedRect: thumb, cornerRadius: thumb.height / 2)
+        // Draw the shadow in the same frame, without layer animations or fades.
+        context.saveGState()
+        context.setShadow(offset: CGSize(width: 0, height: 1.5), blur: 3,
+                          color: UIColor.black.withAlphaComponent(isEnabled ? 0.28 : 0.16).cgColor)
         // The solid variant deliberately ignores thumb alpha. No transient
         // glass, scaling, fade, implicit layer animation or delayed redraw.
         (thumbColor ?? .white).withAlphaComponent(1).setFill()
-        UIBezierPath(ovalIn: thumbRect).fill()
+        thumbPath.fill()
+        context.restoreGState()
+        // Shading stays above the opaque fill and away from its centre.
+        context.saveGState()
+        thumbPath.addClip()
+        if let gloss = CGGradient(colorsSpace: CGColorSpaceCreateDeviceRGB(),
+                                  colors: [UIColor.white.withAlphaComponent(0.55).cgColor, UIColor.clear.cgColor] as CFArray,
+                                  locations: [0, 1]) {
+            context.drawLinearGradient(gloss, start: CGPoint(x: thumb.midX, y: thumb.minY),
+                                       end: CGPoint(x: thumb.midX, y: thumb.minY + thumb.height * 0.40), options: [])
+        }
+        if let sheen = CGGradient(colorsSpace: CGColorSpaceCreateDeviceRGB(),
+                                  colors: [UIColor.clear.cgColor, UIColor.black.withAlphaComponent(0.07).cgColor] as CFArray,
+                                  locations: [0, 1]) {
+            context.drawLinearGradient(sheen, start: CGPoint(x: thumb.midX, y: thumb.maxY - thumb.height * 0.20),
+                                       end: CGPoint(x: thumb.midX, y: thumb.maxY), options: [])
+        }
+        context.restoreGState()
+        // A hairline rim, so it still separates from a pale track.
+        UIColor.black.withAlphaComponent(0.06).setStroke()
+        thumbPath.lineWidth = 0.5
+        thumbPath.stroke()
+    }
+
+    /// Mix two colours, for a track that changes with the thumb rather than
+    /// ahead of it.
+    private static func blend(_ from: UIColor, _ to: UIColor, _ amount: CGFloat) -> UIColor {
+        let mix = min(1, max(0, amount))
+        var fr: CGFloat = 0, fg: CGFloat = 0, fb: CGFloat = 0, fa: CGFloat = 0
+        var tr: CGFloat = 0, tg: CGFloat = 0, tb: CGFloat = 0, ta: CGFloat = 0
+        guard from.getRed(&fr, green: &fg, blue: &fb, alpha: &fa),
+              to.getRed(&tr, green: &tg, blue: &tb, alpha: &ta) else { return mix < 0.5 ? from : to }
+        return UIColor(red: fr + (tr - fr) * mix, green: fg + (tg - fg) * mix,
+                       blue: fb + (tb - fb) * mix, alpha: fa + (ta - fa) * mix)
     }
     override func traitCollectionDidChange(_ previousTraitCollection: UITraitCollection?) {
         super.traitCollectionDidChange(previousTraitCollection)
@@ -5585,6 +5787,7 @@ final class CraftNativeSolidSwitch: UIControl {
         guard isEnabled else { return false }
         touchOrigin = touch.location(in: self)
         dragPosition = nil
+        press(1)
         return true
     }
     func updateDrag(to point: CGPoint) {
@@ -5599,7 +5802,15 @@ final class CraftNativeSolidSwitch: UIControl {
         return true
     }
     override func endTracking(_ touch: UITouch?, with event: UIEvent?) {
-        defer { touchOrigin = nil; dragPosition = nil; setNeedsDisplay() }
+        // The thumb carries on from wherever the finger left it, rather than
+        // jumping to the end of the track the moment it lifts.
+        defer {
+            touchOrigin = nil
+            if let released = dragPosition { drawnPosition = released }
+            dragPosition = nil
+            press(0)
+            moveThumb()
+        }
         guard isEnabled, let touch, touchOrigin != nil,
               bounds.insetBy(dx: -10, dy: -10).contains(touch.location(in: self)) else { return }
         let next = dragPosition.map { ($0 >= 0.5) == (effectiveUserInterfaceLayoutDirection != .rightToLeft) } ?? !isOn
@@ -5607,8 +5818,10 @@ final class CraftNativeSolidSwitch: UIControl {
     }
     override func cancelTracking(with event: UIEvent?) {
         touchOrigin = nil
+        if let released = dragPosition { drawnPosition = released }
         dragPosition = nil
-        setNeedsDisplay()
+        press(0)
+        moveThumb()
     }
     override func accessibilityActivate() -> Bool {
         guard isEnabled else { return false }

package/dist/ios/templates/testing/DriverTests.swift.template

@@ -193,10 +193,15 @@ final class DriverTests: XCTestCase {
               visibleScrollFrame(target.frame, in: app.frame) else { return false }
         // Hittable alone accepts controls clipped by the scroll view's edge.
         // Only an ancestor scroll view clips this target, not its siblings.
+        // One that does not overlap the target is not its ancestor, whatever
+        // the descendants query says: with a keyboard up, the query matched
+        // a form's Send button inside the keyboard's suggestion strip, and
+        // Send, in full view above the keys, could never be scrolled to.
         let identity = NSPredicate(format: "identifier == %@ AND label == %@", target.identifier, target.label)
-        for scroll in app.scrollViews.allElementsBoundByIndex {
+        let frame = target.frame
+        for scroll in app.scrollViews.allElementsBoundByIndex where scroll.frame.intersects(frame) {
             if scroll.descendants(matching: .any).matching(identity).firstMatch.exists,
-               !visibleScrollFrame(target.frame, in: scroll.frame.intersection(app.frame)) { return false }
+               !visibleScrollFrame(frame, in: scroll.frame.intersection(app.frame)) { return false }
         }
         return true
     }
@@ -287,6 +292,12 @@ final class DriverTests: XCTestCase {
 
     /// A switch reports "0" or "1". Any other value is not a switch state to
     /// wait on, so the tap stands as it would for any other control.
+    /// The switch answers `/exec` with 200 whatever the hook did, its first
+    /// word the hook's exit code: only `exit 0` is a hook that worked.
+    func hookSucceeded(_ answer: String) -> Bool {
+        answer.trimmingCharacters(in: .whitespacesAndNewlines).hasPrefix("exit 0")
+    }
+
     func switchFlipped(from before: String?, to after: String?) -> Bool {
         let states: Set<String> = ["0", "1"]
         guard let before, let after, states.contains(before), states.contains(after) else { return true }
@@ -390,7 +401,12 @@ final class DriverTests: XCTestCase {
                 check(false, "exec \(arg): hook failed or returned no successful response")
                 return
             }
-            note("exec \(arg): \(out.trimmingCharacters(in: .whitespacesAndNewlines))")
+            let answer = out.trimmingCharacters(in: .whitespacesAndNewlines)
+            note("exec \(arg): \(answer)")
+            // A failed hook (a fresh install that never reinstalled) stops the
+            // journey here with its reason, not three steps later at a screen
+            // that was never reset.
+            check(hookSucceeded(answer), "exec \(arg): hook failed: \(answer)")
         case "openurl":
             if let url = URL(string: arg) {
                 XCUIDevice.shared.system.open(url)

package/dist/macos/src/index.js

@@ -43,9 +43,9 @@ import process from "process";
 var macosToolchain = {
   zig: "0.18.0-dev.252+86dc5ce25",
   sources: {
-    "zig-js": { repository: "zig-utils/zig-js", revision: "95d835edcbad55a7456cff76a9bb7ef6cdf265fc", paths: ["src", "include", "tests", "tools", "docs", "bench", "conformance"] },
+    "zig-js": { repository: "zig-utils/zig-js", revision: "58885b7dad974d15b4eb410dc617da64d8c29550", paths: ["src", "include", "tests", "tools", "docs", "bench", "conformance"] },
     "zig-regex": { repository: "zig-utils/zig-regex", revision: "fdd9c2e333ea6ac2fd06d080d939ef7f11d61b1b", paths: ["src"] },
-    "zig-gc": { repository: "zig-utils/zig-gc", revision: "73c802e05768a729614e9c4296abb118aa06faf9", paths: ["src"] }
+    "zig-gc": { repository: "zig-utils/zig-gc", revision: "9bdb139cb4c6cdaa37b6fa2abebcf549cfe43762", paths: ["src"] }
   }
 };
 var defaultRun = async (args, cwd) => {

package/dist/macos/src/toolchain.d.ts

@@ -9,7 +9,7 @@ export declare const macosToolchain: {
     readonly sources: {
         readonly 'zig-js': {
             readonly repository: 'zig-utils/zig-js';
-            readonly revision: '95d835edcbad55a7456cff76a9bb7ef6cdf265fc';
+            readonly revision: '58885b7dad974d15b4eb410dc617da64d8c29550';
             readonly paths: readonly ['src', 'include', 'tests', 'tools', 'docs', 'bench', 'conformance'];
         };
         readonly 'zig-regex': {
@@ -19,7 +19,7 @@ export declare const macosToolchain: {
         };
         readonly 'zig-gc': {
             readonly repository: 'zig-utils/zig-gc';
-            readonly revision: '73c802e05768a729614e9c4296abb118aa06faf9';
+            readonly revision: '9bdb139cb4c6cdaa37b6fa2abebcf549cfe43762';
             readonly paths: readonly ['src'];
         };
     };

package/dist/macos/templates/CraftMacRenderer.swift

@@ -304,17 +304,25 @@ final class CraftMacBox: NSView, NSTextFieldDelegate, NSTextViewDelegate, NSDrag
     private struct MeasureKey: Hashable { let width: CGFloat, stretch: Bool }
     private var measured: [MeasureKey: CGSize] = [:]
     /// What this box measured is stale: it or something inside it changed (CraftMacRenderer.update).
-    func forgetMeasurements() { measured.removeAll(keepingCapacity: true); controlSize = nil }
+    func forgetMeasurements() { measured.removeAll(keepingCapacity: true); controlSize = nil; mergedLayoutStyle = nil }
     private var measuredGeneration = -1
     /// A control's own size (a button, a switch, a picker), asked once rather than at every width the box is
     /// measured at: a button answers through SwiftUI's layout on current macOS. Forgotten with the measurements.
     private var controlSize: CGSize?
     var componentRoot: CraftMacBox? { props["data-stx-component-wrapper"] != nil && flow?.boxes.count == 1 && flow?.boxes.first?.kind != "Modal" ? flow?.boxes.first : nil }
+    static let componentLayoutKeys = ["width", "height", "minWidth", "minHeight", "maxWidth", "maxHeight", "flex", "flexGrow", "flexShrink", "flexBasis", "alignSelf", "position", "zIndex", "left", "right", "top", "bottom", "margin", "marginTop", "marginRight", "marginBottom", "marginLeft", "marginHorizontal", "marginVertical"]
+    /// A component wrapper's style with its root's layout keys merged in, kept as its measurements are (it
+    /// depends on the same things): a flex pass asks for each child's several times, and a wrapper's merge
+    /// asked its root for its own once per key, so nested wrappers rebuilt their styles many times over.
+    private var mergedLayoutStyle: [String: Any]?
+    private var mergedGeneration = -1
     var layoutStyle: [String: Any] {
         guard let child = componentRoot else { return style }
-        let keys = ["width", "height", "minWidth", "minHeight", "maxWidth", "maxHeight", "flex", "flexGrow", "flexShrink", "flexBasis", "alignSelf", "position", "zIndex", "left", "right", "top", "bottom", "margin", "marginTop", "marginRight", "marginBottom", "marginLeft", "marginHorizontal", "marginVertical"]
+        if mergedGeneration == CraftMacBox.measureGeneration, let merged = mergedLayoutStyle { return merged }
+        let inner = child.layoutStyle
         var result = style
-        for key in keys where result[key] == nil { result[key] = child.layoutStyle[key] }
+        for key in Self.componentLayoutKeys where result[key] == nil { result[key] = inner[key] }
+        mergedLayoutStyle = result; mergedGeneration = CraftMacBox.measureGeneration
         return result
     }
     override var isFlipped: Bool { true }
@@ -371,7 +379,7 @@ final class CraftMacBox: NSView, NSTextFieldDelegate, NSTextViewDelegate, NSDrag
     required init?(coder: NSCoder) { fatalError("Native controls are created from STX") }
 
     func configure(_ node: [String: Any]) {
-        controlSize = nil
+        controlSize = nil; mergedLayoutStyle = nil
         props = node["props"] as? [String: Any] ?? [:]
         flow?.componentScope = props["data-stx-component-wrapper"] != nil
         style = node["style"] as? [String: Any] ?? [:]
@@ -775,11 +783,16 @@ final class CraftMacBox: NSView, NSTextFieldDelegate, NSTextViewDelegate, NSDrag
             let rect = (text.stringValue as NSString).boundingRect(with: CGSize(width: max(1, limit - 6 - textPadding.left - textPadding.right), height: 1_000_000), options: [.usesLineFragmentOrigin, .usesFontLeading], attributes: [.font: text.font ?? NSFont.systemFont(ofSize: 13)])
             size = CGSize(width: min(limit, ceil(rect.width) + 9 + textPadding.left + textPadding.right), height: max(18, ceil(rect.height) + 2))
             // The field draws only whole lines inside its cell's insets, so a height short of what the cell
-            // asks for at the width it will draw at drops the last line. Ask the cell, not just the string.
-            let fieldWidth = max(1, size.width - textPadding.left - textPadding.right)
-            if let drawn = text.cell?.cellSize(forBounds: CGRect(x: 0, y: 0, width: fieldWidth, height: 1_000_000)).height { size.height = max(size.height, ceil(drawn)) }
-            if text.maximumNumberOfLines > 0 { size.height = min(size.height, ceil((text.font?.ascender ?? 13) - (text.font?.descender ?? -3) + (text.font?.leading ?? 0)) * CGFloat(text.maximumNumberOfLines) + 2) }
-            if text.maximumNumberOfLines == 1 { size.height = max(18, (text.font?.pointSize ?? 13) + 5) }
+            // asks for at the width it will draw at drops the last line. Ask the cell, not just the string,
+            // unless the line limit decides the height anyway: one line, or a cap the string already reaches.
+            let lines = text.maximumNumberOfLines
+            let cap = lines > 0 ? ceil((text.font?.ascender ?? 13) - (text.font?.descender ?? -3) + (text.font?.leading ?? 0)) * CGFloat(lines) + 2 : .infinity
+            if lines != 1, size.height < cap {
+                let fieldWidth = max(1, size.width - textPadding.left - textPadding.right)
+                if let drawn = text.cell?.cellSize(forBounds: CGRect(x: 0, y: 0, width: fieldWidth, height: 1_000_000)).height { size.height = max(size.height, ceil(drawn)) }
+            }
+            if lines > 0 { size.height = min(size.height, cap) }
+            if lines == 1 { size.height = max(18, (text.font?.pointSize ?? 13) + 5) }
             size.height += textPadding.top + textPadding.bottom
         } else if kind == "ScrollView" || kind == "FlatList" || kind == "Sidebar" { size = CGSize(width: limit, height: 100) }
         else if kind == "WebView" { size = CGSize(width: limit, height: 300) }

package/dist/macos/templates/CraftMacRuntime.swift

@@ -15,6 +15,8 @@ enum CraftTrace {
         return Double(info.kp_proc.p_starttime.tv_sec) + Double(info.kp_proc.p_starttime.tv_usec) / 1_000_000
     }()
     private static func since() -> Double { (Date().timeIntervalSince1970 - processStart) * 1000 }
+    /// Milliseconds on a monotonic clock, for timing a span from either side of the bridge.
+    static func now() -> Double { Double(clock_gettime_nsec_np(CLOCK_UPTIME_RAW)) / 1_000_000 }
     static func mark(_ phase: @autoclosure () -> String) {
         guard enabled else { return }
         fputs(String(format: "[craft trace] %8.1f %@\n", since(), phase()), stderr)
@@ -135,10 +137,12 @@ final class CraftMacRuntime {
     let route: String
     let network: CraftMacNetwork
     private let thread = CraftMacScriptThread()
+    /// Decodes what the screen posts (`receive`), in the order it was posted, and keeps its network tasks.
+    private let decoder = DispatchQueue(label: "craft.script.decode", qos: .userInteractive)
+    private var tasks: [String: URLSessionTask] = [:]
     // Script thread only: the context and what the screen asked of it.
     private var context: ZigJSContext?
     private var timers: [Int: CFRunLoopTimer] = [:]
-    private var tasks: [String: URLSessionTask] = [:]
     private var stopped = false
     // Main thread only.
     private(set) weak var scene: CraftMacScene?
@@ -169,13 +173,25 @@ final class CraftMacRuntime {
         defer { JSGlobalContextRelease(created) }
         let context = ZigJSContext(jsGlobalContextRef: created)!
         self.context = context
+        // The bundle's parsed tree is kept between launches, in the app's own caches (entries are trusted,
+        // so never a shared folder): a screen's next start skips parsing its bundle.
+        if let caches = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first {
+            let directory = caches.appendingPathComponent(Bundle.main.bundleIdentifier ?? "dev.craft.native", isDirectory: true).appendingPathComponent("zig-js-scripts", isDirectory: true)
+            _ = ZJSContextSetScriptCacheDirectory(created, directory.path)
+        }
         context.exceptionHandler = { [weak self] _, value in
             let message = value?.objectForKeyedSubscript("message")?.toString() ?? "Native script failed"
             let stack = value?.objectForKeyedSubscript("stack")?.toString() ?? ""
             self?.report(message)
             fputs("[craft native] \(message)\n\(stack)\n", stderr)
         }
-        let post: @convention(block) (String) -> Void = { [weak self] text in self?.receive(text) }
+        // An NSString: bridging the text to a Swift String would copy it again on the screen's thread.
+        let post: @convention(block) (NSString) -> Void = { [weak self] text in self?.receive(text) }
+        // Under CRAFT_TRACE the screen's side of each post is timed too (`post`, below), from JavaScript.
+        let tracePost: @convention(block) (Double, Double) -> Void = { bytes, start in
+            CraftTrace.mark(String(format: "  post %.0f bytes (%.2f ms on the screen's thread)", bytes, CraftTrace.now() - start))
+        }
+        let now: @convention(block) () -> Double = { CraftTrace.now() }
         let schedule: @convention(block) (Int, Double) -> Void = { [weak self] id, delay in
             guard let self, !self.stopped else { return }
             self.timers[id] = self.thread.after(max(0, min(delay.isFinite ? delay : 0, 2_147_483_647)) / 1000) { [weak self] in
@@ -205,6 +221,10 @@ final class CraftMacRuntime {
         context.setObject(storageSet, forKeyedSubscript: "craftNativeStorageSet" as NSString)
         context.setObject(secureGet, forKeyedSubscript: "craftNativeSecureGet" as NSString)
         context.setObject(post, forKeyedSubscript: "craftNativePostMessage" as NSString)
+        if CraftTrace.enabled {
+            context.setObject(tracePost, forKeyedSubscript: "craftNativeTracePost" as NSString)
+            context.setObject(now, forKeyedSubscript: "craftNativeNow" as NSString)
+        }
         context.setObject(schedule, forKeyedSubscript: "craftNativeScheduleTimer" as NSString)
         context.setObject(cancel, forKeyedSubscript: "craftNativeCancelTimer" as NSString)
         context.setObject(log, forKeyedSubscript: "craftNativeLog" as NSString)
@@ -222,7 +242,9 @@ final class CraftMacRuntime {
         context.evaluateScript("""
         globalThis.__stxNativeCallback = null;
         globalThis.__stxNativeBridge = \(bridgeJSON);
-        __stxNativeBridge.postMessage = function(text) { craftNativePostMessage(text); };
+        __stxNativeBridge.postMessage = typeof craftNativeTracePost === 'function'
+            ? function(text) { var start = craftNativeNow(); craftNativePostMessage(text); craftNativeTracePost(text.length, start); }
+            : function(text) { craftNativePostMessage(text); };
         __stxNativeBridge.onMessage = function(callback) { globalThis.__stxNativeCallback = callback; };
         globalThis.craft = globalThis.craft || {};
         craft.storage = {
@@ -322,12 +344,12 @@ final class CraftMacRuntime {
         CraftMacWebTabs.shared.closeAll(owner: self)
         #endif
         network.cancelStreams(owner: self)
+        decoder.async { self.tasks.values.forEach { $0.cancel() }; self.tasks.removeAll() }
         let done = DispatchSemaphore(value: 0)
         thread.run {
             self.context?.objectForKeyedSubscript("__stxNativeUnmount")?.call(withArguments: [])
             self.stopped = true
             self.timers.values.forEach(CFRunLoopTimerInvalidate); self.timers.removeAll()
-            self.tasks.values.forEach { $0.cancel() }; self.tasks.removeAll()
             // Released on the thread that made it.
             self.context = nil
             done.signal()
@@ -355,10 +377,19 @@ final class CraftMacRuntime {
         send("EVENT", ["handlerId": id, "nativeEvent": payload])
     }
 
-    /// A message from the screen, on its thread. Network requests start here, so a screen's first fetch
-    /// leaves while AppKit is still launching; whatever draws or needs AppKit goes to the main thread.
-    private func receive(_ text: String) {
-        guard let data = text.data(using: .utf8), let message = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else { return }
+    /// A message from the screen, on its thread: handed to a queue of its own to decode, so the screen's
+    /// post returns at once. Decoding a batch of a few hundred operations took the screen's thread several
+    /// milliseconds per post, inside the screen's render.
+    private func receive(_ text: NSString) {
+        decoder.async { [weak self] in self?.decode(text) }
+    }
+
+    /// Decodes the screen's messages in order. Network requests start and storage answers here; whatever
+    /// draws or needs AppKit goes to the main thread.
+    private func decode(_ text: NSString) {
+        guard let message = CraftTrace.span("  decode \(text.length) chars", atLeast: 1, {
+            text.data(using: String.Encoding.utf8.rawValue).flatMap { try? JSONSerialization.jsonObject(with: $0) as? [String: Any] }
+        }) else { return }
         let payload = message["payload"] as? [String: Any] ?? [:]
         switch message["type"] as? String {
         case "RENDER", "MUTATE": DispatchQueue.main.async { self.whenAttached { self.handle(message) } }
@@ -414,15 +445,16 @@ final class CraftMacRuntime {
 
     /// An answer to the screen's request `id`, from any thread.
     func answer(_ id: String, _ value: Any = NSNull()) {
-        thread.run { self.tasks.removeValue(forKey: id) }
+        decoder.async { self.tasks.removeValue(forKey: id) }
         send("API_RESPONSE", ["version": 1, "requestId": id, "data": value], correlation: id)
     }
     func fail(_ id: String, _ code: String, _ message: String) {
-        thread.run { self.tasks.removeValue(forKey: id) }
+        decoder.async { self.tasks.removeValue(forKey: id) }
         send("API_ERROR", ["version": 1, "requestId": id, "code": code, "message": message], correlation: id)
     }
 
-    /// `Network` requests, on the script thread. Their answers come back on the network's own queue.
+    /// `Network` requests, on the decoding queue, which keeps their tasks: a request leaves as soon as it is
+    /// posted, even while the screen goes on rendering. Their answers come back on the network's own queue.
     private func fetch(_ id: String, _ method: String, _ args: [Any]) {
         let options = args.first as? [String: Any] ?? [:]
         if method == "cancelStream" { network.cancelStream(args.first as? String ?? "", owner: self); answer(id); return }
@@ -442,7 +474,7 @@ final class CraftMacRuntime {
         tasks[id] = task; network.resume(task)
     }
 
-    /// `Storage` and `SecureStorage`, on the script thread: UserDefaults and the Keychain answer on any.
+    /// `Storage` and `SecureStorage`, on the decoding queue: UserDefaults and the Keychain answer on any thread.
     private func store(_ id: String, _ module: String, _ method: String, _ args: [Any]) {
         switch module {
         case "SecureStorage":

package/dist/updater/index.d.ts

@@ -87,6 +87,19 @@ export interface UpdaterConfig {
      */
     relaunch?: (appPath: string) => void | Promise<void>;
 }
+/** Background policy; the host keeps preferences in its own native model. */
+export interface AutoCheckOptions {
+    enabled?: () => boolean | Promise<boolean>;
+    /** Delay the first check without delaying manual checks. Defaults to zero. */
+    initialDelay?: number;
+    /** How often to re-read enabled while a check is not due. Defaults to a minute. */
+    policyInterval?: number;
+    /** Download in the background, independently of manual check behavior. */
+    autoDownload?: boolean;
+}
+export interface CheckForUpdatesOptions {
+    autoDownload?: boolean;
+}
 export interface UpdateProgress {
     phase: 'checking' | 'downloading' | 'extracting' | 'installing' | 'done' | 'error';
     percent: number;
@@ -99,7 +112,12 @@ export declare class AutoUpdater extends EventEmitter {
     private config;
     private updateInfo;
     private downloadPath;
+    private verifiedDownloadPath;
     private checkTimer;
+    private autoCheckGeneration;
+    private autoCheckRunning;
+    private checking;
+    private downloading;
     private cachedEtag;
     private cachedLastModified;
     private cachedManifest;
@@ -128,22 +146,18 @@ export declare class AutoUpdater extends EventEmitter {
      */
     getLastError(): Error | null;
     constructor(config: UpdaterConfig);
-    /**
-     * Start automatic update checking
-     */
-    startAutoCheck(): void;
-    /**
-     * Stop automatic update checking
-     */
+    /** Start one background lifecycle. Repeated starts are idempotent. Never installs by default. */
+    startAutoCheck(options?: AutoCheckOptions): void;
+    /** Stop timers and invalidate policy reads already in flight. Downloads already started may finish. */
     stopAutoCheck(): void;
-    /**
-     * Check for available updates
-     */
-    checkForUpdates(): Promise<UpdateInfo | null>;
+    /** Concurrent manual and background callers share one manifest request. */
+    checkForUpdates(options?: CheckForUpdatesOptions): Promise<UpdateInfo | null>;
+    private performCheck;
     /**
      * Download the update
      */
     downloadUpdate(): Promise<string | null>;
+    private performDownload;
     /**
      * Install the downloaded update.
      *

package/package.json

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