@tapflowio/ios-agent 0.13.0 → 0.14.0

package/dist/XCUITreeReader.js

@@ -0,0 +1,194 @@
+import { spawn, execFile } from 'child_process';
+import { promisify } from 'util';
+import { readdirSync } from 'fs';
+import { join } from 'path';
+import { createLogger, PlatformError } from '@tapflowio/agent-core';
+import { parseTreeText } from './xcuiTree.js';
+const logger = createLogger('ios-agent:xcui-tree');
+const execFileAsync = promisify(execFile);
+const RUNNER_DIR = join(import.meta.dirname, '..', 'xctest-runner');
+const PROJECT = join(RUNNER_DIR, 'TapflowTreeRunner.xcodeproj');
+const BUILD_DIR = join(RUNNER_DIR, 'build');
+const PRODUCTS_DIR = join(BUILD_DIR, 'Build', 'Products');
+const SCHEME = 'TreeRunner';
+// The in-simulator host app the UI-test runner attaches to. Terminating it ends
+// the test session so the HTTP port is released (killing the xcodebuild wrapper
+// alone does not tear the in-simulator process down).
+const RUNNER_HOST_BUNDLE = 'dev.tapflow.treerunner.host';
+// Fixed port: xcodebuild does not propagate host env to the in-simulator test
+// runner, so a per-udid port can't be passed this way. A single resident runner
+// (guarded below) means no collision; concurrent multi-device is deferred (Q8).
+const PORT = 22087;
+const defaultNative = {
+    xctestrunReady() {
+        // test-without-building needs the .xctestrun, not just the .app — gate on it.
+        try {
+            return readdirSync(PRODUCTS_DIR).some((f) => f.endsWith('.xctestrun'));
+        }
+        catch {
+            return false;
+        }
+    },
+    async build(destination) {
+        await execFileAsync('xcodebuild', ['build-for-testing', '-project', PROJECT, '-scheme', SCHEME, '-destination', destination, '-derivedDataPath', BUILD_DIR, '-quiet'], { timeout: 300_000, maxBuffer: 64 * 1024 * 1024 });
+    },
+    spawn(destination, port) {
+        return spawn('xcodebuild', ['test-without-building', '-project', PROJECT, '-scheme', SCHEME, '-destination', destination, '-derivedDataPath', BUILD_DIR, '-quiet'], { env: { ...process.env, TAPFLOW_TREE_PORT: String(port) }, stdio: 'ignore', detached: true });
+    },
+    terminateHost(udid) {
+        execFile('xcrun', ['simctl', 'terminate', udid, RUNNER_HOST_BUNDLE], () => { });
+    },
+};
+// Drives the resident XCUITest tree runner: builds it once, launches it (staying
+// resident), and queries GET /tree over the simulator-shared loopback. Replaces
+// the AXUIElement path (UITreeReader), which required a Simulator.app window.
+export class XCUITreeReader {
+    native;
+    runner;
+    building;
+    starting;
+    constructor(native = defaultNative) {
+        this.native = native;
+    }
+    destination(udid) {
+        // No arch — xcodebuild resolves it (arm64 on Apple Silicon, x86_64 on Intel).
+        return `platform=iOS Simulator,id=${udid}`;
+    }
+    async ensureBuilt(udid) {
+        if (this.native.xctestrunReady())
+            return;
+        if (this.building)
+            return this.building;
+        this.building = (async () => {
+            logger.info('building tree runner (first run — cached afterwards)...');
+            await this.native.build(this.destination(udid));
+            logger.info('tree runner built');
+        })();
+        try {
+            await this.building;
+        }
+        catch (e) {
+            throw new PlatformError(`failed to build the UI-tree runner — ensure Xcode and an iOS simulator runtime are installed (xcode-select -p): ${e.message.slice(0, 300)}`);
+        }
+        finally {
+            this.building = undefined;
+        }
+    }
+    runnerAlive(h) {
+        return !!h && h.proc.exitCode === null && !h.proc.killed;
+    }
+    async ensureRunner(udid) {
+        if (this.runnerAlive(this.runner) && this.runner.udid === udid)
+            return this.runner;
+        // Serialize concurrent callers so we never double-spawn or hand back an
+        // un-ready runner (a second caller must await waitReady, not just the object).
+        if (this.starting) {
+            const h = await this.starting.catch(() => undefined);
+            if (h && this.runnerAlive(h) && h.udid === udid)
+                return h;
+        }
+        this.starting = this.launchRunner(udid);
+        try {
+            return await this.starting;
+        }
+        finally {
+            this.starting = undefined;
+        }
+    }
+    async launchRunner(udid) {
+        this.stop(); // tear down any stale/other-udid runner first
+        await this.ensureBuilt(udid);
+        const proc = this.native.spawn(this.destination(udid), PORT);
+        proc.on('error', (e) => logger.error('tree runner process error:', e.message));
+        const handle = { proc, udid, port: PORT };
+        this.runner = handle;
+        await this.waitReady(handle);
+        return handle;
+    }
+    async waitReady(handle) {
+        for (let i = 0; i < 90; i++) {
+            if (!this.runnerAlive(handle)) {
+                if (this.runner === handle)
+                    this.runner = undefined;
+                throw new PlatformError('tree runner exited before becoming ready — check Xcode/simulator state');
+            }
+            try {
+                const r = await fetch(`http://localhost:${handle.port}/health`, { signal: AbortSignal.timeout(1000) });
+                if (r.ok)
+                    return;
+            }
+            catch {
+                /* not listening yet */
+            }
+            await new Promise((r) => setTimeout(r, 1000));
+        }
+        this.stop();
+        throw new PlatformError('tree runner did not become ready in time');
+    }
+    async read(udid, bundleId) {
+        if (!bundleId)
+            throw new PlatformError('UI tree query needs a foreground app — launch an app first');
+        const { port } = await this.ensureRunner(udid);
+        let text;
+        try {
+            const r = await fetch(`http://localhost:${port}/tree?bundleId=${encodeURIComponent(bundleId)}`, { signal: AbortSignal.timeout(10_000) });
+            if (!r.ok)
+                throw new PlatformError(`tree runner returned HTTP ${r.status} for ${bundleId}`);
+            text = await r.text();
+        }
+        catch (e) {
+            if (e instanceof PlatformError)
+                throw e;
+            throw new PlatformError(`UI tree query failed: ${e.message}`);
+        }
+        // Guard against a garbage / wrong-bundleId body silently parsing to an empty
+        // tree — consumers must see an error, never a false "screen has no elements".
+        if (!text.includes('Element subtree:') && !text.includes('Application,')) {
+            throw new PlatformError(`tree runner returned an unexpected response for ${bundleId} — is the app running in the foreground?`);
+        }
+        return parseTreeText(text);
+    }
+    // Stop the resident runner regardless of which device it serves.
+    stop() {
+        const handle = this.runner;
+        if (!handle)
+            return;
+        this.runner = undefined;
+        this.killHandle(handle);
+    }
+    // Stop only if the runner currently serves this device — so shutting down one
+    // booted device does not kill another device's runner.
+    stopIfDevice(udid) {
+        if (this.runner?.udid === udid)
+            this.stop();
+    }
+    killHandle(handle) {
+        const { proc, udid } = handle;
+        const pid = proc.pid;
+        // detached spawn → the child leads its own group; kill the whole group.
+        try {
+            if (pid)
+                process.kill(-pid, 'SIGTERM');
+            else
+                proc.kill('SIGTERM');
+        }
+        catch {
+            /* already gone */
+        }
+        // The in-simulator test host is not in that group — terminate it so the HTTP
+        // port is released instead of lingering.
+        this.native.terminateHost(udid);
+        // SIGKILL fallback if SIGTERM did not take.
+        const timer = setTimeout(() => {
+            try {
+                if (pid)
+                    process.kill(-pid, 'SIGKILL');
+            }
+            catch {
+                /* gone */
+            }
+        }, 3000);
+        timer.unref?.();
+    }
+}
+//# sourceMappingURL=XCUITreeReader.js.map

package/dist/XCUITreeReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"XCUITreeReader.js","sourceRoot":"","sources":["../src/XCUITreeReader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAqB,MAAM,eAAe,CAAA;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,MAAM,CAAA;AAChC,OAAO,EAAE,WAAW,EAAE,MAAM,IAAI,CAAA;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAE3B,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAE7C,MAAM,MAAM,GAAG,YAAY,CAAC,qBAAqB,CAAC,CAAA;AAClD,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAA;AAEzC,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,eAAe,CAAC,CAAA;AACnE,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE,6BAA6B,CAAC,CAAA;AAC/D,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,CAAA;AAC3C,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,UAAU,CAAC,CAAA;AACzD,MAAM,MAAM,GAAG,YAAY,CAAA;AAC3B,gFAAgF;AAChF,gFAAgF;AAChF,sDAAsD;AACtD,MAAM,kBAAkB,GAAG,6BAA6B,CAAA;AACxD,8EAA8E;AAC9E,gFAAgF;AAChF,gFAAgF;AAChF,MAAM,IAAI,GAAG,KAAK,CAAA;AAiBlB,MAAM,aAAa,GAAiB;IAClC,cAAc;QACZ,8EAA8E;QAC9E,IAAI,CAAC;YACH,OAAO,WAAW,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAA;QACxE,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC;IACD,KAAK,CAAC,KAAK,CAAC,WAAW;QACrB,MAAM,aAAa,CACjB,YAAY,EACZ,CAAC,mBAAmB,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,kBAAkB,EAAE,SAAS,EAAE,QAAQ,CAAC,EACnI,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,EAAE,CAClD,CAAA;IACH,CAAC;IACD,KAAK,CAAC,WAAW,EAAE,IAAI;QACrB,OAAO,KAAK,CACV,YAAY,EACZ,CAAC,uBAAuB,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,kBAAkB,EAAE,SAAS,EAAE,QAAQ,CAAC,EACvI,EAAE,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAC9F,CAAA;IACH,CAAC;IACD,aAAa,CAAC,IAAI;QAChB,QAAQ,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,kBAAkB,CAAC,EAAE,GAAG,EAAE,GAAqB,CAAC,CAAC,CAAA;IACnG,CAAC;CACF,CAAA;AAED,iFAAiF;AACjF,gFAAgF;AAChF,8EAA8E;AAC9E,MAAM,OAAO,cAAc;IAKI;IAJrB,MAAM,CAAe;IACrB,QAAQ,CAAgB;IACxB,QAAQ,CAAwB;IAExC,YAA6B,SAAuB,aAAa;QAApC,WAAM,GAAN,MAAM,CAA8B;IAAG,CAAC;IAE7D,WAAW,CAAC,IAAY;QAC9B,8EAA8E;QAC9E,OAAO,6BAA6B,IAAI,EAAE,CAAA;IAC5C,CAAC;IAEO,KAAK,CAAC,WAAW,CAAC,IAAY;QACpC,IAAI,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE;YAAE,OAAM;QACxC,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC,QAAQ,CAAA;QACvC,IAAI,CAAC,QAAQ,GAAG,CAAC,KAAK,IAAI,EAAE;YAC1B,MAAM,CAAC,IAAI,CAAC,yDAAyD,CAAC,CAAA;YACtE,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAA;YAC/C,MAAM,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAA;QAClC,CAAC,CAAC,EAAE,CAAA;QACJ,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,QAAQ,CAAA;QACrB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,aAAa,CACrB,mHAAoH,CAAW,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CACxJ,CAAA;QACH,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAA;QAC3B,CAAC;IACH,CAAC;IAEO,WAAW,CAAC,CAA2B;QAC7C,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAA;IAC1D,CAAC;IAEO,KAAK,CAAC,YAAY,CAAC,IAAY;QACrC,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC,MAAM,CAAA;QAClF,wEAAwE;QACxE,+EAA+E;QAC/E,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;YACpD,IAAI,CAAC,IAAI,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI;gBAAE,OAAO,CAAC,CAAA;QAC3D,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAA;QACvC,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,QAAQ,CAAA;QAC5B,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAA;QAC3B,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,YAAY,CAAC,IAAY;QACrC,IAAI,CAAC,IAAI,EAAE,CAAA,CAAC,8CAA8C;QAC1D,MAAM,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAA;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAA;QAC5D,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,4BAA4B,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAA;QAC9E,MAAM,MAAM,GAAiB,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;QACvD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;QACpB,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAA;QAC5B,OAAO,MAAM,CAAA;IACf,CAAC;IAEO,KAAK,CAAC,SAAS,CAAC,MAAoB;QAC1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5B,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC9B,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM;oBAAE,IAAI,CAAC,MAAM,GAAG,SAAS,CAAA;gBACnD,MAAM,IAAI,aAAa,CAAC,wEAAwE,CAAC,CAAA;YACnG,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,CAAC,GAAG,MAAM,KAAK,CAAC,oBAAoB,MAAM,CAAC,IAAI,SAAS,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;gBACtG,IAAI,CAAC,CAAC,EAAE;oBAAE,OAAM;YAClB,CAAC;YAAC,MAAM,CAAC;gBACP,uBAAuB;YACzB,CAAC;YACD,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAA;QAC/C,CAAC;QACD,IAAI,CAAC,IAAI,EAAE,CAAA;QACX,MAAM,IAAI,aAAa,CAAC,0CAA0C,CAAC,CAAA;IACrE,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAY,EAAE,QAAgB;QACvC,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,aAAa,CAAC,4DAA4D,CAAC,CAAA;QACpG,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAA;QAC9C,IAAI,IAAY,CAAA;QAChB,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,MAAM,KAAK,CAAC,oBAAoB,IAAI,kBAAkB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;YACxI,IAAI,CAAC,CAAC,CAAC,EAAE;gBAAE,MAAM,IAAI,aAAa,CAAC,6BAA6B,CAAC,CAAC,MAAM,QAAQ,QAAQ,EAAE,CAAC,CAAA;YAC3F,IAAI,GAAG,MAAM,CAAC,CAAC,IAAI,EAAE,CAAA;QACvB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,YAAY,aAAa;gBAAE,MAAM,CAAC,CAAA;YACvC,MAAM,IAAI,aAAa,CAAC,yBAA0B,CAAW,CAAC,OAAO,EAAE,CAAC,CAAA;QAC1E,CAAC;QACD,6EAA6E;QAC7E,8EAA8E;QAC9E,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;YACzE,MAAM,IAAI,aAAa,CAAC,mDAAmD,QAAQ,0CAA0C,CAAC,CAAA;QAChI,CAAC;QACD,OAAO,aAAa,CAAC,IAAI,CAAC,CAAA;IAC5B,CAAC;IAED,iEAAiE;IACjE,IAAI;QACF,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAA;QAC1B,IAAI,CAAC,MAAM;YAAE,OAAM;QACnB,IAAI,CAAC,MAAM,GAAG,SAAS,CAAA;QACvB,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAA;IACzB,CAAC;IAED,8EAA8E;IAC9E,uDAAuD;IACvD,YAAY,CAAC,IAAY;QACvB,IAAI,IAAI,CAAC,MAAM,EAAE,IAAI,KAAK,IAAI;YAAE,IAAI,CAAC,IAAI,EAAE,CAAA;IAC7C,CAAC;IAEO,UAAU,CAAC,MAAoB;QACrC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,MAAM,CAAA;QAC7B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAA;QACpB,wEAAwE;QACxE,IAAI,CAAC;YACH,IAAI,GAAG;gBAAE,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;;gBACjC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,kBAAkB;QACpB,CAAC;QACD,6EAA6E;QAC7E,yCAAyC;QACzC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAAA;QAC/B,4CAA4C;QAC5C,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,IAAI,CAAC;gBACH,IAAI,GAAG;oBAAE,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;YACxC,CAAC;YAAC,MAAM,CAAC;gBACP,UAAU;YACZ,CAAC;QACH,CAAC,EAAE,IAAI,CAAC,CAAA;QACR,KAAK,CAAC,KAAK,EAAE,EAAE,CAAA;IACjB,CAAC;CACF"}

package/dist/xcuiTree.d.ts

@@ -0,0 +1,3 @@
+import type { UIElement } from '@tapflowio/agent-core';
+export declare function parseTreeText(text: string): UIElement[];
+//# sourceMappingURL=xcuiTree.d.ts.map

package/dist/xcuiTree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xcuiTree.d.ts","sourceRoot":"","sources":["../src/xcuiTree.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAiB,MAAM,uBAAuB,CAAA;AAuFrE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,CAgDvD"}

package/dist/xcuiTree.js

@@ -0,0 +1,129 @@
+// Parses the text emitted by XCUIApplication.debugDescription (served by the
+// resident xctest-runner) into the unified UIElement schema. Kept as a pure
+// function so it stays unit-testable against a fixed fixture (Open Q9: a format
+// change in a future Xcode is caught by the snapshot regression test).
+//
+// A debugDescription element line looks like:
+//   NavigationBar, 0x105808b10, {{0.0, 47.4}, {402.0, 47.4}}, identifier: 'The App'
+//   Other, 0x105810800, {{0.0, 131.3}, {402.0, 66.4}}, identifier: 'Echo Box', label: 'Echo Box'
+//   Other, 0x105811820, {{366.6, 94.7}, {32.2, 779.3}}, label: 'Vertical scroll bar', value: 0%
+// Fields after the address appear in order: [pid], [frame], [identifier], [label], [value].
+// XCUITest element type → unified vocabulary. XCUITest labels many custom/composed
+// views as "Other" (they still carry identifier/label), so role is best-effort and
+// identifier/label carry the selector weight.
+function toRole(type) {
+    switch (type) {
+        case 'Button':
+        case 'Key':
+            return 'button';
+        case 'TextField':
+        case 'SecureTextField':
+        case 'SearchField':
+        case 'TextView':
+            return 'input';
+        case 'StaticText':
+            return 'text';
+        case 'Image':
+        case 'Icon':
+            return 'image';
+        case 'Switch':
+        case 'Toggle':
+            return 'switch';
+        case 'CheckBox':
+            return 'checkbox';
+        case 'Slider':
+            return 'slider';
+        case 'Table':
+        case 'CollectionView':
+        case 'ScrollView':
+            return 'list';
+        case 'Cell':
+            return 'cell';
+        case 'TabBar':
+        case 'TabGroup':
+            return 'tab';
+        default:
+            return 'other';
+    }
+}
+const ACTIONABLE = new Set(['button', 'input', 'checkbox', 'switch', 'slider', 'tab', 'cell']);
+const round4 = (n) => Math.round(n * 10000) / 10000;
+const FRAME_RE = /\{\{(-?[\d.]+), (-?[\d.]+)\}, \{(-?[\d.]+), (-?[\d.]+)\}\}/;
+// Terminate quoted fields on the next field boundary, so a quote inside the
+// value (e.g. label: 'Don't') does not truncate the match. The `, value: `
+// lookahead stays even though value isn't captured — a trailing value field is
+// still a valid label boundary.
+const IDENTIFIER_RE = /, identifier: '(.*?)'(?=, label: |, value: |$)/;
+const LABEL_RE = /, label: '(.*?)'(?=, value: |$)/;
+function parseLine(line) {
+    // Strip indentation + the root arrow, then take the type up to ", 0x<addr>".
+    const m = /^\s*→?\s*(.+?), 0x[0-9a-fA-F]+/.exec(line);
+    if (!m)
+        return null;
+    const node = { type: m[1] };
+    const fm = FRAME_RE.exec(line);
+    if (fm) {
+        node.frame = { x: parseFloat(fm[1]), y: parseFloat(fm[2]), width: parseFloat(fm[3]), height: parseFloat(fm[4]) };
+    }
+    const im = IDENTIFIER_RE.exec(line);
+    if (im)
+        node.identifier = im[1];
+    const lm = LABEL_RE.exec(line);
+    if (lm)
+        node.label = lm[1];
+    return node;
+}
+export function parseTreeText(text) {
+    const lines = text.split('\n');
+    const startIdx = lines.findIndex((l) => l.trim() === 'Element subtree:');
+    const bodyLines = startIdx >= 0 ? lines.slice(startIdx + 1) : lines;
+    const raw = [];
+    for (const line of bodyLines) {
+        if (!line.trim())
+            continue;
+        // debugDescription ends with sections like "Path to element:" / "Query chain:".
+        if (!/, 0x[0-9a-fA-F]+/.test(line))
+            break;
+        const node = parseLine(line);
+        if (node)
+            raw.push(node);
+    }
+    // Screen size = the first Window frame (normalization basis, same coordinate
+    // space as the tap path). Fall back to the largest frame if no Window is found.
+    const windowFrame = raw.find((n) => n.type.startsWith('Window') && n.frame)?.frame;
+    const basis = windowFrame ?? raw.reduce((max, n) => {
+        if (!n.frame)
+            return max;
+        const area = n.frame.width * n.frame.height;
+        return !max || area > max.width * max.height ? n.frame : max;
+    }, undefined);
+    if (!basis || basis.width <= 0 || basis.height <= 0)
+        return [];
+    const elements = [];
+    for (const node of raw) {
+        if (!node.frame || node.frame.width <= 0 || node.frame.height <= 0)
+            continue;
+        const role = toRole(node.type);
+        const label = node.label ?? '';
+        // Skip pure structural containers with no label and no actionable role.
+        if (!ACTIONABLE.has(role) && label === '' && !node.identifier)
+            continue;
+        const element = {
+            role,
+            label,
+            frame: {
+                x: round4((node.frame.x - basis.x) / basis.width),
+                y: round4((node.frame.y - basis.y) / basis.height),
+                width: round4(node.frame.width / basis.width),
+                height: round4(node.frame.height / basis.height),
+            },
+            enabled: true, // debugDescription does not expose enabled; default true (Open Q9)
+        };
+        if (node.identifier)
+            element.identifier = node.identifier;
+        element.rawRole = node.type;
+        elements.push(element);
+    }
+    return elements;
+}
+//# sourceMappingURL=xcuiTree.js.map

package/dist/xcuiTree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xcuiTree.js","sourceRoot":"","sources":["../src/xcuiTree.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tapflowio/ios-agent",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "iOS simulator agent for tapflow — xcrun simctl control and screen streaming",
   "keywords": [
     "tapflow",
@@ -38,6 +38,10 @@
   "files": [
     "dist",
     "bin",
+    "xctest-runner/project.yml",
+    "xctest-runner/TreeHost",
+    "xctest-runner/TreeRunner",
+    "xctest-runner/TapflowTreeRunner.xcodeproj",
     "README.md",
     "LICENSE"
   ],
@@ -49,15 +53,15 @@
   },
   "dependencies": {
     "ws": "^8.21.0",
-    "@tapflowio/audiotap-helper": "0.2.3",
-    "@tapflowio/agent-core": "0.13.0"
+    "@tapflowio/agent-core": "0.14.0",
+    "@tapflowio/audiotap-helper": "0.2.4"
   },
   "devDependencies": {
     "@types/node": "^20.19.43",
     "@types/ws": "^8.0.0",
     "typescript": "^5.0.0",
     "vitest": "^4.1.9",
-    "@tapflowio/relay": "0.13.0"
+    "@tapflowio/relay": "0.14.0"
   },
   "scripts": {
     "postinstall": "node -e \"if (process.platform === 'darwin') { require('fs').readdirSync('bin').forEach(f => require('fs').chmodSync('bin/' + f, 0o755)) }\"",