@ishlabs/cli 0.25.0 → 0.26.1

package/dist/lib/docs.js

@@ -380,6 +380,14 @@ ish iteration create --platform figma --url https://figma.com/proto \\
     --screen-format mobile_portrait --file-key abc123 --start-node-id 0:1 \\
     --flow-name "Onboarding A"
 
+# Native app (ios / android): --app names the target, stored as app_artifact (no URL).
+ish iteration create --platform ios --app com.example.app
+ish iteration create --platform ios            # --app optional; "chosen at run time"
+# drive it locally against a booted simulator / emulator — the iteration
+# remembers the app, so no --app needed on reruns:
+ish study run --local
+ish study run --local --app ./Build.app        # override with a fresh local build
+
 # Text/email content from a file:
 ish iteration create --content-text @./email.html --title "Newsletter"
 
@@ -1992,10 +2000,14 @@ Interactive study runs produce per-frame screenshots server-side. They
 let you (or an agent) see what participants actually saw alongside the
 sentiment summary.
 
-## Screenshots — interactive studies only
+## Screenshots — remote interactive studies only
 
-Screenshots are produced by interactive runs only — chat / video / text
-studies don't have them.
+Screenshots are produced by remote interactive runs only — chat / video /
+text studies don't have them. **Local runs** (\`ish study run --local\`,
+including ios/android) don't push screenshots to the server either; they
+write a per-step HTML debug report to \`~/.ish/debug/sim-*.html\` (the path is
+printed at the end of the run). \`ish study screenshots list\` on a local-only
+study therefore returns nothing useful — open the debug report instead.
 
 ### CLI
 

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

@@ -25,6 +25,24 @@ export declare function resolveTextValue(action: LocalStepAction, contextValues:
  * Compare two base64 screenshots to detect visible change.
  */
 export declare function detectNoVisibleChange(before: string, after: string): boolean;
+/**
+ * Logical classification of what a completed step's batch of actions did to the
+ * screen, used to tell the backend's frame matcher whether the NEXT observation
+ * is the same logical screen (so it reuses the previous frame instead of minting
+ * a new one off shifted pixels).
+ *
+ * - "scroll":   a pure vertical scroll (all actions succeeded) — same screen.
+ * - "keyboard": raised the keyboard without submitting/navigating — same screen.
+ * - "ui_change": anything that (likely) changed the logical screen — NOT same.
+ * - "none":     nothing actionable happened (empty batch / think-only).
+ */
+export type StepKind = "scroll" | "keyboard" | "ui_change" | "none";
+/**
+ * Classify a step's batch of actions into a StepKind. Pure — `successByIndex[i]`
+ * is the executor's `result.success` for `actions[i]`. `think` actions are
+ * ignored entirely (they neither move the screen nor count toward a verdict).
+ */
+export declare function classifyStepKind(actions: LocalStepAction[], successByIndex: boolean[]): StepKind;
 /**
  * Build a human-readable action description matching backend's format_action_detail().
  */

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

@@ -403,6 +403,36 @@ function isRecoverableError(err) {
 export function detectNoVisibleChange(before, after) {
     return before === after;
 }
+// Scroll directions that keep us on the same logical screen (vertical pan).
+// undefined/null defaults to a downward scroll in executeScroll(), so it counts.
+const VERTICAL_SCROLL_DIRECTIONS = new Set([
+    "up", "down", "to_top", "to_bottom", "to_element",
+]);
+/**
+ * Classify a step's batch of actions into a StepKind. Pure — `successByIndex[i]`
+ * is the executor's `result.success` for `actions[i]`. `think` actions are
+ * ignored entirely (they neither move the screen nor count toward a verdict).
+ */
+export function classifyStepKind(actions, successByIndex) {
+    // Keep the original index so success lines up after dropping `think`s.
+    const considered = actions
+        .map((action, i) => ({ action, success: successByIndex[i] }))
+        .filter(({ action }) => action.type !== "think");
+    if (considered.length === 0)
+        return "none";
+    // Pure vertical scroll: every action a successful vertical scroll.
+    const allScroll = considered.every(({ action, success }) => action.type === "scroll" &&
+        success === true &&
+        VERTICAL_SCROLL_DIRECTIONS.has(action.direction ?? "down"));
+    if (allScroll)
+        return "scroll";
+    // Keyboard-only: every action a text_input that raises the keyboard WITHOUT
+    // submitting/navigating. A submit makes it a ui_change (it can navigate away).
+    const allKeyboard = considered.every(({ action }) => action.type === "text_input" && !action.submit);
+    if (allKeyboard)
+        return "keyboard";
+    return "ui_change";
+}
 /**
  * Build a human-readable action description matching backend's format_action_detail().
  */
@@ -429,6 +459,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

@@ -10,6 +10,8 @@
  * backend's 0-1000 coordinates against the screencap pixel size and taps
  * directly. (Verified by the Layer-1 driver smoke; see scripts/mobile-e2e.)
  */
+/** Resolve adb, downloading Google's platform-tools on first use if not found. */
+export declare function ensureAdb(): Promise<string>;
 export declare class AdbError extends Error {
     constructor(message: string);
 }
@@ -17,6 +19,27 @@ export declare class AdbError extends Error {
 export declare function adb(args: string[], timeoutMs?: number): Promise<string>;
 /** Run `adb shell <args>` and return trimmed stdout. */
 export declare function adbShell(args: string[], timeoutMs?: number): Promise<string>;
+/**
+ * Pull versionName / versionCode out of `dumpsys package <pkg>` text. The
+ * relevant lines read `versionCode=42 minSdk=24 targetSdk=34` and
+ * `versionName=1.2.3`; `\d+` stops the build before the trailing tokens and
+ * `\S+` takes the version up to the next space. Returns null when neither is
+ * present (wrong/empty package).
+ */
+export declare function parseDumpsysAppBuild(out: string): {
+    version: string | null;
+    build: string | null;
+} | null;
+/**
+ * Read an installed package's versionName / versionCode from
+ * `dumpsys package <pkg>`. Best-effort: returns null on any failure (the run
+ * never depends on it). Covers both freshly-installed apks and pre-installed
+ * packages — by call time the package name is already resolved.
+ */
+export declare function appBuildFromDevice(pkg: string): Promise<{
+    version: string | null;
+    build: string | null;
+} | null>;
 /**
  * Capture the current screen as raw PNG bytes via `adb exec-out screencap -p`.
  * `exec-out` (not `shell`) avoids the CRLF translation that corrupts binary
@@ -44,6 +67,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

@@ -10,30 +10,90 @@
  * backend's 0-1000 coordinates against the screencap pixel size and taps
  * directly. (Verified by the Layer-1 driver smoke; see scripts/mobile-e2e.)
  */
-import { execFile } from "node:child_process";
-import { existsSync } from "node:fs";
+import { execFile, execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
 import { promisify } from "node:util";
+import { binDir, adbBin } from "../paths.js";
 const execFileAsync = promisify(execFile);
-// adb ships with Homebrew's android-platform-tools and inside the SDK. Prefer
-// an explicit absolute path so we never depend on the caller's PATH (mirrors
-// scripts/mobile-e2e/lib.sh). Override with ISH_ADB / ADB.
-function resolveAdb() {
+// Resolve adb without depending on the caller's PATH: ISH_ADB/ADB override → the
+// Android SDK → Homebrew → our own download cache → PATH. If none is found,
+// ensureAdb() fetches Google's standalone platform-tools (a small zip) into
+// ~/.ish/bin, mirroring how cloudflared / the iOS WebDriverAgent runner are
+// fetched. Override the binary with ISH_ADB / ADB.
+function findAdb() {
     const fromEnv = process.env.ISH_ADB || process.env.ADB;
     if (fromEnv && existsSync(fromEnv))
         return fromEnv;
-    const homebrew = "/opt/homebrew/bin/adb";
-    if (existsSync(homebrew))
-        return homebrew;
     const sdkHome = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT;
     if (sdkHome) {
-        const sdkAdb = `${sdkHome}/platform-tools/adb`;
+        const sdkAdb = join(sdkHome, "platform-tools", "adb");
         if (existsSync(sdkAdb))
             return sdkAdb;
     }
-    // Last resort: rely on PATH and surface a clear error if it's missing.
-    return "adb";
+    const homebrew = "/opt/homebrew/bin/adb";
+    if (existsSync(homebrew))
+        return homebrew;
+    if (existsSync(adbBin()))
+        return adbBin(); // our downloaded cache
+    // PATH fallback — only if `adb` actually resolves there.
+    try {
+        execFileSync(process.platform === "win32" ? "where" : "which", ["adb"], { stdio: "ignore" });
+        return "adb";
+    }
+    catch {
+        return null;
+    }
+}
+let cachedAdb = null;
+/** Resolve adb, downloading Google's platform-tools on first use if not found. */
+export async function ensureAdb() {
+    if (cachedAdb)
+        return cachedAdb;
+    cachedAdb = findAdb() ?? (await downloadAdb());
+    return cachedAdb;
+}
+const PLATFORM_TOOLS_OS = {
+    darwin: "darwin",
+    linux: "linux",
+    win32: "windows",
+};
+/** Fetch + unpack Google's standalone platform-tools into ~/.ish/bin. */
+async function downloadAdb() {
+    const os = PLATFORM_TOOLS_OS[process.platform];
+    if (!os) {
+        throw new AdbError(`no prebuilt adb for ${process.platform}; install Android platform-tools and set ISH_ADB`);
+    }
+    const url = `https://dl.google.com/android/repository/platform-tools-latest-${os}.zip`;
+    const dir = binDir();
+    console.error("Fetching adb (Android platform-tools) from Google...");
+    mkdirSync(dir, { recursive: true });
+    const zipPath = join(dir, "platform-tools.zip");
+    let resp;
+    try {
+        resp = await fetch(url, { signal: AbortSignal.timeout(120_000) });
+    }
+    catch (e) {
+        throw new AdbError(`failed to download platform-tools from ${url}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!resp.ok)
+        throw new AdbError(`failed to download platform-tools: HTTP ${resp.status} from ${url}`);
+    writeFileSync(zipPath, Buffer.from(await resp.arrayBuffer()));
+    try {
+        // The zip carries a top-level `platform-tools/` dir; extract into binDir().
+        const [cmd, args] = process.platform === "win32"
+            ? ["tar", ["-xf", zipPath, "-C", dir]]
+            : ["unzip", ["-o", "-q", zipPath, "-d", dir]];
+        await execFileAsync(cmd, args, { timeout: 120_000 });
+    }
+    catch (e) {
+        throw new AdbError(`failed to unpack platform-tools: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    rmSync(zipPath, { force: true });
+    if (!existsSync(adbBin()))
+        throw new AdbError(`platform-tools unpacked but adb is missing at ${adbBin()}`);
+    return adbBin();
 }
-const ADB = resolveAdb();
 const DEFAULT_TIMEOUT_MS = 30_000;
 // screencap on a cold emulator frame can be slow; give it generous headroom.
 const SCREENCAP_TIMEOUT_MS = 30_000;
@@ -47,8 +107,9 @@ export class AdbError extends Error {
 }
 /** Run `adb <args>` and return trimmed stdout. Throws AdbError on failure. */
 export async function adb(args, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const bin = await ensureAdb();
     try {
-        const { stdout } = await execFileAsync(ADB, args, {
+        const { stdout } = await execFileAsync(bin, args, {
             timeout: timeoutMs,
             maxBuffer: 4 * 1024 * 1024,
         });
@@ -63,14 +124,43 @@ export async function adb(args, timeoutMs = DEFAULT_TIMEOUT_MS) {
 export async function adbShell(args, timeoutMs = DEFAULT_TIMEOUT_MS) {
     return adb(["shell", ...args], timeoutMs);
 }
+/**
+ * Pull versionName / versionCode out of `dumpsys package <pkg>` text. The
+ * relevant lines read `versionCode=42 minSdk=24 targetSdk=34` and
+ * `versionName=1.2.3`; `\d+` stops the build before the trailing tokens and
+ * `\S+` takes the version up to the next space. Returns null when neither is
+ * present (wrong/empty package).
+ */
+export function parseDumpsysAppBuild(out) {
+    const version = out.match(/versionName=(\S+)/)?.[1] ?? null;
+    const build = out.match(/versionCode=(\d+)/)?.[1] ?? null;
+    if (!version && !build)
+        return null;
+    return { version, build };
+}
+/**
+ * Read an installed package's versionName / versionCode from
+ * `dumpsys package <pkg>`. Best-effort: returns null on any failure (the run
+ * never depends on it). Covers both freshly-installed apks and pre-installed
+ * packages — by call time the package name is already resolved.
+ */
+export async function appBuildFromDevice(pkg) {
+    try {
+        return parseDumpsysAppBuild(await adbShell(["dumpsys", "package", pkg], 30_000));
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Capture the current screen as raw PNG bytes via `adb exec-out screencap -p`.
  * `exec-out` (not `shell`) avoids the CRLF translation that corrupts binary
  * output. Returns the PNG buffer at full device resolution.
  */
 export async function screencapPng() {
+    const bin = await ensureAdb();
     try {
-        const { stdout } = await execFileAsync(ADB, ["exec-out", "screencap", "-p"], {
+        const { stdout } = await execFileAsync(bin, ["exec-out", "screencap", "-p"], {
             timeout: SCREENCAP_TIMEOUT_MS,
             maxBuffer: SCREENCAP_MAX_BUFFER,
             encoding: "buffer",
@@ -90,7 +180,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 "${findAdb() ?? "adb"}"). Run \`ish check android\` to check your setup. ${msg}`);
     }
     // Output: "List of devices attached\n<serial>\tdevice\n..."
     const online = out
@@ -99,7 +189,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 +243,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.d.ts

@@ -19,7 +19,7 @@
  *   - Vision path: px = round(x / 1000 * screencapWidth); same for y.
  */
 import type { LocalStepAction, ContextValue } from "./types.js";
-import type { SimulationDevice, DeviceObservation, DeviceActionResult } from "./device.js";
+import type { SimulationDevice, DeviceObservation, DeviceActionResult, AppBuild } from "./device.js";
 export interface AndroidDeviceOptions {
     /** App package name to force-stop/relaunch between participants. May be derived from --app. */
     appPackage?: string;
@@ -47,6 +47,12 @@ export declare class AndroidDevice implements SimulationDevice {
     private adbKeyboardActive;
     constructor(opts: AndroidDeviceOptions);
     launchOrReset(target: string): Promise<void>;
+    /**
+     * The installed app's version/build, read off the device after
+     * launchOrReset has resolved the package. Best-effort — null until the
+     * package is known, or if dumpsys can't report it.
+     */
+    appBuild(): Promise<AppBuild | null>;
     /**
      * Resolve which package to drive, returning a non-null package name or
      * throwing. For a local .apk we read the package straight from its binary

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, appBuildFromDevice, 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";
@@ -74,6 +74,21 @@ export class AndroidDevice {
         // Prime screencap dimensions for the first de-normalization.
         await this.refreshDimensions();
     }
+    /**
+     * The installed app's version/build, read off the device after
+     * launchOrReset has resolved the package. Best-effort — null until the
+     * package is known, or if dumpsys can't report it.
+     */
+    async appBuild() {
+        if (!this.appPackage)
+            return null;
+        const meta = await appBuildFromDevice(this.appPackage);
+        return {
+            package: this.appPackage,
+            version: meta?.version ?? null,
+            build: meta?.build ?? null,
+        };
+    }
     /**
      * Resolve which package to drive, returning a non-null package name or
      * throwing. For a local .apk we read the package straight from its binary
@@ -276,6 +291,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
@@ -56,6 +56,19 @@ export interface DeviceActionResult {
     } | null;
     openedNewTab: boolean;
 }
+/**
+ * The version/build of the installed native app being driven, read off the
+ * device after `launchOrReset`. Lets the web app show which build an iteration
+ * last ran against. `package` is the resolved bundle id (iOS) / package name
+ * (Android); `version` is the marketing version (CFBundleShortVersionString /
+ * versionName) and `build` the build number (CFBundleVersion / versionCode),
+ * either of which may be null when the device doesn't report it.
+ */
+export interface AppBuild {
+    package: string;
+    version: string | null;
+    build: string | null;
+}
 /**
  * A drivable simulation target. Implementations own their own lifecycle and
  * (for the browser) tab bookkeeping.
@@ -90,6 +103,12 @@ export interface SimulationDevice {
     executeAction(action: LocalStepAction): Promise<DeviceActionResult>;
     /** Current location string for recording (URL for browser; "" for native). */
     currentUrl(): string;
+    /**
+     * Native only: the version/build of the installed app being driven, read
+     * off the device after `launchOrReset`. Browser omits it. Best-effort — a
+     * failed read resolves to null and never disturbs the run.
+     */
+    appBuild?(): Promise<AppBuild | null>;
     /** Tear down. For shared-browser tabs this closes just the tab. */
     close(): Promise<void>;
 }
@@ -130,7 +149,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).
@@ -30,7 +31,7 @@
  *   backend never converts coords with screen_width/height.
  */
 import type { LocalStepAction, ContextValue } from "./types.js";
-import type { SimulationDevice, DeviceObservation, DeviceActionResult } from "./device.js";
+import type { SimulationDevice, DeviceObservation, DeviceActionResult, AppBuild } from "./device.js";
 export interface IosDeviceOptions {
     /** Bundle id to terminate/relaunch between participants. Derived from --app when a .app is given. */
     bundleId?: string;
@@ -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;
@@ -67,6 +70,12 @@ export declare class IOSDevice implements SimulationDevice {
     private lastNodeMap;
     constructor(opts: IosDeviceOptions);
     launchOrReset(target: string): Promise<void>;
+    /**
+     * The installed app's version/build, read off the simulator after
+     * launchOrReset has resolved the bundle id. Best-effort — null until the
+     * bundle id is known, or if simctl/plutil can't report it.
+     */
+    appBuild(): Promise<AppBuild | null>;
     /**
      * Resolve the bundle id to drive, returning a non-null id or throwing.
      * Installs a local `.app` first and reads its CFBundleIdentifier from
@@ -77,7 +86,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 +98,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 +149,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