@houwert/conductor 0.2.0

package/dist/drivers/ios.js

@@ -0,0 +1,328 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IOSDriver = void 0;
+/**
+ * Direct HTTP client for the Conductor iOS XCTest driver.
+ * The driver runs inside the simulator at http://127.0.0.1:1075 (or custom port).
+ *
+ * Protocol: plain HTTP REST with JSON bodies.
+ * Endpoints map directly to XCUITest actions — no JVM required.
+ */
+const http_1 = __importDefault(require("http"));
+const promises_1 = __importDefault(require("fs/promises"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+class IOSDriver {
+    constructor(port = 1075, host = '127.0.0.1', deviceId) {
+        this.port = port;
+        this.host = host;
+        this.deviceId = deviceId;
+        this._recordingProcess = null;
+    }
+    request(method, path, body) {
+        return new Promise((resolve, reject) => {
+            const bodyBuf = body !== undefined ? Buffer.from(JSON.stringify(body), 'utf-8') : undefined;
+            const options = {
+                hostname: this.host,
+                port: this.port,
+                path,
+                method,
+                headers: {
+                    ...(bodyBuf
+                        ? { 'Content-Type': 'application/json', 'Content-Length': bodyBuf.length }
+                        : {}),
+                },
+            };
+            const req = http_1.default.request(options, (res) => {
+                const chunks = [];
+                res.on('data', (chunk) => chunks.push(chunk));
+                res.on('end', () => resolve({ status: res.statusCode ?? 0, data: Buffer.concat(chunks) }));
+                res.on('error', reject);
+            });
+            req.setTimeout(30000, () => {
+                req.destroy(new Error(`iOS driver request timed out: ${method} ${path}`));
+            });
+            req.on('error', reject);
+            if (bodyBuf)
+                req.write(bodyBuf);
+            req.end();
+        });
+    }
+    async post(path, body) {
+        const { status, data } = await this.request('POST', `/${path}`, body);
+        if (status < 200 || status >= 300) {
+            throw new Error(`iOS driver ${path} failed (HTTP ${status}): ${data.toString('utf-8').slice(0, 200)}`);
+        }
+    }
+    async get(path) {
+        const { status, data } = await this.request('GET', `/${path}`);
+        if (status < 200 || status >= 300) {
+            throw new Error(`iOS driver GET ${path} failed (HTTP ${status}): ${data.toString('utf-8').slice(0, 200)}`);
+        }
+        return JSON.parse(data.toString('utf-8'));
+    }
+    requireDeviceId() {
+        if (!this.deviceId)
+            throw new Error('IOSDriver: deviceId is required for this operation');
+        return this.deviceId;
+    }
+    simctl(args) {
+        const _id = this.requireDeviceId();
+        return new Promise((resolve, reject) => {
+            const proc = (0, child_process_1.spawn)('xcrun', ['simctl', ...args], { stdio: 'ignore' });
+            proc.on('close', (code) => code === 0 ? resolve() : reject(new Error(`xcrun simctl ${args[0]} failed (exit ${code})`)));
+            proc.on('error', reject);
+        });
+    }
+    simctlCapture(args) {
+        this.requireDeviceId();
+        return new Promise((resolve, reject) => {
+            const proc = (0, child_process_1.spawn)('xcrun', ['simctl', ...args], { stdio: ['ignore', 'pipe', 'pipe'] });
+            let out = '';
+            let err = '';
+            proc.stdout?.on('data', (chunk) => {
+                out += chunk.toString();
+            });
+            proc.stderr?.on('data', (chunk) => {
+                err += chunk.toString();
+            });
+            proc.on('close', (code) => code === 0
+                ? resolve(out.trim())
+                : reject(new Error(`xcrun simctl ${args[0]} failed: ${err.trim()}`)));
+            proc.on('error', reject);
+        });
+    }
+    async isAlive() {
+        try {
+            const { status } = await this.request('GET', '/status');
+            return status >= 200 && status < 300;
+        }
+        catch {
+            return false;
+        }
+    }
+    async deviceInfo() {
+        return this.get('deviceInfo');
+    }
+    async tap(x, y, duration) {
+        await this.post('touch', { x, y, ...(duration !== undefined ? { duration } : {}) });
+    }
+    async swipe(startX, startY, endX, endY, duration, appIds) {
+        await this.post('swipeV2', {
+            startX,
+            startY,
+            endX,
+            endY,
+            duration,
+            ...(appIds ? { appIds } : {}),
+        });
+    }
+    async inputText(text, appIds = []) {
+        await this.post('inputText', { text, appIds });
+    }
+    async pressKey(key) {
+        await this.post('pressKey', { key });
+    }
+    async pressButton(button) {
+        await this.post('pressButton', { button });
+    }
+    async launchApp(bundleId, args) {
+        if (args && Object.keys(args).length > 0) {
+            const deviceId = this.requireDeviceId();
+            // xctest /launchApp doesn't support launch args — use simctl
+            await this.simctl(['terminate', deviceId, bundleId]).catch(() => { });
+            const argPairs = [];
+            for (const [key, value] of Object.entries(args)) {
+                argPairs.push(`-${key}`, value);
+            }
+            await this.simctl(['launch', '--terminate-running-process', deviceId, bundleId, ...argPairs]);
+        }
+        else {
+            await this.post('launchApp', { bundleId });
+        }
+    }
+    async terminateApp(appId) {
+        await this.post('terminateApp', { appId });
+    }
+    async clearAppState(bundleId) {
+        const deviceId = this.requireDeviceId();
+        // Terminate first to prevent app from saving state after clear
+        await this.simctl(['terminate', deviceId, bundleId]).catch(() => { });
+        // Capture the .app bundle path before uninstalling — uninstall deletes the UUID directory
+        // so the path is invalid by the time we need to reinstall from it.
+        const appPath = await this.simctlCapture(['get_app_container', deviceId, bundleId, 'app']);
+        // Copy the .app bundle to a temp dir so it survives the uninstall
+        const tmpDir = await promises_1.default.mkdtemp(path_1.default.join(os_1.default.tmpdir(), 'conductor-clear-state-'));
+        const tmpAppPath = path_1.default.join(tmpDir, path_1.default.basename(appPath));
+        try {
+            await promises_1.default.cp(appPath, tmpAppPath, { recursive: true });
+            await this.simctl(['uninstall', deviceId, bundleId]);
+            await this.simctl(['install', deviceId, tmpAppPath]);
+        }
+        finally {
+            await promises_1.default.rm(tmpDir, { recursive: true, force: true }).catch(() => { });
+        }
+    }
+    async clearKeychain() {
+        const deviceId = this.requireDeviceId();
+        await this.simctl(['keychain', deviceId, 'reset']);
+    }
+    async openLink(url) {
+        const deviceId = this.requireDeviceId();
+        await this.simctl(['openurl', deviceId, url]);
+    }
+    async setLocation(latitude, longitude) {
+        const deviceId = this.requireDeviceId();
+        await this.simctl(['location', deviceId, 'set', `${latitude},${longitude}`]);
+    }
+    async setOrientation(orientation) {
+        await this.post('setOrientation', { orientation });
+    }
+    async setPermissions(appId, permissions) {
+        // All iOS permissions the XCTest runner's interruption monitor can handle.
+        const IOS_ALL_PERMISSIONS = [
+            'notifications',
+            'camera',
+            'microphone',
+            'photos',
+            'location',
+            'contacts',
+            'calendar',
+            'reminders',
+            'bluetooth',
+            'health',
+            'motion',
+            'speech',
+            'tracking',
+            'faceId',
+            'homeKit',
+            'mediaLibrary',
+            'siri',
+            'localNetwork',
+        ];
+        // Expand 'all' to every known permission
+        const expanded = { ...permissions };
+        const allValue = expanded['all'];
+        if (allValue !== undefined) {
+            delete expanded['all'];
+            for (const perm of IOS_ALL_PERMISSIONS) {
+                if (!(perm in expanded)) {
+                    expanded[perm] = allValue;
+                }
+            }
+        }
+        // ── simctl privacy ────────────────────────────────────────────────────────
+        // For simulators: use simctl privacy grant/revoke to pre-approve permissions
+        // in TCC so no dialog ever appears. This covers ALL permission types including
+        // ATT (tracking), local network, etc. that the XCTest runner can't intercept.
+        //
+        // simctl service names differ from Maestro key names for some entries.
+        const SIMCTL_SERVICE = {
+            notifications: 'notifications',
+            camera: 'camera',
+            microphone: 'microphone',
+            photos: 'photos',
+            location: 'location',
+            contacts: 'contacts',
+            calendar: 'calendar',
+            reminders: 'reminders',
+            bluetooth: 'bluetooth',
+            motion: 'motion',
+            speech: 'speech',
+            tracking: 'tracking',
+            faceId: 'faceid',
+            homeKit: 'homekit',
+            mediaLibrary: 'media-library',
+            siri: 'siri',
+        };
+        const deviceId = this.requireDeviceId();
+        if (allValue !== undefined) {
+            // Best-effort bulk grant/revoke. 'all' covers TCC-managed permissions but
+            // NOT ATT (tracking), which needs an explicit individual call below.
+            const action = allValue === 'allow' ? 'grant' : 'revoke';
+            try {
+                await this.simctl(['privacy', deviceId, action, 'all', appId]);
+            }
+            catch {
+                /* not installed yet */
+            }
+        }
+        // Always grant/revoke each permission individually — some services (e.g. tracking/ATT)
+        // are not included in 'grant all' and require an explicit call.
+        for (const [perm, value] of Object.entries(expanded)) {
+            const service = SIMCTL_SERVICE[perm];
+            if (!service)
+                continue;
+            const action = value === 'allow' ? 'grant' : 'revoke';
+            try {
+                await this.simctl(['privacy', deviceId, action, service, appId]);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        // Also notify the XCTest runner — its interruption monitor handles the
+        // notifications dialog and acts as a fallback for any dialog we missed.
+        await this.post('setPermissions', { permissions: expanded });
+    }
+    async addMedia(filePath) {
+        const deviceId = this.requireDeviceId();
+        await this.simctl(['addmedia', deviceId, filePath]);
+    }
+    async setAirplaneMode(_enabled) {
+        throw new Error('setAirplaneMode is not supported on iOS simulators');
+    }
+    async getAirplaneMode() {
+        throw new Error('getAirplaneMode is not supported on iOS simulators');
+    }
+    async startRecording(outputPath) {
+        const deviceId = this.requireDeviceId();
+        if (this._recordingProcess)
+            await this.stopRecording();
+        this._recordingProcess = (0, child_process_1.spawn)('xcrun', ['simctl', 'io', deviceId, 'recordVideo', '--codec', 'hevc', outputPath], { stdio: 'ignore' });
+    }
+    async stopRecording() {
+        if (this._recordingProcess) {
+            this._recordingProcess.kill('SIGINT');
+            await new Promise((r) => setTimeout(r, 500));
+            this._recordingProcess = null;
+        }
+    }
+    async viewHierarchy(excludeKeyboardElements = false, appIds = []) {
+        const { status, data } = await this.request('POST', '/viewHierarchy', {
+            appIds,
+            excludeKeyboardElements,
+        });
+        if (status < 200 || status >= 300) {
+            throw new Error(`iOS driver viewHierarchy failed (HTTP ${status}): ${data.toString('utf-8').slice(0, 200)}`);
+        }
+        return JSON.parse(data.toString('utf-8'));
+    }
+    async screenshot() {
+        const { status, data } = await this.request('GET', '/screenshot');
+        if (status < 200 || status >= 300) {
+            throw new Error(`iOS driver screenshot failed (HTTP ${status})`);
+        }
+        return data;
+    }
+    async isScreenStatic() {
+        const result = await this.get('isScreenStatic');
+        return result.isScreenStatic;
+    }
+    async runningApp(appIds) {
+        const { status, data } = await this.request('POST', '/runningApp', { appIds });
+        if (status < 200 || status >= 300) {
+            throw new Error(`iOS driver runningApp failed (HTTP ${status}): ${data.toString('utf-8').slice(0, 200)}`);
+        }
+        const parsed = JSON.parse(data.toString('utf-8'));
+        const id = parsed.runningAppBundleId;
+        if (!id)
+            throw new Error('Could not determine foreground app');
+        return id;
+    }
+}
+exports.IOSDriver = IOSDriver;

package/dist/drivers/js-engine.js

@@ -0,0 +1,150 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeScript = executeScript;
+/**
+ * JavaScript execution engine for runScript commands.
+ *
+ * Mirrors Maestro's GraalJsEngine behaviour using Node's built-in vm module:
+ *  - All flow env vars injected as globals
+ *  - `output` object shared with the rest of the flow (mutations persist)
+ *  - `http` client with get/post/put/delete/request
+ *  - `json(text)` and `relativePoint(x, y)` helpers
+ *  - Top-level `await` supported (script is wrapped in an async IIFE)
+ */
+const node_vm_1 = __importDefault(require("node:vm"));
+const node_child_process_1 = require("node:child_process");
+/**
+ * Synchronous HTTP request — matches Maestro's GraalVM behaviour where http.*
+ * calls block until the response arrives (no await needed in scripts).
+ *
+ * Implemented via spawnSync so the VM thread blocks while fetch runs in a
+ * child Node process, keeping script semantics identical to the JVM engine.
+ */
+function httpRequest(url, method, options = {}) {
+    let fullUrl = url;
+    if (options.params && Object.keys(options.params).length > 0) {
+        fullUrl += '?' + new URLSearchParams(options.params).toString();
+    }
+    const headers = { ...(options.headers ?? {}) };
+    const bodyStr = options.body !== undefined
+        ? typeof options.body === 'string'
+            ? options.body
+            : JSON.stringify(options.body)
+        : undefined;
+    if (bodyStr !== undefined && !headers['Content-Type']) {
+        headers['Content-Type'] = 'application/json';
+    }
+    const fetchOpts = { method };
+    if (Object.keys(headers).length > 0)
+        fetchOpts.headers = headers;
+    if (bodyStr !== undefined)
+        fetchOpts.body = bodyStr;
+    // Run fetch in a child process so this call is synchronous from the script's
+    // perspective (mirrors the blocking Java HTTP client in Maestro's GraalVM).
+    const childScript = `(async () => {
+  try {
+    const res = await fetch(${JSON.stringify(fullUrl)}, ${JSON.stringify(fetchOpts)});
+    const body = await res.text();
+    const headers = {};
+    res.headers.forEach((v, k) => { headers[k] = v; });
+    process.stdout.write(JSON.stringify({ ok: res.ok, status: res.status, body, headers }));
+  } catch (e) {
+    process.stderr.write(String(e));
+    process.exit(1);
+  }
+})();`;
+    const result = (0, node_child_process_1.spawnSync)(process.execPath, ['-e', childScript], {
+        encoding: 'utf8',
+        timeout: 30000,
+    });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0)
+        throw new Error(result.stderr || 'HTTP request failed');
+    return JSON.parse(result.stdout);
+}
+const httpBinding = {
+    get: (url, opts) => httpRequest(url, 'GET', opts),
+    post: (url, opts) => httpRequest(url, 'POST', opts),
+    put: (url, opts) => httpRequest(url, 'PUT', opts),
+    delete: (url, opts) => httpRequest(url, 'DELETE', opts),
+    request: (url, opts) => httpRequest(url, opts?.method ?? 'GET', opts),
+};
+// ── Script execution ──────────────────────────────────────────────────────────
+/**
+ * Execute a JavaScript script in an isolated VM context.
+ *
+ * @param script     JS source code
+ * @param env        Flow env vars injected as global variables (read-only by convention)
+ * @param output     Shared output object — mutations persist back to the flow
+ * @param sourceName Path shown in stack traces
+ * @param maestroObj Optional maestro object injected as `maestro` global
+ */
+async function executeScript(script, env, output, sourceName = 'script', maestroObj) {
+    const sandbox = {
+        // Env vars as globals (mirrors Maestro GraalJsEngine behaviour)
+        ...env,
+        // Output properties as globals so conditions can reference them directly
+        // (e.g. `auth` in a when.true condition refers to `output.auth`)
+        ...output,
+        // Shared output — mutations are visible to subsequent commands
+        output,
+        // Maestro object (platform, copiedText, etc.)
+        maestro: maestroObj ?? {},
+        // API surface
+        http: httpBinding,
+        json: (text) => JSON.parse(text),
+        relativePoint: (x, y) => `${Math.ceil(x * 100)}%,${Math.ceil(y * 100)}%`,
+        console: {
+            log: (...args) => {
+                console.log(...args);
+            },
+            warn: (...args) => {
+                console.warn(...args);
+            },
+            error: (...args) => {
+                console.error(...args);
+            },
+        },
+        // Standard JS globals (not available in vm context by default)
+        Date,
+        Math,
+        JSON,
+        parseInt,
+        parseFloat,
+        isNaN,
+        isFinite,
+        Number,
+        String,
+        Boolean,
+        Array,
+        Object,
+        RegExp,
+        Error,
+        TypeError,
+        RangeError,
+        Map,
+        Set,
+        Symbol,
+        Uint8Array,
+        // Async plumbing
+        Promise,
+        setTimeout,
+        clearTimeout,
+    };
+    // Proxy prevents ReferenceError for undeclared variables (e.g. ${auth == 'sign-in'}
+    // when `auth` is an optional env param not passed by the caller). Matches Maestro's
+    // GraalJS behaviour where undeclared vars resolve to undefined instead of throwing.
+    const proxy = new Proxy(sandbox, {
+        has: () => true,
+        get: (target, key) => (key in target ? target[key] : undefined),
+    });
+    node_vm_1.default.createContext(proxy);
+    // Wrap in async IIFE so scripts can use top-level await
+    const wrapped = `(async () => {\n${script}\n})()`;
+    const promise = node_vm_1.default.runInContext(wrapped, proxy, { filename: sourceName });
+    await promise;
+}

package/dist/drivers/wait.js

@@ -0,0 +1,211 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPTIONAL_TIMEOUT_MS = void 0;
+exports.waitForIOSElement = waitForIOSElement;
+exports.waitForAndroidElement = waitForAndroidElement;
+exports.waitUntilIOSElementGone = waitUntilIOSElementGone;
+exports.waitUntilAndroidElementGone = waitUntilAndroidElementGone;
+exports.waitForIOSScreenToSettle = waitForIOSScreenToSettle;
+exports.waitForIOSTransitionToSettle = waitForIOSTransitionToSettle;
+exports.waitForIOSHierarchyToSettle = waitForIOSHierarchyToSettle;
+exports.waitForAndroidHierarchyToSettle = waitForAndroidHierarchyToSettle;
+const element_resolver_js_1 = require("./element-resolver.js");
+const utils_js_1 = require("../utils.js");
+const DEFAULT_TIMEOUT_MS = 17000;
+const DEFAULT_INTERVAL_MS = 500;
+exports.OPTIONAL_TIMEOUT_MS = 7000;
+async function waitForIOSElement(getHierarchy, selector, timeoutMs = DEFAULT_TIMEOUT_MS, intervalMs = DEFAULT_INTERVAL_MS) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const root = await getHierarchy();
+            const el = (0, element_resolver_js_1.findIOSElement)(root, selector);
+            if (el)
+                return el;
+        }
+        catch {
+            // Hierarchy fetch failed; keep retrying
+        }
+        await (0, utils_js_1.sleep)(intervalMs);
+    }
+    const desc = selectorDesc(selector);
+    throw new Error(`Element not found after ${timeoutMs}ms: ${desc}`);
+}
+async function waitForAndroidElement(getHierarchy, selector, timeoutMs = DEFAULT_TIMEOUT_MS, intervalMs = DEFAULT_INTERVAL_MS) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const xml = await getHierarchy();
+            const el = (0, element_resolver_js_1.findAndroidElement)(xml, selector);
+            if (el)
+                return el;
+        }
+        catch {
+            // Hierarchy fetch failed; keep retrying
+        }
+        await (0, utils_js_1.sleep)(intervalMs);
+    }
+    const desc = selectorDesc(selector);
+    throw new Error(`Element not found after ${timeoutMs}ms: ${desc}`);
+}
+/**
+ * Wait until an iOS element is gone from the hierarchy.
+ * Fast path: if element is absent on the first check, resolves immediately.
+ * Otherwise polls every 500 ms until absent or outer timeout (default 7 s) expires.
+ */
+async function waitUntilIOSElementGone(getHierarchy, selector, timeoutMs = exports.OPTIONAL_TIMEOUT_MS) {
+    const deadline = Date.now() + timeoutMs;
+    do {
+        try {
+            const root = await getHierarchy();
+            if (!(0, element_resolver_js_1.findIOSElement)(root, selector))
+                return; // fast path or gone
+        }
+        catch {
+            return; // hierarchy fetch failed — treat as gone
+        }
+        await (0, utils_js_1.sleep)(DEFAULT_INTERVAL_MS);
+    } while (Date.now() < deadline);
+    const desc = selectorDesc(selector);
+    throw new Error(`Element still visible after ${timeoutMs}ms: ${desc}`);
+}
+/**
+ * Wait until an Android element is gone from the hierarchy.
+ * Fast path: if element is absent on the first check, resolves immediately.
+ * Otherwise polls every 500 ms until absent or outer timeout (default 7 s) expires.
+ */
+async function waitUntilAndroidElementGone(getHierarchy, selector, timeoutMs = exports.OPTIONAL_TIMEOUT_MS) {
+    const deadline = Date.now() + timeoutMs;
+    do {
+        try {
+            const xml = await getHierarchy();
+            if (!(0, element_resolver_js_1.findAndroidElement)(xml, selector))
+                return; // fast path or gone
+        }
+        catch {
+            return; // hierarchy fetch failed — treat as gone
+        }
+        await (0, utils_js_1.sleep)(DEFAULT_INTERVAL_MS);
+    } while (Date.now() < deadline);
+    const desc = selectorDesc(selector);
+    throw new Error(`Element still visible after ${timeoutMs}ms: ${desc}`);
+}
+/**
+ * Wait until the iOS screen is visually static, mirroring Maestro's `waitUntilScreenIsStatic`.
+ * Calls the XCTest runner's /isScreenStatic endpoint, which takes two back-to-back screenshots
+ * and returns true when their SHA256 hashes match. Retries until stable or timeout.
+ * Times out silently — the next command's waitForElement will handle any remaining delay.
+ */
+async function waitForIOSScreenToSettle(isScreenStatic, timeoutMs = 3000) {
+    const deadline = Date.now() + timeoutMs;
+    do {
+        try {
+            if (await isScreenStatic())
+                return;
+        }
+        catch {
+            // request failed — keep retrying
+        }
+    } while (Date.now() < deadline);
+    // Timed out — proceed anyway
+}
+/**
+ * Two-phase settle for any action that triggers a screen transition.
+ *
+ * A plain `waitForIOSScreenToSettle` can return false-positive immediately if
+ * called before the transition animation has started.
+ *
+ * Phase 1 — wait for transition to START (screen becomes non-static), up to `changeTimeoutMs`.
+ *   If the screen never moves, the action completed without animation; proceed immediately.
+ * Phase 2 — wait for transition to FINISH (screen becomes static again), up to `settleTimeoutMs`.
+ */
+async function waitForIOSTransitionToSettle(isScreenStatic, changeTimeoutMs = 1500, settleTimeoutMs = 3000) {
+    // Phase 1: wait until screen starts changing
+    const changeDeadline = Date.now() + changeTimeoutMs;
+    let navigationStarted = false;
+    do {
+        try {
+            if (!(await isScreenStatic())) {
+                navigationStarted = true;
+                break;
+            }
+        }
+        catch {
+            // request failed — keep retrying
+        }
+    } while (Date.now() < changeDeadline);
+    if (!navigationStarted)
+        return; // link opened without visible navigation animation
+    // Phase 2: wait until screen stops changing
+    await waitForIOSScreenToSettle(isScreenStatic, settleTimeoutMs);
+}
+/**
+ * Wait until the iOS view hierarchy stops changing between consecutive polls.
+ * Mirrors Maestro's `waitForAppToSettle` / `waitUntilScreenIsStatic` logic.
+ * Times out silently so the next command (which retries on its own) can proceed.
+ */
+async function waitForIOSHierarchyToSettle(getHierarchy, timeoutMs = 3000, intervalMs = 200) {
+    const deadline = Date.now() + timeoutMs;
+    let prev = null;
+    while (Date.now() < deadline) {
+        try {
+            const root = await getHierarchy();
+            const curr = JSON.stringify(root);
+            if (curr === prev)
+                return; // stable
+            prev = curr;
+        }
+        catch {
+            // hierarchy fetch failed — keep waiting
+        }
+        await (0, utils_js_1.sleep)(intervalMs);
+    }
+    // Timed out — proceed anyway; the next assertVisible will retry
+}
+/**
+ * Wait until the Android view hierarchy XML stops changing between consecutive polls.
+ */
+async function waitForAndroidHierarchyToSettle(getHierarchy, timeoutMs = 3000, intervalMs = 200) {
+    const deadline = Date.now() + timeoutMs;
+    let prev = null;
+    while (Date.now() < deadline) {
+        try {
+            const xml = await getHierarchy();
+            if (xml === prev)
+                return; // stable
+            prev = xml;
+        }
+        catch {
+            // ignore
+        }
+        await (0, utils_js_1.sleep)(intervalMs);
+    }
+}
+function selectorDesc(sel) {
+    const parts = [];
+    if (sel.query)
+        parts.push(`query="${sel.query}"`);
+    if (sel.text)
+        parts.push(`text="${sel.text}"`);
+    if (sel.id)
+        parts.push(`id="${sel.id}"`);
+    if (sel.index !== undefined)
+        parts.push(`index=${sel.index}`);
+    if (sel.enabled !== undefined)
+        parts.push(`enabled=${sel.enabled}`);
+    if (sel.checked !== undefined)
+        parts.push(`checked=${sel.checked}`);
+    if (sel.focused !== undefined)
+        parts.push(`focused=${sel.focused}`);
+    if (sel.selected !== undefined)
+        parts.push(`selected=${sel.selected}`);
+    if (sel.below)
+        parts.push(`below(${selectorDesc(sel.below)})`);
+    if (sel.above)
+        parts.push(`above(${selectorDesc(sel.above)})`);
+    if (sel.leftOf)
+        parts.push(`leftOf(${selectorDesc(sel.leftOf)})`);
+    if (sel.rightOf)
+        parts.push(`rightOf(${selectorDesc(sel.rightOf)})`);
+    return parts.join(', ') || '(no selector)';
+}