craft-native 0.0.154 → 0.0.155

package/dist/cli.js

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

package/dist/index.cjs

@@ -310,7 +310,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.154";
+var version = "0.0.155";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;

package/dist/index.js

@@ -58,7 +58,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.154";
+var version = "0.0.155";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;

package/dist/ios/src/index.d.ts

@@ -412,6 +412,8 @@ export declare function installRuntime(output: string, runtimeDir: string): Prom
  * valid Swift type.
  */
 export declare function productName(name: string): string;
+/** Restore package-owned Swift into an existing project, without changing its Xcode metadata or bundled screens. */
+export declare function restoreShell(output: string): void;
 export declare function init(options: InitOptions): Promise<void>;
 /**
  * Build web assets and generate Xcode project
@@ -475,3 +477,5 @@ export declare function bootSimulator(device: SimulatorDevice): Promise<void>;
  */
 export declare function showSimulator(): Promise<void>;
 export declare function run(options: RunOptions): Promise<void>;
+export { createNativeMutationValidator, initSimulatorDriver, serializeSimulatorSteps } from './testing.js';
+export type { NativeMutationValidator, NativeValidationResult, SimulatorDriverOptions, SimulatorStep } from './testing.js';

package/dist/ios/src/index.js

@@ -1,12 +1,149 @@
 // @bun
 // ../ios/src/index.ts
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "fs";
-import { dirname, join, resolve } from "path";
+import { cpSync, existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync2, readdirSync, rmSync as rmSync2, statSync, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2, join as join2, resolve } from "path";
 var {$ } = globalThis.Bun;
-var TEMPLATES_DIR = join(dirname(import.meta.dir), "templates");
+
+// ../ios/src/testing.ts
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { dirname, join } from "path";
+import { spawnSync } from "child_process";
+var templates = join(dirname(import.meta.dir), "templates/testing");
+function bundleIdentifier(value) {
+  if (!/^[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+$/.test(value))
+    throw new Error(`Invalid bundle identifier: ${value}`);
+}
+function swiftString(value) {
+  return JSON.stringify(value).replace(/\\u([a-f\d]{4})/gi, "\\u{$1}");
+}
+function initSimulatorDriver(options) {
+  const { output, bundleId } = options;
+  const name = options.projectName ?? "CraftDriver";
+  const prefix = options.bundleIdPrefix ?? `${bundleId}.driver`;
+  const version = options.deploymentTarget ?? "17.0";
+  const control = options.controlUrl ?? "http://127.0.0.1:3401";
+  bundleIdentifier(bundleId);
+  bundleIdentifier(prefix);
+  if (!/^[A-Za-z][A-Za-z0-9]*$/.test(name))
+    throw new Error("projectName must be an alphanumeric Xcode name starting with a letter");
+  if (!/^\d+\.\d+$/.test(version) || Number(version) < 17)
+    throw new Error("The simulator driver requires iOS 17.0 or newer");
+  if (!["http:", "https:"].includes(new URL(control).protocol))
+    throw new Error("controlUrl must use HTTP or HTTPS");
+  const replacements = {
+    PROJECT_NAME: name,
+    BUNDLE_PREFIX: prefix,
+    IOS_VERSION: version,
+    BUNDLE_ID: swiftString(bundleId),
+    CONTROL_URL: swiftString(control),
+    TABS: `[${(options.tabs ?? []).map(swiftString).join(", ")}]`
+  };
+  for (const [source, destination] of [
+    ["HostApp.swift", "Host/HostApp.swift"],
+    ["DriverTests.swift.template", "UITests/DriverTests.swift"],
+    ["project.yml.template", "project.yml"]
+  ]) {
+    const path = join(output, destination);
+    mkdirSync(dirname(path), { recursive: true });
+    const content = readFileSync(join(templates, source), "utf8").replace(/\{\{([A-Z_]+)\}\}/g, (_, key) => replacements[key]);
+    let previous;
+    try {
+      previous = readFileSync(path, "utf8");
+    } catch {}
+    if (previous !== content)
+      writeFileSync(path, content);
+  }
+}
+function serializeSimulatorSteps(steps) {
+  const number = (value) => {
+    if (!Number.isFinite(value) || value < 0)
+      throw new Error("Simulator values must be finite and nonnegative");
+    return value;
+  };
+  const token = (value) => {
+    if (!value || /\s/.test(value))
+      throw new Error("Simulator identifiers must be nonempty single tokens");
+    return value;
+  };
+  return steps.map((step) => {
+    let arg = "";
+    if ("seconds" in step && !("text" in step))
+      arg = String(number(step.seconds));
+    else if ("milliseconds" in step)
+      arg = String(number(step.milliseconds));
+    else if ("state" in step)
+      arg = step.state;
+    else if ("direction" in step)
+      arg = step.direction;
+    else if ("x" in step) {
+      if (number(step.x) > 1 || number(step.y) > 1)
+        throw new Error("tapxy coordinates must be between 0 and 1");
+      arg = `${step.x} ${step.y}`;
+    } else if ("index" in step) {
+      if (!Number.isInteger(number(step.index)))
+        throw new Error("field index must be an integer");
+      arg = `${step.index} ${step.text}`;
+    } else if ("id" in step)
+      arg = `${token(step.id)} ${step.text}`;
+    else if ("text" in step) {
+      arg = step.text;
+      if ("seconds" in step && step.seconds !== undefined) {
+        if (arg.includes("|"))
+          throw new Error("A timed expectation cannot contain |");
+        arg += ` | ${number(step.seconds)}`;
+      }
+    } else if ("name" in step)
+      arg = token(step.name);
+    else if ("url" in step)
+      arg = step.url;
+    if (/[\r\n]/.test(arg))
+      throw new Error("Simulator arguments cannot contain newlines");
+    return `${step.command}${arg ? ` ${arg}` : ""}`;
+  }).join(`
+`) + `
+`;
+}
+function createNativeMutationValidator() {
+  const output = mkdtempSync(join(tmpdir(), "craft-native-mutation-"));
+  const binary = join(output, "validate");
+  try {
+    writeFileSync(join(output, "main.swift"), readFileSync(join(templates, "MutationValidator.swift")));
+    const build = Bun.spawnSync(["swiftc", join(templates, "../CraftNativeMutation.swift"), join(output, "main.swift"), "-o", binary]);
+    if (build.exitCode !== 0)
+      throw new Error(build.stderr.toString());
+  } catch (error) {
+    rmSync(output, { recursive: true, force: true });
+    throw error;
+  }
+  let disposed = false;
+  return {
+    validate(messages) {
+      if (disposed)
+        throw new Error("The native mutation validator has been disposed");
+      const input = join(output, "messages.json");
+      writeFileSync(input, JSON.stringify(messages));
+      const report = join(output, "result.txt");
+      rmSync(report, { force: true });
+      const result = spawnSync(binary, [input, report], { encoding: "utf8" });
+      let stdout = result.stdout ?? "";
+      try {
+        stdout = readFileSync(report, "utf8");
+      } catch {}
+      return { exitCode: result.status ?? 1, stdout, stderr: result.stderr || result.error?.message || (result.signal ? `Validator terminated by ${result.signal}` : "") };
+    },
+    dispose() {
+      disposed = true;
+      rmSync(output, { recursive: true, force: true });
+    }
+  };
+}
+
+// ../ios/src/index.ts
+var TEMPLATES_DIR = join2(dirname2(import.meta.dir), "templates");
 var CRAFT_VERSION = (() => {
   try {
-    return JSON.parse(readFileSync(join(dirname(import.meta.dir), "package.json"), "utf8")).version ?? "0.0.0";
+    return JSON.parse(readFileSync2(join2(dirname2(import.meta.dir), "package.json"), "utf8")).version ?? "0.0.0";
   } catch {
     return "0.0.0";
   }
@@ -122,8 +259,8 @@ function hybridConfigProblems(config) {
 function installNativeBundle(source, output) {
   if (!existsSync(source))
     throw new Error(`Native bundle not found: ${source}`);
-  const destination = join(output, "dist", "native-screen.js");
-  mkdirSync(dirname(destination), { recursive: true });
+  const destination = join2(output, "dist", "native-screen.js");
+  mkdirSync2(dirname2(destination), { recursive: true });
   if (resolve(source) !== resolve(destination))
     cpSync(source, destination);
 }
@@ -471,7 +608,7 @@ function pngHasAlpha(bytes) {
   return false;
 }
 function writeOpaqueIcon(source, target) {
-  const bytes = new Uint8Array(readFileSync(source));
+  const bytes = new Uint8Array(readFileSync2(source));
   if (!pngHasAlpha(bytes) || process.platform !== "darwin") {
     cpSync(source, target);
     return;
@@ -480,27 +617,27 @@ function writeOpaqueIcon(source, target) {
   const run = (args) => Bun.spawnSync(["sips", ...args], { stdout: "ignore", stderr: "pipe" });
   const toJpeg = run(["-s", "format", "jpeg", "-s", "formatOptions", "100", source, "--out", flattened]);
   const toPng = toJpeg.exitCode === 0 ? run(["-s", "format", "png", flattened, "--out", target]) : toJpeg;
-  rmSync(flattened, { force: true });
+  rmSync2(flattened, { force: true });
   if (toPng.exitCode !== 0) {
     cpSync(source, target);
     console.warn(`[craft] Could not remove the app icon's alpha channel; App Store Connect will refuse it: ${toPng.stderr.toString().trim()}`);
   }
 }
 function renderAssetCatalog(output, config) {
-  const catalog = join(output, "Assets.xcassets");
-  const appIcon = join(catalog, "AppIcon.appiconset");
-  const launchBackground = join(catalog, "LaunchBackground.colorset");
-  mkdirSync(appIcon, { recursive: true });
-  mkdirSync(launchBackground, { recursive: true });
-  writeFileSync(join(catalog, "Contents.json"), `${JSON.stringify({ info: { author: "xcode", version: 1 } }, null, 2)}
+  const catalog = join2(output, "Assets.xcassets");
+  const appIcon = join2(catalog, "AppIcon.appiconset");
+  const launchBackground = join2(catalog, "LaunchBackground.colorset");
+  mkdirSync2(appIcon, { recursive: true });
+  mkdirSync2(launchBackground, { recursive: true });
+  writeFileSync2(join2(catalog, "Contents.json"), `${JSON.stringify({ info: { author: "xcode", version: 1 } }, null, 2)}
 `);
   const iconFilename = config.appIconPath ? "AppIcon-1024.png" : undefined;
   if (config.appIconPath) {
     if (!existsSync(config.appIconPath))
       throw new Error(`App icon not found: ${config.appIconPath}`);
-    writeOpaqueIcon(config.appIconPath, join(appIcon, iconFilename));
+    writeOpaqueIcon(config.appIconPath, join2(appIcon, iconFilename));
   }
-  writeFileSync(join(appIcon, "Contents.json"), `${JSON.stringify({
+  writeFileSync2(join2(appIcon, "Contents.json"), `${JSON.stringify({
     images: iconFilename ? [{
       filename: iconFilename,
       idiom: "universal",
@@ -527,7 +664,7 @@ function renderAssetCatalog(output, config) {
       idiom: "universal"
     });
   }
-  writeFileSync(join(launchBackground, "Contents.json"), `${JSON.stringify({
+  writeFileSync2(join2(launchBackground, "Contents.json"), `${JSON.stringify({
     colors,
     info: { author: "xcode", version: 1 }
   }, null, 2)}
@@ -536,11 +673,11 @@ function renderAssetCatalog(output, config) {
 }
 var LAUNCH_LOGO = "LaunchLogo";
 function renderLaunchLogo(catalog, config) {
-  const imageset = join(catalog, `${LAUNCH_LOGO}.imageset`);
-  rmSync(imageset, { recursive: true, force: true });
+  const imageset = join2(catalog, `${LAUNCH_LOGO}.imageset`);
+  rmSync2(imageset, { recursive: true, force: true });
   if (!config.splashImagePath)
     return;
-  mkdirSync(imageset, { recursive: true });
+  mkdirSync2(imageset, { recursive: true });
   const images = [];
   let vector = false;
   for (const [source, dark] of [[config.splashImagePath, false], [config.splashImagePathDark, true]]) {
@@ -552,14 +689,14 @@ function renderLaunchLogo(catalog, config) {
     if (extension === "svg" || extension === "pdf")
       vector = true;
     const filename = `${LAUNCH_LOGO}${dark ? "-dark" : ""}.${extension}`;
-    cpSync(source, join(imageset, filename));
+    cpSync(source, join2(imageset, filename));
     images.push({
       ...dark ? { appearances: [{ appearance: "luminosity", value: "dark" }] } : {},
       filename,
       idiom: "universal"
     });
   }
-  writeFileSync(join(imageset, "Contents.json"), `${JSON.stringify({
+  writeFileSync2(join2(imageset, "Contents.json"), `${JSON.stringify({
     images,
     info: { author: "xcode", version: 1 },
     ...vector ? { properties: { "preserves-vector-representation": true } } : {}
@@ -673,15 +810,15 @@ function syncWebAssets(source, output) {
   const sourcePath = resolve(source);
   if (!existsSync(sourcePath))
     throw new Error(`Web asset path not found: ${source}`);
-  const distDir = join(output, "dist");
-  rmSync(distDir, { recursive: true, force: true });
-  mkdirSync(distDir, { recursive: true });
+  const distDir = join2(output, "dist");
+  rmSync2(distDir, { recursive: true, force: true });
+  mkdirSync2(distDir, { recursive: true });
   if (statSync(sourcePath).isDirectory()) {
     cpSync(sourcePath, distDir, { recursive: true });
   } else {
-    cpSync(sourcePath, join(distDir, "index.html"));
+    cpSync(sourcePath, join2(distDir, "index.html"));
   }
-  if (!existsSync(join(distDir, "index.html"))) {
+  if (!existsSync(join2(distDir, "index.html"))) {
     throw new Error(`Web asset directory must contain index.html: ${source}`);
   }
 }
@@ -703,32 +840,32 @@ var RUNTIME_ARCHIVES = {
 };
 async function installRuntime(output, runtimeDir) {
   const resolved = Object.entries(RUNTIME_ARCHIVES).map(([sdk, archives]) => {
-    const present = archives.filter((a) => existsSync(join(runtimeDir, a)));
+    const present = archives.filter((a) => existsSync(join2(runtimeDir, a)));
     if (present.length === 0) {
       throw new Error(`${runtimeDir} has none of ${archives.join(", ")}. ` + `Run \`zig build build-ios-all\` in packages/zig and point at its zig-out/lib.`);
     }
     return { sdk, archives, present };
   });
-  const dest = join(output, "Runtime");
-  rmSync(dest, { recursive: true, force: true });
+  const dest = join2(output, "Runtime");
+  rmSync2(dest, { recursive: true, force: true });
   for (const { sdk, archives, present } of resolved) {
-    const sdkDir = join(dest, sdk);
-    mkdirSync(sdkDir, { recursive: true });
-    const target = join(sdkDir, "libcraft-ios.a");
+    const sdkDir = join2(dest, sdk);
+    mkdirSync2(sdkDir, { recursive: true });
+    const target = join2(sdkDir, "libcraft-ios.a");
     if (present.length === 1) {
       const missing = archives.filter((a) => !present.includes(a));
       if (missing.length > 0) {
         console.warn(`   \u26A0 ${sdk}: only ${present[0]} was found; ${missing.join(", ")} is missing. ` + `The generated project will not link on the other architecture.`);
       }
-      cpSync(join(runtimeDir, present[0]), target);
+      cpSync(join2(runtimeDir, present[0]), target);
     } else {
-      await $`lipo -create ${present.map((a) => join(runtimeDir, a))} -output ${target}`.quiet();
+      await $`lipo -create ${present.map((a) => join2(runtimeDir, a))} -output ${target}`.quiet();
     }
   }
   return true;
 }
 async function refreshRuntime(output, override) {
-  if (!existsSync(join(output, "Runtime")))
+  if (!existsSync(join2(output, "Runtime")))
     return;
   const dir = resolveRuntimeDir(override);
   if (!dir) {
@@ -745,6 +882,43 @@ function productName(name) {
     return "Craft";
   return /^\d/.test(joined) ? `App${joined}` : joined;
 }
+function restoreShell(output) {
+  const config = JSON.parse(readFileSync2(join2(output, "craft.config.json"), "utf8"));
+  writeShell(output, config);
+}
+function writeShell(output, config) {
+  if (!config.appName || !/^[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+$/.test(config.bundleId))
+    throw new Error("The iOS shell needs an appName and a valid bundleId in craft.config.json.");
+  const name = productName(config.appName);
+  mkdirSync2(join2(output, "Sources"), { recursive: true });
+  mkdirSync2(join2(output, "Shared"), { recursive: true });
+  const swiftTemplate = readFileSync2(join2(TEMPLATES_DIR, "CraftApp.swift"), "utf-8");
+  const swiftSource = swiftTemplate.replace(/CraftApp/g, `${name}App`).replace(/\{\{BUNDLE_ID\}\}/g, config.bundleId).replace(/\{\{CRAFT_VERSION\}\}/g, CRAFT_VERSION);
+  writeFileSync2(join2(output, "Sources", `${name}App.swift`), swiftSource);
+  cpSync(join2(TEMPLATES_DIR, "CraftNativeScreen.swift"), join2(output, "Sources", "CraftNativeScreen.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftNativeFlatList.swift"), join2(output, "Sources", "CraftNativeFlatList.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftNativeActions.swift"), join2(output, "Sources", "CraftNativeActions.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftHealth.swift"), join2(output, "Sources", "CraftHealth.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftMusic.swift"), join2(output, "Sources", "CraftMusic.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftHeartRate.swift"), join2(output, "Sources", "CraftHeartRate.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftNativeMutation.swift"), join2(output, "Sources", "CraftNativeMutation.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftNativeUI.swift"), join2(output, "Sources", "CraftNativeUI.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftNativeServices.swift"), join2(output, "Sources", "CraftNativeServices.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftNativeFiles.swift"), join2(output, "Sources", "CraftNativeFiles.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftWebAudio.swift"), join2(output, "Sources", "CraftWebAudio.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftHybrid.swift"), join2(output, "Sources", "CraftHybrid.swift"));
+  cpSync(join2(TEMPLATES_DIR, "CraftActivityAttributes.swift"), join2(output, "Shared", "CraftActivityAttributes.swift"));
+  for (const [enabled, folder, template, filename] of [
+    [config.enableLiveActivities, "WidgetExtension", "CraftLiveActivityWidget.swift.template", `${name}LiveActivity.swift`],
+    [config.enableWatchApp, "WatchExtension", "CraftWatchApp.swift.template", `${name}WatchApp.swift`]
+  ]) {
+    if (!enabled)
+      continue;
+    mkdirSync2(join2(output, folder), { recursive: true });
+    const source = readFileSync2(join2(TEMPLATES_DIR, template), "utf8").replace(/\{\{APP_NAME\}\}/g, name);
+    writeFileSync2(join2(output, folder, filename), source);
+  }
+}
 async function init(options) {
   const { name: displayName, bundleId, teamId, output } = options;
   const name = productName(displayName);
@@ -752,12 +926,12 @@ async function init(options) {
 \u26A1 Initializing Craft iOS project: ${displayName}`);
   console.log(`   Output: ${output}
 `);
-  const dirs = [output, join(output, "Sources"), join(output, "Shared"), join(output, "dist")];
+  const dirs = [output, join2(output, "Sources"), join2(output, "Shared"), join2(output, "dist")];
   if (options.config?.enableWatchApp)
-    dirs.push(join(output, "WatchApp"), join(output, "WatchExtension"));
+    dirs.push(join2(output, "WatchApp"), join2(output, "WatchExtension"));
   for (const dir of dirs) {
     if (!existsSync(dir)) {
-      mkdirSync(dir, { recursive: true });
+      mkdirSync2(dir, { recursive: true });
     }
   }
   const finalBundleId = bundleId || `com.craft.${name.toLowerCase()}`;
@@ -781,29 +955,15 @@ async function init(options) {
 `));
   if (Object.keys(config.shareStorage ?? {}).length)
     config.enableSecureStorage = true;
-  writeFileSync(join(output, "craft.config.json"), JSON.stringify(config, null, 2));
-  const swiftTemplate = readFileSync(join(TEMPLATES_DIR, "CraftApp.swift"), "utf-8");
-  const swiftSource = swiftTemplate.replace(/CraftApp/g, `${name}App`).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId).replace(/\{\{CRAFT_VERSION\}\}/g, CRAFT_VERSION);
-  writeFileSync(join(output, "Sources", `${name}App.swift`), swiftSource);
-  cpSync(join(TEMPLATES_DIR, "CraftNativeScreen.swift"), join(output, "Sources", "CraftNativeScreen.swift"));
-  cpSync(join(TEMPLATES_DIR, "CraftNativeFlatList.swift"), join(output, "Sources", "CraftNativeFlatList.swift"));
-  cpSync(join(TEMPLATES_DIR, "CraftNativeActions.swift"), join(output, "Sources", "CraftNativeActions.swift"));
-  cpSync(join(TEMPLATES_DIR, "CraftHealth.swift"), join(output, "Sources", "CraftHealth.swift"));
-  cpSync(join(TEMPLATES_DIR, "CraftMusic.swift"), join(output, "Sources", "CraftMusic.swift"));
-  cpSync(join(TEMPLATES_DIR, "CraftHeartRate.swift"), join(output, "Sources", "CraftHeartRate.swift"));
-  cpSync(join(TEMPLATES_DIR, "CraftNativeMutation.swift"), join(output, "Sources", "CraftNativeMutation.swift"));
-  cpSync(join(TEMPLATES_DIR, "CraftNativeUI.swift"), join(output, "Sources", "CraftNativeUI.swift"));
-  cpSync(join(TEMPLATES_DIR, "CraftNativeServices.swift"), join(output, "Sources", "CraftNativeServices.swift"));
-  cpSync(join(TEMPLATES_DIR, "CraftNativeFiles.swift"), join(output, "Sources", "CraftNativeFiles.swift"));
-  cpSync(join(TEMPLATES_DIR, "CraftWebAudio.swift"), join(output, "Sources", "CraftWebAudio.swift"));
-  cpSync(join(TEMPLATES_DIR, "CraftHybrid.swift"), join(output, "Sources", "CraftHybrid.swift"));
-  const infoPlistTemplate = readFileSync(join(TEMPLATES_DIR, "Info.plist.template"), "utf-8");
+  writeFileSync2(join2(output, "craft.config.json"), JSON.stringify(config, null, 2));
+  writeShell(output, config);
+  const infoPlistTemplate = readFileSync2(join2(TEMPLATES_DIR, "Info.plist.template"), "utf-8");
   const infoPlist = infoPlistTemplate.replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId).replace(/\{\{VERSION\}\}/g, config.version || "1.0.0").replace(/\{\{BUILD_NUMBER\}\}/g, config.buildNumber || "1").replace(/\{\{UI_STYLE\}\}/g, renderAppearance(config).interfaceStyle).replace(/\{\{STATUS_BAR_STYLE\}\}/g, renderAppearance(config).statusBarStyle).replace(/\{\{ORIENTATIONS\}\}/g, renderOrientations(config)).replace(/\{\{USAGE_DESCRIPTIONS\}\}/g, renderUsageDescriptions(config)).replace(/\{\{URL_TYPES\}\}/g, renderUrlTypes(config)).replace(/\{\{APP_BOUND_DOMAINS\}\}/g, renderAppBoundDomains(config)).replace(/\{\{BACKGROUND_MODES\}\}/g, renderBackgroundModes(config)).replace(/\{\{BACKGROUND_TASK_IDENTIFIERS\}\}/g, renderBackgroundTaskIdentifiers(config)).replace(/\{\{LAUNCH_SCREEN\}\}/g, renderLaunchScreen(config)).replace(/\{\{NON_EXEMPT_ENCRYPTION\}\}/g, config.usesNonExemptEncryption ? "true" : "false").replace(/\{\{LIVE_ACTIVITY_SUPPORT\}\}/g, config.enableLiveActivities ? `    <key>NSSupportsLiveActivities</key>
     <true/>
     <key>NSSupportsLiveActivitiesFrequentUpdates</key>
     <true/>` : "");
-  writeFileSync(join(output, "Info.plist"), infoPlist);
-  const projectYmlTemplate = readFileSync(join(TEMPLATES_DIR, "project.yml.template"), "utf-8");
+  writeFileSync2(join2(output, "Info.plist"), infoPlist);
+  const projectYmlTemplate = readFileSync2(join2(TEMPLATES_DIR, "project.yml.template"), "utf-8");
   const nativeDependencies = [];
   if (config.enableLiveActivities)
     nativeDependencies.push(`      - target: ${name}LiveActivity`);
@@ -860,35 +1020,30 @@ async function init(options) {
   if (hasRuntime) {
     console.log("   Linked the Zig runtime from", runtimeDir);
   } else {
-    rmSync(join(output, "Runtime"), { recursive: true, force: true });
+    rmSync2(join2(output, "Runtime"), { recursive: true, force: true });
   }
   const projectYml = projectYmlTemplate.replace(/\{\{CRAFT_RUNTIME_SETTINGS\}\}/g, hasRuntime ? renderRuntimeSettings() : "").replace(/\{\{APP_NAME\}\}/g, name).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId).replace(/\{\{BUNDLE_ID_PREFIX\}\}/g, bundleIdPrefix).replace(/\{\{VERSION\}\}/g, config.version || "1.0.0").replace(/\{\{BUILD_NUMBER\}\}/g, config.buildNumber || "1").replace(/\{\{IOS_VERSION\}\}/g, config.iosVersion || "15.0").replace(/\{\{DEVICE_FAMILIES\}\}/g, renderDeviceFamilies(config)).replace(/\{\{TEAM_ID\}\}/g, teamId || "").replace(/\{\{NATIVE_DEPENDENCIES\}\}/g, nativeDependencies.length ? `    dependencies:
 ${nativeDependencies.join(`
 `)}` : "").replace(/\{\{NATIVE_TARGETS\}\}/g, nativeTargets.join(`
 `));
-  writeFileSync(join(output, "project.yml"), projectYml);
-  writeFileSync(join(output, "Craft.entitlements"), renderEntitlements(config));
-  writeFileSync(join(output, "PrivacyInfo.xcprivacy"), renderPrivacyManifest(config));
+  writeFileSync2(join2(output, "project.yml"), projectYml);
+  writeFileSync2(join2(output, "Craft.entitlements"), renderEntitlements(config));
+  writeFileSync2(join2(output, "PrivacyInfo.xcprivacy"), renderPrivacyManifest(config));
   renderAssetCatalog(output, config);
-  cpSync(join(TEMPLATES_DIR, "CraftActivityAttributes.swift"), join(output, "Shared", "CraftActivityAttributes.swift"));
   if (config.enableLiveActivities) {
-    mkdirSync(join(output, "WidgetExtension"), { recursive: true });
-    const widgetSource = readFileSync(join(TEMPLATES_DIR, "CraftLiveActivityWidget.swift.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, name);
-    writeFileSync(join(output, "WidgetExtension", `${name}LiveActivity.swift`), widgetSource);
-    const widgetInfo = readFileSync(join(TEMPLATES_DIR, "WidgetExtension.Info.plist"), "utf8");
-    writeFileSync(join(output, "WidgetExtension", "Info.plist"), widgetInfo);
+    mkdirSync2(join2(output, "WidgetExtension"), { recursive: true });
+    const widgetInfo = readFileSync2(join2(TEMPLATES_DIR, "WidgetExtension.Info.plist"), "utf8");
+    writeFileSync2(join2(output, "WidgetExtension", "Info.plist"), widgetInfo);
   }
   if (config.enableWatchApp) {
-    const watchSource = readFileSync(join(TEMPLATES_DIR, "CraftWatchApp.swift.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, name);
-    writeFileSync(join(output, "WatchExtension", `${name}WatchApp.swift`), watchSource);
-    const watchInfo = readFileSync(join(TEMPLATES_DIR, "WatchApp.Info.plist.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId);
-    writeFileSync(join(output, "WatchApp", "Info.plist"), watchInfo);
-    writeFileSync(join(output, "WatchApp", "Watch.entitlements"), renderWatchEntitlements(config));
-    const watchExtensionInfo = readFileSync(join(TEMPLATES_DIR, "WatchExtension.Info.plist.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId);
-    writeFileSync(join(output, "WatchExtension", "Info.plist"), watchExtensionInfo);
-    writeFileSync(join(output, "WatchExtension", "Watch.entitlements"), renderWatchEntitlements(config));
+    const watchInfo = readFileSync2(join2(TEMPLATES_DIR, "WatchApp.Info.plist.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId);
+    writeFileSync2(join2(output, "WatchApp", "Info.plist"), watchInfo);
+    writeFileSync2(join2(output, "WatchApp", "Watch.entitlements"), renderWatchEntitlements(config));
+    const watchExtensionInfo = readFileSync2(join2(TEMPLATES_DIR, "WatchExtension.Info.plist.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId);
+    writeFileSync2(join2(output, "WatchExtension", "Info.plist"), watchExtensionInfo);
+    writeFileSync2(join2(output, "WatchExtension", "Watch.entitlements"), renderWatchEntitlements(config));
   }
-  writeFileSync(join(output, "dist", "index.html"), renderOfflinePage(config));
+  writeFileSync2(join2(output, "dist", "index.html"), renderOfflinePage(config));
   if (isHybrid(config)) {
     if (config.nativeBundle)
       installNativeBundle(config.nativeBundle, output);
@@ -913,11 +1068,11 @@ async function build(options) {
   const { htmlPath, nativeBundlePath, devServer, output, generateProject = true } = options;
   console.log(`
 \uD83D\uDCE6 Building Craft iOS project...`);
-  const configPath = join(output, "craft.config.json");
+  const configPath = join2(output, "craft.config.json");
   if (!existsSync(configPath)) {
     throw new Error(`No craft.config.json found in ${output}. Run 'craft ios init' first.`);
   }
-  const config = JSON.parse(readFileSync(configPath, "utf-8"));
+  const config = JSON.parse(readFileSync2(configPath, "utf-8"));
   if (config.renderer !== undefined && config.renderer !== "web" && config.renderer !== "native") {
     throw new Error(`Unknown iOS renderer: ${config.renderer}. Expected web or native.`);
   }
@@ -926,11 +1081,11 @@ async function build(options) {
       throw new Error("A native iOS screen cannot use --html-path or --dev-server.");
     }
     if (nativeBundlePath) {
-      const destination = join(output, "dist", "native-screen.js");
+      const destination = join2(output, "dist", "native-screen.js");
       if (resolve(nativeBundlePath) !== resolve(destination))
         cpSync(nativeBundlePath, destination);
     }
-    if (!existsSync(join(output, "dist", "native-screen.js"))) {
+    if (!existsSync(join2(output, "dist", "native-screen.js"))) {
       throw new Error("Native iOS mode needs dist/native-screen.js. Compile a .stx screen with `stx native compile` first.");
     }
   } else if (nativeBundlePath && !isHybrid(config)) {
@@ -944,7 +1099,7 @@ async function build(options) {
     config.devServerURL = devServer;
     const origin = new URL(devServer).origin;
     config.trustedOrigins = [...new Set([...config.trustedOrigins ?? [], origin])];
-    writeFileSync(configPath, JSON.stringify(config, null, 2));
+    writeFileSync2(configPath, JSON.stringify(config, null, 2));
     console.log(`   Dev server: ${devServer}`);
   }
   if (htmlPath) {
@@ -956,7 +1111,7 @@ async function build(options) {
     if (bundle) {
       installNativeBundle(bundle, output);
       console.log(`   Native screens: ${bundle} \u2192 dist/native-screen.js`);
-    } else if (!existsSync(join(output, "dist", "native-screen.js"))) {
+    } else if (!existsSync(join2(output, "dist", "native-screen.js"))) {
       console.warn("   \u26A0 nativeScreens is set but there is no native bundle: every path opens in the web view.");
     }
   }
@@ -986,7 +1141,7 @@ async function open(options) {
   if (!xcodeproj) {
     throw new Error(`No Xcode project found in ${output}. Run 'craft ios build' first.`);
   }
-  const projectPath = join(output, xcodeproj);
+  const projectPath = join2(output, xcodeproj);
   console.log(`\uD83D\uDE80 Opening ${xcodeproj}...`);
   await $`open ${projectPath}`;
 }
@@ -1027,7 +1182,7 @@ async function showSimulator() {
   const selected = await $`xcode-select -p`.quiet().nothrow();
   const developer = selected.exitCode === 0 ? selected.stdout.toString().trim() : "";
   if (developer) {
-    const app = join(developer, "Applications", "Simulator.app");
+    const app = join2(developer, "Applications", "Simulator.app");
     if (existsSync(app)) {
       await $`open ${app}`.quiet().nothrow();
       return;
@@ -1043,12 +1198,12 @@ async function run(options) {
   if (!xcodeproj) {
     throw new Error(`No Xcode project found in ${output}`);
   }
-  const projectPath = join(output, xcodeproj);
+  const projectPath = join2(output, xcodeproj);
   const appName = xcodeproj.replace(".xcodeproj", "");
-  const configPath = join(output, "craft.config.json");
+  const configPath = join2(output, "craft.config.json");
   if (!existsSync(configPath))
     throw new Error(`No craft.config.json found in ${output}. Run 'craft-ios init' first.`);
-  const config = JSON.parse(readFileSync(configPath, "utf-8"));
+  const config = JSON.parse(readFileSync2(configPath, "utf-8"));
   if (simulator) {
     console.log("\uD83D\uDCF1 Building and running on simulator...");
     const device = await pickSimulator();
@@ -1058,8 +1213,8 @@ async function run(options) {
     console.log(`   Device: ${device.name} (${device.runtime})`);
     try {
       await bootSimulator(device);
-      const derivedData = join(output, "build");
-      const product = join(derivedData, "Build", "Products", "Debug-iphonesimulator", `${appName}.app`);
+      const derivedData = join2(output, "build");
+      const product = join2(derivedData, "Build", "Products", "Debug-iphonesimulator", `${appName}.app`);
       await $`xcodebuild -project ${projectPath} -scheme ${appName} -configuration Debug -destination ${`id=${device.udid}`} -derivedDataPath ${derivedData} build`;
       if (!existsSync(product)) {
         throw new Error(`xcodebuild reported success but ${product} does not exist. ` + "The scheme may build a different product name than the project.");
@@ -1085,7 +1240,9 @@ async function run(options) {
 export {
   syncWebAssets,
   showSimulator,
+  serializeSimulatorSteps,
   run,
+  restoreShell,
   resolveRuntimeDir,
   resolveAppearance,
   renderWatchEntitlements,
@@ -1112,8 +1269,10 @@ export {
   matchNativePath,
   isHybrid,
   installRuntime,
+  initSimulatorDriver,
   init,
   hybridConfigProblems,
+  createNativeMutationValidator,
   build,
   bootSimulator,
   backgroundRefreshIdentifier,

package/dist/ios/src/testing.d.ts

@@ -0,0 +1,71 @@
+export interface SimulatorDriverOptions {
+    output: string;
+    /** The installed app to drive; the test host is a separate application. */
+    bundleId: string;
+    projectName?: string;
+    bundleIdPrefix?: string;
+    deploymentTarget?: string;
+    controlUrl?: string;
+    tabs?: readonly string[];
+}
+/** Generate the reusable XCUITest shell from package templates. No app-owned Swift. */
+export declare function initSimulatorDriver(options: SimulatorDriverOptions): void;
+export type SimulatorStep = {
+    command: 'launch' | 'activate' | 'terminate' | 'home' | 'back' | 'return' | 'unlabelled';
+} | {
+    command: 'background' | 'wait';
+    seconds: number;
+} | {
+    command: 'delay';
+    milliseconds: number;
+} | {
+    command: 'net';
+    state: 'online' | 'offline';
+} | {
+    command: 'swipe';
+    direction: 'up' | 'down' | 'left' | 'right';
+} | {
+    command: 'tabbar';
+    state: 'shown' | 'hidden';
+} | {
+    command: 'tapxy';
+    x: number;
+    y: number;
+} | {
+    command: 'field';
+    index: number;
+    text: string;
+} | {
+    command: 'typeid';
+    id: string;
+    text: string;
+} | {
+    command: 'expect' | 'expectexact' | 'expectid';
+    text: string;
+    seconds?: number;
+} | {
+    command: 'tap' | 'tapif' | 'tapid' | 'tapexact' | 'type' | 'absent' | 'absentid' | 'selected' | 'tab' | 'scrollto' | 'dismiss' | 'log';
+    text: string;
+} | {
+    command: 'shot' | 'tree' | 'audit' | 'exec';
+    name: string;
+} | {
+    command: 'openurl';
+    url: string;
+};
+/** Typed journeys use the same wire protocol as existing line-based scripts. */
+export declare function serializeSimulatorSteps(steps: readonly SimulatorStep[]): string;
+export interface NativeValidationResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface NativeMutationValidator {
+    validate(messages: readonly {
+        type: string;
+        payload?: unknown;
+    }[]): NativeValidationResult;
+    dispose(): void;
+}
+/** Compile the actual Foundation mutation host once, then validate captured STX messages. Requires macOS and swiftc. */
+export declare function createNativeMutationValidator(): NativeMutationValidator;

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

@@ -0,0 +1,305 @@
+import XCTest
+
+/// Drives the installed app from a script the Mac serves (netswitch.ts
+/// `/script`), one command a line:
+///
+///   launch | activate | terminate | home
+///   background <secs>     Home, wait, back to the app
+///   wait <seconds>
+///   net offline|online
+///   delay <ms>            every proxied request waits this long (0 = off)
+///   exec <hook>           runs the switch's HOOKS/<hook>.sh on the Mac (restart the API, …)
+///   openurl <url>         opens a link through the system, answering "Open in the app?"
+///   shot <name>           screenshot → shots/<name>.png
+///   tree <name>           accessibility tree → shots/<name>.txt
+///   tap <text>            first hittable element whose label contains text
+///   tapif <text>          tap it when it is on screen, else carry on (the big timer's "Show the controls")
+///   tapid <identifier>
+///   tapxy <x> <y>         normalised 0…1 of the screen
+///   tapexact <label>      a button whose label is exactly this
+///   back                  the navigation bar's back button, else an edge swipe
+///   type <text>           into the focused element
+///   return                the keyboard's return key (Go on a sign-in form)
+///   field <n> <text>      tap the n-th text field (0-based, secure fields after plain) and type
+///   typeid <identifier> <text>  tap the element with this identifier and type
+///   expect <text> [| secs]  waits for an element containing text; logs PASS/FAIL
+///   expectexact <label> [| secs]  a button or text whose label is exactly this
+///   absent <text>         logs PASS when no element contains text
+///   expectid <id> [| secs] / absentid <id>   the same by accessibility identifier (testID)
+///   tabbar shown|hidden   the native tab bar (Today, Calendar, …) can be tapped, or not
+///   selected <tab>        the tab bar's selected button is this one
+///   tab <name>            tap a tab bar button
+///   scrollto <text>       swipes up (at most 8 times) until text is hittable
+///   swipe up|down|left|right
+///   audit <name>          accessibility audit (element descriptions, Dynamic Type, contrast); logs each issue
+///   unlabelled            logs every hittable button without a label (FAIL if any)
+///   dismiss [label]       a system prompt's button (default Not Now: "Save Password?")
+///   log <text>
+///
+/// Checks log `PASS …` / `FAIL …` lines into driver.log; matrix.sh counts them.
+final class DriverTests: XCTestCase {
+    let control = ProcessInfo.processInfo.environment["CRAFT_TEST_CONTROL"] ?? {{CONTROL_URL}}
+    let app = XCUIApplication(bundleIdentifier: {{BUNDLE_ID}})
+    let tabs: [String] = {{TABS}}
+
+    func get(_ path: String, timeout: Double = 15) -> Data? {
+        var result: Data?
+        let done = expectation(description: path)
+        URLSession.shared.dataTask(with: URL(string: control + path)!) { data, _, _ in result = data; done.fulfill() }.resume()
+        wait(for: [done], timeout: timeout)
+        return result
+    }
+
+    func post(_ path: String, _ body: Data) {
+        var request = URLRequest(url: URL(string: control + path)!)
+        request.httpMethod = "POST"
+        request.httpBody = body
+        let done = expectation(description: path)
+        URLSession.shared.dataTask(with: request) { _, _, _ in done.fulfill() }.resume()
+        wait(for: [done], timeout: 15)
+    }
+
+    func note(_ text: String) {
+        print("DRIVER \(text)")
+        post("/note", Data(text.utf8))
+    }
+
+    func check(_ ok: Bool, _ what: String) {
+        note(ok ? "PASS \(what)" : "FAIL \(what)")
+        XCTAssertTrue(ok, what)
+    }
+
+    func element(containing text: String) -> XCUIElement? {
+        let predicate = NSPredicate(format: "label CONTAINS[c] %@ OR value CONTAINS[c] %@ OR identifier == %@", text, text, text)
+        for query in [app.buttons, app.links, app.staticTexts, app.otherElements, app.cells, app.textFields] {
+            let matches = query.matching(predicate)
+            let count = min(matches.count, 25)
+            for index in 0..<count {
+                let candidate = matches.element(boundBy: index)
+                if candidate.exists && candidate.isHittable { return candidate }
+            }
+        }
+        let any = app.descendants(matching: .any).matching(predicate).firstMatch
+        return any.exists ? any : nil
+    }
+
+    func exact(_ label: String) -> XCUIElement? {
+        let predicate = NSPredicate(format: "label == %@", label)
+        for query in [app.buttons, app.links, app.staticTexts] {
+            let matches = query.matching(predicate)
+            for index in 0..<min(matches.count, 25) {
+                let candidate = matches.element(boundBy: index)
+                if candidate.exists && candidate.isHittable { return candidate }
+            }
+        }
+        return nil
+    }
+
+    func poll(_ seconds: Double, _ find: () -> XCUIElement?) -> XCUIElement? {
+        let end = Date().addingTimeInterval(seconds)
+        repeat {
+            if let found = find() { return found }
+            Thread.sleep(forTimeInterval: 0.5)
+        } while Date() < end
+        return nil
+    }
+
+    func waitFor(_ text: String, _ seconds: Double) -> XCUIElement? {
+        poll(seconds) { element(containing: text) }
+    }
+
+    /// The native tab bar's button: Craft's floating bar is not a UITabBar, and
+    /// XCUITest calls its buttons not hittable, so it is the button with this
+    /// label in the bottom fifth of the window.
+    func tabButton(_ name: String) -> XCUIElement? {
+        let height = app.windows.firstMatch.frame.height
+        let matches = app.buttons.matching(NSPredicate(format: "label == %@", name))
+        for index in 0..<min(matches.count, 10) {
+            let candidate = matches.element(boundBy: index)
+            if candidate.exists && candidate.frame.minY > height * 0.8 && candidate.frame.maxY <= height + 1 && candidate.frame.width > 0 { return candidate }
+        }
+        return nil
+    }
+
+    func tabBarShown() -> Bool {
+        let required = min(3, tabs.count)
+        return required > 0 && tabs.filter { tabButton($0) != nil }.count >= required
+    }
+
+    func split(_ arg: String) -> (String, Double) {
+        let parts = arg.split(separator: "|").map { $0.trimmingCharacters(in: .whitespaces) }
+        return (parts[0], parts.count > 1 ? Double(parts[1]) ?? 10 : 10)
+    }
+
+    /// A tap that never fails the run: an element covered a moment (the big
+    /// timer coming up) is tapped where it is, and the check after says.
+    func press(_ element: XCUIElement) {
+        if element.isHittable { element.tap() }
+        else { element.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.5)).tap() }
+    }
+
+    func answerOpenPrompt() {
+        let springboard = XCUIApplication(bundleIdentifier: "com.apple.springboard")
+        let open = springboard.buttons["Open"]
+        if open.waitForExistence(timeout: 4) { open.tap() }
+    }
+
+    func testScript() throws {
+        continueAfterFailure = true
+        guard let data = get("/script"), let script = String(data: data, encoding: .utf8) else {
+            XCTFail("no script")
+            return
+        }
+        for raw in script.split(separator: "\n") {
+            let line = raw.trimmingCharacters(in: .whitespaces)
+            if line.isEmpty || line.hasPrefix("#") { continue }
+            let parts = line.split(separator: " ", maxSplits: 1).map(String.init)
+            let command = parts[0]
+            let arg = parts.count > 1 ? parts[1] : ""
+            switch command {
+            case "launch": app.launch()
+            case "activate": app.activate()
+            case "terminate": app.terminate()
+            case "home": XCUIDevice.shared.press(.home)
+            case "background":
+                XCUIDevice.shared.press(.home)
+                Thread.sleep(forTimeInterval: Double(arg) ?? 3)
+                app.activate()
+            case "wait": Thread.sleep(forTimeInterval: Double(arg) ?? 1)
+            case "net": _ = get("/\(arg)"); note("net \(arg)")
+            case "delay": _ = get("/delay?ms=\(arg)"); note("delay \(arg)ms")
+            case "exec":
+                let out = get("/exec?name=\(arg)", timeout: 180).flatMap { String(data: $0, encoding: .utf8) } ?? "no answer"
+                note("exec \(arg): \(out.trimmingCharacters(in: .whitespacesAndNewlines))")
+            case "openurl":
+                if let url = URL(string: arg) {
+                    XCUIDevice.shared.system.open(url)
+                    answerOpenPrompt()
+                    note("openurl \(arg)")
+                }
+            case "shot":
+                let shot = XCUIScreen.main.screenshot()
+                post("/save?name=\(arg).png", shot.pngRepresentation)
+            case "tree":
+                post("/save?name=\(arg).txt", Data(app.debugDescription.utf8))
+            case "tap":
+                if let target = waitFor(arg, 10) { press(target); note("tap \(arg): ok") }
+                else { XCTFail("Element not found"); note("FAIL tap \(arg): NOT FOUND") }
+            case "tapif":
+                if let target = element(containing: arg), target.isHittable { press(target); note("tapif \(arg): tapped") }
+                else { note("tapif \(arg): not shown") }
+            case "tapexact":
+                if let target = poll(10, { exact(arg) }) { press(target); note("tapexact \(arg): ok") }
+                else { XCTFail("Element not found"); note("FAIL tapexact \(arg): NOT FOUND") }
+            case "tapid":
+                let target = app.descendants(matching: .any)[arg]
+                if target.waitForExistence(timeout: 10) { press(target); note("tapid \(arg): ok") }
+                else { XCTFail("Element not found"); note("FAIL tapid \(arg): NOT FOUND") }
+            case "tapxy":
+                let xy = arg.split(separator: " ").compactMap { Double($0) }
+                if xy.count == 2 && xy.allSatisfy({ $0 >= 0 && $0 <= 1 }) {
+                    app.coordinate(withNormalizedOffset: CGVector(dx: xy[0], dy: xy[1])).tap()
+                } else { XCTFail("tapxy needs two coordinates between 0 and 1") }
+            case "back":
+                let bar = app.navigationBars.buttons.firstMatch
+                if bar.exists && bar.isHittable { bar.tap(); note("back: bar button") }
+                else {
+                    let start = app.coordinate(withNormalizedOffset: CGVector(dx: 0.02, dy: 0.5))
+                    start.press(forDuration: 0.05, thenDragTo: app.coordinate(withNormalizedOffset: CGVector(dx: 0.8, dy: 0.5)))
+                    note("back: edge swipe")
+                }
+            case "type": app.typeText(arg)
+            case "return": app.typeText(XCUIKeyboardKey.return.rawValue); note("return")
+            case "typeid":
+                let idParts = arg.split(separator: " ", maxSplits: 1).map(String.init)
+                let target = app.descendants(matching: .any)[idParts[0]]
+                if target.waitForExistence(timeout: 10) {
+                    target.tap()
+                    Thread.sleep(forTimeInterval: 0.8)
+                    app.typeText(idParts.count > 1 ? idParts[1] : "")
+                    note("typeid \(idParts[0]): ok")
+                } else { XCTFail("Element not found"); note("FAIL typeid \(idParts[0]): NOT FOUND") }
+            case "field":
+                let fieldParts = arg.split(separator: " ", maxSplits: 1).map(String.init)
+                let index = Int(fieldParts[0]) ?? 0
+                let fields = app.textFields.allElementsBoundByIndex + app.secureTextFields.allElementsBoundByIndex
+                if index >= 0 && index < fields.count {
+                    fields[index].tap()
+                    Thread.sleep(forTimeInterval: 0.6)
+                    app.typeText(fieldParts.count > 1 ? fieldParts[1] : "")
+                    note("field \(index): ok")
+                } else { XCTFail("Element not found"); note("FAIL field \(index): NOT FOUND (\(fields.count) fields)") }
+            case "expect":
+                let (text, seconds) = split(arg)
+                check(waitFor(text, seconds) != nil, "expect \(text)")
+            case "expectexact":
+                let (text, seconds) = split(arg)
+                check(poll(seconds, { exact(text) }) != nil, "expectexact \(text)")
+            case "expectid":
+                let (id, seconds) = split(arg)
+                check(app.descendants(matching: .any)[id].waitForExistence(timeout: seconds), "expectid \(id)")
+            case "absentid":
+                check(!app.descendants(matching: .any)[arg].exists, "absentid \(arg)")
+            case "absent":
+                check(element(containing: arg) == nil, "absent \(arg)")
+            case "tabbar":
+                let want = arg != "hidden"
+                let end = Date().addingTimeInterval(5)
+                var shown = tabBarShown()
+                while shown != want && Date() < end { Thread.sleep(forTimeInterval: 0.5); shown = tabBarShown() }
+                check(shown == want, "tabbar \(arg)")
+            case "selected":
+                check(poll(5, { tabButton(arg).flatMap { $0.isSelected ? $0 : nil } }) != nil, "selected \(arg)")
+            case "tab":
+                if let button = poll(10, { tabButton(arg) }) { button.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.5)).tap(); note("tab \(arg): ok") }
+                else { XCTFail("Element not found"); note("FAIL tab \(arg): NOT FOUND") }
+            case "scrollto":
+                var found = element(containing: arg)
+                var swipes = 0
+                while (found == nil || !(found!.isHittable)) && swipes < 8 {
+                    app.swipeUp()
+                    swipes += 1
+                    found = element(containing: arg)
+                }
+                check(found != nil && found!.isHittable, "scrollto \(arg)")
+            case "swipe":
+                switch arg {
+                case "up": app.swipeUp()
+                case "down": app.swipeDown()
+                case "left": app.swipeLeft()
+                default: app.swipeRight()
+                }
+            case "audit":
+                var issues: [String] = []
+                do {
+                    try app.performAccessibilityAudit(for: [.sufficientElementDescription, .dynamicType, .contrast, .hitRegion]) { issue in
+                        let label = issue.element?.label ?? ""
+                        let id = issue.element?.identifier ?? ""
+                        issues.append("\(issue.auditType.rawValue) \(issue.compactDescription) [\(label)|\(id)]")
+                        return true
+                    }
+                } catch { issues.append("audit error \(error)") }
+                post("/save?name=audit-\(arg).txt", Data(issues.joined(separator: "\n").utf8))
+                note("AUDIT \(arg): \(issues.count) issue(s)")
+            case "unlabelled":
+                let buttons = app.buttons.allElementsBoundByIndex.filter { $0.exists && $0.isHittable && $0.label.trimmingCharacters(in: .whitespaces).isEmpty }
+                let where_ = buttons.prefix(5).map { "\(Int($0.frame.midX)),\(Int($0.frame.midY)) id=\($0.identifier)" }.joined(separator: "; ")
+                check(buttons.isEmpty, "unlabelled buttons \(arg) \(buttons.count) \(where_)")
+            case "dismiss":
+                // A system prompt over the app ("Save Password?" → Not Now), wherever iOS shows it.
+                let label = arg.isEmpty ? "Not Now" : arg
+                let springboard = XCUIApplication(bundleIdentifier: "com.apple.springboard")
+                let candidates = [app.buttons[label], springboard.buttons[label]]
+                let end = Date().addingTimeInterval(6)
+                var done = false
+                while !done && Date() < end {
+                    if let button = candidates.first(where: { $0.exists && $0.isHittable }) { button.tap(); done = true }
+                    else { Thread.sleep(forTimeInterval: 0.5) }
+                }
+                note("dismiss \(label): \(done ? "tapped" : "none shown")")
+            case "log": note(arg)
+            default: XCTFail("Unknown command \(command)"); note("FAIL unknown command \(command)")
+            }
+        }
+    }
+}

package/dist/ios/templates/testing/HostApp.swift

@@ -0,0 +1,6 @@
+import SwiftUI
+
+@main
+struct HostApp: App {
+    var body: some Scene { WindowGroup { Text("Craft simulator driver") } }
+}

package/dist/ios/templates/testing/MutationValidator.swift

@@ -0,0 +1,15 @@
+import Foundation
+let messages = try JSONSerialization.jsonObject(with: Data(contentsOf: URL(fileURLWithPath: CommandLine.arguments[1]))) as! [[String: Any]]
+func report(_ message: String) {
+  try! (message + "\n").write(to: URL(fileURLWithPath: CommandLine.arguments[2]), atomically: true, encoding: .utf8)
+}
+let document = CraftNativeMutationDocument()
+for message in messages {
+  let payload = message["payload"] as? [String: Any] ?? [:]
+  if message["type"] as? String == "RENDER" { document.replace(with: payload["document"] as! [String: Any]) }
+  if message["type"] as? String == "MUTATE" {
+    do { _ = try document.apply(payload) }
+    catch let failure as CraftNativeMutationFailure { report("\(failure.code): \(failure.message) at operation \(failure.operationIndex ?? -1)"); exit(1) }
+  }
+}
+report("Accepted all native update batches")

package/dist/ios/templates/testing/project.yml.template

@@ -0,0 +1,36 @@
+name: {{PROJECT_NAME}}
+options:
+  bundleIdPrefix: {{BUNDLE_PREFIX}}
+  deploymentTarget:
+    iOS: "{{IOS_VERSION}}"
+targets:
+  {{PROJECT_NAME}}Host:
+    type: application
+    platform: iOS
+    sources: [Host]
+    settings:
+      PRODUCT_BUNDLE_IDENTIFIER: {{BUNDLE_PREFIX}}.host
+      GENERATE_INFOPLIST_FILE: YES
+      INFOPLIST_KEY_UILaunchScreen_Generation: YES
+      SWIFT_VERSION: "5.0"
+      CODE_SIGNING_ALLOWED: NO
+  {{PROJECT_NAME}}UITests:
+    type: bundle.ui-testing
+    platform: iOS
+    sources: [UITests]
+    settings:
+      TEST_TARGET_NAME: {{PROJECT_NAME}}Host
+      PRODUCT_BUNDLE_IDENTIFIER: {{BUNDLE_PREFIX}}.uitests
+      GENERATE_INFOPLIST_FILE: YES
+      SWIFT_VERSION: "5.0"
+      CODE_SIGNING_ALLOWED: NO
+    dependencies:
+      - target: {{PROJECT_NAME}}Host
+schemes:
+  {{PROJECT_NAME}}:
+    build:
+      targets:
+        {{PROJECT_NAME}}Host: all
+        {{PROJECT_NAME}}UITests: [test]
+    test:
+      targets: [{{PROJECT_NAME}}UITests]

package/package.json

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