craft-native 0.0.154 → 0.0.156

package/dist/ios/templates/CraftNativeScreen.swift

@@ -367,7 +367,12 @@ struct CraftNativeScreen: UIViewControllerRepresentable {
     let config: CraftConfig
 
     func makeUIViewController(context: Context) -> UINavigationController {
-        UINavigationController(rootViewController: CraftNativeScreenController(config: config))
+        let screen = CraftNativeScreenController(config: config)
+        // The shell hears the first frame (the app script starts after it)
+        // and `craft.navigation.open`, which has no paths to open here but
+        // web addresses, in the in-app browser.
+        screen.hybridEvents = CraftHybrid.shared
+        return UINavigationController(rootViewController: screen)
     }
 
     func updateUIViewController(_ controller: UINavigationController, context: Context) {}
@@ -2086,11 +2091,17 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     weak var hybridEvents: CraftHybridScreenEvents?
     private var hybridRendered = false
     private var runtimeDisposed = false
+    /// The app script (`nativeApp`, CraftHybrid.swift): a bundle route with
+    /// no screen, loaded once and never shown, that runs for the app's life.
+    /// It hears every `APP_STATE` and the app's events (`CRAFT_EVENT`), no
+    /// `DEEP_LINK`; it can open paths but not push, pop or style a bar.
+    let isAppScript: Bool
 
-    init(config: CraftConfig, routeName: String? = nil, routeParams: [String: Any] = [:]) {
+    init(config: CraftConfig, routeName: String? = nil, routeParams: [String: Any] = [:], isAppScript: Bool = false) {
         self.config = config
         self.routeName = routeName
         self.routeParams = routeParams
+        self.isAppScript = isAppScript
         super.init(nibName: nil, bundle: nil)
     }
 
@@ -2127,6 +2138,13 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         setupJavaScript()
         loadBundle()
         observeNativeEvents()
+        if isAppScript {
+            // Its bundle has run, so its listeners are in place: the app's
+            // events that waited for it arrive now, in order.
+            CraftEventManager.shared.appScriptReady { [weak self] event, detail in
+                self?.send(type: "CRAFT_EVENT", payload: ["event": event, "detail": detail])
+            }
+        }
     }
 
     override func traitCollectionDidChange(_ previousTraitCollection: UITraitCollection?) {
@@ -2280,6 +2298,13 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         let capabilities = CraftNativeActions.capabilities(config: config)
         let capabilityData = try? JSONSerialization.data(withJSONObject: capabilities)
         let capabilityJSON = capabilityData.flatMap { String(data: $0, encoding: .utf8) } ?? "[]"
+        // The app's site and build, as JSON strings: the site an all-native
+        // app's paths and links belong to (`devServerURL`), and the version a
+        // request or a crash report names.
+        let info = Bundle.main.infoDictionary
+        let appURL = Self.jsonString(config.devServerURL ?? "")
+        let appVersion = Self.jsonString(info?["CFBundleShortVersionString"] as? String ?? "")
+        let appBuild = Self.jsonString(info?["CFBundleVersion"] as? String ?? "")
         jsContext.evaluateScript("""
             globalThis.__stxNativeCallback = null;
             globalThis.__stxNativeBridge = {
@@ -2290,6 +2315,9 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
                 capabilities: \(capabilityJSON),
                 initialAppState: "\(CraftNativeActions.currentAppState())",
                 colorScheme: "\(colorScheme)",
+                appURL: \(appURL),
+                appVersion: \(appVersion),
+                appBuild: \(appBuild),
                 postMessage: function(message) { craftNativePostMessage(message); },
                 onMessage: function(callback) { globalThis.__stxNativeCallback = callback; }
             };
@@ -2350,6 +2378,13 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         """)
     }
 
+    /// `value` as a JavaScript string literal (JSON), quotes and all.
+    static func jsonString(_ value: String) -> String {
+        guard let data = try? JSONSerialization.data(withJSONObject: [value]),
+              let array = String(data: data, encoding: .utf8), array.count >= 2 else { return "\"\"" }
+        return String(array.dropFirst().dropLast())
+    }
+
     /// `"dark"` or `"light"` for the bundle's `dark:` classes (contract A4):
     /// the window's appearance once there is one, else the app's setting.
     private var colorScheme: String {
@@ -2379,6 +2414,9 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     ///   asynchronous `craft.storage` uses. `getSync` answers what `get` would.
     /// - `craft.snapshots.get(name)` (sync) and `set(name, value)` (a
     ///   promise): `Application Support/craft-snapshots/<name>.json`.
+    ///   `clear(keep?)` (a promise) deletes every snapshot but the names in
+    ///   `keep`, as a sign-out does; each removal is a `SNAPSHOT_CHANGED`
+    ///   for every screen.
     /// - `craft.secureStorage.getSync(key)`: the Keychain item the web page's
     ///   `craft.secureStorage.set` wrote.
     /// - `craft.navigation.setOptions({ title, largeTitle, hidden, backTitle,
@@ -2405,6 +2443,12 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
                 done.call(withArguments: [ok])
             }
         }
+        let snapshotClear: @convention(block) (JSValue, JSValue) -> Void = { keep, done in
+            let names = (keep.isUndefined || keep.isNull ? [] : (keep.toArray() ?? [])).compactMap { $0 as? String }
+            CraftSnapshots.clear(keeping: Set(names)) { ok in
+                done.call(withArguments: [ok])
+            }
+        }
         let config = self.config
         let secureGet: @convention(block) (String) -> String? = { key in
             config.enableSecureStorage ? CraftNativeActions.webSecureValue(forKey: key) : nil
@@ -2419,6 +2463,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         jsContext.setObject(storageSet, forKeyedSubscript: "craftNativeStorageSet" as NSString)
         jsContext.setObject(snapshotGet, forKeyedSubscript: "craftNativeSnapshotGet" as NSString)
         jsContext.setObject(snapshotSet, forKeyedSubscript: "craftNativeSnapshotSet" as NSString)
+        jsContext.setObject(snapshotClear, forKeyedSubscript: "craftNativeSnapshotClear" as NSString)
         jsContext.setObject(secureGet, forKeyedSubscript: "craftNativeSecureGet" as NSString)
         jsContext.setObject(setOptions, forKeyedSubscript: "craftNativeSetOptions" as NSString)
         // `AudioContext` and the rest of Web Audio, rendered natively.
@@ -2568,6 +2613,16 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
                                 else reject(new Error('craft.snapshots.set could not write ' + name));
                             });
                         });
+                    },
+                    // Every snapshot but the names in `keep` (a sign-out).
+                    clear: function(keep) {
+                        var names = Array.isArray(keep) ? keep.map(String) : [];
+                        return new Promise(function(resolve, reject) {
+                            craftNativeSnapshotClear(names, function(ok) {
+                                if (ok) resolve();
+                                else reject(new Error('craft.snapshots.clear could not remove every snapshot'));
+                            });
+                        });
                     }
                 });
                 keep('secureStorage', {
@@ -2623,6 +2678,8 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     /// `craft.navigation.setOptions`: this screen's bar. Every key is
     /// optional and only the keys given change.
     private func applyNavigationOptions(_ options: [String: Any]) {
+        // The app script has no screen, so no bar and no tab bar to change.
+        guard !isAppScript else { return }
         if options.keys.contains("title") {
             navigationItem.title = options["title"] as? String
             titleFromOptions = true
@@ -2826,20 +2883,23 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         observe(UIApplication.didBecomeActiveNotification, state: "active")
         observe(UIApplication.willResignActiveNotification, state: "inactive")
         observe(UIApplication.didEnterBackgroundNotification, state: "background")
-        lifecycleObservers.append(NotificationCenter.default.addObserver(
-            forName: UIResponder.keyboardWillChangeFrameNotification,
-            object: nil,
-            queue: .main
-        ) { [weak self] notification in
-            self?.applyKeyboardSafeArea(notification)
-        })
-        lifecycleObservers.append(NotificationCenter.default.addObserver(
-            forName: UIResponder.keyboardWillHideNotification,
-            object: nil,
-            queue: .main
-        ) { [weak self] notification in
-            self?.applyKeyboardSafeArea(notification, hidden: true)
-        })
+        // The app script has no screen for the keyboard to cover.
+        if !isAppScript {
+            lifecycleObservers.append(NotificationCenter.default.addObserver(
+                forName: UIResponder.keyboardWillChangeFrameNotification,
+                object: nil,
+                queue: .main
+            ) { [weak self] notification in
+                self?.applyKeyboardSafeArea(notification)
+            })
+            lifecycleObservers.append(NotificationCenter.default.addObserver(
+                forName: UIResponder.keyboardWillHideNotification,
+                object: nil,
+                queue: .main
+            ) { [weak self] notification in
+                self?.applyKeyboardSafeArea(notification, hidden: true)
+            })
+        }
         lifecycleObservers.append(NotificationCenter.default.addObserver(
             forName: CraftSnapshots.changed,
             object: nil,
@@ -2873,6 +2933,8 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         sounds.emit = { [weak self] payload in self?.send(type: "SOUND_EVENT", payload: payload) }
         streams.emit = { [weak self] payload in self?.send(type: "NETWORK_STREAM", payload: payload) }
         sendAppState(CraftNativeActions.currentAppState())
+        // Links are the screens' to show; the app script hears none.
+        guard !isAppScript else { return }
         deepLinkListener = DeepLinkManager.shared.addNativeListener { [weak self] url, initial in
             guard let self = self, self.navigationController?.topViewController === self else { return }
             var payload = CraftNativeActions.deepLinkData(url)
@@ -2952,7 +3014,9 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     }
 
     private func sendAppState(_ state: String) {
-        guard navigationController?.topViewController === self else { return }
+        // A screen hears it while it is on top of its stack; the app script,
+        // which is on no stack, always.
+        guard isAppScript || navigationController?.topViewController === self else { return }
         send(type: "APP_STATE", payload: ["state": state])
     }
 
@@ -2972,6 +3036,9 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     /// is up, and are logged.
     private func hybridFailed(_ message: String) {
         guard !hybridRendered else { return }
+        // The app script draws nothing for anything to stand in for: logged
+        // (by the caller) and left to run on.
+        guard !isAppScript else { return }
         hybridEvents?.nativeScreen(self, didFail: message)
     }
 
@@ -3014,7 +3081,8 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
                 ])
             }
         case "NAVIGATE", "NAVIGATE_REPLACE":
-            guard navigationController?.topViewController === self,
+            // A screen's own stack; the app script has none (it opens paths).
+            guard !isAppScript, navigationController?.topViewController === self,
                   let screen = payload["screen"] as? String, !screen.isEmpty,
                   let navigation = navigationController else { return }
             let params = payload["params"] as? [String: Any] ?? [:]
@@ -3034,13 +3102,13 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             guard let path = payload["path"] as? String, !path.isEmpty else { return }
             hybridEvents?.nativeScreen(self, open: path)
         case "NAVIGATE_BACK":
-            if navigationController?.topViewController === self {
+            if !isAppScript, navigationController?.topViewController === self {
                 navigationController?.popViewController(animated: true)
             }
         case "NAVIGATE_POP_TO_ROOT":
             // Back to the first screen of this screen's stack in one move: a
             // finished task (a saved workout) closes the way it was reached.
-            if navigationController?.topViewController === self {
+            if !isAppScript, navigationController?.topViewController === self {
                 navigationController?.popToRootViewController(animated: true)
             }
         case "API_REQUEST":
@@ -3181,7 +3249,8 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         renderCommitted(document)
         if !hybridRendered {
             hybridRendered = true
-            hybridEvents?.nativeScreenDidRender(self)
+            // The app script's drawing is never on screen: not a first frame.
+            if !isAppScript { hybridEvents?.nativeScreenDidRender(self) }
         }
     }
 

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

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

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

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

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

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

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

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

package/package.json

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