@ishlabs/cli 0.25.0 → 0.26.0

package/dist/commands/doctor.d.ts

@@ -0,0 +1,26 @@
+/**
+ * ish check / ish setup — environment diagnostics + dependency setup for
+ * local web and native (iOS/Android) simulations. (`doctor` is a kept alias.)
+ *
+ * `check [platform]` runs read-only checks and prints a flutter-doctor-style
+ * checklist (or `--json`), scoped to one platform's group + Account when a
+ * platform is given (ios|android|web), else everything. `setup`
+ * fetches/installs what it can (Chromium today; the iOS XCUITest runner once
+ * the artifact pipeline lands) and prints guidance for the rest, then re-runs
+ * the checks.
+ *
+ * Design notes:
+ *  - Device probes are light, NON-throwing `execFile` calls reimplemented here
+ *    (not imported from the local-sim drivers): doctor must never throw on a
+ *    missing tool, and must not pull the playwright/local-sim module graph.
+ *  - The Chromium check/setup is a DYNAMIC import of `install.ts` — that module
+ *    deep-imports a non-exported playwright path that crashes at module load on
+ *    the npm-installed CLI, so it can only be loaded lazily (same reason
+ *    `study run --local` imports it dynamically).
+ *  - iOS UI automation is migrating from idb to Apple's XCUITest (a prebuilt
+ *    WebDriverAgent runner fetched into `wdaDir()`); the runner row reflects
+ *    that target. Until the artifact ships, point `ISH_WDA_PATH` at a local
+ *    build.
+ */
+import type { Command } from "commander";
+export declare function registerDoctorCommands(program: Command): void;

package/dist/commands/doctor.js

@@ -0,0 +1,334 @@
+/**
+ * ish check / ish setup — environment diagnostics + dependency setup for
+ * local web and native (iOS/Android) simulations. (`doctor` is a kept alias.)
+ *
+ * `check [platform]` runs read-only checks and prints a flutter-doctor-style
+ * checklist (or `--json`), scoped to one platform's group + Account when a
+ * platform is given (ios|android|web), else everything. `setup`
+ * fetches/installs what it can (Chromium today; the iOS XCUITest runner once
+ * the artifact pipeline lands) and prints guidance for the rest, then re-runs
+ * the checks.
+ *
+ * Design notes:
+ *  - Device probes are light, NON-throwing `execFile` calls reimplemented here
+ *    (not imported from the local-sim drivers): doctor must never throw on a
+ *    missing tool, and must not pull the playwright/local-sim module graph.
+ *  - The Chromium check/setup is a DYNAMIC import of `install.ts` — that module
+ *    deep-imports a non-exported playwright path that crashes at module load on
+ *    the npm-installed CLI, so it can only be loaded lazily (same reason
+ *    `study run --local` imports it dynamically).
+ *  - iOS UI automation is migrating from idb to Apple's XCUITest (a prebuilt
+ *    WebDriverAgent runner fetched into `wdaDir()`); the runner row reflects
+ *    that target. Until the artifact ships, point `ISH_WDA_PATH` at a local
+ *    build.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync, readdirSync } from "node:fs";
+import * as path from "node:path";
+import { runInline } from "../lib/command-helpers.js";
+import { output } from "../lib/output.js";
+import { loadConfig } from "../config.js";
+import { decodeJwtClaims, isTokenExpired } from "../auth.js";
+import { wdaDir } from "../lib/paths.js";
+import pkg from "../../package.json" with { type: "json" };
+const execFileAsync = promisify(execFile);
+const XCRUN = "/usr/bin/xcrun";
+const isMac = process.platform === "darwin";
+async function tryExec(cmd, args, timeoutMs = 8000) {
+    try {
+        const { stdout, stderr } = await execFileAsync(cmd, args, {
+            timeout: timeoutMs,
+            maxBuffer: 8 * 1024 * 1024,
+        });
+        return { ok: true, stdout, stderr };
+    }
+    catch (e) {
+        const err = e;
+        return {
+            ok: false,
+            stdout: err.stdout ?? "",
+            stderr: err.stderr ?? err.message ?? String(e),
+        };
+    }
+}
+/** adb path, mirroring the device layer's resolution (ISH_ADB → ANDROID_HOME → PATH). */
+function resolveAdb() {
+    for (const v of [process.env.ISH_ADB, process.env.ADB]) {
+        if (v && existsSync(v))
+            return v;
+    }
+    for (const home of [process.env.ANDROID_HOME, process.env.ANDROID_SDK_ROOT]) {
+        if (home) {
+            const p = path.join(home, "platform-tools", "adb");
+            if (existsSync(p))
+                return p;
+        }
+    }
+    return "adb";
+}
+// ── Individual checks ──────────────────────────────────────────────────────
+function checkAuth() {
+    const cfg = loadConfig();
+    const token = cfg.access_token || cfg.token;
+    if (!token) {
+        return { key: "auth", name: "Account", group: "Account", status: "fail", message: "not logged in", fix: "ish login" };
+    }
+    const claims = decodeJwtClaims(token);
+    const email = claims?.email ?? "authenticated";
+    if (isTokenExpired(token)) {
+        // Expired access tokens auto-refresh via the refresh_token on the next API
+        // call, so this is a warn, not a hard fail.
+        return { key: "auth", name: "Account", group: "Account", status: "warn", message: `${email} (token expired — refreshes on next call)`, fix: "ish login (if refresh fails)" };
+    }
+    return { key: "auth", name: "Account", group: "Account", status: "pass", message: email };
+}
+function checkWorkspace() {
+    const cfg = loadConfig();
+    if (cfg.workspace) {
+        return { key: "workspace", name: "Active workspace", group: "Account", status: "pass", message: cfg.workspace };
+    }
+    return { key: "workspace", name: "Active workspace", group: "Account", status: "warn", message: "none set", fix: "ish workspace use <id>" };
+}
+async function checkXcode() {
+    if (!isMac) {
+        return { key: "xcode", name: "Xcode / xcrun", group: "iOS", status: "skip", message: "iOS simulations require macOS" };
+    }
+    const r = await tryExec(XCRUN, ["--version"]);
+    if (r.ok) {
+        const ver = r.stdout.trim().split("\n")[0] || "xcrun present";
+        return { key: "xcode", name: "Xcode / xcrun", group: "iOS", status: "pass", message: ver };
+    }
+    return { key: "xcode", name: "Xcode / xcrun", group: "iOS", status: "fail", message: "xcrun not found", fix: "Install Xcode from the App Store, then `xcodebuild -runFirstLaunch`" };
+}
+async function checkSimulator() {
+    if (!isMac) {
+        return { key: "ios_simulator", name: "iOS simulator", group: "iOS", status: "skip" };
+    }
+    const r = await tryExec(XCRUN, ["simctl", "list", "devices", "booted", "-j"]);
+    if (!r.ok) {
+        return { key: "ios_simulator", name: "iOS simulator", group: "iOS", status: "fail", message: "could not query simctl", fix: "Install Xcode" };
+    }
+    let booted = [];
+    try {
+        const parsed = JSON.parse(r.stdout);
+        booted = Object.values(parsed.devices ?? {})
+            .flat()
+            .filter((d) => d.state === "Booted")
+            .map((d) => ({ name: d.name, udid: d.udid }));
+    }
+    catch {
+        return { key: "ios_simulator", name: "iOS simulator", group: "iOS", status: "fail", message: "could not parse simctl output" };
+    }
+    if (booted.length === 1) {
+        return { key: "ios_simulator", name: "iOS simulator", group: "iOS", status: "pass", message: `${booted[0].name} (booted)` };
+    }
+    if (booted.length === 0) {
+        return { key: "ios_simulator", name: "iOS simulator", group: "iOS", status: "warn", message: "none booted", fix: "Open Simulator.app (Xcode ships simulators) or `xcrun simctl boot <udid>`" };
+    }
+    return { key: "ios_simulator", name: "iOS simulator", group: "iOS", status: "warn", message: `${booted.length} booted — native runs drive exactly one`, fix: "Shut down the extras" };
+}
+/** True when the prebuilt XCUITest runner (WebDriverAgent `.app`) is present. */
+function wdaBundlePresent() {
+    const override = process.env.ISH_WDA_PATH;
+    if (override)
+        return existsSync(override);
+    const dir = wdaDir();
+    if (!existsSync(dir))
+        return false;
+    try {
+        return readdirSync(dir).some((e) => e.endsWith(".app"));
+    }
+    catch {
+        return false;
+    }
+}
+function checkXcuitestRunner() {
+    if (!isMac) {
+        return { key: "xcuitest_runner", name: "XCUITest runner", group: "iOS", status: "skip" };
+    }
+    if (wdaBundlePresent()) {
+        return { key: "xcuitest_runner", name: "XCUITest runner", group: "iOS", status: "pass", message: process.env.ISH_WDA_PATH ? "ISH_WDA_PATH" : wdaDir() };
+    }
+    return { key: "xcuitest_runner", name: "XCUITest runner", group: "iOS", status: "warn", message: "not installed", fix: "ish setup (or set ISH_WDA_PATH to a local WebDriverAgent build)" };
+}
+async function checkAdb() {
+    const adbPath = resolveAdb();
+    const r = await tryExec(adbPath, ["devices"]);
+    if (!r.ok) {
+        const adb = { key: "adb", name: "Android adb", group: "Android", status: "warn", message: "not found (only needed for Android)", fix: "Install Android platform-tools" };
+        const emulator = { key: "android_emulator", name: "Android emulator", group: "Android", status: "skip" };
+        return { adb, emulator };
+    }
+    const adb = { key: "adb", name: "Android adb", group: "Android", status: "pass", message: adbPath };
+    // Lines after the "List of devices attached" header, in "device" state.
+    const devices = r.stdout
+        .split("\n")
+        .slice(1)
+        .map((l) => l.trim())
+        .filter((l) => l.endsWith("\tdevice"));
+    const emulator = devices.length === 1
+        ? { key: "android_emulator", name: "Android emulator", group: "Android", status: "pass", message: devices[0].split("\t")[0] }
+        : devices.length === 0
+            ? { key: "android_emulator", name: "Android emulator", group: "Android", status: "warn", message: "none online", fix: "Create + boot an AVD in Android Studio > Device Manager (or `emulator -avd <name>`)" }
+            : { key: "android_emulator", name: "Android emulator", group: "Android", status: "warn", message: `${devices.length} online — native runs drive exactly one`, fix: "Stop the extras" };
+    return { adb, emulator };
+}
+async function checkChromium() {
+    try {
+        const { isBrowserInstalled } = await import("../lib/local-sim/install.js");
+        return isBrowserInstalled()
+            ? { key: "chromium", name: "Chromium (web local)", group: "Web", status: "pass", message: "installed" }
+            : { key: "chromium", name: "Chromium (web local)", group: "Web", status: "warn", message: "not installed", fix: "ish setup" };
+    }
+    catch {
+        return { key: "chromium", name: "Chromium (web local)", group: "Web", status: "skip", message: "unavailable in this build" };
+    }
+}
+function checkCli() {
+    return { key: "cli", name: "ish CLI", group: "Account", status: "pass", message: `v${pkg.version}` };
+}
+async function runChecks() {
+    const { adb, emulator } = await checkAdb();
+    return [
+        await checkXcode(),
+        await checkSimulator(),
+        checkXcuitestRunner(),
+        adb,
+        emulator,
+        await checkChromium(),
+        checkAuth(),
+        checkWorkspace(),
+        checkCli(),
+    ];
+}
+// ── Rendering ───────────────────────────────────────────────────────────────
+const MARK = { pass: "[ OK ]", warn: "[WARN]", fail: "[FAIL]", skip: "[ -- ]" };
+const GROUP_ORDER = ["iOS", "Android", "Web", "Account"];
+const GROUP_LABEL = {
+    iOS: "iOS (native simulations)",
+    Android: "Android (native simulations)",
+    Web: "Web (local browser simulations)",
+    Account: "Account",
+};
+// `ish check <platform>` scopes the report to one platform's group + Account,
+// so an Android study never nags about Xcode and an iOS study never about adb.
+const PLATFORM_GROUPS = {
+    ios: ["iOS", "Account"],
+    android: ["Android", "Account"],
+    web: ["Web", "Account"],
+};
+function scopeChecks(checks, platform) {
+    if (!platform)
+        return checks;
+    const groups = PLATFORM_GROUPS[platform];
+    return groups ? checks.filter((c) => groups.includes(c.group)) : checks;
+}
+function overall(checks) {
+    if (checks.some((c) => c.status === "fail"))
+        return "fail";
+    if (checks.some((c) => c.status === "warn"))
+        return "warn";
+    return "pass";
+}
+function renderHuman(checks) {
+    const lines = ["", "ish check — local & native simulation environment", ""];
+    const width = Math.max(...checks.map((c) => c.name.length)) + 2;
+    for (const group of GROUP_ORDER) {
+        const inGroup = checks.filter((c) => c.group === group);
+        if (inGroup.length === 0)
+            continue;
+        lines.push(`  ${GROUP_LABEL[group]}`);
+        for (const c of inGroup) {
+            const label = c.name.padEnd(width, " ");
+            let line = `    ${MARK[c.status]}  ${label}${c.message ?? ""}`;
+            lines.push(line.trimEnd());
+            if ((c.status === "warn" || c.status === "fail") && c.fix) {
+                lines.push(`            ↳ ${c.fix}`);
+            }
+        }
+        lines.push("");
+    }
+    const o = overall(checks);
+    const fails = checks.filter((c) => c.status === "fail").length;
+    const warns = checks.filter((c) => c.status === "warn").length;
+    if (o === "pass") {
+        lines.push("Everything checks out.");
+    }
+    else {
+        const parts = [fails ? `${fails} blocking` : "", warns ? `${warns} optional` : ""].filter(Boolean);
+        lines.push(`${parts.join(", ")} issue(s). Run \`ish setup\` to fetch what's fetchable.`);
+    }
+    console.log(lines.join("\n"));
+}
+// ── Commands ──────────────────────────────────────────────────────────────
+export function registerDoctorCommands(program) {
+    program
+        .command("check [platform]")
+        .alias("doctor")
+        .description("Check your local simulation setup for a platform (ios | android | web), or everything")
+        .action(async (platform, _opts, cmd) => {
+        await runInline(cmd, async (globals) => {
+            const scope = platform?.toLowerCase();
+            if (scope && !PLATFORM_GROUPS[scope]) {
+                throw new Error(`Unknown platform "${platform}". Use one of: ios, android, web.`);
+            }
+            const checks = scopeChecks(await runChecks(), scope);
+            if (globals.json) {
+                output({ checks, overall: overall(checks) }, true);
+            }
+            else {
+                renderHuman(checks);
+            }
+        });
+    });
+    program
+        .command("setup")
+        .description("Fetch/install local-simulation dependencies (Chromium, iOS runner) and show what's left to do")
+        .action(async (_opts, cmd) => {
+        await runInline(cmd, async (globals) => {
+            const quiet = globals.json;
+            const log = (m) => { if (!quiet)
+                console.error(m); };
+            // 1. Chromium (web local) — auto-fetchable.
+            try {
+                const { isBrowserInstalled, ensureBrowser } = await import("../lib/local-sim/install.js");
+                if (isBrowserInstalled()) {
+                    log("Chromium: already installed.");
+                }
+                else {
+                    log("Chromium: fetching for local web simulations...");
+                    await ensureBrowser({ quiet, skipPrompt: true });
+                }
+            }
+            catch (e) {
+                log(`Chromium: could not install (${e instanceof Error ? e.message : String(e)}).`);
+            }
+            // 2. iOS XCUITest runner (WebDriverAgent) — auto-fetchable on macOS.
+            if (isMac) {
+                try {
+                    if (wdaBundlePresent()) {
+                        log("iOS runner: already installed.");
+                    }
+                    else {
+                        log("iOS runner: fetching WebDriverAgent...");
+                        const { resolveWdaBundle } = await import("../lib/local-sim/xcuitest.js");
+                        await resolveWdaBundle();
+                    }
+                }
+                catch (e) {
+                    log(`iOS runner: could not fetch (${e instanceof Error ? e.message : String(e)}).`);
+                }
+            }
+            // 3. Re-run checks so the user sees the resulting state, and hand back
+            //    the structured result on --json.
+            const checks = await runChecks();
+            if (globals.json) {
+                output({ checks, overall: overall(checks) }, true);
+            }
+            else {
+                renderHuman(checks);
+            }
+        });
+    });
+}

package/dist/index.js

@@ -19,6 +19,7 @@ import { registerDocsCommands } from "./commands/docs.js";
 import { registerInitCommands } from "./commands/init.js";
 import { registerMcpCommands } from "./commands/mcp.js";
 import { registerSecretCommands } from "./commands/secret.js";
+import { registerDoctorCommands } from "./commands/doctor.js";
 import { AGENT_HELP_FOOTER } from "./lib/docs.js";
 import { runInline, EXIT_USAGE, injectGlobalWorkspaceOption } from "./lib/command-helpers.js";
 import { resolveApiUrl, resolveToken, verifyToken } from "./lib/auth.js";
@@ -510,6 +511,7 @@ registerDocsCommands(program);
 registerInitCommands(program);
 registerMcpCommands(program);
 registerSecretCommands(program);
+registerDoctorCommands(program);
 program
     .command("upgrade")
     .description("Update ish to the latest version")

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

@@ -429,6 +429,8 @@ export function describeAction(action) {
             return `wait ${action.duration_ms ?? 1000}ms`;
         case "navigate_back":
             return "navigate back";
+        case "open_system_panel":
+            return `open_system_panel (${action.panel ?? "notifications"})`;
         case "long_press":
             return `long_press on '${element}'${modSuffix}`;
         case "double_tap":

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

@@ -44,6 +44,16 @@ export declare function inputDrag(x1: number, y1: number, x2: number, y2: number
 /** A long-press is a zero-distance swipe held for `durationMs`. */
 export declare function inputLongPress(x: number, y: number, durationMs?: number): Promise<void>;
 export declare function pressKeyEvent(keyevent: string): Promise<void>;
+/**
+ * Open a system panel via `adb shell cmd statusbar expand-settings|expand-notifications`
+ * — a deterministic OS-driven open, chosen over a top-edge `input swipe` because the
+ * generic swipe is center-anchored and a synthetic top-edge swipe never registers the
+ * system pull-down. `expand-notifications` opens the notification shade;
+ * `expand-settings` pulls all the way to quick settings.
+ */
+export declare function statusbarExpand(panel: "expand-settings" | "expand-notifications"): Promise<void>;
+/** Collapse the open system panel (`cmd statusbar collapse`). */
+export declare function statusbarCollapse(): Promise<void>;
 /**
  * Force a device orientation. We first disable auto-rotation
  * (`accelerometer_rotation 0`) — otherwise the sensor immediately overrides

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

@@ -90,7 +90,7 @@ export async function requireOneDevice() {
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        throw new AdbError(`Could not run adb (looked for "${ADB}"). Is the Android SDK installed and an emulator booted? ${msg}`);
+        throw new AdbError(`Could not run adb (looked for "${ADB}"). Run \`ish check android\` to check your setup. ${msg}`);
     }
     // Output: "List of devices attached\n<serial>\tdevice\n..."
     const online = out
@@ -99,7 +99,7 @@ export async function requireOneDevice() {
         .map((l) => l.trim())
         .filter((l) => l && l.endsWith("\tdevice"));
     if (online.length === 0) {
-        throw new AdbError("No Android device/emulator online. Boot one first (e.g. `npm run mobile-e2e-setup`).");
+        throw new AdbError("No Android device/emulator online. Run `ish check android` to check your setup and how to boot one.");
     }
     if (online.length > 1) {
         throw new AdbError(`Expected exactly one Android device, found ${online.length}. Stop the extras (the sim drives a single device).`);
@@ -153,6 +153,20 @@ export async function inputLongPress(x, y, durationMs = 600) {
 export async function pressKeyEvent(keyevent) {
     await adbShell(["input", "keyevent", keyevent]);
 }
+/**
+ * Open a system panel via `adb shell cmd statusbar expand-settings|expand-notifications`
+ * — a deterministic OS-driven open, chosen over a top-edge `input swipe` because the
+ * generic swipe is center-anchored and a synthetic top-edge swipe never registers the
+ * system pull-down. `expand-notifications` opens the notification shade;
+ * `expand-settings` pulls all the way to quick settings.
+ */
+export async function statusbarExpand(panel) {
+    await adbShell(["cmd", "statusbar", panel]);
+}
+/** Collapse the open system panel (`cmd statusbar collapse`). */
+export async function statusbarCollapse() {
+    await adbShell(["cmd", "statusbar", "collapse"]);
+}
 /**
  * Force a device orientation. We first disable auto-rotation
  * (`accelerometer_rotation 0`) — otherwise the sensor immediately overrides

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

@@ -19,7 +19,7 @@
  *   - Vision path: px = round(x / 1000 * screencapWidth); same for y.
  */
 import { resolveTextValue } from "./actions.js";
-import { requireOneDevice, screencapPng, pngDimensions, dumpUiautomatorXml, inputTap, inputSwipe, inputDrag, inputLongPress, setUserRotation, forceStop, launchApp, installApk, isPackageInstalled, listPackages, isAdbKeyboardInstalled, enableAdbKeyboard, setIme, resetIme, currentIme, adbKeyboardType, adbKeyboardClear, pressKeyEvent, ADB_KEYBOARD_PKG, } from "./adb.js";
+import { requireOneDevice, screencapPng, pngDimensions, dumpUiautomatorXml, inputTap, inputSwipe, inputDrag, inputLongPress, setUserRotation, forceStop, launchApp, installApk, isPackageInstalled, listPackages, isAdbKeyboardInstalled, enableAdbKeyboard, setIme, resetIme, currentIme, adbKeyboardType, adbKeyboardClear, pressKeyEvent, statusbarExpand, ADB_KEYBOARD_PKG, } from "./adb.js";
 import { isLocalPath } from "../upload.js";
 import { deNormalizePoint, deNormalizeDrag } from "./coordinates.js";
 import { parseUiautomatorXml, serializeNativeTree, boundsCenter } from "./native-a11y.js";
@@ -276,6 +276,11 @@ export class AndroidDevice {
                     await pressKeyEvent("KEYCODE_BACK");
                     break;
                 }
+                case "open_system_panel": {
+                    // Element-less, like navigate_back: no px, just an OS-driven panel open.
+                    await statusbarExpand(action.panel === "quick_settings" ? "expand-settings" : "expand-notifications");
+                    break;
+                }
                 case "drag": {
                     // A drag GRABS an element and RELEASES it elsewhere ("click the
                     // element, move, let go") — distinct from a swipe (element-less

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

@@ -3,7 +3,7 @@
  *
  * The backend's vision locator returns NORMALIZED 0-1000 coordinates. A native
  * device de-normalizes them against a concrete dimension (screencap pixels for
- * Android; idb POINTS for the iOS tap, screenshot PIXELS for the iOS record),
+ * Android; WDA POINTS for the iOS tap, screenshot PIXELS for the iOS record),
  * and the loop later re-normalizes the recorded coordinate back to 0-1000.
  *
  * Pure and side-effect-free so the round-trip can be unit-tested without a
@@ -32,7 +32,7 @@ export declare function deNormalizePoint(c: {
  * De-normalize a drag's start AND end points (each normalized 0-1000) against
  * one device dimension into the {start,end} pixel/point pair the drivers feed to
  * a slow swipe. The drag path is a from→to gesture, so BOTH ends de-normalize
- * against the SAME basis (Android: screencap pixels; iOS: idb POINTS). Pure so
+ * against the SAME basis (Android: screencap pixels; iOS: WDA POINTS). Pure so
  * the two-ended de-normalization is unit-testable without a device.
  */
 export declare function deNormalizeDrag(drag: {
@@ -52,9 +52,9 @@ export declare function deNormalizeDrag(drag: {
 };
 /**
  * Scale an iOS POINT coordinate into the PIXEL space, used by the element path:
- * `idb` reports a11y frames (and so the tappable bounds-center) in POINTS, but
+ * WebDriverAgent reports a11y frames (and so the tappable bounds-center) in POINTS, but
  * the loop records — and re-normalizes against `dimensions()` — in PIXELS. So
- * the element path taps the point-center directly (idb consumes points) yet must
+ * the element path taps the point-center directly (WDA consumes points) yet must
  * RECORD a pixel-center; this converts the one to the other per-axis by the
  * point→pixel ratio (the @Nx scale). Pure so the conversion is unit-testable
  * without a simulator. Android needs no analog: its screencap and tap share one

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

@@ -3,7 +3,7 @@
  *
  * The backend's vision locator returns NORMALIZED 0-1000 coordinates. A native
  * device de-normalizes them against a concrete dimension (screencap pixels for
- * Android; idb POINTS for the iOS tap, screenshot PIXELS for the iOS record),
+ * Android; WDA POINTS for the iOS tap, screenshot PIXELS for the iOS record),
  * and the loop later re-normalizes the recorded coordinate back to 0-1000.
  *
  * Pure and side-effect-free so the round-trip can be unit-tested without a
@@ -32,7 +32,7 @@ export function deNormalizePoint(c, width, height) {
  * De-normalize a drag's start AND end points (each normalized 0-1000) against
  * one device dimension into the {start,end} pixel/point pair the drivers feed to
  * a slow swipe. The drag path is a from→to gesture, so BOTH ends de-normalize
- * against the SAME basis (Android: screencap pixels; iOS: idb POINTS). Pure so
+ * against the SAME basis (Android: screencap pixels; iOS: WDA POINTS). Pure so
  * the two-ended de-normalization is unit-testable without a device.
  */
 export function deNormalizeDrag(drag, width, height) {
@@ -43,9 +43,9 @@ export function deNormalizeDrag(drag, width, height) {
 }
 /**
  * Scale an iOS POINT coordinate into the PIXEL space, used by the element path:
- * `idb` reports a11y frames (and so the tappable bounds-center) in POINTS, but
+ * WebDriverAgent reports a11y frames (and so the tappable bounds-center) in POINTS, but
  * the loop records — and re-normalizes against `dimensions()` — in PIXELS. So
- * the element path taps the point-center directly (idb consumes points) yet must
+ * the element path taps the point-center directly (WDA consumes points) yet must
  * RECORD a pixel-center; this converts the one to the other per-axis by the
  * point→pixel ratio (the @Nx scale). Pure so the conversion is unit-testable
  * without a simulator. Android needs no analog: its screencap and tap share one

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

@@ -18,7 +18,7 @@ import type { BrowserSession } from "./browser.js";
  * One observation of the target's current state.
  *
  * `accessibilityTree` is populated by the browser (CDP) and by native targets
- * (uiautomator / idb describe-all), serialized to the same `[id] role "name"`
+ * (uiautomator / WDA /source), serialized to the same `[id] role "name"`
  * format the backend DOMLocator reasons over; it's "" only when a native dump
  * fails or yields a sparse tree, which makes the backend take its vision branch.
  * `url` is browser-only ("" for native). `tabs` is browser-only and empty for
@@ -130,7 +130,7 @@ export declare class BrowserDevice implements SimulationDevice {
 /**
  * Build the device for a platform. `web`/`browser`/`""` → Playwright
  * `BrowserDevice`; `android` → `AndroidDevice` (adb); `ios` → `IOSDevice`
- * (simctl + idb). The native cases are dynamically imported so the browser path
+ * (simctl + WebDriverAgent). The native cases are dynamically imported so the browser path
  * never pulls in the adb/simctl modules.
  */
 export declare function createDevice(platform: string, opts: {

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

@@ -116,7 +116,7 @@ export class BrowserDevice {
 /**
  * Build the device for a platform. `web`/`browser`/`""` → Playwright
  * `BrowserDevice`; `android` → `AndroidDevice` (adb); `ios` → `IOSDevice`
- * (simctl + idb). The native cases are dynamically imported so the browser path
+ * (simctl + WebDriverAgent). The native cases are dynamically imported so the browser path
  * never pulls in the adb/simctl modules.
  */
 export async function createDevice(platform, opts) {

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

@@ -1,14 +1,15 @@
 /**
- * IOSDevice — drives a local iOS simulator via `xcrun simctl` + `idb`,
+ * IOSDevice — drives a local iOS simulator via `xcrun simctl` (lifecycle +
+ * screenshot) and WebDriverAgent/XCUITest (UI + a11y; see xcuitest.ts),
  * implementing the SimulationDevice surface the loop expects. Mirrors
  * AndroidDevice; the one substantive difference is the coordinate space.
  *
  * Two resolution paths, mirroring the browser:
- *  - ELEMENT (preferred): observe() reads the `idb ui describe-all` a11y tree,
- *    serializes it to the `[id] role "label"` string the backend DOMLocator
- *    reasons over, and keeps a local `shortId → bounds` map (bounds in POINTS).
- *    The backend returns a `node_id`; executeAction() looks the bounds up and
- *    taps the element's CENTER.
+ *  - ELEMENT (preferred): observe() reads WDA's `/source` a11y tree, serializes
+ *    it to the `[id] role "label"` string the backend DOMLocator reasons over,
+ *    and keeps a local `shortId → bounds` map (bounds in POINTS). The backend
+ *    returns a `node_id`; executeAction() looks the bounds up and taps the
+ *    element's CENTER.
  *  - VISION (fallback): when the tree is empty/sparse, observe() returns an
  *    empty tree so the backend takes its vision branch and returns NORMALIZED
  *    0-1000 coordinates. Also taken per-action whenever node_id is absent.
@@ -16,7 +17,7 @@
  * COORDINATE SPACE — two spaces, the key difference from Android (where
  * screencap and tap share one pixel space):
  *   `simctl io booted screenshot` is in PIXELS (e.g. 1179x2556 @3x), but
- *   `idb ui tap/swipe` AND the `describe-all` a11y frames are POINTS (393x852).
+ *   WDA taps/swipes AND the `/source` a11y frames are POINTS (393x852).
  *   The invariant in BOTH paths: TAP in points, RECORD in pixels, because the
  *   loop re-normalizes the recorded coord against dimensions() (PIXELS).
  *     - VISION:  tap pt = round(n/1000 * pointSize); record px = round(n/1000 * pixelSize).
@@ -46,6 +47,8 @@ export declare class IOSDevice implements SimulationDevice {
     private readonly appPath;
     /** udid of the single booted simulator we drive. */
     private udid;
+    /** Set once the WebDriverAgent runner is up, so the startup note logs once. */
+    private wdaStarted;
     /** POINT size — what idb ui tap/swipe consume (de-normalization basis for TAPS). */
     private pointWidth;
     private pointHeight;
@@ -77,7 +80,7 @@ export declare class IOSDevice implements SimulationDevice {
     private refreshScreen;
     observe(): Promise<DeviceObservation>;
     /**
-     * Read + serialize the idb describe-all a11y tree (bounds in POINTS). Any
+     * Read + serialize WDA's /source a11y tree (bounds in POINTS). Any
      * failure (retries exhausted on a trivial tree, parse error) degrades to an
      * empty tree so the backend falls back to vision — a missing tree must never
      * abort the observation.
@@ -89,7 +92,7 @@ export declare class IOSDevice implements SimulationDevice {
         width: number;
         height: number;
     };
-    /** Normalized 0-1000 → POINT space (idb ui tap/swipe take points). */
+    /** Normalized 0-1000 → POINT space (WDA taps/swipes take points). */
     private toPoints;
     /** Normalized 0-1000 → PIXEL space (the recorded/reported coord). */
     private toPixels;
@@ -140,6 +143,20 @@ export declare class IOSDevice implements SimulationDevice {
      * do drive the system gesture) when no back button is visible.
      */
     private navigateBack;
+    /**
+     * Best-effort open of an iOS system panel by swiping down from the top edge.
+     * iOS has no `cmd statusbar` equivalent, so on a Face-ID layout:
+     *   - notifications → Notification Center: swipe down from the top-CENTER.
+     *   - quick_settings → Control Center: swipe down from the top-RIGHT corner.
+     * Coordinates are POINTS (idb consumes points; see toPoints()/the swipe()
+     * helper). This is FLAKY on the simulator — idb's synthetic touch frequently
+     * doesn't trigger the system edge gesture (the same limitation navigateBack's
+     * edge-swipe hits). We compare a before/after screenshot and log LOUDLY when
+     * the screen didn't change, rather than silently reporting success, so a
+     * no-op is visible in the run. The executeAction caller still returns
+     * success:true (the gesture was attempted); the loud log is the signal.
+     */
+    private openSystemPanel;
     /**
      * The nav-bar back button: the leading (leftmost) actionable button in the
      * top nav-bar band. iOS HIG guarantees "back" is the leading nav item in a