@ishlabs/cli 0.25.0 → 0.26.0

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

@@ -1,21 +1,18 @@
 /**
- * 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";
@@ -24,22 +21,7 @@ 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

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

@@ -114,6 +114,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 +158,7 @@ export interface LocalSimStepResponseRaw {
                 key?: string;
                 tab_id?: string;
                 orientation?: string;
+                panel?: "quick_settings" | "notifications";
                 scale?: number;
                 coordinates?: {
                     x: number;

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 {};

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

@@ -0,0 +1,303 @@
+/**
+ * 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 { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync, readdirSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import * as path from "node:path";
+import { wdaDir, wdaVersionFile } from "../paths.js";
+import { IosError } from "./simctl.js";
+const execFileAsync = promisify(execFile);
+const XCRUN = "/usr/bin/xcrun";
+/** Bundle id of Appium's prebuilt WDA xctrunner (self-hosts the XCTest runtime). */
+const WDA_BUNDLE_ID = "com.facebook.WebDriverAgentRunner.xctrunner";
+/** Default WDA port; override with ISH_WDA_PORT. One device → one runner. */
+const DEFAULT_PORT = Number(process.env.ISH_WDA_PORT) || 8100;
+/** WDA's XCTest runtime cold-starts slowly; poll /status up to this long. */
+const STARTUP_TIMEOUT_MS = 75_000;
+/** W3C ENTER key (maps the idb HID Return keycode 40 used by ios.ts). */
+const W3C_ENTER = "\uE007"; // idb HID Return (40) -> W3C ENTER
+const sessions = new Map();
+// ── WDA bundle resolution (fetch is wired in the distribution phase) ──────────
+/** Appium's prebuilt WebDriverAgent simulator release we fetch + pin. */
+const WDA_PINNED_TAG = "v13.2.0";
+/**
+ * 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 async function resolveWdaBundle() {
+    const override = process.env.ISH_WDA_PATH;
+    if (override) {
+        if (!existsSync(override)) {
+            throw new IosError(`ISH_WDA_PATH does not exist: ${override}`);
+        }
+        return override.endsWith(".app") ? override : findApp(override);
+    }
+    const dir = wdaDir();
+    if (existsSync(dir)) {
+        try {
+            return findApp(dir);
+        }
+        catch {
+            // cache dir exists but holds no .app yet → (re)download
+        }
+    }
+    return downloadWdaBundle();
+}
+/**
+ * Fetch Appium's prebuilt WDA-for-simulator zip (just the xctrunner `.app`,
+ * which self-hosts the XCTest runtime — no xcodebuild) and unpack it into
+ * `~/.ish/bin/wda/`. arch follows the host (arm64 sims on Apple Silicon, x86_64
+ * on Intel). Logs to stderr so a run shows the one-time fetch.
+ */
+async function downloadWdaBundle() {
+    const arch = process.arch === "arm64" ? "arm64" : "x86_64";
+    const asset = `WebDriverAgentRunner-Build-Sim-${arch}.zip`;
+    const url = `https://github.com/appium/WebDriverAgent/releases/download/${WDA_PINNED_TAG}/${asset}`;
+    const dir = wdaDir();
+    console.error(`Fetching the iOS automation runner (WebDriverAgent ${WDA_PINNED_TAG}, ${arch})...`);
+    mkdirSync(dir, { recursive: true });
+    const zipPath = path.join(dir, "wda.zip");
+    let resp;
+    try {
+        resp = await fetch(url, { signal: AbortSignal.timeout(120_000) });
+    }
+    catch (e) {
+        throw new IosError(`failed to download WebDriverAgent from ${url}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!resp.ok) {
+        throw new IosError(`failed to download WebDriverAgent: HTTP ${resp.status} from ${url}`);
+    }
+    writeFileSync(zipPath, Buffer.from(await resp.arrayBuffer()));
+    try {
+        await execFileAsync("/usr/bin/unzip", ["-o", "-q", zipPath, "-d", dir], { timeout: 60_000 });
+    }
+    catch (e) {
+        throw new IosError(`failed to unpack WebDriverAgent: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    rmSync(zipPath, { force: true });
+    writeFileSync(wdaVersionFile(), `${WDA_PINNED_TAG} ${arch}\n`);
+    return findApp(dir);
+}
+/** First `*.app` directly under `dir` (or `dir` itself if it is one). */
+function findApp(dir) {
+    if (dir.endsWith(".app") && existsSync(dir))
+        return dir;
+    try {
+        const hit = readdirSync(dir).find((e) => e.endsWith(".app"));
+        if (hit)
+            return path.join(dir, hit);
+    }
+    catch {
+        /* fallthrough */
+    }
+    throw new IosError(`No WebDriverAgentRunner-Runner.app found under ${dir}`);
+}
+// ── HTTP to the runner ────────────────────────────────────────────────────
+async function wdaCall(port, method, route, body) {
+    const url = `http://localhost:${port}${route}`;
+    let resp;
+    try {
+        resp = await fetch(url, {
+            method,
+            headers: body ? { "Content-Type": "application/json" } : undefined,
+            body: body ? JSON.stringify(body) : undefined,
+            signal: AbortSignal.timeout(30_000),
+        });
+    }
+    catch (e) {
+        throw new IosError(`WDA ${method} ${route} failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const text = await resp.text();
+    let json;
+    try {
+        json = text ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new IosError(`WDA ${method} ${route} returned non-JSON (HTTP ${resp.status})`);
+    }
+    if (!resp.ok) {
+        const detail = json?.value?.message ?? text.slice(0, 200);
+        throw new IosError(`WDA ${method} ${route} -> HTTP ${resp.status}: ${detail}`);
+    }
+    return json;
+}
+function unwrap(json) {
+    return json && typeof json === "object" && "value" in json
+        ? json.value
+        : json;
+}
+// ── Lifecycle ─────────────────────────────────────────────────────────────
+async function simctlRun(args, timeoutMs = 180_000) {
+    try {
+        const { stdout } = await execFileAsync(XCRUN, ["simctl", ...args], {
+            timeout: timeoutMs,
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        return stdout;
+    }
+    catch (e) {
+        throw new IosError(`xcrun simctl ${args[0]} failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function statusOk(port) {
+    try {
+        const resp = await fetch(`http://localhost:${port}/status`, { signal: AbortSignal.timeout(2500) });
+        return resp.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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 async function ensureWda(udid, opts = {}) {
+    const existing = sessions.get(udid);
+    if (existing && (await statusOk(existing.port)))
+        return existing;
+    const port = DEFAULT_PORT;
+    if (!(await statusOk(port))) {
+        const app = await resolveWdaBundle();
+        await simctlRun(["install", udid, app]);
+        // SIMCTL_CHILD_* env passes through to the launched process; USE_PORT tells
+        // WDA which port to bind. --terminate-running-process clears a stale runner.
+        await execFileAsync(XCRUN, ["simctl", "launch", "--terminate-running-process", udid, WDA_BUNDLE_ID], { timeout: 30_000, env: { ...process.env, SIMCTL_CHILD_USE_PORT: String(port) } }).catch((e) => {
+            throw new IosError(`failed to launch WDA runner: ${e instanceof Error ? e.message : String(e)}`);
+        });
+        const deadline = Date.now() + STARTUP_TIMEOUT_MS;
+        while (!(await statusOk(port))) {
+            if (Date.now() > deadline) {
+                throw new IosError(`WDA runner did not start within ${STARTUP_TIMEOUT_MS / 1000}s`);
+            }
+            await sleep(1000);
+        }
+    }
+    const baseUrl = `http://localhost:${port}`;
+    const caps = opts.bundleId
+        ? { capabilities: { alwaysMatch: { bundleId: opts.bundleId } } }
+        : { capabilities: { alwaysMatch: {} } };
+    const resp = (await wdaCall(port, "POST", "/session", caps));
+    const sessionId = resp.sessionId ?? unwrap(resp)?.sessionId;
+    if (!sessionId)
+        throw new IosError("WDA did not return a sessionId");
+    const session = { port, baseUrl, sessionId };
+    sessions.set(udid, session);
+    return session;
+}
+async function getSession(udid) {
+    const s = sessions.get(udid);
+    if (s && (await statusOk(s.port)))
+        return s;
+    return ensureWda(udid);
+}
+/** Tear down the WDA session for `udid` (the runner is left for the next run). */
+export async function closeWda(udid) {
+    const s = sessions.get(udid);
+    sessions.delete(udid);
+    if (!s)
+        return;
+    try {
+        await wdaCall(s.port, "DELETE", `/session/${s.sessionId}`);
+    }
+    catch {
+        /* best-effort teardown */
+    }
+}
+// ── Geometry + a11y ─────────────────────────────────────────────────────────
+/** Screen geometry from WDA `/wda/screen` (points + retina scale). */
+export async function describeScreen(udid) {
+    const s = await getSession(udid);
+    const v = unwrap(await wdaCall(s.port, "GET", "/wda/screen"));
+    const pointWidth = Number(v.screenSize?.width) || 0;
+    const pointHeight = Number(v.screenSize?.height) || 0;
+    const density = Number(v.scale) || 1;
+    if (!pointWidth || !pointHeight)
+        throw new IosError("WDA /wda/screen returned no screen size");
+    return {
+        pointWidth,
+        pointHeight,
+        density,
+        pixelWidth: Math.round(pointWidth * density),
+        pixelHeight: Math.round(pointHeight * density),
+    };
+}
+/** Raw WDA `/source?format=json` string — feed to `parseXcuiHierarchy`. */
+export async function describeAll(udid) {
+    const s = await getSession(udid);
+    const json = await wdaCall(s.port, "GET", `/session/${s.sessionId}/source?format=json`);
+    return JSON.stringify(json);
+}
+// ── Gestures (W3C pointer actions; coordinates in POINTS) ────────────────────
+function pointerAction(steps) {
+    return {
+        actions: [{ type: "pointer", id: "finger1", parameters: { pointerType: "touch" }, actions: steps }],
+    };
+}
+async function performActions(udid, steps) {
+    const s = await getSession(udid);
+    await wdaCall(s.port, "POST", `/session/${s.sessionId}/actions`, pointerAction(steps));
+}
+export async function uiTap(udid, x, y) {
+    await performActions(udid, [
+        { type: "pointerMove", duration: 0, x, y },
+        { type: "pointerDown", button: 0 },
+        { type: "pause", duration: 60 },
+        { type: "pointerUp", button: 0 },
+    ]);
+}
+export async function uiLongPress(udid, x, y, durationMs = 600) {
+    await performActions(udid, [
+        { type: "pointerMove", duration: 0, x, y },
+        { type: "pointerDown", button: 0 },
+        { type: "pause", duration: durationMs },
+        { type: "pointerUp", button: 0 },
+    ]);
+}
+export async function uiSwipe(udid, x1, y1, x2, y2, durationMs = 300) {
+    await performActions(udid, [
+        { type: "pointerMove", duration: 0, x: x1, y: y1 },
+        { type: "pointerDown", button: 0 },
+        { type: "pointerMove", duration: durationMs, x: x2, y: y2 },
+        { type: "pointerUp", button: 0 },
+    ]);
+}
+/** Type into the focused element (the caller taps a field first). */
+export async function uiText(udid, text) {
+    const s = await getSession(udid);
+    await wdaCall(s.port, "POST", `/session/${s.sessionId}/wda/keys`, { value: [...text] });
+}
+/**
+ * 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 async function uiKey(udid, keycode) {
+    if (keycode !== 40)
+        throw new IosError(`unsupported WDA keycode: ${keycode}`);
+    const s = await getSession(udid);
+    await wdaCall(s.port, "POST", `/session/${s.sessionId}/wda/keys`, { value: [W3C_ENTER] });
+}
+/** Re-export so a future ios.ts can drop the simctl HID constant. */
+export const HID_KEY_RETURN = 40;

package/dist/lib/paths.d.ts

@@ -12,4 +12,12 @@ export declare function binDir(): string;
 export declare function browsersDir(): string;
 export declare function simulationsDir(): string;
 export declare function cloudflaredBin(): string;
+/**
+ * Cache dir for the prebuilt iOS XCUITest runner (WebDriverAgent) bundle —
+ * the `.app` + `.xctestrun` fetched on demand for native iOS simulations,
+ * mirroring how `cloudflaredBin()` is fetched into `binDir()`.
+ */
+export declare function wdaDir(): string;
+/** Stamp file recording which CLI/runner version the cached WDA bundle is for. */
+export declare function wdaVersionFile(): string;
 export declare function connectLockPath(): string;

package/dist/lib/paths.js

@@ -34,6 +34,18 @@ export function cloudflaredBin() {
     const exe = process.platform === "win32" ? "cloudflared.exe" : "cloudflared";
     return path.join(binDir(), exe);
 }
+/**
+ * Cache dir for the prebuilt iOS XCUITest runner (WebDriverAgent) bundle —
+ * the `.app` + `.xctestrun` fetched on demand for native iOS simulations,
+ * mirroring how `cloudflaredBin()` is fetched into `binDir()`.
+ */
+export function wdaDir() {
+    return path.join(binDir(), "wda");
+}
+/** Stamp file recording which CLI/runner version the cached WDA bundle is for. */
+export function wdaVersionFile() {
+    return path.join(wdaDir(), "VERSION");
+}
 export function connectLockPath() {
     return path.join(rootDir(), "connect.lock");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ishlabs/cli",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "The command-line interface for ish",
   "type": "module",
   "bin": {