craft-native 0.0.154 → 0.0.156

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";
   }
@@ -91,11 +228,25 @@ function matchNativePath(nativeScreens, raw) {
 function isHybrid(config) {
   return (config.renderer ?? "web") === "web" && Object.keys(config.nativeScreens ?? {}).length > 0;
 }
+function hasNativeRoutes(config) {
+  return config.renderer === "native" && Object.keys(config.nativeScreens ?? {}).length > 0;
+}
+function usesNativeBundle(config) {
+  return config.renderer === "native" || Object.keys(config.nativeScreens ?? {}).length > 0;
+}
+function nativeStartPath(config) {
+  if (!config.devServerURL)
+    return "/";
+  try {
+    const url = new URL(config.devServerURL);
+    return `${url.pathname || "/"}${url.search}`;
+  } catch {
+    return "/";
+  }
+}
 function hybridConfigProblems(config) {
   const problems = [];
   const screens = Object.entries(config.nativeScreens ?? {});
-  if (screens.length && config.renderer === "native")
-    problems.push('nativeScreens mixes native screens into a web app; it needs renderer: "web" (renderer: "native" is all native already).');
   for (const [pattern, screen] of screens) {
     if (normalizeNativePath(pattern) !== pattern || /[?#]/.test(pattern))
       problems.push(`nativeScreens path "${pattern}" must be an absolute path with no query, hash or trailing slash.`);
@@ -117,13 +268,28 @@ function hybridConfigProblems(config) {
     if (!key || typeof target !== "string" || !target)
       problems.push(`shareStorage "${key}" needs the Keychain key native screens read it under.`);
   }
+  if (hasNativeRoutes(config)) {
+    for (const id of ids) {
+      if (!matchNativePath(config.nativeScreens, id))
+        problems.push(`Tab "${id}" is not a nativeScreens path; with renderer: "native" every tab must be a native screen.`);
+    }
+    const start = nativeStartPath(config);
+    if (!matchNativePath(config.nativeScreens, start))
+      problems.push(`The start path "${start}" (from devServerURL) is not a nativeScreens path; with renderer: "native" the app must start on a native screen.`);
+  }
+  if (config.nativeApp !== undefined) {
+    if (typeof config.nativeApp !== "string" || !/^[A-Za-z_$][\w$-]*$/.test(config.nativeApp))
+      problems.push(`nativeApp "${String(config.nativeApp)}" must be a route name from the native bundle.`);
+    else if (!usesNativeBundle(config))
+      problems.push('nativeApp runs in the native bundle; it needs nativeScreens or renderer: "native".');
+  }
   return problems;
 }
 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 +637,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 +646,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 +693,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 +702,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 +718,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 +839,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 +869,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 +911,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 +955,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 +984,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,40 +1049,37 @@ 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));
-  if (isHybrid(config)) {
+  writeFileSync2(join2(output, "dist", "index.html"), renderOfflinePage(config));
+  if (usesNativeBundle(config)) {
     if (config.nativeBundle)
       installNativeBundle(config.nativeBundle, output);
-    else
+    else if (isHybrid(config))
       console.warn("   \u26A0 nativeScreens is set without nativeBundle: every path opens in the web view until `craft ios build --native-bundle` supplies one.");
+    else if (hasNativeRoutes(config))
+      console.warn("   \u26A0 nativeScreens is set without nativeBundle: the app has no screens until `craft ios build --native-bundle` supplies one.");
   }
   console.log("\u2705 Project initialized");
   console.log("");
@@ -913,11 +1099,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.`);
   }
@@ -925,12 +1111,10 @@ async function build(options) {
     if (htmlPath || devServer) {
       throw new Error("A native iOS screen cannot use --html-path or --dev-server.");
     }
-    if (nativeBundlePath) {
-      const destination = join(output, "dist", "native-screen.js");
-      if (resolve(nativeBundlePath) !== resolve(destination))
-        cpSync(nativeBundlePath, destination);
-    }
-    if (!existsSync(join(output, "dist", "native-screen.js"))) {
+    const bundle = nativeBundlePath ?? config.nativeBundle;
+    if (bundle)
+      installNativeBundle(bundle, output);
+    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 +1128,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 +1140,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 +1170,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 +1211,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 +1227,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 +1242,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.");
@@ -1083,9 +1267,12 @@ async function run(options) {
   }
 }
 export {
+  usesNativeBundle,
   syncWebAssets,
   showSimulator,
+  serializeSimulatorSteps,
   run,
+  restoreShell,
   resolveRuntimeDir,
   resolveAppearance,
   renderWatchEntitlements,
@@ -1109,11 +1296,15 @@ export {
   orderSimulators,
   open,
   normalizeNativePath,
+  nativeStartPath,
   matchNativePath,
   isHybrid,
   installRuntime,
+  initSimulatorDriver,
   init,
   hybridConfigProblems,
+  hasNativeRoutes,
+  createNativeMutationValidator,
   build,
   bootSimulator,
   backgroundRefreshIdentifier,