@auraindustry/aurajs 0.1.3 → 0.1.5

package/src/mobile/ios/build.mjs

@@ -0,0 +1,1323 @@
+import { spawnSync } from 'node:child_process';
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+
+const IOS_BUILD_MANIFEST_SCHEMA = 'aurajs.ios-build-manifest.v1';
+const IOS_BUILD_CONFIGURATION = 'Release';
+const IOS_RESOURCE_ROOT_NAME = 'aurajs';
+const IOS_HOST_XCFRAMEWORK_NAME = 'aurajs-host.xcframework';
+const IOS_HOST_FRAMEWORK_DIRECTORY = 'aurajs-host.framework';
+const IOS_HOST_FRAMEWORK_BINARY = 'aurajs-host';
+const IOS_DEVICE_LIBRARY_IDENTIFIER = 'ios-arm64';
+const IOS_SIMULATOR_LIBRARY_IDENTIFIER = 'ios-arm64-simulator';
+const IOS_XCODE_PROJECT_NAME = 'AuraJSApp.xcodeproj';
+const IOS_XCODE_PROJECT_FILE = 'project.pbxproj';
+const IOS_XCODE_SCHEME_NAME = 'AuraJSApp';
+const IOS_XCODE_PRODUCT_NAME = 'AuraJSApp.app';
+const IOS_EXPORT_OPTIONS_FILE = 'ExportOptions.plist';
+const IOS_DERIVED_DATA_ROOT = 'derived-data';
+const TEMPLATE_ROOT = resolve(
+  new URL('../../../../platform/ios/template/', import.meta.url).pathname,
+);
+const DIST_ROOT = resolve(
+  new URL('../../../../platform/dist/ios/', import.meta.url).pathname,
+);
+const HOST_XCFRAMEWORK_ROOT = resolve(
+  new URL('../../../../platform/ios/host/aurajs-host.xcframework/', import.meta.url).pathname,
+);
+
+const IOS_GENERATED_PROJECT_PBXPROJ = `// !$*UTF8*$!
+{
+\tarchiveVersion = 1;
+\tclasses = {
+\t};
+\tobjectVersion = 56;
+\tobjects = {
+
+/* Begin PBXBuildFile section */
+\t\tA1B2C3D41E00000100000001 /* AppDelegate.swift in Sources */ = {isa = PBXBuildFile; fileRef = A1B2C3D31E00000100000001 /* AppDelegate.swift */; };
+\t\tA1B2C3D51E00000100000001 /* UIKit.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = A1B2C3D61E00000100000001 /* UIKit.framework */; };
+/* End PBXBuildFile section */
+
+/* Begin PBXFileReference section */
+\t\tA1B2C3D01E00000100000001 /* AuraJSApp.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = AuraJSApp.app; sourceTree = BUILT_PRODUCTS_DIR; };
+\t\tA1B2C3D31E00000100000001 /* AppDelegate.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AuraJSApp/AppDelegate.swift; sourceTree = SOURCE_ROOT; };
+\t\tA1B2C3D21E00000100000001 /* Info.plist */ = {isa = PBXFileReference; lastKnownFileType = text.plist.xml; path = AuraJSApp/Info.plist; sourceTree = SOURCE_ROOT; };
+\t\tA1B2C3D61E00000100000001 /* UIKit.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = UIKit.framework; path = System/Library/Frameworks/UIKit.framework; sourceTree = SDKROOT; };
+/* End PBXFileReference section */
+
+/* Begin PBXFrameworksBuildPhase section */
+\t\tA1B2C3D81E00000100000001 /* Frameworks */ = {
+\t\t\tisa = PBXFrameworksBuildPhase;
+\t\t\tbuildActionMask = 2147483647;
+\t\t\tfiles = (
+\t\t\t\tA1B2C3D51E00000100000001 /* UIKit.framework in Frameworks */,
+\t\t\t);
+\t\t\trunOnlyForDeploymentPostprocessing = 0;
+\t\t};
+/* End PBXFrameworksBuildPhase section */
+
+/* Begin PBXShellScriptBuildPhase section */
+\t\tA1B2C3D61E00000100000002 /* Sync AuraJS Runtime */ = {
+\t\t\tisa = PBXShellScriptBuildPhase;
+\t\t\tbuildActionMask = 2147483647;
+\t\t\tfiles = (
+\t\t\t);
+\t\t\tinputPaths = (
+\t\t\t);
+\t\t\tname = "Sync AuraJS Runtime";
+\t\t\toutputPaths = (
+\t\t\t);
+\t\t\trunOnlyForDeploymentPostprocessing = 0;
+\t\t\tshellPath = /bin/sh;
+\t\t\tshellScript = "set -eu\\nAURAJS_RESOURCE_ROOT=\\\"\${PROJECT_DIR}/../staging/aurajs\\\"\\nAURAJS_RESOURCE_DEST=\\\"\${TARGET_BUILD_DIR}/\${UNLOCALIZED_RESOURCES_FOLDER_PATH}/aurajs\\\"\\nif [ ! -d \\\"\${AURAJS_RESOURCE_ROOT}\\\" ]; then\\n  echo \\\"Missing AuraJS staged resources at \${AURAJS_RESOURCE_ROOT}. Run the AuraJS iOS staging build first.\\\" >&2\\n  exit 1\\nfi\\nrm -rf \\\"\${AURAJS_RESOURCE_DEST}\\\"\\nmkdir -p \\\"$(dirname \\\"\${AURAJS_RESOURCE_DEST}\\\")\\\"\\nditto \\\"\${AURAJS_RESOURCE_ROOT}\\\" \\\"\${AURAJS_RESOURCE_DEST}\\\"\\ncase \\\"\${PLATFORM_NAME}\\\" in\\n  iphonesimulator)\\n    AURAJS_FRAMEWORK_SLICE=ios-arm64-simulator\\n    ;;\\n  iphoneos)\\n    AURAJS_FRAMEWORK_SLICE=ios-arm64\\n    ;;\\n  *)\\n    echo \\\"Unsupported Apple platform: \${PLATFORM_NAME}\\\" >&2\\n    exit 1\\n    ;;\\nesac\\nAURAJS_FRAMEWORK_SOURCE=\\\"\${PROJECT_DIR}/../host/aurajs-host.xcframework/\${AURAJS_FRAMEWORK_SLICE}/aurajs-host.framework\\\"\\nAURAJS_FRAMEWORK_DEST=\\\"\${TARGET_BUILD_DIR}/\${FRAMEWORKS_FOLDER_PATH}/aurajs-host.framework\\\"\\nif [ ! -d \\\"\${AURAJS_FRAMEWORK_SOURCE}\\\" ]; then\\n  echo \\\"Missing AuraJS host framework slice at \${AURAJS_FRAMEWORK_SOURCE}. Run the AuraJS iOS host-artifact build first.\\\" >&2\\n  exit 1\\nfi\\nrm -rf \\\"\${AURAJS_FRAMEWORK_DEST}\\\"\\nmkdir -p \\\"$(dirname \\\"\${AURAJS_FRAMEWORK_DEST}\\\")\\\"\\nditto \\\"\${AURAJS_FRAMEWORK_SOURCE}\\\" \\\"\${AURAJS_FRAMEWORK_DEST}\\\"\\n";
+\t\t};
+/* End PBXShellScriptBuildPhase section */
+
+/* Begin PBXGroup section */
+\t\tA1B2C3DB1E00000100000001 = {
+\t\t\tisa = PBXGroup;
+\t\t\tchildren = (
+\t\t\t\tA1B2C3DD1E00000100000001 /* AuraJSApp */,
+\t\t\t\tA1B2C3DC1E00000100000001 /* Frameworks */,
+\t\t\t\tA1B2C3DE1E00000100000001 /* Products */,
+\t\t\t);
+\t\t\tsourceTree = "<group>";
+\t\t};
+\t\tA1B2C3DC1E00000100000001 /* Frameworks */ = {
+\t\t\tisa = PBXGroup;
+\t\t\tchildren = (
+\t\t\t\tA1B2C3D61E00000100000001 /* UIKit.framework */,
+\t\t\t);
+\t\t\tname = Frameworks;
+\t\t\tsourceTree = "<group>";
+\t\t};
+\t\tA1B2C3DD1E00000100000001 /* AuraJSApp */ = {
+\t\t\tisa = PBXGroup;
+\t\t\tchildren = (
+\t\t\t\tA1B2C3D31E00000100000001 /* AppDelegate.swift */,
+\t\t\t\tA1B2C3D21E00000100000001 /* Info.plist */,
+\t\t\t);
+\t\t\tname = AuraJSApp;
+\t\t\tsourceTree = "<group>";
+\t\t};
+\t\tA1B2C3DE1E00000100000001 /* Products */ = {
+\t\t\tisa = PBXGroup;
+\t\t\tchildren = (
+\t\t\t\tA1B2C3D01E00000100000001 /* AuraJSApp.app */,
+\t\t\t);
+\t\t\tname = Products;
+\t\t\tsourceTree = "<group>";
+\t\t};
+/* End PBXGroup section */
+
+/* Begin PBXNativeTarget section */
+\t\tA1B2C3D71E00000100000001 /* AuraJSApp */ = {
+\t\t\tisa = PBXNativeTarget;
+\t\t\tbuildConfigurationList = A1B2C3E31E00000100000001 /* Build configuration list for PBXNativeTarget "AuraJSApp" */;
+\t\t\tbuildPhases = (
+\t\t\t\tA1B2C3D91E00000100000001 /* Sources */,
+\t\t\t\tA1B2C3D81E00000100000001 /* Frameworks */,
+\t\t\t\tA1B2C3DA1E00000100000001 /* Resources */,
+\t\t\t\tA1B2C3D61E00000100000002 /* Sync AuraJS Runtime */,
+\t\t\t);
+\t\t\tbuildRules = (
+\t\t\t);
+\t\t\tdependencies = (
+\t\t\t);
+\t\t\tname = AuraJSApp;
+\t\t\tproductName = AuraJSApp;
+\t\t\tproductReference = A1B2C3D01E00000100000001 /* AuraJSApp.app */;
+\t\t\tproductType = "com.apple.product-type.application";
+\t\t};
+/* End PBXNativeTarget section */
+
+/* Begin PBXProject section */
+\t\tA1B2C3DF1E00000100000001 /* Project object */ = {
+\t\t\tisa = PBXProject;
+\t\t\tattributes = {
+\t\t\t\tBuildIndependentTargetsInParallel = 1;
+\t\t\t\tLastSwiftUpdateCheck = 1600;
+\t\t\t\tLastUpgradeCheck = 1600;
+\t\t\t\tTargetAttributes = {
+\t\t\t\t\tA1B2C3D71E00000100000001 = {
+\t\t\t\t\t\tCreatedOnToolsVersion = 16.0;
+\t\t\t\t\t};
+\t\t\t\t};
+\t\t\t};
+\t\t\tbuildConfigurationList = A1B2C3E01E00000100000001 /* Build configuration list for PBXProject "AuraJSApp" */;
+\t\t\tcompatibilityVersion = "Xcode 14.0";
+\t\t\tdevelopmentRegion = en;
+\t\t\thasScannedForEncodings = 0;
+\t\t\tknownRegions = (
+\t\t\t\ten,
+\t\t\t\tBase,
+\t\t\t);
+\t\t\tmainGroup = A1B2C3DB1E00000100000001;
+\t\t\tproductRefGroup = A1B2C3DE1E00000100000001 /* Products */;
+\t\t\tprojectDirPath = "";
+\t\t\tprojectRoot = "";
+\t\t\ttargets = (
+\t\t\t\tA1B2C3D71E00000100000001 /* AuraJSApp */,
+\t\t\t);
+\t\t};
+/* End PBXProject section */
+
+/* Begin PBXResourcesBuildPhase section */
+\t\tA1B2C3DA1E00000100000001 /* Resources */ = {
+\t\t\tisa = PBXResourcesBuildPhase;
+\t\t\tbuildActionMask = 2147483647;
+\t\t\tfiles = (
+\t\t\t);
+\t\t\trunOnlyForDeploymentPostprocessing = 0;
+\t\t};
+/* End PBXResourcesBuildPhase section */
+
+/* Begin PBXSourcesBuildPhase section */
+\t\tA1B2C3D91E00000100000001 /* Sources */ = {
+\t\t\tisa = PBXSourcesBuildPhase;
+\t\t\tbuildActionMask = 2147483647;
+\t\t\tfiles = (
+\t\t\t\tA1B2C3D41E00000100000001 /* AppDelegate.swift in Sources */,
+\t\t\t);
+\t\t\trunOnlyForDeploymentPostprocessing = 0;
+\t\t};
+/* End PBXSourcesBuildPhase section */
+
+/* Begin XCBuildConfiguration section */
+\t\tA1B2C3E11E00000100000001 /* Debug */ = {
+\t\t\tisa = XCBuildConfiguration;
+\t\t\tbuildSettings = {
+\t\t\t\tALWAYS_SEARCH_USER_PATHS = NO;
+\t\t\t\tCLANG_ENABLE_MODULES = YES;
+\t\t\t\tCOPY_PHASE_STRIP = NO;
+\t\t\t\tDEBUG_INFORMATION_FORMAT = dwarf;
+\t\t\t\tENABLE_TESTABILITY = YES;
+\t\t\t\tGCC_C_LANGUAGE_STANDARD = gnu17;
+\t\t\t\tGCC_NO_COMMON_BLOCKS = YES;
+\t\t\t\tIPHONEOS_DEPLOYMENT_TARGET = 16.0;
+\t\t\t\tSDKROOT = iphoneos;
+\t\t\t\tSWIFT_VERSION = 5.0;
+\t\t\t};
+\t\t\tname = Debug;
+\t\t};
+\t\tA1B2C3E21E00000100000001 /* Release */ = {
+\t\t\tisa = XCBuildConfiguration;
+\t\t\tbuildSettings = {
+\t\t\t\tALWAYS_SEARCH_USER_PATHS = NO;
+\t\t\t\tCLANG_ENABLE_MODULES = YES;
+\t\t\t\tCOPY_PHASE_STRIP = NO;
+\t\t\t\tDEBUG_INFORMATION_FORMAT = "dwarf-with-dsym";
+\t\t\t\tGCC_C_LANGUAGE_STANDARD = gnu17;
+\t\t\t\tGCC_NO_COMMON_BLOCKS = YES;
+\t\t\t\tIPHONEOS_DEPLOYMENT_TARGET = 16.0;
+\t\t\t\tSDKROOT = iphoneos;
+\t\t\t\tSWIFT_COMPILATION_MODE = wholemodule;
+\t\t\t\tSWIFT_VERSION = 5.0;
+\t\t\t};
+\t\t\tname = Release;
+\t\t};
+\t\tA1B2C3E41E00000100000001 /* Debug */ = {
+\t\t\tisa = XCBuildConfiguration;
+\t\t\tbuildSettings = {
+\t\t\t\tCODE_SIGN_STYLE = Automatic;
+\t\t\t\tCURRENT_PROJECT_VERSION = 1;
+\t\t\t\tGENERATE_INFOPLIST_FILE = NO;
+\t\t\t\tINFOPLIST_FILE = AuraJSApp/Info.plist;
+\t\t\t\tLD_RUNPATH_SEARCH_PATHS = (
+\t\t\t\t\t"$(inherited)",
+\t\t\t\t\t"@executable_path/Frameworks",
+\t\t\t\t);
+\t\t\t\tMARKETING_VERSION = 0.1.0;
+\t\t\t\tPRODUCT_BUNDLE_IDENTIFIER = com.aurajs.template;
+\t\t\t\tPRODUCT_NAME = "$(TARGET_NAME)";
+\t\t\t\tSUPPORTED_PLATFORMS = "iphoneos iphonesimulator";
+\t\t\t\tSWIFT_EMIT_LOC_STRINGS = YES;
+\t\t\t\tTARGETED_DEVICE_FAMILY = "1,2";
+\t\t\t};
+\t\t\tname = Debug;
+\t\t};
+\t\tA1B2C3E51E00000100000001 /* Release */ = {
+\t\t\tisa = XCBuildConfiguration;
+\t\t\tbuildSettings = {
+\t\t\t\tCODE_SIGN_STYLE = Automatic;
+\t\t\t\tCURRENT_PROJECT_VERSION = 1;
+\t\t\t\tGENERATE_INFOPLIST_FILE = NO;
+\t\t\t\tINFOPLIST_FILE = AuraJSApp/Info.plist;
+\t\t\t\tLD_RUNPATH_SEARCH_PATHS = (
+\t\t\t\t\t"$(inherited)",
+\t\t\t\t\t"@executable_path/Frameworks",
+\t\t\t\t);
+\t\t\t\tMARKETING_VERSION = 0.1.0;
+\t\t\t\tPRODUCT_BUNDLE_IDENTIFIER = com.aurajs.template;
+\t\t\t\tPRODUCT_NAME = "$(TARGET_NAME)";
+\t\t\t\tSUPPORTED_PLATFORMS = "iphoneos iphonesimulator";
+\t\t\t\tSWIFT_EMIT_LOC_STRINGS = YES;
+\t\t\t\tTARGETED_DEVICE_FAMILY = "1,2";
+\t\t\t};
+\t\t\tname = Release;
+\t\t};
+/* End XCBuildConfiguration section */
+
+/* Begin XCConfigurationList section */
+\t\tA1B2C3E01E00000100000001 /* Build configuration list for PBXProject "AuraJSApp" */ = {
+\t\t\tisa = XCConfigurationList;
+\t\t\tbuildConfigurations = (
+\t\t\t\tA1B2C3E11E00000100000001 /* Debug */,
+\t\t\t\tA1B2C3E21E00000100000001 /* Release */,
+\t\t\t);
+\t\t\tdefaultConfigurationIsVisible = 0;
+\t\t\tdefaultConfigurationName = Release;
+\t\t};
+\t\tA1B2C3E31E00000100000001 /* Build configuration list for PBXNativeTarget "AuraJSApp" */ = {
+\t\t\tisa = XCConfigurationList;
+\t\t\tbuildConfigurations = (
+\t\t\t\tA1B2C3E41E00000100000001 /* Debug */,
+\t\t\t\tA1B2C3E51E00000100000001 /* Release */,
+\t\t\t);
+\t\t\tdefaultConfigurationIsVisible = 0;
+\t\t\tdefaultConfigurationName = Release;
+\t\t};
+/* End XCConfigurationList section */
+\t};
+\trootObject = A1B2C3DF1E00000100000001 /* Project object */;
+}
+`;
+
+const IOS_GENERATED_XCSCHEME = `<?xml version="1.0" encoding="UTF-8"?>
+<Scheme
+   LastUpgradeVersion = "1600"
+   version = "1.7">
+   <BuildAction
+      parallelizeBuildables = "YES"
+      buildImplicitDependencies = "YES">
+      <BuildActionEntries>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "A1B2C3D71E00000100000001"
+               BuildableName = "AuraJSApp.app"
+               BlueprintName = "AuraJSApp"
+               ReferencedContainer = "container:AuraJSApp.xcodeproj">
+            </BuildableReference>
+         </BuildActionEntry>
+      </BuildActionEntries>
+   </BuildAction>
+   <TestAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      shouldUseLaunchSchemeArgsEnv = "YES">
+      <Testables>
+      </Testables>
+   </TestAction>
+   <LaunchAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      launchStyle = "0"
+      useCustomWorkingDirectory = "NO"
+      ignoresPersistentStateOnLaunch = "NO"
+      debugDocumentVersioning = "YES"
+      debugServiceExtension = "internal"
+      allowLocationSimulation = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "A1B2C3D71E00000100000001"
+            BuildableName = "AuraJSApp.app"
+            BlueprintName = "AuraJSApp"
+            ReferencedContainer = "container:AuraJSApp.xcodeproj">
+         </BuildableReference>
+      </BuildableProductRunnable>
+   </LaunchAction>
+   <ProfileAction
+      buildConfiguration = "Release"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      savedToolIdentifier = ""
+      useCustomWorkingDirectory = "NO"
+      debugDocumentVersioning = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "A1B2C3D71E00000100000001"
+            BuildableName = "AuraJSApp.app"
+            BlueprintName = "AuraJSApp"
+            ReferencedContainer = "container:AuraJSApp.xcodeproj">
+         </BuildableReference>
+      </BuildableProductRunnable>
+   </ProfileAction>
+   <AnalyzeAction
+      buildConfiguration = "Debug">
+   </AnalyzeAction>
+   <ArchiveAction
+      buildConfiguration = "Release"
+      revealArchiveInOrganizer = "YES">
+   </ArchiveAction>
+</Scheme>
+`;
+
+export function stageIosProject(options = {}) {
+  const projectRoot = resolve(options.projectRoot || process.cwd());
+  const outRoot = resolve(options.outRoot || join(projectRoot, 'build', 'ios'));
+  const buildManifestPath = resolveRequiredPath(options.buildManifestPath, 'buildManifestPath');
+  const assetsManifestPath = resolveRequiredPath(options.assetsManifestPath, 'assetsManifestPath');
+  const bundlePath = resolveRequiredPath(options.bundlePath, 'bundlePath');
+  const identity = normalizeIdentity(options.identity || {});
+  const sourceBuildRoot = options.sourceBuildRoot
+    ? resolve(options.sourceBuildRoot)
+    : resolve(bundlePath, '..', '..');
+  const hostFrameworkContract = resolveHostFrameworkContract({
+    projectRoot,
+    hostFrameworkPath: options.hostFrameworkPath || null,
+    distRoot: options.distRoot || DIST_ROOT,
+  });
+
+  const toolchain = detectIosToolchain({
+    environment: options.environment || process.env,
+    spawnSyncImpl: options.spawnSyncImpl || spawnSync,
+    xcodebuildExecutable: options.xcodebuildExecutable || null,
+  });
+  const signing = detectIosSigning({
+    environment: options.environment || process.env,
+    bundleId: identity.bundleId,
+  });
+
+  mkdirSync(outRoot, { recursive: true });
+  const templateOutRoot = join(outRoot, 'template');
+  const hostOutRoot = join(outRoot, 'host');
+  const hostFrameworkPath = join(hostOutRoot, IOS_HOST_XCFRAMEWORK_NAME);
+  const stagingRoot = join(outRoot, 'staging', IOS_RESOURCE_ROOT_NAME);
+  const stagingJsRoot = join(stagingRoot, 'js');
+  const stagingAssetsRoot = join(stagingRoot, 'assets');
+  const simulatorAppPath = join(outRoot, 'simulator', `${identity.appName}.app`);
+  const deviceAppPath = join(outRoot, 'device', `${identity.appName}.app`);
+  const archivePath = join(outRoot, 'archive', `${identity.appName}.xcarchive`);
+  const exportPath = join(outRoot, 'export', `${identity.appName}.ipa`);
+
+  copyDirectory(TEMPLATE_ROOT, templateOutRoot);
+  writeGeneratedXcodeProject(templateOutRoot);
+  copyDirectory(hostFrameworkContract.sourcePath, hostFrameworkPath);
+
+  mkdirSync(stagingJsRoot, { recursive: true });
+  mkdirSync(stagingAssetsRoot, { recursive: true });
+
+  cpSync(buildManifestPath, join(stagingRoot, 'build-manifest.json'));
+  cpSync(assetsManifestPath, join(stagingRoot, 'assets-manifest.json'));
+  cpSync(bundlePath, join(stagingJsRoot, 'game.bundle.js'));
+  const sourceRuntimeConfigPath = join(sourceBuildRoot, 'runtime-config.json');
+  if (existsSync(sourceRuntimeConfigPath) && statSync(sourceRuntimeConfigPath).isFile()) {
+    cpSync(sourceRuntimeConfigPath, join(stagingRoot, 'runtime-config.json'));
+  }
+
+  const sourceAssetsRoot = join(sourceBuildRoot, 'assets');
+  if (existsSync(sourceAssetsRoot) && statSync(sourceAssetsRoot).isDirectory()) {
+    copyDirectory(sourceAssetsRoot, stagingAssetsRoot);
+  }
+
+  mkdirSync(simulatorAppPath, { recursive: true });
+  mkdirSync(deviceAppPath, { recursive: true });
+  mkdirSync(dirnameSafe(archivePath), { recursive: true });
+  mkdirSync(dirnameSafe(exportPath), { recursive: true });
+  const bundledDeviceResourceRoot = join(deviceAppPath, IOS_RESOURCE_ROOT_NAME);
+  const bundledSimulatorResourceRoot = join(simulatorAppPath, IOS_RESOURCE_ROOT_NAME);
+  copyDirectory(stagingRoot, bundledDeviceResourceRoot);
+  copyDirectory(stagingRoot, bundledSimulatorResourceRoot);
+  const embeddedFrameworks = embedHostFrameworkSlices({
+    contract: hostFrameworkContract,
+    deviceAppPath,
+    simulatorAppPath,
+  });
+
+  const manifest = {
+    schema: IOS_BUILD_MANIFEST_SCHEMA,
+    schemaVersion: '1.0.0',
+    buildTarget: 'ios',
+    packagingForm: 'xcframework',
+    hostFramework: relativePosix(outRoot, hostFrameworkPath),
+    hostFrameworkStatus: {
+      reasonCode: hostFrameworkContract.reasonCode,
+      sourceKind: hostFrameworkContract.sourceKind,
+      sourcePath: relativeToRootOrAbsolute(projectRoot, hostFrameworkContract.sourcePath),
+      stagedPath: relativePosix(outRoot, hostFrameworkPath),
+      expectedSlices: {
+        device: `${IOS_DEVICE_LIBRARY_IDENTIFIER}/${IOS_HOST_FRAMEWORK_DIRECTORY}`,
+        simulator: `${IOS_SIMULATOR_LIBRARY_IDENTIFIER}/${IOS_HOST_FRAMEWORK_DIRECTORY}`,
+      },
+      embeddedFrameworks: {
+        device: embeddedFrameworks.device
+          ? relativePosix(outRoot, embeddedFrameworks.device)
+          : null,
+        simulator: embeddedFrameworks.simulator
+          ? relativePosix(outRoot, embeddedFrameworks.simulator)
+          : null,
+      },
+    },
+    templateRoot: relativePosix(outRoot, templateOutRoot),
+    resourceRoot: relativePosix(outRoot, stagingRoot),
+    identity: {
+      appName: identity.appName,
+      bundleId: identity.bundleId,
+      version: identity.version,
+      buildNumber: identity.buildNumber,
+    },
+    slices: {
+      device: {
+        sdk: 'iphoneos',
+        architectures: ['arm64'],
+        app: relativePosix(outRoot, deviceAppPath),
+      },
+      simulator: {
+        sdk: 'iphonesimulator',
+        architectures: ['arm64'],
+        app: relativePosix(outRoot, simulatorAppPath),
+      },
+    },
+    artifacts: {
+      buildDeviceApp: relativePosix(outRoot, deviceAppPath),
+      buildSimulatorApp: relativePosix(outRoot, simulatorAppPath),
+      archive: relativePosix(outRoot, archivePath),
+      exportIpa: relativePosix(outRoot, exportPath),
+    },
+    resourceContract: {
+      root: `${IOS_RESOURCE_ROOT_NAME}/`,
+      buildManifest: `${IOS_RESOURCE_ROOT_NAME}/build-manifest.json`,
+      assetsManifest: `${IOS_RESOURCE_ROOT_NAME}/assets-manifest.json`,
+      bundle: `${IOS_RESOURCE_ROOT_NAME}/js/game.bundle.js`,
+      assetsRoot: `${IOS_RESOURCE_ROOT_NAME}/assets`,
+      bundledDeviceRoot: relativePosix(outRoot, bundledDeviceResourceRoot),
+      bundledSimulatorRoot: relativePosix(outRoot, bundledSimulatorResourceRoot),
+    },
+    buildStatus: {
+      simulator: 'not_built',
+      device: 'not_built',
+      archive: 'not_built',
+      export: 'not_built',
+      reasonCode: 'ios_external_build_not_run',
+    },
+    toolchain,
+    signing,
+  };
+
+  const manifestPath = join(outRoot, 'ios-build-manifest.json');
+  writeCanonicalJson(manifestPath, manifest);
+
+  return {
+    outRoot,
+    manifestPath,
+    templateOutRoot,
+    hostFrameworkPath,
+    stagingRoot,
+    simulatorAppPath,
+    deviceAppPath,
+    archivePath,
+    exportPath,
+    toolchain,
+    signing,
+  };
+}
+
+export function detectIosToolchain(options = {}) {
+  const environment = options.environment || process.env;
+  const spawnSyncImpl = options.spawnSyncImpl || spawnSync;
+  const xcodebuildExecutable = cleanString(options.xcodebuildExecutable)
+    || cleanString(environment.AURA_IOS_XCODEBUILD)
+    || 'xcodebuild';
+  if (String(environment.AURAJS_SKIP_XCODE_PROBE || '') === '1') {
+    return {
+      available: false,
+      reasonCode: 'ios_xcode_probe_skipped',
+      detail: 'Xcode probing was skipped by AURAJS_SKIP_XCODE_PROBE=1.',
+      executablePath: xcodebuildExecutable,
+    };
+  }
+
+  const result = spawnSyncImpl(xcodebuildExecutable, ['-version'], {
+    encoding: 'utf8',
+    env: environment,
+  });
+  if (result.status !== 0) {
+    return {
+      available: false,
+      reasonCode: 'ios_xcodebuild_missing',
+      detail: 'xcodebuild was not available in PATH.',
+      executablePath: xcodebuildExecutable,
+    };
+  }
+
+  const versionLine = String(result.stdout || '')
+    .split('\n')
+    .map((line) => line.trim())
+    .find((line) => line.startsWith('Xcode '))
+    || null;
+
+  return {
+    available: true,
+    reasonCode: 'ios_xcodebuild_available',
+    detail: versionLine,
+    executablePath: xcodebuildExecutable,
+  };
+}
+
+export function detectIosSigning(options = {}) {
+  const environment = options.environment || process.env;
+  const bundleId = cleanString(environment.AURA_IOS_BUNDLE_ID) || cleanString(options.bundleId);
+  const teamId = cleanString(environment.AURA_IOS_TEAM_ID);
+  const codeSignIdentity = cleanString(environment.AURA_IOS_CODE_SIGN_IDENTITY);
+
+  if (bundleId && (teamId || codeSignIdentity)) {
+    return {
+      configured: true,
+      reasonCode: 'ios_signing_configured',
+      bundleId,
+      teamId,
+      codeSignIdentity,
+    };
+  }
+
+  return {
+    configured: false,
+    reasonCode: 'ios_signing_unconfigured',
+    bundleId: bundleId || null,
+    teamId,
+    codeSignIdentity,
+  };
+}
+
+export function buildIosArtifacts(options = {}) {
+  const outRoot = resolveRequiredPath(options.outRoot, 'outRoot');
+  const manifestPath = resolveRequiredPath(
+    options.manifestPath || join(outRoot, 'ios-build-manifest.json'),
+    'manifestPath',
+  );
+  const environment = options.environment || process.env;
+  const spawnSyncImpl = options.spawnSyncImpl || spawnSync;
+  const operations = normalizeIosOperations(options.operations);
+  const manifest = readIosBuildManifest(manifestPath);
+  const toolchain = detectIosToolchain({
+    environment,
+    spawnSyncImpl,
+    xcodebuildExecutable: options.xcodebuildExecutable || null,
+  });
+  const signing = detectIosSigning({
+    environment,
+    bundleId: manifest.identity?.bundleId || null,
+  });
+  const hostFrameworkRoot = join(outRoot, manifest.hostFramework);
+  const projectBundlePath = join(outRoot, manifest.templateRoot, IOS_XCODE_PROJECT_NAME);
+  const stagingRoot = join(outRoot, manifest.resourceRoot);
+  const derivedDataPath = resolve(options.derivedDataPath || join(outRoot, IOS_DERIVED_DATA_ROOT));
+  const buildStatus = {
+    simulator: manifest.buildStatus?.simulator || 'not_built',
+    device: manifest.buildStatus?.device || 'not_built',
+    archive: manifest.buildStatus?.archive || 'not_built',
+    export: manifest.buildStatus?.export || 'not_built',
+  };
+  const executedPhases = [];
+  const outputs = {
+    simulatorApp: null,
+    deviceApp: null,
+    archive: null,
+    exportIpa: null,
+  };
+
+  manifest.toolchain = toolchain;
+  manifest.signing = signing;
+
+  if (!toolchain.available) {
+    return finalizeIosBuildFailure({
+      manifest,
+      manifestPath,
+      buildStatus,
+      reasonCode: toolchain.reasonCode,
+      outRoot,
+      detail: toolchain.detail,
+      executedPhases,
+      outputs,
+      derivedDataPath,
+      exportOptionsPath: null,
+    });
+  }
+
+  if (manifest.hostFrameworkStatus?.reasonCode !== 'ios_host_framework_validated') {
+    return finalizeIosBuildFailure({
+      manifest,
+      manifestPath,
+      buildStatus,
+      reasonCode: manifest.hostFrameworkStatus?.reasonCode || 'ios_host_framework_placeholder',
+      outRoot,
+      detail: 'A validated iOS host xcframework is required before build/archive/export can run.',
+      executedPhases,
+      outputs,
+      derivedDataPath,
+      exportOptionsPath: null,
+    });
+  }
+
+  if (!existsSync(join(projectBundlePath, IOS_XCODE_PROJECT_FILE))) {
+    return finalizeIosBuildFailure({
+      manifest,
+      manifestPath,
+      buildStatus,
+      reasonCode: 'ios_xcode_project_missing',
+      outRoot,
+      detail: `Missing generated Xcode project at ${projectBundlePath}.`,
+      executedPhases,
+      outputs,
+      derivedDataPath,
+      exportOptionsPath: null,
+    });
+  }
+
+  const frameworkSlices = validateHostFrameworkSlices(hostFrameworkRoot);
+  let exportOptionsPath = null;
+
+  try {
+    if (operations.simulator) {
+      executeXcodebuildPhase({
+        phase: 'build-simulator',
+        outRoot,
+        spawnSyncImpl,
+        executablePath: toolchain.executablePath,
+        environment,
+        args: buildIosCommandArgs({
+          projectBundlePath,
+          identity: manifest.identity,
+          sdk: 'iphonesimulator',
+          derivedDataPath,
+          signing,
+          signBuild: false,
+        }),
+      });
+      synchronizeBuiltApp({
+        sourceAppPath: resolveRequiredPath(
+          join(
+            derivedDataPath,
+            'Build',
+            'Products',
+            `${IOS_BUILD_CONFIGURATION}-iphonesimulator`,
+            IOS_XCODE_PRODUCT_NAME,
+          ),
+          'simulator build output',
+        ),
+        outputAppPath: join(outRoot, manifest.artifacts.buildSimulatorApp),
+        stagingRoot,
+        frameworkSlicePath: frameworkSlices.simulator,
+      });
+      buildStatus.simulator = 'built';
+      outputs.simulatorApp = join(outRoot, manifest.artifacts.buildSimulatorApp);
+      executedPhases.push('build-simulator');
+    }
+
+    if ((operations.device || operations.archive || operations.export) && !signing.configured) {
+      return finalizeIosBuildFailure({
+        manifest,
+        manifestPath,
+        buildStatus,
+        reasonCode: signing.reasonCode,
+        outRoot,
+        detail: 'Device build, archive, and export require configured signing state.',
+        executedPhases,
+        outputs,
+        derivedDataPath,
+        exportOptionsPath,
+      });
+    }
+
+    if (operations.device) {
+      executeXcodebuildPhase({
+        phase: 'build-device',
+        outRoot,
+        spawnSyncImpl,
+        executablePath: toolchain.executablePath,
+        environment,
+        args: buildIosCommandArgs({
+          projectBundlePath,
+          identity: manifest.identity,
+          sdk: 'iphoneos',
+          derivedDataPath,
+          signing,
+          signBuild: true,
+        }),
+      });
+      synchronizeBuiltApp({
+        sourceAppPath: resolveRequiredPath(
+          join(
+            derivedDataPath,
+            'Build',
+            'Products',
+            `${IOS_BUILD_CONFIGURATION}-iphoneos`,
+            IOS_XCODE_PRODUCT_NAME,
+          ),
+          'device build output',
+        ),
+        outputAppPath: join(outRoot, manifest.artifacts.buildDeviceApp),
+        stagingRoot,
+        frameworkSlicePath: frameworkSlices.device,
+      });
+      buildStatus.device = 'built';
+      outputs.deviceApp = join(outRoot, manifest.artifacts.buildDeviceApp);
+      executedPhases.push('build-device');
+    }
+
+    if (operations.archive) {
+      executeXcodebuildPhase({
+        phase: 'archive',
+        outRoot,
+        spawnSyncImpl,
+        executablePath: toolchain.executablePath,
+        environment,
+        args: archiveIosCommandArgs({
+          projectBundlePath,
+          identity: manifest.identity,
+          archivePath: join(outRoot, manifest.artifacts.archive),
+          derivedDataPath,
+          signing,
+        }),
+      });
+      const archiveAppPath = resolveArchiveApplicationPath(join(outRoot, manifest.artifacts.archive));
+      injectBundledRuntimeIntoApp({
+        appPath: archiveAppPath,
+        stagingRoot,
+        frameworkSlicePath: frameworkSlices.device,
+      });
+      buildStatus.archive = 'built';
+      outputs.archive = join(outRoot, manifest.artifacts.archive);
+      executedPhases.push('archive');
+    }
+
+    if (operations.export) {
+      const archivePath = join(outRoot, manifest.artifacts.archive);
+      if (!existsSync(archivePath)) {
+        return finalizeIosBuildFailure({
+          manifest,
+          manifestPath,
+          buildStatus,
+          reasonCode: 'ios_archive_missing',
+          outRoot,
+          detail: `Cannot export without archive: ${archivePath}`,
+          executedPhases,
+          outputs,
+          derivedDataPath,
+          exportOptionsPath,
+        });
+      }
+      exportOptionsPath = writeIosExportOptionsPlist({
+        outRoot,
+        signing,
+        exportMethod: cleanString(options.exportMethod)
+          || cleanString(environment.AURA_IOS_EXPORT_METHOD)
+          || 'development',
+      });
+      const exportStagingRoot = join(outRoot, 'export', '.xcodebuild');
+      rmSync(exportStagingRoot, { recursive: true, force: true });
+      mkdirSync(exportStagingRoot, { recursive: true });
+      executeXcodebuildPhase({
+        phase: 'export',
+        outRoot,
+        spawnSyncImpl,
+        executablePath: toolchain.executablePath,
+        environment,
+        args: exportIosCommandArgs({
+          archivePath,
+          exportRoot: exportStagingRoot,
+          exportOptionsPath,
+        }),
+      });
+      const sourceIpaPath = resolveExportedIpaPath(exportStagingRoot);
+      const outputIpaPath = join(outRoot, manifest.artifacts.exportIpa);
+      mkdirSync(dirnameSafe(outputIpaPath), { recursive: true });
+      cpSync(sourceIpaPath, outputIpaPath, { force: true });
+      buildStatus.export = 'built';
+      outputs.exportIpa = outputIpaPath;
+      executedPhases.push('export');
+    }
+  } catch (error) {
+    return finalizeIosBuildFailure({
+      manifest,
+      manifestPath,
+      buildStatus,
+      reasonCode: error?.reasonCode || 'ios_xcodebuild_failed',
+      outRoot,
+      detail: error instanceof Error ? error.message : String(error),
+      executedPhases,
+      outputs,
+      derivedDataPath,
+      exportOptionsPath,
+    });
+  }
+
+  manifest.buildStatus = {
+    simulator: buildStatus.simulator,
+    device: buildStatus.device,
+    archive: buildStatus.archive,
+    export: buildStatus.export,
+    reasonCode: 'ios_xcodebuild_complete',
+    executedPhases,
+    derivedDataPath: relativeToRootOrAbsolute(outRoot, derivedDataPath),
+    exportOptionsPath: exportOptionsPath
+      ? relativeToRootOrAbsolute(outRoot, exportOptionsPath)
+      : null,
+  };
+  writeCanonicalJson(manifestPath, manifest);
+
+  return {
+    ok: true,
+    manifestPath,
+    manifest,
+    toolchain,
+    signing,
+    outputs,
+    derivedDataPath,
+    exportOptionsPath,
+  };
+}
+
+function normalizeIdentity(identity) {
+  const appName = cleanString(identity.appName) || 'AuraJSGame';
+  return {
+    appName,
+    bundleId: cleanString(identity.bundleId) || `com.aurajs.${slugify(appName)}`,
+    version: cleanString(identity.version) || '0.1.0',
+    buildNumber: cleanString(identity.buildNumber) || '1',
+  };
+}
+
+function normalizeIosOperations(value) {
+  const requested = Array.isArray(value) && value.length > 0
+    ? value
+    : ['simulator', 'device', 'archive', 'export'];
+  const set = new Set(
+    requested
+      .map((entry) => String(entry || '').trim().toLowerCase())
+      .filter(Boolean),
+  );
+  return {
+    simulator: set.has('simulator'),
+    device: set.has('device'),
+    archive: set.has('archive'),
+    export: set.has('export'),
+  };
+}
+
+function buildIosCommandArgs({
+  projectBundlePath,
+  identity,
+  sdk,
+  derivedDataPath,
+  signing,
+  signBuild,
+}) {
+  const args = [
+    '-project',
+    projectBundlePath,
+    '-scheme',
+    IOS_XCODE_SCHEME_NAME,
+    '-configuration',
+    IOS_BUILD_CONFIGURATION,
+    '-sdk',
+    sdk,
+    '-derivedDataPath',
+    derivedDataPath,
+    `PRODUCT_BUNDLE_IDENTIFIER=${identity.bundleId}`,
+    `MARKETING_VERSION=${identity.version}`,
+    `CURRENT_PROJECT_VERSION=${identity.buildNumber}`,
+  ];
+  if (sdk === 'iphonesimulator') {
+    args.push('-destination', 'generic/platform=iOS Simulator');
+  } else {
+    args.push('-destination', 'generic/platform=iOS');
+  }
+  if (signBuild) {
+    if (signing.teamId) {
+      args.push(`DEVELOPMENT_TEAM=${signing.teamId}`);
+    }
+    if (signing.codeSignIdentity) {
+      args.push(`CODE_SIGN_IDENTITY=${signing.codeSignIdentity}`);
+    }
+  } else {
+    args.push('CODE_SIGNING_ALLOWED=NO', 'CODE_SIGNING_REQUIRED=NO');
+  }
+  args.push('build');
+  return args;
+}
+
+function archiveIosCommandArgs({
+  projectBundlePath,
+  identity,
+  archivePath,
+  derivedDataPath,
+  signing,
+}) {
+  const args = [
+    '-project',
+    projectBundlePath,
+    '-scheme',
+    IOS_XCODE_SCHEME_NAME,
+    '-configuration',
+    IOS_BUILD_CONFIGURATION,
+    '-sdk',
+    'iphoneos',
+    '-destination',
+    'generic/platform=iOS',
+    '-archivePath',
+    archivePath,
+    '-derivedDataPath',
+    derivedDataPath,
+    `PRODUCT_BUNDLE_IDENTIFIER=${identity.bundleId}`,
+    `MARKETING_VERSION=${identity.version}`,
+    `CURRENT_PROJECT_VERSION=${identity.buildNumber}`,
+  ];
+  if (signing.teamId) {
+    args.push(`DEVELOPMENT_TEAM=${signing.teamId}`);
+  }
+  if (signing.codeSignIdentity) {
+    args.push(`CODE_SIGN_IDENTITY=${signing.codeSignIdentity}`);
+  }
+  args.push('archive');
+  return args;
+}
+
+function exportIosCommandArgs({ archivePath, exportRoot, exportOptionsPath }) {
+  return [
+    '-exportArchive',
+    '-archivePath',
+    archivePath,
+    '-exportPath',
+    exportRoot,
+    '-exportOptionsPlist',
+    exportOptionsPath,
+  ];
+}
+
+function writeIosExportOptionsPlist({ outRoot, signing, exportMethod }) {
+  const exportRoot = join(outRoot, 'export');
+  mkdirSync(exportRoot, { recursive: true });
+  const exportOptionsPath = join(exportRoot, IOS_EXPORT_OPTIONS_FILE);
+  const lines = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    '<dict>',
+    '  <key>compileBitcode</key>',
+    '  <false/>',
+    '  <key>method</key>',
+    `  <string>${escapeXml(exportMethod)}</string>`,
+    '  <key>signingStyle</key>',
+    '  <string>automatic</string>',
+  ];
+  if (signing.teamId) {
+    lines.push('  <key>teamID</key>');
+    lines.push(`  <string>${escapeXml(signing.teamId)}</string>`);
+  }
+  lines.push('</dict>');
+  lines.push('</plist>');
+  lines.push('');
+  writeFileSync(exportOptionsPath, lines.join('\n'), 'utf8');
+  return exportOptionsPath;
+}
+
+function escapeXml(value) {
+  return String(value)
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;');
+}
+
+function executeXcodebuildPhase({
+  phase,
+  outRoot,
+  spawnSyncImpl,
+  executablePath,
+  environment,
+  args,
+}) {
+  const result = spawnSyncImpl(executablePath, args, {
+    cwd: outRoot,
+    encoding: 'utf8',
+    env: environment,
+  });
+  if (result.status !== 0) {
+    const message = String(result.stderr || result.stdout || '').trim() || `${phase} failed`;
+    const error = new Error(message);
+    error.reasonCode = `ios_${phase.replaceAll('-', '_')}_failed`;
+    throw error;
+  }
+}
+
+function synchronizeBuiltApp({
+  sourceAppPath,
+  outputAppPath,
+  stagingRoot,
+  frameworkSlicePath,
+}) {
+  replaceDirectory(sourceAppPath, outputAppPath);
+  injectBundledRuntimeIntoApp({
+    appPath: outputAppPath,
+    stagingRoot,
+    frameworkSlicePath,
+  });
+}
+
+function resolveArchiveApplicationPath(archivePath) {
+  const applicationsRoot = resolveRequiredPath(
+    join(archivePath, 'Products', 'Applications'),
+    'archive applications root',
+  );
+  const entries = readdirSync(applicationsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name.endsWith('.app'));
+  if (entries.length === 0) {
+    throw Object.assign(new Error(`archive did not contain an .app under ${applicationsRoot}`), {
+      reasonCode: 'ios_archive_missing',
+    });
+  }
+  return join(applicationsRoot, entries[0].name);
+}
+
+function resolveExportedIpaPath(exportRoot) {
+  const entries = readdirSync(resolveRequiredPath(exportRoot, 'exportRoot'), { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.ipa'));
+  if (entries.length === 0) {
+    throw Object.assign(new Error(`export did not emit an .ipa under ${exportRoot}`), {
+      reasonCode: 'ios_export_ipa_missing',
+    });
+  }
+  return join(exportRoot, entries[0].name);
+}
+
+function injectBundledRuntimeIntoApp({ appPath, stagingRoot, frameworkSlicePath }) {
+  replaceDirectory(stagingRoot, join(appPath, IOS_RESOURCE_ROOT_NAME));
+  replaceDirectory(frameworkSlicePath, join(appPath, 'Frameworks', IOS_HOST_FRAMEWORK_DIRECTORY));
+}
+
+function finalizeIosBuildFailure({
+  manifest,
+  manifestPath,
+  buildStatus,
+  reasonCode,
+  outRoot,
+  detail,
+  executedPhases,
+  outputs,
+  derivedDataPath,
+  exportOptionsPath,
+}) {
+  manifest.buildStatus = {
+    simulator: buildStatus.simulator,
+    device: buildStatus.device,
+    archive: buildStatus.archive,
+    export: buildStatus.export,
+    reasonCode,
+    executedPhases,
+    derivedDataPath: relativeToRootOrAbsolute(outRoot, derivedDataPath),
+    exportOptionsPath: exportOptionsPath
+      ? relativeToRootOrAbsolute(outRoot, exportOptionsPath)
+      : null,
+  };
+  writeCanonicalJson(manifestPath, manifest);
+  return {
+    ok: false,
+    reasonCode,
+    detail,
+    manifestPath,
+    manifest,
+    toolchain: manifest.toolchain,
+    signing: manifest.signing,
+    outputs,
+    derivedDataPath,
+    exportOptionsPath,
+  };
+}
+
+function slugify(input) {
+  return String(input || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    || 'game';
+}
+
+function cleanString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function resolveRequiredPath(value, label) {
+  if (!value) {
+    throw new Error(`ios build requires ${label}.`);
+  }
+  const resolved = resolve(value);
+  if (!existsSync(resolved)) {
+    throw new Error(`ios build requires existing ${label}: ${resolved}`);
+  }
+  return resolved;
+}
+
+function resolveHostFrameworkContract({ projectRoot, hostFrameworkPath, distRoot }) {
+  let sourcePath = null;
+  let sourceKind = null;
+  let reasonCode = 'ios_host_framework_validated';
+
+  if (hostFrameworkPath) {
+    sourcePath = resolveRequiredPath(hostFrameworkPath, 'hostFrameworkPath');
+    sourceKind = 'explicit_input';
+  } else {
+    const distFrameworkPath = join(resolve(distRoot || DIST_ROOT), IOS_HOST_XCFRAMEWORK_NAME);
+    if (existsSync(distFrameworkPath)) {
+      sourcePath = resolveRequiredPath(distFrameworkPath, 'distRoot/aurajs-host.xcframework');
+      sourceKind = 'platform_dist';
+    }
+  }
+
+  if (!sourcePath) {
+    return {
+      sourcePath: HOST_XCFRAMEWORK_ROOT,
+      sourceKind: 'placeholder_scaffold',
+      reasonCode: 'ios_host_framework_placeholder',
+      validatedSlices: null,
+    };
+  }
+
+  const validatedSlices = validateHostFrameworkSlices(sourcePath);
+  return {
+    sourcePath,
+    sourceKind,
+    reasonCode,
+    validatedSlices,
+  };
+}
+
+function validateHostFrameworkSlices(hostFrameworkPath) {
+  resolveRequiredPath(join(hostFrameworkPath, 'Info.plist'), 'hostFrameworkPath/Info.plist');
+  const deviceFrameworkPath = resolveRequiredPath(
+    join(
+      hostFrameworkPath,
+      IOS_DEVICE_LIBRARY_IDENTIFIER,
+      IOS_HOST_FRAMEWORK_DIRECTORY,
+      IOS_HOST_FRAMEWORK_BINARY,
+    ),
+    'hostFrameworkPath device slice binary',
+  );
+  const simulatorFrameworkPath = resolveRequiredPath(
+    join(
+      hostFrameworkPath,
+      IOS_SIMULATOR_LIBRARY_IDENTIFIER,
+      IOS_HOST_FRAMEWORK_DIRECTORY,
+      IOS_HOST_FRAMEWORK_BINARY,
+    ),
+    'hostFrameworkPath simulator slice binary',
+  );
+
+  return {
+    device: dirnameSafe(deviceFrameworkPath),
+    simulator: dirnameSafe(simulatorFrameworkPath),
+  };
+}
+
+function embedHostFrameworkSlices({ contract, deviceAppPath, simulatorAppPath }) {
+  if (!contract.validatedSlices) {
+    return {
+      device: null,
+      simulator: null,
+    };
+  }
+
+  const deviceFrameworkPath = join(deviceAppPath, 'Frameworks', IOS_HOST_FRAMEWORK_DIRECTORY);
+  const simulatorFrameworkPath = join(
+    simulatorAppPath,
+    'Frameworks',
+    IOS_HOST_FRAMEWORK_DIRECTORY,
+  );
+  copyDirectory(contract.validatedSlices.device, deviceFrameworkPath);
+  copyDirectory(contract.validatedSlices.simulator, simulatorFrameworkPath);
+  return {
+    device: deviceFrameworkPath,
+    simulator: simulatorFrameworkPath,
+  };
+}
+
+function writeGeneratedXcodeProject(templateOutRoot) {
+  const projectRoot = join(templateOutRoot, IOS_XCODE_PROJECT_NAME);
+  const projectFilePath = join(projectRoot, IOS_XCODE_PROJECT_FILE);
+  const schemePath = join(projectRoot, 'xcshareddata', 'xcschemes', `${IOS_XCODE_SCHEME_NAME}.xcscheme`);
+  mkdirSync(dirnameSafe(projectFilePath), { recursive: true });
+  mkdirSync(dirnameSafe(schemePath), { recursive: true });
+  writeFileSync(projectFilePath, IOS_GENERATED_PROJECT_PBXPROJ, 'utf8');
+  writeFileSync(schemePath, IOS_GENERATED_XCSCHEME, 'utf8');
+  return projectRoot;
+}
+
+function dirnameSafe(path) {
+  return resolve(path, '..');
+}
+
+function replaceDirectory(sourceRoot, destRoot) {
+  rmSync(destRoot, { recursive: true, force: true });
+  copyDirectory(sourceRoot, destRoot);
+}
+
+function copyDirectory(sourceRoot, destRoot) {
+  mkdirSync(destRoot, { recursive: true });
+  cpSync(sourceRoot, destRoot, {
+    recursive: true,
+    dereference: false,
+    force: true,
+  });
+}
+
+function relativePosix(fromRoot, targetPath) {
+  return relative(fromRoot, targetPath).replace(/\\/g, '/');
+}
+
+function relativeToRootOrAbsolute(root, targetPath) {
+  const rel = relative(root, targetPath).replace(/\\/g, '/');
+  if (!rel || (!rel.startsWith('../') && rel !== '..')) {
+    return rel || '.';
+  }
+  return targetPath;
+}
+
+function writeCanonicalJson(path, value) {
+  writeFileSync(path, `${JSON.stringify(sortKeysDeep(value), null, 2)}\n`, 'utf8');
+}
+
+function sortKeysDeep(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortKeysDeep);
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .map((key) => [key, sortKeysDeep(value[key])]),
+    );
+  }
+  return value;
+}
+
+export function readIosBuildManifest(path) {
+  return JSON.parse(readFileSync(resolveRequiredPath(path, 'manifestPath'), 'utf8'));
+}
+
+export {
+  IOS_BUILD_MANIFEST_SCHEMA,
+  IOS_HOST_XCFRAMEWORK_NAME,
+  IOS_RESOURCE_ROOT_NAME,
+};