craft-native 0.0.442 → 0.0.446

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/android/src/index.d.ts

@@ -122,6 +122,18 @@ export interface CraftAndroidConfig {
     }>;
     trustedOrigins?: string[];
     appIconPath?: string;
+    /**
+     * The launch splash: a directory laid out as Android resources, holding
+     * `drawable-<density>/splash_icon.png` (Android 12's splash icon, 288dp
+     * with its content inside the 192dp circle) and `splash_logo.png` (the
+     * logo the window background centres before Android 12), with Dark Mode
+     * ones in `drawable-night-<density>`. ts-images' `generateSplashScreens`
+     * writes exactly this (`android.resources`). Both sit on `backgroundColor`
+     * (`backgroundColorDark` at night), the colour the first frame continues.
+     * Without it, Android 12 shows the launcher icon and older versions the
+     * background colour.
+     */
+    splashResources?: string;
     /**
      * The small icon in the status bar and on every notification the app
      * shows, push or local: an Android vector drawable (`.xml`) or a `.png`,
@@ -268,6 +280,30 @@ export interface RunOptions {
     device?: string;
     output: string;
 }
+/** A splash file, by its place under `res/` (`drawable-night-xxhdpi/splash_icon.png`). */
+export interface AndroidSplashFile {
+    folder: string;
+    name: 'splash_icon.png' | 'splash_logo.png';
+    path: string;
+}
+/**
+ * The splash files in a resources directory: `splash_icon.png` and
+ * `splash_logo.png` in each `drawable[-night][-<density>]` folder. A directory
+ * with neither is a mistake, not an app without a splash.
+ */
+export declare function androidSplashFiles(resources: string): AndroidSplashFile[];
+/**
+ * The launch theme the activity starts in, and the theme it swaps to before
+ * its first frame. Android 12 and later draw their splash from
+ * `windowSplashScreen*`; earlier versions draw the window background, here
+ * the logo centred on the background colour. Either way the colour is the
+ * app's own `background`, so nothing flashes when the first frame replaces it.
+ */
+export declare function androidLaunchThemes(splash: Pick<AndroidSplashFile, 'name'>[]): {
+    base: string;
+    v31: string;
+    background?: string;
+};
 export declare function syncAndroidWebAssets(source: string, output: string): void;
 export declare function renderAndroidPermissions(config: CraftAndroidConfig): string;
 export declare function renderAndroidDeepLinks(config: CraftAndroidConfig): string;

package/dist/android/src/index.js

@@ -757,6 +757,49 @@ function requireRegularFile(path, label) {
   if (!statSync(path).isFile())
     throw new Error(`${label} must be a file: ${path}`);
 }
+function androidSplashFiles(resources) {
+  if (!existsSync(resources) || !statSync(resources).isDirectory())
+    throw new Error(`Splash resources must be a directory: ${resources}`);
+  const files = [];
+  for (const folder of readdirSync(resources).sort()) {
+    if (!/^drawable(?:-night)?(?:-(?:l|m|tv|h|xh|xxh|xxxh)dpi)?$/.test(folder))
+      continue;
+    for (const name of ["splash_icon.png", "splash_logo.png"]) {
+      const path = join3(resources, folder, name);
+      if (existsSync(path) && statSync(path).isFile())
+        files.push({ folder, name, path });
+    }
+  }
+  if (!files.length)
+    throw new Error(`Splash resources hold no drawable*/splash_icon.png or splash_logo.png: ${resources}`);
+  return files;
+}
+function androidLaunchThemes(splash) {
+  const icon = splash.some((file) => file.name === "splash_icon.png");
+  const logo = splash.some((file) => file.name === "splash_logo.png");
+  const base = logo ? `    <style name="Theme.CraftApp.Launch" parent="Theme.CraftApp">
+        <item name="android:windowBackground">@drawable/craft_launch_background</item>
+    </style>
+` : `    <style name="Theme.CraftApp.Launch" parent="Theme.CraftApp" />
+`;
+  const v31 = `<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <style name="Theme.CraftApp.Launch" parent="Theme.CraftApp">
+        <item name="android:windowSplashScreenBackground">@color/background</item>${icon ? `
+        <item name="android:windowSplashScreenAnimatedIcon">@drawable/splash_icon</item>` : ""}
+    </style>
+</resources>
+`;
+  const background = logo ? `<?xml version="1.0" encoding="utf-8"?>
+<layer-list xmlns:android="http://schemas.android.com/apk/res/android" android:opacity="opaque">
+    <item android:drawable="@color/background" />
+    <item>
+        <bitmap android:gravity="center" android:src="@drawable/splash_logo" />
+    </item>
+</layer-list>
+` : undefined;
+  return { base, v31, background };
+}
 function containsPath(parent, candidate) {
   const relativePath = relative(parent, candidate);
   return relativePath === "" || relativePath !== ".." && !relativePath.startsWith(`..${sep}`) && !isAbsolute2(relativePath);
@@ -964,6 +1007,7 @@ function writeAndroidConfig(output, config) {
   writeFileSync(join3(output, "craft.config.json"), JSON.stringify(config, null, 2));
   const runtimeConfig = { ...config };
   delete runtimeConfig.appIconPath;
+  delete runtimeConfig.splashResources;
   delete runtimeConfig.notificationIconPath;
   delete runtimeConfig.googleServicesFile;
   writeFileSync(join3(output, "app/src/main/assets/craft.config.json"), JSON.stringify(runtimeConfig, null, 2));
@@ -1266,6 +1310,7 @@ async function init(options) {
   if (config.appIconPath && ![".gif", ".jpg", ".png", ".webp"].includes(appIconExtension ?? "")) {
     throw new Error(`Unsupported Android app icon format: ${appIconExtension || "(none)"}`);
   }
+  const splash = config.splashResources ? androidSplashFiles(config.splashResources) : [];
   if (config.notificationIconPath)
     requireRegularFile(config.notificationIconPath, "Notification icon");
   const notificationIconExtension = config.notificationIconPath ? extname(config.notificationIconPath).toLowerCase() : undefined;
@@ -1475,6 +1520,17 @@ zipStorePath=wrapper/dists
 </vector>
 `);
   }
+  const resDir = join3(output, "app/src/main/res");
+  for (const folder of existsSync(resDir) ? readdirSync(resDir) : []) {
+    if (folder.startsWith("drawable"))
+      for (const name of ["splash_icon.png", "splash_logo.png"])
+        rmSync2(join3(resDir, folder, name), { force: true });
+  }
+  for (const file of splash) {
+    mkdirSync2(join3(resDir, file.folder), { recursive: true });
+    cpSync(file.path, join3(resDir, file.folder, file.name));
+  }
+  const launch = androidLaunchThemes(splash);
   const themesXml = `<?xml version="1.0" encoding="utf-8"?>
 <resources>
     <style name="Theme.CraftApp" parent="Theme.Material3.DayNight.NoActionBar">
@@ -1482,9 +1538,15 @@ zipStorePath=wrapper/dists
         <item name="android:navigationBarColor">@color/primary</item>
         <item name="android:windowBackground">@color/background</item>
     </style>
-</resources>
+${launch.base}</resources>
 `;
   writeFileSync(join3(output, "app/src/main/res/values/themes.xml"), themesXml);
+  mkdirSync2(join3(output, "app/src/main/res/values-v31"), { recursive: true });
+  writeFileSync(join3(output, "app/src/main/res/values-v31/themes.xml"), launch.v31);
+  if (launch.background)
+    writeFileSync(join3(output, "app/src/main/res/drawable/craft_launch_background.xml"), launch.background);
+  else
+    rmSync2(join3(output, "app/src/main/res/drawable/craft_launch_background.xml"), { force: true });
   const activityMainXml = config.renderer === "native" ? `<?xml version="1.0" encoding="utf-8"?>
 <FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
     android:id="@+id/native_root"
@@ -1708,6 +1770,8 @@ async function run(options) {
 export {
   ANDROID_MIN_SDK,
   HEALTH_CONNECT_PERMISSIONS,
+  androidLaunchThemes,
+  androidSplashFiles,
   build,
   compressNativeSources,
   createAndroidEmulator,

package/dist/android/templates/AndroidManifest.xml.template

@@ -45,7 +45,8 @@
             android:windowSoftInputMode="adjustResize"
             android:supportsPictureInPicture="true"
             android:resizeableActivity="true"
-            android:launchMode="singleTask">
+            android:launchMode="singleTask"
+            android:theme="@style/Theme.CraftApp.Launch">
             <intent-filter>
                 <action android:name="android.intent.action.MAIN" />
                 <category android:name="android.intent.category.LAUNCHER" />

package/dist/android/templates/MainActivity.kt.template

@@ -76,6 +76,9 @@ class MainActivity : AppCompatActivity() {
 
     @SuppressLint("SetJavaScriptEnabled")
     override fun onCreate(savedInstanceState: Bundle?) {
+        // The activity starts in the launch theme (the splash); its own theme
+        // takes over before the first frame, on the same background colour.
+        setTheme(R.style.Theme_CraftApp)
         applyConfiguredAppearance()
         super.onCreate(savedInstanceState)
 

package/dist/android/templates/MainActivityNative.kt.template

@@ -4738,6 +4738,9 @@ class MainActivity : AppCompatActivity() {
     }
 
     override fun onCreate(savedInstanceState: Bundle?) {
+        // The activity starts in the launch theme (the splash); its own theme
+        // takes over before the first frame, on the same background colour.
+        setTheme(R.style.Theme_CraftApp)
         applyConfiguredAppearance()
         super.onCreate(savedInstanceState)
         onBackPressedDispatcher.addCallback(this, object : OnBackPressedCallback(true) {

package/dist/cli.js

@@ -3228,7 +3228,7 @@ function pinCraftNativeDependency(packagePath, craftVersion) {
 `);
 }
 // package.json
-var version = "0.0.442";
+var version = "0.0.446";
 
 // 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.442";
+var version = "0.0.446";
 
 // 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.442";
+var version = "0.0.446";
 
 // 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/src/index.d.ts

@@ -208,7 +208,9 @@ export interface CraftConfig {
      * screen until the page says it is ready (`splash.hide()`), so the app goes
      * from launch to content without a blank web view in between. PNG, PDF or
      * SVG, drawn at its own size in points: give an SVG the width and height it
-     * should have on screen.
+     * should have on screen. A PNG with `@2x` and `@3x` files beside it
+     * (`LaunchLogo.png`, `LaunchLogo@2x.png`, `LaunchLogo@3x.png`, as ts-images'
+     * `generateSplashScreens` writes them) is sharp on every screen.
      */
     splashImagePath?: string;
     /** The splash logo in Dark Mode, on `backgroundColorDark`. The light one if unset. */
@@ -532,6 +534,16 @@ export declare function renderPrivacyManifest(config: CraftConfig): string;
 export declare function pngHasAlpha(bytes: Uint8Array): boolean;
 /** The asset the launch screen and the splash both draw, so one hands over to the other unseen. */
 export declare const LAUNCH_LOGO = "LaunchLogo";
+/**
+ * A bitmap splash's `@2x` and `@3x` files beside it (`LaunchLogo.png`,
+ * `LaunchLogo@2x.png`, `LaunchLogo@3x.png`, as ts-images'
+ * `generateSplashScreens` writes them), by scale. A bitmap without them is
+ * one image, drawn at its pixel size in points.
+ */
+export declare function splashScales(source: string): Array<{
+    scale: 1 | 2 | 3;
+    path: string;
+}>;
 /** The launch screen: the background colour, and the splash logo on it when there is one. */
 export declare function renderLaunchScreen(config: Pick<CraftConfig, 'splashImagePath'>): string;
 /** Near-black or near-white, whichever reads on `background` (WCAG relative luminance). */

package/dist/ios/src/index.js

@@ -1107,6 +1107,14 @@ function renderAssetCatalog(output, config) {
   renderLaunchLogo(catalog, config);
 }
 var LAUNCH_LOGO = "LaunchLogo";
+function splashScales(source) {
+  const extension = extname(source);
+  if (!/^\.(?:png|jpe?g)$/i.test(extension))
+    return [{ scale: 1, path: source }];
+  const stem = source.slice(0, -extension.length);
+  const scales = [2, 3].map((scale) => ({ scale, path: `${stem}@${scale}x${extension}` })).filter((item) => existsSync2(item.path));
+  return scales.length ? [{ scale: 1, path: source }, ...scales] : [{ scale: 1, path: source }];
+}
 function renderLaunchLogo(catalog, config) {
   const imageset = join4(catalog, `${LAUNCH_LOGO}.imageset`);
   rmSync3(imageset, { recursive: true, force: true });
@@ -1123,13 +1131,18 @@ function renderLaunchLogo(catalog, config) {
     const extension = source.split(".").pop().toLowerCase();
     if (extension === "svg" || extension === "pdf")
       vector = true;
-    const filename = `${LAUNCH_LOGO}${dark ? "-dark" : ""}.${extension}`;
-    cpSync(source, join4(imageset, filename));
-    images.push({
-      ...dark ? { appearances: [{ appearance: "luminosity", value: "dark" }] } : {},
-      filename,
-      idiom: "universal"
-    });
+    const files = splashScales(source);
+    const scaled = files.length > 1;
+    for (const { scale, path } of files) {
+      const filename = `${LAUNCH_LOGO}${dark ? "-dark" : ""}${scale === 1 ? "" : `@${scale}x`}.${extension}`;
+      cpSync(path, join4(imageset, filename));
+      images.push({
+        ...dark ? { appearances: [{ appearance: "luminosity", value: "dark" }] } : {},
+        filename,
+        idiom: "universal",
+        ...scaled ? { scale: `${scale}x` } : {}
+      });
+    }
   }
   writeFileSync3(join4(imageset, "Contents.json"), `${JSON.stringify({
     images,
@@ -1841,6 +1854,7 @@ export {
   runPostGenerateHook,
   serializeSimulatorSteps,
   showSimulator,
+  splashScales,
   syncNativeFonts,
   syncWebAssets,
   usesNativeBundle

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/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?
@@ -175,7 +179,13 @@ final class CraftMacRuntime {
             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 +215,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 +236,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 +338,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 +371,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 +439,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 +468,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.442",
+  "version": "0.0.446",
   "type": "module",
   "description": "Build desktop apps with web languages - TypeScript SDK for Craft",
   "author": "Chris Breuer <chris@stacksjs.org>",