@@ -283,6 +283,9 @@ jobs:
           # the bundled engine (own_compilers.py exit code 1). sign_engine_tree.sh signs only a Mach-O file without any signature and checks the rest.
           ditto "$RUNNER_TEMP/engine-tree" "$APP/Contents/Resources/engine"
           tools/sign_engine_tree.sh "$APP/Contents/Resources/engine" "$RUNNER_TEMP/engine-tree"
+          # The iPhone shell's Swift package: build_shell.sh links it by DM_SHELL_PACKAGE and the launcher passes this folder (the engine has
+          # none since #214). The step runs in frontend/, the package is one level up. No .build or .swiftpm.
+          rsync -a --exclude .build --exclude .swiftpm ../frontend-ios/ "$APP/Contents/Resources/frontend-ios/"
           V="${{ steps.ver.outputs.version }}"
           cat > "$APP/Contents/Info.plist" <<PLIST
           <?xml version="1.0" encoding="UTF-8"?>
@@ -326,6 +329,8 @@ jobs:
           cmp "$E/.engine-id" "$RUNNER_TEMP/engine-tree/.engine-id"
           cmp "$E/.upstream-ref" ../.upstream-ref
           test -f "$E/scripts/build_ipa_from_nsp.py" && test -f "$E/dm/tools/romfs_image.py" && test -f "$E/dm/fork_patches.txt"
+          # The iPhone shell's package (DM_SHELL_PACKAGE): the project template links it and its AppIcon.icon.
+          test -f "NX2Apple.app/Contents/Resources/frontend-ios/Package.swift" && test -d "NX2Apple.app/Contents/Resources/frontend-ios/AppIcon.icon"
           test ! -e "$E/.git"
           # The engine files are the zip asset's, byte for byte, and spirv-cross matches dmsh_chain.lock, so a shader build from the bundled engine starts.
           tools/sign_engine_tree.sh --check "$E" "$RUNNER_TEMP/engine-tree"
 
@@ -86,9 +86,17 @@ enum ShellInstall {
         ["/bin/bash", repo + "/dm/ios/tools/build_shell.sh", "--prepare-xcode"]
     }
 
+    /// The `frontend-ios` Swift package the shell project links (build_shell.sh's DM_SHELL_PACKAGE). The script defaults to
+    /// `frontend-ios` beside `dm/`, which is the engine root, and an engine tree has none since #214. So: the release app's
+    /// Contents/Resources/frontend-ios, else the source checkout's `frontend-ios` (`repo`). nil when neither has a Package.swift.
+    static func shellPackage(resources: String?, repo: String, fm: FileManager = .default) -> String? {
+        ([resources, repo].compactMap { $0 }.filter { !$0.isEmpty }).map { $0 + "/frontend-ios" }
+            .first { fm.fileExists(atPath: $0 + "/Package.swift") }
+    }
+
     /// What build_shell.sh reads. `path` is the build's own tool PATH (xcodegen must be found on it).
     static func projectEnvironment(root: String, frameworks: [String], bundleID: String, team: String, python: String,
-                                   path: String, home: String, user: String, tmp: String? = nil) -> [String: String] {
+                                   path: String, home: String, user: String, tmp: String? = nil, package: String? = nil) -> [String: String] {
         var env = ["SHELL_DIR": projectFolder(root: root),
                    "DM_SHELL_FRAMEWORKS": frameworks.joined(separator: "\n"),
                    "DM_BUNDLE_ID": bundleID,
@@ -97,6 +105,7 @@ enum ShellInstall {
                    "FONT_PY": python,
                    "PATH": path, "HOME": home, "USER": user, "LANG": "en_US.UTF-8"]
         if let tmp { env["TMPDIR"] = tmp }
+        if let package { env["DM_SHELL_PACKAGE"] = package }
         return env
     }
 
@@ -290,6 +299,8 @@ struct ShellStage {
 struct ShellInstaller {
     var xcrun = "/usr/bin/xcrun"
     var repo: String
+    /// The app's Contents/Resources, where a release app carries frontend-ios. Nil for a launcher run from a checkout.
+    var resources: String? = Bundle.main.resourceURL?.path
     var python: String
     var root: String
     var device: String
@@ -361,9 +372,13 @@ struct ShellInstaller {
         }
 
         // 4: the project
+        guard let package = ShellInstall.shellPackage(resources: resources, repo: repo) else {
+            let looked = ([resources, repo].compactMap { $0 }.filter { !$0.isEmpty }).map { $0 + "/frontend-ios" }.joined(separator: ", ")
+            return Outcome(ok: false, message: fmt("shell.projectFailed", "no frontend-ios Swift package (Package.swift) in " + looked))
+        }
         var env = ShellInstall.projectEnvironment(root: root, frameworks: library.games.map(\.framework), bundleID: library.bundleID,
                                                   team: team, python: python, path: toolPath, home: NSHomeDirectory(), user: NSUserName(),
-                                                  tmp: NSTemporaryDirectory())
+                                                  tmp: NSTemporaryDirectory(), package: package)
         env.merge(BundledTools.environment(for: python)) { $1 }
         let projectName = t("shell.projectStage")
         begin(Self.projectStageID, projectName)
 
@@ -63,6 +63,45 @@ final class ShellInstallTests: XCTestCase {
 
     // ---- the commands ----
 
+    // ---- the iOS shell package (DM_SHELL_PACKAGE) ----
+
+    private func makeTree(_ files: [String]) throws -> String {
+        let dir = NSTemporaryDirectory() + "shellpkg-" + UUID().uuidString
+        for f in files {
+            try FileManager.default.createDirectory(atPath: (dir + "/" + f as NSString).deletingLastPathComponent, withIntermediateDirectories: true)
+            FileManager.default.createFile(atPath: dir + "/" + f, contents: Data())
+        }
+        try FileManager.default.createDirectory(atPath: dir, withIntermediateDirectories: true)
+        addTeardownBlock { try? FileManager.default.removeItem(atPath: dir) }
+        return dir
+    }
+
+    func testShellPackagePrefersTheBundleThenTheCheckout() throws {
+        let bundle = try makeTree(["frontend-ios/Package.swift"])
+        let checkout = try makeTree(["frontend-ios/Package.swift"])
+        XCTAssertEqual(ShellInstall.shellPackage(resources: bundle, repo: checkout), bundle + "/frontend-ios")
+        XCTAssertEqual(ShellInstall.shellPackage(resources: nil, repo: checkout), checkout + "/frontend-ios")
+        let bare = try makeTree([])
+        XCTAssertEqual(ShellInstall.shellPackage(resources: bare, repo: checkout), checkout + "/frontend-ios")
+        XCTAssertNil(ShellInstall.shellPackage(resources: bare, repo: bare))
+        XCTAssertNil(ShellInstall.shellPackage(resources: nil, repo: ""))
+    }
+
+    /// The failure of the report: the repo is an engine in the store (no frontend-ios in it), the release app carries the package.
+    func testStoreEngineGetsTheBundledPackage() throws {
+        let store = try makeTree(["engine/id/dm/ios/tools/build_shell.sh"]) + "/engine/id"
+        let bundle = try makeTree(["frontend-ios/Package.swift", "frontend-ios/AppIcon.icon/icon.json"])
+        let package = try XCTUnwrap(ShellInstall.shellPackage(resources: bundle, repo: store))
+        let env = ShellInstall.projectEnvironment(root: "/R", frameworks: [], bundleID: "b", team: "T", python: "/py", path: "/p",
+                                                  home: "/h", user: "u", package: package)
+        let path = try XCTUnwrap(env["DM_SHELL_PACKAGE"])
+        XCTAssertTrue(FileManager.default.fileExists(atPath: path + "/Package.swift"))
+        XCTAssertTrue(FileManager.default.fileExists(atPath: path + "/AppIcon.icon"))
+        XCTAssertFalse(path.hasPrefix(store))
+        XCTAssertNil(ShellInstall.projectEnvironment(root: "/R", frameworks: [], bundleID: "b", team: "T", python: "/py", path: "/p",
+                                                     home: "/h", user: "u")["DM_SHELL_PACKAGE"])
+    }
+
     func testCommandsAreExact() {
         let root = "/R/NX2Apple-shell"
         XCTAssertEqual(ShellInstall.buildArguments(workDir: "/W", team: "T"), ["--shell-framework", "/W/shell-framework", "--team-id", "T"])
@@ -272,6 +311,7 @@ final class ShellInstallTests: XCTestCase {
         env | sort > "\(state)/shell-env.txt"
         if [ "${DM_ENTITLEMENTS+set}" = set ] && [ -z "$DM_ENTITLEMENTS" ]; then touch "$SHELL_DIR/entitlements-empty"; else rm -f "$SHELL_DIR/entitlements-empty"; fi
         """)
+        try write(repo + "/frontend-ios/Package.swift", "// swift-tools-version: 5.9\n")
         return repo
     }
 
@@ -313,6 +353,7 @@ final class ShellInstallTests: XCTestCase {
         var i = ShellInstaller(xcrun: f.xcrun, repo: f.repo, python: "/usr/bin/python3", root: f.root, device: device, team: team)
         i.deviceName = "Z"
         i.pollInterval = 0.02
+        i.resources = nil
         return i
     }
 
@@ -362,7 +403,7 @@ final class ShellInstallTests: XCTestCase {
         XCTAssertEqual(try String(contentsOfFile: save), "my save")
         let env = try String(contentsOfFile: state + "/shell-env.txt")
         for line in ["DM_BUNDLE_ID=org.nxnative.shell", "DM_SHELL_FRAMEWORKS=\(f.framework)", "DM_TEAM_ID=TEAM123456",
-                     "SHELL_DIR=\(f.root)/project", "DM_XCODE_DERIVED_DATA=\(f.root)/derived-data", "FONT_PY=/usr/bin/python3"] {
+                     "SHELL_DIR=\(f.root)/project", "DM_XCODE_DERIVED_DATA=\(f.root)/derived-data", "FONT_PY=/usr/bin/python3", "DM_SHELL_PACKAGE=\(f.repo)/frontend-ios"] {
             XCTAssertTrue(env.contains(line), line)
         }
         let library = ShellLibrary.load(root: f.root)
@@ -425,6 +466,15 @@ final class ShellInstallTests: XCTestCase {
         XCTAssertFalse(calls.contains { $0.hasPrefix("xcodebuild") || $0.hasPrefix("devicectl device") })   // nothing was signed or installed
     }
 
+    func testMissingShellPackageStopsBeforeTheScript() throws {
+        let f = try makeFixture()
+        try fm.removeItem(atPath: f.repo + "/frontend-ios")
+        let r = run(f)
+        XCTAssertEqual(r.status, 1)
+        XCTAssertTrue(r.output.contains("FAIL: The shared app could not be prepared: no frontend-ios Swift package"), r.output)
+        XCTAssertFalse(fm.fileExists(atPath: state + "/shell-env.txt"), "build_shell.sh must not run")
+    }
+
     func testCLIChecksItsArguments() throws {
         var output = ""
         XCTAssertEqual(ShellCLI.run(["--install-shell", "--framework", "/x"], defaults: UserDefaults(suiteName: "nspb-shell-" + UUID().uuidString)!) { output += $0 }, 1)