@craft-native/ios 0.0.368 → 0.0.374

package/dist/cli.js

@@ -3,12 +3,118 @@
 
 // src/cli.ts
 import { parseArgs } from "util";
-import { resolve as resolve2 } from "path";
+import { resolve as resolve3 } from "path";
 
 // src/index.ts
 import { gzipSync } from "zlib";
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync as readdirSync2, rmSync, statSync, writeFileSync } from "fs";
-import { dirname as dirname2, extname, join as join3, resolve, sep as sep2 } from "path";
+
+// src/runtime-profile.ts
+import { createHash } from "crypto";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join, resolve } from "path";
+var iosPermissionNames = ["speech", "microphone", "camera", "photos", "location", "contacts", "calendar", "bluetooth", "motion", "biometric", "music", "health", "nfc"];
+function iosPermissions(config) {
+  const enabled = {
+    speech: config.enableSpeechRecognition,
+    microphone: config.enableSpeechRecognition || config.enableAudioRecording || config.enableVideoRecording,
+    camera: config.enableCamera || config.enableVideoRecording || config.enableQRScanner || config.enableAR,
+    photos: config.enableCamera || config.enableVideoRecording,
+    location: config.enableGeolocation || config.enableBackgroundLocation,
+    contacts: config.enableContacts,
+    calendar: config.enableCalendar,
+    bluetooth: config.enableBluetooth || config.enableHeartRate,
+    motion: config.enableMotionSensors,
+    biometric: config.enableBiometric,
+    music: config.enableAppleMusic,
+    health: config.enableHealthKit,
+    nfc: config.enableNFC
+  };
+  return iosPermissionNames.filter((name) => enabled[name] === true);
+}
+function iosPermissionMask(config) {
+  return iosPermissions(config).reduce((mask, name) => mask | 1 << iosPermissionNames.indexOf(name), 0);
+}
+function renderPermissionSource(source, config) {
+  const enabled = new Set(iosPermissions(config));
+  return source.replace(/#if CRAFT_(?:PERMISSION_([A-Z]+)|APPLE_(MUSIC))\b/g, (_match, permission, music) => {
+    const name = music ? "music" : permission.toLowerCase();
+    if (!iosPermissionNames.includes(name))
+      throw new Error(`Unknown Swift permission gate: ${name}`);
+    return `#if ${enabled.has(name) ? "true" : "false"}`;
+  });
+}
+var archives = ["libcraft-ios.a", "libcraft-ios-simulator-arm64.a", "libcraft-ios-simulator-x64.a"];
+var digest = (path) => createHash("sha256").update(readFileSync(path)).digest("hex");
+function verifyRuntimeProfile(directory, config) {
+  if (!existsSync(join(directory, "ios-permissions.json")))
+    throw new Error("Unprofiled Zig runtime: use runtimeSource to build archives for this app");
+  const profile = JSON.parse(readFileSync(join(directory, "ios-permissions.json"), "utf8"));
+  if (profile.version !== 1 || profile.mask !== iosPermissionMask(config))
+    throw new Error("Zig runtime permission profile does not match craft.config.json; rebuild it for this app");
+  if (!existsSync(join(directory, archives[0])) || !archives.slice(1).some((name) => existsSync(join(directory, name))))
+    throw new Error("Zig runtime must include device and simulator archives");
+  for (const name of archives) {
+    if (!existsSync(join(directory, name)) && !profile.sha256?.[name])
+      continue;
+    if (!existsSync(join(directory, name)) || profile.sha256?.[name] !== digest(join(directory, name)))
+      throw new Error(`Zig runtime archive identity mismatch: ${name}; rebuild it for this app`);
+  }
+}
+function writeInstalledProfile(directory, config, source) {
+  const paths = ["device/libcraft-ios.a", "simulator/libcraft-ios.a"];
+  writeFileSync(join(directory, "profile.json"), JSON.stringify({
+    version: 1,
+    mask: iosPermissionMask(config),
+    source,
+    sha256: Object.fromEntries(paths.map((path) => [path, digest(join(directory, path))]))
+  }, null, 2));
+}
+function verifyInstalledProfile(directory, config) {
+  if (!existsSync(join(directory, "profile.json")))
+    throw new Error("Unprofiled Zig runtime: regenerate this project with runtimeSource before omitting permission descriptions");
+  const profile = JSON.parse(readFileSync(join(directory, "profile.json"), "utf8"));
+  if (profile.version !== 1 || profile.mask !== iosPermissionMask(config))
+    throw new Error("Installed Zig runtime permission profile is stale; rebuild it for craft.config.json");
+  for (const path of ["device/libcraft-ios.a", "simulator/libcraft-ios.a"]) {
+    if (!existsSync(join(directory, path)) || profile.sha256?.[path] !== digest(join(directory, path)))
+      throw new Error(`Installed Zig runtime identity mismatch: ${path}; rebuild it for this app`);
+  }
+}
+async function withAppRuntime(source, config, use) {
+  const root = resolve(source);
+  const manifest = readFileSync(join(root, "build.zig.zon"), "utf8");
+  const version = /\.minimum_zig_version\s*=\s*"([^"]+)"/.exec(manifest)?.[1];
+  if (!version)
+    throw new Error("Craft Zig source must declare its pinned minimum_zig_version");
+  const zig = process.env.CRAFT_ZIG || "zig";
+  const actual = Bun.spawnSync([zig, "version"], { stdout: "pipe", stderr: "pipe" });
+  if (actual.exitCode !== 0 || actual.stdout.toString().trim() !== version)
+    throw new Error(`Per-app iOS runtime requires Zig ${version}; set CRAFT_ZIG to that executable`);
+  const output = mkdtempSync(join(tmpdir(), "craft-ios-runtime-"));
+  try {
+    const names = iosPermissions(config);
+    const command = [zig, "build", "build-ios-all", `-Dios-permissions=${names.join(",") || "none"}`, "-Djs-runtime=false", "-Doptimize=ReleaseFast", "--prefix", output];
+    const child = Bun.spawn(command, { cwd: root, stdout: "inherit", stderr: "inherit" });
+    if (await child.exited !== 0)
+      throw new Error("Per-app iOS Zig runtime build failed; installed runtime was not replaced");
+    const directory = join(output, "lib");
+    const profile = JSON.parse(readFileSync(join(directory, "ios-permissions.json"), "utf8"));
+    if (profile.version !== 1 || profile.mask !== iosPermissionMask(config))
+      throw new Error("Craft Zig source did not build the requested iOS permission profile");
+    profile.sha256 = Object.fromEntries(archives.map((name) => [name, digest(join(directory, name))]));
+    writeFileSync(join(directory, "ios-permissions.json"), `${JSON.stringify(profile, null, 2)}
+`);
+    verifyRuntimeProfile(directory, config);
+    return await use(directory);
+  } finally {
+    rmSync(output, { recursive: true, force: true });
+  }
+}
+
+// src/index.ts
+import { cpSync, existsSync as existsSync2, mkdirSync, mkdtempSync as mkdtempSync2, readFileSync as readFileSync2, readdirSync as readdirSync2, renameSync, rmSync as rmSync2, statSync, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2, extname, join as join4, resolve as resolve2, sep as sep2 } from "path";
 var {$ } = globalThis.Bun;
 
 // src/app-shortcuts.ts
@@ -67,7 +173,7 @@ ${entries}
 
 // src/source-audit.ts
 import { readdirSync } from "fs";
-import { join, relative, sep } from "path";
+import { join as join2, relative, sep } from "path";
 var defaultIgnoredPaths = [
   ".git",
   "node_modules",
@@ -87,7 +193,7 @@ function isIgnored(path, ignoredPaths) {
 }
 function visit(root, current, ignoredPaths, found) {
   for (const entry of readdirSync(current, { withFileTypes: true })) {
-    const absolute = join(current, entry.name);
+    const absolute = join2(current, entry.name);
     const relativePath = relative(root, absolute);
     if (isIgnored(relativePath, ignoredPaths))
       continue;
@@ -114,27 +220,27 @@ ${sources.map((path) => `- ${path}`).join(`
   }
 }
 // src/testing.ts
-import { dirname, join as join2 } from "path";
-var templates = join2(dirname(import.meta.dir), "templates/testing");
+import { dirname, join as join3 } from "path";
+var templates = join3(dirname(import.meta.dir), "templates/testing");
 
 // src/index.ts
 function compressNativeSources(target) {
   if (statSync(target).isDirectory()) {
     for (const entry of readdirSync2(target))
-      compressNativeSources(join3(target, entry));
+      compressNativeSources(join4(target, entry));
     return;
   }
   if (!/\.(?:js|json)$/.test(target))
     return;
-  const bytes = readFileSync(target);
+  const bytes = readFileSync2(target);
   if (bytes.length < 1024 || bytes[0] === 31 && bytes[1] === 139)
     return;
   const packed = gzipSync(bytes, { level: 9 });
   if (packed.length < bytes.length)
-    writeFileSync(target, packed);
+    writeFileSync2(target, packed);
 }
 function syncNativeFonts(fonts, output) {
-  const destination = join3(output, "NativeFonts");
+  const destination = join4(output, "NativeFonts");
   const names = new Set;
   const files = Object.entries(fonts ?? {}).map(([family, entry]) => {
     if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(family))
@@ -142,32 +248,32 @@ function syncNativeFonts(fonts, output) {
     if (names.has(family.toLowerCase()))
       throw new Error(`Duplicate native font name: ${family}`);
     names.add(family.toLowerCase());
-    if ([entry.src, entry.license].some((file) => file && resolve(file).startsWith(resolve(destination) + sep2)))
+    if ([entry.src, entry.license].some((file) => file && resolve2(file).startsWith(resolve2(destination) + sep2)))
       throw new Error("Native font sources must be outside the generated NativeFonts directory");
     const extension = extname(entry.src).toLowerCase();
-    if (![".ttf", ".otf"].includes(extension) || !existsSync(entry.src) || !statSync(entry.src).isFile())
+    if (![".ttf", ".otf"].includes(extension) || !existsSync2(entry.src) || !statSync(entry.src).isFile())
       throw new Error(`Native font ${family} must reference an existing TTF or OTF file: ${entry.src}`);
-    if (entry.license && (!existsSync(entry.license) || !statSync(entry.license).isFile()))
+    if (entry.license && (!existsSync2(entry.license) || !statSync(entry.license).isFile()))
       throw new Error(`Native font license not found: ${entry.license}`);
     return { family, ...entry, filename: `${family}${extension}` };
   });
-  rmSync(destination, { recursive: true, force: true });
+  rmSync2(destination, { recursive: true, force: true });
   if (!files.length)
     return [];
   mkdirSync(destination, { recursive: true });
   for (const file of files) {
-    cpSync(file.src, join3(destination, file.filename));
+    cpSync(file.src, join4(destination, file.filename));
     if (file.license)
-      cpSync(file.license, join3(destination, `${file.family}.LICENSE.txt`));
+      cpSync(file.license, join4(destination, `${file.family}.LICENSE.txt`));
   }
   return files.map((file) => `NativeFonts/${file.filename}`);
 }
-var TEMPLATES_DIR = join3(dirname2(import.meta.dir), "templates");
+var TEMPLATES_DIR = join4(dirname2(import.meta.dir), "templates");
 function resolveCraftVersion(startDir = import.meta.dir) {
-  let directory = resolve(startDir);
+  let directory = resolve2(startDir);
   while (true) {
     try {
-      const packageJSON = JSON.parse(readFileSync(join3(directory, "package.json"), "utf8"));
+      const packageJSON = JSON.parse(readFileSync2(join4(directory, "package.json"), "utf8"));
       if ((packageJSON.name === "@craft-native/ios" || packageJSON.name === "craft-native") && typeof packageJSON.version === "string" && packageJSON.version.length > 0)
         return packageJSON.version;
     } catch {}
@@ -319,29 +425,29 @@ function hybridConfigProblems(config) {
   return problems;
 }
 function installNativeBundle(source, output) {
-  if (!existsSync(source))
+  if (!existsSync2(source))
     throw new Error(`Native bundle not found: ${source}`);
-  const single = join3(output, "dist", "native-screen.js");
-  const routes = join3(output, "dist", "native-screens");
+  const single = join4(output, "dist", "native-screen.js");
+  const routes = join4(output, "dist", "native-screens");
   mkdirSync(dirname2(single), { recursive: true });
   if (statSync(source).isDirectory()) {
     if (!readdirSync2(source).some((name) => name.endsWith(".js")))
       throw new Error(`Native route bundles not found in ${source}`);
-    if (resolve(source) !== resolve(routes)) {
-      rmSync(routes, { recursive: true, force: true });
+    if (resolve2(source) !== resolve2(routes)) {
+      rmSync2(routes, { recursive: true, force: true });
       cpSync(source, routes, { recursive: true });
     }
     compressNativeSources(routes);
-    rmSync(single, { force: true });
+    rmSync2(single, { force: true });
     return;
   }
-  if (resolve(source) !== resolve(single))
+  if (resolve2(source) !== resolve2(single))
     cpSync(source, single);
   compressNativeSources(single);
-  rmSync(routes, { recursive: true, force: true });
+  rmSync2(routes, { recursive: true, force: true });
 }
 function hasInstalledNativeBundle(output) {
-  return existsSync(join3(output, "dist", "native-screen.js")) || existsSync(join3(output, "dist", "native-screens"));
+  return existsSync2(join4(output, "dist", "native-screen.js")) || existsSync2(join4(output, "dist", "native-screens"));
 }
 function runPostGenerateHook(hook, output, phase = "build") {
   if (!hook)
@@ -447,23 +553,10 @@ function renderAppearance(config) {
     return { interfaceStyle: "Light", statusBarStyle: "UIStatusBarStyleDarkContent" };
   return { interfaceStyle: "Dark", statusBarStyle: "UIStatusBarStyleLightContent" };
 }
-var LINKED_PURPOSES = {
-  NSSpeechRecognitionUsageDescription: "speech recognition",
-  NSMicrophoneUsageDescription: "the microphone",
-  NSCameraUsageDescription: "the camera",
-  NSPhotoLibraryUsageDescription: "your photo library",
-  NSLocationWhenInUseUsageDescription: "your location",
-  NSContactsUsageDescription: "your contacts",
-  NSCalendarsUsageDescription: "your calendar",
-  NSBluetoothAlwaysUsageDescription: "Bluetooth",
-  NSMotionUsageDescription: "motion data",
-  NSFaceIDUsageDescription: "Face ID",
-  NSAppleMusicUsageDescription: "your music"
-};
 function renderUsageDescriptions(config) {
   const entries = [
     [config.enableSpeechRecognition, "NSSpeechRecognitionUsageDescription", `${config.appName} uses speech recognition for voice input.`],
-    [config.enableSpeechRecognition || config.enableAudioRecording, "NSMicrophoneUsageDescription", `${config.appName} uses the microphone to record audio.`],
+    [config.enableSpeechRecognition || config.enableAudioRecording || config.enableVideoRecording, "NSMicrophoneUsageDescription", `${config.appName} uses the microphone to record audio.`],
     [config.enableCamera || config.enableVideoRecording || config.enableQRScanner || config.enableAR, "NSCameraUsageDescription", `${config.appName} uses the camera for photos, video, scanning, and augmented reality.`],
     [config.enableCamera || config.enableVideoRecording, "NSPhotoLibraryUsageDescription", `${config.appName} lets you choose photos and videos from your library.`],
     [config.enableGeolocation || config.enableBackgroundLocation, "NSLocationWhenInUseUsageDescription", `${config.appName} uses your location while you record an activity.`],
@@ -486,8 +579,7 @@ function renderUsageDescriptions(config) {
       return [key, custom];
     if (enabled)
       return [key, value];
-    const linked = LINKED_PURPOSES[key];
-    return linked ? [key, `${config.appName} asks for ${linked} only in a feature that needs it.`] : null;
+    return null;
   }).filter((entry) => entry !== null).map(([key, value]) => plistString(key, value)).join(`
 `);
 }
@@ -652,9 +744,11 @@ function renderRuntimeSettings() {
 `);
 }
 function renderFeatureSettings(config) {
-  const conditions = [];
+  const conditions = iosPermissions(config).filter((name) => name !== "music").map((name) => `CRAFT_PERMISSION_${name.toUpperCase()}`);
   if (config.enableScheduledWorkouts)
     conditions.push("CRAFT_SCHEDULED_WORKOUTS");
+  if (config.enableAppleMusic)
+    conditions.push("CRAFT_APPLE_MUSIC");
   if (!conditions.length)
     return "";
   return `      SWIFT_ACTIVE_COMPILATION_CONDITIONS: "$(inherited) ${conditions.join(" ")}"`;
@@ -729,7 +823,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;
@@ -738,27 +832,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 = join3(output, "Assets.xcassets");
-  const appIcon = join3(catalog, "AppIcon.appiconset");
-  const launchBackground = join3(catalog, "LaunchBackground.colorset");
+  const catalog = join4(output, "Assets.xcassets");
+  const appIcon = join4(catalog, "AppIcon.appiconset");
+  const launchBackground = join4(catalog, "LaunchBackground.colorset");
   mkdirSync(appIcon, { recursive: true });
   mkdirSync(launchBackground, { recursive: true });
-  writeFileSync(join3(catalog, "Contents.json"), `${JSON.stringify({ info: { author: "xcode", version: 1 } }, null, 2)}
+  writeFileSync2(join4(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))
+    if (!existsSync2(config.appIconPath))
       throw new Error(`App icon not found: ${config.appIconPath}`);
-    writeOpaqueIcon(config.appIconPath, join3(appIcon, iconFilename));
+    writeOpaqueIcon(config.appIconPath, join4(appIcon, iconFilename));
   }
-  writeFileSync(join3(appIcon, "Contents.json"), `${JSON.stringify({
+  writeFileSync2(join4(appIcon, "Contents.json"), `${JSON.stringify({
     images: iconFilename ? [{
       filename: iconFilename,
       idiom: "universal",
@@ -785,7 +879,7 @@ function renderAssetCatalog(output, config) {
       idiom: "universal"
     });
   }
-  writeFileSync(join3(launchBackground, "Contents.json"), `${JSON.stringify({
+  writeFileSync2(join4(launchBackground, "Contents.json"), `${JSON.stringify({
     colors,
     info: { author: "xcode", version: 1 }
   }, null, 2)}
@@ -794,8 +888,8 @@ function renderAssetCatalog(output, config) {
 }
 var LAUNCH_LOGO = "LaunchLogo";
 function renderLaunchLogo(catalog, config) {
-  const imageset = join3(catalog, `${LAUNCH_LOGO}.imageset`);
-  rmSync(imageset, { recursive: true, force: true });
+  const imageset = join4(catalog, `${LAUNCH_LOGO}.imageset`);
+  rmSync2(imageset, { recursive: true, force: true });
   if (!config.splashImagePath)
     return;
   mkdirSync(imageset, { recursive: true });
@@ -804,20 +898,20 @@ function renderLaunchLogo(catalog, config) {
   for (const [source, dark] of [[config.splashImagePath, false], [config.splashImagePathDark, true]]) {
     if (!source)
       continue;
-    if (!existsSync(source))
+    if (!existsSync2(source))
       throw new Error(`Splash image not found: ${source}`);
     const extension = source.split(".").pop().toLowerCase();
     if (extension === "svg" || extension === "pdf")
       vector = true;
     const filename = `${LAUNCH_LOGO}${dark ? "-dark" : ""}.${extension}`;
-    cpSync(source, join3(imageset, filename));
+    cpSync(source, join4(imageset, filename));
     images.push({
       ...dark ? { appearances: [{ appearance: "luminosity", value: "dark" }] } : {},
       filename,
       idiom: "universal"
     });
   }
-  writeFileSync(join3(imageset, "Contents.json"), `${JSON.stringify({
+  writeFileSync2(join4(imageset, "Contents.json"), `${JSON.stringify({
     images,
     info: { author: "xcode", version: 1 },
     ...vector ? { properties: { "preserves-vector-representation": true } } : {}
@@ -928,18 +1022,18 @@ function renderOfflinePage(config) {
 `;
 }
 function syncWebAssets(source, output) {
-  const sourcePath = resolve(source);
-  if (!existsSync(sourcePath))
+  const sourcePath = resolve2(source);
+  if (!existsSync2(sourcePath))
     throw new Error(`Web asset path not found: ${source}`);
-  const distDir = join3(output, "dist");
-  rmSync(distDir, { recursive: true, force: true });
+  const distDir = join4(output, "dist");
+  rmSync2(distDir, { recursive: true, force: true });
   mkdirSync(distDir, { recursive: true });
   if (statSync(sourcePath).isDirectory()) {
     cpSync(sourcePath, distDir, { recursive: true });
   } else {
-    cpSync(sourcePath, join3(distDir, "index.html"));
+    cpSync(sourcePath, join4(distDir, "index.html"));
   }
-  if (!existsSync(join3(distDir, "index.html"))) {
+  if (!existsSync2(join4(distDir, "index.html"))) {
     throw new Error(`Web asset directory must contain index.html: ${source}`);
   }
 }
@@ -949,7 +1043,7 @@ function resolveRuntimeDir(override) {
   const dir = override ?? process.env.CRAFT_IOS_RUNTIME;
   if (!dir)
     return null;
-  if (!existsSync(dir)) {
+  if (!existsSync2(dir)) {
     const source = override === undefined ? "CRAFT_IOS_RUNTIME points at" : "runtimeDir is";
     throw new Error(`${source} ${dir}, which does not exist.`);
   }
@@ -959,43 +1053,71 @@ var RUNTIME_ARCHIVES = {
   device: ["libcraft-ios.a"],
   simulator: ["libcraft-ios-simulator-arm64.a", "libcraft-ios-simulator-x64.a"]
 };
-async function installRuntime(output, runtimeDir) {
+async function installRuntime(output, runtimeDir, config) {
+  if (config)
+    verifyRuntimeProfile(runtimeDir, config);
   const resolved = Object.entries(RUNTIME_ARCHIVES).map(([sdk, archives]) => {
-    const present = archives.filter((a) => existsSync(join3(runtimeDir, a)));
+    const present = archives.filter((a) => existsSync2(join4(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 = join3(output, "Runtime");
-  rmSync(dest, { recursive: true, force: true });
-  for (const { sdk, archives, present } of resolved) {
-    const sdkDir = join3(dest, sdk);
-    mkdirSync(sdkDir, { recursive: true });
-    const target = join3(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.`);
+  const installed = join4(output, "Runtime");
+  const staging = mkdtempSync2(join4(output, ".craft-runtime-"));
+  const dest = join4(staging, "next");
+  const previous = join4(staging, "previous");
+  try {
+    for (const { sdk, archives, present } of resolved) {
+      const sdkDir = join4(dest, sdk);
+      mkdirSync(sdkDir, { recursive: true });
+      const target = join4(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(join4(runtimeDir, present[0]), target);
+      } else {
+        await $`lipo -create ${present.map((a) => join4(runtimeDir, a))} -output ${target}`.quiet();
       }
-      cpSync(join3(runtimeDir, present[0]), target);
-    } else {
-      await $`lipo -create ${present.map((a) => join3(runtimeDir, a))} -output ${target}`.quiet();
     }
+    if (config)
+      writeInstalledProfile(dest, config);
+    if (existsSync2(installed))
+      renameSync(installed, previous);
+    try {
+      renameSync(dest, installed);
+    } catch (error) {
+      if (existsSync2(previous))
+        renameSync(previous, installed);
+      throw error;
+    }
+    return true;
+  } finally {
+    rmSync2(staging, { recursive: true, force: true });
   }
-  return true;
 }
-async function refreshRuntime(output, override) {
-  if (!existsSync(join3(output, "Runtime")))
+async function refreshRuntime(output, config, override) {
+  if (!existsSync2(join4(output, "Runtime")))
     return;
   const dir = resolveRuntimeDir(override);
   if (!dir) {
+    verifyInstalledProfile(join4(output, "Runtime"), config);
     console.log("   Keeping the Zig runtime installed at init (no runtime directory configured)");
     return;
   }
-  await installRuntime(output, dir);
+  await installRuntime(output, dir, config);
   console.log("   Refreshed the Zig runtime from", dir);
 }
+async function installAppRuntime(output, source, config) {
+  return withAppRuntime(source, config, async (directory) => {
+    verifyRuntimeProfile(directory, config);
+    await installRuntime(output, directory, config);
+    writeInstalledProfile(join4(output, "Runtime"), config, resolve2(source));
+    return true;
+  });
+}
 function productName(name) {
   const words = name.split(/[^A-Za-z0-9]+/).filter(Boolean);
   const joined = words.map((word) => word[0].toUpperCase() + word.slice(1)).join("");
@@ -1006,45 +1128,63 @@ function productName(name) {
 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 writeSource = (path, source) => {
+    const rendered = renderPermissionSource(source, config);
+    if (!existsSync2(path) || readFileSync2(path, "utf8") !== rendered)
+      writeFileSync2(path, rendered);
+  };
   const name = productName(config.appName);
   const shortcutSource = appShortcutsSwift(config.appShortcuts, config.urlSchemes);
-  mkdirSync(join3(output, "Sources"), { recursive: true });
-  mkdirSync(join3(output, "Shared"), { recursive: true });
-  const swiftTemplate = readFileSync(join3(TEMPLATES_DIR, "CraftApp.swift"), "utf-8");
+  mkdirSync(join4(output, "Sources"), { recursive: true });
+  mkdirSync(join4(output, "Shared"), { recursive: true });
+  const swiftTemplate = readFileSync2(join4(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);
-  writeFileSync(join3(output, "Sources", `${name}App.swift`), swiftSource);
-  writeFileSync(join3(output, "Sources", "CraftAppShortcuts.swift"), shortcutSource);
-  cpSync(join3(TEMPLATES_DIR, "CraftNativeScreen.swift"), join3(output, "Sources", "CraftNativeScreen.swift"));
-  cpSync(join3(TEMPLATES_DIR, "CraftNativeFlatList.swift"), join3(output, "Sources", "CraftNativeFlatList.swift"));
-  cpSync(join3(TEMPLATES_DIR, "CraftNativeActions.swift"), join3(output, "Sources", "CraftNativeActions.swift"));
-  cpSync(join3(TEMPLATES_DIR, "CraftHealth.swift"), join3(output, "Sources", "CraftHealth.swift"));
-  cpSync(join3(TEMPLATES_DIR, "CraftMusic.swift"), join3(output, "Sources", "CraftMusic.swift"));
-  cpSync(join3(TEMPLATES_DIR, "CraftBluetooth.swift"), join3(output, "Sources", "CraftBluetooth.swift"));
-  cpSync(join3(TEMPLATES_DIR, "CraftHeartRate.swift"), join3(output, "Sources", "CraftHeartRate.swift"));
-  cpSync(join3(TEMPLATES_DIR, "CraftRecordingArchive.swift"), join3(output, "Sources", "CraftRecordingArchive.swift"));
-  cpSync(join3(TEMPLATES_DIR, "CraftPersistentStorage.swift"), join3(output, "Sources", "CraftPersistentStorage.swift"));
-  cpSync(join3(TEMPLATES_DIR, "CraftScheduledWorkouts.swift"), join3(output, "Sources", "CraftScheduledWorkouts.swift"));
-  cpSync(join3(TEMPLATES_DIR, "CraftNativeMutation.swift"), join3(output, "Sources", "CraftNativeMutation.swift"));
-  cpSync(join3(TEMPLATES_DIR, "CraftNativeUI.swift"), join3(output, "Sources", "CraftNativeUI.swift"));
-  cpSync(join3(TEMPLATES_DIR, "CraftNativeServices.swift"), join3(output, "Sources", "CraftNativeServices.swift"));
-  cpSync(join3(TEMPLATES_DIR, "CraftNativeFiles.swift"), join3(output, "Sources", "CraftNativeFiles.swift"));
-  cpSync(join3(TEMPLATES_DIR, "CraftVoiceRecording.swift"), join3(output, "Sources", "CraftVoiceRecording.swift"));
-  cpSync(join3(TEMPLATES_DIR, "CraftWebAudio.swift"), join3(output, "Sources", "CraftWebAudio.swift"));
-  cpSync(join3(TEMPLATES_DIR, "CraftHybrid.swift"), join3(output, "Sources", "CraftHybrid.swift"));
-  writeFileSync(join3(output, "Sources", "CraftCrashReporter.swift"), readFileSync(join3(TEMPLATES_DIR, "CraftCrashReporter.swift"), "utf-8").replace(/\{\{CRAFT_VERSION\}\}/g, CRAFT_VERSION));
-  cpSync(join3(TEMPLATES_DIR, "CraftLiveActivities.swift"), join3(output, "Sources", "CraftLiveActivities.swift"));
-  cpSync(join3(TEMPLATES_DIR, "CraftActivityAttributes.swift"), join3(output, "Shared", "CraftActivityAttributes.swift"));
+  writeSource(join4(output, "Sources", `${name}App.swift`), swiftSource);
+  writeSource(join4(output, "Sources", "CraftAppShortcuts.swift"), shortcutSource);
+  writeSource(join4(output, "Sources", "CraftNativeScreen.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftNativeScreen.swift"), "utf8"));
+  writeSource(join4(output, "Sources", "CraftNativeFlatList.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftNativeFlatList.swift"), "utf8"));
+  writeSource(join4(output, "Sources", "CraftNativeActions.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftNativeActions.swift"), "utf8"));
+  writeSource(join4(output, "Sources", "CraftHealth.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftHealth.swift"), "utf8"));
+  writeSource(join4(output, "Sources", "CraftMusic.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftMusic.swift"), "utf8"));
+  writeSource(join4(output, "Sources", "CraftBluetooth.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftBluetooth.swift"), "utf8"));
+  writeSource(join4(output, "Sources", "CraftHeartRate.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftHeartRate.swift"), "utf8"));
+  writeSource(join4(output, "Sources", "CraftRecordingArchive.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftRecordingArchive.swift"), "utf8"));
+  writeSource(join4(output, "Sources", "CraftPersistentStorage.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftPersistentStorage.swift"), "utf8"));
+  writeSource(join4(output, "Sources", "CraftScheduledWorkouts.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftScheduledWorkouts.swift"), "utf8"));
+  writeSource(join4(output, "Sources", "CraftNativeMutation.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftNativeMutation.swift"), "utf8"));
+  writeSource(join4(output, "Sources", "CraftNativeUI.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftNativeUI.swift"), "utf8"));
+  writeSource(join4(output, "Sources", "CraftNativeServices.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftNativeServices.swift"), "utf8"));
+  writeSource(join4(output, "Sources", "CraftNativeFiles.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftNativeFiles.swift"), "utf8"));
+  writeSource(join4(output, "Sources", "CraftVoiceRecording.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftVoiceRecording.swift"), "utf8"));
+  writeSource(join4(output, "Sources", "CraftWebAudio.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftWebAudio.swift"), "utf8"));
+  writeSource(join4(output, "Sources", "CraftHybrid.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftHybrid.swift"), "utf8"));
+  writeSource(join4(output, "Sources", "CraftCrashReporter.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftCrashReporter.swift"), "utf-8").replace(/\{\{CRAFT_VERSION\}\}/g, CRAFT_VERSION));
+  writeSource(join4(output, "Sources", "CraftLiveActivities.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftLiveActivities.swift"), "utf8"));
+  writeSource(join4(output, "Shared", "CraftActivityAttributes.swift"), readFileSync2(join4(TEMPLATES_DIR, "CraftActivityAttributes.swift"), "utf8"));
   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;
-    mkdirSync(join3(output, folder), { recursive: true });
-    const source = readFileSync(join3(TEMPLATES_DIR, template), "utf8").replace(/\{\{APP_NAME\}\}/g, name).replace(/\{\{HEALTH_KIT_ENABLED\}\}/g, config.enableHealthKit ? "true" : "false");
-    writeFileSync(join3(output, folder, filename), source);
+    mkdirSync(join4(output, folder), { recursive: true });
+    const source = readFileSync2(join4(TEMPLATES_DIR, template), "utf8").replace(/\{\{APP_NAME\}\}/g, name).replace(/\{\{HEALTH_KIT_ENABLED\}\}/g, config.enableHealthKit ? "true" : "false");
+    writeSource(join4(output, folder, filename), source);
   }
 }
+function refreshUsageDescriptions(output, config) {
+  const path = join4(output, "Info.plist");
+  if (!existsSync2(path))
+    return;
+  const managed = /\s*<key>(?:NS(?:SpeechRecognition|Microphone|Camera|PhotoLibrary|LocationWhenInUse|LocationAlwaysAndWhenInUse|Contacts|Calendars|BluetoothAlways|Motion|LocalNetwork|HealthShare|HealthUpdate|FaceID|AppleMusic)|NFCReader)UsageDescription<\/key>\s*<string>[\s\S]*?<\/string>/g;
+  const plist = readFileSync2(path, "utf8").replace(managed, "");
+  const end = plist.lastIndexOf("</dict>");
+  if (end < 0)
+    throw new Error("Info.plist must contain a root dictionary");
+  writeFileSync2(path, `${plist.slice(0, end).trimEnd()}
+${renderUsageDescriptions(config)}
+${plist.slice(end)}`);
+}
 async function init(options) {
   const { name: displayName, bundleId, teamId, output } = options;
   const name = productName(displayName);
@@ -1052,11 +1192,11 @@ async function init(options) {
 \u26A1 Initializing Craft iOS project: ${displayName}`);
   console.log(`   Output: ${output}
 `);
-  const dirs = [output, join3(output, "Sources"), join3(output, "Shared"), join3(output, "dist")];
+  const dirs = [output, join4(output, "Sources"), join4(output, "Shared"), join4(output, "dist")];
   if (options.config?.enableWatchApp)
-    dirs.push(join3(output, "WatchApp"), join3(output, "WatchExtension"));
+    dirs.push(join4(output, "WatchApp"), join4(output, "WatchExtension"));
   for (const dir of dirs) {
-    if (!existsSync(dir)) {
+    if (!existsSync2(dir)) {
       mkdirSync(dir, { recursive: true });
     }
   }
@@ -1086,10 +1226,20 @@ async function init(options) {
 `));
   if (Object.keys(config.shareStorage ?? {}).length)
     config.enableSecureStorage = true;
-  writeFileSync(join3(output, "craft.config.json"), JSON.stringify(config, null, 2));
+  const runtimeDir = resolveRuntimeDir(options.runtimeDir);
+  const runtimeSource = options.runtimeSource === null || options.runtimeDir === null ? undefined : options.runtimeSource ?? process.env.CRAFT_IOS_RUNTIME_SOURCE;
+  if (runtimeSource && runtimeDir)
+    throw new Error("Choose runtimeSource or runtimeDir, not both");
+  const hasRuntime = runtimeSource ? await installAppRuntime(output, runtimeSource, config) : runtimeDir ? await installRuntime(output, runtimeDir, config) : false;
+  if (hasRuntime) {
+    console.log("   Linked the Zig runtime from", runtimeSource ?? runtimeDir);
+  } else {
+    rmSync2(join4(output, "Runtime"), { recursive: true, force: true });
+  }
+  writeFileSync2(join4(output, "craft.config.json"), JSON.stringify(config, null, 2));
   writeShell(output, config);
   const nativeFontFiles = syncNativeFonts(config.nativeFonts, output);
-  const infoPlistTemplate = readFileSync(join3(TEMPLATES_DIR, "Info.plist.template"), "utf-8");
+  const infoPlistTemplate = readFileSync2(join4(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(/\{\{NATIVE_FONTS\}\}/g, nativeFontFiles.length ? `    <key>UIAppFonts</key>
     <array>
 ${plistArray(nativeFontFiles, 2)}
@@ -1097,8 +1247,8 @@ ${plistArray(nativeFontFiles, 2)}
     <true/>
     <key>NSSupportsLiveActivitiesFrequentUpdates</key>
     <true/>` : "");
-  writeFileSync(join3(output, "Info.plist"), infoPlist);
-  const projectYmlTemplate = readFileSync(join3(TEMPLATES_DIR, "project.yml.template"), "utf-8");
+  writeFileSync2(join4(output, "Info.plist"), infoPlist);
+  const projectYmlTemplate = readFileSync2(join4(TEMPLATES_DIR, "project.yml.template"), "utf-8");
   const nativeDependencies = [];
   if (config.enableLiveActivities)
     nativeDependencies.push(`      - target: ${name}LiveActivity`);
@@ -1153,38 +1303,31 @@ ${plistArray(nativeFontFiles, 2)}
       APPLICATION_EXTENSION_API_ONLY: YES
       SKIP_INSTALL: YES`);
   }
-  const runtimeDir = resolveRuntimeDir(options.runtimeDir);
-  const hasRuntime = runtimeDir ? await installRuntime(output, runtimeDir) : false;
-  if (hasRuntime) {
-    console.log("   Linked the Zig runtime from", runtimeDir);
-  } else {
-    rmSync(join3(output, "Runtime"), { recursive: true, force: true });
-  }
   const projectYml = projectYmlTemplate.replace(/\{\{NATIVE_FONT_RESOURCES\}\}/g, nativeFontFiles.length ? `      - path: NativeFonts
         type: folder
         buildPhase: resources` : "").replace(/\{\{CRAFT_RUNTIME_SETTINGS\}\}/g, hasRuntime ? renderRuntimeSettings() : "").replace(/\{\{FEATURE_SETTINGS\}\}/g, renderFeatureSettings(config)).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(join3(output, "project.yml"), projectYml);
-  writeFileSync(join3(output, "Craft.entitlements"), renderEntitlements(config));
-  writeFileSync(join3(output, "PrivacyInfo.xcprivacy"), renderPrivacyManifest(config));
+  writeFileSync2(join4(output, "project.yml"), projectYml);
+  writeFileSync2(join4(output, "Craft.entitlements"), renderEntitlements(config));
+  writeFileSync2(join4(output, "PrivacyInfo.xcprivacy"), renderPrivacyManifest(config));
   renderAssetCatalog(output, config);
   if (config.enableLiveActivities) {
-    mkdirSync(join3(output, "WidgetExtension"), { recursive: true });
-    const widgetInfo = readFileSync(join3(TEMPLATES_DIR, "WidgetExtension.Info.plist"), "utf8");
-    writeFileSync(join3(output, "WidgetExtension", "Info.plist"), widgetInfo);
+    mkdirSync(join4(output, "WidgetExtension"), { recursive: true });
+    const widgetInfo = readFileSync2(join4(TEMPLATES_DIR, "WidgetExtension.Info.plist"), "utf8");
+    writeFileSync2(join4(output, "WidgetExtension", "Info.plist"), widgetInfo);
   }
   if (config.enableWatchApp) {
-    const watchInfo = readFileSync(join3(TEMPLATES_DIR, "WatchApp.Info.plist.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId);
-    writeFileSync(join3(output, "WatchApp", "Info.plist"), watchInfo);
-    writeFileSync(join3(output, "WatchApp", "Watch.entitlements"), renderWatchEntitlements(config));
-    const watchExtensionInfo = readFileSync(join3(TEMPLATES_DIR, "WatchExtension.Info.plist.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId).replace(/\{\{HEALTH_USAGE_DESCRIPTIONS\}\}/g, config.enableHealthKit ? `${plistString("NSHealthShareUsageDescription", `${displayName} reads health data you choose to share.`)}
+    const watchInfo = readFileSync2(join4(TEMPLATES_DIR, "WatchApp.Info.plist.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId);
+    writeFileSync2(join4(output, "WatchApp", "Info.plist"), watchInfo);
+    writeFileSync2(join4(output, "WatchApp", "Watch.entitlements"), renderWatchEntitlements(config));
+    const watchExtensionInfo = readFileSync2(join4(TEMPLATES_DIR, "WatchExtension.Info.plist.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId).replace(/\{\{HEALTH_USAGE_DESCRIPTIONS\}\}/g, config.enableHealthKit ? `${plistString("NSHealthShareUsageDescription", `${displayName} reads health data you choose to share.`)}
 ${plistString("NSHealthUpdateUsageDescription", `${displayName} writes health data only with your permission.`)}` : "");
-    writeFileSync(join3(output, "WatchExtension", "Info.plist"), watchExtensionInfo);
-    writeFileSync(join3(output, "WatchExtension", "Watch.entitlements"), renderWatchEntitlements(config));
+    writeFileSync2(join4(output, "WatchExtension", "Info.plist"), watchExtensionInfo);
+    writeFileSync2(join4(output, "WatchExtension", "Watch.entitlements"), renderWatchEntitlements(config));
   }
-  writeFileSync(join3(output, "dist", "index.html"), renderOfflinePage(config));
+  writeFileSync2(join4(output, "dist", "index.html"), renderOfflinePage(config));
   if (usesNativeBundle(config)) {
     if (config.nativeBundle)
       installNativeBundle(config.nativeBundle, output);
@@ -1211,11 +1354,11 @@ async function build(options) {
   const { htmlPath, nativeBundlePath, devServer, output, generateProject = true } = options;
   console.log(`
 \uD83D\uDCE6 Building Craft iOS project...`);
-  const configPath = join3(output, "craft.config.json");
-  if (!existsSync(configPath)) {
+  const configPath = join4(output, "craft.config.json");
+  if (!existsSync2(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.`);
   }
@@ -1240,7 +1383,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) {
@@ -1256,7 +1399,20 @@ async function build(options) {
       console.warn("   \u26A0 nativeScreens is set but there is no native bundle: every path opens in the web view.");
     }
   }
-  await refreshRuntime(output, options.runtimeDir);
+  const profilePath = join4(output, "Runtime", "profile.json");
+  const savedProfile = existsSync2(profilePath) ? JSON.parse(readFileSync2(profilePath, "utf8")) : undefined;
+  const runtimeSource = options.runtimeSource === null || options.runtimeDir === null ? undefined : options.runtimeSource ?? process.env.CRAFT_IOS_RUNTIME_SOURCE ?? savedProfile?.source;
+  if (runtimeSource && existsSync2(join4(output, "Runtime"))) {
+    if (options.runtimeDir)
+      throw new Error("Choose runtimeSource or runtimeDir, not both");
+    await installAppRuntime(output, runtimeSource, config);
+  } else {
+    if (savedProfile && savedProfile.mask !== iosPermissionMask(config))
+      throw new Error("Installed Zig runtime permission profile is stale; provide runtimeSource to rebuild it");
+    await refreshRuntime(output, config, options.runtimeDir);
+  }
+  writeShell(output, config);
+  refreshUsageDescriptions(output, config);
   if (!generateProject)
     return;
   try {
@@ -1283,7 +1439,7 @@ async function open(options) {
   if (!xcodeproj) {
     throw new Error(`No Xcode project found in ${output}. Run 'craft ios build' first.`);
   }
-  const projectPath = join3(output, xcodeproj);
+  const projectPath = join4(output, xcodeproj);
   console.log(`\uD83D\uDE80 Opening ${xcodeproj}...`);
   await $`open ${projectPath}`;
 }
@@ -1337,8 +1493,8 @@ async function showSimulator() {
   const selected = await $`xcode-select -p`.quiet().nothrow();
   const developer = selected.exitCode === 0 ? selected.stdout.toString().trim() : "";
   if (developer) {
-    const app = join3(developer, "Applications", "Simulator.app");
-    if (existsSync(app)) {
+    const app = join4(developer, "Applications", "Simulator.app");
+    if (existsSync2(app)) {
       await $`open ${app}`.quiet().nothrow();
       return;
     }
@@ -1353,12 +1509,12 @@ async function run(options) {
   if (!xcodeproj) {
     throw new Error(`No Xcode project found in ${output}`);
   }
-  const projectPath = join3(output, xcodeproj);
+  const projectPath = join4(output, xcodeproj);
   const appName = xcodeproj.replace(".xcodeproj", "");
-  const configPath = join3(output, "craft.config.json");
-  if (!existsSync(configPath))
+  const configPath = join4(output, "craft.config.json");
+  if (!existsSync2(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();
@@ -1368,10 +1524,10 @@ async function run(options) {
     console.log(`   Device: ${device.name} (${device.runtime})`);
     try {
       await bootSimulator(device);
-      const derivedData = join3(output, "build");
-      const product = join3(derivedData, "Build", "Products", "Debug-iphonesimulator", `${appName}.app`);
+      const derivedData = join4(output, "build");
+      const product = join4(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)) {
+      if (!existsSync2(product)) {
         throw new Error(`xcodebuild reported success but ${product} does not exist. ` + "The scheme may build a different product name than the project.");
       }
       await $`xcrun simctl install ${device.udid} ${product}`;
@@ -1477,7 +1633,7 @@ async function main() {
         });
         break;
       case "audit-sources": {
-        const root = resolve2(values["app-root"] || ".");
+        const root = resolve3(values["app-root"] || ".");
         assertNoApplicationSwiftSources(root);
         console.log(`\u2705 No application-owned Swift sources found in ${root}`);
         break;