@vostride/agent-qa-ios 0.1.21 → 0.2.2

package/dist/index.js

@@ -1,8 +1,44 @@
 // src/adapter.ts
-import { MobileSetupError, parseMobileSource, MobileElementResolver, KEY_MAP, computeSwipe, computePinch, computeFingerPositions, alignToWindow, warnIfOutOfBounds } from "@vostride/agent-qa-core";
+import {
+  assertNever,
+  buildScreenState,
+  compareFillReread,
+  createSnapshotLiveStream,
+  resolveAppName,
+  runDirectionScroll,
+  runToEndScroll,
+  runUntilVisibleLoop
+} from "@vostride/agent-qa-runner";
+import {
+  KEY_MAP,
+  MobileElementResolver,
+  MobileSetupError,
+  buildRefEntries,
+  computeFingerPositions,
+  computePinch,
+  computeSwipe,
+  deriveMobileScroll,
+  IOS_EDITABLE_TYPES,
+  parseMobileSource,
+  warnIfOutOfBounds
+} from "@vostride/agent-qa-core";
+import { alignToWindow } from "@vostride/agent-qa-runner-local";
 
 // src/session.ts
 import { remote } from "webdriverio";
+var IOS_SNAPSHOT_MAX_DEPTH = 62;
+var IOS_SNAPSHOT_FALLBACK_DEPTH = 50;
+var IOS_SNAPSHOT_DEPTH_ENV = "AGENT_QA_IOS_SNAPSHOT_MAX_DEPTH";
+var IOS_SNAPSHOT_DEPTH_CAPABILITY = "appium:settings[snapshotMaxDepth]";
+function positiveInteger(value) {
+  if (typeof value === "number") return Number.isSafeInteger(value) && value > 0 ? value : void 0;
+  if (typeof value !== "string" || !/^\d+$/.test(value.trim())) return void 0;
+  const parsed = Number(value.trim());
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : void 0;
+}
+function resolveIOSSnapshotDepth(farmCapabilities) {
+  return positiveInteger(farmCapabilities?.[IOS_SNAPSHOT_DEPTH_CAPABILITY]) ?? positiveInteger(process.env[IOS_SNAPSHOT_DEPTH_ENV]) ?? IOS_SNAPSHOT_MAX_DEPTH;
+}
 async function createIOSSession(config, farmSession) {
   const match = config.device?.match ?? {};
   const appiumUrl = process.env.AGENT_QA_APPIUM_URL ?? config.appiumUrl ?? "http://localhost:4723";
@@ -14,7 +50,8 @@ async function createIOSSession(config, farmSession) {
     "appium:automationName": match.automationName ?? "XCUITest",
     "appium:deviceName": config.device?.name ?? "iPhone Simulator",
     "appium:showIOSLog": true,
-    "appium:newCommandTimeout": config.timeouts?.test ? Math.ceil(config.timeouts.test / 1e3) : 300
+    "appium:newCommandTimeout": config.timeouts?.test ? Math.ceil(config.timeouts.test / 1e3) : 300,
+    [IOS_SNAPSHOT_DEPTH_CAPABILITY]: resolveIOSSnapshotDepth()
   };
   if (!browserName && appStateNoReset !== void 0) capabilities["appium:noReset"] = appStateNoReset;
   if (match.platformVersion) capabilities["appium:platformVersion"] = match.platformVersion;
@@ -49,7 +86,6 @@ async function createIOSSession(config, farmSession) {
 }
 
 // src/adapter.ts
-var IOS_FILLABLE_ROLES = /* @__PURE__ */ new Set(["textbox", "searchbox", "textfield", "securetextfield", "searchfield", "combobox"]);
 var IOS_NATIVE_SELECT_TYPES = /* @__PURE__ */ new Set([
   "XCUIElementTypePickerWheel",
   "XCUIElementTypePicker",
@@ -58,6 +94,36 @@ var IOS_NATIVE_SELECT_TYPES = /* @__PURE__ */ new Set([
   "XCUIElementTypeComboBox"
 ]);
 var IOS_NATIVE_SELECT_ROLES = /* @__PURE__ */ new Set(["pickerwheel", "spinbutton", "combobox"]);
+var W3C_ELEMENT_KEY = "element-6066-11e4-a52e-4f735a1b0f2d";
+var IOS_SNAPSHOT_PROBE_INTERVAL = 20;
+function errorNameAndMessage(err) {
+  return err instanceof Error ? `${err.name} ${err.message}` : String(err);
+}
+function isIOSSnapshotDepthError(err) {
+  return /kAXErrorIllegalArgument/i.test(errorNameAndMessage(err));
+}
+function isIOSSnapshotReadError(err) {
+  return /getting snapshot|stale element/i.test(errorNameAndMessage(err));
+}
+var FOCUS_POLLS = 3;
+var FOCUS_POLL_PAUSE_MS = 300;
+var RECT_TOLERANCE = 1;
+var MULTI_LINE_SUBMIT_NOTICE = "submit not sent: Return would add a new line in this multi-line field; tap its send or submit control";
+var IOS_BUTTON_NAME = {
+  home: "home",
+  volumeUp: "volumeup",
+  action: "action"
+};
+var VOLUME_BUTTONS = /* @__PURE__ */ new Set(["volumeUp"]);
+var MAX_PICKER_INDEX = 20;
+var IOS_SAFARI_BUNDLE_ID = "com.apple.mobilesafari";
+var IOS_SPRINGBOARD_BUNDLE_ID = "com.apple.springboard";
+var IOS_LINK_HANDOFF_POLLS = 12;
+var IOS_LINK_HANDOFF_PAUSE_MS = 500;
+function firstErrorLine(err) {
+  return (err instanceof Error ? err.message : String(err)).split("\n")[0];
+}
+var IOS_TAP_HOLD_MS = 100;
 async function safePerform(chain) {
   try {
     await chain.perform();
@@ -91,6 +157,18 @@ function isIOSNativeSelectTarget(refData) {
     role && IOS_NATIVE_SELECT_ROLES.has(role) || refData?.nativeType && IOS_NATIVE_SELECT_TYPES.has(refData.nativeType)
   );
 }
+function rectMatches(a, b) {
+  return Math.abs(a.x - b.x) <= RECT_TOLERANCE && Math.abs(a.y - b.y) <= RECT_TOLERANCE && Math.abs(a.width - b.width) <= RECT_TOLERANCE && Math.abs(a.height - b.height) <= RECT_TOLERANCE;
+}
+function rectWithin(inner, outer) {
+  return inner.x >= outer.x - RECT_TOLERANCE && inner.y >= outer.y - RECT_TOLERANCE && inner.x + inner.width <= outer.x + outer.width + RECT_TOLERANCE && inner.y + inner.height <= outer.y + outer.height + RECT_TOLERANCE;
+}
+function elementIdOf(ref) {
+  if (!ref || typeof ref !== "object") return void 0;
+  const record = ref;
+  const id = record[W3C_ELEMENT_KEY] ?? record.ELEMENT;
+  return typeof id === "string" && id ? id : void 0;
+}
 function normalizePickerValue(value) {
   return value.trim().replace(/\s+/g, " ").toLowerCase();
 }
@@ -137,6 +215,31 @@ function matchesIOSApp(processName, bundleId) {
   const appName = bundleId.split(".").pop() ?? bundleId;
   return processName === appName || processName.includes(appName);
 }
+var CONTROL_CHAR_RE = /[\u0000-\u001F\u007F]/;
+function escapeIOSPredicateText(value) {
+  if (CONTROL_CHAR_RE.test(value)) {
+    throw new Error(
+      `scroll target contains a control character and cannot be used as an XCUITest predicate \u2014 provide a plain-text target for untilVisible.`
+    );
+  }
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function buildIOSPredicate(target) {
+  const escaped = escapeIOSPredicateText(target);
+  return `label CONTAINS "${escaped}" OR name CONTAINS "${escaped}" OR value CONTAINS "${escaped}"`;
+}
+function fingerDirectionFor(scroll) {
+  switch (scroll) {
+    case "up":
+      return "down";
+    case "down":
+      return "up";
+    case "left":
+      return "right";
+    case "right":
+      return "left";
+  }
+}
 function parseIOSSyslogLine(message, timestamp, bundleId) {
   const appiumMatch = message.match(IOS_APPIUM_LOG_REGEX);
   if (appiumMatch) {
@@ -170,14 +273,26 @@ var IOSPlatformAdapter = class {
   activeWebContext = null;
   webContextChecked = false;
   currentContext = null;
+  liveStreamCapability;
   consoleLogs = [];
   consoleDrainIndex = 0;
   captureConsole = true;
   bundleId = null;
+  // EXEC-03 session-cached app registry (D-10/D-12): enumerated once per session. null = not yet
+  // enumerated OR enumeration unavailable (iOS simulator — mobile: listApps throws). Reset in cleanup().
+  appRegistry = null;
+  sessionSnapshotDepth = IOS_SNAPSHOT_MAX_DEPTH;
+  snapshotDepth = IOS_SNAPSHOT_MAX_DEPTH;
+  readsAtLoweredDepth = 0;
+  snapshotDepthWarned = false;
   async setup(config) {
     this.config = config;
     this.captureConsole = config.logCapture?.console !== false;
     this.bundleId = this.config.bundleId ?? config.device?.match?.bundleId ?? null;
+    this.sessionSnapshotDepth = resolveIOSSnapshotDepth(config.farmSession?.capabilities);
+    this.snapshotDepth = this.sessionSnapshotDepth;
+    this.readsAtLoweredDepth = 0;
+    this.snapshotDepthWarned = false;
     this.driver = await createIOSSession(this.config, config.farmSession);
     const bundleId = this.bundleId;
     if (bundleId) {
@@ -196,6 +311,11 @@ var IOSPlatformAdapter = class {
     }
   }
   async cleanup() {
+    try {
+      await this.liveStreamCapability?.stop();
+    } catch {
+    }
+    this.liveStreamCapability = void 0;
     try {
       if (this.driver) {
         await this.driver.deleteSession();
@@ -207,9 +327,25 @@ var IOSPlatformAdapter = class {
     this.config = null;
     this.consoleLogs = [];
     this.bundleId = null;
+    this.appRegistry = null;
     this.activeWebContext = null;
     this.webContextChecked = false;
     this.currentContext = null;
+    this.sessionSnapshotDepth = IOS_SNAPSHOT_MAX_DEPTH;
+    this.snapshotDepth = IOS_SNAPSHOT_MAX_DEPTH;
+    this.readsAtLoweredDepth = 0;
+    this.snapshotDepthWarned = false;
+  }
+  /**
+   * 428 D-11: the labelled 1s snapshot preview, over `captureScreenshot()` — `takeScreenshot()`
+   * and nothing else. Never `screenshot()`: that one switches the Appium context, and a tick
+   * landing between a step's context switch and its command would run the command in the wrong
+   * context. Declared before the driver exists (a capture then answers `undefined`), so the
+   * composition's selection never falls through to `screenshot()`.
+   */
+  get liveStream() {
+    this.liveStreamCapability ??= createSnapshotLiveStream({ capture: () => this.captureScreenshot() });
+    return this.liveStreamCapability;
   }
   async observe(_options) {
     if (!this.driver) {
@@ -217,11 +353,11 @@ var IOSPlatformAdapter = class {
     }
     await this.ensureContext("NATIVE_APP");
     const [xml, viewport] = await Promise.all([
-      this.driver.getPageSource(),
+      this.readIOSPageSource(),
       this.driver.getWindowSize()
     ]);
-    const parsed = parseMobileSource(xml, "ios", viewport);
-    this.lastRefs = parsed.refs;
+    const { nodes } = parseMobileSource(xml, "ios", viewport);
+    const scroll = deriveMobileScroll(nodes, viewport);
     let url;
     const webCtx = await this.getWebContext();
     if (webCtx) {
@@ -236,13 +372,17 @@ var IOSPlatformAdapter = class {
         }
       }
     }
-    return {
-      tree: parsed.tree,
-      elements: parsed.elements,
-      url,
+    const { state, binding } = buildScreenState({
+      platform: "ios",
+      nodes,
+      viewport,
+      scroll,
+      coordSpace: "viewport",
       timestamp: Date.now(),
-      metadata: { coordSpace: "viewport", viewportWidth: viewport.width, viewportHeight: viewport.height, refMap: parsed.refs }
-    };
+      ...url !== void 0 ? { url } : {}
+    });
+    this.lastRefs = buildRefEntries(nodes, binding);
+    return state;
   }
   async execute(action) {
     if (!this.driver) {
@@ -334,6 +474,20 @@ var IOSPlatformAdapter = class {
     this.webContextChecked = false;
     this.activeWebContext = null;
   }
+  async readForegroundBundleId() {
+    try {
+      const info = await this.driver.execute("mobile: activeAppInfo");
+      if (!info || typeof info !== "object") return void 0;
+      const bundleId = info.bundleId;
+      return firstNonEmpty(typeof bundleId === "string" ? bundleId : void 0);
+    } catch {
+      return void 0;
+    }
+  }
+  isBrowserSession() {
+    const browserName = this.config?.device?.match?.browserName;
+    return typeof browserName === "string" && browserName.trim().length > 0;
+  }
   async ensureContext(target) {
     if (this.currentContext === target) return;
     try {
@@ -358,6 +512,427 @@ var IOSPlatformAdapter = class {
     }
   }
   // ---------------------------------------------------------------------------
+  // Compound behaviors (EXEC-01/02/03)
+  // ---------------------------------------------------------------------------
+  async readIOSPageSource() {
+    const driver = this.driver;
+    if (this.snapshotDepth < this.sessionSnapshotDepth && this.readsAtLoweredDepth >= IOS_SNAPSHOT_PROBE_INTERVAL) {
+      this.readsAtLoweredDepth = 0;
+      try {
+        await driver.updateSettings({ snapshotMaxDepth: this.sessionSnapshotDepth });
+        this.snapshotDepth = this.sessionSnapshotDepth;
+      } catch {
+      }
+    }
+    try {
+      return this.countLoweredRead(await driver.getPageSource());
+    } catch (readErr) {
+      const depthError = isIOSSnapshotDepthError(readErr);
+      if (!depthError && !isIOSSnapshotReadError(readErr)) throw readErr;
+      if (depthError && this.snapshotDepth > IOS_SNAPSHOT_FALLBACK_DEPTH) {
+        try {
+          await driver.updateSettings({ snapshotMaxDepth: IOS_SNAPSHOT_FALLBACK_DEPTH });
+        } catch {
+          throw readErr;
+        }
+        const failedDepth = this.snapshotDepth;
+        this.snapshotDepth = IOS_SNAPSHOT_FALLBACK_DEPTH;
+        this.readsAtLoweredDepth = 0;
+        if (!this.snapshotDepthWarned) {
+          this.snapshotDepthWarned = true;
+          const detail = (readErr instanceof Error ? readErr.message : String(readErr)).split("\n")[0].slice(0, 160);
+          console.warn(
+            `[ios-adapter] page source failed at snapshotMaxDepth ${failedDepth}; later reads stay at ${IOS_SNAPSHOT_FALLBACK_DEPTH} and retry ${this.sessionSnapshotDepth} every ${IOS_SNAPSHOT_PROBE_INTERVAL} reads (${detail})`
+          );
+        }
+      }
+      return this.countLoweredRead(await driver.getPageSource());
+    }
+  }
+  countLoweredRead(xml) {
+    if (this.snapshotDepth < this.sessionSnapshotDepth) this.readsAtLoweredDepth++;
+    return xml;
+  }
+  async tapAt(point) {
+    await safePerform(
+      this.driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: Math.round(point.x), y: Math.round(point.y) }).down({ button: 0 }).pause(IOS_TAP_HOLD_MS).up({ button: 0 })
+    );
+  }
+  async readRect(elementId) {
+    try {
+      const rect = await this.driver.getElementRect(elementId);
+      return rect && typeof rect.x === "number" ? rect : void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  /**
+   * The ref's own text-entry element: candidates of its XCUI type (selector built from the fixed
+   * type list only, never from app-supplied text) whose rect matches the observed bounds. Only a
+   * unique match is used; two or more matches, or none, ⇒ undefined. Position never selects.
+   */
+  async locateIOSTextTarget(ref) {
+    const refData = this.lastRefs[ref];
+    const nativeType = refData?.nativeType;
+    const bounds = refData?.bounds;
+    if (!nativeType || !IOS_EDITABLE_TYPES.has(nativeType) || !bounds) return void 0;
+    let candidates;
+    try {
+      candidates = Array.from(await this.driver.$$(`-ios class chain:**/${nativeType}`));
+    } catch {
+      return void 0;
+    }
+    const matches = [];
+    for (const el of candidates) {
+      if (!el?.elementId) continue;
+      const rect = await this.readRect(el.elementId);
+      if (!rect || !rectMatches(rect, bounds)) continue;
+      matches.push({ el, rect });
+    }
+    return matches.length === 1 ? matches[0] : void 0;
+  }
+  async readIOSFocusedIds() {
+    const driver = this.driver;
+    try {
+      const id = elementIdOf(await driver.getActiveElement());
+      if (id) return [id];
+    } catch {
+    }
+    const ids = [];
+    for (const type of IOS_EDITABLE_TYPES) {
+      try {
+        const focused = Array.from(await driver.$$(`-ios class chain:**/${type}[\`hasFocus == 1\`]`));
+        for (const el of focused) if (el?.elementId) ids.push(el.elementId);
+      } catch {
+      }
+    }
+    return ids;
+  }
+  /**
+   * WDA's typing taps an element that lacks keyboard focus and then sends keystrokes without
+   * re-checking focus, so they land wherever focus is. Text is typed only once the target (or
+   * a descendant) holds keyboard focus.
+   */
+  async confirmIOSKeyboardFocus(target) {
+    let outcome = "none";
+    for (let poll = 0; poll < FOCUS_POLLS; poll++) {
+      if (poll > 0) await this.driver.pause(FOCUS_POLL_PAUSE_MS);
+      const ids = await this.readIOSFocusedIds();
+      if (ids.length === 0) {
+        outcome = "none";
+        continue;
+      }
+      for (const id of ids) {
+        if (id === target.el.elementId) return "focused";
+        const rect = await this.readRect(id);
+        if (rect && rectWithin(rect, target.rect)) return "focused";
+      }
+      outcome = "elsewhere";
+    }
+    return outcome;
+  }
+  textInputRefusal(verb, ref, evidence, box) {
+    const nothing = verb === "fill" ? "Nothing was typed." : "Nothing was cleared.";
+    let error;
+    switch (evidence) {
+      case "no-editable-signal": {
+        const picker = isIOSNativeSelectTarget(this.lastRefs[ref]) ? " Use nativeSelect for native pickers." : "";
+        error = `Element ${ref} is not editable: the observation carries no editable signal for it.${picker} ${nothing}`;
+        break;
+      }
+      case "no-keyboard-focus":
+        error = `Element ${ref} is not editable: it did not take keyboard focus when tapped. ${nothing}`;
+        break;
+      case "focus-elsewhere":
+        error = `Element ${ref} is not editable here: after tapping it, keyboard focus is on another element. Input is never sent to an element other than the target. ${nothing}`;
+        break;
+      case "stale-target":
+        error = `Element ${ref} was not found at its observed position; the screen changed. Re-observe before typing. ${nothing}`;
+        break;
+      default:
+        return assertNever(evidence);
+    }
+    const cause = evidence === "stale-target" ? "target-not-found" : "not-editable";
+    const fillRefusal = { verb, cause, evidence };
+    return { success: false, error, ...box ?? {}, metadata: { fillRefusal } };
+  }
+  /** Gate → own-element lookup → tap → keyboard-focus check shared by fill and clearText. */
+  async focusIOSTextTarget(verb, ref, box) {
+    if (this.lastRefs[ref]?.editable !== true) {
+      return { refusal: this.textInputRefusal(verb, ref, "no-editable-signal") };
+    }
+    const target = await this.locateIOSTextTarget(ref);
+    if (!target) return { refusal: this.textInputRefusal(verb, ref, "stale-target") };
+    await this.tapAt(box.coordinates);
+    const focus = await this.confirmIOSKeyboardFocus(target);
+    if (focus === "focused") return { target };
+    return {
+      refusal: this.textInputRefusal(verb, ref, focus === "elsewhere" ? "focus-elsewhere" : "no-keyboard-focus", box)
+    };
+  }
+  /** A non-empty empty-field hint (XCUITest placeholderValue); undefined when absent. */
+  async readIOSPlaceholder(el) {
+    try {
+      const hint = await el.getAttribute("placeholderValue");
+      return typeof hint === "string" && hint !== "" ? hint : void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  /** Read a focused element's `value` attribute; undefined when nothing is readable. */
+  async readIOSValue(el) {
+    try {
+      const value = await el.getAttribute("value");
+      return typeof value === "string" ? value : void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  /**
+   * EXEC-01 iOS fill compound (D-05..D-08). From the SAME focused-element handle: (append) capture
+   * the prior value FIRST via getAttribute('value') then addValue, or (replace) setValue; RE-READ
+   * via getAttribute('value') on that same handle; verdict via compareFillReread. Secure fields
+   * (nativeType XCUIElementTypeSecureTextField) take the non-empty-only lane — the comparator yields
+   * length sentinels so no raw value enters the result (T-359-02); bullet masking is tolerated
+   * (A3/Pitfall 7 — never a length compare). On a passing re-read AND submit, a return/newline is
+   * delivered AFTER the re-read (D-07). Single typing attempt; a mismatch is success:false + §7.1.
+   *
+   * Append (437 FA-1, owner 2026-10-08): the XCUITest `value` attribute often lags after addValue,
+   * so a re-read equal to the prior cannot show the appended text. That fill is recorded unverified:
+   * never exact, and never a mismatch. Every fill records the shared verdict as `fillVerdict`.
+   * An empty field reads as its placeholder, so an append prior equal to it counts as empty.
+   *
+   * Return in a multi-line field adds a new line instead of submitting, so a multi-line submit is
+   * never sent and is recorded as such.
+   *
+   * An unreadable re-read is unverified and does not stop a requested Return, as on Android (D-09,
+   * D-10; owner 2026-10-09), but focus is confirmed once first and a Return is held as focus-lost
+   * when the field no longer has it (444.1 D-10).
+   */
+  async fillIOSCompound(el, action, box, secure, multiline, target) {
+    const driver = this.driver;
+    const isAppend = action.clearMode === "append";
+    let prior = isAppend ? await this.readIOSValue(el) ?? "" : "";
+    if (prior !== "" && prior === await this.readIOSPlaceholder(el)) prior = "";
+    if (isAppend) {
+      await el.addValue(action.text);
+    } else {
+      await el.setValue(action.text);
+    }
+    const expected = isAppend ? prior + action.text : action.text;
+    const raw = await this.readIOSValue(el);
+    const actual = isAppend && raw === prior ? void 0 : raw;
+    const verdict = compareFillReread({ expected, actual, secure });
+    const fillVerdict = {
+      verb: "fill",
+      verdict: verdict.verdict,
+      ...verdict.secure ? { secure: true } : {}
+    };
+    const unsent = multiline ? { sent: false, reason: "multi-line-field" } : { sent: false };
+    const notice = action.submit && multiline ? { data: MULTI_LINE_SUBMIT_NOTICE } : {};
+    let fillSubmit = unsent;
+    if (verdict.ok && action.submit && !multiline) {
+      if (raw === void 0 && await this.confirmIOSKeyboardFocus(target) !== "focused") {
+        fillSubmit = { sent: false, reason: "focus-lost" };
+      } else {
+        await driver.keys(["\n"]);
+        fillSubmit = { sent: true };
+      }
+    }
+    const metadata = {
+      ...verdict.meta ? { fillReread: verdict.meta } : {},
+      fillVerdict,
+      ...action.submit ? { fillSubmit } : {}
+    };
+    return verdict.ok ? { success: true, ...box, ...notice, metadata } : { success: false, error: verdict.selfCorrectingError, ...box, ...notice, metadata };
+  }
+  /**
+   * EXEC-02 platform primitives injected into the shared runner scroll loops (D-02/D-03). The swipe
+   * is a page-sized directional gesture (inverted to the finger direction) that reports unknown
+   * movement; nativeSearchScroll drives
+   * the XCUITest `mobile: scroll` predicateString rung over an injection-escaped target; readInterimTree
+   * is a light page-source parse — NO refMap mint, NO screenshot, lastRefs untouched.
+   */
+  async buildIOSScrollPrimitives(scrollDirection, maxSwipes, factor = 1) {
+    const driver = this.driver;
+    const viewport = await driver.getWindowSize();
+    const axisLength = scrollDirection === "left" || scrollDirection === "right" ? viewport.width : viewport.height;
+    const distance = Math.max(1, Math.round(axisLength * 0.6 * factor));
+    return {
+      swipeOnce: async (direction, ref) => {
+        let sx = Math.round(viewport.width / 2);
+        let sy = Math.round(viewport.height / 2);
+        if (ref) {
+          const { center } = new MobileElementResolver(this.lastRefs).resolve(ref);
+          sx = Math.round(center.x);
+          sy = Math.round(center.y);
+        }
+        const pts = computeSwipe(sx, sy, fingerDirectionFor(direction), distance);
+        await safePerform(
+          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: pts.startX, y: pts.startY }).down({ button: 0 }).move({ x: pts.endX, y: pts.endY, duration: 300 }).up({ button: 0 })
+        );
+        return "unknown";
+      },
+      nativeSearchScroll: async (target) => {
+        const predicateString = buildIOSPredicate(target);
+        try {
+          await driver.execute("mobile: scroll", { predicateString });
+          return true;
+        } catch {
+          return false;
+        }
+      },
+      readInterimTree: async () => {
+        const xml = await this.readIOSPageSource();
+        const { nodes } = parseMobileSource(xml, "ios", viewport);
+        return nodes;
+      }
+    };
+  }
+  /**
+   * EXEC-03 openApp (D-10/D-12, Pitfall 5). Resolve a human name to a bundle id (or validate an
+   * explicit bundleId) over the session-cached registry, then launch via activateApp. On real devices
+   * `mobile: listApps` enumerates the registry; on simulators it throws, leaving the registry
+   * unavailable — the appName lane then mints a structured §7.1 error directing to an explicit
+   * bundleId, and the bundleId lane validates without the registry (isAppInstalled / activateApp
+   * error conversion, A2). Never a best-guess launch (T-359-04); an invalid bundle never succeeds.
+   */
+  async openApp(action) {
+    const driver = this.driver;
+    const registry = await this.ensureAppRegistry();
+    if ("bundleId" in action) {
+      return await this.openByBundleId(action.bundleId, registry);
+    }
+    if (registry === null) {
+      return {
+        success: false,
+        error: `openApp could not enumerate installed apps by name: "mobile: listApps" is unavailable on iOS simulators. Retry with an explicit openApp {bundleId} using the app's exact bundle identifier.`
+      };
+    }
+    let reg = registry;
+    let resolution = resolveAppName(action.appName, reg);
+    if (resolution.kind === "unknown" || resolution.kind === "ambiguous") {
+      const fresh = await this.enumerateApps();
+      if (fresh !== null) {
+        this.appRegistry = fresh;
+        reg = fresh;
+        resolution = resolveAppName(action.appName, reg);
+      }
+    }
+    switch (resolution.kind) {
+      case "exact":
+      case "fuzzy":
+        await driver.activateApp(resolution.id);
+        return { success: true, metadata: { openApp: { resolvedId: resolution.id, matchKind: resolution.kind } } };
+      case "ambiguous":
+      case "unknown": {
+        const ids = resolution.candidates.map((c) => c.id).join(", ");
+        const lead = resolution.kind === "ambiguous" ? "is ambiguous between installed apps" : "did not match an installed app";
+        return {
+          success: false,
+          error: `openApp: "${action.appName}" ${lead}. Closest candidates: ${ids || "(none)"}. Retry openApp {bundleId} with the exact bundle identifier.`
+        };
+      }
+    }
+  }
+  /**
+   * Explicit `{bundleId}` launch (D-12, A2). With a registry, validate membership; without one
+   * (simulator) validate via `driver.isAppInstalled` when the driver exposes it, otherwise attempt
+   * `activateApp` and convert a driver rejection into the structured §7.1 error. An invalid bundle
+   * NEVER returns success:true.
+   */
+  async openByBundleId(bundleId, registry) {
+    const driver = this.driver;
+    if (registry !== null) {
+      if (!registry.some((entry) => entry.id === bundleId)) {
+        return {
+          success: false,
+          error: `openApp: bundleId "${bundleId}" is not installed (not in the app registry). Verify the bundle identifier or use openApp {appName}.`
+        };
+      }
+      await driver.activateApp(bundleId);
+      return { success: true, metadata: { openApp: { resolvedId: bundleId, matchKind: "explicit" } } };
+    }
+    const isAppInstalled = driver.isAppInstalled;
+    if (typeof isAppInstalled === "function") {
+      let installed = false;
+      try {
+        installed = await isAppInstalled.call(driver, bundleId);
+      } catch {
+        installed = false;
+      }
+      if (!installed) {
+        return {
+          success: false,
+          error: `openApp: bundleId "${bundleId}" is not installed on this device. Verify the bundle identifier.`
+        };
+      }
+      await driver.activateApp(bundleId);
+      return { success: true, metadata: { openApp: { resolvedId: bundleId, matchKind: "explicit" } } };
+    }
+    try {
+      await driver.activateApp(bundleId);
+      return { success: true, metadata: { openApp: { resolvedId: bundleId, matchKind: "explicit" } } };
+    } catch (err) {
+      return {
+        success: false,
+        error: `openApp: could not launch bundleId "${bundleId}": ${err instanceof Error ? err.message : String(err)}. Verify the bundle identifier.`
+      };
+    }
+  }
+  /** Return the cached registry, enumerating once on first use. Failed enumeration returns null (uncached). */
+  async ensureAppRegistry() {
+    if (this.appRegistry !== null) return this.appRegistry;
+    const enumerated = await this.enumerateApps();
+    if (enumerated !== null) this.appRegistry = enumerated;
+    return enumerated;
+  }
+  /**
+   * Enumerate installed apps through the driver only (ownership contract — webdriverio only, no
+   * child_process/simctl). `mobile: listApps` maps bundle ids → AppRegistryEntry with CFBundleName
+   * labels when present (D-10 — no per-app round-trips). It throws on simulators (Pitfall 5) ⇒ null,
+   * leaving enumeration unavailable WITHOUT crashing.
+   */
+  async enumerateApps() {
+    const driver = this.driver;
+    try {
+      const raw = await driver.execute("mobile: listApps");
+      return this.mapListApps(raw);
+    } catch {
+      return null;
+    }
+  }
+  /** Coerce a `mobile: listApps` result (bundle-id-keyed map, or an array of entries) into the registry. */
+  mapListApps(raw) {
+    const labelOf = (value) => {
+      if (!value || typeof value !== "object") return void 0;
+      const v = value;
+      for (const key of ["CFBundleName", "CFBundleDisplayName", "label", "name"]) {
+        const candidate = v[key];
+        if (typeof candidate === "string" && candidate.length > 0) return candidate;
+      }
+      return void 0;
+    };
+    const entries = [];
+    if (Array.isArray(raw)) {
+      for (const item of raw) {
+        if (!item || typeof item !== "object") continue;
+        const v = item;
+        const id = v.bundleId ?? v.CFBundleIdentifier ?? v.id;
+        if (typeof id !== "string" || id.length === 0) continue;
+        const label = labelOf(item);
+        entries.push(label !== void 0 ? { id, label } : { id });
+      }
+    } else if (raw && typeof raw === "object") {
+      for (const [id, value] of Object.entries(raw)) {
+        if (!id) continue;
+        const label = labelOf(value);
+        entries.push(label !== void 0 ? { id, label } : { id });
+      }
+    }
+    return entries;
+  }
+  // ---------------------------------------------------------------------------
   // Actions
   // ---------------------------------------------------------------------------
   async executeAction(action) {
@@ -365,58 +940,25 @@ var IOSPlatformAdapter = class {
     const resolver = new MobileElementResolver(this.lastRefs);
     await this.ensureContext("NATIVE_APP");
     switch (action.type) {
-      case "tap":
-      case "click": {
+      case "tap": {
         const { center, bounds } = resolver.resolve(action.ref);
-        await safePerform(
-          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: Math.round(center.x), y: Math.round(center.y) }).down({ button: 0 }).up({ button: 0 })
-        );
+        await this.tapAt(center);
         return { success: true, coordinates: center, boundingBox: bounds };
       }
       case "fill": {
         const { center, bounds } = resolver.resolve(action.ref);
-        const refData = this.lastRefs[action.ref];
-        const role = refData?.role?.toLowerCase();
-        if (role && !IOS_FILLABLE_ROLES.has(role)) {
-          return {
-            success: false,
-            error: `Element ${action.ref} is not fillable (role: ${role}). Use a textbox or input element instead.`
-          };
-        }
-        await safePerform(
-          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: Math.round(center.x), y: Math.round(center.y) }).down({ button: 0 }).up({ button: 0 })
+        const box = { coordinates: center, boundingBox: bounds };
+        const focused = await this.focusIOSTextTarget("fill", action.ref, box);
+        if ("refusal" in focused) return focused.refusal;
+        const nativeType = this.lastRefs[action.ref]?.nativeType;
+        return await this.fillIOSCompound(
+          focused.target.el,
+          action,
+          box,
+          nativeType === "XCUIElementTypeSecureTextField",
+          nativeType === "XCUIElementTypeTextView",
+          focused.target
         );
-        const selectors = [
-          // Focused element (most precise)
-          "-ios class chain:**/XCUIElementTypeTextField[`hasFocus == 1`]",
-          "-ios class chain:**/XCUIElementTypeSecureTextField[`hasFocus == 1`]",
-          "-ios class chain:**/XCUIElementTypeSearchField[`hasFocus == 1`]",
-          // Any visible element of the type (fallback — some apps don't report hasFocus)
-          "-ios class chain:**/XCUIElementTypeSearchField",
-          "-ios class chain:**/XCUIElementTypeTextField",
-          "-ios class chain:**/XCUIElementTypeSecureTextField"
-        ];
-        for (const sel of selectors) {
-          try {
-            const el = await driver.$(sel);
-            if (await el.isExisting()) {
-              await el.setValue(action.value);
-              return { success: true, coordinates: center, boundingBox: bounds };
-            }
-          } catch {
-          }
-        }
-        await driver.keys([action.value]);
-        return { success: true, coordinates: center, boundingBox: bounds };
-      }
-      case "select": {
-        const { center, bounds } = resolver.resolve(action.ref);
-        return {
-          success: false,
-          error: "select is for HTML dropdowns. Use nativeSelect for iOS native picker wheels, or tap/swipe/tapCoordinate for custom controls.",
-          coordinates: center,
-          boundingBox: bounds
-        };
       }
       case "nativeSelect": {
         const { center, bounds } = resolver.resolve(action.ref);
@@ -475,58 +1017,58 @@ var IOSPlatformAdapter = class {
         };
       }
       case "scroll": {
-        const webCtx = await this.getWebContext();
-        if (webCtx) {
+        if (action.mode === "untilVisible") {
           try {
-            await this.ensureContext(webCtx);
-            const dx = action.scrollType === "horizontal" ? action.value : 0;
-            const dy = action.scrollType === "vertical" ? action.value : 0;
-            await driver.execute(
-              "window.scrollBy(arguments[0], arguments[1]);",
-              dx,
-              dy
-            );
-            await this.ensureContext("NATIVE_APP");
-            return { success: true };
-          } catch {
-            try {
-              await this.ensureContext("NATIVE_APP");
-            } catch {
-            }
+            escapeIOSPredicateText(action.text);
+          } catch (err) {
+            return { success: false, error: err instanceof Error ? err.message : String(err) };
           }
+          const primitives2 = await this.buildIOSScrollPrimitives(action.direction, action.maxSwipes);
+          const { meta: meta2 } = await runUntilVisibleLoop(primitives2, {
+            target: action.text,
+            direction: action.direction,
+            maxSwipes: action.maxSwipes,
+            retryOpposite: action.retryOpposite,
+            ...action.ref ? { ref: action.ref } : {}
+          });
+          return { success: true, metadata: { scrollUntilVisible: meta2 } };
         }
-        const { width, height } = await driver.getWindowSize();
-        const centerX = Math.round(width / 2);
-        const centerY = Math.round(height / 2);
-        const scrollStartX = centerX;
-        const scrollStartY = centerY;
-        const scrollEndX = action.scrollType === "horizontal" ? centerX - action.value : centerX;
-        const scrollEndY = action.scrollType === "vertical" ? centerY - action.value : centerY;
-        const scrollDuration = action.duration ?? 300;
-        await safePerform(
-          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: scrollStartX, y: scrollStartY }).down({ button: 0 }).move({ x: scrollEndX, y: scrollEndY, duration: scrollDuration }).up({ button: 0 })
-        );
-        return { success: true };
+        const factor = action.amount === "halfPage" ? 0.5 : 1;
+        const primitives = await this.buildIOSScrollPrimitives(action.direction, 0, factor);
+        if (action.amount === "toEnd") {
+          const { meta: meta2 } = await runToEndScroll(primitives, action.direction, action.ref);
+          return { success: true, metadata: { scrollUntilVisible: meta2 } };
+        }
+        const { meta } = await runDirectionScroll(primitives, {
+          direction: action.direction,
+          ...action.ref ? { ref: action.ref } : {}
+        });
+        return { success: true, metadata: { scrollUntilVisible: meta } };
       }
       case "swipe": {
         const { width, height } = await driver.getWindowSize();
-        let sx = Math.round(width / 2);
-        let sy = Math.round(height / 2);
-        if (action.ref) {
-          const { center } = resolver.resolve(action.ref);
-          sx = Math.round(center.x);
-          sy = Math.round(center.y);
+        let pts;
+        if (action.mode === "path") {
+          pts = {
+            startX: Math.round(action.from.x),
+            startY: Math.round(action.from.y),
+            endX: Math.round(action.to.x),
+            endY: Math.round(action.to.y)
+          };
+        } else {
+          let sx = Math.round(width / 2);
+          let sy = Math.round(height / 2);
+          if (action.ref) {
+            const { center } = resolver.resolve(action.ref);
+            sx = Math.round(center.x);
+            sy = Math.round(center.y);
+          }
+          const distance = Math.round(height * 0.6);
+          pts = computeSwipe(sx, sy, action.direction, distance);
         }
-        const distance = Math.round(height * 0.6);
-        const pts = action.startX !== void 0 && action.startY !== void 0 && action.endX !== void 0 && action.endY !== void 0 ? {
-          startX: action.startX,
-          startY: action.startY,
-          endX: action.endX,
-          endY: action.endY
-        } : computeSwipe(sx, sy, action.direction, distance);
         warnIfOutOfBounds({ x: pts.startX, y: pts.startY }, { width, height }, "swipe");
         warnIfOutOfBounds({ x: pts.endX, y: pts.endY }, { width, height }, "swipe");
-        const swipeDuration = action.duration ?? 300;
+        const swipeDuration = action.durationMs;
         await safePerform(
           driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: pts.startX, y: pts.startY }).down({ button: 0 }).move({ x: pts.endX, y: pts.endY, duration: swipeDuration }).up({ button: 0 })
         );
@@ -540,13 +1082,14 @@ var IOSPlatformAdapter = class {
         const { width: pinchW, height: pinchH } = await driver.getWindowSize();
         let pcx = Math.round(pinchW / 2);
         let pcy = Math.round(pinchH / 2);
-        if (action.ref) {
+        if ("ref" in action) {
           const { center } = resolver.resolve(action.ref);
           pcx = Math.round(center.x);
           pcy = Math.round(center.y);
+        } else {
+          pcx = action.x;
+          pcy = action.y;
         }
-        if (action.x !== void 0) pcx = action.x;
-        if (action.y !== void 0) pcy = action.y;
         warnIfOutOfBounds({ x: pcx, y: pcy }, { width: pinchW, height: pinchH }, "pinch");
         const { finger1Start, finger1End, finger2Start, finger2End } = computePinch(pcx, pcy, action.scale);
         const pinchDuration = 500;
@@ -560,13 +1103,14 @@ var IOSPlatformAdapter = class {
         const { width: mtW, height: mtH } = await driver.getWindowSize();
         let mtcx = Math.round(mtW / 2);
         let mtcy = Math.round(mtH / 2);
-        if (action.ref) {
+        if ("ref" in action) {
           const { center } = resolver.resolve(action.ref);
           mtcx = Math.round(center.x);
           mtcy = Math.round(center.y);
+        } else {
+          mtcx = action.x;
+          mtcy = action.y;
         }
-        if (action.x !== void 0) mtcx = action.x;
-        if (action.y !== void 0) mtcy = action.y;
         warnIfOutOfBounds({ x: mtcx, y: mtcy }, { width: mtW, height: mtH }, "multiTap");
         const positions = computeFingerPositions(mtcx, mtcy, action.fingers);
         await driver.actions(
@@ -584,35 +1128,48 @@ var IOSPlatformAdapter = class {
         return { success: true };
       }
       case "waitFor": {
-        await driver.pause(action.timeout ?? 2e3);
-        return { success: true };
+        if (action.on === "selector") {
+          return {
+            success: false,
+            error: 'waitFor {on:"selector"} (CSS/XPath) is a web-only mode. On native iOS, wait on visible text with waitFor {on:"text"} or {on:"gone"}.'
+          };
+        }
+        const wantPresent = action.on === "text";
+        const needle = action.text;
+        const deadline = Date.now() + action.timeoutMs;
+        for (; ; ) {
+          let source = "";
+          try {
+            source = await this.readIOSPageSource();
+          } catch {
+            source = "";
+          }
+          if (source.includes(needle) === wantPresent) return { success: true };
+          if (Date.now() >= deadline) break;
+          await driver.pause(Math.min(250, Math.max(1, deadline - Date.now())));
+        }
+        return {
+          success: false,
+          error: wantPresent ? `waitFor: text "${needle}" did not appear within ${action.timeoutMs}ms.` : `waitFor: text "${needle}" was still present after ${action.timeoutMs}ms.`
+        };
       }
       case "delay": {
         await driver.pause(action.ms);
         return { success: true };
       }
       case "keypress": {
+        if (action.mode !== "press") {
+          return {
+            success: false,
+            error: `keypress {mode:"${action.mode}"} (key hold/release) is web-only. On mobile, emit keypress {mode:"press"} to send the key.`
+          };
+        }
         for (const rawKey of action.keys) {
           const mapped = KEY_MAP[rawKey] ?? rawKey;
           await driver.keys([mapped]);
         }
         return { success: true };
       }
-      case "navigate": {
-        try {
-          await driver.url(action.url);
-          this.invalidateWebContext();
-          return { success: true };
-        } catch {
-          return { success: false, error: "navigate is not supported for this app. Use tap/fill on UI elements to navigate." };
-        }
-      }
-      case "hover": {
-        return { success: false, error: "hover is a web-only action. Use tap or longpress instead." };
-      }
-      case "assert": {
-        return { success: true };
-      }
       // --- New actions ---
       case "hideKeyboard": {
         try {
@@ -623,58 +1180,140 @@ var IOSPlatformAdapter = class {
       }
       case "clearText": {
         const { center, bounds } = resolver.resolve(action.ref);
-        const clearRefData = this.lastRefs[action.ref];
-        const clearRole = clearRefData?.role?.toLowerCase();
-        if (clearRole && !IOS_FILLABLE_ROLES.has(clearRole)) {
+        const box = { coordinates: center, boundingBox: bounds };
+        const focused = await this.focusIOSTextTarget("clearText", action.ref, box);
+        if ("refusal" in focused) return focused.refusal;
+        const { el } = focused.target;
+        await el.clearValue();
+        const remaining = await this.readIOSValue(el) ?? "";
+        if (remaining === "" || remaining === await this.readIOSPlaceholder(el)) {
+          return { success: true, ...box };
+        }
+        const secure = this.lastRefs[action.ref]?.nativeType === "XCUIElementTypeSecureTextField";
+        const residue = secure ? ` (${remaining.length} characters remain)` : "";
+        return {
+          success: false,
+          error: `Element ${action.ref}: the field still has text after clearing${residue} \u2014 re-observe and retry.`,
+          ...box
+        };
+      }
+      case "openUniversalLink": {
+        const explicit = firstNonEmpty(action.bundleId);
+        const configured = firstNonEmpty(this.bundleId);
+        const openInApp = async (appId) => {
+          await driver.execute("mobile: deepLink", { url: action.url, bundleId: appId });
+        };
+        const openScoped = async (appId) => {
+          try {
+            await openInApp(appId);
+            this.invalidateWebContext();
+            return { success: true };
+          } catch (err) {
+            return { success: false, error: `Failed to open universal link ${action.url} in iOS app ${appId}: ${err instanceof Error ? err.message : String(err)}` };
+          }
+        };
+        if (!/^https?:\/\//i.test(action.url)) {
+          const bundleId = explicit ?? configured;
+          if (!bundleId) {
+            return { success: false, error: `Missing iOS bundle id for native deep link: ${action.url}` };
+          }
+          return openScoped(bundleId);
+        }
+        if (explicit) return openScoped(explicit);
+        if (this.isBrowserSession()) {
+          try {
+            await driver.url(action.url);
+            this.invalidateWebContext();
+            return { success: true };
+          } catch (err) {
+            return { success: false, error: `Failed to open universal link ${action.url}: ${err instanceof Error ? err.message : String(err)}` };
+          }
+        }
+        let configuredFailure;
+        if (configured) {
+          try {
+            await openInApp(configured);
+            this.invalidateWebContext();
+            return { success: true };
+          } catch (err) {
+            configuredFailure = `opening it in the configured iOS app ${configured} failed first: ${firstErrorLine(err)}`;
+          }
+        }
+        const before = await this.readForegroundBundleId();
+        try {
+          await driver.url(action.url);
+        } catch (err) {
           return {
             success: false,
-            error: `Element ${action.ref} is not fillable (role: ${clearRole}). clearText only works on text inputs. Use a textbox or input element instead.`
+            error: `Failed to open universal link ${action.url} through the iOS system handler: ${firstErrorLine(err)}${configuredFailure ? ` (${configuredFailure})` : ""}`
           };
         }
-        await safePerform(
-          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: Math.round(center.x), y: Math.round(center.y) }).down({ button: 0 }).up({ button: 0 })
-        );
-        const clearSelectors = [
-          "-ios class chain:**/XCUIElementTypeTextField[`hasFocus == 1`]",
-          "-ios class chain:**/XCUIElementTypeSecureTextField[`hasFocus == 1`]",
-          "-ios class chain:**/XCUIElementTypeSearchField[`hasFocus == 1`]",
-          "-ios class chain:**/XCUIElementTypeSearchField",
-          "-ios class chain:**/XCUIElementTypeTextField",
-          "-ios class chain:**/XCUIElementTypeSecureTextField"
-        ];
-        for (const sel of clearSelectors) {
+        this.invalidateWebContext();
+        if (!before || before === IOS_SAFARI_BUNDLE_ID) return { success: true };
+        let after;
+        for (let poll = 0; poll < IOS_LINK_HANDOFF_POLLS; poll++) {
+          await driver.pause(IOS_LINK_HANDOFF_PAUSE_MS);
+          after = await this.readForegroundBundleId();
+          if (after && after !== before && after !== IOS_SPRINGBOARD_BUNDLE_ID) break;
+        }
+        if (after !== IOS_SAFARI_BUNDLE_ID) return { success: true };
+        let error = `iOS opened ${action.url} in Safari: no installed app claimed the link (the foreground app was ${before}). Pass bundleId to open it in a specific app, or com.apple.mobilesafari to open it in Safari.`;
+        if (before !== IOS_SPRINGBOARD_BUNDLE_ID) {
           try {
-            const el = await driver.$(sel);
-            if (await el.isExisting()) {
-              await el.clearValue();
-              break;
-            }
-          } catch {
+            await driver.activateApp(before);
+            error += ` Returned to ${before}.`;
+          } catch (err) {
+            error += ` Could not return to ${before}: ${firstErrorLine(err)}.`;
           }
         }
-        return { success: true, coordinates: center, boundingBox: bounds };
+        return { success: false, error };
       }
-      case "openLink": {
-        const bundleId = firstNonEmpty(action.appId, action.bundleId, this.bundleId);
-        const isWebUrl = /^https?:\/\//i.test(action.url);
-        if (!bundleId && !isWebUrl) {
-          return { success: false, error: `Missing iOS bundle id for native deep link: ${action.url}` };
+      case "assertValue": {
+        const webCtx = await this.getWebContext();
+        const inWeb = webCtx !== null;
+        if ("expr" in action) {
+          if (!inWeb) {
+            return {
+              success: false,
+              error: "assertValue {expr} evaluates JavaScript and is only available in an iOS WebView/browser context. Assert on a native signal, or run against a web target."
+            };
+          }
+          await this.ensureContext(webCtx);
+          const value = await driver.execute(`return (${action.expr});`);
+          return { success: true, data: value };
         }
-        try {
-          if (bundleId) {
-            const deepLink = driver.deepLink;
-            if (typeof deepLink === "function") {
-              await deepLink.call(driver, action.url, bundleId, action.waitForLaunch ?? true);
-            } else {
-              await driver.execute("mobile: deepLink", { url: action.url, bundleId });
+        switch (action.source) {
+          case "url": {
+            if (!inWeb) {
+              return {
+                success: false,
+                error: 'assertValue {source:"url"} reads the browser URL and is only available in an iOS WebView/browser context; native screens have no URL.'
+              };
             }
-          } else {
-            await driver.url(action.url);
+            await this.ensureContext(webCtx);
+            const value = await driver.execute("return window.location.href;");
+            return { success: true, data: value };
           }
-          this.invalidateWebContext();
-          return { success: true };
-        } catch (err) {
-          return { success: false, error: `Failed to open link ${action.url}${bundleId ? ` in iOS app ${bundleId}` : ""}: ${err instanceof Error ? err.message : String(err)}` };
+          case "storage": {
+            if (!inWeb) {
+              return {
+                success: false,
+                error: 'assertValue {source:"storage"} reads Web Storage and is only available in an iOS WebView/browser context.'
+              };
+            }
+            await this.ensureContext(webCtx);
+            const value = await driver.execute(
+              "return Object.fromEntries(Object.keys(localStorage).map(function(k){return [k, localStorage.getItem(k)];}));"
+            );
+            return { success: true, data: value };
+          }
+          case "network":
+            return {
+              success: false,
+              error: 'assertValue {source:"network"} (HTTP log inspection) is not available on the iOS adapter. Use a web target for network assertions, or assert on visible UI text.'
+            };
+          case "expr-result":
+            return { success: true, data: void 0 };
         }
       }
       case "drag": {
@@ -694,10 +1333,8 @@ var IOSPlatformAdapter = class {
         );
         return { success: true, coordinates: center, boundingBox: bounds };
       }
-      case "launchApp": {
-        await driver.activateApp(action.bundleId);
-        return { success: true };
-      }
+      case "openApp":
+        return await this.openApp(action);
       case "stopApp": {
         await driver.terminateApp(action.bundleId);
         return { success: true };
@@ -715,20 +1352,97 @@ var IOSPlatformAdapter = class {
         const y = action.y;
         const tcVp = await driver.getWindowSize();
         warnIfOutOfBounds({ x, y }, { width: tcVp.width, height: tcVp.height }, "tapCoordinate");
-        await safePerform(
-          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x, y }).down({ button: 0 }).up({ button: 0 })
-        );
+        await this.tapAt({ x, y });
         return { success: true, coordinates: { x, y } };
       }
-      case "readConsoleLogs": {
-        await this.pollDeviceLogs();
-        const all = [...this.consoleLogs];
-        const entries = action.level ? all.filter((e) => e.level === action.level) : all;
-        return { success: true, data: entries };
+      // --- iOS hardware / native verbs ---
+      case "pressButton": {
+        const name = IOS_BUTTON_NAME[action.button];
+        if (VOLUME_BUTTONS.has(action.button)) {
+          const registry = await this.enumerateApps();
+          if (registry === null) {
+            return {
+              success: false,
+              error: `pressButton "${action.button}" (a volume hardware button) is only supported on real devices; this appears to be an iOS simulator session, where volume buttons are unavailable. Run against a real device to use volume controls.`
+            };
+          }
+        }
+        await driver.execute("mobile: pressButton", { name });
+        return { success: true };
       }
-      default: {
-        return { success: false, error: `Unknown action type: ${action.type}` };
+      case "pickerSelect": {
+        const wheel = await driver.$("-ios class chain:**/XCUIElementTypePickerWheel");
+        if (!await wheel.isExisting()) {
+          return { success: false, error: "pickerSelect: no picker wheel is present on screen." };
+        }
+        const elementId = wheel.elementId;
+        if ("value" in action) {
+          await driver.execute("mobile: selectPickerWheelValue", {
+            elementId,
+            order: "next",
+            value: action.value,
+            maxAttempts: 25
+          });
+          return { success: true };
+        }
+        if (!Number.isInteger(action.order) || action.order < 0 || action.order > MAX_PICKER_INDEX) {
+          return {
+            success: false,
+            error: `pickerSelect: order ${action.order} is out of range (expected a 0-based wheel index in [0, ${MAX_PICKER_INDEX}]). Prefer pickerSelect {value} to select by the visible option text.`
+          };
+        }
+        for (let i = 0; i < MAX_PICKER_INDEX; i++) {
+          await driver.execute("mobile: selectPickerWheelValue", { elementId, order: "previous", offset: 0.15 });
+        }
+        for (let i = 0; i < action.order; i++) {
+          await driver.execute("mobile: selectPickerWheelValue", { elementId, order: "next", offset: 0.15 });
+        }
+        return { success: true };
       }
+      case "swipeFromEdge": {
+        const { width, height } = await driver.getWindowSize();
+        const midX = Math.round(width / 2);
+        const midY = Math.round(height / 2);
+        let start;
+        let end;
+        switch (action.edge) {
+          case "left":
+            start = { x: 0, y: midY };
+            end = { x: Math.round(width * 0.6), y: midY };
+            break;
+          case "right":
+            start = { x: width - 1, y: midY };
+            end = { x: Math.round(width * 0.4), y: midY };
+            break;
+          case "top":
+            start = { x: midX, y: 0 };
+            end = { x: midX, y: Math.round(height * 0.6) };
+            break;
+          case "bottom":
+            start = { x: midX, y: height - 1 };
+            end = { x: midX, y: Math.round(height * 0.4) };
+            break;
+        }
+        await safePerform(
+          driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: start.x, y: start.y }).down({ button: 0 }).move({ x: end.x, y: end.y, duration: 300 }).up({ button: 0 })
+        );
+        return { success: true, startCoordinates: start, endCoordinates: end };
+      }
+      // Runner-minted / author-channel verbs (D-01/D-15): reportValue, assertAI, extractAI, and
+      // setVariable are intercepted at the runner dispatch seam and never reach the adapter. A
+      // grouped §7.1 defensive case surfaces a dispatch-routing error if one arrives here;
+      // assertNever remains the backstop for a genuinely unknown schema verb. (uniqueValue is
+      // web-only and is not part of ActionsFor<'ios'>.)
+      case "reportValue":
+      case "assertAI":
+      case "extractAI":
+      case "setVariable":
+        return {
+          success: false,
+          error: `Action "${action.type}" is handled by the runner dispatch seam and must not reach the iOS adapter (runner-minted/author-channel verb). This indicates a dispatch routing error.`
+        };
+      default:
+        return assertNever(action);
     }
   }
 };