@ishlabs/cli 0.25.0 → 0.26.1

package/dist/lib/local-sim/native-a11y.js

@@ -12,7 +12,7 @@
  *
  * COORDINATE SPACE — carried, not converted, by this module:
  *   - Android `uiautomator dump` bounds are screencap PIXELS (`space: "px"`).
- *   - iOS `idb ui describe-all` frames are POINTS (`space: "points"`).
+ *   - iOS WebDriverAgent /source frames are POINTS (`space: "points"`).
  * The device de-normalizes/taps in its own space (AndroidDevice taps pixels;
  * IOSDevice taps points), so the `space` tag tells the caller which dimension a
  * node's bounds-center belongs to. This module never mixes the two.
@@ -50,7 +50,7 @@ const ROLE_NORMALIZATION = {
     ScrollView: "generic",
     RecyclerView: "list",
     ListView: "list",
-    // iOS (idb `type`, AX-prefixed `role` handled by stripAxPrefix below).
+    // iOS (WDA / XCUITest `type`, AX-prefixed `role` handled by stripAxPrefix below).
     StaticText: "text",
     TextField: "textbox",
     SecureTextField: "textbox",
@@ -181,6 +181,9 @@ function buildAndroidTree(xml) {
 function makeRawAndroidNode(role, text, contentDesc, resourceId, clickable, bounds) {
     return { role, text, contentDesc, resourceId, clickable, bounds, children: [] };
 }
+// ---------------------------------------------------------------------------
+// iOS — shared helpers for the WebDriverAgent (XCUITest) /source parser below
+// ---------------------------------------------------------------------------
 /** iOS roles/types that are directly actionable (the device taps their center). */
 const IOS_ACTIONABLE_TYPES = new Set([
     "Button",
@@ -195,50 +198,7 @@ const IOS_ACTIONABLE_TYPES = new Set([
     "MenuItem",
     "Tab",
 ]);
-/**
- * Parse `idb ui describe-all` JSON (a FLAT array of elements, each with a `frame`
- * in POINTS) into NativeNodes in array order. iOS is already a flat,
- * properly-labeled list — no ancestor walk needed — so `clickable` is derived
- * from the element's role/type and whether it carries a usable label.
- */
-export function parseIdbDescribeAll(json) {
-    let parsed;
-    try {
-        parsed = JSON.parse(json);
-    }
-    catch {
-        return [];
-    }
-    if (!Array.isArray(parsed))
-        return [];
-    const out = [];
-    for (const raw of parsed) {
-        const bounds = idbFrameToBounds(raw.frame);
-        if (!bounds)
-            continue; // malformed / zero-area frame → no tappable center
-        // Label: prefer the spoken AXLabel; fall back to AXValue (search fields
-        // expose their placeholder as AXValue, e.g. "Search"). AXValue is only a
-        // STRING fallback — switches/sliders/steppers report it as a number/boolean
-        // (a Switch is 1/0), and `.trim()` on those would throw and lose the whole
-        // tree to a silent vision fallback. An unlabeled toggle then emits as a bare
-        // `[id] switch` (still tappable via its frame center).
-        const label = (raw.AXLabel ?? (typeof raw.AXValue === "string" ? raw.AXValue : "")).trim();
-        const rawType = raw.type ?? (raw.role ? stripAxPrefix(raw.role) : "");
-        const typeKey = stripAxPrefix(rawType);
-        const actionable = IOS_ACTIONABLE_TYPES.has(typeKey) && raw.enabled !== false;
-        out.push({
-            role: normalizeRole(rawType),
-            label,
-            bounds,
-            clickable: actionable,
-            hasOwnLabel: label.length > 0,
-            resourceId: raw.AXUniqueId ?? undefined,
-            space: "points",
-        });
-    }
-    return out;
-}
-function idbFrameToBounds(frame) {
+function frameToBounds(frame) {
     if (!frame)
         return null;
     const { x, y, width, height } = frame;
@@ -254,6 +214,81 @@ function idbFrameToBounds(frame) {
     }
     return { x, y, width, height };
 }
+/** WDA's "1"/"0" (or real boolean) → boolean. */
+function wdaTruthy(v) {
+    return v === true || v === "1";
+}
+/**
+ * Parse WDA's `GET /source?format=json` — a NESTED accessibility tree — into the
+ * FLAT, depth-first `NativeNode[]` (POINTS) that `parseXcuiHierarchy` produces,
+ * so `serializeNativeTree` consumes it unchanged. WDA's `type` matches idb's iOS
+ * types (Button/StaticText/SearchField/Cell/Image/Application…), so
+ * `normalizeRole`/`IOS_ACTIONABLE_TYPES`/`frameToBounds` all apply as-is.
+ *
+ * KEY: WDA's `/source` is the FULL XCUIElement tree — every container and leaf —
+ * NOT idb's clean accessibility-elements list. iOS settings rows surface as an
+ * accessible `Button` ("General", isAccessible=1) that ALSO contains a duplicate
+ * inner `StaticText` ("General", isAccessible=0) and is wrapped in a `Cell`
+ * (isAccessible=0). Emitting all three yields "General General" + empty
+ * listitems. So we emit ONLY `isAccessible && isVisible` nodes — exactly the
+ * VoiceOver-exposed set idb returned: the labeled Button is both the label and
+ * the tap target; the duplicate StaticText and the wrapping Cell are pruned. A
+ * sparse a11y tree degrades to the loop's vision fallback, so strict filtering
+ * never strands the run.
+ *
+ * Accepts either the raw tree or the W3C `{ value: <tree> }` envelope WDA returns.
+ */
+export function parseXcuiHierarchy(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return [];
+    }
+    // WDA returns the tree under a W3C `{ value: <tree>, sessionId }` envelope, but
+    // a raw tree NODE also has its own `value` field (the element's value) — so we
+    // can't unwrap on `"value" in parsed` alone. The actual tree root is the one
+    // carrying a node-shaped `type`; only unwrap `value` when the top level is NOT
+    // itself a node.
+    const obj = parsed;
+    const root = obj && typeof obj === "object" && !("type" in obj) && "value" in obj
+        ? obj.value
+        : obj;
+    if (!root || typeof root !== "object")
+        return [];
+    const out = [];
+    const visit = (n) => {
+        const bounds = frameToBounds(n.rect ?? undefined);
+        if (bounds && wdaTruthy(n.isAccessible) && wdaTruthy(n.isVisible)) {
+            // Prefer the spoken label; fall back to a STRING value (search fields
+            // expose their placeholder as `value`). Non-string values (a Switch's 1/0)
+            // are ignored for the label, exactly like the idb path.
+            const label = (n.label ?? (typeof n.value === "string" ? n.value : "")).trim();
+            const rawType = n.type ?? "";
+            const typeKey = stripAxPrefix(rawType);
+            // `isEnabled` absent ⇒ assume enabled (WDA omits it on always-enabled types).
+            const enabled = n.isEnabled == null ? true : wdaTruthy(n.isEnabled);
+            const actionable = IOS_ACTIONABLE_TYPES.has(typeKey) && enabled;
+            out.push({
+                role: normalizeRole(rawType),
+                label,
+                bounds,
+                clickable: actionable,
+                hasOwnLabel: label.length > 0,
+                resourceId: (n.name || n.rawIdentifier) ?? undefined,
+                space: "points",
+            });
+        }
+        // Recurse into ALL children — an accessible element can nest inside a
+        // non-accessible container (the Cell wrapping the Button), so we must not
+        // prune the walk by accessibility, only the emission.
+        for (const c of n.children ?? [])
+            visit(c);
+    };
+    visit(root);
+    return out;
+}
 // ---------------------------------------------------------------------------
 // Serialization — flat NativeNode list → `[id] role "label"` + nodeMap
 // ---------------------------------------------------------------------------
@@ -271,7 +306,7 @@ function normalizeLabel(label) {
 }
 /**
  * Serialize a flat NativeNode list (from `parseUiautomatorXml` /
- * `parseIdbDescribeAll`) into the `[id] role "label"` string the DOMLocator
+ * `parseXcuiHierarchy`) into the `[id] role "label"` string the DOMLocator
  * reasons over, plus a `shortId → bounds` map for local tap resolution.
  *
  * Emission rules (kept tight, like the DOM serializer):

package/dist/lib/local-sim/simctl.d.ts

@@ -1,38 +1,34 @@
 /**
- * Thin async wrappers over `xcrun simctl` + `idb` for the native-iOS sim path.
+ * Thin async wrappers over `xcrun simctl` for the native-iOS sim path: simulator
+ * LIFECYCLE (boot detection, install, terminate, launch) and the SCREENSHOT.
  *
- * Two tools, two jobs:
- *  - `xcrun simctl` drives the simulator LIFECYCLE (boot detection, install,
- *    terminate, launch) and the SCREENSHOT.
- *  - `idb` drives UI INPUT (tap/swipe/text/key) and reports the screen
- *    geometry (pixels, points, and the scale between them).
+ * UI interaction + the accessibility tree live in `xcuitest.ts` (WebDriverAgent),
+ * NOT here — iOS no longer depends on idb.
  *
  * COORDINATE SPACES (the key difference from Android, where screencap and tap
  * share one pixel space):
  *  - `simctl io booted screenshot` writes a PNG in PIXELS (e.g. 1179x2556 @3x).
- *  - `idb ui tap/swipe` take POINTS (e.g. 393x852) — pixels / scale.
- * The native sim TAPS in points (de-normalize 0-1000 against the POINT size)
- * but RECORDS in PIXELS: dimensions() returns the pixel size so the loop's
- * round-trip is exact. Recording in points would drift — the point grid (393)
- * is coarser than the 0-1000 normalized grid, so it double-rounds. See
- * IOSDevice for the full derivation.
+ *  - WebDriverAgent's taps/swipes + a11y frames are POINTS (e.g. 393x852).
+ * The native sim TAPS in points (de-normalize 0-1000 against the POINT size) but
+ * RECORDS in PIXELS: dimensions() returns the pixel size so the loop's round-trip
+ * is exact. Recording in points would drift — the point grid (393) is coarser
+ * than the 0-1000 normalized grid, so it double-rounds. See IOSDevice.
  */
 export declare class IosError extends Error {
     constructor(message: string);
 }
 /** Run `xcrun simctl <args>` and return trimmed stdout. */
 export declare function simctl(args: string[], timeoutMs?: number): Promise<string>;
-/** Run `idb <args>` and return trimmed stdout. */
-export declare function idb(args: string[], timeoutMs?: number): Promise<string>;
 /**
  * Assert exactly one simulator is Booted and return its udid. We pin every
- * subsequent idb/simctl call (and the screenshot) to "booted", so multiple
+ * subsequent simctl/WDA call (and the screenshot) to "booted", so multiple
  * booted simulators are ambiguous and rejected.
  */
 export declare function requireOneBootedSimulator(): Promise<string>;
 /**
- * Screen geometry from `idb describe --json`: PIXEL size, POINT size, and the
- * scale (`density`) between them. Points drive idb ui tap/swipe; pixels are the
+ * Screen geometry: PIXEL size, POINT size, and the scale (`density`) between
+ * them. Produced by the XCUITest driver's `describeScreen` (xcuitest.ts) and
+ * consumed by IOSDevice — points drive WDA taps/swipes; pixels are the
  * screenshot's resolution.
  */
 export interface IosScreen {
@@ -42,38 +38,12 @@ export interface IosScreen {
     pointHeight: number;
     density: number;
 }
-export declare function describeScreen(udid: string): Promise<IosScreen>;
 /**
  * Capture the booted simulator's screen as PNG bytes via
  * `simctl io booted screenshot`. simctl writes to a file path (no reliable
  * stdout in current Xcode), so we round-trip through a temp file.
  */
 export declare function screenshotPng(): Promise<Buffer>;
-export declare function uiTap(udid: string, x: number, y: number): Promise<void>;
-export declare function uiLongPress(udid: string, x: number, y: number, durationMs?: number): Promise<void>;
-export declare function uiSwipe(udid: string, x1: number, y1: number, x2: number, y2: number, durationMs?: number): Promise<void>;
-/**
- * Type text into the focused field. Unlike Android's `adb shell input text`,
- * `idb ui text` handles spaces/unicode/quotes correctly, so no helper IME is
- * needed.
- */
-export declare function uiText(udid: string, text: string): Promise<void>;
-/**
- * Press a hardware key by HID usage code. `idb ui key 40` is Return/Enter
- * (used to submit a text field).
- */
-export declare function uiKey(udid: string, keycode: number): Promise<void>;
-/** HID usage code for Return/Enter. */
-export declare const HID_KEY_RETURN = 40;
-/**
- * Capture the current accessibility tree as `idb ui describe-all` JSON (a flat
- * array of elements, each with a POINT frame) and return it. Mirrors the
- * oracle's `ios_describe`: right after a tap the tree can be mid-transition and
- * come back empty/partial, so we retry until we get an array with more than just
- * the root application node. Throws IosError if every attempt yields a trivial
- * tree so the caller can degrade to the vision path.
- */
-export declare function describeAll(udid: string): Promise<string>;
 export declare function terminateApp(udid: string, bundleId: string): Promise<void>;
 export declare function launchApp(udid: string, bundleId: string): Promise<void>;
 export declare function installApp(udid: string, appPath: string): Promise<void>;
@@ -83,3 +53,18 @@ export declare function isAppInstalled(udid: string, bundleId: string): Promise<
  * terminate+launch a just-installed app without diffing the app list.
  */
 export declare function bundleIdFromApp(appPath: string): Promise<string | null>;
+/**
+ * Read the installed app's marketing version + build number from the booted
+ * simulator. `simctl listapps` emits a (NeXTSTEP) plist of every installed
+ * bundle; we round-trip it through `plutil -convert json` and index by bundle
+ * id. JSON-not-keypath because a bundle id's dots (`com.apple.Preferences`)
+ * collide with plutil's `-extract` keypath separator.
+ *
+ * Best-effort: returns null on any failure (the run never depends on it). Works
+ * for both CLI-installed `.app`s and pre-installed system/app-store bundles —
+ * by call time the bundle id is already resolved.
+ */
+export declare function appBuildFromSimulator(udid: string, bundleId: string): Promise<{
+    version: string | null;
+    build: string | null;
+} | null>;

package/dist/lib/local-sim/simctl.js

@@ -1,45 +1,27 @@
 /**
- * Thin async wrappers over `xcrun simctl` + `idb` for the native-iOS sim path.
+ * Thin async wrappers over `xcrun simctl` for the native-iOS sim path: simulator
+ * LIFECYCLE (boot detection, install, terminate, launch) and the SCREENSHOT.
  *
- * Two tools, two jobs:
- *  - `xcrun simctl` drives the simulator LIFECYCLE (boot detection, install,
- *    terminate, launch) and the SCREENSHOT.
- *  - `idb` drives UI INPUT (tap/swipe/text/key) and reports the screen
- *    geometry (pixels, points, and the scale between them).
+ * UI interaction + the accessibility tree live in `xcuitest.ts` (WebDriverAgent),
+ * NOT here — iOS no longer depends on idb.
  *
  * COORDINATE SPACES (the key difference from Android, where screencap and tap
  * share one pixel space):
  *  - `simctl io booted screenshot` writes a PNG in PIXELS (e.g. 1179x2556 @3x).
- *  - `idb ui tap/swipe` take POINTS (e.g. 393x852) — pixels / scale.
- * The native sim TAPS in points (de-normalize 0-1000 against the POINT size)
- * but RECORDS in PIXELS: dimensions() returns the pixel size so the loop's
- * round-trip is exact. Recording in points would drift — the point grid (393)
- * is coarser than the 0-1000 normalized grid, so it double-rounds. See
- * IOSDevice for the full derivation.
+ *  - WebDriverAgent's taps/swipes + a11y frames are POINTS (e.g. 393x852).
+ * The native sim TAPS in points (de-normalize 0-1000 against the POINT size) but
+ * RECORDS in PIXELS: dimensions() returns the pixel size so the loop's round-trip
+ * is exact. Recording in points would drift — the point grid (393) is coarser
+ * than the 0-1000 normalized grid, so it double-rounds. See IOSDevice.
  */
 import { execFile } from "node:child_process";
 import { existsSync } from "node:fs";
-import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
-// idb installs to ~/.local/bin via pip; resolve an explicit path so we don't
-// depend on the caller's PATH. Override with ISH_IDB.
-function resolveIdb() {
-    const fromEnv = process.env.ISH_IDB;
-    if (fromEnv && existsSync(fromEnv))
-        return fromEnv;
-    const local = `${process.env.HOME ?? ""}/.local/bin/idb`;
-    if (existsSync(local))
-        return local;
-    const homebrew = "/opt/homebrew/bin/idb";
-    if (existsSync(homebrew))
-        return homebrew;
-    return "idb";
-}
 const XCRUN = "/usr/bin/xcrun";
-const IDB = resolveIdb();
 const PLUTIL = "/usr/bin/plutil";
 const DEFAULT_TIMEOUT_MS = 30_000;
 const SCREENSHOT_TIMEOUT_MS = 30_000;
@@ -63,24 +45,10 @@ export async function simctl(args, timeoutMs = DEFAULT_TIMEOUT_MS) {
         throw new IosError(`xcrun simctl ${args.join(" ")} failed: ${msg}`);
     }
 }
-/** Run `idb <args>` and return trimmed stdout. */
-export async function idb(args, timeoutMs = DEFAULT_TIMEOUT_MS) {
-    try {
-        const { stdout } = await execFileAsync(IDB, args, {
-            timeout: timeoutMs,
-            maxBuffer: 8 * 1024 * 1024,
-        });
-        return stdout.trim();
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        throw new IosError(`idb ${args.join(" ")} failed: ${msg}`);
-    }
-}
 // --- Device state ---
 /**
  * Assert exactly one simulator is Booted and return its udid. We pin every
- * subsequent idb/simctl call (and the screenshot) to "booted", so multiple
+ * subsequent simctl/WDA call (and the screenshot) to "booted", so multiple
  * booted simulators are ambiguous and rejected.
  */
 export async function requireOneBootedSimulator() {
@@ -90,7 +58,7 @@ export async function requireOneBootedSimulator() {
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        throw new IosError(`Could not run xcrun simctl. Is Xcode installed and a simulator booted? ${msg}`);
+        throw new IosError(`Could not run xcrun simctl. Run \`ish check ios\` to check your setup. ${msg}`);
     }
     let booted = [];
     try {
@@ -104,7 +72,7 @@ export async function requireOneBootedSimulator() {
         throw new IosError("Could not parse `simctl list devices booted -j` output.");
     }
     if (booted.length === 0) {
-        throw new IosError("No iOS simulator booted. Boot one first (e.g. `xcrun simctl boot <udid>` or open Simulator.app).");
+        throw new IosError("No iOS simulator booted. Open Simulator.app, or run `ish check ios` to check your setup.");
     }
     if (booted.length > 1) {
         throw new IosError(`Expected exactly one booted simulator, found ${booted.length} (${booted.map((d) => d.name).join(", ")}). ` +
@@ -112,27 +80,6 @@ export async function requireOneBootedSimulator() {
     }
     return booted[0].udid;
 }
-export async function describeScreen(udid) {
-    const out = await idb(["describe", "--json", "--udid", udid]);
-    let dims;
-    try {
-        const parsed = JSON.parse(out);
-        dims = parsed.screen_dimensions;
-    }
-    catch {
-        throw new IosError("Could not parse `idb describe --json` output.");
-    }
-    if (!dims || !dims.width_points || !dims.height_points || !dims.width || !dims.height) {
-        throw new IosError(`idb describe returned no usable screen_dimensions: ${out.slice(0, 200)}`);
-    }
-    return {
-        pixelWidth: dims.width,
-        pixelHeight: dims.height,
-        pointWidth: dims.width_points,
-        pointHeight: dims.height_points,
-        density: dims.density ?? dims.width / dims.width_points,
-    };
-}
 // --- Screenshot (PIXELS) ---
 /**
  * Capture the booted simulator's screen as PNG bytes via
@@ -150,82 +97,6 @@ export async function screenshotPng() {
         await rm(dir, { recursive: true, force: true }).catch(() => { });
     }
 }
-// --- UI input via idb (POINTS) ---
-export async function uiTap(udid, x, y) {
-    await idb(["ui", "tap", "--udid", udid, String(Math.round(x)), String(Math.round(y))]);
-}
-export async function uiLongPress(udid, x, y, durationMs = 600) {
-    // idb takes the press duration in SECONDS.
-    await idb([
-        "ui", "tap", "--udid", udid,
-        "--duration", (durationMs / 1000).toFixed(2),
-        String(Math.round(x)), String(Math.round(y)),
-    ]);
-}
-export async function uiSwipe(udid, x1, y1, x2, y2, durationMs = 300) {
-    await idb([
-        "ui", "swipe", "--udid", udid,
-        "--duration", (durationMs / 1000).toFixed(2),
-        String(Math.round(x1)), String(Math.round(y1)),
-        String(Math.round(x2)), String(Math.round(y2)),
-    ]);
-}
-/**
- * Type text into the focused field. Unlike Android's `adb shell input text`,
- * `idb ui text` handles spaces/unicode/quotes correctly, so no helper IME is
- * needed.
- */
-export async function uiText(udid, text) {
-    await idb(["ui", "text", "--udid", udid, text]);
-}
-/**
- * Press a hardware key by HID usage code. `idb ui key 40` is Return/Enter
- * (used to submit a text field).
- */
-export async function uiKey(udid, keycode) {
-    await idb(["ui", "key", "--udid", udid, String(keycode)]);
-}
-/** HID usage code for Return/Enter. */
-export const HID_KEY_RETURN = 40;
-// --- Accessibility tree (idb describe-all) ---
-/**
- * Capture the current accessibility tree as `idb ui describe-all` JSON (a flat
- * array of elements, each with a POINT frame) and return it. Mirrors the
- * oracle's `ios_describe`: right after a tap the tree can be mid-transition and
- * come back empty/partial, so we retry until we get an array with more than just
- * the root application node. Throws IosError if every attempt yields a trivial
- * tree so the caller can degrade to the vision path.
- */
-export async function describeAll(udid) {
-    let lastJson = "";
-    for (let i = 0; i < 5; i++) {
-        try {
-            const json = await idb(["ui", "describe-all", "--udid", udid]);
-            lastJson = json;
-            // A valid non-trivial tree has more than just the root application node.
-            if (countJsonArray(json) >= 2)
-                return json;
-        }
-        catch (err) {
-            lastJson = err instanceof Error ? err.message : String(err);
-        }
-        await delay(800);
-    }
-    throw new IosError(`idb ui describe-all returned a trivial/empty tree after retries (last: ${lastJson.slice(0, 200)})`);
-}
-/** Length of a JSON array string, or 0 if it isn't a parseable array. */
-function countJsonArray(json) {
-    try {
-        const parsed = JSON.parse(json);
-        return Array.isArray(parsed) ? parsed.length : 0;
-    }
-    catch {
-        return 0;
-    }
-}
-function delay(ms) {
-    return new Promise((r) => setTimeout(r, ms));
-}
 // --- App lifecycle (simctl) ---
 export async function terminateApp(udid, bundleId) {
     // Terminating an app that isn't running exits non-zero ("found nothing to
@@ -271,3 +142,43 @@ export async function bundleIdFromApp(appPath) {
         return null;
     }
 }
+/**
+ * Read the installed app's marketing version + build number from the booted
+ * simulator. `simctl listapps` emits a (NeXTSTEP) plist of every installed
+ * bundle; we round-trip it through `plutil -convert json` and index by bundle
+ * id. JSON-not-keypath because a bundle id's dots (`com.apple.Preferences`)
+ * collide with plutil's `-extract` keypath separator.
+ *
+ * Best-effort: returns null on any failure (the run never depends on it). Works
+ * for both CLI-installed `.app`s and pre-installed system/app-store bundles —
+ * by call time the bundle id is already resolved.
+ */
+export async function appBuildFromSimulator(udid, bundleId) {
+    const dir = await mkdtemp(join(tmpdir(), "ish-ios-apps-"));
+    const path = join(dir, "apps.plist");
+    try {
+        const { stdout } = await execFileAsync(XCRUN, ["simctl", "listapps", udid], {
+            timeout: 60_000,
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        await writeFile(path, stdout);
+        const { stdout: json } = await execFileAsync(PLUTIL, ["-convert", "json", "-o", "-", path], {
+            timeout: 10_000,
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        const apps = JSON.parse(json);
+        const app = apps[bundleId];
+        if (!app)
+            return null;
+        return {
+            version: app.CFBundleShortVersionString ?? null,
+            build: app.CFBundleVersion ?? null,
+        };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true }).catch(() => { });
+    }
+}

package/dist/lib/local-sim/types.d.ts

@@ -12,10 +12,12 @@ export interface LocalSimInitRequest {
     iteration_id: string;
 }
 export interface IterationDetails {
-    url: string;
+    url?: string;
     platform: string;
     screen_format: "desktop" | "mobile_portrait";
     locale?: string;
+    /** Native (ios/android): the app target to install/launch (bundle id / package / path). */
+    app_artifact?: string;
 }
 export interface LocalSimInitResponse {
     participant_id: string;
@@ -114,6 +116,7 @@ export interface LocalStepAction {
     key: string | null;
     tab_id: string | null;
     orientation: string | null;
+    panel: "quick_settings" | "notifications" | null;
     scale: number | null;
     coordinates: {
         x: number;
@@ -157,6 +160,7 @@ export interface LocalSimStepResponseRaw {
                 key?: string;
                 tab_id?: string;
                 orientation?: string;
+                panel?: "quick_settings" | "notifications";
                 scale?: number;
                 coordinates?: {
                     x: number;
@@ -219,6 +223,14 @@ export interface RecordInteraction {
     assignment_status: AssignmentStatus;
     tabs?: LocalTabInfo[];
 }
+export interface LocalSimInteractionRequest {
+    participant_id: string;
+    product_id: string;
+    interaction: RecordInteraction;
+}
+export interface LocalSimInteractionResponse {
+    interaction_id: string;
+}
 export interface AssignmentStatusUpdate {
     assignment_id: string;
     status: string;
@@ -227,7 +239,6 @@ export interface AssignmentStatusUpdate {
 export interface LocalSimRecordRequest {
     participant_id: string;
     product_id: string;
-    interactions: RecordInteraction[];
     final_status: string;
     assignment_statuses: AssignmentStatusUpdate[];
 }

package/dist/lib/local-sim/xcuitest.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Host-side WebDriverAgent (XCUITest) client — the iOS UI-interaction + a11y
+ * layer that replaces idb. Device LIFECYCLE (install target app, screenshot,
+ * launch/terminate target) stays on `xcrun simctl` in `simctl.ts`; this module
+ * owns ONLY the WDA surface.
+ *
+ * Mechanism (validated on the simulator, no xcodebuild): a PREBUILT WDA runner
+ * (Appium's `WebDriverAgentRunner-Runner.app`, bundle id
+ * `com.facebook.WebDriverAgentRunner.xctrunner`) is `simctl install`-ed and
+ * `simctl launch`-ed with `SIMCTL_CHILD_USE_PORT`; the xctrunner self-hosts the
+ * XCTest runtime and serves W3C WebDriver on `localhost:<port>`. We then drive
+ * taps/swipes/text via `/session/:id/actions` and read the a11y tree via
+ * `/session/:id/source?format=json` (parsed by `parseXcuiHierarchy`).
+ *
+ * API mirrors the idb functions in `simctl.ts` (udid-keyed, points space) so
+ * `ios.ts` swaps the import with a near-identical call surface. Per-udid session
+ * state (port + WDA sessionId) is held in a module map; `ensureWda` is idempotent
+ * and reuses an already-running runner.
+ */
+import { type IosScreen } from "./simctl.js";
+interface Session {
+    port: number;
+    baseUrl: string;
+    sessionId: string;
+}
+/**
+ * Resolve the prebuilt WDA `.app`, downloading it on first use:
+ * `ISH_WDA_PATH` override → `~/.ish/bin/wda/` cache → fetch Appium's prebuilt
+ * WebDriverAgent-for-simulator from its GitHub release. Mirrors
+ * `connect.ts:resolveCloudflaredBin` (which fetches cloudflared the same way).
+ */
+export declare function resolveWdaBundle(): Promise<string>;
+/**
+ * Ensure a WDA runner is up for `udid` and a session exists, idempotently. If a
+ * runner already answers on the port (a prior `ensureWda`, or an externally
+ * launched one), it is reused — only a fresh session is created. Otherwise the
+ * prebuilt runner is installed and `simctl launch`-ed.
+ */
+export declare function ensureWda(udid: string, opts?: {
+    bundleId?: string;
+}): Promise<Session>;
+/** Tear down the WDA session for `udid` (the runner is left for the next run). */
+export declare function closeWda(udid: string): Promise<void>;
+/** Screen geometry from WDA `/wda/screen` (points + retina scale). */
+export declare function describeScreen(udid: string): Promise<IosScreen>;
+/** Raw WDA `/source?format=json` string — feed to `parseXcuiHierarchy`. */
+export declare function describeAll(udid: string): Promise<string>;
+export declare function uiTap(udid: string, x: number, y: number): Promise<void>;
+export declare function uiLongPress(udid: string, x: number, y: number, durationMs?: number): Promise<void>;
+export declare function uiSwipe(udid: string, x1: number, y1: number, x2: number, y2: number, durationMs?: number): Promise<void>;
+/** Type into the focused element (the caller taps a field first). */
+export declare function uiText(udid: string, text: string): Promise<void>;
+/**
+ * Press a key. Only the idb HID Return keycode (40) is used by ios.ts today;
+ * map it to W3C ENTER. Unknown codes are a no-op-safe error.
+ */
+export declare function uiKey(udid: string, keycode: number): Promise<void>;
+/** Re-export so a future ios.ts can drop the simctl HID constant. */
+export declare const HID_KEY_RETURN = 40;
+export {};