craft-native 0.0.155 → 0.0.158

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?) {
@@ -2168,7 +2186,14 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
 
     override func viewDidDisappear(_ animated: Bool) {
         super.viewDidDisappear(animated)
-        if isMovingFromParent || navigationController?.viewControllers.contains(where: { $0 === self }) == false {
+        // Gone for good only when its stack no longer holds it. UIKit's
+        // `isMovingFromParent` is no witness: a tab's first screen covered
+        // by a push while its own first appearance was still settling (an
+        // app script opening the sign-in screen at launch) reports it true
+        // while still the root of its stack, and the screen's script was
+        // torn down under it, frozen on whatever it showed then.
+        let inStack = navigationController?.viewControllers.contains(where: { $0 === self }) ?? false
+        if !inStack {
             disposeRuntime()
         } else {
             screenVisibilityChanged(false)
@@ -2280,6 +2305,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 +2322,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 +2385,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 +2421,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 +2450,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 +2470,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 +2620,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 +2685,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 +2890,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 +2940,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 +3021,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 +3043,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 +3088,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 +3109,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 +3256,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

@@ -26,6 +26,7 @@ import XCTest
 ///   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)
+///   labelid <id> <text>   that element's label is exactly text (a count, a status)
 ///   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
@@ -34,6 +35,7 @@ import XCTest
 ///   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?")
+///   ifid <id> <command…>  runs the command only when that element is there (a screen shown the first time)
 ///   log <text>
 ///
 /// Checks log `PASS …` / `FAIL …` lines into driver.log; matrix.sh counts them.
@@ -153,153 +155,167 @@ final class DriverTests: XCTestCase {
         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) }
+            run(line)
+        }
+    }
+
+    func run(_ line: String) {
+        let parts = line.split(separator: " ", maxSplits: 1).map(String.init)
+        let command = parts[0]
+        let arg = parts.count > 1 ? parts[1] : ""
+        switch command {
+        case "ifid":
+            let rest = arg.split(separator: " ", maxSplits: 1).map(String.init)
+            if rest.count == 2, app.descendants(matching: .any)[rest[0]].waitForExistence(timeout: 3) { note("ifid \(rest[0]): shown"); run(rest[1]) }
+            else { note("ifid \(rest.first ?? ""): not shown") }
+        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 "labelid":
+            let idParts = arg.split(separator: " ", maxSplits: 1).map(String.init)
+            let target = app.descendants(matching: .any)[idParts[0]]
+            let want = idParts.count > 1 ? idParts[1] : ""
+            let seen = target.waitForExistence(timeout: 5) ? target.label : "(missing)"
+            check(seen == want, "labelid \(idParts[0]) \(want) (saw \(seen))")
+        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
                 }
-                note("dismiss \(label): \(done ? "tapped" : "none shown")")
-            case "log": note(arg)
-            default: XCTFail("Unknown command \(command)"); note("FAIL unknown command \(command)")
+            } 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/package.json

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